cclaw-cli 0.51.23 → 0.51.25

package/dist/doctor.js

@@ -24,6 +24,7 @@ import { resolveTrackFromPrompt } from "./track-heuristics.js";
 import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./content/utility-skills.js";
 import { validateHookDocument } from "./hook-schema.js";
+import { HOOK_EVENTS_BY_HARNESS } from "./content/hook-events.js";
 import { validateKnowledgeEntry } from "./knowledge-store.js";
 import { readSeedShelf } from "./content/seed-shelf.js";
 import { evaluateRetroGate } from "./retro-gate.js";
@@ -130,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);
@@ -295,8 +310,12 @@ function opencodeConfigCandidates(projectRoot) {
     return [
         path.join(projectRoot, "opencode.json"),
         path.join(projectRoot, "opencode.jsonc"),
+        path.join(projectRoot, "oh-my-opencode.jsonc"),
+        path.join(projectRoot, "oh-my-openagent.jsonc"),
         path.join(projectRoot, ".opencode/opencode.json"),
-        path.join(projectRoot, ".opencode/opencode.jsonc")
+        path.join(projectRoot, ".opencode/opencode.jsonc"),
+        path.join(projectRoot, ".opencode/oh-my-opencode.jsonc"),
+        path.join(projectRoot, ".opencode/oh-my-openagent.jsonc")
     ];
 }
 function openCodeConfigRegistersPlugin(parsed) {
@@ -360,6 +379,87 @@ function opencodeQuestionEnvCheck() {
         details: "Set OPENCODE_ENABLE_QUESTION_TOOL=1 for OpenCode ACP clients so permission-gated structured questions can use the question tool."
     };
 }
+function codexFlagInactiveDetail(configPath, state, error) {
+    if (state === "enabled") {
+        return `codex_hooks feature flag is enabled in ${configPath}; Codex hooks are active.`;
+    }
+    if (state === "read-error") {
+        return `Codex hooks are inactive: could not read ${configPath} (${error instanceof Error ? error.message : String(error)}).`;
+    }
+    if (state === "missing-file") {
+        return `Codex hooks are inactive: ${configPath} does not exist; .codex/hooks.json is ignored until [features] codex_hooks = true is configured.`;
+    }
+    if (state === "missing-section") {
+        return `Codex hooks are inactive: ${configPath} has no [features] section; add codex_hooks = true to activate configured hooks.`;
+    }
+    if (state === "missing-key") {
+        return `Codex hooks are inactive: ${configPath} is missing codex_hooks under [features]; add codex_hooks = true to activate configured hooks.`;
+    }
+    return `Codex hooks are inactive: ${configPath} sets codex_hooks to a non-true value; set codex_hooks = true under [features].`;
+}
+function hookCommandsWithMatchers(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    for (const item of value) {
+        const obj = toObject(item);
+        if (!obj)
+            continue;
+        const matcher = typeof obj.matcher === "string" ? obj.matcher : undefined;
+        if (typeof obj.command === "string") {
+            out.push({ command: obj.command, matcher });
+        }
+        const nested = hookCommandsWithMatchers(obj.hooks);
+        for (const child of nested) {
+            out.push({ ...child, matcher: child.matcher ?? matcher });
+        }
+    }
+    return out;
+}
+function commandHasHandler(entries, handler) {
+    return entries.some((entry) => entry.command.includes(`run-hook.cmd ${handler}`) || entry.command.includes(`run-hook.mjs ${handler}`));
+}
+function codexBashOnly(entries, handler) {
+    const matches = entries.filter((entry) => entry.command.includes(`run-hook.cmd ${handler}`) || entry.command.includes(`run-hook.mjs ${handler}`));
+    return matches.length > 0 && matches.every((entry) => entry.matcher === "Bash|bash");
+}
+function codexStructuralWiringCheck(codexHooks) {
+    const problems = [];
+    const expectedSession = HOOK_EVENTS_BY_HARNESS.codex.session_rehydrate;
+    if (expectedSession !== "SessionStart matcher=startup|resume") {
+        problems.push("semantic session_rehydrate mapping must remain SessionStart matcher=startup|resume");
+    }
+    const session = hookCommandsWithMatchers(codexHooks.SessionStart);
+    if (!commandHasHandler(session, "session-start") || !session.some((entry) => entry.matcher === "startup|resume")) {
+        problems.push("SessionStart must run session-start with matcher startup|resume");
+    }
+    const userPrompt = hookCommandsWithMatchers(codexHooks.UserPromptSubmit);
+    if (!commandHasHandler(userPrompt, "prompt-guard")) {
+        problems.push("UserPromptSubmit must run prompt-guard");
+    }
+    if (!commandHasHandler(userPrompt, "verify-current-state")) {
+        problems.push("UserPromptSubmit must run verify-current-state");
+    }
+    const pre = hookCommandsWithMatchers(codexHooks.PreToolUse);
+    if (!codexBashOnly(pre, "prompt-guard")) {
+        problems.push("PreToolUse prompt-guard must be Bash-only matcher Bash|bash");
+    }
+    if (!codexBashOnly(pre, "workflow-guard")) {
+        problems.push("PreToolUse workflow-guard must be Bash-only matcher Bash|bash");
+    }
+    const post = hookCommandsWithMatchers(codexHooks.PostToolUse);
+    if (!codexBashOnly(post, "context-monitor")) {
+        problems.push("PostToolUse context-monitor must be Bash-only matcher Bash|bash");
+    }
+    const stop = hookCommandsWithMatchers(codexHooks.Stop);
+    if (!commandHasHandler(stop, "stop-handoff")) {
+        problems.push("Stop must run stop-handoff");
+    }
+    return problems.length === 0
+        ? { ok: true, details: "Codex hook events, matchers, and manifest semantic mappings are structurally valid" }
+        : { ok: false, details: problems.join("; ") };
+}
 async function initRecoveryCheck(projectRoot) {
     const sentinelPath = path.join(projectRoot, RUNTIME_ROOT, "state", ".init-in-progress");
     if (!(await exists(sentinelPath))) {
@@ -1003,34 +1103,48 @@ export async function doctorChecks(projectRoot, options = {}) {
             ok: codexWiringOk,
             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`.
-        // Advisory warning — not a hard failure, because the skills still
-        // work without the flag.
+        const codexStructural = codexStructuralWiringCheck(codexHooks);
+        checks.push({
+            name: "hook:wiring:codex:structure",
+            ok: codexStructural.ok,
+            details: codexStructural.details
+        });
+        // Codex ignores `.codex/hooks.json` unless the user has
+        // `[features] codex_hooks = true` in `~/.codex/config.toml`.
         const codexConfig = codexConfigPath();
-        let featureFlagNote = "";
+        let codexFlagState = "read-error";
+        let codexFlagReadError;
         try {
             const content = await readCodexConfig(codexConfig);
-            const state = classifyCodexHooksFlag(content);
-            featureFlagNote =
-                state === "enabled"
-                    ? `codex_hooks feature flag is enabled in ${codexConfig}`
-                    : state === "missing-file"
-                        ? `warning: ${codexConfig} does not exist; .codex/hooks.json will be ignored until you create it with \`[features]\\ncodex_hooks = true\\n\`.`
-                        : state === "missing-section"
-                            ? `warning: ${codexConfig} has no [features] section; add \`[features]\\ncodex_hooks = true\\n\` to enable cclaw hooks.`
-                            : state === "missing-key"
-                                ? `warning: ${codexConfig} is missing the codex_hooks key under [features]. Add \`codex_hooks = true\` to enable cclaw hooks.`
-                                : `warning: ${codexConfig} sets codex_hooks to a non-true value; set \`codex_hooks = true\` under [features] to enable cclaw hooks.`;
+            codexFlagState = classifyCodexHooksFlag(content);
         }
         catch (err) {
-            featureFlagNote = `warning: could not read ${codexConfig}: ${err instanceof Error ? err.message : String(err)}`;
+            codexFlagReadError = err;
         }
+        const featureFlagNote = codexFlagInactiveDetail(codexConfig, codexFlagState, codexFlagReadError);
+        const featureFlagOk = codexFlagState === "enabled";
         checks.push({
             name: "warning:codex:feature_flag",
-            ok: true,
-            details: featureFlagNote
+            ok: featureFlagOk,
+            details: featureFlagNote,
+            summary: featureFlagOk
+                ? "Codex hooks are active."
+                : "Codex hooks are inactive; configured hooks will be ignored.",
+            fix: "Set `[features] codex_hooks = true` in the Codex config or run cclaw init/sync with Codex flag repair.",
+            docRef: "docs/harnesses.md"
         });
+        if (parsedConfig?.strictness === "strict") {
+            checks.push({
+                name: "hook:codex:feature_flag_active",
+                ok: featureFlagOk,
+                details: featureFlagNote,
+                summary: featureFlagOk
+                    ? "Codex hooks are active for strict runtime enforcement."
+                    : "Codex hooks are inactive; strict Codex hook enforcement is not ready.",
+                fix: "Set `[features] codex_hooks = true` in the Codex config so strict Codex hooks can run.",
+                docRef: "docs/harnesses.md"
+            });
+        }
         // Legacy `.codex/commands/*` must not linger from older cclaw installs.
         // (The `.codex/hooks.json` path is now managed and is validated above,
         // so there is no longer a legacy_hooks_json warning.)
@@ -1530,13 +1644,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;
@@ -1544,9 +1666,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({
@@ -1556,13 +1682,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({
@@ -1632,18 +1765,27 @@ 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 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}`
     });
     checks.push({
         name: "warning:delegation:waived",

package/dist/flow-state.d.ts

@@ -63,6 +63,7 @@ export interface CloseoutState {
     retroSkipReason?: string;
     compoundCompletedAt?: string;
     compoundSkipped?: boolean;
+    compoundSkipReason?: string;
     compoundPromoted: number;
 }
 export declare function createInitialCloseoutState(): CloseoutState;

package/dist/flow-state.js

@@ -42,6 +42,7 @@ export function createInitialCloseoutState() {
         retroSkipReason: undefined,
         compoundCompletedAt: undefined,
         compoundSkipped: undefined,
+        compoundSkipReason: undefined,
         compoundPromoted: 0
     };
 }

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/install.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";
@@ -191,15 +192,84 @@ function resolveRepoRoot() {
   return process.cwd();
 }
 
+function isZeroSha(value) {
+  return /^0{40,64}$/u.test(value);
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function uniqueLines(chunks) {
+  return [...new Set(chunks
+    .join("\n")
+    .split(/\r?\n/gu)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0))].join("\n");
+}
+
+function diffNames(root, range) {
+  const result = runGit(["diff", "--name-only", range], root);
+  return result.status === 0 ? result.stdout : "";
+}
+
+function changedFilesFromUnpushedCommits(root, localSha = "HEAD") {
+  const revList = runGit(["rev-list", "--reverse", localSha, "--not", "--remotes"], root);
+  if (revList.status !== 0 || revList.stdout.trim().length === 0) {
+    return "";
+  }
+  const chunks = [];
+  for (const commit of revList.stdout.split(/\r?\n/gu).map((line) => line.trim()).filter(Boolean)) {
+    const diffTree = runGit(["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", commit], root);
+    if (diffTree.status === 0) chunks.push(diffTree.stdout);
+  }
+  return uniqueLines(chunks);
+}
+
+function changedFilesFromPrePushStdin(root, stdin) {
+  const chunks = [];
+  for (const rawLine of stdin.split(/\r?\n/gu)) {
+    const parts = rawLine.trim().split(/\s+/u);
+    if (parts.length < 4) continue;
+    const [localRef, localSha, remoteRef, remoteSha] = parts;
+    void localRef;
+    void remoteRef;
+    if (!localSha || isZeroSha(localSha)) continue;
+    if (remoteSha && !isZeroSha(remoteSha)) {
+      chunks.push(diffNames(root, remoteSha + ".." + localSha));
+      continue;
+    }
+    const upstream = runGit(["rev-parse", "--verify", "--quiet", "@{upstream}"], root);
+    if (upstream.status === 0 && upstream.stdout.trim().length > 0) {
+      chunks.push(diffNames(root, upstream.stdout.trim() + ".." + localSha));
+      continue;
+    }
+    chunks.push(changedFilesFromUnpushedCommits(root, localSha));
+  }
+  return uniqueLines(chunks);
+}
+
 function resolveChangedFiles(root) {
   if (HOOK_NAME === "pre-commit") {
     const result = runGit(["diff", "--cached", "--name-only"], root);
     return result.status === 0 ? result.stdout : "";
   }
-  const upstreamResult = runGit(["diff", "--name-only", "@{upstream}...HEAD"], root);
+  const stdinChanged = changedFilesFromPrePushStdin(root, readStdin());
+  if (stdinChanged.length > 0) {
+    return stdinChanged;
+  }
+  const upstreamResult = runGit(["diff", "--name-only", "@{upstream}..HEAD"], root);
   if (upstreamResult.status === 0) {
     return upstreamResult.stdout;
   }
+  const unpushed = changedFilesFromUnpushedCommits(root);
+  if (unpushed.length > 0) {
+    return unpushed;
+  }
   const fallback = runGit(["diff", "--name-only", "HEAD~1...HEAD"], root);
   return fallback.status === 0 ? fallback.stdout : "";
 }
@@ -1270,13 +1340,7 @@ export async function uninstallCclaw(projectRoot) {
     }
     await removeIfEmpty(codexSkillsRoot);
     await removeIfEmpty(path.join(projectRoot, ".agents"));
-    const managedAgentNames = [
-        "planner",
-        "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`));