agent-harness-kit 0.5.0 → 0.6.0

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -67,9 +67,13 @@ Option B: install as a Claude Code plugin
    is ~100 lines). The kit's CLAUDE.md is 50–80 lines.
 2. **Every agent failure becomes a permanent harness change** (Hashimoto's
    discipline). The `/propose-harness-improvement` skill enforces this.
-3. **Computational sensors before LLM sensors** (Fowler/Böckeler). The TS and
+3. **Computational sensors as safety net** (Fowler/Böckeler). The TS and
    Python adapters ship one deterministic structural test per language; LLM
-   subagents are reserved for semantic judgment.
+   subagents are reserved for semantic judgment. Note: in our 1-shot bench
+   (n=3, ts-layered), the agent already followed visible seed patterns and
+   produced 0 boundary violations without enforcement. Treat structural tests
+   as a safety net for drift in long sessions, not as a happy-path
+   differentiator — see [Honest expectations](#honest-expectations).
 4. **Garbage collection over Friday cleanup, scaled to solo** (OpenAI's
    ritual, shrunk to top-3 fixes per week).
 
@@ -140,6 +144,33 @@ agent-harness-kit doctor      # diagnose installed kit + Claude Code env
 agent-harness-kit --version
 ```
 
+## Honest expectations
+
+What this kit **does** differentiate from bare claude-cli (anecdotal + design-level):
+
+- Opinionated CLAUDE.md template (50–80 lines) so context isn't blown on style
+- 10 skills (`/add-feature`, `/garbage-collection`, `/propose-harness-improvement`, …) that codify Hashimoto/OpenAI rituals
+- 5 read-only review subagents for cheap second-opinion passes
+- `feature_list.json` + ADR template + GC ritual for solo-scale planning hygiene
+- Solo-dev cost defaults (~$2/day) and per-run budget enforcement
+
+What it does **not** measurably differentiate (5 consecutive null benches, May 2026):
+
+- Structural enforcement on happy-path 1-shot tasks. When seed code shows the
+  layer pattern, claude-cli follows it — the boundaries lint has nothing to
+  catch. We measured 0/6 ui→repo violations across bare and kit arms on the
+  `ts-layered` fixture.
+
+Where the structural test *might* still earn its keep (untested, listed for
+honesty, not as a claim):
+
+- Long multi-turn sessions where pattern context drifts
+- Adversarial "make it fast" pressure that tempts shortcuts
+- Greenfield code with no existing pattern to follow
+- Weaker model substrates (haiku, gpt-4o-mini)
+
+Use the lint as a **safety net**, not as the reason you adopted the kit.
+
 ## Token / cost expectations
 
 A typical day with the default model split (Sonnet 4.6 main + Haiku 4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.5.0",
+  "version": "0.6.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/detect-stack.mjs

@@ -68,6 +68,22 @@ export async function detectStack(cwd) {
   // primary language. Walks 1 level deep into common monorepo dirs.
   await probePolyglot(cwd, result);
 
+  // Rust workspace — must be checked BEFORE package.json because a polyglot
+  // repo (Rust backend + Next.js frontend) typically has BOTH at the root,
+  // and we want the Rust adapter installed by default since structural-test
+  // enforcement matters more for the workspace than for the marketing site.
+  // Single-crate Cargo.toml falls through to the legacy check at the bottom.
+  const rootCargo = await readTextSafe(resolve(cwd, "Cargo.toml"));
+  if (rootCargo && /^\s*\[workspace\]/m.test(rootCargo)) {
+    result.language = "rust";
+    result.framework = "rust-workspace";
+    result.packageManager = "cargo";
+    result.monorepo = true;
+    result.suggestedPreset = "generic";
+    result.availablePresets = ["generic"];
+    return result;
+  }
+
   // JavaScript/TypeScript.
   const pkg = await readJsonSafe(resolve(cwd, "package.json"));
   if (pkg) {

package/src/core/upgrade.mjs

@@ -67,6 +67,37 @@ export async function syncHarnessConfigVersion(cwd, kitVersion) {
   return { changed: true, reason: "synced" };
 }
 
+// Ensure .claude/settings.json includes the critical write-tool permissions.
+// Older kit versions shipped a template without Edit/Write/MultiEdit, which
+// causes agents to silently no-op when they try to modify files. This patch
+// adds any missing entries to the existing `permissions.allow` array without
+// touching anything else the user customized.
+//
+// Exported for unit tests; called from `upgrade()` below.
+export async function ensureWritePermissions(cwd) {
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  if (!existsSync(settingsPath)) return { changed: false, reason: "missing" };
+  const raw = await readFile(settingsPath, "utf8");
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch {
+    return { changed: false, reason: "invalid-json" };
+  }
+  const allow = cfg?.permissions?.allow;
+  if (!Array.isArray(allow)) return { changed: false, reason: "no-allow-list" };
+
+  const required = ["Edit", "Write", "MultiEdit"];
+  const missing = required.filter((p) => !allow.includes(p));
+  if (missing.length === 0) return { changed: false, reason: "already-present" };
+
+  // Prepend missing entries so they appear before other Bash(...) rules,
+  // matching the template's ordering.
+  cfg.permissions.allow = [...missing, ...allow];
+  await writeFile(settingsPath, JSON.stringify(cfg, null, 2) + "\n");
+  return { changed: true, reason: "patched", added: missing };
+}
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_ROOT = resolve(__dirname, "..", "templates");
 
@@ -115,11 +146,19 @@ export async function upgrade({ cwd, kitVersion, yes }) {
     // older `version`/`$schema` (it's user-owned and skipped by the file walk).
     // Sync those two fields so doctor stops flagging drift.
     const cfgSync = await syncHarnessConfigVersion(cwd, kitVersion);
+    // Also patch settings.json if it's missing write permissions (legacy bug).
+    const permSync = await ensureWritePermissions(cwd);
     if (cfgSync.changed) {
       console.log(
         pc.green(`harness.config.json version + $schema synced to v${kitVersion}.`),
       );
-    } else {
+    }
+    if (permSync.changed) {
+      console.log(
+        pc.green(`.claude/settings.json patched: added ${permSync.added.join(", ")}.`),
+      );
+    }
+    if (!cfgSync.changed && !permSync.changed) {
       console.log(pc.green(`Already on v${kitVersion}. Nothing to do.`));
     }
     return;
@@ -263,6 +302,16 @@ export async function upgrade({ cwd, kitVersion, yes }) {
     console.log(pc.dim(`  ${pc.green("~")} harness.config.json (version + $schema synced)`));
   }
 
+  // Patch .claude/settings.json if it's missing the critical write
+  // permissions (Edit/Write/MultiEdit). Old kit versions shipped without
+  // these — agents would silently no-op. Idempotent.
+  const permSync = await ensureWritePermissions(cwd);
+  if (permSync.changed) {
+    console.log(
+      pc.dim(`  ${pc.green("~")} .claude/settings.json (added ${permSync.added.join(", ")})`),
+    );
+  }
+
   console.log(pc.bold(pc.green(`\n✓ upgrade complete (v${kitVersion}).`)));
   if (sidecars.length > 0) {
     console.log(

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

@@ -2,6 +2,9 @@
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "permissions": {
     "allow": [
+      "Edit",
+      "Write",
+      "MultiEdit",
       "Bash(npm run harness:*)",
       "Bash(npm run lint:*)",
       "Bash(npm test:*)",

package/src/templates/_adapter-rust/harness/structural-check.mjs.hbs

@@ -2,16 +2,26 @@
 //
 // Reads harness.config.json. For each domain, walks every .rs file under
 // the domain root (excluding target/, .git/, vendor/) and asserts no
-// `use crate::<layer>::...` import goes "backward" through the layer order.
+// import goes "backward" through the layer order.
 //
-// Layer assignment: a file's layer = first path segment after `<root>/`.
-// E.g. `src/repo/store.rs` belongs to the `repo` layer when
-// `domains[0].root == "src"`.
+// Two layouts are supported:
+//
+//   * Single-crate (default): a file's layer is the first path segment
+//     after `<root>/`. Intra-crate dependencies are written as
+//     `use crate::<layer>::...`.
+//
+//   * Workspace mode (`layerDirPattern` + `useIdentPattern` in
+//     `harness.config.json`): each layer is its own crate. The directory
+//     pattern maps layer name → folder (e.g. `unibot-{layer}` →
+//     `unibot-types/`), and the use-ident pattern maps layer name → the
+//     crate identifier in `use` statements (e.g. `unibot_{layer}` →
+//     `use unibot_types::`). Both default to `{layer}` and preserve the
+//     legacy single-crate behavior.
 //
 // Why Node + regex (not a Cargo binary):
 //   - Avoids polluting the user's Cargo workspace with a check crate.
 //   - Node is already required to install the kit (npx).
-//   - Regex over `use crate::<X>` is sufficient — we never need full
+//   - Regex over `use <crate>::<X>` is sufficient — we never need full
 //     parse trees because the layer rule is a syntactic property.
 //   - `super::` and `self::` are scoped to the current module, which is
 //     by definition the same layer, so we ignore them.
@@ -68,6 +78,12 @@ function* walkRustFiles(root) {
 }
 
 // Returns { layer, domain } or null.
+//
+// Resolution:
+//   1. Strip the domain root prefix from the path.
+//   2. The first segment is the candidate layer directory.
+//   3. Match it against `layerDirPattern` (default `{layer}`) — if the
+//      pattern resolves a layer name, use it.
 function layerOf(relPath, cfg) {
   for (const d of cfg.domains) {
     const altPrefix = d.root + "/";
@@ -78,12 +94,72 @@ function layerOf(relPath, cfg) {
       stripped = relPath.slice(sepPrefix.length);
     else continue;
     const first = stripped.split(/[\/\\]/)[0];
-    if (d.layers.includes(first)) return { layer: first, domain: d };
+    const pattern = d.layerDirPattern || "{layer}";
+    const layer = resolveLayerFromDir(first, pattern, d.layers);
+    if (layer) return { layer, domain: d };
+  }
+  return null;
+}
+
+// Given a directory name and a pattern like `unibot-{layer}`, return the
+// matching layer name from `layers` (or null). Handles the legacy
+// `{layer}` pattern as the identity case.
+function resolveLayerFromDir(dirName, pattern, layers) {
+  if (pattern === "{layer}") {
+    return layers.includes(dirName) ? dirName : null;
+  }
+  // Escape regex specials in the surrounding pattern fragments.
+  const [prefix, suffix] = pattern.split("{layer}");
+  const pre = (prefix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const suf = (suffix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^${pre}(.+?)${suf}$`);
+  const m = dirName.match(re);
+  if (m && layers.includes(m[1])) return m[1];
+  return null;
+}
+
+// Capture the first identifier after `use ` (or `pub use ...`). The trailing
+// `::` is optional — `use demo_service;` is legal Rust even though most
+// real usage is `use demo_service::foo`.
+const USE_RE = /\b(?:pub\s+)?use\s+([a-zA-Z_][a-zA-Z0-9_]*)/g;
+
+function parseUseTargets(line, domain) {
+  const useIdent = domain.useIdentPattern || "crate";
+  const matches = [...line.matchAll(USE_RE)];
+  const layers = [];
+  for (const m of matches) {
+    const ident = m[1];
+    const layer = resolveLayerFromUseIdent(ident, useIdent, domain.layers);
+    if (layer) layers.push(layer);
+  }
+  return layers;
+}
+
+// Map a `use <ident>` to a layer. For single-crate mode this is
+// `use crate::<layer>::...` — `ident == "crate"` and the layer is the
+// SECOND segment. For workspace mode it is `use <crate>::...` where the
+// crate name itself encodes the layer.
+function resolveLayerFromUseIdent(ident, useIdentPattern, layers) {
+  if (useIdentPattern === "crate") {
+    // Legacy single-crate mode: only `use crate::...` matters; the layer
+    // is read from the captured ident only when ident === "crate" but
+    // the actual layer name is the segment AFTER `crate::` — see the
+    // separate `USE_CRATE_RE` path used by the caller for compatibility.
+    return null;
+  }
+  if (useIdentPattern === "{layer}") {
+    return layers.includes(ident) ? ident : null;
   }
+  const [prefix, suffix] = useIdentPattern.split("{layer}");
+  const pre = (prefix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const suf = (suffix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^${pre}(.+?)${suf}$`);
+  const m = ident.match(re);
+  if (m && layers.includes(m[1])) return m[1];
   return null;
 }
 
-// Capture the first identifier after `use crate::` (or `pub use crate::`).
+// Backwards-compat: also keep the original single-crate matcher.
 const USE_CRATE_RE = /\b(?:pub\s+)?use\s+crate::([a-zA-Z_][a-zA-Z0-9_]*)/g;
 
 function parseUseCrate(line) {
@@ -134,9 +210,14 @@ function main() {
 
       const content = readFileSync(file, "utf8");
       const lines = content.split("\n");
+      // Workspace mode uses `useIdentPattern` (e.g. "unibot_{layer}");
+      // single-crate mode keeps the historical `use crate::<layer>::` form.
+      const workspaceMode = !!src.domain.useIdentPattern;
       for (let i = 0; i < lines.length; i++) {
         const codeOnly = stripCommentsAndStrings(lines[i]);
-        const targets = parseUseCrate(codeOnly);
+        const targets = workspaceMode
+          ? parseUseTargets(codeOnly, src.domain)
+          : parseUseCrate(codeOnly);
         for (const tgtLayer of targets) {
           if (!src.domain.layers.includes(tgtLayer)) continue;
           const tgtIdx = src.domain.layers.indexOf(tgtLayer);

package/src/templates/_adapter-typescript/eslint.config.mjs

@@ -22,15 +22,17 @@ export default [
       "boundaries/include": ["src/**/*"],
     },
     rules: {
-      "boundaries/dependencies": [2, {
+      // eslint-plugin-boundaries v5: rule name is `element-types`, not `dependencies`.
+      // Schema: `{ from: ["t1"], allow: ["t2", "t3"] }` — flat arrays of element-type names.
+      "boundaries/element-types": [2, {
         default: "disallow",
         rules: [
-          { from: { type: "ui" },      allow: { to: { type: ["runtime","service","config","types"] } } },
-          { from: { type: "runtime" }, allow: { to: { type: ["service","repo","config","types"] } } },
-          { from: { type: "service" }, allow: { to: { type: ["repo","config","types"] } } },
-          { from: { type: "repo" },    allow: { to: { type: ["config","types"] } } },
-          { from: { type: "config" },  allow: { to: { type: ["types"] } } },
-          { from: { type: "types" },   disallow: { to: { type: "*" } } },
+          { from: ["ui"],      allow: ["runtime", "service", "config", "types"] },
+          { from: ["runtime"], allow: ["service", "repo", "config", "types"] },
+          { from: ["service"], allow: ["repo", "config", "types"] },
+          { from: ["repo"],    allow: ["config", "types"] },
+          { from: ["config"],  allow: ["types"] },
+          { from: ["types"],   disallow: ["*"] },
         ],
       }],
     },

package/src/templates/scripts/pre-push.sh

@@ -2,7 +2,7 @@
 # pre-push hook — Stripe "shift-feedback-left" pattern. Runs only the
 # deterministic checks (structural test + linter + tests on changed files).
 # Lives in scripts/ so it ships with the repo; install via install-git-hooks.sh.
-set -e
+set -eo pipefail
 
 # Baseline monotonic guard. .harness/structural-baseline.json is decreasing-
 # only — fixes REMOVE entries; no path should ADD them. Catches the "mask
@@ -33,11 +33,20 @@ if [ -f "$BASELINE_FILE" ] \
   fi
 fi
 
-echo "[pre-push] running structural test…"
-if [ -f harness.config.json ] && grep -q '"language": "python"' harness.config.json; then
-  python -m harness.structural_test
+# Structural test. Skipped when `structuralTest.engine` is explicitly "none"
+# (e.g. during scaffold of a polyglot repo where the adapter is not yet
+# wired). Without this guard the push fails silently because
+# `npm run harness:check` has no matching script.
+if [ -f harness.config.json ] \
+   && grep -qE '"engine"[[:space:]]*:[[:space:]]*"none"' harness.config.json; then
+  echo "[pre-push] structural test skipped (structuralTest.engine: none)"
 else
-  npm run --silent harness:check
+  echo "[pre-push] running structural test…"
+  if [ -f harness.config.json ] && grep -q '"language": "python"' harness.config.json; then
+    python -m harness.structural_test
+  else
+    npm run --silent harness:check
+  fi
 fi
 
 echo "[pre-push] running lint…"

package/src/templates/scripts/precompletion-checklist.sh.hbs

@@ -39,8 +39,12 @@ run_check() {
   fi
 }
 
-# Structural test.
-if [ -f harness.config.json ]; then
+# Structural test. Skipped when `structuralTest.engine` is explicitly "none"
+# (e.g. during scaffold of a polyglot repo where the adapter is not yet
+# wired). Without this guard the check fails silently with an empty body
+# because `npm run harness:check` has no matching script.
+if [ -f harness.config.json ] \
+   && ! grep -qE '"engine"[[:space:]]*:[[:space:]]*"none"' harness.config.json; then
   if grep -q '"language": "python"' harness.config.json; then
     run_check structural-test python -m harness.structural_test || true
   else
@@ -107,11 +111,17 @@ if [ -f harness.config.json ] && command -v jq >/dev/null 2>&1 && command -v git
     while [ "$i" -lt "$NUM_DOMAINS" ]; do
       ROOT=$(jq -r ".domains[$i].root" harness.config.json)
       DOMAIN=$(jq -r ".domains[$i].name" harness.config.json)
+      # Optional layerDirPattern — supports conventions where the layer
+      # directory is not literally `{layer}`. Example: a Rust workspace
+      # with crates named `unibot-types`, `unibot-crypto`, ... uses
+      # `"layerDirPattern": "unibot-{layer}"`. Defaults to `{layer}`.
+      LAYER_PATTERN=$(jq -r ".domains[$i].layerDirPattern // \"{layer}\"" harness.config.json)
       TOUCHED_COUNT=0
       TOUCHED_NAMES=""
       while IFS= read -r layer; do
         [ -z "$layer" ] && continue
-        if echo "$CHANGED" | grep -qE "^${ROOT}/${layer}(/|$)"; then
+        LAYER_DIR=$(printf '%s' "$LAYER_PATTERN" | sed "s/{layer}/$layer/g")
+        if echo "$CHANGED" | grep -qE "^${ROOT}/${LAYER_DIR}(/|$)"; then
           TOUCHED_COUNT=$((TOUCHED_COUNT + 1))
           TOUCHED_NAMES="$TOUCHED_NAMES $layer"
         fi

package/src/templates/scripts/structural-test-on-edit.sh.hbs

@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
 # PostToolUse hook — runs the structural test on the file just edited.
 # Defensive: never blocks on missing tooling. Exit code 2 = block + Claude reads stderr.
-set -e
+#
+# `pipefail` is critical — without it, `cmd | tail` swallows cmd's exit code
+# and a real structural-test failure looks clean to the agent.
+set -eo pipefail
 
 INPUT=$(cat)
 if ! command -v jq >/dev/null 2>&1; then
@@ -15,6 +18,7 @@ FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 case "$FILE" in
   *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)  ENGINE=ts ;;
   *.py)                               ENGINE=py ;;
+  *.rs)                               ENGINE=rust ;;
   *)                                  exit 0 ;;
 esac
 
@@ -25,6 +29,14 @@ if [ "${AHK_HOOK_MODE:-}" = "warn" ]; then
   exit 0
 fi
 
+# Skip cleanly when the structural test is explicitly disabled (polyglot
+# scaffolds where the adapter is not yet wired). Without this guard every
+# edit fires a failing hook that the agent can't actually fix.
+if [ -f harness.config.json ] \
+   && grep -qE '"engine"[[:space:]]*:[[:space:]]*"none"' harness.config.json; then
+  exit 0
+fi
+
 # Run the structural test scoped to this file. Capture output so we can
 # return only the relevant lines via stderr to Claude.
 if [ "$ENGINE" = "ts" ]; then
@@ -46,6 +58,23 @@ Structural test failed for $FILE.
 Layer order: see harness.config.json.
 Run \`python -m harness.structural_test\` for full output.
 Fix the violation before continuing — do NOT disable the test.
+EOF
+    exit 2
+  fi
+elif [ "$ENGINE" = "rust" ]; then
+  # The Rust adapter is a Node script (`harness/structural-check.mjs`); it
+  # scans the whole workspace rather than a single file because the regex
+  # is cheap. If the script isn't present yet, exit 0 (graceful degrade).
+  if [ ! -f harness/structural-check.mjs ]; then
+    exit 0
+  fi
+  if ! node harness/structural-check.mjs 2>&1 | tail -50 >&2; then
+    cat >&2 <<EOF
+
+Structural test failed (triggered by edit to $FILE).
+Layer order: see harness.config.json.
+Run \`node harness/structural-check.mjs\` for full output.
+Fix the violation before continuing — do NOT disable the test.
 EOF
     exit 2
   fi