ai-dev-harness 0.1.1 → 0.1.2

package/dist/cli.js

@@ -1,26 +1,38 @@
 #!/usr/bin/env node
-import { readFile, writeFile } from "node:fs/promises";
+import { copyFile, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { AuditLogger, prepareRunFiles, writeJson } from "./audit.js";
 import { checkAgentContract, createAgentAdapter } from "./agent.js";
+import { evaluateApprovalGate } from "./approval.js";
+import { createCheckpoint, restoreCheckpoint, writePostIterationDiff } from "./checkpoint.js";
 import { loadConfig, loadSkill } from "./config.js";
 import { buildContextPack } from "./context.js";
+import { writeContextScore } from "./contextScore.js";
+import { writeVerifyDiagnostics } from "./diagnostics.js";
+import { runDoctor } from "./doctor.js";
+import { feedbackEvent } from "./feedback.js";
 import { initHarness } from "./init.js";
 import { installIntegration } from "./integration.js";
-import { makeRunPaths } from "./runPaths.js";
+import { evaluateIteration, renderReworkFeedback, writeLoopArtifacts } from "./loop.js";
+import { collectRunMetrics, renderMetricsText } from "./metrics.js";
+import { buildReplayPlan, renderReplayPlan } from "./replay.js";
+import { makeIterationPaths, makeRunPaths } from "./runPaths.js";
 import { writeSummary } from "./summarize.js";
 import { runVerify } from "./verify.js";
-import { git, pathExists } from "./utils.js";
+import { ensureDir, git, pathExists } from "./utils.js";
+const booleanArgs = new Set(["dry", "json", "live", "no-integration"]);
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
-    const args = {};
+    const args = { _: [] };
     for (let i = 0; i < rest.length; i += 1) {
         const item = rest[i];
-        if (!item.startsWith("--"))
+        if (!item.startsWith("--")) {
+            args._.push(item);
             continue;
+        }
         const key = item.slice(2);
         const next = rest[i + 1];
-        if (!next || next.startsWith("--"))
+        if (booleanArgs.has(key) || !next || next.startsWith("--"))
             args[key] = true;
         else {
             args[key] = next;
@@ -35,13 +47,35 @@ function usage() {
 用法:
   harness init
   harness init --no-integration
-  harness run --task <text> --skill <name> --agent <codex|claude>
-  harness run --task <text> --skill <name> --agent <codex|claude> --live
+  harness doctor
+  harness smoke --agent <codex|claude|cursor|gemini> [--live]
+  harness run --task <text> --skill <name> --agent <codex|claude|cursor|gemini>
+  harness run --task <text> --skill <name> --agent <codex|claude|cursor|gemini> --live
   harness verify --run <run_id_or_path>
   harness summarize --run <run_id_or_path>
-  harness install-integration --agent <claude|codex|both> [--target <repo>] [--command <harness command>]
+  harness restore --run <run_id_or_path> --iteration <n>
+  harness runs metrics [--json]
+  harness replay --run <run_id_or_path> [--dry] [--agent <codex|claude|cursor|gemini>]
+  harness install-integration --agent <claude|codex|cursor|gemini|both|all> [--target <repo>] [--command <harness command>]
 `;
 }
+async function commandDoctor(cwd) {
+    const config = await loadConfig(cwd);
+    const result = await runDoctor(cwd, config);
+    console.log(result.text);
+    if (result.failed)
+        throw new Error("doctor 检查失败，请先修复 FAIL 项。");
+}
+async function commandSmoke(cwd, args) {
+    const agentName = requireAgent(requireString(args, "agent"));
+    const live = Boolean(args.live);
+    await commandRun(cwd, {
+        task: "Smoke test only. Analyze repository context and do not modify repository files.",
+        skill: "update_docs",
+        agent: agentName,
+        live
+    });
+}
 function requireString(args, key) {
     const value = args[key];
     if (typeof value !== "string" || !value.trim())
@@ -49,8 +83,9 @@ function requireString(args, key) {
     return value;
 }
 function requireAgent(value) {
-    if (value !== "codex" && value !== "claude")
-        throw new Error(`无效 agent：${value}。期望 codex 或 claude。`);
+    if (value !== "codex" && value !== "claude" && value !== "cursor" && value !== "gemini") {
+        throw new Error(`无效 agent：${value}。期望 codex、claude、cursor 或 gemini。`);
+    }
     return value;
 }
 function quoteCommandPath(filePath) {
@@ -72,13 +107,13 @@ async function commandInit(cwd) {
     console.log(`AI Dev Harness 初始化完成：${cwd}`);
     console.log(`创建 ${result.created.length} 个文件，跳过 ${result.skipped.length} 个已存在文件。`);
     if (process.argv.includes("--no-integration")) {
-        console.log("已跳过 Claude/Codex 对话集成。");
+        console.log("已跳过 Agent 对话集成。");
         return;
     }
     const harnessCliPath = path.resolve(process.argv[1]);
     const harnessCommand = `node ${quoteCommandPath(harnessCliPath)}`;
-    const integration = await installIntegration({ targetDir: cwd, harnessCommand, harnessCliPath, agent: "both", packageRoot });
-    console.log("Claude/Codex 对话集成已安装。");
+    const integration = await installIntegration({ targetDir: cwd, harnessCommand, harnessCliPath, agent: "all", packageRoot });
+    console.log("Claude/Codex/Cursor/Gemini 对话集成已安装。");
     console.log(`集成创建：${integration.created.length ? integration.created.join(", ") : "无"}`);
     console.log(`集成更新：${integration.updated.length ? integration.updated.join(", ") : "无"}`);
     console.log(`集成跳过：${integration.skipped.length ? integration.skipped.join(", ") : "无"}`);
@@ -87,6 +122,26 @@ function sayLive(live, message) {
     if (live)
         console.log(`[harness] ${message}`);
 }
+async function copyIfExists(from, to) {
+    if (await pathExists(from))
+        await copyFile(from, to);
+}
+async function syncIterationSnapshot(paths, iterationPaths) {
+    await copyIfExists(iterationPaths.contextPack, paths.contextPack);
+    await copyIfExists(iterationPaths.agentPrompt, paths.agentPrompt);
+    await copyIfExists(iterationPaths.plan, paths.plan);
+    await copyIfExists(iterationPaths.executionLog, paths.executionLog);
+    await copyIfExists(iterationPaths.agentContract, paths.agentContract);
+    await copyIfExists(iterationPaths.gitDiff, paths.gitDiff);
+    await copyIfExists(iterationPaths.verify, paths.verify);
+    await copyIfExists(iterationPaths.verifyDiagnostics, paths.verifyDiagnostics);
+    await copyIfExists(iterationPaths.contextScore, paths.contextScore);
+    await copyIfExists(iterationPaths.approvalRequired, paths.approvalRequired);
+    await copyIfExists(iterationPaths.feedback, paths.feedback);
+    await copyIfExists(iterationPaths.checkpoint, paths.checkpoint);
+    await copyIfExists(iterationPaths.preIterationDiff, paths.preIterationDiff);
+    await copyIfExists(iterationPaths.postIterationDiff, paths.postIterationDiff);
+}
 async function commandRun(cwd, args) {
     const task = requireString(args, "task");
     const skillName = requireString(args, "skill");
@@ -121,24 +176,60 @@ async function commandRun(cwd, args) {
         await audit.event({ stage: "run", event: "run_finished", status: "failed" });
         throw new Error(`harness run 必须在 Git 仓库内执行。证据目录：${paths.runDir}`);
     }
-    sayLive(live, "正在构建 Context Pack：包含 Agent MCP 指引和本地兜底上下文");
-    await audit.event({ stage: "context_pack", event: "build_started", status: "started" });
-    const contextPack = await buildContextPack({
-        cwd,
-        task,
-        config,
-        skill,
-        contextPackPath: paths.contextPack,
-        mcpLogPath: paths.mcpQueries,
-        audit
-    });
-    await audit.event({
-        stage: "context_pack",
-        event: "build_finished",
-        status: "succeeded"
-    });
-    sayLive(live, `Context Pack 已生成：${paths.contextPack}`);
-    const plan = `# 执行阶段协议
+    const adapter = createAgentAdapter(agentName, config);
+    const agentCommand = config.agents[agentName].command;
+    const maxIterations = Math.max(1, config.loop.maxIterations);
+    const evaluations = [];
+    let previousFeedback;
+    let agentResult = {
+        status: "failed",
+        exitCode: null,
+        stdout: "",
+        stderr: "",
+        changedFiles: [],
+        diff: "",
+        error: "Agent 未运行"
+    };
+    let verifyResult = { status: "skipped", commands: [] };
+    let contractCheck = { status: "failed", requiredSections: [], missingSections: [] };
+    let verifyDiagnostics;
+    let contextScore;
+    let approval;
+    for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
+        const iterationPaths = makeIterationPaths(paths, iteration);
+        await ensureDir(iterationPaths.iterationDir);
+        await writeFile(iterationPaths.feedback, "", "utf8");
+        const checkpoint = await createCheckpoint({
+            cwd,
+            iteration,
+            checkpointPath: iterationPaths.checkpoint,
+            preDiffPath: iterationPaths.preIterationDiff,
+            runDir: paths.runDir
+        });
+        await feedbackEvent(iterationPaths.feedback, "checkpoint_created", { iteration, restoreSupported: checkpoint.restoreSupported });
+        sayLive(live, `正在构建 Context Pack（自纠偏循环 ${iteration}/${maxIterations}）`);
+        await audit.event({ stage: "context_pack", event: "build_started", status: "started", detail: { iteration } });
+        await buildContextPack({
+            cwd,
+            task,
+            config,
+            skill,
+            contextPackPath: iterationPaths.contextPack,
+            mcpLogPath: paths.mcpQueries,
+            audit
+        });
+        await feedbackEvent(iterationPaths.feedback, "context_pack_created", { iteration, path: iterationPaths.contextPack });
+        await audit.event({
+            stage: "context_pack",
+            event: "build_finished",
+            status: "succeeded",
+            detail: { iteration }
+        });
+        sayLive(live, `Context Pack 已生成：${iterationPaths.contextPack}`);
+        const plan = `# 执行阶段协议
+
+## 当前轮次
+${iteration}/${maxIterations}
 
 Agent 必须：
 1. 阅读 context_pack.md。
@@ -147,59 +238,123 @@ Agent 必须：
 4. 执行最小安全变更。
 5. 说明验证计划和残余风险。
 6. 让 Harness 运行验证并生成总结。
+7. 如果上一轮失败，只围绕失败原因做最小 rework。
 `;
-    await writeFile(paths.plan, plan, "utf8");
-    await audit.event({ stage: "plan", event: "plan_written", status: "succeeded", detail: { path: paths.plan } });
-    sayLive(live, `阶段协议已写入：${paths.plan}`);
-    const adapter = createAgentAdapter(agentName, config);
-    const agentCommand = agentName === "codex" ? config.agents.codex.command : config.agents.claude.command;
-    sayLive(live, `正在执行 ${adapter.name}：${agentCommand}`);
-    await audit.event({ stage: "execute", event: "agent_started", status: "started", detail: { agent: adapter.name, command: agentCommand } });
-    let agentResult;
-    try {
-        agentResult = await adapter.run({
-            cwd,
-            task,
-            skill,
-            contextPackPath: paths.contextPack,
-            promptPath: paths.agentPrompt,
-            executionLogPath: paths.executionLog,
-            live
+        await writeFile(iterationPaths.plan, plan, "utf8");
+        await audit.event({ stage: "plan", event: "plan_written", status: "succeeded", detail: { path: iterationPaths.plan, iteration } });
+        sayLive(live, `阶段协议已写入：${iterationPaths.plan}`);
+        sayLive(live, `正在执行 ${adapter.name}：${agentCommand}`);
+        await feedbackEvent(iterationPaths.feedback, "agent_invoked", { iteration, agent: adapter.name });
+        await audit.event({
+            stage: "execute",
+            event: "agent_started",
+            status: "started",
+            detail: { agent: adapter.name, command: agentCommand, iteration }
         });
+        try {
+            agentResult = await adapter.run({
+                cwd,
+                task,
+                skill,
+                contextPackPath: iterationPaths.contextPack,
+                promptPath: iterationPaths.agentPrompt,
+                executionLogPath: iterationPaths.executionLog,
+                live,
+                iteration,
+                previousFeedback
+            });
+            await audit.event({
+                stage: "execute",
+                event: "agent_finished",
+                status: agentResult.status === "success" ? "succeeded" : "failed",
+                detail: { iteration, exitCode: agentResult.exitCode, changedFiles: agentResult.changedFiles, error: agentResult.error }
+            });
+        }
+        catch (error) {
+            agentResult = {
+                status: "failed",
+                exitCode: null,
+                stdout: "",
+                stderr: "",
+                changedFiles: [],
+                diff: "",
+                error: error instanceof Error ? error.message : String(error)
+            };
+            await audit.event({ stage: "execute", event: "agent_error", status: "failed", detail: { iteration, error: agentResult.error } });
+        }
+        await writeFile(iterationPaths.gitDiff, agentResult.diff, "utf8");
+        contractCheck = checkAgentContract(`${agentResult.stdout}\n${agentResult.stderr}`);
+        await writeJson(iterationPaths.agentContract, contractCheck);
+        await feedbackEvent(iterationPaths.feedback, "agent_contract_checked", { iteration, status: contractCheck.status, missingSections: contractCheck.missingSections });
         await audit.event({
             stage: "execute",
-            event: "agent_finished",
-            status: agentResult.status === "success" ? "succeeded" : "failed",
-            detail: { exitCode: agentResult.exitCode, changedFiles: agentResult.changedFiles, error: agentResult.error }
+            event: "agent_contract_check",
+            status: contractCheck.status === "passed" ? "succeeded" : "failed",
+            detail: { iteration, contractCheck }
         });
-    }
-    catch (error) {
-        agentResult = {
-            status: "failed",
-            exitCode: null,
-            stdout: "",
-            stderr: "",
-            changedFiles: [],
-            diff: "",
-            error: error instanceof Error ? error.message : String(error)
+        sayLive(live, `Agent 执行完成：status=${agentResult.status} changedFiles=${agentResult.changedFiles.length} contract=${contractCheck.status}`);
+        sayLive(live, "正在运行验证命令");
+        await audit.event({ stage: "verify", event: "verify_started", status: "started", detail: { iteration } });
+        verifyResult = await runVerify(cwd, config, skill, iterationPaths.verify);
+        verifyDiagnostics = await writeVerifyDiagnostics(iterationPaths.verifyDiagnostics, verifyResult);
+        await feedbackEvent(iterationPaths.feedback, "verify_command_finished", { iteration, status: verifyResult.status });
+        await feedbackEvent(iterationPaths.feedback, "verify_diagnostics_created", { iteration, failedCommands: verifyDiagnostics.failedCommands.length });
+        await audit.event({
+            stage: "verify",
+            event: "verify_finished",
+            status: verifyResult.status === "passed" ? "succeeded" : "failed",
+            detail: { iteration, verifyResult }
+        });
+        sayLive(live, `验证完成：${verifyResult.status} ${iterationPaths.verify}`);
+        const agentOutput = `${agentResult.stdout}\n${agentResult.stderr}`;
+        contextScore = await writeContextScore(iterationPaths.contextScore, agentOutput);
+        await feedbackEvent(iterationPaths.feedback, "context_score_created", { iteration, status: contextScore.status, missing: contextScore.missing });
+        approval = await evaluateApprovalGate({
+            cwd,
+            config,
+            agentResult,
+            agentOutput,
+            approvalPath: iterationPaths.approvalRequired
+        });
+        if (approval.required)
+            await feedbackEvent(iterationPaths.feedback, "approval_gate_triggered", { iteration, reasons: approval.reasons });
+        agentResult.diff = await writePostIterationDiff(cwd, iterationPaths.postIterationDiff);
+        await writeFile(iterationPaths.gitDiff, agentResult.diff, "utf8");
+        const evaluation = evaluateIteration({
+            iteration,
+            maxIterations,
+            previous: evaluations.at(-1),
+            agentResult,
+            contractCheck,
+            verifyResult,
+            verifyDiagnostics,
+            contextScore,
+            approval
+        });
+        evaluations.push(evaluation);
+        const loopReview = {
+            status: evaluation.status === "passed" ? "passed" : "stopped",
+            maxIterations,
+            iterations: evaluations
         };
-        await audit.event({ stage: "execute", event: "agent_error", status: "failed", detail: agentResult.error });
+        await writeLoopArtifacts({ reviewPath: paths.loopReview, reportPath: paths.loopReport, review: loopReview });
+        await audit.event({
+            stage: "evaluate",
+            event: "iteration_evaluated",
+            status: evaluation.status === "passed" ? "succeeded" : "failed",
+            detail: evaluation
+        });
+        await feedbackEvent(iterationPaths.feedback, "loop_evaluated", { iteration, status: evaluation.status, failureType: evaluation.failureType });
+        await syncIterationSnapshot(paths, iterationPaths);
+        sayLive(live, `评估完成：${evaluation.status} failure=${evaluation.failureType}`);
+        if (evaluation.nextAction === "summarize")
+            break;
+        if (evaluation.nextAction === "stop")
+            break;
+        previousFeedback = renderReworkFeedback(evaluation);
+        await audit.event({ stage: "rework", event: "rework_scheduled", status: "started", detail: evaluation });
+        sayLive(live, `进入下一轮自纠偏：${evaluation.reason}`);
     }
-    await writeFile(paths.gitDiff, agentResult.diff, "utf8");
-    const contractCheck = checkAgentContract(`${agentResult.stdout}\n${agentResult.stderr}`);
-    await writeJson(paths.agentContract, contractCheck);
-    await audit.event({
-        stage: "execute",
-        event: "agent_contract_check",
-        status: contractCheck.status === "passed" ? "succeeded" : "failed",
-        detail: contractCheck
-    });
-    sayLive(live, `Agent 执行完成：status=${agentResult.status} changedFiles=${agentResult.changedFiles.length} contract=${contractCheck.status}`);
-    sayLive(live, "正在运行验证命令");
-    await audit.event({ stage: "verify", event: "verify_started", status: "started" });
-    const verifyResult = await runVerify(cwd, config, skill, paths.verify);
-    await audit.event({ stage: "verify", event: "verify_finished", status: verifyResult.status === "passed" ? "succeeded" : "failed", detail: verifyResult });
-    sayLive(live, `验证完成：${verifyResult.status} ${paths.verify}`);
     await writeSummary({
         task,
         skillName,
@@ -214,7 +369,8 @@ Agent 必须：
     await audit.event({ stage: "persist", event: "suggestions_written", status: "succeeded" });
     sayLive(live, `总结已写入：${paths.summary}`);
     sayLive(live, `知识沉淀建议已写入：${paths.persistSuggestions}`);
-    const runPassed = verifyResult.status === "passed" && agentResult.status === "success";
+    sayLive(live, `自纠偏报告已写入：${paths.loopReport}`);
+    const runPassed = evaluations.at(-1)?.status === "passed";
     await audit.event({ stage: "run", event: "run_finished", status: runPassed ? "succeeded" : "failed" });
     console.log(`运行完成：${paths.runId}`);
     console.log(`证据目录：${paths.runDir}`);
@@ -223,8 +379,8 @@ Agent 必须：
 }
 async function commandInstallIntegration(cwd, args) {
     const rawAgent = String(args.agent ?? "both");
-    if (rawAgent !== "claude" && rawAgent !== "codex" && rawAgent !== "both") {
-        throw new Error(`无效 --agent ${rawAgent}。期望 claude、codex 或 both。`);
+    if (rawAgent !== "claude" && rawAgent !== "codex" && rawAgent !== "cursor" && rawAgent !== "gemini" && rawAgent !== "both" && rawAgent !== "all") {
+        throw new Error(`无效 --agent ${rawAgent}。期望 claude、codex、cursor、gemini、both 或 all。`);
     }
     const targetDir = typeof args.target === "string" ? path.resolve(cwd, args.target) : cwd;
     const packageRoot = path.resolve(path.dirname(process.argv[1]), "..");
@@ -242,10 +398,48 @@ async function commandVerify(cwd, args) {
     const config = await loadConfig(cwd);
     const skill = await loadSkill(cwd, intake.skill);
     const result = await runVerify(cwd, config, skill, path.join(runDir, "verify.json"));
+    await writeVerifyDiagnostics(path.join(runDir, "verify_diagnostics.json"), result);
     const audit = new AuditLogger(path.join(runDir, "audit.jsonl"));
     await audit.event({ stage: "verify", event: "verify_rerun", status: result.status === "passed" ? "succeeded" : "failed", detail: result });
     console.log(`验证 ${result.status}：${runDir}`);
 }
+async function commandRestore(cwd, args) {
+    const runDir = await resolveRunDir(cwd, requireString(args, "run"));
+    const iteration = Number(requireString(args, "iteration"));
+    if (!Number.isInteger(iteration) || iteration < 1)
+        throw new Error("--iteration 必须是正整数");
+    const checkpointPath = path.join(runDir, `iteration-${iteration}`, "checkpoint.json");
+    if (!(await pathExists(checkpointPath)))
+        throw new Error(`未找到 checkpoint：${checkpointPath}`);
+    const checkpoint = JSON.parse(await readFile(checkpointPath, "utf8"));
+    const result = await restoreCheckpoint(cwd, checkpoint);
+    const audit = new AuditLogger(path.join(runDir, "audit.jsonl"));
+    await audit.event({ stage: "restore", event: "restore_requested", status: result.ok ? "succeeded" : "failed", detail: { iteration, message: result.message } });
+    console.log(result.message);
+    if (!result.ok)
+        throw new Error(`restore 失败：${result.message}`);
+}
+async function commandRuns(cwd, args) {
+    const [subcommand] = args._ ?? [];
+    if (subcommand !== "metrics")
+        throw new Error(`未知 runs 子命令：${subcommand ?? ""}`);
+    const config = await loadConfig(cwd);
+    const metrics = await collectRunMetrics(cwd, config);
+    if (args.json)
+        console.log(JSON.stringify(metrics, null, 2));
+    else
+        console.log(renderMetricsText(metrics));
+}
+async function commandReplay(cwd, args) {
+    const runDir = await resolveRunDir(cwd, requireString(args, "run"));
+    const overrideAgent = typeof args.agent === "string" ? requireAgent(args.agent) : undefined;
+    const dry = Boolean(args.dry);
+    const plan = await buildReplayPlan(runDir, overrideAgent, dry);
+    console.log(renderReplayPlan(plan));
+    if (dry)
+        return;
+    await commandRun(cwd, { task: plan.task, skill: plan.skill, agent: plan.agent });
+}
 async function commandSummarize(cwd, args) {
     const runDir = await resolveRunDir(cwd, requireString(args, "run"));
     const intake = JSON.parse(await readFile(path.join(runDir, "intake.json"), "utf8"));
@@ -286,12 +480,22 @@ async function main() {
     }
     if (command === "init")
         return commandInit(cwd);
+    if (command === "doctor")
+        return commandDoctor(cwd);
+    if (command === "smoke")
+        return commandSmoke(cwd, args);
     if (command === "run")
         return commandRun(cwd, args);
     if (command === "verify")
         return commandVerify(cwd, args);
     if (command === "summarize")
         return commandSummarize(cwd, args);
+    if (command === "restore")
+        return commandRestore(cwd, args);
+    if (command === "runs")
+        return commandRuns(cwd, args);
+    if (command === "replay")
+        return commandReplay(cwd, args);
     if (command === "install-integration")
         return commandInstallIntegration(cwd, args);
     throw new Error(`未知命令：${command}\n${usage()}`);

package/dist/config.js

@@ -4,7 +4,9 @@ import { pathExists, readTextIfExists } from "./utils.js";
 export const defaultConfig = {
     agents: {
         codex: { command: "codex exec --full-auto -" },
-        claude: { command: "claude -p -" }
+        claude: { command: "claude -p -" },
+        cursor: { command: "cursor-agent" },
+        gemini: { command: "gemini" }
     },
     mcp: {
         codegraph: { type: "http", url: "http://localhost:7331/mcp", headers: {} },
@@ -18,6 +20,21 @@ export const defaultConfig = {
     context: {
         fallbackInclude: ["AGENTS.md", "TOOLS.md", "SKILLS.md", "README.md", "package.json", "src"],
         exclude: ["node_modules", ".git", "dist", "build", ".next", "coverage", "runs"]
+    },
+    loop: {
+        maxIterations: 1,
+        stopOn: ["same_failure_repeated", "max_iterations_reached"]
+    },
+    policy: {
+        protectedPaths: [".github/", "scripts/release/", "security/"],
+        requireApproval: [
+            "protected_path_change",
+            "dependency_change",
+            "delete_files",
+            "public_api_change_declared",
+            "security_change_declared"
+        ],
+        approvalMode: "file"
     }
 };
 export function renderYaml(value, indent = 0) {
@@ -163,6 +180,8 @@ export async function loadConfig(cwd) {
     const verifyRoot = topSection(text, "verify");
     const verifySection = verifyRoot.match(/defaultCommands:\n([\s\S]*?)(?=^\S|^  [a-zA-Z][\w]*:|$)/m)?.[1] ?? "";
     const contextSection = topSection(text, "context");
+    const loopSection = topSection(text, "loop");
+    const policySection = topSection(text, "policy");
     const codegraphSection = indentedSection(text, "codegraph", 2);
     const knowledgeSection = indentedSection(text, "knowledgeGraph", 2);
     return {
@@ -172,6 +191,12 @@ export async function loadConfig(cwd) {
             },
             claude: {
                 command: String(scalar(text, /agents:\n[\s\S]*?claude:\n\s+command:\s*([^\n]+)/m, defaultConfig.agents.claude.command))
+            },
+            cursor: {
+                command: String(scalar(text, /agents:\n[\s\S]*?cursor:\n\s+command:\s*([^\n]+)/m, defaultConfig.agents.cursor.command))
+            },
+            gemini: {
+                command: String(scalar(text, /agents:\n[\s\S]*?gemini:\n\s+command:\s*([^\n]+)/m, defaultConfig.agents.gemini.command))
             }
         },
         mcp: {
@@ -200,6 +225,19 @@ export async function loadConfig(cwd) {
             exclude: blockList(contextSection, "exclude").length
                 ? blockList(contextSection, "exclude")
                 : defaultConfig.context.exclude
+        },
+        loop: {
+            maxIterations: Number(scalar(loopSection, /maxIterations:\s*([^\n]+)/m, defaultConfig.loop.maxIterations)),
+            stopOn: blockList(loopSection, "stopOn").length ? blockList(loopSection, "stopOn") : defaultConfig.loop.stopOn
+        },
+        policy: {
+            protectedPaths: blockList(policySection, "protectedPaths").length
+                ? blockList(policySection, "protectedPaths")
+                : defaultConfig.policy.protectedPaths,
+            requireApproval: blockList(policySection, "requireApproval").length
+                ? blockList(policySection, "requireApproval")
+                : defaultConfig.policy.requireApproval,
+            approvalMode: "file"
         }
     };
 }

package/dist/context.js

@@ -57,7 +57,9 @@ export async function buildContextPack(options) {
     const markdown = `# Context Pack
 
 ## How To Use This Context
-- CodeGraph and Knowledge Graph are agent-side MCP sources. Use Claude/Codex MCP tools directly before and during execution when available.
+- CodeGraph and Knowledge Graph are agent-side MCP sources. Use the current execution agent's MCP tools directly before and during execution when available.
+- For colbymchenry/codegraph, prefer the default codegraph_explore tool first. Ask it with the suspected flow, file, symbol, or behavior; use its grouped source, line-numbered source, call paths, dynamic dispatch hops, and blast-radius summary to build context.
+- For browser_knowledge_service, use progressive disclosure: list_path/search_docs/search_sections/search_chunks or hybrid_search/answer_context first, then read_doc_outline, then read_section/read_doc_range/read_chunk/get_related_chunks for exact evidence. Do not call propose_doc in Harness v1; write suggestions to persist_suggestions.md.
 - Harness records MCP configuration and audit evidence, but it does not implement MCP transport or replace the agent MCP client.
 - If the current agent cannot access an MCP source, explicitly mention the missing source and rely on fallback context carefully.
 - Do not assume fallback file snippets are complete repository knowledge.
@@ -69,17 +71,24 @@ Before editing, assemble context in this exact shape:
 
 ### MCP Preflight Findings
 - CodeGraph tools used:
+- CodeGraph primary query:
 - CodeGraph findings:
-  - Related files:
-  - Related symbols:
-  - Callers / dependencies:
-  - Impact scope:
+  - Source grouped by file:
+  - Current line-numbered source:
+  - Call paths:
+  - Dynamic dispatch hops:
+  - Blast-radius summary:
 - Knowledge Graph tools used:
 - Knowledge Graph findings:
+  - Search tools used:
+  - Candidate concept_ids:
+  - Read tools used:
+  - Evidence sections/chunks:
   - ADRs / decisions:
   - Module notes:
   - API notes:
   - Runbooks / known issues:
+  - Audit/backlink findings:
 - Missing context:
 
 ### Impact Analysis

package/dist/contextScore.js

@@ -0,0 +1,44 @@
+import { writeFile } from "node:fs/promises";
+function hasValueAfter(label, output) {
+    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = output.match(new RegExp(`${escaped}\\s*[:：]?\\s*([^\\n]+)`, "i"));
+    if (!match)
+        return false;
+    const value = match[1].trim();
+    return Boolean(value && !/^[-(]?\s*(none|n\/a|unknown|无|没有|未使用|缺失|不适用)/i.test(value));
+}
+function hasAnyValueAfter(labels, output) {
+    return labels.some((label) => hasValueAfter(label, output));
+}
+function hasAnyPattern(patterns, output) {
+    return patterns.some((pattern) => pattern.test(output));
+}
+export function createContextScore(output) {
+    const requiredFields = {
+        codegraphToolsUsed: hasAnyValueAfter(["CodeGraph tools used", "CodeGraph 工具", "CodeGraph 使用工具", "代码图谱工具"], output) ||
+            hasAnyPattern([/codegraph[_-]?\w+/i, /codegraph_explore/i], output),
+        blastRadiusSummary: hasAnyValueAfter(["Blast-radius summary", "Blast radius summary", "影响范围", "影响面", "变更影响范围"], output) ||
+            hasAnyPattern([/blast[_ -]?radius/i, /影响范围\s*[:：]\s*\S+/i], output),
+        knowledgeConceptIds: hasAnyValueAfter(["Candidate concept_ids", "Concept IDs", "候选 concept_ids", "知识库 concept_ids", "知识概念"], output) ||
+            hasAnyPattern([/concept[_ -]?ids?\s*[:：]\s*\S+/i, /\/[^ \n]+\/(overview|features|metrics|api|playbooks|references)\//i], output),
+        missingContextDeclared: hasAnyValueAfter(["Missing context", "缺失上下文", "上下文缺口", "未确认上下文"], output) ||
+            hasAnyPattern([/Missing context\s*[:：]/i, /缺失上下文\s*[:：]/i, /上下文缺口\s*[:：]/i], output)
+    };
+    const missing = Object.entries(requiredFields)
+        .filter(([, present]) => !present)
+        .map(([key]) => key);
+    const presentCount = Object.values(requiredFields).filter(Boolean).length;
+    return {
+        status: presentCount >= 4 ? "strong" : presentCount >= 2 ? "acceptable" : "weak",
+        requiredFields,
+        missing,
+        recommendation: missing.length
+            ? `下一轮请补充以下上下文证据：${missing.join(", ")}。`
+            : "上下文证据结构完整。"
+    };
+}
+export async function writeContextScore(path, output) {
+    const score = createContextScore(output);
+    await writeFile(path, `${JSON.stringify(score, null, 2)}\n`, "utf8");
+    return score;
+}