ai-dev-harness 0.1.0

package/dist/templates.js

@@ -0,0 +1,217 @@
+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
+`
+    }
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.js

@@ -0,0 +1,95 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+export async function pathExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+export async function writeFileIfMissing(filePath, content) {
+    if (await pathExists(filePath))
+        return false;
+    await ensureDir(path.dirname(filePath));
+    await writeFile(filePath, content, "utf8");
+    return true;
+}
+export async function readTextIfExists(filePath) {
+    if (!(await pathExists(filePath)))
+        return "";
+    return readFile(filePath, "utf8");
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function slugify(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48) || "task";
+}
+export function timestampId() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+export function truncate(input, max = 4000) {
+    if (input.length <= max)
+        return input;
+    return `${input.slice(0, max)}\n...[truncated ${input.length - max} chars]`;
+}
+export function runCommand(command, cwd, input, timeoutMs = 10 * 60 * 1000, options = {}) {
+    const started = Date.now();
+    return new Promise((resolve) => {
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+            child.kill();
+            stderr += `\nCommand timed out after ${timeoutMs}ms.`;
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            const text = chunk.toString();
+            stdout += text;
+            if (options.live)
+                process.stdout.write(options.stdoutPrefix ? prefixLines(text, options.stdoutPrefix) : text);
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = chunk.toString();
+            stderr += text;
+            if (options.live)
+                process.stderr.write(options.stderrPrefix ? prefixLines(text, options.stderrPrefix) : text);
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            resolve({ exitCode: null, stdout, stderr: `${stderr}\n${error.message}`, durationMs: Date.now() - started });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ exitCode: code, stdout, stderr, durationMs: Date.now() - started });
+        });
+        if (input)
+            child.stdin.write(input);
+        child.stdin.end();
+    });
+}
+function prefixLines(text, prefix) {
+    return text
+        .split(/(\r?\n)/)
+        .map((part) => (part === "\n" || part === "\r\n" || part === "" ? part : `${prefix}${part}`))
+        .join("");
+}
+export async function git(cwd, args) {
+    const result = await runCommand(`git ${args}`, cwd, undefined, 60_000);
+    return result.exitCode === 0 ? result.stdout.trim() : "";
+}

package/dist/verify.js

@@ -0,0 +1,28 @@
+import { writeFile } from "node:fs/promises";
+import { runCommand, truncate } from "./utils.js";
+export async function runVerify(cwd, config, skill, verifyPath) {
+    const commands = skill.verifyCommands.length ? skill.verifyCommands : config.verify.defaultCommands;
+    if (!commands.length) {
+        const skipped = { status: "skipped", commands: [] };
+        await writeFile(verifyPath, `${JSON.stringify(skipped, null, 2)}\n`, "utf8");
+        return skipped;
+    }
+    const results = [];
+    for (const command of commands) {
+        const result = await runCommand(command.command, cwd);
+        results.push({
+            name: command.name,
+            command: command.command,
+            exitCode: result.exitCode,
+            stdout: truncate(result.stdout, 6000),
+            stderr: truncate(result.stderr, 6000),
+            durationMs: result.durationMs
+        });
+    }
+    const verify = {
+        status: results.every((item) => item.exitCode === 0) ? "passed" : "failed",
+        commands: results
+    };
+    await writeFile(verifyPath, `${JSON.stringify(verify, null, 2)}\n`, "utf8");
+    return verify;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ai-dev-harness",
+  "version": "0.1.0",
+  "description": "Auditable AI development harness for Codex and Claude Code.",
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "agent",
+    "codex",
+    "claude",
+    "harness",
+    "mcp",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "harness": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "!dist/**/*.test.js",
+    "!dist/testSupport.js",
+    "scripts/",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/**/*.test.js",
+    "start": "node dist/cli.js",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}

package/scripts/read-evidence.ps1

@@ -0,0 +1,36 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [string]$Run,
+
+  [string]$Repo = (Get-Location).Path
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoPath = Resolve-Path -LiteralPath $Repo
+$runPath = if (Test-Path -LiteralPath $Run) {
+  Resolve-Path -LiteralPath $Run
+} else {
+  Resolve-Path -LiteralPath (Join-Path $repoPath "runs\$Run")
+}
+
+Write-Host "[harness-skill] evidence: $runPath"
+
+$summary = Join-Path $runPath "summary.md"
+$verify = Join-Path $runPath "verify.json"
+$audit = Join-Path $runPath "audit.jsonl"
+
+if (Test-Path -LiteralPath $summary) {
+  Write-Host "`n--- summary.md ---"
+  Get-Content -LiteralPath $summary
+}
+
+if (Test-Path -LiteralPath $verify) {
+  Write-Host "`n--- verify.json ---"
+  Get-Content -LiteralPath $verify
+}
+
+if (Test-Path -LiteralPath $audit) {
+  Write-Host "`n--- audit degraded/errors ---"
+  Select-String -LiteralPath $audit -Pattern "degraded|failed|error|run_finished" | ForEach-Object { $_.Line }
+}

package/scripts/run-harness.ps1

@@ -0,0 +1,53 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [string]$Task,
+
+  [Parameter(Mandatory = $true)]
+  [ValidateSet("fix_bug", "add_feature", "write_tests", "update_docs")]
+  [string]$Skill,
+
+  [Parameter(Mandatory = $true)]
+  [ValidateSet("claude", "codex")]
+  [string]$Agent,
+
+  [string]$Repo = (Get-Location).Path,
+
+  [switch]$Live = $true
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoPath = Resolve-Path -LiteralPath $Repo
+$harnessYaml = Join-Path $repoPath "harness.yaml"
+$cliPath = Resolve-Path -LiteralPath (Join-Path $PSScriptRoot "..\dist\cli.js")
+
+Write-Host "[harness-skill] repo: $repoPath"
+Write-Host "[harness-skill] checking config: $harnessYaml"
+
+if (-not (Test-Path -LiteralPath $harnessYaml)) {
+  Write-Error "harness.yaml not found in $repoPath. Run: node `"$cliPath`" init"
+}
+
+$gitCheck = git -C $repoPath rev-parse --show-toplevel 2>$null
+if ($LASTEXITCODE -ne 0) {
+  Write-Error "$repoPath is not a Git repository. AI Dev Harness run requires a business Git repository."
+}
+
+$argsList = @(
+  $cliPath,
+  "run",
+  "--task",
+  $Task,
+  "--skill",
+  $Skill,
+  "--agent",
+  $Agent
+)
+
+if ($Live) {
+  $argsList += "--live"
+}
+
+Write-Host "[harness-skill] starting harness: $Skill via $Agent"
+node @argsList
+exit $LASTEXITCODE