ai-dev-harness 0.1.0

package/dist/context.js

@@ -0,0 +1,114 @@
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ContextSource } from "./mcp.js";
+import { git, pathExists, truncate } from "./utils.js";
+async function listFallbackFiles(cwd, includes, excludes) {
+    const found = [];
+    const excluded = new Set(excludes.map((item) => path.normalize(item)));
+    async function walk(rel) {
+        const normalized = path.normalize(rel);
+        if (excluded.has(normalized) || [...excluded].some((ex) => normalized.startsWith(`${ex}${path.sep}`)))
+            return;
+        const abs = path.join(cwd, rel);
+        if (!(await pathExists(abs)))
+            return;
+        const info = await stat(abs);
+        if (info.isDirectory()) {
+            const entries = await readdir(abs);
+            for (const entry of entries)
+                await walk(path.join(rel, entry));
+            return;
+        }
+        if (info.size <= 80_000)
+            found.push(rel);
+    }
+    for (const item of includes)
+        await walk(item);
+    return found.slice(0, 80);
+}
+async function fallbackContext(cwd, config, skill) {
+    const includes = skill.fallbackInclude.length ? skill.fallbackInclude : config.context.fallbackInclude;
+    const files = await listFallbackFiles(cwd, includes, config.context.exclude);
+    const snippets = [];
+    for (const file of files) {
+        try {
+            const text = await readFile(path.join(cwd, file), "utf8");
+            snippets.push(`## ${file}\n\n\`\`\`\n${truncate(text, 5000)}\n\`\`\``);
+        }
+        catch {
+            // Binary or unreadable files are ignored in fallback context.
+        }
+    }
+    return snippets.join("\n\n");
+}
+export async function buildContextPack(options) {
+    const { cwd, task, config, skill, contextPackPath, mcpLogPath, audit } = options;
+    await audit.event({ stage: "context_pack", event: "mcp_query", status: "started" });
+    const source = new ContextSource(config, mcpLogPath);
+    const { codeContext, knowledgeContext } = await source.searchTaskContext(task, skill);
+    const degraded = codeContext.degraded || knowledgeContext.degraded;
+    if (degraded)
+        await audit.event({
+            stage: "context_pack",
+            event: "mcp_query",
+            status: "degraded",
+            detail: {
+                codegraph: codeContext.error,
+                knowledgeGraph: knowledgeContext.error
+            }
+        });
+    else
+        await audit.event({ stage: "context_pack", event: "mcp_query", status: "succeeded" });
+    const branch = await git(cwd, "branch --show-current");
+    const status = await git(cwd, "status --short");
+    const recent = await git(cwd, "log -5 --oneline");
+    const fallback = await fallbackContext(cwd, config, skill);
+    const markdown = `# Context Pack
+
+## How To Use This Context
+- Treat CodeGraph and Knowledge Graph results as primary context when status is ok.
+- If either MCP source is degraded, explicitly mention the degraded source in your analysis and rely on fallback context carefully.
+- Do not assume fallback file snippets are complete repository knowledge.
+- Cross-check task assumptions against Git state, project rules, and available source files before editing.
+- Prefer minimal changes in files directly connected to the task.
+
+## Task
+${task}
+
+## Skill
+${skill.name}
+
+${skill.markdown}
+
+## Git State
+- Branch: ${branch || "(unknown)"}
+
+\`\`\`
+${status || "(clean or unavailable)"}
+\`\`\`
+
+## Recent Commits
+\`\`\`
+${recent || "(unavailable)"}
+\`\`\`
+
+## CodeGraph MCP
+Status: ${codeContext.ok ? "ok" : "degraded"}
+
+\`\`\`json
+${truncate(JSON.stringify(codeContext.data ?? { error: codeContext.error }, null, 2), 12000)}
+\`\`\`
+
+## Knowledge Graph MCP
+Status: ${knowledgeContext.ok ? "ok" : "degraded"}
+
+\`\`\`json
+${truncate(JSON.stringify(knowledgeContext.data ?? { error: knowledgeContext.error }, null, 2), 12000)}
+\`\`\`
+
+## Fallback Repository Context
+${fallback || "(no fallback context found)"}
+`;
+    await writeFile(contextPackPath, markdown, "utf8");
+    return { markdown, degraded, mcpResults: [codeContext, knowledgeContext] };
+}

package/dist/init.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { mkdir } from "node:fs/promises";
+import { rootTemplates, skillTemplates } from "./templates.js";
+import { ensureDir, writeFileIfMissing } from "./utils.js";
+export async function initHarness(cwd) {
+    const created = [];
+    const skipped = [];
+    for (const [file, content] of Object.entries(rootTemplates)) {
+        const target = path.join(cwd, file);
+        if (await writeFileIfMissing(target, content))
+            created.push(file);
+        else
+            skipped.push(file);
+    }
+    await ensureDir(path.join(cwd, "runs"));
+    await ensureDir(path.join(cwd, "skills"));
+    for (const [skillName, files] of Object.entries(skillTemplates)) {
+        await mkdir(path.join(cwd, "skills", skillName), { recursive: true });
+        for (const [file, content] of Object.entries(files)) {
+            const rel = path.join("skills", skillName, file);
+            const target = path.join(cwd, rel);
+            if (await writeFileIfMissing(target, content))
+                created.push(rel);
+            else
+                skipped.push(rel);
+        }
+    }
+    return { created, skipped };
+}

package/dist/integration.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import { appendFile, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+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());
+    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);
+        if (result === "created")
+            created.push(".claude/skills/ai-dev-harness/SKILL.md");
+        else if (result === "updated")
+            updated.push(".claude/skills/ai-dev-harness/SKILL.md");
+        else
+            skipped.push(".claude/skills/ai-dev-harness/SKILL.md");
+    }
+    if (options.agent === "codex" || options.agent === "both") {
+        const result = await installCodexRules(options.targetDir, options.harnessCommand);
+        if (result === "created")
+            created.push("AGENTS.md");
+        else if (result === "updated")
+            updated.push("AGENTS.md");
+        else
+            skipped.push("AGENTS.md");
+    }
+    return { created, updated, skipped };
+}
+async function installScriptAssets(targetDir, packageRoot) {
+    const created = [];
+    const updated = [];
+    const skipped = [];
+    const assets = ["run-harness.ps1", "read-evidence.ps1"];
+    const targetScriptDir = path.join(targetDir, ".harness", "ai-dev-harness", "scripts");
+    await mkdir(targetScriptDir, { recursive: true });
+    for (const asset of assets) {
+        const source = path.join(packageRoot, "scripts", asset);
+        const target = path.join(targetScriptDir, asset);
+        const rel = path.join(".harness", "ai-dev-harness", "scripts", asset);
+        if (!(await pathExists(source)))
+            continue;
+        const next = await readFile(source, "utf8");
+        if (await pathExists(target)) {
+            const current = await readFile(target, "utf8");
+            if (current === next) {
+                skipped.push(rel);
+                continue;
+            }
+            await writeFile(target, next, "utf8");
+            updated.push(rel);
+            continue;
+        }
+        await copyFile(source, target);
+        created.push(rel);
+    }
+    return { created, updated, skipped };
+}
+async function installClaudeSkill(targetDir, harnessCommand) {
+    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);
+        if (current === next)
+            return "skipped";
+        await writeFile(skillPath, next, "utf8");
+        return "updated";
+    }
+    await writeFile(skillPath, claudeSkill(harnessCommand), "utf8");
+    return "created";
+}
+async function installCodexRules(targetDir, harnessCommand) {
+    const agentsPath = path.join(targetDir, "AGENTS.md");
+    const block = codexBlock(harnessCommand);
+    if (!(await pathExists(agentsPath))) {
+        await writeFile(agentsPath, `# Project Agent Rules\n\n${block}`, "utf8");
+        return "created";
+    }
+    const current = await readFile(agentsPath, "utf8");
+    if (current.includes("## AI Dev Harness")) {
+        const next = current.replace(/(?:\r?\n){0,2}## AI Dev Harness[\s\S]*$/m, `\n\n${block}`);
+        if (next === current)
+            return "skipped";
+        await writeFile(agentsPath, next, "utf8");
+        return "updated";
+    }
+    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.
+`;
+}
+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\`.
+`;
+}

package/dist/mcp.js

@@ -0,0 +1,145 @@
+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 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);
+}
+export class CodeGraphSource {
+    config;
+    queryLogPath;
+    constructor(config, queryLogPath) {
+        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;
+        }
+    }
+}
+export class KnowledgeGraphSource {
+    config;
+    queryLogPath;
+    constructor(config, queryLogPath) {
+        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;
+        }
+    }
+}
+export class ContextSource {
+    codeGraph;
+    knowledgeGraph;
+    constructor(config, queryLogPath) {
+        this.codeGraph = new CodeGraphSource(config, queryLogPath);
+        this.knowledgeGraph = new KnowledgeGraphSource(config, queryLogPath);
+    }
+    async searchTaskContext(task, skill) {
+        const codeContext = await this.codeGraph.getImpactContext(task, skill);
+        const knowledgeContext = await this.knowledgeGraph.searchKnowledge(task, skill, codeContext.data ?? codeContext.error);
+        return { codeContext, knowledgeContext };
+    }
+}

package/dist/runPaths.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { slugify, timestampId } from "./utils.js";
+export function makeRunPaths(cwd, config, task) {
+    const runId = `${timestampId()}-${slugify(task)}`;
+    const runDir = path.join(cwd, config.audit.path, runId);
+    return {
+        runId,
+        runDir,
+        intake: path.join(runDir, "intake.json"),
+        mcpQueries: path.join(runDir, "mcp_queries.jsonl"),
+        contextPack: path.join(runDir, "context_pack.md"),
+        agentPrompt: path.join(runDir, "agent_prompt.md"),
+        plan: path.join(runDir, "plan.md"),
+        executionLog: path.join(runDir, "execution.log"),
+        gitDiff: path.join(runDir, "git_diff.patch"),
+        verify: path.join(runDir, "verify.json"),
+        summary: path.join(runDir, "summary.md"),
+        persistSuggestions: path.join(runDir, "persist_suggestions.md"),
+        audit: path.join(runDir, "audit.jsonl")
+    };
+}

package/dist/summarize.js

@@ -0,0 +1,72 @@
+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
+
+## 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"}
+
+## Task
+${options.task}
+
+## Skill
+${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)"}
+
+## Verification
+- Status: ${options.verifyResult?.status ?? "not-run"}
+
+## 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.
+
+## PR Description Draft
+### What changed
+${options.agentResult?.changedFiles.length ? `Updated ${options.agentResult.changedFiles.length} file(s).` : "No file changes detected."}
+
+### Why
+- See execution.log for the agent's impact analysis, plan, and final report.
+
+### Verification
+${options.verifyResult?.commands.map((cmd) => `- ${cmd.name}: ${cmd.exitCode === 0 ? "passed" : "failed"} (${cmd.command})`).join("\n") || "- Not run"}
+
+### Risk
+- Review required for correctness, safety, compatibility, and knowledge persistence before merging.
+
+### Knowledge Follow-up
+- Review persist_suggestions.md before updating Knowledge Graph.
+
+## Diff Snapshot
+\`\`\`diff
+${truncate(diff, 12000)}
+\`\`\`
+`;
+    const persist = `# Knowledge Persist Suggestions
+
+Review these suggestions before updating the Knowledge Graph.
+
+- 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.
+`;
+    await writeFile(options.summaryPath, summary, "utf8");
+    await writeFile(options.persistPath, persist, "utf8");
+}