cclaw-cli 0.48.5 → 0.48.7

package/dist/artifact-linter.js

@@ -1092,6 +1092,14 @@ export async function validateReviewArmy(projectRoot) {
     }
     const severitySet = new Set(["Critical", "Important", "Suggestion"]);
     const statusSet = new Set(["open", "accepted", "resolved"]);
+    const sourceSet = new Set([
+        "spec",
+        "correctness",
+        "security",
+        "performance",
+        "architecture",
+        "external-safety"
+    ]);
     const findingIds = new Set();
     const openCriticalIds = new Set();
     if (!Array.isArray(root.findings)) {
@@ -1128,6 +1136,17 @@ export async function validateReviewArmy(projectRoot) {
             if (!isStringArray(o.reportedBy) || o.reportedBy.length === 0) {
                 errors.push(`findings[${i}].reportedBy must be a non-empty string array.`);
             }
+            if (o.sources !== undefined) {
+                if (!isStringArray(o.sources) || o.sources.length === 0) {
+                    errors.push(`findings[${i}].sources must be a non-empty string array when present.`);
+                }
+                else {
+                    const invalidSources = o.sources.filter((source) => !sourceSet.has(source));
+                    if (invalidSources.length > 0) {
+                        errors.push(`findings[${i}].sources contains unknown values: ${invalidSources.join(", ")}.`);
+                    }
+                }
+            }
             if (o.location === undefined || o.location === null) {
                 errors.push(`findings[${i}].location is required and must be an object with file + line.`);
             }
@@ -1231,6 +1250,19 @@ export async function validateReviewArmy(projectRoot) {
                 }
             }
         }
+        if (rec.layerCoverage !== undefined) {
+            if (rec.layerCoverage === null || typeof rec.layerCoverage !== "object" || Array.isArray(rec.layerCoverage)) {
+                errors.push("reconciliation.layerCoverage must be an object when present.");
+            }
+            else {
+                const coverage = rec.layerCoverage;
+                for (const source of sourceSet) {
+                    if (coverage[source] !== undefined && typeof coverage[source] !== "boolean") {
+                        errors.push(`reconciliation.layerCoverage.${source} must be boolean when present.`);
+                    }
+                }
+            }
+        }
     }
     return { valid: errors.length === 0, errors };
 }

package/dist/config.d.ts

@@ -42,7 +42,7 @@ export declare function readConfig(projectRoot: string): Promise<CclawConfig>;
  * 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" | "tdd" | "compound" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview";
+type AdvancedConfigKey = "promptGuardMode" | "tddEnforcement" | "tddTestGlobs" | "tdd" | "compound" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview" | "ironLaws";
 /**
  * Options controlling the serialisation shape of `config.yaml`.
  *

package/dist/config.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { parse, stringify } from "yaml";
 import { CCLAW_VERSION, DEFAULT_HARNESSES, FLOW_VERSION, RUNTIME_ROOT } from "./constants.js";
+import { isIronLawId, normalizeStrictLawIds } from "./content/iron-laws.js";
 import { exists, writeFileSafe } from "./fs-utils.js";
 import { FLOW_TRACKS, HARNESS_IDS, LANGUAGE_RULE_PACKS } from "./types.js";
 const CONFIG_PATH = `${RUNTIME_ROOT}/config.yaml`;
@@ -25,7 +26,8 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "defaultTrack",
     "languageRulePacks",
     "trackHeuristics",
-    "sliceReview"
+    "sliceReview",
+    "ironLaws"
 ]);
 /**
  * Config keys always present in the minimal init template. Everything else
@@ -141,7 +143,11 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack
         },
         gitHookGuards: false,
         defaultTrack,
-        languageRulePacks: []
+        languageRulePacks: [],
+        ironLaws: {
+            mode: "advisory",
+            strictLaws: []
+        }
     };
 }
 /**
@@ -409,6 +415,36 @@ export async function readConfig(projectRoot) {
             enforceOnTracks: enforceOnTracks ?? DEFAULT_SLICE_REVIEW_TRACKS
         };
     }
+    const ironLawsRaw = parsed.ironLaws;
+    let ironLaws = undefined;
+    if (Object.prototype.hasOwnProperty.call(parsed, "ironLaws")) {
+        if (!isRecord(ironLawsRaw)) {
+            throw configValidationError(fullPath, `"ironLaws" must be an object`);
+        }
+        const unknownIronLawKeys = Object.keys(ironLawsRaw).filter((key) => key !== "mode" && key !== "strictLaws");
+        if (unknownIronLawKeys.length > 0) {
+            throw configValidationError(fullPath, `"ironLaws" has unknown key(s): ${unknownIronLawKeys.join(", ")}`);
+        }
+        const modeRaw = ironLawsRaw.mode;
+        if (modeRaw !== undefined && modeRaw !== "advisory" && modeRaw !== "strict") {
+            throw configValidationError(fullPath, `"ironLaws.mode" must be "advisory" or "strict"`);
+        }
+        const strictLawIdsRaw = validateStringArray(ironLawsRaw.strictLaws, "ironLaws.strictLaws", fullPath) ?? [];
+        const unknownStrictLawIds = strictLawIdsRaw.filter((id) => !isIronLawId(id));
+        if (unknownStrictLawIds.length > 0) {
+            throw configValidationError(fullPath, `"ironLaws.strictLaws" contains unknown law id(s): ${unknownStrictLawIds.join(", ")}`);
+        }
+        ironLaws = {
+            mode: modeRaw === "strict" ? "strict" : "advisory",
+            strictLaws: normalizeStrictLawIds(strictLawIdsRaw)
+        };
+    }
+    else {
+        ironLaws = {
+            mode: strictness,
+            strictLaws: []
+        };
+    }
     return {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
@@ -428,7 +464,8 @@ export async function readConfig(projectRoot) {
         defaultTrack,
         languageRulePacks,
         trackHeuristics,
-        sliceReview
+        sliceReview,
+        ironLaws
     };
 }
 function isMinimalKey(key) {
@@ -452,7 +489,8 @@ function buildSerializableConfig(config, options = {}) {
         "defaultTrack",
         "languageRulePacks",
         "trackHeuristics",
-        "sliceReview"
+        "sliceReview",
+        "ironLaws"
     ];
     for (const key of ordered) {
         const value = config[key];
@@ -506,7 +544,8 @@ export async function detectAdvancedKeys(projectRoot) {
             "defaultTrack",
             "languageRulePacks",
             "trackHeuristics",
-            "sliceReview"
+            "sliceReview",
+            "ironLaws"
         ];
         const present = new Set();
         for (const key of advancedCandidates) {

package/dist/content/hooks.d.ts

@@ -8,7 +8,8 @@
 export interface HookRuntimeOptions {
 }
 /** Shared bash preamble for generated hook scripts. */
-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 const RUNTIME_SHELL_DETECT_ROOT = "CCLAW_HOOK_LIB_PATH=\"\"\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\" ] && [ -f \"$candidate/.cclaw/hooks/_lib.sh\" ]; then\n    CCLAW_HOOK_LIB_PATH=\"$candidate/.cclaw/hooks/_lib.sh\"\n    break\n  fi\ndone\nif [ -n \"$CCLAW_HOOK_LIB_PATH\" ] && [ -f \"$CCLAW_HOOK_LIB_PATH\" ]; then\n  # shellcheck disable=SC1090\n  . \"$CCLAW_HOOK_LIB_PATH\"\nfi\n\nif command -v cclaw_hook_detect_root >/dev/null 2>&1; then\n  cclaw_hook_detect_root\nelse\n  HARNESS=\"codex\"\n  if [ -n \"${CLAUDE_PROJECT_DIR:-}\" ]; then\n    HARNESS=\"claude\"\n  elif [ -n \"${CURSOR_PROJECT_DIR:-}\" ] || [ -n \"${CURSOR_PROJECT_ROOT:-}\" ]; then\n    HARNESS=\"cursor\"\n  elif [ -n \"${OPENCODE_PROJECT_DIR:-}\" ] || [ -n \"${OPENCODE_PROJECT_ROOT:-}\" ]; then\n    HARNESS=\"opencode\"\n  fi\n\n  ROOT=\"\"\n  for 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\n  done\n  if [ -z \"$ROOT\" ]; then\n    ROOT=\"${CCLAW_PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-${CURSOR_PROJECT_ROOT:-${OPENCODE_PROJECT_DIR:-${OPENCODE_PROJECT_ROOT:-${PWD}}}}}}}\"\n  fi\nfi";
+export declare function hookLibScript(): string;
 export declare function sessionStartScript(_options?: HookRuntimeOptions): string;
 export declare function stopCheckpointScript(): string;
 export declare function runHookDispatcherScript(): string;
@@ -18,4 +19,3 @@ export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js"
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";
 export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";
 export { opencodePluginJs } from "./opencode-plugin.js";
-export declare function hooksAgentsMdBlock(): string;

package/dist/content/hooks.js

@@ -15,39 +15,201 @@ const ESCAPE_FN = `escape_json() {
   str=\${str//$'\\n'/\\\\n}
   printf '%s' "$str"
 }`;
-const DETECT_ROOT = `HARNESS="codex"
-if [ -n "\${CLAUDE_PROJECT_DIR:-}" ]; then
-  HARNESS="claude"
-elif [ -n "\${CURSOR_PROJECT_DIR:-}" ] || [ -n "\${CURSOR_PROJECT_ROOT:-}" ]; then
-  HARNESS="cursor"
-elif [ -n "\${OPENCODE_PROJECT_DIR:-}" ] || [ -n "\${OPENCODE_PROJECT_ROOT:-}" ]; then
-  HARNESS="opencode"
-fi
-
-ROOT=""
+const HOOK_LIB_FILE = "_lib.sh";
+/** Shared bash preamble for generated hook scripts. */
+export const RUNTIME_SHELL_DETECT_ROOT = `CCLAW_HOOK_LIB_PATH=""
 for candidate in "\${CCLAW_PROJECT_ROOT:-}" "\${CLAUDE_PROJECT_DIR:-}" "\${CURSOR_PROJECT_DIR:-}" "\${CURSOR_PROJECT_ROOT:-}" "\${OPENCODE_PROJECT_DIR:-}" "\${OPENCODE_PROJECT_ROOT:-}" "\${PWD:-}"; do
-  if [ -n "$candidate" ] && [ -d "$candidate/${RUNTIME_ROOT}" ]; then
-    ROOT="$candidate"
+  if [ -n "$candidate" ] && [ -f "$candidate/${RUNTIME_ROOT}/hooks/${HOOK_LIB_FILE}" ]; then
+    CCLAW_HOOK_LIB_PATH="$candidate/${RUNTIME_ROOT}/hooks/${HOOK_LIB_FILE}"
     break
   fi
 done
-if [ -z "$ROOT" ]; then
-  ROOT="\${CCLAW_PROJECT_ROOT:-\${CLAUDE_PROJECT_DIR:-\${CURSOR_PROJECT_DIR:-\${CURSOR_PROJECT_ROOT:-\${OPENCODE_PROJECT_DIR:-\${OPENCODE_PROJECT_ROOT:-\${PWD}}}}}}}"
+if [ -n "$CCLAW_HOOK_LIB_PATH" ] && [ -f "$CCLAW_HOOK_LIB_PATH" ]; then
+  # shellcheck disable=SC1090
+  . "$CCLAW_HOOK_LIB_PATH"
+fi
+
+if command -v cclaw_hook_detect_root >/dev/null 2>&1; then
+  cclaw_hook_detect_root
+else
+  HARNESS="codex"
+  if [ -n "\${CLAUDE_PROJECT_DIR:-}" ]; then
+    HARNESS="claude"
+  elif [ -n "\${CURSOR_PROJECT_DIR:-}" ] || [ -n "\${CURSOR_PROJECT_ROOT:-}" ]; then
+    HARNESS="cursor"
+  elif [ -n "\${OPENCODE_PROJECT_DIR:-}" ] || [ -n "\${OPENCODE_PROJECT_ROOT:-}" ]; then
+    HARNESS="opencode"
+  fi
+
+  ROOT=""
+  for candidate in "\${CCLAW_PROJECT_ROOT:-}" "\${CLAUDE_PROJECT_DIR:-}" "\${CURSOR_PROJECT_DIR:-}" "\${CURSOR_PROJECT_ROOT:-}" "\${OPENCODE_PROJECT_DIR:-}" "\${OPENCODE_PROJECT_ROOT:-}" "\${PWD:-}"; do
+    if [ -n "$candidate" ] && [ -d "$candidate/${RUNTIME_ROOT}" ]; then
+      ROOT="$candidate"
+      break
+    fi
+  done
+  if [ -z "$ROOT" ]; then
+    ROOT="\${CCLAW_PROJECT_ROOT:-\${CLAUDE_PROJECT_DIR:-\${CURSOR_PROJECT_DIR:-\${CURSOR_PROJECT_ROOT:-\${OPENCODE_PROJECT_DIR:-\${OPENCODE_PROJECT_ROOT:-\${PWD}}}}}}}"
+  fi
 fi`;
-/** Shared bash preamble for generated hook scripts. */
-export const RUNTIME_SHELL_DETECT_ROOT = DETECT_ROOT;
+export function hookLibScript() {
+    return `#!/usr/bin/env bash
+# cclaw shared hook library — generated by cclaw sync
+# Shared helper functions for root detection and lightweight JSON parsing.
+
+cclaw_hook_detect_root() {
+  HARNESS="codex"
+  if [ -n "\${CLAUDE_PROJECT_DIR:-}" ]; then
+    HARNESS="claude"
+  elif [ -n "\${CURSOR_PROJECT_DIR:-}" ] || [ -n "\${CURSOR_PROJECT_ROOT:-}" ]; then
+    HARNESS="cursor"
+  elif [ -n "\${OPENCODE_PROJECT_DIR:-}" ] || [ -n "\${OPENCODE_PROJECT_ROOT:-}" ]; then
+    HARNESS="opencode"
+  fi
+
+  ROOT=""
+  for candidate in "\${CCLAW_PROJECT_ROOT:-}" "\${CLAUDE_PROJECT_DIR:-}" "\${CURSOR_PROJECT_DIR:-}" "\${CURSOR_PROJECT_ROOT:-}" "\${OPENCODE_PROJECT_DIR:-}" "\${OPENCODE_PROJECT_ROOT:-}" "\${PWD:-}"; do
+    if [ -n "$candidate" ] && [ -d "$candidate/${RUNTIME_ROOT}" ]; then
+      ROOT="$candidate"
+      break
+    fi
+  done
+  if [ -z "$ROOT" ]; then
+    ROOT="\${CCLAW_PROJECT_ROOT:-\${CLAUDE_PROJECT_DIR:-\${CURSOR_PROJECT_DIR:-\${CURSOR_PROJECT_ROOT:-\${OPENCODE_PROJECT_DIR:-\${OPENCODE_PROJECT_ROOT:-\${PWD}}}}}}}"
+  fi
+}
+
+cclaw_hook_lower() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]'
+}
+
+cclaw_hook_extract_tool_and_payload() {
+  local input_json="$1"
+  CCLAW_HOOK_TOOL="unknown"
+  CCLAW_HOOK_PAYLOAD=""
+  if command -v jq >/dev/null 2>&1; then
+    CCLAW_HOOK_TOOL=$(printf '%s' "$input_json" | jq -r '.tool_name // .tool // .toolName // .name // .id // .command // .tool.name // .tool.id // .input.tool_name // .input.tool // .input.toolName // .input.name // .input.id // .input.command // .input.tool.name // .input.tool.id // "unknown"' 2>/dev/null || echo "unknown")
+    CCLAW_HOOK_PAYLOAD=$(printf '%s' "$input_json" | jq -r '.tool_input // .input // .arguments // .params // .payload // {} | tostring' 2>/dev/null || echo "")
+  elif command -v python3 >/dev/null 2>&1; then
+    CCLAW_HOOK_TOOL=$(INPUT_JSON="$input_json" python3 - <<'PY'
+import json
+import os
+try:
+    value = json.loads(os.environ.get("INPUT_JSON", "{}"))
+except Exception:
+    value = {}
+
+def pick_tool(payload):
+    if not isinstance(payload, dict):
+        return "unknown"
+    candidates = [
+        payload.get("tool_name"),
+        payload.get("tool"),
+        payload.get("toolName"),
+        payload.get("name"),
+        payload.get("id"),
+        payload.get("command")
+    ]
+    top_tool = payload.get("tool")
+    if isinstance(top_tool, dict):
+        candidates.extend([top_tool.get("name"), top_tool.get("id")])
+    nested = payload.get("input")
+    if isinstance(nested, dict):
+        candidates.extend([
+            nested.get("tool_name"),
+            nested.get("tool"),
+            nested.get("toolName"),
+            nested.get("name"),
+            nested.get("id"),
+            nested.get("command")
+        ])
+        nested_tool = nested.get("tool")
+        if isinstance(nested_tool, dict):
+            candidates.extend([nested_tool.get("name"), nested_tool.get("id")])
+    for candidate in candidates:
+        if isinstance(candidate, str) and candidate.strip():
+            return candidate.strip()
+    return "unknown"
+
+print(pick_tool(value))
+PY
+)
+    CCLAW_HOOK_PAYLOAD=$(printf '%s' "$input_json")
+  else
+    CCLAW_HOOK_PAYLOAD=$(printf '%s' "$input_json")
+  fi
+  [ -n "$CCLAW_HOOK_PAYLOAD" ] || CCLAW_HOOK_PAYLOAD=$(printf '%s' "$input_json")
+  [ -n "$CCLAW_HOOK_TOOL" ] || CCLAW_HOOK_TOOL="unknown"
+}
+
+cclaw_hook_read_flow_state_minimal() {
+  local flow_state_file="$1"
+  CCLAW_HOOK_FLOW_STAGE="none"
+  CCLAW_HOOK_FLOW_RUN_ID="active"
+  CCLAW_HOOK_FLOW_COMPLETED="0"
+  [ -f "$flow_state_file" ] || return 0
+
+  if command -v jq >/dev/null 2>&1; then
+    CCLAW_HOOK_FLOW_STAGE=$(jq -r '.currentStage // "none"' "$flow_state_file" 2>/dev/null || echo "none")
+    CCLAW_HOOK_FLOW_RUN_ID=$(jq -r '.activeRunId // "active"' "$flow_state_file" 2>/dev/null || echo "active")
+    CCLAW_HOOK_FLOW_COMPLETED=$(jq -r '(.completedStages // []) | length' "$flow_state_file" 2>/dev/null || echo "0")
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    local flow_meta
+    flow_meta=$(python3 - "$flow_state_file" <<'PY'
+import json
+import sys
+stage = "none"
+run_id = "active"
+completed = 0
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        payload = json.load(fh)
+    stage_value = payload.get("currentStage")
+    run_value = payload.get("activeRunId")
+    completed_value = payload.get("completedStages")
+    if isinstance(stage_value, str) and stage_value:
+        stage = stage_value
+    if isinstance(run_value, str) and run_value:
+        run_id = run_value
+    if isinstance(completed_value, list):
+        completed = len(completed_value)
+except Exception:
+    pass
+print(stage)
+print(run_id)
+print(completed)
+PY
+)
+    {
+      IFS= read -r CCLAW_HOOK_FLOW_STAGE
+      IFS= read -r CCLAW_HOOK_FLOW_RUN_ID
+      IFS= read -r CCLAW_HOOK_FLOW_COMPLETED
+    } <<EOF
+$flow_meta
+EOF
+    [ -n "$CCLAW_HOOK_FLOW_STAGE" ] || CCLAW_HOOK_FLOW_STAGE="none"
+    [ -n "$CCLAW_HOOK_FLOW_RUN_ID" ] || CCLAW_HOOK_FLOW_RUN_ID="active"
+    [ -n "$CCLAW_HOOK_FLOW_COMPLETED" ] || CCLAW_HOOK_FLOW_COMPLETED="0"
+  fi
+}
+`;
+}
 export function sessionStartScript(_options = {}) {
     return `#!/usr/bin/env bash
 # cclaw session-start hook — generated by cclaw sync
 # Injects using-cclaw + flow status + active artifacts + compact knowledge digest + checkpoint/activity summary.
 set -euo pipefail
 
-${DETECT_ROOT}
+${RUNTIME_SHELL_DETECT_ROOT}
 
 STATE_FILE="$ROOT/${RUNTIME_ROOT}/state/flow-state.json"
 ACTIVE_FEATURE_FILE="$ROOT/${RUNTIME_ROOT}/state/active-feature.json"
 CHECKPOINT_FILE="$ROOT/${RUNTIME_ROOT}/state/checkpoint.json"
 ACTIVITY_FILE="$ROOT/${RUNTIME_ROOT}/state/stage-activity.jsonl"
+IRON_LAWS_FILE="$ROOT/${RUNTIME_ROOT}/state/iron-laws.json"
 SUGGESTION_MEMORY_FILE="$ROOT/${RUNTIME_ROOT}/state/suggestion-memory.json"
 CONTEXT_WARNINGS_FILE="$ROOT/${RUNTIME_ROOT}/state/context-warnings.jsonl"
 CONTEXT_MODE_FILE="$ROOT/${RUNTIME_ROOT}/state/context-mode.json"
@@ -352,74 +514,99 @@ if [ -f "$META_SKILL" ]; then
   META_CONTENT=$(cat "$META_SKILL" 2>/dev/null || echo "")
 fi
 
-# --- Build compact knowledge digest (stage-biased, top entries only) ---
+# --- Build compact knowledge digest (stage + branch + diff aware) ---
 KNOWLEDGE_DIGEST=""
 LEARNINGS_COUNT=0
 if [ -f "$KNOWLEDGE_FILE" ] && [ -s "$KNOWLEDGE_FILE" ]; then
   LEARNINGS_COUNT=$(grep -c '^{' "$KNOWLEDGE_FILE" 2>/dev/null || echo "0")
+fi
+
+if command -v cclaw >/dev/null 2>&1 && [ -f "$KNOWLEDGE_FILE" ] && [ -s "$KNOWLEDGE_FILE" ]; then
+  BRANCH_NAME=""
+  if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    BRANCH_NAME=$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  fi
+  DIFF_FILES_CSV=""
+  if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    DIFF_FILES_CSV=$(git -C "$ROOT" diff --name-only HEAD~5..HEAD 2>/dev/null | head -n 20 | tr '\n' ',' | sed 's/,$//' || echo "")
+  fi
+  OPEN_GATES_CSV=""
+  if [ -f "$STATE_FILE" ] && command -v jq >/dev/null 2>&1; then
+    OPEN_GATES_CSV=$(jq -r --arg stage "$STAGE" '
+      (.stageGateCatalog[$stage].required // [])
+      - (.stageGateCatalog[$stage].passed // [])
+      | join(",")
+    ' "$STATE_FILE" 2>/dev/null || echo "")
+  fi
+  DIGEST_CMD=(cclaw internal knowledge-digest --stage="$STAGE" --limit=8)
+  if [ -n "$BRANCH_NAME" ]; then
+    DIGEST_CMD+=("--branch=$BRANCH_NAME")
+  fi
+  if [ -n "$DIFF_FILES_CSV" ]; then
+    DIGEST_CMD+=("--diff-files=$DIFF_FILES_CSV")
+  fi
+  if [ -n "$OPEN_GATES_CSV" ]; then
+    DIGEST_CMD+=("--open-gates=$OPEN_GATES_CSV")
+  fi
+  KNOWLEDGE_DIGEST=$("\${DIGEST_CMD[@]}" 2>/dev/null || echo "")
+fi
+
+if [ -z "$KNOWLEDGE_DIGEST" ] && [ -f "$KNOWLEDGE_FILE" ] && [ -s "$KNOWLEDGE_FILE" ]; then
   if command -v jq >/dev/null 2>&1; then
-    KNOWLEDGE_DIGEST=$(tail -n 200 "$KNOWLEDGE_FILE" 2>/dev/null | jq -Rsc --arg stage "$STAGE" '
+    KNOWLEDGE_DIGEST=$(tail -n 120 "$KNOWLEDGE_FILE" 2>/dev/null | jq -Rsc --arg stage "$STAGE" '
       split("\\n")
       | map(select(length > 0))
       | map(try fromjson catch null)
       | map(select(type == "object"))
       | map(select((.stage // null) == $stage or (.stage // null) == null))
       | reverse
-      | .[0:8]
+      | .[0:6]
       | map("- [" + ((.confidence // "unknown")|tostring) + " • " + ((.stage // "global")|tostring) + " • " + ((.domain // "general")|tostring) + "] " + ((.trigger // "trigger")|tostring) + " -> " + ((.action // "action")|tostring))
       | join("\\n")
     ' 2>/dev/null || echo "")
+  else
+    KNOWLEDGE_DIGEST=$(tail -n 6 "$KNOWLEDGE_FILE" 2>/dev/null || echo "")
+  fi
+fi
+
+if [ -n "$KNOWLEDGE_DIGEST" ]; then
+  printf '# Knowledge digest (auto-generated)\\n\\n%s\\n' "$KNOWLEDGE_DIGEST" > "$KNOWLEDGE_DIGEST_FILE" 2>/dev/null || true
+elif [ -f "$KNOWLEDGE_DIGEST_FILE" ]; then
+  printf '# Knowledge digest (auto-generated)\\n\\n(no matching entries for current stage)\\n' > "$KNOWLEDGE_DIGEST_FILE" 2>/dev/null || true
+fi
+
+IRON_LAWS_SUMMARY=""
+if [ -f "$IRON_LAWS_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    IRON_LAWS_SUMMARY=$(jq -r '
+      (.laws // [])
+      | map("- [" + (if (.strict // false) then "strict" else "advisory" end) + "] " + ((.id // "law")|tostring) + " -> " + ((.rule // "")|tostring))
+      | .[0:6]
+      | join("\\n")
+    ' "$IRON_LAWS_FILE" 2>/dev/null || echo "")
   elif command -v python3 >/dev/null 2>&1; then
-    KNOWLEDGE_DIGEST=$(python3 - "$KNOWLEDGE_FILE" "$STAGE" <<'PY'
+    IRON_LAWS_SUMMARY=$(python3 - "$IRON_LAWS_FILE" <<'PY'
 import json
 import sys
-
-path = sys.argv[1]
-stage = sys.argv[2]
-entries = []
+out = []
 try:
-    with open(path, "r", encoding="utf-8") as fh:
-        lines = fh.readlines()[-200:]
-    for raw in lines:
-        raw = raw.strip()
-        if not raw:
-            continue
-        try:
-            obj = json.loads(raw)
-        except Exception:
-            continue
-        if not isinstance(obj, dict):
-            continue
-        row_stage = obj.get("stage")
-        if row_stage not in (stage, None):
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        parsed = json.load(fh)
+    for row in (parsed.get("laws") or [])[:6]:
+        if not isinstance(row, dict):
             continue
-        entries.append(obj)
+        strict = "strict" if row.get("strict") else "advisory"
+        law_id = str(row.get("id") or "law")
+        rule = str(row.get("rule") or "")
+        out.append(f"- [{strict}] {law_id} -> {rule}")
 except Exception:
-    entries = []
-
-entries = list(reversed(entries))[:8]
-out = []
-for obj in entries:
-    conf = str(obj.get("confidence", "unknown"))
-    row_stage = str(obj.get("stage", "global"))
-    domain = str(obj.get("domain", "general"))
-    trigger = str(obj.get("trigger", "trigger"))
-    action = str(obj.get("action", "action"))
-    out.append(f"- [{conf} • {row_stage} • {domain}] {trigger} -> {action}")
+    out = []
 print("\\n".join(out))
 PY
 )
-  else
-    KNOWLEDGE_DIGEST=$(tail -n 8 "$KNOWLEDGE_FILE" 2>/dev/null || echo "")
   fi
 fi
 
-if [ -n "$KNOWLEDGE_DIGEST" ]; then
-  printf '# Knowledge digest (auto-generated)\\n\\n%s\\n' "$KNOWLEDGE_DIGEST" > "$KNOWLEDGE_DIGEST_FILE" 2>/dev/null || true
-elif [ -f "$KNOWLEDGE_DIGEST_FILE" ]; then
-  printf '# Knowledge digest (auto-generated)\\n\\n(no matching entries for current stage)\\n' > "$KNOWLEDGE_DIGEST_FILE" 2>/dev/null || true
-fi
-
 # --- Installed cclaw-cli version vs. project's recorded version (one-block
 # upgrade-check, gstack-style). Purely informational — we never block. ---
 VERSION_NOTE=""
@@ -503,6 +690,11 @@ if [ -n "$KNOWLEDGE_DIGEST" ]; then
 Knowledge digest (top relevant entries):
 $KNOWLEDGE_DIGEST"
 fi
+if [ -n "$IRON_LAWS_SUMMARY" ]; then
+  CTX="$CTX
+Iron laws (enforced policy highlights):
+$IRON_LAWS_SUMMARY"
+fi
 if [ -n "$META_CONTENT" ]; then
   CTX="$CTX
 
@@ -536,7 +728,7 @@ export function stopCheckpointScript() {
 # Writes checkpoint state and reminds agent about flow/session consistency.
 set -euo pipefail
 
-${DETECT_ROOT}
+${RUNTIME_SHELL_DETECT_ROOT}
 
 INPUT=$(cat 2>/dev/null || echo '{}')
 
@@ -545,6 +737,7 @@ STATE_FILE="$STATE_DIR/flow-state.json"
 CHECKPOINT_FILE="$STATE_DIR/checkpoint.json"
 CHECKPOINT_TMP="$STATE_DIR/checkpoint.json.tmp.$$"
 CHECKPOINT_LOCK_DIR="$STATE_DIR/.checkpoint.lock"
+IRON_LAWS_FILE="$STATE_DIR/iron-laws.json"
 STAGE="none"
 ACTIVE_RUN="none"
 LOOP_COUNT=""
@@ -617,6 +810,38 @@ if command -v git >/dev/null 2>&1; then
   fi
 fi
 
+STRICT_STOP_DIRTY="false"
+if [ -f "$IRON_LAWS_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    STRICT_STOP_DIRTY=$(jq -r '
+      if (.mode // "advisory") == "strict" then "true"
+      elif ((.laws // []) | any(.id == "stop-clean-or-checkpointed" and .strict == true)) then "true"
+      else "false"
+      end
+    ' "$IRON_LAWS_FILE" 2>/dev/null || echo "false")
+  elif command -v python3 >/dev/null 2>&1; then
+    STRICT_STOP_DIRTY=$(python3 - "$IRON_LAWS_FILE" <<'PY'
+import json
+import sys
+value = "false"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        parsed = json.load(fh)
+    if str(parsed.get("mode", "advisory")) == "strict":
+        value = "true"
+    else:
+        for row in parsed.get("laws", []):
+            if isinstance(row, dict) and row.get("id") == "stop-clean-or-checkpointed" and row.get("strict") is True:
+                value = "true"
+                break
+except Exception:
+    value = "false"
+print(value)
+PY
+)
+  fi
+fi
+
 TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
 mkdir -p "$STATE_DIR" 2>/dev/null || true
 CHECKPOINT_WRITTEN=0
@@ -742,6 +967,11 @@ if [ "$CHECKPOINT_WRITTEN" -eq 0 ]; then
   CHECKPOINT_NOTE="Checkpoint update failed. Review ${RUNTIME_ROOT}/state/checkpoint.json manually."
 fi
 
+if [ "$DIRTY_STATE" = "dirty" ] && [ "$STRICT_STOP_DIRTY" = "true" ]; then
+  printf '[cclaw] Stop blocked by iron law "stop-clean-or-checkpointed": working tree is dirty. Commit/revert changes or update checkpoint blockers before ending the session.\\n' >&2
+  exit 1
+fi
+
 RUN_SYNC_NOTE="Run metadata sync removed; active artifacts stay in ${RUNTIME_ROOT}/artifacts until /cc-ops archive (or cclaw archive runtime)."
 
 # --- Escape for JSON ---
@@ -775,7 +1005,7 @@ export function runHookDispatcherScript() {
 # Single entrypoint used by harness hook JSON wiring.
 set -euo pipefail
 
-${DETECT_ROOT}
+${RUNTIME_SHELL_DETECT_ROOT}
 
 if [ "$#" -lt 1 ]; then
   printf 'Usage: bash ${RUNTIME_ROOT}/hooks/run-hook.cmd <session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor>\\n' >&2
@@ -826,7 +1056,7 @@ export function stageCompleteScript() {
 # mutation to \`cclaw internal advance-stage\`.
 set -euo pipefail
 
-${DETECT_ROOT}
+${RUNTIME_SHELL_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
@@ -857,9 +1087,7 @@ export function preCompactScript() {
 # having to re-derive it from scratch.
 set -uo pipefail
 
-${DETECT_ROOT}
-
-INPUT=$(cat 2>/dev/null || echo '{}')
+${RUNTIME_SHELL_DETECT_ROOT}
 
 STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
 STATE_FILE="$STATE_DIR/flow-state.json"
@@ -1004,27 +1232,3 @@ export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";
 // OpenCode plugin — JS module
 // ---------------------------------------------------------------------------
 export { opencodePluginJs } from "./opencode-plugin.js";
-// ---------------------------------------------------------------------------
-// AGENTS.md block for hooks
-// ---------------------------------------------------------------------------
-export function hooksAgentsMdBlock() {
-    return `### Hooks (real lifecycle integration)
-
-Cclaw generates real hook integrations for every harness that exposes a
-hook primitive:
-- **Claude/Cursor:** lifecycle rehydration + PreToolUse/PostToolUse + Stop
-- **OpenCode:** session lifecycle + system transform rehydration + bootstrap parity (digest/warnings/knowledge snapshot)
-- **Codex:** Codex CLI ≥ v0.114 exposes lifecycle hooks at \`.codex/hooks.json\`, gated behind \`[features] codex_hooks = true\` in \`~/.codex/config.toml\`. \`PreToolUse\`/\`PostToolUse\` intercept **only the \`Bash\` tool** in Codex; \`Write\`/\`Edit\`/\`WebSearch\`/MCP calls are substituted via the \`/cc\` skill bodies under \`.agents/skills/cc*/SKILL.md\` and explicit in-turn agent steps. See \`.cclaw/references/harnesses/codex-playbook.md\` for the coverage matrix.
-
-| Harness | Hook file | Events |
-|---------|-----------|--------|
-| Claude Code | \`.claude/hooks/hooks.json\` | SessionStart(startup/resume/clear/compact), PreToolUse, PostToolUse, Stop |
-| Cursor | \`.cursor/hooks.json\` | sessionStart/sessionResume/sessionClear/sessionCompact, preToolUse, postToolUse, stop |
-| OpenCode | \`${RUNTIME_ROOT}/hooks/opencode-plugin.mjs\` | session.created/updated/resumed/cleared/compacted/idle, tool.execute.before/after, system transform |
-| Codex | \`.codex/hooks.json\` | SessionStart(startup/resume), UserPromptSubmit, PreToolUse(Bash), PostToolUse(Bash), Stop (feature-gated by \`codex_hooks = true\`) |
-
-Hook state files:
-- \`${RUNTIME_ROOT}/state/stage-activity.jsonl\`
-- \`${RUNTIME_ROOT}/state/checkpoint.json\`
-`;
-}