# A write refused

In the [example repository](https://github.com/spec-family/example), 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`](https://github.com/spec-family/example/blob/77b504ff1625988557b2767356b68d4a40f09a8c/scripts/demo.mjs) at [`77b504f`](https://github.com/spec-family/example/commit/77b504ff1625988557b2767356b68d4a40f09a8c), with spec-harness 0.26.0, in this site's CI.

[Brief 001](https://github.com/spec-family/example/blob/77b504ff1625988557b2767356b68d4a40f09a8c/briefs/001_charge-a-late-fee.md) 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:

```console
$ 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:

```console
$ 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 tool
```

Exit `1` · spec-harness 0.26.0.

With the hooks `spec-harness init` wrote into [`.claude/settings.json`](https://github.com/spec-family/example/blob/77b504ff1625988557b2767356b68d4a40f09a8c/.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:

```console
$ 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."}}
```

Exit `0` · spec-harness 0.26.0.

The 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:

```console
$ 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:

```console
$ 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)
```

Exit `1` · spec-harness 0.26.0.

## In CI

The example's CI runs the audit on a brief's branch. Pull request
[#2](https://github.com/spec-family/example/pull/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](https://github.com/spec-family/spec-harness/blob/v0.26.0/docs/reference/guard.md), and
  [the audit](https://github.com/spec-family/spec-harness/blob/v0.26.0/docs/reference/audit.md), in the spec-harness reference.
- [The other story](https://spec-family.github.io/stories/claim-without-evidence/index.md): a claim without
  evidence.

---

This is the Markdown version of https://spec-family.github.io/stories/write-refused/. Every command's output in it is printed by spec-brief 0.15.0, spec-graph 0.26.0, spec-guard 0.35.0 and spec-harness 0.26.0 in the site's CI; [llms.txt](https://spec-family.github.io/llms.txt) lists every page.
