cclaw-cli 0.15.0 → 0.15.1

package/dist/content/stages/review.js

@@ -0,0 +1,197 @@
+// ---------------------------------------------------------------------------
+// REVIEW — reference: superpowers code-review + gstack /review
+// ---------------------------------------------------------------------------
+export 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.",
+    ironLaw: "NO SHIP VERDICT UNTIL BOTH REVIEW LAYERS COMPLETE AND EVERY CRITICAL IS RESOLVED OR EXPLICITLY ACCEPTED.",
+    purpose: "Validate that implementation matches spec and meets quality/security/performance bar through structured two-layer review.",
+    whenToUse: [
+        "After TDD stage completes",
+        "Before any ship action",
+        "When release risk must be assessed explicitly"
+    ],
+    whenNotToUse: [
+        "There is no implementation diff to review",
+        "TDD stage evidence is missing or stale",
+        "The goal is direct release execution without layered quality checks"
+    ],
+    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.",
+        "Adversarial Trigger Check — compute changed-line count (`git diff --shortstat <base>..HEAD`), files-touched count, and whether trust boundaries changed (auth/secrets/external inputs/permissions). If `lines > 100` OR `files > 10` OR `trust boundary changed`, **dispatch a SECOND reviewer agent with the `adversarial-review` skill loaded** and reconcile its findings into the review army (treat the conditional dispatch as mandatory whenever the trigger holds; record the trigger that fired in the dashboard).",
+        "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. **Mandatory:** also load and execute the `.cclaw/skills/security-audit/SKILL.md` utility skill (proactive pattern sweep across diff + touched modules, not just the diff itself) and merge findings into the review army. The Layer 2 security pass is not complete until the audit sweep records a finding count (0 acceptable) with file:line evidence for every Critical.",
+        "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, and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that fully closes the finding with no carry-over risk and the smallest blast radius. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "Resolve all critical blockers before ship.",
+        "For final verdict: use AskQuestion/AskUserQuestion only if runtime schema is confirmed; otherwise collect verdict with a plain-text single-choice prompt (APPROVED / APPROVED_WITH_CONCERNS / BLOCKED).",
+        "**STOP.** Do NOT proceed to ship until the user provides an explicit verdict."
+    ],
+    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." },
+        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." },
+        { id: "review_completeness_scored", description: "Completeness score is computed and recorded (AC coverage, task coverage, slice coverage, adversarial pass)." },
+        { id: "review_security_audit_swept", description: "The security-audit utility skill was run against the diff scope and the modules it touches. Finding count (0 if clean) recorded in the review army with file:line evidence for every Critical." }
+    ],
+    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"
+    ],
+    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",
+    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", ".cclaw/artifacts/07-review-army.json"],
+        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: "Review Readiness Dashboard", required: true, validationRule: "Includes a per-pass table (Layer 1 / Layer 2 / Adversarial / Schema) with a 'Completed at' column, a Delegation log snapshot block (path .cclaw/state/delegation-log.json with required/completed/waived/pending), a Staleness signal block (commit at last review pass and current commit), and a Headline with open critical blockers + ship recommendation. At minimum, the section text must contain the substrings 'Completed at', 'delegation-log.json', 'commit at last review pass', and 'Ship recommendation'." },
+        { section: "Completeness Score", required: true, validationRule: "Records AC coverage, task coverage, test-slice coverage, and adversarial-review pass status as numeric or boolean values. At minimum, a line like 'AC coverage: N/M' or 'AC coverage: 100%'." },
+        { section: "Severity Summary", required: true, validationRule: "Per-severity count lines for critical, important, and suggestion buckets." },
+        { section: "Final Verdict", required: true, validationRule: "Exactly one of: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED." }
+    ]
+};

package/dist/content/stages/schema-types.d.ts

@@ -0,0 +1,94 @@
+import type { FlowStage } from "../../types.js";
+export interface StageGate {
+    id: string;
+    description: string;
+    tier?: "required" | "recommended" | "conditional";
+    /** Used when tier=conditional. Predicate syntax mirrors conditional delegation rules. */
+    condition?: string;
+}
+export interface ReviewSection {
+    title: string;
+    evaluationPoints: string[];
+    stopGate: boolean;
+}
+export interface CrossStageTrace {
+    readsFrom: string[];
+    writesTo: string[];
+    traceabilityRule: string;
+}
+export interface ArtifactValidation {
+    section: string;
+    required: boolean;
+    tier?: "required" | "recommended" | "conditional";
+    /** Optional predicate for conditional validations. */
+    condition?: string;
+    validationRule: string;
+}
+export interface StageAutoSubagentDispatch {
+    agent: "planner" | "reviewer" | "security-reviewer" | "test-author" | "doc-updater";
+    /**
+     * - `mandatory` — must be dispatched (or explicitly waived) before stage transition.
+     * - `proactive` — should be dispatched automatically when context matches `when`.
+     * - `conditional` — dispatched only when `condition` evaluates true at runtime; counted as
+     *   mandatory **only when the condition holds**.
+     */
+    mode: "mandatory" | "proactive" | "conditional";
+    when: string;
+    purpose: string;
+    requiresUserGate: boolean;
+    /**
+     * Optional machine-friendly trigger expression for `conditional` rows.
+     * Supported predicates: `diff_lines_gt:<N>`, `files_touched_gt:<N>`,
+     * `trust_boundary_changed`, `release_blast_radius_high`.
+     * Multiple predicates joined by `||` mean ANY trigger satisfies the condition.
+     */
+    condition?: string;
+    /** Optional skill folder the dispatched agent should load as additional context. */
+    skill?: string;
+}
+export interface StageSchema {
+    stage: FlowStage;
+    skillFolder: string;
+    skillName: string;
+    skillDescription: string;
+    hardGate: string;
+    /**
+     * One-line "Iron Law" punchcard — the single rule that, if broken,
+     * invalidates the stage outright. Rendered in ALL-CAPS wrapped in
+     * <EXTREMELY-IMPORTANT> XML markers at the very top of the skill body.
+     * Reference: Superpowers (obra) "NO PRODUCTION CODE WITHOUT A FAILING
+     * TEST FIRST".
+     */
+    ironLaw: string;
+    purpose: string;
+    whenToUse: string[];
+    whenNotToUse: string[];
+    interactionProtocol: string[];
+    process: string[];
+    requiredGates: StageGate[];
+    requiredEvidence: string[];
+    inputs: string[];
+    requiredContext: string[];
+    /** In-thread research procedures for this stage (`.cclaw/skills/research/*.md`). */
+    researchPlaybooks?: string[];
+    outputs: string[];
+    blockers: string[];
+    exitCriteria: string[];
+    antiPatterns: string[];
+    redFlags: string[];
+    policyNeedles: string[];
+    artifactFile: string;
+    next: FlowStage | "done";
+    checklist: string[];
+    reviewSections: ReviewSection[];
+    completionStatus: string[];
+    crossStageTrace: CrossStageTrace;
+    artifactValidation: ArtifactValidation[];
+    /** When true, stage skill includes wave auto-execute guidance (tdd). */
+    waveExecutionAllowed?: boolean;
+    /** Sections that remain required even when the trivial-change escape hatch is active (design only). */
+    trivialOverrideSections?: string[];
+    /** Agent names that MUST be dispatched (or waived) before stage transition — derived from mandatory auto-subagent rows. */
+    mandatoryDelegations: string[];
+}
+export type StageSchemaInput = Omit<StageSchema, "mandatoryDelegations">;

package/dist/content/stages/schema-types.js

@@ -0,0 +1 @@
+export {};

package/dist/content/stages/scope.d.ts

@@ -0,0 +1,2 @@
+import type { StageSchemaInput } from "./schema-types.js";
+export declare const SCOPE: StageSchemaInput;

package/dist/content/stages/scope.js

@@ -0,0 +1,188 @@
+// ---------------------------------------------------------------------------
+// SCOPE — reference: gstack CEO review
+// ---------------------------------------------------------------------------
+export 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.",
+    ironLaw: "EVERY SCOPE CHANGE IS AN EXPLICIT USER OPT-IN — NEVER A SILENT ENLARGEMENT OR TRIM.",
+    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"
+    ],
+    whenNotToUse: [
+        "Brainstorm has not been approved yet",
+        "Scope boundaries are already locked and user requested no scope changes",
+        "The work is a pure implementation or debugging pass within existing scope"
+    ],
+    checklist: [
+        "**Assess complexity** — Read the brainstorm artifact. If project is simple (single component, clear architecture, personal/prototype), run light-touch scope: mode selection, 3-5 key in/out boundaries, deferred items. Skip Dream State Mapping and Temporal Interrogation. If project is complex (multi-component, team delivery, production), run the full checklist.",
+        "**Prime Directives** — Zero silent failures. For each in-scope capability, name concrete failure modes, the exact error surface, and trace all four data-flow paths (happy, nil, empty, upstream error). Include interaction edge cases (double-click, navigate-away, stale state), observability commitments, and explicit deferred-item logging.",
+        "**Premise Challenge** — Is this the right problem? What if we do nothing? What are we optimizing for?",
+        "**Existing Code Leverage** — Search for existing solutions before deciding to build new.",
+        "**Dream State Mapping** — (complex projects only) describe the ideal state 12 months out using `CURRENT STATE -> THIS PLAN -> 12-MONTH IDEAL`, then verify this scope moves toward that target.",
+        "**Implementation Alternatives** — Produce 2-3 distinct approaches. For each: Name, Summary, Effort (S/M/L/XL), Risk (Low/Med/High), 2-3 Pros, 2-3 Cons, and explicit Reuses. One option must be minimal viable, one must be ideal architecture.",
+        "**Temporal Interrogation** — (complex projects only) simulate implementation timeline: HOUR 1 foundations, HOUR 2-3 core logic, HOUR 4-5 integration surprises, HOUR 6+ polish/tests. Decide what must be locked now vs safely deferred.",
+        "**Mode Selection** — Present expand/selective/hold/reduce with recommendation and default heuristic: greenfield -> expand, feature enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius (>15 files or multi-team impact) -> reduce.",
+        "**Mode-Specific Analysis** — After mode is selected, run the matching analysis: EXPAND (10x and delight opportunities), SELECTIVE (hold-scope rigor then cherry-picked expansions), HOLD (minimum-change-set hardening), REDUCE (ruthless cuts and follow-up split).",
+        "**Error and Rescue Registry** — For each capability: what breaks, how detected, what fallback."
+    ],
+    interactionProtocol: [
+        "For scope mode selection: use the Decision Protocol — present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that best covers the prime-directive failure modes, four data-flow paths, observability, and deferred handling for the in-scope set with the smallest blast radius. Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "Walk through the scope checklist interactively. Each checklist item that surfaces a decision should be presented to the user as a question, not as a monologue. Do not dump all items at once.",
+        "Challenge premise and verify the problem framing before anything else.",
+        "Take a position on every scope decision. Avoid hedging phrases like 'this could work' or 'there are many ways'; state your recommendation and one concrete condition that would change it.",
+        "Use pushback patterns when framing is weak: vague scope -> force a specific user/problem, platform vision -> force a narrowest viable wedge, social proof -> demand behavioral evidence.",
+        "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.",
+        "**STOP.** Wait for explicit user approval of scope contract before advancing to design."
+    ],
+    process: [
+        "Run premise challenge and existing-solution leverage check.",
+        "Produce 2-3 scope alternatives in a structured format (Name, Summary, Effort, Risk, Pros, Cons, Reuses) with minimum viable and ideal architecture options included.",
+        "Choose scope mode with user approval.",
+        "Run mode-specific analysis that matches the selected scope mode.",
+        "Walk through scope review sections one at a time.",
+        "Write explicit scope contract, discretion areas, and deferred items.",
+        "Produce scope summary plus completion dashboard (checklist findings, number of resolved decisions, unresolved items or `None`)."
+    ],
+    requiredGates: [
+        { id: "scope_premise_challenged", description: "Problem framing and assumptions were challenged." },
+        { id: "scope_alternatives_produced", description: "At least 2 implementation alternatives were evaluated with explicit effort/risk and reuse fields." },
+        { 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_discretion_documented", description: "Discretion areas are documented (or explicitly marked as none)." },
+        { 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.",
+        "Discretion areas are explicit (or marked as `None`).",
+        "Selected mode and rationale are documented.",
+        "Premise challenge findings documented.",
+        "Deferred items list with one-line rationale for each.",
+        "Completion dashboard lists checklist findings, decision count, and unresolved items (or `None`)."
+    ],
+    inputs: ["brainstorm artifact", "timeline constraints", "product priorities"],
+    requiredContext: [
+        "approved brainstorm direction",
+        "existing capabilities and reusable components",
+        "delivery deadlines and risk tolerance"
+    ],
+    researchPlaybooks: [
+        "research/git-history.md"
+    ],
+    outputs: ["scope mode decision", "scope contract", "discretion areas list", "deferred scope list", "scope summary", "scope completion dashboard"],
+    blockers: [
+        "scope mode not selected",
+        "in/out boundaries ambiguous",
+        "discretion areas undefined",
+        "critical premise disagreement unresolved"
+    ],
+    exitCriteria: [
+        "scope contract approved by user",
+        "discretion areas recorded explicitly",
+        "required gates marked satisfied",
+        "deferred list recorded explicitly",
+        "completion dashboard produced",
+        "scope summary produced"
+    ],
+    antiPatterns: [
+        "Scope silently expanded during discussion",
+        "No explicit out-of-scope section",
+        "Premise accepted without challenge",
+        "Sycophantic agreement without evidence-based pushback",
+        "Hedged recommendations that avoid taking a position",
+        "Batching multiple scope issues into one question",
+        "Re-arguing for smaller scope after user rejects reduction"
+    ],
+    redFlags: [
+        "No selected mode in artifact",
+        "Mode selected without heuristic justification",
+        "No discretion section (or explicit `None`) 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", "Discretion Areas", "NOT in scope", "Premise Challenge"],
+    artifactFile: "02-scope.md",
+    next: "design",
+    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: "For each scoped capability: named failure modes, explicit error surface, four data-flow paths, interaction edge cases, observability expectations, and deferred-item handling." },
+        { section: "Premise Challenge", required: true, validationRule: "Must contain explicit answers to: right problem? direct path? what if nothing?" },
+        { section: "Requirements", required: true, validationRule: "Table of stable requirement IDs (R1, R2, R3…) one per row with observable outcome, priority, and source. IDs are assigned once and never renumbered across scope/design/spec/plan/review; dropped requirements stay with Priority `DROPPED`." },
+        { section: "Implementation Alternatives", required: true, validationRule: "2-3 options with Name, Summary, Effort, Risk, Pros, Cons, and Reuses. Must include minimal viable and ideal architecture options." },
+        { section: "Scope Mode", required: true, validationRule: "Must state selected mode and rationale with default heuristic justification." },
+        { section: "Mode-Specific Analysis", required: true, validationRule: "Must document the analysis matching the selected scope mode: EXPAND (10x and delight opportunities), SELECTIVE (hold-scope baseline then cherry-picked expansions), HOLD (minimum-change-set hardening), REDUCE (ruthless cuts and follow-up split)." },
+        { section: "In Scope / Out of Scope", required: true, validationRule: "Two separate explicit lists. Out-of-scope must not be empty." },
+        { section: "Discretion Areas", required: true, validationRule: "Explicit list of implementer decision zones, or 'None' if scope is fully locked." },
+        { 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: "Completion Dashboard", required: true, validationRule: "Lists checklist findings, count of resolved decisions, and unresolved decisions (or 'None')." },
+        { section: "Scope Summary", required: true, validationRule: "Clean summary: mode, strongest challenges, recommended path, accepted scope, deferred, excluded." },
+        { section: "Dream State Mapping", required: false, validationRule: "If present (complex projects): CURRENT STATE, THIS PLAN, 12-MONTH IDEAL, and alignment verdict." },
+        { section: "Temporal Interrogation", required: false, validationRule: "If present (complex projects): timeline simulation table with decision pressures and lock-now vs defer verdicts." }
+    ]
+};

package/dist/content/stages/ship.d.ts

@@ -0,0 +1,2 @@
+import type { StageSchemaInput } from "./schema-types.js";
+export declare const SHIP: StageSchemaInput;

package/dist/content/stages/ship.js

@@ -0,0 +1,142 @@
+// ---------------------------------------------------------------------------
+// SHIP — reference: superpowers finishing-a-development-branch + gstack /ship
+// ---------------------------------------------------------------------------
+export 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.",
+    ironLaw: "NO MERGE WITHOUT GREEN CI, A WRITTEN ROLLBACK, AND EXACTLY ONE SELECTED FINALIZATION MODE.",
+    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"
+    ],
+    whenNotToUse: [
+        "Review verdict is BLOCKED or unresolved critical findings remain",
+        "Preflight checks cannot run and no approved exception exists",
+        "The request is still design/spec/implementation work, not release handoff"
+    ],
+    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 enum: (A) FINALIZE_MERGE_LOCAL, (B) FINALIZE_OPEN_PR, (C) FINALIZE_KEEP_BRANCH, (D) FINALIZE_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/D) with consequences, and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the mode that best addresses release blast-radius, rollback readiness, observability, and stakeholder communication — ties go to the most reversible option. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "Do not proceed if critical blockers remain from review.",
+        "**STOP.** Present finalization options and wait for user selection before executing any finalization action."
+    ],
+    process: [
+        "Validate review and test gates.",
+        "Run preflight: build, test, lint, uncommitted-changes check.",
+        "Generate release notes and rollback procedure.",
+        "Choose one finalization enum: FINALIZE_MERGE_LOCAL, FINALIZE_OPEN_PR, FINALIZE_KEEP_BRANCH, or FINALIZE_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." },
+        { id: "ship_post_merge_tests", description: "Full test suite re-run on the merged result (not just the branch). Post-merge failures caught before release." }
+    ],
+    requiredEvidence: [
+        "Artifact written to `.cclaw/artifacts/08-ship.md`.",
+        "Release notes section is complete.",
+        "Rollback section includes trigger conditions, steps, and verification.",
+        "Finalization section shows exactly one selected enum token.",
+        "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"
+    ],
+    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",
+        "FINALIZE_MERGE_LOCAL",
+        "FINALIZE_OPEN_PR",
+        "FINALIZE_KEEP_BRANCH",
+        "FINALIZE_DISCARD_BRANCH"
+    ],
+    artifactFile: "08-ship.md",
+    next: "done",
+    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", ".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
+        writesTo: [".cclaw/artifacts/08-ship.md"],
+        traceabilityRule: "Ship artifact must reference review verdict and resolution status. Release notes must reference spec criteria. 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 finalization enum token selected. Execution result documented. Worktree cleaned if applicable." },
+        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." },
+        { section: "Compound Step", required: false, validationRule: "Optional retrospective: at least one bullet of the form 'Insight: ... | Action: append [compound] entry to .cclaw/knowledge.jsonl', or an explicit 'No compound insight this run.' line." }
+    ]
+};

package/dist/content/stages/spec.d.ts

@@ -0,0 +1,2 @@
+import type { StageSchemaInput } from "./schema-types.js";
+export declare const SPEC: StageSchemaInput;