cclaw-cli 0.48.5 → 0.48.7

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

@@ -16,8 +16,7 @@ export const REVIEW = {
     ],
     whenNotToUse: [
         "There is no implementation diff to review",
-        "TDD stage evidence is missing or stale",
-        "The goal is direct release execution without layered quality checks"
+        "TDD stage evidence is missing or stale"
     ],
     checklist: [
         "Diff Scope — Run `git diff` against base branch. If no diff, exit early with APPROVED (no changes to review). Scope the review to changed files unless blast-radius analysis requires wider inspection.",
@@ -54,7 +53,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."
@@ -62,6 +61,7 @@ export const REVIEW = {
     requiredGates: [
         { id: "review_layer1_spec_compliance", description: "Spec compliance check completed with per-criterion verdict." },
         { id: "review_layer2_security", description: "Security review completed." },
+        { id: "review_layer_coverage_complete", description: "Layer coverage map in 07-review-army.json confirms spec/correctness/security/performance/architecture/external-safety passes." },
         { id: "review_criticals_resolved", description: "No unresolved critical blockers remain." },
         { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." },
         { id: "review_trace_matrix_clean", description: "Trace matrix has no orphaned criteria/tasks/test slices for the active run." }
@@ -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." },

package/dist/content/stages/tdd.js

@@ -22,13 +22,13 @@ export const TDD = {
     checklist: [
         "Select plan slice — pick one task from the plan. Do not batch multiple tasks.",
         "Map to acceptance criterion — identify the specific spec criterion this test proves.",
-        "Dispatch mandatory `test-author` subagent in `TEST_RED_ONLY` mode — produce failing behavior tests and RED evidence only (no production edits).",
+        "Dispatch mandatory `tdd-red` execution (or `test-author` in TEST_RED_ONLY mode) — produce failing behavior tests and RED evidence only (no production edits). Set `CCLAW_ACTIVE_AGENT=tdd-red` when supported.",
         "RED: Capture failure output — copy the exact failure output as RED evidence. Record in artifact.",
-        "Dispatch `test-author` subagent in `BUILD_GREEN_REFACTOR` mode — minimal implementation + full-suite GREEN + refactor notes.",
+        "Dispatch `tdd-green` execution (or `test-author` in BUILD_GREEN_REFACTOR mode) — minimal implementation + full-suite GREEN. Set `CCLAW_ACTIVE_AGENT=tdd-green` when supported.",
         "GREEN: Run full suite — execute ALL tests, not just the ones you wrote. The full suite must be GREEN.",
         "GREEN: Verify no regressions — if any existing test breaks, fix the regression before proceeding.",
         "Run verification-before-completion discipline for the slice — capture a fresh test command, commit SHA, and explicit PASS/FAIL status before completion claims.",
-        "REFACTOR: Improve code quality — without changing behavior. Document what you changed and why.",
+        "REFACTOR: Dispatch `tdd-refactor` execution (or dedicated refactor mode) to improve code quality without behavior changes. Set `CCLAW_ACTIVE_AGENT=tdd-refactor` when supported.",
         "Record evidence — capture RED failure, GREEN output, and REFACTOR notes in the TDD artifact.",
         "Annotate traceability — link to plan task ID and spec criterion.",
         "Per-Slice Review (conditional) — if `.cclaw/config.yaml::sliceReview.enabled` is true and the slice meets any trigger (touchCount >= filesChangedThreshold, touchPaths match touchTriggers, or highRisk=true), append a `## Per-Slice Review` entry for this slice before moving on (see the dedicated section below).",
@@ -36,7 +36,7 @@ export const TDD = {
     ],
     interactionProtocol: [
         "Pick one planned slice at a time.",
-        "Controller owns orchestration; execution runs through the mandatory `test-author` delegation for RED then GREEN/REFACTOR modes.",
+        "Controller owns orchestration; execution runs through phase-specific delegation (`tdd-red` -> `tdd-green` -> `tdd-refactor`) or equivalent `test-author` modes.",
         "Write behavior-focused tests before changing implementation (RED).",
         "Capture and store failing output as RED evidence.",
         "Apply minimal change to satisfy RED tests (GREEN).",
@@ -49,12 +49,12 @@ export const TDD = {
     ],
     process: [
         "Select slice and map to acceptance criterion.",
-        "Dispatch `test-author` in TEST_RED_ONLY mode and produce failing test(s) for expected reason (RED).",
+        "Dispatch `tdd-red` (or `test-author` TEST_RED_ONLY mode) and produce failing test(s) for expected reason (RED).",
         "Run tests and capture failure output.",
-        "Dispatch `test-author` in BUILD_GREEN_REFACTOR mode and implement smallest change needed for GREEN.",
+        "Dispatch `tdd-green` (or `test-author` BUILD_GREEN_REFACTOR mode) and implement smallest change needed for GREEN.",
         "Run full tests and build checks.",
         "Run a fresh verification-before-completion check and capture command + commit SHA + PASS/FAIL in guard evidence.",
-        "Perform refactor pass preserving behavior.",
+        "Dispatch `tdd-refactor` pass preserving behavior.",
         "Record RED, GREEN, and REFACTOR evidence in artifact.",
         "Annotate traceability to plan task and spec criterion; on `sliceReview` triggers, append a Per-Slice Review entry before closing the slice."
     ],

package/dist/content/start-command.js

@@ -100,6 +100,18 @@ If during any stage the agent discovers evidence that contradicts the initial Ph
 2. If flow state is missing → run \`cclaw init\` guidance and stop.
 3. Behave exactly like \`/cc-next\`: check current stage gates, resume if incomplete, advance if complete.
 
+## Headless mode
+
+When called by another skill or subagent in machine mode, emit exactly one
+JSON envelope (no prose) and stop:
+
+\`\`\`json
+{"version":"1","kind":"stage-output","stage":"brainstorm","payload":{"command":"/cc","track":"standard","action":"start_or_resume"},"emittedAt":"<ISO-8601>"}
+\`\`\`
+
+Validate envelopes with:
+\`cclaw internal envelope-validate --stdin\`
+
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${START_SKILL_FOLDER}/SKILL.md**

package/dist/content/subagents.js

@@ -39,6 +39,32 @@ For cclaw flow stages, machine-only specialist work should auto-dispatch without
 
 Human input remains mandatory only at explicit approval gates (plan approval, user challenge resolution, release finalization mode).
 
+### Review parallel fan-out protocol
+
+In review stage, prefer a fixed six-pass fan-out before reconciliation:
+
+1. \`review-spec\` (Layer 1)
+2. \`review-correctness\` (Layer 2a)
+3. \`review-security\` (Layer 2b)
+4. \`review-performance\` (Layer 2c)
+5. \`review-architecture\` (Layer 2d)
+6. \`review-external-safety\` (Layer 2e)
+
+Dispatch these in parallel where the harness supports isolated workers, then run
+one reconciliation pass that merges findings into \`.cclaw/artifacts/07-review-army.json\`
+with explicit source tags per finding.
+
+### TDD phase fan-out protocol
+
+Treat RED, GREEN, and REFACTOR as separate delegated intents:
+
+- \`tdd-red\`: tests only, no production writes
+- \`tdd-green\`: minimal production implementation, no new RED tests
+- \`tdd-refactor\`: cleanup only after GREEN is proven
+
+Set \`CCLAW_ACTIVE_AGENT\` to the active phase name when possible so workflow-guard
+can enforce phase-appropriate write boundaries.
+
 ## Model & Harness Routing Notes
 
 ### Harness routing

package/dist/content/templates.js

@@ -609,6 +609,14 @@ inputs_hash: sha256:pending
     "duplicatesCollapsed": 0,
     "conflicts": [],
     "multiSpecialistConfirmed": [],
+    "layerCoverage": {
+      "spec": false,
+      "correctness": false,
+      "security": false,
+      "performance": false,
+      "architecture": false,
+      "external-safety": false
+    },
     "shipBlockers": []
   }
 }

package/dist/content/view-command.js

@@ -27,6 +27,17 @@ Subcommands:
    - \`diff\` -> load \`${RUNTIME_ROOT}/commands/diff.md\` + \`${RUNTIME_ROOT}/skills/flow-diff/SKILL.md\`
 3. Unknown subcommand -> print supported values and stop.
 
+## Headless mode
+
+For machine orchestration, emit one JSON envelope:
+
+\`\`\`json
+{"version":"1","kind":"stage-output","stage":"review","payload":{"command":"/cc-view","subcommand":"status","summary":"<short>"},"emittedAt":"<ISO-8601>"}
+\`\`\`
+
+Validate envelopes with:
+\`cclaw internal envelope-validate --stdin\`
+
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${VIEW_SKILL_FOLDER}/SKILL.md**

package/dist/doctor.js

@@ -673,6 +673,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     }
     // Hook scripts
     for (const script of [
+        "_lib.sh",
         "session-start.sh",
         "stop-checkpoint.sh",
         "run-hook.cmd",
@@ -877,6 +878,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         const codexStopCmds = collectHookCommands(codexHooks.Stop);
         const codexWiringOk = codexSessionCmds.some((cmd) => cmd.includes("session-start.sh")) &&
             codexUserPromptCmds.some((cmd) => cmd.includes("prompt-guard.sh")) &&
+            codexUserPromptCmds.some((cmd) => cmd.includes("workflow-guard.sh")) &&
             codexUserPromptCmds.some((cmd) => cmd.includes("verify-current-state --quiet")) &&
             codexPreCmds.some((cmd) => cmd.includes("prompt-guard.sh")) &&
             codexPreCmds.some((cmd) => cmd.includes("workflow-guard.sh")) &&
@@ -885,7 +887,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         checks.push({
             name: "hook:wiring:codex",
             ok: codexWiringOk,
-            details: `${codexHooksFile} must wire SessionStart, UserPromptSubmit(prompt-guard + verify-current-state), PreToolUse(prompt/workflow), PostToolUse(context-monitor), and Stop(stop-checkpoint). PreToolUse/PostToolUse run Bash-only in Codex v0.114+`
+            details: `${codexHooksFile} must wire SessionStart, UserPromptSubmit(prompt/workflow/verify-current-state), PreToolUse(prompt/workflow), PostToolUse(context-monitor), and Stop(stop-checkpoint). PreToolUse/PostToolUse run Bash-only in Codex v0.114+`
         });
         // Feature flag warning: Codex ignores `.codex/hooks.json` unless the
         // user has `[features] codex_hooks = true` in `~/.codex/config.toml`.
@@ -965,10 +967,12 @@ export async function doctorChecks(projectRoot, options = {}) {
                     content.includes("workflow-guard.sh") &&
                     content.includes("context-monitor.sh") &&
                     content.includes("pre-compact.sh") &&
+                    content.includes('"session.created"') &&
                     content.includes('"session.idle"') &&
                     content.includes('"session.resumed"') &&
                     content.includes('"session.compacted"') &&
                     content.includes('"session.cleared"') &&
+                    content.includes('"session.updated"') &&
                     content.includes('"experimental.chat.system.transform"');
             singleHandlerPathOk =
                 !content.includes('eventType === "tool.execute.before"') &&
@@ -982,7 +986,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         checks.push({
             name: "lifecycle:opencode:rehydration_events",
             ok,
-            details: `${file} must include event lifecycle handler, tool.execute.before/after with prompt/workflow/context hooks, session.idle checkpoint, and transform rehydration`
+            details: `${file} must include event lifecycle handler, session.created/updated/resumed/cleared/compacted rehydration, tool.execute.before/after with prompt/workflow/context hooks, session.idle checkpoint, and transform rehydration`
         });
         checks.push({
             name: "hook:opencode:single_tool_handler_path",

package/dist/harness-adapters.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
 import { CCLAW_AGENTS, agentMarkdown } from "./content/core-agents.js";
+import { ironLawsAgentsMdBlock } from "./content/iron-laws.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 export const CCLAW_MARKER_START = "<!-- cclaw-start -->";
 export const CCLAW_MARKER_END = "<!-- cclaw-end -->";
@@ -200,6 +201,8 @@ Before responding to a coding request:
 2. Use \`/cc\` to start or \`/cc-next\` to continue the flow.
 3. If no stage applies, respond normally.
 
+${ironLawsAgentsMdBlock()}
+
 ### Task Classification (before \`/cc\`)
 
 | Class | Examples | Route |

package/dist/install.js

@@ -23,7 +23,8 @@ 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, runHookDispatcherScript, stageCompleteScript, preCompactScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
+import { hookLibScript, sessionStartScript, stopCheckpointScript, runHookDispatcherScript, 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";
@@ -255,6 +256,7 @@ async function writeSkills(projectRoot, config) {
     await writeFileSafe(runtimePath(projectRoot, "skills", "subagent-dev", "SKILL.md"), subagentDrivenDevSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "parallel-dispatch", "SKILL.md"), parallelAgentsSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "session", "SKILL.md"), sessionHooksSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "iron-laws", "SKILL.md"), ironLawsSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", META_SKILL_NAME, "SKILL.md"), usingCclawSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "references", "protocols", "decision.md"), decisionProtocolMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "references", "protocols", "completion.md"), completionProtocolMarkdown());
@@ -621,7 +623,14 @@ async function writeMergedHookJson(projectRoot, hookFilePath, generatedJson) {
 async function writeHooks(projectRoot, config) {
     const harnesses = config.harnesses;
     const hooksDir = runtimePath(projectRoot, "hooks");
+    const stateDir = runtimePath(projectRoot, "state");
     await ensureDir(hooksDir);
+    await ensureDir(stateDir);
+    await writeFileSafe(runtimePath(projectRoot, "state", "iron-laws.json"), `${JSON.stringify(ironLawRuntimeDocument({
+        mode: config.ironLaws?.mode,
+        strictLaws: config.ironLaws?.strictLaws
+    }), null, 2)}\n`);
+    await writeFileSafe(path.join(hooksDir, "_lib.sh"), hookLibScript());
     await writeFileSafe(path.join(hooksDir, "session-start.sh"), sessionStartScript());
     await writeFileSafe(path.join(hooksDir, "stop-checkpoint.sh"), stopCheckpointScript());
     await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookDispatcherScript());
@@ -641,6 +650,7 @@ async function writeHooks(projectRoot, config) {
     await writeFileSafe(path.join(hooksDir, "opencode-plugin.mjs"), opencodePluginSource);
     try {
         for (const script of [
+            "_lib.sh",
             "session-start.sh",
             "stop-checkpoint.sh",
             "run-hook.cmd",

package/dist/internal/advance-stage.js

@@ -10,6 +10,9 @@ import { getAvailableTransitions, getTransitionGuards, isFlowTrack } from "../fl
 import { appendKnowledge } from "../knowledge-store.js";
 import { readFlowState, writeFlowState } from "../runs.js";
 import { FLOW_STAGES } from "../types.js";
+import { runEnvelopeValidateCommand } from "./envelope-validate.js";
+import { runKnowledgeDigestCommand } from "./knowledge-digest.js";
+import { runTddRedEvidenceCommand } from "./tdd-red-evidence.js";
 function unique(values) {
     return [...new Set(values)];
 }
@@ -621,7 +624,7 @@ async function runVerifyCurrentState(projectRoot, args, io) {
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence\n");
         return 1;
     }
     try {
@@ -634,7 +637,16 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "verify-current-state") {
             return await runVerifyCurrentState(projectRoot, parseVerifyCurrentStateArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state\n`);
+        if (subcommand === "knowledge-digest") {
+            return await runKnowledgeDigestCommand(projectRoot, tokens, io);
+        }
+        if (subcommand === "envelope-validate") {
+            return await runEnvelopeValidateCommand(projectRoot, tokens, io);
+        }
+        if (subcommand === "tdd-red-evidence") {
+            return await runTddRedEvidenceCommand(projectRoot, tokens, io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence\n`);
         return 1;
     }
     catch (err) {

package/dist/internal/envelope-validate.d.ts

@@ -0,0 +1,7 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function runEnvelopeValidateCommand(_projectRoot: string, tokens: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/envelope-validate.js

@@ -0,0 +1,66 @@
+import fs from "node:fs/promises";
+import { parseSkillEnvelope, validateSkillEnvelope } from "../content/stage-schema.js";
+function parseArgs(tokens) {
+    const args = { stdin: false, quiet: false };
+    for (const token of tokens) {
+        if (token === "--stdin") {
+            args.stdin = true;
+            continue;
+        }
+        if (token === "--quiet") {
+            args.quiet = true;
+            continue;
+        }
+        if (token.startsWith("--json=")) {
+            args.json = token.replace("--json=", "");
+            continue;
+        }
+        if (token.startsWith("--file=")) {
+            args.file = token.replace("--file=", "");
+            continue;
+        }
+        throw new Error(`Unknown flag for envelope-validate: ${token}`);
+    }
+    return args;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runEnvelopeValidateCommand(_projectRoot, tokens, io) {
+    const args = parseArgs(tokens);
+    let raw = "";
+    if (args.json !== undefined) {
+        raw = args.json;
+    }
+    else if (args.file !== undefined) {
+        raw = await fs.readFile(args.file, "utf8");
+    }
+    else if (args.stdin) {
+        raw = await readStdin();
+    }
+    else {
+        throw new Error("Provide one source: --json=<payload> | --file=<path> | --stdin");
+    }
+    const parsed = parseSkillEnvelope(raw);
+    if (parsed) {
+        if (!args.quiet) {
+            io.stdout.write(`${JSON.stringify(parsed, null, 2)}\n`);
+        }
+        return 0;
+    }
+    let candidate;
+    try {
+        candidate = JSON.parse(raw);
+    }
+    catch (error) {
+        io.stderr.write(`Invalid JSON: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    const validation = validateSkillEnvelope(candidate);
+    io.stderr.write(`Invalid envelope: ${validation.errors.join(" ")}\n`);
+    return 1;
+}

package/dist/internal/knowledge-digest.d.ts

@@ -0,0 +1,7 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare function runKnowledgeDigestCommand(projectRoot: string, tokens: string[], io: InternalIo): Promise<number>;
+export {};