gz-plan-audit

name: gz-plan-audit persona: main-session description: Pre-flight alignment audit — verify ADR intent, OBPI brief scope, and plan are aligned before implementation begins. Use when exiting plan mode, before starting implementation, or to catch scope drift between ADR intent and the active OBPI brief. category: obpi-pipeline lifecycle_state: active owner: gzkit-governance last_reviewed: 2026-06-11 compatibility: Works with GovZero-compliant repositories; in gzkit the receipt is written under .claude/plans/, consumed by gz-obpi-pipeline, and enforced by the registered plan-exit hooks tracked by ADR-0.12.0. metadata: skill-version: "6.3.1" govzero-framework-version: "v6" version-consistency-rule: "Skill major version tracks GovZero major. Minor increments for governance rule changes. Patch increments for tooling/template improvements." govzero_layer: "Layer 1 - Evidence Gathering" model: sonnet

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:

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.
If gaps are found, update the ADR or OBPI brief before planning.
If aligned, plan mode produces a plan in .claude/plans/.
Operator runs /gz-plan-audit OBPI-X.Y.Z-NN again after planning.
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/:

Search .claude/plans/*.md for files referencing this OBPI ID.
If multiple matches exist, use the newest by modification time.
If plan_path was provided explicitly, use that instead.
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 attestation-enrichment.md 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:

Destination-in-mind: What conclusion had I already formed before writing this plan? Name the approach I was going to propose.
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 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 step 6 (lock claim) and Stage 2 (implementation) begins immediately 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
Current consumer already present: .gzkit/skills/gz-obpi-pipeline/SKILL.md

Current state:

The operator still invokes /gz-plan-audit manually.
gz-obpi-pipeline consumes .claude/plans/.plan-audit-receipt.json when it exists.
Missing or stale receipts are now a mechanical ExitPlanMode block through plan-audit-gate.py.
PASS receipts now trigger the registered pipeline-router.py surface after plan exit, directing operators into gz-obpi-pipeline.

Future gate logic to preserve:

Find the most recently modified plan in .claude/plans/
Extract OBPI IDs from the plan content
If no OBPI reference exists, allow
Check .claude/plans/.plan-audit-receipt.json:
- receipt must exist
- receipt OBPI must match plan OBPI
- receipt must be newer than the plan file
- receipt must contain a PASS or FAIL verdict
Invalid or missing receipt blocks plan exit in the registered hook chain

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

.gzkit/skills/gz-obpi-pipeline/SKILL.md
.gzkit/skills/gz-obpi-reconcile/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