cclaw-cli 2.0.0 → 4.0.0

package/dist/content/opencode-plugin.js

@@ -609,10 +609,7 @@ export default function cclawPlugin(ctx) {
         eventType === "session.updated";
       if (isSessionLifecycle) {
         // Keep OpenCode aligned with Claude/Cursor/Codex: session-start is
-        // the canonical rehydrate path that refreshes derived state such as
-        // Ralph Loop, compound readiness, and hook-error breadcrumbs. The
-        // plugin refreshes its local bootstrap cache afterwards so the system
-        // transform sees the side effects from the hook runtime.
+        // the canonical rehydrate path.
         await runHookScript("session-start", eventData ?? {});
         await refreshBootstrapCache(true);
       }
@@ -620,74 +617,6 @@ export default function cclawPlugin(ctx) {
         await runHookScript("stop-handoff", { loop_count: 0 });
       }
     },
-    "tool.execute.before": async (input, output) => {
-      const disabled = isCclawDisabled();
-      if (disabled.disabled) {
-        // Explicit user override (CCLAW_DISABLE=1 et al): stay fully out
-        // of the way. Any real problem with the guard chain should not
-        // prevent the user from unblocking themselves.
-        noteDisabled(disabled);
-        return;
-      }
-      const payload = normalizeToolPayload(input, output);
-      if (isSafeReadOnlyTool(payload)) {
-        // Read-only tools bypass guards — they cannot mutate state and
-        // blocking them gives users an unusable session when guards are
-        // misconfigured or cclaw isn't fully initialized.
-        return;
-      }
-      if (!isCclawInitialized()) {
-        // Project has no flow-state or hook runtime: cclaw isn't in use
-        // here. Never block the user's tools because of setup they didn't
-        // ask for. Surface a single advisory so they can notice.
-        noteNotInitialized();
-        return;
-      }
-      const [promptOk, workflowOk] = await Promise.all([
-        runHookScript("prompt-guard", payload),
-        runHookScript("workflow-guard", payload)
-      ]);
-      if (!promptOk || !workflowOk) {
-        const failed = !promptOk ? "prompt-guard" : "workflow-guard";
-        const rawDetail = lastHookStderr.get(failed) || "";
-        const detail = rawDetail.length > 0 ? rawDetail.slice(-400) : "(no stderr captured)";
-        if (looksLikeInfrastructureFailure(rawDetail)) {
-          // Never let a broken hook runtime or misrouted child-process
-          // stderr (yargs help, Node crash, ENOENT, timeout) masquerade
-          // as a policy block. Log the infra hit and let the user keep
-          // working regardless of strictness.
-          logToFile(
-            "infra: " + failed + " non-zero exit with non-guard stderr — treated as infrastructure failure, tool allowed. " +
-            "stderr=" + detail.replace(/\\s+/g, " ").slice(0, 300)
-          );
-          return;
-        }
-        const strictness = await resolveStrictness();
-        if (strictness !== "strict") {
-          // Advisory mode (the default) — every guard refusal is a hint,
-          // not a hard stop. Users report the "failure" as a log line
-          // and keep working. Only \`strictness: strict\` in config.yaml
-          // or CCLAW_STRICTNESS=strict upgrades this to a thrown block.
-          logToFile(
-            "advisory: " + failed + " flagged tool.execute.before (strictness=" +
-            strictness + "). detail=" + detail.replace(/\\s+/g, " ").slice(0, 300)
-          );
-          return;
-        }
-        throw new Error(
-          "cclaw " + failed + " blocked tool.execute.before.\\n" +
-          "Reason: " + detail + "\\n" +
-          "Diagnose: run \`npx cclaw-cli sync\` in project root.\\n" +
-          "Bypass (temporary): export CCLAW_DISABLE=1 before starting OpenCode,\\n" +
-          "or set \`strictness: advisory\` in .cclaw/config.yaml."
-        );
-      }
-    },
-    "tool.execute.after": async (input, output) => {
-      const payload = normalizeToolPayload(input, output);
-      await runHookScript("context-monitor", payload);
-      void refreshBootstrapCache(false);
-    },
     "experimental.chat.system.transform": (payload) => {
       const bootstrap = getBootstrap();
       if (!bootstrap) return payload;

package/dist/content/review-prompts.js

@@ -53,7 +53,7 @@ value. Do not nitpick wording.
 | 10-star delta | Is there a better high-leverage scope move worth cherry-picking? |
 | Boundary | Are accepted, deferred, and excluded items unambiguous? |
 | Mode fit | Does the selected mode match the evidence: SCOPE EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, or SCOPE REDUCTION? |
-| Downstream refs | Are R-IDs and LD#hash anchors ready for design/spec/plan? |
+| Downstream refs | Are R-IDs and D-XX decision IDs ready for design/spec/plan? |
 
 ## Output
 
@@ -82,7 +82,7 @@ rework, missing failure behavior, or unverifiable acceptance criteria.
 | Architecture | Are component boundaries concrete and aligned with scope? |
 | Data flow | Are inputs, outputs, persistence, and async/sync edges explicit? |
 | Failure modes | Does every meaningful failure have detection, rescue, and user-visible behavior? |
-| Traceability | Do design decisions reference relevant R-IDs and LD#hash anchors? |
+| Traceability | Do design decisions reference relevant R-IDs and D-XX decision IDs? |
 | Verification | Is each risky choice testable by spec/plan/TDD? |
 | Overbuild | Is any architecture stronger than the locked scope actually needs? |
 
@@ -95,7 +95,7 @@ Record findings in the design artifact's review section:
 **Status:** Approved | Issues Found
 
 **Issues:**
-- [R#/LD#hash]: <specific issue> — <why it matters>
+- [R#/D-XX]: <specific issue> — <why it matters>
 
 **Recommendations:**
 - <advisory item or None>

package/dist/content/skills-elicitation.js

@@ -18,18 +18,38 @@ export function adaptiveElicitationSkillMarkdown() {
     const budgetTable = renderQuestionBudgetHintTable();
     return `---
 name: adaptive-elicitation
-description: "Harness-native one-question-at-a-time dialogue for brainstorm/scope/design with stop signals, smart-skip, and append-only Q&A logging."
+description: "Harness-native one-question-at-a-time dialogue for brainstorm/scope/design with stop signals, smart-skip, and append-only Q&A logging. Walking forcing questions in order is mandatory; the linter blocks stage-complete when Q&A Log is below floor."
 ---
 
 # Adaptive Elicitation
 
 Pinned anchor: "Don't tell it what to do, give it success criteria and watch it go."
 
-## HARD-GATE
+## Anti-pattern (BAD examples — never do these)
+
+These behaviors are the exact reason this skill exists. The linter will block your stage-complete if you do them.
+
+- **Bad**: User asks for a "simple web app" -> agent asks 1 question about stack -> 1 question about auth -> drafts the brainstorm artifact and asks for approval.
+- **Good**: User asks for a "simple web app" -> agent asks Q1 (what pain) -> Q2 (direct path) -> Q3 (do-nothing cost) -> Q4 (first operator/user) -> Q5 (no-go boundaries) -> self-eval: clear -> drafts the brainstorm artifact.
+
+- **Bad**: Agent immediately dispatches a subagent (\`product-discovery\`, \`critic\`, \`planner\`) at the start of brainstorm/scope/design to "gather context" before any user dialogue.
+- **Good**: Agent walks the Q&A loop with the user first; subagent dispatch happens only after the user approves the elicitation outcome.
+
+- **Bad**: Agent batches 3-5 grill questions into one large message and asks the user to answer them all at once.
+- **Good**: Agent asks one grill question, waits, logs the answer, asks the next.
+
+- **Bad**: Agent skips forcing questions because it "already has a good idea" of the answer.
+- **Good**: Agent asks the forcing question; if the user's reply confirms the assumption, log it as \`asked (confirmed assumption)\` and move on. Do not silently skip.
+
+## HARD-GATE (machine-enforced)
+
 - User does not run cclaw manually. Do not tell the user to run CLI commands for answers.
 - Ask exactly one question per turn and wait for the answer before asking the next one.
 - Use harness-native question tools first; prose fallback is allowed only when the tool is unavailable.
 - Keep a running Q&A trace in the active artifact under \`## Q&A Log\` in \`${RUNTIME_ROOT}/artifacts/\` as append-only rows.
+- **Hard floor**: do NOT advance the stage (do NOT call \`stage-complete.mjs\`) until \`## Q&A Log\` contains at least \`min(track, stage)\` substantive entries OR an explicit user stop-signal is recorded as a row. The linter rule \`qa_log_below_min\` enforces this; \`stage-complete\` will fail otherwise.
+- **NEVER run shell hash commands** (\`shasum\`, \`sha256sum\`, \`md5sum\`, \`Get-FileHash\`, \`certutil\`, etc.) to compute artifact hashes. If a linter ever asks you for a hash, that is a linter bug — report failure and stop, do not auto-fix in bash.
+- **NEVER paste cclaw command lines into chat** (e.g. \`node .cclaw/hooks/stage-complete.mjs ... --evidence-json '{...}'\`). Run them via the tool layer; report only the resulting summary. The user does not run cclaw manually and seeing the command line is noise.
 
 ## Harness Question Surface
 
@@ -43,67 +63,81 @@ If unavailable, ask one concise prose question and explicitly wait for chat answ
 
 ## Core Protocol
 
-1. Ask one decision-changing question.
+1. Ask one decision-changing question via the harness-native question tool.
 2. Wait for the answer.
 3. Append one row to \`## Q&A Log\`: \`Turn | Question | User answer (1-line) | Decision impact\`.
 4. Self-evaluate:
    - What did I learn?
    - Is context enough to draft now? (yes/no + reason)
-   - If no, what is the next most decision-changing question?
-5. Repeat until context is clear OR user asks to proceed.
+   - Have I covered all stage forcing questions in order? (yes/no + which remain)
+   - If forcing questions remain or context is incomplete, what is the next decision-changing question?
+5. Repeat until **all forcing questions are answered/skipped/waived AND self-evaluation says context is sufficient**, OR user records an explicit stop-signal row.
 
 ## Question Shape Rules
 
 - Prefer single-select multiple choice when one direction/priority/next step must be chosen.
 - Use multi-select only for compatible sets (goals, constraints, non-goals).
-- Smart-skip questions already answered earlier (directly or implicitly) and log "skipped (already covered)" when relevant.
+- Smart-skip: if a question is already answered earlier (directly or implicitly), log \`skipped (already covered: turn N)\` instead of skipping silently. The smart-skip row counts as a substantive Q&A Log entry for floor purposes.
 
 ## Stop Signals (Natural Language)
 
 Treat these as stop-and-draft signals:
-- RU: "достаточно", "хватит", "давай драфт"
-- EN: "enough", "skip", "just draft it", "stop asking", "move on"
+- RU: "достаточно", "хватит", "давай драфт", "хватит вопросов"
+- EN: "enough", "skip", "just draft it", "stop asking", "move on", "no more questions"
 - UA: "досить", "вистачить", "давай драфт", "рухаємось далі"
 
 When detected:
+- Append a Q&A Log row exactly like: \`Turn N | (stop-signal) | <user quote> | stop-and-draft\` — this row satisfies the linter floor escape hatch.
 - Do not ask another question in this stage loop.
 - Move to drafting with available context.
-- For internal agent calls only, pass \`--skip-questions\` on the next advance helper call.
+- For the next internal agent-only call to advance-stage, pass \`--skip-questions\`. **The user never sees or types this flag.**
 
 ## Conditional Grilling (Only On Risk Triggers)
 
-Ask an extra 3-5 sharp questions only when one of these triggers appears:
+When one of these triggers appears, continue the elicitation loop with sharper questions **one at a time** (do NOT batch them):
 - Irreversibility (data deletion, schema migration, breaking API/contract)
 - Security/auth boundary changes
 - Domain-model ambiguity with multiple plausible invariants
 
+Each grill question follows the same Core Protocol: ask one, wait, log, self-eval, ask next.
+
 Do not ask extra questions "for theater" on simple low-risk work.
 
-## Question Budget Hint (Soft Guidance)
+## Question Budget Hint (linter-enforced floor)
 
-Use as orientation, never as a hard stop. Source of truth is \`questionBudgetHint(track, stage)\`:
+Source of truth: \`questionBudgetHint(track, stage)\`. The \`Min\` column is enforced by \`qa_log_below_min\` linter rule — \`stage-complete\` fails when below.
 
 ${budgetTable}
 
 Track mapping note: \`quick\` ~= lightweight, \`medium\` ~= standard, \`standard\` ~= deep.
-Stop based on clarity/user signal, not raw count.
 
-## Stage Forcing Questions
+How to use the columns:
+- \`Min\` — hard floor. Below this, \`stage-complete\` is blocked unless escape hatch is recorded.
+- \`Recommended\` — target for normal flows.
+- \`Hard cap warning\` — point at which to stop or compress remaining forcing questions into one final batched ask. Not skip.
+
+## Stage Forcing Questions (walk in order, one per turn)
 
-Always keep at least one unresolved forcing question in play until answered or explicitly waived:
+**Walk the forcing questions list one-by-one in order, asking each as a separate turn.** Do NOT batch. Do NOT pick favorites — go in order. For each question record one of:
+- \`asked\` — question was asked and answered.
+- \`asked (confirmed assumption)\` — question was asked, user confirmed your prior reading.
+- \`skipped (already covered: turn N)\` — answered implicitly by an earlier reply; cite the turn.
+- \`waived (user override)\` — user explicitly waived this question.
 
-- Brainstorm:
+Stage forcing question lists:
+
+- **Brainstorm**:
   - What pain are we solving?
   - What is the most direct path?
   - What happens if we do nothing?
   - Who is the operator/user impacted first?
   - What are non-negotiable no-go boundaries?
-- Scope:
+- **Scope**:
   - What is definitely in and definitely out?
   - Which decisions are already locked upstream?
   - What is the rollback path if this fails?
   - What are the top failure modes we must design for?
-- Design:
+- **Design**:
   - What is the data flow end-to-end?
   - Where are the seams/interfaces and ownership boundaries?
   - Which invariants must always hold?
@@ -118,6 +152,10 @@ For irreversible moves (deletion, schema migration, breaking API):
 
 ## Completion Rule
 
-"Continue until clear OR user wants to proceed."
-Never force a fixed N-question script.`;
+Continue asking forcing questions in order until one of:
+- (a) all forcing questions for the stage are answered/skipped/waived AND self-evaluation says context is sufficient, OR
+- (b) user records an explicit stop-signal row in \`## Q&A Log\`, OR
+- (c) the \`hard cap warning\` count is reached and you compressed the remaining forcing questions into one final batched ask (not skip).
+
+Do NOT exit the loop after the first 1-2 questions just because you can draft something. The point of the loop is to surface the user's actual constraints, not to confirm your initial reading.`;
 }

package/dist/content/skills.js

@@ -175,18 +175,23 @@ function autoSubagentDispatchBlock(stage, track) {
         const userGate = rule.requiresUserGate ? "required" : "not required";
         const dispatchClass = rule.dispatchClass ?? "stage-specialist";
         const returnSchema = rule.returnSchema ?? "agent-default";
-        return `| ${rule.agent} | ${rule.mode} | ${dispatchClass} | ${returnSchema} | ${userGate} | ${rule.when} | ${rule.purpose} |`;
+        const runPhase = rule.runPhase ?? "any";
+        return `| ${rule.agent} | ${rule.mode} | ${runPhase} | ${dispatchClass} | ${returnSchema} | ${userGate} | ${rule.when} | ${rule.purpose} |`;
     })
         .join("\n");
     const mandatory = schema.mandatoryDelegations;
     const mandatoryList = mandatory.length > 0 ? mandatory.map((a) => `\`${a}\``).join(", ") : "none";
     const delegationLogRel = `${RUNTIME_ROOT}/state/delegation-log.json`;
     const delegationEventsRel = `${RUNTIME_ROOT}/state/delegation-events.jsonl`;
+    const hasPostElicitation = rules.some((rule) => rule.runPhase === "post-elicitation");
+    const runPhaseLegend = hasPostElicitation
+        ? `\nRun Phase legend: \`post-elicitation\` = run only AFTER the adaptive elicitation Q&A loop converges (forcing questions answered/skipped/waived OR user stop-signal recorded). \`pre-elicitation\` = run before any user dialogue (rare). \`any\` = no ordering constraint.`
+        : "";
     return `## Automatic Subagent Dispatch
-| Agent | Mode | Class | Return Schema | User Gate | Trigger | Purpose |
-|---|---|---|---|---|---|---|
+| Agent | Mode | Run Phase | Class | Return Schema | User Gate | Trigger | Purpose |
+|---|---|---|---|---|---|---|---|
 ${rows}
-Mandatory: ${mandatoryList}. Record lifecycle rows in \`${delegationLogRel}\` and append-only \`${delegationEventsRel}\` before completion.
+Mandatory: ${mandatoryList}. Record lifecycle rows in \`${delegationLogRel}\` and append-only \`${delegationEventsRel}\` before completion.${runPhaseLegend}
 ### Harness Dispatch Contract — use true harness dispatch: Claude Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\` via Task/@agent, Codex \`.codex/agents/<agent>.toml\`. Do not collapse OpenCode or Codex to role-switch by default. Worker ACK Contract: ACK must include \`spanId\`, \`dispatchId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and \`ackTs\`; never claim \`fulfillmentMode: "isolated"\` without matching lifecycle proof. Helper: \`.cclaw/hooks/delegation-record.mjs --status=<status> --span-id=<spanId> --dispatch-id=<dispatchId> --dispatch-surface=<surface> --agent-definition-path=<path> --json\`. Exact recipe: scheduled -> launched -> acknowledged -> completed with the same span; completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`.
 
 ${perHarnessLifecycleRecipeBlock()}`;
@@ -392,6 +397,14 @@ function delegationAndCompletionBlock(schema, track) {
 ${normalizedDispatch}
 
 ${completionBlock}
+
+### Stage Closure (harness-only UX)
+
+- **NEVER paste the \`stage-complete.mjs\` command line into chat.** The user does not run cclaw manually; seeing \`node .cclaw/hooks/stage-complete.mjs ... --evidence-json '{...}' --waive-delegation=...\` is noise. Run the helper via the tool layer; report only the resulting summary.
+- **NEVER paste the \`--evidence-json\` payload into chat.** It is structured data for the helper, not for the user. The same evidence already lives in the artifact section.
+- On failure, report a compact human-readable summary based on the helper's JSON \`findings\` array — list failing section names only (one line each), include the full helper JSON in a single fenced \`json\` block. Do not echo the invoking command.
+- **NEVER run shell hash commands** (\`shasum\`, \`sha256sum\`, \`md5sum\`, \`Get-FileHash\`, \`certutil\`, etc.) for hash compute. If the linter ever asks for a hash, that is a linter bug — report failure and stop, do not auto-fix in bash.
+- The helper defaults to quiet success (\`CCLAW_STAGE_COMPLETE_QUIET=1\`); rely on the resulting JSON, not stdout chatter.
 `;
 }
 function quickStartBlock(stage, track) {
@@ -638,10 +651,10 @@ CLI commands, using existing \`cclaw run resume\` and \`internal verify-current-
 
 1. **Wave Start**: author wave plan as \`.cclaw/wave-plans/<wave-n>.md\` referencing previous wave's ship artifact.
 2. **Carry-forward Audit**: at brainstorm of the next wave, re-read previous wave ship artifact and explicitly record in the existing \`## Wave Carry-forward\` section:
-   - Carrying forward: <scope LD# hash references still valid>
+   - Carrying forward: <scope D-XX decision references still valid>
    - Drift detected: <decisions no longer valid + reason>
    - Re-scope needed: <yes/no>
-   - Never create a second \`## Locked Decisions\` heading in brainstorm; reference prior LD# hashes inline.
+   - Never create a second \`## Locked Decisions\` heading in brainstorm; reference prior D-XX IDs inline.
 3. **Resume Path**: if a wave was interrupted mid-stage, \`cclaw run resume\` restores state. Run \`internal verify-current-state\` before continuing.
 4. **Wave End**: at ship, architect cross-stage verification runs from dispatch matrix. If \`DRIFT_DETECTED\`, fix before ship.
 5. **Next Wave Trigger**: launch new \`/cc <topic>\` for next wave and reference previous wave ship artifact in upstream handoff.

package/dist/content/stage-schema.js

@@ -445,14 +445,16 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "product-discovery",
             mode: "mandatory",
             requiredAtTier: "standard",
-            when: "Always for standard/deep brainstorm to validate value, persona/JTBD, success metric, and why-now framing.",
+            runPhase: "post-elicitation",
+            when: "Always for standard/deep brainstorm to validate value, persona/JTBD, success metric, and why-now framing. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Run product-discovery mode to pressure-test problem/value fit and produce product evidence for the Problem Decision Record.",
             requiresUserGate: false
         },
         {
             agent: "divergent-thinker",
             mode: "proactive",
-            when: "When brainstorm has >1 candidate direction or user signals openness to alternatives.",
+            runPhase: "post-elicitation",
+            when: "When brainstorm has >1 candidate direction or user signals openness to alternatives. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Expand option-space with alternative framings and approaches before planner/critic convergence.",
             requiresUserGate: false
         },
@@ -460,7 +462,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "critic",
             mode: "mandatory",
             requiredAtTier: "standard",
-            when: "Always for standard/deep brainstorm to challenge the premise, do-nothing path, and higher-upside alternatives.",
+            runPhase: "post-elicitation",
+            when: "Always for standard/deep brainstorm to challenge the premise, do-nothing path, and higher-upside alternatives. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Attack assumptions and surface non-goals before direction approval, with pre-commitment predictions validated against evidence.",
             requiresUserGate: false,
             skill: "critic-multi-perspective"
@@ -468,7 +471,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         {
             agent: "researcher",
             mode: "proactive",
-            when: "When repository, market, docs, or prior-art context changes the approach set.",
+            runPhase: "post-elicitation",
+            when: "When repository, market, docs, or prior-art context changes the approach set. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Provide search-before-read summaries and context-readiness evidence before large reads or decisions.",
             requiresUserGate: false
         }
@@ -478,14 +482,16 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "planner",
             mode: "mandatory",
             requiredAtTier: "standard",
-            when: "Always during scope shaping.",
+            runPhase: "post-elicitation",
+            when: "Always during scope shaping. Runs only after the adaptive elicitation Q&A loop converges and the user has approved the scope contract draft.",
             purpose: "Challenge premise, map alternatives, and produce explicit in/out contract.",
             requiresUserGate: false
         },
         {
             agent: "divergent-thinker",
             mode: "proactive",
-            when: "When scope mode is SCOPE EXPANSION or SELECTIVE EXPANSION, or scope contract has fewer than 3 alternatives considered.",
+            runPhase: "post-elicitation",
+            when: "When scope mode is SCOPE EXPANSION or SELECTIVE EXPANSION, or scope contract has fewer than 3 alternatives considered. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Generate additional framings and approach variants before scope convergence hardens.",
             requiresUserGate: false
         },
@@ -493,7 +499,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "critic",
             mode: "mandatory",
             requiredAtTier: "standard",
-            when: "Always during scope shaping for standard/deep work.",
+            runPhase: "post-elicitation",
+            when: "Always during scope shaping for standard/deep work. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Test whether the selected scope mode is too timid, too broad, or hiding a smaller useful slice, using pre-commitment predictions and validation.",
             requiresUserGate: false,
             skill: "critic-multi-perspective"
@@ -501,14 +508,16 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         {
             agent: "researcher",
             mode: "proactive",
-            when: "When churn, prior attempts, reference patterns, or external constraints may change scope boundaries.",
+            runPhase: "post-elicitation",
+            when: "When churn, prior attempts, reference patterns, or external constraints may change scope boundaries. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Summarize search/context findings before the scope contract locks accepted/rejected/deferred ideas.",
             requiresUserGate: false
         },
         {
             agent: "product-discovery",
             mode: "proactive",
-            when: "When scope choices change user value, success metrics, or product positioning (Mode: discovery).",
+            runPhase: "post-elicitation",
+            when: "When scope choices change user value, success metrics, or product positioning (Mode: discovery). Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Keep accepted/deferred reference ideas tied to user value and measurable success under product-discovery mode.",
             requiresUserGate: false
         },
@@ -516,14 +525,16 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "product-discovery",
             mode: "proactive",
             requiredAtTier: "standard",
-            when: "When scope mode resolves to SCOPE EXPANSION or SELECTIVE EXPANSION (Mode: strategist).",
+            runPhase: "post-elicitation",
+            when: "When scope mode resolves to SCOPE EXPANSION or SELECTIVE EXPANSION (Mode: strategist). Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Drive 10x vision and concrete expansion proposals before locking the scope contract via product-discovery strategist mode.",
             requiresUserGate: false
         },
         {
             agent: "scope-guardian-reviewer",
             mode: "proactive",
-            when: "When scope mode is SCOPE EXPANSION or SELECTIVE EXPANSION, or scope contract has many accepted ideas.",
+            runPhase: "post-elicitation",
+            when: "When scope mode is SCOPE EXPANSION or SELECTIVE EXPANSION, or scope contract has many accepted ideas. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Challenge complexity growth and enforce minimum-change scope discipline before scope lock.",
             requiresUserGate: false,
             skill: "document-scope-guard"
@@ -534,7 +545,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "architect",
             mode: "mandatory",
             requiredAtTier: "standard",
-            when: "Always during design lock.",
+            runPhase: "post-elicitation",
+            when: "Always during design lock. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Stress architecture boundaries, dependency graph, critical path, and spec handoff.",
             requiresUserGate: false
         },
@@ -542,14 +554,16 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "test-author",
             mode: "mandatory",
             requiredAtTier: "standard",
-            when: "Always during design lock.",
+            runPhase: "post-elicitation",
+            when: "Always during design lock. Runs only after the adaptive elicitation Q&A loop converges.",
             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, or when security/auth/authz trust boundaries are involved.",
+            runPhase: "post-elicitation",
+            when: "When architecture alternatives, coupling, cost, or rollback risk remain debatable, or when security/auth/authz trust boundaries are involved. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Produce a shadow alternative, switch trigger, and cheaper-path challenge for the engineering lock with pre-commitment predictions and validation.",
             requiresUserGate: false,
             skill: "critic-multi-perspective"
@@ -557,21 +571,24 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         {
             agent: "researcher",
             mode: "proactive",
-            when: "When framework/library docs, repo graph context, or reference contracts may change the design.",
+            runPhase: "post-elicitation",
+            when: "When framework/library docs, repo graph context, or reference contracts may change the design. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Run search-before-read context synthesis before architecture locks.",
             requiresUserGate: false
         },
         {
             agent: "security-reviewer",
             mode: "proactive",
-            when: "When trust boundaries, auth, secrets, sensitive data, or external inputs are involved.",
+            runPhase: "post-elicitation",
+            when: "When trust boundaries, auth, secrets, sensitive data, or external inputs are involved. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Catch design-level security risks before implementation.",
             requiresUserGate: false
         },
         {
             agent: "coherence-reviewer",
             mode: "proactive",
-            when: "When design touches multiple subsystems or includes multiple alternatives sections.",
+            runPhase: "post-elicitation",
+            when: "When design touches multiple subsystems or includes multiple alternatives sections. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Detect internal contradictions, terminology drift, and broken cross-section references in design docs.",
             requiresUserGate: false,
             skill: "document-coherence-pass"
@@ -579,7 +596,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         {
             agent: "feasibility-reviewer",
             mode: "proactive",
-            when: "When design assumes runtime conditions, scaling behavior, or external service availability.",
+            runPhase: "post-elicitation",
+            when: "When design assumes runtime conditions, scaling behavior, or external service availability. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Validate that design assumptions remain feasible in real runtime and rollout constraints.",
             requiresUserGate: false,
             skill: "document-feasibility-pass"

package/dist/content/stages/brainstorm.js

@@ -36,8 +36,8 @@ 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.",
-            "**Adaptive elicitation loop (shared skill)** — load `.cclaw/skills/adaptive-elicitation/SKILL.md` and run one decision-changing question at a time via harness-native question tools. After each answer, append one row to `## Q&A Log` (`Turn | Question | User answer (1-line) | Decision impact`). Continue until context is clear or user signals to proceed.",
+            "**ADAPTIVE ELICITATION COMES FIRST (no exceptions, no subagent dispatch before).** Load `.cclaw/skills/adaptive-elicitation/SKILL.md`. Walk the brainstorm forcing questions one-at-a-time via the harness-native question tool, append one row to `## Q&A Log` (`Turn | Question | User answer (1-line) | Decision impact`) after each user answer. Continue until all forcing questions are answered/skipped/waived OR user records an explicit stop-signal row. Only then proceed to delegations, drafts, or analysis. The linter `qa_log_below_min` rule will block `stage-complete` if Q&A Log is below floor.",
+            "**Explore project context** — after the elicitation loop converges, inspect existing files/docs/recent activity to refine the Discovered context section; capture matching files/patterns/seeds in `Context > Discovered context` so downstream stages don't redo discovery.",
             "**Brainstorm forcing questions (must be covered or explicitly waived)** — what pain are we solving, what is the direct path, what happens if we do nothing, who is the first operator/user affected, and what no-go boundaries are non-negotiable.",
             "**Classify stage depth** — choose `lite` for clear low-risk tasks, `standard` for normal engineering/product changes, or `deep` for ambiguity, architecture, external dependency, security/data risk, or explicit think-bigger requests.",
             "**Write the Problem Decision Record** — pick a free-form `Frame type` label that names how this work is framed (examples: product, technical-maintenance, research-spike, ops-incident, infrastructure), then fill the universal Framing fields: affected user/role/operator, current state/failure mode/opportunity, desired observable outcome, evidence/signal, why now, do-nothing consequence, and non-goals.",
@@ -52,7 +52,7 @@ export const BRAINSTORM = {
             "**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.",
             "**Run early Ralph loop discipline** — after each producer iteration, append a `Critic Pass` JSONL row to `.cclaw/state/early-loop-log.jsonl`, refresh `.cclaw/state/early-loop.json`, and iterate until open concerns clear or convergence guard escalates.",
-            "**Embedded Grill (post-pick)** — after `Selected Direction` is named, run 3-5 sharp checks on hidden constraints, reversibility/rollback, scope boundaries, existing-pattern conformance, and domain-language fit; record each question with recommended answer and disposition (accept/refine/reject).",
+            "**Embedded Grill (post-pick, one-at-a-time)** — after `Selected Direction` is named, if grilling triggers fire (irreversibility, security/auth boundary, domain-model ambiguity per `adaptive-elicitation:Conditional Grilling`), continue the elicitation loop with sharper questions **one at a time**, appended to `## Q&A Log` and reflected as rows in `## Embedded Grill`. Do NOT batch the 3-5 grill checks — each one follows the Core Protocol (ask, wait, log, self-eval, ask next).",
             "**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 to close the stage** — state exactly what direction is being approved after the adaptive elicitation loop converges; do not advance without approval and artifact review.",
             "**Handoff packet** — only after approval, produce a scope handoff packet with selected direction, why rejected options were rejected, explicit non-goals, unresolved questions, risk hints, and explicit drift from the initial ask so scope starts from locked upstream decisions instead of rediscovering intent."

package/dist/content/stages/design.js

@@ -40,7 +40,7 @@ export const DESIGN = {
     },
     executionModel: {
         checklist: [
-            "**Adaptive elicitation loop (shared skill)** — load `.cclaw/skills/adaptive-elicitation/SKILL.md` and run one decision-changing question per turn via harness-native tools. After each answer, append one row to `## Q&A Log` (`Turn | Question | User answer (1-line) | Decision impact`). Continue until architecture context is clear or user signals to proceed.",
+            "**ADAPTIVE ELICITATION COMES FIRST (no exceptions, no subagent dispatch before).** Load `.cclaw/skills/adaptive-elicitation/SKILL.md`. Walk the design forcing questions one-at-a-time via the harness-native question tool, append one row to `## Q&A Log` (`Turn | Question | User answer (1-line) | Decision impact`) after each user answer. Continue until all forcing questions are answered/skipped/waived OR user records an explicit stop-signal row. Only then proceed to research, investigator pass, architecture lock, or any delegations. The linter `qa_log_below_min` rule will block `stage-complete` if Q&A Log is below floor.",
             "**Design forcing questions (must be covered or explicitly waived)** — what is the end-to-end data flow, where are seams/ownership boundaries, which invariants must hold, and what will explicitly NOT be refactored now.",
             "Compact design lock — design does not decide what to build; it decides how the approved scope works. For simple slices, produce a tight lock: upstream handoff, existing fit, architecture boundary, one labeled diagram, data/state flow, critical path, failure/rescue, trust boundaries, test/perf expectations, rollout/rollback, rejected alternative, and spec handoff.",
             "Trivial-Change Escape Hatch — for <=3 files, no new interfaces, and no cross-module data flow, produce a mini-design (rationale, changed files, one risk) and proceed to spec.",
@@ -68,7 +68,7 @@ export const DESIGN = {
             "Classify ambiguity before acting. Only non-critical preference/default assumptions may continue; STOP on uncertainty about scope, architecture, security, data loss, public API, migration, auth/pricing, or required user approval. Design hypotheses must name validation path, rollback trigger, and owner before they can be carried forward.",
             "Before final approval, run the critic pass, reconcile material findings, and bound retries with the review-loop policy.",
             "For baseline approval, present the full design plus exact spec handoff and **STOP** until explicit approval.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived, then close via `node .cclaw/hooks/stage-complete.mjs design`."
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` runs **AFTER user approval of the design lock**, not before Q&A. Sequence is: Q&A loop -> draft design lock -> user approval -> `planner` delegation -> `stage-complete`. Legal fulfillment modes for `planner`: (a) **harness-native Task tool** — run the delegation, then record via `node .cclaw/hooks/delegation-record.mjs --stage=design --agent=planner --mode=mandatory --status=completed --span-id=<uuid> --dispatch-surface=cursor-task --agent-definition-path=<agent-md-path> --evidence-ref=<artifact#section>`; (b) **role-switch** — write planner output into the design artifact, then record with `--dispatch-surface=role-switch`; (c) **cclaw subagent helper** with `--dispatch-surface=isolated`. Run `node .cclaw/hooks/stage-complete.mjs design` from the tool layer (do not paste the command into chat); report only the resulting summary."
         ],
         process: [
             "Read upstream artifacts and current design docs.",
@@ -94,7 +94,7 @@ export const DESIGN = {
             "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.",
-            "Stale diagram audit finding is clear by default (unless `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is explicitly false): no blast-radius file newer than diagram markers without explicit update.",
+            "Stale diagram audit finding is clear: no blast-radius file newer than diagram markers without explicit update.",
             "Security & threat model findings are documented with mitigations.",
             "Observability and deployment plans are explicit for critical flows.",
             "Outside-voice findings and dispositions are recorded (accept/reject/defer).",
@@ -165,7 +165,7 @@ export const DESIGN = {
             { section: "Data-Flow Shadow Paths", required: false, validationRule: "Standard/Deep add-on: include `<!-- diagram: data-flow-shadow-paths -->` marker plus a table for high-risk choices: chosen path, shadow alternative, switch trigger, failure/rescue/degraded behavior, and verification evidence." },
             { section: "Error Flow Diagram", required: false, validationRule: "Standard/Deep add-on: include `<!-- diagram: error-flow -->` marker and failure-detection -> rescue -> user-visible outcome flow." },
             { 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: "Default-on audit (unless `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is false): blast-radius files from Codebase Investigation must not be newer than the current design diagram-marker baseline unless explicitly refreshed." },
+            { section: "Stale Diagram Audit", required: false, validationRule: "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." },

package/dist/content/stages/plan.js

@@ -45,8 +45,8 @@ export const PLAN = {
             "Group tasks into dependency batches — batch N+1 cannot start until batch N has verification evidence.",
             "Slice into vertical tasks — each task targets 2-5 minutes, produces one testable outcome, and touches one coherent area.",
             "Task Contract — every task has one coherent outcome, AC mapping, exact verification command/manual step, and expected evidence snippet or pass condition. Avoid vague `run tests` wording.",
-            "Annotate slice-review metadata — if `.cclaw/config.yaml::sliceReview.enabled` is true, every task row additionally carries `touchCount` (rough number of files expected to change) and `touchPaths` (glob hints, e.g. `migrations/**`, `src/auth/**`). A task may set `highRisk: true` to force a review pass regardless of thresholds. These fields feed the TDD stage's Per-Slice Review point; when `sliceReview` is disabled they are optional.",
-            "Map scope Locked Decisions — every LD#hash anchor from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
+            "Annotate slice-review metadata — task rows may carry `touchCount` (rough number of files expected to change), `touchPaths` (glob hints, e.g. `migrations/**`, `src/auth/**`), and optional `highRisk: true` to force a review pass. These fields feed the TDD stage's Per-Slice Review point.",
+            "Map scope Locked Decisions — every D-XX ID from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
             "Run anti-placeholder + anti-scope-reduction scans — block `TODO/TBD/...` and phrasing like `v1`, `for now`, `later` for locked boundaries.",
             "Define validation points — mark where progress must be checked before continuing, with concrete command and expected evidence.",
             "Define execution posture — record whether execution should be sequential, dependency-batched, parallel-safe, or blocked; include risk triggers and RED/GREEN/REFACTOR checkpoint/commit expectations when the repo workflow supports them. This fulfills the `plan_execution_posture_recorded` gate.",
@@ -127,7 +127,7 @@ export const PLAN = {
             { section: "Upstream Handoff", required: false, validationRule: "Summarizes spec/design/scope decisions, constraints, open questions, and explicit drift before task breakdown." },
             { section: "Dependency Graph", required: false, validationRule: "Ordering and parallel opportunities explicit. No circular dependencies." },
             { section: "Dependency Batches", required: true, validationRule: "Every task belongs to a batch. Each batch has an exit gate and dependency statement." },
-            { section: "Task List", required: true, validationRule: "Each task row includes ID, description, acceptance criterion, exact verification command/manual step, expected evidence/pass condition, and effort estimate (S/M/L). Every task must also carry a minutes estimate within the 2-5 minute budget. When the sliceReview option is enabled in the cclaw config, each task row additionally declares touchCount, touchPaths, and an optional highRisk flag so the TDD stage can decide whether a Per-Slice Review pass is required." },
+            { section: "Task List", required: true, validationRule: "Each task row includes ID, description, acceptance criterion, exact verification command/manual step, expected evidence/pass condition, and effort estimate (S/M/L). Every task must also carry a minutes estimate within the 2-5 minute budget. When present, touchCount/touchPaths/highRisk metadata drives Per-Slice Review escalation in TDD." },
             { section: "Acceptance Mapping", required: true, validationRule: "Every spec criterion is covered by at least one task." },
             { section: "Execution Posture", required: true, validationRule: "States sequential/batch/parallel posture, stop conditions, risk triggers, and RED/GREEN/REFACTOR checkpoint or commit expectations for TDD when consistent with the repo workflow." },
             { section: "Locked Decision Coverage", required: false, validationRule: "Every locked decision ID (D-XX) from scope is listed with linked task IDs or explicit defer rationale." },

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

@@ -38,6 +38,15 @@ export interface StageAutoSubagentDispatch {
     when: string;
     purpose: string;
     requiresUserGate: boolean;
+    /**
+     * When this delegation may run relative to the adaptive elicitation Q&A loop.
+     * - `pre-elicitation` — run before any user dialogue (rare; only for trivial info-gathering).
+     * - `post-elicitation` — run only after the Q&A loop converges (default for brainstorm/scope/design
+     *   so subagents do not preempt the user dialogue).
+     * - `any` — no ordering constraint (default for stages that do not run elicitation:
+     *   spec/plan/tdd/review/ship).
+     */
+    runPhase?: "pre-elicitation" | "post-elicitation" | "any";
     /** Role category used by generated routing tables and lifecycle checks. */
     dispatchClass?: StageSubagentDispatchClass;
     /** Strict status/evidence contract the dispatched agent must return. */