cclaw-cli 6.4.0 → 6.5.0

package/dist/artifact-linter/scope.js

@@ -43,11 +43,11 @@ export async function lintScopeStage(ctx) {
         const skipByTrack = shouldDemoteArtifactValidationByTrack(track, taskClass);
         if (skipByTrack) {
             findings.push({
-                section: "Expansion Strategist Delegation",
+                section: "Product Discovery Delegation (Strategist Mode)",
                 required: false,
                 rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
                 found: true,
-                details: `Expansion Strategist delegation requirement skipped for track="${track}"` +
+                details: `Product-discovery delegation requirement skipped for track="${track}"` +
                     (taskClass ? `, taskClass="${taskClass}"` : "") +
                     ` (Wave 25: lite-tier escape; selectedMode=${selectedScopeMode}).`
             });
@@ -78,12 +78,12 @@ export async function lintScopeStage(ctx) {
             const hasCompleted = discoveryRows.length > 0;
             const hasEvidence = discoveryRows.some((entry) => Array.isArray(entry.evidenceRefs) && entry.evidenceRefs.length > 0);
             findings.push({
-                section: "Expansion Strategist Delegation",
+                section: "Product Discovery Delegation (Strategist Mode)",
                 required: true,
                 rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
                 found: hasCompleted && hasEvidence,
                 details: !hasCompleted
-                    ? `Scope mode ${selectedScopeMode} requires a completed product-discovery delegation row for active run ${delegationLedger.runId}.`
+                    ? `Scope mode ${selectedScopeMode} requires a completed product-discovery delegation row for active run ${delegationLedger.runId}. In SELECTIVE EXPANSION / SCOPE EXPANSION, run product-discovery (mode=proactive) BEFORE stage-complete.`
                     : hasEvidence
                         ? `product-discovery delegation satisfied for mode ${selectedScopeMode}.`
                         : "product-discovery delegation exists but evidenceRefs is empty; add at least one artifact/code evidence reference."

package/dist/artifact-linter.js

@@ -367,7 +367,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
  *  - `Architecture Diagram` — sync/async + failure-edge enforcement
  *  - `Data Flow` — Interaction Edge Case mandatory rows
  *  - `Stale Diagram Drift Check` — blast-radius file mtime audit
- *  - `Expansion Strategist Delegation` — product-discovery delegation
+ *  - `Product Discovery Delegation (Strategist Mode)` — product-discovery delegation
  *
  * Findings remain in the result so the caller can surface them as
  * advisory hints; only `required` flips to `false`.
@@ -376,5 +376,5 @@ const ARTIFACT_VALIDATION_LITE_DEMOTE_SECTIONS = new Set([
     "Architecture Diagram",
     "Data Flow",
     "Stale Diagram Drift Check",
-    "Expansion Strategist Delegation"
+    "Product Discovery Delegation (Strategist Mode)"
 ]);

package/dist/content/hooks.js

@@ -380,6 +380,47 @@ function buildRow(args, status, runId, now) {
   };
 }
 
+async function acquireDelegationLogLock(stateDir) {
+  const lockDir = path.join(stateDir, "delegation-log.json.lock");
+  const maxWaitMs = 3000;
+  const startMs = Date.now();
+  let delayMs = 25;
+  while (true) {
+    try {
+      await fs.mkdir(lockDir, { recursive: false });
+      return lockDir;
+    } catch (err) {
+      const code = err && typeof err === "object" && "code" in err ? err.code : "";
+      if (code !== "EEXIST") throw err;
+      if (Date.now() - startMs >= maxWaitMs) {
+        process.stderr.write(
+          "[cclaw] delegation-record: timeout waiting for delegation-log.json.lock (max " + maxWaitMs + "ms)\\n"
+        );
+        process.exit(2);
+      }
+      const jitter = Math.floor(Math.random() * 25);
+      await new Promise((resolve) => setTimeout(resolve, delayMs + jitter));
+      delayMs = Math.min(delayMs * 2, 200);
+    }
+  }
+}
+
+async function releaseDelegationLogLock(lockDir) {
+  try {
+    await fs.rm(lockDir, { recursive: true, force: true });
+  } catch {
+    // best-effort release
+  }
+}
+
+async function writeDelegationLedgerAtomic(ledgerPath, ledger) {
+  const dir = path.dirname(ledgerPath);
+  const tmp =
+    path.join(dir, ".delegation-log.json." + process.pid + "." + Date.now() + "." + Math.random().toString(16).slice(2) + ".tmp");
+  await fs.writeFile(tmp, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+  await fs.rename(tmp, ledgerPath);
+}
+
 async function persistEntry(root, runId, clean, event, options = {}) {
   const stateDir = path.join(root, RUNTIME_ROOT, "state");
   await fs.mkdir(stateDir, { recursive: true });
@@ -387,29 +428,34 @@ async function persistEntry(root, runId, clean, event, options = {}) {
 
   const ledgerPath = path.join(stateDir, "delegation-log.json");
   let ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
+  const lockDir = await acquireDelegationLogLock(stateDir);
   try {
-    ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
-    if (!Array.isArray(ledger.entries)) ledger.entries = [];
-  } catch {
-    ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
-  }
-
-  // Rerecord semantics: replace any pre-existing row with the same spanId
-  // (regardless of its status) so the legacy v1/v2 row is upgraded to v3
-  // shape on disk. The append path keeps the historical dedup semantics:
-  // an exact (spanId, status) duplicate is dropped to keep retried hooks
-  // idempotent.
-  if (options.replaceBySpanId) {
-    ledger.entries = ledger.entries.filter((entry) => entry.spanId !== clean.spanId);
-    ledger.entries.push(clean);
-    ledger.runId = runId;
-    ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
-    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
-  } else if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
-    ledger.entries.push(clean);
-    ledger.runId = runId;
-    ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
-    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+    try {
+      ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
+      if (!Array.isArray(ledger.entries)) ledger.entries = [];
+    } catch {
+      ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
+    }
+
+    // Rerecord semantics: replace any pre-existing row with the same spanId
+    // (regardless of its status) so the legacy v1/v2 row is upgraded to v3
+    // shape on disk. The append path keeps the historical dedup semantics:
+    // an exact (spanId, status) duplicate is dropped to keep retried hooks
+    // idempotent.
+    if (options.replaceBySpanId) {
+      ledger.entries = ledger.entries.filter((entry) => entry.spanId !== clean.spanId);
+      ledger.entries.push(clean);
+      ledger.runId = runId;
+      ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
+      await writeDelegationLedgerAtomic(ledgerPath, ledger);
+    } else if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
+      ledger.entries.push(clean);
+      ledger.runId = runId;
+      ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
+      await writeDelegationLedgerAtomic(ledgerPath, ledger);
+    }
+  } finally {
+    await releaseDelegationLogLock(lockDir);
   }
 
   const active = ledger.entries.filter((entry) => ["scheduled", "launched", "acknowledged"].includes(entry.status));

package/dist/content/skills.js

@@ -192,7 +192,7 @@ function autoSubagentDispatchBlock(stage, track) {
 |---|---|---|---|---|---|---|---|
 ${rows}
 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>\`.
+### 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. Canonical helper (same flags as \`delegation-record.mjs --help\`): \`node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|...> --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--evidence-ref=<ref>] --json\`. Lifecycle order: \`scheduled → launched → acknowledged → completed\` on one span (reuse the same span id); completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`. For a partial audit trail, \`--repair --span-id=<id> --repair-reason="<why>"\` appends missing phases (see \`--help\`) instead of inventing shortcuts.
 
 ${perHarnessLifecycleRecipeBlock()}`;
 }
@@ -390,7 +390,7 @@ function completionParametersBlock(schema, track) {
 - If you edit any completed-stage artifact after it shipped (\`completedStageMeta\` timestamps exist), append a short \`## Amendments\` section with dated bullets (timestamp + reason) instead of overwriting the archived narrative silently — advisory linter rule \`stage_artifact_post_closure_mutation\` enforces visibility when this trail is missing.
 - Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""} If proactive delegations were intentionally skipped, rerun only with \`--accept-proactive-waiver\` (optionally \`--accept-proactive-waiver-reason="<why safe>"\`) after explicit user approval.
 - Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If a helper fails, report a one-line human-readable failure plus fenced JSON diagnostics; never echo the invoking command line or apply a manual state workaround.
-- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the single-line success JSON exactly as printed to stdout (for example \`{"ok":true,"command":"stage-complete",...}\` including \`completedStages\` / \`currentStage\` / \`runId\`); do not paraphrase. Do not infer success from empty stdout or from skipped retries (quiet mode always emits one JSON line on success).
 - Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
 }
@@ -412,7 +412,7 @@ ${completionBlock}
 - **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.
+- The helper defaults to quiet (\`CCLAW_STAGE_COMPLETE_QUIET=1\`): no pretty-printed chatter, but **stdout still prints exactly one line** of machine-readable success JSON (same contract as \`start-flow\` in quiet mode).
 `;
 }
 function quickStartBlock(stage, track) {

package/dist/content/stages/scope.js

@@ -52,6 +52,7 @@ export const SCOPE = {
             "**Premise carry-forward (do NOT re-author)** — brainstorm OWNS the premise check (right problem / direct path / what if nothing). Cite brainstorm's `## Premise Check` section in `## Upstream Handoff > Decisions carried forward`. Add a row to `## Premise Drift` only when the scope-stage Q&A surfaced NEW evidence that materially changes the brainstorm answer (e.g. new constraint, new user signal). Otherwise mark `Premise Drift: None` — do not duplicate the brainstorm premise table.",
             "**Conditional 10-star boundary** — for deep/high-risk/product-strategy work, show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded without vague `later/for now` placeholders. Skip this for straightforward repair work and record `not needed: compact scope`.",
             "**Pick one operational mode with the user** — HOLD SCOPE preserves focus; SELECTIVE EXPANSION cherry-picks high-leverage reference ideas; SCOPE EXPANSION explores ambitious alternatives; SCOPE REDUCTION cuts to the essential wedge. Recommend one, state why and what signal would change it, then keep elicitation focused until the user either approves or asks to proceed with draft boundaries.",
+            "**Product-discovery is REQUIRED for SELECTIVE / SCOPE EXPANSION (hard gate)** — If the resolved scope mode is SELECTIVE EXPANSION or SCOPE EXPANSION, run \`product-discovery\` in proactive mode **after** adaptive elicitation converges and **before** \`stage-complete\`. Do not complete this stage until the delegation ledger shows \`product-discovery\` as \`completed\` with non-empty \`evidenceRefs\` pointing at this scope artifact. HOLD SCOPE and SCOPE REDUCTION do not require this row.",
             "**Run mode-specific analysis only to needed depth** — lean discovery keeps the selected-mode row compact; guided adds the standard contract rows; deep may add Landscape Check, Taste Calibration, Reference Pattern Registry, Reference Pull, Ambitious Alternatives, and Ruthless Minimum Slice evidence when mode/risk warrants it.",
             "**Decision-driver contract** — list weighted decision drivers (value, risk, reversibility, effort, timeline) and score candidate scope moves so the selected mode and boundaries are evidence-backed, not preference-led.",
             "**Architecture handoff (do NOT pick architecture tier here)** — design OWNS architecture choice (minimum-viable / product-grade / ideal). Scope only picks the SCOPE MODE (HOLD/SELECTIVE/EXPAND/REDUCE) and boundary; record in `## Scope Contract > Design handoff` what design must decide (e.g. `architecture-tier`, `framework`, `data-model`). Do NOT enumerate Implementation Alternatives in scope.",

package/dist/content/templates.d.ts

@@ -7,5 +7,5 @@ export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n-
  * (premature draft, premature subagent dispatch, command-line echo to chat).
  */
 export declare const CURSOR_GUIDELINES_RULE_MDC = "---\ndescription: cclaw zero-install behavior baseline (always-on)\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-guidelines-rule -->\n\n# Cclaw Baseline Guidelines\n\nThese three rules apply to every Cursor agent session in this project,\nregardless of whether stage skills loaded.\n\n## 1. Q&A floor before drafting (brainstorm/scope/design)\n\nBefore drafting any `.cclaw/artifacts/01-brainstorm-*.md`,\n`02-scope-*.md`, or `03-design-*.md`, verify that the artifact's\n`## Q&A Log` table demonstrates Ralph-Loop convergence: every\nforcing-question topic id is tagged `[topic:<id>]` on at least one row\n(see the stage's forcing-questions checklist for the id list), the last\n2 turns produce no new decision-changing impact, OR an explicit user\nstop-signal row is recorded. Walk the stage forcing questions one at a\ntime via the `AskQuestion` tool. If you find yourself proposing a\ndraft after 1-2 questions while forcing topic ids remain untagged, STOP\nand continue the loop.\n\nThe `qa_log_unconverged` linter rule will block `stage-complete` when\nconvergence has not been reached. Wave 24 (v6.0.0) made `[topic:<id>]`\ntagging mandatory; the English keyword fallback was removed because it\nmis-reported convergence on RU/UA Q&A logs.\n\n## 2. Mandatory subagents run after Q&A approval\n\nFor brainstorm / scope / design, mandatory subagents (\n`product-discovery`, `critic`, `planner`, `architect`,\n`test-author`) run **only AFTER the user approves the elicitation\noutcome**, never before the Q&A loop converges. Dispatching them early\npreempts the user dialogue and violates the elicitation contract \u2014 the\nlinter will block stage-complete.\n\nSee each stage's \"Run Phase: post-elicitation\" rows in the materialized\nAutomatic Subagent Dispatch table.\n\n## 3. Never echo cclaw command lines to chat\n\nThe user does not run cclaw helpers (`node .cclaw/hooks/...`) manually.\nNEVER paste full command lines, `--evidence-json '{...}'` payloads,\n`--waive-delegation=...`, or shell hash commands (`shasum`,\n`sha256sum`, `Get-FileHash`, `certutil`, etc.) into chat. Run the\nhelper via the tool layer and report only the resulting summary. On\nfailure, report a compact human-readable summary plus the helper JSON in\na single fenced `json` block.\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Stage completion claim requires `stage-complete` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.\n\n## Protocol label hygiene\n\n`skip` wording means different things depending on phase: brainstorm/scope/design Q&A stop-signals may still literal **skip**/enough/move-on wording; structured ship closeout retros and compound clustering prompts should expose **no changes** (or accept-as-is language) rather than labeling the passive path as skip. Keep the verbs aligned with the harness question copy you present to the human.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Stage completion claim requires `stage-complete` exit 0 in the current turn. Quote the single-line success JSON printed to stdout (e.g. `{\"ok\":true,\"command\":\"stage-complete\",...}`); do not paraphrase, do not infer success from empty stdout or from skipped retries.\n\n## Protocol label hygiene\n\n`skip` wording means different things depending on phase: brainstorm/scope/design Q&A stop-signals may still literal **skip**/enough/move-on wording; structured ship closeout retros and compound clustering prompts should expose **no changes** (or accept-as-is language) rather than labeling the passive path as skip. Keep the verbs aligned with the harness question copy you present to the human.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -1565,7 +1565,7 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 ## Verification Discipline
 
 - No completion claim without fresh command evidence in this turn.
-- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the single-line success JSON printed to stdout (e.g. \`{"ok":true,"command":"stage-complete",...}\`); do not paraphrase, do not infer success from empty stdout or from skipped retries.
 
 ## Protocol label hygiene
 

package/dist/internal/advance-stage/advance.js

@@ -601,7 +601,17 @@ export async function runAdvanceStage(projectRoot, args, io) {
         interactionHints
     };
     await writeFlowState(projectRoot, finalState);
-    if (!args.quiet) {
+    if (args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "stage-complete",
+            stage: args.stage,
+            completedStages: finalState.completedStages,
+            currentStage: finalState.currentStage,
+            runId: finalState.activeRunId
+        })}\n`);
+    }
+    else {
         io.stdout.write(`${JSON.stringify({
             ok: true,
             command: "advance-stage",

package/dist/internal/advance-stage/start-flow.js

@@ -211,19 +211,31 @@ export async function runStartFlow(projectRoot, args, io) {
     nextState = { ...nextState, repoSignals };
     await writeFlowState(projectRoot, nextState, { allowReset: true });
     await appendIdeaArtifact(projectRoot, args, current);
-    if (!args.quiet) {
+    const successPayload = {
+        ok: true,
+        command: "start-flow",
+        reclassify: args.reclassify,
+        track: nextState.track,
+        discoveryMode: nextState.discoveryMode,
+        taskClass: nextState.taskClass ?? null,
+        currentStage: nextState.currentStage,
+        skippedStages: nextState.skippedStages,
+        activeRunId: nextState.activeRunId,
+        repoSignals
+    };
+    if (args.quiet) {
         io.stdout.write(`${JSON.stringify({
             ok: true,
             command: "start-flow",
-            reclassify: args.reclassify,
-            track: nextState.track,
-            discoveryMode: nextState.discoveryMode,
-            taskClass: nextState.taskClass ?? null,
-            currentStage: nextState.currentStage,
-            skippedStages: nextState.skippedStages,
-            activeRunId: nextState.activeRunId,
-            repoSignals
-        }, null, 2)}\n`);
+            track: successPayload.track,
+            discoveryMode: successPayload.discoveryMode,
+            currentStage: successPayload.currentStage,
+            activeRunId: successPayload.activeRunId,
+            repoSignals: successPayload.repoSignals
+        })}\n`);
+    }
+    else {
+        io.stdout.write(`${JSON.stringify(successPayload, null, 2)}\n`);
     }
     return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {