cclaw-cli 0.43.0 → 0.44.0

package/README.md

@@ -140,7 +140,7 @@ Plus harness-specific shims:
 `cclaw init` writes five keys, on purpose:
 
 ```yaml
-version: 0.43.0
+version: 0.44.0
 flowVersion: 1.0.0
 harnesses:
   - codex

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import type { FlowTrack, HarnessId } from "./types.js";
 import type { EvalMode } from "./eval/types.js";
-type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive" | "eval";
+type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive" | "eval" | "internal";
 interface ParsedArgs {
     command?: CommandName;
     harnesses?: HarnessId[];
@@ -33,6 +33,8 @@ interface ParsedArgs {
     evalArgs?: string[];
     evalBackground?: boolean;
     evalCompareModel?: string;
+    /** Hidden plumbing command (`cclaw internal ...`) arguments. */
+    internalArgs?: string[];
     showHelp?: boolean;
     showVersion?: boolean;
 }

package/dist/cli.js

@@ -24,6 +24,7 @@ import { formatDiffMarkdown, runEvalDiff } from "./eval/diff.js";
 import { ensureRunDir, generateRunId, isRunAlive, listRuns, readRunStatus, resolveRunId, runLogPath, writeRunStatus } from "./eval/runs.js";
 import { parseModeInput } from "./eval/mode.js";
 import { FLOW_STAGES } from "./types.js";
+import { runInternalCommand } from "./internal/advance-stage.js";
 const INSTALLER_COMMANDS = [
     "init",
     "sync",
@@ -31,7 +32,8 @@ const INSTALLER_COMMANDS = [
     "upgrade",
     "uninstall",
     "archive",
-    "eval"
+    "eval",
+    "internal"
 ];
 export function usage() {
     return `cclaw - installer-first flow toolkit
@@ -418,6 +420,12 @@ function parseArgs(argv) {
     parsed.command = INSTALLER_COMMANDS.includes(commandRaw)
         ? commandRaw
         : undefined;
+    // Hidden maintainer surface for runtime guards/helpers. Keep raw positional
+    // args untouched so subcommand-level parsing can evolve independently.
+    if (parsed.command === "internal") {
+        parsed.internalArgs = [...rest];
+        return parsed;
+    }
     // For `eval`, the next non-flag argument is an optional subcommand. Any
     // subsequent non-flag tokens are captured as evalArgs (consumed by the
     // subcommand handler). This preserves backwards compat: callers that run
@@ -796,6 +804,9 @@ async function runCommand(parsed, ctx) {
     if (!command) {
         return printNoArgsHint(ctx);
     }
+    if (command === "internal") {
+        return runInternalCommand(ctx.cwd, parsed.internalArgs ?? [], ctx);
+    }
     if (command === "init") {
         const resolved = await resolveInitInputs(parsed, ctx);
         const effectiveTrack = resolved.track;

package/dist/content/harness-playbooks.js

@@ -232,10 +232,12 @@ Codex CLI has a different shape from Claude/Cursor:
 - **Tool interception is Bash-only.** Codex's \`PreToolUse\` and
   \`PostToolUse\` events only fire for the \`Bash\` tool. \`Write\`,
   \`Edit\`, \`WebSearch\`, and MCP tool calls are **not** gated by hooks.
-  cclaw partially compensates by also wiring \`UserPromptSubmit\` to
-  \`prompt-guard.sh\` so the stage routing check fires before the turn
-  executes, but workflow-guard (TDD red-first, artifact presence) only
-  fires on Bash turns. See the hook coverage matrix below.
+  cclaw partially compensates by wiring \`UserPromptSubmit\` to both
+  \`prompt-guard.sh\` and a non-blocking
+  \`cclaw internal verify-current-state --quiet\` nudge that emits
+  unmet-delegation / missing-evidence warnings before the turn executes.
+  This is still a nudge, not a hard block: workflow-guard (TDD red-first,
+  artifact presence) only fires on Bash turns. See the hook coverage matrix below.
 - **Legacy paths.** \`.codex/commands/*\` was never consumed by Codex and
   is removed on every \`cclaw sync\`. The v0.39.x \`.agents/skills/cclaw-cc*/\`
   layout is replaced by \`.agents/skills/cc*/\` and the old folders are
@@ -289,6 +291,8 @@ disabled in v0.33 and remains off.
 - \`/use cc\` — open the \`/cc\` skill and pick a track.
 - \`/use cc-next\` — advance the flow one stage.
 - \`/use cc-ops\` — compound / archive / rewind.
+- \`bash .cclaw/hooks/stage-complete.sh <stage>\` — canonical stage closeout helper;
+  validates delegations + gate evidence before mutating \`flow-state.json\`.
 - Typing \`/cc …\` or \`/cc-next …\` in plain text also works: Codex
   matches the skill descriptions (which spell out these tokens) and
   auto-loads the right skill body.
@@ -316,6 +320,7 @@ continue to work regardless.
 |-------------|---------------|----------|
 | SessionStart rehydration | \`SessionStart\` matcher \`startup|resume\` → \`session-start.sh\` | Full. |
 | PreToolUse prompt-guard | \`PreToolUse\` matcher \`Bash\` + \`UserPromptSubmit\` → \`prompt-guard.sh\` | Bash tool calls are gated inline; \`UserPromptSubmit\` catches prompts before any tool fires, so non-Bash writes (\`Write\`/\`Edit\`) are still prompt-guarded at the turn boundary. |
+| UserPromptSubmit state nudge | \`UserPromptSubmit\` → \`cclaw internal verify-current-state --quiet\` | Non-blocking warning only. Prints unmet mandatory delegation / gate-evidence counts before the turn; cannot block non-Bash \`Write\`/\`Edit\`. |
 | PreToolUse workflow-guard | \`PreToolUse\` matcher \`Bash\` → \`workflow-guard.sh\` | Bash-only. For \`Write\`/\`Edit\` calls the agent performs the TDD-order / artifact check in-turn (see the stage skill). |
 | PostToolUse context-monitor | \`PostToolUse\` matcher \`Bash\` → \`context-monitor.sh\` | Bash-only. Other tool calls get context-monitored at end-of-turn via \`.cclaw/references/protocols/ethos.md\`. |
 | Stop checkpoint | \`Stop\` → \`stop-checkpoint.sh\` | Full. |

package/dist/content/harnesses-doc.js

@@ -68,6 +68,11 @@ ${hookRows}
 - \`tier1\`: full native delegation + structured asks + full hook surface.
 - \`tier2\`: usable flow with capability gaps; mandatory delegation can require waivers.
 - \`tier3\`: manual-only fallback; no native automation guarantees.
+- Codex-specific ceiling: \`PreToolUse\` can only intercept \`Bash\`. Direct
+  \`Write\`/\`Edit\` to \`.cclaw/state/flow-state.json\` cannot be hard-blocked
+  at hook level, so the canonical path is
+  \`bash .cclaw/hooks/stage-complete.sh <stage>\` plus the non-blocking
+  \`UserPromptSubmit\` state nudge.
 
 ## Shared command contract
 

package/dist/content/hooks.d.ts

@@ -11,6 +11,7 @@ export interface HookRuntimeOptions {
 export declare const RUNTIME_SHELL_DETECT_ROOT = "HARNESS=\"codex\"\nif [ -n \"${CLAUDE_PROJECT_DIR:-}\" ]; then\n  HARNESS=\"claude\"\nelif [ -n \"${CURSOR_PROJECT_DIR:-}\" ] || [ -n \"${CURSOR_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"cursor\"\nelif [ -n \"${OPENCODE_PROJECT_DIR:-}\" ] || [ -n \"${OPENCODE_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"opencode\"\nfi\n\nROOT=\"\"\nfor candidate in \"${CCLAW_PROJECT_ROOT:-}\" \"${CLAUDE_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_ROOT:-}\" \"${OPENCODE_PROJECT_DIR:-}\" \"${OPENCODE_PROJECT_ROOT:-}\" \"${PWD:-}\"; do\n  if [ -n \"$candidate\" ] && [ -d \"$candidate/.cclaw\" ]; then\n    ROOT=\"$candidate\"\n    break\n  fi\ndone\nif [ -z \"$ROOT\" ]; then\n  ROOT=\"${CCLAW_PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-${CURSOR_PROJECT_ROOT:-${OPENCODE_PROJECT_DIR:-${OPENCODE_PROJECT_ROOT:-${PWD}}}}}}}\"\nfi";
 export declare function sessionStartScript(_options?: HookRuntimeOptions): string;
 export declare function stopCheckpointScript(): string;
+export declare function stageCompleteScript(): string;
 export declare function preCompactScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";

package/dist/content/hooks.js

@@ -769,6 +769,35 @@ case "$HARNESS" in
 esac
 `;
 }
+export function stageCompleteScript() {
+    return `#!/usr/bin/env bash
+# cclaw stage-complete helper — generated by cclaw sync
+# Canonical helper for stage closeout: delegates validation + flow-state
+# mutation to \`cclaw internal advance-stage\`.
+set -euo pipefail
+
+${DETECT_ROOT}
+
+if [ "$#" -lt 1 ]; then
+  printf 'Usage: bash ${RUNTIME_ROOT}/hooks/stage-complete.sh <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...]\\n' >&2
+  exit 1
+fi
+
+if [ ! -d "$ROOT/${RUNTIME_ROOT}" ]; then
+  printf '[cclaw] stage-complete: runtime root not found at %s\\n' "$ROOT/${RUNTIME_ROOT}" >&2
+  exit 1
+fi
+
+STAGE="$1"
+shift || true
+
+if command -v cclaw >/dev/null 2>&1; then
+  exec cclaw internal advance-stage "$STAGE" "$@"
+fi
+
+exec npx -y cclaw-cli internal advance-stage "$STAGE" "$@"
+`;
+}
 export function preCompactScript() {
     return `#!/usr/bin/env bash
 # cclaw pre-compact hook — generated by cclaw sync
@@ -1109,14 +1138,15 @@ export default function cclawPlugin(ctx) {
     const scriptPath = join(root, "${RUNTIME_ROOT}/hooks/" + scriptFileName);
     const input = typeof payload === "string" ? payload : JSON.stringify(payload ?? {});
     try {
-      spawnSync("bash", [scriptPath], {
+      const result = spawnSync("bash", [scriptPath], {
         cwd: root,
         timeout: 20000,
         stdio: ["pipe", "ignore", "ignore"],
         input
       });
+      return typeof result.status === "number" ? result.status === 0 : false;
     } catch {
-      // advisory-only runtime path
+      return false;
     }
   }
 
@@ -1167,8 +1197,13 @@ export default function cclawPlugin(ctx) {
       }
       if (eventType === "tool.execute.before") {
         const toolPayload = normalizeToolPayload(eventData, undefined);
-        await runHookScript("prompt-guard.sh", toolPayload);
-        await runHookScript("workflow-guard.sh", toolPayload);
+        const promptOk = await runHookScript("prompt-guard.sh", toolPayload);
+        const workflowOk = await runHookScript("workflow-guard.sh", toolPayload);
+        if (!promptOk || !workflowOk) {
+          throw new Error(
+            "cclaw OpenCode guard blocked tool.execute.before (prompt/workflow guard non-zero exit)."
+          );
+        }
       }
       if (eventType === "tool.execute.after") {
         const toolPayload = normalizeToolPayload(eventData, undefined);
@@ -1177,8 +1212,13 @@ export default function cclawPlugin(ctx) {
     },
     "tool.execute.before": async (input, output) => {
       const payload = normalizeToolPayload(input, output);
-      await runHookScript("prompt-guard.sh", payload);
-      await runHookScript("workflow-guard.sh", payload);
+      const promptOk = await runHookScript("prompt-guard.sh", payload);
+      const workflowOk = await runHookScript("workflow-guard.sh", payload);
+      if (!promptOk || !workflowOk) {
+        throw new Error(
+          "cclaw OpenCode guard blocked tool.execute.before (prompt/workflow guard non-zero exit)."
+        );
+      }
     },
     "tool.execute.after": async (input, output) => {
       const payload = normalizeToolPayload(input, output);

package/dist/content/next-command.js

@@ -44,13 +44,14 @@ This is the only progression command the user needs to drive the entire flow. St
 5. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
 6. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
 7. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
-8. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if the agent is **completed** or **waived**.
+8. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if each mandatory agent is **completed** or **waived**.
+9. If any mandatory delegation is missing and no waiver exists: **STOP** and ask the user whether to dispatch now or waive with rationale. Do not mark gates passed while delegation is unresolved.
 
 ### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
 
 → Load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<currentStage>.md\`** for the current stage.
 → Execute that stage's protocol. The stage skill handles the full interaction including STOP points and gate tracking.
-→ When the stage completes, the Stage Completion Protocol in the skill updates \`flow-state.json\` automatically.
+→ Stage completion must use \`bash .cclaw/hooks/stage-complete.sh <currentStage>\` (canonical), which validates delegations + gate evidence before mutating \`flow-state.json\`.
 
 ### Path B: Current stage IS complete (all gates passed, all delegations satisfied)
 
@@ -152,6 +153,8 @@ For each gate id in \`requiredGates\` for \`currentStage\`:
 - **Unmet** otherwise.
 
 Check \`mandatoryDelegations\` via **\`${delegationPath}\`** — satisfied only if **completed** or **waived**.
+If a mandatory delegation is missing and no waiver exists, **STOP** and ask:
+(A) dispatch now, (B) waive with rationale, (C) cancel stage advance.
 
 ### Step 3: Act
 
@@ -161,7 +164,7 @@ Load the current stage's skill and command contract:
 - \`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`
 - \`${RUNTIME_ROOT}/commands/<currentStage>.md\`
 
-Execute the stage protocol. The stage skill handles interaction, STOP points, gate tracking, and the Stage Completion Protocol (updates \`flow-state.json\` when done).
+Execute the stage protocol. The stage skill handles interaction, STOP points, gate tracking, and stage completion via \`bash .cclaw/hooks/stage-complete.sh <stage>\` (canonical flow-state mutation path).
 
 **Path B — stage IS complete (all gates met, all delegations done):**
 

package/dist/content/observe.d.ts

@@ -10,6 +10,7 @@ export interface PromptGuardOptions {
 }
 export declare function promptGuardScript(options?: PromptGuardOptions): string;
 export interface WorkflowGuardOptions {
+    workflowGuardMode?: "advisory" | "strict";
     tddEnforcementMode?: "advisory" | "strict";
     tddTestGlobs?: string[];
 }

package/dist/content/observe.js

@@ -154,6 +154,7 @@ exit 0
 `;
 }
 export function workflowGuardScript(options = {}) {
+    const workflowGuardMode = options.workflowGuardMode === "strict" ? "strict" : "advisory";
     const tddEnforcementMode = options.tddEnforcementMode === "strict" ? "strict" : "advisory";
     const tddTestGlobs = options.tddTestGlobs && options.tddTestGlobs.length > 0
         ? options.tddTestGlobs.join(",")
@@ -162,7 +163,7 @@ export function workflowGuardScript(options = {}) {
 # cclaw workflow guard hook — generated by cclaw sync
 # Enforces stage-aware command discipline and recent flow-state read hygiene.
 set -uo pipefail
-WORKFLOW_GUARD_MODE="\${CCLAW_WORKFLOW_GUARD_MODE:-advisory}"
+WORKFLOW_GUARD_MODE="\${CCLAW_WORKFLOW_GUARD_MODE:-${workflowGuardMode}}"
 MAX_FLOW_READ_AGE_SEC="\${CCLAW_WORKFLOW_GUARD_MAX_AGE_SEC:-1800}"
 TDD_ENFORCEMENT_MODE="${tddEnforcementMode}"
 TDD_TEST_GLOBS="${tddTestGlobs}"
@@ -342,6 +343,81 @@ is_cclaw_cli_payload() {
   printf '%s' "$1" | grep -Eq '(cclaw |npx cclaw |/cc-|/cc[^[:alnum:]_-])'
 }
 
+extract_flow_state_after_json() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$INPUT" | jq -r '
+      .tool_input?.content //
+      .input?.content //
+      .arguments?.content //
+      .params?.content //
+      .payload?.content //
+      .content //
+      .input?.new_string //
+      .tool_input?.new_string //
+      ""
+    ' 2>/dev/null || echo ""
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    INPUT_JSON="$INPUT" python3 - <<'PY'
+import json
+import os
+
+try:
+    payload = json.loads(os.environ.get("INPUT_JSON", "{}"))
+except Exception:
+    payload = {}
+
+def pick(value):
+    if not isinstance(value, dict):
+        return ""
+    for key in ("tool_input", "input", "arguments", "params", "payload"):
+        nested = value.get(key)
+        if isinstance(nested, dict):
+            content = nested.get("content")
+            if isinstance(content, str) and content.strip():
+                return content
+            new_string = nested.get("new_string")
+            if isinstance(new_string, str) and new_string.strip():
+                return new_string
+    content = value.get("content")
+    if isinstance(content, str) and content.strip():
+        return content
+    return ""
+
+print(pick(payload))
+PY
+    return 0
+  fi
+
+  printf ''
+  return 0
+}
+
+verify_flow_state_candidate() {
+  local candidate_json="$1"
+  [ -n "$candidate_json" ] || return 1
+  local tmp_file="$STATE_DIR/.flow-state-candidate.$$.$RANDOM.json"
+  printf '%s' "$candidate_json" > "$tmp_file" 2>/dev/null || {
+    rm -f "$tmp_file" 2>/dev/null || true
+    return 1
+  }
+
+  local verify_cmd=(npx -y cclaw-cli internal verify-flow-state-diff --after-file="$tmp_file" --quiet)
+  if command -v cclaw >/dev/null 2>&1; then
+    verify_cmd=(cclaw internal verify-flow-state-diff --after-file="$tmp_file" --quiet)
+  fi
+
+  if "\${verify_cmd[@]}" >/dev/null 2>&1; then
+    rm -f "$tmp_file" 2>/dev/null || true
+    return 0
+  fi
+
+  rm -f "$tmp_file" 2>/dev/null || true
+  return 1
+}
+
 is_preimplementation_stage() {
   case "$1" in
     brainstorm|scope|design|spec|plan) return 0 ;;
@@ -480,6 +556,22 @@ if [ -n "$TARGET_STAGE" ] && [ "$CURRENT_STAGE" != "none" ]; then
   fi
 fi
 
+if is_mutating_tool "$TOOL_LOWER" && printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/state/flow-state\.json'; then
+  if [ -n "$REASONS" ]; then
+    REASONS="$REASONS,direct_flow_state_edit"
+  else
+    REASONS="direct_flow_state_edit"
+  fi
+  FLOW_STATE_AFTER_JSON=$(extract_flow_state_after_json)
+  if [ -n "$FLOW_STATE_AFTER_JSON" ]; then
+    if ! verify_flow_state_candidate "$FLOW_STATE_AFTER_JSON"; then
+      REASONS="$REASONS,flow_state_edit_failed_internal_validation"
+    fi
+  else
+    REASONS="$REASONS,flow_state_edit_without_serialized_content"
+  fi
+fi
+
 if is_preimplementation_stage "$CURRENT_STAGE" && is_mutating_tool "$TOOL_LOWER"; then
   if ! printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/'; then
     if [ -n "$REASONS" ]; then
@@ -567,7 +659,11 @@ PY
 fi
 
 if [ -n "$REASONS" ]; then
-  NOTE="Cclaw workflow guard: detected potential flow violation (\${REASONS}). Re-read ${RUNTIME_ROOT}/state/flow-state.json, avoid source edits before tdd stage, and enforce RED -> GREEN -> REFACTOR discipline inside tdd."
+  if printf '%s' "$REASONS" | grep -Eq 'direct_flow_state_edit'; then
+    NOTE="Cclaw workflow guard: direct flow-state edit bypasses the canonical stage-complete helper (\${REASONS}). Prefer: bash ${RUNTIME_ROOT}/hooks/stage-complete.sh <stage>. In strict mode this is blocked."
+  else
+    NOTE="Cclaw workflow guard: detected potential flow violation (\${REASONS}). Re-read ${RUNTIME_ROOT}/state/flow-state.json, avoid source edits before tdd stage, and enforce RED -> GREEN -> REFACTOR discipline inside tdd."
+  fi
   if command -v jq >/dev/null 2>&1; then
     ENTRY=$(jq -n -c \
       --arg ts "$TS" \
@@ -1826,6 +1922,9 @@ export function codexHooksJsonWithObservation() {
                     hooks: [{
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                        }, {
+                            type: "command",
+                            command: "bash -lc 'if command -v cclaw >/dev/null 2>&1; then cclaw internal verify-current-state --quiet >/dev/null || true; else npx -y cclaw-cli internal verify-current-state --quiet >/dev/null || true; fi'"
                         }]
                 }],
             PreToolUse: [{

package/dist/content/protocols.js

@@ -99,16 +99,21 @@ Shared closeout sequence applied by every stage skill.
 ## Required order
 
 1. Verify mandatory delegations are completed or explicitly waived.
-2. Update \`.cclaw/state/flow-state.json\`:
-   - mark passed gates,
-   - clear blocked gates that are resolved,
-   - update \`guardEvidence\`.
-3. Persist stage artifact under \`.cclaw/artifacts/\`.
-4. Run \`npx cclaw doctor\` and resolve failures.
-5. **Capture through-flow learnings** — see the policy below. Knowledge
+2. Persist stage artifact under \`.cclaw/artifacts/\`.
+3. Use the canonical helper:
+   - \`bash .cclaw/hooks/stage-complete.sh <stage>\`
+   - helper responsibilities: validate mandatory delegations, validate
+     current-stage gate evidence/artifact lint, update
+     \`stageGateCatalog\` + \`guardEvidence\`, and advance \`currentStage\`.
+4. Legacy fallback (only when helper is unavailable): manually edit
+   \`.cclaw/state/flow-state.json\` to mark passed gates, clear resolved
+   blocked gates, and update \`guardEvidence\`. This path is legacy and
+   intentionally noisy in workflow guards.
+5. Run \`npx cclaw doctor\` and resolve failures.
+6. **Capture through-flow learnings** — see the policy below. Knowledge
    accrues continuously across stages, not just at retro.
-6. Notify user with stage completion and next action (\`/cc-next\`).
-7. Stop; do not auto-run the next stage unless user asks.
+7. Notify user with stage completion and next action (\`/cc-next\`).
+8. Stop; do not auto-run the next stage unless user asks.
 
 ## Through-flow knowledge capture
 

package/dist/content/skills.js

@@ -222,6 +222,9 @@ function completionParametersBlock(schema) {
 - \`gates\`: ${gateList}
 - \`artifact\`: \`${RUNTIME_ROOT}/artifacts/${schema.artifactFile}\`
 - \`mandatory delegations\`: ${mandatory}
+- \`completion helper\`: \`bash .cclaw/hooks/stage-complete.sh ${schema.stage}\`
+- Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.
+- Use the completion helper instead of raw \`flow-state.json\` edits (legacy direct edits trigger workflow-guard warnings or strict-mode blocks).
 
 Apply shared completion logic from:
 \`${COMPLETION_PROTOCOL_PATH}\`

package/dist/content/stages/design.js

@@ -42,6 +42,7 @@ export const DESIGN = {
         "If a section has no issues, say 'No issues found' and move on.",
         "Do not skip failure-mode mapping.",
         "For design baseline approval: present the full baseline. **STOP.** Do NOT proceed until user explicitly approves the design.",
+        "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `bash .cclaw/hooks/stage-complete.sh design` (do not hand-edit `.cclaw/state/flow-state.json`).",
         "Take a firm position on every recommendation. Do NOT hedge with 'it depends' or 'you could do either'. State your opinion, then justify it.",
         "Use pushback patterns for weak framing: if the user says 'it's just a small change', respond with 'small changes to shared interfaces have outsized blast radius — let's map it'. If 'we'll refactor later', respond with 'later never comes — show me the refactor ticket or do it now'.",
         "When the user's proposed architecture is suboptimal, say so directly. Offer the alternative with concrete trade-offs, do not bury criticism in praise.",

package/dist/content/stages/plan.js

@@ -29,7 +29,7 @@ export const PLAN = {
         "Map scope Locked Decisions — every D-XX from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
         "Run anti-placeholder + anti-scope-reduction scans — block `TODO/TBD/...` and phrasing like `v1`, `for now`, `later` for locked boundaries.",
         "Define checkpoints — mark points where progress should be validated before continuing.",
-        "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. **STOP.** Do NOT proceed until user confirms. Then update `flow-state.json` and tell user to run `/cc-next`."
+        "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. **STOP.** Do NOT proceed until user confirms. Then close the stage with `bash .cclaw/hooks/stage-complete.sh plan` and tell user to run `/cc-next`."
     ],
     interactionProtocol: [
         "Plan in read-only mode relative to implementation.",
@@ -38,7 +38,8 @@ export const PLAN = {
         "Attach verification step to every task.",
         "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. Then update `flow-state.json` and tell user to run `/cc-next`."
+        "**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 `bash .cclaw/hooks/stage-complete.sh plan` and tell the user to run `/cc-next`."
     ],
     process: [
         "Build dependency graph and ordered slices.",

package/dist/content/stages/scope.js

@@ -41,7 +41,8 @@ export const SCOPE = {
         "Record explicit in-scope and out-of-scope contract.",
         "Once the user accepts or rejects a recommendation, commit fully. Do not re-argue.",
         "Produce a clean scope summary after all issues are resolved.",
-        "**STOP.** Wait for explicit user approval of scope contract before advancing to design."
+        "**STOP.** Wait for explicit user approval of scope contract before advancing to design.",
+        "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `bash .cclaw/hooks/stage-complete.sh scope` (do not hand-edit `.cclaw/state/flow-state.json`)."
     ],
     process: [
         "Run premise challenge and existing-solution leverage check.",

package/dist/content/stages/tdd.js

@@ -92,18 +92,11 @@ export const TDD = {
     ],
     commonRationalizations: [
         "Writing code before failing test",
-        "Asserting implementation details instead of behavior",
-        "Big-bang implementation across multiple slices",
         "Partial test runs presented as GREEN",
         "Skipping evidence capture",
         "Undocumented refactor changes",
-        "Adding features beyond what RED tests require",
-        "No failing test output (RED missing)",
-        "Implementation edits appear before RED evidence",
         "No full-suite GREEN evidence",
-        "No refactor notes",
-        "Multiple tasks implemented in one pass without justification",
-        "Files changed outside current slice scope"
+        "Multiple tasks implemented in one pass without justification"
     ],
     policyNeedles: ["RED", "GREEN", "REFACTOR", "failing test", "full test suite", "acceptance criteria", "traceable to plan slice"],
     artifactFile: "06-tdd.md",

package/dist/install.js

@@ -23,7 +23,7 @@ import { archiveCommandContract, archiveCommandSkillMarkdown } from "./content/a
 import { rewindCommandContract, rewindCommandSkillMarkdown } from "./content/rewind-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
-import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { sessionStartScript, stopCheckpointScript, stageCompleteScript, preCompactScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./content/observe.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { decisionProtocolMarkdown, completionProtocolMarkdown, ethosProtocolMarkdown } from "./content/protocols.js";
@@ -616,11 +616,13 @@ async function writeHooks(projectRoot, config) {
     await ensureDir(hooksDir);
     await writeFileSafe(path.join(hooksDir, "session-start.sh"), sessionStartScript());
     await writeFileSafe(path.join(hooksDir, "stop-checkpoint.sh"), stopCheckpointScript());
+    await writeFileSafe(path.join(hooksDir, "stage-complete.sh"), stageCompleteScript());
     await writeFileSafe(path.join(hooksDir, "pre-compact.sh"), preCompactScript());
     await writeFileSafe(path.join(hooksDir, "prompt-guard.sh"), promptGuardScript({
         strictMode: config.promptGuardMode === "strict"
     }));
     await writeFileSafe(path.join(hooksDir, "workflow-guard.sh"), workflowGuardScript({
+        workflowGuardMode: config.strictness ?? "advisory",
         tddEnforcementMode: config.tddEnforcement ?? "advisory",
         tddTestGlobs: config.tddTestGlobs
     }));
@@ -631,6 +633,7 @@ async function writeHooks(projectRoot, config) {
         for (const script of [
             "session-start.sh",
             "stop-checkpoint.sh",
+            "stage-complete.sh",
             "pre-compact.sh",
             "prompt-guard.sh",
             "workflow-guard.sh",
@@ -1260,7 +1263,12 @@ function stripManagedHookCommands(value) {
 }
 function isManagedRuntimeHookCommand(command) {
     const normalized = command.trim().replace(/\s+/gu, " ");
-    return /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized);
+    if (/(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized)) {
+        return true;
+    }
+    // Codex UserPromptSubmit non-blocking state nudge:
+    // bash -lc '... cclaw internal verify-current-state --quiet ...'
+    return /internal verify-current-state --quiet/u.test(normalized);
 }
 async function removeManagedHookEntries(hookFilePath) {
     if (!(await exists(hookFilePath)))

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

@@ -0,0 +1,7 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function runInternalCommand(projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/advance-stage.js

@@ -0,0 +1,425 @@
+import fs from "node:fs/promises";
+import { stageSchema } from "../content/stage-schema.js";
+import { appendDelegation, checkMandatoryDelegations } from "../delegation.js";
+import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../gate-evidence.js";
+import { isFlowTrack, nextStage } from "../flow-state.js";
+import { readFlowState, writeFlowState } from "../runs.js";
+import { FLOW_STAGES } from "../types.js";
+function unique(values) {
+    return [...new Set(values)];
+}
+function parseStringList(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function isFlowStageValue(value) {
+    return typeof value === "string" && FLOW_STAGES.includes(value);
+}
+function parseGuardEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    const next = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw !== "string")
+            continue;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        next[key] = trimmed;
+    }
+    return next;
+}
+function parseCandidateGateCatalog(value, fallback) {
+    const next = {};
+    for (const stage of FLOW_STAGES) {
+        const base = fallback[stage];
+        next[stage] = {
+            required: [...base.required],
+            recommended: [...base.recommended],
+            conditional: [...base.conditional],
+            triggered: [...base.triggered],
+            passed: [...base.passed],
+            blocked: [...base.blocked]
+        };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return next;
+    }
+    const rawCatalog = value;
+    for (const stage of FLOW_STAGES) {
+        const rawStage = rawCatalog[stage];
+        if (!rawStage || typeof rawStage !== "object" || Array.isArray(rawStage)) {
+            continue;
+        }
+        const typed = rawStage;
+        const base = fallback[stage];
+        const allowed = new Set([...base.required, ...base.recommended, ...base.conditional]);
+        const conditional = new Set(base.conditional);
+        const passed = unique(parseStringList(typed.passed)).filter((gateId) => allowed.has(gateId));
+        const blocked = unique(parseStringList(typed.blocked)).filter((gateId) => allowed.has(gateId));
+        const triggered = unique([
+            ...parseStringList(typed.triggered).filter((gateId) => conditional.has(gateId)),
+            ...passed.filter((gateId) => conditional.has(gateId)),
+            ...blocked.filter((gateId) => conditional.has(gateId))
+        ]);
+        next[stage] = {
+            required: [...base.required],
+            recommended: [...base.recommended],
+            conditional: [...base.conditional],
+            triggered,
+            passed,
+            blocked
+        };
+    }
+    return next;
+}
+function coerceCandidateFlowState(raw, fallback) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return fallback;
+    }
+    const typed = raw;
+    const track = isFlowTrack(typed.track) ? typed.track : fallback.track;
+    const currentStage = isFlowStageValue(typed.currentStage)
+        ? typed.currentStage
+        : fallback.currentStage;
+    const completedStages = unique(parseStringList(typed.completedStages).filter((stage) => isFlowStageValue(stage)));
+    const skippedStagesRaw = parseStringList(typed.skippedStages).filter((stage) => isFlowStageValue(stage));
+    const skippedStages = skippedStagesRaw.length > 0 ? skippedStagesRaw : fallback.skippedStages;
+    return {
+        ...fallback,
+        currentStage,
+        completedStages,
+        track,
+        skippedStages,
+        guardEvidence: parseGuardEvidence(typed.guardEvidence),
+        stageGateCatalog: parseCandidateGateCatalog(typed.stageGateCatalog, fallback.stageGateCatalog)
+    };
+}
+function parseEvidenceByGate(raw) {
+    if (!raw || raw.trim().length === 0) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`--evidence-json must be valid JSON object: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("--evidence-json must deserialize to an object.");
+    }
+    const next = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            continue;
+        next[key] = trimmed;
+    }
+    return next;
+}
+function parseCsv(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function parseAdvanceStageArgs(tokens) {
+    const [stageRaw, ...flagTokens] = tokens;
+    if (!isFlowStageValue(stageRaw)) {
+        throw new Error(`internal advance-stage requires a stage positional argument (${FLOW_STAGES.join(", ")}).`);
+    }
+    let evidenceJson;
+    let passed = [];
+    let waiveDelegations = [];
+    let waiverReason;
+    let quiet = false;
+    for (const token of flagTokens) {
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token.startsWith("--evidence-json=")) {
+            evidenceJson = token.replace("--evidence-json=", "");
+            continue;
+        }
+        if (token.startsWith("--passed=")) {
+            passed = [...passed, ...parseCsv(token.replace("--passed=", ""))];
+            continue;
+        }
+        if (token.startsWith("--waive-delegation=")) {
+            waiveDelegations = [
+                ...waiveDelegations,
+                ...parseCsv(token.replace("--waive-delegation=", ""))
+            ];
+            continue;
+        }
+        if (token.startsWith("--waiver-reason=")) {
+            waiverReason = token.replace("--waiver-reason=", "").trim();
+            continue;
+        }
+        throw new Error(`Unknown flag for internal advance-stage: ${token}`);
+    }
+    return {
+        stage: stageRaw,
+        passedGateIds: unique(passed),
+        evidenceByGate: parseEvidenceByGate(evidenceJson),
+        waiveDelegations: unique(waiveDelegations),
+        waiverReason,
+        quiet
+    };
+}
+function parseVerifyFlowStateDiffArgs(tokens) {
+    let afterJson;
+    let afterFile;
+    let quiet = false;
+    for (const token of tokens) {
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token.startsWith("--after-json=")) {
+            afterJson = token.replace("--after-json=", "");
+            continue;
+        }
+        if (token.startsWith("--after-file=")) {
+            afterFile = token.replace("--after-file=", "");
+            continue;
+        }
+        throw new Error(`Unknown flag for internal verify-flow-state-diff: ${token}`);
+    }
+    if (!afterJson && !afterFile) {
+        throw new Error("internal verify-flow-state-diff requires --after-json=<json> or --after-file=<path>.");
+    }
+    return { afterJson, afterFile, quiet };
+}
+function parseVerifyCurrentStateArgs(tokens) {
+    let quiet = false;
+    for (const token of tokens) {
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        throw new Error(`Unknown flag for internal verify-current-state: ${token}`);
+    }
+    return { quiet };
+}
+async function buildValidationReport(projectRoot, flowState) {
+    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
+    const gates = await verifyCurrentStageGateEvidence(projectRoot, flowState);
+    const completedStages = verifyCompletedStagesGateClosure(flowState);
+    const ok = delegation.satisfied && gates.ok && gates.complete && completedStages.ok;
+    return {
+        ok,
+        stage: flowState.currentStage,
+        delegation: {
+            satisfied: delegation.satisfied,
+            missing: delegation.missing,
+            waived: delegation.waived,
+            missingEvidence: delegation.missingEvidence,
+            expectedMode: delegation.expectedMode
+        },
+        gates: {
+            ok: gates.ok,
+            complete: gates.complete,
+            issues: gates.issues,
+            missingRequired: gates.missingRequired,
+            missingTriggeredConditional: gates.missingTriggeredConditional
+        },
+        completedStages: {
+            ok: completedStages.ok,
+            issues: completedStages.issues
+        }
+    };
+}
+async function runAdvanceStage(projectRoot, args, io) {
+    const flowState = await readFlowState(projectRoot);
+    if (flowState.currentStage !== args.stage) {
+        io.stderr.write(`cclaw internal advance-stage: current stage is "${flowState.currentStage}", not "${args.stage}".\n`);
+        return 1;
+    }
+    const schema = stageSchema(args.stage);
+    const requiredGateIds = schema.requiredGates
+        .filter((gate) => gate.tier === "required")
+        .map((gate) => gate.id);
+    const allowedGateIds = new Set(schema.requiredGates.map((gate) => gate.id));
+    const selectedGateIds = args.passedGateIds.length > 0
+        ? args.passedGateIds.filter((gateId) => allowedGateIds.has(gateId))
+        : requiredGateIds;
+    const missingRequired = requiredGateIds.filter((gateId) => !selectedGateIds.includes(gateId));
+    if (missingRequired.length > 0) {
+        io.stderr.write(`cclaw internal advance-stage: required gates not selected as passed: ${missingRequired.join(", ")}.\n`);
+        return 1;
+    }
+    const mandatory = new Set(schema.mandatoryDelegations);
+    for (const agent of args.waiveDelegations) {
+        if (!mandatory.has(agent)) {
+            io.stderr.write(`cclaw internal advance-stage: cannot waive "${agent}" for stage "${args.stage}" (not mandatory).\n`);
+            return 1;
+        }
+    }
+    if (args.waiveDelegations.length > 0) {
+        const waiverReason = args.waiverReason && args.waiverReason.length > 0
+            ? args.waiverReason
+            : "manual_waiver";
+        for (const agent of args.waiveDelegations) {
+            await appendDelegation(projectRoot, {
+                stage: args.stage,
+                agent,
+                mode: "mandatory",
+                status: "waived",
+                waiverReason,
+                fulfillmentMode: "role-switch",
+                ts: new Date().toISOString()
+            });
+        }
+    }
+    const catalog = flowState.stageGateCatalog[args.stage];
+    const nextPassed = unique([...catalog.passed, ...selectedGateIds]).filter((gateId) => allowedGateIds.has(gateId));
+    const nextBlocked = unique(catalog.blocked.filter((gateId) => !nextPassed.includes(gateId))).filter((gateId) => allowedGateIds.has(gateId));
+    const conditional = new Set(catalog.conditional);
+    const nextTriggered = unique([
+        ...catalog.triggered.filter((gateId) => conditional.has(gateId)),
+        ...nextPassed.filter((gateId) => conditional.has(gateId)),
+        ...nextBlocked.filter((gateId) => conditional.has(gateId))
+    ]);
+    const nextGuardEvidence = { ...flowState.guardEvidence };
+    for (const gateId of nextPassed) {
+        const existing = nextGuardEvidence[gateId];
+        if (typeof existing === "string" && existing.trim().length > 0)
+            continue;
+        const provided = args.evidenceByGate[gateId];
+        nextGuardEvidence[gateId] = provided && provided.trim().length > 0
+            ? provided.trim()
+            : `stage-complete helper auto-evidence for ${gateId} @ ${new Date().toISOString()} (${schema.artifactFile})`;
+    }
+    const nextStageCatalog = {
+        required: [...catalog.required],
+        recommended: [...catalog.recommended],
+        conditional: [...catalog.conditional],
+        triggered: nextTriggered,
+        passed: nextPassed,
+        blocked: nextBlocked
+    };
+    const candidateState = {
+        ...flowState,
+        guardEvidence: nextGuardEvidence,
+        stageGateCatalog: {
+            ...flowState.stageGateCatalog,
+            [args.stage]: nextStageCatalog
+        }
+    };
+    const validation = await buildValidationReport(projectRoot, candidateState);
+    if (!validation.ok) {
+        io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}".\n`);
+        if (validation.delegation.missing.length > 0) {
+            io.stderr.write(`- missing delegations: ${validation.delegation.missing.join(", ")}\n`);
+        }
+        if (validation.delegation.missingEvidence.length > 0) {
+            io.stderr.write(`- role-switch evidence missing: ${validation.delegation.missingEvidence.join(", ")}\n`);
+        }
+        if (validation.gates.issues.length > 0) {
+            io.stderr.write(`- gate issues: ${validation.gates.issues.join(" | ")}\n`);
+        }
+        if (validation.completedStages.issues.length > 0) {
+            io.stderr.write(`- completed-stage closure issues: ${validation.completedStages.issues.join(" | ")}\n`);
+        }
+        return 1;
+    }
+    const successor = nextStage(args.stage, flowState.track);
+    const completedStages = flowState.completedStages.includes(args.stage)
+        ? [...flowState.completedStages]
+        : [...flowState.completedStages, args.stage];
+    const finalState = {
+        ...candidateState,
+        completedStages,
+        currentStage: successor ?? args.stage
+    };
+    await writeFlowState(projectRoot, finalState);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "advance-stage",
+            stage: args.stage,
+            nextStage: successor,
+            currentStage: finalState.currentStage,
+            completedStages: finalState.completedStages
+        }, null, 2)}\n`);
+    }
+    return 0;
+}
+async function runVerifyFlowStateDiff(projectRoot, args, io) {
+    let raw = args.afterJson;
+    if (!raw && args.afterFile) {
+        raw = await fs.readFile(args.afterFile, "utf8");
+    }
+    if (!raw) {
+        io.stderr.write("cclaw internal verify-flow-state-diff: no candidate state payload.\n");
+        return 1;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        io.stderr.write(`cclaw internal verify-flow-state-diff: invalid JSON payload (${err instanceof Error ? err.message : String(err)}).\n`);
+        return 1;
+    }
+    const current = await readFlowState(projectRoot);
+    const candidate = coerceCandidateFlowState(parsed, current);
+    const validation = await buildValidationReport(projectRoot, candidate);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify(validation, null, 2)}\n`);
+    }
+    if (!validation.ok) {
+        io.stderr.write(`cclaw internal verify-flow-state-diff: candidate state is invalid for stage "${validation.stage}".\n`);
+    }
+    return validation.ok ? 0 : 1;
+}
+async function runVerifyCurrentState(projectRoot, args, io) {
+    const current = await readFlowState(projectRoot);
+    const validation = await buildValidationReport(projectRoot, current);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify(validation, null, 2)}\n`);
+    }
+    if (!validation.ok) {
+        const unmetDelegations = validation.delegation.missing.length + validation.delegation.missingEvidence.length;
+        const gatesWithoutEvidence = validation.gates.issues.filter((issue) => issue.includes("missing guardEvidence entry")).length;
+        io.stderr.write(`cclaw: current stage has ${unmetDelegations} unmet mandatory delegations and ${gatesWithoutEvidence} gates without evidence.\n`);
+        io.stderr.write(`cclaw internal verify-current-state: unresolved stage constraints for "${validation.stage}".\n`);
+    }
+    return validation.ok ? 0 : 1;
+}
+export async function runInternalCommand(projectRoot, argv, io) {
+    const [subcommand, ...tokens] = argv;
+    if (!subcommand) {
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state\n");
+        return 1;
+    }
+    try {
+        if (subcommand === "advance-stage") {
+            return await runAdvanceStage(projectRoot, parseAdvanceStageArgs(tokens), io);
+        }
+        if (subcommand === "verify-flow-state-diff") {
+            return await runVerifyFlowStateDiff(projectRoot, parseVerifyFlowStateDiffArgs(tokens), io);
+        }
+        if (subcommand === "verify-current-state") {
+            return await runVerifyCurrentState(projectRoot, parseVerifyCurrentStateArgs(tokens), io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state\n`);
+        return 1;
+    }
+    catch (err) {
+        io.stderr.write(`cclaw internal ${subcommand} failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}

package/package.json

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