cclaw-cli 0.43.0 → 0.45.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.45.0
 flowVersion: 1.0.0
 harnesses:
   - codex

package/dist/artifact-linter.d.ts

@@ -1,4 +1,4 @@
-import type { FlowStage } from "./types.js";
+import { type FlowStage } from "./types.js";
 export interface LintFinding {
     section: string;
     required: boolean;
@@ -12,6 +12,36 @@ export interface LintResult {
     passed: boolean;
     findings: LintFinding[];
 }
+export declare function extractMarkdownSectionBody(markdown: string, section: string): string | null;
+export type LearningEntryType = "rule" | "pattern" | "lesson" | "compound";
+export type LearningConfidence = "high" | "medium" | "low";
+export type LearningUniversality = "project" | "personal" | "universal";
+export type LearningMaturity = "raw" | "lifted-to-rule" | "lifted-to-enforcement";
+export interface LearningSeedEntry {
+    type: LearningEntryType;
+    trigger: string;
+    action: string;
+    confidence: LearningConfidence;
+    domain?: string | null;
+    stage?: FlowStage | null;
+    origin_stage?: FlowStage | null;
+    origin_feature?: string | null;
+    frequency?: number;
+    universality?: LearningUniversality;
+    maturity?: LearningMaturity;
+    created?: string;
+    first_seen_ts?: string;
+    last_seen_ts?: string;
+    project?: string | null;
+}
+export interface LearningsParseResult {
+    ok: boolean;
+    none: boolean;
+    entries: LearningSeedEntry[];
+    errors: string[];
+    details: string;
+}
+export declare function parseLearningsSection(sectionBody: string): LearningsParseResult;
 export declare function lintArtifact(projectRoot: string, stage: FlowStage): Promise<LintResult>;
 export declare function lintAllArtifacts(projectRoot: string): Promise<LintResult[]>;
 export declare function validateReviewArmy(projectRoot: string): Promise<{

package/dist/artifact-linter.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
 import { exists } from "./fs-utils.js";
 import { orderedStageSchemas, stageSchema } from "./content/stage-schema.js";
+import { FLOW_STAGES } from "./types.js";
 async function resolveArtifactPath(projectRoot, fileName) {
     const relPath = path.join(RUNTIME_ROOT, "artifacts", fileName);
     const absPath = path.join(projectRoot, relPath);
@@ -55,6 +56,9 @@ function sectionBodyByName(sections, section) {
     }
     return null;
 }
+export function extractMarkdownSectionBody(markdown, section) {
+    return sectionBodyByName(extractH2Sections(markdown), section);
+}
 function meaningfulLineCount(sectionBody) {
     return sectionBody
         .split(/\r?\n/)
@@ -179,6 +183,211 @@ function getMarkdownTableRows(sectionBody) {
     }
     return rows;
 }
+const LEARNING_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
+const LEARNING_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
+const LEARNING_UNIVERSALITY_SET = new Set(["project", "personal", "universal"]);
+const LEARNING_MATURITY_SET = new Set(["raw", "lifted-to-rule", "lifted-to-enforcement"]);
+const FLOW_STAGE_SET = new Set(FLOW_STAGES);
+const LEARNING_ALLOWED_KEYS = new Set([
+    "type",
+    "trigger",
+    "action",
+    "confidence",
+    "domain",
+    "stage",
+    "origin_stage",
+    "origin_feature",
+    "frequency",
+    "universality",
+    "maturity",
+    "created",
+    "first_seen_ts",
+    "last_seen_ts",
+    "project"
+]);
+function isIsoUtcTimestamp(value) {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u.test(value);
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function isNullableStage(value) {
+    return value === null || (typeof value === "string" && FLOW_STAGE_SET.has(value));
+}
+function parseLearningSeedEntry(raw, index) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, error: `Learnings bullet #${index} must be a JSON object.` };
+    }
+    const obj = raw;
+    for (const key of Object.keys(obj)) {
+        if (!LEARNING_ALLOWED_KEYS.has(key)) {
+            return {
+                ok: false,
+                error: `Learnings bullet #${index} includes unknown key "${key}" (allowed keys mirror knowledge JSONL fields).`
+            };
+        }
+    }
+    const type = typeof obj.type === "string" ? obj.type.toLowerCase() : "";
+    if (!LEARNING_TYPE_SET.has(type)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} must set type to one of: rule, pattern, lesson, compound.`
+        };
+    }
+    const trigger = typeof obj.trigger === "string" ? obj.trigger.trim() : "";
+    if (trigger.length === 0) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} must include non-empty "trigger".`
+        };
+    }
+    const action = typeof obj.action === "string" ? obj.action.trim() : "";
+    if (action.length === 0) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} must include non-empty "action".`
+        };
+    }
+    const confidence = typeof obj.confidence === "string" ? obj.confidence.toLowerCase() : "";
+    if (!LEARNING_CONFIDENCE_SET.has(confidence)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} must set confidence to high|medium|low.`
+        };
+    }
+    if (obj.domain !== undefined && !isNullableString(obj.domain)) {
+        return { ok: false, error: `Learnings bullet #${index} field "domain" must be string or null.` };
+    }
+    if (obj.stage !== undefined && !isNullableStage(obj.stage)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "stage" must be one of ${FLOW_STAGES.join(", ")} or null.`
+        };
+    }
+    if (obj.origin_stage !== undefined && !isNullableStage(obj.origin_stage)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "origin_stage" must be one of ${FLOW_STAGES.join(", ")} or null.`
+        };
+    }
+    if (obj.origin_feature !== undefined && !isNullableString(obj.origin_feature)) {
+        return { ok: false, error: `Learnings bullet #${index} field "origin_feature" must be string or null.` };
+    }
+    if (obj.project !== undefined && !isNullableString(obj.project)) {
+        return { ok: false, error: `Learnings bullet #${index} field "project" must be string or null.` };
+    }
+    if (obj.frequency !== undefined &&
+        (typeof obj.frequency !== "number" || !Number.isInteger(obj.frequency) || obj.frequency < 1)) {
+        return { ok: false, error: `Learnings bullet #${index} field "frequency" must be an integer >= 1.` };
+    }
+    if (obj.universality !== undefined &&
+        (typeof obj.universality !== "string" ||
+            !LEARNING_UNIVERSALITY_SET.has(obj.universality))) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "universality" must be project|personal|universal.`
+        };
+    }
+    if (obj.maturity !== undefined &&
+        (typeof obj.maturity !== "string" || !LEARNING_MATURITY_SET.has(obj.maturity))) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "maturity" must be raw|lifted-to-rule|lifted-to-enforcement.`
+        };
+    }
+    for (const timestampField of ["created", "first_seen_ts", "last_seen_ts"]) {
+        const value = obj[timestampField];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string" || !isIsoUtcTimestamp(value)) {
+            return {
+                ok: false,
+                error: `Learnings bullet #${index} field "${timestampField}" must be ISO UTC (YYYY-MM-DDTHH:MM:SSZ).`
+            };
+        }
+    }
+    return {
+        ok: true,
+        entry: {
+            ...obj,
+            type: type,
+            trigger,
+            action,
+            confidence: confidence
+        }
+    };
+}
+export function parseLearningsSection(sectionBody) {
+    const lines = sectionBody.split(/\r?\n/).map((line) => line.trim());
+    const nonEmpty = lines.filter((line) => line.length > 0);
+    const bullets = nonEmpty.filter((line) => /^-\s+\S+/u.test(line));
+    if (bullets.length === 0) {
+        return {
+            ok: false,
+            none: false,
+            entries: [],
+            errors: ["Learnings section must contain bullet entries."],
+            details: "Learnings section must contain bullet entries."
+        };
+    }
+    const nonBulletContent = nonEmpty.filter((line) => !/^-\s+\S+/u.test(line));
+    if (nonBulletContent.length > 0) {
+        return {
+            ok: false,
+            none: false,
+            entries: [],
+            errors: ["Learnings section must only contain bullet lines (one bullet per learning)."],
+            details: "Learnings section must only contain bullet lines (one bullet per learning)."
+        };
+    }
+    if (bullets.length === 1) {
+        const payload = bullets[0].replace(/^-\s+/u, "").trim();
+        if (/^none this stage\.?$/iu.test(payload)) {
+            return {
+                ok: true,
+                none: true,
+                entries: [],
+                errors: [],
+                details: "Learnings section explicitly marked as none."
+            };
+        }
+    }
+    const entries = [];
+    const errors = [];
+    for (let i = 0; i < bullets.length; i += 1) {
+        const payload = bullets[i].replace(/^-\s+/u, "").trim();
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch (err) {
+            errors.push(`Learnings bullet #${i + 1} must be valid JSON object or "None this stage.": ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        const parsedEntry = parseLearningSeedEntry(parsed, i + 1);
+        if (!parsedEntry.ok || !parsedEntry.entry) {
+            errors.push(parsedEntry.error ?? `Learnings bullet #${i + 1} is invalid.`);
+            continue;
+        }
+        entries.push(parsedEntry.entry);
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            none: false,
+            entries: [],
+            errors,
+            details: errors.join(" | ")
+        };
+    }
+    return {
+        ok: true,
+        none: false,
+        entries,
+        errors: [],
+        details: `Parsed ${entries.length} learning bullet(s) as knowledge-compatible JSON entries.`
+    };
+}
 function lineContainsVagueAdjective(text) {
     const lower = text.toLowerCase();
     for (const adjective of VAGUE_AC_ADJECTIVES) {
@@ -453,6 +662,27 @@ export async function lintArtifact(projectRoot, stage) {
                 : validation.details
         });
     }
+    const learningsBody = sectionBodyByName(sections, "Learnings");
+    const requireLearnings = parsedFrontmatter.hasFrontmatter;
+    if (learningsBody === null) {
+        findings.push({
+            section: "Learnings",
+            required: requireLearnings,
+            rule: "Required for schema-v1 artifacts: include `## Learnings` with bullets of strict JSON objects compatible with knowledge.jsonl schema, or a single `- None this stage.` sentinel.",
+            found: false,
+            details: "No ## heading matching required section \"Learnings\"."
+        });
+    }
+    else {
+        const learnings = parseLearningsSection(learningsBody);
+        findings.push({
+            section: "Learnings",
+            required: requireLearnings,
+            rule: "`## Learnings` must contain either a single `- None this stage.` bullet or JSON bullets compatible with knowledge.jsonl fields (type/trigger/action/confidence required).",
+            found: learnings.ok,
+            details: learnings.details
+        });
+    }
     if (stage === "plan") {
         const strictPlanGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "No-Placeholder Scan") ||

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/learnings.js

@@ -49,6 +49,20 @@ Use the store to keep durable knowledge that should survive sessions:
 - **lesson**: non-obvious outcome from a failure or trade-off.
 - **compound**: post-ship insight about how to make the *next* feature faster (process accelerator, not domain rule).
 
+## Continuous capture (stage closeout path)
+
+Knowledge capture is now stage-native:
+- Each stage artifact has a \`## Learnings\` section.
+- Allowed payloads:
+  - \`- None this stage.\` (explicit no-op)
+  - JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (optional keys may mirror the full JSONL schema fields).
+- During \`bash .cclaw/hooks/stage-complete.sh <stage>\`, cclaw:
+  1. validates \`## Learnings\`,
+  2. appends deduped entries to \`${KNOWLEDGE_PATH}\`,
+  3. writes a harvest marker into the artifact.
+
+\`/cc-learn\` remains the manual/query surface (search, backfill, curation).
+
 ## HARD-GATE
 
 Under \`/cc-learn\`, only modify \`${KNOWLEDGE_PATH}\`, \`${KNOWLEDGE_ARCHIVE_PATH}\`,
@@ -113,6 +127,7 @@ Rules:
 - Ask for required user-facing fields in order: \`type\`, \`trigger\`, \`action\`, \`confidence\`, \`domain\`, \`stage\`, \`universality\`, \`project\`.
 - \`confidence\` must be one of \`high\`, \`medium\`, \`low\`. Default to \`medium\` if the user declines to set it.
 - \`domain\`, \`stage\`, and \`project\` may be explicitly \`null\`.
+- Prefer stage-native \`## Learnings\` capture for new flow work; use \`add\` mainly for backfilling historical lessons or ad-hoc entries outside a stage closeout.
 - \`origin_stage\` defaults to \`stage\`; \`origin_feature\` defaults to active feature (or \`null\` if unknown).
 - \`frequency\` starts at \`1\`.
 - \`maturity\` starts at \`raw\`.
@@ -136,6 +151,11 @@ Manage the project knowledge store. One canonical file, strict JSONL:
 - \`${KNOWLEDGE_PATH}\` — append-only JSONL, one entry per line.
 - \`${KNOWLEDGE_ARCHIVE_PATH}\` — soft-archive target written only by curate.
 
+Stage-native pipeline:
+- During \`stage-complete.sh\`, cclaw harvests \`## Learnings\` from the current
+  stage artifact into \`${KNOWLEDGE_PATH}\` automatically.
+- Use \`/cc-learn\` for query, backfill, and curation workflows.
+
 ## HARD-GATE
 
 Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`,

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