cclaw-cli 6.5.0 → 6.7.0

package/dist/content/skills.js

@@ -1,7 +1,8 @@
 import { RUNTIME_ROOT, STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { nextStage as nextStageForTrack } from "../flow-state.js";
 import { FLOW_STAGES } from "../types.js";
-import { stageExamples } from "./examples.js";
+import { behaviorAnchorFor, stageExamples } from "./examples.js";
+import { INVESTIGATION_DISCIPLINE_BLOCK } from "./templates.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
 import { referencePatternsForStage } from "./reference-patterns.js";
 import { harnessDelegationRecipes } from "../harness-adapters.js";
@@ -104,6 +105,40 @@ Any "the failure is real" claim (failing test, broken build, regression catch, d
 For TDD specifically, this is the watched-RED proof and is required per new test before \`stage-complete\` accepts the stage.
 `;
 }
+/**
+ * Stages that perform real investigation work. The shared
+ * `INVESTIGATION_DISCIPLINE_BLOCK` is rendered once per stage skill in this
+ * set so the search → graph → narrow-read → draft ladder appears verbatim
+ * across the elicitation/spec/plan/tdd/review pipeline. `ship` is excluded:
+ * it consumes the upstream trace rather than producing one.
+ */
+export const INVESTIGATION_DISCIPLINE_STAGES = new Set([
+    "brainstorm",
+    "scope",
+    "design",
+    "spec",
+    "plan",
+    "tdd",
+    "review"
+]);
+export function investigationDisciplineBlock() {
+    return INVESTIGATION_DISCIPLINE_BLOCK;
+}
+export function behaviorAnchorBlock(stage) {
+    const anchor = behaviorAnchorFor(stage);
+    if (!anchor)
+        return "";
+    const ruleHint = anchor.ruleHint && anchor.ruleHint.trim().length > 0
+        ? `\n\nRule hint: ${anchor.ruleHint.trim()}`
+        : "";
+    return `## Behavior anchor
+
+Anchored to artifact section: \`${anchor.section}\`.
+
+- Bad: ${anchor.bad}
+- Good: ${anchor.good}${ruleHint}
+`;
+}
 function crossCuttingMechanicsBlock(stage) {
     // All stages share the universal mechanics, but each stage's matching
     // linter rules decide what is mandatory vs. structural-only.
@@ -117,6 +152,13 @@ function crossCuttingMechanicsBlock(stage) {
     if (stage === "tdd" || stage === "review" || stage === "ship") {
         blocks.push(watchedFailProofBlock());
     }
+    if (INVESTIGATION_DISCIPLINE_STAGES.has(stage)) {
+        blocks.push(investigationDisciplineBlock());
+    }
+    const anchor = behaviorAnchorBlock(stage);
+    if (anchor.length > 0) {
+        blocks.push(anchor);
+    }
     return blocks.join("\n");
 }
 function whenNotToUseBlock(items) {
@@ -388,7 +430,7 @@ function completionParametersBlock(schema, track) {
 - \`delegation lifecycle proof\`: use the delegation helper recipe in this section with explicit lifecycle rows: \`--status=scheduled\` -> \`--status=launched\` -> \`--status=acknowledged\` -> \`--status=completed\` (completed isolated/generic requires prior ACK for the same span or \`--ack-ts=<iso>\`).
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
 - 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.
+- 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, first issue a short-lived waiver token with \`cclaw-cli internal waiver-grant --stage <stage> --reason "<short-slug>"\`, then rerun the completion helper with \`--accept-proactive-waiver=<token> --accept-proactive-waiver-reason="<why safe>"\` after explicit user approval. Tokens expire in 30 minutes and are single-use; bare \`--accept-proactive-waiver\` is no longer accepted.
 - 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 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.

package/dist/content/stages/brainstorm.js

@@ -38,10 +38,10 @@ export const BRAINSTORM = {
         checklist: [
             "**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 **and stamp the row's `Decision impact` cell with the matching `[topic:<id>]` tag** (e.g. `[topic:pain]`). Continue until every forcing-question topic id is tagged on a row OR Ralph-Loop convergence detector says no new decision-changing rows in last 2 iterations OR user records an explicit stop-signal row. Only then proceed to delegations, drafts, or analysis. The linter `qa_log_unconverged` rule will block `stage-complete` if convergence is not reached.",
             "**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)** — `pain: what pain are we solving`; `direct-path: what is the direct path`; `do-nothing: what happens if we do nothing`; `operator: who is the first operator/user affected`; `no-go: what no-go boundaries are non-negotiable`. Tag the matching `## Q&A Log` row's `Decision impact` cell with `[topic:<id>]` (e.g. `[topic:pain]`) so the linter can verify coverage in any natural language. Tags are MANDATORY for forcing-question rows; un-tagged rows do NOT count toward coverage.",
+            "**Brainstorm forcing questions (must be covered or explicitly waived)** — `pain: what pain are we solving`; `direct-path: what is the direct path`; `operator: who is the first operator/user affected`; `no-go: what no-go boundaries are non-negotiable`. Tag the matching `## Q&A Log` row's `Decision impact` cell with `[topic:<id>]` (e.g. `[topic:pain]`) so the linter can verify coverage in any natural language. Tags are MANDATORY for forcing-question rows; un-tagged rows do NOT count toward coverage. Round 6 (v6.7.0) removed the counterfactual `do-nothing` topic; the Problem Decision Record already captures `Do-nothing consequence`.",
             "**Discovery posture (flow-state `discoveryMode`)** — follow `lean` / `guided` / `deep` from the active run. Use lean for smallest safe discovery pass; guided as the default balanced pass; escalate to deep when ambiguity, architecture, external dependency, security/data risk, or explicit think-bigger requests warrant fuller option pressure and mandatory specialist coverage.",
             "**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.",
-            "**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.",
+            "**Premise check (one pass)** — answer the two gstack-style questions in the artifact body: *Right problem? Direct path?* Take a position; do not hedge. Round 6 (v6.7.0): the counterfactual premise line was retired; Do-nothing consequence already lives in the Problem Decision Record.",
             "**Reframe with How Might We** — write a single `How Might We …?` line that names the user/operator, the desired outcome, and the constraint. This is the altitude check before approaches.",
             "**Run Clarity Gate** — record ambiguity score (0.00-1.00), decision boundaries, reaffirmed non-goals, and residual-risk handoff before locking recommendations. If ambiguity remains high (>0.40), ask one decision-changing question before recommending.",
             "**Sharpening question discipline** — ask one decision-changing question at a time. Do not default to 3-5 batched questions; record only questions that changed the direction or a critical stop decision.",
@@ -62,14 +62,16 @@ export const BRAINSTORM = {
             "\"If something is unclear, stop. Name what's confusing. Ask.\"",
             "Start from observed project context; if the idea is vague, first narrow the project type with **one** structured question, then keep going.",
             "Honor the run's `discoveryMode` (`lean` | `guided` | `deep`) from flow-state: lean stays fastest, guided is the default breadth, deep pulls in fuller critique and mandatory delegations when the run is classified that way.",
-            "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.",
+            "Lead with the premise check (right problem / direct path) and the `How Might We` reframing before approaches; both go in the artifact, not just the chat. Round 6 (v6.7.0) removed the counterfactual premise line; Do-nothing consequence still lives in the Problem Decision Record.",
             "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.",
             "Run the shared adaptive elicitation cycle from `.cclaw/skills/adaptive-elicitation/SKILL.md`, including stop-signal handling (RU/EN/UA), smart-skip, conditional grilling triggers, and append-only `## Q&A Log` updates.",
             "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.",
             "For simple low-risk greenfield work, present a compact A/B choice with one recommended path and one higher-upside challenger; keep the artifact concise but structurally complete (Context, Premise, How Might We, Sharpening Questions, Approaches, Reaction, Selected Direction, Not Doing).",
             "Show approaches before the recommendation; include a higher-upside challenger and gather reaction first.",
             "Self-review before approval: re-read the artifact, fix contradictions/placeholders/weak trade-offs, then ask for approval. Do not ask for approval on a draft you have not re-read.",
-            "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact."
+            "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block (search -> graph/impact -> narrow read of 1-3 files -> draft) before any drafting or delegation; pass repo-relative paths and refs (never file bodies) in delegations.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how this stage's `Problem Decision Record` must be filled."
         ],
         process: [
             "Explore project context and align work to the run's discovery mode (lean / guided / deep).",
@@ -140,7 +142,7 @@ 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 Decision Record", required: true, validationRule: "Must include a free-form `Frame type` label (examples only: product, technical-maintenance, research-spike, ops-incident, infrastructure) and the universal Framing fields: affected user/role/operator, current state/failure mode/opportunity, desired observable outcome, evidence/signal, why now, do-nothing consequence, non-goals. The linter checks that the section has meaningful content; the field labels themselves are the structural contract." },
-            { 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: "Premise Check", required: false, validationRule: "Recommended: explicit answers to `Right problem?` and `Direct path?` — take a position, do not hedge. Round 6 (v6.7.0) retired the counterfactual premise line; Do-nothing consequence already lives in the Problem Decision Record." },
             { section: "How Might We", required: false, validationRule: "Recommended: a single `How Might We …?` line naming the user, the outcome, and the binding constraint." },
             { section: "Clarity Gate", required: false, validationRule: "Recommended before recommendation lock: include ambiguity score (0.00-1.00), decision boundaries, reaffirmed non-goals, and residual-risk handoff for scope." },
             { section: "Sharpening Questions", required: false, validationRule: "Recommended only when needed: one decision-changing question per turn with explicit `Decision impact`; compact tasks may record `None - early exit` with rationale." },

package/dist/content/stages/design.js

@@ -71,7 +71,9 @@ 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` 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."
+            "**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.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block before drafting architecture — populate `Codebase Investigation` from a search/graph trace and pass paths/refs (never file bodies) to investigator/critic delegations.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how `Codebase Investigation` must precede any ADR commitment."
         ],
         process: [
             "Read upstream artifacts and current design docs.",

package/dist/content/stages/plan.js

@@ -61,7 +61,9 @@ export const PLAN = {
             "Preserve locked scope boundaries: no silent scope reduction language in task rows.",
             "Enforce WAIT_FOR_CONFIRM: present the plan summary with options (A) Approve / (B) Revise / (C) Reject.",
             "**STOP.** Do NOT proceed until user explicitly approves.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `node .cclaw/hooks/stage-complete.mjs plan` and tell the user to run `/cc`."
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `node .cclaw/hooks/stage-complete.mjs plan` and tell the user to run `/cc`.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block — when defining `Implementation Units`, list cited paths in the `Files` and `Patterns to follow` rows instead of pasting code into chat or delegations.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how `Execution Posture` may only claim parallel-safe with disjoint units and a cited interface contract."
         ],
         process: [
             "Build dependency graph and ordered slices.",

package/dist/content/stages/review.js

@@ -58,7 +58,9 @@ export const REVIEW = {
             "Resolve all critical blockers before ship. If verdict is BLOCKED, do not pass `review_criticals_resolved`; pass only the remediation route gate `review_verdict_blocked` when routing back to TDD.",
             "When verdict is BLOCKED, do not end with a passive stop: explicitly route remediation to TDD via `ROUTE_BACK_TO_TDD`, point to `npx cclaw-cli internal rewind tdd` with the blocking IDs, and tell the operator to ack the stale TDD marker only after rework is complete.",
             structuredAskSingleChoiceInstruction("final verdict", "verdict (APPROVED / APPROVED_WITH_CONCERNS / BLOCKED)"),
-            "**STOP.** Do NOT proceed to ship until the user provides an explicit verdict."
+            "**STOP.** Do NOT proceed to ship until the user provides an explicit verdict.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block — `Changed-File Coverage` and Layer 2 findings cite `path:line`; delegate `reviewer`/`security-reviewer` with paths and refs, never with pasted file contents.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors that `Layer 2 Findings` surface defects, not drive-by refactors."
         ],
         process: [
             "Layer 1: check acceptance criteria and requirement coverage.",

package/dist/content/stages/scope.js

@@ -47,9 +47,9 @@ export const SCOPE = {
     executionModel: {
         checklist: [
             "**ADAPTIVE ELICITATION COMES FIRST (no exceptions, no subagent dispatch before).** Load `.cclaw/skills/adaptive-elicitation/SKILL.md`. Walk the scope 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 **and stamp the row's `Decision impact` cell with the matching `[topic:<id>]` tag** (e.g. `[topic:in-out]`). Continue until every forcing-question topic id is tagged on a row OR Ralph-Loop convergence detector says no new decision-changing rows in last 2 iterations OR user records an explicit stop-signal row. Only then propose the scope contract draft, recommend a mode, or dispatch any delegations. The linter `qa_log_unconverged` rule will block `stage-complete` if convergence is not reached.",
-            "**Scope forcing questions (must be covered or explicitly waived)** — `in-out: what is definitely in/out`; `locked-upstream: which upstream decisions are locked`; `rollback: what rollback path protects users if scope assumptions fail`; `failure-modes: what are the top failure modes we must design for`. Tag the matching `## Q&A Log` row's `Decision impact` cell with `[topic:<id>]` (e.g. `[topic:in-out]`) so the linter can verify coverage in any natural language. Tags are MANDATORY for forcing-question rows; un-tagged rows do NOT count toward coverage.",
+            "**Scope forcing questions (must be covered or explicitly waived)** — `in-out: what is definitely in/out`; `locked-upstream: which upstream decisions are locked`. Tag the matching `## Q&A Log` row's `Decision impact` cell with `[topic:<id>]` (e.g. `[topic:in-out]`) so the linter can verify coverage in any natural language. Tags are MANDATORY for forcing-question rows; un-tagged rows do NOT count toward coverage. Round 6 (v6.7.0) removed the counterfactual `rollback` and `failure-modes` topics from scope forcing questions; Design still owns the Failure Mode Table and rollback evidence.",
             "**Scope contract first** — read brainstorm handoff, name upstream decisions used, explicit drift, confidence, unresolved questions, and next-stage risk hints; draft the in-scope/out-of-scope/deferred/discretion contract before any design choice.",
-            "**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.",
+            "**Premise carry-forward (do NOT re-author)** — brainstorm OWNS the premise check (right problem / direct path). 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.",
@@ -74,7 +74,9 @@ export const SCOPE = {
             "If the user says no but cannot name the change, offer concrete moves: keep scope, add one obvious adjacent capability, reduce to wedge, or re-open stack/product direction.",
             "Before final approval, record outside-voice findings and a `## Scope Outside Voice Loop` table per the Scope Outside Voice Loop policy above.",
             "**STOP.** Wait for explicit user approval of the scope mode and scope contract before writing final approval language or advancing.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` runs **AFTER user approval of the scope contract**, not before Q&A. Sequence is: Q&A loop -> propose contract -> user approval -> `planner` delegation -> `stage-complete`. If you delegate `planner` before the Q&A loop converges, you violate the elicitation contract and the linter will block stage-complete via `qa_log_unconverged`. Legal fulfillment modes for `planner`: (a) **harness-native Task tool** — run the delegation, then record the lifecycle row via `node .cclaw/hooks/delegation-record.mjs --stage=scope --agent=planner --mode=mandatory --status=completed --span-id=<uuid> --dispatch-surface=cursor-task --agent-definition-path=<agent-md-path> --evidence-ref=<artifact#section>` (the helper sets `fulfillmentMode: \"generic-dispatch\"` automatically); (b) **role-switch** — announce `## cclaw role-switch: scope/planner (mandatory)`, write the planner output/evidence into the scope artifact, then record the row with `--dispatch-surface=role-switch --agent-definition-path=<artifact-anchor>` (helper sets `fulfillmentMode: \"role-switch\"` automatically); (c) **cclaw subagent helper** if available, with `--dispatch-surface=isolated`. Run `node .cclaw/hooks/stage-complete.mjs scope` from the tool layer (do not paste the command into chat); report only the resulting summary."
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` runs **AFTER user approval of the scope contract**, not before Q&A. Sequence is: Q&A loop -> propose contract -> user approval -> `planner` delegation -> `stage-complete`. If you delegate `planner` before the Q&A loop converges, you violate the elicitation contract and the linter will block stage-complete via `qa_log_unconverged`. Legal fulfillment modes for `planner`: (a) **harness-native Task tool** — run the delegation, then record the lifecycle row via `node .cclaw/hooks/delegation-record.mjs --stage=scope --agent=planner --mode=mandatory --status=completed --span-id=<uuid> --dispatch-surface=cursor-task --agent-definition-path=<agent-md-path> --evidence-ref=<artifact#section>` (the helper sets `fulfillmentMode: \"generic-dispatch\"` automatically); (b) **role-switch** — announce `## cclaw role-switch: scope/planner (mandatory)`, write the planner output/evidence into the scope artifact, then record the row with `--dispatch-surface=role-switch --agent-definition-path=<artifact-anchor>` (helper sets `fulfillmentMode: \"role-switch\"` automatically); (c) **cclaw subagent helper** if available, with `--dispatch-surface=isolated`. Run `node .cclaw/hooks/stage-complete.mjs scope` from the tool layer (do not paste the command into chat); report only the resulting summary.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block (search -> graph/impact -> narrow read of 1-3 files -> draft); pass repo-relative paths and refs to any delegated planner/critic instead of pasting upstream content.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how this stage's `Scope Contract` must trace each row to a recorded user signal."
         ],
         process: [
             "Run pre-scope system audit (git log/diff/stash + debt-marker scan) — scope OWNS the repo audit; design will only diff the blast radius since this scope baseline.",

package/dist/content/stages/ship.js

@@ -59,7 +59,8 @@ export const SHIP = {
             "Document release notes and rollback plan explicitly.",
             decisionProtocolInstruction("finalization mode", "present modes as labeled options (A/B/C/D/E) with consequences, and mark one as (recommended)", "recommend the mode that best addresses release blast-radius, rollback readiness, observability, and stakeholder communication — ties go to the most reversible option"),
             "Do not proceed if critical blockers remain from review.",
-            "**STOP.** Present finalization options and wait for user selection before executing any finalization action."
+            "**STOP.** Present finalization options and wait for user selection before executing any finalization action.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors that `Preflight Results` cite fresh command output, exit codes, and the commit SHA from this turn."
         ],
         process: [
             "Validate review and test gates.",

package/dist/content/stages/spec.js

@@ -54,7 +54,9 @@ export const SPEC = {
             "**Chunk acceptance criteria for review.** When presenting the spec to the user for sign-off, deliver acceptance criteria in batches of 3-5 and **pause for explicit ACK** (via Decision Protocol) before sending the next batch. Do not dump the full criteria wall in one message — small batches surface objections earlier and keep the sign-off meaningful. Full spec writeup still lands in `04-spec.md`, but the conversation itself must be digestible.",
             "Require user confirmation on the written spec. **STOP.** Do NOT proceed to plan until user approves.",
             "For each criterion, ask: what exact evidence proves this passed? If the evidence or verification command/manual step is vague, rewrite.",
-            "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate non-critical interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity. STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user-approval uncertainty."
+            "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate non-critical interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity. STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user-approval uncertainty.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block — derive ACs from cited upstream paths/refs (`02-scope.md#R-2`, `03-design.md#DD-1`) instead of pasting their bodies into delegation prompts.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how each `Acceptance Criteria` row must carry an observable predicate plus the evidence path."
         ],
         process: [
             "Define measurable acceptance criteria.",

package/dist/content/stages/tdd.js

@@ -71,7 +71,9 @@ export const TDD = {
             "Use incremental RED/GREEN/REFACTOR commits when the repository workflow and working tree make that appropriate; otherwise record the checkpoint boundaries in the artifact.",
             "Stop if regressions appear and fix before proceeding.",
             "If a test passes unexpectedly, investigate: does the behavior already exist, or is the test wrong?",
-            "**Per-Slice Review point (conditional).** Check every slice against the triggers before declaring it DONE. Triggers: `touchCount >= filesChangedThreshold`, any `touchPaths` match a `touchTriggers` glob, or the plan row declares `highRisk: true`. On a trigger, run two passes on the slice alone — (1) Spec-Compliance: trace RED/GREEN/REFACTOR evidence back to its plan task + spec criterion, noting edge cases the tests skip; (2) Quality: diff-scan for naming, error handling, dead code, simpler alternatives. Record both under `## Per-Slice Review` in `06-tdd.md`, naming the trigger that fired. Dispatch the `reviewer` subagent natively when available (log `fulfillmentMode: \"isolated\"`); otherwise fulfil via in-session role switch (`fulfillmentMode: \"role-switch\"`). Never fabricate an isolated pass from memory."
+            "**Per-Slice Review point (conditional).** Check every slice against the triggers before declaring it DONE. Triggers: `touchCount >= filesChangedThreshold`, any `touchPaths` match a `touchTriggers` glob, or the plan row declares `highRisk: true`. On a trigger, run two passes on the slice alone — (1) Spec-Compliance: trace RED/GREEN/REFACTOR evidence back to its plan task + spec criterion, noting edge cases the tests skip; (2) Quality: diff-scan for naming, error handling, dead code, simpler alternatives. Record both under `## Per-Slice Review` in `06-tdd.md`, naming the trigger that fired. Dispatch the `reviewer` subagent natively when available (log `fulfillmentMode: \"isolated\"`); otherwise fulfil via in-session role switch (`fulfillmentMode: \"role-switch\"`). Never fabricate an isolated pass from memory.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block — `Watched-RED Proof` and `RED Evidence` rows must cite test paths and command logs, not pasted source bodies; delegate `test-author` with paths and refs only.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how `RED Evidence` must contain a falsifiable assertion (no tautologies)."
         ],
         process: [
             "Select one vertical slice and map it to acceptance criterion(s).",

package/dist/content/templates.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Shared investigation discipline block (Round 5 / v6.6.0). Rendered once per
+ * elicitation/spec stage skill (brainstorm, scope, design, spec, plan, tdd,
+ * review). The block enforces a four-step ladder before drafting and a
+ * path-passing rule for delegations so token cost and "jumped into code"
+ * regressions stay bounded. Stop-trigger count and ladder-step count are
+ * verified by `tests/unit/investigation-discipline-block.test.ts`.
+ */
+export declare const INVESTIGATION_DISCIPLINE_BLOCK = "## Investigation Discipline\n\nUse this ladder before drafting or delegating; do not jump straight to the editor.\n\n1. **Search** \u2014 locate the surface (file path, symbol, ref) before reading. Use `rg` / glob / graph; record the query, not the chunk.\n2. **Graph / impact** \u2014 name what the change touches (callers, callees, tests, configs) and its blast radius before opening a file.\n3. **Narrow read** \u2014 read at most 1-3 files, only the sections needed; cite paths with `:line` ranges instead of pasting bodies.\n4. **Draft** \u2014 only after the trace exists; the trace is the authority, not chat history or memory.\n\n**Path-passing in delegations.** When delegating, pass repo-relative paths and refs (e.g. `src/foo/bar.ts:42`, `D-12`, `AC-3`) \u2014 never the file body. The subagent re-reads from path; pasting content fragments breaks freshness and inflates tokens.\n\n**Stop triggers** (any one means halt and re-enter the ladder):\n\n- You are about to read more than 3 files in one pass.\n- You are about to load file content into a delegation prompt instead of paths or refs.\n- You are about to start a draft before any trace (search log, graph note, narrow-read citation) exists.\n";
 export declare const ARTIFACT_TEMPLATES: Record<string, string>;
 export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n- Follow flow order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\n- Require explicit user confirmation after plan before TDD\n- Keep evidence artifacts in `.cclaw/artifacts/`\n- Enforce RED before GREEN in TDD\n- Run two-layer review (spec_compliance and code_quality) before ship\n- Validate all inputs before processing \u2014 never trust external data without sanitization\n- Prefer immutable data patterns and pure functions where the language supports them\n- Follow existing repo conventions, patterns, and directory structure \u2014 match the codebase\n- Verify claims with fresh evidence: \"tests pass\" requires running tests in this message\n- Use conventional commits: `type(scope): description` (feat, fix, refactor, test, docs, chore)\n\n## MUST_NEVER\n- Skip RED phase and jump directly to GREEN in TDD\n- Ship with critical review findings\n- Start implementation during /brainstorm\n- Modify generated cclaw files manually when CLI can regenerate them\n- Commit `.cclaw/` or generated shim files\n- Expose secrets, tokens, API keys, or absolute system paths in agent output\n- Duplicate existing functionality without explicit justification \u2014 search before building\n- Bypass security checks, linting hooks, or type checking to \"move faster\"\n- Claim success (\"Done,\" \"All good,\" \"Tests pass\") without running verification in this message\n- Make changes outside the blast radius of the current task without user consent\n\n## DELEGATION\nWhen a task requires specialist knowledge (security audit, performance profiling, database review),\ndelegate to a specialized agent or skill if the harness supports it. The primary agent should:\n1. Identify the specialist domain\n2. Provide focused context (relevant files, the specific concern)\n3. Evaluate the specialist output before acting on it \u2014 do not blindly apply recommendations\n";
 /**

package/dist/content/templates.js

@@ -1,4 +1,5 @@
 import { CCLAW_VERSION, SHIP_FINALIZATION_MODES } from "../constants.js";
+import { renderBehaviorAnchorTemplateLine } from "./examples.js";
 import { orderedStageSchemas } from "./stage-schema.js";
 import { FLOW_STAGES } from "../types.js";
 const SHIP_FINALIZATION_ENUM_LINES = SHIP_FINALIZATION_MODES.map((mode) => `  - ${mode}`).join("\n");
@@ -17,11 +18,38 @@ const SEED_SHELF_SECTION = `## Seed Shelf Candidates (optional)
 | Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
 |---|---|---|---|
 | .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |`;
+/**
+ * Shared investigation discipline block (Round 5 / v6.6.0). Rendered once per
+ * elicitation/spec stage skill (brainstorm, scope, design, spec, plan, tdd,
+ * review). The block enforces a four-step ladder before drafting and a
+ * path-passing rule for delegations so token cost and "jumped into code"
+ * regressions stay bounded. Stop-trigger count and ladder-step count are
+ * verified by `tests/unit/investigation-discipline-block.test.ts`.
+ */
+export const INVESTIGATION_DISCIPLINE_BLOCK = `## Investigation Discipline
+
+Use this ladder before drafting or delegating; do not jump straight to the editor.
+
+1. **Search** — locate the surface (file path, symbol, ref) before reading. Use \`rg\` / glob / graph; record the query, not the chunk.
+2. **Graph / impact** — name what the change touches (callers, callees, tests, configs) and its blast radius before opening a file.
+3. **Narrow read** — read at most 1-3 files, only the sections needed; cite paths with \`:line\` ranges instead of pasting bodies.
+4. **Draft** — only after the trace exists; the trace is the authority, not chat history or memory.
+
+**Path-passing in delegations.** When delegating, pass repo-relative paths and refs (e.g. \`src/foo/bar.ts:42\`, \`D-12\`, \`AC-3\`) — never the file body. The subagent re-reads from path; pasting content fragments breaks freshness and inflates tokens.
+
+**Stop triggers** (any one means halt and re-enter the ladder):
+
+- You are about to read more than 3 files in one pass.
+- You are about to load file content into a delegation prompt instead of paths or refs.
+- You are about to start a draft before any trace (search log, graph note, narrow-read citation) exists.
+`;
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `${artifactFrontmatter("brainstorm")}
 
 # Brainstorm Artifact
 
+${renderBehaviorAnchorTemplateLine("brainstorm")}
+
 ## Mode Block
 - **Mode:** STARTUP | BUILDER | ENGINEERING | OPS | RESEARCH (pick exactly one)
 - **Why this mode:** (one line; cite a concrete signal — repo state, user prompt, ownership, risk window)
@@ -61,7 +89,6 @@ export const ARTIFACT_TEMPLATES = {
 ## Premise Check
 - **Right problem?** (yes/no + one-line justification — take a position)
 - **Direct path?** (yes/no + one-line justification)
-- **What if we do nothing?** (concrete consequence, not "nothing happens")
 
 ## How Might We
 - *How might we …?* — one line naming the user, the desired outcome, and the binding constraint.
@@ -89,7 +116,7 @@ export const ARTIFACT_TEMPLATES = {
 | 1 |  |  | scope-shaping [topic:pain] |
 
 > Append-only by turn. Add one row after each user answer; do not rewrite prior rows.
-> **Topic tag is MANDATORY for forcing-question rows.** Stamp \`[topic:<id>]\` in the \`Decision impact\` cell so the linter can verify coverage in any natural language (RU/EN/UA/etc.). Brainstorm IDs: \`pain\`, \`direct-path\`, \`do-nothing\`, \`operator\`, \`no-go\`. Multiple tags allowed when one answer covers several topics. Stop-signal rows do NOT need a tag. Wave 24 (v6.0.0) removed the English keyword fallback.
+> **Topic tag is MANDATORY for forcing-question rows.** Stamp \`[topic:<id>]\` in the \`Decision impact\` cell so the linter can verify coverage in any natural language (RU/EN/UA/etc.). Brainstorm IDs: \`pain\`, \`direct-path\`, \`operator\`, \`no-go\`. Multiple tags allowed when one answer covers several topics. Stop-signal rows do NOT need a tag. Wave 24 (v6.0.0) removed the English keyword fallback; Round 6 (v6.7.0) retired the counterfactual \`do-nothing\` topic (Do-nothing consequence stays in the Problem Decision Record).
 
 ## Approach Tier
 - Tier: lite | standard | deep
@@ -200,6 +227,8 @@ ${MARKDOWN_CODE_FENCE}
 
 # Scope Artifact
 
+${renderBehaviorAnchorTemplateLine("scope")}
+
 ## Upstream Handoff
 - Source artifacts: \`00-idea.md\`, \`01-brainstorm-<slug>.md\`
 - Decisions carried forward:
@@ -434,6 +463,8 @@ ${MARKDOWN_CODE_FENCE}
 
 # Design Artifact
 
+${renderBehaviorAnchorTemplateLine("design")}
+
 ## Compact-First Scaffold
 - Default to the compact design spine unless risk requires Standard/Deep add-ons.
 - Compact required spine: Upstream Handoff, Codebase Investigation, Engineering Lock, Architecture Boundaries, Architecture Diagram, Data Flow, Failure Mode Table, Test Strategy, Spec Handoff, and Completion Dashboard.
@@ -698,6 +729,8 @@ ${MARKDOWN_CODE_FENCE}
 
 # Specification Artifact
 
+${renderBehaviorAnchorTemplateLine("spec")}
+
 ## Upstream Handoff
 - Source artifacts: standard uses \`02-scope-<slug>.md\` + \`03-design-<slug>.md\`; medium uses \`01-brainstorm-<slug>.md\` when present; quick uses \`00-idea.md\` plus reproduction context.
 - Decisions carried forward:
@@ -797,6 +830,8 @@ ${MARKDOWN_CODE_FENCE}
 
 # Plan Artifact
 
+${renderBehaviorAnchorTemplateLine("plan")}
+
 ## Plan Header
 - **Goal:** (one sentence — what this plan delivers)
 - **Architecture:** (2-3 sentences — approach + key boundaries)
@@ -912,12 +947,14 @@ Execution rule: complete and verify each batch before starting the next batch.
 - **Inline recipe (if Inline executor):** TDD loop unit-by-unit with batch checkpoints
 
 ## Plan Quality Scan
+<!-- linter-meta -->
 - Placeholder scan:
   - Scanned tokens: \`TODO\`, \`TBD\`, \`FIXME\`, \`<fill-in>\`, \`<your-*-here>\`, \`xxx\`, bare ellipsis in task rows.
   - Hits: 0 (required for WAIT_FOR_CONFIRM to resolve).
 - Scope reduction language scan:
   - Scanned phrases: \`v1\`, \`for now\`, \`later\`, \`temporary\`, \`placeholder\`, \`mock for now\`, \`hardcoded for now\`, \`will improve later\`.
   - Hits: 0 (required when Locked Decisions section is non-empty; reference D-XX IDs from scope).
+<!-- /linter-meta -->
 
 ## WAIT_FOR_CONFIRM
 - Status: pending
@@ -930,6 +967,8 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 # TDD Artifact
 
+${renderBehaviorAnchorTemplateLine("tdd")}
+
 ## Upstream Handoff
 - Source artifacts: \`04-spec.md\` plus the active track's upstream source item (plan slice on standard/medium, spec acceptance item or bug reproduction slice on quick).
 - Decisions carried forward:
@@ -1126,6 +1165,8 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 # Review Artifact
 
+${renderBehaviorAnchorTemplateLine("review")}
+
 ## Upstream Handoff
 - Source artifacts: \`04-spec.md\`, \`06-tdd.md\`, plus the active track's upstream source item when available.
 - Decisions carried forward:
@@ -1298,6 +1339,8 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 # Ship Artifact
 
+${renderBehaviorAnchorTemplateLine("ship")}
+
 ## Upstream Handoff
 - Source artifacts: \`06-tdd.md\`, \`07-review.md\`
 - Decisions carried forward:

package/dist/delegation.d.ts

@@ -60,6 +60,15 @@ export type DelegationEntry = {
     taskId?: string;
     waiverReason?: string;
     acceptedBy?: DelegationWaiverAcceptedBy;
+    /**
+     * Waiver approval token captured from `cclaw-cli internal waiver-grant`.
+     * Present on waiver rows written after v6.7.0. Legacy waiver rows omit
+     * these fields and are surfaced as the advisory linter finding
+     * `waiver_legacy_provenance`.
+     */
+    approvalToken?: string;
+    approvalReason?: string;
+    approvalIssuedAt?: string;
     ts?: string;
     /**
      * Run id the entry belongs to. Older ledgers written before 0.5.17 may omit this;

package/dist/delegation.js

@@ -199,6 +199,9 @@ function isDelegationEntry(value) {
         (o.taskId === undefined || typeof o.taskId === "string") &&
         (o.waiverReason === undefined || typeof o.waiverReason === "string") &&
         (o.acceptedBy === undefined || o.acceptedBy === "user-flag") &&
+        (o.approvalToken === undefined || typeof o.approvalToken === "string") &&
+        (o.approvalReason === undefined || typeof o.approvalReason === "string") &&
+        (o.approvalIssuedAt === undefined || typeof o.approvalIssuedAt === "string") &&
         waiverOk &&
         (o.runId === undefined || typeof o.runId === "string") &&
         (o.fulfillmentMode === undefined ||

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

@@ -12,6 +12,7 @@ import { extractReviewLoopEnvelopeFromArtifact } from "../../content/review-loop
 import { unique } from "./helpers.js";
 import { AUTO_REVIEW_LOOP_GATE_BY_STAGE, reviewLoopArtifactFixHint, reviewLoopEnvelopeExample, validateGateEvidenceShape } from "./review-loop.js";
 import { ensureProactiveDelegationTrace } from "./proactive-delegation-trace.js";
+import { consumeWaiverToken } from "../waiver-grant.js";
 function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGuards, selectedTransitionGuards) {
     const natural = transitionTargets[0] ?? null;
     const specialTargets = transitionTargets.filter((target) => target !== natural);
@@ -542,9 +543,30 @@ export async function runAdvanceStage(projectRoot, args, io) {
         }
         return 1;
     }
+    let approvalRecord = null;
+    if (args.acceptProactiveWaiver) {
+        const tokenRaw = args.acceptProactiveWaiverToken?.trim() ?? "";
+        if (tokenRaw.length === 0) {
+            io.stderr.write(`cclaw internal advance-stage: --accept-proactive-waiver now requires =<token>. Run \`cclaw-cli internal waiver-grant --stage ${args.stage} --reason "<why safe>"\` to issue one, then rerun with --accept-proactive-waiver=<token>.\n`);
+            return 2;
+        }
+        const consumed = await consumeWaiverToken(projectRoot, {
+            stage: args.stage,
+            token: tokenRaw,
+            consumedBy: "advance-stage"
+        });
+        if (!consumed.ok) {
+            io.stderr.write(`cclaw internal advance-stage: waiver token rejected (${consumed.reason}): ${consumed.detail}. Issue a fresh token via \`cclaw-cli internal waiver-grant --stage ${args.stage} --reason "<why safe>"\`.\n`);
+            return 2;
+        }
+        approvalRecord = consumed.record;
+    }
     const proactiveTrace = await ensureProactiveDelegationTrace(projectRoot, args.stage, {
         acceptWaiver: args.acceptProactiveWaiver,
         waiverReason: args.acceptProactiveWaiverReason,
+        approvalToken: approvalRecord?.token,
+        approvalReason: approvalRecord?.reason,
+        approvalIssuedAt: approvalRecord?.issuedAt,
         discoveryMode: flowState.discoveryMode,
         repoSignals: flowState.repoSignals
     });
@@ -600,7 +622,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
         currentStage: successor ?? args.stage,
         interactionHints
     };
-    await writeFlowState(projectRoot, finalState);
+    await writeFlowState(projectRoot, finalState, { writerSubsystem: "advance-stage" });
     if (args.quiet) {
         io.stdout.write(`${JSON.stringify({
             ok: true,

package/dist/internal/advance-stage/parsers.d.ts

@@ -8,6 +8,14 @@ export interface AdvanceStageArgs {
     waiverReason?: string;
     acceptProactiveWaiver: boolean;
     acceptProactiveWaiverReason?: string;
+    /**
+     * Approval token issued by `cclaw-cli internal waiver-grant`. Required
+     * (via `--accept-proactive-waiver=<token>`) whenever the caller asserts
+     * `acceptProactiveWaiver`. Legacy `--accept-proactive-waiver` without a
+     * token is still parsed but rejected downstream by the advance-stage
+     * handler so operators see the error at runtime.
+     */
+    acceptProactiveWaiverToken?: string;
     skipQuestions: boolean;
     quiet: boolean;
     json: boolean;

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

@@ -12,6 +12,7 @@ export function parseAdvanceStageArgs(tokens) {
     let waiverReason;
     let acceptProactiveWaiver = false;
     let acceptProactiveWaiverReason;
+    let acceptProactiveWaiverToken;
     let skipQuestions = false;
     let quiet = false;
     let json = false;
@@ -81,6 +82,11 @@ export function parseAdvanceStageArgs(tokens) {
             acceptProactiveWaiver = true;
             continue;
         }
+        if (token.startsWith("--accept-proactive-waiver=")) {
+            acceptProactiveWaiver = true;
+            acceptProactiveWaiverToken = token.slice("--accept-proactive-waiver=".length).trim();
+            continue;
+        }
         if (token === "--skip-questions") {
             skipQuestions = true;
             continue;
@@ -107,6 +113,7 @@ export function parseAdvanceStageArgs(tokens) {
         waiverReason,
         acceptProactiveWaiver,
         acceptProactiveWaiverReason,
+        acceptProactiveWaiverToken,
         skipQuestions,
         quiet,
         json

package/dist/internal/advance-stage/proactive-delegation-trace.d.ts

@@ -16,6 +16,9 @@ export interface ProactiveDelegationTraceResult {
 export declare function ensureProactiveDelegationTrace(projectRoot: string, stage: FlowStage, options: {
     acceptWaiver: boolean;
     waiverReason?: string;
+    approvalToken?: string;
+    approvalReason?: string;
+    approvalIssuedAt?: string;
     discoveryMode: DiscoveryMode;
     repoSignals?: RepoSignals;
 }): Promise<ProactiveDelegationTraceResult>;

package/dist/internal/advance-stage/proactive-delegation-trace.js

@@ -31,7 +31,11 @@ export async function ensureProactiveDelegationTrace(projectRoot, stage, options
         return { missingRules: [] };
     if (!options.acceptWaiver)
         return { missingRules };
-    const waiverReason = options.waiverReason?.trim() || "accepted via --accept-proactive-waiver";
+    const approvalToken = options.approvalToken?.trim();
+    const approvalReason = options.approvalReason?.trim();
+    const waiverReason = options.waiverReason?.trim() ||
+        approvalReason ||
+        "accepted via --accept-proactive-waiver";
     for (const rule of missingRules) {
         await appendDelegation(projectRoot, {
             stage,
@@ -42,6 +46,9 @@ export async function ensureProactiveDelegationTrace(projectRoot, stage, options
             acceptedBy: "user-flag",
             conditionTrigger: rule.when,
             skill: rule.skill,
+            ...(approvalToken ? { approvalToken } : {}),
+            ...(approvalReason ? { approvalReason } : {}),
+            ...(options.approvalIssuedAt ? { approvalIssuedAt: options.approvalIssuedAt } : {}),
             ts: new Date().toISOString()
         });
     }

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

@@ -40,7 +40,7 @@ export async function runRewind(projectRoot, args, io) {
         const staleStages = { ...current.staleStages };
         delete staleStages[args.targetStage];
         const nextState = { ...current, staleStages };
-        await writeFlowState(projectRoot, nextState);
+        await writeFlowState(projectRoot, nextState, { writerSubsystem: "rewind-ack" });
         const payload = {
             ok: true,
             command: "rewind",
@@ -85,7 +85,7 @@ export async function runRewind(projectRoot, args, io) {
         staleStages,
         rewinds: [...current.rewinds, record]
     };
-    await writeFlowState(projectRoot, nextState);
+    await writeFlowState(projectRoot, nextState, { writerSubsystem: "rewind" });
     const payload = {
         ok: true,
         command: "rewind",

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

@@ -209,7 +209,10 @@ export async function runStartFlow(projectRoot, args, io) {
     }
     const repoSignals = await collectRepoSignals(projectRoot);
     nextState = { ...nextState, repoSignals };
-    await writeFlowState(projectRoot, nextState, { allowReset: true });
+    await writeFlowState(projectRoot, nextState, {
+        allowReset: true,
+        writerSubsystem: "start-flow"
+    });
     await appendIdeaArtifact(projectRoot, args, current);
     const successPayload = {
         ok: true,