cclaw-cli 0.1.0 → 0.2.0

package/dist/delegation.js

@@ -0,0 +1,94 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "./constants.js";
+import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+import { readFlowState } from "./runs.js";
+import { stageSchema } from "./content/stage-schema.js";
+function delegationLogPath(projectRoot, runId) {
+    return path.join(projectRoot, RUNTIME_ROOT, "runs", runId, "delegation-log.json");
+}
+function delegationLockPath(projectRoot, runId) {
+    return path.join(projectRoot, RUNTIME_ROOT, "runs", runId, ".delegation.lock");
+}
+function isDelegationEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const o = value;
+    const modeOk = o.mode === "mandatory" || o.mode === "proactive";
+    const statusOk = o.status === "scheduled" ||
+        o.status === "completed" ||
+        o.status === "failed" ||
+        o.status === "waived";
+    return (typeof o.stage === "string" &&
+        typeof o.agent === "string" &&
+        modeOk &&
+        statusOk &&
+        typeof o.ts === "string" &&
+        (o.taskId === undefined || typeof o.taskId === "string") &&
+        (o.waiverReason === undefined || typeof o.waiverReason === "string"));
+}
+function parseLedger(raw, runId) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { runId, entries: [] };
+    }
+    const o = raw;
+    const entriesRaw = o.entries;
+    const entries = [];
+    if (Array.isArray(entriesRaw)) {
+        for (const item of entriesRaw) {
+            if (isDelegationEntry(item)) {
+                entries.push(item);
+            }
+        }
+    }
+    return { runId, entries };
+}
+export async function readDelegationLedger(projectRoot) {
+    const { activeRunId } = await readFlowState(projectRoot);
+    const filePath = delegationLogPath(projectRoot, activeRunId);
+    if (!(await exists(filePath))) {
+        return { runId: activeRunId, entries: [] };
+    }
+    try {
+        const text = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(text);
+        return parseLedger(parsed, activeRunId);
+    }
+    catch {
+        return { runId: activeRunId, entries: [] };
+    }
+}
+export async function appendDelegation(projectRoot, entry) {
+    const { activeRunId } = await readFlowState(projectRoot);
+    await withDirectoryLock(delegationLockPath(projectRoot, activeRunId), async () => {
+        const filePath = delegationLogPath(projectRoot, activeRunId);
+        const prior = await readDelegationLedger(projectRoot);
+        const ledger = {
+            runId: activeRunId,
+            entries: [...prior.entries, entry]
+        };
+        await writeFileSafe(filePath, `${JSON.stringify(ledger, null, 2)}\n`);
+    });
+}
+export async function checkMandatoryDelegations(projectRoot, stage) {
+    const mandatory = stageSchema(stage).mandatoryDelegations;
+    const ledger = await readDelegationLedger(projectRoot);
+    const forStage = ledger.entries.filter((e) => e.stage === stage);
+    const missing = [];
+    const waived = [];
+    for (const agent of mandatory) {
+        const rows = forStage.filter((e) => e.agent === agent);
+        const ok = rows.some((e) => e.status === "completed" || e.status === "waived");
+        if (!ok) {
+            missing.push(agent);
+        }
+        else if (rows.some((e) => e.status === "waived")) {
+            waived.push(agent);
+        }
+    }
+    return {
+        satisfied: missing.length === 0,
+        missing,
+        waived
+    };
+}

package/dist/doctor.d.ts

@@ -3,5 +3,9 @@ export interface DoctorCheck {
     ok: boolean;
     details: string;
 }
-export declare function doctorChecks(projectRoot: string): Promise<DoctorCheck[]>;
+export interface DoctorOptions {
+    /** When true, normalize current-stage gate catalog and persist reconciliation before checks. */
+    reconcileCurrentStageGates?: boolean;
+}
+export declare function doctorChecks(projectRoot: string, options?: DoctorOptions): Promise<DoctorCheck[]>;
 export declare function doctorSucceeded(checks: DoctorCheck[]): boolean;

package/dist/doctor.js

@@ -10,7 +10,13 @@ import { gitignoreHasRequiredPatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END } from "./harness-adapters.js";
 import { policyChecks } from "./policy.js";
 import { readFlowState } from "./runs.js";
+import { checkMandatoryDelegations } from "./delegation.js";
+import { buildTraceMatrix } from "./trace-matrix.js";
+import { reconcileAndWriteCurrentStageGateCatalog, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { stageSkillFolder } from "./content/skills.js";
+import { UTILITY_SKILL_FOLDERS } from "./content/utility-skills.js";
+import { CONTEXT_MODES, DEFAULT_CONTEXT_MODE } from "./content/contexts.js";
+import { validateHookDocument } from "./hook-schema.js";
 const execFileAsync = promisify(execFile);
 async function isGitRepo(projectRoot) {
     try {
@@ -21,6 +27,19 @@ async function isGitRepo(projectRoot) {
         return false;
     }
 }
+async function resolveGitHooksDir(projectRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", "hooks"], { cwd: projectRoot });
+        const rel = stdout.trim();
+        if (rel.length === 0) {
+            return null;
+        }
+        return path.resolve(projectRoot, rel);
+    }
+    catch {
+        return null;
+    }
+}
 async function gitIgnoresRuntime(projectRoot) {
     try {
         await execFileAsync("git", ["check-ignore", "-q", `${RUNTIME_ROOT}/`], { cwd: projectRoot });
@@ -128,7 +147,46 @@ async function readHookDocument(filePath) {
         return null;
     }
 }
-export async function doctorChecks(projectRoot) {
+function normalizeOpenCodePluginEntry(entry) {
+    if (typeof entry === "string" && entry.trim().length > 0)
+        return entry.trim();
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return null;
+    const obj = entry;
+    for (const key of ["path", "src", "plugin"]) {
+        const value = obj[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+async function opencodeRegistrationCheck(projectRoot) {
+    const expected = ".opencode/plugins/cclaw-plugin.mjs";
+    const candidates = [
+        path.join(projectRoot, "opencode.json"),
+        path.join(projectRoot, "opencode.jsonc"),
+        path.join(projectRoot, ".opencode/opencode.json"),
+        path.join(projectRoot, ".opencode/opencode.jsonc")
+    ];
+    for (const configPath of candidates) {
+        if (!(await exists(configPath))) {
+            continue;
+        }
+        const parsed = await readHookDocument(configPath);
+        if (!parsed) {
+            continue;
+        }
+        const plugins = Array.isArray(parsed.plugins) ? parsed.plugins : [];
+        const registered = plugins.some((entry) => normalizeOpenCodePluginEntry(entry) === expected);
+        if (registered) {
+            return { ok: true, details: `${path.relative(projectRoot, configPath)} registers ${expected}` };
+        }
+        return { ok: false, details: `${path.relative(projectRoot, configPath)} missing plugin ${expected}` };
+    }
+    return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${expected}` };
+}
+export async function doctorChecks(projectRoot, options = {}) {
     const checks = [];
     for (const dir of REQUIRED_DIRS) {
         const fullPath = path.join(projectRoot, dir);
@@ -169,8 +227,10 @@ export async function doctorChecks(projectRoot) {
         details: ".gitignore must include cclaw ignore block"
     });
     let configuredHarnesses = [];
+    let parsedConfig = null;
     try {
         const config = await readConfig(projectRoot);
+        parsedConfig = config;
         configuredHarnesses = config.harnesses;
         checks.push({
             name: "config:valid",
@@ -185,6 +245,55 @@ export async function doctorChecks(projectRoot) {
             details: error instanceof Error ? error.message : "Invalid config"
         });
     }
+    if (parsedConfig) {
+        const expectedMode = parsedConfig.promptGuardMode === "strict" ? "strict" : "advisory";
+        const promptGuardPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", "prompt-guard.sh");
+        let promptGuardModeOk = false;
+        if (await exists(promptGuardPath)) {
+            const promptGuardContent = await fs.readFile(promptGuardPath, "utf8");
+            promptGuardModeOk = promptGuardContent.includes(`PROMPT_GUARD_MODE="${expectedMode}"`);
+        }
+        checks.push({
+            name: "hook:prompt_guard:mode",
+            ok: promptGuardModeOk,
+            details: `${promptGuardPath} must match promptGuardMode=${expectedMode}`
+        });
+        if (parsedConfig.gitHookGuards === true) {
+            const runtimePreCommit = path.join(projectRoot, RUNTIME_ROOT, "hooks", "git", "pre-commit.sh");
+            const runtimePrePush = path.join(projectRoot, RUNTIME_ROOT, "hooks", "git", "pre-push.sh");
+            const runtimeScriptsOk = (await exists(runtimePreCommit)) && (await exists(runtimePrePush));
+            checks.push({
+                name: "git_hooks:managed:runtime_scripts",
+                ok: runtimeScriptsOk,
+                details: `${RUNTIME_ROOT}/hooks/git/pre-commit.sh and pre-push.sh must exist when gitHookGuards=true`
+            });
+            const gitHooksDir = await resolveGitHooksDir(projectRoot);
+            if (!gitHooksDir) {
+                checks.push({
+                    name: "git_hooks:managed:relays",
+                    ok: true,
+                    details: "git repository not detected; relay hook check skipped"
+                });
+            }
+            else {
+                const preCommitHookPath = path.join(gitHooksDir, "pre-commit");
+                const prePushHookPath = path.join(gitHooksDir, "pre-push");
+                let relaysOk = false;
+                if ((await exists(preCommitHookPath)) && (await exists(prePushHookPath))) {
+                    const preCommitHook = await fs.readFile(preCommitHookPath, "utf8");
+                    const prePushHook = await fs.readFile(prePushHookPath, "utf8");
+                    relaysOk =
+                        preCommitHook.includes("cclaw-managed-git-hook") &&
+                            prePushHook.includes("cclaw-managed-git-hook");
+                }
+                checks.push({
+                    name: "git_hooks:managed:relays",
+                    ok: relaysOk,
+                    details: `${path.relative(projectRoot, gitHooksDir)}/pre-commit and pre-push must contain managed relay marker`
+                });
+            }
+        }
+    }
     for (const harness of configuredHarnesses) {
         const adapter = HARNESS_ADAPTERS[harness];
         if (!adapter) {
@@ -223,19 +332,14 @@ export async function doctorChecks(projectRoot) {
         const hasAllCommands = COMMAND_FILE_ORDER.every((stage) => content.includes(`/cc-${stage}`));
         const hasRouting = content.includes("Intent → Stage Routing") || content.includes("Intent → Stage");
         const hasVerification = content.includes("Verification Discipline");
-        const hasFileMap = content.includes("File Map");
-        const hasLearnings = content.includes("Learnings Store");
-        const hasAutoplan = content.includes("Autoplan Orchestrator");
-        const hasAgents = content.includes("Agent Specialists");
-        const hasSubagents = content.includes("Subagent Orchestration");
-        const hasSessionProtocols = content.includes("Session Guidelines");
-        const hasHooks = content.includes("Hooks");
-        agentsBlockOk = hasMarkers && hasAllCommands && hasRouting && hasVerification && hasFileMap && hasLearnings && hasAutoplan && hasAgents && hasSubagents && hasSessionProtocols && hasHooks;
+        const hasMinimalMarker = content.includes("intentionally minimal for cross-project use");
+        const hasMetaSkillPointer = content.includes(".cclaw/skills/using-cclaw/SKILL.md");
+        agentsBlockOk = hasMarkers && hasAllCommands && hasRouting && hasVerification && hasMinimalMarker && hasMetaSkillPointer;
     }
     checks.push({
         name: "agents:cclaw_block",
         ok: agentsBlockOk,
-        details: `${agentsFile} must contain cclaw marker block with routing, verification, and file map`
+        details: `${agentsFile} must contain the managed cclaw marker block with routing, verification, and minimal detail pointer`
     });
     // Utility commands
     for (const cmd of ["learn", "autoplan"]) {
@@ -262,14 +366,8 @@ export async function doctorChecks(projectRoot) {
             details: skillPath
         });
     }
-    // New utility skills (security, debugging, performance, ci-cd, docs)
-    for (const folder of [
-        "security",
-        "debugging",
-        "performance",
-        "ci-cd",
-        "docs"
-    ]) {
+    // Extended utility skills generated from utility skill map.
+    for (const folder of UTILITY_SKILL_FOLDERS) {
         const skillPath = path.join(projectRoot, RUNTIME_ROOT, "skills", folder, "SKILL.md");
         checks.push({
             name: `utility_skill:${folder}`,
@@ -296,6 +394,7 @@ export async function doctorChecks(projectRoot) {
         "session-start.sh",
         "stop-checkpoint.sh",
         "prompt-guard.sh",
+        "workflow-guard.sh",
         "context-monitor.sh",
         "observe.sh",
         "summarize-observations.sh",
@@ -349,14 +448,33 @@ export async function doctorChecks(projectRoot) {
                 ok: hookOk,
                 details: fullPath
             });
+            if (harness === "claude" || harness === "cursor" || harness === "codex") {
+                const schema = validateHookDocument(harness, parsed);
+                checks.push({
+                    name: `hook:schema:${harness}`,
+                    ok: schema.ok,
+                    details: schema.ok
+                        ? `${fullPath} matches cclaw hook schema v1`
+                        : `${fullPath} schema issues: ${schema.errors.join("; ")}`
+                });
+            }
         }
     }
-    // OpenCode plugin
+    // OpenCode plugin source + deployed path
     checks.push({
-        name: "hook:opencode_plugin",
+        name: "hook:opencode_plugin_source",
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "hooks", "opencode-plugin.mjs")),
         details: `${RUNTIME_ROOT}/hooks/opencode-plugin.mjs`
     });
+    const opencodeEnabled = configuredHarnesses.includes("opencode");
+    const opencodeDeployed = await exists(path.join(projectRoot, ".opencode/plugins/cclaw-plugin.mjs"));
+    checks.push({
+        name: "hook:opencode_plugin_deployed",
+        ok: opencodeEnabled ? opencodeDeployed : true,
+        details: opencodeEnabled
+            ? ".opencode/plugins/cclaw-plugin.mjs"
+            : "opencode harness disabled; deployed plugin check skipped"
+    });
     if (configuredHarnesses.includes("claude")) {
         const file = path.join(projectRoot, ".claude/hooks/hooks.json");
         const parsed = await readHookDocument(file);
@@ -374,6 +492,7 @@ export async function doctorChecks(projectRoot) {
         const stopCommands = collectHookCommands(hooks.Stop);
         const wiringOk = sessionCommands.some((cmd) => cmd.includes("session-start.sh")) &&
             preCommands.some((cmd) => cmd.includes("prompt-guard.sh")) &&
+            preCommands.some((cmd) => cmd.includes("workflow-guard.sh")) &&
             preCommands.some((cmd) => cmd.includes("observe.sh pre")) &&
             postCommands.some((cmd) => cmd.includes("observe.sh post")) &&
             postCommands.some((cmd) => cmd.includes("context-monitor.sh")) &&
@@ -382,7 +501,7 @@ export async function doctorChecks(projectRoot) {
         checks.push({
             name: "hook:wiring:claude",
             ok: wiringOk,
-            details: `${file} must wire session-start/prompt-guard/observe/context-monitor/summarize/stop-checkpoint`
+            details: `${file} must wire session-start/prompt-guard/workflow-guard/observe/context-monitor/summarize/stop-checkpoint`
         });
     }
     if (configuredHarnesses.includes("cursor")) {
@@ -409,6 +528,7 @@ export async function doctorChecks(projectRoot) {
         const stopCommands = collectHookCommands(hooks.stop);
         const wiringOk = sessionCommands.some((cmd) => cmd.includes("session-start.sh")) &&
             preCommands.some((cmd) => cmd.includes("prompt-guard.sh")) &&
+            preCommands.some((cmd) => cmd.includes("workflow-guard.sh")) &&
             preCommands.some((cmd) => cmd.includes("observe.sh pre")) &&
             postCommands.some((cmd) => cmd.includes("observe.sh post")) &&
             postCommands.some((cmd) => cmd.includes("context-monitor.sh")) &&
@@ -417,7 +537,21 @@ export async function doctorChecks(projectRoot) {
         checks.push({
             name: "hook:wiring:cursor",
             ok: wiringOk,
-            details: `${file} must wire session-start/prompt-guard/observe/context-monitor/summarize/stop-checkpoint`
+            details: `${file} must wire session-start/prompt-guard/workflow-guard/observe/context-monitor/summarize/stop-checkpoint`
+        });
+        const cursorRulePath = path.join(projectRoot, ".cursor/rules/cclaw-workflow.mdc");
+        let cursorRuleOk = false;
+        if (await exists(cursorRulePath)) {
+            const content = await fs.readFile(cursorRulePath, "utf8");
+            cursorRuleOk =
+                content.includes("cclaw-managed-cursor-workflow-rule") &&
+                    content.includes(".cclaw/state/flow-state.json") &&
+                    content.includes("/cc-next");
+        }
+        checks.push({
+            name: "rules:cursor:workflow",
+            ok: cursorRuleOk,
+            details: `${cursorRulePath} must include managed marker and core cclaw workflow guardrails`
         });
     }
     if (configuredHarnesses.includes("codex")) {
@@ -437,6 +571,7 @@ export async function doctorChecks(projectRoot) {
         const stopCommands = collectHookCommands(hooks.Stop);
         const wiringOk = sessionCommands.some((cmd) => cmd.includes("session-start.sh")) &&
             preCommands.some((cmd) => cmd.includes("prompt-guard.sh")) &&
+            preCommands.some((cmd) => cmd.includes("workflow-guard.sh")) &&
             preCommands.some((cmd) => cmd.includes("observe.sh pre")) &&
             postCommands.some((cmd) => cmd.includes("observe.sh post")) &&
             postCommands.some((cmd) => cmd.includes("context-monitor.sh")) &&
@@ -445,25 +580,37 @@ export async function doctorChecks(projectRoot) {
         checks.push({
             name: "hook:wiring:codex",
             ok: wiringOk,
-            details: `${file} must wire session-start/prompt-guard/observe/context-monitor/summarize/stop-checkpoint`
+            details: `${file} must wire session-start/prompt-guard/workflow-guard/observe/context-monitor/summarize/stop-checkpoint`
         });
     }
     if (configuredHarnesses.includes("opencode")) {
-        const file = path.join(projectRoot, RUNTIME_ROOT, "hooks", "opencode-plugin.mjs");
+        const file = path.join(projectRoot, ".opencode/plugins/cclaw-plugin.mjs");
         let ok = false;
         if (await exists(file)) {
             const content = await fs.readFile(file, "utf8");
             ok =
-                content.includes('"session.created"') &&
+                content.includes("event: async") &&
+                    content.includes('"tool.execute.before"') &&
+                    content.includes('"tool.execute.after"') &&
+                    content.includes("prompt-guard.sh") &&
+                    content.includes("workflow-guard.sh") &&
+                    content.includes("context-monitor.sh") &&
+                    content.includes('"session.idle"') &&
+                    content.includes('"session.updated"') &&
                     content.includes('"session.resumed"') &&
-                    content.includes('"session.compacted"') &&
                     content.includes('"session.cleared"') &&
                     content.includes('"experimental.chat.system.transform"');
         }
         checks.push({
             name: "lifecycle:opencode:rehydration_events",
             ok,
-            details: `${file} must include created/resumed/compacted/cleared and transform rehydration handlers`
+            details: `${file} must include event lifecycle handler, tool.execute.before/after with prompt/workflow/context hooks, session.idle summarization, and transform rehydration`
+        });
+        const registration = await opencodeRegistrationCheck(projectRoot);
+        checks.push({
+            name: "hook:opencode:config_registration",
+            ok: registration.ok,
+            details: registration.details
         });
     }
     const hasBash = await commandAvailable("bash");
@@ -516,7 +663,56 @@ export async function doctorChecks(projectRoot) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "suggestion-memory.json")),
         details: `${RUNTIME_ROOT}/state/suggestion-memory.json must exist for proactive suggestion memory`
     });
-    const flowState = await readFlowState(projectRoot);
+    const contextModeStatePath = path.join(projectRoot, RUNTIME_ROOT, "state", "context-mode.json");
+    checks.push({
+        name: "state:context_mode_exists",
+        ok: await exists(contextModeStatePath),
+        details: `${RUNTIME_ROOT}/state/context-mode.json must exist for context mode switching`
+    });
+    if (await exists(contextModeStatePath)) {
+        let contextModeOk = false;
+        try {
+            const parsed = JSON.parse(await fs.readFile(contextModeStatePath, "utf8"));
+            const activeMode = typeof parsed.activeMode === "string" ? parsed.activeMode : "";
+            contextModeOk = activeMode.length > 0 && Object.prototype.hasOwnProperty.call(CONTEXT_MODES, activeMode);
+        }
+        catch {
+            contextModeOk = false;
+        }
+        checks.push({
+            name: "state:context_mode_valid",
+            ok: contextModeOk,
+            details: `${RUNTIME_ROOT}/state/context-mode.json must reference one of: ${Object.keys(CONTEXT_MODES).join(", ")} (default=${DEFAULT_CONTEXT_MODE})`
+        });
+    }
+    for (const mode of Object.keys(CONTEXT_MODES)) {
+        const modePath = path.join(projectRoot, RUNTIME_ROOT, "contexts", `${mode}.md`);
+        checks.push({
+            name: `contexts:mode:${mode}`,
+            ok: await exists(modePath),
+            details: modePath
+        });
+    }
+    let flowState = await readFlowState(projectRoot);
+    if (options.reconcileCurrentStageGates === true) {
+        const reconciliation = await reconcileAndWriteCurrentStageGateCatalog(projectRoot);
+        if (reconciliation.wrote) {
+            flowState = {
+                ...flowState,
+                stageGateCatalog: {
+                    ...flowState.stageGateCatalog,
+                    [reconciliation.stage]: reconciliation.after
+                }
+            };
+        }
+        checks.push({
+            name: "gates:reconcile:writeback",
+            ok: true,
+            details: reconciliation.wrote
+                ? `reconciled gate catalog for stage "${reconciliation.stage}": ${reconciliation.notes.join("; ")}`
+                : `no gate reconciliation changes needed for stage "${reconciliation.stage}"`
+        });
+    }
     checks.push({
         name: "flow_state:active_run_id",
         ok: typeof flowState.activeRunId === "string" && flowState.activeRunId.trim().length > 0,
@@ -537,6 +733,55 @@ export async function doctorChecks(projectRoot) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs", flowState.activeRunId, "00-handoff.md")),
         details: `${RUNTIME_ROOT}/runs/${flowState.activeRunId}/00-handoff.md must exist`
     });
+    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
+    checks.push({
+        name: "delegation:mandatory:current_stage",
+        ok: delegation.satisfied,
+        details: delegation.satisfied
+            ? `All mandatory delegations satisfied for stage "${flowState.currentStage}"`
+            : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}`
+    });
+    checks.push({
+        name: "warning:delegation:waived",
+        ok: true,
+        details: delegation.waived.length > 0
+            ? `warning: waived mandatory delegations for stage "${flowState.currentStage}": ${delegation.waived.join(", ")}`
+            : "no waived mandatory delegations for current stage"
+    });
+    const trace = await buildTraceMatrix(projectRoot);
+    const traceHasSignal = trace.entries.length > 0 ||
+        trace.orphanedCriteria.length > 0 ||
+        trace.orphanedTasks.length > 0 ||
+        trace.orphanedTests.length > 0;
+    checks.push({
+        name: "trace:criteria_coverage",
+        ok: !traceHasSignal || trace.orphanedCriteria.length === 0,
+        details: trace.orphanedCriteria.length === 0
+            ? "all spec criteria are linked to plan tasks"
+            : `orphaned criteria: ${trace.orphanedCriteria.join(", ")}`
+    });
+    checks.push({
+        name: "trace:task_to_test_coverage",
+        ok: !traceHasSignal || trace.orphanedTasks.length === 0,
+        details: trace.orphanedTasks.length === 0
+            ? "all plan tasks are linked to test slices"
+            : `orphaned tasks: ${trace.orphanedTasks.join(", ")}`
+    });
+    checks.push({
+        name: "trace:test_to_criteria_coverage",
+        ok: !traceHasSignal || trace.orphanedTests.length === 0,
+        details: trace.orphanedTests.length === 0
+            ? "all test slices map to acceptance-linked tasks"
+            : `orphaned test slices: ${trace.orphanedTests.join(", ")}`
+    });
+    const gateEvidence = await verifyCurrentStageGateEvidence(projectRoot, flowState);
+    checks.push({
+        name: "gates:evidence:current_stage",
+        ok: gateEvidence.ok,
+        details: gateEvidence.ok
+            ? `stage "${gateEvidence.stage}" gate evidence is consistent (required=${gateEvidence.requiredCount}, passed=${gateEvidence.passedCount}, blocked=${gateEvidence.blockedCount})`
+            : gateEvidence.issues.join(" ")
+    });
     // Utility shims in harness dirs
     for (const harness of configuredHarnesses) {
         const adapter = HARNESS_ADAPTERS[harness];
@@ -601,7 +846,7 @@ export async function doctorChecks(projectRoot) {
         ok: hasRules,
         details: rulesJsonPath
     });
-    const policy = await policyChecks(projectRoot);
+    const policy = await policyChecks(projectRoot, { harnesses: configuredHarnesses });
     checks.push(...policy);
     return checks;
 }

package/dist/fs-utils.d.ts

@@ -1,4 +1,14 @@
 export declare function ensureDir(dirPath: string): Promise<void>;
+export interface DirectoryLockOptions {
+    retries?: number;
+    retryDelayMs?: number;
+    staleAfterMs?: number;
+}
+/**
+ * Acquire a lightweight lock by creating a directory.
+ * The lock is removed in a finally block.
+ */
+export declare function withDirectoryLock<T>(lockPath: string, fn: () => Promise<T>, options?: DirectoryLockOptions): Promise<T>;
 export declare function writeFileSafe(filePath: string, content: string): Promise<void>;
 export declare function exists(filePath: string): Promise<boolean>;
 export declare function removeIfExists(targetPath: string): Promise<void>;

package/dist/fs-utils.js

@@ -3,6 +3,53 @@ import path from "node:path";
 export async function ensureDir(dirPath) {
     await fs.mkdir(dirPath, { recursive: true });
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Acquire a lightweight lock by creating a directory.
+ * The lock is removed in a finally block.
+ */
+export async function withDirectoryLock(lockPath, fn, options = {}) {
+    const retries = options.retries ?? 200;
+    const retryDelayMs = options.retryDelayMs ?? 20;
+    const staleAfterMs = options.staleAfterMs ?? 60_000;
+    await ensureDir(path.dirname(lockPath));
+    let acquired = false;
+    for (let attempt = 0; attempt < retries; attempt += 1) {
+        try {
+            await fs.mkdir(lockPath);
+            acquired = true;
+            break;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code !== "EEXIST") {
+                throw error;
+            }
+            try {
+                const stat = await fs.stat(lockPath);
+                if (Date.now() - stat.mtimeMs > staleAfterMs) {
+                    await fs.rm(lockPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                // Lock directory disappeared between retries.
+            }
+            await sleep(retryDelayMs);
+        }
+    }
+    if (!acquired) {
+        throw new Error(`Failed to acquire lock: ${lockPath}`);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+    }
+}
 export async function writeFileSafe(filePath, content) {
     await ensureDir(path.dirname(filePath));
     const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);

package/dist/gate-evidence.d.ts

@@ -0,0 +1,26 @@
+import type { FlowState, StageGateState } from "./flow-state.js";
+import type { FlowStage } from "./types.js";
+export interface GateEvidenceCheckResult {
+    ok: boolean;
+    stage: FlowStage;
+    issues: string[];
+    requiredCount: number;
+    passedCount: number;
+    blockedCount: number;
+}
+export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState): Promise<GateEvidenceCheckResult>;
+export interface GateReconciliationResult {
+    stage: FlowStage;
+    changed: boolean;
+    before: StageGateState;
+    after: StageGateState;
+    notes: string[];
+}
+export interface GateReconciliationWritebackResult extends GateReconciliationResult {
+    wrote: boolean;
+}
+export declare function reconcileCurrentStageGateCatalog(flowState: FlowState): {
+    nextState: FlowState;
+    reconciliation: GateReconciliationResult;
+};
+export declare function reconcileAndWriteCurrentStageGateCatalog(projectRoot: string): Promise<GateReconciliationWritebackResult>;