chore: adopt the agent-harness copier template v0.7.0-3-g0fa3c56

[egparedes]

Feature

Harness maintenance — no development/work/ unit. Supersedes and closes #3,
which took the repo to template v0.6.0; this branch carries those five commits
forward and lands on template v0.7.0-3-g0fa3c56 — the v0.7.0 release
plus the three post-release fixes this adoption prompted upstream.

docs/ and work/ move into development/, leaving docs/ for user
documentation (docs/api.md) as the new convention reserves it, and the harness
tracks template v0.7.0-3-g0fa3c56.

Why one branch instead of merging #3 first

The three upstream releases arrived while #3 was open, and two of them rewrote
the same files #3 touched. Stacking the reconciliation on top of #3 keeps a
single reviewable end state instead of a merge-then-immediately-rewrite pair.
#3's own CI stayed green throughout; nothing in it is discarded except patches
upstream has since superseded (below).

The migration is a separate first commit, deliberately

A bare copier update exits 0, reports no conflict, and deletes
docs/architecture.md, docs/style.md, docs/testing.md and
docs/tool-bootstrap.md, substituting template scaffolds at the new path —
_skip_if_exists does not cover the delete side of a rename. Moving the tree
first (ae0c46d) puts those files where _skip_if_exists can see them.
Verified both ways on throwaway clones before touching a real branch, and
re-verified after each of the three template bumps.

Line counts against 1beb326: architecture.md 78 → 78, style.md 133 → 133,
tool-bootstrap.md 122 → 126, testing.md 107 → 121 (grafted sections).

Absorbed from v0.6.0 → v0.7.0

• report.md as a fifth work-unit artifact; decision register in
  development/adr/README.md, seeded with the two decisions this repo had
  already granted; development/glossary.md; document-liveness and authority
  rules.
• Simplification wave: eleven copier answers dropped (license, mode,
  project_slug, pr_merge_strategy, the include_example_* gates, cursor,
  mcp, …), generate_scripts derived from verify_command, 13 questions
  left. The four role playbook skills fold into their subagent files, leaving
  design-principles as the only skill. The verify skill is gone — capability
  not replaced, accepted deliberately.
• One hand-back convention: HANDBACK(<spike|explore|replan>): with flat
  per-kind caps each role restates in its own reply, so the bound survives
  description-match invocation.
• Hook payload reader (v0.7.0): all three Claude hooks read input via
  .agents/hooks/hook-input.sh (jq, then python3) and branch on its exit
  code.

Eight defects this repo reported upstream, all fixed there

Found while adopting the template; filed rather than patched locally, so the
fixes ship for every downstream repo. The last four were found reviewing this
branch, and their fixes are what this PR now pins to.

Upstream	Was
#25	plan.md's Review checklist had unbounded authority over the reviewer's verdict rules
#26	Hand-back loops unserviced and uncapped outside the slash commands
#27	Loop round caps lived only in the slash commands, which the subagents state may never have been read
#31	jq an undocumented hard requirement: Bash guard denied everything, Stop loop-guard defeated, format-on-edit silently off
#33	_skip_if_exists matched a bare README.md at every depth, freezing the template's own nested READMEs downstream
#34	The reader's two backends disagreed on objects, arrays and numbers, contradicting its documented parity contract
#35	The reader committed to jq on command -v alone, so a broken jq failed the read; the Stop hook skipped the gate on any reader failure
#36	The deny-list matched inside quoted arguments, blocking read-only commands that merely mention a pattern

The local patches for these are retired in favour of upstream's, which are
better in three specific ways this repo got wrong:

• Fail-open hook skips must exit 1, not 0 — Claude Code surfaces only
  non-zero stderr, so the local warnings would never have been seen.
• The local block-destructive.sh used grep -o to name the matched pattern.
  -o is non-POSIX and GNU grep suppresses its stdout on binary-classified
  input, so it could match and report nothing — failing open on exactly the
  input a deny-list matters for. Upstream keeps the decision on POSIX
  grep -qE and names the whole deny-list instead.
• hook-input.sh probes python3 by running it: stock macOS ships a CLT stub
  that passes command -v but fails at runtime.

.claude/settings.json, .opencode/opencode.jsonc and all three
.agents/hooks/* scripts are byte-identical to a pristine render of the pinned
template commit — verified file by file, not assumed.

Absorbed from v0.7.0 → v0.7.0-3-g0fa3c56

• _skip_if_exists is root-anchored. Under gitignore semantics a bare
  README.md matched at every depth, so .agents/README.md,
  .claude/rules/README.md and development/README.md were silently frozen
  downstream with no conflict reported in either direction. .agents/README.md
  here was 63 lines stale because of it.
• The deny-list matches operations outside quotes, so grep -rn 'rm -rf' .
  passes while cd x && rm -rf y is denied, with a fallback for the string a
  nested shell runs (sh -c, ssh, eval, su, or a pipe into a shell). The
  SQL pattern still matches anywhere: it has no unquoted form, so its mention
  and its use are indistinguishable.
• The payload reader probes each backend by running it, so a jq that
  resolves but is broken falls through to python3; and the Stop gate
  reports instead of skipping — a gate that cannot be blocked still runs and
  says so, rather than ending the session unverified.

.agents/README.md takes the template's version wholesale: upstream's rewrite
generalises the local caveat this branch carried (hooks are template-owned) to
all of .agents/, and adds the safe-to-edit list.
development/harness-usage.md and development/tool-bootstrap.md are
_skip_if_exists, so the new behaviour is ported by hand. The Stop-hook
paragraph is rewritten rather than replaced — upstream covers the reader path
but not the uv-unavailable path, which still skips the gate on exit 1.

Deliberate divergence (six items)

All in territory ADR 0012
states was left untouched: the decision-register row owner (no role could write
it), the marker-less-row exemption (both seeded rows are that kind), the
no-work-unit review axes (a harness PR like this one had no defined behaviour),
the location-scoped DECISION-PENDING: definition, gate-output pointers to
development/testing.md (which records the sanctioned DEVMM_GPU skips), and
the architect's Write-to-create exception for scratch.md.

Plus AGENTS.md's BSD-3-Clause line and squash-merge guidance — both lost to
deleted questions — and devmm's stricter rule that a required runtime
dependency needs an ADR, since the empty required-dependency set is an invariant
tests/test_packaging.py enforces.

Definition of done

• Gate green: make verify, exit 0 — 900 passed, 75 skipped
• Every success criterion evidenced — checks below
• report.md written — n/a, no work unit; deviations declared here
• No test, tolerance or assertion weakened. The 75 skips are the CUDA and
  ROCm suites off hardware (ADR 0003), unchanged from 1beb326; the
  tests/ diff is prose-only path references
• Every DECISION-PENDING: line has a register row — none added; the
  register is seeded with two pre-existing accepted decisions
• New structural decisions have an ADR — none; this adopts an upstream
  layout rather than deciding one

Also verified: every relative Markdown link in every tracked .md resolves;
.claude/.opencode symlinks intact; docs/api.md doctests green; the hook
wiring exercised across all parser scenarios (jq, python3-only, broken jq,
neither) for allow, deny and the Stop loop guard; AGENTS.md at 127 lines.

Every claim this branch adds to harness-usage.md and tool-bootstrap.md was
checked against the scripts themselves rather than read off the upstream diff:
13 deny-list cases (quoted mention, bare operation, nested-shell runner, pipe
into a shell, \rm alias bypass, the push-ends-in-sh non-match) and the
reader's exit codes for broken jq (falls through), python3-only, no working
parser (3) and an empty payload (4).

Deviations & notes for the reviewer

• .copier-answers.yml loses ten answers. Expected — those questions no
  longer exist upstream.
• The verify skill is gone. Gate failures now have no triage helper;
  make verify runs the gate and nothing summarises the failure.
• development/tool-bootstrap.md and development/harness-usage.md are
  _skip_if_exists, so upstream changes to them never arrive on update. Both
  ported by hand, twice now.
• development/README.md is template-owned and not _skip_if_exists. It
  carries local content here (the sdist/wheel note). Upstream did not change it
  in this bump, so nothing was lost; a future bump that does will surface as a
  merge conflict rather than a silent overwrite.
• Two problems surfaced only in verification and are fixed here: 65 links broke
  because work units gained a directory level (../ → ../../), and the
  .gitignore managed block briefly held a duplicate entry once post_gen.py
  became incremental.

🤖 Generated with Claude Code

[egparedes]

Review: approving — ready to merge, no blocking findings

Verdict: ready to merge. Three MINOR findings below, all documentation/contract accuracy; none blocks the merge. (Posted as COMMENT because GitHub does not accept APPROVE on your own PR.)

Scope reviewed: 4a2dab3f against origin/main — 6 commits, 89 files, +1230/-492. I re-derived the claims in the description rather than taking them on trust.

Verified independently

• Gate green. Exported the head tree and ran make verify: exit 0, format/lint/mypy --strict clean, 900 passed, 75 skipped in 9.65s. The 75 are exactly the DEVMM_GPU suites (36 CUDA + 6 integrations + 33 ROCm), unchanged from 1beb326 and sanctioned by ADR 0003. Nothing weakened — the tests/ diff is prose-only path references, with no marker, tolerance or assertion touched.
• Links. Every relative Markdown link in every tracked .md at the head commit resolves: 0 broken, checked tree-wide.
• No stale paths. No surviving reference to docs/{architecture,style,testing,tool-bootstrap,harness-usage,adr} or to a top-level work/<unit>; the three deleted .agents/*/README.md files have no remaining referrers; removing the verify skill leaves no dangling mention.
• Hook wiring, exercised rather than reasoned about. Ran hook-input.sh under jq 1.6 and again under a PATH containing only python3, across: string, boolean true, boolean false, absent key, explicit null, path through a non-object, top-level array, unparseable payload, empty payload. Value and exit code agree on every scalar case, and both failure cases exit 4 under both backends. The wiring posture is right: the PreToolUse Bash guard denies on every non-zero reader exit (fails closed), while PostToolUse-fmt and Stop exit 1 (fail open, stderr surfaced). The old failure mode is not hypothetical — a command issued during this review that merely quoted a deny-listed pattern was refused with literally No stderr output, which is exactly what the new message fixes.
• sdist claim. development/README.md asserts the tree travels in the sdist; I built one — 53 development/ entries in devmm-0.1.0.tar.gz, wheel unaffected (packages = ["src/devmm"]).
• Internal consistency. The hand-back caps in AGENTS.md match the ones each role restates in architect.md, developer.md and product-owner.md; the OpenCode deny globs still mirror all four block-destructive.sh patterns.

Findings (MINOR, non-blocking)

1. .agents/hooks/hook-input.sh — the documented backend-parity contract does not hold for objects, arrays or numbers. Inline below.
2. development/glossary.md — ships empty while this PR wires it up as the vocabulary authority, with no route in for terms the code already uses. Inline below.
3. .agents/README.md (not in this diff, so no inline anchor) — the Caveats section still lists .agents/hooks/* among the net-new files that are safe from copier update. This PR makes block-destructive.sh and ensure-toolchain.sh byte-identical to a pristine v0.7.0 render and adds hook-input.sh from the template, and 91d9e4b shows copier update rewriting ensure-toolchain.sh on its own. Hook scripts are template-owned now, so local edits there will be reverted — the opposite of what the caveat tells a contributor. Move .agents/hooks/* into the template-owned sentence above it.

Notes

• Doing the tree move as a separate first commit (ae0c46d) so _skip_if_exists can see the project-authored docs is the right call, and the preserved line counts back it up. Same for retiring the local hook patches in favour of upstream: the grep -o reasoning in particular is correct, and failing open on binary-classified input is precisely the case a deny-list exists for.
• Losing the verify skill is a real capability regression, but it is declared, /verify and make verify both survive, and CLAUDE.md was updated to stop advertising it. Fine as an accepted cost.
• The description says AGENTS.md is 127 lines; it is 130. Immaterial.

[egparedes]

All three findings handled — pushed 9f27b8f.

F2 (glossary) — fixed here. Seeded with 12 terms from devmm-design.md §3, marked as an explicit one-time baseline so the promotion rule still governs everything after it. All 22 cited identifiers verified against the built package. Detail in the thread.

F1 (hook-input.sh parity) — reproduced, routed upstream as grAItools/harness-copier-template#34, per your recommendation. Not patched locally, since a divergence in a hook file works against this PR's thesis.

F3 (.agents/README.md caveat) — fixed here, and it had a bigger root cause.

Chasing it turned up why that file could carry a stale claim at all: our copy was 63 lines behind and had never been updated since the initial scaffold. It was byte-identical to the v0.5.0 render, missing the entire ## Layout section the simplification wave merged in from the four deleted per-directory READMEs.

The cause is copier.yml's _skip_if_exists, which lists a bare README.md. That has no path anchor, so it matches every README in the render, not just the root one — .agents/README.md and development/README.md included. It also explains something from earlier in this branch: development/README.md silently did not update during the v0.7.0 bump and had to be installed from a fresh render by hand. Same glob, and the skip is silent in both directions — copier update reports no conflict and no change.

So this PR now refreshes .agents/README.md from the v0.7.0 render (the Layout section arrives with it) and applies your caveat fix on top: .agents/hooks/* moves into the template-owned sentence, since this PR is exactly what makes those files template-owned. Filed upstream as grAItools/harness-copier-template#33 — the glob, plus the caveat, which is wrong in the template too.

Gate green at 9f27b8f: 900 passed, 75 skipped, unchanged.

Two notes on your review, both accepted: AGENTS.md is 130 lines, not the 127 I claimed, and losing the verify skill is a real regression rather than a neutral simplification.

[egparedes]

[CONFIRMED] correctness — ⏭️ Not fixed here

jq is selected by command -v alone and any jq failure exits 4 instead of falling through to the python3 fallback — the exact "probe by running, not command -v" rule the file's own header (lines 15-18) states, applied only to python3. [same root cause also at: .agents/hooks/hook-input.sh:32, .agents/hooks/hook-input.sh:32, /home/enriqueg/.ao/data/worktrees/devmm/devmm-4/.agents/hooks/hook-input.sh:37, .claude/settings.json:31]

Failure scenario

On a host where jq resolves but fails when executed (an asdf/mise shim with no version set, a half-removed package, a wrapper), command -v jq succeeds, the out=$(... | jq ...) substitution returns non-zero, and hook-input.sh exits 4 without ever trying python3. The PreToolUse guard in .claude/settings.json maps rc!=0 to exit 2, so EVERY Bash tool call is denied with "could not read the tool input (hook-input.sh exit 4; payload unreadable ...)" — the agent cannot run a single command for the whole session, and the message blames the payload rather than jq. Reproduced: with a stub jq that exits 126 and a fully working python3 on PATH, the benign command ls -la was denied (hook exit 2); the same payload parses fine when jq is simply absent.

Upstream-owned (v0.7.0 render, byte-identical). Routing to the template rather than re-diverging — this PR's thesis is retiring local hook patches, and the human reviewer endorsed that split. Adding to grAItools/harness-copier-template#34.

[egparedes]

[CONFIRMED] correctness — ⏭️ Not fixed here

The rewritten Stop hook exits 1 (non-blocking) whenever hook-input.sh cannot be read or run, so make verify never executes — the old hook ran the gate regardless of payload-parse trouble. [same root cause also at: .claude/settings.json:63, .claude/settings.json:63, /home/enriqueg/.ao/data/worktrees/devmm/devmm-4/.claude/settings.json:63, .claude/settings.json:63]

Failure scenario

On a host with neither jq nor a working python3 (the exact macOS-stub case hook-input.sh's own comment calls out), or when CLAUDE_PROJECT_DIR is unset and the agent's cwd is a subdirectory so ./.agents/hooks/hook-input.sh does not resolve, hook-input.sh returns 3 or 127. The hook prints verify skipped: ... and exits 1, which is non-blocking, so the session ends with the agent claiming "done" and make verify never run — unformatted, lint-failing, type-failing or test-failing code is committed and only caught in CI. The previous command had no such dependency: INPUT=$(cat); [ "$(... jq -r '.stop_hook_active // false')" = 'true' ] && exit 0; ... make verify || exit 2 — with jq missing the substitution was empty, the guard fell through, and the gate still ran (and a broken make invocation exited 2, blocking the stop loudly). The sibling PreToolUse hook in the same diff deliberately fails closed (exit 2) for the identical condition; Stop fails open.

Upstream-owned, and a deliberate ADR 0013 choice (fail open on Stop to avoid the loop). The finding is still a fair challenge to it — the old hook ran the gate anyway — so it goes upstream as evidence against that trade, not as a local patch.

[egparedes]

[CONFIRMED] correctness — ⏭️ Not fixed here

The deny regex matches anywhere in the command string, including inside quoted arguments and search patterns, and the newly added message asserts the command "matches the destructive deny-list".

Failure scenario

Read-only commands that merely mention a deny-list token are refused: grep -rn 'rm -rf' ., git log --grep='reset --hard', or any command whose arguments quote one of the four patterns. The agent is blocked from grepping or testing its own deny-list, and the new stderr text tells it the command is destructive rather than that a substring matched, so it retries the same class of command. Reproduced twice in this session against the live hook: a grep -rn -E 'rm -rf|push --force|...' repository search and a printf of a JSON test fixture were both denied with "block-destructive: denied - the command matches the destructive deny-list".

Upstream-owned and pre-existing: the regex was substring-matching long before this PR; only the message is new. Hit twice in this session, so it is real. Reporting upstream.

[egparedes]

[CONFIRMED] correctness — ✅ Fixed in 17232e3

The decision-register scan command git diff --unified=0 -- 'development/work/*/report.md' has no revision range, so it inspects only unstaged working-tree changes and always finds nothing on a committed branch.

Failure scenario

The Reviewer follows this file's contract ("a marker added in the diff without a row here is a defect") and runs the documented pipeline against the feature branch after the Developer has committed. git diff with no range compares the worktree to the index, which is clean, so the grep exits 1 with no output and the check silently passes. A PR that added a DECISION-PENDING: line to report.md with no register row gets a GO instead of the automatic MAJOR that reviewer.md:180 requires. After merge report.md freezes and, per this same file, "this register alone records the outcome" — so the escalated decision is permanently lost with nothing marked pending. Verified: on the current clean tree the documented command produces no output (grep exit 1), while the range form git diff origin/main...HEAD -- ... is the one that would actually inspect the change.

[egparedes]

[CONFIRMED] correctness — ⏭️ Not fixed here

The documented contract "Prints the field's value ... identically under either backend" is false: jq and python3 emit different text for objects, arrays and numbers. [same root cause also at: .agents/hooks/hook-input.sh:7, /home/enriqueg/.ao/data/worktrees/devmm/devmm-4/.agents/hooks/hook-input.sh:33, /home/enriqueg/.ao/data/worktrees/devmm/devmm-4/.agents/hooks/hook-input.sh:41, /home/enriqueg/.ao/data/worktrees/devmm/devmm-4/.agents/hooks/hook-input.sh:36, .agents/hooks/hook-input.sh:33]

Failure scenario

Verified on this machine (jq 1.6 vs python3): {"a":{"b":1,"c":[1,2]}} with path .a yields jq's pretty-printed multi-line {\n "b": 1,\n "c": [\n 1,\n 2\n ]\n} but python's compact {"b": 1, "c": [1, 2]}; {"a":[1,2]} yields multi-line vs [1, 2]; {"a":1.0} yields 1 vs 1.0; and {"a":12345678901234567890} yields 12345678901234567000 (jq 1.6 coerces through a C double) vs the exact integer. Any future hook that reads a non-string field — e.g. a numeric id or a .tool_response object — silently gets different values on a jq host than on a python-only host, and the multi-line jq form breaks the v=$(...)/[ "$v" = ... ] single-line comparison idiom every caller in .claude/settings.json uses.

Already filed as grAItools/harness-copier-template#34 before this review ran.

[egparedes]

[CONFIRMED] correctness — ✅ Fixed in 17232e3

The Fixed entry inverts the pre-fix behaviour of the destructive-command guard: without jq the old hook failed OPEN (allowed everything), not "denied every Bash call", and line 43's "still fails closed" asserts a property the old hook never had. [same root cause also at: CHANGELOG.md:40]

Failure scenario

A maintainer auditing whether jq-less hosts or CI images were protected before this change reads "Previously a host without jq had every Bash call denied" and "the Bash guard still fails closed", concludes the deny-list was enforced on those hosts, and skips any audit or remediation. In reality the old PreToolUse body (jq -r '.tool_input.command // empty' | sh block-destructive.sh) fed empty stdin to grep when jq was missing, so the pipeline exited 0 and rm -rf, push --force, reset --hard and DROP TABLE all ran unblocked. Verified by replaying the origin/main hook body with no JSON parser on PATH against the payload git push --force origin main: exit 0 (ALLOWED); the new body denies the same payload with exit 2.

[egparedes]

[CONFIRMED] correctness — ✅ Fixed in 17232e3

The harness guide states the Stop hook's "non-zero blocks the stop", but the Stop hook it documents deliberately uses exit 1 for its skip paths, which is non-blocking in Claude Code. [same root cause also at: development/harness-usage.md:69]

Failure scenario

An agent or contributor reads harness-usage.md:78-79 and concludes that a session which stopped must have had a green gate. In fact .claude/settings.json:63 exits 1 (not 2) when uv is missing or the payload is unreadable, so the session stops normally with make verify never executed. Work is handed off as "done, gate green" on a tree that was never linted, type-checked, or tested, and only a stderr line no one reads records the skip.

[egparedes]

[CONFIRMED] correctness — ✅ Fixed in 17232e3

The new "change with no work unit" carve-out exempts the spec/plan axes and both register contracts but not the scope check, so a repo-layout PR that moves other features' development/work/ directories trips an automatic MAJOR that nothing can clear.

Failure scenario

Running /verify on this very PR: reviewer.md:100-104 says "Touching another feature's development/work/ directory, a merged feature's report.md ... is an automatic MAJOR defect unless the plan explicitly called for it." This diff moves all 13 work/2026-07-p* directories (including merged reports) into development/work/, and reviewer.md:113-117 declares only the conformance axes and register contracts n/a for a work-unit-less change - the scope rule still applies, and with no plan.md there is no way for a plan to have "explicitly called for it." The Reviewer returns NEEDS-WORK with a MAJOR the Developer cannot fix, and the /build -> /verify loop can never reach GO for any layout refactor.

[egparedes]

[CONFIRMED] correctness — ✅ Fixed in 17232e3

Ownership of the decision-register row is assigned to two different actors: /build step 5 tells the main agent to add it, while developer.md:83-90 and development/adr/README.md:75 say the row is the Developer's alone to append.

Failure scenario

Developer hits a decision beyond its authority, writes DECISION-PENDING: in report.md plus its register row in development/adr/README.md, and stops. The main agent, following build.md:40-42, appends a second row for the same decision before re-invoking. The register now carries two rows with different IDs for one escalation, so the documented "scan the table for pending rows" procedure double-counts open decisions. In the mirror case each side assumes the other owns the row, no row is written, and the Reviewer's rule (reviewer.md:180-181) makes the missing row an automatic MAJOR -> NEEDS-WORK on a build that was actually correct.

[egparedes]

[CONFIRMED] correctness — ✅ Fixed in 17232e3

The Developer is told appending one register row is "the sole sanctioned exception to leaving development/ alone", but line 103 of the same file and architect.md:128 both require the Developer to author ADR files under development/adr/.

Failure scenario

A phase needs a test skipped. developer.md:102-104 says "draft an ADR under development/adr/ and ask before proceeding", and architect.md:126-129 hands ADR authoring to "the human or the Developer", but the Constraints block the Developer reads first declares the register row the only permitted write under development/. The Developer either refuses to draft the ADR and stalls the phase, or silently skips the test without the ADR that /verify (verify.md:31-33) expects - and the Reviewer then flags the undeclared skip as a defect. Same collision applies to the Architect's ADR needed: markers, which have no writer that both files agree on.

[egparedes]

[CONFIRMED] correctness — ✅ Fixed in 17232e3

The subagent capability table advertises the reviewer as "read-only + verify/test/lint" bash, but .agents/README.md states in this same diff that the permission: map that enforces that is OpenCode-only and ignored by Claude Code.

Failure scenario

Under Claude Code the reviewer's frontmatter tools: Read, Grep, Glob, Bash grants unrestricted Bash - the bash: allow-map in reviewer.md:14-30 is ignored (per the new .agents/README.md Layout section: "OpenCode only - Claude Code ignores this field"), and .claude/settings.json denies only three git/rm patterns. A reviewer subagent run in an unattended Claude Code session can therefore execute sed -i, git checkout, or uv run against the tree it is meant to judge independently, despite reviewer.md:129-130 ("Never edit files ... Never auto-fix defects yourself") and the table row claiming otherwise. The same gap applies to the explorer row on line 50, which the /build flow invokes routinely.

[egparedes]

.agents/skills/verify/SKILL.md (file deleted — no inline anchor)

[PLAUSIBLE] correctness — ⏭️ Not fixed here

Deleting the verify skill removes the only description-triggered path that ran make verify outside the four-phase loop; the replacement in the docs is a manual instruction to run it yourself. [same root cause also at: CHANGELOG.md:29]

Failure scenario

The skill fired on "verify", "is this ready", "ready to commit", "check this", or after any non-trivial edit. Its trigger phrases were not folded into reviewer.md's new description (which adds only "is this good", "review this", "find problems"), and development/harness-usage.md deletes both the "Just run the gate and triage failures" table row and the section documenting the trigger, replacing them with "edit directly, then run make verify". Under OpenCode — which the same file states has no session-end gate ("there is nothing equivalent to Claude Code's Stop hook") — a user who makes a small fix and asks "is this ready to commit?" now gets an answer from the model's memory with no gate run and no backstop, and pushes lint/type/test-failing code.

Intended: removing the verify skill was an explicit decision by the repo owner, taken with the capability loss stated. Declared in the PR description and CHANGELOG.

[egparedes]

[CONFIRMED] correctness — ✅ Fixed in 17232e3

The register's ID legend says ID = <feature-slug>.<k> with the example 2026-07-user-auth.1, but both seeded rows use 2026-07-p12.N while the actual work-unit slug is 2026-07-p12-conformance-docs-release, so the stated convention and the shipped data disagree.

Failure scenario

The Developer appends the next row for that same work unit. Following the legend it writes 2026-07-p12-conformance-docs-release.1, which collides in meaning with the existing 2026-07-p12.1/.2 while sorting and reading as a different feature; following the existing rows it writes 2026-07-p12.3, which contradicts the legend the Reviewer checks against. Either way the register's IDs stop being a reliable key back to a work-unit directory, which is the whole point of the <feature-slug> prefix.

[egparedes]

[CONFIRMED] cleanup — ⏭️ Not fixed here

The same rc=$? / -eq 3 / -ne 0 dispatch block is copy-pasted into three hooks (lines 42, 53, 63), each re-printing an install-jq message hook-input.sh already wrote to stderr. [same root cause also at: .claude/settings.json:31]

Failure scenario

Every failure prints two messages to the operator (hook-input.sh's "no working JSON parser (jq or python3) on PATH; ... Install jq (apt-get install jq / brew install jq)." plus the hook's own near-identical line), and the three copies must be edited in lockstep: adding an exit code to hook-input.sh means editing three escaped-JSON one-liners, so one gets missed and that hook mis-classifies the new code as a generic failure. Simpler: let hook-input.sh own the diagnostics (it already does) and have each hook branch only on rc to pick its exit code, or move the whole dispatch into a second tiny wrapper script the three hooks share.

Upstream-owned. A local dedupe would re-diverge .claude/settings.json, which this PR just made byte-identical to the template.

[egparedes]

[CONFIRMED] cleanup — ⏭️ Not fixed here

The four hand-back cap numbers are restated verbatim in nine places across six files instead of having one authoritative home. [same root cause also at: .agents/subagents/reviewer.md:171, development/README.md:25]

Failure scenario

The caps ("three spike hand-backs per plan, three explore hand-backs per phase, three replan hand-backs per feature, five question rounds per spec") appear at AGENTS.md:55-56, development/harness-usage.md:59-60, .agents/commands/plan.md:27, .agents/commands/build.md:37 and :44, .agents/commands/spec.md:29, .agents/subagents/architect.md:205, .agents/subagents/developer.md:163 and :173, .agents/subagents/product-owner.md:152. Raising the explore cap to five means nine coordinated edits; miss two and the developer subagent self-stops at three while /build keeps re-invoking it to five, so the loop the caps exist to bound behaves differently depending on which document the acting agent happened to read. This is the DRY rule the diff's own new skill states (.agents/skills/design-principles/SKILL.md: "Every piece of knowledge — code, schema, doc, config — has one authoritative representation").

Mostly upstream text across six files; a local single-source refactor would diverge from the template in five of them for a DRY win that the template is better placed to make.

[egparedes]

xhigh multi-agent review: 15 findings — 8 fixed in 17232e3, 7 routed upstream or intended. Inline on each.

Fixed here (all locally-owned; the harness-instruction ones were introduced by this branch):

• development/adr/README.md — the decision-register scan command had no revision range, so git diff compared worktree to index and found nothing on any committed branch. Verified: a DECISION-PENDING: line committed to a report was missed by the documented command and caught by the range form. The check meant to make an unregistered escalation an automatic MAJOR silently passed instead — and since the report freezes at merge and the register alone records outcomes, the decision would have been lost with nothing marked pending. This was the sharpest finding, and it was mine.
• Register-row ownership was assigned twice. /build step 5 has the caller add the row; the text I added in e245a65 claimed the Developer was the only role that could. Upstream's version now covers exactly what that patch was written for, so I removed the local claim rather than reconciling it — which also retires its "sole sanctioned exception to leaving development/ alone", contradicted 15 lines later by the Developer's duty to draft ADRs.
• The no-work-unit review carve-out exempted the spec/plan axes and both register contracts but not the scope check — so a repo-layout PR touching every work unit (this one) tripped an automatic MAJOR nothing could clear.
• Three false doc claims, all made false by this branch: the CHANGELOG said the pre-fix guard denied every Bash call when it in fact failed open; harness-usage.md said a non-zero Stop hook blocks the stop, when its skip paths exit 1 (non-blocking); and the subagent table presented the reviewer's read-only bash as enforced, when the permission: map is OpenCode-only and Claude Code honours tools: alone. Register IDs also disagreed with their own legend.

Routed upstream — the hook scripts are byte-identical to the v0.7.0 render, and re-diverging works against this PR's thesis (the same split you recommended for the parity finding):

• hook-input.sh commits to jq on presence alone, and the Stop hook now skips the gate on any reader failure harness-copier-template#35 — two real ones. hook-input.sh commits to jq on command -v alone, so a broken jq exits 4 without ever trying python3, and PreToolUse then denies every Bash call for the session. Reproduced: with a stub jq exiting 126 and a working python3, ls -la was denied; the same payload succeeds when jq is merely absent. A broken jq is worse than none. Same issue covers the Stop hook now skipping make verify on any reader failure, where the old hook ran it anyway.
• block-destructive.sh matches deny-list tokens inside quoted arguments, blocking read-only commands that merely mention them harness-copier-template#36 — the deny-list matches inside quoted arguments. It hit four times this session; the fourth was filing that very issue, whose body quotes the patterns — I had to write it via a non-Bash tool. A guard that cannot be documented from inside the harness it guards is over-matching.
• hook-input.sh: jq and python3 backends disagree on objects, arrays and non-integral numbers, contradicting the documented parity contract harness-copier-template#34 — the parity contract you found, already filed.

Intended, not fixed: removing the verify skill (your call, capability loss stated); and two DRY findings in .claude/settings.json / cap numbers, both upstream-owned.

Gate green at 17232e3: 900 passed, 75 skipped, unchanged.

[egparedes]

Re-pinned to template v0.7.0-3-g0fa3c56 (06940b4)

The template moved three commits past v0.7.0, and all three are fixes for
issues this branch reported. All eight upstream issues from this adoption
(#25–#36) are now closed.

Upstream fix	Effect here
_skip_if_exists root-anchored	.agents/README.md was frozen by a bare README.md matching at every depth; it now updates from the template
Reader probes each backend by running it	A jq that resolves but is broken falls through to python3 instead of failing the read
Stop gate reports instead of skipping	A gate that cannot be blocked still runs, rather than the session ending unverified
Deny-list matches outside quotes	grep -rn '<pattern>' . passes; cd x && <operation> y is still denied

Conflict resolution

One conflict, in .agents/README.md — upstream rewrote the exact bullet this
branch had patched. Taken wholesale from the template: upstream's version
generalises the local claim (hooks are template-owned) to all of .agents/,
and adds the safe-to-edit list. Nothing local was lost; the file is now
byte-identical to a pristine render.

development/harness-usage.md and development/tool-bootstrap.md are
_skip_if_exists, so copier left them untouched and the new behaviour was
ported by hand. The Stop-hook paragraph was rewritten, not replaced —
upstream's new text covers the reader path but not the uv-unavailable path,
which still skips the gate on exit 1. Both paths are now stated.

Verification

The dry run happened on a throwaway clone first, and every template-owned file
in the end state was compared byte-for-byte against a pristine render of the
pinned commit before the real branch was touched.

Every claim added to the two hand-ported documents was checked against the
scripts rather than read off the upstream diff — 13 deny-list cases (quoted
mention, bare operation, nested-shell runner, pipe into a shell, \rm alias
bypass, and the push-ends-in-sh non-match) and the reader's exit codes for
broken jq, python3-only, no working parser (3) and empty payload (4). All
13 matched; all four exit codes matched.

One note on the new deny rule, from using it: committing this change was
itself denied, because the commit message quotes the SQL pattern and rule 3
matches that anywhere. That is documented behaviour, not a regression — the
message now lives in a file passed to git commit -F.

Gate: 900 passed, 75 skipped — unchanged. CI 9/9 green.

[egparedes]

Rule 2's [^'\"]* halts at a quote nested inside the runner's script, so an operation preceded by a quoted word is allowed.

Reproduced independently against both versions: bash -c 'git fetch && echo "resetting" && git reset --hard origin/main' → allowed here, denied on main. Rule 1 has already classified the outer span as a mention, so nothing catches it.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

The -…c flag must be adjacent to the shell name, so a long option or option cluster escapes rule 2.

${shells}[[:space:]]+-[[:alnum:]]*c cannot match a second -. Reproduced: bash -euo pipefail -c '…' and bash --norc -c '…' → allowed here, denied on main; the adjacent sh -c form still denies.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

outside_quotes is ^-anchored per line, which is unsound for a command carrying a multi-line quoted argument.

The continuation line begins inside the string, so its closing quote is unmatched and nothing after it is reachable. Reproduced with the ordinary multi-line commit-message form chained to a delete: allowed here, denied on main.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

squoted models POSIX single quotes only; $'…' permits \' inside and desynchronises the parity model.

Reproduced: git commit -m $'fix don\'t break' && rm -rf build → allowed here, denied on main. Every operation later on the line becomes unreachable.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

piped cannot cross a second pipe and allows only a sudo prefix, so an extra stage lets the operation reach a shell.

Reproduced: | tee /tmp/x | sh and | env sh → allowed here, denied on main; bare | sh still denies. The header claims rule 2 covers an operation ahead of a pipe into a shell.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

The printf '{}' | jq -e . probe proves parsing, not query compatibility.

The real query uses try … catch, which jq gained in 1.5. A jq 1.4 passes the probe, then fails on a syntax error that 2>/dev/null swallows → exit 4 → .claude/settings.json maps it to exit 2, denying every Bash call while blaming a damaged reader and never mentioning the working python3 on the same PATH.

Skipped here — filed upstream as template#41. Template-owned; same reasoning as the guard findings.

[egparedes]

The proxy checks the guard is readable, not that it runs, so a truncated guard exits 0 and allows everything.

[ -r ... ] passes for a present-but-damaged script; running an empty file exits 0 and the hook reports success. The SessionStart probe exercises hook-input.sh only, so nothing signals that the deny-list has stopped working — while .agents/README.md advertises it as failing closed.

Skipped here — filed upstream as template#41. Template-owned; same reasoning as the guard findings.

[egparedes]

Rule 1 is an anchored regex of bracket expressions, so one byte invalid in the current locale defeats it.

Under LANG=en_US.UTF-8, cd \377x && rm -rf y is allowed; the identical input under LC_ALL=C is denied, and the pre-rewrite one-liner matched it. Locale-dependent, so it will not reproduce on a C-locale CI runner.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

push --force prefix-matches push --force-with-lease, hard-denying the safe form.

git push --force-with-lease origin main → exit 2. Unlike a quoted mention there is no rephrase — quoting it stops it being a command — and permissions.deny's Bash(git push --force:*) denies it a second time. Pre-dates this PR; it is not a regression.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

The header calls "a shell run from a file it wrote" a blind spot "unchanged in kind" — the earlier form denied it.

Reproduced: printf 'rm -rf /tmp/x' > s.sh; sh s.sh → allowed here, denied on main. A maintainer reading the header would believe this exposure pre-dates the change and needs no re-evaluation.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

matches() forks a fresh grep per rule, scanning the same short string four times on every Bash call.

Four call sites, on top of the five processes hook-input.sh already spawns, on the critical path of every Bash invocation. Rule 2's two patterns could be one alternation and rules 1 and 3 could share a pass.

Skipped here — filed upstream as template#40. This file is template-owned and byte-identical to the pinned render; patching it locally would re-diverge the file this PR exists to align. The shape is xfail(strict=True) in tests/test_harness_deny_list.py, so the upstream fix will announce itself as an XPASS.

[egparedes]

Review round 3 (xhigh) — 15 findings, 4 fixed here, 11 routed upstream

The headline: the template's quote-aware guard rewrite fails open on eight
command shapes the previous matcher denied. I re-derived this independently
of the review agents by feeding identical text to both versions of the script
— it only reads stdin, so nothing was executed:

Command shape	v0.7.0	pinned
nested quote inside a bash -c script	deny	allow
-c not adjacent to the shell name (-euo pipefail -c, --norc -c)	deny	allow
multi-line quoted argument, then a chained operation	deny	allow
$'…' ANSI-C quoting, then a chained operation	deny	allow
an extra pipeline stage before the shell (| tee x | sh, | env sh)	deny	allow
write a script, then run it	deny	allow

Five distinct causes, all in the one regex grammar. Filed as
template#40
rather than patched here: .agents/hooks/* is byte-identical to the pinned
render, and re-diverging it is the thing this PR exists to undo. A second
issue, template#41,
covers two health checks that establish less than they conclude — the jq probe
proves parsing but not query compatibility (a jq older than 1.5 denies every
Bash call while blaming a damaged reader), and the PreToolUse proxy checks the
guard is readable rather than that it runs.

What that leaves this branch

Merging before upstream fixes #40 means accepting a guard weaker than main's
for those eight shapes. permissions.deny does not compensate: its patterns
(Bash(rm -rf:*)) are prefix matches, so they never fired on the embedded
forms in the first place.

The mitigation that is in scope landed instead — tests/test_harness_deny_list.py,
pinning the verdict for 24 shapes: 15 assertions locking correct behaviour, 9
xfail(strict=True) for the known gaps. Strict matters both ways. An upstream
fix fails the gate as an XPASS instead of passing unnoticed, and a future
copier update that weakens the guard fails instead of arriving conflict-free
with nothing to review — which is exactly how these eight shapes got in.

Fixed here

• The register scan was vacuous on any repo where origin/main does not
  resolve. "$(git merge-base origin/main HEAD)" expands to nothing, the
  range degenerates to HEAD...HEAD, and the scan reports clean for any diff.
  Now origin/main...HEAD, which resolves the same merge base (verified
  byte-identical output) and exits 128 rather than returning nothing. This is
  the second defect found in this one snippet, and both times it failed by
  looking clean — the failure mode a contract check can least afford.
• The SessionStart bullet documented one hook after this PR added a second.
• The wheel-vs-sdist invariant lived only in development/README.md, which is
  template-owned and unprotected; moved to
  development/architecture.md#distribution-boundary, which is not.

Skipped, one line each

.agents/hooks/* and .claude/settings.json findings (8 of them) are all
byte-identical template files → #40 / #41. --force-with-lease being
prefix-denied by push --force pre-dates this PR → #40. The per-rule grep
fork count is real but minor, and lives in the same upstream file → #40.

Gate: 915 passed, 75 skipped, 9 xfailed. CI 9/9 green.