cclaw-cli 0.51.24 → 0.51.25

package/dist/content/skills.js

@@ -4,6 +4,7 @@ import { FLOW_STAGES } from "../types.js";
 import { stageExamples } from "./examples.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
 import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
+import { referencePatternsForStage } from "./reference-patterns.js";
 const VERIFICATION_STAGES = ["tdd", "review", "ship"];
 function whenNotToUseBlock(items) {
     if (items.length === 0) {
@@ -37,24 +38,17 @@ Before execution:
 2. Load active artifacts from \`.cclaw/artifacts/\`.
 3. Load upstream artifacts required by this stage:
 ${readLines}
-4. Read the state contract for this stage from \`.cclaw/templates/state-contracts/<stage>.json\`.
-   Treat it as the machine-readable skeleton: required top-level fields,
-   closed taxonomies, and the derived markdown path. Do not validate natural-language
-   prose by regex; put semantic quality checks in the review prompts.
-5. Read the canonical artifact template at \`${artifactTemplatePath}\` and reuse its
-   exact section layout — per-row tables with stable column order, calibrated review block;
-   do not invent layouts for sections the template already defines.
-6. Extract upstream decisions, constraints, and open questions into the current
-   artifact's \`Upstream Handoff\` section when that section exists.
-7. Before doing stage work, give a compact user-facing drift preamble: "Carrying forward: <1-3 bullets>. Drift since upstream: None / <specific drift>. Recommendation: continue / re-scope."
-8. If you change an upstream decision, record an explicit drift reason in the
-   current artifact before continuing.
-9. Confirm stage inputs:
+4. Read the state contract from \`.cclaw/templates/state-contracts/<stage>.json\` for required fields, taxonomies, and derived markdown path.
+5. Read the canonical artifact template at \`${artifactTemplatePath}\` and reuse its exact section layout — per-row tables with stable column order, calibrated review block; do not invent layouts.
+6. Extract upstream decisions, constraints, and open questions into the current artifact's \`Upstream Handoff\` section when present.
+7. Confirm context readiness: upstream artifact freshness, required context, canonical template shape, relevant in-repo/reference patterns, and unresolved blockers are known. If any item is missing, load it or stop before drafting.
+8. Before doing stage work, give a compact user-facing drift preamble: "Carrying forward: <1-3 bullets>. Drift since upstream: None / <specific drift>. Recommendation: continue / re-scope."
+9. If you change an upstream decision, record an explicit drift reason in the current artifact before continuing.
+10. Confirm stage inputs:
 ${inputs}
-10. Confirm required context:
+11. Confirm required context:
 ${requiredContext}
-11. Use the injected knowledge digest from session-start; only fall back to full
-   \`.cclaw/knowledge.jsonl\` when the digest is insufficient.
+12. Use the injected knowledge digest; only fall back to full \`.cclaw/knowledge.jsonl\` when insufficient.
 `;
 }
 function autoSubagentDispatchBlock(stage, track) {
@@ -65,7 +59,9 @@ function autoSubagentDispatchBlock(stage, track) {
     const rows = rules
         .map((rule) => {
         const userGate = rule.requiresUserGate ? "required" : "not required";
-        return `| ${rule.agent} | ${rule.mode} | ${userGate} | ${rule.when} | ${rule.purpose} |`;
+        const dispatchClass = rule.dispatchClass ?? "stage-specialist";
+        const returnSchema = rule.returnSchema ?? "agent-default";
+        return `| ${rule.agent} | ${rule.mode} | ${dispatchClass} | ${returnSchema} | ${userGate} | ${rule.when} | ${rule.purpose} |`;
     })
         .join("\n");
     const mandatory = schema.mandatoryDelegations;
@@ -73,27 +69,37 @@ function autoSubagentDispatchBlock(stage, track) {
     const delegationLogRel = `${RUNTIME_ROOT}/state/delegation-log.json`;
     const artifactRef = `${RUNTIME_ROOT}/artifacts/${schema.artifactRules.artifactFile}`;
     return `## Automatic Subagent Dispatch
-| Agent | Mode | User Gate | Trigger | Purpose |
-|---|---|---|---|---|
+| Agent | Mode | Class | Return Schema | User Gate | Trigger | Purpose |
+|---|---|---|---|---|---|---|
 ${rows}
-Mandatory: ${mandatoryList}. Record completion/waiver in \`${delegationLogRel}\` before completion.
+Mandatory: ${mandatoryList}. Record scheduled/completed/waived lifecycle rows in \`${delegationLogRel}\` before completion.
 ### Harness Dispatch Contract
-Use true harness dispatch: Claude native Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\`, Codex \`.codex/agents/<agent>.toml\`. Run independent read-only/review agents in parallel where safe, write evidence into \`${artifactRef}\`, then append \`${delegationLogRel}\` rows with matching \`fulfillmentMode: "isolated"\` or \`"generic-dispatch"\`. Do not collapse OpenCode or Codex to role-switch by default; role-switch is degraded fallback and must carry non-empty \`evidenceRefs\`. Missing evidence blocks completion.
+Use true harness dispatch: Claude native Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\`, Codex \`.codex/agents/<agent>.toml\`. Run independent read-only/review agents in parallel where safe, write evidence into \`${artifactRef}\`, then append \`${delegationLogRel}\` rows with matching \`fulfillmentMode: "isolated"\` or \`"generic-dispatch"\`. Each dispatched worker should have a scheduled row and a terminal row sharing \`spanId\`; stale scheduled spans block completion. Do not collapse OpenCode or Codex to role-switch by default; role-switch is degraded fallback and must carry non-empty \`evidenceRefs\`. Missing evidence blocks completion.
 `;
 }
 function researchPlaybooksBlock(playbooks) {
     if (playbooks.length === 0)
         return "";
     const rows = playbooks
-        .map((playbook) => `- \`${RUNTIME_ROOT}/skills/${playbook}\``)
-        .join("\n");
+        .map((playbook) => `\`${RUNTIME_ROOT}/skills/${playbook}\``)
+        .join("; ");
     return `## Research Playbooks
-
-Use these in-thread research procedures before locking this stage. They are
-playbooks (not delegated personas), so execute them in the primary agent context
-and record outcomes in the stage artifact when relevant.
-
-${rows}
+Execute in primary agent context before locking the stage; record outcomes in the artifact when relevant: ${rows}.
+`;
+}
+function referencePatternsBlock(stage) {
+    const patterns = referencePatternsForStage(stage);
+    if (patterns.length === 0)
+        return "";
+    const summaries = patterns
+        .map((pattern) => {
+        const contract = pattern.contracts.find((item) => item.stage === stage);
+        const sections = contract ? contract.artifactSections.join(", ") : "n/a";
+        return `${pattern.title} (sections: ${sections})`;
+    })
+        .join("; ");
+    return `## Reference Patterns
+Prompt-only; no runtime/delegation changes. These compact pattern titles come from the internal registry; use the behavior and artifact sections, not the source project history. Use: ${summaries}.
 `;
 }
 function reviewSectionsBlock(sectionsInput) {
@@ -389,9 +395,8 @@ ${conversationLanguagePolicyMarkdown()}
 ${philosophy.purpose}
 
 ## Complexity Tier
-- Active tier: \`${schema.complexityTier}\`
-- Scale-to-complexity rule: execute required gates and artifact sections, but keep optional/deep sections compact unless risk, novelty, or configuration triggers them. Do not mechanically expand lightweight work into a strategy workshop.
-- Mandatory delegations at this tier: ${mandatoryDelegationSummary}
+- Active tier: \`${schema.complexityTier}\`; mandatory delegations: ${mandatoryDelegationSummary}
+- Scale-to-complexity: execute required gates/sections; keep optional/deep sections compact unless risk, novelty, or config triggers them.
 - Track render context: \`${trackContext.track}\` (${trackContext.usesPlanTerminology ? "plan-first wording" : "acceptance-first wording"})
 
 ## When to Use
@@ -406,14 +411,14 @@ ${mergedAntiPatterns(philosophy, executionModel)}
 
 ## Process
 
-This is the stage **state machine** — the canonical ordered flow. For every detailed step, gate, and wording, follow the Checklist below; this diagram is the map, not the territory.
-
+Stage state machine (map only; Checklist is authoritative):
 ${processFlowMermaid.length > 0 ? processFlowMermaid : "```mermaid\nflowchart TD\n  S1[\"Execute Checklist\"] --> S2[\"Satisfy required gates\"] --> S3[\"Verify before closeout\"]\n```"}
 
 ${platformNotesBlock}${contextLoadingBlock(stage, artifactRules.crossStageTrace, executionModel)}
 ${autoSubagentDispatchBlock(stage, track)}
 ${stackAwareReviewRoutingBlock(stage)}
 ${researchPlaybooksBlock(executionModel.researchPlaybooks ?? [])}
+${referencePatternsBlock(stage)}
 
 ## Checklist
 

package/dist/content/stage-common-guidance.js

@@ -14,6 +14,11 @@ ${conversationLanguagePolicyMarkdown()}
   harvest learnings, then use \`/cc-next\` for progression.
 - Do not create separate protocol files.
 
+## Context readiness
+
+- Before drafting, know the upstream artifact freshness, required template shape, relevant code/reference patterns, and unresolved blockers.
+- If any item is missing, load it or stop with a blocker instead of inventing content.
+
 ## Shared decision protocol
 
 - Ask only decision-changing questions.
@@ -28,7 +33,7 @@ Use this same closeout menu for every stage:
 - **A) Advance** — run \`/cc-next\` and continue the critical path; after \`ship\`, the same command drives \`retro -> compound -> archive\`.
 - **B) Revise this stage** — stay on current stage and apply feedback.
 - **C) Pause / park** — run \`/cc-view status\`, then stop and resume later.
-- **D) Rewind** — run \`npx cclaw-cli internal rewind <target-stage> "<reason>"\` as a support/runtime repair action.
+- **D) Rewind** — run \`npx cclaw-cli internal rewind <target-stage> "<reason>"\` as the managed support/runtime repair action; after redoing the target stage, run \`npx cclaw-cli internal rewind --ack <target-stage>\` to clear the stale marker.
 - **E) Abandon** — only when the user explicitly wants to end a non-ship active run early, archive with \`npx cclaw-cli archive --skip-retro --retro-reason="<reason>"\`. Once in post-ship closeout, continue \`/cc-next\` through retro/compound/archive instead.
 
 Recommendation defaults:
@@ -37,6 +42,12 @@ Recommendation defaults:
 - Completion status \`DONE_WITH_CONCERNS\` -> recommend **B**.
 - Completion status \`BLOCKED\` -> recommend **B** or **C**.
 
+## Iterate / Victory Detector
+
+- Iterate while a required gate, artifact section, or fresh evidence item is missing.
+- Stop only when the stage-specific Victory Detector passes or a named blocker is recorded.
+- Do not use vague closeout wording such as \`looks good\`, \`done enough\`, or \`all set\` without the detector evidence.
+
 ## Completion status vocabulary
 
 - \`DONE\` — all required gates and checks satisfied.
@@ -63,9 +74,12 @@ Rollback / fallback: <if decision proves wrong>
 
 Before closeout, fill the artifact \`## Learnings\` section (do not write
 \`.cclaw/knowledge.jsonl\` by hand):
-- \`- None this stage.\` when nothing reusable emerged.
+- \`- None this stage.\` only when nothing reusable emerged.
 - Or 1-3 JSON bullets with required keys \`type\`, \`trigger\`, \`action\`,
   \`confidence\` (optional fields may mirror knowledge.jsonl schema keys).
+- For meaningful \`design\`, \`tdd\`, or \`review\` work, prefer a small JSON
+  learning over \`None\` when you made a reusable decision, found a testing
+  pattern, or caught a review/security issue.
 During \`node .cclaw/hooks/stage-complete.mjs <stage>\`, cclaw validates those
 bullets, appends unique entries to \`.cclaw/knowledge.jsonl\`, and stamps a
 harvest marker in the artifact.
@@ -78,7 +92,9 @@ Track policy:
 - \`quick\`: recommended only.
 
 \`- None this stage.\` is acceptable only when the stage produced no reusable
-insight (for example, purely mechanical edits with no new decisions).
+insight (for example, purely mechanical edits with no new decisions). If unsure,
+record a concise \`lesson\` with \`confidence":"medium"\` instead of dropping
+operator knowledge.
 
 ## Progressive disclosure baseline
 

package/dist/content/stage-schema.d.ts

@@ -23,11 +23,23 @@ export interface StageStackAwareReviewRoute {
     signals: string[];
     focus: string;
 }
+export interface StageDelegationDispatchRule {
+    agent: string;
+    mode: "mandatory" | "proactive";
+    when: string;
+    purpose: string;
+    requiresUserGate: boolean;
+    requiredAtTier?: StageComplexityTier;
+    dispatchClass: NonNullable<StageAutoSubagentDispatch["dispatchClass"]>;
+    returnSchema: NonNullable<StageAutoSubagentDispatch["returnSchema"]>;
+    skill?: string;
+}
 export interface StageDelegationSummary {
     stage: FlowStage;
     mandatoryAgents: string[];
     proactiveAgents: string[];
     primaryAgents: string[];
+    dispatchRules: StageDelegationDispatchRule[];
     stackAwareRoutes: StageStackAwareReviewRoute[];
 }
 export declare function reviewStackAwareRoutes(): StageStackAwareReviewRoute[];

package/dist/content/stage-schema.js

@@ -81,6 +81,66 @@ function dedupeAgentsInOrder(agents) {
     }
     return out;
 }
+function defaultReturnSchemaForAgent(agent) {
+    switch (agent) {
+        case "researcher":
+            return "research-return";
+        case "architect":
+            return "architecture-return";
+        case "spec-validator":
+            return "spec-validation-return";
+        case "slice-implementer":
+            return "worker-return";
+        case "performance-reviewer":
+            return "performance-return";
+        case "compatibility-reviewer":
+            return "compatibility-return";
+        case "observability-reviewer":
+            return "observability-return";
+        case "release-reviewer":
+            return "release-return";
+        case "planner":
+            return "planning-return";
+        case "product-manager":
+            return "product-return";
+        case "critic":
+            return "critic-return";
+        case "reviewer":
+            return "review-return";
+        case "security-reviewer":
+            return "security-return";
+        case "test-author":
+            return "tdd-return";
+        case "doc-updater":
+            return "docs-return";
+        case "fixer":
+            return "fixer-return";
+        case "implementer":
+            return "worker-return";
+    }
+}
+function dispatchClassForRow(row) {
+    if (row.dispatchClass)
+        return row.dispatchClass;
+    if (row.agent === "implementer" || row.agent === "fixer" || row.agent === "slice-implementer")
+        return "worker";
+    return row.skill?.includes("review") || row.agent === "reviewer" || row.agent === "security-reviewer" || row.agent.endsWith("-reviewer")
+        ? "review-lens"
+        : "stage-specialist";
+}
+function delegationDispatchRule(row) {
+    return {
+        agent: row.agent,
+        mode: row.mode,
+        when: row.when,
+        purpose: row.purpose,
+        requiresUserGate: row.requiresUserGate,
+        requiredAtTier: row.requiredAtTier,
+        dispatchClass: dispatchClassForRow(row),
+        returnSchema: row.returnSchema ?? defaultReturnSchemaForAgent(row.agent),
+        skill: row.skill
+    };
+}
 /**
  * Canonical delegation summary derived from STAGE_AUTO_SUBAGENT_DISPATCH.
  *
@@ -106,6 +166,7 @@ export function stageDelegationSummary(complexityTier = "standard") {
             mandatoryAgents,
             proactiveAgents,
             primaryAgents,
+            dispatchRules: eligibleRows.map(delegationDispatchRule),
             stackAwareRoutes: stackAwareRoutesForStage(stage)
         };
     });
@@ -361,23 +422,25 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
     brainstorm: [
         {
             agent: "product-manager",
-            mode: "proactive",
-            when: "When product value, persona/JTBD, success metric, or why-now framing is ambiguous.",
+            mode: "mandatory",
+            requiredAtTier: "standard",
+            when: "Always for standard/deep brainstorm to validate value, persona/JTBD, success metric, and why-now framing.",
             purpose: "Pressure-test problem/value fit and produce product-discovery evidence for the Problem Decision Record.",
             requiresUserGate: false
         },
         {
             agent: "critic",
-            mode: "proactive",
-            when: "When the premise may be wrong, cheaper alternatives exist, or the do-nothing path could be acceptable.",
+            mode: "mandatory",
+            requiredAtTier: "standard",
+            when: "Always for standard/deep brainstorm to challenge the premise, do-nothing path, and higher-upside alternatives.",
             purpose: "Attack assumptions and surface non-goals before direction approval.",
             requiresUserGate: false
         },
         {
-            agent: "planner",
+            agent: "researcher",
             mode: "proactive",
-            when: "When request is ambiguous, multi-surface, or staged feasibility is unclear.",
-            purpose: "Map scope and alternatives before direction lock.",
+            when: "When repository, market, docs, or prior-art context changes the approach set.",
+            purpose: "Provide search-before-read summaries and context-readiness evidence before large reads or decisions.",
             requiresUserGate: false
         }
     ],
@@ -392,11 +455,19 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         },
         {
             agent: "critic",
-            mode: "proactive",
-            when: "When selecting SELECTIVE EXPANSION, SCOPE EXPANSION, or SCOPE REDUCTION, or when boundaries feel soft.",
+            mode: "mandatory",
+            requiredAtTier: "standard",
+            when: "Always during scope shaping for standard/deep work.",
             purpose: "Test whether the selected scope mode is too timid, too broad, or hiding a smaller useful slice.",
             requiresUserGate: false
         },
+        {
+            agent: "researcher",
+            mode: "proactive",
+            when: "When churn, prior attempts, reference patterns, or external constraints may change scope boundaries.",
+            purpose: "Summarize search/context findings before the scope contract locks accepted/rejected/deferred ideas.",
+            requiresUserGate: false
+        },
         {
             agent: "product-manager",
             mode: "proactive",
@@ -407,13 +478,21 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
     ],
     design: [
         {
-            agent: "planner",
+            agent: "architect",
             mode: "mandatory",
             requiredAtTier: "standard",
             when: "Always during design lock.",
             purpose: "Stress architecture boundaries, dependency graph, critical path, and spec handoff.",
             requiresUserGate: false
         },
+        {
+            agent: "test-author",
+            mode: "mandatory",
+            requiredAtTier: "standard",
+            when: "Always during design lock.",
+            purpose: "Check test diagram mapping, RED expressibility, assertion quality, and verification routes before implementation.",
+            requiresUserGate: false
+        },
         {
             agent: "critic",
             mode: "proactive",
@@ -421,6 +500,13 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             purpose: "Produce a shadow alternative, switch trigger, and cheaper-path challenge for the engineering lock.",
             requiresUserGate: false
         },
+        {
+            agent: "researcher",
+            mode: "proactive",
+            when: "When framework/library docs, repo graph context, or reference contracts may change the design.",
+            purpose: "Run search-before-read context synthesis before architecture locks.",
+            requiresUserGate: false
+        },
         {
             agent: "security-reviewer",
             mode: "proactive",
@@ -429,26 +515,36 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             requiresUserGate: false
         },
         {
-            agent: "test-author",
+            agent: "compatibility-reviewer",
+            mode: "proactive",
+            requiredAtTier: "lightweight",
+            when: "When public API, config, persisted data, CLI, generated clients, or cross-version behavior can change.",
+            purpose: "Identify backward-compatibility and migration hazards before spec/plan.",
+            requiresUserGate: false
+        },
+        {
+            agent: "observability-reviewer",
             mode: "proactive",
-            when: "When testability, failure/rescue behavior, or verification evidence is unclear.",
-            purpose: "Check that the design can produce concrete RED/GREEN/REFACTOR and rollout verification evidence.",
+            requiredAtTier: "lightweight",
+            when: "When runtime/debuggability, rollout, failure detection, or supportability matters.",
+            purpose: "Validate logs/metrics/traces, alerting, and rescue-path visibility 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.",
+            agent: "spec-validator",
+            mode: "mandatory",
+            requiredAtTier: "standard",
+            when: "Always for standard/deep specs before plan handoff.",
+            purpose: "Validate measurability, edge cases, assumptions, and AC-to-testability mapping.",
             requiresUserGate: false
         },
         {
-            agent: "reviewer",
+            agent: "test-author",
             mode: "proactive",
-            when: "When acceptance criteria and edge cases are drafted and need independent validation before plan stage.",
-            purpose: "Independent review of spec against measurability, testability, and completeness before locking the contract for plan.",
+            when: "When acceptance criteria need testability review or RED expressibility is uncertain.",
+            purpose: "Confirm likely test levels, commands/manual evidence, and assertion surfaces are concrete.",
             requiresUserGate: false
         }
     ],
@@ -458,7 +554,14 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             mode: "mandatory",
             requiredAtTier: "standard",
             when: "Always when producing execution slices.",
-            purpose: "Create dependency-aware task graph with verification steps.",
+            purpose: "Create dependency-aware executable packets with expected failing test, passing command, stop condition, and verification evidence.",
+            requiresUserGate: false
+        },
+        {
+            agent: "researcher",
+            mode: "proactive",
+            when: "When plan tasks touch unfamiliar areas or reference-pattern adoption needs source verification.",
+            purpose: "Confirm context/search evidence before plan packets rely on discovered patterns.",
             requiresUserGate: false
         }
     ],
@@ -468,10 +571,25 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             mode: "mandatory",
             requiredAtTier: "lightweight",
             when: "Always during the TDD cycle.",
-            purpose: "Own phase-specific RED/GREEN/REFACTOR evidence for each slice: failing tests before production writes, minimal GREEN implementation, then behavior-preserving refactor notes.",
+            purpose: "Own RED quality and per-slice RED/GREEN/REFACTOR evidence: failing tests before production writes, minimal GREEN implementation, then behavior-preserving refactor notes.",
             requiresUserGate: false,
             skill: "tdd-cycle-evidence"
         },
+        {
+            agent: "slice-implementer",
+            mode: "proactive",
+            requiredAtTier: "lightweight",
+            when: "When a bounded GREEN/REFACTOR slice has non-overlapping file ownership and a clear RED failure.",
+            purpose: "Implement the minimal passing slice inside explicit file boundaries and return strict worker evidence.",
+            requiresUserGate: false
+        },
+        {
+            agent: "reviewer",
+            mode: "proactive",
+            when: "When per-slice review triggers fire or assertion quality needs an independent read-only overseer.",
+            purpose: "Read-only overseer pass for slice spec fit, assertion quality, and simpler alternatives.",
+            requiresUserGate: false
+        },
         {
             agent: "doc-updater",
             mode: "proactive",
@@ -486,7 +604,7 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             mode: "mandatory",
             requiredAtTier: "lightweight",
             when: "Always in review stage.",
-            purpose: "Layer 1 spec compliance plus integrated Layer 2 review across correctness, performance, architecture, and external-safety tags with source-tagged findings.",
+            purpose: "Layer 1 spec compliance plus integrated Layer 2 review across correctness, architecture, and external-safety tags with source-tagged findings.",
             requiresUserGate: false,
             skill: "review-spec-pass"
         },
@@ -494,11 +612,35 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "security-reviewer",
             mode: "mandatory",
             requiredAtTier: "lightweight",
-            when: "Always in review stage. Even when no trust boundaries changed, produce an explicit 'no-change' security attestation.",
-            purpose: "Guarantee a dedicated security pass on every diff: auth, input validation, secrets, injection, privilege, and blast-radius review are never opt-in. MUST load the `security-audit` skill and run a pattern-based sweep across the diff scope and touched modules in addition to the per-diff Layer 2 security checklist.",
+            when: "Always in review stage. Even when no trust boundaries changed, produce an explicit no-change/no-impact security attestation.",
+            purpose: "Guarantee a dedicated security pass on every diff: auth, input validation, secrets, injection, privilege, and blast-radius review are never opt-in.",
             requiresUserGate: false,
             skill: "security-audit"
         },
+        {
+            agent: "performance-reviewer",
+            mode: "proactive",
+            requiredAtTier: "lightweight",
+            when: "When hot paths, IO, data volume, rendering, caching, or algorithmic cost can move.",
+            purpose: "Run a focused performance lens and report evidence-backed regressions or no-impact rationale.",
+            requiresUserGate: false
+        },
+        {
+            agent: "compatibility-reviewer",
+            mode: "proactive",
+            requiredAtTier: "lightweight",
+            when: "When public API, CLI/config, persisted data, generated clients, or dependency versions change.",
+            purpose: "Check compatibility, migrations, and consumer-facing contract stability.",
+            requiresUserGate: false
+        },
+        {
+            agent: "observability-reviewer",
+            mode: "proactive",
+            requiredAtTier: "lightweight",
+            when: "When failure diagnosis, logging/metrics/traces, rollout, or operational support matters.",
+            purpose: "Check observability and supportability evidence against the design/review artifact.",
+            requiresUserGate: false
+        },
         {
             agent: "reviewer",
             mode: "proactive",
@@ -511,7 +653,7 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "reviewer",
             mode: "proactive",
             when: "When external reviewer comments, bot findings, or CI annotations are present after the initial review pass.",
-            purpose: "Run the receiving-code-review workflow so every incoming feedback item gets an explicit disposition with evidence, and the queue is mirrored into review artifacts.",
+            purpose: "Run the receiving-code-review workflow so every incoming feedback item gets an explicit disposition with evidence.",
             requiresUserGate: false,
             skill: "receiving-code-review"
         },
@@ -526,10 +668,17 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
     ],
     ship: [
         {
-            agent: "doc-updater",
+            agent: "release-reviewer",
             mode: "mandatory",
             requiredAtTier: "lightweight",
             when: "Always in ship stage.",
+            purpose: "Run release readiness, finalization mode, rollback, evidence freshness, and victory-detector checks before archive/ship.",
+            requiresUserGate: false
+        },
+        {
+            agent: "doc-updater",
+            mode: "proactive",
+            when: "When release notes, migrations, public behavior, CLI/config, or docs changed.",
             purpose: "Ensure release notes and docs reflect actual shipped behavior.",
             requiresUserGate: false
         },
@@ -661,5 +810,12 @@ export function stageTrackRenderContext(track = "standard") {
     return trackRenderContext(track);
 }
 export function stageAutoSubagentDispatch(stage) {
-    return STAGE_AUTO_SUBAGENT_DISPATCH[stage];
+    return STAGE_AUTO_SUBAGENT_DISPATCH[stage].map((row) => {
+        const normalized = delegationDispatchRule(row);
+        return {
+            ...row,
+            dispatchClass: normalized.dispatchClass,
+            returnSchema: normalized.returnSchema
+        };
+    });
 }

package/dist/content/stages/_lint-metadata/index.js

@@ -1,5 +1,6 @@
 import { SHIP_FINALIZATION_MODES } from "../../../constants.js";
 import { renderTrackTerminology, trackRenderContext } from "../../track-render-context.js";
+import { referencePatternPolicyNeedles } from "../../reference-patterns.js";
 const STAGE_POLICY_NEEDLES = {
     brainstorm: [
         "Explore project context",
@@ -64,10 +65,10 @@ const STAGE_POLICY_NEEDLES = {
     ]
 };
 export function stagePolicyNeedlesFromMetadata(stage, track = "standard") {
-    const needles = STAGE_POLICY_NEEDLES[stage];
+    const needles = [...STAGE_POLICY_NEEDLES[stage], ...referencePatternPolicyNeedles(stage)];
     const renderContext = trackRenderContext(track);
     if (stage === "tdd" && !renderContext.usesPlanTerminology) {
         return needles.map((needle) => renderTrackTerminology(needle, renderContext));
     }
-    return [...needles];
+    return needles;
 }

package/dist/content/stages/brainstorm.js

@@ -41,11 +41,12 @@ export const BRAINSTORM = {
             "**Write the Problem Decision Record** — product work captures persona/JTBD/pain/value/evidence/success/why-now/do-nothing/non-goals; technical-maintenance work captures affected operator/developer, failure mode, operational improvement, verification signal, do-nothing cost, and non-goals.",
             "**Premise check (one pass)** — answer the three gstack-style questions in the artifact body: *Right problem? Direct path? What if we do nothing?* Take a position; do not hedge.",
             "**Reframe with How Might We** — write a single `How Might We …?` line that names the user/operator, the desired outcome, and the constraint. This is the altitude check before approaches.",
+            "**Run Clarity Gate** — record ambiguity score (0.00-1.00), decision boundaries, reaffirmed non-goals, and residual-risk handoff before locking recommendations. If ambiguity remains high (>0.40), ask one decision-changing question before recommending.",
             "**Sharpening question discipline** — ask one decision-changing question at a time. Do not default to 3-5 batched questions; record only questions that changed the direction or a critical stop decision.",
             "**Use compact discovery for simple apps** — for concrete low-risk asks (todo app, landing page, local widget), do one context pass, compare one baseline and one challenger, then ask for one explicit approval; do not drag the user through a full workshop.",
             "**Early-exit concrete asks** — for unambiguous implementation-only requests, write a compact Problem Decision Record plus short-circuit handoff (context, approved intent, constraints, assumptions, next-stage risks) and ask for one explicit approval.",
             "**Ask only decision-changing questions** — one at a time; if answers would not change approach and are non-critical preference/default assumptions, state the assumption and continue; STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user approval uncertainty.",
-            "**Compare 2-3 distinct approaches with stable Role/Upside columns** — Role values are `baseline` | `challenger` | `wild-card`; Upside is `low` | `modest` | `high` | `higher`; include real trade-offs and reuse notes; include exactly one challenger with explicit `high` or `higher` upside.",
+            "**Compare 2-3 distinct approaches with stable Role/Upside columns** — Role values are `baseline` | `challenger` | `wild-card`; Upside is `low` | `modest` | `high` | `higher`; include real trade-offs, reuse notes, and reference-pattern source/disposition when a known pattern influenced the option; include exactly one challenger with explicit `high` or `higher` upside.",
             "**Collect reaction before recommending** — ask which option feels closest and what concern remains, then recommend based on that reaction.",
             "**Write the `Not Doing` list** — name 3-5 things this brainstorm explicitly is not committing to (vs. deferred). This protects scope from silent enlargement and the next stage from rework.",
             "**Self-review before user approval** — re-read the artifact and patch contradictions, weak trade-offs, placeholders, ambiguity, and weak handoff language. Record the result in `Self-Review Notes` using the calibrated review format: `- Status: Approved` (or `Issues Found`), `- Patches applied:` with inline note or sub-bullets, `- Remaining concerns:` with inline note or sub-bullets. Use `Patches applied: None` and `Remaining concerns: None` when there is nothing to record.",
@@ -81,8 +82,9 @@ export const BRAINSTORM = {
             "Artifact written to `.cclaw/artifacts/01-brainstorm-<slug>.md`.",
             "Project context was explored (files, docs, or recent activity referenced).",
             "Problem Decision Record includes product framing or technical-maintenance framing.",
+            "Clarity Gate records ambiguity score, decision boundaries, reaffirmed non-goals, and residual-risk handoff.",
             "Clarifying questions are one-at-a-time and captured only when they change a decision or stop condition.",
-            "2-3 approaches with trade-offs are recorded, including one higher-upside challenger option.",
+            "2-3 approaches with trade-offs are recorded, including one higher-upside challenger option and reference-pattern source/disposition when applicable.",
             "User reaction to approaches is captured before final recommendation.",
             "Final recommendation explicitly reflects user reaction.",
             "Selected Direction includes the handoff to the track-aware next stage: scope on standard, spec on medium when scope/design are skipped.",
@@ -131,11 +133,13 @@ export const BRAINSTORM = {
             { section: "Problem Decision Record", required: true, validationRule: "Must include either product framing fields (persona/JTBD/pain/value/evidence/success/why-now/do-nothing/non-goals) or technical-maintenance fields (operator/developer, failure mode, operational improvement, verification signal, do-nothing cost, non-goals)." },
             { section: "Premise Check", required: false, validationRule: "Recommended: explicit answers to `Right problem?`, `Direct path?`, `What if we do nothing?` — take a position, do not hedge." },
             { section: "How Might We", required: false, validationRule: "Recommended: a single `How Might We …?` line naming the user, the outcome, and the binding constraint." },
+            { section: "Clarity Gate", required: false, validationRule: "Recommended before recommendation lock: include ambiguity score (0.00-1.00), decision boundaries, reaffirmed non-goals, and residual-risk handoff for scope." },
             { section: "Sharpening Questions", required: false, validationRule: "Recommended only when needed: one decision-changing question per turn with explicit `Decision impact`; compact tasks may record `None - early exit` with rationale." },
             { section: "Clarifying Questions", required: false, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
             { section: "Approach Tier", required: true, validationRule: "Must classify depth as lite/standard/deep and explain the risk/uncertainty signal." },
             { section: "Short-Circuit Decision", required: false, validationRule: "Must include Status/Why/Scope handoff lines when short-circuit is discussed; compact stubs are valid for concrete asks." },
-            { section: "Approaches", required: true, validationRule: "Must compare 2-3 distinct options with real trade-offs. Use the canonical `Role` column with `baseline` | `challenger` | `wild-card` and the `Upside` column with `low` | `modest` | `high` | `higher`; include exactly one challenger row with `high` or `higher` upside." },
+            { section: "Reference Pattern Candidates", required: false, validationRule: "Recommended when examples influence direction: list pattern/source, reusable invariant, accept/reject/defer disposition, and reason before approaches are finalized." },
+            { section: "Approaches", required: true, validationRule: "Must compare 2-3 distinct options with real trade-offs. Use the canonical `Role` column with `baseline` | `challenger` | `wild-card` and the `Upside` column with `low` | `modest` | `high` | `higher`; include exactly one challenger row with `high` or `higher` upside, and cite reference-pattern source/disposition when applicable." },
             { section: "Approach Reaction", required: true, validationRule: "Must appear before Selected Direction and summarize user reaction before recommendation, including `Closest option`, `Concerns`, and what changed after reaction." },
             { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, explicit approval marker, rationale traceable to Approach Reaction, and scope handoff with decisions, drift, confidence, unresolved questions, risk hints, and non-goals." },
             { section: "Not Doing", required: false, validationRule: "Recommended: 3-5 explicitly non-committed items (distinct from deferred). Protects scope from silent enlargement and the next stage from rework." },