Skip to content

Harness engineering beginner tutorial, from 0 to 1

feat: add zero-dependency shell audit tool (L03–L12)

Steve Kimoi8d7920eb21d3
diff --git a/README.md b/README.md
index 0cb996e..15b8493 100644
--- a/README.md
+++ b/README.md
@@ -546,6 +546,8 @@ learn-harness-engineering/
│ └── project-NN/ # Per-project starter/ and solution/ directories
├── skills/ # Reusable AI agent skills
│ └── harness-creator/ # Harness engineering skill
+├── tools/ # Zero-dependency shell utilities
+│ └── audit-harness.sh # Shell-based harness audit (L03–L12, no Node.js needed)
├── package.json # VitePress + dev tooling
└── CLAUDE.md # Claude Code instructions for this repo
```
@@ -568,6 +570,20 @@ This repository also includes reusable AI agent skills that you can install dire
- [**harness-creator**](./skills/harness-creator/): A skill that helps you scaffold a production-grade harness for your own project in minutes.
+## Tools
+
+Zero-dependency utilities you can run without installing Node.js.
+
+- [**audit-harness.sh**](./tools/audit-harness.sh): A shell-based audit script that checks an existing repo against all five harness subsystems (L03–L12). Exits 0 when all CRITICAL items pass. No Node.js required — complements `harness-creator`'s `validate-harness.mjs`.
+
+```bash
+# Run directly on any repo
+curl -fsSL https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/tools/audit-harness.sh | bash -s -- /path/to/your/repo
+
+# Or after cloning
+bash tools/audit-harness.sh /path/to/your/repo
+```
+
---
## Other Courses
diff --git a/tools/audit-harness.sh b/tools/audit-harness.sh
new file mode 100755
index 0000000..f6a9374
--- /dev/null
+++ b/tools/audit-harness.sh
@@ -0,0 +1,541 @@
+#!/usr/bin/env bash
+# audit-harness.sh — Zero-dependency shell audit for harness engineering
+# Usage: ./tools/audit-harness.sh [path/to/repo]
+# curl -fsSL https://raw.githubusercontent.com/walkinglabs/learn-harness-engineering/main/tools/audit-harness.sh | bash -s -- /path/to/repo
+# Checks an existing repo for all five harness subsystems (L03–L12).
+# Exit 0 if all CRITICAL items pass; exit 1 otherwise.
+# No Node.js required — complements skills/harness-creator/scripts/validate-harness.mjs
+#
+# Course reference: https://walkinglabs.github.io/learn-harness-engineering/en/
+# Author: Stephen Kimoi (https://github.com/Stephen-Kimoi/harness-engineering-template)
+
+set -euo pipefail
+
+REPO="${1:-.}"
+
+# ── Colours ────────────────────────────────────────────────────────────────────
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+pass() { echo -e " ${GREEN}[PASS]${RESET} $1"; }
+fail() { echo -e " ${RED}[FAIL]${RESET} $1"; }
+warn() { echo -e " ${YELLOW}[WARN]${RESET} $1"; }
+header(){ echo -e "\n${CYAN}${BOLD}$1${RESET}"; }
+
+CRITICAL_PASS=0
+CRITICAL_FAIL=0
+RECOMMENDED_PASS=0
+RECOMMENDED_FAIL=0
+RECS=()
+
+check_critical() {
+ local description="$1"
+ local result="$2" # "pass" or "fail"
+ local fix="${3:-}"
+ if [[ "$result" == "pass" ]]; then
+ pass "[CRITICAL] $description"
+ CRITICAL_PASS=$((CRITICAL_PASS + 1))
+ else
+ fail "[CRITICAL] $description"
+ CRITICAL_FAIL=$((CRITICAL_FAIL + 1))
+ [[ -n "$fix" ]] && RECS+=("${RED}[CRITICAL]${RESET} $fix")
+ fi
+ return 0
+}
+
+check_recommended() {
+ local description="$1"
+ local result="$2"
+ local fix="${3:-}"
+ if [[ "$result" == "pass" ]]; then
+ pass "[RECOMMENDED] $description"
+ RECOMMENDED_PASS=$((RECOMMENDED_PASS + 1))
+ else
+ warn "[RECOMMENDED] $description"
+ RECOMMENDED_FAIL=$((RECOMMENDED_FAIL + 1))
+ [[ -n "$fix" ]] && RECS+=("${YELLOW}[RECOMMENDED]${RESET} $fix")
+ fi
+ return 0
+}
+
+file_exists() { [[ -f "$REPO/$1" ]] && echo "pass" || echo "fail"; }
+dir_exists() { [[ -d "$REPO/$1" ]] && echo "pass" || echo "fail"; }
+any_file_match() {
+ # any_file_match "pattern1" "pattern2" ...
+ for pattern in "$@"; do
+ # shellcheck disable=SC2086
+ if ls $REPO/$pattern 2>/dev/null | grep -q .; then
+ echo "pass"; return
+ fi
+ done
+ echo "fail"
+}
+
+contains_pattern() {
+ local file="$REPO/$1"
+ local pattern="$2"
+ if [[ -f "$file" ]] && grep -qiE "$pattern" "$file" 2>/dev/null; then
+ echo "pass"
+ else
+ echo "fail"
+ fi
+}
+
+instructions_file() {
+ [[ -f "$REPO/AGENTS.md" ]] || [[ -f "$REPO/CLAUDE.md" ]] && echo "pass" || echo "fail"
+}
+
+instructions_path() {
+ [[ -f "$REPO/AGENTS.md" ]] && echo "AGENTS.md" || echo "CLAUDE.md"
+}
+
+makefile_has_target() {
+ local target="$1"
+ if [[ -f "$REPO/Makefile" ]] && grep -qE "^${target}[[:space:]]*:" "$REPO/Makefile" 2>/dev/null; then
+ echo "pass"
+ else
+ echo "fail"
+ fi
+}
+
+echo -e "${BOLD}Harness Engineering Audit${RESET}"
+echo -e "Repo: ${REPO}"
+echo -e "Ref: https://walkinglabs.github.io/learn-harness-engineering/en/"
+
+# ── Subsystem 1: Instructions ──────────────────────────────────────────────────
+header "Subsystem 1: Instructions"
+
+inst="$(instructions_file)"
+check_critical "AGENTS.md or CLAUDE.md exists at repo root" "$inst" \
+ "Create AGENTS.md (or CLAUDE.md) at the repo root. It must answer 'what is this system?' in the first 10 lines and list the verification command."
+
+if [[ "$inst" == "pass" ]]; then
+ ipath="$(instructions_path)"
+ check_critical "Instructions file answers 'what is this system?' in first 10 lines" \
+ "$(head -10 "$REPO/$ipath" 2>/dev/null | grep -qiE "(project|system|service|app|what|overview|this (is|repo|tool))" && echo "pass" || echo "fail")" \
+ "Add a one-line description of the system in the first 10 lines of $ipath (e.g. '# This is a ...' or '## Overview')."
+ check_critical "Verification commands are listed in instructions file" \
+ "$(contains_pattern "$ipath" "(make check|npm test|mix test|pytest|cargo test|make test|yarn test|verification|verify)")" \
+ "Add a Verification section to $ipath listing the command to run (e.g. 'make check' or 'npm test')."
+ check_recommended "Hard constraints (MUST / MUST NOT) are stated" \
+ "$(contains_pattern "$ipath" "(MUST|MUST NOT|must not|must never|constraint|forbidden|never)")" \
+ "Add a Constraints section to $ipath with explicit MUST / MUST NOT rules."
+ check_recommended "State files are enumerated (PROGRESS.md, feature_list)" \
+ "$(contains_pattern "$ipath" "(PROGRESS|feature_list|DECISIONS)")" \
+ "Reference PROGRESS.md, DECISIONS.md, and feature_list.json in $ipath so agents know where state lives."
+ check_recommended "Documentation staleness rule present (update docs with code, no stale docs)" \
+ "$(contains_pattern "$ipath" "(stale|staleness|same commit|doc.*update|update.*doc|outdated)")" \
+ "Add a rule to $ipath: 'Update docs in the same commit as the code change — no stale documentation.'"
+ check_recommended "Commit atomicity rule present (one logical op per commit)" \
+ "$(contains_pattern "$ipath" "(atomic|one commit|same commit|partial commit|consistent.*commit|commit.*consistent)")" \
+ "Add a rule to $ipath: 'One logical operation per commit; the repo must be in a consistent state after every commit.'"
+
+ # L04: Split instructions
+ _inst_lines="$(wc -l < "$REPO/$ipath" 2>/dev/null || echo 999)"
+ check_recommended "Entry file is 50–200 lines (router, not encyclopedia) [L04]" \
+ "$([[ $_inst_lines -le 200 ]] && echo "pass" || echo "fail")" \
+ "$ipath is $_inst_lines lines — split detailed sections into docs/ topic files and link to them from $ipath."
+ check_recommended "Entry file links to topic documents in docs/ [L04]" \
+ "$(contains_pattern "$ipath" "(docs/[a-z])")" \
+ "Add links in $ipath to topic docs in docs/ (e.g. 'See [Architecture](docs/architecture.md)')."
+ check_recommended "Hard constraints section has source/why annotations per rule [L04]" \
+ "$(contains_pattern "$ipath" "(source:|remove when:|why:|added because)")" \
+ "Annotate each constraint in $ipath with a 'source:' or 'why:' comment so agents know the reason (e.g. '# source: outage-2024-03')."
+else
+ fail "[CRITICAL] Cannot check instructions content — file missing"
+ RECS+=("${RED}[CRITICAL]${RESET} Create AGENTS.md at the repo root covering: system description, verification command, constraints, and state file references.")
+ CRITICAL_FAIL=$((CRITICAL_FAIL + 2))
+ warn "[RECOMMENDED] Cannot check hard constraints — file missing"
+ warn "[RECOMMENDED] Cannot check state file references — file missing"
+ RECOMMENDED_FAIL=$((RECOMMENDED_FAIL + 2))
+fi
+
+# Proximity principle: at least one module-level doc exists somewhere under src/lib/app
+check_recommended "Module-level doc (ARCHITECTURE.md or CONSTRAINTS.md) co-located with code" \
+ "$(find "$REPO" -not -path '*/.git/*' \( -name 'ARCHITECTURE.md' -o -name 'CONSTRAINTS.md' \) 2>/dev/null | grep -qv "^$REPO/ARCHITECTURE.md\|^$REPO/CONSTRAINTS.md" && echo "pass" || echo "fail")" \
+ "Create ARCHITECTURE.md or CONSTRAINTS.md inside a code directory (e.g. src/ARCHITECTURE.md) describing that module's design."
+
+# ── Subsystem 2: Tools ─────────────────────────────────────────────────────────
+header "Subsystem 2: Tools"
+
+check_recommended "Tool access is scoped (settings.json, .claude/, or MCP config present)" \
+ "$(any_file_match ".claude/settings.json" ".claude/settings.local.json" "mcp.json" ".mcp.json")" \
+ "Create .claude/settings.json to scope which tools the agent is allowed to use."
+check_recommended "MCP or tool integrations documented in instructions file" \
+ "$(contains_pattern "$(instructions_path 2>/dev/null || echo "AGENTS.md")" "(MCP|tool|permission|capability)")" \
+ "Add a Tools/MCP section to your instructions file listing available integrations and their permitted capabilities."
+
+# ── Subsystem 3: Environment ───────────────────────────────────────────────────
+header "Subsystem 3: Environment"
+
+check_critical "Dependency lockfile present" \
+ "$(any_file_match "package-lock.json" "yarn.lock" "pnpm-lock.yaml" "mix.lock" "Pipfile.lock" "poetry.lock" "requirements.txt" "Cargo.lock" "go.sum" "Gemfile.lock")" \
+ "Commit a dependency lockfile (package-lock.json, yarn.lock, requirements.txt, go.sum, etc.) so installs are reproducible."
+
+check_recommended "Runtime version pinned (.tool-versions, .nvmrc, .python-version, etc.)" \
+ "$(any_file_match ".tool-versions" ".nvmrc" ".node-version" ".python-version" ".ruby-version" ".java-version")" \
+ "Create a .nvmrc (Node) or .python-version (Python) or .tool-versions (asdf) file pinning the exact runtime version."
+
+check_recommended "Makefile (or equivalent task runner) present" \
+ "$(any_file_match "Makefile" "package.json" "mix.exs" "justfile" "Taskfile.yml")" \
+ "Create a Makefile with at least setup, check, and test targets so all repo operations are one command."
+
+check_recommended "Single-command setup target exists (make setup / npm install)" \
+ "$(makefile_has_target "setup")" \
+ "Add a 'setup:' target to your Makefile that installs all dependencies from scratch (e.g. 'setup: npm install')."
+
+check_recommended "Single-command dev server target exists (make dev)" \
+ "$(makefile_has_target "dev")" \
+ "Add a 'dev:' target to your Makefile that starts the local dev server (e.g. 'dev: npm run dev')."
+
+# ── Subsystem 4: State ─────────────────────────────────────────────────────────
+header "Subsystem 4: State"
+
+check_critical "PROGRESS.md exists at repo root" "$(file_exists "PROGRESS.md")" \
+ "Create PROGRESS.md at the repo root with sections: Current State (commit hash + test status), In Progress, Next Steps, and Blockers."
+
+if [[ "$(file_exists "PROGRESS.md")" == "pass" ]]; then
+ check_recommended "PROGRESS.md references current task / in-progress work" \
+ "$(contains_pattern "PROGRESS.md" "(in.progress|current|task|next step|blocker|completed)")" \
+ "Add an '## In Progress' section to PROGRESS.md describing the current task."
+fi
+
+decisions_result="$(any_file_match "DECISIONS.md" "docs/decisions")"
+check_recommended "DECISIONS.md or docs/decisions/ exists" "$decisions_result" \
+ "Create DECISIONS.md at the repo root to log architectural decisions and their rationale."
+
+check_recommended "feature_list.json (or equivalent) exists" \
+ "$(any_file_match "feature_list.json" "features.json" "features.md" "FEATURES.md")" \
+ "Create feature_list.json — an array of objects each with fields: id, behavior, verification, state (values: planned/active/passing)."
+
+if [[ "$(any_file_match "feature_list.json" "features.json")" == "pass" ]]; then
+ fl_file=""
+ for _f in "$REPO/feature_list.json" "$REPO/features.json"; do
+ [[ -f "$_f" ]] && { fl_file="$_f"; break; }
+ done
+ if [[ -n "$fl_file" ]]; then
+ check_recommended "feature_list.json contains required fields (id, behavior, verification, state)" \
+ "$(grep -qE '"id"' "$fl_file" && grep -qE '"behavior"' "$fl_file" && grep -qE '"verification"' "$fl_file" && grep -qE '"state"' "$fl_file" && echo "pass" || echo "fail")"
+ fi
+fi
+
+# ── Subsystem 5: Feedback ──────────────────────────────────────────────────────
+header "Subsystem 5: Feedback"
+
+check_recommended "Makefile has a 'check' target (runs full verification pipeline)" \
+ "$(makefile_has_target "check")" \
+ "Add a 'check:' target to Makefile that runs the full pipeline (lint + tests). This is the single command agents use to verify the repo is green."
+
+check_recommended "Makefile has a 'test' target" \
+ "$(makefile_has_target "test")" \
+ "Add a 'test:' target to Makefile (e.g. 'test: npm test' or 'test: pytest')."
+
+check_critical "Verification command documented in AGENTS.md or CLAUDE.md" \
+ "$(contains_pattern "$(instructions_path 2>/dev/null || echo "AGENTS.md")" "(make check|npm test|mix test|pytest|cargo test|make test|yarn test|verify|verification)")" \
+ "Add a Verification section to your instructions file with the exact command to run (e.g. 'Run \`make check\` — must exit 0 before every commit')."
+
+# ── L05: Cross-Session Continuity ─────────────────────────────────────────────
+header "L05: Cross-Session Continuity"
+
+ipath_l05="$(instructions_path 2>/dev/null || echo "AGENTS.md")"
+
+check_critical "PROGRESS.md has a Current State block (commit hash + test status)" \
+ "$(contains_pattern "PROGRESS.md" "(last commit|current state|commit.*hash|test.*pass|passing.*fail)")" \
+ "Add a '## Current State' section to PROGRESS.md, e.g.: 'Last commit: abc1234 | make check: passing'. Update this on every clock-out."
+
+check_recommended "Clock-in routine documented in instructions (read PROGRESS.md then run check)" \
+ "$(contains_pattern "$ipath_l05" "(clock.in|session start|before touching)")" \
+ "Add a Clock-in section to $ipath_l05: 'Before touching code: read PROGRESS.md, then run make check to confirm green baseline.'"
+
+check_recommended "Clock-out routine documented in instructions (update PROGRESS.md then commit)" \
+ "$(contains_pattern "$ipath_l05" "(clock.out|session end|before closing)")" \
+ "Add a Clock-out section to $ipath_l05: 'Before closing: update PROGRESS.md current state + next steps, run make check, commit.'"
+
+check_recommended "Context anxiety / rushed-finish warning present in instructions" \
+ "$(contains_pattern "$ipath_l05" "(context.*anxi|rushed|running low|skip verif|do not rush)")" \
+ "Add a warning to $ipath_l05: 'If running low on context, do NOT rush to finish — stop, update PROGRESS.md, and commit a clean checkpoint.'"
+
+check_recommended "Commit message guidance (explain why, not just what) present" \
+ "$(contains_pattern "$ipath_l05" "(commit.*why|why.*commit|explain why|not just what)")" \
+ "Add commit guidance to $ipath_l05: 'Write commit messages that explain WHY the change was made, not just what changed.'"
+
+check_recommended "PROGRESS.md Next Steps section exists with specific actions" \
+ "$(contains_pattern "PROGRESS.md" "(next step|next action)")" \
+ "Add a '## Next Steps' section to PROGRESS.md listing specific, actionable items so the next session can start immediately."
+
+# ── L03: Repository as System of Record ───────────────────────────────────────
+header "L03: Repository as System of Record"
+
+ipath_l03="$(instructions_path 2>/dev/null || echo "AGENTS.md")"
+
+_durability="fail"
+if [[ -f "$REPO/PROGRESS.md" ]] && { [[ -f "$REPO/DECISIONS.md" ]] || [[ -d "$REPO/docs/decisions" ]]; }; then
+ _durability="pass"
+fi
+check_recommended "ACID – Durability: cross-session knowledge written to tracked files (PROGRESS + DECISIONS present)" "$_durability" \
+ "Both PROGRESS.md and DECISIONS.md (or docs/decisions/) must exist so cross-session knowledge is never lost in an agent's context window."
+
+check_recommended "ACID – Consistency: verifiable consistent-state predicate documented (make check / equivalent)" \
+ "$(contains_pattern "$ipath_l03" "(make check|consistent state|exits 0|all tests pass|verification pipeline)")" \
+ "Document the consistent-state predicate in $ipath_l03 (e.g. 'The repo is consistent when \`make check\` exits 0')."
+
+check_recommended "ACID – Atomicity: commit atomicity rule stated in instructions" \
+ "$(contains_pattern "$ipath_l03" "(atomic|one commit|same commit|partial commit|consistent.*commit|commit.*consistent)")" \
+ "State commit atomicity in $ipath_l03: 'Each commit must represent one complete logical change; no partial work.'"
+
+check_recommended "Knowledge proximity: at least one module-level doc exists alongside code (not only root-level docs)" \
+ "$(find "$REPO" -not -path '*/.git/*' \( -name 'ARCHITECTURE.md' -o -name 'CONSTRAINTS.md' \) 2>/dev/null | grep -qv "^${REPO%/}/ARCHITECTURE.md\|^${REPO%/}/CONSTRAINTS.md" && echo "pass" || echo "fail")" \
+ "Create ARCHITECTURE.md or CONSTRAINTS.md inside a code directory (e.g. src/ARCHITECTURE.md) to document that module's design decisions."
+
+# ── L07: WIP=1 and VCR Enforcement ───────────────────────────────────────────
+header "L07: WIP=1 and VCR Enforcement"
+
+ipath_l07="$(instructions_path 2>/dev/null || echo "AGENTS.md")"
+
+check_recommended "WIP=1 rule present in instructions (one active feature at a time) [L07]" \
+ "$(contains_pattern "$ipath_l07" "(WIP.?1|one.*active|active.*at.*time|single.*active|only.*one.*active|activate.*new.*feature|new.*feature.*while.*active)")" \
+ "Add a WIP=1 rule to $ipath_l07: 'Only one feature may have state=active at a time. Complete and move to passing before activating the next.'"
+
+check_recommended "make vcr target exists in Makefile [L07]" \
+ "$(makefile_has_target "vcr")" \
+ "Add a 'vcr:' target to Makefile that prints the VCR ratio: passing features / activated features (e.g. uses jq on feature_list.json)."
+
+# Runtime VCR check — compute from feature_list.json
+if [[ "$(any_file_match "feature_list.json" "features.json")" == "pass" ]]; then
+ _vcr_file=""
+ for _f in "$REPO/feature_list.json" "$REPO/features.json"; do
+ [[ -f "$_f" ]] && { _vcr_file="$_f"; break; }
+ done
+ if [[ -n "$_vcr_file" ]]; then
+ _vcr_active=0; _vcr_passing=0
+ if grep -q '"state":[[:space:]]*"active"' "$_vcr_file" 2>/dev/null; then
+ _vcr_active=$(grep -c '"state":[[:space:]]*"active"' "$_vcr_file")
+ fi
+ if grep -q '"state":[[:space:]]*"passing"' "$_vcr_file" 2>/dev/null; then
+ _vcr_passing=$(grep -c '"state":[[:space:]]*"passing"' "$_vcr_file")
+ fi
+ _vcr_activated=$(( _vcr_active + _vcr_passing ))
+ if [[ "$_vcr_activated" -eq 0 ]]; then
+ check_recommended "VCR: no activated features yet (OK to activate first feature) [L07]" "pass"
+ elif [[ "$_vcr_active" -gt 0 ]]; then
+ check_recommended "VCR = $_vcr_passing/$_vcr_activated — $_vcr_active active feature(s) not yet passing (VCR < 1.0) [L07]" "fail"
+ else
+ check_recommended "VCR = $_vcr_passing/$_vcr_activated = 1.0 — all activated features are passing [L07]" "pass"
+ fi
+ fi
+fi
+
+# ── L08: Feature List as Harness Primitive ────────────────────────────────────
+header "L08: Feature List as Harness Primitive"
+
+ipath_l08="$(instructions_path 2>/dev/null || echo "AGENTS.md")"
+
+# Helper: find first present feature list file
+_fl_path() {
+ for _f in "$REPO/feature_list.json" "$REPO/features.json"; do
+ [[ -f "$_f" ]] && { echo "$_f"; return; }
+ done
+ echo ""
+}
+
+_fl="$(_fl_path)"
+
+check_recommended "feature_list.json entries have an 'evidence' field [L08]" \
+ "$( [[ -n "$_fl" ]] && grep -q '"evidence"' "$_fl" 2>/dev/null && echo "pass" || echo "fail" )" \
+ "Add an 'evidence' field to every entry in feature_list.json. Example: \"evidence\": \"commit abc1234, verified 2026-06-07\"."
+
+check_recommended "verify-feature script present (scripts/verify-feature.sh) [L08]" \
+ "$(any_file_match "scripts/verify-feature.sh")" \
+ "Create scripts/verify-feature.sh — the harness gate that runs a feature's verification command and transitions state to passing. Get the template from: https://github.com/Stephen-Kimoi/harness-engineering-template/blob/main/scripts/verify-feature.sh"
+
+check_recommended "make verify-feature target exists in Makefile [L08]" \
+ "$(makefile_has_target "verify-feature")" \
+ "Add a 'verify-feature:' target to Makefile: 'bash scripts/verify-feature.sh \$(F)'. Usage: make verify-feature F=F02"
+
+check_recommended "Feature List Rules documented in instructions (pass-state gating) [L08]" \
+ "$(contains_pattern "$ipath_l08" "(verify.feature|verification script|don.t.*state|state.*automatically|harness.*updat|pass.state|never.*set.*state.*passing|never.*edit.*state)")" \
+ "Add a Feature List Rules section to $ipath_l08 stating: 'Never set state to passing directly — run make verify-feature F=<id>.'"
+
+check_recommended "Feature granularity rule documented (one session per feature) [L08]" \
+ "$(contains_pattern "$ipath_l08" "(one session|completable.*session|session.*complet|one feature.*session|single session)")" \
+ "Add a granularity rule to $ipath_l08: 'Each feature must be completable in one session. If it spans sessions, split it.'"
+
+check_recommended "State machine documented (not_started → active → passing) [L08]" \
+ "$(contains_pattern "$ipath_l08" "(not_started|state machine|no skipping|active.*passing)")" \
+ "Document the state machine in $ipath_l08: not_started → active → passing. Note that skipping states is not allowed."
+
+# ── L09: Preventing Premature Completion Declarations ─────────────────────────
+header "L09: Premature Completion Prevention"
+
+ipath_l09="$(instructions_path 2>/dev/null || echo "AGENTS.md")"
+
+check_recommended "Definition of Done section present in instructions [L09]" \
+ "$(contains_pattern "$ipath_l09" "(definition of done|feature complete|runtime evidence|code is written|all layers pass)")" \
+ "Add a 'Definition of Done' section to $ipath_l09 stating: 'A task is complete when runtime evidence passes — not when code is written or the agent is confident.'"
+
+check_recommended "Three-layer verification model documented [L09]" \
+ "$(contains_pattern "$ipath_l09" "(layer 1|layer 2|layer 3|syntax.*static|runtime.*behav|system.*confirm|end.to.end.*verif)")" \
+ "Document the three-layer model in $ipath_l09: Layer 1 (syntax/static), Layer 2 (runtime behavior), Layer 3 (system confirmation / e2e)."
+
+check_recommended "Layer ordering rule documented (do not skip layers) [L09]" \
+ "$(contains_pattern "$ipath_l09" "(do not proceed|don.t proceed|layer.*fail|skip.*layer|must pass in order|in order)")" \
+ "Add the ordering rule to $ipath_l09: 'Do not proceed to Layer N+1 if Layer N fails.'"
+
+check_recommended "Runtime signals documented (app startup, side effects) [L09]" \
+ "$(contains_pattern "$ipath_l09" "(ready state|app.*start|startup|side effect|database write|file operation|cleanup|debug artifact)")" \
+ "Add runtime signals to $ipath_l09: app reaches ready state, side effects are correct, no debug artifacts remain."
+
+# Check for layers field with repair instructions in feature_list.json
+_fl_l09="$(_fl_path)"
+_has_layers_repair="fail"
+if [[ -n "$_fl_l09" ]] && grep -q '"layers"' "$_fl_l09" 2>/dev/null && grep -q '"repair"' "$_fl_l09" 2>/dev/null; then
+ _has_layers_repair="pass"
+fi
+check_recommended "feature_list.json uses layers with repair instructions [L09]" \
+ "$_has_layers_repair" \
+ "Add a 'layers' array to feature_list.json entries. Each layer needs: label, cmd, repair. The repair field gives the agent actionable fix instructions on failure."
+
+check_recommended "verify-feature.sh handles multi-layer validation with repair output [L09]" \
+ "$(grep -q 'repair\|run_layer\|How to fix' "$REPO/scripts/verify-feature.sh" 2>/dev/null && echo "pass" || echo "fail")" \
+ "Update scripts/verify-feature.sh to run layers in sequence and print the repair instruction when a layer fails. Get the updated template from the harness-engineering-template repo."
+
+# ── L10: End-to-End Testing and Architectural Boundaries ─────────────────────
+header "L10: E2E Testing and Architectural Boundaries"
+
+ipath_l10="$(instructions_path 2>/dev/null || echo "AGENTS.md")"
+
+check_recommended "make e2e target exists in Makefile [L10]" \
+ "$(makefile_has_target "e2e")" \
+ "Add an 'e2e:' target to Makefile running your end-to-end suite (e.g. 'npx playwright test', 'pytest tests/e2e/', 'mix test --only e2e'). Required when changes cross component boundaries."
+
+check_recommended "make check-arch target exists in Makefile [L10]" \
+ "$(makefile_has_target "check-arch")" \
+ "Add a 'check-arch:' target to Makefile: 'bash scripts/check-arch.sh'. This runs architectural constraint rules and outputs WHAT/WHY/FIX on violations."
+
+check_recommended "scripts/check-arch.sh present [L10]" \
+ "$(any_file_match "scripts/check-arch.sh")" \
+ "Create scripts/check-arch.sh — the architectural constraint runner. Get the template from: https://github.com/Stephen-Kimoi/harness-engineering-template/blob/main/scripts/check-arch.sh"
+
+check_recommended ".harness/arch-rules.json present (architectural rule registry) [L10]" \
+ "$(any_file_match ".harness/arch-rules.json")" \
+ "Create .harness/arch-rules.json with at least one rule. Each rule needs: id, description, check, expect, what, why, fix. Promote every code-review finding into a rule here."
+
+check_recommended "Arch rules use WHAT/WHY/FIX error format [L10]" \
+ "$( [[ -f "$REPO/.harness/arch-rules.json" ]] && grep -q '"what"' "$REPO/.harness/arch-rules.json" && grep -q '"why"' "$REPO/.harness/arch-rules.json" && grep -q '"fix"' "$REPO/.harness/arch-rules.json" && echo "pass" || echo "fail" )" \
+ "Ensure each rule in .harness/arch-rules.json has 'what', 'why', and 'fix' fields with agent-actionable text (name the specific file, function, or env var to change)."
+
+check_recommended "Architecture Boundaries section present in instructions [L10]" \
+ "$(contains_pattern "$ipath_l10" "(architecture.*boundar|arch.*boundar|layer.*depend|enforce.*invariant|check-arch|arch.rules)")" \
+ "Add an Architecture Boundaries section to $ipath_l10 describing your layer model and stating that 'make check-arch' enforces the constraints."
+
+check_recommended "E2E requirement for cross-component changes documented [L10]" \
+ "$(contains_pattern "$ipath_l10" "(cross.component|cross.domain|layer 3.*required|e2e.*required|end.to.end.*required|required.*cross)")" \
+ "Add a rule to $ipath_l10: 'Layer 3 (e2e) is required when changes cross component or domain boundaries.'"
+
+check_recommended "Review-to-automation promotion principle documented [L10]" \
+ "$(contains_pattern "$ipath_l10" "(code review.*automat|review.*promot|promot.*check|new.*error.*rule|catch.*review.*rule|arch.rules)")" \
+ "Add the promotion principle to $ipath_l10: 'Every new error category caught in code review becomes a rule in .harness/arch-rules.json.'"
+
+# ── L11: Observability Inside the Harness ─────────────────────────────────────
+header "L11: Observability"
+
+ipath_l11="$(instructions_path 2>/dev/null || echo "AGENTS.md")"
+
+check_recommended "templates/sprint-contract.md present [L11]" \
+ "$(file_exists "templates/sprint-contract.md")" \
+ "Create templates/sprint-contract.md — the pre-feature negotiation template defining scope, DoD, and exclusions. Get it from: https://github.com/Stephen-Kimoi/harness-engineering-template/blob/main/templates/sprint-contract.md"
+
+check_recommended "templates/evaluator-rubric.md present [L11]" \
+ "$(file_exists "templates/evaluator-rubric.md")" \
+ "Create templates/evaluator-rubric.md — the scoring rubric with A/B/C/D thresholds per dimension (correctness, arch compliance, test coverage, verification evidence)."
+
+check_recommended "scripts/session-trace.sh present (runtime signal collector) [L11]" \
+ "$(any_file_match "scripts/session-trace.sh")" \
+ "Create scripts/session-trace.sh to record structured JSONL events per session. Get the template from: https://github.com/Stephen-Kimoi/harness-engineering-template/blob/main/scripts/session-trace.sh"
+
+check_recommended ".harness/traces/ directory present [L11]" \
+ "$(dir_exists ".harness/traces")" \
+ "Create .harness/traces/ directory (add a .gitkeep so it's tracked). Add .harness/traces/traces.jsonl to .gitignore — it's a runtime artifact, not source."
+
+check_recommended "Observability / sprint contract protocol documented in instructions [L11]" \
+ "$(contains_pattern "$ipath_l11" "(sprint contract|observabilit|session.trace|session-trace|runtime signal|signal collect)")" \
+ "Add an Observability section to $ipath_l11: sprint contract before each feature, session-trace events during verification, evaluator rubric scoring after completion."
+
+check_recommended "Evaluator rubric referenced in instructions [L11]" \
+ "$(contains_pattern "$ipath_l11" "(rubric|evaluator.*score|scoring.*dimension|dimension.*score|A or B|passing.*threshold)")" \
+ "Reference the evaluator rubric in $ipath_l11: 'Score each completed sprint against templates/evaluator-rubric.md — every dimension must reach B or above.'"
+
+check_recommended "make session-start and session-end targets present [L11]" \
+ "$(makefile_has_target "session-start")" \
+ "Add session-start and session-end targets to Makefile wrapping scripts/session-trace.sh."
+
+# ── L12: Clean State Protocol ─────────────────────────────────────────────────
+header "L12: Clean State Protocol"
+
+ipath_l12="$(instructions_path 2>/dev/null || echo "AGENTS.md")"
+
+check_recommended "templates/clean-state-checklist.md present [L12]" \
+ "$(file_exists "templates/clean-state-checklist.md")" \
+ "Create templates/clean-state-checklist.md with the 5 dimensions: build passes, tests pass, feature list updated, no debug artifacts, startup path works. A session is not complete until all five pass."
+
+check_recommended "scripts/clean-state-check.sh present (idempotent verifier) [L12]" \
+ "$(any_file_match "scripts/clean-state-check.sh")" \
+ "Create scripts/clean-state-check.sh — an idempotent script that checks the 5 clean-state dimensions and exits 0 only when all pass. Safe to run repeatedly."
+
+check_recommended "make clean-check target present [L12]" \
+ "$(makefile_has_target "clean-check")" \
+ "Add a 'clean-check:' target to Makefile: 'bash scripts/clean-state-check.sh .' Agents run this at clock-out before committing."
+
+check_recommended "Session exit checklist / clean-state referenced in instructions [L12]" \
+ "$(contains_pattern "$ipath_l12" "(clean.state|clean-state|clean_state|session exit|exit checklist|debug artifact|no.*debug|remove.*debug)")" \
+ "Add a clean-state reference to the Clock-Out section in $ipath_l12: 'Run make clean-check before committing — confirms build, no debug artifacts, PROGRESS.md updated.'"
+
+check_recommended "Quality document present (module health scores) [L12]" \
+ "$( [[ -f "$REPO/docs/quality-document.md" ]] || [[ -f "$REPO/templates/quality-document.md" ]] && echo "pass" || echo "fail" )" \
+ "Create docs/quality-document.md (or use templates/quality-document.md) scoring each module A/B/C/D across 5 dimensions. New sessions read this to know where to prioritize."
+
+check_recommended "Quality document referenced in instructions [L12]" \
+ "$(contains_pattern "$ipath_l12" "(quality.doc|quality doc|quality-doc|quality score|module.*grade|module.*quality|A.*B.*C.*D|grade.*module)")" \
+ "Reference the quality document in $ipath_l12 Clock-Out: 'Update docs/quality-document.md for the module you touched (A/B/C/D per dimension).'"
+
+check_recommended "Dual-mode cleanup documented (immediate + periodic/weekly) [L12]" \
+ "$(contains_pattern "$ipath_l12" "(periodic|weekly|monthly|dual.mode|immediate.*cleanup|cleanup.*periodic|regular.*sweep|periodic.*sweep)")" \
+ "Document the dual-mode cleanup strategy in $ipath_l12: immediate cleanup at every session end + periodic (weekly/monthly) full-system sweep for structural drift."
+
+# ── Summary ────────────────────────────────────────────────────────────────────
+TOTAL_PASS=$((CRITICAL_PASS + RECOMMENDED_PASS))
+TOTAL=$((CRITICAL_PASS + CRITICAL_FAIL + RECOMMENDED_PASS + RECOMMENDED_FAIL))
+
+echo ""
+echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+echo -e "${BOLD}Summary${RESET}"
+echo -e " Total: ${TOTAL_PASS} / ${TOTAL} harness components present"
+echo -e " Critical: ${CRITICAL_PASS} / $((CRITICAL_PASS + CRITICAL_FAIL)) (must-have for basic function)"
+echo -e " Recommended: ${RECOMMENDED_PASS} / $((RECOMMENDED_PASS + RECOMMENDED_FAIL)) (best practice)"
+echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+
+if [[ ${#RECS[@]} -gt 0 ]]; then
+ echo ""
+ echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+ echo -e "${BOLD}What to fix${RESET}"
+ echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+ for rec in "${RECS[@]}"; do
+ echo -e " • ${rec}"
+ done
+ echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+fi
+
+if [[ $CRITICAL_FAIL -gt 0 ]]; then
+ echo -e "\n${RED}${BOLD}CRITICAL items are missing. Address these before running long agent sessions.${RESET}"
+ exit 1
+else
+ echo -e "\n${GREEN}${BOLD}All CRITICAL harness components are present.${RESET}"
+ if [[ $RECOMMENDED_FAIL -gt 0 ]]; then
+ echo -e "${YELLOW}Some RECOMMENDED items are missing. See above for specific fixes.${RESET}"
+ fi
+ exit 0
+fi