cclaw-cli 0.51.24 → 0.51.26

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." },

package/dist/content/stages/design.js

@@ -45,9 +45,10 @@ export const DESIGN = {
             "Tiered Research — for simple/medium work, do compact inline codebase/research synthesis in `Research Fleet Synthesis`; write `.cclaw/artifacts/02a-research.md` and run the full fleet only for deep/high-risk work or when external framework/architecture uncertainty exists.",
             "Design Doc Check — read upstream artifacts and current design docs; latest superseding doc wins.",
             "Investigator pass — before design decisions, read blast-radius code and record touched files, responsibilities, reuse candidates, and existing patterns.",
-            "Scope Challenge + Search Before Building — find existing solutions, minimum change set, and complexity smells before custom architecture.",
+            "Scope Challenge + Search Before Building — find existing solutions, minimum change set, reference-grade contracts to mirror, and complexity smells before custom architecture.",
             "Architecture Review — lock boundaries, chosen path, shadow alternative, switch trigger, failure/rescue/degraded behavior, and verification evidence for every high-risk choice; include tier-required diagrams.",
             "Review core risk areas — existing system fit, data/state flow, critical path, security/trust boundaries, tests, performance budget, observability/debuggability, rollout/rollback, rejected alternatives, and spec handoff.",
+            "**ADR + pre-mortem contract** — capture ADR-style decision rows (context, decision, alternatives, consequences), run a pre-mortem on likely failures, and map each critical flow to a validating test and diagram anchor before lock.",
             `Critic pass — run/reconcile adversarial second opinion on architecture, coupling, failure modes, and cheaper alternatives. ${reviewLoopPolicySummary("design")} ${reviewLoopSecondOpinionSummary("design")}`,
             "Run optional stale-diagram audit only when configured.",
             "Capture leftovers — seed high-upside deferred ideas, list unresolved decisions with defaults, document distribution for new artifact types, and cross-reference deferred items to scope or unresolved decisions."
@@ -83,7 +84,7 @@ export const DESIGN = {
             { id: "design_test_and_perf_defined", description: "Test strategy and performance budget are defined." }
         ],
         requiredEvidence: [
-            "Research Fleet Synthesis is filled in `03-design.md`; for deep/high-risk work, `.cclaw/artifacts/02a-research.md` is also written with stack/features/architecture/pitfalls sections plus synthesis.",
+            "Research Fleet Synthesis is filled in `.cclaw/artifacts/03-design-<slug>.md`; for deep/high-risk work, `.cclaw/artifacts/02a-research.md` is also written with stack/features/architecture/pitfalls sections plus synthesis.",
             "Artifact written to `.cclaw/artifacts/03-design-<slug>.md`.",
             "Failure-mode table exists in Method/Exception/Rescue/UserSees format.",
             "Tier-required diagram markers are present: architecture (all tiers). Standard/Deep add-ons (shadow/error) and Deep add-ons (state-machine/rollback/deployment-sequence) are included only when risk warrants them.",
@@ -93,7 +94,10 @@ export const DESIGN = {
             "Outside-voice findings and dispositions are recorded (accept/reject/defer).",
             `Spec review loop summary includes iteration count and quality score trajectory per ${reviewLoopPolicySummary("design")}`,
             reviewLoopSecondOpinionSummary("design"),
-            "Adversarial lock table includes chosen path, shadow alternative, switch trigger, failure/rescue/degraded behavior, and verification evidence.",
+            "Adversarial lock table includes chosen path, shadow alternative, switch trigger, failure/rescue/degraded behavior, and verification evidence, with reference-grade contracts for mirrored patterns when applicable.",
+            "Architecture Decision Record (ADR) section captures context, decision, alternatives, consequences, and reversal trigger for major choices.",
+            "Pre-mortem section lists top failure scenarios, early signals, mitigations, and owner before implementation begins.",
+            "Test-Diagram Mapping links critical flows to both validating tests and diagram anchors.",
             "Test strategy includes unit/integration/e2e expectations.",
             "When a high-upside idea is deferred, a seed file is created under `.cclaw/seeds/` and referenced in the artifact.",
             "NOT-in-scope section produced.",
@@ -147,6 +151,7 @@ export const DESIGN = {
             { section: "Research Fleet Synthesis", required: true, validationRule: "Must summarize the tiered lenses actually run and map findings to concrete design decisions. Default may be compact inline synthesis; full separate research pack is Deep/high-risk only." },
             { section: "Codebase Investigation", required: false, validationRule: "Investigator pass: list blast-radius files with current responsibilities, discovered patterns, reuse candidates, and existing system fit." },
             { section: "Engineering Lock", required: true, validationRule: "Canonical lock: chosen path, shadow alternative, switch trigger, failure/rescue/degraded behavior, verification evidence, critical path, rollout/rollback, and confidence." },
+            { section: "Architecture Decision Record (ADR)", required: false, validationRule: "Recommended: rows for context, decision, alternatives, consequences, and reversal trigger for each major architecture choice." },
             { section: "Search Before Building", required: false, validationRule: "For each technical choice: Layer 1 (exact match), Layer 2 (partial match), Layer 3 (inspiration), EUREKA labels with reuse-first default." },
             { section: "Architecture Boundaries", required: true, validationRule: "Must list component boundaries with ownership." },
             { section: "Architecture Diagram", required: true, validationRule: "Must include `<!-- diagram: architecture -->` marker. Diagram must label concrete nodes, label arrows, mark direction, distinguish sync/async edges, and include at least one failure/degraded edge." },
@@ -155,12 +160,16 @@ export const DESIGN = {
             { section: "Data Flow", required: false, validationRule: "Must include data/state flow, happy path, nil input, empty input, upstream error paths, plus Interaction Edge Case matrix rows for double-click, nav-away-mid-request, 10K-result dataset, background-job abandonment, zombie connection. Each row declares handled yes/no and deferred item when not handled." },
             { section: "Stale Diagram Audit", required: false, validationRule: "When `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is true: blast-radius files from Codebase Investigation must not be newer than the current design diagram-marker baseline unless explicitly refreshed." },
             { section: "Failure Mode Table", required: true, validationRule: "Use Method/Exception/Rescue/UserSees columns and treat silent user impact without rescue as critical." },
+            { section: "Pre-mortem", required: false, validationRule: "Recommended: list top failure scenarios, early warning signal, mitigation owner, and containment action before implementation." },
             { section: "Security & Threat Model", required: true, validationRule: "Must list trust boundaries, abuse/failure scenarios, mitigations, and residual risks." },
             { section: "Test Strategy", required: false, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
+            { section: "Test-Diagram Mapping", required: false, validationRule: "Recommended: map each critical flow to at least one validating test ID and one diagram marker/anchor." },
+            { section: "Test Strategy", required: false, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
             { section: "Performance Budget", required: false, validationRule: "For each critical path: metric name, target threshold, and measurement method." },
             { section: "Observability & Debuggability", required: true, validationRule: "Must define logs/metrics/traces plus alerting/debug path for critical failure modes." },
             { section: "Deployment & Rollout", required: true, validationRule: "Must define migration/flag strategy, rollout/rollback plan, switch trigger, and post-deploy verification steps." },
             { section: "What Already Exists", required: false, validationRule: "For each sub-problem: existing code/library found (Layer 1-3/EUREKA label), reuse decision, and adaptation needed." },
+            { section: "Reference-Grade Contracts", required: false, validationRule: "For every mirrored pattern: source, reusable invariant, local adaptation, rejection boundary, and verification signal. Omit with `None - no external or in-repo pattern mirrored` for compact local changes." },
             { section: "Rejected Alternatives", required: false, validationRule: "List alternatives considered, why rejected, and what signal would revive them." },
             { section: "Design Decisions", required: false, validationRule: "Stable design decisions with requirement/locked-decision refs and downstream spec impact." },
             { section: "Spec Handoff", required: true, validationRule: "Exact requirements, design decisions, risks, test/perf expectations, and unresolved questions that spec must carry forward." },

package/dist/content/stages/review.js

@@ -45,8 +45,9 @@ export const REVIEW = {
             "Structured Review reconciliation — normalize findings into `07-review-army.json`, dedup by fingerprint, and mark multi-specialist confirmations when multiple lenses agree.",
             "Meta-Review — Were tests/diagnostics actually run? Do test names match what they test? Are there real assertions? Is the dependency/version surface unchanged or audited?",
             "Classify findings — Critical (blocks ship), Important (should fix), Suggestion (optional improvement).",
+            "Victory Detector — before verdict, confirm Layer 1, Layer 2, security sweep, structured findings, trace evidence, and unresolved-critical status are complete; otherwise iterate findings or route back to TDD.",
             "Produce verdict — APPROVED, APPROVED_WITH_CONCERNS, or BLOCKED.",
-            "If verdict is BLOCKED, emit remediation route token `ROUTE_BACK_TO_TDD`, include `cclaw internal rewind tdd \"review_blocked_by_critical\"` with the blocking finding IDs, and satisfy the special transition guard `review_verdict_blocked` instead of `review_criticals_resolved`."
+            "If verdict is BLOCKED, emit remediation route token `ROUTE_BACK_TO_TDD`, include the managed command `cclaw internal rewind tdd \"review_blocked_by_critical <finding-ids>\"`, and satisfy the special transition guard `review_verdict_blocked` instead of `review_criticals_resolved`. After TDD rework, clear the stale marker with `cclaw internal rewind --ack tdd` before `/cc-next`."
         ],
         interactionProtocol: [
             "Run Layer 1 (spec compliance) completely before starting Layer 2.",
@@ -54,7 +55,7 @@ export const REVIEW = {
             "Classify every finding as Critical, Important, or Suggestion.",
             decisionProtocolInstruction("each Critical finding", "present resolution options (A/B/C) with trade-offs, and mark one as (recommended)", "recommend the option that fully closes the finding with no carry-over risk and the smallest blast radius", STRUCTURED_ASK_TOOL_LIST_REVIEW),
             "Resolve all critical blockers before ship. If verdict is BLOCKED, do not pass `review_criticals_resolved`; pass only the remediation route gate `review_verdict_blocked` when routing back to TDD.",
-            "When verdict is BLOCKED, do not end with a passive stop: explicitly route remediation to TDD via `ROUTE_BACK_TO_TDD` and point to `cclaw internal rewind tdd` with the blocking IDs.",
+            "When verdict is BLOCKED, do not end with a passive stop: explicitly route remediation to TDD via `ROUTE_BACK_TO_TDD`, point to `cclaw internal rewind tdd` with the blocking IDs, and tell the operator to ack the stale TDD marker only after rework is complete.",
             structuredAskSingleChoiceInstruction("final verdict", "verdict (APPROVED / APPROVED_WITH_CONCERNS / BLOCKED)"),
             "**STOP.** Do NOT proceed to ship until the user provides an explicit verdict."
         ],
@@ -65,7 +66,7 @@ export const REVIEW = {
             "Reconcile structured findings into `.cclaw/artifacts/07-review-army.json` (dedup + confidence + conflict notes + source tags from spec/correctness/security/performance/architecture/external-safety passes).",
             "Classify and prioritize all findings.",
             "Write review report artifact with explicit verdict.",
-            "If verdict is BLOCKED, include the remediation route token `ROUTE_BACK_TO_TDD` and the rewind command payload."
+            "If verdict is BLOCKED, include the remediation route token `ROUTE_BACK_TO_TDD`, the managed rewind command payload, and the follow-up ack command after TDD rework."
         ],
         requiredGates: [
             { id: "review_layer1_spec_compliance", description: "Spec compliance check completed with per-criterion verdict." },
@@ -86,9 +87,10 @@ export const REVIEW = {
             "No-finding attestation is explicit when no issues are found.",
             "Dependency/version audit is recorded when manifests, lockfiles, generated clients, CI, runtime config, or external APIs are relevant.",
             "Severity log includes critical/important/suggestion buckets.",
+            "Victory Detector recorded: Layer 1, Layer 2, security sweep, structured findings, trace evidence, and unresolved-critical status are complete, or BLOCKED route is explicit.",
             "Explicit final verdict: APPROVED, APPROVED_WITH_CONCERNS, or BLOCKED.",
             "Fresh verification command discovery recorded, and the command cited in `review_trace_matrix_clean` evidence before ship handoff.",
-            "If BLOCKED: include explicit remediation route (`ROUTE_BACK_TO_TDD`) with blocking finding IDs."
+            "If BLOCKED: include explicit remediation route (`ROUTE_BACK_TO_TDD`) with blocking finding IDs, managed rewind command, and post-rework ack instruction."
         ],
         inputs: ["implementation diff", "upstream artifacts", "test/build evidence"],
         requiredContext: ["spec criteria", "tdd artifact", "rulebook constraints"],
@@ -126,7 +128,7 @@ export const REVIEW = {
             { section: "Security Sweep Attestation", required: false, validationRule: "Dedicated security-reviewer result: findings or `NO_CHANGE_ATTESTATION` / `NO_SECURITY_IMPACT` with inspected surfaces and rationale." },
             { section: "Dependency & Version Audit", required: false, validationRule: "Required when manifests, lockfiles, generated clients, CI, runtime config, or external APIs changed; otherwise record no-impact rationale." },
             { section: "Review Findings Contract", required: true, validationRule: "Structured findings in 07-review-army.json include id/severity/confidence/fingerprint/reportedBy/status and source tags from {spec, correctness, security, performance, architecture, external-safety} with dedup reconciliation summary." },
-            { section: "Review Readiness Snapshot", required: false, validationRule: "Optional compact summary: completed checks, delegation-log status, staleness signal, open critical blockers, and ship recommendation." },
+            { section: "Review Readiness Snapshot", required: false, validationRule: "Optional compact summary: completed checks, delegation-log status, staleness signal, open critical blockers, ship recommendation, and Victory Detector pass/fail." },
             { section: "Completeness Snapshot", required: false, validationRule: "Optional compact coverage summary for AC coverage, source item coverage, test-slice coverage, and adversarial-review status when triggered." },
             { section: "Incoming Feedback Queue", required: false, validationRule: "When external review feedback exists, include a queue summary with per-item disposition (resolved / accepted-risk / rejected-with-evidence) and evidence refs." },
             { section: "Trace Matrix Check", required: false, validationRule: "Records source-item/test orphan counts (all zero on enforced tracks) with command output reference." },

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

@@ -20,8 +20,11 @@ export interface ArtifactValidation {
     tier?: "required" | "recommended";
     validationRule: string;
 }
+export type StageSubagentName = "researcher" | "architect" | "spec-validator" | "slice-implementer" | "performance-reviewer" | "compatibility-reviewer" | "observability-reviewer" | "release-reviewer" | "planner" | "product-manager" | "critic" | "reviewer" | "security-reviewer" | "test-author" | "doc-updater" | "implementer" | "fixer";
+export type StageSubagentDispatchClass = "stage-specialist" | "worker" | "review-lens";
+export type StageSubagentReturnSchema = "planning-return" | "product-return" | "critic-return" | "review-return" | "security-return" | "tdd-return" | "docs-return" | "worker-return" | "fixer-return" | "research-return" | "architecture-return" | "spec-validation-return" | "performance-return" | "compatibility-return" | "observability-return" | "release-return";
 export interface StageAutoSubagentDispatch {
-    agent: "planner" | "product-manager" | "critic" | "reviewer" | "security-reviewer" | "test-author" | "doc-updater";
+    agent: StageSubagentName;
     /**
      * - `mandatory` — must be dispatched (or explicitly waived) before stage transition.
      * - `proactive` — should be dispatched automatically when context matches `when`.
@@ -29,12 +32,16 @@ export interface StageAutoSubagentDispatch {
     mode: "mandatory" | "proactive";
     /**
      * Minimum complexity tier where this dispatch policy applies.
-     * Defaults to `standard` for mandatory dispatches when omitted.
+     * Defaults to `standard` for mandatory/proactive dispatches when omitted.
      */
     requiredAtTier?: StageComplexityTier;
     when: string;
     purpose: string;
     requiresUserGate: boolean;
+    /** Role category used by generated routing tables and lifecycle checks. */
+    dispatchClass?: StageSubagentDispatchClass;
+    /** Strict status/evidence contract the dispatched agent must return. */
+    returnSchema?: StageSubagentReturnSchema;
     /** Optional skill folder the dispatched agent should load as additional context. */
     skill?: string;
 }

package/dist/content/stages/scope.js

@@ -49,7 +49,8 @@ export const SCOPE = {
             "**Premise and leverage check** — answer in the artifact: *Right problem? Direct path? What if nothing? Where can we leverage existing code? What is the reversibility cost?* Take a position; do not hedge.",
             "**Conditional 10-star boundary** — for deep/high-risk/product-strategy work, show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded without vague `later/for now` placeholders. Skip this for straightforward repair work and record `not needed: compact scope`.",
             "**Pick one operational mode with the user** — HOLD SCOPE preserves focus; SELECTIVE EXPANSION cherry-picks high-leverage reference ideas; SCOPE EXPANSION explores ambitious alternatives; SCOPE REDUCTION cuts to the essential wedge. Recommend one, state why and what signal would change it, then STOP for approval.",
-            "**Run mode-specific analysis only to needed depth** — lite keeps the selected-mode row compact; standard adds requirements/locked decisions/discretion; deep may add Landscape Check, Taste Calibration, Reference Pull, Ambitious Alternatives, and Ruthless Minimum Slice evidence when mode/risk warrants it.",
+            "**Run mode-specific analysis only to needed depth** — lite keeps the selected-mode row compact; standard adds requirements/locked decisions/discretion; deep may add Landscape Check, Taste Calibration, Reference Pattern Registry, Reference Pull, Ambitious Alternatives, and Ruthless Minimum Slice evidence when mode/risk warrants it.",
+            "**Decision-driver contract** — list weighted decision drivers (value, risk, reversibility, effort, timeline) and score candidate scope moves so the selected mode and boundaries are evidence-backed, not preference-led.",
             "**Compare implementation alternatives** — include minimum viable, product-grade, and ideal architecture options with effort (S/M/L/XL), risk (Low/Med/High), pros, cons, and reuses. Recommend one and tie it to mode.",
             "**Run outside voice before final approval** — for simple/low-risk scope, record one concise adversarial self-check row; for complex/high-risk/configured scope, iterate until threshold. Record the loop summary in `## Scope Outside Voice Loop`, but do not treat it as user approval.",
             "**Ask only one decision-changing question** — if the user rejects the contract but is unsure, offer 3-4 concrete scope moves instead of open-ended interrogation.",
@@ -87,7 +88,9 @@ export const SCOPE = {
             "In-scope and out-of-scope lists are explicit.",
             "Discretion areas are explicit (or marked as `None`).",
             "Selected mode and rationale are documented using HOLD SCOPE, SELECTIVE EXPANSION, SCOPE EXPANSION, or SCOPE REDUCTION.",
-            "Scope Contract captures requirements, locked decisions, discretion areas, accepted/rejected reference ideas, success definition, and design handoff.",
+            "Scope Contract captures requirements, locked decisions, discretion areas, accepted/rejected/deferred reference ideas from the Reference Pattern Registry, success definition, and design handoff.",
+            "Decision Drivers section records weighted criteria and per-option scores used to choose mode and boundary moves.",
+            "Scope Completeness Score is recorded (0.00-1.00) with the explicit blocker list for any remaining uncertainty.",
             "Locked Decisions section lists stable LD#hash anchors for non-negotiable boundaries.",
             "Premise challenge findings documented.",
             "Outside Voice findings and dispositions are recorded (accept/reject/defer with rationale) before final approval.",
@@ -142,8 +145,11 @@ export const SCOPE = {
             { section: "Prime Directives", required: false, 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: false, validationRule: "Must list at least 3 question/answer rows in a markdown table or bullet list (gstack default trio: right problem? direct path? what if we do nothing? — extend with leverage and reversibility for richer scope). The linter enforces structure, not English wording — answers may be in any language." },
             { section: "Scope Contract", required: true, validationRule: "Canonical contract: selected mode, in scope, out of scope, requirements, locked decisions, discretion areas, deferred ideas, accepted/rejected reference ideas, success definition, and design handoff." },
+            { section: "Decision Drivers", required: false, validationRule: "Recommended: weighted decision drivers (value, risk, reversibility, effort, timeline) with scored options and the selected boundary rationale." },
+            { section: "Scope Completeness Score", required: false, validationRule: "Recommended: score 0.00-1.00 plus unresolved blockers and the escalation trigger when confidence is low." },
             { section: "Landscape Check", required: false, validationRule: "Optional evidence heading for EXPAND/SELECTIVE/deep modes: include reference insight and impact on scope, or omit for compact HOLD SCOPE." },
             { section: "Taste Calibration", required: false, validationRule: "Optional evidence heading: reference 2-3 strong in-repo modules/files that define the quality bar or justify omission." },
+            { section: "Reference Pattern Registry", required: false, validationRule: "Recommended for SELECTIVE/EXPAND/deep scope: table of pattern/source, accepted/rejected/deferred disposition, invariant to preserve, and boundary impact. Compact HOLD SCOPE may state `Not needed - compact scope`." },
             { section: "Reference Pull", required: false, validationRule: "Optional evidence heading: cite ideas pulled from `/Users/zuevrs/Downloads/references` or state no reference pull was needed for compact HOLD SCOPE." },
             { section: "Ambitious Alternatives", required: false, validationRule: "Optional evidence heading for SCOPE EXPANSION/SELECTIVE: list larger alternatives considered and their disposition." },
             { section: "Ruthless Minimum Slice", required: false, validationRule: "Optional evidence heading for SCOPE REDUCTION or high-risk scope: define the smallest useful wedge and what it proves." },