cclaw-cli 0.48.4 → 0.48.6

package/dist/content/iron-laws.js

@@ -0,0 +1,182 @@
+import { RUNTIME_ROOT } from "../constants.js";
+export const IRON_LAWS = [
+    {
+        id: "tdd-red-before-write",
+        title: "RED before production write",
+        rule: "Do not edit production code in tdd stage before a failing RED test exists for the slice.",
+        rationale: "Prevents implementation-first behavior and keeps RED as executable specification.",
+        enforcement: "PreToolUse",
+        severity: "hard-gate",
+        appliesTo: ["tdd"],
+        hookMatcher: {
+            toolPattern: "write|edit|multiedit|applypatch|shell|bash",
+            payloadPattern: "\\.(ts|tsx|js|jsx|py|go|java|rs|rb|php|c|cc|cpp|h|hpp)"
+        }
+    },
+    {
+        id: "plan-requires-approval",
+        title: "No implementation before plan approval",
+        rule: "Do not perform write-like actions while plan stage is pending WAIT_FOR_CONFIRM approval.",
+        rationale: "Locks intent before execution and reduces expensive rework from unapproved paths.",
+        enforcement: "PreToolUse",
+        severity: "hard-gate",
+        appliesTo: ["plan"]
+    },
+    {
+        id: "runtime-writes-managed-only",
+        title: "Runtime writes are managed",
+        rule: `Do not mutate ${RUNTIME_ROOT}/state, ${RUNTIME_ROOT}/hooks, or ${RUNTIME_ROOT}/skills by ad-hoc edits unless using cclaw-managed commands.`,
+        rationale: "Protects generated runtime integrity and avoids drift that silently breaks hooks or skills.",
+        enforcement: "PreToolUse",
+        severity: "hard-gate",
+        appliesTo: "all",
+        hookMatcher: {
+            toolPattern: "write|edit|multiedit|delete|applypatch|shell|bash",
+            payloadPattern: "\\.cclaw/(state|hooks|skills)"
+        }
+    },
+    {
+        id: "flow-state-read-fresh",
+        title: "Fresh flow-state read required",
+        rule: `Before mutating actions, a fresh read of ${RUNTIME_ROOT}/state/flow-state.json must exist within guard freshness window.`,
+        rationale: "Prevents stale-stage mutations after context shifts or multi-agent divergence.",
+        enforcement: "PreToolUse",
+        severity: "hard-gate",
+        appliesTo: "all"
+    },
+    {
+        id: "review-layer-order",
+        title: "Review layers are sequential",
+        rule: "Review stage must complete Layer 1 spec compliance before Layer 2 quality/security passes.",
+        rationale: "Stops premature quality discussion when acceptance criteria are not yet satisfied.",
+        enforcement: "advisory",
+        severity: "soft-gate",
+        appliesTo: ["review"]
+    },
+    {
+        id: "review-criticals-close-before-ship",
+        title: "No ship with open criticals",
+        rule: "Ship decisions are blocked when review-army contains open Critical findings or ship blockers.",
+        rationale: "Enforces explicit risk closure before release finalization.",
+        enforcement: "PreToolUse",
+        severity: "hard-gate",
+        appliesTo: ["ship"]
+    },
+    {
+        id: "ship-preflight-required",
+        title: "Preflight required before finalization",
+        rule: "Do not execute release finalization actions until ship preflight gate is passed.",
+        rationale: "Catches regressions before irreversible release steps.",
+        enforcement: "PreToolUse",
+        severity: "hard-gate",
+        appliesTo: ["ship"]
+    },
+    {
+        id: "subagent-task-self-contained",
+        title: "Subagent tasks are self-contained",
+        rule: "Delegated tasks must include explicit objective, constraints, and expected output, not just references.",
+        rationale: "Avoids context loss and low-quality delegation in isolated worker contexts.",
+        enforcement: "advisory",
+        severity: "soft-gate",
+        appliesTo: "all"
+    },
+    {
+        id: "no-secrets-in-artifacts",
+        title: "Never log secrets in artifacts",
+        rule: "Secrets/tokens/passwords must not be written to review, ship, or runtime state artifacts.",
+        rationale: "Prevents accidental credential leakage through generated workflow artifacts.",
+        enforcement: "PostToolUse",
+        severity: "hard-gate",
+        appliesTo: "all"
+    },
+    {
+        id: "stop-clean-or-checkpointed",
+        title: "Stop only from clean checkpoint",
+        rule: "Do not end a session with dirty state unless checkpoint explicitly records unresolved work and blockers.",
+        rationale: "Protects continuity and prevents silent half-finished sessions.",
+        enforcement: "Stop",
+        severity: "hard-gate",
+        appliesTo: "all"
+    }
+];
+export function isIronLawId(value) {
+    return IRON_LAWS.some((law) => law.id === value);
+}
+export function normalizeStrictLawIds(ids) {
+    if (!Array.isArray(ids))
+        return [];
+    const unique = new Set();
+    for (const id of ids) {
+        if (typeof id !== "string")
+            continue;
+        const trimmed = id.trim();
+        if (!trimmed || !isIronLawId(trimmed))
+            continue;
+        unique.add(trimmed);
+    }
+    return [...unique];
+}
+export function ironLawRuntimeDocument(options = {}) {
+    const mode = options.mode === "strict" ? "strict" : "advisory";
+    const strictLawSet = new Set(normalizeStrictLawIds(options.strictLaws));
+    const laws = IRON_LAWS.map((law) => ({
+        id: law.id,
+        title: law.title,
+        rule: law.rule,
+        enforcement: law.enforcement,
+        severity: law.severity,
+        appliesTo: law.appliesTo === "all" ? "all" : [...law.appliesTo],
+        strict: mode === "strict" || strictLawSet.has(law.id),
+        hookMatcher: "hookMatcher" in law ? law.hookMatcher : undefined
+    }));
+    return {
+        version: 1,
+        generatedAt: options.nowIso ?? new Date().toISOString(),
+        mode,
+        strictLaws: [...strictLawSet],
+        laws
+    };
+}
+export function ironLawsAgentsMdBlock() {
+    const rows = IRON_LAWS.map((law) => {
+        return `| \`${law.id}\` | ${law.rule} | ${law.enforcement} | ${law.severity} |`;
+    }).join("\n");
+    return `### Iron Laws
+
+These rules are always-on. Hook-enforced laws can block actions in strict mode.
+
+| ID | Rule | Enforced by | Level |
+|---|---|---|---|
+${rows}
+`;
+}
+export function ironLawsSkillMarkdown() {
+    const list = IRON_LAWS.map((law, index) => {
+        const applies = law.appliesTo === "all" ? "all stages" : law.appliesTo.join(", ");
+        return `### ${index + 1}. ${law.title}
+
+- **ID:** \`${law.id}\`
+- **Rule:** ${law.rule}
+- **Why:** ${law.rationale}
+- **Applies to:** ${applies}
+- **Enforced by:** ${law.enforcement} (${law.severity})
+`;
+    }).join("\n");
+    return `---
+name: iron-laws
+description: "Non-negotiable workflow constraints enforced by cclaw hooks and routing."
+---
+
+# Iron Laws
+
+These are cclaw's non-negotiable constraints for harness sessions.  
+Use them as the final arbitration layer when local instructions conflict.
+
+${list}
+
+## Practical rule
+
+If a law says stop, stop and surface the blocking reason with the smallest safe
+next step.
+`;
+}

package/dist/content/meta-skill.js

@@ -85,6 +85,7 @@ Load utility skills only when triggered by the current task:
 - verification-before-completion before completion claims
 - finishing-a-development-branch during ship/finalization
 - document-review, receiving-code-review, and execution context skills
+- iron-laws as policy arbitration when instructions conflict
 - language rule packs from \`.cclaw/config.yaml\` when enabled
 
 Custom project skills under \`.cclaw/custom-skills/\` are opt-in supplements,

package/dist/content/next-command.js

@@ -102,6 +102,18 @@ This is the only progression command the user needs to drive the entire flow. St
   regenerating the retro draft.
 - No special resume command needed — \`/cc-next\` IS the resume command.
 
+## Headless mode
+
+When orchestrated by another skill/subagent, emit exactly one JSON envelope and
+no narrative text:
+
+\`\`\`json
+{"version":"1","kind":"gate-result","stage":"review","payload":{"command":"/cc-next","decision":"resume_or_advance","nextStage":"ship"},"emittedAt":"<ISO-8601>"}
+\`\`\`
+
+Validate envelopes with:
+\`cclaw internal envelope-validate --stdin\`
+
 ## Primary skill
 
 **${skillRel}** — full protocol and stage table.

package/dist/content/observe.js

@@ -179,6 +179,7 @@ ${RUNTIME_SHELL_DETECT_ROOT}
 STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
 FLOW_STATE_FILE="$STATE_DIR/flow-state.json"
 TDD_LOG_FILE="$STATE_DIR/tdd-cycle-log.jsonl"
+IRON_LAWS_FILE="$STATE_DIR/iron-laws.json"
 GUARD_STATE_FILE="$STATE_DIR/workflow-guard.json"
 GUARD_LOG="$STATE_DIR/workflow-guard.jsonl"
 mkdir -p "$STATE_DIR" 2>/dev/null || true
@@ -247,6 +248,14 @@ TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
 NOW_EPOCH=$(date +%s 2>/dev/null || echo "0")
 REASONS=""
 
+ACTIVE_AGENT="\${CCLAW_ACTIVE_AGENT:-}"
+if [ -z "$ACTIVE_AGENT" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    ACTIVE_AGENT=$(printf '%s' "$INPUT" | jq -r '.agent_name // .agent // .input.agent_name // .input.agent // .tool_input.agent_name // .tool_input.agent // ""' 2>/dev/null || echo "")
+  fi
+fi
+ACTIVE_AGENT_LOWER=$(printf '%s' "$ACTIVE_AGENT" | tr '[:upper:]' '[:lower:]')
+
 CURRENT_STAGE="none"
 CURRENT_RUN="active"
 if [ -f "$FLOW_STATE_FILE" ]; then
@@ -287,6 +296,87 @@ PY
   fi
 fi
 
+SHIP_PREFLIGHT_PASSED="false"
+if [ -f "$FLOW_STATE_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    SHIP_PREFLIGHT_PASSED=$(jq -r '
+      if ((.stageGateCatalog.ship.passed // []) | index("ship_preflight_passed")) == null
+      then "false"
+      else "true"
+      end
+    ' "$FLOW_STATE_FILE" 2>/dev/null || echo "false")
+  elif command -v python3 >/dev/null 2>&1; then
+    SHIP_PREFLIGHT_PASSED=$(python3 - "$FLOW_STATE_FILE" <<'PY'
+import json
+import sys
+value = "false"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        parsed = json.load(fh)
+    ship = ((parsed.get("stageGateCatalog") or {}).get("ship") or {}).get("passed") or []
+    if isinstance(ship, list) and "ship_preflight_passed" in ship:
+        value = "true"
+except Exception:
+    value = "false"
+print(value)
+PY
+)
+  fi
+fi
+
+IRON_LAW_STRICT_ALL="false"
+IRON_LAW_STRICT_IDS=""
+if [ -f "$IRON_LAWS_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    IRON_LAW_STRICT_ALL=$(jq -r 'if (.mode // "advisory") == "strict" then "true" else "false" end' "$IRON_LAWS_FILE" 2>/dev/null || echo "false")
+    IRON_LAW_STRICT_IDS=$(jq -r '(.laws // []) | map(select(.strict == true) | (.id // "")) | map(select(length > 0)) | join(",")' "$IRON_LAWS_FILE" 2>/dev/null || echo "")
+  elif command -v python3 >/dev/null 2>&1; then
+    IRON_LAW_STRICT_ALL=$(python3 - "$IRON_LAWS_FILE" <<'PY'
+import json
+import sys
+mode = "false"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        parsed = json.load(fh)
+    if str(parsed.get("mode", "advisory")) == "strict":
+        mode = "true"
+except Exception:
+    mode = "false"
+print(mode)
+PY
+)
+    IRON_LAW_STRICT_IDS=$(python3 - "$IRON_LAWS_FILE" <<'PY'
+import json
+import sys
+out = []
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        parsed = json.load(fh)
+    for row in parsed.get("laws", []):
+        if isinstance(row, dict) and row.get("strict") and isinstance(row.get("id"), str):
+            out.append(row["id"].strip())
+except Exception:
+    out = []
+print(",".join([v for v in out if v]))
+PY
+)
+  fi
+fi
+
+iron_law_is_strict() {
+  local law_id="$1"
+  if [ "$IRON_LAW_STRICT_ALL" = "true" ]; then
+    return 0
+  fi
+  if [ -z "$IRON_LAW_STRICT_IDS" ]; then
+    return 1
+  fi
+  case ",$IRON_LAW_STRICT_IDS," in
+    *",$law_id,"*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 LAST_FLOW_READ_AT=0
 if [ -f "$GUARD_STATE_FILE" ]; then
   if command -v jq >/dev/null 2>&1; then
@@ -332,6 +422,14 @@ is_mutating_tool() {
   esac
 }
 
+is_execution_or_mutating_tool() {
+  case "$1" in
+    write|edit|multiedit|multi_edit|delete|applypatch|apply_patch) return 0 ;;
+    shell|bash|runcommand|run_command|execcommand|exec_command|terminal) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 is_plan_mode_safe_tool() {
   case "$1" in
     read|readfile|open|view|cat|head|tail) return 0 ;;
@@ -817,6 +915,65 @@ if [ "$CURRENT_STAGE" = "tdd" ] && is_mutating_tool "$TOOL_LOWER"; then
   fi
 fi
 
+if [ "$CURRENT_STAGE" = "tdd" ] && is_mutating_tool "$TOOL_LOWER"; then
+  if [ "$ACTIVE_AGENT_LOWER" = "tdd-red" ] && is_tdd_production_write_payload "$PAYLOAD_LOWER" "$MUTATION_PATHS"; then
+    if [ -n "$REASONS" ]; then
+      REASONS="$REASONS,tdd_red_agent_cannot_write_production"
+    else
+      REASONS="tdd_red_agent_cannot_write_production"
+    fi
+  fi
+  if [ "$ACTIVE_AGENT_LOWER" = "tdd-green" ] && is_tdd_test_payload "$PAYLOAD_LOWER" "$MUTATION_PATHS"; then
+    if [ -n "$REASONS" ]; then
+      REASONS="$REASONS,tdd_green_agent_cannot_write_tests"
+    else
+      REASONS="tdd_green_agent_cannot_write_tests"
+    fi
+  fi
+  if [ "$ACTIVE_AGENT_LOWER" = "tdd-refactor" ]; then
+    TDD_AGENT_STATE=$(tdd_cycle_state)
+    if [ "$TDD_AGENT_STATE" != "green_done" ]; then
+      if [ -n "$REASONS" ]; then
+        REASONS="$REASONS,tdd_refactor_before_green"
+      else
+        REASONS="tdd_refactor_before_green"
+      fi
+    fi
+  fi
+fi
+
+if is_mutating_tool "$TOOL_LOWER"; then
+  if [ "$LAST_FLOW_READ_AT" -le 0 ] || [ "$NOW_EPOCH" -le 0 ] || [ $((NOW_EPOCH - LAST_FLOW_READ_AT)) -gt "$MAX_FLOW_READ_AGE_SEC" ]; then
+    if [ -n "$REASONS" ]; then
+      REASONS="$REASONS,mutating_without_recent_flow_read"
+    else
+      REASONS="mutating_without_recent_flow_read"
+    fi
+  fi
+fi
+
+if is_mutating_tool "$TOOL_LOWER" && printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/(state|hooks|skills)'; then
+  if ! is_cclaw_cli_payload "$PAYLOAD_LOWER"; then
+    if [ -n "$REASONS" ]; then
+      REASONS="$REASONS,runtime_write_requires_managed_only"
+    else
+      REASONS="runtime_write_requires_managed_only"
+    fi
+  fi
+fi
+
+if [ "$CURRENT_STAGE" = "ship" ] && is_execution_or_mutating_tool "$TOOL_LOWER"; then
+  if printf '%s' "$PAYLOAD_LOWER" | grep -Eq '(npm publish|pnpm publish|yarn publish|gh release create|git push[[:space:]].*--tags|npm version)'; then
+    if [ "$SHIP_PREFLIGHT_PASSED" != "true" ]; then
+      if [ -n "$REASONS" ]; then
+        REASONS="$REASONS,ship_preflight_required"
+      else
+        REASONS="ship_preflight_required"
+      fi
+    fi
+  fi
+fi
+
 if is_preimplementation_stage "$CURRENT_STAGE" && ! is_plan_mode_safe_tool "$TOOL_LOWER"; then
   if ! is_mutating_tool "$TOOL_LOWER"; then
     if ! printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/' && ! is_cclaw_cli_payload "$PAYLOAD_LOWER"; then
@@ -882,12 +1039,22 @@ PY
 fi
 
 if [ -n "$REASONS" ]; then
-  if printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red'; then
+  if printf '%s' "$REASONS" | grep -Eq 'tdd_red_agent_cannot_write_production'; then
+    NOTE="Cclaw workflow guard: tdd-red agent is limited to test-side RED work and cannot edit production files."
+  elif printf '%s' "$REASONS" | grep -Eq 'tdd_green_agent_cannot_write_tests'; then
+    NOTE="Cclaw workflow guard: tdd-green agent can implement production fixes but should not author new RED tests."
+  elif printf '%s' "$REASONS" | grep -Eq 'tdd_refactor_before_green'; then
+    NOTE="Cclaw workflow guard: tdd-refactor requires a green_done cycle state before refactor edits."
+  elif printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red'; then
     NOTE="Cclaw workflow guard: Write a failing test first before editing production files during tdd stage (state=\${TDD_CYCLE_STATE})."
+  elif printf '%s' "$REASONS" | grep -Eq 'ship_preflight_required'; then
+    NOTE="Cclaw workflow guard: ship finalization command detected before ship_preflight_passed gate. Run preflight and record evidence first."
   elif printf '%s' "$REASONS" | grep -Eq 'tdd_cycle_counts_unavailable'; then
     NOTE="Cclaw workflow guard: unable to inspect run-scoped tdd-cycle counts (missing usable jq/python3/awk). Install one of these tools before writing production code in tdd."
-  elif 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."
+  elif printf '%s' "$REASONS" | grep -Eq 'runtime_write_requires_managed_only|direct_flow_state_edit'; then
+    NOTE="Cclaw workflow guard: runtime write to managed ${RUNTIME_ROOT} internals detected (\${REASONS}). Prefer cclaw-managed helpers (stage-complete, sync, command contracts) instead of ad-hoc edits."
+  elif printf '%s' "$REASONS" | grep -Eq 'mutating_without_recent_flow_read'; then
+    NOTE="Cclaw workflow guard: mutating action requires a fresh read of ${RUNTIME_ROOT}/state/flow-state.json before edits."
   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
@@ -913,9 +1080,27 @@ if [ -n "$REASONS" ]; then
   if printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red' && [ "$TDD_ENFORCEMENT_MODE" = "strict" ]; then
     SHOULD_BLOCK="true"
   fi
+  if printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red' && iron_law_is_strict "tdd-red-before-write"; then
+    SHOULD_BLOCK="true"
+  fi
+  if printf '%s' "$REASONS" | grep -Eq 'runtime_write_requires_managed_only|direct_flow_state_edit' && iron_law_is_strict "runtime-writes-managed-only"; then
+    SHOULD_BLOCK="true"
+  fi
+  if printf '%s' "$REASONS" | grep -Eq 'mutating_without_recent_flow_read|stage_invocation_without_recent_flow_read' && iron_law_is_strict "flow-state-read-fresh"; then
+    SHOULD_BLOCK="true"
+  fi
+  if printf '%s' "$REASONS" | grep -Eq 'ship_preflight_required' && iron_law_is_strict "ship-preflight-required"; then
+    SHOULD_BLOCK="true"
+  fi
+  if printf '%s' "$REASONS" | grep -Eq 'implementation_write_before_plan_completion' && iron_law_is_strict "plan-requires-approval"; then
+    SHOULD_BLOCK="true"
+  fi
   if printf '%s' "$REASONS" | grep -Eq 'tdd_cycle_counts_unavailable'; then
     SHOULD_BLOCK="true"
   fi
+  if printf '%s' "$REASONS" | grep -Eq 'tdd_red_agent_cannot_write_production|tdd_green_agent_cannot_write_tests|tdd_refactor_before_green'; then
+    SHOULD_BLOCK="true"
+  fi
   if [ "$WORKFLOW_GUARD_MODE" = "strict" ] || [ "$SHOULD_BLOCK" = "true" ]; then
     printf '[cclaw] %s (blocked by workflow guard)\n' "$NOTE" >&2
     exit 1
@@ -1289,7 +1474,7 @@ export function codexHooksJsonWithObservation() {
                             command: hookDispatcherCommand("workflow-guard.sh")
                         }, {
                             type: "command",
-                            command: "bash -lc 'if ! command -v cclaw >/dev/null 2>&1; then echo \"[cclaw] codex hook: cclaw binary is required for verify-current-state\" >&2; exit 1; fi; cclaw internal verify-current-state --quiet >/dev/null || true'"
+                            command: "bash -lc 'if ! command -v cclaw >/dev/null 2>&1; then echo \"[cclaw] codex hook: cclaw binary is required for verify-current-state\" >&2; exit 1; fi; MODE=\"${CCLAW_WORKFLOW_GUARD_MODE:-advisory}\"; if [ \"$MODE\" = \"strict\" ]; then cclaw internal verify-current-state --quiet >/dev/null; else cclaw internal verify-current-state --quiet >/dev/null || true; fi'"
                         }]
                 }],
             PreToolUse: [{

package/dist/content/ops-command.js

@@ -33,6 +33,17 @@ Subcommands:
    - \`rewind\` -> \`${RUNTIME_ROOT}/commands/rewind.md\`
 3. Unknown subcommand -> print supported values and stop.
 
+## Headless mode
+
+For skill-to-skill dispatch, emit exactly one JSON envelope:
+
+\`\`\`json
+{"version":"1","kind":"stage-output","stage":"ship","payload":{"command":"/cc-ops","subcommand":"archive","status":"completed"},"emittedAt":"<ISO-8601>"}
+\`\`\`
+
+Validate envelopes with:
+\`cclaw internal envelope-validate --stdin\`
+
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${OPS_SKILL_FOLDER}/SKILL.md**

package/dist/content/session-hooks.js

@@ -29,7 +29,8 @@ When a new session begins in any harness:
 2. **Load knowledge:** Stream the tail of \`.cclaw/knowledge.jsonl\` (strict JSONL store) and surface the most relevant rules/patterns.
 3. **Check for in-progress work:** If the last stage is incomplete, remind the user and offer to resume.
 4. **Load suggestion memory:** Read \`.cclaw/state/suggestion-memory.json\` and honor \`enabled=false\` opt-out.
-5. **Read AGENTS.md:** The cclaw block contains routing and rules — follow them.
+5. **Load iron laws:** Read \`.cclaw/state/iron-laws.json\` to know which laws are strict in this repo.
+6. **Read AGENTS.md:** The cclaw block contains routing and rules — follow them.
 
 ### What to show the user at session start
 
@@ -133,5 +134,6 @@ Session boundary behavior (real hooks inject context automatically; guidelines c
 - **Resume:** Re-read state, verify artifact, re-load knowledge, continue from last step.
 
 Skill: \`.cclaw/skills/session/SKILL.md\`
+Policy: \`.cclaw/skills/iron-laws/SKILL.md\`
 `;
 }

package/dist/content/stage-schema.d.ts

@@ -1,6 +1,22 @@
 import type { FlowStage, FlowTrack, TransitionRule } from "../types.js";
 import type { StageAutoSubagentDispatch, StageSchema } from "./stages/schema-types.js";
 export type { ArtifactValidation, CrossStageTrace, ReviewSection, StageAutoSubagentDispatch, StageGate, StageSchema, StageSchemaInput } from "./stages/schema-types.js";
+export declare const SKILL_ENVELOPE_KINDS: readonly ["stage-output", "gate-result", "delegation-record"];
+export type SkillEnvelopeKind = (typeof SKILL_ENVELOPE_KINDS)[number];
+export interface SkillEnvelope {
+    version: "1";
+    kind: SkillEnvelopeKind;
+    stage: FlowStage;
+    payload: unknown;
+    emittedAt: string;
+    agent?: string;
+}
+export interface SkillEnvelopeValidation {
+    ok: boolean;
+    errors: string[];
+}
+export declare function validateSkillEnvelope(value: unknown): SkillEnvelopeValidation;
+export declare function parseSkillEnvelope(raw: string): SkillEnvelope | null;
 /** Transition guard: agents with `mode: "mandatory"` in auto-subagent dispatch for this stage. */
 export declare function mandatoryDelegationsForStage(stage: FlowStage): string[];
 export declare function stageSchema(stage: FlowStage, track?: FlowTrack): StageSchema;

package/dist/content/stage-schema.js

@@ -2,6 +2,65 @@ import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "../types.js";
 import { STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { BRAINSTORM, SCOPE, DESIGN, SPEC, PLAN, TDD, REVIEW, SHIP } from "./stages/index.js";
 import { tddStageForTrack } from "./stages/tdd.js";
+// ---------------------------------------------------------------------------
+// NOTE: The former QUESTION_FORMAT_SPEC / ERROR_BUDGET_SPEC exports were
+// hoisted into `src/content/meta-skill.ts` (Shared Decision + Tool-Use
+// Protocol). They are no longer re-exported from here to avoid duplication
+// and drift. Stage skills cite the meta-skill by path instead.
+// ---------------------------------------------------------------------------
+export const SKILL_ENVELOPE_KINDS = [
+    "stage-output",
+    "gate-result",
+    "delegation-record"
+];
+const FLOW_STAGE_SET = new Set(FLOW_STAGES);
+const SKILL_ENVELOPE_KIND_SET = new Set(SKILL_ENVELOPE_KINDS);
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+export function validateSkillEnvelope(value) {
+    const errors = [];
+    const record = asRecord(value);
+    if (!record) {
+        return { ok: false, errors: ["envelope must be a JSON object"] };
+    }
+    if (record.version !== "1") {
+        errors.push('envelope.version must equal "1".');
+    }
+    if (typeof record.kind !== "string" || !SKILL_ENVELOPE_KIND_SET.has(record.kind)) {
+        errors.push(`envelope.kind must be one of: ${SKILL_ENVELOPE_KINDS.join(", ")}.`);
+    }
+    if (typeof record.stage !== "string" || !FLOW_STAGE_SET.has(record.stage)) {
+        errors.push(`envelope.stage must be one of: ${FLOW_STAGES.join(", ")}.`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(record, "payload")) {
+        errors.push("envelope.payload is required.");
+    }
+    if (typeof record.emittedAt !== "string" || Number.isNaN(Date.parse(record.emittedAt))) {
+        errors.push("envelope.emittedAt must be an ISO-8601 timestamp string.");
+    }
+    if (record.agent !== undefined && typeof record.agent !== "string") {
+        errors.push("envelope.agent must be a string when present.");
+    }
+    return { ok: errors.length === 0, errors };
+}
+export function parseSkillEnvelope(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const validation = validateSkillEnvelope(parsed);
+    if (!validation.ok) {
+        return null;
+    }
+    return parsed;
+}
 const ARTIFACT_STAGE_BY_PATH = {
     ".cclaw/artifacts/01-brainstorm.md": "brainstorm",
     ".cclaw/artifacts/02-scope.md": "scope",
@@ -191,9 +250,26 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         {
             agent: "test-author",
             mode: "mandatory",
-            when: "Always during TDD cycle (RED → GREEN → REFACTOR).",
-            purpose: "Guarantee failing tests, traceable implementation, and full-suite verification.",
-            requiresUserGate: false
+            when: "Always during TDD cycle (RED phase).",
+            purpose: "Produce failing RED tests only; no production writes.",
+            requiresUserGate: false,
+            skill: "tdd-red-phase"
+        },
+        {
+            agent: "test-author",
+            mode: "mandatory",
+            when: "Always during TDD cycle (GREEN phase).",
+            purpose: "Implement minimum production changes to satisfy RED and prove full-suite GREEN.",
+            requiresUserGate: false,
+            skill: "tdd-green-phase"
+        },
+        {
+            agent: "test-author",
+            mode: "mandatory",
+            when: "Always during TDD cycle (REFACTOR phase).",
+            purpose: "Refactor only after GREEN proof, preserving behavior and test pass state.",
+            requiresUserGate: false,
+            skill: "tdd-refactor-phase"
         },
         {
             agent: "doc-updater",
@@ -208,8 +284,9 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "reviewer",
             mode: "mandatory",
             when: "Always in review stage.",
-            purpose: "Run spec compliance and code-quality passes with file evidence.",
-            requiresUserGate: false
+            purpose: "Layer 1 spec compliance pass plus coordination of parallel Layer 2 fan-out (correctness, performance, architecture, external-safety) with source-tagged findings.",
+            requiresUserGate: false,
+            skill: "review-spec-pass"
         },
         {
             agent: "security-reviewer",

package/dist/content/stages/review.js

@@ -54,7 +54,7 @@ export const REVIEW = {
         "Layer 2b: check security — validation, auth, secrets, injection.",
         "Layer 2c: check performance — queries, memory, caching, hot paths.",
         "Layer 2d: check architecture fit — design compliance, coupling, interfaces.",
-        "Reconcile multi-agent findings into `.cclaw/artifacts/07-review-army.json` (dedup + confidence + conflict notes).",
+        "Reconcile multi-agent findings into `.cclaw/artifacts/07-review-army.json` (dedup + confidence + conflict notes + source tags from spec/correctness/security/performance/architecture/external-safety passes).",
         "Classify and prioritize all findings.",
         "Write review report artifact with explicit verdict.",
         "If verdict is BLOCKED, include the remediation route token `ROUTE_BACK_TO_TDD` and the rewind command payload."
@@ -202,7 +202,7 @@ export const REVIEW = {
     artifactValidation: [
         { section: "Layer 1 Verdict", required: true, validationRule: "Per-criterion pass/fail with references." },
         { section: "Layer 2 Findings", required: false, validationRule: "Each finding has severity, description, and resolution status. Security coverage must include either explicit security findings or `NO_CHANGE_ATTESTATION: <reason>` when no security-relevant changes were found." },
-        { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status with dedup reconciliation summary." },
+        { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status and source tags from {spec, correctness, security, performance, architecture, external-safety} with dedup reconciliation summary." },
         { section: "Review Readiness Dashboard", required: false, validationRule: "Includes a per-pass table (Layer 1 / Layer 2 / Adversarial / Schema) with a 'Completed at' column, a Delegation log snapshot block (path .cclaw/state/delegation-log.json with required/completed/waived/pending), a Staleness signal block (commit at last review pass and current commit), and a Headline with open critical blockers + ship recommendation. At minimum, the section text must contain the substrings 'Completed at', 'delegation-log.json', 'commit at last review pass', and 'Ship recommendation'." },
         { section: "Completeness Score", required: false, validationRule: "Records AC coverage, task coverage, test-slice coverage, and adversarial-review pass status as numeric or boolean values. At minimum, a line like 'AC coverage: N/M' or 'AC coverage: 100%'." },
         { section: "Incoming Feedback Queue", required: false, validationRule: "When external review feedback exists, include a queue summary with per-item disposition (resolved / accepted-risk / rejected-with-evidence) and evidence refs." },