Skip to content

tvproductions/gzkit / .agents/skills/gz-obpi-brief-drift

gz-obpi-brief-drift

Verified

Use when an OBPI brief may have drifted from the project; reconciles it and can write attested amendments.

gz obpi brief-drift

Overview

gz obpi brief-drift runs the OBPI-0.0.37-05 reconciliation engine to measure drift between an OBPI brief and the project tree across five dimensions — allowlist, discovery checklist, verification verbs, REQ count, and citation tuples (invariant CIC-2, brief↔reality coherence). Every run, --dry-run included, appends a brief_reconciled ledger event, plus brief_reconcile_drift_detected when the result gates.

What gates depends on the brief's status::

  • Terminal (list in step 1): deltas are reported, nothing gates.
  • Draft: allowlisted paths missing on disk and unresolved gz verbs are reported but do not gate, because they name what the OBPI will create. A Discovery Checklist path still gates unless a sibling OBPI's Allowed Paths create it; stale citations still gate.
  • Live (Active, in_progress): allowlist, discovery, verification and citation drift all gate.

The REQ count delta never gates; it is reported for information.

When to Use

  • Before Stage 2 implementation, to confirm a brief still matches project shape.
  • Before OBPI completion, to confirm zero residual drift.
  • Whenever a brief's allowlist or REQ set looks stale relative to the code.

Workflow

  1. Confirm the target OBPI id and that its brief file exists. Check its status: first — a terminal brief (Completed, attested_completed, Validated, Superseded, archived, Promoted, Abandoned, Withdrawn) reports deltas but never gates: has_drift is always false and the run exits 0. Its deltas read as "what moved since this shipped", never as a repair worklist. --apply on one is refused — exit 3, nothing written, no ledger event, --dry-run included — because the amendment would rewrite a sealed record under an attestation no operator can honestly give (GHI #707, #1115).
  2. Run uv run gz obpi brief-drift <OBPI-ID> to report per-dimension deltas. Exit 0 means clean; exit 3 means drift. On a live (non-terminal) brief only.
  3. If drift is real, preview with uv run gz obpi brief-drift <OBPI-ID> --apply --dry-run. The preview writes nothing to the brief and lists every line --apply would add or remove (planned_amendments under --json). Show that list to the operator: it is the amendment they attest in step 4.
  4. Apply with uv run gz obpi brief-drift <OBPI-ID> --apply. --attestor takes a handle, never a real name, and defaults to authorship.attestor_handle in .gzkit.json; --apply refuses without one. The write adds each src/ module that the brief's REQ-covering tests import, that sits beside an allowlisted src/ path, and that the brief neither allows nor denies — to frontmatter allowlist: on a structured brief, under ## Allowed Paths on a legacy one — and records unresolved verbs and REQ identity drift under ## Tracked Defects, never rewriting them. Allowlisted paths missing on disk, discovery and citation drift are not repaired. --apply re-measures the brief after writing and reports that second measurement, so the exit contract in step 2 binds here too: exit 3 means drift survived the amendment (--apply repairs the allowlist dimension only), not that the write failed.

Validation

  • The exit code already reflects the post-amendment brief — a re-run is a confirmation, not the measurement. Confirm the expected dimensions now report zero (or the residual is intentional and tracked).
  • Confirm the brief_reconciled ledger event was emitted (and brief_reconcile_drift_detected when drift was present).

Example

Use $gz-obpi-brief-drift to reconcile an OBPI brief against project state before completion.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall