tvproductions/gzkit / .agents/skills/gz-obpi-brief-drift
gz-obpi-brief-drift
VerifiedUse 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 unresolvedgzverbs 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
- 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_driftis always false and the run exits 0. Its deltas read as "what moved since this shipped", never as a repair worklist.--applyon one is refused — exit 3, nothing written, no ledger event,--dry-runincluded — because the amendment would rewrite a sealed record under an attestation no operator can honestly give (GHI #707, #1115). - 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. - 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--applywould add or remove (planned_amendmentsunder--json). Show that list to the operator: it is the amendment they attest in step 4. - Apply with
uv run gz obpi brief-drift <OBPI-ID> --apply.--attestortakes a handle, never a real name, and defaults toauthorship.attestor_handlein.gzkit.json;--applyrefuses without one. The write adds eachsrc/module that the brief's REQ-covering tests import, that sits beside an allowlistedsrc/path, and that the brief neither allows nor denies — to frontmatterallowlist:on a structured brief, under## Allowed Pathson 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.--applyre-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 (--applyrepairs 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_reconciledledger event was emitted (andbrief_reconcile_drift_detectedwhen drift was present).
Example
Use $gz-obpi-brief-drift to reconcile an OBPI brief against project state before completion.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |