cclaw-cli 0.51.24 → 0.51.26

package/dist/doctor.js

@@ -13,7 +13,7 @@ import { policyChecks } from "./policy.js";
 import { CorruptFlowStateError, readFlowState } from "./runs.js";
 import { createInitialFlowState, skippedStagesForTrack } from "./flow-state.js";
 import { FLOW_STAGES, TRACK_STAGES } from "./types.js";
-import { checkMandatoryDelegations } from "./delegation.js";
+import { checkMandatoryDelegations, readDelegationEvents } from "./delegation.js";
 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";
@@ -131,6 +131,20 @@ async function generatedCliEntrypointsOk(projectRoot) {
             : "local CLI entrypoint check skipped because generated hook scripts are absent"
     };
 }
+function expectedArtifactPrefix(stage) {
+    const index = FLOW_STAGES.indexOf(stage);
+    return `${String(index + 1).padStart(2, "0")}-`;
+}
+function artifactStageFromFileName(fileName) {
+    if (!fileName.endsWith(".md"))
+        return null;
+    for (const stage of FLOW_STAGES) {
+        if (fileName.startsWith(expectedArtifactPrefix(stage))) {
+            return stage;
+        }
+    }
+    return null;
+}
 function extractUserPromptFromIdeaArtifact(markdown) {
     const normalized = markdown.replace(/\r\n?/gu, "\n");
     const heading = /^##\s+User prompt\s*$/imu.exec(normalized);
@@ -291,6 +305,20 @@ function normalizeOpenCodePluginEntry(entry) {
     }
     return null;
 }
+function generatedAgentShape(content, kind, agentName) {
+    if (kind === "opencode") {
+        return content.includes("mode: subagent") && content.includes(`# ${agentName}`) && content.includes("STRICT_RETURN_SCHEMA");
+    }
+    return content.includes(`name = "${agentName}"`) && content.includes("developer_instructions") && content.includes("STRICT_RETURN_SCHEMA");
+}
+function harnessRealityLabel(harness) {
+    const adapter = HARNESS_ADAPTERS[harness];
+    const declaredSupport = adapter.capabilities.nativeSubagentDispatch;
+    const runtimeLaunch = harness === "opencode" || harness === "codex" ? "prompt-level launch" : declaredSupport === "generic" ? "generic Task launch" : "native tool launch";
+    const proofRequired = adapter.capabilities.subagentFallback === "native" ? "dispatchId+spanId+ack" : "evidenceRefs";
+    const proofSource = harness === "opencode" ? ".opencode/agents + delegation-events.jsonl" : harness === "codex" ? ".codex/agents + delegation-events.jsonl" : ".cclaw/state/delegation-log.json";
+    return `declaredSupport=${declaredSupport}; runtimeLaunch=${runtimeLaunch}; proofRequired=${proofRequired}; proofSource=${proofSource}`;
+}
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 function opencodeConfigCandidates(projectRoot) {
     return [
@@ -766,6 +794,14 @@ export async function doctorChecks(projectRoot, options = {}) {
             }
         }
     }
+    for (const harness of configuredHarnesses) {
+        checks.push({
+            name: `harness:reality:${harness}`,
+            ok: true,
+            severity: "info",
+            details: harnessRealityLabel(harness)
+        });
+    }
     const agentsFile = path.join(projectRoot, "AGENTS.md");
     let agentsBlockOk = false;
     if (await exists(agentsFile)) {
@@ -870,12 +906,39 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: agentPath
         });
     }
+    for (const agent of CCLAW_AGENTS) {
+        if (configuredHarnesses.includes("opencode")) {
+            const agentPath = path.join(projectRoot, ".opencode", "agents", `${agent.name}.md`);
+            let ok = false;
+            if (await exists(agentPath)) {
+                ok = generatedAgentShape(await fs.readFile(agentPath, "utf8"), "opencode", agent.name);
+            }
+            checks.push({
+                name: `agent:opencode:${agent.name}:shape`,
+                ok,
+                details: `${agentPath} must be a generated OpenCode subagent with mode: subagent and strict return schema`
+            });
+        }
+        if (configuredHarnesses.includes("codex")) {
+            const agentPath = path.join(projectRoot, ".codex", "agents", `${agent.name}.toml`);
+            let ok = false;
+            if (await exists(agentPath)) {
+                ok = generatedAgentShape(await fs.readFile(agentPath, "utf8"), "codex", agent.name);
+            }
+            checks.push({
+                name: `agent:codex:${agent.name}:shape`,
+                ok,
+                details: `${agentPath} must be a generated Codex custom agent TOML with developer_instructions and strict return schema`
+            });
+        }
+    }
     // Hook scripts
     for (const script of [
         "run-hook.mjs",
         "run-hook.cmd",
         "stage-complete.mjs",
         "start-flow.mjs",
+        "delegation-record.mjs",
         "opencode-plugin.mjs"
     ]) {
         const scriptPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", script);
@@ -1630,13 +1693,21 @@ export async function doctorChecks(projectRoot, options = {}) {
     });
     const artifactsRoot = path.join(projectRoot, RUNTIME_ROOT, "artifacts");
     let artifactPlaceholderHits = [];
+    let duplicateArtifactGroups = [];
     if (await exists(artifactsRoot)) {
         try {
             const entries = await fs.readdir(artifactsRoot, { withFileTypes: true });
             const placeholderPattern = /\b(?:TODO|TBD|FIXME)\b|<fill-in>|<your-.*-here>/giu;
+            const stageArtifactFiles = new Map();
             for (const entry of entries) {
                 if (!entry.isFile() || !entry.name.endsWith(".md"))
                     continue;
+                const stageForArtifact = artifactStageFromFileName(entry.name);
+                if (stageForArtifact) {
+                    const files = stageArtifactFiles.get(stageForArtifact) ?? [];
+                    files.push(entry.name);
+                    stageArtifactFiles.set(stageForArtifact, files);
+                }
                 const filePath = path.join(artifactsRoot, entry.name);
                 const content = await fs.readFile(filePath, "utf8");
                 const matchCount = (content.match(placeholderPattern) ?? []).length;
@@ -1644,9 +1715,13 @@ export async function doctorChecks(projectRoot, options = {}) {
                     artifactPlaceholderHits.push(`${entry.name}:${matchCount}`);
                 }
             }
+            duplicateArtifactGroups = [...stageArtifactFiles.entries()]
+                .filter(([, files]) => files.length > 1)
+                .map(([stageName, files]) => `${stageName}: ${files.sort().join(", ")}`);
         }
         catch {
             artifactPlaceholderHits = [];
+            duplicateArtifactGroups = [];
         }
     }
     checks.push({
@@ -1656,13 +1731,20 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no TODO/TBD/FIXME placeholder markers found in active artifacts"
             : `warning: placeholder markers detected in active artifacts (${artifactPlaceholderHits.join(", ")}). Clear before marking completion.`
     });
+    checks.push({
+        name: "warning:artifacts:duplicate_stage_artifacts",
+        ok: duplicateArtifactGroups.length === 0,
+        details: duplicateArtifactGroups.length === 0
+            ? "no duplicate stage artifacts detected in active artifacts"
+            : `warning: duplicate stage artifacts detected (${duplicateArtifactGroups.join("; ")}). The resolver uses the newest matching file; archive or rename stale copies to avoid ambiguous operator handoff.`
+    });
     const staleStages = Object.keys(flowState.staleStages).filter((value) => FLOW_STAGES.includes(value));
     checks.push({
         name: "state:stale_stages_resolved",
         ok: staleStages.length === 0,
         details: staleStages.length === 0
             ? "no stale stages pending acknowledgement"
-            : `stale stages pending acknowledgement: ${staleStages.join(", ")}`
+            : `stale stages pending acknowledgement: ${staleStages.join(", ")}. Re-run the current stale stage, then clear it with cclaw internal rewind --ack ${flowState.currentStage}.`
     });
     const retroGateStatus = await evaluateRetroGate(projectRoot, flowState);
     checks.push({
@@ -1732,18 +1814,51 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: archiveIntegrity.ok,
         details: archiveIntegrity.details
     });
+    const currentGateState = flowState.stageGateCatalog[flowState.currentStage];
+    const currentStageUntouched = flowState.completedStages.length === 0 &&
+        flowState.rewinds.length === 0 &&
+        Object.keys(flowState.guardEvidence).length === 0 &&
+        (currentGateState?.passed.length ?? 0) === 0 &&
+        (currentGateState?.blocked.length ?? 0) === 0;
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage, {
         repairFeatureSystem: false
     });
+    const delegationEvents = await readDelegationEvents(projectRoot);
+    const delegationSatisfiedForDoctor = currentStageUntouched || delegation.satisfied;
     const missingEvidenceNote = delegation.missingEvidence && delegation.missingEvidence.length > 0
         ? ` (role-switch rows without evidenceRefs: ${delegation.missingEvidence.join(", ")})`
         : "";
     checks.push({
         name: "delegation:mandatory:current_stage",
-        ok: delegation.satisfied,
-        details: delegation.satisfied
-            ? `All mandatory delegations satisfied for stage "${flowState.currentStage}" (mode: ${delegation.expectedMode})`
-            : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}`
+        ok: delegationSatisfiedForDoctor,
+        details: currentStageUntouched
+            ? `mandatory delegation check deferred for untouched stage "${flowState.currentStage}"; stage-complete enforces it when work begins`
+            : delegation.satisfied
+                ? `All mandatory delegations satisfied for stage "${flowState.currentStage}" (mode: ${delegation.expectedMode})`
+                : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}; missingDispatchProof=${delegation.missingDispatchProof.join(", ")}; staleWorkers=${delegation.staleWorkers.join(", ")}; corruptEventLines=${delegation.corruptEventLines.join(", ")}`
+    });
+    checks.push({
+        name: "delegation:events:parse",
+        ok: delegationEvents.corruptLines.length === 0,
+        details: delegationEvents.corruptLines.length === 0
+            ? `${RUNTIME_ROOT}/state/delegation-events.jsonl parsed successfully (${delegationEvents.events.length} event(s))`
+            : `corrupt delegation event line(s): ${delegationEvents.corruptLines.join(", ")}`
+    });
+    checks.push({
+        name: "delegation:proof:current_stage",
+        ok: currentStageUntouched || delegation.missingDispatchProof.length === 0,
+        details: currentStageUntouched
+            ? `dispatch proof check deferred for untouched stage "${flowState.currentStage}"`
+            : delegation.missingDispatchProof.length === 0
+                ? `no dispatch proof gaps for current stage "${flowState.currentStage}"`
+                : `isolated completions missing dispatchId/dispatchSurface/agentDefinitionPath/ackTs/completedTs: ${delegation.missingDispatchProof.join(", ")}`
+    });
+    checks.push({
+        name: "warning:delegation:legacy_inferred_completions",
+        ok: true,
+        details: delegation.legacyInferredCompletions.length > 0
+            ? `warning: legacy inferred isolated completion rows lack event-log proof: ${delegation.legacyInferredCompletions.join(", ")}`
+            : "no legacy inferred isolated completions for current stage"
     });
     checks.push({
         name: "warning:delegation:waived",

package/dist/gate-evidence.js

@@ -9,6 +9,7 @@ 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 { validateTddVerificationEvidence } from "./tdd-verification-evidence.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { FLOW_STAGES } from "./types.js";
 async function currentStageArtifactExists(projectRoot, stage, track) {
@@ -36,6 +37,22 @@ async function readArtifactMarkdown(projectRoot, artifactFile) {
     }
     return null;
 }
+async function readStageArtifactMarkdown(projectRoot, stage, track) {
+    const resolved = await resolveArtifactPath(stage, {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    if (!(await exists(resolved.absPath))) {
+        return null;
+    }
+    try {
+        return await fs.readFile(resolved.absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
 function unique(values) {
     return [...new Set(values)];
 }
@@ -263,6 +280,12 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             issues.push(`passed gate "${gateId}" is missing guardEvidence entry.`);
             continue;
         }
+        if (stage === "tdd" && gateId === "tdd_verified_before_complete") {
+            const verification = await validateTddVerificationEvidence(projectRoot, evidence);
+            if (!verification.ok) {
+                issues.push(`tdd verification gate blocked (${gateId}): ${verification.issues.join(" ")}`);
+            }
+        }
         const discoveredCommandIssue = await verifyDiscoveredCommandEvidence(projectRoot, stage, gateId, flowState);
         if (discoveredCommandIssue) {
             issues.push(discoveredCommandIssue);
@@ -336,7 +359,7 @@ 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 designMarkdown = await readStageArtifactMarkdown(projectRoot, "design", flowState.track);
                 const inlineResearchBody = designMarkdown
                     ? extractMarkdownSectionBody(designMarkdown, "Research Fleet Synthesis")
                     : null;
@@ -354,7 +377,7 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                 const inlineResearchComplete = inlineResearchLines.length > 0;
                 const researchMarkdown = await readArtifactMarkdown(projectRoot, "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.");
+                    issues.push("design research gate blocked (design_research_complete): fill `Research Fleet Synthesis` in the active design artifact, or write `.cclaw/artifacts/02a-research.md` for deep/high-risk research.");
                 }
                 else if (researchMarkdown) {
                     const missingSections = [];

package/dist/harness-adapters.d.ts

@@ -37,6 +37,12 @@ export type SubagentFallback =
 export type ShimKind = "command" | "skill";
 export interface HarnessAdapter {
     id: HarnessId;
+    reality: {
+        declaredSupport: "full" | "generic" | "partial" | "none";
+        runtimeLaunch: string;
+        proofRequired: string;
+        proofSource: string;
+    };
     /**
      * Root directory where cclaw writes `/cc*` entry points.
      *

package/dist/harness-adapters.js

@@ -71,6 +71,12 @@ export function harnessShimSkillNames() {
 export const HARNESS_ADAPTERS = {
     claude: {
         id: "claude",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "native Task launch",
+            proofRequired: "spanId+dispatchId or workerRunId+ACK for isolated completion",
+            proofSource: ".cclaw/state/delegation-events.jsonl plus delegation-log.json"
+        },
         commandDir: ".claude/commands",
         shimKind: "command",
         capabilities: {
@@ -82,6 +88,12 @@ export const HARNESS_ADAPTERS = {
     },
     cursor: {
         id: "cursor",
+        reality: {
+            declaredSupport: "generic",
+            runtimeLaunch: "generic Task/Subagent launch with cclaw role prompt",
+            proofRequired: "spanId+dispatchId/evidenceRefs for generic-dispatch completion",
+            proofSource: ".cclaw/state/delegation-events.jsonl plus artifact evidenceRefs"
+        },
         commandDir: ".cursor/commands",
         shimKind: "command",
         capabilities: {
@@ -97,6 +109,12 @@ export const HARNESS_ADAPTERS = {
     },
     opencode: {
         id: "opencode",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "prompt-level launch via Task or @agent against generated .opencode/agents",
+            proofRequired: "spanId+dispatchId+ackTs+completedTs before isolated completion",
+            proofSource: ".opencode/agents/<agent>.md and .cclaw/state/delegation-events.jsonl"
+        },
         commandDir: ".opencode/commands",
         shimKind: "command",
         capabilities: {
@@ -119,6 +137,12 @@ export const HARNESS_ADAPTERS = {
     },
     codex: {
         id: "codex",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "prompt-level launch by asking Codex to spawn generated custom agents",
+            proofRequired: "spanId+dispatchId+ackTs+completedTs before isolated completion",
+            proofSource: ".codex/agents/<agent>.toml and .cclaw/state/delegation-events.jsonl"
+        },
         // Codex CLI reads skills from the universal `.agents/skills/` path
         // (OpenAI Codex 0.89, Jan 2026). It does NOT have a native
         // `.codex/commands/*` slash-command discovery — cclaw installs
@@ -155,9 +179,9 @@ export function harnessDispatchSurface(harnessId) {
         case "cursor":
             return "Use Cursor Subagent/Task with a generic subagent_type (explore for read-only mapping, generalPurpose for broader work, shell/browser-use when specifically needed) and paste the cclaw role prompt; record fulfillmentMode: \"generic-dispatch\" with evidenceRefs.";
         case "opencode":
-            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>, run independent agents in parallel when safe, then record fulfillmentMode: \"isolated\".";
+            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
         case "codex":
-            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name, wait for all results, then record fulfillmentMode: \"isolated\".";
+            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
     }
 }
 export function harnessDispatchFallback(harnessId) {
@@ -597,7 +621,7 @@ async function cleanupLegacyCodexSurfaces(projectRoot) {
     }
 }
 function codexAgentToml(agent) {
-    const instructions = `${agent.body}\n\n${enhancedAgentInstruction(agent.name)}`.trim();
+    const instructions = `${agentMarkdown(agent)}\n\n${enhancedAgentInstruction(agent.name)}`.trim();
     const sandboxMode = agent.tools.some((tool) => ["Write", "Edit", "Bash"].includes(tool))
         ? "workspace-write"
         : "read-only";
@@ -625,7 +649,7 @@ permission:
 ${agentMarkdown(agent)}`;
 }
 function enhancedAgentInstruction(agentName) {
-    return `You are the cclaw ${agentName} subagent. Follow the parent prompt as the task boundary, produce evidence suitable for .cclaw/state/delegation-log.json, and do not recursively orchestrate other agents unless the parent explicitly asks.`;
+    return `## Worker ACK Contract\n\nYou are the cclaw ${agentName} subagent. Follow the parent prompt as the task boundary. ACK first with JSON containing spanId, dispatchId or workerRunId, dispatchSurface, agentDefinitionPath, ackTs, and status: "ACK". Finish with the strict return schema plus the same spanId+dispatchId proof so the parent can append .cclaw/state/delegation-events.jsonl and .cclaw/state/delegation-log.json. Do not let the parent claim isolated completion without matching ACK/result proof. Do not recursively orchestrate other agents unless the parent explicitly asks.`;
 }
 async function syncAgentFiles(projectRoot, harnesses) {
     const agentsDir = path.join(projectRoot, RUNTIME_ROOT, "agents");

package/dist/install.js

@@ -13,7 +13,7 @@ import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-co
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
-import { stageCompleteScript, startFlowScript, runHookCmdScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { stageCompleteScript, startFlowScript, runHookCmdScript, delegationRecordScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
@@ -23,6 +23,7 @@ import { stageSkillFolder, stageSkillMarkdown } from "./content/skills.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LANGUAGE_RULE_PACK_GENERATORS, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./content/utility-skills.js";
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { SUBAGENT_CONTEXT_SKILLS } from "./content/subagent-context-skills.js";
+import { CCLAW_AGENTS } from "./content/core-agents.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
@@ -883,6 +884,7 @@ async function writeHooks(projectRoot, config) {
         compoundRecurrenceThreshold: config.compound?.recurrenceThreshold
     }));
     await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookCmdScript());
+    await writeFileSafe(path.join(hooksDir, "delegation-record.mjs"), delegationRecordScript());
     const opencodePluginSource = opencodePluginJs();
     await writeFileSafe(path.join(hooksDir, "opencode-plugin.mjs"), opencodePluginSource);
     try {
@@ -891,6 +893,7 @@ async function writeHooks(projectRoot, config) {
             "start-flow.mjs",
             "run-hook.mjs",
             "run-hook.cmd",
+            "delegation-record.mjs",
             "opencode-plugin.mjs"
         ]) {
             await fs.chmod(path.join(hooksDir, script), 0o755);
@@ -1339,15 +1342,7 @@ export async function uninstallCclaw(projectRoot) {
     }
     await removeIfEmpty(codexSkillsRoot);
     await removeIfEmpty(path.join(projectRoot, ".agents"));
-    const managedAgentNames = [
-        "planner",
-        "product-manager",
-        "critic",
-        "reviewer",
-        "security-reviewer",
-        "test-author",
-        "doc-updater"
-    ];
+    const managedAgentNames = CCLAW_AGENTS.map((agent) => agent.name);
     for (const agentName of managedAgentNames) {
         await removeBestEffort(path.join(projectRoot, ".opencode/agents", `${agentName}.md`));
         await removeBestEffort(path.join(projectRoot, ".codex/agents", `${agentName}.toml`));