agent-harness-kit 0.6.0 → 0.8.0

package/src/templates/.claude/skills/doc-drift-scan/scripts/scan-paths.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// scan-paths.mjs — deterministic step for /doc-drift-scan.
+// Walks docs/ + CLAUDE.md, extracts backtick paths, checks existsSync.
+// Output JSON: { stats, drift }.
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const PATH_IN_BACKTICKS = /`([^`\s][^`]*?)`/g;
+const PATH_LIKE = /^[^|&;$][\w./@-]+\/[\w./@-]+/;
+
+function walkText() {
+  const out = [];
+  if (existsSync(join(ROOT, "CLAUDE.md"))) out.push(join(ROOT, "CLAUDE.md"));
+  if (existsSync(join(ROOT, "docs"))) {
+    for (const f of walkRecursive(join(ROOT, "docs"))) {
+      if (/\.(md|markdown|mdx)$/i.test(f)) out.push(f);
+    }
+  }
+  return out;
+}
+function* walkRecursive(d) {
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    const p = join(d, e.name);
+    if (e.isDirectory()) yield* walkRecursive(p);
+    else yield p;
+  }
+}
+function extractPaths(body) {
+  const found = new Set();
+  let m;
+  while ((m = PATH_IN_BACKTICKS.exec(body)) !== null) {
+    const candidate = m[1].trim();
+    if (!PATH_LIKE.test(candidate)) continue;
+    if (/^https?:\/\//.test(candidate)) continue;
+    found.add(candidate);
+  }
+  return [...found];
+}
+function fileExistsRelative(p) {
+  const clean = p.replace(/:\d+(-\d+)?$/, "");
+  return existsSync(resolve(ROOT, clean));
+}
+
+function main() {
+  const files = walkText();
+  const drift = [];
+  const stats = { docs_scanned: files.length, refs_found: 0, refs_missing: 0 };
+  for (const doc of files) {
+    let body;
+    try { body = readFileSync(doc, "utf8"); } catch { continue; }
+    for (const ref of extractPaths(body)) {
+      stats.refs_found++;
+      if (!fileExistsRelative(ref)) {
+        stats.refs_missing++;
+        drift.push({ doc: relative(ROOT, doc), ref });
+      }
+    }
+  }
+  process.stdout.write(JSON.stringify({ stats, drift }, null, 2) + "\n");
+}
+
+main();

package/src/templates/.claude/skills/garbage-collection/SKILL.md.hbs

@@ -1,7 +1,7 @@
 ---
 name: garbage-collection
 description: Use this skill on Fridays, before tagging a release, or when the user mentions "cleanup", "tech debt", "AI slop", "GC", or "garbage collection". Runs the deterministic linters, structural tests, and doc-drift scans, then proposes the top-3 highest-leverage cleanups (with risk/cost/benefit) — does NOT auto-merge. This is the solo-dev shrunk version of OpenAI's Friday garbage-collection ritual.
-allowed-tools: Read, Glob, Grep, Bash(npm run:*), Bash(pytest:*), Bash(ruff:*), Bash(git:*), Bash(gh:*)
+allowed-tools: Read, Glob, Grep, Bash(npm run:*), Bash(pytest:*), Bash(ruff:*), Bash(git:*), Bash(gh:*), Bash(node .claude/skills/garbage-collection/scripts/gc-classify.mjs:*)
 suggested-turns: 15
 ---
 
@@ -19,10 +19,19 @@ suggested-turns: 15
    - **Doc drift** (a path in `docs/architecture.md` no longer exists) →
      invoke `doc-drift-scan` skill.
    - **Hand-rolled helper** matching a shared utility → propose replacement.
-3. **Score** each candidate fix on three 1–5 dimensions:
-   - **Risk**: 1 = trivial rename, 5 = touches multiple modules.
-   - **Cost**: tokens + minutes.
-   - **Benefit**: how often this drift recurs (read `.harness/gc-history.json`).
+3. **Score** each candidate fix on three 1–5 dimensions via the side-car
+   script (replaces the previous LLM-scored turn — deterministic and
+   auditable):
+
+   ```bash
+   node .claude/skills/garbage-collection/scripts/gc-classify.mjs \
+     --baseline .harness/gc-<date>.json \
+     --history  .harness/gc-history.json
+   ```
+
+   The script applies the mechanical rubric: `risk = 1 + ceil(touched/3)`,
+   `cost = 1 + ceil(lines/30)`, `benefit = recurrenceCount(class)`. Read
+   the JSON `candidates[]` sorted by `(benefit desc, cost asc, risk asc)`.
 4. **Propose ONLY the top 3** cleanups (solo-dev cap; OpenAI does dozens, you
    do 3). Open them as separate PRs with `gh pr create --label gc --draft`.
 5. **Append a row** to `.harness/gc-history.json`:

package/src/templates/.claude/skills/garbage-collection/scripts/gc-classify.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// gc-classify.mjs — deterministic scoring step for /garbage-collection.
+// Replaces "LLM-scored risk/cost/benefit" turn with mechanical rubric.
+//
+// Usage:
+//   gc-classify.mjs --baseline <gc-snapshot.json> [--history <hist.json>] [--out <file>]
+//
+// Rubric:
+//   risk    = 1 + ceil(touched_files / 3)            capped at 5
+//   cost    = 1 + ceil(lines_to_change / 30)         capped at 5
+//   benefit = recurrenceCount(class) from gc-history capped at 5
+
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+function loadJSON(p, fallback = null) {
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return fallback; }
+}
+
+function parseArgs(argv) {
+  const out = { baseline: null, history: ".harness/gc-history.json", out: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--baseline") out.baseline = argv[++i];
+    else if (argv[i] === "--history") out.history = argv[++i];
+    else if (argv[i] === "--out") out.out = argv[++i];
+  }
+  if (!out.baseline) {
+    console.error("usage: gc-classify.mjs --baseline <gc-snapshot.json> [--history <hist.json>] [--out <file>]");
+    process.exit(2);
+  }
+  return out;
+}
+
+function recurrenceCount(history, klass) {
+  if (!history?.runs) return 1;
+  let n = 0;
+  for (const run of history.runs) {
+    if (Array.isArray(run.classes_seen) && run.classes_seen.includes(klass)) n++;
+  }
+  return n;
+}
+
+function cap5(n) { return Math.max(1, Math.min(5, n)); }
+
+function classify(baseline, history) {
+  const violations = Array.isArray(baseline?.violations) ? baseline.violations : [];
+  return violations.map((v) => {
+    const touched = Number(v.files_touched) || 1;
+    const lines = Number(v.lines_estimate) || 5;
+    return {
+      class: v.class || "unknown",
+      path: v.path || "(unspecified)",
+      summary: v.summary || `${v.class} at ${v.path || "(unspecified)"}`,
+      risk: cap5(1 + Math.ceil(touched / 3)),
+      cost: cap5(1 + Math.ceil(lines / 30)),
+      benefit: cap5(recurrenceCount(history, v.class)),
+    };
+  });
+}
+
+function main() {
+  const { baseline, history: histPath, out } = parseArgs(process.argv.slice(2));
+  const base = loadJSON(resolve(baseline));
+  if (!base) {
+    console.error(`gc-classify: cannot read baseline at ${baseline}`);
+    process.exit(2);
+  }
+  const hist = existsSync(resolve(histPath)) ? loadJSON(resolve(histPath), { runs: [] }) : { runs: [] };
+  const scored = classify(base, hist);
+  scored.sort((a, b) => b.benefit - a.benefit || a.cost - b.cost || a.risk - b.risk);
+  const payload = { total: scored.length, candidates: scored };
+  const text = JSON.stringify(payload, null, 2);
+  if (out) writeFileSync(resolve(out), text + "\n");
+  else process.stdout.write(text + "\n");
+}
+
+main();

package/src/templates/.claude/skills/inspect-module/SKILL.md.hbs

@@ -1,7 +1,7 @@
 ---
 name: inspect-module
 description: Use this skill whenever the user mentions "explore", "inspect", "understand", "what does X do", "where is Y", or before adding a new feature in an unfamiliar area. Produces a structured map of one module — files, exports, dependencies, layer assignment, and recent commits — without reading the entire codebase. Always invoke this skill before editing an unfamiliar module so the agent has accurate context, not guesses.
-allowed-tools: Read, Glob, Grep, Bash(git log:*), Bash(git ls-tree:*), Bash(tree:*)
+allowed-tools: Read, Glob, Grep, Bash(git log:*), Bash(git ls-tree:*), Bash(tree:*), Bash(node .claude/skills/inspect-module/scripts/module-summary.mjs:*)
 suggested-turns: 6
 ---
 
@@ -15,19 +15,22 @@ feature Y, what's in the area?", "explore <path>", "show me the shape of
 
 1. **Resolve the target.** If the user gave a feature name (not a path), grep
    `feature_list.json` for it. If multiple paths match, ask the user which.
-2. **Recent activity.** Run `git log --oneline -20 -- <target>` and read the
-   top 3 commit messages.
-3. **Layer.** Cross-reference the path against `harness.config.json` →
-   `domains[].layers` to determine the layer.
-4. **Public surface.** List exported symbols:
-   - TypeScript: `grep -nE "^export " <target>/**/*.ts`
-   - Python: `grep -nE "^def |^class |^[A-Z_][A-Z0-9_]+ ?=" <target>/**/*.py`
-5. **Dependencies.** List inbound imports (who depends on this module) and
-   outbound imports (what this module depends on). Verify both respect the
-   forward-only layer order; if not, **stop and report the violation** before
-   proceeding with any change plan.
-6. **Risks.** Flag any of: dynamic imports, eval, shell-out with
-   interpolation, missing tests for an exported function.
+2. **One-shot summary (deterministic).** Run the side-car script — bundles
+   exports + inbound + outbound deps + layer + recent commits into one JSON
+   blob, replacing three LLM turns of grep:
+
+   ```bash
+   node .claude/skills/inspect-module/scripts/module-summary.mjs <target>
+   ```
+
+   Read the JSON. If `layer` is `null`, the file is outside any configured
+   layer root — flag that and ask whether the user wants to add it.
+3. **Forward-only check.** Walk `outbound[]` and verify each crosses layers
+   forward only (never backward). The structural test enforces this
+   mechanically too, but flagging here short-circuits a wasted write step.
+4. **Risks.** Flag any of: dynamic imports, eval, shell-out with
+   interpolation, missing tests for an exported function. (LLM judgment —
+   the side-car reports facts, not risks.)
 
 ## Output contract
 

package/src/templates/.claude/skills/inspect-module/scripts/module-summary.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// module-summary.mjs — deterministic step for /inspect-module.
+// Bundles exports + outbound + inbound + layer + recent commits in JSON.
+// Prefer ripgrep, fallback grep -rE.
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { resolve, relative, join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function bail(msg) {
+  console.error("module-summary: " + msg);
+  process.exit(2);
+}
+
+// Walk a path (file or directory) and yield matching source files. Skip
+// node_modules, .git, dist, build — folders that contain mountains of
+// irrelevant exports and blow up the result set.
+const SOURCE_EXTS = /\.(ts|tsx|js|jsx|mjs|cjs|py|rs|go|swift|kt|kts)$/i;
+const SKIP_DIRS = new Set(["node_modules", ".git", ".harness", "dist", "build", "target", ".next"]);
+
+function* walkSources(absPath) {
+  let st;
+  try { st = statSync(absPath); } catch { return; }
+  if (st.isFile()) {
+    if (SOURCE_EXTS.test(absPath)) yield absPath;
+    return;
+  }
+  if (!st.isDirectory()) return;
+  for (const entry of readdirSync(absPath, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") && entry.name !== "." && entry.name !== "..") {
+      if (SKIP_DIRS.has(entry.name)) continue;
+    }
+    if (SKIP_DIRS.has(entry.name)) continue;
+    yield* walkSources(join(absPath, entry.name));
+  }
+}
+
+// scan: read each file line-by-line, run the regex, collect matches with
+// per-line annotation `path:line: content`. Pure Node — no external grep
+// dependency, so the script works the same on macOS local, Linux CI,
+// minimal Alpine, etc. (Previous shell-out to grep failed on CI with an
+// empty result set; root cause: spawn-time differences between BSD and
+// GNU grep when the target argument is a single file. Node fs is the
+// portable answer.)
+function scan(target, regex) {
+  const lines = [];
+  const absTarget = resolve(ROOT, target);
+  for (const file of walkSources(absTarget)) {
+    let body;
+    try { body = readFileSync(file, "utf8"); } catch { continue; }
+    const rel = relative(ROOT, file);
+    const fileLines = body.split("\n");
+    for (let i = 0; i < fileLines.length; i++) {
+      if (regex.test(fileLines[i])) {
+        lines.push(`${rel}:${i + 1}: ${fileLines[i]}`);
+      }
+    }
+  }
+  return lines;
+}
+
+function listExports(target) {
+  const out = new Set();
+  for (const line of scan(target, /^export /)) {
+    const m = line.match(/^([^:]+):(\d+):\s*export\s+(.*)$/);
+    if (m) out.add(`${m[3].slice(0, 80)}  (${m[1]}:${m[2]})`);
+  }
+  for (const line of scan(target, /^(def |class )/)) {
+    const m = line.match(/^([^:]+):(\d+):\s*(def|class)\s+(\w+)/);
+    if (m) out.add(`${m[3]} ${m[4]}  (${m[1]}:${m[2]})`);
+  }
+  return [...out].slice(0, 50);
+}
+
+function outboundDeps(target) {
+  const out = new Set();
+  for (const line of scan(target, /^(import |from |use crate)/)) {
+    const m = line.match(/^[^:]+:\d+:\s*(.+)$/);
+    if (m) out.add(m[1].trim().slice(0, 100));
+  }
+  return [...out].slice(0, 50);
+}
+
+function inboundDeps(target) {
+  const relTarget = relative(ROOT, resolve(ROOT, target));
+  const name = relTarget.split("/").pop().replace(/\.[a-z]+$/i, "");
+  if (!name) return [];
+  const seen = new Set();
+  // Search the whole project root for references back to the target
+  // module. Filter out self-references.
+  const re = new RegExp(`(import|from|require\\().*['"][^'"]*${name.replace(/[.*+?^${}()|[\\\]\\\\]/g, "\\\\$&")}`);
+  for (const line of scan(".", re)) {
+    const m = line.match(/^([^:]+):\d+:/);
+    if (m && m[1] !== relTarget && !m[1].endsWith(`/${relTarget}`)) seen.add(m[1]);
+  }
+  return [...seen].slice(0, 30);
+}
+
+function readLayers() {
+  try { return JSON.parse(readFileSync(resolve(ROOT, "harness.config.json"), "utf8")); }
+  catch { return null; }
+}
+
+function whichLayer(target, cfg) {
+  if (!cfg?.domains) return null;
+  const rel = relative(ROOT, resolve(ROOT, target));
+  for (const d of cfg.domains) {
+    if (!d?.layers || !d.root) continue;
+    for (const layer of d.layers) {
+      const prefix = `${d.root}/${layer}/`;
+      if (rel.startsWith(prefix) || rel === `${d.root}/${layer}`) {
+        return { domain: d.name || "default", layer };
+      }
+    }
+  }
+  return null;
+}
+
+function recentCommits(target) {
+  const r = spawnSync("git", ["log", "--oneline", "-5", "--", target], { cwd: ROOT, encoding: "utf8" });
+  if (r.status !== 0) return [];
+  return (r.stdout || "").split("\n").filter(Boolean);
+}
+
+function main() {
+  const target = process.argv[2];
+  if (!target) bail("missing target path argument");
+  const abs = resolve(ROOT, target);
+  if (!existsSync(abs)) bail(`target not found: ${target}`);
+  const cfg = readLayers();
+  const out = {
+    module: relative(ROOT, abs),
+    layer: whichLayer(target, cfg),
+    exports: listExports(target),
+    outbound: outboundDeps(target),
+    inbound: inboundDeps(target),
+    recent: recentCommits(target),
+  };
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+}
+
+main();

package/src/templates/CLAUDE.md.hbs

@@ -10,7 +10,7 @@ an encyclopedia.
 - Dev:        `{{devCmd}}`
 - Test:       `{{testCmd}}`
 - Lint:       `{{lintCmd}}`
-- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}{{#if isGo}}go run harness/structural_check.go{{else}}{{#if isRust}}node harness/structural-check.mjs{{else}}npm run harness:check{{/if}}{{/if}}{{/if}}` (must pass before any PR)
+- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}{{#if isGo}}go run harness/structural_check.go{{else}}{{#if isRust}}node harness/structural-check.mjs{{else}}{{#if isSwift}}node harness/structural-check.mjs{{else}}{{#if isKotlin}}node harness/structural-check.mjs{{else}}npm run harness:check{{/if}}{{/if}}{{/if}}{{/if}}{{/if}}` (must pass before any PR)
 
 ## Architecture (brief)
 
@@ -31,11 +31,15 @@ Full list: `docs/golden-principles.md`.
 
 ## Where to look (read on demand)
 
-- `docs/architecture.md`     — read when adding a new module or moving code.
-- `docs/adr/`                — read when changing public APIs.
-- `docs/golden-principles.md` — read before any refactor.
-- `feature_list.json`        — read before claiming a feature is done.
-- `.harness/PROGRESS.md`     — read at session start; write at session end.
+The lines below use Claude Code 2.1+ `@`-imports — Claude loads the file
+into context only when this section is referenced, keeping the working
+CLAUDE.md tiny.
+
+- @docs/architecture.md      — when adding a new module or moving code.
+- @docs/adr/                 — when changing public APIs.
+- @docs/golden-principles.md — before any refactor.
+- @feature_list.json         — before claiming a feature is done.
+- `.harness/PROGRESS.md`     — read at session start; append at session end (kit-managed, not @-imported).
 
 ## Skills you should use
 

package/src/templates/CLAUDE.md.vi.hbs

@@ -0,0 +1,74 @@
+# {{projectName}} — Ghi chú làm việc cho Agent
+
+{{description}} Dự án {{language}}/{{framework}}. Solo-dev hobby. File này
+**cố ý ngắn** — nó là **Mục lục**, không phải Bách khoa toàn thư.
+
+## Build & Run
+
+- Cài đặt:   `{{installCmd}}`
+- Dev:       `{{devCmd}}`
+- Test:      `{{testCmd}}`
+- Lint:      `{{lintCmd}}`
+- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}{{#if isGo}}go run harness/structural_check.go{{else}}{{#if isRust}}node harness/structural-check.mjs{{else}}{{#if isSwift}}node harness/structural-check.mjs{{else}}{{#if isKotlin}}node harness/structural-check.mjs{{else}}npm run harness:check{{/if}}{{/if}}{{/if}}{{/if}}{{/if}}` (phải pass trước mọi PR)
+
+## Kiến trúc (tóm tắt)
+
+Thứ tự layer, ép buộc bằng test cơ học:
+
+**{{layersJoined}}** — code chỉ được phụ thuộc theo chiều tiến. Các mối
+quan tâm cắt ngang (cross-cutting) vào qua `providers/`.
+
+Sơ đồ đầy đủ và lý do: `docs/architecture.md` (chỉ tiếng Anh).
+
+## Nguyên tắc vàng (phải giữ)
+
+1. Ưu tiên utility chung trong `src/shared/` thay vì viết helper mới.
+2. Validate ở biên hệ thống; không bao giờ "đoán mò" hình dạng dữ liệu.
+3. Mỗi test là end-to-end qua một feature trong `feature_list.json`.
+
+Danh sách đầy đủ: `docs/golden-principles.md`.
+
+## Đọc khi cần (read on demand)
+
+Các dòng dưới dùng cú pháp `@`-import của Claude Code 2.1+ — Claude chỉ
+nạp file vào context khi section này được tham chiếu, giữ CLAUDE.md
+luôn gọn.
+
+- @docs/architecture.md      — khi thêm module hoặc dời code.
+- @docs/adr/                 — khi đổi public API.
+- @docs/golden-principles.md — trước mọi refactor.
+- @feature_list.json         — trước khi tuyên bố một feature đã xong.
+- `.harness/PROGRESS.md`     — đọc đầu session; append cuối session (kit quản lý, không @-import).
+
+## Skills nên dùng
+
+- `/inspect-module <path>`            khi cần hiểu code đã có.
+- `/add-feature <description>`        khi thêm khả năng mới — không freestyle.
+- `/structural-test-author <layer>`   khi thêm rule kiến trúc mới.
+- `/garbage-collection`               mỗi thứ Sáu hoặc trước khi tag release.
+- `/eval-runner`                      trước khi merge bất kỳ thay đổi nào ở skill / agent file.
+
+## Subagents nên ủy thác (KHÔNG inline review)
+
+- `architecture-reviewer` — cho mọi thay đổi cross-layer.
+- `security-reviewer`     — cho mọi thay đổi liên quan auth, input, secret.
+- `reliability-reviewer`  — cho mọi error path mới, retry loop, async boundary.
+
+## Workflow contract
+
+1. Bắt đầu session: chạy `/inspect-module .` và đọc `.harness/PROGRESS.md`.
+2. Chọn MỘT feature trong `feature_list.json` có `passes: false`.
+3. Triển khai. Chạy structural test. Nếu fail thì FIX trước khi tiếp tục.
+4. Tự verify bằng subagent reviewer phù hợp.
+5. Commit với message mô tả. Append một dòng vào `.harness/PROGRESS.md`.
+6. Update `feature_list.json` (`passes: true`) **chỉ khi** end-to-end test pass.
+
+## Cấm
+
+- Không thêm layer mới mà không có ADR.
+- Không disable structural test để PR pass.
+- Không viết code mà structural test không thể phân tích (no dynamic
+  imports across layers).
+- Không update CLAUDE.md mà không qua `/propose-harness-improvement`.
+- Không cho CLAUDE.md vượt 200 instruction (hoặc maxTokens nếu đã set)
+  — Stop hook sẽ block. Phần thừa cho vào `docs/` hoặc @-import.