ai-dev-harness 0.1.0 → 0.1.2

package/templates/default-project/SKILLS.md

@@ -0,0 +1,13 @@
+# Skill Index
+
+- fix_bug: diagnose and fix a defect with tests when possible.
+- add_feature: implement a scoped feature with verification.
+- write_tests: add or improve tests for existing behavior.
+- update_docs: update project documentation and knowledge suggestions.
+
+Every skill follows the same execution contract:
+
+1. Analysis Contract: identify assumptions, affected files/modules, likely risks, and the smallest viable plan.
+2. Execution Contract: make only task-relevant changes and avoid opportunistic refactors.
+3. Verification Contract: run or defer verification with explicit reasons.
+4. Report Contract: explain root cause or intent, changed files, verification, residual risk, and knowledge suggestions.

package/templates/default-project/TOOLS.md

@@ -0,0 +1,11 @@
+# Tool Rules
+
+- 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/SKILL.md

@@ -0,0 +1,34 @@
+# add_feature
+
+## Goal
+基于现有项目模式实现范围明确的功能。
+
+## Analysis Contract
+- 复述功能意图和非目标。
+- 识别受影响模块、公共接口、数据流和兼容性风险。
+- 使用 CodeGraph 检查调用方、依赖和集成点。
+- 使用 Knowledge Graph 检查 ADR、接口契约和历史决策。
+
+## Execution Contract
+- 实现满足任务的最小完整切片。
+- 优先遵循现有模式，再考虑新增抽象。
+- 不改变无关行为，不扩大范围。
+- 除非任务明确允许破坏性变更，否则保持向后兼容。
+
+## Verification Contract
+- 行为变化时添加或更新测试。
+- 通过 Harness 运行配置的验证命令。
+- 记录未验证场景和原因。
+
+## Report Contract
+- 已实现的功能行为。
+- 修改文件。
+- 兼容性说明。
+- 验证结果。
+- 残余风险。
+- 文档或知识沉淀建议。
+
+## Outputs
+- 代码变更。
+- 测试或验证。
+- 行为变化时的文档和知识沉淀建议。

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

@@ -0,0 +1,33 @@
+queries:
+  - 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:
+      - 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:
+      - 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
+  - src

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

@@ -0,0 +1,2 @@
+- name: git status
+  command: git status --short

package/templates/default-project/skills/fix_bug/SKILL.md

@@ -0,0 +1,45 @@
+# fix_bug
+
+## Goal
+用最小安全变更定位并修复缺陷。
+
+## Inputs
+- 任务描述或 Issue。
+- CodeGraph 影响范围上下文。
+- Knowledge Graph 中的决策、模块说明、接口说明和运行手册。
+
+## Outputs
+- 代码变更。
+- 测试或验证结果。
+- 包含根因、影响、风险和后续建议的总结。
+
+## Analysis Contract
+- 复述观察到的缺陷和期望行为。
+- 识别可能根因和涉及的代码路径。
+- 修改前列出假设和信心等级。
+- 使用 CodeGraph 影响范围，避免遗漏调用方或依赖模块。
+- 使用 Knowledge Graph 决策和 runbook，避免违背历史约束。
+
+## Execution Contract
+- 做和任务相关的最小变更。
+- 可行时添加或更新回归测试。
+- 不重写无关代码，不重命名公共 API，不做大范围格式化，不升级依赖。
+- 如果根因不清楚，停止并报告缺失证据，不要猜。
+
+## Verification Contract
+- 通过 Harness 运行配置的验证命令。
+- 如需手动或定向验证，说明确切命令或场景。
+- 记录无法执行的验证及原因。
+
+## Report Contract
+- 根因。
+- 修改文件。
+- 为什么这个修复是安全的。
+- 验证结果。
+- 残余风险。
+- 知识库或 runbook 更新建议。
+
+## Acceptance
+- 缺陷被解释清楚。
+- 变更限定在受影响区域。
+- 相关验证命令通过，或失败原因被记录。

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

@@ -0,0 +1,33 @@
+queries:
+  - 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:
+      - 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
+      - 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:
+  - README.md
+  - src

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

@@ -0,0 +1,2 @@
+- name: git status
+  command: git status --short

package/templates/default-project/skills/update_docs/SKILL.md

@@ -0,0 +1,28 @@
+# update_docs
+
+## Goal
+更新项目文档，并提出 Knowledge Graph 沉淀建议。
+
+## Analysis Contract
+- 识别文档更新的读者和目的。
+- 对照代码、CodeGraph 上下文和 Knowledge Graph 记录校验文档。
+- 区分已确认事实和推断建议。
+
+## Execution Contract
+- 除非明确要求改代码，否则只更新文档或知识建议产物。
+- 文档应简洁、可操作，并和真实项目行为一致。
+- v1 不直接写入 Knowledge Graph。
+
+## Verification Contract
+- 检查文档中的链接、命令、路径和文件名。
+- 如果文档影响生成产物或示例，运行配置的验证命令。
+
+## Report Contract
+- 修改的文档。
+- 使用的事实来源。
+- 验证结果。
+- Knowledge Graph 沉淀建议。
+
+## Outputs
+- 文档变更。
+- ADR、模块说明、runbook 或决策记录的沉淀建议。

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

@@ -0,0 +1,30 @@
+queries:
+  - 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:
+      - 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:
+      - 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/update_docs/verify.yaml

@@ -0,0 +1,2 @@
+- name: git status
+  command: git status --short

package/templates/default-project/skills/write_tests/SKILL.md

@@ -0,0 +1,30 @@
+# write_tests
+
+## Goal
+为已有行为添加或改进测试，除非必要，不改变生产行为。
+
+## Analysis Contract
+- 识别被测行为以及它覆盖的风险。
+- 找到现有测试模式、fixture 和 helper API。
+- 使用 CodeGraph 检查受影响代码路径。
+- 不发明源码或知识上下文不支持的行为。
+
+## Execution Contract
+- 优先编写聚焦测试，避免脆弱的大快照或过宽集成测试。
+- 除非现有代码不可测试且改动很小，否则不修改生产代码。
+- fixture 应尽量确定性，并尽量局部化。
+
+## Verification Contract
+- 运行相关测试命令或 Harness 配置的验证命令。
+- 如果全量测试成本过高，记录定向命令和原因。
+
+## Report Contract
+- 覆盖的场景。
+- 修改文件。
+- 验证结果。
+- 剩余未覆盖风险。
+
+## Outputs
+- 测试文件或 fixture 更新。
+- 验证结果。
+- 覆盖场景总结。

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

@@ -0,0 +1,32 @@
+queries:
+  - 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:
+      - 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:
+      - 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
+  - src

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

@@ -0,0 +1,2 @@
+- name: git status
+  command: git status --short

package/templates/integrations/claude/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: ai-dev-harness
+description: 从 Claude Code 对话中触发可审计的 AI Dev Harness CLI，并在当前对话中展示 Harness 执行过程。
+---
+
+# AI Dev Harness
+
+当用户要求使用 Harness、AI Dev Harness、可审计执行、CodeGraph/Knowledge Graph 上下文，或要求执行 `fix_bug`、`add_feature`、`write_tests`、`update_docs` 时，使用本 Skill。
+
+## Agent MCP Preflight
+
+运行 Harness 命令前，优先使用 Claude Code 已配置的 MCP 工具。
+
+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:
+- 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
+
+MCP preflight 完成后，在仓库根目录运行：
+
+```bash
+powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill <skill> -Agent claude -Live
+```
+
+兜底直接命令：
+
+```bash
+{{HARNESS_COMMAND}} run --task "<task>" --skill <skill> --agent claude --live
+```
+
+## Skill Mapping
+
+- 缺陷或回归问题：`fix_bug`
+- 范围明确的功能：`add_feature`
+- 添加或改进测试：`write_tests`
+- 只读分析或文档：`update_docs`
+
+只读分析时，在任务里明确写入：“Do not modify repository files”。
+
+## 过程汇报
+
+命令执行期间和结束后，在当前对话中报告：
+
+- 使用了哪些 MCP 工具，以及关键上下文发现。
+- Harness live output 中当前可见的生命周期阶段。
+- 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 工具不可用或上下文缺失情况。
+
+必要时可读取证据：
+
+```bash
+powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/read-evidence.ps1" -Run <run_id_or_path>
+```
+
+除非用户明确要求直接手工处理，否则实现类任务不要绕过 Harness。

package/templates/integrations/codex/AGENTS_BLOCK.md

@@ -0,0 +1,82 @@
+## AI Dev Harness
+
+当用户要求使用 Harness、可审计执行、CodeGraph/Knowledge Graph 辅助研发，或要求执行以下技能时，使用 AI Dev Harness CLI：
+
+- `fix_bug`
+- `add_feature`
+- `write_tests`
+- `update_docs`
+
+运行 Harness 前，优先使用 Codex 已配置的 MCP 工具。
+
+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:
+- 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 完成后，在仓库根目录运行：
+
+```bash
+powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill <skill> -Agent codex -Live
+```
+
+兜底直接命令：
+
+```bash
+{{HARNESS_COMMAND}} run --task "<task>" --skill <skill> --agent codex --live
+```
+
+只读分析时，在任务里明确写入 “Do not modify repository files”，通常使用 `update_docs`。
+
+每次 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`。

package/templates/integrations/cursor/ai-dev-harness.mdc

@@ -0,0 +1,55 @@
+---
+description: 使用 AI Dev Harness 执行可审计研发任务
+alwaysApply: false
+---
+
+# AI Dev Harness
+
+当用户要求使用 Harness、可审计执行、CodeGraph/Knowledge Graph 辅助研发，或要求执行 `fix_bug`、`add_feature`、`write_tests`、`update_docs` 时，优先使用 AI Dev Harness。
+
+## MCP Preflight
+
+运行 Harness 前，先使用 Cursor 当前可用的 MCP 工具收集上下文：
+
+- CodeGraph：优先围绕任务、文件、符号、调用链和影响范围查询，记录使用过的工具与关键发现。
+- Knowledge Graph：优先查找 ADR、模块说明、接口说明、runbook、历史决策和踩坑记录。
+- 不要在 Harness 内实现 MCP transport；MCP 调用属于当前 Agent/编辑器的能力。
+- 不要直接写入 Knowledge Graph，只在 Harness 产物 `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:
+```
+
+## Harness Command
+
+MCP preflight 完成后，在仓库根目录运行：
+
+```bash
+powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill <skill> -Agent cursor -Live
+```
+
+兜底命令：
+
+```bash
+{{HARNESS_COMMAND}} run --task "<task>" --skill <skill> --agent cursor --live
+```
+
+执行结束后，向用户报告 Harness 证据目录、生命周期状态、验证结果、审批门禁、Context Score、Loop Review 和知识沉淀建议。

package/templates/integrations/gemini/GEMINI_BLOCK.md

@@ -0,0 +1,46 @@
+## AI Dev Harness
+
+当用户要求使用 Harness、可审计执行、CodeGraph/Knowledge Graph 辅助研发，或要求执行 `fix_bug`、`add_feature`、`write_tests`、`update_docs` 时，优先使用 AI Dev Harness CLI。
+
+运行 Harness 前，先使用 Gemini 当前可用的 MCP 工具收集上下文：
+
+- CodeGraph：围绕任务、文件、符号、调用链和影响范围查询，记录使用过的工具与关键发现。
+- Knowledge Graph：查询 ADR、模块说明、接口说明、runbook、历史决策和踩坑记录。
+- Harness 不负责连接 MCP；MCP 调用由当前 Agent 完成。
+- 不要直接写入 Knowledge Graph，只在 Harness 产物 `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:
+```
+
+MCP preflight 完成后，在仓库根目录运行：
+
+```bash
+powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill <skill> -Agent gemini -Live
+```
+
+兜底命令：
+
+```bash
+{{HARNESS_COMMAND}} run --task "<task>" --skill <skill> --agent gemini --live
+```
+
+执行结束后，向用户报告 Harness 证据目录、生命周期状态、验证结果、审批门禁、Context Score、Loop Review 和知识沉淀建议。