cclaw-cli 0.51.23 → 0.51.25

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)
         };
     });
@@ -242,27 +303,29 @@ const REQUIRED_GATE_IDS = {
 const REQUIRED_ARTIFACT_SECTIONS = {
     brainstorm: [
         "Context",
-        "Problem",
+        "Problem Decision Record",
         "Approach Tier",
         "Approaches",
         "Approach Reaction",
         "Selected Direction"
     ],
-    scope: ["Scope Mode", "In Scope / Out of Scope", "Completion Dashboard", "Scope Summary"],
+    scope: ["Scope Contract", "Scope Mode", "In Scope / Out of Scope", "Completion Dashboard", "Scope Summary"],
     design: [
         "Research Fleet Synthesis",
+        "Engineering Lock",
         "Architecture Boundaries",
         "Architecture Diagram",
         "Failure Mode Table",
         "Security & Threat Model",
         "Observability & Debuggability",
         "Deployment & Rollout",
+        "Spec Handoff",
         "Completion Dashboard"
     ],
     spec: ["Acceptance Criteria", "Edge Cases", "Assumptions Before Finalization", "Acceptance Mapping", "Approval"],
     plan: ["Task List", "Dependency Batches", "Acceptance Mapping", "Execution Posture", "WAIT_FOR_CONFIRM"],
     tdd: ["Test Discovery", "System-Wide Impact Check", "RED Evidence", "GREEN Evidence", "REFACTOR Notes", "Traceability", "Verification Ladder"],
-    review: ["Layer 1 Verdict", "Review Findings Contract", "Severity Summary", "Final Verdict"],
+    review: ["Review Evidence Scope", "Changed-File Coverage", "Layer 1 Verdict", "Review Findings Contract", "Severity Summary", "Final Verdict"],
     ship: ["Preflight Results", "Release Notes", "Rollback Plan", "Finalization"]
 };
 function resolveRequiredGateIds(stage, track) {
@@ -358,10 +421,26 @@ const STAGE_SCHEMA_MAP = {
 const STAGE_AUTO_SUBAGENT_DISPATCH = {
     brainstorm: [
         {
-            agent: "planner",
+            agent: "product-manager",
+            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: "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: "researcher",
             mode: "proactive",
-            when: "When request is ambiguous, multi-surface, or spans multiple modules.",
-            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
         }
     ],
@@ -373,38 +452,99 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "Always during scope shaping.",
             purpose: "Challenge premise, map alternatives, and produce explicit in/out contract.",
             requiresUserGate: false
+        },
+        {
+            agent: "critic",
+            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",
+            when: "When scope choices change user value, success metrics, or product positioning.",
+            purpose: "Keep accepted/deferred reference ideas tied to user value and measurable success.",
+            requiresUserGate: false
         }
     ],
     design: [
         {
-            agent: "planner",
+            agent: "architect",
             mode: "mandatory",
             requiredAtTier: "standard",
             when: "Always during design lock.",
-            purpose: "Stress architecture boundaries and dependency graph.",
+            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",
+            when: "When architecture alternatives, coupling, cost, or rollback risk remain debatable.",
+            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",
-            when: "When trust boundaries, auth, secrets, or external inputs are involved.",
+            when: "When trust boundaries, auth, secrets, sensitive data, or external inputs are involved.",
             purpose: "Catch design-level security risks before implementation.",
             requiresUserGate: false
+        },
+        {
+            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",
+            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
         }
     ],
@@ -414,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
         }
     ],
@@ -424,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",
@@ -442,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"
         },
@@ -450,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",
@@ -467,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"
         },
@@ -482,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
         },
@@ -617,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

@@ -7,11 +7,11 @@ export const BRAINSTORM = {
     complexityTier: "standard",
     skillFolder: "brainstorming",
     skillName: "brainstorming",
-    skillDescription: "Design-first stage. Explore context, understand intent through collaborative dialogue, propose distinct approaches, and lock an approved direction before scope/design work.",
+    skillDescription: "Problem-discovery stage. Build a concise Problem Decision Record, choose lite/standard/deep depth, compare distinct directions, and hand approved decisions to scope.",
     philosophy: {
         hardGate: "Do NOT invoke implementation skills, write code, scaffold projects, or mutate product behavior until a concrete direction is approved by the user.",
         ironLaw: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY APPROVED DIRECTION — SILENCE IS NOT APPROVAL.",
-        purpose: "Turn an initial idea into an approved design direction through natural collaborative dialogue — understanding the problem before proposing solutions.",
+        purpose: "Turn an initial idea into an approved problem frame and direction, using product or technical-maintenance discovery before proposing solutions.",
         whenToUse: [
             "Starting a new feature or behavior change",
             "Requirements are ambiguous or trade-offs are unclear",
@@ -37,22 +37,25 @@ export const BRAINSTORM = {
     executionModel: {
         checklist: [
             "**Explore project context** — inspect existing files/docs/recent activity before asking what to build; capture matching files/patterns/seeds in `Context > Discovered context` so downstream stages don't redo discovery.",
-            "**Classify depth and scope** — pick Lightweight / Standard / Deep; decompose independent subsystems before deeper work.",
+            "**Classify stage depth** — choose `lite` for clear low-risk tasks, `standard` for normal product/engineering changes, or `deep` for ambiguity, architecture, external dependency, security/data risk, or explicit think-bigger requests.",
+            "**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, the desired outcome, and the constraint. This is the altitude check before approaches.",
-            "**Sharpening questions (3-5)** — capture decision-changing question/answer pairs in the `Sharpening Questions` table with the actual decision impact; only non-critical preference/default assumptions may continue. STOP and ask on scope, architecture, security, data loss, public API, migration, auth/pricing, or user-approval uncertainty.",
+            "**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.",
-            "**Short-circuit concrete asks** — for unambiguous implementation-only requests, write a compact brainstorm stub (context, problem, approved intent, constraints, assumptions) and ask for one explicit approval.",
+            "**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.",
             "**Request explicit approval** — state exactly what direction is being approved; do not advance without approval and artifact review.",
-            "**Handoff** — only after approval, complete the stage and point to `/cc-next`."
+            "**Handoff** — only after approval, hand scope: upstream decisions used, explicit drift, confidence level, unresolved questions, next-stage risk hints, and non-goals."
         ],
         interactionProtocol: [
             "Start from observed project context; if the idea is vague, first narrow the project type with **one** structured question, then keep going.",
+            "Select depth explicitly: `lite`, `standard`, or `deep`; keep lite concise, but escalate when risk/ambiguity changes decisions.",
             "Lead with the premise check (right problem / direct path / what if nothing) and the `How Might We` reframing before approaches; both go in the artifact, not just the chat.",
             "Ask at most one question per turn, only when decision-changing; if using a structured question tool, send exactly one question object, not a multi-question form.",
             "Only non-critical preference/default assumptions may continue inline. STOP and ask when uncertainty affects scope, architecture, security, data loss, public API, migration, auth/pricing, or user approval.",
@@ -78,14 +81,17 @@ export const BRAINSTORM = {
         requiredEvidence: [
             "Artifact written to `.cclaw/artifacts/01-brainstorm-<slug>.md`.",
             "Project context was explored (files, docs, or recent activity referenced).",
-            "Clarifying questions and their answers are captured.",
-            "2-3 approaches with trade-offs are recorded, including one higher-upside challenger option.",
+            "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 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.",
             "When a promising option is parked, a seed file is created under `.cclaw/seeds/` and referenced in the artifact.",
             "Approved direction and approval marker are present.",
-            "Assumptions and open questions are captured (or explicitly marked as none)."
+            "Assumptions and open questions are captured (or explicitly marked as none).",
+            "Scope handoff includes upstream decisions used, explicit drift, confidence, unresolved questions, next-stage risk hints, and non-goals."
         ],
         inputs: ["problem statement", "constraints", "success criteria"],
         requiredContext: [
@@ -124,16 +130,18 @@ export const BRAINSTORM = {
         },
         artifactValidation: [
             { section: "Context", required: true, validationRule: "Must reference project state and relevant existing code or patterns. A `Discovered context` subsection (or list) is recommended for downstream traceability." },
-            { section: "Problem", required: true, validationRule: "Must define what we're solving, success criteria, and constraints." },
+            { 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: "Sharpening Questions", required: false, validationRule: "Recommended: 3-5 question/answer pairs with explicit `Decision impact` so downstream stages see what each answer changed." },
+            { 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 Lightweight/Standard/Deep and explain why." },
+            { 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, an explicit approval marker, rationale traceable to the prior Approach Reaction, and a track-aware next-stage handoff." },
+            { 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." },
             { section: "Design", required: false, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
             { section: "Visual Companion", required: false, validationRule: "If architecture/data-flow complexity is medium+, include compact ASCII/Mermaid diagram or explicitly justify omission." },
@@ -142,7 +150,7 @@ export const BRAINSTORM = {
         ],
         trivialOverrideSections: [
             "Context",
-            "Problem",
+            "Problem Decision Record",
             "Approach Tier",
             "Short-Circuit Decision",
             "Selected Direction"
@@ -150,7 +158,8 @@ export const BRAINSTORM = {
     },
     reviewLens: {
         outputs: [
-            "approved design direction",
+            "Problem Decision Record",
+            "approved direction",
             "alternatives with trade-offs",
             "brainstorm artifact"
         ],