ai-dev-harness 0.1.0 → 0.1.2

package/README.md

@@ -1,82 +1,143 @@
 # AI Dev Harness
 
-Auditable TypeScript CLI harness that wraps Codex CLI or Claude Code, retrieves context from CodeGraph and Knowledge Graph MCP services, verifies changes, and writes local run evidence.
+AI Dev Harness 是一个可分发的 TypeScript CLI，用来把 Codex、Claude Code、Cursor Agent、Gemini CLI 的研发任务变成可审计的执行闭环。
 
-This repository is a distributable Harness package:
+它的核心定位不是替代 Agent，也不是实现 MCP Client，而是：
 
-- CLI: `dist/cli.js`
-- Claude/Codex conversation integration installer
-- Claude Skill package installed into `.claude/skills/ai-dev-harness/`
-- Agent helper scripts installed into `.harness/ai-dev-harness/scripts/`
-- Git-native project skills installed into `skills/`
+> 让大模型知道如何组装上下文、制定计划、执行任务、验证结果，并把整个生命周期记录下来。
 
-## Quick Start
+## 核心边界
+
+- Codex / Claude / Cursor / Gemini 负责：理解任务、调用 MCP、调用工具、使用 Skill、修改代码。
+- Harness 负责：执行闭环、过程日志、验证命令、审计证据、总结、沉淀建议。
+- CodeGraph / Knowledge Graph 是 Agent 侧 MCP 工具源，不是 Harness 内部服务依赖。
+- Harness 会记录 MCP source metadata，但不会记录 bearer token 原文。
+
+## 包内容
+
+- CLI：`dist/cli.js`
+- Claude/Codex/Cursor/Gemini 对话集成安装器
+- Claude Skill：`.claude/skills/ai-dev-harness/`
+- Agent 辅助脚本：`.harness/ai-dev-harness/scripts/`
+- Git-native 项目技能：`skills/`
+- 可编辑模板：`templates/`
+
+线上安装使用手册见 `ONLINE_INSTALL_GUIDE.md`。
+同事试用手册见 `COLLEAGUE_TRIAL_GUIDE.md`。
+
+## 快速开始
 
 ```bash
 npm install
 npm run build
 node dist/cli.js init
-node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent codex
+node dist/cli.js doctor
+node dist/cli.js smoke --agent codex --live
 ```
 
-The CLI is intended to be installed inside a business Git repository. `init` creates `harness.yaml`, `skills/`, `AGENTS.md`, `TOOLS.md`, `SKILLS.md`, and `runs/`.
-`harness run` must execute inside a Git repository; if it is launched elsewhere, the harness writes intake/audit evidence and exits nonzero.
+CLI 应在业务 Git 仓库内初始化。`init` 会创建 `harness.yaml`、`skills/`、`AGENTS.md`、`TOOLS.md`、`SKILLS.md` 和 `runs/`。
 
-## Commands
+## 命令
 
 ```bash
 node dist/cli.js init
+node dist/cli.js init --no-integration
+node dist/cli.js doctor
+node dist/cli.js smoke --agent claude --live
 node dist/cli.js run --task "add refund flow tests" --skill write_tests --agent claude
 node dist/cli.js run --task "analyze download startup flow. Do not modify repository files." --skill update_docs --agent claude --live
+node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent cursor --live
+node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent gemini --live
 node dist/cli.js verify --run <run_id_or_path>
 node dist/cli.js summarize --run <run_id_or_path>
-node dist/cli.js install-integration --agent both --target <repo>
+node dist/cli.js restore --run <run_id_or_path> --iteration 1
+node dist/cli.js runs metrics --json
+node dist/cli.js replay --run <run_id_or_path> --dry
+node dist/cli.js replay --run <run_id_or_path> --agent codex
+node dist/cli.js install-integration --agent all --target <repo>
 ```
 
-## Claude/Codex Conversation Trigger
+## Claude/Codex/Cursor/Gemini 对话触发
 
-Install conversation integration into a business repository:
+`harness init` 默认安装对话集成。也可以手动刷新：
 
 ```bash
-node "E:\ai native\dist\cli.js" install-integration --agent both --target "C:\path\to\repo"
+node "E:\ai native\dist\cli.js" install-integration --agent all --target "C:\path\to\repo"
 ```
 
-This creates:
+它会创建：
 
-- `.claude/skills/ai-dev-harness/SKILL.md` for Claude Code.
-- An `AGENTS.md` Harness section for Codex.
+- `.claude/skills/ai-dev-harness/SKILL.md`
+- `AGENTS.md` 中的 Harness 规则块
+- `.cursor/rules/ai-dev-harness.mdc`
+- `GEMINI.md` 中的 Harness 规则块
 - `.harness/ai-dev-harness/scripts/run-harness.ps1`
 - `.harness/ai-dev-harness/scripts/read-evidence.ps1`
 
-Then, inside Claude Code or Codex, ask naturally:
+然后在 Claude Code、Codex、Cursor 或 Gemini 中自然提问：
 
 ```text
 Use AI Dev Harness to run update_docs: analyze the download startup flow. Do not modify repository files.
 ```
 
-or:
+或：
 
 ```text
 Use Harness to run fix_bug: fix the download resume progress issue.
 ```
 
-The generated integration uses `--live`, so the current conversation terminal can see Harness stages and agent output as the run progresses.
+集成脚本默认使用 `--live`，所以当前对话终端能看到 Harness 阶段日志和 Agent 输出。
 
-The installed Skill prefers the helper script:
+## MCP Preflight
 
-```bash
-powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill fix_bug -Agent claude -Live
-```
+Harness 不直接调用 MCP。Agent 应在触发 Harness 前使用自己已配置的 MCP 工具，并按以下格式汇报：
 
-The direct CLI command remains available as a fallback:
+如果 CodeGraph 使用的是 `colbymchenry/codegraph`，默认优先调用 `codegraph_explore`。用任务里的业务流程、文件路径、函数/类/符号名或错误现象作为 query，并重点读取它返回的 grouped source、line-numbered source、call paths、dynamic dispatch hops 和 blast-radius summary。
 
-```bash
-node "E:\ai native\dist\cli.js" run --task "<task>" --skill fix_bug --agent claude --live
+如果 Knowledge Graph 使用的是 `browser_knowledge_service`，推荐读取顺序：
+
+1. 用 `list_path`、`search_docs`、`search_sections`、`search_chunks` 缩小范围。
+2. RAG 场景优先用 `answer_context`；需要自控排序时用 `hybrid_search`。
+3. 定位 concept_id 后先用 `read_doc_outline` 看结构。
+4. 再用 `read_section`、`read_doc_range`、`read_chunk`、`get_related_chunks` 精读证据。
+5. 需要关系时用 `get_backlinks`，需要近期变更记录时用 `get_audit_log`。
+6. v1 不直接调用 `propose_doc` 写入知识库；只生成 `persist_suggestions.md`。
+
+```text
+## MCP Preflight Findings
+- CodeGraph tools used:
+- CodeGraph primary query:
+- Source grouped by file:
+- Current line-numbered source:
+- Call paths:
+- Dynamic dispatch hops:
+- Blast-radius summary:
+- Knowledge Graph tools used:
+- Candidate concept_ids:
+- Read tools used:
+- Evidence sections/chunks:
+- ADRs / decisions:
+- Module notes:
+- API notes / runbooks:
+- Audit/backlink findings:
+- Missing context:
 ```
 
-## Configuration
+关键 MCP 发现应被带入 Harness 的任务文本，进入审计证据。
+
+## OKF 知识沉淀
+
+`persist_suggestions.md` 按 PC 浏览器团队知识库规范生成 OKF 候选内容，不自动写入 Knowledge Graph。
+
+- 候选文档路径应落到 `/<project>/overview/`、`/<project>/features/`、`/<project>/metrics/`、`/<project>/api/`、`/<project>/playbooks/` 或 `/<project>/references/`。
+- 每个候选 concept 应包含 `type`、`title`、`description`、`tags`、`timestamp`；API/数据类建议补充 `resource`。
+- `## 相关` 必须使用有效 Markdown 链接，推荐 bundle 根相对路径。
+- `type: API Reference` 需要包含 `## 关键实现锚点` 和 `### Agent 使用建议`。
+- 合入知识库前应同步更新对应目录的 `index.md` 和 `log.md`，并人工检查敏感信息。
 
-Edit `harness.yaml` in the business repository:
+## 配置
+
+编辑业务仓库里的 `harness.yaml`：
 
 ```yaml
 agents:
@@ -84,11 +145,20 @@ agents:
     command: codex exec --full-auto -
   claude:
     command: claude -p -
+  cursor:
+    command: cursor-agent
+  gemini:
+    command: gemini
 mcp:
   codegraph:
+    type: sse
     url: http://localhost:7331/mcp
+    headers: {}
   knowledgeGraph:
+    type: http
     url: http://localhost:7332/mcp
+    headers:
+      Authorization: Bearer ${OKF_TOKEN}
   timeoutMs: 15000
 verify:
   defaultCommands:
@@ -96,36 +166,165 @@ verify:
       command: git status --short
 audit:
   path: 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
+```
+
+MCP header 支持环境变量，例如 `${OKF_TOKEN}`。不要把真实 token 提交到 Git。
+
+`agents.*.command` 都可以按团队机器上的实际 CLI 改写。Harness 统一通过 stdin 把最终 prompt 传给执行器，不绑定 Codex、Claude、Cursor 或 Gemini 的内部能力。
+
+## 自纠偏循环
+
+Harness 会在每轮执行后进入 `Evaluate` 阶段，判断是否完成目标、Agent 契约是否满足、验证是否通过。
+
+默认 `loop.maxIterations: 1`，行为等同单轮执行。需要开启低风险自动重做时，在业务仓库 `harness.yaml` 中调大：
+
+```yaml
+loop:
+  maxIterations: 2
+  stopOn:
+    - same_failure_repeated
+    - max_iterations_reached
+```
+
+会自动进入下一轮的典型情况：
+
+- Agent 命令失败。
+- Agent 输出缺少 `Impact Analysis / Plan / Execution Notes / Verification Notes / Final Report`。
+- 验证命令失败。
+
+会停止并要求人工评审的典型情况：
+
+- 连续两轮出现同一种失败。
+- 达到最大循环轮次。
+- Agent 在报告里说明目标不明确、需要扩大范围、要改公共接口或安全策略。
+
+## 运行证据
+
+每次 `run` 会创建 `runs/<run_id>/`：
+
+- `intake.json`：任务、skill、agent、Git 状态。
+- `mcp_queries.jsonl`：Agent-driven MCP source metadata，不包含 token 原文。
+- `context_pack.md`：上下文组装协议、MCP source 记录、本地兜底上下文。
+- `agent_prompt.md`：发送给当前执行器的最终提示词。
+- `plan.md`：Harness 执行阶段协议。
+- `execution.log`：Agent stdout/stderr。
+- `agent_contract.json`：Agent 必需章节检查结果。
+- `git_diff.patch`：代码变更。
+- `verify.json`：验证结果。
+- `verify_diagnostics.json`：从验证 stdout/stderr 提取的通用失败诊断。
+- `context_score.json`：Agent 是否按协议提供上下文证据的结构化评分。
+- `approval_required.json`：机械审批门禁结果。
+- `feedback.jsonl`：Harness 可见机器反馈事件，不记录 Agent 内部工具调用。
+- `checkpoint.json`：本轮 Git checkpoint 和 restore 支持状态。
+- `pre_iteration_diff.patch` / `post_iteration_diff.patch`：本轮前后 diff。
+- `loop_review.json`：每轮评估、失败归因和下一步动作。
+- `loop_report.md`：自纠偏循环的人类可读报告。
+- `summary.md`：评审/PR 总结。
+- `persist_suggestions.md`：知识沉淀建议。
+- `audit.jsonl`：完整审计事件流。
+
+Harness 会检查 Agent 输出是否包含以下章节：
+
+- `Impact Analysis`
+- `Plan`
+- `Execution Notes`
+- `Verification Notes`
+- `Final Report`
+
+检查结果写入 `agent_contract.json`，并记录到 `audit.jsonl`。
+
+每轮循环会额外生成 `iteration-<n>/` 子目录。根目录同名文件是最后一轮快照，方便旧脚本继续读取。
+
+## Checkpoint / Restore
+
+Harness 每轮开始记录 checkpoint。只有运行开始前工作区是 clean，才允许自动 restore：
+
+```bash
+node dist/cli.js restore --run <run_id_or_path> --iteration 1
+```
+
+如果运行前已有未提交改动，Harness 会拒绝自动恢复，避免覆盖用户手工改动。
+
+## Approval Gate
+
+Harness 只做机械门禁，不判断业务方案。默认会在以下情况写入 `approval_required.json` 并停止：
+
+- 命中 `policy.protectedPaths`。
+- 修改依赖文件，例如 `package.json`、lockfile。
+- 删除文件。
+- Agent 最终报告声明 `public_api_change_declared` 或 `security_change_declared`。
+
+## Metrics / Replay
+
+读取本地 `runs/` 证据生成运行指标：
+
+```bash
+node dist/cli.js runs metrics
+node dist/cli.js runs metrics --json
 ```
 
-The agent command receives the generated prompt on stdin. CodeGraph and Knowledge Graph MCP are queried first; if either service is unavailable, the run is marked degraded and the harness falls back to local Git/file context.
-If the agent command or verification fails, the run still writes all evidence files and then exits nonzero so CI can treat the run as failed.
+Replay 复用历史 run 的 task 和 skill，创建新的 run，不覆盖旧证据：
 
-## Run Evidence
+```bash
+node dist/cli.js replay --run <run_id_or_path> --dry
+node dist/cli.js replay --run <run_id_or_path> --agent claude
+```
 
-Each `run` creates `runs/<run_id>/` with:
+## Skill 规范
 
-- `intake.json`
-- `mcp_queries.jsonl`
-- `context_pack.md`
-- `agent_prompt.md`
-- `plan.md`
-- `execution.log`
-- `git_diff.patch`
-- `verify.json`
-- `summary.md`
-- `persist_suggestions.md`
-- `audit.jsonl`
+内置 skill 会通过 `context.yaml` 告诉 Agent：
 
-Knowledge Graph updates are not applied automatically in v1. Review `persist_suggestions.md` before writing them back.
+- 应该从 CodeGraph MCP 查询什么。
+- 应该从 Knowledge Graph MCP 查询什么。
+- 什么情况下必须停止，不要猜。
+- 本地兜底上下文应包含哪些路径。
 
-## Engineering Prompt Contracts
+示例：
 
-Generated skills and agent prompts use a company-grade execution contract:
+```yaml
+mcp_preflight:
+  codegraph:
+    required: true
+    primary_tool: codegraph_explore
+    ask_for:
+      - relevant_source_grouped_by_file
+      - current_line_numbered_source_for_known_file_or_symbol
+      - call_paths_between_related_symbols
+      - dynamic_dispatch_hops
+      - blast_radius_summary
+  knowledgeGraph:
+    required: true
+    ask_for:
+      - search_docs_or_search_chunks_for_defect_terms
+      - answer_context_for_direct_rag_context
+      - read_doc_outline_for_relevant_concepts
+      - read_section_or_read_doc_range_for_evidence
+      - get_backlinks_for_related_decisions
+stop_conditions:
+  - root cause is unclear
+  - impact scope cannot be determined
+```
 
-- Analysis Contract: restate the task, list assumptions, affected areas, risks, and missing context.
-- Execution Contract: make only task-relevant minimal changes; no opportunistic refactors or broad cleanup.
-- Verification Contract: run configured verification or record why checks could not run.
-- Report Contract: summarize intent or root cause, changed files, verification, residual risk, and knowledge suggestions.
+## 验证
 
-The test suite verifies that initialized skills and run evidence include these contracts.
+```bash
+npm test
+npm pack --dry-run
+```

package/dist/agent.js

@@ -1,54 +1,90 @@
 import { appendFile, readFile, writeFile } from "node:fs/promises";
 import { git, runCommand, truncate } from "./utils.js";
 function renderPrompt(input, contextPack) {
-    return `You are running inside an auditable AI development harness. Treat this as a company engineering task, not a casual chat.
+    return `你正在一个可审计的 AI 研发 Harness 中执行任务。请把它当作公司级研发任务，而不是随意聊天。
 
-Task:
+当前循环轮次:
+${input.iteration ?? 1}
+
+任务:
 ${input.task}
 
 Skill:
 ${input.skill.name}
 
-Execution Contract:
-1. Analysis first.
-   - Restate the task in one or two sentences.
-   - Identify assumptions, affected files/modules, relevant CodeGraph context, relevant Knowledge Graph context, and risks.
-   - If required context is missing or confidence is low, stop and report what is missing instead of guessing.
-2. Plan before editing.
-   - Provide a minimal step-by-step plan.
-   - Keep the plan limited to the requested task.
-3. Safe execution.
-   - Make the smallest task-relevant change.
-   - Do not perform opportunistic refactors, formatting-only sweeps, dependency upgrades, broad renames, or unrelated cleanup.
-   - Preserve public interfaces and backward compatibility unless explicitly instructed otherwise.
-   - Do not update Knowledge Graph directly.
-4. Verification discipline.
-   - Harness will run configured verification after you finish.
-   - Only run extra commands when needed to understand or validate the task.
-   - Report any verification you could not run and why.
-5. Required final report.
-   - Root cause or implementation intent.
-   - Files changed.
-   - Verification performed or deferred.
-   - Residual risk.
-   - Knowledge persistence suggestions.
+执行契约:
+1. 先分析。
+   - 用一两句话复述任务。
+   - 识别假设、受影响文件/模块、CodeGraph 上下文、Knowledge Graph 上下文和风险。
+   - 如果关键上下文缺失或信心不足，停止并说明缺什么，不要猜。
+2. 先计划再修改。
+   - 给出最小步骤计划。
+   - 计划必须限定在当前任务范围内。
+3. 安全执行。
+   - 只做和任务相关的最小变更。
+   - 不做机会主义重构、纯格式化清扫、依赖升级、大范围重命名或无关清理。
+   - 除非任务明确要求，否则保持公共接口和向后兼容。
+   - 不直接写入 Knowledge Graph。
+4. 验证纪律。
+   - Harness 会在你完成后运行配置的验证命令。
+   - 只有在理解或验证任务确实需要时才额外运行命令。
+   - 说明无法执行的验证及原因。
+5. 必须输出最终报告。
+   - 根因或实现意图。
+   - 修改文件。
+   - 已执行或延后的验证。
+   - 残余风险。
+   - 知识沉淀建议。建议必须遵循 OKF v0.1 扩展：说明建议写入的项目目录、子域、type、title、description、相关 concept 链接、index.md/log.md 更新项；API 文档还要说明关键实现锚点和 Agent 使用建议。
+
+自纠偏规则:
+- 如果这是第 2 轮或更高轮次，先阅读上一轮失败诊断，只围绕失败原因做最小 rework。
+- 不要因为验证失败就绕过验证或删除验证。
+- 如果需要扩大范围、改公共接口、修改安全策略、或目标本身不明确，请停止并在 Final Report 中说明需要人工确认。
 
-Output Format:
+${input.previousFeedback ? `上一轮反馈:\n${input.previousFeedback}\n` : ""}
+
+必须使用以下输出格式，标题不要改名:
 ## Impact Analysis
 ## Plan
 ## Execution Notes
 ## Verification Notes
 ## Final Report
 
-Project Rules:
-- Respect AGENTS.md, TOOLS.md, and SKILLS.md when present.
-- Work inside this repository only.
-- Leave an auditable, reviewable result.
+项目规则:
+- 遵守 AGENTS.md、TOOLS.md 和 SKILLS.md。
+- 只在当前仓库内工作。
+- 留下可审计、可复查的结果。
 
-Context pack:
+Context Pack:
 ${contextPack}
 `;
 }
+export function checkAgentContract(output) {
+    const required = ["Impact Analysis", "Plan", "Execution Notes", "Verification Notes", "Final Report"];
+    const requiredSections = required.map((name) => ({
+        name,
+        present: new RegExp(`^##\\s+${name}\\s*$`, "im").test(output)
+    }));
+    const missingSections = requiredSections.filter((section) => !section.present).map((section) => section.name);
+    return {
+        status: missingSections.length ? "failed" : "passed",
+        requiredSections,
+        missingSections
+    };
+}
+function parseChangedFiles(status) {
+    return status
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const rename = line.match(/^R\s+(.+)\s+->\s+(.+)$/);
+        if (rename)
+            return rename[2];
+        return line.slice(3).trim();
+    })
+        .filter(Boolean);
+}
 async function executeAgent(input) {
     const contextPack = await readFile(input.contextPackPath, "utf8");
     const prompt = renderPrompt(input, contextPack);
@@ -60,9 +96,9 @@ async function executeAgent(input) {
         stderrPrefix: `[${input.agent}:stderr] `
     });
     await appendFile(input.executionLogPath, `## STDOUT\n${result.stdout}\n\n## STDERR\n${result.stderr}\n`, "utf8");
-    const changedFilesRaw = await git(input.cwd, "diff --name-only");
+    const changedFilesRaw = await git(input.cwd, "status --porcelain");
     const diff = await git(input.cwd, "diff --no-ext-diff");
-    const changedFiles = changedFilesRaw ? changedFilesRaw.split(/\r?\n/).filter(Boolean) : [];
+    const changedFiles = changedFilesRaw ? parseChangedFiles(changedFilesRaw) : [];
     return {
         status: result.exitCode === 0 ? "success" : "failed",
         exitCode: result.exitCode,
@@ -73,20 +109,11 @@ async function executeAgent(input) {
         error: result.exitCode === 0 ? undefined : `Agent command failed with exit code ${result.exitCode}`
     };
 }
-export class CodexAdapter {
-    command;
-    name = "codex";
-    constructor(command) {
-        this.command = command;
-    }
-    run(input) {
-        return executeAgent({ ...input, agent: this.name, command: this.command });
-    }
-}
-export class ClaudeAdapter {
+export class CliAgentAdapter {
+    name;
     command;
-    name = "claude";
-    constructor(command) {
+    constructor(name, command) {
+        this.name = name;
         this.command = command;
     }
     run(input) {
@@ -94,7 +121,5 @@ export class ClaudeAdapter {
     }
 }
 export function createAgentAdapter(agent, config) {
-    if (agent === "codex")
-        return new CodexAdapter(config.agents.codex.command);
-    return new ClaudeAdapter(config.agents.claude.command);
+    return new CliAgentAdapter(agent, config.agents[agent].command);
 }

package/dist/approval.js

@@ -0,0 +1,64 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { git } from "./utils.js";
+function normalizeRel(file) {
+    return file.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function matchesProtected(file, protectedPath) {
+    const normalized = normalizeRel(file);
+    const protectedNormalized = normalizeRel(protectedPath).replace(/\/?$/, "/");
+    return normalized === protectedNormalized.slice(0, -1) || normalized.startsWith(protectedNormalized);
+}
+function dependencyFile(file) {
+    const base = path.basename(file).toLowerCase();
+    return ["package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "requirements.txt", "poetry.lock", "go.mod", "go.sum", "cargo.toml", "cargo.lock"].includes(base);
+}
+function declaredRisk(output, marker) {
+    return new RegExp(marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i").test(output);
+}
+function deletedFilesFromNameStatus(nameStatus) {
+    return nameStatus
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("D\t"))
+        .map((line) => normalizeRel(line.slice(2)));
+}
+export async function evaluateApprovalGate(options) {
+    const changedFiles = options.agentResult.changedFiles.map(normalizeRel);
+    const unstagedNameStatus = await git(options.cwd, "diff --name-status");
+    const stagedNameStatus = await git(options.cwd, "diff --cached --name-status");
+    const deleted = Array.from(new Set([...deletedFilesFromNameStatus(unstagedNameStatus), ...deletedFilesFromNameStatus(stagedNameStatus)]));
+    const reasons = [];
+    const required = new Set(options.config.policy.requireApproval);
+    if (required.has("protected_path_change")) {
+        for (const file of changedFiles) {
+            const matched = options.config.policy.protectedPaths.find((protectedPath) => matchesProtected(file, protectedPath));
+            if (matched)
+                reasons.push({ type: "protected_path_change", detail: `${file} matches ${matched}` });
+        }
+    }
+    if (required.has("dependency_change")) {
+        for (const file of changedFiles.filter(dependencyFile))
+            reasons.push({ type: "dependency_change", detail: file });
+    }
+    if (required.has("delete_files")) {
+        for (const file of deleted)
+            reasons.push({ type: "delete_files", detail: file });
+    }
+    if (required.has("public_api_change_declared") && declaredRisk(options.agentOutput, "public_api_change_declared")) {
+        reasons.push({ type: "public_api_change_declared", detail: "Agent declared public API change." });
+    }
+    if (required.has("security_change_declared") && declaredRisk(options.agentOutput, "security_change_declared")) {
+        reasons.push({ type: "security_change_declared", detail: "Agent declared security change." });
+    }
+    const approval = {
+        required: reasons.length > 0,
+        reasons,
+        changedFiles,
+        mode: "file",
+        message: reasons.length
+            ? "Harness 已停止：本次变更触发审批门禁，请人工评审 approval_required.json。"
+            : "未触发审批门禁。"
+    };
+    await writeFile(options.approvalPath, `${JSON.stringify(approval, null, 2)}\n`, "utf8");
+    return approval;
+}

package/dist/audit.js

@@ -17,5 +17,6 @@ export async function prepareRunFiles(paths) {
     await ensureDir(paths.runDir);
     await writeJson(paths.intake, {});
     await writeFile(paths.mcpQueries, "", "utf8");
+    await writeFile(paths.feedback, "", "utf8");
     await writeFile(paths.audit, "", "utf8");
 }