ai-dev-harness 0.1.0 → 0.1.1

package/dist/integration.js

@@ -1,16 +1,17 @@
 import path from "node:path";
-import { appendFile, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { readTemplateFile, renderTemplate } from "./templates.js";
 import { pathExists } from "./utils.js";
 export async function installIntegration(options) {
     const created = [];
     const updated = [];
     const skipped = [];
-    const scriptResult = await installScriptAssets(options.targetDir, options.packageRoot ?? process.cwd());
+    const scriptResult = await installScriptAssets(options.targetDir, options.packageRoot ?? process.cwd(), options.harnessCliPath);
     created.push(...scriptResult.created);
     updated.push(...scriptResult.updated);
     skipped.push(...scriptResult.skipped);
     if (options.agent === "claude" || options.agent === "both") {
-        const result = await installClaudeSkill(options.targetDir, options.harnessCommand);
+        const result = await installClaudeSkill(options.targetDir, options.harnessCommand, options.packageRoot);
         if (result === "created")
             created.push(".claude/skills/ai-dev-harness/SKILL.md");
         else if (result === "updated")
@@ -19,7 +20,7 @@ export async function installIntegration(options) {
             skipped.push(".claude/skills/ai-dev-harness/SKILL.md");
     }
     if (options.agent === "codex" || options.agent === "both") {
-        const result = await installCodexRules(options.targetDir, options.harnessCommand);
+        const result = await installCodexRules(options.targetDir, options.harnessCommand, options.packageRoot);
         if (result === "created")
             created.push("AGENTS.md");
         else if (result === "updated")
@@ -29,7 +30,7 @@ export async function installIntegration(options) {
     }
     return { created, updated, skipped };
 }
-async function installScriptAssets(targetDir, packageRoot) {
+async function installScriptAssets(targetDir, packageRoot, harnessCliPath) {
     const created = [];
     const updated = [];
     const skipped = [];
@@ -42,7 +43,8 @@ async function installScriptAssets(targetDir, packageRoot) {
         const rel = path.join(".harness", "ai-dev-harness", "scripts", asset);
         if (!(await pathExists(source)))
             continue;
-        const next = await readFile(source, "utf8");
+        const raw = await readFile(source, "utf8");
+        const next = renderTemplate(raw, { HARNESS_CLI_PATH: harnessCliPath ?? "{{HARNESS_CLI_PATH}}" });
         if (await pathExists(target)) {
             const current = await readFile(target, "utf8");
             if (current === next) {
@@ -53,28 +55,28 @@ async function installScriptAssets(targetDir, packageRoot) {
             updated.push(rel);
             continue;
         }
-        await copyFile(source, target);
+        await writeFile(target, next, "utf8");
         created.push(rel);
     }
     return { created, updated, skipped };
 }
-async function installClaudeSkill(targetDir, harnessCommand) {
+async function installClaudeSkill(targetDir, harnessCommand, packageRoot) {
     const skillPath = path.join(targetDir, ".claude", "skills", "ai-dev-harness", "SKILL.md");
     await mkdir(path.dirname(skillPath), { recursive: true });
     if (await pathExists(skillPath)) {
         const current = await readFile(skillPath, "utf8");
-        const next = claudeSkill(harnessCommand);
+        const next = await claudeSkill(harnessCommand, packageRoot);
         if (current === next)
             return "skipped";
         await writeFile(skillPath, next, "utf8");
         return "updated";
     }
-    await writeFile(skillPath, claudeSkill(harnessCommand), "utf8");
+    await writeFile(skillPath, await claudeSkill(harnessCommand, packageRoot), "utf8");
     return "created";
 }
-async function installCodexRules(targetDir, harnessCommand) {
+async function installCodexRules(targetDir, harnessCommand, packageRoot) {
     const agentsPath = path.join(targetDir, "AGENTS.md");
-    const block = codexBlock(harnessCommand);
+    const block = await codexBlock(harnessCommand, packageRoot);
     if (!(await pathExists(agentsPath))) {
         await writeFile(agentsPath, `# Project Agent Rules\n\n${block}`, "utf8");
         return "created";
@@ -90,84 +92,13 @@ async function installCodexRules(targetDir, harnessCommand) {
     await appendFile(agentsPath, `\n\n${block}`, "utf8");
     return "updated";
 }
-function claudeSkill(harnessCommand) {
-    return `---
-name: ai-dev-harness
-description: Trigger the auditable AI Dev Harness CLI from Claude Code conversations and stream the Harness process in the current chat.
----
-
-# AI Dev Harness
-
-Use this skill when the user asks to use Harness, AI Dev Harness, an audited run, CodeGraph/Knowledge Graph context, or one of these skills: \`fix_bug\`, \`add_feature\`, \`write_tests\`, \`update_docs\`.
-
-## Command
-
-Run from the repository root:
-
-\`\`\`bash
-powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill <skill> -Agent claude -Live
-\`\`\`
-
-Fallback direct command:
-
-\`\`\`bash
-${harnessCommand} run --task "<task>" --skill <skill> --agent claude --live
-\`\`\`
-
-## Skill Mapping
-
-- Defect or regression: \`fix_bug\`
-- Scoped feature: \`add_feature\`
-- Add or improve tests: \`write_tests\`
-- Read-only analysis or docs: \`update_docs\`
-
-For read-only analysis, include "Do not modify repository files" in the task.
-
-## Reporting
-
-After the command finishes, inspect and report:
-
-- Evidence directory printed by Harness
-- \`summary.md\`
-- \`verify.json\`
-- \`audit.jsonl\`
-- MCP degradation errors, if present
-
-You may use:
-
-\`\`\`bash
-powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/read-evidence.ps1" -Run <run_id_or_path>
-\`\`\`
-
-Do not bypass Harness for implementation tasks unless the user explicitly asks for direct manual work.
-`;
+async function claudeSkill(harnessCommand, packageRoot) {
+    return renderTemplate(await readTemplateFile(path.join("integrations", "claude", "SKILL.md"), packageRoot), {
+        HARNESS_COMMAND: harnessCommand
+    });
 }
-function codexBlock(harnessCommand) {
-    return `## AI Dev Harness
-
-Use the AI Dev Harness CLI when the user asks for Harness, an audited run, CodeGraph/Knowledge Graph assisted work, or one of these skills:
-
-- \`fix_bug\`
-- \`add_feature\`
-- \`write_tests\`
-- \`update_docs\`
-
-Run from the repository root:
-
-\`\`\`bash
-powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill <skill> -Agent codex -Live
-\`\`\`
-
-Fallback direct command:
-
-\`\`\`bash
-${harnessCommand} run --task "<task>" --skill <skill> --agent codex --live
-\`\`\`
-
-For read-only analysis, include "Do not modify repository files" in the task and usually use \`update_docs\`.
-
-After every Harness run, report the evidence directory, inspect \`summary.md\`, \`verify.json\`, and \`audit.jsonl\`, and report MCP degradation errors if present.
-Use \`.harness/ai-dev-harness/scripts/read-evidence.ps1\` to print the evidence summary when useful.
-Do not write directly to Knowledge Graph in v1; use \`persist_suggestions.md\`.
-`;
+async function codexBlock(harnessCommand, packageRoot) {
+    return renderTemplate(await readTemplateFile(path.join("integrations", "codex", "AGENTS_BLOCK.md"), packageRoot), {
+        HARNESS_COMMAND: harnessCommand
+    });
 }

package/dist/mcp.js

@@ -1,49 +1,25 @@
 import { appendFile } from "node:fs/promises";
-import { truncate } from "./utils.js";
-async function postJson(url, body, timeoutMs) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const response = await fetch(url, {
-            method: "POST",
-            headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
-            body: JSON.stringify(body),
-            signal: controller.signal
-        });
-        const text = await response.text();
-        if (!response.ok)
-            throw new Error(`HTTP ${response.status}: ${truncate(text, 1000)}`);
-        return parseMcpResponse(text, response.headers.get("content-type") ?? "");
-    }
-    finally {
-        clearTimeout(timer);
-    }
+function endpointSummary(endpoint) {
+    return {
+        type: endpoint.type ?? "http",
+        url: endpoint.url,
+        headerNames: Object.keys(endpoint.headers ?? {})
+    };
 }
-function parseMcpResponse(text, contentType) {
-    if (contentType.includes("text/event-stream")) {
-        const dataLines = text
-            .split(/\r?\n/)
-            .filter((line) => line.startsWith("data:"))
-            .map((line) => line.slice(5).trim())
-            .filter((line) => line && line !== "[DONE]");
-        return dataLines.map((line) => {
-            try {
-                return JSON.parse(line);
-            }
-            catch {
-                return line;
-            }
-        });
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return text;
-    }
-}
-function summarize(data) {
-    return truncate(typeof data === "string" ? data : JSON.stringify(data, null, 2), 6000);
+function agentDrivenResult(source, endpoint, skill) {
+    const request = {
+        mode: "agent-driven",
+        instruction: "Claude/Codex should call this MCP server with its own configured MCP client before invoking Harness. Harness records the configured source but does not implement MCP transport.",
+        endpoint: endpointSummary(endpoint),
+        suggestedQueries: skill.contextQueries
+    };
+    return {
+        source,
+        ok: true,
+        request,
+        responseSummary: `${source} is configured as an agent-driven MCP context source.`,
+        data: request
+    };
 }
 export class CodeGraphSource {
     config;
@@ -52,41 +28,10 @@ export class CodeGraphSource {
         this.config = config;
         this.queryLogPath = queryLogPath;
     }
-    async getImpactContext(task, skill, changedFiles) {
-        const request = {
-            type: "codegraph.impact",
-            task,
-            skill: skill.name,
-            queries: skill.contextQueries,
-            changedFiles
-        };
-        return this.query("codegraph", this.config.mcp.codegraph.url, request);
-    }
-    async query(source, url, request) {
-        try {
-            const data = await postJson(url, request, this.config.mcp.timeoutMs);
-            const result = {
-                source,
-                ok: true,
-                degraded: false,
-                request,
-                responseSummary: summarize(data),
-                data
-            };
-            await appendFile(this.queryLogPath, `${JSON.stringify(result)}\n`, "utf8");
-            return result;
-        }
-        catch (error) {
-            const result = {
-                source,
-                ok: false,
-                degraded: true,
-                request,
-                error: error instanceof Error ? error.message : String(error)
-            };
-            await appendFile(this.queryLogPath, `${JSON.stringify(result)}\n`, "utf8");
-            return result;
-        }
+    async getImpactContext(_task, skill) {
+        const result = agentDrivenResult("codegraph", this.config.mcp.codegraph, skill);
+        await appendFile(this.queryLogPath, `${JSON.stringify(result)}\n`, "utf8");
+        return result;
     }
 }
 export class KnowledgeGraphSource {
@@ -96,38 +41,10 @@ export class KnowledgeGraphSource {
         this.config = config;
         this.queryLogPath = queryLogPath;
     }
-    async searchKnowledge(task, skill, codeContext) {
-        const request = {
-            type: "knowledge.search",
-            task,
-            skill: skill.name,
-            queries: skill.contextQueries,
-            codeContext
-        };
-        try {
-            const data = await postJson(this.config.mcp.knowledgeGraph.url, request, this.config.mcp.timeoutMs);
-            const result = {
-                source: "knowledgeGraph",
-                ok: true,
-                degraded: false,
-                request,
-                responseSummary: summarize(data),
-                data
-            };
-            await appendFile(this.queryLogPath, `${JSON.stringify(result)}\n`, "utf8");
-            return result;
-        }
-        catch (error) {
-            const result = {
-                source: "knowledgeGraph",
-                ok: false,
-                degraded: true,
-                request,
-                error: error instanceof Error ? error.message : String(error)
-            };
-            await appendFile(this.queryLogPath, `${JSON.stringify(result)}\n`, "utf8");
-            return result;
-        }
+    async searchKnowledge(_task, skill) {
+        const result = agentDrivenResult("knowledgeGraph", this.config.mcp.knowledgeGraph, skill);
+        await appendFile(this.queryLogPath, `${JSON.stringify(result)}\n`, "utf8");
+        return result;
     }
 }
 export class ContextSource {
@@ -139,7 +56,7 @@ export class ContextSource {
     }
     async searchTaskContext(task, skill) {
         const codeContext = await this.codeGraph.getImpactContext(task, skill);
-        const knowledgeContext = await this.knowledgeGraph.searchKnowledge(task, skill, codeContext.data ?? codeContext.error);
+        const knowledgeContext = await this.knowledgeGraph.searchKnowledge(task, skill);
         return { codeContext, knowledgeContext };
     }
 }

package/dist/runPaths.js

@@ -12,6 +12,7 @@ export function makeRunPaths(cwd, config, task) {
         agentPrompt: path.join(runDir, "agent_prompt.md"),
         plan: path.join(runDir, "plan.md"),
         executionLog: path.join(runDir, "execution.log"),
+        agentContract: path.join(runDir, "agent_contract.json"),
         gitDiff: path.join(runDir, "git_diff.patch"),
         verify: path.join(runDir, "verify.json"),
         summary: path.join(runDir, "summary.md"),

package/dist/summarize.js

@@ -2,14 +2,14 @@ import { readFile, writeFile } from "node:fs/promises";
 import { truncate } from "./utils.js";
 export async function writeSummary(options) {
     const diff = await readFile(options.gitDiffPath, "utf8").catch(() => "");
-    const summary = `# Run Summary
+    const summary = `# 运行总结
 
-## Executive Status
-- Task status: ${options.agentResult?.status === "success" && options.verifyResult?.status === "passed" ? "ready for review" : "requires attention"}
-- Agent status: ${options.agentResult?.status ?? "not-run"}
-- Verification status: ${options.verifyResult?.status ?? "not-run"}
+## 执行状态
+- 任务状态: ${options.agentResult?.status === "success" && options.verifyResult?.status === "passed" ? "可进入评审" : "需要关注"}
+- Agent 状态: ${options.agentResult?.status ?? "未运行"}
+- 验证状态: ${options.verifyResult?.status ?? "未运行"}
 
-## Task
+## 任务
 ${options.task}
 
 ## Skill
@@ -18,54 +18,57 @@ ${options.skillName}
 ## Agent
 ${options.agentName}
 
-## Execution
-- Status: ${options.agentResult?.status ?? "not-run"}
-- Exit code: ${options.agentResult?.exitCode ?? "n/a"}
-- Changed files: ${options.agentResult?.changedFiles.join(", ") || "(none)"}
+## 执行结果
+- 状态: ${options.agentResult?.status ?? "未运行"}
+- 退出码: ${options.agentResult?.exitCode ?? "n/a"}
+- 修改文件: ${options.agentResult?.changedFiles.join(", ") || "无"}
 
-## Verification
-- Status: ${options.verifyResult?.status ?? "not-run"}
+## 验证结果
+- 状态: ${options.verifyResult?.status ?? "未运行"}
 
-## Review Checklist
-- Confirm the change is limited to the requested task.
-- Confirm public interfaces and backward compatibility were preserved.
-- Confirm verification failures or skipped checks are understood.
-- Confirm Knowledge Graph suggestions are reviewed before persistence.
+## 评审检查清单
+- 确认变更限定在任务范围内。
+- 确认公共接口和向后兼容性没有被意外破坏。
+- 确认失败或跳过的验证项已被理解。
+- 确认知识沉淀建议经过人工评审后再写入 Knowledge Graph。
 
-## PR Description Draft
-### What changed
-${options.agentResult?.changedFiles.length ? `Updated ${options.agentResult.changedFiles.length} file(s).` : "No file changes detected."}
+## PR 描述草稿
+### 变更内容
+${options.agentResult?.changedFiles.length ? `更新 ${options.agentResult.changedFiles.length} 个文件。` : "未检测到文件变更。"}
 
-### Why
-- See execution.log for the agent's impact analysis, plan, and final report.
+### 变更原因
+- 见 execution.log 中的 Agent 影响分析、计划和最终报告。
 
-### Verification
-${options.verifyResult?.commands.map((cmd) => `- ${cmd.name}: ${cmd.exitCode === 0 ? "passed" : "failed"} (${cmd.command})`).join("\n") || "- Not run"}
+### 验证
+${options.verifyResult?.commands.map((cmd) => `- ${cmd.name}: ${cmd.exitCode === 0 ? "通过" : "失败"} (${cmd.command})`).join("\n") || "- 未运行"}
 
-### Risk
-- Review required for correctness, safety, compatibility, and knowledge persistence before merging.
+### 风险
+- 合并前需要评审正确性、安全性、兼容性和知识沉淀建议。
 
-### Knowledge Follow-up
-- Review persist_suggestions.md before updating Knowledge Graph.
+### 知识沉淀跟进
+- 写入 Knowledge Graph 前先评审 persist_suggestions.md。
 
-## Diff Snapshot
+## Diff 快照
 \`\`\`diff
 ${truncate(diff, 12000)}
 \`\`\`
 `;
-    const persist = `# Knowledge Persist Suggestions
+    const persist = `# 知识沉淀建议
 
-Review these suggestions before updating the Knowledge Graph.
+写入 Knowledge Graph 前，请先人工评审这些建议。
 
-- Task: ${options.task}
+- 任务: ${options.task}
 - Skill: ${options.skillName}
-- Changed files: ${options.agentResult?.changedFiles.join(", ") || "(none)"}
-- Persistence policy: human review required before writing to Knowledge Graph.
-- Suggested knowledge updates:
-  - Add or update module notes if the change clarifies ownership or behavior.
-  - Add ADR/decision note if the implementation chose between meaningful alternatives.
-  - Add runbook/testing note if verification uncovered a recurring operational step.
-  - Record known MCP degradation or missing context if it affected confidence.
+- 修改文件: ${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 上下文影响了信心，记录缺失项。
 `;
     await writeFile(options.summaryPath, summary, "utf8");
     await writeFile(options.persistPath, persist, "utf8");