cclaw-cli 0.51.23 → 0.51.25

package/dist/content/core-agents.js

@@ -6,6 +6,38 @@ function yamlScalarString(value) {
 function yamlFlowSequence(values) {
     return JSON.stringify(values);
 }
+const WORKER_RETURN_SCHEMA = {
+    statusField: "status",
+    allowedStatuses: ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
+    requiredFields: ["status", "filesChanged", "testsRun", "evidenceRefs", "concerns", "needsContext", "blockers"],
+    evidenceFields: ["testsRun", "evidenceRefs"]
+};
+const REVIEW_RETURN_SCHEMA = {
+    statusField: "status",
+    allowedStatuses: ["PASS", "PASS_WITH_GAPS", "FAIL", "BLOCKED"],
+    requiredFields: ["status", "findings", "criteria", "evidenceRefs", "blockers"],
+    evidenceFields: ["findings.location", "criteria.evidence", "evidenceRefs"]
+};
+const ADVISORY_RETURN_SCHEMA = {
+    statusField: "status",
+    allowedStatuses: ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
+    requiredFields: ["status", "summary", "recommendations", "evidenceRefs", "unknowns"],
+    evidenceFields: ["evidenceRefs", "recommendations"]
+};
+const DOC_RETURN_SCHEMA = {
+    statusField: "status",
+    allowedStatuses: ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
+    requiredFields: ["status", "filesUpdated", "summary", "evidenceRefs", "openQuestions"],
+    evidenceFields: ["filesUpdated", "evidenceRefs"]
+};
+function formatReturnSchema(schema) {
+    return [
+        `- Status field: \`${schema.statusField}\``,
+        `- Allowed statuses: ${schema.allowedStatuses.map((status) => `\`${status}\``).join(", ")}`,
+        `- Required fields: ${schema.requiredFields.map((field) => `\`${field}\``).join(", ")}`,
+        `- Evidence fields: ${schema.evidenceFields.map((field) => `\`${field}\``).join(", ")}`
+    ].join("\n");
+}
 function formattedAgentsForStages(stages) {
     const summary = stageDelegationSummary("standard");
     const merged = [];
@@ -39,7 +71,7 @@ function activationModeSummary() {
     };
 }
 /**
- * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ * Canonical specialist roster materialized under `.cclaw/agents/`.
  *
  * Declared with `satisfies` so the array retains literal `name` types for
  * downstream type-level consumers (e.g. `AgentName`), while still being
@@ -48,6 +80,26 @@ function activationModeSummary() {
  * to `string` and break the compile-time drift guard.
  */
 export const CCLAW_AGENTS = [
+    {
+        name: "researcher",
+        description: "PROACTIVE when context readiness, repo search, reference patterns, or external docs could change a stage decision. MUST summarize search-before-read evidence before large reads.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "fast",
+        activation: "proactive",
+        relatedStages: ["brainstorm", "scope", "design", "plan"],
+        returnSchema: ADVISORY_RETURN_SCHEMA,
+        body: [
+            "You are a **context readiness and research specialist**.",
+            "",
+            "When invoked:",
+            "1. Start with search/query summaries before reading large files.",
+            "2. Name provider status when known: graph/search/docs/MCP/semantic index freshness.",
+            "3. Separate observed facts from assumptions and stale or missing context.",
+            "4. Return concise evidence refs the controller can paste into stage artifacts.",
+            "",
+            "**Role boundary:** research and context synthesis only. Do NOT edit files."
+        ].join("\n")
+    },
     {
         name: "planner",
         description: "MANDATORY for scope/design/plan and PROACTIVE for high-ambiguity work. MUST BE USED when sequencing, dependency mapping, or risk trade-offs are required before coding.",
@@ -55,18 +107,97 @@ export const CCLAW_AGENTS = [
         model: "deep",
         activation: "mandatory",
         relatedStages: ["brainstorm", "scope", "design", "spec", "plan"],
+        returnSchema: ADVISORY_RETURN_SCHEMA,
         body: [
             "You are an **implementation planning specialist** (staff engineer mindset).",
             "",
             "When invoked:",
-            "1. Analyze scope and break it into concrete sub-problems.",
-            "2. Map each sub-problem to existing modules and reusable code.",
-            "3. Produce an ordered execution plan with dependencies and checks.",
-            "4. Highlight risks and unknowns that need user decisions.",
+            "1. Map upstream decisions, scope boundaries, and explicit drift before planning.",
+            "2. Break the work into concrete sub-problems with dependencies and existing-module fit.",
+            "3. Enforce one-question discipline: ask only decision-changing questions, one at a time.",
+            "4. Produce an ordered execution plan with verification checks and handoff quality notes.",
+            "5. Highlight risks and unknowns that need user decisions.",
             "",
             "**Role boundary:** planning only. Do NOT write production code."
         ].join("\n")
     },
+    {
+        name: "product-manager",
+        description: "PROACTIVE during brainstorm/scope when product value, persona/JTBD, success metric, or why-now framing is unclear. Use for product discovery, not implementation.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["brainstorm", "scope"],
+        returnSchema: ADVISORY_RETURN_SCHEMA,
+        body: [
+            "You are a **product discovery specialist**.",
+            "",
+            "Produce concise evidence for:",
+            "- persona / user and job to be done",
+            "- pain or trigger",
+            "- value hypothesis and success metric",
+            "- evidence or signal strength",
+            "- why now, do-nothing consequence, and non-goals",
+            "",
+            "For technical-maintenance work, translate this to operator/developer, failure mode, operational improvement, verification signal, do-nothing cost, and non-goals.",
+            "",
+            "**Role boundary:** frame value and problem fit. Do NOT choose implementation architecture."
+        ].join("\n")
+    },
+    {
+        name: "critic",
+        description: "PROACTIVE during brainstorm/scope/design when premises, alternatives, cost, rollback, or hidden assumptions need adversarial pressure.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["brainstorm", "scope", "design"],
+        returnSchema: ADVISORY_RETURN_SCHEMA,
+        body: [
+            "You are an **adversarial critic** for product and engineering decisions.",
+            "",
+            "Your job:",
+            "1. Attack the premise and name what could make the current direction wrong.",
+            "2. Identify cheaper, smaller, or more reversible alternatives.",
+            "3. Surface hidden assumptions, do-nothing viability, and scope creep.",
+            "4. In design, require a shadow alternative, switch trigger, failure/rescue path, and verification evidence.",
+            "",
+            "Return confirmed risks, disproven concerns, and the smallest decision-changing recommendation."
+        ].join("\n")
+    },
+    {
+        name: "architect",
+        description: "MANDATORY during design. MUST BE USED to validate architecture boundaries, alternatives, failure modes, rollout, and spec handoff before implementation.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "deep",
+        activation: "mandatory",
+        relatedStages: ["design"],
+        returnSchema: ADVISORY_RETURN_SCHEMA,
+        body: [
+            "You are an **architecture validation specialist**.",
+            "",
+            "Check architecture boundaries, existing-system fit, critical paths, data/state flow, alternatives, rescue paths, and verification hooks.",
+            "Return chosen path risks, rejected alternatives, switch triggers, and required evidence before spec handoff.",
+            "",
+            "**Role boundary:** design validation only. Do NOT write implementation code."
+        ].join("\n")
+    },
+    {
+        name: "spec-validator",
+        description: "MANDATORY during standard/deep spec. MUST BE USED to validate measurable acceptance criteria, assumptions, edge cases, and testability mapping.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["spec"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
+        body: [
+            "You are a **specification validation specialist**.",
+            "",
+            "For every acceptance criterion, verify it is observable, measurable, falsifiable, mapped to upstream decisions, and paired with concrete verification evidence.",
+            "Flag vague language, missing edge cases, hidden assumptions, and RED tests that cannot be expressed.",
+            "",
+            "**Role boundary:** validate the spec; do NOT write plan tasks or implementation."
+        ].join("\n")
+    },
     {
         name: "reviewer",
         description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.",
@@ -74,6 +205,7 @@ export const CCLAW_AGENTS = [
         model: "balanced",
         activation: "mandatory",
         relatedStages: ["spec", "review", "ship"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
         body: [
             "You are a **combined spec + code reviewer**.",
             "",
@@ -91,12 +223,59 @@ export const CCLAW_AGENTS = [
             "",
             "For each finding include:",
             "- Severity: `Critical` | `Important` | `Suggestion`",
-            "- Location: `file:line`",
+            "- Location: `file:line`; if no line is possible, state the no-line reason",
             "- Problem and concrete recommendation",
             "",
+            "Also report files inspected, changed-file coverage, diagnostics run, dependency/version audit when relevant, and a no-finding attestation when no issues are found.",
+            "",
             "**Trust model:** never rely on implementer claims; verify by reading code."
         ].join("\n")
     },
+    {
+        name: "performance-reviewer",
+        description: "PROACTIVE during review for hot paths, IO, data volume, caching, rendering, or algorithmic cost changes. Produces no-impact rationale when clean.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["review"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
+        body: [
+            "You are a **performance review specialist**.",
+            "",
+            "Check hot paths, algorithmic complexity, IO/network calls, caching behavior, bundle/runtime costs, and accidental N+1 or repeated work.",
+            "Every finding needs a concrete code citation and a measurement or measurement plan."
+        ].join("\n")
+    },
+    {
+        name: "compatibility-reviewer",
+        description: "PROACTIVE during design/review when public APIs, config, persisted data, CLI behavior, generated clients, or dependency versions may change.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["design", "review"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
+        body: [
+            "You are a **compatibility review specialist**.",
+            "",
+            "Check API compatibility, config/schema stability, persisted data migrations, CLI/user-facing behavior, generated clients, and rollout fallback paths.",
+            "Distinguish shipped compatibility obligations from in-branch implementation churn."
+        ].join("\n")
+    },
+    {
+        name: "observability-reviewer",
+        description: "PROACTIVE during design/review when diagnosis, telemetry, rollout visibility, or supportability could affect safe operation.",
+        tools: ["Read", "Grep", "Glob"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["design", "review"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
+        body: [
+            "You are an **observability review specialist**.",
+            "",
+            "Check logs, metrics, traces, alerts, debug handles, failure detection, and support handoff evidence for the changed paths.",
+            "Report missing visibility as a ship risk only when it affects diagnosis or rollback."
+        ].join("\n")
+    },
     {
         name: "security-reviewer",
         description: "MANDATORY during review; PROACTIVE during design/ship for trust-boundary changes. Always produce an explicit no-change attestation when no security-relevant surface moved.",
@@ -104,6 +283,7 @@ export const CCLAW_AGENTS = [
         model: "balanced",
         activation: "mandatory",
         relatedStages: ["design", "review", "ship"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
         body: [
             "You are a **security vulnerability specialist** focused on exploitability.",
             "",
@@ -118,7 +298,8 @@ export const CCLAW_AGENTS = [
             "- severity aligned to ship risk",
             "- CWE ID when possible (or UNKNOWN)",
             "- short proof-of-concept vector",
-            "- concrete control-oriented fix"
+            "- concrete control-oriented fix",
+            "- `NO_CHANGE_ATTESTATION` or `NO_SECURITY_IMPACT` with inspected surfaces when no security finding exists"
         ].join("\n")
     },
     {
@@ -128,10 +309,11 @@ export const CCLAW_AGENTS = [
         model: "balanced",
         activation: "mandatory",
         relatedStages: ["tdd"],
+        returnSchema: WORKER_RETURN_SCHEMA,
         body: [
             "You are a **test-driven development** specialist.",
             "",
-            "**Iron law:** no production code without a failing test first.",
+            "**Iron law:** no production code without a failing test first during RED. In design, focus on testability and verification evidence without editing production code.",
             "",
             "Process:",
             "1. RED: write a failing test for the desired behavior.",
@@ -141,6 +323,21 @@ export const CCLAW_AGENTS = [
             "5. REFACTOR with behavior preserved."
         ].join("\n")
     },
+    {
+        name: "release-reviewer",
+        description: "MANDATORY during ship. MUST BE USED for release readiness, rollback, finalization mode, evidence freshness, and victory detector checks.",
+        tools: ["Read", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "mandatory",
+        relatedStages: ["ship"],
+        returnSchema: REVIEW_RETURN_SCHEMA,
+        body: [
+            "You are a **release readiness reviewer**.",
+            "",
+            "Verify preflight evidence, review verdict freshness, rollback trigger and steps, finalization enum, no-VCS handoff when applicable, learnings capture, and handoff completeness.",
+            "Block ship on stale evidence, unresolved criticals, missing rollback, or ambiguous finalization."
+        ].join("\n")
+    },
     {
         name: "doc-updater",
         description: "MANDATORY only at ship; PROACTIVE during tdd/review whenever behavior, config, or public API changes. Keep docs and runbooks in lockstep with shipped behavior.",
@@ -148,16 +345,78 @@ export const CCLAW_AGENTS = [
         model: "fast",
         activation: "mandatory",
         relatedStages: ["tdd", "ship"],
+        returnSchema: DOC_RETURN_SCHEMA,
         body: [
             "You are a **documentation maintenance specialist**.",
             "",
             "After code changes, verify and update only stale sections in:",
             "- README / setup / usage",
             "- API docs and examples",
-            "- migration and operational notes",
+            "- migration, rollout, rollback, and operational notes",
+            "- public-surface change notes tied to actual changed files",
             "",
             "Preserve existing tone and structure; avoid rewrites for style alone."
         ].join("\n")
+    },
+    {
+        name: "slice-implementer",
+        description: "ON-DEMAND or PROACTIVE during TDD GREEN/REFACTOR for one bounded vertical slice after RED evidence exists and file ownership is non-overlapping.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "on-demand",
+        relatedStages: ["tdd"],
+        returnSchema: WORKER_RETURN_SCHEMA,
+        body: [
+            "You are a **vertical-slice implementation worker**.",
+            "",
+            "Rules:",
+            "1. Start only from the assigned RED failure and acceptance mapping.",
+            "2. Edit only the allowed files for the slice.",
+            "3. Implement the minimal GREEN change, then preserve behavior during REFACTOR.",
+            "4. Return files changed, tests run, evidence refs, concerns, and blockers.",
+            "",
+            "**Role boundary:** do not broaden scope, do not review your own work as final approval, and do not spawn subagents."
+        ].join("\n")
+    },
+    {
+        name: "implementer",
+        description: "ON-DEMAND worker for one scoped implementation slice. Use only with self-contained task text, explicit file boundaries, and verification expectations.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "on-demand",
+        relatedStages: ["tdd"],
+        returnSchema: WORKER_RETURN_SCHEMA,
+        body: [
+            "You are an **implementation worker** for one bounded cclaw task.",
+            "",
+            "Rules:",
+            "1. Treat the parent prompt as the full task boundary; do not infer hidden scope from plan files.",
+            "2. Make the smallest coherent code change that satisfies the pasted acceptance criteria.",
+            "3. Run the requested verification commands when feasible and report representative evidence.",
+            "4. Return the strict worker JSON schema before prose.",
+            "",
+            "**Role boundary:** do not review your own work as final approval and do not spawn subagents."
+        ].join("\n")
+    },
+    {
+        name: "fixer",
+        description: "ON-DEMAND fresh worker after review FAIL/PARTIAL evidence. Must fix only the cited criterion within explicit allowed files.",
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        model: "balanced",
+        activation: "on-demand",
+        relatedStages: ["review", "tdd"],
+        returnSchema: WORKER_RETURN_SCHEMA,
+        body: [
+            "You are a **fresh fixer worker** dispatched after a review found a concrete gap.",
+            "",
+            "Rules:",
+            "1. Start from the failing criterion and reviewer evidence, not from implementer claims.",
+            "2. Stay inside the allowed files and forbidden-change constraints.",
+            "3. Apply the smallest fix and rerun the relevant verification.",
+            "4. Return the strict fixer JSON schema before prose.",
+            "",
+            "**Role boundary:** fix only the cited gap; do not redesign the slice."
+        ].join("\n")
     }
 ];
 import { stageDelegationSummary } from "./stage-schema.js";
@@ -187,6 +446,12 @@ ${agent.body}
 - Mode: ${agent.activation}
 - Related stages: ${relatedStages}
 
+## Required Return Schema
+
+STRICT_RETURN_SCHEMA: return a structured object matching this contract before any narrative when delegated.
+
+${formatReturnSchema(agent.returnSchema)}
+
 ## Rules
 
 ## Conversation Language Policy
@@ -221,26 +486,39 @@ export function agentRoutingTable() {
 `;
 }
 /**
- * Cost tier routing for the core-5 agent roster.
+ * Cost tier routing for the specialist agent roster.
  */
 export function agentCostTierTable() {
     return `| Tier | Use for | Example agents |
 |---|---|---|
 | \`deep\` | one heavy planning pass per stage | planner |
-| \`balanced\` | review and TDD specialists with stronger reasoning depth | reviewer, security-reviewer, test-author |
+| \`balanced\` | discovery, criticism, review, TDD, and bounded worker execution | product-manager, critic, reviewer, security-reviewer, test-author, implementer, fixer |
 | \`fast\` | bounded maintenance updates with limited blast radius | doc-updater |
 `;
 }
+export function agentRegistryMatrix() {
+    const rows = CCLAW_AGENTS.map((agent) => {
+        const stages = agent.relatedStages.length > 0 ? agent.relatedStages.join(", ") : "none";
+        return `| ${agent.name} | ${agent.activation} | ${agent.model} | ${stages} | ${agent.returnSchema.allowedStatuses.join(" / ")} |`;
+    }).join("\n");
+    return `| Agent | Activation | Model | Related stages | Terminal statuses |
+|---|---|---|---|---|
+${rows}`;
+}
 /**
  * AGENTS.md-ready section describing cclaw’s specialist delegation model.
  */
 export function agentsAgentsMdBlock() {
     return `### Agent Specialists
 
-cclaw materializes **5 core specialist agents** under \`.cclaw/agents/\`.
+cclaw materializes specialist agents under \`.cclaw/agents/\`: ${CCLAW_AGENTS.map((agent) => agent.name).join(", ")}.
 
 ${agentRoutingTable()}
 
+### Agent Registry Matrix
+
+${agentRegistryMatrix()}
+
 ### Research Playbooks (in-thread)
 
 Research work is no longer modeled as standalone personas. Use in-thread playbooks under \`.cclaw/skills/research/\`:
@@ -257,7 +535,7 @@ ${(() => {
         const mode = activationModeSummary();
         return `- **Mandatory:** ${mode.mandatory}.
 - **Proactive:** ${mode.proactive}.
-- **On-demand:** none in the core-5 roster; research playbooks are in-thread procedures.`;
+- **On-demand:** slice-implementer, implementer, fixer. Research playbooks are in-thread procedures.`;
     })()}
 
 ### Cost-aware routing

package/dist/content/examples.js

@@ -4,11 +4,19 @@ const STAGE_EXAMPLES = {
 - **Project state:** Monorepo with CI pipeline using custom release scripts. Release checks are scattered across shell scripts with no shared validation logic.
 - **Relevant existing code/patterns:** \`scripts/pre-publish.sh\` does metadata checks. \`src/release/\` has partial validation helpers.
 
-## Problem
+## Problem Decision Record
 
-- **What we're solving:** release checks are fragile and inconsistent between CI and local runs. Invalid metadata sometimes reaches npm publish.
-- **Success criteria:** invalid release preconditions are caught before publish with explicit operator feedback, in both CI and local workflows.
-- **Constraints:** no new runtime dependencies; must work within existing CI pipeline structure.
+- **Depth:** standard
+- **Frame type:** technical-maintenance
+
+### Technical-maintenance framing
+
+- **Affected operator/developer:** release operator and package maintainer.
+- **Current failure mode:** release checks are fragile and inconsistent between CI and local runs; invalid metadata sometimes reaches npm publish.
+- **Expected operational improvement:** invalid release preconditions are caught before publish with explicit operator feedback in CI and local workflows.
+- **Verification signal:** shared release validation tests and CI release-check command fail on invalid metadata.
+- **Do-nothing cost:** continued publish risk and duplicated local/CI fixes.
+- **Non-goals:** no new runtime dependencies; no release-framework rewrite.
 
 ## Clarifying Questions
 
@@ -482,7 +490,7 @@ const GOOD_BAD_EXAMPLES = {
         },
         {
             label: "Scope change trace",
-            good: "Scope delta at 2026-04-15: user asked to add per-user mute preferences. Decision: moved from Out-of-scope → In-scope; acknowledged cost (≈1 day, +1 schema migration); risk: touches settings surface. Recorded in \`03-design.md#scope-trace\`. Requires re-running scope review before design lock.",
+            good: "Scope delta at 2026-04-15: user asked to add per-user mute preferences. Decision: moved from Out-of-scope → In-scope; acknowledged cost (≈1 day, +1 schema migration); risk: touches settings surface. Recorded in \`.cclaw/artifacts/03-design-<slug>.md#scope-trace\`. Requires re-running scope review before design lock.",
             bad: "Added mute preferences to scope.",
             lesson: "Scope changes silently are how projects drift. Every in↔out move needs a timestamp, a cost estimate, and a link to the next review it invalidates."
         }
@@ -667,13 +675,14 @@ function exampleSummaryBullets(stage) {
 // sample in STAGE_EXAMPLES gains or loses a top-level section.
 const STAGE_EXAMPLE_SECTION_HEADINGS = {
     brainstorm: [
-        "Problem framing (problem, success, constraints)",
-        "Candidate approaches with trade-offs",
+        "Problem Decision Record (product or technical-maintenance framing)",
+        "Reference Pattern Candidates and approaches with trade-offs",
         "Recommended direction + open questions",
         "Clarification log and decision record"
     ],
     scope: [
         "In-scope / out-of-scope / deferred lists with concrete capabilities",
+        "Reference Pattern Registry with accepted/rejected/deferred dispositions",
         "Requirements table with stable R# IDs",
         "Boundary stress-tests and non-negotiables",
         "Decision record for premise challenges"
@@ -681,6 +690,7 @@ const STAGE_EXAMPLE_SECTION_HEADINGS = {
     design: [
         "Blast-radius file list",
         "Mandatory architecture diagram (Mermaid)",
+        "Reference-Grade Contracts for mirrored patterns",
         "Failure-mode table with detection + mitigation",
         "Test strategy + performance budget",
         "Completion dashboard + unresolved decisions"
@@ -698,7 +708,7 @@ const STAGE_EXAMPLE_SECTION_HEADINGS = {
         "No-Placeholder scan row + WAIT_FOR_CONFIRM marker"
     ],
     tdd: [
-        "RED evidence per slice (failing test output)",
+        "RED evidence per vertical slice (failing test output)",
         "Acceptance mapping per slice",
         "GREEN evidence (full-suite pass)",
         "REFACTOR notes with behavior-preservation confirmation",
@@ -708,10 +718,11 @@ const STAGE_EXAMPLE_SECTION_HEADINGS = {
         "Spec-compliance findings (Layer 1)",
         "Code-quality findings (Layer 2)",
         "Severity, evidence, and status per finding",
-        "Go / no-go verdict"
+        "Victory Detector-backed go / no-go verdict"
     ],
     ship: [
         "Release checklist (version, changelog, tag, artifacts)",
+        "Victory Detector: valid review, fresh preflight, rollback, finalization enum",
         "Rollback plan with trigger, steps, verification",
         "Runbook (how to verify the release post-deploy)",
         "Sign-off block"
@@ -724,7 +735,7 @@ const DOMAIN_LABELS = {
     "data-pipeline": "Data pipeline / ETL"
 };
 export const RESEARCH_FLEET_USAGE_EXAMPLE = [
-    "Before drafting `03-design.md`, run `research/research-fleet.md` once and",
+    "Before drafting `.cclaw/artifacts/03-design-<slug>.md`, run `research/research-fleet.md` once and",
     "capture all four lenses in `.cclaw/artifacts/02a-research.md`.",
     "Dispatch semantics by harness: Claude/OpenCode/Codex = native subagents;",
     "Cursor = generic-dispatch Task mapping; role-switch only as degraded fallback.",

package/dist/content/next-command.js

@@ -76,7 +76,7 @@ ${conversationLanguagePolicyMarkdown()}
 
 1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
 2. Parse JSON. Capture \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If \`staleStages[currentStage]\` exists, do not advance automatically. Re-run the stage artifact work, then clear the marker with \`cclaw internal rewind --ack <currentStage>\`.
+3. If \`staleStages[currentStage]\` exists, do not advance automatically. Report the stale marker reason/rewindId, re-run the stage artifact work, then clear only the current stage marker with \`cclaw internal rewind --ack <currentStage>\`.
 4. Read **\`${reconciliationNoticesPath}\`** when present. If it contains entries for \`activeRunId + currentStage\` and the listed gate is still blocked in \`stageGateCatalog[currentStage].blocked\`, emit a structured warning before any stage-advance decision.
 5. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
 6. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
@@ -85,7 +85,7 @@ ${conversationLanguagePolicyMarkdown()}
 9. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if each mandatory agent is **completed** or **waived**.
 10. For each satisfied mandatory delegation row, verify \`evidenceRefs\` is a non-empty array (unless status is \`waived\` with rationale). Missing evidenceRefs means delegation is unresolved.
 11. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch now or waive with rationale. Do not mark gates passed while delegation is unresolved.
-12. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend \`cclaw internal rewind tdd "review_blocked_by_critical"\` with the blocking finding IDs, and do not attempt to advance toward ship.
+12. If \`currentStage === "review"\` and \`catalog.blocked\` includes \`review_criticals_resolved\`, treat this as a hard remediation branch: recommend the managed command \`cclaw internal rewind tdd "review_blocked_by_critical <finding-ids>"\`, and do not attempt to advance toward ship. After TDD rework, require \`cclaw internal rewind --ack tdd\` before continuing.
 
 ### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
 
@@ -186,11 +186,13 @@ ${conversationLanguagePolicyMarkdown()}
 Default output should be compact, like OMC/OMX operator surfaces:
 
 \`\`\`
-Stage: <currentStage> (<track>)
+Current: <currentStage or closeout.shipSubstate> (<track>)
+Stage: <currentStage>
 Gates: <passed>/<required> passed, <blocked> blocked
 Delegations: <done>/<mandatory> done
-Blockers: <none | gate/delegation/reconciliation ids>
+Blocked by: <none | gate/delegation/reconciliation/stale/TDD/review ids>
 Next: <exact next action, usually /cc-next or one named remediation>
+Evidence needed: <artifact/test/review/delegation evidence required to unblock>
 \`\`\`
 
 Only expand beyond this when blocked, when asking a structured question, or when
@@ -214,7 +216,7 @@ Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (p
 
 1. Open **\`${flowPath}\`**.
 2. Record \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If \`staleStages[currentStage]\` exists, re-run the stage and clear marker via \`cclaw internal rewind --ack <currentStage>\` before advancing.
+3. If \`staleStages[currentStage]\` exists, show the marker reason/rewindId, re-run the stage, and clear only the current marker via \`cclaw internal rewind --ack <currentStage>\` before advancing.
 4. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
 5. Read \`${reconciliationNoticesPath}\` when present. For entries matching \`activeRunId + currentStage\` whose gate is still in \`stageGateCatalog[currentStage].blocked\`, show a warning with gate id + reason before proceeding.
 
@@ -242,7 +244,9 @@ Execute the stage protocol. The stage skill handles interaction, STOP points, ga
 
 ${ralphLoopContractSnippet()}
 
-Special-case for review: if \`review_criticals_resolved\` is in \`blocked\`, route to rework instead of looping review forever — recommend \`cclaw internal rewind tdd "review_blocked_by_critical"\`.
+Special-case for review: if \`review_criticals_resolved\` is in \`blocked\`, route to rework instead of looping review forever - recommend \`cclaw internal rewind tdd "review_blocked_by_critical <finding-ids>"\`, then \`cclaw internal rewind --ack tdd\` after TDD rework.
+
+Special-case for TDD blockers: when \`06-tdd.md\` records \`NO_SOURCE_CONTEXT\`, \`NO_TEST_SURFACE\`, \`NO_IMPLEMENTABLE_SLICE\`, \`RED_NOT_EXPRESSIBLE\`, or \`NO_VCS_MODE\`, keep status BLOCKED and print \`Current\`, \`Blocked by\`, \`Next\`, and \`Evidence needed\` instead of retrying speculative RED/GREEN work.
 
 **Path B — stage IS complete (all gates met, all delegations done):**
 

package/dist/content/reference-patterns.d.ts

@@ -0,0 +1,18 @@
+import type { FlowStage } from "../types.js";
+export interface ReferencePatternContract {
+    stage: FlowStage;
+    guidance: string[];
+    artifactSections: string[];
+}
+export interface ReferencePattern {
+    id: string;
+    title: string;
+    intent: string;
+    useWhen: string;
+    policyNeedles: string[];
+    contracts: ReferencePatternContract[];
+}
+export declare const REFERENCE_PATTERNS: ReferencePattern[];
+export declare function referencePatternsForStage(stage: FlowStage): ReferencePattern[];
+export declare function referencePatternContractsForStage(stage: FlowStage): ReferencePatternContract[];
+export declare function referencePatternPolicyNeedles(stage: FlowStage): string[];