wr-architect: edit gate binds to the Edit/Write tool, so Bash-routed edits of governed files bypass it entirely

[tompahoward]

wr-architect: the edit gate binds to the Edit/Write tool, so Bash-routed edits of governed files bypass it entirely

architect-enforce-edit.sh is registered in hooks/hooks.json under "matcher": "Edit|Write". It therefore fires on the tool name, not on the predicate "a file under docs/decisions/ is being modified". Any edit routed through Bash (a node script, a perl -pi, a sed -i) modifies governed files with no gate firing at all.

Checked against 0.20.2.

What we saw

A node script invoked through Bash rewrote 141 link targets across 47 files, including 14 ADR bodies under docs/decisions/. No gate fired at any point.

The gate then blocked the very next Edit-tool call against one of those same ADRs. That asymmetry is the only reason we noticed: the ungated batch left no signal of its own.

The same Edit|Write scoping applies on the PostToolUse side, so architect-refresh-hash.sh and architect-compendium-update-entry.sh also did not fire for those 141 edits. Stored content hashes are consequently stale against the 14 edited ADR bodies, and the compendium is missing their entries. That direction fails safe: the next Edit-tool touch blocks on decision-drift rather than silently accepting. The operator still experiences it as an unexplained gate refusal with no obvious cause.

The channel is already wired, which makes this cheap

0.20.2 already registers Bash on both sides:

• PreToolUse "matcher": "Bash" -> architect-readme-pairing-check.sh
• PostToolUse "matcher": "Agent|Bash|Skill" -> architect-slide-marker.sh

So this isn't a missing capability. The plugin subscribes to Bash for marker-sliding and for a README pairing check; it just doesn't subscribe for governed-file detection.

Why matcher-widening can't be the fix

Widening the PreToolUse matcher to include Bash cannot work: node scripts/fix-links.mjs carries zero information about which files it will write. The governed path set only exists after execution.

So the fix shape looks PostToolUse-diff-based: after a Bash call, check whether any path under the governed globs changed, and if so refresh the hash and demand review before the next gated action. architect-slide-marker.sh is already firing on exactly that event, so there is somewhere obvious to hang it.

A commit-time check is the other candidate: assert every governed file in the staged set carries a fresh architect marker. Later than detection-time, but path-complete and not bypassable by choice of tool.

We haven't measured the cost of diffing after every Bash invocation. That is your call, since it depends on how the hook budget is allocated across the suite.

Relationship to #410

We deliberately did not append this to #410 (wr-risk-scorer: text-matching command detection).

#410 is an incomplete command-position grammar: its anchor set enumerates some command-introduction positions and misses others, and both of its proposed fixes repair a matcher that exists and does fire. Here the matcher never subscribes to the channel doing the writing.

Different plugin, different matcher, different fix shape. Folding them together would let #410 close in full while this stays open.

They do share a class, which may be worth naming somewhere: a governance gate observing a proxy (the tool name, or the command text) instead of the governed action. #410's root-cause section already articulates that class.

Workaround we're using

Consult the architect agent voluntarily before any bulk edit that will touch docs/decisions/. That is what happened in the originating batch: two review passes, both returning ISSUES FOUND, both materially changing the work.

It is not a control. It depended entirely on the agent choosing to ask, which is the property a gate exists to remove.

We'll send a PR if the PostToolUse-diff shape is the direction you want.

[tompahoward]

Correction to the PostToolUse paragraph in the report above. We asserted that stored content hashes were left stale against the 14 edited ADR bodies, and that the compendium was missing their entries. Both are wrong. The error was assuming a per-file hash store the plugin does not have. Checked against 0.20.2.

• _substance_hash_path in hooks/lib/gate-helpers.sh computes one sha256 over every docs/decisions/*.md concatenated, README excluded, whitespace-normalised. There is no per-ADR hash.
• It is session-scoped, at /tmp/architect-reviewed-<SESSION_ID>.hash, so nothing durable is left behind for a later session to inherit.
• The comparison lives in hooks/lib/architect-gate.sh, not in architect-enforce-edit.sh, which contains no hash logic at all. On mismatch it removes the marker and the hash file and denies with a re-delegate directive, so a stale digest cannot persist: the first Edit-tool touch that sees it clears it and buys one review.
• The compendium was complete when we checked: 41 ADRs on disk, 41 entries. A compendium entry carries title, status, oversight and Related-ADR IDs rather than body content, so a link-target rewrite inside an ADR body cannot change one.

The consequence runs the opposite way to what we wrote. architect-refresh-hash.sh not firing after a Bash-routed edit is the safe direction: had it fired, it would have re-blessed the digest and erased the only remaining signal that those edits happened. Its Edit|Write scoping is doing the right thing here.

The PreToolUse half of the report stands unchanged, and it is the part we are asking about: no architecture review is demanded before a Bash-routed edit of a governed file. What the drift check buys afterwards is a whole-directory re-review triggered by the next Edit-tool touch, which is weaker than a gate on the specific change, and is not nothing. That makes the report narrower than filed.