cclaw-cli 0.1.0

package/dist/content/stage-schema.js

@@ -0,0 +1,1453 @@
+import { COMMAND_FILE_ORDER } from "../constants.js";
+// ---------------------------------------------------------------------------
+// BRAINSTORM — reference: superpowers brainstorming
+// ---------------------------------------------------------------------------
+const BRAINSTORM = {
+    stage: "brainstorm",
+    skillFolder: "brainstorming",
+    skillName: "brainstorming",
+    skillDescription: "Design-first stage. Clarify intent, compare options, and get explicit approval before implementation planning.",
+    hardGate: "Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.",
+    purpose: "Turn a rough request into an approved design direction with clear assumptions and boundaries.",
+    whenToUse: [
+        "Starting a new feature or behavior change",
+        "Requirements are ambiguous or solution path is unclear",
+        "Before any implementation-stage command"
+    ],
+    checklist: [
+        "Explore project context — check files, docs, recent commits, existing behavior.",
+        "Assess scope — if the request describes multiple independent subsystems, flag for decomposition before detailed questions.",
+        "Ask clarifying questions — one at a time, understand purpose, constraints, success criteria. Prefer multiple choice.",
+        "Propose 2-3 approaches — with trade-offs and your explicit recommendation with reasoning.",
+        "Present design — in sections scaled to their complexity (few sentences if simple, up to 300 words if nuanced). Get approval after each section.",
+        "Write design doc — save to `.cclaw/artifacts/01-brainstorm.md`.",
+        "Self-review — scan for placeholders, TBDs, contradictions, ambiguity, scope creep. Fix inline.",
+        "User reviews written artifact — ask user to review before proceeding. Wait for response.",
+        "Transition — invoke /cc-scope only after explicit user approval."
+    ],
+    interactionProtocol: [
+        "Explore context first (files, docs, existing behavior).",
+        "Ask one clarifying question per message. Do NOT combine questions.",
+        "For approach selection: use the Decision Protocol — present labeled options (A/B/C) with trade-offs, mark one as (recommended), use AskQuestion/AskUserQuestion tool when available.",
+        "Get section-by-section approval before finalizing the design direction.",
+        "Run a self-review pass (ambiguity, placeholders, contradictions) before handoff.",
+        "Wait for explicit user approval after writing the artifact. Do NOT auto-advance."
+    ],
+    process: [
+        "Capture problem statement, users, constraints, and success criteria.",
+        "Identify whether request should be decomposed into smaller sub-problems.",
+        "Offer alternatives and recommendation with rationale.",
+        "Present design in sections, ask after each section whether it looks right.",
+        "Write artifact with validated design.",
+        "Run self-review: placeholder scan, internal consistency, scope check, ambiguity check.",
+        "Ask user to review the written spec. Wait for changes or approval.",
+        "Handoff to scope stage only after approval is explicit."
+    ],
+    requiredGates: [
+        { id: "brainstorm_context_explored", description: "Project context and constraints have been reviewed." },
+        { id: "brainstorm_options_compared", description: "At least two alternatives were compared with trade-offs." },
+        { id: "brainstorm_design_approved", description: "User approved a concrete design direction." },
+        { id: "brainstorm_self_review_passed", description: "Design doc passed placeholder/ambiguity/consistency checks." },
+        { id: "brainstorm_user_reviewed_artifact", description: "User reviewed the written artifact and confirmed readiness." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
+        "Approved direction captured in artifact.",
+        "Open questions explicitly listed (if any).",
+        "Self-review pass completed with no unresolved issues."
+    ],
+    inputs: ["problem statement", "constraints", "success criteria"],
+    requiredContext: [
+        "existing project docs and patterns",
+        "current behavior of affected area",
+        "business and delivery constraints"
+    ],
+    outputs: [
+        "approved design direction",
+        "alternatives and trade-off table",
+        "brainstorm artifact"
+    ],
+    blockers: [
+        "no explicit approval",
+        "critical ambiguity unresolved",
+        "scope too broad and not decomposed"
+    ],
+    exitCriteria: [
+        "approved design direction documented",
+        "required gates marked satisfied",
+        "no implementation action taken",
+        "self-review completed with fixes applied"
+    ],
+    antiPatterns: [
+        "Skipping design because task seems simple",
+        "Asking many questions in one message",
+        "Jumping directly into implementation",
+        "Combining visual companion offer with a clarifying question",
+        "Invoking implementation skills before writing plans"
+    ],
+    rationalizations: [
+        { claim: "This is too simple for design.", reality: "Simple tasks fail fast when assumptions are wrong; a short design pass prevents rework." },
+        { claim: "We can figure it out while coding.", reality: "Coding before alignment creates churn and hidden scope growth." },
+        { claim: "There is only one obvious approach.", reality: "Without alternatives, trade-offs stay implicit and risk goes unexamined." },
+        { claim: "The user already knows what they want.", reality: "Unstated assumptions diverge during implementation; explicit design surfaces them early." }
+    ],
+    redFlags: [
+        "No alternatives documented",
+        "No explicit approval checkpoint",
+        "Implementation-related actions before approval",
+        "Self-review skipped or glossed over",
+        "Artifact has TBD or placeholder sections"
+    ],
+    policyNeedles: [
+        "One clarifying question per message",
+        "2-3 approaches with trade-offs",
+        "Do NOT implement, scaffold, or modify behavior"
+    ],
+    artifactFile: "01-brainstorm.md",
+    next: "scope",
+    cognitivePatterns: [
+        { name: "Divergent-Convergent Thinking", description: "First expand the solution space widely, then converge on the strongest option. Do not skip the divergent phase." },
+        { name: "YAGNI Ruthlessness", description: "Remove unnecessary features from all designs. Every feature must earn its place against the cost of complexity." },
+        { name: "Decomposition Instinct", description: "When a request describes multiple independent subsystems, decompose before refining. Each sub-project gets its own cycle." },
+        { name: "Isolation Preference", description: "Break the system into units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently." }
+    ],
+    reviewSections: [],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [],
+        writesTo: [".cclaw/artifacts/01-brainstorm.md"],
+        traceabilityRule: "Every approved direction must be traceable forward through scope and design. Downstream stages must reference brainstorm decisions."
+    },
+    artifactValidation: [
+        { section: "Problem Statement", required: true, validationRule: "Must describe the user problem, not the solution." },
+        { section: "Alternatives Table", required: true, validationRule: "At least 2 approaches with trade-offs and recommendation." },
+        { section: "Approved Direction", required: true, validationRule: "Must contain explicit approval marker from user." },
+        { section: "Open Questions", required: true, validationRule: "If empty, state 'None' explicitly. Do not omit." }
+    ],
+    namedAntiPattern: {
+        title: "This Is Too Simple To Need A Design",
+        description: "Every project goes through this process. A todo list, a single-function utility, a config change — all of them. 'Simple' projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval."
+    }
+};
+// ---------------------------------------------------------------------------
+// SCOPE — reference: gstack CEO review
+// ---------------------------------------------------------------------------
+const SCOPE = {
+    stage: "scope",
+    skillFolder: "scope-shaping",
+    skillName: "scope-shaping",
+    skillDescription: "Strategic scope stage. Challenge premise and lock explicit in-scope/out-of-scope boundaries using CEO-level thinking.",
+    hardGate: "Do NOT begin architecture, design, or code. This stage produces scope decisions only. Do not silently add or remove scope — every change is an explicit user opt-in.",
+    purpose: "Decide the right scope before technical lock-in using explicit mode selection and rigorous premise challenge.",
+    whenToUse: [
+        "After brainstorm approval",
+        "Before architecture/design lock-in",
+        "When ambition vs feasibility trade-off is unclear"
+    ],
+    checklist: [
+        "Prime Directives — Zero silent failures (every failure mode visible). Every error has a name (not 'handle errors' — name the exception). Every data flow has four paths: happy, nil input, upstream error, downstream timeout. Observability is a scope deliverable, not a post-launch add-on.",
+        "Premise Challenge — Is this the right problem? Could a different framing yield a simpler or more impactful solution? What happens if we do nothing? What are we optimizing for — speed, quality, cost, user experience?",
+        "Existing Code Leverage — Map every sub-problem to existing code. Run searches (grep, codebase exploration) BEFORE deciding to build new. If built-in or library solutions exist, default to them.",
+        "Dream State Mapping — Describe the ideal end state 12 months from now. Does this plan move toward that state or away from it?",
+        "Implementation Alternatives (MANDATORY) — Produce 2-3 distinct approaches. One must be 'minimal viable', one must be 'ideal architecture'. Include effort/risk/reversibility for each.",
+        "Temporal Interrogation — Think in time slices: HOUR 1 (foundation, what must exist first), HOURS 2-3 (core logic, what builds on foundation), HOURS 4-5 (integration, what connects the pieces), HOUR 6+ (polish, what can wait). What decisions must be locked NOW vs deferred to implementation?",
+        "Mode Selection with Default Heuristic — Present four options: SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials). Suggest default: greenfield → EXPANSION, bug/hotfix → HOLD, >15 files touched → suggest REDUCTION. Once selected, commit fully.",
+        "Error & Rescue Registry — For every new capability in scope: what breaks if it fails? How is the failure detected? What is the fallback? This is scope, not design — decide WHAT to protect, not HOW."
+    ],
+    interactionProtocol: [
+        "For scope mode selection: use the Decision Protocol — present expand/selective/hold/reduce as labeled options with trade-offs, mark one as (recommended), use AskQuestion/AskUserQuestion tool when available.",
+        "Challenge premise and verify the problem framing before anything else.",
+        "Present one structural scope issue at a time for decision. Do NOT batch. Use structured options for each scope boundary question.",
+        "Record explicit in-scope and out-of-scope contract.",
+        "Once the user accepts or rejects a recommendation, commit fully. Do not re-argue.",
+        "Produce a clean scope summary after all issues are resolved."
+    ],
+    process: [
+        "Run premise challenge and existing-solution leverage check.",
+        "Produce 2-3 scope alternatives (minimum viable + ideal included).",
+        "Choose scope mode with user approval.",
+        "Walk through scope review sections one at a time.",
+        "Write explicit scope contract and deferred items.",
+        "Produce scope summary with mode, in-scope, out-of-scope, and deferred."
+    ],
+    requiredGates: [
+        { id: "scope_premise_challenged", description: "Problem framing and assumptions were challenged." },
+        { id: "scope_alternatives_produced", description: "At least 2 implementation alternatives with effort/risk evaluated." },
+        { id: "scope_mode_selected", description: "One scope mode was explicitly selected." },
+        { id: "scope_contract_written", description: "In-scope/out-of-scope contract is documented." },
+        { id: "scope_user_approved", description: "User approved the final scope direction." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/02-scope.md`.",
+        "In-scope and out-of-scope lists are explicit.",
+        "Selected mode and rationale are documented.",
+        "Premise challenge findings documented.",
+        "Deferred items list with one-line rationale for each."
+    ],
+    inputs: ["brainstorm artifact", "timeline constraints", "product priorities"],
+    requiredContext: [
+        "approved brainstorm direction",
+        "existing capabilities and reusable components",
+        "delivery deadlines and risk tolerance"
+    ],
+    outputs: ["scope mode decision", "scope contract", "deferred scope list", "scope summary"],
+    blockers: [
+        "scope mode not selected",
+        "in/out boundaries ambiguous",
+        "critical premise disagreement unresolved"
+    ],
+    exitCriteria: [
+        "scope contract approved by user",
+        "required gates marked satisfied",
+        "deferred list recorded explicitly",
+        "scope summary produced"
+    ],
+    antiPatterns: [
+        "Scope silently expanded during discussion",
+        "No explicit out-of-scope section",
+        "Premise accepted without challenge",
+        "Batching multiple scope issues into one question",
+        "Re-arguing for smaller scope after user rejects reduction"
+    ],
+    rationalizations: [
+        { claim: "Scope can be finalized during implementation.", reality: "Late scope decisions create architecture churn and missed deadlines." },
+        { claim: "Mode selection is unnecessary overhead.", reality: "Mode selection makes trade-offs explicit and prevents silent drift." },
+        { claim: "Out-of-scope is obvious.", reality: "Unwritten exclusions return later as hidden requirements." },
+        { claim: "We do not need alternatives for a clear request.", reality: "Even clear requests benefit from a minimal-viable vs ideal comparison." }
+    ],
+    redFlags: [
+        "No selected mode in artifact",
+        "No deferred/not-in-scope section",
+        "No user approval marker",
+        "Premise challenge missing or superficial",
+        "No implementation alternatives evaluated"
+    ],
+    policyNeedles: ["Scope mode", "In Scope", "Out of Scope", "NOT in scope", "Premise Challenge"],
+    artifactFile: "02-scope.md",
+    next: "design",
+    cognitivePatterns: [
+        { name: "Classification Instinct", description: "Categorize every decision by reversibility x magnitude. Most things are two-way doors — move fast. Only slow down for irreversible + high-magnitude decisions." },
+        { name: "Inversion Reflex", description: "For every 'how do we win?' also ask 'what would make us fail?' Map failure modes before committing to scope." },
+        { name: "Focus as Subtraction", description: "Primary value-add is what to NOT do. Default: do fewer things, better. Every feature must earn its place." },
+        { name: "Speed Calibration", description: "Fast is default. Only slow down for irreversible + high-magnitude decisions. 70% information is enough to decide." },
+        { name: "Leverage Obsession", description: "Find inputs where small effort creates massive output. Reuse existing code aggressively. Build new only when nothing exists." },
+        { name: "Proxy Skepticism", description: "Is this metric/feature solving the actual problem or a proxy for it? Ask: if this succeeds perfectly, does the user's real problem go away?" },
+        { name: "Narrative Coherence", description: "The scope should tell a story: problem → insight → solution → impact. If you cannot tell that story in two sentences, scope is too broad or misframed." },
+        { name: "Blast Radius Awareness", description: "For every scope item, count how many systems/files/teams it touches. High blast radius = high risk = needs explicit justification." }
+    ],
+    reviewSections: [
+        {
+            title: "Scope Boundary Audit",
+            evaluationPoints: [
+                "Are all in-scope items justified by the problem statement?",
+                "Are any in-scope items actually solving a proxy problem instead of the real one?",
+                "Could any in-scope item be deferred without blocking the core objective?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Deferred Items Review",
+            evaluationPoints: [
+                "Does each deferred item have a one-line rationale?",
+                "Are any deferred items actually blockers for the core scope?",
+                "Will deferring these items create technical debt that is expensive to unwind?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Risk and Reversibility Check",
+            evaluationPoints: [
+                "For each major scope decision: is it reversible?",
+                "What is the blast radius if this decision is wrong?",
+                "Are there hidden dependencies between in-scope and out-of-scope items?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Existing-Code Reuse Check",
+            evaluationPoints: [
+                "Has every sub-problem been mapped to existing code?",
+                "Is the plan rebuilding anything that already exists?",
+                "Are there integration opportunities that reduce new code?",
+                "Have you searched for built-in or library solutions before scoping custom work?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Error & Rescue Scope Check",
+            evaluationPoints: [
+                "For every new capability: what breaks if it fails?",
+                "Is failure detection in scope or deferred? If deferred, is that acceptable?",
+                "Are there rescue/fallback paths for critical user journeys?",
+                "Is observability (logging, metrics, alerts) explicitly in or out of scope?"
+            ],
+            stopGate: true
+        }
+    ],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/01-brainstorm.md"],
+        writesTo: [".cclaw/artifacts/02-scope.md"],
+        traceabilityRule: "Every scope boundary must be traceable to a brainstorm decision. Every downstream design choice must stay within the scope contract."
+    },
+    artifactValidation: [
+        { section: "Prime Directives", required: true, validationRule: "Named error modes for each capability. Four paths per data flow." },
+        { section: "Premise Challenge", required: true, validationRule: "Must contain explicit answers to: right problem? direct path? what if nothing?" },
+        { section: "Scope Mode", required: true, validationRule: "Must state selected mode and rationale with default heuristic justification." },
+        { section: "In Scope / Out of Scope", required: true, validationRule: "Two separate explicit lists. Out-of-scope must not be empty." },
+        { section: "Deferred Items", required: true, validationRule: "Each item has one-line rationale. If empty, state 'None' explicitly." },
+        { section: "Error & Rescue Registry", required: true, validationRule: "Each scoped capability has: failure mode, detection method, fallback decision." },
+        { section: "Scope Summary", required: true, validationRule: "Clean summary: mode, strongest challenges, recommended path, accepted scope, deferred, excluded." }
+    ],
+    namedAntiPattern: {
+        title: "Scope Is Obvious From Context",
+        description: "Scope is never obvious. Unstated boundaries return as hidden requirements during implementation. Even when a request seems perfectly clear, the act of writing explicit in-scope and out-of-scope lists reveals assumptions that would otherwise surface as late surprises."
+    }
+};
+// ---------------------------------------------------------------------------
+// DESIGN — reference: gstack Eng review
+// ---------------------------------------------------------------------------
+const DESIGN = {
+    stage: "design",
+    skillFolder: "engineering-design-lock",
+    skillName: "engineering-design-lock",
+    skillDescription: "Engineering lock-in stage. Build a concrete technical spine before spec and planning, with section-by-section interactive review.",
+    hardGate: "Do NOT write implementation code. This stage produces design decisions and architecture documents only. No code changes, no scaffolding, no test files.",
+    purpose: "Lock architecture, data flow, failure modes, and test/performance expectations through rigorous interactive review.",
+    whenToUse: [
+        "After scope contract approval",
+        "Before writing final spec and execution plan",
+        "When architecture risks need explicit treatment"
+    ],
+    checklist: [
+        "Design Doc Check — read existing design docs, scope artifact, brainstorm artifact. If a design doc exists that covers this area, check for 'Supersedes:' and use the latest. Use upstream artifacts as source of truth.",
+        "Step 0: Scope Challenge — what existing code solves sub-problems? Minimum change set? Complexity check: 8+ files or 2+ new services = complexity smell → flag for possible scope reduction.",
+        "Search Before Building — For each technical choice (library, pattern, architecture), search for existing solutions. Label findings: Layer 1 (exact match), Layer 2 (partial match, needs adaptation), Layer 3 (inspiration only), EUREKA (unexpected perfect solution). Default to existing before custom.",
+        "Architecture Review — system design, component boundaries, data flow, scaling, security architecture. For each new codepath: one realistic production failure scenario.",
+        "Code Quality Review — code organization, DRY violations, error handling patterns, over/under-engineering assessment.",
+        "Test Review — diagram every new flow, data path, error path. For each: what test type covers it? Does one exist? What is the gap? Produce test plan artifact.",
+        "Performance Review — N+1 queries, memory concerns, caching opportunities, slow code paths. What breaks at 10x load? At 100x?",
+        "Parallelization Strategy — If multiple independent modules, produce dependency table: which can be built in parallel? Where are conflict risks? Flag shared-state modules.",
+        "Unresolved Decisions — List any design decisions that could not be resolved in this session. For each: what information is missing? Who can provide it? What is the default if no answer comes?",
+        "Distribution Check — If the plan creates new artifact types (packages, CLI tools, configs), document the build/publish story. How does it reach the user?"
+    ],
+    interactionProtocol: [
+        "Review architecture decisions section-by-section.",
+        "For EACH issue found in a review section, present it ONE AT A TIME. Do NOT batch multiple issues.",
+        "For each issue: use the Decision Protocol — describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, mark one as (recommended), use AskQuestion/AskUserQuestion tool when available.",
+        "Only proceed to the next review section after ALL issues in the current section are resolved.",
+        "If a section has no issues, say 'No issues found' and move on.",
+        "Do not skip failure-mode mapping.",
+        "For design baseline approval: present the full baseline and wait for explicit user approval."
+    ],
+    process: [
+        "Read upstream artifacts (brainstorm, scope).",
+        "Run Step 0 scope challenge: existing code leverage, minimum change set, complexity check.",
+        "Walk through each review section interactively.",
+        "Define architecture boundaries and ownership.",
+        "Describe data flow and state transitions with edge paths.",
+        "Map failure modes and recovery strategy.",
+        "Define test coverage strategy and performance budget.",
+        "Produce required outputs: NOT-in-scope section, What-already-exists section, diagrams, failure mode table.",
+        "Write design lock artifact for downstream spec/plan."
+    ],
+    requiredGates: [
+        { id: "design_scope_challenge_done", description: "Step 0 scope challenge completed with existing-code mapping." },
+        { id: "design_architecture_locked", description: "Architecture boundaries are explicit and approved." },
+        { id: "design_data_flow_mapped", description: "Data/state flow includes edge-case paths." },
+        { id: "design_failure_modes_mapped", description: "Failure modes and mitigations are documented." },
+        { id: "design_test_and_perf_defined", description: "Test strategy and performance budget are defined." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/03-design.md`.",
+        "Failure-mode table exists with mitigations.",
+        "Test strategy includes unit/integration/e2e expectations.",
+        "NOT-in-scope section produced.",
+        "What-already-exists section produced."
+    ],
+    inputs: ["scope contract", "system constraints", "non-functional requirements"],
+    requiredContext: [
+        "existing architecture and boundaries",
+        "operational constraints",
+        "security and reliability expectations"
+    ],
+    outputs: [
+        "architecture lock",
+        "risk and failure map",
+        "test and performance baseline",
+        "NOT-in-scope section",
+        "What-already-exists section"
+    ],
+    blockers: [
+        "architecture ambiguity remains",
+        "failure modes not mapped",
+        "test/performance targets missing"
+    ],
+    exitCriteria: [
+        "design baseline approved",
+        "all review sections completed",
+        "required gates marked satisfied",
+        "artifact complete for spec handoff"
+    ],
+    antiPatterns: [
+        "Architecture deferred to implementation phase",
+        "Missing data-flow edge cases",
+        "No performance budget for critical path",
+        "Batching multiple design issues into one question",
+        "Skipping review sections because plan seems simple"
+    ],
+    rationalizations: [
+        { claim: "Architecture can emerge incrementally while coding.", reality: "Unplanned architecture decisions cause incompatible module boundaries." },
+        { claim: "Failure modes are edge cases we can ignore for now.", reality: "Production incidents usually come from unplanned edge paths." },
+        { claim: "Performance can be optimized after launch.", reality: "Missing performance budgets make regressions invisible until late." },
+        { claim: "This is a strategy doc so implementation sections do not apply.", reality: "Implementation details are where strategy breaks down. Every section must be evaluated." }
+    ],
+    redFlags: [
+        "No explicit architecture boundary section",
+        "No failure recovery strategy",
+        "No defined test/perf baseline",
+        "Review sections skipped or condensed",
+        "No NOT-in-scope output section"
+    ],
+    policyNeedles: [
+        "Architecture",
+        "Data Flow",
+        "Failure Modes and Mitigation",
+        "Performance Budget",
+        "One issue at a time"
+    ],
+    artifactFile: "03-design.md",
+    next: "spec",
+    cognitivePatterns: [
+        { name: "Boring By Default", description: "Every company gets about three innovation tokens. Everything else should be proven technology. If the plan rolls a custom solution where a built-in exists, flag it." },
+        { name: "Incremental Over Revolutionary", description: "Strangler fig, not big bang. Canary, not global rollout. Refactor, not rewrite." },
+        { name: "Systems Over Heroes", description: "Design for tired humans at 3am, not your best engineer on their best day. If it requires heroics to operate, the design is wrong." },
+        { name: "Essential vs Accidental Complexity", description: "Before adding anything: is this solving a real problem or one we created? Distinguish essential complexity from accidental." },
+        { name: "Blast Radius Instinct", description: "Every decision evaluated through: what is the worst case and how many systems/people does it affect?" },
+        { name: "Completeness Push", description: "AI effort is cheap. Push for completeness in plans: cover all files in blast radius, all edge cases in touched code, all affected tests. Favor doing it now over creating a TODO." },
+        { name: "Owner Preference Alignment", description: "Every recommendation must align with project conventions (DRY, test style, minimal diff, edge-case rigor). Read existing patterns before recommending new ones." }
+    ],
+    reviewSections: [
+        {
+            title: "Architecture Review",
+            evaluationPoints: [
+                "System design and component boundaries",
+                "Dependency graph and coupling concerns",
+                "Data flow patterns and potential bottlenecks",
+                "Scaling characteristics and single points of failure",
+                "Security architecture (auth, data access, API boundaries)",
+                "For each new codepath: one realistic production failure scenario"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Code Quality Review",
+            evaluationPoints: [
+                "Code organization and module structure",
+                "DRY violations — flag aggressively",
+                "Error handling patterns and missing edge cases",
+                "Over-engineered or under-engineered areas",
+                "Existing diagrams in touched files — still accurate?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Test Review",
+            evaluationPoints: [
+                "Diagram every new UX flow, data flow, codepath, background job, integration, error path",
+                "For each: what type of test covers it? Does one exist? What is the gap?",
+                "Coverage expectations: unit, integration, e2e split"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Performance Review",
+            evaluationPoints: [
+                "N+1 queries and database access patterns",
+                "Memory-usage concerns",
+                "Caching opportunities",
+                "Slow or high-complexity code paths",
+                "What breaks at 10x load? At 100x?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Distribution & Delivery Review",
+            evaluationPoints: [
+                "If new artifact types are created (packages, CLI, configs): is the build/publish story documented?",
+                "Are there new dependencies that need version pinning?",
+                "Does the change affect existing consumers (APIs, shared modules)?",
+                "Is backwards compatibility maintained or is a migration needed?"
+            ],
+            stopGate: false
+        }
+    ],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/01-brainstorm.md", ".cclaw/artifacts/02-scope.md"],
+        writesTo: [".cclaw/artifacts/03-design.md"],
+        traceabilityRule: "Every architecture decision must trace to a scope boundary. Every downstream spec requirement must trace to a design decision."
+    },
+    artifactValidation: [
+        { section: "Architecture Boundaries", required: true, validationRule: "Must list component boundaries with ownership." },
+        { section: "Data Flow", required: true, validationRule: "Must include happy path, nil input, empty input, upstream error paths." },
+        { section: "Failure Mode Table", required: true, validationRule: "Each failure mode has: trigger, detection, mitigation, user impact." },
+        { section: "Test Strategy", required: true, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
+        { section: "NOT in scope", required: true, validationRule: "Work considered and explicitly deferred with one-line rationale." },
+        { section: "Parallelization Strategy", required: false, validationRule: "If multi-module: dependency table, parallel lanes, conflict flags." },
+        { section: "Unresolved Decisions", required: false, validationRule: "If any: what info is missing, who provides it, default if unanswered." }
+    ],
+    namedAntiPattern: {
+        title: "Architecture Will Emerge While Coding",
+        description: "Emergent architecture is a myth for non-trivial systems. What actually emerges is accidental complexity, incompatible module boundaries, and tech debt that costs 10x to fix later. Lock architecture explicitly before writing code."
+    },
+    decisionRecordFormat: `### Decision: [TITLE]
+**Status:** Proposed | Accepted | Rejected
+**Context:** [What is the situation?]
+**Options:**
+- A: [option] — effort: [S/M/L], risk: [low/med/high]
+- B: [option] — effort: [S/M/L], risk: [low/med/high]
+**Decision:** [chosen option]
+**Rationale:** [why this option over others]
+**Consequences:** [what changes as a result]`
+};
+// ---------------------------------------------------------------------------
+// SPEC
+// ---------------------------------------------------------------------------
+const SPEC = {
+    stage: "spec",
+    skillFolder: "specification-authoring",
+    skillName: "specification-authoring",
+    skillDescription: "Specification stage. Produce measurable, testable requirements without ambiguity.",
+    hardGate: "Do NOT plan tasks or write implementation code. This stage produces a specification document only. Every requirement must be expressed in observable, testable terms.",
+    purpose: "Create a testable specification aligned with approved design and constraints.",
+    whenToUse: [
+        "After design lock",
+        "Before planning and implementation",
+        "When acceptance criteria must be measurable"
+    ],
+    checklist: [
+        "Read upstream — load design artifact and scope contract. Cross-reference architecture decisions.",
+        "Define measurable acceptance criteria — each criterion must be observable and falsifiable. No vague adjectives.",
+        "Capture edge cases — for each criterion, define at least one boundary condition and one error condition.",
+        "Document constraints and assumptions — regulatory, system, integration, and performance boundaries. Surface implicit assumptions explicitly.",
+        "Confirm testability — for each acceptance criterion, describe the test that would prove it. If untestable, rewrite the criterion.",
+        "Write spec artifact and request user approval — wait for explicit confirmation before proceeding."
+    ],
+    interactionProtocol: [
+        "Express each requirement in observable terms.",
+        "Resolve ambiguity before moving to plan. Challenge vague language.",
+        "Capture assumptions explicitly, not implicitly.",
+        "Require user confirmation on the written spec.",
+        "For each criterion, ask: how would you test this? If the answer is unclear, rewrite."
+    ],
+    process: [
+        "Define measurable acceptance criteria.",
+        "Capture constraints, assumptions, and edge cases.",
+        "Build testability map: criterion -> test description.",
+        "Confirm testability for each criterion.",
+        "Write spec artifact and request approval."
+    ],
+    requiredGates: [
+        { id: "spec_acceptance_measurable", description: "Acceptance criteria are measurable and observable." },
+        { id: "spec_edge_cases_documented", description: "Boundary and error conditions are defined for each criterion." },
+        { id: "spec_constraints_documented", description: "Constraints and assumptions are explicit." },
+        { id: "spec_testability_confirmed", description: "Each criterion has a described test method." },
+        { id: "spec_user_approved", description: "User approved the final written spec." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/04-spec.md`.",
+        "Each acceptance criterion maps to a testable outcome.",
+        "Edge cases documented per criterion.",
+        "Approval marker captured in artifact."
+    ],
+    inputs: ["design artifact", "business constraints", "quality requirements"],
+    requiredContext: [
+        "design lock baseline",
+        "regulatory or system boundaries",
+        "integration constraints"
+    ],
+    outputs: [
+        "measurable specification",
+        "acceptance-to-testability map",
+        "approved spec artifact"
+    ],
+    blockers: [
+        "non-measurable criteria",
+        "constraints missing",
+        "open ambiguities remain"
+    ],
+    exitCriteria: [
+        "spec approved by user",
+        "required gates marked satisfied",
+        "plan-ready acceptance mapping exists",
+        "testability confirmed for all criteria"
+    ],
+    antiPatterns: [
+        "High-level goals without measurable outcomes",
+        "Implicit assumptions",
+        "Proceeding to plan before approval",
+        "Using vague adjectives (fast, intuitive, robust) without thresholds"
+    ],
+    rationalizations: [
+        { claim: "The implementation will clarify this requirement.", reality: "Unclear specs create rework and contradictory implementations." },
+        { claim: "Acceptance criteria do not need to be measurable.", reality: "Without measurability, verification becomes subjective." },
+        { claim: "We can skip explicit approval to save time.", reality: "Skipping approval shifts uncertainty into later, costlier stages." },
+        { claim: "Edge cases are implementation details.", reality: "Edge cases determine acceptance boundaries; specifying them prevents scope creep." }
+    ],
+    redFlags: [
+        "Criteria use vague language (fast, intuitive, robust) without thresholds",
+        "No explicit assumptions section",
+        "No approval record",
+        "No testability mapping",
+        "Edge cases missing or deferred"
+    ],
+    policyNeedles: ["Acceptance Criteria", "Constraints", "Testability", "approved spec", "Edge Cases"],
+    artifactFile: "04-spec.md",
+    next: "plan",
+    cognitivePatterns: [
+        { name: "Observable Over Descriptive", description: "Requirements describe what can be observed, not what should feel like. Replace every adjective with a measurement." },
+        { name: "Boundary Precision", description: "Every acceptance criterion has boundary conditions. What is the minimum valid input? Maximum? What happens at the edges?" },
+        { name: "Assumption Surfacing", description: "Implicit assumptions are invisible requirements. Force every assumption into an explicit statement. If you cannot name the assumption, you have not found it yet." }
+    ],
+    reviewSections: [],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
+        writesTo: [".cclaw/artifacts/04-spec.md"],
+        traceabilityRule: "Every acceptance criterion must trace to a design decision. Every downstream plan task must trace to a spec criterion."
+    },
+    artifactValidation: [
+        { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable." },
+        { section: "Edge Cases", required: true, validationRule: "At least one boundary and one error condition per criterion." },
+        { section: "Constraints and Assumptions", required: true, validationRule: "All implicit assumptions surfaced. Constraints have sources." },
+        { section: "Testability Map", required: true, validationRule: "Each criterion maps to a concrete test description." },
+        { section: "Approval", required: true, validationRule: "Explicit user approval marker present." }
+    ]
+};
+// ---------------------------------------------------------------------------
+// PLAN
+// ---------------------------------------------------------------------------
+const PLAN = {
+    stage: "plan",
+    skillFolder: "planning-and-task-breakdown",
+    skillName: "planning-and-task-breakdown",
+    skillDescription: "Execution planning stage with strict confirmation gate before implementation.",
+    hardGate: "Do NOT write code or tests. Planning only. This stage produces a task graph and execution order. WAIT_FOR_CONFIRM before any handoff to implementation.",
+    purpose: "Create small executable tasks with dependencies and pause for explicit user confirmation.",
+    whenToUse: [
+        "After spec approval",
+        "Before writing tests or implementation",
+        "When delivery path and dependency order are needed"
+    ],
+    checklist: [
+        "Read upstream — load spec, design, and scope artifacts. Cross-reference acceptance criteria.",
+        "Build dependency graph — identify task ordering, parallel opportunities, and blocking dependencies.",
+        "Group tasks into dependency waves — wave N+1 cannot start until wave N has verification evidence.",
+        "Slice into vertical tasks — each task targets 2-5 minutes, produces one testable outcome, and touches one coherent area.",
+        "Attach verification — every task has an acceptance criterion mapping and a concrete verification command.",
+        "Define checkpoints — mark points where progress should be validated before continuing.",
+        "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. Do NOT proceed to /cc-test until user confirms."
+    ],
+    interactionProtocol: [
+        "Plan in read-only mode relative to implementation.",
+        "Split work into small vertical slices (target 2-5 minute tasks).",
+        "Publish explicit dependency waves with entry and exit checks for each wave.",
+        "Attach verification step to every task.",
+        "Enforce WAIT_FOR_CONFIRM before moving to /cc-test. Use AskQuestion/AskUserQuestion tool: present the plan summary with options (A) Approve / (B) Revise / (C) Reject.",
+        "Wait for explicit approval. Do not auto-advance."
+    ],
+    process: [
+        "Build dependency graph and ordered slices.",
+        "Group slices into execution waves and define gate criteria per wave.",
+        "Define each task with acceptance mapping and verification commands.",
+        "Record checkpoints and blockers.",
+        "Write plan artifact and pause at WAIT_FOR_CONFIRM."
+    ],
+    requiredGates: [
+        { id: "plan_tasks_sliced_2_5_min", description: "Tasks are small, executable slices." },
+        { id: "plan_dependency_graph_written", description: "Dependency graph and order are explicit." },
+        { id: "plan_dependency_waves_defined", description: "Tasks are grouped into executable waves with gate checks." },
+        { id: "plan_verification_steps_defined", description: "Each task has verification guidance." },
+        { id: "plan_acceptance_mapped", description: "Each task maps to a spec acceptance criterion." },
+        { id: "plan_wait_for_confirm", description: "Execution blocked until explicit user confirmation." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/05-plan.md`.",
+        "Task list includes acceptance mapping.",
+        "Dependency graph documented.",
+        "Dependency waves documented with wave-by-wave verification gates.",
+        "WAIT_FOR_CONFIRM status recorded."
+    ],
+    inputs: ["approved spec", "codebase context", "delivery constraints"],
+    requiredContext: [
+        "spec acceptance criteria",
+        "current architecture",
+        "known technical debt and dependencies"
+    ],
+    outputs: ["task graph", "dependency wave plan", "ordered plan", "explicit confirmation checkpoint"],
+    blockers: [
+        "tasks too broad",
+        "dependency uncertainty unresolved",
+        "wave boundaries are unclear",
+        "no explicit confirmation"
+    ],
+    exitCriteria: [
+        "plan quality gates complete",
+        "WAIT_FOR_CONFIRM present and unresolved until user approves",
+        "artifact ready for TDD execution",
+        "acceptance mapping complete"
+    ],
+    antiPatterns: [
+        "Horizontal decomposition without end-to-end slices",
+        "Tasks without verification steps",
+        "Starting execution before approval",
+        "Tasks that touch multiple unrelated areas"
+    ],
+    rationalizations: [
+        { claim: "Task details can be finalized during coding.", reality: "Underspecified tasks cause context thrash and broken sequencing." },
+        { claim: "Dependency map is overkill for this change.", reality: "Missing dependencies are a major source of blocked execution." },
+        { claim: "We can assume approval and continue.", reality: "Explicit confirmation is the contract boundary between planning and execution." }
+    ],
+    redFlags: [
+        "No dependency graph",
+        "No WAIT_FOR_CONFIRM marker",
+        "No explicit dependency waves",
+        "Tasks exceed one coherent outcome",
+        "No acceptance mapping"
+    ],
+    policyNeedles: ["WAIT_FOR_CONFIRM", "Task Graph", "Dependency Waves", "Acceptance Mapping", "verification steps"],
+    artifactFile: "05-plan.md",
+    next: "test",
+    cognitivePatterns: [
+        { name: "Vertical Slice Thinking", description: "Each task delivers one thin end-to-end slice of value. Horizontal layers (all models, then all controllers) create integration risk. Vertical slices (one feature through all layers) reduce it." },
+        { name: "Two-Minute Smell Test", description: "If a competent engineer cannot understand and start a task in two minutes, the task is too large or too vague. Break it down further." },
+        { name: "Make the Change Easy, Then Make the Easy Change", description: "Refactor first, implement second. Never structural + behavioral changes simultaneously. Sequence tasks accordingly." }
+    ],
+    reviewSections: [],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/03-design.md", ".cclaw/artifacts/02-scope.md"],
+        writesTo: [".cclaw/artifacts/05-plan.md"],
+        traceabilityRule: "Every task must trace to a spec acceptance criterion. Every downstream RED test must trace to a plan task."
+    },
+    artifactValidation: [
+        { section: "Dependency Graph", required: true, validationRule: "Ordering and parallel opportunities explicit. No circular dependencies." },
+        { section: "Dependency Waves", required: true, validationRule: "Every task belongs to a wave. Each wave has an exit gate and dependency statement." },
+        { section: "Task List", required: true, validationRule: "Each task: ID, description, acceptance criterion link, verification command." },
+        { section: "Acceptance Mapping", required: true, validationRule: "Every spec criterion is covered by at least one task." },
+        { section: "WAIT_FOR_CONFIRM", required: true, validationRule: "Explicit marker present. Status: pending until user approves." }
+    ]
+};
+// ---------------------------------------------------------------------------
+// TEST — TDD RED stage
+// ---------------------------------------------------------------------------
+const TEST = {
+    stage: "test",
+    skillFolder: "red-first-testing",
+    skillName: "red-first-testing",
+    skillDescription: "TDD RED stage. Establish failing tests as proof before implementation changes.",
+    hardGate: "Do NOT change implementation code. This stage writes failing tests ONLY. If you find yourself editing non-test files, STOP — you have left the RED stage.",
+    purpose: "Create RED evidence tied to acceptance criteria before any implementation.",
+    whenToUse: [
+        "After plan confirmation",
+        "Before /cc-build",
+        "For every behavior change in scope"
+    ],
+    checklist: [
+        "Select plan slice — pick one task from the plan. Do not batch multiple tasks.",
+        "Map to acceptance criterion — identify the specific spec criterion this test proves.",
+        "Write behavior-focused test — test the expected behavior, not implementation details. Name tests descriptively.",
+        "Run tests and observe failure — tests MUST fail. If they pass, either the behavior already exists or the test is wrong.",
+        "Capture failure output — copy the exact failure output as RED evidence. Record in artifact.",
+        "Repeat for each slice — return to step 1 for the next plan slice."
+    ],
+    interactionProtocol: [
+        "Pick one planned slice at a time.",
+        "Write behavior-focused tests before changing implementation.",
+        "Capture and store failing output as RED evidence.",
+        "Do not proceed to build without RED evidence.",
+        "If a test passes unexpectedly, investigate: does the behavior already exist, or is the test wrong?"
+    ],
+    process: [
+        "Select slice and map to acceptance criterion.",
+        "Write test(s) that fail for expected reason.",
+        "Run tests and capture failure output.",
+        "Record RED evidence in TDD artifact.",
+        "Verify failure reason matches expected missing behavior."
+    ],
+    requiredGates: [
+        { id: "tdd_red_test_written", description: "Failing tests exist before implementation changes." },
+        { id: "tdd_red_failure_captured", description: "Failure output is captured as evidence." },
+        { id: "tdd_trace_to_acceptance", description: "RED tests trace to explicit acceptance criteria." },
+        { id: "tdd_red_failure_reason_verified", description: "Failure is for the expected reason, not an unrelated error." }
+    ],
+    requiredEvidence: [
+        "Artifact updated at `.cclaw/artifacts/06-tdd.md` RED section.",
+        "Failing command output captured.",
+        "Acceptance mapping documented.",
+        "Failure reason analysis recorded."
+    ],
+    inputs: ["approved plan slice", "spec acceptance criterion", "test harness configuration"],
+    requiredContext: ["plan artifact", "spec artifact", "existing test patterns"],
+    outputs: ["failing test set", "captured RED evidence", "ready signal for GREEN stage"],
+    blockers: [
+        "tests pass before behavior change",
+        "failure reason does not match expected behavior",
+        "no evidence recorded"
+    ],
+    exitCriteria: [
+        "RED evidence exists and is traceable",
+        "required gates marked satisfied",
+        "no implementation changes made in this stage",
+        "failure reason verified for each test"
+    ],
+    antiPatterns: [
+        "Writing code before failing test",
+        "Asserting implementation details instead of behavior",
+        "Skipping evidence capture",
+        "Testing multiple slices without recording evidence for each"
+    ],
+    rationalizations: [
+        { claim: "This change is obvious, tests can be added later.", reality: "Without RED proof, regressions hide behind optimistic assumptions." },
+        { claim: "A passing baseline is enough to continue.", reality: "Baseline pass does not prove new behavior requirements." },
+        { claim: "One broad integration test is enough.", reality: "Slice-level RED tests are required for precise failure signal." }
+    ],
+    redFlags: [
+        "No failing test output",
+        "No acceptance linkage",
+        "Implementation edits appear before RED evidence",
+        "Test passes without behavior change"
+    ],
+    policyNeedles: ["RED", "failing test", "acceptance criteria", "no implementation changes"],
+    artifactFile: "06-tdd.md",
+    next: "build",
+    cognitivePatterns: [
+        { name: "Behavior Over Implementation", description: "Tests describe WHAT the system does, not HOW. Test the observable behavior from outside the unit. If you need to test internals, the design needs work." },
+        { name: "Failure-First Thinking", description: "The failing test IS the specification. Until you see the right failure, you do not understand what you are building. Wrong failures are information." },
+        { name: "Proof Before Claim", description: "Do not claim a feature works without evidence. RED output is proof of what is missing. GREEN output is proof it was added. Both are required." }
+    ],
+    reviewSections: [],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
+        writesTo: [".cclaw/artifacts/06-tdd.md"],
+        traceabilityRule: "Every RED test traces to a plan task. Every plan task traces to a spec criterion. Evidence chain: spec -> plan -> RED test -> failure output."
+    },
+    artifactValidation: [
+        { section: "RED Evidence", required: true, validationRule: "Failing test output captured per slice." },
+        { section: "Acceptance Mapping", required: true, validationRule: "Each RED test links to a plan task and spec criterion." },
+        { section: "Failure Analysis", required: true, validationRule: "Failure reason matches expected missing behavior." }
+    ]
+};
+// ---------------------------------------------------------------------------
+// BUILD — TDD GREEN + REFACTOR stage
+// ---------------------------------------------------------------------------
+const BUILD = {
+    stage: "build",
+    skillFolder: "incremental-implementation",
+    skillName: "incremental-implementation",
+    skillDescription: "TDD GREEN and REFACTOR stage with strict traceability to plan slices.",
+    hardGate: "Do NOT merge, ship, or skip review. This stage produces GREEN and REFACTOR evidence for one plan slice at a time. If you are touching files unrelated to the current slice, STOP.",
+    purpose: "Implement minimal passing change, run full suite GREEN, then refactor safely.",
+    whenToUse: [
+        "After RED evidence is complete",
+        "For one accepted plan slice at a time",
+        "Before review stage"
+    ],
+    checklist: [
+        "Minimal GREEN change — implement the smallest code change that makes the RED tests pass. No extra features.",
+        "Run full suite — execute ALL tests, not just the ones you wrote. The full suite must be GREEN.",
+        "Verify no regressions — if any existing test breaks, fix the regression before proceeding.",
+        "Refactor pass — improve code quality without changing behavior. Document what you changed and why.",
+        "Record evidence — capture GREEN output and REFACTOR notes in the TDD artifact.",
+        "Annotate traceability — link the implementation to the plan task ID and spec criterion."
+    ],
+    interactionProtocol: [
+        "Apply minimal change to satisfy RED tests.",
+        "Run full suite, not partial checks, for GREEN validation.",
+        "Refactor without changing behavior and document rationale.",
+        "Stop if regressions appear and return to prior step.",
+        "Record traceability to plan slice explicitly."
+    ],
+    process: [
+        "Implement smallest change needed for GREEN.",
+        "Run full tests and build checks.",
+        "Perform refactor pass preserving behavior.",
+        "Record GREEN and REFACTOR evidence in artifact.",
+        "Annotate traceability to plan task and spec criterion."
+    ],
+    requiredGates: [
+        { id: "build_minimal_change_applied", description: "Implementation matches a single plan slice." },
+        { id: "tdd_green_full_suite", description: "Full relevant suite passes in GREEN state." },
+        { id: "tdd_refactor_completed", description: "Refactor pass completed with behavior preservation verified." },
+        { id: "tdd_refactor_notes_written", description: "Refactor decisions and outcomes are documented." },
+        { id: "build_traceable_to_plan", description: "Change traceability to plan slice is explicit." }
+    ],
+    requiredEvidence: [
+        "Artifact `.cclaw/artifacts/06-tdd.md` includes GREEN and REFACTOR sections.",
+        "Full test/build output recorded.",
+        "Traceability to task identifier is documented.",
+        "Refactor rationale captured."
+    ],
+    inputs: ["RED evidence", "approved plan slice", "coding standards and constraints"],
+    requiredContext: ["tdd artifact", "plan artifact", "spec acceptance criteria"],
+    outputs: ["passing implementation", "refactor evidence", "review-ready change set"],
+    blockers: [
+        "no RED evidence",
+        "full suite not green",
+        "behavior changed during refactor"
+    ],
+    exitCriteria: [
+        "GREEN evidence captured",
+        "REFACTOR evidence captured",
+        "required gates marked satisfied",
+        "traceability annotated"
+    ],
+    antiPatterns: [
+        "Big-bang implementation across multiple slices",
+        "Partial test runs presented as GREEN",
+        "Undocumented refactor changes",
+        "Adding features beyond what RED tests require"
+    ],
+    rationalizations: [
+        { claim: "Refactor can be skipped for speed.", reality: "Skipping refactor accumulates debt and weakens maintainability." },
+        { claim: "Only changed tests need to pass.", reality: "Full-suite checks are needed to detect regressions." },
+        { claim: "Traceability is implied by commit diff.", reality: "Explicit mapping avoids ambiguity in review and rollback." }
+    ],
+    redFlags: [
+        "No full-suite GREEN evidence",
+        "No refactor notes",
+        "Multiple tasks implemented in one pass without justification",
+        "Files changed outside current slice scope"
+    ],
+    policyNeedles: ["GREEN", "full test suite", "REFACTOR", "traceable to plan slice"],
+    artifactFile: "06-tdd.md",
+    next: "review",
+    cognitivePatterns: [
+        { name: "Minimal Viable Change", description: "The best implementation is the smallest one that passes all RED tests. Every extra line is risk. Resist the urge to 'improve while you are here.'" },
+        { name: "Regression Paranoia", description: "Assume every change breaks something until the full suite proves otherwise. Partial test runs are lies of omission." },
+        { name: "Refactor-as-Hygiene", description: "Refactoring is not optional cleanup — it is the third leg of TDD. GREEN without REFACTOR accumulates mess. REFACTOR without GREEN breaks things." }
+    ],
+    reviewSections: [],
+    completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/05-plan.md"],
+        writesTo: [".cclaw/artifacts/06-tdd.md"],
+        traceabilityRule: "Every GREEN change traces to a RED test. Every RED test traces to a plan task. Evidence chain must be unbroken."
+    },
+    artifactValidation: [
+        { section: "GREEN Evidence", required: true, validationRule: "Full suite pass output captured." },
+        { section: "REFACTOR Notes", required: true, validationRule: "What changed, why, behavior preservation confirmed." },
+        { section: "Traceability", required: true, validationRule: "Plan task ID and spec criterion linked." }
+    ]
+};
+// ---------------------------------------------------------------------------
+// REVIEW — reference: superpowers code-review + gstack /review
+// ---------------------------------------------------------------------------
+const REVIEW = {
+    stage: "review",
+    skillFolder: "two-layer-review",
+    skillName: "two-layer-review",
+    skillDescription: "Two-layer review stage: spec compliance first, then code quality and production readiness. Section-by-section with severity discipline.",
+    hardGate: "Do NOT ship, merge, or release until both review layers complete with an explicit verdict. No exceptions for urgency. Critical blockers MUST be resolved before handoff.",
+    purpose: "Validate that implementation matches spec and meets quality/security/performance bar through structured two-layer review.",
+    whenToUse: [
+        "After build stage completes",
+        "Before any ship action",
+        "When release risk must be assessed explicitly"
+    ],
+    checklist: [
+        "Diff Scope — Run `git diff` against base branch. If no diff, exit early with APPROVED (no changes to review). Scope the review to changed files unless blast-radius analysis requires wider inspection.",
+        "Change-Size Check — ~100 lines = normal. ~300 lines = consider splitting. ~1000+ lines = strongly recommend stacked PRs. Flag large diffs to the user.",
+        "Load upstream evidence — read TDD artifact (RED + GREEN + REFACTOR), spec, and plan. Verify evidence chain is unbroken.",
+        "Layer 1: Spec Compliance — check every acceptance criterion against implementation. Verdict: pass/fail per criterion.",
+        "Layer 2a: Correctness — logic errors, race conditions, boundary violations, null handling.",
+        "Layer 2b: Security — input validation, auth boundaries, secrets exposure, injection vectors.",
+        "Layer 2c: Performance — N+1 queries, memory leaks, missing caching, hot paths.",
+        "Layer 2d: Architecture Fit — does the implementation match the locked design? Coupling, cohesion, interface contracts.",
+        "Layer 2e: External Safety — SQL safety, concurrency, secrets in logs, enum completeness (grep outside diff), LLM trust boundaries.",
+        "Review Army reconciliation — normalize findings into structured records, dedup by fingerprint, and mark multi-specialist confirmations.",
+        "Meta-Review — Were tests actually run? Do test names match what they test? Are there real assertions?",
+        "Classify findings — Critical (blocks ship), Important (should fix), Suggestion (optional improvement).",
+        "Produce verdict — APPROVED, APPROVED_WITH_CONCERNS, or BLOCKED."
+    ],
+    interactionProtocol: [
+        "Run Layer 1 (spec compliance) completely before starting Layer 2.",
+        "In each review section, present findings ONE AT A TIME. Do NOT batch.",
+        "Classify every finding as Critical, Important, or Suggestion.",
+        "For each Critical finding: use the Decision Protocol — present resolution options (A/B/C) with trade-offs, mark one as (recommended), use AskQuestion/AskUserQuestion tool when available.",
+        "Resolve all critical blockers before ship.",
+        "For final verdict: use AskQuestion/AskUserQuestion tool with options APPROVED / APPROVED_WITH_CONCERNS / BLOCKED."
+    ],
+    process: [
+        "Layer 1: check acceptance criteria and requirement coverage.",
+        "Layer 2a: check correctness — logic, races, boundaries, null handling.",
+        "Layer 2b: check security — validation, auth, secrets, injection.",
+        "Layer 2c: check performance — queries, memory, caching, hot paths.",
+        "Layer 2d: check architecture fit — design compliance, coupling, interfaces.",
+        "Reconcile multi-agent findings into `.cclaw/artifacts/07-review-army.json` (dedup + confidence + conflict notes).",
+        "Classify and prioritize all findings.",
+        "Write review report artifact with explicit verdict."
+    ],
+    requiredGates: [
+        { id: "review_layer1_spec_compliance", description: "Spec compliance check completed with per-criterion verdict." },
+        { id: "review_layer2_correctness", description: "Correctness review completed." },
+        { id: "review_layer2_security", description: "Security review completed." },
+        { id: "review_layer2_performance", description: "Performance review completed." },
+        { id: "review_layer2_architecture", description: "Architecture fit review completed." },
+        { id: "review_severity_classified", description: "All findings are severity-tagged." },
+        { id: "review_criticals_resolved", description: "No unresolved critical blockers remain." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/07-review.md`.",
+        "Artifact written to `.cclaw/artifacts/07-review-army.json`.",
+        "Layer 1 verdict captured with per-criterion pass/fail.",
+        "Layer 2 sections completed with findings.",
+        "Severity log includes critical/important/suggestion buckets.",
+        "Explicit final verdict: APPROVED, APPROVED_WITH_CONCERNS, or BLOCKED."
+    ],
+    inputs: ["implementation diff", "spec and plan artifacts", "test/build evidence"],
+    requiredContext: ["spec criteria", "tdd artifact", "rulebook constraints"],
+    outputs: ["review verdict", "severity-indexed findings", "reconciled review-army findings", "ship readiness decision"],
+    blockers: [
+        "layer 1 failed",
+        "critical findings unresolved",
+        "missing regression evidence"
+    ],
+    exitCriteria: [
+        "both layers completed",
+        "all review sections evaluated",
+        "critical blockers resolved",
+        "ship readiness explicitly stated"
+    ],
+    antiPatterns: [
+        "Single generic review without layered structure",
+        "No severity classification",
+        "Shipping with open criticals",
+        "Batching multiple findings into one report without individual resolution",
+        "Skipping Layer 2 sections because Layer 1 passed"
+    ],
+    rationalizations: [
+        { claim: "Passing tests mean spec compliance by default.", reality: "Tests can miss requirement mismatches; explicit spec review is mandatory." },
+        { claim: "Severity labels are unnecessary.", reality: "Without severity, release decisions become inconsistent." },
+        { claim: "Critical issues can be fixed after ship.", reality: "Critical blockers must be resolved before release handoff." },
+        { claim: "Security review is not needed for internal tools.", reality: "Internal tools become external surface area. Security is always in scope." }
+    ],
+    redFlags: [
+        "No separate Layer 1/Layer 2 outcomes",
+        "No structured review-army reconciliation artifact",
+        "No critical bucket",
+        "No explicit ready/not-ready verdict",
+        "Review sections skipped or abbreviated",
+        "Findings not classified by severity"
+    ],
+    policyNeedles: ["Layer 1", "Layer 2", "Critical", "Review Army", "Ready to Ship", "One issue at a time"],
+    artifactFile: "07-review.md",
+    next: "ship",
+    cognitivePatterns: [
+        { name: "Severity Discipline", description: "Every finding gets a severity label. Critical blocks ship. Important should be fixed. Suggestion is optional. No ambiguous middle ground." },
+        { name: "Spec-First Not Code-First", description: "Review starts with the spec, not the code. Does the code do what was specified? Only after spec compliance is confirmed do you review code quality." },
+        { name: "Blocker Resolution Before Progress", description: "When a critical finding is identified, stop and resolve it before continuing the review. Do not accumulate criticals for batch resolution." },
+        { name: "Evidence or Unknown", description: "For every safety/correctness claim, cite file:line or test name. If you cannot point to evidence, the claim is 'UNKNOWN' not 'safe'. Never say 'probably tested' — check." },
+        { name: "Diff-Scoped Thinking", description: "Start with the diff (git diff vs main). Review only what changed unless a change has blast-radius implications. Skip unchanged files unless directly affected." },
+        { name: "Change-Size Awareness", description: "~100 lines = normal review. ~300 lines = consider splitting. ~1000+ lines = strongly recommend splitting into stacked PRs. Large diffs hide bugs." }
+    ],
+    reviewSections: [
+        {
+            title: "Layer 1: Spec Compliance",
+            evaluationPoints: [
+                "For each acceptance criterion: does the implementation satisfy it?",
+                "Are there spec requirements with no corresponding implementation?",
+                "Are there implementations with no corresponding spec requirement (scope creep)?",
+                "Is every edge case from the spec handled?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Layer 2a: Correctness",
+            evaluationPoints: [
+                "Logic errors and boundary violations",
+                "Race conditions and concurrency issues",
+                "Null/undefined handling",
+                "Error propagation and recovery paths"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Layer 2b: Security",
+            evaluationPoints: [
+                "Input validation completeness",
+                "Authorization boundary enforcement",
+                "Secrets exposure risk",
+                "Injection vector assessment"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Layer 2c: Performance",
+            evaluationPoints: [
+                "N+1 query patterns",
+                "Memory leak potential",
+                "Missing caching opportunities",
+                "Hot path complexity analysis"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Layer 2d: Architecture Fit",
+            evaluationPoints: [
+                "Does implementation match the locked design?",
+                "Coupling and cohesion assessment",
+                "Interface contract compliance",
+                "Unintended architectural drift"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Layer 2e: External Safety Checklist",
+            evaluationPoints: [
+                "SQL/database: parameterized queries, no raw string interpolation, migration safety",
+                "Concurrency: race conditions in shared state, lock ordering, timeout handling",
+                "Secrets: no hardcoded tokens, no secrets in logs, env vars for sensitive config",
+                "Enum/constant completeness: grep for sibling values OUTSIDE the diff — are all cases handled?",
+                "Trust boundaries: if LLM/AI output is used, is it validated before acting on it?"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Meta-Review: Verify the Verification",
+            evaluationPoints: [
+                "Were tests actually run (not just assumed to pass)?",
+                "Do the test names match what they actually test?",
+                "Is there test coverage for the specific changes in this diff?",
+                "Are there assertions, or do tests just run without checking results?"
+            ],
+            stopGate: false
+        }
+    ],
+    completionStatus: ["APPROVED", "APPROVED_WITH_CONCERNS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/05-plan.md"],
+        writesTo: [".cclaw/artifacts/07-review.md"],
+        traceabilityRule: "Review verdict must reference specific spec criteria and TDD evidence. Downstream ship stage must reference review verdict."
+    },
+    artifactValidation: [
+        { section: "Layer 1 Verdict", required: true, validationRule: "Per-criterion pass/fail with references." },
+        { section: "Layer 2 Findings", required: true, validationRule: "Each finding has severity, description, and resolution status." },
+        { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status with dedup reconciliation summary." },
+        { section: "Severity Summary", required: true, validationRule: "Counts: N critical, N important, N suggestion." },
+        { section: "Final Verdict", required: true, validationRule: "Exactly one of: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED." }
+    ],
+    namedAntiPattern: {
+        title: "Tests Pass So It Must Be Correct",
+        description: "Tests verify what the developer thought to test. They do not verify what the spec requires. A passing test suite with failing spec compliance is a false green. Layer 1 exists precisely because tests and specs can diverge without anyone noticing."
+    }
+};
+// ---------------------------------------------------------------------------
+// SHIP — reference: superpowers finishing-a-development-branch + gstack /ship
+// ---------------------------------------------------------------------------
+const SHIP = {
+    stage: "ship",
+    skillFolder: "shipping-and-handoff",
+    skillName: "shipping-and-handoff",
+    skillDescription: "Release handoff stage with preflight checks, rollback readiness, and explicit finalization mode.",
+    hardGate: "Do NOT merge, push, or finalize without a passed preflight check, written rollback plan, and exactly one explicit finalization mode selected. No exceptions for urgency.",
+    purpose: "Prepare a safe release handoff with clear rollback and branch finalization decision.",
+    whenToUse: [
+        "After review passes with APPROVED or APPROVED_WITH_CONCERNS verdict",
+        "Before creating PR/merge/final branch action",
+        "When release notes and rollback plan are required"
+    ],
+    checklist: [
+        "Validate upstream gates — verify review verdict is APPROVED or APPROVED_WITH_CONCERNS. If BLOCKED, stop immediately.",
+        "Run preflight checks — tests pass, build succeeds, linter clean, type-check clean, no uncommitted changes. Every check must produce fresh output in this message.",
+        "Merge-base detection — identify the correct base branch. Run `git merge-base HEAD <base>`. If the base has diverged significantly, flag for rebase-first.",
+        "Re-run tests on merged result — if merging locally, run the full test suite AFTER the merge, not just before. Post-merge failures are common.",
+        "Generate release notes — summarize what changed, why, and what it affects. Reference spec criteria. Include: breaking changes, new dependencies, migration steps if any.",
+        "Write rollback plan — trigger conditions (what tells you it is broken), rollback steps (exact commands/git operations), and verification (how to confirm rollback worked).",
+        "Monitoring checklist — what should be watched after deploy? Error rates, latency, key business metrics. If no monitoring exists, flag it as a risk.",
+        "Select finalization mode — exactly ONE of: (A) merge to main locally, (B) create PR with description, (C) keep branch for later, (D) discard branch. For discard: list what will be deleted, require typed confirmation.",
+        "Execute finalization — perform the selected action. For merge: verify clean merge. For PR: include structured body (summary, test plan, rollback). For discard: verify deletion.",
+        "Worktree cleanup — if using git worktrees, clean up the worktree after merge/discard. Keep it only for 'keep branch' mode."
+    ],
+    interactionProtocol: [
+        "Run preflight checks before any release action.",
+        "Document release notes and rollback plan explicitly.",
+        "For finalization mode: use the Decision Protocol — present modes as labeled options (A/B/C) with consequences, mark one as (recommended), use AskQuestion/AskUserQuestion tool when available.",
+        "Do not proceed if critical blockers remain from review.",
+        "Execute the selected finalization action and verify."
+    ],
+    process: [
+        "Validate review and test gates.",
+        "Run preflight: build, test, lint, uncommitted-changes check.",
+        "Generate release notes and rollback procedure.",
+        "Choose one finalization mode: merge, PR, keep branch, discard branch.",
+        "Execute finalization action.",
+        "Write ship artifact with decision, rationale, and execution result."
+    ],
+    requiredGates: [
+        { id: "ship_review_verdict_valid", description: "Review verdict is APPROVED or APPROVED_WITH_CONCERNS." },
+        { id: "ship_preflight_passed", description: "Preflight checks passed or exceptions documented and approved." },
+        { id: "ship_release_notes_written", description: "Release notes are complete and accurate." },
+        { id: "ship_rollback_plan_ready", description: "Rollback trigger, steps, and verification are documented." },
+        { id: "ship_finalization_mode_selected", description: "Exactly one finalization action is selected." },
+        { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/08-ship.md`.",
+        "Release notes section is complete.",
+        "Rollback section includes trigger conditions, steps, and verification.",
+        "Finalization mode shows exactly one selected.",
+        "Execution result documented."
+    ],
+    inputs: ["review verdict", "test/build outputs", "release context"],
+    requiredContext: ["review artifact", "changelog scope", "deployment constraints"],
+    outputs: ["release package handoff", "rollback plan", "final branch decision"],
+    blockers: [
+        "review verdict is BLOCKED",
+        "critical review blockers remain",
+        "rollback plan missing",
+        "finalization mode not selected"
+    ],
+    exitCriteria: [
+        "preflight completed",
+        "rollback and release notes complete",
+        "finalization action explicitly chosen and executed"
+    ],
+    antiPatterns: [
+        "Shipping without rollback strategy",
+        "Implicit finalization decision",
+        "Bypassing preflight due to urgency",
+        "Selecting multiple finalization modes",
+        "Shipping with BLOCKED review verdict"
+    ],
+    rationalizations: [
+        { claim: "Rollback details can be written after release.", reality: "Rollback is part of release readiness, not post-release cleanup." },
+        { claim: "Finalization choice is obvious from context.", reality: "Explicit branch action prevents accidental release state." },
+        { claim: "Urgent fixes can skip preflight.", reality: "Urgency increases risk; preflight discipline matters more, not less." }
+    ],
+    redFlags: [
+        "No rollback trigger/steps",
+        "More than one finalization mode implied",
+        "No explicit preflight result",
+        "Review verdict not referenced",
+        "Finalization not executed, only planned"
+    ],
+    policyNeedles: [
+        "Pre-Ship Checks",
+        "Release Notes",
+        "Rollback Plan",
+        "merge / PR / keep branch / discard branch"
+    ],
+    artifactFile: "08-ship.md",
+    next: "done",
+    cognitivePatterns: [
+        { name: "Preflight Discipline", description: "Preflight is not bureaucracy — it is the last safety net. Every skip 'just this once' normalizes skipping. Run the checks every time." },
+        { name: "Rollback-First Thinking", description: "Before shipping, answer: what tells me this is broken? How do I undo it? How do I verify the undo worked? If you cannot answer all three, you are not ready." },
+        { name: "Explicit Over Implicit Finalization", description: "Merge, PR, keep, discard — each has different consequences. Pick one. Say it out loud. Write it down. Never let finalization be 'whatever the default is.'" },
+        { name: "Post-Merge Paranoia", description: "The merge itself can introduce failures even when both branches pass independently. Always run the full suite AFTER merge, not just before." },
+        { name: "Observability Before Ship", description: "If you cannot monitor the change in production, you cannot know if it is broken. Monitoring/logging is a ship prerequisite, not a follow-up." }
+    ],
+    reviewSections: [
+        {
+            title: "Preflight Verification",
+            evaluationPoints: [
+                "Test suite: full run, all pass, output captured",
+                "Build: clean build, exit code 0",
+                "Lint/format: no violations",
+                "Type-check: no errors",
+                "Working tree: no uncommitted changes"
+            ],
+            stopGate: true
+        },
+        {
+            title: "Release Readiness",
+            evaluationPoints: [
+                "Release notes are accurate and reference spec criteria",
+                "Breaking changes are documented with migration steps",
+                "Rollback plan has trigger, steps, and verification",
+                "If applicable: monitoring/alerting is in place for the change"
+            ],
+            stopGate: true
+        }
+    ],
+    completionStatus: ["SHIPPED", "SHIPPED_WITH_EXCEPTIONS", "BLOCKED"],
+    crossStageTrace: {
+        readsFrom: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/06-tdd.md"],
+        writesTo: [".cclaw/artifacts/08-ship.md"],
+        traceabilityRule: "Ship artifact must reference review verdict and resolution status. Rollback plan must reference specific changes that could fail."
+    },
+    artifactValidation: [
+        { section: "Preflight Results", required: true, validationRule: "Build, test, lint, type-check results captured with fresh output. Exceptions documented if any." },
+        { section: "Release Notes", required: true, validationRule: "What changed, why, impact. References spec criteria. Breaking changes flagged." },
+        { section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
+        { section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
+        { section: "Finalization", required: true, validationRule: "Exactly one mode selected. Execution result documented. Worktree cleaned if applicable." }
+    ]
+};
+// ---------------------------------------------------------------------------
+// Stage map and accessors
+// ---------------------------------------------------------------------------
+const STAGE_SCHEMA_MAP = {
+    brainstorm: BRAINSTORM,
+    scope: SCOPE,
+    design: DESIGN,
+    spec: SPEC,
+    plan: PLAN,
+    test: TEST,
+    build: BUILD,
+    review: REVIEW,
+    ship: SHIP
+};
+const STAGE_AUTO_SUBAGENT_DISPATCH = {
+    brainstorm: [
+        {
+            agent: "planner",
+            mode: "proactive",
+            when: "When request is ambiguous, multi-surface, or spans multiple modules.",
+            purpose: "Map scope and alternatives before direction lock.",
+            requiresUserGate: false
+        }
+    ],
+    scope: [
+        {
+            agent: "planner",
+            mode: "mandatory",
+            when: "Always during scope shaping.",
+            purpose: "Challenge premise, map alternatives, and produce explicit in/out contract.",
+            requiresUserGate: false
+        }
+    ],
+    design: [
+        {
+            agent: "planner",
+            mode: "mandatory",
+            when: "Always during design lock.",
+            purpose: "Stress architecture boundaries and dependency graph.",
+            requiresUserGate: false
+        },
+        {
+            agent: "security-reviewer",
+            mode: "proactive",
+            when: "When trust boundaries, auth, secrets, or external inputs are involved.",
+            purpose: "Catch design-level security risks before implementation.",
+            requiresUserGate: false
+        }
+    ],
+    spec: [
+        {
+            agent: "planner",
+            mode: "proactive",
+            when: "When acceptance criteria are unclear or constraints conflict.",
+            purpose: "Normalize measurable criteria and testability mapping.",
+            requiresUserGate: false
+        }
+    ],
+    plan: [
+        {
+            agent: "planner",
+            mode: "mandatory",
+            when: "Always when producing execution slices.",
+            purpose: "Create dependency-aware task graph with verification steps.",
+            requiresUserGate: false
+        }
+    ],
+    test: [
+        {
+            agent: "test-author",
+            mode: "mandatory",
+            when: "Always during RED stage.",
+            purpose: "Guarantee failing tests are created before implementation.",
+            requiresUserGate: false
+        }
+    ],
+    build: [
+        {
+            agent: "test-author",
+            mode: "mandatory",
+            when: "Always during GREEN + REFACTOR.",
+            purpose: "Keep implementation traceable to RED evidence and full-suite verification.",
+            requiresUserGate: false
+        },
+        {
+            agent: "doc-updater",
+            mode: "proactive",
+            when: "When public behavior, APIs, or config surfaces change.",
+            purpose: "Prevent code/docs drift before review and ship.",
+            requiresUserGate: false
+        }
+    ],
+    review: [
+        {
+            agent: "spec-reviewer",
+            mode: "mandatory",
+            when: "Always in review stage.",
+            purpose: "Verify implementation against acceptance criteria with file evidence.",
+            requiresUserGate: false
+        },
+        {
+            agent: "code-reviewer",
+            mode: "mandatory",
+            when: "Always in review stage.",
+            purpose: "Assess correctness, maintainability, architecture, and ship risk.",
+            requiresUserGate: false
+        },
+        {
+            agent: "security-reviewer",
+            mode: "proactive",
+            when: "When auth, input validation, secrets, parser, or privileged actions changed.",
+            purpose: "Raise exploitable findings before release.",
+            requiresUserGate: false
+        }
+    ],
+    ship: [
+        {
+            agent: "doc-updater",
+            mode: "mandatory",
+            when: "Always in ship stage.",
+            purpose: "Ensure release notes and docs reflect actual shipped behavior.",
+            requiresUserGate: false
+        },
+        {
+            agent: "code-reviewer",
+            mode: "proactive",
+            when: "When release involves broad blast radius or unresolved concerns.",
+            purpose: "Provide final integration-scale quality pass.",
+            requiresUserGate: false
+        }
+    ]
+};
+export function stageSchema(stage) {
+    return STAGE_SCHEMA_MAP[stage];
+}
+export function orderedStageSchemas() {
+    return COMMAND_FILE_ORDER.map((stage) => stageSchema(stage));
+}
+export function stageGateIds(stage) {
+    return stageSchema(stage).requiredGates.map((gate) => gate.id);
+}
+export function nextCclawCommand(stage) {
+    const next = stageSchema(stage).next;
+    return next === "done" ? "none" : `/cc-${next}`;
+}
+export function buildTransitionRules() {
+    const rules = [];
+    for (const schema of orderedStageSchemas()) {
+        if (schema.next === "done") {
+            continue;
+        }
+        rules.push({
+            from: schema.stage,
+            to: schema.next,
+            guards: stageGateIds(schema.stage)
+        });
+    }
+    return rules;
+}
+export function stagePolicyNeedles(stage) {
+    return stageSchema(stage).policyNeedles;
+}
+export function stageAutoSubagentDispatch(stage) {
+    return STAGE_AUTO_SUBAGENT_DISPATCH[stage];
+}