gz-plan-audit

gz-plan-audit (v6.0.0)

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.

Current gzkit compatibility rule:

• The gz-plan-audit skill is ported and may write .claude/plans/.plan-audit-receipt.json.
• gz-obpi-pipeline already consumes that receipt when it exists.
• The registered Claude hook chain now consumes that receipt mechanically: plan-audit-gate.py blocks ExitPlanMode without a valid receipt and pipeline-router.py routes PASS receipts into gz-obpi-pipeline.

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 a .plan-audit-receipt.json 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 written to .claude/plans/.plan-audit-receipt.json

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	Does the brief inherit the parent ADR attestation requirement correctly?
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 Step 5.

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.

Write the receipt file on completion:

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

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 a

---

Content truncated.