cclaw-cli 0.48.5 → 0.48.7

package/dist/content/ideate-command.js

@@ -58,6 +58,17 @@ same session, or save/discard the backlog.
 6. **Present the handoff prompt** with four concrete options — not A/B/C
    letters. Default = "Start /cc on the top recommendation".
 
+## Headless mode
+
+For skill-to-skill invocation, emit exactly one JSON envelope:
+
+\`\`\`json
+{"version":"1","kind":"stage-output","stage":"brainstorm","payload":{"command":"/cc-ideate","artifact":".cclaw/artifacts/ideate-<date>-<slug>.md","recommendation":"I-1"},"emittedAt":"<ISO-8601>"}
+\`\`\`
+
+Validate envelopes with:
+\`cclaw internal envelope-validate --stdin\`
+
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${IDEATE_SKILL_FOLDER}/SKILL.md**

package/dist/content/iron-laws.d.ts

@@ -0,0 +1,142 @@
+import type { FlowStage } from "../types.js";
+export type IronLawEnforcementPoint = "PreToolUse" | "PostToolUse" | "SessionStart" | "Stop" | "advisory";
+export type IronLawSeverity = "hard-gate" | "soft-gate";
+export interface IronLawDefinition {
+    id: string;
+    title: string;
+    rule: string;
+    rationale: string;
+    enforcement: IronLawEnforcementPoint;
+    severity: IronLawSeverity;
+    appliesTo: "all" | FlowStage[];
+    hookMatcher?: {
+        toolPattern?: string;
+        payloadPattern?: string;
+    };
+}
+export interface IronLawRuntimeRecord {
+    id: string;
+    title: string;
+    rule: string;
+    enforcement: IronLawEnforcementPoint;
+    severity: IronLawSeverity;
+    appliesTo: "all" | FlowStage[];
+    strict: boolean;
+    hookMatcher?: {
+        toolPattern?: string;
+        payloadPattern?: string;
+    };
+}
+export interface IronLawRuntimeDocument {
+    version: 1;
+    generatedAt: string;
+    mode: "advisory" | "strict";
+    strictLaws: string[];
+    laws: IronLawRuntimeRecord[];
+}
+export declare const IRON_LAWS: readonly [{
+    readonly id: "tdd-red-before-write";
+    readonly title: "RED before production write";
+    readonly rule: "Do not edit production code in tdd stage before a failing RED test exists for the slice.";
+    readonly rationale: "Prevents implementation-first behavior and keeps RED as executable specification.";
+    readonly enforcement: "PreToolUse";
+    readonly severity: "hard-gate";
+    readonly appliesTo: ["tdd"];
+    readonly hookMatcher: {
+        readonly toolPattern: "write|edit|multiedit|applypatch|shell|bash";
+        readonly payloadPattern: "\\.(ts|tsx|js|jsx|py|go|java|rs|rb|php|c|cc|cpp|h|hpp)";
+    };
+}, {
+    readonly id: "plan-requires-approval";
+    readonly title: "No implementation before plan approval";
+    readonly rule: "Do not perform write-like actions while plan stage is pending WAIT_FOR_CONFIRM approval.";
+    readonly rationale: "Locks intent before execution and reduces expensive rework from unapproved paths.";
+    readonly enforcement: "PreToolUse";
+    readonly severity: "hard-gate";
+    readonly appliesTo: ["plan"];
+}, {
+    readonly id: "runtime-writes-managed-only";
+    readonly title: "Runtime writes are managed";
+    readonly rule: "Do not mutate .cclaw/state, .cclaw/hooks, or .cclaw/skills by ad-hoc edits unless using cclaw-managed commands.";
+    readonly rationale: "Protects generated runtime integrity and avoids drift that silently breaks hooks or skills.";
+    readonly enforcement: "PreToolUse";
+    readonly severity: "hard-gate";
+    readonly appliesTo: "all";
+    readonly hookMatcher: {
+        readonly toolPattern: "write|edit|multiedit|delete|applypatch|shell|bash";
+        readonly payloadPattern: "\\.cclaw/(state|hooks|skills)";
+    };
+}, {
+    readonly id: "flow-state-read-fresh";
+    readonly title: "Fresh flow-state read required";
+    readonly rule: "Before mutating actions, a fresh read of .cclaw/state/flow-state.json must exist within guard freshness window.";
+    readonly rationale: "Prevents stale-stage mutations after context shifts or multi-agent divergence.";
+    readonly enforcement: "PreToolUse";
+    readonly severity: "hard-gate";
+    readonly appliesTo: "all";
+}, {
+    readonly id: "review-layer-order";
+    readonly title: "Review layers are sequential";
+    readonly rule: "Review stage must complete Layer 1 spec compliance before Layer 2 quality/security passes.";
+    readonly rationale: "Stops premature quality discussion when acceptance criteria are not yet satisfied.";
+    readonly enforcement: "advisory";
+    readonly severity: "soft-gate";
+    readonly appliesTo: ["review"];
+}, {
+    readonly id: "review-criticals-close-before-ship";
+    readonly title: "No ship with open criticals";
+    readonly rule: "Ship decisions are blocked when review-army contains open Critical findings or ship blockers.";
+    readonly rationale: "Enforces explicit risk closure before release finalization.";
+    readonly enforcement: "PreToolUse";
+    readonly severity: "hard-gate";
+    readonly appliesTo: ["ship"];
+}, {
+    readonly id: "ship-preflight-required";
+    readonly title: "Preflight required before finalization";
+    readonly rule: "Do not execute release finalization actions until ship preflight gate is passed.";
+    readonly rationale: "Catches regressions before irreversible release steps.";
+    readonly enforcement: "PreToolUse";
+    readonly severity: "hard-gate";
+    readonly appliesTo: ["ship"];
+}, {
+    readonly id: "review-coverage-complete-before-ship";
+    readonly title: "Review layer coverage before ship";
+    readonly rule: "Block ship finalization when review-army does not confirm full Layer 1/2 coverage map.";
+    readonly rationale: "Prevents finalization when multi-pass review evidence is incomplete or partially missing.";
+    readonly enforcement: "PreToolUse";
+    readonly severity: "hard-gate";
+    readonly appliesTo: ["ship"];
+}, {
+    readonly id: "subagent-task-self-contained";
+    readonly title: "Subagent tasks are self-contained";
+    readonly rule: "Delegated tasks must include explicit objective, constraints, and expected output, not just references.";
+    readonly rationale: "Avoids context loss and low-quality delegation in isolated worker contexts.";
+    readonly enforcement: "advisory";
+    readonly severity: "soft-gate";
+    readonly appliesTo: "all";
+}, {
+    readonly id: "no-secrets-in-artifacts";
+    readonly title: "Never log secrets in artifacts";
+    readonly rule: "Secrets/tokens/passwords must not be written to review, ship, or runtime state artifacts.";
+    readonly rationale: "Prevents accidental credential leakage through generated workflow artifacts.";
+    readonly enforcement: "PostToolUse";
+    readonly severity: "hard-gate";
+    readonly appliesTo: "all";
+}, {
+    readonly id: "stop-clean-or-checkpointed";
+    readonly title: "Stop only from clean checkpoint";
+    readonly rule: "Do not end a session with dirty state unless checkpoint explicitly records unresolved work and blockers.";
+    readonly rationale: "Protects continuity and prevents silent half-finished sessions.";
+    readonly enforcement: "Stop";
+    readonly severity: "hard-gate";
+    readonly appliesTo: "all";
+}];
+export declare function isIronLawId(value: string): boolean;
+export declare function normalizeStrictLawIds(ids: string[] | undefined): string[];
+export declare function ironLawRuntimeDocument(options?: {
+    mode?: "advisory" | "strict";
+    strictLaws?: string[];
+    nowIso?: string;
+}): IronLawRuntimeDocument;
+export declare function ironLawsAgentsMdBlock(): string;
+export declare function ironLawsSkillMarkdown(): string;

package/dist/content/iron-laws.js

@@ -0,0 +1,191 @@
+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: "review-coverage-complete-before-ship",
+        title: "Review layer coverage before ship",
+        rule: "Block ship finalization when review-army does not confirm full Layer 1/2 coverage map.",
+        rationale: "Prevents finalization when multi-pass review evidence is incomplete or partially missing.",
+        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.