cclaw-cli 0.42.0 → 0.44.0

package/README.md

@@ -135,10 +135,31 @@ Plus harness-specific shims:
   folders are auto-cleaned on sync.)
 - `AGENTS.md` with a managed routing block (includes a Codex-specific note)
 
-`.cclaw/config.yaml` holds every tunable key (prompt guard strictness,
-TDD enforcement, git-hook guards, language rule packs, track heuristics).
-Edit it directly — `cclaw-cli upgrade` preserves your changes. Full key
-reference: [`docs/config.md`](./docs/config.md).
+### `.cclaw/config.yaml` — the minimal surface
+
+`cclaw init` writes five keys, on purpose:
+
+```yaml
+version: 0.44.0
+flowVersion: 1.0.0
+harnesses:
+  - codex
+strictness: advisory     # advisory | strict — one knob for prompt-guard + TDD
+gitHookGuards: false     # opt in to managed .git/hooks/pre-commit + pre-push
+```
+
+If cclaw detects a Node / Python / Go project at init time, a sixth
+`languageRulePacks` line appears (auto-populated from `package.json`,
+`pyproject.toml` / `requirements.txt`, `go.mod`). That is the full
+default surface — a new user sees nothing they need to understand yet.
+
+Advanced knobs (`promptGuardMode` / `tddEnforcement` per-axis overrides,
+`tddTestGlobs`, `defaultTrack`, `trackHeuristics`, `sliceReview`) are
+**opt-in**: add them by hand when you need them. `cclaw upgrade`
+preserves exactly what you wrote — it never silently reintroduces
+defaults you removed.
+
+Full key-by-key reference: [`docs/config.md`](./docs/config.md).
 
 ---
 

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;
@@ -827,6 +838,11 @@ async function runCommand(parsed, ctx) {
         }
         const trackNote = effectiveTrack ? ` (track=${effectiveTrack})` : "";
         info(ctx, `Initialized .cclaw runtime and generated harness shims${trackNote}`);
+        // Point new users at the one config surface they might actually flip —
+        // `strictness` and `gitHookGuards` — without overselling the other knobs
+        // (those live behind docs/config.md until someone needs them).
+        info(ctx, "Config: .cclaw/config.yaml (strictness=advisory, gitHookGuards=false).");
+        info(ctx, "Need stricter guards or language rule packs? See docs/config.md.");
         await maybeEnableCodexHooksFlag(effectiveHarnesses, parsed, ctx);
         return 0;
     }

package/dist/config.d.ts

@@ -1,5 +1,66 @@
-import type { FlowTrack, HarnessId, VibyConfig } from "./types.js";
+import type { FlowTrack, HarnessId, LanguageRulePack, VibyConfig } from "./types.js";
 export declare function configPath(projectRoot: string): string;
+/**
+ * Default test-file globs used by workflow-guard.sh to detect when a write
+ * targets a test file during TDD. Users rarely need to override this — the
+ * defaults cover TypeScript / JavaScript / Python / Go / Rust / Java layouts.
+ * Exposed so `install.ts` can reuse the same list when seeding the shell
+ * guard script, even though the field is no longer written to the default
+ * `config.yaml` template.
+ */
+export declare const DEFAULT_TDD_TEST_GLOBS: readonly string[];
+/**
+ * Populated runtime view of config values that downstream callers (install,
+ * observe, doctor) consume. Always has the derived guard modes populated,
+ * regardless of whether the user wrote `strictness`, the legacy keys, both,
+ * or neither.
+ */
 export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrack?: FlowTrack): VibyConfig;
+/**
+ * Probe common project-root manifests to infer which language rule packs the
+ * user would reasonably want. Pure-functional best-effort: any filesystem
+ * error is swallowed, producing an empty list — the user can always override
+ * by hand.
+ *
+ * Called from `cclaw init` only (not `readConfig`), so subsequent upgrades
+ * never surprise a user who intentionally cleared the list.
+ */
+export declare function detectLanguageRulePacks(projectRoot: string): Promise<LanguageRulePack[]>;
 export declare function readConfig(projectRoot: string): Promise<VibyConfig>;
-export declare function writeConfig(projectRoot: string, config: VibyConfig): Promise<void>;
+/**
+ * Fields that live on the populated runtime `VibyConfig` but are considered
+ * "advanced" — we keep them in the in-memory object so downstream callers
+ * don't have to branch, but we do **not** write them to `config.yaml` unless
+ * the user set them explicitly. Keeps the default template small and honest:
+ * only knobs a new user would meaningfully flip show up.
+ */
+type AdvancedConfigKey = "promptGuardMode" | "tddEnforcement" | "tddTestGlobs" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview";
+/**
+ * Options controlling the serialisation shape of `config.yaml`.
+ *
+ * - `"full"` (default): write every field on the `VibyConfig` object that
+ *   isn't `undefined`. Preserves existing shapes and keeps legacy callers
+ *   working without migration.
+ * - `"minimal"`: write only the user-facing knobs (`MINIMAL_CONFIG_KEYS`)
+ *   plus any non-empty `languageRulePacks` (so auto-detected values survive
+ *   a fresh `cclaw init`). Use this when generating the default template;
+ *   power users can still add advanced keys by hand.
+ *
+ * `advancedKeysPresent` upgrades an otherwise-minimal serialisation by
+ * including the listed advanced keys. `cclaw upgrade` uses it to preserve
+ * the exact shape a user hand-authored, while still re-minimising configs
+ * where the user stayed at defaults.
+ */
+export interface WriteConfigOptions {
+    mode?: "full" | "minimal";
+    advancedKeysPresent?: ReadonlySet<AdvancedConfigKey>;
+}
+export declare function writeConfig(projectRoot: string, config: VibyConfig, options?: WriteConfigOptions): Promise<void>;
+/**
+ * Enumerate which advanced keys are currently set in the on-disk config.
+ * Used by `cclaw upgrade` to preserve the user's existing shape — if they
+ * wrote `tddTestGlobs` by hand, the upgrade keeps it; if they didn't, the
+ * upgrade stays minimal.
+ */
+export declare function detectAdvancedKeys(projectRoot: string): Promise<ReadonlySet<AdvancedConfigKey>>;
+export {};

package/dist/config.js

@@ -15,6 +15,7 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "version",
     "flowVersion",
     "harnesses",
+    "strictness",
     "promptGuardMode",
     "tddEnforcement",
     "tddTestGlobs",
@@ -24,6 +25,21 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "trackHeuristics",
     "sliceReview"
 ]);
+/**
+ * Config keys always present in the minimal init template. Everything else
+ * is "advanced" — parsed when present, but not pre-populated by `cclaw init`.
+ *
+ * Deliberately small: a first-time user should only see knobs they might
+ * actually flip. Power users override by adding more keys by hand; the
+ * reference lives in `docs/config.md`.
+ */
+const MINIMAL_CONFIG_KEYS = [
+    "version",
+    "flowVersion",
+    "harnesses",
+    "strictness",
+    "gitHookGuards"
+];
 const DEFAULT_SLICE_REVIEW_THRESHOLD = 5;
 const DEFAULT_SLICE_REVIEW_TRACKS = ["standard"];
 function configFixExample() {
@@ -57,19 +73,78 @@ function validateStringArray(value, fieldName, configFilePath) {
 export function configPath(projectRoot) {
     return path.join(projectRoot, CONFIG_PATH);
 }
+/**
+ * Default test-file globs used by workflow-guard.sh to detect when a write
+ * targets a test file during TDD. Users rarely need to override this — the
+ * defaults cover TypeScript / JavaScript / Python / Go / Rust / Java layouts.
+ * Exposed so `install.ts` can reuse the same list when seeding the shell
+ * guard script, even though the field is no longer written to the default
+ * `config.yaml` template.
+ */
+export const DEFAULT_TDD_TEST_GLOBS = [
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**"
+];
+/**
+ * Populated runtime view of config values that downstream callers (install,
+ * observe, doctor) consume. Always has the derived guard modes populated,
+ * regardless of whether the user wrote `strictness`, the legacy keys, both,
+ * or neither.
+ */
 export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack = "standard") {
     return {
         version: CCLAW_VERSION,
         flowVersion: FLOW_VERSION,
         harnesses,
+        strictness: "advisory",
         promptGuardMode: "advisory",
         tddEnforcement: "advisory",
-        tddTestGlobs: ["**/*.test.*", "**/*.spec.*", "**/test/**"],
+        tddTestGlobs: [...DEFAULT_TDD_TEST_GLOBS],
         gitHookGuards: false,
         defaultTrack,
         languageRulePacks: []
     };
 }
+/**
+ * Probe common project-root manifests to infer which language rule packs the
+ * user would reasonably want. Pure-functional best-effort: any filesystem
+ * error is swallowed, producing an empty list — the user can always override
+ * by hand.
+ *
+ * Called from `cclaw init` only (not `readConfig`), so subsequent upgrades
+ * never surprise a user who intentionally cleared the list.
+ */
+export async function detectLanguageRulePacks(projectRoot) {
+    const detected = [];
+    const pkgPath = path.join(projectRoot, "package.json");
+    if (await exists(pkgPath)) {
+        try {
+            const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+            const deps = {
+                ...pkg.dependencies,
+                ...pkg.devDependencies
+            };
+            if ("typescript" in deps || typeof pkg.types === "string") {
+                detected.push("typescript");
+            }
+        }
+        catch {
+            // Malformed package.json — skip; user can set the pack manually later.
+        }
+    }
+    const pythonMarkers = ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"];
+    for (const marker of pythonMarkers) {
+        if (await exists(path.join(projectRoot, marker))) {
+            detected.push("python");
+            break;
+        }
+    }
+    if (await exists(path.join(projectRoot, "go.mod"))) {
+        detected.push("go");
+    }
+    return [...new Set(detected)];
+}
 export async function readConfig(projectRoot) {
     const fullPath = configPath(projectRoot);
     if (!(await exists(fullPath))) {
@@ -105,23 +180,39 @@ export async function readConfig(projectRoot) {
     const harnesses = hasHarnessesField
         ? [...new Set(validatedHarnesses)]
         : DEFAULT_HARNESSES;
+    const strictnessRaw = parsed.strictness;
+    if (Object.prototype.hasOwnProperty.call(parsed, "strictness") &&
+        strictnessRaw !== "advisory" &&
+        strictnessRaw !== "strict") {
+        throw configValidationError(fullPath, `"strictness" must be "advisory" or "strict"`);
+    }
+    const strictness = strictnessRaw === "strict" ? "strict" : "advisory";
+    // Legacy guard fields — keep honouring explicit values for power users who
+    // want asymmetric behaviour (e.g. strict prompt guard + advisory TDD).
+    // When the user only set `strictness`, both axes inherit from it.
+    const hasExplicitPromptGuard = Object.prototype.hasOwnProperty.call(parsed, "promptGuardMode");
     const promptGuardModeRaw = parsed.promptGuardMode;
-    if (Object.prototype.hasOwnProperty.call(parsed, "promptGuardMode") &&
+    if (hasExplicitPromptGuard &&
         promptGuardModeRaw !== "advisory" &&
         promptGuardModeRaw !== "strict") {
         throw configValidationError(fullPath, `"promptGuardMode" must be "advisory" or "strict"`);
     }
-    const promptGuardMode = promptGuardModeRaw === "strict" ? "strict" : "advisory";
+    const promptGuardMode = hasExplicitPromptGuard
+        ? (promptGuardModeRaw === "strict" ? "strict" : "advisory")
+        : strictness;
+    const hasExplicitTddEnforcement = Object.prototype.hasOwnProperty.call(parsed, "tddEnforcement");
     const tddEnforcementRaw = parsed.tddEnforcement;
-    if (Object.prototype.hasOwnProperty.call(parsed, "tddEnforcement") &&
+    if (hasExplicitTddEnforcement &&
         tddEnforcementRaw !== "advisory" &&
         tddEnforcementRaw !== "strict") {
         throw configValidationError(fullPath, `"tddEnforcement" must be "advisory" or "strict"`);
     }
-    const tddEnforcement = tddEnforcementRaw === "strict" ? "strict" : "advisory";
+    const tddEnforcement = hasExplicitTddEnforcement
+        ? (tddEnforcementRaw === "strict" ? "strict" : "advisory")
+        : strictness;
     const tddTestGlobsRaw = parsed.tddTestGlobs;
     const tddTestGlobs = validateStringArray(tddTestGlobsRaw, "tddTestGlobs", fullPath)
-        ?? ["**/*.test.*", "**/*.spec.*", "**/test/**"];
+        ?? [...DEFAULT_TDD_TEST_GLOBS];
     const gitHookGuardsRaw = parsed.gitHookGuards;
     if (Object.prototype.hasOwnProperty.call(parsed, "gitHookGuards") &&
         typeof gitHookGuardsRaw !== "boolean") {
@@ -232,6 +323,7 @@ export async function readConfig(projectRoot) {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
         harnesses,
+        strictness,
         promptGuardMode,
         tddEnforcement,
         tddTestGlobs,
@@ -242,6 +334,88 @@ export async function readConfig(projectRoot) {
         sliceReview
     };
 }
-export async function writeConfig(projectRoot, config) {
-    await writeFileSafe(configPath(projectRoot), stringify(config));
+function isMinimalKey(key) {
+    return MINIMAL_CONFIG_KEYS.includes(key);
+}
+function buildSerializableConfig(config, options = {}) {
+    const mode = options.mode ?? "full";
+    const advanced = options.advancedKeysPresent;
+    const output = {};
+    const ordered = [
+        "version",
+        "flowVersion",
+        "harnesses",
+        "strictness",
+        "promptGuardMode",
+        "tddEnforcement",
+        "tddTestGlobs",
+        "gitHookGuards",
+        "defaultTrack",
+        "languageRulePacks",
+        "trackHeuristics",
+        "sliceReview"
+    ];
+    for (const key of ordered) {
+        const value = config[key];
+        if (value === undefined)
+            continue;
+        if (mode === "full") {
+            output[key] = value;
+            continue;
+        }
+        // Minimal mode: always include the short list; advanced keys only when
+        // the caller explicitly opted in, or for auto-detected non-empty
+        // `languageRulePacks`.
+        if (isMinimalKey(key)) {
+            output[key] = value;
+            continue;
+        }
+        if (advanced?.has(key)) {
+            output[key] = value;
+            continue;
+        }
+        if (key === "languageRulePacks" && Array.isArray(value) && value.length > 0) {
+            output[key] = value;
+        }
+    }
+    return output;
+}
+export async function writeConfig(projectRoot, config, options = {}) {
+    const serialisable = buildSerializableConfig(config, options);
+    await writeFileSafe(configPath(projectRoot), stringify(serialisable));
+}
+/**
+ * Enumerate which advanced keys are currently set in the on-disk config.
+ * Used by `cclaw upgrade` to preserve the user's existing shape — if they
+ * wrote `tddTestGlobs` by hand, the upgrade keeps it; if they didn't, the
+ * upgrade stays minimal.
+ */
+export async function detectAdvancedKeys(projectRoot) {
+    const fullPath = configPath(projectRoot);
+    if (!(await exists(fullPath)))
+        return new Set();
+    try {
+        const parsedUnknown = parse(await fs.readFile(fullPath, "utf8"));
+        if (!isRecord(parsedUnknown))
+            return new Set();
+        const advancedCandidates = [
+            "promptGuardMode",
+            "tddEnforcement",
+            "tddTestGlobs",
+            "defaultTrack",
+            "languageRulePacks",
+            "trackHeuristics",
+            "sliceReview"
+        ];
+        const present = new Set();
+        for (const key of advancedCandidates) {
+            if (Object.prototype.hasOwnProperty.call(parsedUnknown, key)) {
+                present.add(key);
+            }
+        }
+        return present;
+    }
+    catch {
+        return new Set();
+    }
 }

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[];
 }