cclaw-cli 0.43.0 → 0.45.0

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,7 +222,10 @@ function completionParametersBlock(schema) {
 - \`gates\`: ${gateList}
 - \`artifact\`: \`${RUNTIME_ROOT}/artifacts/${schema.artifactFile}\`
 - \`mandatory delegations\`: ${mandatory}
-
+- \`completion helper\`: \`bash .cclaw/hooks/stage-complete.sh ${schema.stage}\`
+- Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
+- 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/stage-common-guidance.js

@@ -58,8 +58,15 @@ Rollback / fallback: <if decision proves wrong>
 
 ## Self-improvement reminder
 
-Before closeout, capture 1-3 reusable insights in \`.cclaw/knowledge.jsonl\`
-whenever the stage produced non-obvious decisions, patterns, or lessons.
+Before closeout, fill the artifact \`## Learnings\` section (do not write
+\`.cclaw/knowledge.jsonl\` by hand):
+- \`- None this stage.\` when nothing reusable emerged.
+- Or 1-3 JSON bullets with required keys \`type\`, \`trigger\`, \`action\`,
+  \`confidence\` (optional fields may mirror knowledge.jsonl schema keys).
+During \`bash .cclaw/hooks/stage-complete.sh <stage>\`, cclaw validates those
+bullets, appends unique entries to \`.cclaw/knowledge.jsonl\`, and stamps a
+harvest marker in the artifact.
+
 Prefer \`type=rule|pattern|lesson\` (\`compound\` stays retro-focused).
 
 Track policy:
@@ -67,8 +74,8 @@ Track policy:
   recommended for other stages.
 - \`quick\`: recommended only.
 
-"No learning captured" is acceptable only with an explicit reason
-(for example, purely mechanical edits with no new decisions).
+\`- None this stage.\` is acceptable only when the stage produced no reusable
+insight (for example, purely mechanical edits with no new decisions).
 
 ## Progressive disclosure baseline
 

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/content/templates.js

@@ -45,6 +45,9 @@ inputs_hash: sha256:pending
 ## Assumptions and Open Questions
 - **Assumptions:**
 - **Open questions (or "None"):**
+
+## Learnings
+- None this stage.
 `,
     "02-scope.md": `---
 stage: scope
@@ -148,6 +151,9 @@ inputs_hash: sha256:pending
 - Accepted scope:
 - Deferred:
 - Explicitly excluded:
+
+## Learnings
+- None this stage.
 `,
     "03-design.md": `---
 stage: design
@@ -241,6 +247,9 @@ inputs_hash: sha256:pending
 | Distribution & Delivery Review |  |  |
 
 **Decisions made:** 0 | **Unresolved:** 0
+
+## Learnings
+- None this stage.
 `,
     "04-spec.md": `---
 stage: spec
@@ -294,6 +303,9 @@ inputs_hash: sha256:pending
 ## Approval
 - Approved by:
 - Date:
+
+## Learnings
+- None this stage.
 `,
     "05-plan.md": `---
 stage: plan
@@ -370,6 +382,9 @@ Execution rule: complete and verify each batch before starting the next batch.
 ## WAIT_FOR_CONFIRM
 - Status: pending
 - Confirmed by:
+
+## Learnings
+- None this stage.
 `,
     "06-tdd.md": `---
 stage: tdd
@@ -434,6 +449,9 @@ inputs_hash: sha256:pending
 | Slice | Reproduction test | RED-without-fix evidence | GREEN-with-fix evidence | Revert-guard note |
 |---|---|---|---|---|
 | S-1 |  |  |  |  |
+
+## Learnings
+- None this stage.
 `,
     "07-review.md": `---
 stage: review
@@ -504,6 +522,9 @@ inputs_hash: sha256:pending
 
 ## Final Verdict
 - APPROVED | APPROVED_WITH_CONCERNS | BLOCKED
+
+## Learnings
+- None this stage.
 `,
     "07-review-army.json": `{
   "version": 1,
@@ -571,6 +592,9 @@ inputs_hash: sha256:pending
 - Run \`/cc-ops retro\` before archive.
 - Retro artifact path: \`.cclaw/artifacts/09-retro.md\`
 - Archive remains blocked until retro gate is complete.
+
+## Learnings
+- None this stage.
 `,
     "09-retro.md": `---
 stage: retro
@@ -611,6 +635,9 @@ inputs_hash: sha256:pending
 - RETRO_COMPLETE: yes
 - Completed at (UTC):
 - Notes:
+
+## Learnings
+- None this stage.
 `
 };
 export const RULEBOOK_MARKDOWN = `# Cclaw Rulebook

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 {};