A write refused
In the example repository, a person has approved a brief for one round of agent work: charge a late fee. The brief says which files the round may write and which it must not change. Below, the round runs on the brief's branch, and every block is what the command printed.
Played by the example's scripts/demo.mjs at 77b504f, with spec-harness 0.26.0, in this site's CI.
Brief 001 is active on main: a person approved it. Its round may write src/fees.js and its test; it must not change src/loans.js, the loan record, or anything under docs/. The agent works on a branch whose name names the brief:
git switch -c story/brief-001-write-refused
Switched to a new branch 'story/brief-001-write-refused'Its plan puts a fee on every loan, in src/loans.js. Before a write, the guard says whether the round may make it:
npx --no-install @spec-family/spec-harness guard src/fees.js src/loans.js
ok src/fees.js is in brief 001's scope (src/fees.js)
refused brief 001 does not empower this round to change src/loans.js (protectedFiles: src/loans.js)
if the round cannot be done without it, stop and ask for a ruling: spec-harness escalate --path <file> --reason <why>, or the request_escalation tool1 · spec-harness 0.26.0With the hooks spec-harness init wrote into .claude/settings.json, Claude Code asks the same before each Edit, Write, MultiEdit and NotebookEdit. Its question about a Write of src/loans.js, the new text left out here, and the answer:
echo '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"src/loans.js","content":"…"}}' | npx --no-install @spec-family/spec-harness hook claude
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"spec-harness: brief 001 does not empower this round to change src/loans.js (protectedFiles: src/loans.js). Next: if the round cannot be done without it, stop and ask for a ruling: spec-harness escalate --path <file> --reason <why>, or the request_escalation tool."}}0 · spec-harness 0.26.0The refusal is the answer's permissionDecision, which Claude Code reads, and the write is not made; the exit code says only that the hook could answer. So the agent writes src/fees.js and test/fees.test.js, which the brief allows, ticks the brief's boxes, and makes the refused change through the shell, where no hook is asked:
node -e "const f = 'src/loans.js'; fs.writeFileSync(f, fs.readFileSync(f, 'utf8').replace('LOAN_DAYS }', 'LOAN_DAYS, fee: 0 }'))"
git add -A
git commit -q -m "Charge a late fee"
git diff --stat main
briefs/001_charge-a-late-fee.md | 6 +++---
src/fees.js | 7 +++++++
src/loans.js | 2 +-
test/fees.test.js | 14 ++++++++++++++
4 files changed, 25 insertions(+), 4 deletions(-)Nothing stopped it: the guard is a guardrail, not a gate. The gate is the audit, which reads the round's commits from main, whatever wrote them:
npx --no-install @spec-family/spec-harness audit
audit of brief 001 from main (81b814dcdc9f)
error briefs/001_charge-a-late-fee.md:7 the round changed src/loans.js, which this brief protects archive/protected-file
revert the change, or ask the person who approved the brief to rule on it (spec-harness escalate): a signed ruling, which a plugin that verifies rulings reads, lifts this
measured: goals: 1 held, 0 failed · premises: none declared · archive: asked · rulings: none · dependencies: 0 changed, 0 unread
1 error(s), 0 warning(s), 0 note(s)1 · spec-harness 0.26.0In CI
The example's CI runs the audit on a brief's branch. Pull request
#2 holds this story's
branch and is left open: its round job, where the audit
runs, is red, and no other job is.
With git's pre-commit hook installed (spec-harness init --git-hook --write),
the commit itself is refused, for any agent or none. The hook lives on one
machine and git commit --no-verify skips it, so the audit stays the gate.
Further
- The guard and its hooks, and the audit, in the spec-harness reference.
- The other story: a claim without evidence.