cclaw-cli 6.6.0 → 6.7.0

package/dist/content/skills-elicitation.js

@@ -29,7 +29,7 @@ Pinned anchor: "Don't tell it what to do, give it success criteria and watch it
 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.
+- **Good**: User asks for a "simple web app" -> agent asks Q1 (what pain) -> Q2 (direct path) -> Q3 (first operator/user) -> Q4 (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.
@@ -121,7 +121,7 @@ Default mapping note: \`lean\` maps to a lightweight specialist tier on early st
 
 ### Topic tagging (MANDATORY for forcing-question rows)
 
-Each forcing question has a stable topic id (kebab-case ASCII, e.g. \`pain\`, \`do-nothing\`, \`data-flow\`). Tag the matching Q&A Log row's \`Decision impact\` cell with \`[topic:<id>]\` so the linter can verify coverage in any natural language. This is a **HARD requirement** in Wave 24 (v6.0.0): the linter no longer keyword-matches English question prose, so an un-tagged row does NOT count toward coverage even if the answer fully addresses the topic.
+Each forcing question has a stable topic id (kebab-case ASCII, e.g. \`pain\`, \`direct-path\`, \`data-flow\`). Tag the matching Q&A Log row's \`Decision impact\` cell with \`[topic:<id>]\` so the linter can verify coverage in any natural language. This is a **HARD requirement** in Wave 24 (v6.0.0): the linter no longer keyword-matches English question prose, so an un-tagged row does NOT count toward coverage even if the answer fully addresses the topic.
 
 RU example (after asking \`pain\` in Russian):
 
@@ -131,21 +131,18 @@ RU example (after asking \`pain\` in Russian):
 | 1 | Какую боль мы решаем? | Регистрация занимает 30 минут. | scope-shaping [topic:pain] |
 \`\`\`
 
-Multiple tags in one row are allowed when one answer covers several topics: \`[topic:pain] [topic:do-nothing]\`. Stop-signal rows do NOT need a tag.
+Multiple tags in one row are allowed when one answer covers several topics: \`[topic:pain] [topic:direct-path]\`. Stop-signal rows do NOT need a tag.
 
 Stage forcing question lists (id → topic):
 
 - **Brainstorm**:
   - \`pain\` — What pain are we solving?
   - \`direct-path\` — What is the most direct path?
-  - \`do-nothing\` — What happens if we do nothing?
   - \`operator\` — Who is the operator/user impacted first?
   - \`no-go\` — What are non-negotiable no-go boundaries?
 - **Scope**:
   - \`in-out\` — What is definitely in and definitely out?
   - \`locked-upstream\` — Which decisions are already locked upstream?
-  - \`rollback\` — What is the rollback path if this fails?
-  - \`failure-modes\` — What are the top failure modes we must design for?
 - **Design**:
   - \`data-flow\` — What is the data flow end-to-end?
   - \`seams\` — Where are the seams/interfaces and ownership boundaries?

package/dist/content/skills.js

@@ -430,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,7 +62,7 @@ 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.",
@@ -142,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/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.",

package/dist/content/templates.js

@@ -89,7 +89,6 @@ ${renderBehaviorAnchorTemplateLine("brainstorm")}
 ## 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.
@@ -117,7 +116,7 @@ ${renderBehaviorAnchorTemplateLine("brainstorm")}
 | 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
@@ -948,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

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,

package/dist/internal/advance-stage.js

@@ -11,13 +11,33 @@ import { runRewind } from "./advance-stage/rewind.js";
 import { runVerifyFlowStateDiff, runVerifyCurrentState } from "./advance-stage/verify.js";
 import { runHookCommand } from "./advance-stage/hook.js";
 import { parseAdvanceStageArgs, parseCancelRunArgs, parseHookArgs, parseRewindArgs, parseStartFlowArgs, parseVerifyCurrentStateArgs, parseVerifyFlowStateDiffArgs } from "./advance-stage/parsers.js";
+import { parseFlowStateRepairArgs, runFlowStateRepair } from "./flow-state-repair.js";
+import { parseWaiverGrantArgs, runWaiverGrant } from "./waiver-grant.js";
+import { FlowStateGuardMismatchError, verifyFlowStateGuard } from "../run-persistence.js";
+/**
+ * Subcommands that mutate or consult flow-state.json via the CLI runtime.
+ * They all require the sha256 sidecar to match before continuing so a
+ * manual edit hard-blocks with exit code 2 (same contract as the inline
+ * hook checks).
+ */
+const GUARD_ENFORCED_SUBCOMMANDS = new Set([
+    "advance-stage",
+    "start-flow",
+    "cancel-run",
+    "rewind",
+    "verify-flow-state-diff",
+    "verify-current-state"
+]);
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant\n");
         return 1;
     }
     try {
+        if (GUARD_ENFORCED_SUBCOMMANDS.has(subcommand)) {
+            await verifyFlowStateGuard(projectRoot);
+        }
         if (subcommand === "advance-stage") {
             return await runAdvanceStage(projectRoot, parseAdvanceStageArgs(tokens), io);
         }
@@ -57,10 +77,20 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook\n`);
+        if (subcommand === "flow-state-repair") {
+            return await runFlowStateRepair(projectRoot, parseFlowStateRepairArgs(tokens), io);
+        }
+        if (subcommand === "waiver-grant") {
+            return await runWaiverGrant(projectRoot, parseWaiverGrantArgs(tokens), io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant\n`);
         return 1;
     }
     catch (err) {
+        if (err instanceof FlowStateGuardMismatchError) {
+            io.stderr.write(`cclaw internal ${subcommand}: ${err.message}\n`);
+            return 2;
+        }
         io.stderr.write(`cclaw internal ${subcommand} failed: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }

package/dist/internal/flow-state-repair.d.ts

@@ -0,0 +1,13 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export interface FlowStateRepairArgs {
+    reason: string;
+    json: boolean;
+    quiet: boolean;
+}
+export declare function parseFlowStateRepairArgs(tokens: string[]): FlowStateRepairArgs;
+export declare function runFlowStateRepair(projectRoot: string, args: FlowStateRepairArgs, io: InternalIo): Promise<number>;
+export {};

package/dist/internal/flow-state-repair.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { RUNTIME_ROOT } from "../constants.js";
+import { repairFlowStateGuard } from "../run-persistence.js";
+export function parseFlowStateRepairArgs(tokens) {
+    let reason;
+    let json = false;
+    let quiet = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const nextToken = tokens[i + 1];
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--reason") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--reason requires a short slug value.");
+            }
+            reason = nextToken.trim();
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--reason=")) {
+            reason = token.slice("--reason=".length).trim();
+            continue;
+        }
+        throw new Error(`Unknown flag for internal flow-state-repair: ${token}`);
+    }
+    if (!reason || reason.length === 0) {
+        throw new Error("internal flow-state-repair requires --reason=<slug> (e.g. --reason=manual_edit_recovery).");
+    }
+    return { reason, json, quiet };
+}
+export async function runFlowStateRepair(projectRoot, args, io) {
+    const result = await repairFlowStateGuard(projectRoot, args.reason);
+    const logRel = path.relative(projectRoot, result.repairLogPath).replace(/\\/gu, "/");
+    const guardRel = path.relative(projectRoot, result.guardPath).replace(/\\/gu, "/");
+    if (args.json) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "flow-state-repair",
+            reason: args.reason,
+            sidecar: result.sidecar,
+            guardPath: guardRel,
+            repairLogPath: logRel,
+            runtimeRoot: RUNTIME_ROOT
+        })}\n`);
+        return 0;
+    }
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "flow-state-repair",
+            reason: args.reason,
+            sidecar: result.sidecar,
+            guardPath: guardRel,
+            repairLogPath: logRel
+        }, null, 2)}\n`);
+    }
+    return 0;
+}

package/dist/internal/waiver-grant.d.ts

@@ -0,0 +1,62 @@
+import { type FlowStage } from "../types.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare const WAIVER_TOKEN_DEFAULT_TTL_MINUTES = 30;
+export declare const WAIVER_TOKEN_MAX_TTL_MINUTES = 120;
+export declare const WAIVER_REASON_PATTERN: RegExp;
+export interface WaiverRecord {
+    token: string;
+    stage: FlowStage;
+    reason: string;
+    issuedAt: string;
+    expiresAt: string;
+    consumedAt: string | null;
+    issuerSubsystem: string;
+    consumedBy?: string;
+}
+export interface WaiverLedger {
+    schemaVersion: number;
+    pending: WaiverRecord[];
+    consumed: WaiverRecord[];
+}
+export interface IssueWaiverTokenOptions {
+    stage: FlowStage;
+    reason: string;
+    expiresInMinutes?: number;
+    issuerSubsystem?: string;
+    now?: Date;
+}
+export interface ConsumeWaiverOptions {
+    stage: FlowStage;
+    token: string;
+    consumedBy?: string;
+    now?: Date;
+}
+export declare function formatWaiverToken(stage: FlowStage, fingerprint: string, expiresAt: Date): string;
+export declare function issueWaiverToken(projectRoot: string, options: IssueWaiverTokenOptions): Promise<WaiverRecord>;
+export type ConsumeWaiverFailureReason = "not-found" | "wrong-stage" | "expired" | "already-consumed";
+export interface ConsumeWaiverSuccess {
+    ok: true;
+    record: WaiverRecord;
+}
+export interface ConsumeWaiverFailure {
+    ok: false;
+    reason: ConsumeWaiverFailureReason;
+    record?: WaiverRecord;
+    detail: string;
+}
+export type ConsumeWaiverResult = ConsumeWaiverSuccess | ConsumeWaiverFailure;
+export declare function consumeWaiverToken(projectRoot: string, options: ConsumeWaiverOptions): Promise<ConsumeWaiverResult>;
+export interface WaiverGrantArgs {
+    stage: FlowStage;
+    reason: string;
+    ttlMinutes: number;
+    json: boolean;
+    quiet: boolean;
+}
+export declare function parseWaiverGrantArgs(tokens: string[]): WaiverGrantArgs;
+export declare function runWaiverGrant(projectRoot: string, args: WaiverGrantArgs, io: InternalIo): Promise<number>;
+export {};