cclaw-cli 0.51.29 → 0.55.2

package/dist/install.js

@@ -5,17 +5,15 @@ import { promisify } from "node:util";
 import { CCLAW_VERSION, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { writeConfig, createDefaultConfig, readConfig, configPath, detectLanguageRulePacks, detectAdvancedKeys } from "./config.js";
 import { learnSkillMarkdown } from "./content/learnings.js";
-import { nextCommandContract, nextCommandSkillMarkdown } from "./content/next-command.js";
 import { stageCommandShimMarkdown } from "./content/stage-command.js";
-import { ideateCommandContract, ideateCommandSkillMarkdown } from "./content/ideate-command.js";
+import { ideaCommandContract, ideaCommandSkillMarkdown } from "./content/idea-command.js";
 import { startCommandContract, startCommandSkillMarkdown } from "./content/start-command.js";
 import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-command.js";
-import { finishCommandContract, finishCommandSkillMarkdown } from "./content/finish-command.js";
 import { cancelCommandContract, cancelCommandSkillMarkdown } from "./content/cancel-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
-import { stageCompleteScript, startFlowScript, runHookCmdScript, delegationRecordScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { stageCompleteScript, startFlowScript, cancelRunScript, 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";
@@ -30,10 +28,11 @@ import { createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ManagedResourceSession, setActiveManagedResourceSession } from "./managed-resources.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
-import { HARNESS_ADAPTERS, harnessShimFileNames, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
+import { HARNESS_ADAPTERS, harnessShimFileNames, harnessShimSkillNames, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
 import { validateHookDocument } from "./hook-schema.js";
 import { detectHarnesses } from "./init-detect.js";
-import { ensureRunSystem } from "./runs.js";
+import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
+import { CorruptFlowStateError, ensureRunSystem } from "./runs.js";
 import { FLOW_STAGES } from "./types.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
@@ -50,6 +49,23 @@ async function writeInitSentinel(projectRoot, operation) {
     await writeFileSafe(sentinelPath, `${JSON.stringify({ operation, startedAt: new Date().toISOString() }, null, 2)}\n`);
     return sentinelPath;
 }
+async function warnStaleInitSentinel(projectRoot, operation) {
+    const sentinelPath = runtimePath(projectRoot, "state", INIT_SENTINEL_FILE);
+    if (!(await exists(sentinelPath)))
+        return;
+    let startedAt = "unknown time";
+    try {
+        const raw = await fs.readFile(sentinelPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.startedAt === "string" && parsed.startedAt.trim().length > 0) {
+            startedAt = parsed.startedAt;
+        }
+    }
+    catch {
+        // best-effort parse of stale sentinel metadata
+    }
+    process.stderr.write(`[${operation}] Detected stale .init-in-progress sentinel from ${startedAt}; previous run may have crashed. Continuing.\n`);
+}
 async function removeBestEffort(targetPath, recursive = false) {
     try {
         await fs.rm(targetPath, { recursive, force: true });
@@ -90,6 +106,16 @@ const DEPRECATED_UTILITY_SKILL_FOLDERS = [
     "flow-tree",
     "flow-diff"
 ];
+const DEPRECATED_STAGE_SKILL_FOLDERS = [
+    "brainstorming",
+    "scope-shaping",
+    "engineering-design-lock",
+    "specification-authoring",
+    "planning-and-task-breakdown",
+    "test-driven-development",
+    "two-layer-review",
+    "shipping-and-handoff"
+];
 const DEPRECATED_AGENT_FILES = [
     "securityer.md",
     "spec-reviewer.md",
@@ -102,6 +128,7 @@ const DEPRECATED_AGENT_FILES = [
 ];
 const DEPRECATED_COMMAND_FILES = [
     "learn.md",
+    "finish.md",
     "status.md",
     "tree.md",
     "diff.md",
@@ -114,6 +141,7 @@ const DEPRECATED_COMMAND_FILES = [
     "rewind.md"
 ];
 const DEPRECATED_SKILL_FILES = [
+    ["flow-finish", "SKILL.md"],
     ["flow-ops", "SKILL.md"],
     ["tdd-cycle-log", "SKILL.md"],
     ["flow-retro", "SKILL.md"],
@@ -450,11 +478,9 @@ async function writeSkills(projectRoot, config) {
     }
     // Utility skills (not flow stages)
     await writeFileSafe(runtimePath(projectRoot, "skills", "learnings", "SKILL.md"), learnSkillMarkdown());
-    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-next-step", "SKILL.md"), nextCommandSkillMarkdown());
-    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-ideate", "SKILL.md"), ideateCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-idea", "SKILL.md"), ideaCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-start", "SKILL.md"), startCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-view", "SKILL.md"), viewCommandSkillMarkdown());
-    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-finish", "SKILL.md"), finishCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-cancel", "SKILL.md"), cancelCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "subagent-dev", "SKILL.md"), subagentDrivenDevSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "parallel-dispatch", "SKILL.md"), parallelAgentsSkill());
@@ -516,10 +542,8 @@ async function writeSkills(projectRoot, config) {
 }
 async function writeEntryCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "start.md"), startCommandContract());
-    await writeFileSafe(runtimePath(projectRoot, "commands", "next.md"), nextCommandContract());
-    await writeFileSafe(runtimePath(projectRoot, "commands", "ideate.md"), ideateCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "idea.md"), ideaCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "view.md"), viewCommandContract());
-    await writeFileSafe(runtimePath(projectRoot, "commands", "finish.md"), finishCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "cancel.md"), cancelCommandContract());
     for (const stage of FLOW_STAGES) {
         await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), stageCommandShimMarkdown(stage));
@@ -859,14 +883,16 @@ async function writeMergedHookJson(projectRoot, hookFilePath, generatedJson) {
     if (harness) {
         const generatedSchema = validateHookDocument(harness, generatedDoc);
         if (!generatedSchema.ok) {
-            throw new Error(`Generated ${harness} hook document failed schema validation: ${generatedSchema.errors.join("; ")}`);
+            throw new Error(`[sync fail-fast] Hook document drift detected for ${harness}: generated hook document is invalid (${generatedSchema.errors.join("; ")}). ` +
+                "Run `npx cclaw-cli sync` to regenerate managed hooks or repair the generated hook shape manually.");
         }
     }
     const mergedDoc = mergeHookDocuments(existingDoc, generatedDoc);
     if (harness) {
         const mergedSchema = validateHookDocument(harness, mergedDoc);
         if (!mergedSchema.ok) {
-            throw new Error(`Merged ${harness} hook document failed schema validation: ${mergedSchema.errors.join("; ")}`);
+            throw new Error(`[sync fail-fast] Hook document drift detected for ${harness}: merged hook document is invalid (${mergedSchema.errors.join("; ")}). ` +
+                "Run `npx cclaw-cli sync` after fixing the custom hook entry or remove the malformed user-authored hook block.");
         }
     }
     await writeFileSafe(hookFilePath, `${JSON.stringify(mergedDoc, null, 2)}\n`);
@@ -884,11 +910,14 @@ async function writeHooks(projectRoot, config) {
     }), null, 2)}\n`);
     await writeFileSafe(path.join(hooksDir, "stage-complete.mjs"), stageCompleteScript());
     await writeFileSafe(path.join(hooksDir, "start-flow.mjs"), startFlowScript());
+    await writeFileSafe(path.join(hooksDir, "cancel-run.mjs"), cancelRunScript());
     await writeFileSafe(path.join(hooksDir, "run-hook.mjs"), nodeHookRuntimeScript({
         strictness: effectiveStrictness,
         tddTestPathPatterns: config.tdd?.testPathPatterns ?? config.tddTestGlobs,
         tddProductionPathPatterns: config.tdd?.productionPathPatterns,
-        compoundRecurrenceThreshold: config.compound?.recurrenceThreshold
+        compoundRecurrenceThreshold: config.compound?.recurrenceThreshold,
+        earlyLoopEnabled: config.earlyLoop?.enabled,
+        earlyLoopMaxIterations: config.earlyLoop?.maxIterations
     }));
     await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookCmdScript());
     await writeFileSafe(path.join(hooksDir, "delegation-record.mjs"), delegationRecordScript());
@@ -901,7 +930,8 @@ async function writeHooks(projectRoot, config) {
             "run-hook.mjs",
             "run-hook.cmd",
             "delegation-record.mjs",
-            "opencode-plugin.mjs"
+            "opencode-plugin.mjs",
+            "cancel-run.mjs"
         ]) {
             await fs.chmod(path.join(hooksDir, script), 0o755);
         }
@@ -939,8 +969,8 @@ async function writeHooks(projectRoot, config) {
             // flag in `~/.codex/config.toml`. cclaw always writes the file so
             // the moment the flag flips on, the cclaw hooks start firing. See
             // `codexHooksJsonWithObservation` for the Bash-only caveat on
-            // PreToolUse/PostToolUse. `cclaw doctor` warns if the feature flag
-            // is not set.
+            // PreToolUse/PostToolUse. If the feature flag is off, hooks remain
+            // inert until the user enables codex_hooks in ~/.codex/config.toml.
             const codexDir = path.join(projectRoot, ".codex");
             await ensureDir(codexDir);
             await writeMergedHookJson(projectRoot, path.join(codexDir, "hooks.json"), codexHooksJson());
@@ -990,7 +1020,7 @@ async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
     for (const entry of managedHookFiles) {
         if (enabled.has(entry.harness))
             continue;
-        await removeManagedHookEntries(entry.hookPath);
+        await removeManagedHookEntries(entry.hookPath, { failOnParseError: true });
     }
     if (!enabled.has("opencode")) {
         try {
@@ -999,8 +1029,22 @@ async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
         catch {
             // best-effort cleanup
         }
+        try {
+            await fs.rm(path.join(projectRoot, ".opencode/agents"), { recursive: true, force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
         await removeManagedOpenCodePluginConfig(projectRoot, OPENCODE_PLUGIN_REL_PATH);
     }
+    if (!enabled.has("codex")) {
+        try {
+            await fs.rm(path.join(projectRoot, ".codex/agents"), { recursive: true, force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
 }
 async function writeState(projectRoot, config, forceReset = false) {
     const statePath = runtimePath(projectRoot, "state", "flow-state.json");
@@ -1014,6 +1058,9 @@ async function cleanLegacyArtifacts(projectRoot) {
     for (const legacyFolder of DEPRECATED_UTILITY_SKILL_FOLDERS) {
         await removeBestEffort(runtimePath(projectRoot, "skills", legacyFolder), true);
     }
+    for (const legacyFolder of DEPRECATED_STAGE_SKILL_FOLDERS) {
+        await removeBestEffort(runtimePath(projectRoot, "skills", legacyFolder), true);
+    }
     for (const legacyAgentFile of DEPRECATED_AGENT_FILES) {
         await removeBestEffort(runtimePath(projectRoot, "agents", legacyAgentFile));
     }
@@ -1038,16 +1085,30 @@ async function cleanLegacyArtifacts(projectRoot) {
     for (const legacyRuntimeDir of DEPRECATED_RUNTIME_DIRS) {
         await removeBestEffort(runtimePath(projectRoot, legacyRuntimeDir), true);
     }
-    // D-4 terminology migration: rename historical ideation artifacts to the
-    // canonical ideate-* naming without deleting user-authored content.
+    // Archive storage migration: `.cclaw/runs` is legacy and no longer a valid
+    // archive root. Remove only when empty; otherwise keep it so users can
+    // manually migrate or inspect old data.
+    const legacyRunsDir = runtimePath(projectRoot, "runs");
+    try {
+        const entries = await fs.readdir(legacyRunsDir);
+        if (entries.length === 0) {
+            await fs.rm(legacyRunsDir, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // missing or unreadable legacy dir; keep best-effort behavior
+    }
+    // D-4 terminology migration: rename historical ideation artifact prefixes to
+    // the canonical idea-* naming without deleting user-authored content.
+    const legacyIdeaArtifactPattern = /^ideation-(.+\.md)$/u;
     const artifactsDir = runtimePath(projectRoot, "artifacts");
     try {
         const entries = await fs.readdir(artifactsDir);
         for (const entry of entries) {
-            const match = /^ideation-(.+\.md)$/u.exec(entry);
+            const match = legacyIdeaArtifactPattern.exec(entry);
             if (!match)
                 continue;
-            const nextName = `ideate-${match[1]}`;
+            const nextName = `idea-${match[1]}`;
             const from = path.join(artifactsDir, entry);
             const to = path.join(artifactsDir, nextName);
             if (await exists(to)) {
@@ -1062,13 +1123,8 @@ async function cleanLegacyArtifacts(projectRoot) {
 }
 async function cleanStaleFiles(projectRoot) {
     const expectedShimFiles = new Set(harnessShimFileNames());
+    const expectedShimSkills = new Set(harnessShimFileNames().map((fileName) => fileName.replace(/\.md$/u, "")));
     for (const adapter of Object.values(HARNESS_ADAPTERS)) {
-        // Skill-kind shims (Codex) live in per-skill directories, not flat
-        // markdown files, so the regex-based stale sweep below would never
-        // match them anyway. The legacy `.codex/commands/` cleanup happens in
-        // `cleanupLegacyCodexSurfaces` inside syncHarnessShims().
-        if (adapter.shimKind === "skill")
-            continue;
         const commandDir = path.join(projectRoot, adapter.commandDir);
         if (!(await exists(commandDir)))
             continue;
@@ -1079,6 +1135,16 @@ async function cleanStaleFiles(projectRoot) {
         catch {
             entries = [];
         }
+        if (adapter.shimKind === "skill") {
+            for (const entry of entries) {
+                if (!/^cc(?:-.*)?$/u.test(entry))
+                    continue;
+                if (expectedShimSkills.has(entry))
+                    continue;
+                await fs.rm(path.join(commandDir, entry), { recursive: true, force: true });
+            }
+            continue;
+        }
         for (const entry of entries) {
             if (!/^cc(?:-.*)?\.md$/u.test(entry))
                 continue;
@@ -1090,7 +1156,34 @@ async function cleanStaleFiles(projectRoot) {
     // Keep user-owned custom assets under .cclaw/agents and .cclaw/skills.
     // Legacy managed removals happen in cleanLegacyArtifacts() with explicit paths.
 }
+async function assertExpectedHarnessShims(projectRoot, harnesses) {
+    const expectedFiles = harnessShimFileNames();
+    const expectedSkillFolders = harnessShimSkillNames();
+    for (const harness of harnesses) {
+        const adapter = HARNESS_ADAPTERS[harness];
+        const base = path.join(projectRoot, adapter.commandDir);
+        for (const fileName of expectedFiles) {
+            const target = adapter.shimKind === "skill"
+                ? path.join(base, fileName.replace(/\.md$/u, ""), "SKILL.md")
+                : path.join(base, fileName);
+            if (!(await exists(target))) {
+                throw new Error(`[sync fail-fast] Harness shim drift detected for ${harness}: missing ${target}. ` +
+                    `Run \`npx cclaw-cli sync\` again; if the file is still missing, inspect harness permissions/paths.`);
+            }
+        }
+        if (adapter.shimKind === "skill") {
+            for (const folder of expectedSkillFolders) {
+                const skillPath = path.join(base, folder, "SKILL.md");
+                if (!(await exists(skillPath))) {
+                    throw new Error(`[sync fail-fast] Harness skill shim drift detected for ${harness}: missing ${skillPath}. ` +
+                        `Run \`npx cclaw-cli sync\` again; if the issue persists, inspect generated .agents/skills surfaces.`);
+                }
+            }
+        }
+    }
+}
 async function materializeRuntime(projectRoot, config, forceStateReset, operation = "sync") {
+    await warnStaleInitSentinel(projectRoot, operation);
     const sentinelPath = await writeInitSentinel(projectRoot, operation);
     const managedSession = await ManagedResourceSession.create({ projectRoot, operation });
     setActiveManagedResourceSession(managedSession);
@@ -1106,25 +1199,51 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
             writeRulebook(projectRoot)
         ]);
         await writeState(projectRoot, config, forceStateReset);
-        await ensureRunSystem(projectRoot, { createIfMissing: false });
+        try {
+            await ensureRunSystem(projectRoot, { createIfMissing: false });
+        }
+        catch (error) {
+            if (error instanceof CorruptFlowStateError) {
+                throw new Error(`[sync fail-fast] Corrupt flow state detected: ${error.message} ` +
+                    `Resolve the quarantined flow-state file and re-run \`npx cclaw-cli sync\`.`);
+            }
+            throw error;
+        }
         await ensureKnowledgeStore(projectRoot);
         await writeHooks(projectRoot, config);
         await syncDisabledHarnessArtifacts(projectRoot, harnesses);
         await syncManagedGitHooks(projectRoot, config);
         await syncHarnessShims(projectRoot, harnesses);
+        await assertExpectedHarnessShims(projectRoot, harnesses);
         await writeCursorWorkflowRule(projectRoot, harnesses);
         await ensureGitignore(projectRoot);
         await managedSession.commit();
         await fs.unlink(sentinelPath).catch(() => undefined);
     }
     catch (error) {
-        // Leave the sentinel in place so doctor can surface the interrupted run.
+        // Leave the sentinel in place so the interrupted run is visible.
         throw error;
     }
     finally {
         setActiveManagedResourceSession(null);
     }
 }
+async function warnCodexHooksFeatureFlagIfDisabled(harnesses) {
+    if (!harnesses.includes("codex"))
+        return;
+    const codexTomlPath = codexConfigPath();
+    let existing;
+    try {
+        existing = await readCodexConfig(codexTomlPath);
+    }
+    catch (error) {
+        process.stderr.write(`cclaw: could not read ${codexTomlPath} to validate codex_hooks flag: ${error instanceof Error ? error.message : String(error)}\n`);
+        return;
+    }
+    if (classifyCodexHooksFlag(existing) === "enabled")
+        return;
+    process.stderr.write(`cclaw: Codex hooks file written, but [features] codex_hooks is not true in ${codexTomlPath} — hooks are inert until you enable it.\n`);
+}
 export async function initCclaw(options) {
     if (options.harnesses !== undefined && options.harnesses.length === 0) {
         throw new Error("Select at least one harness.");
@@ -1153,7 +1272,7 @@ export async function syncCclaw(projectRoot, options = {}) {
         // Prefer detected harness markers over the hardcoded default list.
         // Without this, a user running `cclaw sync` in a `.claude`-only
         // project ends up with a config that also enables cursor/opencode/
-        // codex, which then fails doctor checks for missing shim folders.
+        // codex, which then creates invalid harness expectations.
         // Fall back to the previous default (config.harnesses) if no markers
         // are found so brand-new projects still bootstrap cleanly.
         const detected = await detectHarnesses(projectRoot);
@@ -1173,6 +1292,7 @@ export async function syncCclaw(projectRoot, options = {}) {
         });
     }
     await materializeRuntime(projectRoot, config, false, "sync");
+    await warnCodexHooksFeatureFlagIfDisabled(config.harnesses);
 }
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
@@ -1270,20 +1390,28 @@ function isManagedRuntimeHookCommand(command) {
     // Codex UserPromptSubmit non-blocking state nudge.
     return /internal verify-current-state(?:\s|$)/u.test(normalized);
 }
-async function removeManagedHookEntries(hookFilePath) {
+async function removeManagedHookEntries(hookFilePath, options = {}) {
     if (!(await exists(hookFilePath)))
         return;
     let parsed = null;
     try {
         const raw = await fs.readFile(hookFilePath, "utf8");
         const recovered = tryParseHookDocument(raw);
-        parsed = recovered?.parsed ?? null;
+        if (recovered === null) {
+            if (options.failOnParseError === true) {
+                throw new Error(`[sync fail-fast] Cannot strip managed hook entries from ${hookFilePath} — JSON is unparseable. ` +
+                    `Run \`rm ${hookFilePath}\` and rerun \`npx cclaw-cli sync\`.`);
+            }
+            return;
+        }
+        parsed = recovered.parsed;
     }
-    catch {
+    catch (error) {
+        if (options.failOnParseError === true) {
+            throw new Error(`[sync fail-fast] Cannot strip managed hook entries from ${hookFilePath} — ${error instanceof Error ? error.message : String(error)}. Run \`rm ${hookFilePath}\` and rerun \`npx cclaw-cli sync\`.`);
+        }
         return;
     }
-    if (parsed === null)
-        return;
     const { updated, changed } = stripManagedHookCommands(parsed);
     if (!changed)
         return;
@@ -1365,7 +1493,7 @@ export async function uninstallCclaw(projectRoot) {
     try {
         const entries = await fs.readdir(codexSkillsRoot);
         for (const entry of entries) {
-            if (/^(?:cclaw-)?cc(?:-(?:next|view|finish|cancel|ops|ideate|brainstorm|scope|design|spec|plan|tdd|review|ship))?$/u.test(entry)) {
+            if (/^(?:cclaw-)?cc(?:-(?:next|view|finish|cancel|ops|idea|brainstorm|scope|design|spec|plan|tdd|review|ship))?$/u.test(entry)) {
                 await fs.rm(path.join(codexSkillsRoot, entry), { recursive: true, force: true });
             }
         }

package/dist/internal/advance-stage/advance.d.ts

@@ -0,0 +1,50 @@
+import { type FlowState } from "../../flow-state.js";
+import { type FlowStage } from "../../types.js";
+import type { AdvanceStageArgs } from "./parsers.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+interface InternalValidationReport {
+    ok: boolean;
+    stage: FlowStage;
+    delegation: {
+        satisfied: boolean;
+        missing: string[];
+        waived: string[];
+        missingEvidence: string[];
+        missingDispatchProof: string[];
+        legacyInferredCompletions: string[];
+        corruptEventLines: number[];
+        staleWorkers: string[];
+        expectedMode: string;
+    };
+    gates: {
+        ok: boolean;
+        complete: boolean;
+        issues: string[];
+        missingRequired: string[];
+        missingTriggeredConditional: string[];
+    };
+    completedStages: {
+        ok: boolean;
+        issues: string[];
+    };
+}
+export declare function hydrateReviewLoopEvidenceFromArtifact(projectRoot: string, stage: FlowStage, track: FlowState["track"], selectedGateIds: string[], evidenceByGate: Record<string, string>): Promise<void>;
+export declare function buildValidationReport(projectRoot: string, flowState: FlowState, options?: {
+    allowBlockedReviewRoute?: boolean;
+}): Promise<InternalValidationReport>;
+interface HarvestLearningsResult {
+    ok: boolean;
+    markerWritten: boolean;
+    parsedEntries: number;
+    appendedEntries: number;
+    skippedDuplicates: number;
+    details: string;
+}
+export declare function withLearningsHarvestMarker(artifactMarkdown: string, appendedEntries: number, skippedDuplicates: number): string;
+export declare function harvestStageLearnings(projectRoot: string, stage: FlowStage, track: FlowState["track"]): Promise<HarvestLearningsResult>;
+export declare function runAdvanceStage(projectRoot: string, args: AdvanceStageArgs, io: InternalIo): Promise<number>;
+export {};