kcode-pi 0.1.24 → 0.1.30

package/src/harness/delegation.ts

@@ -0,0 +1,297 @@
+import { readProjectContext } from "../context/project-context.ts";
+import { readArtifact } from "./artifacts.ts";
+import { formatStatus } from "./format.ts";
+import type { ActiveRun, KdPhase } from "./types.ts";
+import { PHASE_ORDER } from "./types.ts";
+import { isAbsolute, relative } from "node:path";
+
+export type DelegationRole = "research" | "doc" | "code" | "review" | "verify";
+
+export interface DelegationRequest {
+	role: DelegationRole;
+	task: string;
+}
+
+export type DelegationMode = "single" | "parallel" | "chain";
+
+export interface ParsedDelegationArgs extends DelegationRequest {
+	dryRun: boolean;
+}
+
+const ROLE_GUIDANCE: Record<DelegationRole, string[]> = {
+	research: [
+		"只读调研项目、文档、SDK 线索和现有实现。",
+		"输出压缩结论、证据文件/代码位置、风险和建议下一步。",
+		"不要修改文件，不要推进 Harness 状态。",
+	],
+	doc: [
+		"只写当前任务明确要求的文档或阶段产物。",
+		"如果需要改阶段文档，保持内容和当前 Harness 阶段一致。",
+		"不要修改产品源码，不要推进 Harness 状态。",
+	],
+	code: [
+		"只有当前 run 处于 execute 阶段时才允许修改产品代码。",
+		"只修改 PLAN.md 批准的文件；发现新文件需求时停止并说明需要回到 plan。",
+		"完成后列出变更文件、执行步骤证据和需要主 agent 验证的命令。",
+	],
+	review: [
+		"只读交叉自查，不修改文件。",
+		"优先找 bug、状态机漏洞、门禁绕过、证据缺口和测试缺口。",
+		"输出 findings，按严重程度排序并带文件/函数引用；明确是否阻止发布。",
+	],
+	verify: [
+		"只读分析计划中的验证命令、失败证据和风险。",
+		"需要实际运行验证时，把命令和原因交回主 agent 执行。",
+		"验证结果由主 agent 通过 kd_verify_result 记录。",
+		"不要手工绕过 Harness 的 VERIFY/evidence 记录闭环。",
+	],
+};
+
+const ROLE_ALLOWED_WRITES: Record<DelegationRole, string> = {
+	research: "none",
+	doc: "docs-and-current-phase-artifact",
+	code: "plan-approved-files-only",
+	review: "none",
+	verify: "evidence-through-kd_verify_result",
+};
+
+export const DEFAULT_REVIEW_TASK = "审查当前 run 和最近变更，重点找状态机漏洞、门禁绕过、证据缺口、提示词分散和测试缺口。";
+export const CHILD_AGENT_USER_TASK = "执行 KCode 子 agent 委派任务。";
+export const KD_SUBAGENT_TOOL_DESCRIPTION =
+	"将调研、文档、代码、验证或交叉审查任务委派给隔离 Pi 子进程。主 Harness 仍负责阶段推进、证据和门禁。";
+export const KD_DELEGATE_USAGE = "用法：/kd-delegate <research|doc|code|review|verify> <任务> [--dry-run]";
+export const KD_SUBAGENT_INVALID_PARAMS = "kd_subagent 需要 role=research|doc|code|review|verify 和非空 task，或提供 tasks/chain。";
+export const KD_SUBAGENT_PARALLEL_ROLE_ERROR = "kd_subagent 并行模式只允许 research、review、verify 这类只读角色。doc/code 必须串行执行。";
+export const KD_REVIEW_COMMAND_DESCRIPTION = "启动只读交叉自查子 agent：/kd-review [审查重点]";
+export const KD_DELEGATE_COMMAND_DESCRIPTION = "委派任务给隔离子 agent：/kd-delegate <research|doc|code|review|verify> <任务> [--dry-run]";
+export const KD_SUBAGENT_SCHEMA_DESCRIPTIONS = {
+	role: "单任务角色：research、doc、code、review、verify。",
+	task: "单任务内容。",
+	taskItemRole: "任务角色。",
+	taskItemTask: "任务内容。",
+	tasks: "并行任务数组，最多 8 个，最多 4 个同时运行。",
+	chain: "链式任务数组，按顺序运行；后一步会收到上一步输出。",
+	dryRun: "只预览上下文包，不启动子进程。",
+	maxOutputChars: "返回给主 agent 的最大输出字符数，默认 30000。",
+} as const;
+
+const READ_ONLY_ROLES = new Set<DelegationRole>(["research", "review", "verify"]);
+const WRITE_TOOL_NAMES = new Set(["write", "edit"]);
+const SHELL_TOOL_NAMES = new Set(["bash", "shell", "shell_command"]);
+
+export function isDelegationRole(value: string): value is DelegationRole {
+	return value === "research" || value === "doc" || value === "code" || value === "review" || value === "verify";
+}
+
+export function parseDelegationArgs(args: string): ParsedDelegationArgs | undefined {
+	const tokens = tokenizeArgs(args);
+	if (tokens.length === 0) return undefined;
+	const roleText = tokens[0]?.toLowerCase();
+	if (!roleText || !isDelegationRole(roleText)) return undefined;
+
+	const dryRun = tokens.includes("--dry-run");
+	const task = tokens.slice(1).filter((token) => token !== "--dry-run").join(" ").trim();
+	if (!task) return undefined;
+	return { role: roleText, task, dryRun };
+}
+
+export function delegationBlockReason(role: DelegationRole, run: ActiveRun | undefined): string | undefined {
+	if (role === "code") {
+		if (!run) return "code 子 agent 需要 active Harness run，且必须处于 execute 阶段。";
+		if (run.phase !== "execute") return `code 子 agent 只能在 execute 阶段运行；当前阶段：${run.phase}。`;
+	}
+	if (role === "verify" && !run) return "verify 子 agent 需要 active Harness run。";
+	return undefined;
+}
+
+export function isReadOnlyDelegationRole(role: DelegationRole): boolean {
+	return READ_ONLY_ROLES.has(role);
+}
+
+export function parallelDelegationBlockReason(requests: DelegationRequest[]): string | undefined {
+	return requests.some((request) => !isReadOnlyDelegationRole(request.role)) ? KD_SUBAGENT_PARALLEL_ROLE_ERROR : undefined;
+}
+
+export function isSubagentChild(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env.KCODE_SUBAGENT_CHILD === "1";
+}
+
+export function subagentRoleFromEnv(env: NodeJS.ProcessEnv = process.env): DelegationRole | undefined {
+	const role = env.KCODE_SUBAGENT_ROLE;
+	return typeof role === "string" && isDelegationRole(role) ? role : undefined;
+}
+
+export function shouldInjectDelegationGuidance(env: NodeJS.ProcessEnv = process.env): boolean {
+	return !isSubagentChild(env);
+}
+
+export function subagentAllowedTools(role: DelegationRole): string[] {
+	const readTools = ["read", "grep", "find", "ls"];
+	if (role === "doc" || role === "code") return [...readTools, "write", "edit"];
+	return readTools;
+}
+
+export function subagentToolCallBlockReason(input: {
+	role: DelegationRole;
+	toolName: string;
+	path?: string;
+	cwd: string;
+	run?: ActiveRun;
+	sourceLike?: boolean;
+	planWriteBlockReason?: string;
+	sourceWriteBlockReason?: string;
+}): string | undefined {
+	if (SHELL_TOOL_NAMES.has(input.toolName)) {
+		return "子 agent 不允许调用 shell 类工具；需要运行命令时交回主 agent 执行。";
+	}
+	if (!WRITE_TOOL_NAMES.has(input.toolName)) return undefined;
+
+	if (isReadOnlyDelegationRole(input.role)) {
+		return `${input.role} 子 agent 是只读角色，不能写入文件。`;
+	}
+	if (input.role === "doc") {
+		if (isDocWritablePath(input.cwd, input.run, input.path)) return undefined;
+		return "doc 子 agent 只能写 README、docs/ 或当前 run 的阶段文档。";
+	}
+	if (input.role === "code") {
+		if (!input.sourceLike) return "code 子 agent 只能写产品源码，其他文件改动必须交回主 agent。";
+		if (input.sourceWriteBlockReason) return input.sourceWriteBlockReason;
+		if (input.planWriteBlockReason) return input.planWriteBlockReason;
+		return undefined;
+	}
+	return undefined;
+}
+
+export function buildDelegationCommandPrompt(request: DelegationRequest, dryRun: boolean): string {
+	return [
+		"请调用 kd_subagent 完成以下委派任务。",
+		`role: ${request.role}`,
+		`dryRun: ${dryRun ? "true" : "false"}`,
+		"task:",
+		request.task,
+		"",
+		"子 agent 返回后，由主 agent 判断是否需要修改文件、记录 evidence 或推进 Harness。",
+	].join("\n");
+}
+
+export function delegationGuidanceForWorkflow(): string {
+	return [
+		"- 当任务需要大量调研、独立交叉审查、长上下文复盘或可并行拆分时，优先考虑 kd_subagent。",
+		"- 自动委派只做旁路工作；主 agent 仍负责采纳结论、修改文件、记录 evidence 和推进阶段。",
+		"- code 委派只能在 execute 阶段且限于 PLAN.md 批准文件；review/research 默认只读。",
+	].join("\n");
+}
+
+export function buildChainedDelegationRequest(request: DelegationRequest, previousOutput: string): DelegationRequest {
+	if (!previousOutput.trim()) return request;
+	return {
+		role: request.role,
+		task: [
+			request.task.trim(),
+			"",
+			"上一子 agent 输出：",
+			trimForPrompt(previousOutput, 6000),
+			"",
+			"请基于上一输出继续当前步骤，并只交付本步骤结论。",
+		].join("\n"),
+	};
+}
+
+export function buildDelegationPrompt(cwd: string, run: ActiveRun | undefined, request: DelegationRequest): string {
+	const roleGuidance = ROLE_GUIDANCE[request.role];
+	const projectContext = readProjectContext(cwd);
+	const status = run ? formatStatus(cwd, run) : "当前没有 active KCode Harness run。";
+	const phaseContext = run ? delegationMemoryForRun(cwd, run) : "无 active run 阶段资料。";
+
+	return [
+		"KCode 子 agent 委派任务。",
+		"",
+		"角色：",
+		request.role,
+		"",
+		"任务：",
+		request.task.trim(),
+		"",
+		"写入边界：",
+		ROLE_ALLOWED_WRITES[request.role],
+		"",
+		"角色规则：",
+		...roleGuidance.map((item) => `- ${item}`),
+		"- 你不是主状态机；不要调用 /kd-advance、/kd-finish 或改变 run 生命周期。",
+		"- 不要再创建子 agent；把结果交回主 agent 统一决策。",
+		"",
+		"Harness 状态：",
+		status,
+		"",
+		"阶段上下文：",
+		phaseContext,
+		"",
+		"项目上下文：",
+		projectContext ? trimForPrompt(projectContext, 1200) : "未生成。需要项目结构时读取本地文件或提示主 agent 运行 `kcode context --refresh`。",
+		"",
+		"输出格式：",
+		"- 结论",
+		"- 证据/引用",
+		"- 风险",
+		"- 建议给主 agent 的下一步",
+	].join("\n");
+}
+
+export function formatDelegationPreview(cwd: string, run: ActiveRun | undefined, request: DelegationRequest): string {
+	return [
+		`角色：${request.role}`,
+		`写入边界：${ROLE_ALLOWED_WRITES[request.role]}`,
+		run ? `Run：${run.id} | 阶段：${run.phase}` : "Run：无 active run",
+		"",
+		"任务：",
+		request.task.trim(),
+		"",
+		"将发送给隔离子 agent 的上下文包：",
+		buildDelegationPrompt(cwd, run, request),
+	].join("\n");
+}
+
+function delegationMemoryForRun(cwd: string, run: ActiveRun): string {
+	const currentIndex = PHASE_ORDER.indexOf(run.phase);
+	const nearby = PHASE_ORDER.slice(Math.max(0, currentIndex - 2), currentIndex + 1);
+	const sections = nearby
+		.map((phase) => artifactSection(cwd, run, phase))
+		.filter((section): section is string => Boolean(section));
+	return sections.join("\n\n") || `阶段文档路径：.pi/kd/runs/${run.id}/`;
+}
+
+function artifactSection(cwd: string, run: ActiveRun, phase: KdPhase): string | undefined {
+	const content = readArtifact(cwd, run, phase);
+	if (!content) return undefined;
+	return [`## ${phase}`, trimForPrompt(content, 1800)].join("\n");
+}
+
+function trimForPrompt(content: string, maxLength: number): string {
+	if (content.length <= maxLength) return content;
+	return `${content.slice(0, maxLength)}\n\n[...已截断；需要完整内容时读取本地文件...]`;
+}
+
+function isDocWritablePath(cwd: string, run: ActiveRun | undefined, path: string | undefined): boolean {
+	if (!path) return false;
+	const normalized = normalizeWorkspacePath(cwd, path);
+	if (normalized === "README.md") return true;
+	if (normalized.startsWith("docs/") && /\.md$/i.test(normalized)) return true;
+	if (run && normalized.startsWith(`.pi/kd/runs/${run.id}/`) && /\.md$/i.test(normalized)) return true;
+	return false;
+}
+
+function normalizeWorkspacePath(cwd: string, path: string): string {
+	const relativePath = isAbsolute(path) ? relative(cwd, path) : path;
+	return relativePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+function tokenizeArgs(args: string): string[] {
+	const tokens: string[] = [];
+	const pattern = /"([^"]*)"|'([^']*)'|(\S+)/g;
+	let match: RegExpExecArray | null;
+	while ((match = pattern.exec(args)) !== null) {
+		const token = match[1] ?? match[2] ?? match[3];
+		if (token) tokens.push(token);
+	}
+	return tokens;
+}

package/src/harness/evidence.ts

@@ -28,8 +28,9 @@ export function readEvidenceIndex(cwd: string, run: ActiveRun): EvidenceIndex {
 	const path = evidenceIndexPath(cwd, run);
 	if (!existsSync(path)) return { version: 1, entries: [] };
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf8")) as EvidenceIndex;
-		return parsed.version === 1 && Array.isArray(parsed.entries) ? parsed : { version: 1, entries: [] };
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<EvidenceIndex>;
+		if (parsed.version !== 1 || !Array.isArray(parsed.entries)) return { version: 1, entries: [] };
+		return { version: 1, entries: parsed.entries.filter(isEvidenceEntry) };
 	} catch {
 		return { version: 1, entries: [] };
 	}
@@ -37,6 +38,7 @@ export function readEvidenceIndex(cwd: string, run: ActiveRun): EvidenceIndex {
 
 export function hasEvidenceEntry(cwd: string, run: ActiveRun, path: string): boolean {
 	const normalized = normalizeEvidencePath(path);
+	if (!normalized) return false;
 	return readEvidenceIndex(cwd, run).entries.some((entry) => normalizeEvidencePath(entry.path) === normalized);
 }
 
@@ -48,7 +50,7 @@ export function writeEvidenceFile(
 	options: { kind?: string; command?: string; exitCode?: number } = {},
 ): string {
 	const normalized = normalizeEvidencePath(path);
-	if (!normalized.startsWith("evidence/") || normalized === EVIDENCE_INDEX) {
+	if (!normalized || !normalized.startsWith("evidence/") || normalized === EVIDENCE_INDEX) {
 		throw new Error(`非法 evidence 路径：${path}`);
 	}
 
@@ -66,6 +68,7 @@ export function recordEvidence(
 	options: { kind?: string; command?: string; exitCode?: number } = {},
 ): void {
 	const normalized = normalizeEvidencePath(path);
+	if (!normalized) return;
 	const absolutePath = join(runRoot(cwd, run), normalized);
 	if (!existsSync(absolutePath)) return;
 
@@ -96,11 +99,19 @@ export function recordEvidence(
 	writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, "utf8");
 }
 
+function isEvidenceEntry(value: unknown): value is EvidenceEntry {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const entry = value as Partial<EvidenceEntry>;
+	return typeof entry.path === "string" && entry.path.trim().length > 0;
+}
+
 function inferKind(path: string): string {
 	const name = path.split("/").at(-1) ?? path;
 	return name.replace(/\.(md|txt|json)$/i, "");
 }
 
-function normalizeEvidencePath(path: string): string {
-	return path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+function normalizeEvidencePath(path: unknown): string | undefined {
+	if (typeof path !== "string") return undefined;
+	const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+	return normalized.trim() || undefined;
 }

package/src/harness/gates.ts

@@ -9,7 +9,7 @@ import { executionStepsBlockReason, planStepsBlockReason } from "./plan-steps.ts
 import { tddPlanBlockReason, tddVerifyBlockReason } from "./tdd-policy.ts";
 import { SDK_SIGNATURE_EVIDENCE, hasValidSdkSignatureEvidence, requiresSdkSignatureEvidence } from "./sdk-policy.ts";
 import { runRoot } from "./paths.ts";
-import { EVIDENCE_INDEX, hasEvidenceEntry } from "./evidence.ts";
+import { EVIDENCE_INDEX, readEvidenceIndex } from "./evidence.ts";
 import {
 	missingArtifactsReason,
 	missingEvidenceReason,
@@ -129,7 +129,7 @@ function productImplementationDeclaration(cwd: string, run: ActiveRun): boolean
 function hasRiskAssessment(cwd: string, run: ActiveRun): boolean {
 	const level = run.riskAssessment?.level;
 	if (!level) return false;
-	if (run.riskAssessment?.reason.trim()) return true;
+	if (typeof run.riskAssessment?.reason === "string" && run.riskAssessment.reason.trim()) return true;
 	return riskSectionHasContent(readArtifact(cwd, run, "verify") ?? "") || riskSectionHasContent(readArtifact(cwd, run, "ship") ?? "");
 }
 
@@ -143,7 +143,7 @@ function riskSectionHasContent(content: string): boolean {
 }
 
 function inspectOpenQuestions(run: ActiveRun): string | undefined {
-	const open = (run.questions ?? []).filter((question) => question.status === "open" && question.blocking);
+	const open = Array.isArray(run.questions) ? run.questions.filter((question) => question.status === "open" && question.blocking) : [];
 	if (open.length === 0) return undefined;
 	return openQuestionsReason(open);
 }
@@ -212,7 +212,13 @@ function requiredEvidenceForPhase(cwd: string, run: ActiveRun, phase: KdPhase):
 function evidenceArtifactSatisfied(cwd: string, run: ActiveRun, artifact: string): boolean {
 	if (artifact === SDK_SIGNATURE_EVIDENCE) return hasValidSdkSignatureEvidence(cwd, run);
 	if (artifact === EVIDENCE_INDEX) return existsSync(join(runRoot(cwd, run), artifact));
-	return existsSync(join(runRoot(cwd, run), artifact)) && hasEvidenceEntry(cwd, run, artifact);
+	return existsSync(join(runRoot(cwd, run), artifact)) && hasSuccessfulEvidenceEntry(cwd, run, artifact);
+}
+
+function hasSuccessfulEvidenceEntry(cwd: string, run: ActiveRun, artifact: string): boolean {
+	const normalized = artifact.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^\.\//, "");
+	const entry = readEvidenceIndex(cwd, run).entries.find((item) => typeof item.path === "string" && item.path.replace(/\\/g, "/") === normalized);
+	return Boolean(entry && entry.exitCode === 0);
 }
 
 function planHasMetadataRequirement(cwd: string, run: ActiveRun): boolean {

package/src/harness/prompt.ts

@@ -1,5 +1,6 @@
 import { readProjectContext } from "../context/project-context.ts";
 import { readArtifact } from "./artifacts.ts";
+import { delegationGuidanceForWorkflow, shouldInjectDelegationGuidance } from "./delegation.ts";
 import { formatStatus } from "./format.ts";
 import type { ActiveRun, KdPhase } from "./types.ts";
 import { PHASE_ORDER } from "./types.ts";
@@ -9,6 +10,7 @@ export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: stri
 	const memory = workflowMemoryForRun(cwd, run);
 	const phaseGuidance = phaseGuidanceForRun(run.phase);
 	const projectContext = readProjectContext(cwd);
+	const delegationGuidance = shouldInjectDelegationGuidance() ? ["", "子 agent 委派策略：", delegationGuidanceForWorkflow()] : [];
 
 	return [
 		"用户输入：",
@@ -32,6 +34,16 @@ export function workflowPromptForRun(cwd: string, run: ActiveRun, userText: stri
 		"- Java/Cosmic 用当前项目 Gradle；C#/企业版用 dotnet build。",
 		"- evidence 记录命令、Exit 和关键输出；命令无法运行时记录阻塞原因。",
 		"- Windows 下优先使用项目相对路径；绝对路径使用 D:\\... 形式。",
+		...delegationGuidance,
+	].join("\n");
+}
+
+export function repairPromptForRun(run: ActiveRun): string {
+	return [
+		"验证失败，进入自动修复循环。",
+		`失败证据：${run.repair?.lastFailureEvidence ?? "未知"}`,
+		`修复轮次：${run.repair?.attempts ?? 0}/${run.repair?.maxAttempts ?? 3}`,
+		"读取失败证据，定位原因，只修改 PLAN.md 批准文件；修复后重新执行同一验证命令并调用 kd_verify_result。",
 	].join("\n");
 }
 
@@ -41,7 +53,7 @@ function phaseGuidanceForRun(phase: KdPhase): string {
 		spec: "把需求转成验收标准、数据对象、异常行为、依赖和风险。",
 		plan: "检查项目结构，写明目标路径、允许修改文件、查证项、验证命令和回滚说明。",
 		execute: "按 PLAN.md 实现，记录步骤结果、变更文件和 evidence。",
-		verify: "运行计划中的验证命令，更新 VERIFY.md、证据和残余风险。",
+		verify: "运行计划中的验证命令，并用 kd_verify_result 记录结果；失败会回到 execute 修复，成功后更新 VERIFY.md、证据和残余风险。",
 		ship: "整理 SHIP.md，包括摘要、验证证据、风险和后续事项。",
 	};
 	return guidance[phase];

package/src/harness/repair.ts

@@ -0,0 +1,224 @@
+import type { ActiveRun } from "./types.ts";
+import { defaultArtifactContent, ensureArtifact, readArtifact, writeArtifact } from "./artifacts.ts";
+import { writeEvidenceFile } from "./evidence.ts";
+import { inspectGate } from "./gates.ts";
+import { writeActiveRun } from "./state.ts";
+
+export interface VerifyResultInput {
+	command: unknown;
+	exitCode: unknown;
+	stdout?: unknown;
+	stderr?: unknown;
+	summary?: unknown;
+}
+
+export interface VerifyResultOutcome {
+	status: "passed" | "repairing" | "blocked" | "rejected";
+	run: ActiveRun;
+	evidencePath?: string;
+	message: string;
+}
+
+interface NormalizedVerifyResultInput {
+	command: string;
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+	summary: string;
+}
+
+const DEFAULT_MAX_REPAIR_ATTEMPTS = 3;
+
+export function recordVerifyResult(cwd: string, run: ActiveRun, input: VerifyResultInput): VerifyResultOutcome {
+	const blockReason = verifyResultBlockReason(run);
+	if (blockReason) {
+		return {
+			status: "rejected",
+			run,
+			message: blockReason,
+		};
+	}
+
+	const normalized = normalizeInput(input);
+	if (normalized.exitCode === 0) {
+		return recordVerifyPass(cwd, run, normalized);
+	}
+	return recordVerifyFailure(cwd, run, normalized);
+}
+
+function recordVerifyPass(cwd: string, run: ActiveRun, input: NormalizedVerifyResultInput): VerifyResultOutcome {
+	const evidence = "evidence/verify-pass.md";
+	const evidencePath = writeEvidenceFile(cwd, run, evidence, formatVerifyEvidence("验证通过", input), {
+		kind: "verify-pass",
+		command: input.command,
+		exitCode: input.exitCode,
+	});
+	appendVerifyRecord(cwd, run, "验证通过", evidence, input);
+	closeRepairQuestions(run, evidence);
+	run.repair = {
+		attempts: 0,
+		maxAttempts: run.repair?.maxAttempts ?? DEFAULT_MAX_REPAIR_ATTEMPTS,
+		status: "idle",
+		updatedAt: new Date().toISOString(),
+	};
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return {
+		status: "passed",
+		run,
+		evidencePath,
+		message: `验证通过，已记录证据：${evidence}`,
+	};
+}
+
+function recordVerifyFailure(cwd: string, run: ActiveRun, input: NormalizedVerifyResultInput): VerifyResultOutcome {
+	const maxAttempts = run.repair?.maxAttempts ?? DEFAULT_MAX_REPAIR_ATTEMPTS;
+	const attempts = (run.repair?.attempts ?? 0) + 1;
+	const evidence = `evidence/verify-failure-${String(attempts).padStart(3, "0")}.md`;
+	const signature = failureSignature(input);
+	const evidencePath = writeEvidenceFile(cwd, run, evidence, formatVerifyEvidence("验证失败", input), {
+		kind: "verify-failure",
+		command: input.command,
+		exitCode: input.exitCode,
+	});
+	appendVerifyRecord(cwd, run, "验证失败", evidence, input);
+
+	if (attempts >= maxAttempts) {
+		run.phase = "verify";
+		closeRepairQuestions(run, evidence);
+		run.repair = {
+			attempts,
+			maxAttempts,
+			lastFailureEvidence: evidence,
+			lastFailureSignature: signature,
+			status: "blocked",
+			updatedAt: new Date().toISOString(),
+		};
+		run.questions = [
+			...(Array.isArray(run.questions) ? run.questions : []),
+			{
+				id: `Q-${String((run.questions?.length ?? 0) + 1).padStart(3, "0")}`,
+				phase: "verify",
+				question: `验证失败已达到 ${maxAttempts} 轮。是否允许继续修复，或需要回到 plan 调整范围？`,
+				reason: `最近失败证据：${evidence}`,
+				choices: ["继续修复", "回到 plan", "停止"],
+				blocking: true,
+				status: "open",
+				createdAt: new Date().toISOString(),
+			},
+		];
+		run.gate = inspectGate(cwd, run);
+		writeActiveRun(cwd, run);
+		return {
+			status: "blocked",
+			run,
+			evidencePath,
+			message: `验证失败已达到 ${maxAttempts} 轮，已记录 ${evidence} 并创建阻断问题。`,
+		};
+	}
+
+	run.phase = "execute";
+	ensureArtifact(cwd, run, "execute", defaultArtifactContent("execute", run.goal, run.profile));
+	appendExecuteRepairRecord(cwd, run, evidence, attempts, maxAttempts);
+	run.repair = {
+		attempts,
+		maxAttempts,
+		lastFailureEvidence: evidence,
+		lastFailureSignature: signature,
+		status: "repairing",
+		updatedAt: new Date().toISOString(),
+	};
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return {
+		status: "repairing",
+		run,
+		evidencePath,
+		message: `验证失败，已记录 ${evidence}，自动回到 execute 修复（${attempts}/${maxAttempts}）。`,
+	};
+}
+
+function appendVerifyRecord(cwd: string, run: ActiveRun, title: string, evidence: string, input: NormalizedVerifyResultInput): void {
+	const existing = readArtifact(cwd, run, "verify") ?? defaultArtifactContent("verify", run.goal, run.profile);
+	const section = [
+		"",
+		`### ${title} - ${new Date().toISOString()}`,
+		"",
+		`- 命令：${input.command}`,
+		`- Exit：${input.exitCode}`,
+		`- 证据：${evidence}`,
+		input.summary ? `- 摘要：${input.summary}` : undefined,
+		"",
+	].filter(Boolean).join("\n");
+	writeArtifact(cwd, run, "verify", `${existing.trimEnd()}\n${section}`);
+}
+
+function appendExecuteRepairRecord(cwd: string, run: ActiveRun, evidence: string, attempts: number, maxAttempts: number): void {
+	const existing = readArtifact(cwd, run, "execute") ?? defaultArtifactContent("execute", run.goal, run.profile);
+	const section = [
+		"",
+		"## 自动修复循环",
+		"",
+		`- 修复轮次：${attempts}/${maxAttempts}`,
+		`- 失败证据：${evidence}`,
+		"- 下一步：读取失败证据，分析失败原因，只在 PLAN.md 批准文件内修复；如果需要改未批准文件，回到 plan 更新计划。",
+		"",
+	].join("\n");
+	writeArtifact(cwd, run, "execute", `${existing.trimEnd()}\n${section}`);
+}
+
+function formatVerifyEvidence(title: string, input: NormalizedVerifyResultInput): string {
+	return [
+		`# ${title}`,
+		"",
+		`Captured: ${new Date().toISOString()}`,
+		`Command: ${input.command}`,
+		`Exit: ${input.exitCode}`,
+		input.summary ? `Summary: ${input.summary}` : undefined,
+		input.stdout.trim() ? `\nSTDOUT:\n${input.stdout.trim()}` : undefined,
+		input.stderr.trim() ? `\nSTDERR:\n${input.stderr.trim()}` : undefined,
+		"",
+	].filter(Boolean).join("\n");
+}
+
+function normalizeInput(input: VerifyResultInput): NormalizedVerifyResultInput {
+	const exitCode = typeof input.exitCode === "number" ? input.exitCode : Number(input.exitCode);
+	return {
+		command: normalizeText(input.command).trim() || "unknown",
+		exitCode: Number.isFinite(exitCode) ? Math.trunc(exitCode) : 1,
+		stdout: normalizeText(input.stdout),
+		stderr: normalizeText(input.stderr),
+		summary: normalizeText(input.summary),
+	};
+}
+
+function normalizeText(value: unknown): string {
+	return typeof value === "string" ? value : "";
+}
+
+function verifyResultBlockReason(run: ActiveRun): string | undefined {
+	if (run.phase === "verify") return undefined;
+	if (run.phase === "execute" && run.repair?.status === "repairing") return undefined;
+	return `kd_verify_result 只能在 verify 阶段记录，或在自动修复循环的 execute 阶段记录。当前阶段：${run.phase}。`;
+}
+
+function closeRepairQuestions(run: ActiveRun, evidence: string): void {
+	if (!Array.isArray(run.questions)) return;
+	const now = new Date().toISOString();
+	for (const question of run.questions) {
+		if (question.status !== "open" || !question.blocking || question.phase !== "verify") continue;
+		if (!isRepairQuestion(question.question, question.reason)) continue;
+		question.status = "answered";
+		question.answer = `验证已继续处理，最新证据：${evidence}`;
+		question.answeredAt = now;
+	}
+}
+
+function isRepairQuestion(question: string, reason?: string): boolean {
+	return /验证失败已达到/.test(question) || /最近失败证据：evidence\/verify-failure-\d+\.md/.test(reason ?? "");
+}
+
+function failureSignature(input: NormalizedVerifyResultInput): string {
+	const text = [input.stderr, input.stdout, input.summary].join("\n").replace(/\s+/g, " ").trim();
+	return `${input.exitCode}:${text.slice(0, 300)}`;
+}