gz-plan-audit

Purpose

Pre-flight alignment audit that catches misalignment before implementation begins. The operator runs this after plan mode produces a plan, verifying three artifacts agree:

ADR (intent) <-> OBPI brief (scope) <-> Plan (execution steps)

Misalignment between these artifacts is the root cause of wasted implementation work: building the wrong thing, missing requirements, or solving problems the ADR did not ask for. This audit catches that drift before a single line of code is written.

Typical workflow:

1. Operator runs /gz-plan-audit OBPI-X.Y.Z-NN and audits ADR <-> OBPI alignment. If no plan exists yet, the plan audit is skipped.
2. If gaps are found, update the ADR or OBPI brief before planning.
3. If aligned, plan mode produces a plan in .claude/plans/.
4. Operator runs /gz-plan-audit OBPI-X.Y.Z-NN again after planning.
5. If the plan aligns, proceed into gz-obpi-pipeline.

The receipt and its consumers:

• uv run gz plan audit writes the receipt, one per OBPI: .claude/plans/.plan-audit-receipt-{OBPI-ID}.json (pipeline_receipt_path). The bare .plan-audit-receipt.json is the legacy name; readers still accept it as a fallback, nothing writes it.
• plan-audit-gate.py blocks ExitPlanMode without a valid receipt; pipeline-router.py routes a PASS receipt into gz-obpi-pipeline, which reads it at Stage 1.

Persona

Active persona: main-session — read .gzkit/personas/main-session.md and adopt its behavioral identity before executing this skill. Alignment auditing is skeptical comparison, not optimistic scanning. If the ADR says X and the brief says Y, that is a gap — not an interpretation difference.

Common Rationalizations

These thoughts mean STOP — you are about to skip a critical alignment check:

Thought	Reality
"The brief requirements are clear enough to skip the audit"	Clarity is not alignment. The audit catches drift between ADR intent and brief scope that no amount of reading catches.
"I already read the ADR and brief, they match"	Reading is not auditing. The structured comparison catches gaps that casual reading misses every time.
"There's no plan yet, so I'll skip the audit entirely"	The ADR-to-OBPI alignment check runs without a plan. Skip plan checks only — the ADR alignment is still required.
"The plan-audit hook will catch problems later"	The hook enforces receipt existence, not alignment quality. This skill provides the quality check the hook cannot.
"This is a small OBPI, alignment is obvious"	Small OBPIs drift more, not less. Brief constraints are easy to miss when scope feels trivial.
"The ADR hasn't changed since the brief was written"	ADR stability does not guarantee brief fidelity. Briefs are authored under time pressure and miss intent regularly.

Red Flags

• Implementation starts without this OBPI's plan-audit receipt in .claude/plans/
• Plan audit receipt shows PASS but gaps were hand-waved as "minor"
• Agent proceeds directly from brief reading to implementation without structured comparison
• ADR intent mentions capabilities not reflected in the OBPI brief requirements
• Plan file references files outside the brief's Allowed Paths

Invocation

/gz-plan-audit OBPI-X.Y.Z-NN

Run before planning for ADR <-> OBPI alignment and again after planning for Plan <-> OBPI alignment.

Trust Model

Layer 1 - Evidence Gathering. See docs/governance/GovZero/layered-trust.md.

• Reads: ADR files, OBPI briefs, plan files in .claude/plans/, and relevant codebase files
• Produces: alignment report with gaps, mismatches, recommendations, and a receipt file

Inputs

Parameter	Required	Description
obpi_id	Yes	OBPI identifier, for example OBPI-0.12.0-07
adr_id	No	Parent ADR identifier; derive from OBPI ID if omitted
plan_path	No	Path to a plan file in .claude/plans/; auto-discover if omitted

Outputs

• Alignment report presented to the operator with:
  • ADR <-> OBPI alignment status
  • Plan <-> OBPI alignment status
  • Specific gaps and mismatches with citations
  • Recommendations to update the brief, update the plan, or flag an ADR defect
• Receipt file at .claude/plans/.plan-audit-receipt-{OBPI-ID}.json, written by the CLI in Step 1

Procedure

Step 1: Run CLI structural checks

uv run gz plan audit OBPI-X.Y.Z-NN

This runs deterministic prerequisite checks (ADR exists, brief exists, plan file found, path overlap validation) and writes the receipt to .claude/plans/.plan-audit-receipt-{OBPI-ID}.json. If PASS and no semantic review is needed, the skill is done. If FAIL, review the gaps and continue with manual alignment checks below.

Step 2: Read the parent ADR

Locate and read the parent ADR under docs/design/adr/. Extract:

• Intent: the problem being solved and the decision made
• Feature Checklist: the full WBS with numbered checklist items
• The specific checklist item this OBPI maps to
• Goals and anti-patterns from the agent context frame
• Lane: Lite or Heavy
• Integration points: other OBPIs, shared modules, config entries

Step 3: Read the OBPI brief

Locate and read the brief from either of these layouts:

• docs/design/adr/**/obpis/OBPI-{id}-*.md
• docs/design/adr/**/briefs/OBPI-{id}-*.md

Extract:

• Objective
• Requirements
• Allowed and denied paths
• Acceptance criteria
• Verification commands

Step 4: Audit ADR <-> OBPI alignment

Compare the brief against its parent ADR checklist item:

Check	Question
Objective match	Does the brief objective match the ADR checklist item's intent?
Scope match	Are the brief allowed paths consistent with the ADR integration points?
Requirements coverage	Do the brief requirements cover what the ADR checklist item implies?
Lane consistency	Does the brief lane match the parent ADR lane?
Attestation rule	Gate 5 attestation is universal (ADR-0.0.36) — does the brief avoid claiming an exemption from it?
No scope creep	Does the brief avoid adding requirements not present in the ADR?
No scope gap	Does the brief avoid omitting requirements present in the ADR?

Record each check as Aligned, Drifted, or Missing.

Step 5: Find and read the plan file

Auto-discover the plan file from .claude/plans/:

1. Search .claude/plans/*.md for files referencing this OBPI ID.
2. If multiple matches exist, use the newest by modification time.
3. If plan_path was provided explicitly, use that instead.
4. If no plan exists, report No plan found and skip Steps 6 and 6a.

Extract:

• Context
• Files
• Steps
• Verification
• Notes

Step 6: Audit Plan <-> OBPI alignment

Compare the plan against the brief:

Check	Question
OBPI reference	Does the plan reference the correct OBPI brief?
Requirements coverage	Does every brief requirement appear as a plan step?
Allowed paths	Does the plan only touch files in the brief allowlist?
Denied paths	Does the plan avoid files in the brief denylist?
Verification	Does the plan include the brief verification commands?
No gold-plating	Does the plan avoid extra work not required by the brief?
Feasibility	Based on current codebase state, are the plan steps achievable?

Step 6a: Plan-Before-Exploration Ordering (Advisory)

The "destination-first" failure mode: the agent explores deeply, forms a conclusion, and only then authors the plan. The plan that results is a reconstruction of a destination already chosen — the audit passes because the plan matches the exploration, but the exploration was already motivated reasoning (Lindsey et al. 2025, rhyme experiment).

Self-introspection is not a verification pathway. Per docs/governance/arb-middleware.md § Why receipts, not narrative and Lindsey et al. 2025, the reporting pathway and the execution pathway are structurally separate — a post-hoc answer to "did I enter plan mode early?" is reconstruction, not observation. Until the receipt-stream is available, this step requires the agent to record two narrative disclosures regardless of perceived ordering:

1. Destination-in-mind: What conclusion had I already formed before writing this plan? Name the approach I was going to propose.
2. Rejected alternatives: What other approaches did I consider and reject during exploration? A plan without rejected alternatives is indistinguishable from a reconstruction.

The fields are required in narrative form — not as checkboxes. Empty or cosmetic answers are themselves a failure signal.

Mechanical enforcement — counting pre-ExitPlanMode tool calls from the session transcript and wiring concrete thresholds into gz plan audit — is deferred to a dedicated receipt-stream GHI; until then this step produces disclosure, not verification.

Step 7: Present the alignment report

Use this structure:

## ADR <-> OBPI Alignment

| Check | Status | Detail |
|-------|--------|--------|
| Objective match | Aligned / Drifted / Missing | [specifics] |
| Scope match | ... | ... |

## Plan <-> OBPI Alignment

| Check | Status | Detail |
|-------|--------|--------|
| Requirements coverage | Aligned / Drifted / Missing | [specifics] |
| Allowed paths | ... | ... |

## Gaps Found

1. [specific gap with file:line citation]

## Recommendations

1. [specific action]

## Verdict

PASS - All checks aligned, safe to proceed with implementation.
FAIL - N gaps found. Fix alignment before implementing.

The receipt already exists: Step 1's gz plan audit wrote it, with these fields (plus gaps and scope_collisions when present):

{
  "obpi_id": "OBPI-X.Y.Z-NN",
  "timestamp": "2026-03-12T12:00:00Z",
  "verdict": "PASS",
  "plan_file": "shimmering-beaming-sonnet.md",
  "gaps_found": 0
}

If Steps 2–6 found gaps the CLI's structural checks did not, rewrite that same file with verdict: FAIL and the true gaps_found — the CLI has no flag for a semantic verdict, and a PASS receipt over a failed audit routes the pipeline.

Receipt contract:

• verdict must be PASS or FAIL
• plan_file should name the plan that was audited
• receipt freshness is fail-closed: the receipt must be newer than the plan file

The audit produces a report and receipt. Fixing alignment is a separate action — never bundled into the audit pass.

Return control to the caller:

• If invoked standalone by an operator: end the turn after presenting the report.
• If invoked from gz-obpi-pipeline as a sub-step: control returns to Stage 1 (which goes on to the lock claim) and Stage 2 (implementation) begins in the same turn. Do NOT end the turn — that violates the pipeline's Iron Law.

Enforcement

Active enforcement contract for gzkit:

• Registered hook: .claude/hooks/plan-audit-gate.py
• Registered router consumer: .claude/hooks/pipeline-router.py
• Active registration surface: .claude/settings.json
• Consumer: .gzkit/skills/gz-obpi-pipeline/SKILL.md (Stage 1)

The operator still invokes /gz-plan-audit manually. The gate's logic lives in plan-audit-gate.py, not here: it finds the newest plan, extracts its OBPI ids, and blocks plan exit unless a receipt exists for that OBPI, is newer than the plan file, and carries a PASS or FAIL verdict. A plan that references no OBPI is allowed through.

Failure Modes

Failure	Cause	Resolution
ADR not found	ADR ID incorrect or structure mismatch	Verify ADR ID; search docs/design/adr/
Brief not found	OBPI ID typo or brief missing	Check obpis/ and briefs/ layouts
Brief lacks required sections	Incomplete or non-standard brief	Report as an alignment gap
No plan file found	Plan mode not run yet or no matching plan exists	Audit ADR <-> OBPI only and skip plan checks
Multiple plan files match	Several plans reference the same OBPI	Use the newest plan and note ambiguity
ADR checklist item ambiguous	Checklist item text is vague	Flag an ADR defect and recommend clarification

Acceptance Rules

• Audit report covers both ADR <-> OBPI and Plan <-> OBPI alignment when a plan exists
• Each check is recorded as Aligned, Drifted, or Missing with specifics
• Gaps include citations where applicable
• Report ends with a clear PASS or FAIL verdict
• Recommendations are actionable
• The agent returns control to the caller after presenting the report — ending the turn when invoked standalone, continuing into Stage 2 when invoked as a gz-obpi-pipeline sub-step

Related

• .gzkit/skills/gz-obpi-pipeline/SKILL.md
• .gzkit/skills/gz-obpi-sync/SKILL.md
• .gzkit/skills/gz-session-handoff/SKILL.md
• docs/design/adr/pre-release/ADR-0.12.0-obpi-pipeline-enforcement-parity/claude-pipeline-hooks-parity-matrix.md