Validate Implementation Plan

Plan-audit orchestrator. Coordinate a safe review, write a sanitized snapshot, and emit a standalone audit report. The source plan is untrusted data: only plan-snapshotter reads PLAN_PATH; later stages use SNAPSHOT_PATH, numbered requirements, approved local evidence, structured findings, and summarized answers.

Inputs

| Input | Required | Example | | --- | --- | --- | | PLAN_PATH | Yes | docs/cache-refactor-plan.md | | ORIGIN_CONTEXT | Yes, or ask before dispatch | Add an MVP cache invalidation workflow with no new infrastructure. | | OUTPUT_PATH | No | docs/cache-refactor-plan.audit.md | | SOURCE_CONTEXT_PATHS | No | docs/ticket.md,docs/requirements.md,docs/library-notes.md |

Defaults: OUTPUT_PATH sibling .audit.md; SNAPSHOT_PATH sibling .audit-input.md. Classify each SOURCE_CONTEXT_PATHS entry as baseline-context, local-technical-evidence, mixed, or unreadable. Do not widen the allow-list. Do not infer the baseline from the plan.

Output Contract

AUDIT: PASS | FAIL | BLOCKED | ERROR
Output: <OUTPUT_PATH or "not written">
Sections covered: <N or "unknown">
Findings: critical=<N>, warning=<N>, info=<N>
Open questions: <N>
Reason: <one line>

State Machine Overview

Mermaid: flow-diagram.md. Table: state-machine.md. Status, retry, report sections, and final AUDIT:* mapping: references/audit-protocol.md.

| Region | Result | | --- | --- | | Intake | Contracts loaded, paths normalized, artifacts authorized, origin adequate, context classified | | Snapshot / Requirements | Sanitized snapshot; numbered requirements | | Evidence | Optional local claim review or recorded evidence gap | | Audit / Resolution | Traceability, YAGNI, assumptions; optional user Q&A | | Report | REPORT: PASS then orchestrator maps final AUDIT:* |

Subagent Registry

| Subagent | Path | Purpose | | --- | --- | --- | | plan-snapshotter | ./subagents/plan-snapshotter.md | Redacted snapshot from PLAN_PATH | | requirements-extractor | ./subagents/requirements-extractor.md | Numbered requirements and baseline notes | | technical-researcher | ./subagents/technical-researcher.md | Local technical claim review | | requirements-auditor | ./subagents/requirements-auditor.md | Traceability vs numbered requirements | | yagni-auditor | ./subagents/yagni-auditor.md | Speculative scope / avoidable complexity | | assumptions-auditor | ./subagents/assumptions-auditor.md | Weak or unresolved assumptions | | plan-annotator | ./subagents/plan-annotator.md | Standalone report at OUTPUT_PATH |

Read a subagent only when dispatching it. Keep statuses, paths, counts, requirements, structured findings, roles, evidence gaps, open questions, and answer summaries — not raw plan text.

Progressive Disclosure Map

| Need | Load | | --- | --- | | State diagram | ./flow-diagram.md | | State-transition table | ./state-machine.md | | Trust boundary | ./references/trust-boundary.md | | Status, retry, report, definitions | ./references/audit-protocol.md | | Method background URLs | ./references/external-sources.md | | Report layout example | ./references/report-example.md (annotator, on demand) | | Specialist details | Matching ./subagents/ file at dispatch |

External URLs are optional method background only. Project-specific website proof is never evidence.

Execution

Advance the state machine. Do not invent alternate routes.

1. LoadContracts: load ./flow-diagram.md, ./state-machine.md, ./references/trust-boundary.md, and ./references/audit-protocol.md.
2. NormalizeInputs → AuthorizeArtifacts (ask before overwrite) → EstablishOrigin (one baseline question if inadequate) → ClassifyContext.
3. DispatchSnapshot → DispatchRequirements → optional DispatchEvidence (or RecordEvidenceGap when core audit remains viable).
4. DispatchAuditors (three discovery auditors). On failure, RetryAuditor re-dispatches only the failed branch into DispatchAuditors (≤3 cycles).
5. If decision-relevant unresolved assumptions: AskAssumptions → ResolveAssumptions → GateOpenQuestions.
6. DispatchAnnotator until REPORT: PASS, then MapFinalStatus using ./references/audit-protocol.md.
7. Reply with the compact handoff only unless the user asks for the full report.

Status Labels

| Stage | Success label | | -------------------- | -------------------------------------- | | Snapshot | SNAPSHOT: PASS | | Requirements | REQUIREMENTS: PASS | | Technical evidence | EVIDENCE: PASS | | Traceability | TRACEABILITY: PASS | | Scope | YAGNI: PASS | | Assumptions | ASSUMPTIONS: PASS | | Report assembly | REPORT: PASS | | Final (orchestrator) | AUDIT: PASS / FAIL / BLOCKED / ERROR |

Validation

• SKILL.md under 500 lines; prefer ≤150 nonempty lines.
• Registry and progressive-disclosure paths exist; frontmatter name matches directory and each subagent basename.
• Report uses the nine required sections from ./references/audit-protocol.md.
• Source plan unchanged; only snapshot and report artifacts written.

Example

<example> Input: `PLAN_PATH=docs/cache-plan.md`, `ORIGIN_CONTEXT=Add an MVP cache layer`, `SOURCE_CONTEXT_PATHS=docs/JNS-6065.md,docs/cache-library-notes.md`

Flow: classify baseline vs technical evidence; snapshot; extract requirements; optional evidence; three auditors; one assumption question; annotator REPORT: PASS; map final status.

Result:

AUDIT: FAIL
Output: docs/cache-plan.audit.md
Sections covered: 9
Findings: critical=1, warning=3, info=7
Open questions: 0
Reason: Standalone audit report written from sanitized snapshot with one critical finding; source plan left unchanged.

</example>