cclaw-cli 0.51.21 → 0.51.23

package/dist/doctor.js

@@ -18,6 +18,7 @@ import { buildTraceMatrix } from "./trace-matrix.js";
 import { classifyReconciliationNotices, reconcileAndWriteCurrentStageGateCatalog, readReconciliationNotices, RECONCILIATION_NOTICES_REL_PATH, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
 import { stageSkillFolder } from "./content/skills.js";
+import { stageCommandShimMarkdown } from "./content/stage-command.js";
 import { doctorCheckMetadata } from "./doctor-registry.js";
 import { resolveTrackFromPrompt } from "./track-heuristics.js";
 import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
@@ -25,6 +26,7 @@ import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_
 import { validateHookDocument } from "./hook-schema.js";
 import { validateKnowledgeEntry } from "./knowledge-store.js";
 import { readSeedShelf } from "./content/seed-shelf.js";
+import { evaluateRetroGate } from "./retro-gate.js";
 const execFileAsync = promisify(execFile);
 async function isGitRepo(projectRoot) {
     try {
@@ -149,18 +151,30 @@ function knowledgeRoutingSurfaceIsDiscoverable(content) {
     return ["trigger", "action", "origin_run"].every((term) => normalized.includes(term));
 }
 async function commandAvailable(command) {
+    const version = await commandVersion(command);
+    return version.available;
+}
+async function commandVersion(command, args = ["--version"]) {
     try {
         if (process.platform === "win32") {
             await execFileAsync("where", [command]);
-            return true;
         }
-        await execFileAsync(command, ["--version"]);
-        return true;
+        const { stdout, stderr } = await execFileAsync(command, args);
+        return { available: true, output: `${stdout}${stderr}`.trim() };
     }
     catch {
-        return false;
+        return { available: false, output: "" };
     }
 }
+function parseNodeMajor(versionOutput) {
+    const match = /v?(\d+)\./u.exec(versionOutput);
+    if (!match)
+        return null;
+    return Number(match[1]);
+}
+function gitVersionLooksUsable(versionOutput) {
+    return /git version \d+\.\d+/iu.test(versionOutput);
+}
 function stripJsonCommentsOutsideStrings(input) {
     let out = "";
     let i = 0;
@@ -276,17 +290,23 @@ function normalizeOpenCodePluginEntry(entry) {
     }
     return null;
 }
-async function opencodeRegistrationCheck(projectRoot) {
-    const expected = ".opencode/plugins/cclaw-plugin.mjs";
-    const candidates = [
+const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
+function opencodeConfigCandidates(projectRoot) {
+    return [
         path.join(projectRoot, "opencode.json"),
         path.join(projectRoot, "opencode.jsonc"),
         path.join(projectRoot, ".opencode/opencode.json"),
         path.join(projectRoot, ".opencode/opencode.jsonc")
     ];
+}
+function openCodeConfigRegistersPlugin(parsed) {
+    const plugins = Array.isArray(parsed.plugin) ? parsed.plugin : [];
+    return plugins.some((entry) => normalizeOpenCodePluginEntry(entry) === OPENCODE_PLUGIN_REL_PATH);
+}
+async function opencodeRegistrationCheck(projectRoot) {
     const mismatches = [];
     let foundAnyConfig = false;
-    for (const configPath of candidates) {
+    for (const configPath of opencodeConfigCandidates(projectRoot)) {
         if (!(await exists(configPath))) {
             continue;
         }
@@ -296,17 +316,130 @@ async function opencodeRegistrationCheck(projectRoot) {
             mismatches.push(`${path.relative(projectRoot, configPath)} is unreadable or invalid JSON`);
             continue;
         }
-        const plugins = Array.isArray(parsed.plugin) ? parsed.plugin : [];
-        const registered = plugins.some((entry) => normalizeOpenCodePluginEntry(entry) === expected);
-        if (registered) {
-            return { ok: true, details: `${path.relative(projectRoot, configPath)} registers ${expected}` };
+        if (openCodeConfigRegistersPlugin(parsed)) {
+            return { ok: true, details: `${path.relative(projectRoot, configPath)} registers ${OPENCODE_PLUGIN_REL_PATH}` };
         }
-        mismatches.push(`${path.relative(projectRoot, configPath)} missing plugin ${expected}`);
+        mismatches.push(`${path.relative(projectRoot, configPath)} missing plugin ${OPENCODE_PLUGIN_REL_PATH}`);
     }
     if (foundAnyConfig) {
         return { ok: false, details: mismatches.join(" | ") };
     }
-    return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${expected}` };
+    return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${OPENCODE_PLUGIN_REL_PATH}` };
+}
+async function opencodeQuestionPermissionCheck(projectRoot) {
+    const mismatches = [];
+    for (const configPath of opencodeConfigCandidates(projectRoot)) {
+        if (!(await exists(configPath)))
+            continue;
+        const parsed = await readHookDocument(configPath);
+        if (!parsed || !openCodeConfigRegistersPlugin(parsed))
+            continue;
+        const permission = toObject(parsed.permission) ?? {};
+        if (permission.question === "allow") {
+            return {
+                ok: true,
+                details: `${path.relative(projectRoot, configPath)} sets permission.question to "allow" for structured questions`
+            };
+        }
+        mismatches.push(`${path.relative(projectRoot, configPath)} registers ${OPENCODE_PLUGIN_REL_PATH} but must set permission.question to "allow"`);
+    }
+    if (mismatches.length > 0) {
+        return { ok: false, details: mismatches.join(" | ") };
+    }
+    return {
+        ok: false,
+        details: `No opencode config with ${OPENCODE_PLUGIN_REL_PATH} registration found; cannot verify permission.question = "allow"`
+    };
+}
+function opencodeQuestionEnvCheck() {
+    if (process.env.OPENCODE_ENABLE_QUESTION_TOOL === "1") {
+        return { ok: true, details: "OPENCODE_ENABLE_QUESTION_TOOL=1 is set for ACP question tooling" };
+    }
+    return {
+        ok: false,
+        details: "Set OPENCODE_ENABLE_QUESTION_TOOL=1 for OpenCode ACP clients so permission-gated structured questions can use the question tool."
+    };
+}
+async function initRecoveryCheck(projectRoot) {
+    const sentinelPath = path.join(projectRoot, RUNTIME_ROOT, "state", ".init-in-progress");
+    if (!(await exists(sentinelPath))) {
+        return { ok: true, details: "no partial init/sync sentinel found" };
+    }
+    let summary = `${RUNTIME_ROOT}/state/.init-in-progress sentinel present`;
+    try {
+        const parsed = JSON.parse(await fs.readFile(sentinelPath, "utf8"));
+        const operation = typeof parsed.operation === "string" ? parsed.operation : "unknown";
+        const startedAt = typeof parsed.startedAt === "string" ? parsed.startedAt : "unknown";
+        summary = `${summary} (operation=${operation}, startedAt=${startedAt})`;
+    }
+    catch {
+        summary = `${summary} (unreadable sentinel payload)`;
+    }
+    return {
+        ok: false,
+        details: `${summary}. Fix: inspect generated runtime files, then rerun cclaw sync or remove the sentinel only after confirming the runtime is complete.`
+    };
+}
+async function archiveIntegrityCheck(projectRoot) {
+    const runsDir = path.join(projectRoot, RUNTIME_ROOT, "runs");
+    if (!(await exists(runsDir))) {
+        return { ok: true, details: `${RUNTIME_ROOT}/runs is absent; no archives to inspect yet` };
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(runsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ok: false, details: `unable to inspect ${RUNTIME_ROOT}/runs (${reason})` };
+    }
+    const problems = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const runId = entry.name;
+        const runPath = path.join(runsDir, runId);
+        const relRunPath = `${RUNTIME_ROOT}/runs/${runId}`;
+        if (await exists(path.join(runPath, ".archive-in-progress"))) {
+            problems.push(`${relRunPath}/.archive-in-progress sentinel present`);
+        }
+        const manifestPath = path.join(runPath, "archive-manifest.json");
+        if (!(await exists(manifestPath))) {
+            problems.push(`${relRunPath} missing archive-manifest.json`);
+            continue;
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            problems.push(`${relRunPath}/archive-manifest.json unreadable (${reason})`);
+            continue;
+        }
+        const stateFiles = Array.isArray(manifest.snapshottedStateFiles)
+            ? manifest.snapshottedStateFiles.filter((value) => typeof value === "string")
+            : [];
+        const stateDir = path.join(runPath, "state");
+        if (stateFiles.length > 0 && !(await exists(stateDir))) {
+            problems.push(`${relRunPath} manifest lists state snapshot files but state/ is missing`);
+            continue;
+        }
+        for (const stateFile of stateFiles) {
+            if (stateFile.endsWith("/"))
+                continue;
+            if (!(await exists(path.join(stateDir, stateFile)))) {
+                problems.push(`${relRunPath}/state missing ${stateFile} listed in manifest`);
+            }
+        }
+    }
+    if (problems.length === 0) {
+        return { ok: true, details: "no partial archive sentinels or incomplete archive snapshots found" };
+    }
+    return {
+        ok: false,
+        details: `${problems.join("; ")}. Fix: inspect the archive directory, retry archive if the active run was restored, or recover/rollback artifacts and state from the snapshot before removing the sentinel.`
+    };
 }
 async function opencodePluginRuntimeShapeCheck(projectRoot) {
     const pluginPath = path.join(projectRoot, ".opencode/plugins/cclaw-plugin.mjs");
@@ -573,7 +706,6 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: agentsBlockOk,
         details: `${agentsFile} must contain the managed cclaw marker block with routing, verification, and minimal detail pointer`
     });
-    // User-facing entry commands only. Stage and view subcommands live in skills.
     for (const cmd of ["start", "next", "ideate", "view"]) {
         const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${cmd}.md`);
         checks.push({
@@ -582,6 +714,19 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: cmdPath
         });
     }
+    for (const stage of FLOW_STAGES) {
+        const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${stage}.md`);
+        let stageCommandOk = false;
+        if (await exists(cmdPath)) {
+            const content = await fs.readFile(cmdPath, "utf8");
+            stageCommandOk = content === stageCommandShimMarkdown(stage);
+        }
+        checks.push({
+            name: `stage_command:${stage}`,
+            ok: stageCommandOk,
+            details: `${cmdPath} must be a thin shim to ${RUNTIME_ROOT}/skills/${stageSkillFolder(stage)}/SKILL.md and /cc-next`
+        });
+    }
     // Utility skills
     for (const [folder, label] of [
         ["learnings", "learnings"],
@@ -848,7 +993,6 @@ export async function doctorChecks(projectRoot, options = {}) {
         const codexStopCmds = collectHookCommands(codexHooks.Stop);
         const codexWiringOk = codexSessionCmds.some((cmd) => cmd.includes("session-start")) &&
             codexUserPromptCmds.some((cmd) => cmd.includes("prompt-guard")) &&
-            codexUserPromptCmds.some((cmd) => cmd.includes("workflow-guard")) &&
             codexUserPromptCmds.some((cmd) => cmd.includes("verify-current-state")) &&
             codexPreCmds.some((cmd) => cmd.includes("prompt-guard")) &&
             codexPreCmds.some((cmd) => cmd.includes("workflow-guard")) &&
@@ -857,7 +1001,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         checks.push({
             name: "hook:wiring:codex",
             ok: codexWiringOk,
-            details: `${codexHooksFile} must wire SessionStart, UserPromptSubmit(prompt/workflow/verify-current-state), PreToolUse(prompt/workflow), PostToolUse(context-monitor), and Stop(stop-handoff). PreToolUse/PostToolUse run Bash-only in Codex v0.114+`
+            details: `${codexHooksFile} must wire SessionStart, UserPromptSubmit(prompt/verify-current-state), Bash-only PreToolUse(prompt/workflow), Bash-only PostToolUse(context-monitor), and Stop(stop-handoff). Codex workflow-guard is intentionally strict Bash-only.`
         });
         // Feature flag warning: Codex ignores `.codex/hooks.json` unless the
         // user has `[features] codex_hooks = true` in `~/.codex/config.toml`.
@@ -980,12 +1124,49 @@ export async function doctorChecks(projectRoot, options = {}) {
             ok: registration.ok,
             details: registration.details
         });
+        const questionPermission = await opencodeQuestionPermissionCheck(projectRoot);
+        checks.push({
+            name: "hook:opencode:question_permission",
+            ok: questionPermission.ok,
+            details: questionPermission.details
+        });
+        const questionEnv = opencodeQuestionEnvCheck();
+        checks.push({
+            name: "warning:opencode:question_tool_env",
+            ok: questionEnv.ok,
+            details: questionEnv.details
+        });
     }
-    const hasNode = await commandAvailable("node");
+    const nodeVersion = await commandVersion("node");
+    const nodeMajor = parseNodeMajor(nodeVersion.output);
     checks.push({
         name: "capability:required:node",
-        ok: hasNode,
-        details: "node is required for cclaw runtime scripts and CLI wiring"
+        ok: nodeVersion.available,
+        details: nodeVersion.available
+            ? `node binary available (${nodeVersion.output || "version unknown"})`
+            : "node is required for cclaw runtime scripts and CLI wiring"
+    });
+    checks.push({
+        name: "capability:required:node_version",
+        ok: nodeVersion.available && nodeMajor !== null && nodeMajor >= 20,
+        details: nodeVersion.available
+            ? `node >=20 required; detected ${nodeVersion.output || "unknown version"}`
+            : "node version check skipped because node binary is unavailable"
+    });
+    const gitVersion = await commandVersion("git");
+    checks.push({
+        name: "capability:required:git",
+        ok: gitVersion.available,
+        details: gitVersion.available
+            ? `git binary available (${gitVersion.output || "version unknown"})`
+            : "git is required for repository detection, hook setup, and doctor checks"
+    });
+    checks.push({
+        name: "capability:required:git_version",
+        ok: gitVersion.available && gitVersionLooksUsable(gitVersion.output),
+        details: gitVersion.available
+            ? `git version output: ${gitVersion.output || "unknown version"}`
+            : "git version check skipped because git binary is unavailable"
     });
     const windowsHookConfigCandidates = [
         path.join(projectRoot, ".claude/hooks/hooks.json"),
@@ -1083,12 +1264,7 @@ export async function doctorChecks(projectRoot, options = {}) {
                         const key = `${trigger} => ${action}`;
                         triggerActionCounts.set(key, (triggerActionCounts.get(key) ?? 0) + 1);
                     }
-                    const missing = requiredV2Fields.some((field) => {
-                        if (field === "origin_run" && Object.prototype.hasOwnProperty.call(parsed, "origin_feature")) {
-                            return false;
-                        }
-                        return !Object.prototype.hasOwnProperty.call(parsed, field);
-                    });
+                    const missing = requiredV2Fields.some((field) => !Object.prototype.hasOwnProperty.call(parsed, field));
                     if (missing) {
                         missingSchemaV2Fields += 1;
                     }
@@ -1388,17 +1564,17 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no stale stages pending acknowledgement"
             : `stale stages pending acknowledgement: ${staleStages.join(", ")}`
     });
-    const retroRequired = flowState.completedStages.includes("ship");
-    const retroComplete = !retroRequired ||
-        (typeof flowState.retro.completedAt === "string" && flowState.retro.compoundEntries > 0);
+    const retroGateStatus = await evaluateRetroGate(projectRoot, flowState);
     checks.push({
         name: "state:retro_gate",
-        ok: retroComplete,
-        details: retroComplete
-            ? retroRequired
-                ? `retro gate complete (${flowState.retro.compoundEntries} compound entries)`
+        ok: retroGateStatus.completed,
+        details: retroGateStatus.completed
+            ? retroGateStatus.required
+                ? retroGateStatus.skipped
+                    ? "retro gate complete (retro skipped with recorded closeout decision)"
+                    : `retro gate complete (${retroGateStatus.compoundEntries} compound entries)`
                 : "retro gate not required yet (ship not completed)"
-            : "retro gate incomplete: ship flow requires recorded retrospective evidence."
+            : "retro gate incomplete: ship flow requires recorded retrospective evidence or an explicit retro skip."
     });
     const tddLogPath = path.join(projectRoot, RUNTIME_ROOT, "state", "tdd-cycle-log.jsonl");
     const tddLogExists = await exists(tddLogPath);
@@ -1444,6 +1620,18 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs")),
         details: `${RUNTIME_ROOT}/runs must exist for archived run snapshots`
     });
+    const initRecovery = await initRecoveryCheck(projectRoot);
+    checks.push({
+        name: "state:init_recovery",
+        ok: initRecovery.ok,
+        details: initRecovery.details
+    });
+    const archiveIntegrity = await archiveIntegrityCheck(projectRoot);
+    checks.push({
+        name: "runs:archive_integrity",
+        ok: archiveIntegrity.ok,
+        details: archiveIntegrity.details
+    });
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage, {
         repairFeatureSystem: false
     });

package/dist/gate-evidence.js

@@ -336,11 +336,27 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
         if (stage === "design") {
             const researchGateRequired = schema.requiredGates.some((gate) => gate.id === "design_research_complete" && gate.tier === "required");
             if (researchGateRequired) {
+                const designMarkdown = await readArtifactMarkdown(projectRoot, "03-design.md");
+                const inlineResearchBody = designMarkdown
+                    ? extractMarkdownSectionBody(designMarkdown, "Research Fleet Synthesis")
+                    : null;
+                const inlineResearchLines = inlineResearchBody
+                    ? inlineResearchBody
+                        .split(/\r?\n/gu)
+                        .map((line) => line.trim())
+                        .filter((line) => line.length > 0)
+                        .filter((line) => !/^\|?(?:[-:\s|])+$/u.test(line))
+                        .filter((line) => !/\b(?:TODO|TBD|FIXME|pending)\b/iu.test(line) &&
+                        !/<fill-in>/iu.test(line) &&
+                        !/^>\s*Default path:/iu.test(line) &&
+                        !/^\|\s*compact inline synthesis\s*\|\s*\|\s*\|\s*\|?\s*$/iu.test(line))
+                    : [];
+                const inlineResearchComplete = inlineResearchLines.length > 0;
                 const researchMarkdown = await readArtifactMarkdown(projectRoot, "02a-research.md");
-                if (!researchMarkdown) {
-                    issues.push("design research gate blocked (design_research_complete): missing `.cclaw/artifacts/02a-research.md`.");
+                if (!inlineResearchComplete && !researchMarkdown) {
+                    issues.push("design research gate blocked (design_research_complete): fill `Research Fleet Synthesis` in `.cclaw/artifacts/03-design.md`, or write `.cclaw/artifacts/02a-research.md` for deep/high-risk research.");
                 }
-                else {
+                else if (researchMarkdown) {
                     const missingSections = [];
                     for (const section of DESIGN_RESEARCH_REQUIRED_SECTIONS) {
                         const body = extractMarkdownSectionBody(researchMarkdown, section);
@@ -353,10 +369,6 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                             .map((line) => line.trim())
                             .filter((line) => line.length > 0)
                             .filter((line) => !/^\|?(?:[-:\s|])+$/u.test(line));
-                        // `<fill-in>` needs its own check because `\b` does not match
-                        // around `<`/`>` (non-word characters), so the previous combined
-                        // pattern `\b(?:...|<fill-in>)\b` silently never matched placeholder
-                        // templates that used angle-bracket form.
                         const nonPlaceholder = meaningfulLines.filter((line) => !/\b(?:TODO|TBD|FIXME|pending)\b/iu.test(line) &&
                             !/<fill-in>/iu.test(line));
                         if (nonPlaceholder.length === 0) {

package/dist/harness-adapters.d.ts

@@ -1,19 +1,20 @@
-import type { HarnessId } from "./types.js";
+import { type HarnessId } from "./types.js";
 export declare const CCLAW_MARKER_START = "<!-- cclaw-start -->";
 export declare const CCLAW_MARKER_END = "<!-- cclaw-end -->";
 export type SubagentFallback = 
-/** Harness has real, isolated subagent dispatch; no fallback needed. */
+/** Harness has real, isolated named subagent dispatch; no fallback needed. */
 "native"
 /**
- * Harness has generic dispatch (e.g. Cursor's Task tool with
- * `subagent_type`) but not user-defined named subagents; cclaw maps each
- * named agent to the generic dispatcher with a structured role prompt.
+ * Harness has a real dispatcher but not cclaw-named agents. cclaw maps each
+ * named role to the available built-in/generic subagent surface with a
+ * structured role prompt.
  */
  | "generic-dispatch"
 /**
  * No isolated dispatch — the agent performs the named subagent's role
  * in-session with an explicit role announce + delegation-log entry
- * carrying evidenceRefs. Accepted as `completed` in delegation checks.
+ * carrying evidenceRefs. Accepted as `completed` only when no true dispatch
+ * surface exists.
  */
  | "role-switch"
 /**
@@ -50,11 +51,11 @@ export interface HarnessAdapter {
     capabilities: {
         /**
          * Level of native subagent dispatch:
-         * - `full`    — isolated workers + user-defined named subagents (Claude).
-         * - `generic` — generic dispatcher (Task) without named agents (Cursor).
-         * - `partial` — plugin-based dispatch, not a first-class primitive
-         *   (OpenCode).
-         * - `none`    — no dispatch primitive at all (Codex).
+         * - `full`    — isolated workers + user-defined named subagents (Claude,
+         *   OpenCode, Codex custom agents).
+         * - `generic` — generic dispatcher without cclaw-named agents (Cursor).
+         * - `partial` — limited or plugin-only dispatch surface.
+         * - `none`    — no dispatch primitive at all.
          */
         nativeSubagentDispatch: "full" | "generic" | "partial" | "none";
         hookSurface: "full" | "plugin" | "limited" | "none";
@@ -87,6 +88,8 @@ export declare function harnessShimFileNames(): string[];
 /** Skill folder names cclaw writes under `<commandDir>` for skill-kind harnesses. */
 export declare function harnessShimSkillNames(): string[];
 export declare const HARNESS_ADAPTERS: Record<HarnessId, HarnessAdapter>;
+export declare function harnessDispatchSurface(harnessId: HarnessId): string;
+export declare function harnessDispatchFallback(harnessId: HarnessId): string;
 export type HarnessTier = "tier1" | "tier2" | "tier3";
 export declare function harnessTier(harnessId: HarnessId): HarnessTier;
 /**