cclaw-cli 0.51.23 → 0.51.24

package/dist/content/core-agents.d.ts

@@ -23,7 +23,7 @@ export interface AgentDefinition {
     body: string;
 }
 /**
- * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ * Canonical specialist roster materialized under `.cclaw/agents/`.
  *
  * Declared with `satisfies` so the array retains literal `name` types for
  * downstream type-level consumers (e.g. `AgentName`), while still being
@@ -39,6 +39,22 @@ export declare const CCLAW_AGENTS: readonly [{
     readonly activation: "mandatory";
     readonly relatedStages: ["brainstorm", "scope", "design", "spec", "plan"];
     readonly body: string;
+}, {
+    readonly name: "product-manager";
+    readonly description: "PROACTIVE during brainstorm/scope when product value, persona/JTBD, success metric, or why-now framing is unclear. Use for product discovery, not implementation.";
+    readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
+    readonly model: "balanced";
+    readonly activation: "proactive";
+    readonly relatedStages: ["brainstorm", "scope"];
+    readonly body: string;
+}, {
+    readonly name: "critic";
+    readonly description: "PROACTIVE during brainstorm/scope/design when premises, alternatives, cost, rollback, or hidden assumptions need adversarial pressure.";
+    readonly tools: ["Read", "Grep", "Glob", "WebSearch"];
+    readonly model: "balanced";
+    readonly activation: "proactive";
+    readonly relatedStages: ["brainstorm", "scope", "design"];
+    readonly body: string;
 }, {
     readonly name: "reviewer";
     readonly description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.";
@@ -87,7 +103,7 @@ export declare function agentMarkdown(agent: AgentDefinition): string;
  */
 export declare function agentRoutingTable(): string;
 /**
- * Cost tier routing for the core-5 agent roster.
+ * Cost tier routing for the specialist agent roster.
  */
 export declare function agentCostTierTable(): string;
 /**

package/dist/content/core-agents.js

@@ -39,7 +39,7 @@ function activationModeSummary() {
     };
 }
 /**
- * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
+ * Canonical specialist roster materialized under `.cclaw/agents/`.
  *
  * Declared with `satisfies` so the array retains literal `name` types for
  * downstream type-level consumers (e.g. `AgentName`), while still being
@@ -59,14 +59,56 @@ export const CCLAW_AGENTS = [
             "You are an **implementation planning specialist** (staff engineer mindset).",
             "",
             "When invoked:",
-            "1. Analyze scope and break it into concrete sub-problems.",
-            "2. Map each sub-problem to existing modules and reusable code.",
-            "3. Produce an ordered execution plan with dependencies and checks.",
-            "4. Highlight risks and unknowns that need user decisions.",
+            "1. Map upstream decisions, scope boundaries, and explicit drift before planning.",
+            "2. Break the work into concrete sub-problems with dependencies and existing-module fit.",
+            "3. Enforce one-question discipline: ask only decision-changing questions, one at a time.",
+            "4. Produce an ordered execution plan with verification checks and handoff quality notes.",
+            "5. Highlight risks and unknowns that need user decisions.",
             "",
             "**Role boundary:** planning only. Do NOT write production code."
         ].join("\n")
     },
+    {
+        name: "product-manager",
+        description: "PROACTIVE during brainstorm/scope when product value, persona/JTBD, success metric, or why-now framing is unclear. Use for product discovery, not implementation.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["brainstorm", "scope"],
+        body: [
+            "You are a **product discovery specialist**.",
+            "",
+            "Produce concise evidence for:",
+            "- persona / user and job to be done",
+            "- pain or trigger",
+            "- value hypothesis and success metric",
+            "- evidence or signal strength",
+            "- why now, do-nothing consequence, and non-goals",
+            "",
+            "For technical-maintenance work, translate this to operator/developer, failure mode, operational improvement, verification signal, do-nothing cost, and non-goals.",
+            "",
+            "**Role boundary:** frame value and problem fit. Do NOT choose implementation architecture."
+        ].join("\n")
+    },
+    {
+        name: "critic",
+        description: "PROACTIVE during brainstorm/scope/design when premises, alternatives, cost, rollback, or hidden assumptions need adversarial pressure.",
+        tools: ["Read", "Grep", "Glob", "WebSearch"],
+        model: "balanced",
+        activation: "proactive",
+        relatedStages: ["brainstorm", "scope", "design"],
+        body: [
+            "You are an **adversarial critic** for product and engineering decisions.",
+            "",
+            "Your job:",
+            "1. Attack the premise and name what could make the current direction wrong.",
+            "2. Identify cheaper, smaller, or more reversible alternatives.",
+            "3. Surface hidden assumptions, do-nothing viability, and scope creep.",
+            "4. In design, require a shadow alternative, switch trigger, failure/rescue path, and verification evidence.",
+            "",
+            "Return confirmed risks, disproven concerns, and the smallest decision-changing recommendation."
+        ].join("\n")
+    },
     {
         name: "reviewer",
         description: "MANDATORY during review. MUST BE USED to run a two-pass audit: spec compliance first, then correctness/maintainability/performance/architecture.",
@@ -91,9 +133,11 @@ export const CCLAW_AGENTS = [
             "",
             "For each finding include:",
             "- Severity: `Critical` | `Important` | `Suggestion`",
-            "- Location: `file:line`",
+            "- Location: `file:line`; if no line is possible, state the no-line reason",
             "- Problem and concrete recommendation",
             "",
+            "Also report files inspected, changed-file coverage, diagnostics run, dependency/version audit when relevant, and a no-finding attestation when no issues are found.",
+            "",
             "**Trust model:** never rely on implementer claims; verify by reading code."
         ].join("\n")
     },
@@ -118,7 +162,8 @@ export const CCLAW_AGENTS = [
             "- severity aligned to ship risk",
             "- CWE ID when possible (or UNKNOWN)",
             "- short proof-of-concept vector",
-            "- concrete control-oriented fix"
+            "- concrete control-oriented fix",
+            "- `NO_CHANGE_ATTESTATION` or `NO_SECURITY_IMPACT` with inspected surfaces when no security finding exists"
         ].join("\n")
     },
     {
@@ -131,7 +176,7 @@ export const CCLAW_AGENTS = [
         body: [
             "You are a **test-driven development** specialist.",
             "",
-            "**Iron law:** no production code without a failing test first.",
+            "**Iron law:** no production code without a failing test first during RED. In design, focus on testability and verification evidence without editing production code.",
             "",
             "Process:",
             "1. RED: write a failing test for the desired behavior.",
@@ -154,7 +199,8 @@ export const CCLAW_AGENTS = [
             "After code changes, verify and update only stale sections in:",
             "- README / setup / usage",
             "- API docs and examples",
-            "- migration and operational notes",
+            "- migration, rollout, rollback, and operational notes",
+            "- public-surface change notes tied to actual changed files",
             "",
             "Preserve existing tone and structure; avoid rewrites for style alone."
         ].join("\n")
@@ -221,13 +267,13 @@ export function agentRoutingTable() {
 `;
 }
 /**
- * Cost tier routing for the core-5 agent roster.
+ * Cost tier routing for the specialist agent roster.
  */
 export function agentCostTierTable() {
     return `| Tier | Use for | Example agents |
 |---|---|---|
 | \`deep\` | one heavy planning pass per stage | planner |
-| \`balanced\` | review and TDD specialists with stronger reasoning depth | reviewer, security-reviewer, test-author |
+| \`balanced\` | discovery, criticism, review, and TDD specialists with stronger reasoning depth | product-manager, critic, reviewer, security-reviewer, test-author |
 | \`fast\` | bounded maintenance updates with limited blast radius | doc-updater |
 `;
 }
@@ -237,7 +283,7 @@ export function agentCostTierTable() {
 export function agentsAgentsMdBlock() {
     return `### Agent Specialists
 
-cclaw materializes **5 core specialist agents** under \`.cclaw/agents/\`.
+cclaw materializes specialist agents under \`.cclaw/agents/\`, including planner, product-manager, critic, reviewer, security-reviewer, test-author, and doc-updater.
 
 ${agentRoutingTable()}
 
@@ -257,7 +303,7 @@ ${(() => {
         const mode = activationModeSummary();
         return `- **Mandatory:** ${mode.mandatory}.
 - **Proactive:** ${mode.proactive}.
-- **On-demand:** none in the core-5 roster; research playbooks are in-thread procedures.`;
+- **On-demand:** none in the specialist roster; research playbooks are in-thread procedures.`;
     })()}
 
 ### Cost-aware routing

package/dist/content/examples.js

@@ -4,11 +4,19 @@ const STAGE_EXAMPLES = {
 - **Project state:** Monorepo with CI pipeline using custom release scripts. Release checks are scattered across shell scripts with no shared validation logic.
 - **Relevant existing code/patterns:** \`scripts/pre-publish.sh\` does metadata checks. \`src/release/\` has partial validation helpers.
 
-## Problem
+## Problem Decision Record
 
-- **What we're solving:** release checks are fragile and inconsistent between CI and local runs. Invalid metadata sometimes reaches npm publish.
-- **Success criteria:** invalid release preconditions are caught before publish with explicit operator feedback, in both CI and local workflows.
-- **Constraints:** no new runtime dependencies; must work within existing CI pipeline structure.
+- **Depth:** standard
+- **Frame type:** technical-maintenance
+
+### Technical-maintenance framing
+
+- **Affected operator/developer:** release operator and package maintainer.
+- **Current failure mode:** release checks are fragile and inconsistent between CI and local runs; invalid metadata sometimes reaches npm publish.
+- **Expected operational improvement:** invalid release preconditions are caught before publish with explicit operator feedback in CI and local workflows.
+- **Verification signal:** shared release validation tests and CI release-check command fail on invalid metadata.
+- **Do-nothing cost:** continued publish risk and duplicated local/CI fixes.
+- **Non-goals:** no new runtime dependencies; no release-framework rewrite.
 
 ## Clarifying Questions
 
@@ -667,7 +675,7 @@ function exampleSummaryBullets(stage) {
 // sample in STAGE_EXAMPLES gains or loses a top-level section.
 const STAGE_EXAMPLE_SECTION_HEADINGS = {
     brainstorm: [
-        "Problem framing (problem, success, constraints)",
+        "Problem Decision Record (product or technical-maintenance framing)",
         "Candidate approaches with trade-offs",
         "Recommended direction + open questions",
         "Clarification log and decision record"

package/dist/content/seed-shelf.js

@@ -4,6 +4,8 @@ import { parse } from "yaml";
 import { RUNTIME_ROOT } from "../constants.js";
 const SEED_FILE_NAME_PATTERN = /^SEED-(\d{4}-\d{2}-\d{2})-([a-z0-9]+(?:-[a-z0-9]+)*)(?:-(\d+))?\.md$/u;
 const DEFAULT_MAX_MATCHES = 3;
+const MAX_SEED_MATCHES = 10;
+const MIN_TOKEN_OVERLAP = 2;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -189,18 +191,81 @@ export async function readSeedShelf(projectRoot) {
     entries.sort((a, b) => b.fileName.localeCompare(a.fileName));
     return entries;
 }
-export function seedMatchesPrompt(seed, prompt) {
-    const normalizedPrompt = prompt.toLowerCase().trim();
-    if (normalizedPrompt.length === 0)
-        return false;
-    if (seed.triggerWhen.length === 0)
+function normalizeMatchText(value) {
+    return value.toLowerCase().trim().replace(/\s+/gu, " ");
+}
+function tokenizeSeedText(value) {
+    if (!value)
+        return [];
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/u)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3);
+}
+function uniqueTokens(values) {
+    return new Set(values);
+}
+function exactTriggerMatch(seed, normalizedPrompt) {
+    if (normalizedPrompt.length === 0 || seed.triggerWhen.length === 0)
         return false;
-    return seed.triggerWhen.some((trigger) => normalizedPrompt.includes(trigger.toLowerCase()));
+    return seed.triggerWhen.some((trigger) => {
+        const normalizedTrigger = normalizeMatchText(trigger);
+        return normalizedTrigger.length > 0 && normalizedPrompt.includes(normalizedTrigger);
+    });
+}
+function seedContentTokens(seed) {
+    return uniqueTokens([
+        ...tokenizeSeedText(seed.title),
+        ...tokenizeSeedText(seed.summary),
+        ...tokenizeSeedText(seed.hypothesis),
+        ...tokenizeSeedText(seed.action)
+    ]);
+}
+function tokenOverlap(seed, promptTokens) {
+    if (promptTokens.size === 0)
+        return 0;
+    const contentTokens = seedContentTokens(seed);
+    let overlap = 0;
+    for (const token of promptTokens) {
+        if (contentTokens.has(token))
+            overlap += 1;
+    }
+    return overlap;
+}
+export function seedMatchesPrompt(seed, prompt) {
+    const normalizedPrompt = normalizeMatchText(prompt);
+    if (exactTriggerMatch(seed, normalizedPrompt))
+        return true;
+    return tokenOverlap(seed, uniqueTokens(tokenizeSeedText(prompt))) >= MIN_TOKEN_OVERLAP;
 }
 export async function findMatchingSeeds(projectRoot, prompt, maxMatches = DEFAULT_MAX_MATCHES) {
     const seeds = await readSeedShelf(projectRoot);
-    const matches = seeds.filter((seed) => seedMatchesPrompt(seed, prompt));
-    return matches.slice(0, Math.max(1, maxMatches));
+    const normalizedPrompt = normalizeMatchText(prompt);
+    if (normalizedPrompt.length === 0)
+        return [];
+    const promptTokens = uniqueTokens(tokenizeSeedText(prompt));
+    const cappedMax = typeof maxMatches === "number" && Number.isFinite(maxMatches) && maxMatches > 0
+        ? Math.min(MAX_SEED_MATCHES, Math.max(1, Math.floor(maxMatches)))
+        : DEFAULT_MAX_MATCHES;
+    const ranked = seeds
+        .map((seed, index) => {
+        const exact = exactTriggerMatch(seed, normalizedPrompt);
+        const overlap = tokenOverlap(seed, promptTokens);
+        return { seed, index, exact, overlap };
+    })
+        .filter((row) => row.exact || row.overlap >= MIN_TOKEN_OVERLAP);
+    ranked.sort((a, b) => {
+        if (a.exact !== b.exact)
+            return a.exact ? -1 : 1;
+        if (b.overlap !== a.overlap)
+            return b.overlap - a.overlap;
+        const recency = b.seed.createdOn.localeCompare(a.seed.createdOn);
+        if (recency !== 0)
+            return recency;
+        return a.index - b.index;
+    });
+    return ranked.slice(0, cappedMax).map((row) => row.seed);
 }
 export function renderSeedTemplate(input) {
     const triggerWhen = [...input.triggerWhen].map((item) => item.trim()).filter((item) => item.length > 0);

package/dist/content/stage-schema.js

@@ -242,27 +242,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) {
@@ -357,10 +359,24 @@ const STAGE_SCHEMA_MAP = {
 };
 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.",
+            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.",
+            purpose: "Attack assumptions and surface non-goals before direction approval.",
+            requiresUserGate: false
+        },
         {
             agent: "planner",
             mode: "proactive",
-            when: "When request is ambiguous, multi-surface, or spans multiple modules.",
+            when: "When request is ambiguous, multi-surface, or staged feasibility is unclear.",
             purpose: "Map scope and alternatives before direction lock.",
             requiresUserGate: false
         }
@@ -373,6 +389,20 @@ 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: "proactive",
+            when: "When selecting SELECTIVE EXPANSION, SCOPE EXPANSION, or SCOPE REDUCTION, or when boundaries feel soft.",
+            purpose: "Test whether the selected scope mode is too timid, too broad, or hiding a smaller useful slice.",
+            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: [
@@ -381,15 +411,29 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             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: "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: "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: "test-author",
+            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.",
+            requiresUserGate: false
         }
     ],
     spec: [

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,24 @@ 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.",
+            "**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.",
             "**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 +80,16 @@ 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.",
+            "Problem Decision Record includes product framing or technical-maintenance framing.",
+            "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.",
             "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 +128,16 @@ 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: "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: "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 +146,7 @@ export const BRAINSTORM = {
         ],
         trivialOverrideSections: [
             "Context",
-            "Problem",
+            "Problem Decision Record",
             "Approach Tier",
             "Short-Circuit Decision",
             "Selected Direction"
@@ -150,7 +154,8 @@ export const BRAINSTORM = {
     },
     reviewLens: {
         outputs: [
-            "approved design direction",
+            "Problem Decision Record",
+            "approved direction",
             "alternatives with trade-offs",
             "brainstorm artifact"
         ],