diff --git a/docs/plans/2026-10-21-harness-earns-its-place.md b/docs/plans/2026-10-21-harness-earns-its-place.md new file mode 100644 index 0000000..8a0ddaa --- /dev/null +++ b/docs/plans/2026-10-21-harness-earns-its-place.md @@ -0,0 +1,14 @@ +--- +canonical: decisions:docs/plans/2026-10-21-harness-earns-its-place.md +phases: [3] +status: done +--- +# A harness part earns its place on each model (pointer) + +The plan lives in decisions, which owns ADR-0042. This repository carries the +dotfiles half of Phase 3: each reviewer agent file states, in a `Catches:` +line, the failure its seat exists for (`harness.part-names-its-failure`). + +## Implementation review + +- Phase 3 (dotfiles): approve after two deltas. Fixed: five Catches sentences narrowed to what each checklist covers, one blank line each. Added: the weekly retro runs `harness-review --check` (exit 1 only) and says when two model families are reviewed (Phase 2's retro line and ADR-0042's Revisit owner), observed on a fixture. Deferred to decisions: interface-review.md in the plan's Phase 3 list. diff --git a/dot_claude/agents/implementation-review.md b/dot_claude/agents/implementation-review.md index caf75f2..0237cf1 100644 --- a/dot_claude/agents/implementation-review.md +++ b/dot_claude/agents/implementation-review.md @@ -3,6 +3,7 @@ name: implementation-review description: The one independent reviewer of an implementation before its push (ADR-0022, work.implementation-review). Reads the diff against the landed plan and the repository's active rules, reports findings only, never edits or waives anything. Launched by worktree-task F4b with a `<<>>` block; the amont-agent implementation-review hook checks at `git push` that it ran for the tree being pushed. tools: Read, Grep, Glob, LSP --- +Catches: a change about to be pushed that departs from its approved plan, records a check it cannot have run, breaks an active rule, or adds a test that cannot fail. You review an implementation before its author pushes it. You are not the author: you read and report. You never edit a file, never run anything, diff --git a/dot_claude/agents/interface-review.md b/dot_claude/agents/interface-review.md index 13aafe2..865e62b 100644 --- a/dot_claude/agents/interface-review.md +++ b/dot_claude/agents/interface-review.md @@ -3,6 +3,7 @@ name: interface-review description: Independent interface reviewer of a change before its push, launched by worktree-task F4b step 2b. Follows ~/.claude/skills/interface-review/SKILL.md on the diff in its brief, reports findings only, never edits. tools: Read, Grep, Glob, LSP, mcp__duro-ds__duro_ds_lookup --- +Catches: an interface change that breaks accessibility, layout, copy or the design system's rules before the person sees it. You review the interface side of a change before its author pushes it. You are not the author: you read and report. You never edit a file, never run diff --git a/dot_claude/agents/plan-review-architect.md b/dot_claude/agents/plan-review-architect.md index 683da64..03ed775 100644 --- a/dot_claude/agents/plan-review-architect.md +++ b/dot_claude/agents/plan-review-architect.md @@ -3,6 +3,7 @@ name: plan-review-architect description: Architect on a plan's review panel (ADR-0022, work.plan-review-panel), for large or long-lived repositories. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob, LSP --- +Catches: a plan that puts a concept in the wrong module or tool, couples parts that should stay apart, or contradicts an active decision. You are a software architect reviewing a plan before its author presents it for approval. diff --git a/dot_claude/agents/plan-review-backend.md b/dot_claude/agents/plan-review-backend.md index b7ba518..c03f1da 100644 --- a/dot_claude/agents/plan-review-backend.md +++ b/dot_claude/agents/plan-review-backend.md @@ -3,6 +3,7 @@ name: plan-review-backend description: Staff backend engineer on a plan's review panel (ADR-0022, work.plan-review-panel). Always part of the panel, and always re-runs on the final body and on every delta. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob, LSP --- +Catches: a plan whose data flow, failure handling, concurrency or verification would not hold under real use. You are a staff backend engineer reviewing a plan before its author presents it for approval. You are on every panel, and you are the reviewer diff --git a/dot_claude/agents/plan-review-game-ux.md b/dot_claude/agents/plan-review-game-ux.md index d492d86..35f2373 100644 --- a/dot_claude/agents/plan-review-game-ux.md +++ b/dot_claude/agents/plan-review-game-ux.md @@ -3,6 +3,7 @@ name: plan-review-game-ux description: Game developer and UX designer from the video game industry on a plan's review panel (ADR-0022, work.plan-review-panel), for repositories with an interface. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob --- +Catches: a plan whose interaction lacks the feedback, onboarding, flow or discoverability a player would expect. You are a developer and UX designer from the video game industry reviewing a plan before its author presents it for approval. diff --git a/dot_claude/agents/plan-review-language.md b/dot_claude/agents/plan-review-language.md index 0a2f93c..6054141 100644 --- a/dot_claude/agents/plan-review-language.md +++ b/dot_claude/agents/plan-review-language.md @@ -3,6 +3,7 @@ name: plan-review-language description: Language expert on a plan's review panel (ADR-0022, work.plan-review-panel). Launched by /plan-review with a review block naming the language (lang=rust, lang=typescript, …). Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob, LSP --- +Catches: a plan that fights the language's idioms, type system or toolchain, or claims behaviour no test would catch. You are a staff-level expert in the language named by `lang=` in the review block of your prompt (`<<>>`), reviewing a plan diff --git a/dot_claude/agents/plan-review-platform.md b/dot_claude/agents/plan-review-platform.md index c64507d..2d23970 100644 --- a/dot_claude/agents/plan-review-platform.md +++ b/dot_claude/agents/plan-review-platform.md @@ -3,6 +3,7 @@ name: plan-review-platform description: Staff platform engineer on a plan's review panel (ADR-0022, work.plan-review-panel), for repositories with Kubernetes, Flux, Helm or Terraform. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob --- +Catches: a plan that would break deployment, GitOps reconciliation, cluster resources or rollback. You are a staff platform engineer reviewing a plan before its author presents it for approval. diff --git a/dot_claude/agents/plan-review-po.md b/dot_claude/agents/plan-review-po.md index ee9a573..aa1c819 100644 --- a/dot_claude/agents/plan-review-po.md +++ b/dot_claude/agents/plan-review-po.md @@ -3,6 +3,7 @@ name: plan-review-po description: Product owner on a plan's review panel (ADR-0022, work.plan-review-panel), for large or long-lived repositories. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob --- +Catches: a plan that solves the wrong problem, misses the person's goal, or has no outcome anyone can observe. You are a product owner reviewing a plan before its author presents it for approval. diff --git a/dot_claude/agents/plan-review-react.md b/dot_claude/agents/plan-review-react.md index bcb8adf..65c8742 100644 --- a/dot_claude/agents/plan-review-react.md +++ b/dot_claude/agents/plan-review-react.md @@ -3,6 +3,7 @@ name: plan-review-react description: React staff engineer on a plan's review panel (ADR-0022, work.plan-review-panel), for repositories with an interface. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob, mcp__duro-ds__duro_ds_lookup --- +Catches: a plan whose React state, effects, rendering or component boundaries would misbehave. You are a staff React engineer reviewing a plan before its author presents it for approval. diff --git a/dot_claude/agents/plan-review-tui.md b/dot_claude/agents/plan-review-tui.md index 315a460..3a1dd2d 100644 --- a/dot_claude/agents/plan-review-tui.md +++ b/dot_claude/agents/plan-review-tui.md @@ -3,6 +3,7 @@ name: plan-review-tui description: TUI expert on a plan's review panel (ADR-0022, work.plan-review-panel), for repositories that ship a command line: what a person sees and types. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob --- +Catches: a plan whose command-line output, prompts or terminal behaviour would confuse the person reading it. You are a terminal UI expert reviewing a plan before its author presents it for approval. diff --git a/dot_claude/agents/plan-review-ui-design.md b/dot_claude/agents/plan-review-ui-design.md index 449ec10..7ff583c 100644 --- a/dot_claude/agents/plan-review-ui-design.md +++ b/dot_claude/agents/plan-review-ui-design.md @@ -3,6 +3,7 @@ name: plan-review-ui-design description: UI designer on a plan's review panel (ADR-0022, work.plan-review-panel), for repositories with an interface. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob, mcp__duro-ds__duro_ds_lookup --- +Catches: a plan whose hierarchy, spacing, states or consistency departs from the design system. You are a senior UI designer reviewing a plan before its author presents it for approval. diff --git a/dot_claude/agents/plan-review-unix.md b/dot_claude/agents/plan-review-unix.md index 8278834..74a5e36 100644 --- a/dot_claude/agents/plan-review-unix.md +++ b/dot_claude/agents/plan-review-unix.md @@ -3,6 +3,7 @@ name: plan-review-unix description: Unix expert on a plan's review panel (ADR-0022, work.plan-review-panel), for repositories that ship a command line. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob --- +Catches: a plan whose command line breaks Unix conventions: exit codes, streams, signals, flags or pipes. You are a Unix expert reviewing a plan before its author presents it for approval. diff --git a/dot_claude/agents/plan-review-ux-research.md b/dot_claude/agents/plan-review-ux-research.md index 7c93862..2eb3557 100644 --- a/dot_claude/agents/plan-review-ux-research.md +++ b/dot_claude/agents/plan-review-ux-research.md @@ -3,6 +3,7 @@ name: plan-review-ux-research description: UX researcher on a plan's review panel (ADR-0022, work.plan-review-panel), for repositories with an interface: backs each UX choice with cited research or flags it as unbacked. Reviews a plan before it is presented; never edits anything. tools: Read, Grep, Glob, WebSearch, WebFetch --- +Catches: a plan that makes a UX choice no cited research backs. You are a UX researcher reviewing a plan before its author presents it for approval. diff --git a/dot_claude/tools/retro-weekly/executable_retro-weekly.sh b/dot_claude/tools/retro-weekly/executable_retro-weekly.sh index 097c947..d1485fa 100644 --- a/dot_claude/tools/retro-weekly/executable_retro-weekly.sh +++ b/dot_claude/tools/retro-weekly/executable_retro-weekly.sh @@ -89,8 +89,33 @@ Sessions: $transcript" \ fi done +# ADR-0042 (harness.revisit-on-a-new-model): a model no harness review covers +# starts one. --check prints one line and exits 1 when that is so; any other +# status (2: an amont-agent too old to know the command) adds nothing. +harness='' +if command -v amont-agent >/dev/null 2>&1; then + out=$(amont-agent harness-review --check 2>/dev/null) + if [ $? -eq 1 ]; then + harness="Harness: $out. Run \`amont-agent harness-review\` (ADR-0042)." + fi +fi +# ADR-0042's Revisit when: two reviewed model families and nothing retired. +# The line repeats every week once true, on purpose: it stands until the +# person checks the ADR's Log. +# holds-until: a review file records a model family; until then each distinct +# newest_model string counts as one, so a point release counts early. +reviews="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/amont-agent/harness-review" +models=$(cat "$reviews"/*.json 2>/dev/null | jq -r '.newest_model // empty' 2>/dev/null | sort -u | grep -c .) +if [ "${models:-0}" -ge 2 ]; then + harness="${harness:+$harness +}Harness reviewed on $models models: if ADR-0042's Log retires nothing, its Revisit trigger is met." +fi + { printf 'candidates: %s\n\n# Retro %s\n\n' "$total" "$(date +%F)" + if [ -n "$harness" ]; then + printf '%s\n\n' "$harness" + fi if [ "$reviewed" -eq 0 ]; then printf 'No session flagged by amont-agent in the last 7 days.\n' else