cclaw-cli 0.48.4 → 0.48.6

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/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/eval/agents/workflow.js

@@ -29,9 +29,17 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { createSandbox } from "../sandbox.js";
 import { loadStageSkill } from "./single-shot.js";
-import { runWithTools } from "./with-tools.js";
+import { MaxTurnsExceededError, runWithTools } from "./with-tools.js";
 const STAGES_SUBDIR = "stages";
 const ARTIFACT_CANDIDATES = ["artifact.md", "artifact.txt", "ARTIFACT.md"];
+const DEFAULT_WORKFLOW_MAX_TOTAL_TURNS = 40;
+const DEFAULT_STAGE_TURN_CAP = 8;
+function clampPositive(value, fallback) {
+    if (!Number.isInteger(value) || value < 1) {
+        return fallback;
+    }
+    return value;
+}
 export async function runWorkflow(input) {
     const { workflow, config, projectRoot, client } = input;
     const sandboxFactory = input.createSandboxFn ?? createSandbox;
@@ -43,9 +51,17 @@ export async function runWorkflow(input) {
     const artifacts = new Map();
     let totalUsageUsd = 0;
     let totalDurationMs = 0;
+    let totalTurns = 0;
+    const workflowTurnBudget = clampPositive(config.workflowMaxTotalTurns, DEFAULT_WORKFLOW_MAX_TOTAL_TURNS);
     try {
         await fs.mkdir(await sandbox.resolve(STAGES_SUBDIR, { allowMissing: true }), { recursive: true });
         for (const step of workflow.stages) {
+            const remainingWorkflowTurns = workflowTurnBudget - totalTurns;
+            if (remainingWorkflowTurns < 1) {
+                throw new MaxTurnsExceededError(workflowTurnBudget);
+            }
+            const perStageTurnCap = clampPositive(config.toolMaxTurns, DEFAULT_STAGE_TURN_CAP);
+            const stageTurnBudget = Math.min(perStageTurnCap, remainingWorkflowTurns);
             input.onStageStart?.(step.name);
             await clearArtifactFile(sandbox);
             const priorStages = stageResults.map((r) => r.stage);
@@ -58,7 +74,10 @@ export async function runWorkflow(input) {
             };
             const result = await runWithTools({
                 caseEntry,
-                config,
+                config: {
+                    ...config,
+                    toolMaxTurns: stageTurnBudget
+                },
                 projectRoot,
                 client,
                 ...(input.tools ? { tools: input.tools } : {}),
@@ -87,6 +106,7 @@ export async function runWorkflow(input) {
             input.onStageEnd?.(step.name, stageResult);
             totalUsageUsd += result.usageUsd;
             totalDurationMs += result.durationMs;
+            totalTurns += result.toolUse.turns;
         }
         return {
             caseId: workflow.id,

package/dist/gate-evidence.js

@@ -7,6 +7,7 @@ import { readDelegationLedger } from "./delegation.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { detectPublicApiChanges } from "./internal/detect-public-api-changes.js";
 import { readFlowState, writeFlowState } from "./runs.js";
+import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { FLOW_STAGES } from "./types.js";
 async function currentStageArtifactExists(projectRoot, stage, track) {
@@ -200,6 +201,7 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         issues.push(`stale triggered conditional gate "${gateId}" found in stageGateCatalog.triggered for stage "${stage}" (conditional gate DSL removed).`);
     }
     const blockedSet = new Set(catalog.blocked);
+    const passedSet = new Set(catalog.passed);
     for (const gateId of catalog.passed) {
         if (!allowedSet.has(gateId)) {
             issues.push(`passed gate "${gateId}" is not defined for stage "${stage}".`);
@@ -239,6 +241,13 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             if (!verdictConsistency.ok) {
                 issues.push(`review verdict inconsistency: ${verdictConsistency.errors.join("; ")}`);
             }
+            const reviewCriticalsClaimedResolved = passedSet.has("review_criticals_resolved") || flowState.completedStages.includes("review");
+            const unresolvedCriticals = verdictConsistency.openCriticalCount > 0 || verdictConsistency.shipBlockerCount > 0;
+            if (reviewCriticalsClaimedResolved && unresolvedCriticals) {
+                issues.push(`review criticals gate blocked (review_criticals_resolved): review-army still reports ` +
+                    `${verdictConsistency.openCriticalCount} open critical(s) and ` +
+                    `${verdictConsistency.shipBlockerCount} ship blocker(s).`);
+            }
             const securityAttestation = await checkReviewSecurityNoChangeAttestation(projectRoot);
             if (!securityAttestation.ok) {
                 issues.push(`review security attestation failed: ${securityAttestation.errors.join("; ")}`);
@@ -309,9 +318,29 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                     issues.push(`tdd docs drift gate blocked (tdd_docs_drift_check): public surface changes detected (${docsDriftDetection.changedFiles.join(", ")}) but no completed doc-updater delegation exists for the active run.`);
                 }
             }
+            const tddLogPath = path.join(projectRoot, RUNTIME_ROOT, "state", "tdd-cycle-log.jsonl");
+            if (await exists(tddLogPath)) {
+                try {
+                    const tddLogRaw = await fs.readFile(tddLogPath, "utf8");
+                    const parsedCycles = parseTddCycleLog(tddLogRaw);
+                    const tddOrderValidation = validateTddCycleOrder(parsedCycles, {
+                        runId: flowState.activeRunId
+                    });
+                    if (!tddOrderValidation.ok) {
+                        const details = [...tddOrderValidation.issues];
+                        if (tddOrderValidation.openRedSlices.length > 0) {
+                            details.push(`open red slices: ${tddOrderValidation.openRedSlices.join(", ")}`);
+                        }
+                        issues.push(`tdd cycle order gate blocked: ${details.join("; ")}`);
+                    }
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    issues.push(`tdd cycle order gate blocked: unable to read tdd-cycle-log.jsonl (${reason}).`);
+                }
+            }
         }
     }
-    const passedSet = new Set(catalog.passed);
     const missingRequired = required.filter((gateId) => !passedSet.has(gateId));
     const missingRecommended = recommended.filter((gateId) => !passedSet.has(gateId));
     const missingTriggeredConditional = [];

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,6 +23,7 @@ import { archiveCommandContract, archiveCommandSkillMarkdown } from "./content/a
 import { rewindCommandContract, rewindCommandSkillMarkdown } from "./content/rewind-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
+import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
 import { 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";
@@ -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,13 @@ 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, "session-start.sh"), sessionStartScript());
     await writeFileSafe(path.join(hooksDir, "stop-checkpoint.sh"), stopCheckpointScript());
     await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookDispatcherScript());

package/dist/internal/advance-stage.js

@@ -10,6 +10,8 @@ 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";
 function unique(values) {
     return [...new Set(values)];
 }
@@ -621,7 +623,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\n");
         return 1;
     }
     try {
@@ -634,7 +636,13 @@ 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);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate\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 {};

package/dist/internal/knowledge-digest.js

@@ -0,0 +1,93 @@
+import { selectRelevantLearnings } from "../knowledge-store.js";
+import { FLOW_STAGES } from "../types.js";
+function parseCsv(raw) {
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+}
+function parseKnowledgeDigestArgs(tokens) {
+    const args = {
+        diffFiles: [],
+        openGates: [],
+        limit: 8,
+        format: "markdown"
+    };
+    for (const token of tokens) {
+        if (!token.startsWith("--")) {
+            throw new Error(`Unknown positional token for knowledge-digest: ${token}`);
+        }
+        if (token.startsWith("--stage=")) {
+            const value = token.replace("--stage=", "").trim();
+            if (!value)
+                continue;
+            if (!FLOW_STAGES.includes(value)) {
+                throw new Error(`--stage must be one of: ${FLOW_STAGES.join(", ")}`);
+            }
+            args.stage = value;
+            continue;
+        }
+        if (token.startsWith("--branch=")) {
+            const value = token.replace("--branch=", "").trim();
+            if (value.length > 0) {
+                args.branch = value;
+            }
+            continue;
+        }
+        if (token.startsWith("--diff-files=")) {
+            args.diffFiles.push(...parseCsv(token.replace("--diff-files=", "")));
+            continue;
+        }
+        if (token.startsWith("--open-gates=")) {
+            args.openGates.push(...parseCsv(token.replace("--open-gates=", "")));
+            continue;
+        }
+        if (token.startsWith("--limit=")) {
+            const raw = token.replace("--limit=", "").trim();
+            const value = Number.parseInt(raw, 10);
+            if (!Number.isFinite(value) || value <= 0) {
+                throw new Error("--limit must be a positive integer.");
+            }
+            args.limit = value;
+            continue;
+        }
+        if (token === "--json") {
+            args.format = "json";
+            continue;
+        }
+        if (token === "--markdown") {
+            args.format = "markdown";
+            continue;
+        }
+        throw new Error(`Unknown flag for knowledge-digest: ${token}`);
+    }
+    return args;
+}
+function markdownDigest(rows) {
+    if (rows.length === 0) {
+        return "(no relevant learnings)";
+    }
+    return rows
+        .map((entry) => {
+        const stage = entry.stage ?? "global";
+        const domain = entry.domain ?? "general";
+        return `- [${entry.confidence} | ${stage} | ${domain}] ${entry.trigger} -> ${entry.action}`;
+    })
+        .join("\n");
+}
+export async function runKnowledgeDigestCommand(projectRoot, tokens, io) {
+    const args = parseKnowledgeDigestArgs(tokens);
+    const rows = await selectRelevantLearnings(projectRoot, {
+        stage: args.stage,
+        branch: args.branch,
+        diffFiles: args.diffFiles,
+        openGates: args.openGates,
+        limit: args.limit
+    });
+    if (args.format === "json") {
+        io.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+        return 0;
+    }
+    io.stdout.write(`${markdownDigest(rows)}\n`);
+    return 0;
+}

package/dist/knowledge-store.d.ts

@@ -65,6 +65,13 @@ export interface ReadKnowledgeResult {
     entries: KnowledgeEntry[];
     malformedLines: number;
 }
+export interface SelectRelevantLearningsOptions {
+    stage?: FlowStage | null;
+    branch?: string | null;
+    diffFiles?: string[];
+    openGates?: string[];
+    limit?: number;
+}
 export declare function validateKnowledgeEntry(entry: unknown): {
     ok: boolean;
     errors: string[];
@@ -72,3 +79,4 @@ export declare function validateKnowledgeEntry(entry: unknown): {
 export declare function materializeKnowledgeEntry(seed: KnowledgeSeedEntry, defaults?: AppendKnowledgeDefaults): KnowledgeEntry;
 export declare function readKnowledgeSafely(projectRoot: string, options?: ReadKnowledgeOptions): Promise<ReadKnowledgeResult>;
 export declare function appendKnowledge(projectRoot: string, seeds: KnowledgeSeedEntry[], defaults?: AppendKnowledgeDefaults): Promise<AppendKnowledgeResult>;
+export declare function selectRelevantLearnings(projectRoot: string, options?: SelectRelevantLearningsOptions): Promise<KnowledgeEntry[]>;

package/dist/knowledge-store.js

@@ -327,3 +327,98 @@ export async function appendKnowledge(projectRoot, seeds, defaults = {}) {
         appendedEntries
     };
 }
+function tokenizeText(value) {
+    if (!value)
+        return [];
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/u)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 3);
+}
+function uniqueTokens(values) {
+    return [...new Set(values)];
+}
+function pathTokens(paths) {
+    if (!Array.isArray(paths) || paths.length === 0)
+        return [];
+    const tokens = [];
+    for (const filePath of paths) {
+        tokens.push(...tokenizeText(filePath));
+    }
+    return uniqueTokens(tokens);
+}
+export async function selectRelevantLearnings(projectRoot, options = {}) {
+    const { entries } = await readKnowledgeSafely(projectRoot);
+    if (entries.length === 0) {
+        return [];
+    }
+    const stage = options.stage ?? null;
+    const branchTokens = tokenizeText(options.branch ?? null);
+    const diffTokens = pathTokens(options.diffFiles);
+    const gateTokens = pathTokens(options.openGates);
+    const limit = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0
+        ? Math.floor(options.limit)
+        : 8;
+    const ranked = entries.map((entry, index) => {
+        let score = 0;
+        if (stage) {
+            if (entry.stage === stage) {
+                score += 4;
+            }
+            else if (entry.origin_stage === stage) {
+                score += 3;
+            }
+            else if (entry.stage === null) {
+                score += 1;
+            }
+        }
+        if (entry.confidence === "high")
+            score += 2;
+        if (entry.confidence === "medium")
+            score += 1;
+        if (entry.frequency >= 3)
+            score += 1;
+        if (entry.maturity === "lifted-to-enforcement")
+            score -= 1;
+        const searchable = [
+            ...tokenizeText(entry.domain),
+            ...tokenizeText(entry.trigger),
+            ...tokenizeText(entry.action),
+            ...tokenizeText(entry.origin_feature),
+            ...tokenizeText(entry.project)
+        ];
+        const searchSet = new Set(searchable);
+        for (const token of branchTokens) {
+            if (searchSet.has(token))
+                score += 2;
+        }
+        for (const token of diffTokens) {
+            if (searchSet.has(token))
+                score += 2;
+        }
+        for (const token of gateTokens) {
+            if (searchSet.has(token))
+                score += 2;
+        }
+        return {
+            index,
+            score,
+            entry
+        };
+    });
+    ranked.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        const bySeen = Date.parse(b.entry.last_seen_ts) - Date.parse(a.entry.last_seen_ts);
+        if (!Number.isNaN(bySeen) && bySeen !== 0)
+            return bySeen;
+        if (b.entry.frequency !== a.entry.frequency)
+            return b.entry.frequency - a.entry.frequency;
+        return b.index - a.index;
+    });
+    return ranked
+        .filter((row) => row.score > 0)
+        .slice(0, limit)
+        .map((row) => row.entry);
+}

package/dist/tdd-cycle.d.ts

@@ -20,3 +20,10 @@ export declare function parseTddCycleLog(text: string): TddCycleEntry[];
 export declare function validateTddCycleOrder(entries: TddCycleEntry[], options?: {
     runId?: string;
 }): TddCycleValidation;
+/**
+ * Checks whether the log contains a failing RED record associated with
+ * `productionPath` for the active run.
+ */
+export declare function hasFailingTestForPath(entries: TddCycleEntry[], productionPath: string, options?: {
+    runId?: string;
+}): boolean;

package/dist/tdd-cycle.js

@@ -119,3 +119,32 @@ export function validateTddCycleOrder(entries, options = {}) {
         sliceCount: bySlice.size
     };
 }
+function normalizePath(value) {
+    return value.replace(/\\/gu, "/").toLowerCase();
+}
+/**
+ * Checks whether the log contains a failing RED record associated with
+ * `productionPath` for the active run.
+ */
+export function hasFailingTestForPath(entries, productionPath, options = {}) {
+    const normalizedTarget = normalizePath(productionPath);
+    const filtered = options.runId
+        ? entries.filter((entry) => entry.runId === options.runId)
+        : entries;
+    for (const entry of filtered) {
+        if (entry.phase !== "red")
+            continue;
+        if (entry.exitCode === undefined || entry.exitCode === 0)
+            continue;
+        if (!Array.isArray(entry.files) || entry.files.length === 0)
+            continue;
+        const hasMatch = entry.files.some((filePath) => {
+            const normalized = normalizePath(filePath);
+            return normalized === normalizedTarget || normalized.endsWith(`/${normalizedTarget}`);
+        });
+        if (hasMatch) {
+            return true;
+        }
+    }
+    return false;
+}