ai-dev-harness 0.1.1 → 0.1.3

package/dist/summarize.js

@@ -30,7 +30,7 @@ ${options.agentName}
 - 确认变更限定在任务范围内。
 - 确认公共接口和向后兼容性没有被意外破坏。
 - 确认失败或跳过的验证项已被理解。
-- 确认知识沉淀建议经过人工评审后再写入 Knowledge Graph。
+- 确认知识沉淀建议符合 OKF v0.1 + 团队扩展规范，并经过人工评审后再写入 Knowledge Graph。
 
 ## PR 描述草稿
 ### 变更内容
@@ -46,7 +46,7 @@ ${options.verifyResult?.commands.map((cmd) => `- ${cmd.name}: ${cmd.exitCode ===
 - 合并前需要评审正确性、安全性、兼容性和知识沉淀建议。
 
 ### 知识沉淀跟进
-- 写入 Knowledge Graph 前先评审 persist_suggestions.md。
+- 写入 Knowledge Graph 前先评审 persist_suggestions.md，确认目标项目目录、frontmatter、相关链接、index.md 和 log.md 更新项。
 
 ## Diff 快照
 \`\`\`diff
@@ -55,20 +55,148 @@ ${truncate(diff, 12000)}
 `;
     const persist = `# 知识沉淀建议
 
-写入 Knowledge Graph 前，请先人工评审这些建议。
+写入 Knowledge Graph 前，请先人工评审这些建议。本文只生成 OKF 候选内容，不自动写入知识库。
 
 - 任务: ${options.task}
 - Skill: ${options.skillName}
 - 修改文件: ${options.agentResult?.changedFiles.join(", ") || "无"}
 - 沉淀策略: 写入 Knowledge Graph 前必须人工评审。
-- 建议沉淀类型:
-  - ADR Candidate: 如果实现涉及有意义的技术取舍，补充决策记录。
-  - Module Note Candidate: 如果变更澄清了模块职责或行为，补充模块说明。
-  - API Note Candidate: 如果接口语义、入参、返回值或兼容性有变化，补充接口说明。
-  - Runbook Candidate: 如果验证或排障暴露了可复用步骤，补充运行手册。
-  - Test Knowledge Candidate: 如果新增了典型测试场景，补充测试知识。
-  - Skill Improvement Candidate: 如果本次任务暴露 Skill 缺口，补充 Skill 改进建议。
-  - Missing Context Candidate: 如果缺少 Agent 侧 MCP 上下文影响了信心，记录缺失项。
+- 知识库规范: OKF v0.1 + PC 浏览器团队扩展。
+
+## OKF 写作规则
+
+- 每个知识文档是一个 concept，concept_id 等于文件路径去掉 \`.md\` 后缀。
+- 新文档放入具体项目目录，例如 \`/zero/\`、\`/se/\`、\`/yuntun/\`。
+- 子域优先选择 \`overview\`、\`features\`、\`metrics\`、\`api\`、\`playbooks\`、\`references\`。
+- 普通知识文档必须包含 YAML frontmatter: \`type\`、\`title\`、\`description\`、\`tags\`、\`timestamp\`；API/数据类建议补充 \`resource\`。
+- \`## 相关\` 必须使用有效 Markdown 链接，推荐 bundle 根相对路径，例如 \`/zero/features/fast-launch.md\`。
+- API Reference 必须补充 \`## 关键实现锚点\` 和 \`### Agent 使用建议\`。
+- 不写入密钥、Token、明文密码、未脱敏用户数据、未公开内网 IP；内网链接使用占位符域名。
+- 合入知识库时同步更新对应目录的 \`index.md\` 和 \`log.md\`。
+
+## 建议候选文档
+
+### Candidate 1: Feature / Module Note
+
+- 适用条件: 本次变更澄清了功能行为、模块职责、边界条件或实现约束。
+- 建议路径: \`/<project>/features/<feature-or-module>.md\`
+- 建议 type: \`Feature\`
+
+\`\`\`\`markdown
+---
+type: Feature
+title: <功能或模块名称>
+description: <一句话说明这个功能/模块解决什么问题，以及本次变更沉淀了什么>
+tags: [<project>, <feature-or-module>]
+timestamp: ${new Date().toISOString()}
+---
+
+## 背景 / 设计目标
+
+- <为什么需要这个功能或这次变更>
+
+## 方案 / 实现
+
+- <关键实现路径、主要流程、重要约束>
+- 相关代码: \`${options.agentResult?.changedFiles[0] ?? "<path/to/code>"}\`
+
+## 注意事项 / 已知限制
+
+- <边界条件、兼容性、风险点>
+
+## 相关
+
+- [相关文档](/<project>/<domain>/<doc>.md)
+\`\`\`\`
+
+### Candidate 2: API Reference
+
+- 适用条件: 本次变更涉及接口语义、入参、返回值、兼容性或调用链。
+- 建议路径: \`/<project>/api/<api-name>.md\`
+- 建议 type: \`API Reference\`
+
+\`\`\`\`markdown
+---
+type: API Reference
+title: <接口名称>
+description: <一句话说明接口职责和主要调用场景>
+resource: <endpoint-or-openapi-placeholder>
+tags: [<project>, api]
+timestamp: ${new Date().toISOString()}
+---
+
+## 关键实现锚点
+- 模块: \`<代码仓库中的模块路径>\`
+- 类/组件: \`<核心类、Handler 或入口函数>\`
+- 补充入口: \`<配置、部署脚本或 Playbook 路径>\`
+
+### Agent 使用建议
+
+需要实现细节时，继续用 CodeGraph 查询真实调用链和影响面。
+
+# Schema
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| <field> | <type> | <yes/no> | <description> |
+
+# Examples
+
+\`\`\`json
+{
+  "example": true
+}
+\`\`\`
+
+## 相关
+
+- [相关功能](/<project>/features/<feature>.md)
+\`\`\`\`
+
+### Candidate 3: Playbook / Test Knowledge
+
+- 适用条件: 本次修复、验证、回滚或排障步骤可复用。
+- 建议路径: \`/<project>/playbooks/<scenario>.md\`
+- 建议 type: \`Playbook\`
+
+\`\`\`\`markdown
+---
+type: Playbook
+title: <场景处理手册>
+description: <一句话说明该手册解决什么操作/排障场景>
+tags: [<project>, playbook]
+timestamp: ${new Date().toISOString()}
+---
+
+## 适用场景
+
+- <什么情况下使用>
+
+## 操作步骤
+
+1. <步骤一>
+2. <步骤二>
+3. <验证结果>
+
+## 风险与回滚
+
+- <风险>
+- <回滚方式>
+
+## 相关
+
+- [相关功能](/<project>/features/<feature>.md)
+\`\`\`\`
+
+## index.md / log.md 更新建议
+
+- \`index.md\`: 添加新文档链接和一句话 description。
+- \`log.md\`: 最新日期在前，使用 \`**Creation**\`、\`**Update**\`、\`**Deprecation**\` 或 \`**Deletion**\`。
+
+## 缺失上下文记录
+
+- Missing Context Candidate: 如果缺少 CodeGraph 或 Knowledge Graph 证据影响判断，请记录缺失的工具、query、concept_id 或代码路径。
+- Skill Improvement Candidate: 如果本次任务暴露 Skill 输入、验证命令或 MCP 使用规则缺口，请记录到 Skill 改进建议。
 `;
     await writeFile(options.summaryPath, summary, "utf8");
     await writeFile(options.persistPath, persist, "utf8");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-dev-harness",
-  "version": "0.1.1",
-  "description": "Auditable AI development harness for Codex and Claude Code.",
+  "version": "0.1.3",
+  "description": "Auditable AI development harness for Codex, Claude Code, Cursor Agent, and Gemini CLI.",
   "license": "MIT",
   "keywords": [
     "ai",
@@ -23,6 +23,7 @@
     "scripts/",
     "templates/",
     "README.md",
+    "ONLINE_INSTALL_GUIDE.md",
     "COLLEAGUE_TRIAL_GUIDE.md",
     "package.json"
   ],

package/scripts/read-evidence.ps1

@@ -18,7 +18,13 @@ Write-Host "[harness-skill] 证据目录: $runPath"
 
 $summary = Join-Path $runPath "summary.md"
 $verify = Join-Path $runPath "verify.json"
+$verifyDiagnostics = Join-Path $runPath "verify_diagnostics.json"
 $contract = Join-Path $runPath "agent_contract.json"
+$contextScore = Join-Path $runPath "context_score.json"
+$approval = Join-Path $runPath "approval_required.json"
+$checkpoint = Join-Path $runPath "checkpoint.json"
+$loopReview = Join-Path $runPath "loop_review.json"
+$loopReport = Join-Path $runPath "loop_report.md"
 $audit = Join-Path $runPath "audit.jsonl"
 
 if (Test-Path -LiteralPath $summary) {
@@ -31,12 +37,42 @@ if (Test-Path -LiteralPath $verify) {
   Get-Content -LiteralPath $verify
 }
 
+if (Test-Path -LiteralPath $verifyDiagnostics) {
+  Write-Host "`n--- verify_diagnostics.json ---"
+  Get-Content -LiteralPath $verifyDiagnostics
+}
+
 if (Test-Path -LiteralPath $contract) {
   Write-Host "`n--- agent_contract.json ---"
   Get-Content -LiteralPath $contract
 }
 
+if (Test-Path -LiteralPath $contextScore) {
+  Write-Host "`n--- context_score.json ---"
+  Get-Content -LiteralPath $contextScore
+}
+
+if (Test-Path -LiteralPath $approval) {
+  Write-Host "`n--- approval_required.json ---"
+  Get-Content -LiteralPath $approval
+}
+
+if (Test-Path -LiteralPath $checkpoint) {
+  Write-Host "`n--- checkpoint.json ---"
+  Get-Content -LiteralPath $checkpoint
+}
+
+if (Test-Path -LiteralPath $loopReview) {
+  Write-Host "`n--- loop_review.json ---"
+  Get-Content -LiteralPath $loopReview
+}
+
+if (Test-Path -LiteralPath $loopReport) {
+  Write-Host "`n--- loop_report.md ---"
+  Get-Content -LiteralPath $loopReport
+}
+
 if (Test-Path -LiteralPath $audit) {
   Write-Host "`n--- 审计失败/错误 ---"
-  Select-String -LiteralPath $audit -Pattern "failed|error|run_finished" | ForEach-Object { $_.Line }
+  Select-String -LiteralPath $audit -Pattern "failed|error|evaluate|rework|approval|restore|run_finished" | ForEach-Object { $_.Line }
 }

package/scripts/run-harness.ps1

@@ -7,7 +7,7 @@ param(
   [string]$Skill,
 
   [Parameter(Mandatory = $true)]
-  [ValidateSet("claude", "codex")]
+  [ValidateSet("claude", "codex", "cursor", "gemini")]
   [string]$Agent,
 
   [string]$Repo = (Get-Location).Path,

package/templates/default-project/TOOLS.md

@@ -1,8 +1,11 @@
 # Tool Rules
 
-- Codex and Claude Code are execution agents.
-- CodeGraph MCP is used by Claude/Codex for code impact context.
-- Knowledge Graph MCP is used by Claude/Codex for ADR, module, API, runbook, and decision context.
+- Codex, Claude Code, Cursor Agent, and Gemini CLI are supported execution agents.
+- CodeGraph MCP is used by the current execution agent for code impact context.
+- Knowledge Graph MCP is used by the current execution agent for ADR, module, API, runbook, and decision context.
 - Verification commands are defined in harness.yaml and skill verify.yaml files.
 - Harness run evidence is stored in runs/<run_id>/ and must be treated as the audit record.
+- Correction loop evaluation is stored in loop_review.json and loop_report.md.
+- Verification diagnostics, context score, approval gate, feedback events, and checkpoints are Harness evidence only; agents still own code understanding and implementation.
 - Knowledge Graph is read-only in v1. Write suggestions to persist_suggestions.md only.
+- Knowledge persistence suggestions must follow OKF v0.1 + PC browser team rules: choose the right project/domain path, include frontmatter, use valid Markdown links, add API implementation anchors when needed, and remind humans to update index.md and log.md.

package/templates/default-project/skills/add_feature/context.yaml

@@ -1,29 +1,32 @@
 queries:
-  - related files
-  - symbols
-  - call graph
-  - dependencies
-  - impact analysis
+  - use codegraph_explore for the target feature area or user-facing flow
+  - ask how the existing flow works before adding behavior
+  - ask for integration points and public interfaces
+  - ask for blast-radius summary before editing
 mcp_preflight:
   codegraph:
     required: true
+    primary_tool: codegraph_explore
     ask_for:
-      - related_files
-      - extension_points
-      - dependent_modules
-      - public_interfaces
-      - impact_scope
+      - existing_flow_source_grouped_by_file
+      - integration_points
+      - current_line_numbered_source_for_known_file_or_symbol
+      - call_paths_between_entry_point_and_target_behavior
+      - blast_radius_summary
   knowledgeGraph:
     required: true
     ask_for:
-      - product_decisions
-      - adr
-      - api_notes
-      - module_notes
-      - rollout_notes
+      - search_docs_or_hybrid_search_for_feature_terms
+      - answer_context_for_product_and_architecture_context
+      - read_doc_outline_for_relevant_concepts
+      - read_section_or_read_doc_range_for_contracts
+      - get_backlinks_for_related_decisions
+      - get_audit_log_when_recent_knowledge_changes_matter
 stop_conditions:
   - requirement is ambiguous
   - public interface change is needed but not requested
+  - codegraph_explore cannot identify the existing extension point
+  - knowledge MCP cannot confirm product or API constraints
   - impact scope cannot be determined
 fallbackInclude:
   - README.md

package/templates/default-project/skills/fix_bug/context.yaml

@@ -1,28 +1,31 @@
 queries:
-  - related files
-  - symbols
-  - call graph
-  - dependencies
-  - impact analysis
+  - use codegraph_explore for the defect, suspected file, symbol, or user-facing flow
+  - ask for current line-numbered source when a file or symbol is known
+  - ask for call paths between the entry point and suspected behavior
+  - ask for blast-radius summary before editing
 mcp_preflight:
   codegraph:
     required: true
+    primary_tool: codegraph_explore
     ask_for:
-      - related_files
-      - related_symbols
-      - callers
-      - dependencies
-      - impact_scope
+      - 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:
-      - adr
-      - module_notes
-      - api_notes
-      - runbooks
-      - historical_decisions
+      - 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
+      - get_audit_log_when_recent_knowledge_changes_matter
 stop_conditions:
   - root cause is unclear
+  - codegraph_explore cannot identify a plausible affected area
+  - knowledge MCP cannot provide enough decision or runbook evidence for a risky change
   - impact scope cannot be determined
   - verification path is missing
 fallbackInclude:

package/templates/default-project/skills/update_docs/context.yaml

@@ -1,26 +1,30 @@
 queries:
-  - related docs
-  - ADR
-  - module notes
-  - API docs
+  - use codegraph_explore for the documented module, API, or flow
+  - ask how the flow works and which files define it
+  - ask for current line-numbered source when documenting a known file or symbol
 mcp_preflight:
   codegraph:
     required: false
+    primary_tool: codegraph_explore
     ask_for:
-      - related_files
-      - public_interfaces
-      - ownership
+      - relevant_source_grouped_by_file
+      - current_line_numbered_source_for_known_file_or_symbol
+      - call_paths_for_documented_flow
+      - blast_radius_summary_when_docs_affect_shared_behavior
   knowledgeGraph:
     required: true
     ask_for:
-      - adr
-      - module_notes
-      - api_notes
-      - runbooks
-      - stale_docs
+      - list_path_for_doc_area
+      - search_docs_or_search_sections_for_existing_docs
+      - search_chunks_or_hybrid_search_for_relevant_evidence
+      - read_doc_outline_before_deep_reading
+      - read_section_or_read_doc_range_for_source_of_truth
+      - get_backlinks_for_related_docs
 stop_conditions:
   - documentation target is unclear
   - source of truth cannot be identified
+  - codegraph_explore cannot identify the documented behavior
+  - knowledge MCP cannot identify the source-of-truth document
 fallbackInclude:
   - README.md
   - docs

package/templates/default-project/skills/write_tests/context.yaml

@@ -1,28 +1,31 @@
 queries:
-  - related files
-  - symbols
-  - call graph
-  - dependencies
-  - impact analysis
+  - use codegraph_explore for the behavior under test
+  - ask for source grouped by file around the behavior
+  - ask for call paths and likely test targets
+  - ask for blast-radius summary when tests touch shared behavior
 mcp_preflight:
   codegraph:
     required: true
+    primary_tool: codegraph_explore
     ask_for:
-      - related_files
-      - test_targets
-      - dependencies
-      - callers
-      - impacted_paths
+      - relevant_source_grouped_by_file
+      - test_target_files_or_symbols
+      - current_line_numbered_source_for_known_file_or_symbol
+      - call_paths_to_behavior_under_test
+      - blast_radius_summary
   knowledgeGraph:
     required: false
     ask_for:
-      - test_strategy
-      - known_edge_cases
-      - runbooks
-      - historical_bugs
+      - search_docs_or_search_chunks_for_test_strategy
+      - answer_context_for_known_edge_cases
+      - read_section_or_read_chunk_for_test_evidence
+      - get_related_chunks_for_neighboring_context
+      - get_audit_log_when_recent_test_docs_matter
 stop_conditions:
   - expected behavior is unclear
   - no test runner can be identified
+  - codegraph_explore cannot identify the behavior under test
+  - knowledge MCP cannot clarify expected behavior for ambiguous tests
   - test data or fixture requirements are unknown
 fallbackInclude:
   - README.md

package/templates/integrations/claude/SKILL.md

@@ -5,33 +5,64 @@ description: 从 Claude Code 对话中触发可审计的 AI Dev Harness CLI，
 
 # AI Dev Harness
 
-当用户要求使用 Harness、AI Dev Harness、可审计执行、CodeGraph/Knowledge Graph 上下文，或要求执行 `fix_bug`、`add_feature`、`write_tests`、`update_docs` 这些技能时，使用本 Skill。
+当用户要求使用 Harness、AI Dev Harness、可审计执行、CodeGraph/Knowledge Graph 上下文，或要求执行 `fix_bug`、`add_feature`、`write_tests`、`update_docs` 时，使用本 Skill。
 
 ## Agent MCP Preflight
 
-运行 Harness 命令前，优先使用 Claude Code 已配置的 MCP 工具：
+运行 Harness 命令前，优先使用 Claude Code 已配置的 MCP 工具。
 
-- 使用 CodeGraph MCP 检查相关文件、符号、依赖、调用方和影响范围。
-- 使用 Knowledge Graph MCP 检查 ADR、模块说明、接口说明、历史决策和 runbook。
-- 在当前对话中先总结 MCP 发现，再调用 Harness。
-- 把关键 MCP 发现带入 Harness 的任务文本，让审计记录保留决策上下文。
+CodeGraph 使用规则：
 
-请使用以下预检总结格式：
+- 如果使用的是 `colbymchenry/codegraph`，优先调用默认工具 `codegraph_explore`。
+- 用任务里的业务流程、文件路径、函数/类/符号名、错误现象作为 query。
+- 重点读取 `codegraph_explore` 返回的 grouped source、line-numbered source、call paths、dynamic dispatch hops、blast-radius summary。
+- 只有当服务显式暴露了额外工具时，才使用其它 CodeGraph 工具。
+
+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`。
+- v1 不直接调用 `propose_doc` 写入知识库；只把建议写入 Harness 的 `persist_suggestions.md`。
+- 区分已确认事实和推断结论。
+
+知识沉淀建议规则：
+
+- 按 OKF v0.1 扩展输出候选内容。
+- 建议目标路径时，优先选择 `/<project>/overview/`、`/<project>/features/`、`/<project>/metrics/`、`/<project>/api/`、`/<project>/playbooks/`、`/<project>/references/`。
+- 每个候选文档必须说明 `type`、`title`、`description`、`tags`、`timestamp`；API/数据类建议补充 `resource`。
+- `## 相关` 必须使用有效 Markdown 链接，不要只写纯文本 concept 名。
+- API Reference 候选必须包含 `## 关键实现锚点` 和 `### Agent 使用建议`。
+- 只提出写入建议，不直接调用写入类工具；同时提醒更新对应目录的 `index.md` 和 `log.md`。
+- 不要输出密钥、Token、明文密码、未脱敏用户数据、未公开内网 IP。
+
+请在当前对话中使用以下预检总结格式：
 
 ```text
 ## MCP Preflight Findings
 - CodeGraph tools used:
-- Related files:
-- Related symbols:
-- Callers / dependencies:
-- Impact scope:
+- 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:
 ```
 
+把关键 MCP 发现带入 Harness 的任务文本，让审计记录保留决策上下文。
+
 不要在 Harness 内部实现单独的 MCP transport。SSE MCP 访问属于 Claude Code 的 MCP 客户端能力。
 
 ## Harness Command
@@ -66,7 +97,12 @@ powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-ha
 - Harness 打印的证据目录。
 - `summary.md`
 - `verify.json`
+- `verify_diagnostics.json`
 - `agent_contract.json`
+- `context_score.json`
+- `approval_required.json`
+- `loop_review.json`
+- `loop_report.md`
 - `audit.jsonl`
 - MCP 工具不可用或上下文缺失情况。
 

package/templates/integrations/codex/AGENTS_BLOCK.md

@@ -7,29 +7,60 @@
 - `write_tests`
 - `update_docs`
 
-运行 Harness 前，优先使用 Codex 已配置的 MCP 工具：
+运行 Harness 前，优先使用 Codex 已配置的 MCP 工具。
 
-- 查询 CodeGraph MCP，获取相关文件、符号、依赖、调用方和影响范围。
-- 查询 Knowledge Graph MCP，获取 ADR、模块说明、接口说明、历史决策和 runbook。
-- 在当前对话中简要报告 MCP 发现。
-- 把关键发现带入 Harness 的任务文本，让审计记录保留上下文。
+CodeGraph 使用规则：
 
-请使用以下预检总结格式：
+- 如果使用的是 `colbymchenry/codegraph`，优先调用默认工具 `codegraph_explore`。
+- 用任务里的业务流程、文件路径、函数/类/符号名、错误现象作为 query。
+- 重点读取 `codegraph_explore` 返回的 grouped source、line-numbered source、call paths、dynamic dispatch hops、blast-radius summary。
+- 只有当服务显式暴露了额外工具时，才使用其它 CodeGraph 工具。
+
+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`。
+- v1 不直接调用 `propose_doc` 写入知识库；只把建议写入 Harness 的 `persist_suggestions.md`。
+- 区分已确认事实和推断结论。
+
+知识沉淀建议规则：
+
+- 按 OKF v0.1 扩展输出候选内容。
+- 建议目标路径时，优先选择 `/<project>/overview/`、`/<project>/features/`、`/<project>/metrics/`、`/<project>/api/`、`/<project>/playbooks/`、`/<project>/references/`。
+- 每个候选文档必须说明 `type`、`title`、`description`、`tags`、`timestamp`；API/数据类建议补充 `resource`。
+- `## 相关` 必须使用有效 Markdown 链接，不要只写纯文本 concept 名。
+- API Reference 候选必须包含 `## 关键实现锚点` 和 `### Agent 使用建议`。
+- 只提出写入建议，不直接调用写入类工具；同时提醒更新对应目录的 `index.md` 和 `log.md`。
+- 不要输出密钥、Token、明文密码、未脱敏用户数据、未公开内网 IP。
+
+请在当前对话中使用以下预检总结格式：
 
 ```text
 ## MCP Preflight Findings
 - CodeGraph tools used:
-- Related files:
-- Related symbols:
-- Callers / dependencies:
-- Impact scope:
+- 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:
 ```
 
+把关键发现带入 Harness 的任务文本，让审计记录保留上下文。
+
 不要在 Harness 内部实现或期待 SSE MCP transport。SSE MCP 访问属于 Codex MCP 客户端能力。
 
 MCP preflight 完成后，在仓库根目录运行：
@@ -46,6 +77,6 @@ powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-ha
 
 只读分析时，在任务里明确写入 “Do not modify repository files”，通常使用 `update_docs`。
 
-每次 Harness 运行期间和结束后，报告可见生命周期进度、证据目录、`summary.md`、`verify.json`、`agent_contract.json`、`audit.jsonl`，以及 MCP 工具不可用或上下文缺失情况。
+每次 Harness 运行期间和结束后，报告可见生命周期进度、证据目录、`summary.md`、`verify.json`、`verify_diagnostics.json`、`agent_contract.json`、`context_score.json`、`approval_required.json`、`loop_review.json`、`loop_report.md`、`audit.jsonl`，以及 MCP 工具不可用或上下文缺失情况。
 需要时使用 `.harness/ai-dev-harness/scripts/read-evidence.ps1` 打印证据摘要。
 v1 不直接写入 Knowledge Graph；使用 `persist_suggestions.md`。