agent-harness-kit 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.3.0",
+  "version": "0.4.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": {
@@ -40,7 +40,9 @@
   "scripts": {
     "test": "node --test tests/*.test.mjs",
     "lint": "echo 'no-op (kit is plain ESM JS)'",
-    "selftest": "node bin/cli.mjs --version"
+    "selftest": "node bin/cli.mjs --version",
+    "harness:eval": "node src/templates/_adapter-typescript/harness/eval-runner.mjs",
+    "harness:check": "echo 'no-op (kit-level structural rules are TBD; see .harness/eval/tasks/03-add-structural-rule.json)'"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",

package/src/templates/.claude/agents/architecture-reviewer.md.hbs

@@ -1,6 +1,6 @@
 ---
 name: architecture-reviewer
-description: Use this agent immediately after any change that touches multiple layers, adds a new domain, or modifies imports across module boundaries. Verifies the {{layersJoined}} rule, provider boundaries, and golden-principles.md compliance. Read-only — never modifies files.
+description: Use this agent when the Stop hook surfaces a `multi-layer-review` flag (changes span ≥2 layers in a single domain — mechanical count, not self-judgment), or when a change adds a new domain / modifies imports across module boundaries. Verifies the {{layersJoined}} rule, provider boundaries, and golden-principles.md compliance. Read-only — never modifies files.
 tools: Read, Grep, Glob, Bash({{#if isPython}}python -m harness.structural_test{{else}}npm run harness:check{{/if}}), Bash(git diff:*)
 model: sonnet
 ---

package/src/templates/.claude/skills/propose-harness-improvement/SKILL.md

@@ -18,6 +18,12 @@ suggested-turns: 8
      invoke `/write-skill`.
    - **(d) Wrong layer / architecture** — the structure invited the
      mistake. Fix: write an ADR via `/add-adr`.
+   - **(e) Wrong instruction in prompt** — the failure traces back to a
+     skill/agent prompt that was ambiguous, misleading, or under-constrained.
+     The agent followed the prompt correctly but the prompt itself led astray.
+     Fix: edit the offending file under `.claude/skills/<name>/SKILL.md` or
+     `.claude/agents/<name>.md`. Re-run `/eval-runner` afterward to confirm
+     the regression is closed.
 3. **Append entry** to `docs/agent-failures.md` with: date, symptom, fix,
    fix-type, file modified.
 4. **Apply the fix in the right place.** NEVER paper over with a CLAUDE.md

package/src/templates/CLAUDE.md.hbs

@@ -68,3 +68,5 @@ Full list: `docs/golden-principles.md`.
   imports across layers).
 - Don't update CLAUDE.md without proposing a harness improvement
   (`/propose-harness-improvement`).
+- Don't grow CLAUDE.md past 200 instructions — Stop hook blocks the stop on
+  overflow (HumanLayer measurement). Excess belongs in `docs/` or @-imports.

package/src/templates/docs/agent-failures.md

@@ -15,7 +15,7 @@ The `/propose-harness-improvement` skill appends entries here automatically.
 ```
 ### YYYY-MM-DD  <slug>
 - **Symptom:** <what went wrong>
-- **Classification:** (a) missing context | (b) missing rule | (c) missing tool/skill | (d) wrong layer
+- **Classification:** (a) missing context | (b) missing rule | (c) missing tool/skill | (d) wrong layer | (e) wrong instruction in prompt
 - **Fix applied:** <what we did>
 - **Fix lives in:** path/or/file
 ```

package/src/templates/docs/golden-principles.md.hbs

@@ -74,6 +74,51 @@ Why: Mitchell Hashimoto's discipline. CLAUDE.md is a table of contents — it
 won't be re-read on every action.
 Enforced by: `/propose-harness-improvement` skill.
 
+## 8. CLAUDE.md is bounded — at most 200 instructions
+
+CLAUDE.md is loaded into context every session. Beyond ~150-200 instructions
+(HumanLayer measurement) agents stop following it reliably; verbose
+CLAUDE.md silently degrades behavior. Promote details to `docs/` or use
+`@-imports` to load context on demand.
+
+Why: closes principle 7's loop — without a hard cap, "every failure becomes
+a CLAUDE.md line" is the path of least resistance and CLAUDE.md grows
+unbounded until the agent ignores it.
+Enforced by: Stop hook (`scripts/precompletion-checklist.sh`) counts
+bullets and numbered items in `CLAUDE.md` against
+`harness.config.json` `claudeMd.maxInstructions` (default 200) and blocks
+the stop on overflow.
+
+## 9. Baselines are decreasing-only
+
+`.harness/structural-baseline.json` lists existing violations the codebase
+inherits when a new structural rule is introduced. New code must not add to
+this file — fixes only REMOVE entries.
+
+Why: a growing baseline silently masks structural-test failures. Without
+this guard, the path of least resistance for a violation is "append it to
+the baseline," which defeats the rule. PMD's baseline pattern works only
+because it's enforced as monotonic.
+Enforced by: pre-push hook (`scripts/pre-push.sh`) compares
+`.harness/structural-baseline.json` length to its HEAD version and blocks
+the push when the count grew.
+
+## 10. Reviewer subagent triggers are mechanical, not self-judged
+
+`architecture-reviewer` runs when changes span ≥2 layers in a single
+domain. The decision is made by counting layers off
+`harness.config.json` `domains[].layers` against the changed-file set —
+not by the agent guessing whether its diff "touches multiple layers".
+
+Why: self-judged triggers fail open on borderline cases. The agent that
+just shipped a layer-spanning change is the one least equipped to notice
+it. Mechanical counting closes that gap.
+Enforced by: Stop hook (`scripts/precompletion-checklist.sh`) emits a
+`multi-layer-review` failure when `git` reveals ≥2 touched layers in any
+domain. The agent reads the recommendation, invokes
+`architecture-reviewer` (or documents why review is unnecessary), and the
+loop guard (`stop_hook_active`) lets the next stop succeed.
+
 ---
 
 _Add new principles via `/structural-test-author`, which forces you to

package/src/templates/harness.config.json.hbs

@@ -28,6 +28,10 @@
     "maxFixesPerRun": 3,
     "scope": ["dead-imports", "duplicate-utils", "layer-violations", "doc-drift"]
   },
+  "claudeMd": {
+    "path": "CLAUDE.md",
+    "maxInstructions": 200
+  },
   "models": {
     "main": "claude-sonnet-4-6",
     "reviewers": "claude-sonnet-4-6",

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

@@ -4,6 +4,35 @@
 # Lives in scripts/ so it ships with the repo; install via install-git-hooks.sh.
 set -e
 
+# Baseline monotonic guard. .harness/structural-baseline.json is decreasing-
+# only — fixes REMOVE entries; no path should ADD them. Catches the "mask
+# violations by baselining them" anti-pattern before code leaves the machine.
+# Runs first because a grown baseline silently masks structural-test failures.
+BASELINE_FILE=".harness/structural-baseline.json"
+if [ -f "$BASELINE_FILE" ] \
+   && command -v jq >/dev/null 2>&1 \
+   && git rev-parse --verify HEAD >/dev/null 2>&1 \
+   && git cat-file -e "HEAD:$BASELINE_FILE" 2>/dev/null; then
+  CURRENT_COUNT=$(jq 'length' "$BASELINE_FILE" 2>/dev/null || echo 0)
+  HEAD_COUNT=$(git show "HEAD:$BASELINE_FILE" 2>/dev/null | jq 'length' 2>/dev/null || echo 0)
+  if [ "$CURRENT_COUNT" -gt "$HEAD_COUNT" ]; then
+    {
+      echo
+      echo "[pre-push] BLOCKED: structural-baseline.json grew vs HEAD"
+      echo "  Previous: $HEAD_COUNT entries"
+      echo "  Current:  $CURRENT_COUNT entries (+$((CURRENT_COUNT - HEAD_COUNT)))"
+      echo
+      echo "Baseline is decreasing-only. New violations should be FIXED,"
+      echo "not appended to the baseline."
+      echo
+      echo "To bypass intentionally (e.g. legitimate refactor that re-baselines"
+      echo "across a domain boundary):"
+      echo "  git push --no-verify   # then document the reason in the commit"
+    } >&2
+    exit 2
+  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

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

@@ -53,6 +53,86 @@ elif [ -f pyproject.toml ] && command -v ruff >/dev/null 2>&1; then
   run_check ruff ruff check . || true
 fi
 
+# CLAUDE.md instruction cap. HumanLayer measurement: agents stop following
+# CLAUDE.md reliably beyond ~150-200 bullets/numbered items. Treat the file
+# as a table of contents; promote details to docs/ or @-imports.
+if [ -f harness.config.json ] && command -v jq >/dev/null 2>&1; then
+  CMD_PATH=$(jq -r '.claudeMd.path // "CLAUDE.md"' harness.config.json)
+  CMD_CAP=$(jq -r '.claudeMd.maxInstructions // 200' harness.config.json)
+  if [ -f "$CMD_PATH" ] && [ "$CMD_CAP" -gt 0 ] 2>/dev/null; then
+    CMD_COUNT=$(grep -cE '^[[:space:]]*([-*]|[0-9]+\.)[[:space:]]' "$CMD_PATH" 2>/dev/null || echo 0)
+    if [ "$CMD_COUNT" -gt "$CMD_CAP" ]; then
+      {
+        echo "$CMD_PATH instruction count: $CMD_COUNT (cap: $CMD_CAP)"
+        echo
+        echo "HumanLayer measurement: agents stop following CLAUDE.md reliably"
+        echo "beyond ~150-200 instructions. Your file exceeds the cap."
+        echo
+        echo "Fix options:"
+        echo "  - extract sections to docs/ and link from CLAUDE.md"
+        echo "  - use @-imports to load detailed context on demand"
+        echo "  - delete obsolete rules (run /garbage-collection)"
+        echo
+        echo "Adjust the cap (with justification) in harness.config.json:"
+        echo "  .claudeMd.maxInstructions"
+      } > "$TMPDIR_HOOK/claude-md-cap.out"
+      echo "claude-md-cap" >> "$TMPDIR_HOOK/failed.list"
+    fi
+  fi
+fi
+
+# Multi-layer review trigger. When uncommitted/staged/untracked changes touch
+# ≥2 layers within a single domain, the `architecture-reviewer` subagent
+# should run before commit. Replaces the agent's self-judgment about "touches
+# multiple layers" (the §4.3 #3 ambiguity in the harness-techniques research)
+# with a mechanical count off `harness.config.json` `domains[].layers` /
+# `.root`. Fires once per stop; the loop guard (`stop_hook_active`) lets the
+# next stop succeed after the agent has read the recommendation.
+if [ -f harness.config.json ] && command -v jq >/dev/null 2>&1 && command -v git >/dev/null 2>&1; then
+  CHANGED=$(
+    {
+      git diff --name-only 2>/dev/null || true
+      git diff --name-only --cached 2>/dev/null || true
+      git ls-files --others --exclude-standard 2>/dev/null || true
+    } | sort -u
+  )
+  if [ -n "$CHANGED" ]; then
+    NUM_DOMAINS=$(jq '.domains | length' harness.config.json 2>/dev/null || echo 0)
+    MULTI_OUT="$TMPDIR_HOOK/multi-layer-review.out"
+    : > "$MULTI_OUT"
+    MULTI_HIT=0
+    i=0
+    while [ "$i" -lt "$NUM_DOMAINS" ]; do
+      ROOT=$(jq -r ".domains[$i].root" harness.config.json)
+      DOMAIN=$(jq -r ".domains[$i].name" 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
+          TOUCHED_COUNT=$((TOUCHED_COUNT + 1))
+          TOUCHED_NAMES="$TOUCHED_NAMES $layer"
+        fi
+      done < <(jq -r ".domains[$i].layers[]" harness.config.json)
+      if [ "$TOUCHED_COUNT" -ge 2 ]; then
+        echo "Domain '$DOMAIN' has changes spanning $TOUCHED_COUNT layers:$TOUCHED_NAMES" >> "$MULTI_OUT"
+        MULTI_HIT=1
+      fi
+      i=$((i + 1))
+    done
+    if [ "$MULTI_HIT" = "1" ]; then
+      {
+        echo
+        echo "Recommend invoking the 'architecture-reviewer' subagent before commit."
+        echo "Mechanical detection — replaces self-judgment about 'touches multiple layers'."
+        echo "If review is genuinely not needed (e.g. mass-rename across layers), state"
+        echo "the reason in the commit message and re-run; the loop guard will release."
+      } >> "$MULTI_OUT"
+      echo "multi-layer-review" >> "$TMPDIR_HOOK/failed.list"
+    fi
+  fi
+fi
+
 if [ ! -s "$TMPDIR_HOOK/failed.list" ]; then
   exit 0
 fi