ai-dev-harness 0.1.0 → 0.1.1

package/dist/templates.js

@@ -1,217 +1,41 @@
+import path from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import { defaultConfigYaml } from "./config.js";
-export const rootTemplates = {
-    "harness.yaml": defaultConfigYaml(),
-    "AGENTS.md": `# Project Agent Rules
-
-- Work inside this Git repository only.
-- Prefer small, reviewable changes.
-- Do not modify generated or dependency directories.
-- Always explain impact, risk, verification, and follow-up knowledge updates.
-- Before changing code, state assumptions, affected areas, and a minimal plan.
-- If required context is missing or confidence is low, stop and report what is missing instead of guessing.
-- Do not perform broad refactors, formatting-only sweeps, dependency upgrades, or unrelated cleanup unless the task explicitly asks for them.
-`,
-    "TOOLS.md": `# Tool Rules
-
-- Codex and Claude Code are execution agents.
-- CodeGraph MCP provides code impact context.
-- Knowledge Graph MCP provides 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.
-- Knowledge Graph is read-only in v1. Write suggestions to persist_suggestions.md only.
-`,
-    "SKILLS.md": `# 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.
-`
-};
-const baseContext = `queries:
-  - related files
-  - symbols
-  - call graph
-  - dependencies
-  - impact analysis
-fallbackInclude:
-  - README.md
-  - src
-`;
-const defaultVerify = `- name: git status
-  command: git status --short
-`;
-export const skillTemplates = {
-    fix_bug: {
-        "SKILL.md": `# fix_bug
-
-## Goal
-Diagnose and fix a defect with the smallest safe code change.
-
-## Inputs
-- Task text or issue description.
-- CodeGraph impact context.
-- Knowledge Graph related decisions, module notes, APIs, and runbooks.
-
-## Outputs
-- Code change.
-- Test or verification result.
-- Summary with root cause, impact, risk, and follow-up suggestions.
-
-## Analysis Contract
-- Restate the observed defect and expected behavior.
-- Identify the likely root cause and the code path involved.
-- List assumptions and confidence level before editing.
-- Use CodeGraph impact context to avoid missing callers or dependent modules.
-- Use Knowledge Graph decisions and runbooks to avoid violating historical constraints.
-
-## Execution Contract
-- Make the smallest task-relevant change.
-- Prefer adding or updating a regression test when feasible.
-- Do not rewrite unrelated code, rename public APIs, change formatting broadly, or upgrade dependencies.
-- If root cause is unclear after inspection, stop and report missing evidence instead of guessing.
-
-## Verification Contract
-- Run the configured verification commands through Harness.
-- If manual or targeted verification is needed, describe the exact command or scenario.
-- Record any verification that could not be run and why.
-
-## Report Contract
-- Root cause.
-- Files changed.
-- Why the fix is safe.
-- Verification result.
-- Residual risk.
-- Knowledge or runbook update suggestions.
-
-## Acceptance
-- The defect is explained.
-- The change is limited to the affected area.
-- Relevant verification commands pass or failures are recorded.
-`,
-        "verify.yaml": defaultVerify,
-        "context.yaml": baseContext
-    },
-    add_feature: {
-        "SKILL.md": `# add_feature
-
-## Goal
-Implement a scoped feature using existing project patterns.
-
-## Analysis Contract
-- Restate the feature intent and non-goals.
-- Identify affected modules, public interfaces, data flows, and compatibility risks.
-- Check CodeGraph context for callers, dependencies, and likely integration points.
-- Check Knowledge Graph context for ADRs, API contracts, and previous decisions.
-
-## Execution Contract
-- Implement the smallest coherent slice that satisfies the task.
-- Follow existing patterns before introducing new abstractions.
-- Do not change unrelated behavior or broaden scope.
-- Preserve backward compatibility unless the task explicitly allows breaking changes.
-
-## Verification Contract
-- Add or update tests when behavior changes.
-- Run configured verification commands through Harness.
-- Record unverified scenarios and reasons.
-
-## Report Contract
-- Feature behavior implemented.
-- Files changed.
-- Compatibility notes.
-- Verification result.
-- Residual risk.
-- Documentation or knowledge suggestions.
-
-## Outputs
-- Code change.
-- Tests or verification.
-- Documentation and knowledge suggestions when behavior changes.
-`,
-        "verify.yaml": defaultVerify,
-        "context.yaml": baseContext
-    },
-    write_tests: {
-        "SKILL.md": `# write_tests
-
-## Goal
-Add or improve tests for existing behavior without changing production behavior unless required.
-
-## Analysis Contract
-- Identify the behavior under test and the risk it protects.
-- Locate existing test patterns, fixtures, and helper APIs.
-- Check CodeGraph context for affected code paths.
-- Avoid inventing behavior not supported by source code or knowledge context.
-
-## Execution Contract
-- Prefer focused tests over broad snapshot or brittle integration tests.
-- Do not change production code unless the existing code is untestable and the change is minimal.
-- Keep fixtures deterministic and local to the test where possible.
-
-## Verification Contract
-- Run the relevant test command or configured Harness verification.
-- If the full suite is too expensive, document the targeted command and why.
-
-## Report Contract
-- Scenarios covered.
-- Files changed.
-- Verification result.
-- Remaining uncovered risks.
-
-## Outputs
-- Test files or fixture updates.
-- Verification result.
-- Summary of covered scenarios.
-`,
-        "verify.yaml": defaultVerify,
-        "context.yaml": baseContext
-    },
-    update_docs: {
-        "SKILL.md": `# update_docs
-
-## Goal
-Update project documentation and propose knowledge graph additions.
-
-## Analysis Contract
-- Identify the audience and purpose of the documentation update.
-- Cross-check docs against code, CodeGraph context, and Knowledge Graph records.
-- Distinguish confirmed facts from inferred guidance.
-
-## Execution Contract
-- Update only documentation or knowledge suggestion artifacts unless explicitly asked to change code.
-- Keep docs concise, operational, and linked to actual project behavior.
-- Do not write directly to Knowledge Graph in v1.
-
-## Verification Contract
-- Check links, commands, paths, and filenames mentioned in the docs.
-- Run configured verification when docs affect generated artifacts or examples.
-
-## Report Contract
-- Docs changed.
-- Source of truth used.
-- Verification result.
-- Knowledge Graph suggestions.
-
-## Outputs
-- Documentation changes.
-- Persist suggestions for ADR, module notes, runbooks, or decisions.
-`,
-        "verify.yaml": defaultVerify,
-        "context.yaml": `queries:
-  - related docs
-  - ADR
-  - module notes
-  - API docs
-fallbackInclude:
-  - README.md
-  - docs
-`
+import { pathExists } from "./utils.js";
+export function packageRootFromHere() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+export function templateRoot(packageRoot = packageRootFromHere()) {
+    return path.join(packageRoot, "templates");
+}
+export async function readTemplateFile(relPath, packageRoot = packageRootFromHere()) {
+    return readFile(path.join(templateRoot(packageRoot), relPath), "utf8");
+}
+export function renderTemplate(content, vars) {
+    return Object.entries(vars).reduce((next, [key, value]) => next.replaceAll(`{{${key}}}`, value), content);
+}
+export async function readTemplateTree(relDir, packageRoot = packageRootFromHere()) {
+    const root = path.join(templateRoot(packageRoot), relDir);
+    const files = [];
+    async function walk(absDir, relBase) {
+        const entries = await readdir(absDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const abs = path.join(absDir, entry.name);
+            const rel = path.join(relBase, entry.name);
+            if (entry.isDirectory()) {
+                await walk(abs, rel);
+            }
+            else {
+                files.push({ relPath: rel, content: await readFile(abs, "utf8") });
+            }
+        }
     }
-};
+    if (await pathExists(root))
+        await walk(root, "");
+    return files;
+}
+export async function defaultProjectTemplates(packageRoot = packageRootFromHere()) {
+    const files = await readTemplateTree("default-project", packageRoot);
+    return [{ relPath: "harness.yaml", content: defaultConfigYaml() }, ...files];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-dev-harness",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Auditable AI development harness for Codex and Claude Code.",
   "license": "MIT",
   "keywords": [
@@ -21,7 +21,9 @@
     "!dist/**/*.test.js",
     "!dist/testSupport.js",
     "scripts/",
+    "templates/",
     "README.md",
+    "COLLEAGUE_TRIAL_GUIDE.md",
     "package.json"
   ],
   "scripts": {

package/scripts/read-evidence.ps1

@@ -14,10 +14,11 @@ $runPath = if (Test-Path -LiteralPath $Run) {
   Resolve-Path -LiteralPath (Join-Path $repoPath "runs\$Run")
 }
 
-Write-Host "[harness-skill] evidence: $runPath"
+Write-Host "[harness-skill] 证据目录: $runPath"
 
 $summary = Join-Path $runPath "summary.md"
 $verify = Join-Path $runPath "verify.json"
+$contract = Join-Path $runPath "agent_contract.json"
 $audit = Join-Path $runPath "audit.jsonl"
 
 if (Test-Path -LiteralPath $summary) {
@@ -30,7 +31,12 @@ if (Test-Path -LiteralPath $verify) {
   Get-Content -LiteralPath $verify
 }
 
+if (Test-Path -LiteralPath $contract) {
+  Write-Host "`n--- agent_contract.json ---"
+  Get-Content -LiteralPath $contract
+}
+
 if (Test-Path -LiteralPath $audit) {
-  Write-Host "`n--- audit degraded/errors ---"
-  Select-String -LiteralPath $audit -Pattern "degraded|failed|error|run_finished" | ForEach-Object { $_.Line }
+  Write-Host "`n--- 审计失败/错误 ---"
+  Select-String -LiteralPath $audit -Pattern "failed|error|run_finished" | ForEach-Object { $_.Line }
 }

package/scripts/run-harness.ps1

@@ -19,7 +19,11 @@ $ErrorActionPreference = "Stop"
 
 $repoPath = Resolve-Path -LiteralPath $Repo
 $harnessYaml = Join-Path $repoPath "harness.yaml"
-$cliPath = Resolve-Path -LiteralPath (Join-Path $PSScriptRoot "..\dist\cli.js")
+$cliPath = '{{HARNESS_CLI_PATH}}'
+
+if ($cliPath -like '{{*}}') {
+  $cliPath = Resolve-Path -LiteralPath (Join-Path $PSScriptRoot "..\dist\cli.js")
+}
 
 Write-Host "[harness-skill] repo: $repoPath"
 Write-Host "[harness-skill] checking config: $harnessYaml"
@@ -33,8 +37,7 @@ if ($LASTEXITCODE -ne 0) {
   Write-Error "$repoPath is not a Git repository. AI Dev Harness run requires a business Git repository."
 }
 
-$argsList = @(
-  $cliPath,
+$argList = @(
   "run",
   "--task",
   $Task,
@@ -45,9 +48,9 @@ $argsList = @(
 )
 
 if ($Live) {
-  $argsList += "--live"
+  $argList += "--live"
 }
 
 Write-Host "[harness-skill] starting harness: $Skill via $Agent"
-node @argsList
+node $cliPath @argList
 exit $LASTEXITCODE

package/templates/default-project/AGENTS.md

@@ -0,0 +1,9 @@
+# Project Agent Rules
+
+- Work inside this Git repository only.
+- Prefer small, reviewable changes.
+- Do not modify generated or dependency directories.
+- Always explain impact, risk, verification, and follow-up knowledge updates.
+- Before changing code, state assumptions, affected areas, and a minimal plan.
+- If required context is missing or confidence is low, stop and report what is missing instead of guessing.
+- Do not perform broad refactors, formatting-only sweeps, dependency upgrades, or unrelated cleanup unless the task explicitly asks for them.

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,8 @@
+# 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.
+- 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.
+- Knowledge Graph is read-only in v1. Write suggestions to persist_suggestions.md only.

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,30 @@
+queries:
+  - related files
+  - symbols
+  - call graph
+  - dependencies
+  - impact analysis
+mcp_preflight:
+  codegraph:
+    required: true
+    ask_for:
+      - related_files
+      - extension_points
+      - dependent_modules
+      - public_interfaces
+      - impact_scope
+  knowledgeGraph:
+    required: true
+    ask_for:
+      - product_decisions
+      - adr
+      - api_notes
+      - module_notes
+      - rollout_notes
+stop_conditions:
+  - requirement is ambiguous
+  - public interface change is needed but not requested
+  - 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,30 @@
+queries:
+  - related files
+  - symbols
+  - call graph
+  - dependencies
+  - impact analysis
+mcp_preflight:
+  codegraph:
+    required: true
+    ask_for:
+      - related_files
+      - related_symbols
+      - callers
+      - dependencies
+      - impact_scope
+  knowledgeGraph:
+    required: true
+    ask_for:
+      - adr
+      - module_notes
+      - api_notes
+      - runbooks
+      - historical_decisions
+stop_conditions:
+  - root cause is unclear
+  - 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,26 @@
+queries:
+  - related docs
+  - ADR
+  - module notes
+  - API docs
+mcp_preflight:
+  codegraph:
+    required: false
+    ask_for:
+      - related_files
+      - public_interfaces
+      - ownership
+  knowledgeGraph:
+    required: true
+    ask_for:
+      - adr
+      - module_notes
+      - api_notes
+      - runbooks
+      - stale_docs
+stop_conditions:
+  - documentation target is unclear
+  - source of truth cannot be identified
+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,29 @@
+queries:
+  - related files
+  - symbols
+  - call graph
+  - dependencies
+  - impact analysis
+mcp_preflight:
+  codegraph:
+    required: true
+    ask_for:
+      - related_files
+      - test_targets
+      - dependencies
+      - callers
+      - impacted_paths
+  knowledgeGraph:
+    required: false
+    ask_for:
+      - test_strategy
+      - known_edge_cases
+      - runbooks
+      - historical_bugs
+stop_conditions:
+  - expected behavior is unclear
+  - no test runner can be identified
+  - 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