agent-harness-kit 0.7.0 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.7.0"
+        "ref": "v0.8.0"
       },
-      "version": "0.7.0",
+      "version": "0.8.0",
       "description": "Solo-dev harness engineering kit — layered architecture, GC ritual, structural tests, review subagents.",
       "category": "development",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Solo-dev harness engineering kit — layered architecture, garbage-collection ritual, structural tests, review subagents. Optimized for Claude Code 2.1+.",
   "author": {
     "name": "Tuan Le"

package/bin/cli.mjs

@@ -48,6 +48,10 @@ program
     "human language for the CLAUDE.md template (en, vi)",
     "en",
   )
+  .option(
+    "--model <id>",
+    "Claude model to pin in .claude/settings.json (e.g. claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)",
+  )
   .action(async (opts) => {
     const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
     console.log(pc.bold(pc.cyan(`\nagent-harness-kit v${pkg.version}\n`)));
@@ -196,6 +200,7 @@ program
       installCi,
       kitVersion: pkg.version,
       humanLanguage: opts.lang || "en",
+      model: opts.model,
     });
 
     console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Solo-dev harness engineering kit for Claude Code. Layered architecture, structural tests, garbage-collection ritual, review subagents — without the enterprise overhead.",
   "type": "module",
   "bin": {

package/src/core/doctor.mjs

@@ -6,6 +6,7 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { execSync } from "node:child_process";
 import pc from "picocolors";
+import { SUPPORTED_MODELS } from "./render-templates.mjs";
 
 function check(name, ok, info = "") {
   const mark = ok ? pc.green("✓") : pc.red("✗");
@@ -99,6 +100,28 @@ export async function doctor({ cwd, kitVersion }) {
     }
   }
 
+  // 5. Model pin in .claude/settings.json (B4). Catches obvious typos
+  // that would silently no-op in Claude Code.
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  if (existsSync(settingsPath)) {
+    try {
+      const s = JSON.parse(await readFile(settingsPath, "utf8"));
+      if (typeof s.model === "string" && s.model.length > 0) {
+        if (SUPPORTED_MODELS.has(s.model)) {
+          check(`model pin (${s.model})`, true);
+        } else {
+          allOk = false;
+          console.log(
+            pc.red(`  ✗ model pin in .claude/settings.json — "${s.model}" not recognized.`),
+          );
+          console.log(
+            pc.dim(`    Known: ${[...SUPPORTED_MODELS].join(", ")}. Re-run \`agent-harness-kit init --model <id>\`.`),
+          );
+        }
+      }
+    } catch { /* covered by settings parse check elsewhere */ }
+  }
+
   console.log("");
   if (!allOk) {
     process.exit(1);

package/src/core/render-templates.mjs

@@ -23,7 +23,7 @@ const TEMPLATES_ROOT = resolve(__dirname, "..", "templates");
 // Files that the user is expected to edit — they win every time, even on
 // fresh init we won't overwrite if they exist. This list is hard-coded
 // because it's tiny and security-sensitive.
-const USER_OWNED_FILES = new Set([
+export const USER_OWNED_FILES = new Set([
   "CLAUDE.md",
   "AGENTS.md",
   "docs/architecture.md",
@@ -35,7 +35,7 @@ const USER_OWNED_FILES = new Set([
 ]);
 
 // Paths that should be made executable after rendering.
-const EXEC_BITS = new Set([
+export const EXEC_BITS = new Set([
   "scripts/dev-up.sh",
   "scripts/pre-push.sh",
   "scripts/install-git-hooks.sh",
@@ -97,7 +97,21 @@ async function* walk(dir) {
 // will route it. Default is "en" → uses the suffix-less CLAUDE.md.hbs.
 export const SUPPORTED_HUMAN_LANGS = new Set(["en", "vi"]);
 
-function buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage }) {
+// SUPPORTED_MODELS — IDs the kit accepts via `--model` and writes verbatim
+// into `.claude/settings.json#model`. The kit does NOT try to be a model
+// registry — it just rejects obvious typos before they silently no-op in
+// Claude Code (which falls back to the org default on unknown IDs).
+export const SUPPORTED_MODELS = new Set([
+  "claude-opus-4-7",
+  "claude-sonnet-4-6",
+  "claude-haiku-4-5",
+  // Legacy IDs we still accept on upgrade paths.
+  "claude-sonnet-4-5",
+  "claude-haiku-3-5",
+]);
+export const DEFAULT_MODEL = "claude-sonnet-4-6";
+
+export function buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage, model }) {
   const installCmd = (() => {
     if (stack.language === "python") return "pip install -e '.[dev]'";
     if (stack.language === "go") return "go mod download";
@@ -164,6 +178,7 @@ function buildContext({ projectName, preset, layers, stack, kitVersion, humanLan
     lintCmd,
     kitVersion,
     humanLanguage: humanLanguage || "en",
+    model: model || DEFAULT_MODEL,
     isTypescript: stack.language === "typescript",
     isPython: stack.language === "python",
     isGo: stack.language === "go",
@@ -183,7 +198,7 @@ function buildContext({ projectName, preset, layers, stack, kitVersion, humanLan
 // Decide whether a template path should be rendered for this stack/preset.
 // Adapter-specific files live under templates/_adapter-<id>/ and are merged
 // into the root.
-function pathForStack(rel, stack, humanLanguage = "en") {
+export function pathForStack(rel, stack, humanLanguage = "en") {
   // CLAUDE.md locale routing. `CLAUDE.md.hbs` (no language suffix) is the
   // English default. `CLAUDE.md.<lang>.hbs` is rendered into the same
   // target path (`CLAUDE.md`) when the user picks that locale. The
@@ -243,6 +258,59 @@ function sha256(buf) {
   return createHash("sha256").update(buf).digest("hex");
 }
 
+// Inject a statusLine block into .claude/settings.json. Idempotent: if the
+// existing statusLine already references the kit's script, leave it; otherwise
+// set it to invoke scripts/statusline.mjs via node. Doesn't clobber a
+// user-customised type:"command" entry that points at a different command.
+//
+// Returns {changed, rawContent} for the lockfile bookkeeping (mirrors the
+// mergeHooksIntoSettings contract).
+export async function mergeStatusLineIntoSettings(cwd) {
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  const scriptPath = resolve(cwd, "scripts/statusline.mjs");
+  if (!existsSync(scriptPath)) return { changed: false, rawContent: "" };
+  let settings = {};
+  let raw = "";
+  if (existsSync(settingsPath)) {
+    raw = await readFile(settingsPath, "utf8");
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      throw new Error(
+        `mergeStatusLineIntoSettings: ${settingsPath} is not valid JSON`,
+      );
+    }
+  }
+  const desired = {
+    type: "command",
+    command: "node scripts/statusline.mjs",
+  };
+  // Preserve a user-customised entry if it already points elsewhere. We only
+  // inject when statusLine is absent OR explicitly references our script.
+  const cur = settings.statusLine;
+  if (
+    cur &&
+    typeof cur === "object" &&
+    cur.type === "command" &&
+    typeof cur.command === "string" &&
+    !/statusline\.mjs/.test(cur.command)
+  ) {
+    return { changed: false, rawContent: Buffer.from(raw) };
+  }
+  if (
+    cur &&
+    typeof cur === "object" &&
+    cur.type === desired.type &&
+    cur.command === desired.command
+  ) {
+    return { changed: false, rawContent: Buffer.from(raw) };
+  }
+  settings.statusLine = desired;
+  const out = JSON.stringify(settings, null, 2) + "\n";
+  await writeFile(settingsPath, out);
+  return { changed: true, rawContent: Buffer.from(out) };
+}
+
 // Merge .claude/hooks/hooks.json#hooks into .claude/settings.json#hooks.
 // Claude Code only reads hooks from settings.json — a free-standing
 // hooks.json is ignored by the runtime. Kept as a file because the plugin
@@ -295,6 +363,7 @@ export async function renderAll({
   installCi,
   kitVersion,
   humanLanguage = "en",
+  model,
 }) {
   registerHelpers();
   if (!SUPPORTED_HUMAN_LANGS.has(humanLanguage)) {
@@ -302,7 +371,12 @@ export async function renderAll({
       `Unsupported humanLanguage "${humanLanguage}". Supported: ${[...SUPPORTED_HUMAN_LANGS].join(", ")}`,
     );
   }
-  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage });
+  if (model && !SUPPORTED_MODELS.has(model)) {
+    throw new Error(
+      `Unsupported model "${model}". Supported: ${[...SUPPORTED_MODELS].join(", ")}`,
+    );
+  }
+  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage, model });
 
   const written = [];
   const skipped = [];
@@ -365,6 +439,17 @@ export async function renderAll({
     }
   }
 
+  // v0.8 — statusLine injection. Runs after hook merge so the lockfile
+  // captures the final settings.json bytes. Idempotent; never clobbers a
+  // user-customised entry that points elsewhere.
+  if (existsSync(resolve(cwd, "scripts/statusline.mjs"))) {
+    const stat = await mergeStatusLineIntoSettings(cwd);
+    if (stat.changed) {
+      lockfile.files[".claude/settings.json"] = sha256(stat.rawContent);
+      written.push(".claude/settings.json (statusLine)");
+    }
+  }
+
   // Write the lockfile last (after we know the full set of files).
   const lockTarget = resolve(cwd, ".harness/installed.json");
   await mkdir(dirname(lockTarget), { recursive: true });

package/src/templates/.claude/hooks/hooks.json

@@ -13,6 +13,18 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/userprompt-guard.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Bash",
@@ -25,6 +37,18 @@
         ]
       }
     ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/notify-on-block.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit|MultiEdit",

package/src/templates/.claude/settings.json.hbs

@@ -21,7 +21,7 @@
       "Bash(command -v:*)"
     ]
   },
-  "model": "{{#if isPython}}claude-sonnet-4-6{{else}}claude-sonnet-4-6{{/if}}",
+  "model": "{{model}}",
   "env": {
     "AGENT_HARNESS_KIT_VERSION": "{{kitVersion}}"
   }

package/src/templates/.claude/skills/doc-drift-scan/SKILL.md

@@ -1,20 +1,25 @@
 ---
 name: doc-drift-scan
 description: Use this skill weekly, before releases, or when the user mentions "stale docs", "doc drift", "docs are wrong", or "the README is out of date". Cross-checks every code path, file path, and command referenced in `docs/` and `CLAUDE.md` against the current repo state and produces a list of stale references — the doc-gardening agent pattern.
-allowed-tools: Read, Glob, Grep, Bash(test -e:*), Bash(command -v:*)
-suggested-turns: 12
+allowed-tools: Read, Glob, Grep, Bash(test -e:*), Bash(command -v:*), Bash(node .claude/skills/doc-drift-scan/scripts/scan-paths.mjs:*)
+suggested-turns: 8
 ---
 
 ## Steps
 
-1. **Extract references.** From `docs/**/*.md` and `CLAUDE.md`, extract:
-   - Backtick paths matching `[a-z0-9_/.\\-]+\\.(md|ts|tsx|js|py|json|yml|yaml|sh)`
-   - Backtick commands (first token after a backtick).
-   - Markdown links to local files (`./...` or `../...`).
-2. **Validate each.**
-   - Paths: `test -e <path>`. If missing, mark as drift.
-   - Commands: `command -v <cmd>`. If not on PATH, mark as drift (but allow
-     a configured allowlist for known optional tools).
+1. **Extract references + validate (deterministic).** Run the side-car
+   script — walks `docs/**/*.md` + `CLAUDE.md`, extracts every backtick-path
+   containing a slash, checks `existsSync` per ref:
+
+   ```bash
+   node .claude/skills/doc-drift-scan/scripts/scan-paths.mjs
+   ```
+
+   Read the JSON: `{ stats: { docs_scanned, refs_found, refs_missing },
+   drift: [{ doc, ref }] }`. Replaces three LLM grep turns.
+2. **Validate commands (LLM judgment, narrow).** Optional second pass for
+   backtick-commands the side-car doesn't classify (no slash → not a path).
+   Use `command -v <cmd>` and allow a small allowlist (`jq`, `gh`, `rg`).
 3. **Group findings.**
    - `missing-paths`: file moved or deleted.
    - `wrong-layer-claim`: doc says module is in layer X, structural test

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

@@ -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

@@ -30,11 +30,15 @@ Danh sách đầy đủ: `docs/golden-principles.md`.
 
 ## Đọc khi cần (read on demand)
 
-- `docs/architecture.md`     — đọc khi thêm module hoặc dời code.
-- `docs/adr/`                — đọc khi đổi public API.
-- `docs/golden-principles.md` — đọc trước mọi refactor.
-- `feature_list.json`        — đọc trước khi tuyên bố một feature đã xong.
-- `.harness/PROGRESS.md`     — đọc đầu session; ghi cuối session.
+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
 

package/src/templates/scripts/notify-on-block.sh.hbs

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Notification hook — OS-native notification when Claude wants attention.
+# macOS osascript / Linux notify-send / Windows skip.
+# Never blocks. Always exits 0. Opt-out: AHK_DISABLE_NOTIFY=1.
+set -eo pipefail
+
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then
+    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
+  else
+    if [ -n "$2" ]; then
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
+    else
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+    fi
+  fi
+}
+
+if [ "${AHK_DISABLE_NOTIFY:-}" = "1" ]; then
+  exit 0
+fi
+
+TYPE=""
+TITLE=""
+BODY=""
+if have_jp; then
+  TYPE=$(echo "$INPUT"  | jp '.notification.type  // empty')
+  TITLE=$(echo "$INPUT" | jp '.notification.title // empty')
+  BODY=$(echo "$INPUT"  | jp '.notification.body  // empty')
+fi
+
+[ -z "$TITLE" ] && TITLE="Claude Code"
+if [ -n "$TYPE" ]; then
+  BODY="[$TYPE] ${BODY}"
+fi
+[ -z "$BODY" ] && BODY="Claude Code wants your attention."
+
+mkdir -p .harness
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+ESCAPED_TITLE=${TITLE//\"/\\\"}
+ESCAPED_BODY=${BODY//\"/\\\"}
+printf '{"ts":"%s","hook":"Notification","type":"%s","title":"%s","body":"%s"}\n' \
+  "$TS" "$TYPE" "$ESCAPED_TITLE" "$ESCAPED_BODY" >> .harness/telemetry.jsonl
+
+OS_KIND=$(uname -s 2>/dev/null || echo "Unknown")
+case "$OS_KIND" in
+  Darwin)
+    OSA_TITLE=${TITLE//\"/\\\"}
+    OSA_BODY=${BODY//\"/\\\"}
+    osascript -e "display notification \"$OSA_BODY\" with title \"$OSA_TITLE\"" >/dev/null 2>&1 || true
+    ;;
+  Linux)
+    if command -v notify-send >/dev/null 2>&1; then
+      notify-send -a "Claude Code" "$TITLE" "$BODY" >/dev/null 2>&1 || true
+    fi
+    ;;
+  *)
+    :
+    ;;
+esac
+
+exit 0

package/src/templates/scripts/statusline.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// statusLine — single compact line into Claude Code's TUI status bar.
+// Reads stdin (Claude Code payload), augments with kit state, emits to
+// stdout. Failure mode: print nothing rather than crash.
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function safeRead(rel) {
+  try { return readFileSync(resolve(CWD, rel), "utf8"); }
+  catch { return null; }
+}
+function safeJSON(rel) {
+  const raw = safeRead(rel);
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { return null; }
+}
+function readStdinSync() {
+  try { return readFileSync(0, "utf8"); } catch { return ""; }
+}
+
+function pieces() {
+  const out = [];
+  const lock = safeJSON(".harness/installed.json");
+  if (lock?.version) out.push(`{kit-v${lock.version}}`);
+
+  const features = safeJSON("feature_list.json");
+  if (features?.features && Array.isArray(features.features)) {
+    const open = features.features.find((f) => f.passes === false);
+    out.push(open ? `feat:${open.id}` : "feat:clean");
+  }
+
+  try {
+    const br = spawnSync("git", ["branch", "--show-current"], {
+      cwd: CWD, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+    const status = spawnSync("git", ["status", "--short"], {
+      cwd: CWD, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (br.status === 0 && br.stdout.trim()) {
+      const dirty = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
+      out.push(dirty > 0 ? `${br.stdout.trim()}(±${dirty})` : br.stdout.trim());
+    }
+  } catch { /* git not on PATH — skip */ }
+
+  const raw = readStdinSync();
+  let payload = null;
+  if (raw) { try { payload = JSON.parse(raw); } catch { /* ignore */ } }
+  if (payload?.context && typeof payload.context.percentage === "number") {
+    out.push(`ctx:${Math.round(payload.context.percentage)}%`);
+  }
+  if (payload?.cost && typeof payload.cost.total === "number") {
+    const v = payload.cost.total;
+    out.push(`$${v < 1 ? v.toFixed(2) : v.toFixed(1)}`);
+  }
+  return out;
+}
+
+const line = pieces().join(" • ");
+if (line) process.stdout.write(line);

package/src/templates/scripts/userprompt-guard.sh.hbs

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — denies prompt patterns that undo harness safety
+# rules. Hard guardrail replacing soft CLAUDE.md guidance.
+#
+# Denied patterns:
+#   1. "ignore previous instructions" / "disregard above"
+#   2. "disable the structural test" / "skip the structural check"
+#   3. "bypass the (Stop|PreToolUse|hook) (rules?|checks?)"
+#   4. "remove the .harness" / "delete .harness directory"
+#   5. "set disableAllHooks: true"
+#
+# Escape hatch: AHK_ALLOW_BYPASS=1 logs to .harness/bypass.log + lets through.
+set -eo pipefail
+
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+have_jq() {
+  [ "${AHK_DISABLE_JQ:-}" = "1" ] && return 1
+  command -v jq >/dev/null 2>&1
+}
+have_jp() {
+  have_jq && return 0
+  command -v node >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/_lib/json-pick.mjs" ] && return 0
+  return 1
+}
+jp() {
+  if have_jq; then
+    if [ -n "$2" ]; then jq -r "$1" "$2"; else jq -r "$1"; fi
+  else
+    if [ -n "$2" ]; then
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1" "$2"
+    else
+      node "$SCRIPT_DIR/_lib/json-pick.mjs" "$1"
+    fi
+  fi
+}
+
+if ! have_jp; then
+  exit 0
+fi
+
+PROMPT=$(echo "$INPUT" | jp '.prompt // empty')
+[ -z "$PROMPT" ] && exit 0
+
+LOWER=$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+REASON=""
+
+if printf '%s' "$LOWER" | grep -qE '(ignore|disregard|forget) (the|all|any|your|previous|prior|above)'; then
+  REASON="Prompts that ask Claude to ignore previous instructions defeat the harness's safety rules. State the actual change you need; the structural test and Stop checklist are deterministic and stay enforced."
+fi
+
+if [ -z "$REASON" ] \
+   && printf '%s' "$LOWER" | grep -qE '(disable|skip|turn off|bypass) (the )?(structural|layer|stop hook|stop check|precompletion|lint|harness:check)'; then
+  REASON="Disabling the structural test or Stop checklist is not how the kit is meant to be used. Fix the violation in code, or open an ADR if the layer rule itself needs to change."
+fi
+
+if [ -z "$REASON" ] \
+   && printf '%s' "$LOWER" | grep -qE 'bypass (the )?(pretooluse|posttooluse|sessionstart|sessionend|precompact|hook|hooks|rules?|checks?)'; then
+  REASON="Prompts that ask to bypass kit hooks defeat their purpose. If a specific hook is wrong for your workflow, edit it explicitly with a commit message; do not phrase the request as 'bypass'."
+fi
+
+if [ -z "$REASON" ] \
+   && printf '%s' "$LOWER" | grep -qE '(remove|delete|wipe|rm -rf|drop) (the )?(\.harness|\.claude)( |/|$|\.)'; then
+  REASON="Removing .harness/ or .claude/ deletes the kit's lockfile, structural baseline, skills, agents, and hooks. Use 'agent-harness-kit upgrade' to refresh installed files; do not delete by hand."
+fi
+
+if [ -z "$REASON" ] \
+   && printf '%s' "$LOWER" | grep -qE 'disableallhooks.*true'; then
+  REASON="disableAllHooks: true defeats every protection the kit installs. Remove specific hooks explicitly if needed; do not flip the master switch."
+fi
+
+if [ -z "$REASON" ]; then
+  exit 0
+fi
+
+if [ "${AHK_ALLOW_BYPASS:-}" = "1" ]; then
+  mkdir -p .harness
+  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  SHA=$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')
+  ESCAPED_PROMPT=${PROMPT//$'\n'/ }
+  ESCAPED_PROMPT=${ESCAPED_PROMPT//\"/\\\"}
+  printf '{"ts":"%s","sha":"%s","bypass":"AHK_ALLOW_BYPASS","reason":"%s","prompt":"%s","hook":"UserPromptSubmit"}\n' \
+    "$TS" "$SHA" "${REASON//\"/\\\"}" "$ESCAPED_PROMPT" >> .harness/bypass.log
+  exit 0
+fi
+
+if command -v node >/dev/null 2>&1; then
+  node -e "
+    const reason = process.argv[1];
+    const out = { decision: 'block', reason };
+    process.stdout.write(JSON.stringify(out));
+  " "$REASON"
+elif have_jq; then
+  jq -nc --arg r "$REASON" '{decision:"block", reason:$r}'
+else
+  echo "$REASON" >&2
+  exit 2
+fi
+exit 0