[LTSCommerce]

What this changes

DETECTOR-SPEC.md, four passages, no obligation changed. Clause 7.1's detectable route reads "a bespoke Rule the project writes for the Detector under clause 4.1" in place of "a Rule the project can write in the Detector itself", and a new paragraph says what detectable means and what each of the two ways is. Clause 8.1's duty to record a known gap falls only on a detector that declares a version, and says so beside "The declaration is optional"; its second paragraph says anyone may grade a detector by checking it against each clause of sections 4 to 7. Clause 5.3 says what the remainder is, that there is none where the output prints every finding, and that a fuller report elsewhere is not one. Clause 6.1 says it asks for the mechanism and not for every page, a missing page failing clause 6.3, and that a documentation path printed in the message is not enough on its own. Section 2's table gains a Message row.

The observed case

Cold cohorts of the defined-terms change, which touched none of these passages, had two or more readers quote each of them as confusing: clause 7.1 in runs 36, 42, 45, 48, 51 and 54, read as the project editing the detector's own source; clause 8.1 in runs 39 and 42, the gap MUST set against "The declaration is optional"; clause 5.3 in run 32; clause 6.1's message sentence in run 54. Each is a row of acceptance/ROUTED.md, closed by this change's run 66. Runs 60 and 63 of this change then showed Message undefined for a reader given this document alone, clause 8.1's "anyone who exercises the clauses above" stopping two readers, and clause 5.3's new sentence needing two readings.

Kind of change

• Clarity edit: no MUST, SHOULD or MAY added or removed; a reword that keeps the keyword and most of the words counts as clarity
• Obligation: the five tests below are answered

The five scope tests (obligations only)

Not an obligation change; tools/changes.py is clean against next.

Where it goes

Clauses 5.3, 6.1, 7.1 and 8.1, and section 2's table.

Not done here, by design

Version lines are untouched: the entry is under Unreleased. Runs 60, 63, 66, 73, 77 and 78 are recorded under acceptance/runs/; run 66 passed, the text then changed in clauses 5.3 and 8.1 after a cohort of another change that carried this one, runs 73 and 77 failed on clause 5.3's wording, and run 78 passed on the text as it now stands. The answer sheets are posted as comments below. Made under the acceptance process change of pull request 22, at the commit each run record names.

🤖 Generated with Claude Code

[LTSCommerce]

Run 060: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Command and working directory

ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt, each reader in a fresh empty directory made by mktemp -d outside the repository

Model version each reader reported

reader 1: claude-haiku-5-5
reader 2: claude-haiku-5-5
reader 3: claude-haiku-5-5
reader 4: claude-haiku-5-5
reader 5: claude-haiku-5-5

The delegated marker's task prompt

MODE: mark

Worktree: <worktree> (branch `editor/detector-route-rule`). The readers read commit ed30e69. Read, at that commit and in that worktree: ACCEPTANCE.md in full (it is the process as pull request 22 proposes it, merged into this branch at 972cbb7 and 04aa914; the run is made under that process change before it merges, at commit e6bdf40, named here before the readers started), acceptance/runs/README.md, acceptance/detector/QUESTIONS.md, acceptance/detector/KEY.md, acceptance/fixtures/lintomatic.md and DETECTOR-SPEC.md. You may read acceptance/runs/058-toolchain-contradictions-run-2.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 060. Document: DETECTOR-SPEC.md. Change: detector route rule (clause 7.1's detectable route is a bespoke rule the project writes for the detector under clause 4.1, with a paragraph on what detectable means; clause 8.1's gap duty falls only on a detector that declares a version; clause 5.3 says what the remainder is; clause 6.1 says it asks for the mechanism, a missing page failing 6.3, and that a path in the message is not enough on its own). Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 1. Record file to write: <worktree>/acceptance/runs/060-detector-route-rule-run-1.md. Do not commit it.

Sheets: <run-dir>/sheet-1.md to sheet-5.md, each the `result` of reader-N.json. Prompt the readers received: <run-dir>/prompt.txt; its sha256 is d3b016b18288e3589df60de97f746a31179924dbdd5faa339c055fbf95d89125, and it is byte for byte the question set, DETECTOR-SPEC.md and the fixture at ed30e69, each after one `===== FILE: <name> =====` line, one blank line between files. Model: every reader reported claude-haiku-5-5 (<run-dir>/models.txt); the cohort's model named for the run is claude-haiku-5-5. Every reader's JSON has is_error false and subtype success; no reader is set aside.

Facts the editor supplies for the record: cohort of five readers, none reused from any earlier run; each a separate `claude -p` process started through the `ccy-claude` wrapper (which only reattaches the session's credential) in a fresh empty directory made by `mktemp -d` outside any repository, with the packet on standard input, command `ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt`; no tools, no settings, no project context, no saved session; the machine applies no managed settings; the editor attests the rest of the isolation. Marked by a delegated marker, a fresh `dbf-spec-editor` agent (Claude Opus) given this instruction and its agent definition, having seen neither the drafting nor the review.

Text the change wrote or altered, for "Where a finding lies": the output of `git -C <worktree> diff 9e914fe ed30e69 -- DETECTOR-SPEC.md` (9e914fe is the merge base with `next`). Run it and read it. A finding in a paragraph that diff adds, rewords, moves, deletes a sentence from, or changes a word, term or link in, or that a reader sets against such a paragraph, blocks; any other finding is routed to acceptance/ROUTED.md, and the record says so for each.

Mark every sheet, keyed item by keyed item, by ACCEPTANCE.md's Marking section and the key alone. Write the record stating what acceptance/runs/README.md lists, in its order, with the marks table, each miss with the reader's reasoning in brief, every passage named under question 4 with its words or description, clause and readers, each finding and where it lies, any open point and the direction you marked it, the process-change commit e6bdf40, the verdict, and a placeholder line for the link to the posted sheets. Reply with the verdict and the findings only, under thirty lines.

The agent definition the marker ran under

---
name: dbf-spec-editor
description: Drafts, reviews, key-updates, marks or records a change to the Defence Before Fix specification, one mode per dispatch, following the specification repository's CONTRIBUTING.md, SCOPE.md and ACCEPTANCE.md exactly. Dispatched by the dbf-spec-change skill; it cannot run a cohort itself.
tools: Read, Write, Edit, Grep, Glob, Bash
model: opus
---

You work on one change to the Defence Before Fix specification, in the worktree path you are
given. The process is defined by that repository's `CONTRIBUTING.md`, `SCOPE.md`,
`ACCEPTANCE.md` and `acceptance/README.md`; read the ones your mode needs, in full, before you
act. You invent no steps. You never merge, push to `next` or `main`, release, tag or publish,
and you never change a question, threshold or fixture. Your prompt names one mode.

Write as the specification is written: British spelling, no em dashes, defined terms linked as
`spec-qa.py` requires, every clause or section number linked to its heading. Commit on the
worktree's branch.

## MODE: draft

1. Read `SCOPE.md`, `DECLINED.md`, and every clause the change touches, with the terminology
   entries they use.
2. Decide the kind. A change to the sentences carrying MUST, SHOULD or MAY in a numbered section
   or appendix is an obligation; anything else is a clarity edit.
3. For an obligation, answer the five SCOPE tests in a sentence or two each, and name the
   section the obligation extends. If a test fails, or an existing clause already covers it, say
   so and stop without editing.
4. Make the smallest edit that does the job, in the clause that owns the subject.
5. Add one line under `Unreleased` in `CHANGELOG.md`, saying what changed and why, with a
   placeholder `run NNN`. Change no version.
6. If Appendix A changed, run `python3 build-agent-surfaces.py` and commit its outputs.
7. Run `python3 spec-qa.py` and `python3 -m unittest discover -s tools -p 'test_*.py'`; both
   clean.
8. Reply with: kind, SCOPE answers, files changed, commit, QA result, and a filled
   `.github/PULL_REQUEST_TEMPLATE.md` body. Under forty lines.

## MODE: review

You have not seen the drafting. Read the whole changed document and the diff against
`origin/next`. Report, numbered, with clause numbers: contradictions with other clauses, terms
used outside their definition, a sentence a reader could take two ways, an obligation an owner
could not verify from the record. Do not edit.

## MODE: keys

Read `acceptance/README.md` and the `KEY.md` for each changed document. Update every quotation of
a changed sentence to the new wording, verbatim, in a new commit; run `python3 spec-qa.py` until
`key-quote-stale` is gone. If the change adds a load-bearing obligation no keyed question
covers, propose the question and its key in your reply; add it only if your prompt says the owner
has decided to.

## MODE: mark

You have not seen the drafting or the review. Read `ACCEPTANCE.md` in full, the `KEY.md` for the
document, the document at the commit named, and the sheets under `<run-dir>/`.

- Mark each sheet against the key, keyed item by keyed item, by the rules under "Marking" in
  `ACCEPTANCE.md` and nothing else: the key's required elements, accepted grades, conditions and
  wrong readings. Invent no judgement; where neither the rules nor the key settles a mark, mark
  it in the direction the open-point rule gives and record the point.
- A single miss under questions 1 and 3 counts against the document only where the key names
  that reading; say which.
- For question 4, record every passage named, with its words or description and its clause.
  Group the passages by paragraph, count the readers, and for each finding say whether it lies in
  text the change wrote or altered, read against the diff the prompt gives you, or is routed to
  `acceptance/ROUTED.md`. Ignore any suggestion a reader volunteers.
- Apply the pass criteria exactly.
- Write `acceptance/runs/NNN-<slug>-run-<k>.md` stating what `acceptance/runs/README.md` lists,
  in its order. Do not commit it. Reply with the verdict and the findings only.

## MODE: record

Commit the run record, replace the `run NNN` placeholder in `Unreleased` with a link to it, and
for an obligation set the document header to `<next version>-dev, unpublished` in the same
commit if it still names a published version. Run `python3 spec-qa.py` and
`python3 tools/changes.py --base origin/next`; both clean. Reply with the commit.

[LTSCommerce]

Run 060: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Answer sheets, each reader's whole output as its process returned it

reader-1

{"duration_api_ms":58255,"stop_reason":"end_turn","session_id":"fa163836-c5e4-4056-b3cb-ad5a0f7dff2f","total_cost_usd":0.009614929999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11206,"cache_read_input_tokens":2153,"output_tokens":14704,"output_tokens_details":{"thinking_tokens":12584},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11206,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14704,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11206,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11206},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14704,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11206,"webSearchRequests":0,"costUSD":0.009614929999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12584,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules and register them so they run with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and shows whether it fired and what it printed, for bundled and bespoke rules alike (4.2).\n- Each rule has a stable identifier, not derived from its path, class name or position. The detector prints it unaltered with every finding (4.3). A self-check rule for this is a SHOULD (4.4).\n- It must run locally with no infrastructure, including on a single file, and the results must appear in the output of the command the practitioner ran. No finding may be reportable only through a hosted, licence-tier or CI-only route (5.1–5.4).\n- For a bundled rule, a printed identifier must resolve to documentation on disk, offline, and every identifier the rule can print must resolve (6.1–6.3). For a project's own rule, the detector prints the identifier unaltered.\n- An inline suppression route, if offered, must be disableable or detectable (7.1). A detector conforms if it meets every MUST in sections 4 to 7 (8).\n\n## 2. Load-bearing statements\n\n**2a.** Conformance means satisfying every MUST in sections 4 to 7. A detector that predates the document can still conform, because the claim is optional and the verdict rests on checking the clauses.\n\n- \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\"\n- \"A Detector that predates this document, or whose maintainer has never read it, MAY be graded Conforming on evidence by anyone who exercises the clauses above against it, and a verdict on any Detector, declared or not, rests on that exercise and not on the claim.\"\n\n**2b.** The detector must either make the route disableable by configuration or make it detectable. One of these is enough. The detectable route is closed to a detector whose rules cannot see comments, so for those it must be disableable or covered by a documented mechanical check.\n\n- \"For each one it MUST do at least one of two things, and either alone satisfies this clause\"\n- \"A route that can be neither switched off nor seen does not [Conform].\"\n- \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\"\n\n**2c.** The documentation must ship inside the installed package, at the same version as the rule. Resolution must work offline from that installed copy. A website is not sufficient.\n\n- \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\"\n- \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\"\n- \"A catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong place.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | \"A project can add its own rules by writing a Zig module that implements the `Rule` interface and listing it in `lintomatic.toml`; project rules are loaded on every run and are first class in every report.\" |\n| 4.2 | Yes | `check --only <identifier> <path>` runs one rule for bundled or project rules and exits 1 or 0 on whether it fired. The fixture does not say the `--only` run prints finding lines; I am inferring \"what it printed\" from `check`'s one-line output. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, fixed at first release. Project identifiers come from configuration and \"Lintomatic does not add or rewrite any part of the name.\" The one-line form, which carries the identifier, is printed \"whether or not the HTML report is enabled.\" The fixture names no machine-readable format, and the HTML report is not described as carrying identifiers, so I have not counted it as machine-readable. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | Every finding is on stdout with file, line, column, identifier and message, so there is no remainder. The HTML report need not be named in the output. |\n| 5.4 | Yes | \"the same binary is what CI runs,\" and \"every finding [the dashboard] shows is also printed by the command line.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the identifier alone. For a project rule it prints the declared doc string, or \"No documentation declared\" when there is none. |\n| 6.2 | Yes | `explain` reads \"from the installed package,\" and \"The documentation is versioned with the package; there is no separate website.\" |\n| 6.3 | No | \"two of the forty rules currently print `No documentation declared`.\" The forty are the bundled rules, so two bundled identifiers resolve to nothing. The clause says \"One Identifier that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` \"can be disabled project-wide with `ignore_comments = false`,\" which is a route disableable by configuration. |\n\n**Conformance under section 8: No.** Lintomatic fails 6.3, which is a MUST. Section 8 says \"Partial Conformance MUST NOT be described as Conformance,\" so Lintomatic does not conform, and the 6.3 failure is the reason.\n\n**Effect of 6.4: none on the verdict.** 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture says Lintomatic's own CI \"does not check that every `LM-NNNN` identifier has an `explain` entry.\" That check is what 6.4 asks for, so the gap is real. The toolchain specification would make 6.4 a MUST if Lintomatic shipped inside a Toolchain. I was not given that document, so I have not graded it.\n\n(Not graded, as they were outside the list: 7.2 is a SHOULD, and the fixture says the ignore comment \"takes no reason,\" so 7.2 would not be met.)\n\n## 4. Confusion\n\n- 6.1: \"A documentation path printed in the [Message] is therefore not enough on its own\". \"Message\" is defined in the method specification, which I was not given, so I read it as the printed finding text.\n- 6.1: \"Where the [Identifier] is itself a URL, as method clause 3.6 allows\". I cannot check what clause 3.6 allows, so I took the URL case on trust.","ttft_ms":51525,"type":"result","duration_ms":58559,"uuid":"26dfb502-d4f1-4394-82a8-1de61f017720","ttft_stream_ms":1134,"time_to_request_ms":321,"first_content_frame_ms":1135,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":49556,"stop_reason":"end_turn","session_id":"90634206-54b7-4c4a-ab0f-d0507f268923","total_cost_usd":0.00842893,"usage":{"input_tokens":2,"cache_creation_input_tokens":11206,"cache_read_input_tokens":2153,"output_tokens":12332,"output_tokens_details":{"thinking_tokens":10232},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11206,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12332,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11206,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11206},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12332,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11206,"webSearchRequests":0,"costUSD":0.00842893,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10232,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A Detector must let the project write its own Rules and run them with the same standing as bundled Rules (4.1).\n- It must provide a Harness that runs one Rule against supplied code, for bundled and bespoke Rules alike (4.2).\n- Each Rule carries a stable Identifier, not derived from its path, class or position, and the Detector prints it unaltered with every finding (4.3).\n- It must run locally, on a single file as well as a whole codebase, and put every finding in the output of the command the practitioner ran, never only in a hosted, licence-tier or CI-only channel (5.1–5.4).\n- A printed Identifier must resolve to its documentation from the Identifier alone. For bundled Rules that means documentation shipped in the installed package, working offline, covering every Identifier the Rule can print (6.1–6.3).\n- Any inline suppression route must be either switchable off by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\nQuotations have their link brackets removed.\n\n**2a.** A Detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document existed can conform. Its maintainer need not have read the document, and it is graded on evidence.\n\n> \"A Detector Conforms if it satisfies every MUST in sections 4 to 7.\" (section 8)\n\n> \"A Detector that predates this document, or whose maintainer has never read it, MAY be graded Conforming on evidence by anyone who exercises the clauses above against it, and a verdict on any Detector, declared or not, rests on that exercise and not on the claim.\" (8.1)\n\n**2b.** The Detector must do at least one of two things: make the route disableable by configuration, or make it detectable. One of those is enough. The detectable route is only open if the Detector's Rules can see comments, so a Detector whose Rules never see comments needs the disable route or a documented mechanical check.\n\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke Rule … or by a mechanical check the Detector documents.\" (7.1)\n\n> \"a Detector whose Rules never see comments cannot make an ignore comment detectable this way.\" (7.1)\n\n**2c.** The documentation for a bundled Rule's Identifier must ship with the Rule, at a version tracked together with it. It must be readable from the installed copy without network access. A website catalogue does not satisfy this.\n\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together\" (6.3, heading)\n\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (6.2, heading)\n\n> \"Every Identifier a Bundled rule can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\" (6.3)\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project Rules are Zig modules implementing `Rule`, listed in `lintomatic.toml`, \"loaded on every run and … first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one Rule, bundled or project, and exits 1 on fire, 0 otherwise. The fixture does not explicitly say `--only` prints findings, so I take it as a form of `check`, which prints one line per finding. |\n| 4.3 | Yes | Bundled IDs are `LM-NNNN`, fixed at first release. Project IDs are the configured name, which Lintomatic \"does not add or rewrite.\" The one-line default output prints them. The fixture says nothing about a machine-readable format, and the HTML report is not described as one. |\n| 5.1 | Yes | \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line form prints every finding with location and Identifier to stdout, so there is no remainder to point to. |\n| 5.4 | Yes | The dashboard is sold separately, but \"every finding it shows is also printed by the command line,\" and CI runs the same binary. |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the Identifier alone. Project rules print their `doc` string or \"No documentation declared,\" and the Identifier is printed unaltered. |\n| 6.2 | Yes | `explain` \"prints the documentation for a bundled rule from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | No | The documentation ships with the package, but two of the forty bundled rules print \"No documentation declared.\" Under 6.3, \"One Identifier that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `ignore_comments = false` in `lintomatic.toml` disables the `// lintomatic-ignore` route project-wide, which alone satisfies the clause. |\n\n**Conformance (section 8):** Lintomatic does not conform. It fails the MUST in 6.3 on two bundled Rules, and section 8 requires every MUST in sections 4 to 7. It is partial conformance, which section 8 says must not be described as conformance.\n\n**Clause 6.4:** It does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture shows the release check is missing, so the 6.3 failure is not caught before release, but that is a separate SHOULD gap. If Lintomatic is shipped inside a Toolchain, the toolchain specification would make the same check a MUST for the Toolchain. The fixture does not say whether it is, and section 9 keeps that verdict separate from this one.\n\n## 4. Confusion\n\n- **6.1**, heading and project-rule row: \"The Detector MUST provide a mechanism that resolves a printed identifier to its documentation,\" and, for the project's own Rule, \"Print the Identifier unaltered; the lookup is the Toolchain's to give.\" On my reading these point in different directions over whether the Detector owes a mechanism for project Rules.\n- **5.3**: \"a report that only adds detail to those same findings, such as a code snippet, need not be named in the output.\" The phrase \"need not be named\" took a second reading.","ttft_ms":42515,"type":"result","duration_ms":49866,"uuid":"7ae68447-6378-4b4d-a609-e2f0c9a589d8","ttft_stream_ms":1022,"time_to_request_ms":309,"first_content_frame_ms":1022,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":47112,"stop_reason":"end_turn","session_id":"dbe9edf6-c94b-421d-94fa-a258ffce8d69","total_cost_usd":0.00825973,"usage":{"input_tokens":2,"cache_creation_input_tokens":11205,"cache_read_input_tokens":2153,"output_tokens":11994,"output_tokens_details":{"thinking_tokens":10039},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11205,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11994,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11205,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11205},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11994,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11205,"webSearchRequests":0,"costUSD":0.00825973,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10039,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- Let the project write its own rules, in a form the detector's authors never anticipated, and run them with the same standing as bundled rules (4.1).\n- Provide a harness that runs one rule, bundled or bespoke, against supplied code, without the project's test suite or other rules interfering (4.2).\n- Give each rule a stable identifier that is not derived from its path, class name or position, and print it unaltered with every finding, in default and machine-readable output (4.3).\n- Run locally with no infrastructure, on a subset including a single file, with results in the invoked command's output and no findings reportable only through a hosted, licence-tier or CI-only route (5.1–5.4).\n- Resolve a printed identifier to documentation. For bundled rules, the documentation ships with the rule, works offline, resolves from the identifier alone, and covers every identifier the rule can print (6.1–6.3). For project rules, print the identifier unaltered (6.1).\n- If inline suppression is offered, make it disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document can conform: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence by anyone who exercises the clauses above against it\" (8.1). The declaration is optional: \"It is how a maintainer claims [Conformance]; it is not a condition of it.\" (8.1)\n\n**2b.** The detector must do at least one of two things: make the route disableable by configuration, or make it detectable. Doing one is enough: \"For each one it MUST do at least one of two things, and either alone satisfies this clause\" (7.1). \"A route that can be neither switched off nor seen does not [Conform].\" (7.1)\n\n**2c.** The documentation must ship in the installed package, at a version tracked with the rule: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together\" (6.3). Resolution must work offline: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (6.2). Every identifier the rule can print must resolve: \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation\" (6.3).\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | A project writes a Zig module implementing `Rule`, lists it in `lintomatic.toml`, and \"project rules are loaded on every run and are first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, against a file or directory and reports firing through exit codes 1/0/2 and its printed output. |\n| 4.3 | Yes | Bundled `LM-NNNN` identifiers are \"fixed at the rule's first release\"; project names come from configuration and \"Lintomatic does not add or rewrite any part of the name,\" and they print as `proj.no-raw-sql`. The fixture does not say whether `report.html` carries identifiers. I did not count it against this clause because HTML is not described as a machine-readable format. |\n| 5.1 | Yes | The tool \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | Every finding is printed on stdout with location, identifier and message. The HTML report adds only detail, which \"need not be named in the output.\" |\n| 5.4 | Yes | \"The one-line form is printed whether or not the HTML report is enabled,\" and every dashboard finding \"is also printed by the command line.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the identifier as printed and prints bundled documentation. Project rules print their `doc` string, or \"No documentation declared\", and the identifier is printed unaltered. |\n| 6.2 | Yes | Documentation is printed \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | No | Two of the forty bundled rules \"currently print `No documentation declared`.\" \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore <identifier>` can be disabled with `ignore_comments = false`, which satisfies the clause on its own. |\n\n**Conformance:** Lintomatic does not conform. Section 8 requires every MUST in sections 4 to 7, and 6.3 fails. The other ten graded MUSTs are met, which is partial conformance, and per section 8 \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Clause 6.4:** It does not change the verdict. 6.4 is a SHOULD, and section 8 defines conformance by MUSTs only. Lintomatic's repository not checking for `explain` entries is a 6.4 gap, but the verdict already rests on 6.3. Section 6.4 says the toolchain self-audit makes the check a MUST for a shipped toolchain, but the fixture does not describe one, and that would be a separate verdict under section 9.\n\n## 4. Confusion\n\n- **8.1:** \"a [Detector] that declares a version and has learnt … that it fails a MUST in sections 4 to 7 MUST record that gap alongside that version.\" This is a MUST in section 8, while section 8 defines conformance by the MUSTs in sections 4 to 7 and makes the declaration optional. I could not tell whether a recorded gap bears on the verdict.\n- **8.1:** \"by anyone who exercises the clauses above against it.\" I could not tell whether \"the clauses above\" means sections 4 to 7 or the clauses earlier in section 8.","ttft_ms":40979,"type":"result","duration_ms":47429,"uuid":"e7045f8f-31bd-48cc-9933-7889e73a98dc","ttft_stream_ms":1081,"time_to_request_ms":317,"first_content_frame_ms":1082,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":38790,"stop_reason":"end_turn","session_id":"32800d3e-7fed-4793-abd4-2733fae23139","total_cost_usd":0.0070271299999999995,"usage":{"input_tokens":2,"cache_creation_input_tokens":11207,"cache_read_input_tokens":2153,"output_tokens":9528,"output_tokens_details":{"thinking_tokens":7744},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11207,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":9528,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11207,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11207},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":9528,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11207,"webSearchRequests":0,"costUSD":0.0070271299999999995,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":7744,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, registered to run with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and reports whether it fired (4.2).\n- Each rule's identifier must be stable, not derived from file path, class name or position, and printed unaltered with every finding (4.3).\n- It must run locally with no infrastructure, on a subset such as a single file, and put results in the invoked command's output. No finding may be reportable only through a hosted service, licence tier or CI-only mode (5.1 to 5.4).\n- A printed identifier must resolve to its documentation. For bundled rules, the identifier alone must resolve, from the installed copy, offline, with every identifier the rule can print documented (6.1 to 6.3).\n- Any inline suppression route must be either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document can still conform, but it is graded on evidence and not on any declaration.\n\n> \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\"\n\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence by anyone who exercises the clauses above against it, and a verdict on any [Detector], declared or not, rests on that exercise and not on the claim.\"\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Doing either one is enough. Requiring a written reason is only a SHOULD (7.2), so it is not needed for conformance.\n\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a mechanical check the [Detector] documents.\"\n\n**2c.** The documentation for a bundled rule's identifier must ship with the rule, at a version tracked together with it, and must be resolvable from the installed copy without network access.\n\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\"\n\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Projects write a Zig module implementing `Rule` and list it in `lintomatic.toml`; project rules are \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, with exit codes 1, 0 and 2. The fixture does not explicitly say the output is limited to that rule, but \"runs a single rule\" supports it. |\n| 4.3 | Yes | Bundled identifiers are fixed at first release, and project names come from configuration and are not rewritten. Printed output shows them. The fixture names no other machine-readable format, and it does not say whether the HTML report carries identifiers. |\n| 5.1 | Yes | \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | Every finding in the one-line stdout form has its location and identifier. The HTML report only adds a snippet, so no remainder is left out. |\n| 5.4 | Yes | The hosted dashboard is extra, and \"every finding it shows is also printed by the command line.\" The same binary runs in CI. |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier as printed, for bundled and project rules alike. |\n| 6.2 | Yes | It prints \"from the installed package\"; \"there is no separate website.\" |\n| 6.3 | **No** | Two of the forty bundled rules print \"No documentation declared.\" The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | The `// lintomatic-ignore` comment can be disabled with `ignore_comments = false`. |\n\n**Conformance under section 8: No.** Clause 6.3 is a MUST and fails, so Lintomatic does not conform. The fixture describes no 8.1 declaration, which does not change this, since the declaration is optional.\n\n**Effect of 6.4: none on the verdict.** 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture also says Lintomatic's CI does not check that every identifier has an `explain` entry, so 6.4 is not met in practice. That gap is why the 6.3 failure went unnoticed, but the 6.3 failure stands on its own. The toolchain requirement that would make 6.4 a MUST does not apply, since the fixture does not describe a toolchain.\n\nTwo non-MUST clauses are also relevant. 7.2 is a SHOULD and is not met, since the comment \"takes no reason.\" 4.4 is a SHOULD, and the fixture does not mention a rule that enforces 4.3.\n\n## 4. Confusion\n\n- 4.3: \"in its default output and in every machine-readable format it offers.\" The document does not define \"machine-readable,\" so I could not tell whether the HTML report is one.","ttft_ms":33021,"type":"result","duration_ms":39076,"uuid":"9acd70ce-3f77-468c-a9bf-6c955c1e7b3e","ttft_stream_ms":983,"time_to_request_ms":285,"first_content_frame_ms":983,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":54652,"stop_reason":"end_turn","session_id":"914d4f6f-ba34-48a1-ac36-4fada605ee19","total_cost_usd":0.00889893,"usage":{"input_tokens":2,"cache_creation_input_tokens":11206,"cache_read_input_tokens":2153,"output_tokens":13272,"output_tokens_details":{"thinking_tokens":11263},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11206,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13272,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11206,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11206},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13272,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11206,"webSearchRequests":0,"costUSD":0.00889893,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11263,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, registered to run with the same standing as bundled rules (4.1).\n- It must offer a harness that runs one rule against supplied code and shows whether it fired and what it printed (4.2).\n- Each rule carries a stable identifier, chosen once by its author and not derived from path, class name, or position. The detector prints it unaltered with every finding (4.3).\n- It must run locally with no infrastructure, on a subset down to a single file, and put findings in the command's own output. No finding may be reportable only through a hosted, licence-tier, or CI-only route (5.1–5.4).\n- A printed identifier must resolve to documentation. For bundled rules the lookup works from the installed copy, offline, and every printable identifier must have a page (6.1–6.3).\n- An inline suppression route must be switchable off or detectable. Making it detectable is enough (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document, and unaware of it, can conform. Its maintainer's declaration is optional and is not a condition of conformance.\n\n> \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\" (8)\n\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence by anyone who exercises the clauses above against it\" (8.1)\n\n> \"It is how a maintainer claims [Conformance]; it is not a condition of it.\" (8.1)\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Doing one of those is enough.\n\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable\" (7.1)\n\nDetectability by a bespoke rule works only if the detector's rules can see comments. Without that, the mechanical-check route is the one left.\n\n**2c.** The documentation must ship inside the installed package, at a version tracked with the rule. It must be reachable with no network access.\n\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together\" (6.3)\n\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (6.2)\n\nEvery identifier the rule can print must resolve to a page in that shipped documentation (6.3).\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are written as a Zig module implementing `Rule`, listed in `lintomatic.toml`, and are \"first class in every report\", which matches \"the same standing as a Bundled rule\". |\n| 4.2 | Yes | `check --only <identifier> <path>` \"runs a single rule\" for \"any rule name, bundled or project\" and exits 1 on fire. The fixture does not state what `--only` prints, so I read \"what it printed\" as the one-line form that `check` prints. |\n| 4.3 | Yes | Bundled identifiers are \"fixed at the rule's first release\", and \"Lintomatic does not add or rewrite any part of the name\" for project rules. The one-line output prints the identifier. The fixture describes no machine-readable format, and the HTML report is not described as machine-readable or as carrying identifiers, so the \"every machine-readable format\" limb is not engaged. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file\". |\n| 5.3 | Yes | The one-line stdout form gives location, identifier and summary for every finding, and is \"printed whether or not the HTML report is enabled\". Nothing remains in the HTML that stdout omits. |\n| 5.4 | Yes | Local execution, and \"the same binary is what CI runs\". The hosted dashboard shows only findings that \"are also printed by the command line\". |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the identifier as printed. It covers bundled rules from the installed package and project rules through their declared `doc` string. |\n| 6.2 | Yes | Documentation comes \"from the installed package\", and \"there is no separate website.\" |\n| 6.3 | No | \"two of the forty rules currently print `No documentation declared`.\" Those are bundled rules, so two shipped identifiers resolve to no page. Under 6.3, \"One Identifier that does not resolve fails this clause, however many others do.\" The mechanism itself is present, so 6.1 is not failed. |\n\n**Conformance:** Lintomatic does not conform. Every other MUST in sections 4 to 7 is met, but 6.3 is not, and section 8 requires every MUST. Partial conformance cannot be described as conformance.\n\n**Effect of 6.4:** No, it does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture says CI runs `check src` but \"does not check that every `LM-NNNN` identifier has an `explain` entry\", so the release check that 6.4 describes is absent. That is the gap that let the 6.3 failure through. The fixture does not say Lintomatic ships inside a Toolchain, so 6.4 stays a SHOULD for this detector.\n\nTwo other SHOULD clauses are also unmet on the fixture's text, though they do not affect the verdict. The comment \"takes no reason\" (7.2). The fixture does not mention a self-enforcing rule for 4.3 (4.4).\n\n## 4. Confusion\n\n- 6.1: \"A documentation path printed in the [Message] is therefore not enough on its own.\" \"Message\" is not defined in this document, and I had only this document, so I could not be certain what it refers to.\n- 8.1: \"MAY be graded [Conforming] on evidence by anyone who exercises the clauses above against it.\" I could not tell whether the MAY gives the grader permission to award conformance or only says such a verdict is possible.","ttft_ms":48957,"type":"result","duration_ms":54974,"uuid":"a741d9ab-fd31-4b3d-a54d-1bf3f7a6dcc9","ttft_stream_ms":1026,"time_to_request_ms":319,"first_content_frame_ms":1027,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 060: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

The exact prompt every reader received, part 1 of 1

===== FILE: QUESTIONS.md =====
# Questions for a cold reader of DETECTOR-SPEC.md

You have been given `DETECTOR-SPEC.md` and the fixture `fixtures/lintomatic.md`, and nothing
else. Read the document once, then answer every question below in order. Quote the document
where a question asks for a quotation. Do not consult anything outside what you were given.

## 1. Restatement

In your own words and in at most six bullets, what does this document require of a detector?

## 2. Load-bearing statements

Answer each part of each question in a sentence or two, then quote the sentence or sentences of
the document you are relying on.

- 2a. What does it mean for a detector to conform, and can a detector that was written before
  this document existed, and has never heard of it, conform?
- 2b. A detector ships an inline ignore comment. What must the detector do about that route for
  it to conform, and is doing one of those things enough?
- 2c. Where must the documentation for a bundled rule's identifier live, at what version, and
  must it be reachable without network access?

## 3. Application

Grade Lintomatic 4.2, as described in the fixture, against every MUST clause in sections [4](../../DETECTOR-SPEC.md#4-authoring-rules) to [7](../../DETECTOR-SPEC.md#7-suppression):
[4.1](../../DETECTOR-SPEC.md#41-the-detector-must-support-bespoke-rules-written-by-the-project-that-runs-it), [4.2](../../DETECTOR-SPEC.md#42-the-detector-must-provide-a-harness-that-runs-a-single-rule-against-supplied-code), [4.3](../../DETECTOR-SPEC.md#43-the-detector-must-allow-a-rule-to-carry-a-stable-identifier-and-must-print-it-with-every-finding), [5.1](../../DETECTOR-SPEC.md#51-the-detector-must-be-invocable-by-the-practitioner-locally-with-no-infrastructure), [5.2](../../DETECTOR-SPEC.md#52-the-detector-must-support-invocation-over-a-subset-at-minimum-a-single-file), [5.3](../../DETECTOR-SPEC.md#53-the-result-must-reach-the-practitioner-in-the-output-of-the-command-they-ran), [5.4](../../DETECTOR-SPEC.md#54-a-finding-must-not-be-reportable-only-through-a-hosted-service-licence-tier-or-ci-only-mode-the-practitioner-cannot-invoke-locally), [6.1](../../DETECTOR-SPEC.md#61-the-detector-must-provide-a-mechanism-that-resolves-a-printed-identifier-to-its-documentation), [6.2](../../DETECTOR-SPEC.md#62-resolution-of-a-bundled-rules-identifier-must-work-from-the-installed-copy-without-network-access), [6.3](../../DETECTOR-SPEC.md#63-a-bundled-rules-documentation-must-ship-with-the-rule-at-a-version-tracked-together), [7.1](../../DETECTOR-SPEC.md#71-a-detector-may-offer-an-inline-suppression-route-but-must-make-it-detectable-or-disableable). For each give Yes, Partial or No and one
line of reasoning. Then state whether Lintomatic conforms under section [8](../../DETECTOR-SPEC.md#8-conformance), and why. Finally,
state whether clause [6.4](../../DETECTOR-SPEC.md#64-the-detector-should-fail-its-own-release-if-a-bundled-rule-lacks-resolvable-documentation) changes the verdict, and why.

## 4. Confusion

Quote any passage you found confusing on your one reading, with its clause number. Do not say what
would make it clearer and do not propose any change. Write "none" if there was none.

===== FILE: DETECTOR-SPEC.md =====
# Defence Before Fix: Detector Specification

**Version**: 1.0.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the toolchain specification](TOOLING-SPEC.md), version 0.2.0
**Author**: [Joseph Edmonds](https://ltscommerce.dev), [Edmonds Commerce](https://edmondscommerce.co.uk)
**Coined**: 22 February 2026, in [the original article](https://ltscommerce.dev/articles/defence-before-fix-static-analysis)

## 1. What this document is for

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are to be interpreted as
described in RFC 2119.

[The method specification](SPEC.md) states what a [Practitioner] does when a
[Defect] is found. This document states what a [Detector] must offer so that they
can do it: write a [Rule], prove it, run it and resolve what it prints. It is addressed to
whoever maintains a [Detector], which the method specification defines as a tool that reads
code without executing it and reports occurrences of a pattern.

A [Detector] is one part of a project's [Toolchain], and this document judges it
on what it offers alone. What the assembled [Toolchain] of a project must add on top, the
[Project record], the listing of active [Defences] and the
governance of [Suppression], is stated in [the toolchain specification](TOOLING-SPEC.md).
The two are separable because they are built by different people: a [Detector] is authored once
and installed into projects its maintainer will never see, whilst governance is decided by each
project for itself. A document that asked a [Detector] to enforce a project's governance would
fail every [Detector] in use and would not make any project better governed.

**The governing principle**: where the method specification requires a [Practitioner] to do
something with a [Rule], a [Conforming] [Detector] MUST make that possible
without the project building the mechanism first. A [Detector] that leaves the project to
construct the means has moved the obligation rather than met it.

## 2. Terminology

Terms from the method specification carry over unchanged. Every capitalised term links to its
definition; the ones this document leans on most are, in short:

| Term           | In one line                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| [Detector]     | A tool that reads code without executing it and reports what it finds          |
| [Rule]         | One check a [Detector] evaluates                                               |
| [Identifier]   | The stable name printed with a finding that leads to its documentation         |
| [Practitioner] | Whoever is doing the work, a person or an [Agent]                              |
| [Toolchain]    | Everything a project assembles to run its checks through, [Detectors] included |
| [Suppression]  | Making a finding go away without fixing it                                     |
| [Baseline]     | A recorded set of existing findings a [Rule] is told to ignore                 |

These are additional.

#### Rule author

Whoever writes a [Rule]. May be the [Detector]'s maintainer, a [Toolchain]'s maintainer or the project that runs it.

#### Bundled rule

A [Rule] the [Detector] ships, or fetches on the [Practitioner]'s behalf from a source the [Detector]'s maintainer controls. Its [Rule author] will never see the codebases it runs in, so everything a [Practitioner] needs in order to act on it has to travel with it.

#### Harness

The route by which one [Rule] is run against supplied code and its findings observed, without the project's own test suite and without every other [Rule] running alongside it.

The distinction between a [Bundled rule] and a project's own [Rule] matters throughout.
The [Detector] owns the documentation of the first and can be held to shipping it; it cannot
know the documentation of the second, and what it owes there is the mechanism that lets the project
attach its own.

## 3. The division of responsibility

Each mechanism the method needs has two halves. Stating only one of them is what produces a
[Detector] that is *nearly* usable.

| Requirement                          | The [Detector] MUST provide                             | The [Rule author] supplies                              |
| ------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------- |
| Bespoke [Rules]                      | The authoring and registration route                    | The [Rules]                                             |
| The red proof                        | A [Harness]                                             | The [Fixture] and the red run                           |
| Running the [Rule]                   | A local invocation, including subsets                   | Running it                                              |
| The [Identifier]                     | A place to carry it, and printing it with every finding | Choosing it once                                        |
| Resolution of a [Bundled rule]       | The lookup, and the documentation, on disk              | Nothing                                                 |
| Resolution of a project's own [Rule] | The [Identifier] printed unaltered                      | The documentation and, with the [Toolchain], the lookup |
| Inline [Suppression]                 | A route the project can detect or disable               | The decision whether to forbid it                       |

Read down the middle column and the shape of a [Conforming] [Detector] is already
visible. Read across any row and the failure mode is visible too: either half alone leaves the
[Practitioner] stuck.

## 4. Authoring rules

### 4.1 The detector MUST support bespoke rules written by the project that runs it

Configuration of an existing [Rule] set is not sufficient. The project must be able to express a
pattern the [Detector]'s authors have never anticipated, and register it so that it runs with
the same standing as a [Bundled rule].

**Why**: the method turns a specific [Defect] into a [Class] [Defence], and the
[Classes] that matter most to a project are the ones peculiar to it. A [Detector] offering
only a fixed catalogue can defend against the industry's known [Hazards] and none of the
project's own, which is the half that carries its institutional knowledge.

### 4.2 The detector MUST provide a harness that runs a single rule against supplied code

A [Harness] reports, for a given input, whether the [Rule] fired and what it printed, without
executing the project's own test suite and without the other [Rules] obscuring the answer.
This applies to every [Rule] the [Detector] runs, bundled or bespoke; a
[Detector] failing 4.1 is graded here on its [Bundled rules].

**Why**: clause 3.3 of the method specification requires the [Rule] to be proven by making it go
red. A [Practitioner] who can only observe a [Rule]'s behaviour by running every
[Rule] over the whole codebase cannot demonstrate that a [Rule] fires on the pattern rather
than on something incidental.

### 4.3 The detector MUST allow a rule to carry a stable identifier, and MUST print it with every finding

The [Identifier] MUST be stable across releases and MUST NOT be derived from the [Rule]'s
file path, [Class] name or position in a configuration file. The [Rule author] chooses it
once. The [Detector] MUST print it, unaltered, alongside every finding the [Rule]
reports, in its default output and in every machine-readable format it offers. A prefix the
[Detector] adds from the invoking directory or the [Rule]'s location is derived from
the file path. A namespace the [Rule author] assigns once in configuration is not.

| [Identifier]       | Where it comes from                                                         | Stable? |
| ------------------ | --------------------------------------------------------------------------- | ------- |
| `proj.no-raw-sql`  | Written once by the [Rule author] in configuration, printed as is           | Yes     |
| `LM-0107`          | Assigned once by the [Detector]'s maintainer at the [Rule]'s first release  | Yes     |
| `rules/no-raw-sql` | Produced from where the [Rule]'s file sits; changes when the file moves     | No      |
| `NoRawSqlRule`     | The [Rule]'s [Class] name; changes when the [Rule] is renamed               | No      |
| `rule 7`           | The [Rule]'s position in a configuration file; changes when one is inserted | No      |

**Why**: the [Identifier] is the only string that reaches the [Practitioner] and the
only key their lookup can use. An [Identifier] that changes when a [Rule] is renamed
silently breaks every reference to it, including references written down by people who have left.
An [Identifier] the [Detector] carries but does not print is one the
[Practitioner] was never given.

### 4.4 The detector SHOULD enforce 4.3 with a rule of its own

A [Rule] over the [Rules], failing any [Rule] that reports without a stable
[Identifier].

**Why**: this is the method applied to the [Detector] itself, and it is cheap. The worked
example is `php-qa-ci`'s `RequireRuleIdentifierConstantRule`, a [Rule] hosted in PHPStan by a
[Toolchain] built on it: it rejects a magic-string [Identifier] and names the
constant to declare instead. Nothing about it needed to live outside the [Detector].

## 5. Reporting

### 5.1 The detector MUST be invocable by the practitioner, locally, with no infrastructure

**Why**: method specification clause 8.1. An [Agent] that cannot check its own work cannot
iterate against a [Defence], so the loop never closes in the turn where it is cheap to close.

### 5.2 The detector MUST support invocation over a subset, at minimum a single file

**Why**: 5.1 is satisfied in principle by a whole-codebase run and defeated in practice by one.
Checking a single edited file has to be fast enough to do on every edit, or it will not be done on
any.

### 5.3 The result MUST reach the practitioner in the output of the command they ran

Where the [Detector] writes fuller detail elsewhere, the invoked command's own output MUST
carry both a usable summary and the location of the remainder. The remainder is the findings
the summary leaves out. Where the output prints every finding, each with where it is and its
[Identifier], there is no remainder, and a report that only adds detail to those same findings,
such as a code snippet, need not be named in the output.

**Why**: method specification clause 8.2. A report the [Practitioner] has to go and find is a
report that arrives after the decision it was meant to inform.

### 5.4 A finding MUST NOT be reportable only through a hosted service, licence tier or CI-only mode the practitioner cannot invoke locally

A finding that the [Detector] reports only through a hosted service, a licence tier or a
continuous-integration-only mode the [Practitioner] cannot invoke locally does not
[Conform], whatever the same [Rule] reports there.

**Why**: a [Rule] that fires only in an environment the [Practitioner] has no access to
teaches nobody anything and blocks them anyway, which is the worst combination available.

## 6. Resolving an identifier

### 6.1 The detector MUST provide a mechanism that resolves a printed identifier to its documentation

Two cases, by who wrote the [Rule]:

| The [Rule]        | Who supplies the documentation | What this clause asks of the [Detector]                                   |
| ----------------- | ------------------------------ | ------------------------------------------------------------------------- |
| A [Bundled rule]  | The [Detector]                 | Resolve the [Identifier], presented alone, to that documentation          |
| The project's own | The project                    | Print the [Identifier] unaltered; the lookup is the [Toolchain]'s to give |

In both, the mechanism is keyed on **the [Identifier] exactly as printed**. A command, an index
file or a URL are all acceptable forms. This clause asks for the mechanism, not for every page:
where the mechanism works but a [Bundled rule]'s [Identifier] has no documentation to resolve
to, that fails clause 6.3, not this clause. Each case in turn:

**For a [Bundled rule]**, the [Detector] supplies the documentation and the
lookup, and clauses 6.2 and 6.3 say where. The mechanism MUST resolve an [Identifier]
presented alone, because the reader who needs it most has the [Identifier] from a log, a
ticket or a colleague and not the [Message]. A documentation path printed in the [Message] is
therefore not enough on its own: it helps only a reader who has the [Message], and the
[Identifier] alone still leads nowhere.

**For a project's own [Rule]**, the [Detector] cannot know the documentation, so what
it owes is the half it can give: the [Identifier] printed unaltered under clause 4.3, and no
transformation of it. Where the [Identifier] is itself a URL, as method clause 3.6 allows,
the [Detector] prints that URL and has done what this clause asks. What this clause forbids is
a documentation path printed alongside a shorter [Identifier] that cannot be looked up on its
own. The lookup for such
a [Rule] is an obligation on the project's assembled [Toolchain], under clause 4.2
of the [toolchain specification](TOOLING-SPEC.md), and a [Detector] that offers it as well has
gone further than this clause asks.

**Why**: method specification clause 8.3 requires the [Identifier] to resolve without a human.
An index keyed on anything else does not resolve it. This is the most commonly failed clause in this
document and it fails in a specific way: documentation exists, is genuinely good, and is keyed on the
[Rule]'s [Class] or file name, which is a string the [Practitioner] was never
given. The lookup they can actually perform is the only one that counts.

### 6.2 Resolution of a bundled rule's identifier MUST work from the installed copy, without network access

**Why**: an [Agent] working offline, behind a proxy, or against a URL that has since moved needs
the answer to be on disk. A dependency the project already installed is on disk by definition. A
catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong
place.

### 6.3 A bundled rule's documentation MUST ship with the rule, at a version tracked together

Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1,
to a page in that shipped documentation. One [Identifier] that does not resolve fails this
clause, however many others do. A page per [Identifier] satisfies this; a page per family of
[Identifiers] MAY be used instead, under clause 6.5.

**Why**: method specification clause 3.6. A [Bundled rule] travels into codebases its author
will never see. If its documentation lives only in the [Detector]'s repository or on its
website, then every project that installs it is one link rot away from a [Rule] that blocks
without explaining.

The failure to guard against is not the absent document but the **dangling one**: a reference to
documentation that was planned and never written is worse than no reference, because it consumes
the [Practitioner]'s attention before failing them.

### 6.4 The detector SHOULD fail its own release if a bundled rule lacks resolvable documentation

An automated check over every [Identifier] a [Bundled rule] can print, applying the
family list or pattern of clause 6.5 where one is used, that blocks the release when any of them
lands on no page.

**Why**: clause 6.3 is the clause most easily believed to be satisfied whilst being broken, because
the documentation is written by the same person who wrote the [Rule] and its absence is
invisible from the inside. Where the [Detector] is shipped inside a [Toolchain],
the [toolchain specification](TOOLING-SPEC.md)'s self-audit makes this check a MUST for the [Toolchain]; a
[Detector] released on its own is asked for it as a SHOULD because the same [Class] of
[Defect], a [Rule] that blocks without explaining, is detectable mechanically there too.

### 6.5 One page MAY document a family of identifiers, and SHOULD name its members so a check can confirm them

Where several [Bundled rules] share a prefix, one page MAY document them all. Such a page
SHOULD let the check clause 6.4 asks for confirm that each member resolves to it. Two forms do
that and one does not:

| The page                                                                                                  | A check can confirm each member?          |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Lists every full [Identifier] in the family, `LM-0100`, `LM-0101`, and so on                              | Yes                                       |
| Carries a regular expression the check can run, `^LM-01[0-9]{2}$`, matching every member and nothing else | Yes                                       |
| Says in prose that everything under `LM-01` is documented here                                            | No: a person can infer it, a check cannot |

The list or the regular expression lives in the installed file, since clause 6.2 requires
resolution to work from the installed copy, not only in a rendered web page.

**Why**: a family page is a convenience for the author, and the cost of it must not fall on the
check. A page that a person can see covers `LM-0107` but a check cannot leaves clause 6.4 with
nothing to run.

## 7. Suppression

### 7.1 A detector MAY offer an inline suppression route, but MUST make it detectable or disableable

An inline ignore comment, a per-line directive and a generated [Baseline] are all such
routes. The [Detector] MAY ship them. For each one it MUST do at least one of two things, and either
alone satisfies this clause: make the route disableable by configuration; or make the route
detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a
mechanical check the [Detector] documents. Either lets a project which decides to forbid the
route enforce that decision. A route that can be neither switched off nor seen does not [Conform].

A route is detectable when the project can find every use of it. The first way is a bespoke
[Rule]: the project registers a [Rule] of its own, as clause 4.1 provides for, that matches the
route wherever it is used, and the [Detector] runs it like any other bespoke [Rule]; the
[Detector] ships no such [Rule] itself, and need not. That way is open only where the
[Detector]'s [Rules] can see the route: a [Detector] whose [Rules] never see comments cannot make
an ignore comment detectable this way. The second way is a mechanical check the [Detector]
documents, such as a text search for the route's spelling that the [Detector]'s documentation
gives.

**Why**: the method specification's position is that [Suppression] is an [Owner]
decision under its clause 3.4 and section 4, and an [Owner] cannot decide something they are
never shown. The [Detector] is not the [Owner] and does not know the project's
governance, so it is not asked to enforce it; what it is asked is not to hide the route. Every
[Detector] in wide use ships an inline ignore, and a clause that forbade them would fail all of
them without governing any project better. Whether the route is forbidden is the project's decision,
enforced through its [Toolchain] under clause 4.3 of the [toolchain specification](TOOLING-SPEC.md).

### 7.2 An inline suppression route SHOULD require a written reason

The [Detector] SHOULD reject, or be configurable to reject, an inline [Suppression]
that carries no reason, and SHOULD NOT supply a default one, including each entry of a generated
[Baseline].

**Why**: a [Suppression] without a reason is indistinguishable from one nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence costs the author a
minute at the moment they have the reason in mind, and it is the only thing that makes the
[Suppression] reviewable later. PHPStan's `reportIgnoresWithoutComments` is the shape of it.

## 8. Conformance

**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Detector]
that satisfies most of this document is in a normal and respectable condition; it is not
[Conforming], and describing it as such removes the only value the word has.

This document defines one level. The clauses of the method specification's section 8 that reach
beyond what sections 4 to 7 here already secure, the listing of active [Defences] and the
summary for an [Agent]'s context, are obligations on a project's assembled [Toolchain]
and are stated in the [toolchain specification](TOOLING-SPEC.md), so there is no separate [Agent]-support level
for a [Detector].

### 8.1 A maintainer MAY declare the version of this document the detector conforms to, and the declaration records known gaps

The declaration is machine-readable, in whatever form the [Detector]'s ecosystem uses to
record dependencies. The same declaration is where a gap against this document is recorded once it is
known: a [Detector] that declares a version and has learnt, from its own checks or from a
[Practitioner]'s report under the method's clause 3.2, that it fails a MUST in sections 4 to 7
MUST record that gap alongside that version, in the same file or one it names. A declaration
with a non-empty gap record is a statement of where the [Detector] stands and is not a claim of
[Conformance].

The declaration is optional, and so the duty above falls only on a [Detector] that has one; a
gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case. It is how a
maintainer claims [Conformance]; it is not a condition of it. A [Detector] that predates this document, or whose maintainer has never read
it, MAY be graded [Conforming] on evidence by anyone who exercises the clauses above against
it, and a verdict on any [Detector], declared or not, rests on that exercise and not on the
claim. A declaration tells the reader what the maintainer believes and what they know to be missing;
the reader still runs the [Harness].

The shape is illustrative rather than prescribed. In a Composer manifest:

```json
"extra": {
  "defence-before-fix": {
    "method": "1.0.1",
    "detector": "1.0.0",
    "toolchain": null,
    "known-gaps": []
  }
}
```

In a package.json, the equivalent is a top-level `defenceBeforeFix` object with the same keys. A
[Detector] that is not also shipped as a [Toolchain] leaves `toolchain` empty;
a project that ships both declares both. Each entry in `known-gaps` names the clause and states the
gap in a sentence.

**Why**: a [Conformance] claim in a README is a sentence; a claim in a manifest is a fact about
a specific installed artefact, checkable by anyone, including mechanically, and it fixes what
"[Conforming]" meant at the point the claim was made. Making the claim a condition of
[Conformance], though, would mean a [Detector] with every mechanism in place could
never [Conform] until its maintainer had heard of this document, which grades the
maintainer's reading rather than the [Detector].

## 9. Relationship to the other specifications

This document adds no obligations to a [Practitioner] and relaxes none. Every clause here
exists to make a clause of the method specification achievable with a [Detector] in hand.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes one piece of the equipment.

The [toolchain specification](TOOLING-SPEC.md) states what a project's assembled [Toolchain] must offer beyond
what each [Detector] in it offers, and it requires every [Detector] a [Defence]
is routed through to [Conform] to this one. A [Detector] shipped inside a
[Toolchain] is measured here as a [Detector] and there as part of the
[Toolchain]; the two verdicts are separate and neither implies the other.

Nothing here requires a project to use a [Conforming] [Detector]. A project can
[Conform] to the method specification on a [Detector] that [Conforms] to
none of this, at the cost of building the missing mechanisms itself. This document exists so that it
does not have to.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[bundled rule]: #bundled-rule
[bundled rules]: #bundled-rule
[class]: SPEC.md#class
[classes]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[fixture]: SPEC.md#fixture
[harness]: #harness
[hazards]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[project record]: TOOLING-SPEC.md#project-record
[rule]: SPEC.md#rule
[rule author]: #rule-author
[rules]: SPEC.md#rule
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain

===== FILE: fixtures/lintomatic.md =====
# Fixture: Lintomatic 4.2

A fictional detector, described only as far as its documentation would describe it. Grade it
against the document you were given. Where the description does not say, answer from what is
written, not from what a real tool would probably do.

## What the documentation says

Lintomatic is a static analyser for the Zig language. It ships forty rules. A project can add its
own rules by writing a Zig module that implements the `Rule` interface and listing it in
`lintomatic.toml`; project rules are loaded on every run and are first class in every report.

The command `lintomatic check <path>` analyses a directory or a single file and prints one line
per finding to standard output:

```
src/db.zig:41:7  LM-0107  Result of fallible call discarded
src/db.zig:88:3  proj.no-raw-sql  Query built by string concatenation
```

Fuller detail, including a snippet, is written to `.lintomatic/report.html`. The one-line form is
printed whether or not the HTML report is enabled.

`lintomatic check --only <identifier> <path>` runs a single rule. It accepts any rule name,
bundled or project, and exits 1 when the rule fires, 0 when it does not, and 2 when the rule name
is unknown.

Rule identifiers for bundled rules are of the form `LM-NNNN` and are fixed at the rule's first
release. Project rules are identified by the name the project gives them in `lintomatic.toml`,
which the documentation recommends prefixing with `proj.`; Lintomatic does not add or rewrite
any part of the name.

`lintomatic explain <identifier>` prints the documentation for a bundled rule from the installed
package: what the rule finds, why, and the recommended construction. For a project rule it prints
the `doc` string the rule module declares, or `No documentation declared` when there is none.
The documentation is versioned with the package; there is no separate website.

Lintomatic honours the comment `// lintomatic-ignore <identifier>` on the line before a finding.
The comment can be disabled project-wide with `ignore_comments = false` in `lintomatic.toml`.
The comment takes no reason and the documentation does not mention one.

The tool runs locally with no account, no server and no network, and the same binary is what CI
runs. There is a hosted dashboard, sold separately, that aggregates reports across repositories;
every finding it shows is also printed by the command line.

Lintomatic's own repository runs `lintomatic check src` in CI but does not check that every
`LM-NNNN` identifier has an `explain` entry; two of the forty rules currently print
`No documentation declared`.

[LTSCommerce]

Run 063: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Command and working directory

ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt, each reader in a fresh empty directory made by mktemp -d outside the repository

Model version each reader reported

reader 1: claude-haiku-5-5
reader 2: claude-haiku-5-5
reader 3: claude-haiku-5-5
reader 4: claude-haiku-5-5
reader 5: claude-haiku-5-5

The delegated marker's task prompt

MODE: mark

Worktree: <worktree> (branch `editor/detector-route-rule`). The readers read commit 4cbecad. Read, at that commit and in that worktree: ACCEPTANCE.md in full (it is the process as pull request 22 proposes it, merged into this branch; the run is made under that process change before it merges, at commit 4081aa4, named here before the readers started), acceptance/runs/README.md, acceptance/detector/QUESTIONS.md, acceptance/detector/KEY.md, acceptance/fixtures/lintomatic.md and DETECTOR-SPEC.md. You may read acceptance/runs/060-detector-route-rule-run-1.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 063. Document: DETECTOR-SPEC.md. Change: detector route rule (clause 7.1's detectable route is a bespoke rule the project writes for the detector under clause 4.1, with a paragraph on what detectable means; clause 8.1's gap duty falls only on a detector that declares a version; clause 5.3 says what the remainder is; clause 6.1 says it asks for the mechanism, a missing page failing 6.3, and that a path in the message is not enough on its own), revised after run 60 in section 2's table (a Message row) and clause 8.1's second paragraph. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 2 (run 60 came before). Record file to write: <worktree>/acceptance/runs/063-detector-route-rule-run-2.md. Do not commit it.

Sheets: <run-dir>/sheet-1.md to sheet-5.md, each the `result` of reader-N.json. Prompt the readers received: <run-dir>/prompt.txt; its sha256 is 30b41f341b26e48b3c8bf1b1d55a25283ffd43c835328eaf5cd9ec021d265e09, and it is byte for byte the question set, DETECTOR-SPEC.md and the fixture at 4cbecad, each after one `===== FILE: <name> =====` line, one blank line between files. Model: every reader reported claude-haiku-5-5 (<run-dir>/models.txt); the cohort's model named for the run is claude-haiku-5-5. Every reader's JSON has is_error false and subtype success; no reader is set aside.

Facts the editor supplies for the record: cohort of five readers, none reused from any earlier run; each a separate `claude -p` process started through the `ccy-claude` wrapper (which only reattaches the session's credential) in a fresh empty directory made by `mktemp -d` outside any repository, with the packet on standard input, command `ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt`; no tools, no settings, no project context, no saved session; the machine applies no managed settings; the editor attests the rest of the isolation. Marked by a delegated marker, a fresh `dbf-spec-editor` agent (Claude Opus) given this instruction and its agent definition, having seen neither the drafting nor the review.

Text the change wrote or altered, for "Where a finding lies": the output of `git -C <worktree> diff 9e914fe 4cbecad -- DETECTOR-SPEC.md` (9e914fe is the merge base with `next`). Run it and read it. A finding in a paragraph that diff adds, rewords, moves, deletes a sentence from, or changes a word, term or link in, or that a reader sets against such a paragraph, blocks; any other finding is routed to acceptance/ROUTED.md, and the record says so for each.

Mark every sheet, keyed item by keyed item, by ACCEPTANCE.md's Marking section and the key alone. Write the record stating what acceptance/runs/README.md lists, in its order, with the marks table, each miss with the reader's reasoning in brief, every passage named under question 4 with its words or description, clause and readers, each finding and where it lies, any open point and the direction you marked it, the process-change commit 4081aa4, the verdict, and a placeholder line for the link to the posted sheets. Reply with the verdict and the findings only, under thirty lines.

The agent definition the marker ran under

---
name: dbf-spec-editor
description: Drafts, reviews, key-updates, marks or records a change to the Defence Before Fix specification, one mode per dispatch, following the specification repository's CONTRIBUTING.md, SCOPE.md and ACCEPTANCE.md exactly. Dispatched by the dbf-spec-change skill; it cannot run a cohort itself.
tools: Read, Write, Edit, Grep, Glob, Bash
model: opus
---

You work on one change to the Defence Before Fix specification, in the worktree path you are
given. The process is defined by that repository's `CONTRIBUTING.md`, `SCOPE.md`,
`ACCEPTANCE.md` and `acceptance/README.md`; read the ones your mode needs, in full, before you
act. You invent no steps. You never merge, push to `next` or `main`, release, tag or publish,
and you never change a question, threshold or fixture. Your prompt names one mode.

Write as the specification is written: British spelling, no em dashes, defined terms linked as
`spec-qa.py` requires, every clause or section number linked to its heading. Commit on the
worktree's branch.

## MODE: draft

1. Read `SCOPE.md`, `DECLINED.md`, and every clause the change touches, with the terminology
   entries they use.
2. Decide the kind. A change to the sentences carrying MUST, SHOULD or MAY in a numbered section
   or appendix is an obligation; anything else is a clarity edit.
3. For an obligation, answer the five SCOPE tests in a sentence or two each, and name the
   section the obligation extends. If a test fails, or an existing clause already covers it, say
   so and stop without editing.
4. Make the smallest edit that does the job, in the clause that owns the subject.
5. Add one line under `Unreleased` in `CHANGELOG.md`, saying what changed and why, with a
   placeholder `run NNN`. Change no version.
6. If Appendix A changed, run `python3 build-agent-surfaces.py` and commit its outputs.
7. Run `python3 spec-qa.py` and `python3 -m unittest discover -s tools -p 'test_*.py'`; both
   clean.
8. Reply with: kind, SCOPE answers, files changed, commit, QA result, and a filled
   `.github/PULL_REQUEST_TEMPLATE.md` body. Under forty lines.

## MODE: review

You have not seen the drafting. Read the whole changed document and the diff against
`origin/next`. Report, numbered, with clause numbers: contradictions with other clauses, terms
used outside their definition, a sentence a reader could take two ways, an obligation an owner
could not verify from the record. Do not edit.

## MODE: keys

Read `acceptance/README.md` and the `KEY.md` for each changed document. Update every quotation of
a changed sentence to the new wording, verbatim, in a new commit; run `python3 spec-qa.py` until
`key-quote-stale` is gone. If the change adds a load-bearing obligation no keyed question
covers, propose the question and its key in your reply; add it only if your prompt says the owner
has decided to.

## MODE: mark

You have not seen the drafting or the review. Read `ACCEPTANCE.md` in full, the `KEY.md` for the
document, the document at the commit named, and the sheets under `<run-dir>/`.

- Mark each sheet against the key, keyed item by keyed item, by the rules under "Marking" in
  `ACCEPTANCE.md` and nothing else: the key's required elements, accepted grades, conditions and
  wrong readings. Invent no judgement; where neither the rules nor the key settles a mark, mark
  it in the direction the open-point rule gives and record the point.
- A single miss under questions 1 and 3 counts against the document only where the key names
  that reading; say which.
- For question 4, record every passage named, with its words or description and its clause.
  Group the passages by paragraph, count the readers, and for each finding say whether it lies in
  text the change wrote or altered, read against the diff the prompt gives you, or is routed to
  `acceptance/ROUTED.md`. Ignore any suggestion a reader volunteers.
- Apply the pass criteria exactly.
- Write `acceptance/runs/NNN-<slug>-run-<k>.md` stating what `acceptance/runs/README.md` lists,
  in its order. Do not commit it. Reply with the verdict and the findings only.

## MODE: record

Commit the run record, replace the `run NNN` placeholder in `Unreleased` with a link to it, and
for an obligation set the document header to `<next version>-dev, unpublished` in the same
commit if it still names a published version. Run `python3 spec-qa.py` and
`python3 tools/changes.py --base origin/next`; both clean. Reply with the commit.

[LTSCommerce]

Run 063: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Answer sheets, each reader's whole output as its process returned it

reader-1

{"duration_api_ms":43326,"stop_reason":"end_turn","session_id":"346253d3-f746-4477-bf57-436a8c2e29d2","total_cost_usd":0.007463929999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11241,"cache_read_input_tokens":2153,"output_tokens":10388,"output_tokens_details":{"thinking_tokens":8403},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11241,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":10388,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11241,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11241},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":10388,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11241,"webSearchRequests":0,"costUSD":0.007463929999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":8403,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project that runs it write its own rules, registered with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and shows whether it fired and what it printed (4.2).\n- Each rule carries a stable identifier chosen once and not derived from path, class name or position, printed unaltered with every finding (4.3).\n- It must run locally with no infrastructure, including over a single file, and must not report findings only through a hosted service, licence tier or CI-only mode (5.1 to 5.4).\n- A printed identifier must resolve to documentation: a bundled rule's documentation ships on disk with the installed rule, works offline, and covers every identifier it can print. A project's own identifiers are printed unaltered (6.1 to 6.3).\n- An inline suppression route must be either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document, and never checked against it, can still conform, because grading is by evidence and not by declaration.\n- \"A [Conforms] if it satisfies every MUST in sections 4 to 7.\" (8)\n- \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\" (8.1)\n- \"It is how a maintainer claims [Conformance]; it is not a condition of it.\" (8.1)\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Doing one of these is enough.\n- \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a mechanical check the [Detector] documents.\" (7.1)\n\nThe written-reason requirement in 7.2 is a SHOULD, so it does not affect conformance.\n\n**2c.** The documentation for a bundled rule's identifier must be in the installed package at the same version as the rule, and must be reachable without network access.\n- \"A [Bundled rule]'s documentation MUST ship with the rule, at a version tracked together.\" (6.3)\n- \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\" (6.3)\n- \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\" (6.2)\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are written as a Zig module implementing `Rule`, listed in `lintomatic.toml`, and are \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, exits 1 or 0 for fired or not, and as a form of `check` it prints findings. The fixture does not state the `--only` output explicitly. |\n| 4.3 | Yes | Bundled `LM-NNNN` identifiers are fixed at first release, project identifiers come from configuration, and \"Lintomatic does not add or rewrite any part of the name.\" The fixture names no machine-readable format, and it does not say whether the HTML report carries identifiers. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | Stdout prints one line per finding with location, identifier and message, so there is no remainder that the output fails to name. |\n| 5.4 | Yes | The dashboard is optional, \"every finding it shows is also printed by the command line,\" and CI runs the same local binary. |\n| 6.1 | Yes | `lintomatic explain <identifier>` resolves a bundled identifier from the identifier alone. The two undocumented rules are a 6.3 failure, not a 6.1 failure. |\n| 6.2 | Yes | \"The documentation is versioned with the package; there is no separate website,\" and `explain` reads from the installed package. |\n| 6.3 | No | Two of the forty bundled rules print `No documentation declared` and have no page, and \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `ignore_comments = false` in `lintomatic.toml` disables `// lintomatic-ignore`, so the route is disableable by configuration. |\n\n**Conformance:** Lintomatic does not conform. Section 8 requires every MUST in sections 4 to 7, and 6.3 fails. The fixture's own description (two rules with no documentation, so the detector is partially conforming) is the \"partial\" case that section 8 says must not be described as Conformance.\n\n**Clause 6.4:** No, it does not change the verdict. 6.4 is a SHOULD, so its absence is not a MUST failure, and section 8 counts only MUSTs. Even if Lintomatic's release did check for missing documentation, the verdict would still be No, because the check would block the release without adding the two missing pages. The toolchain's self-audit under the toolchain specification is a separate verdict, which section 9 keeps apart from this one.\n\n## 4. Confusion\n\n- 6.1: \"Where the [Identifier] is itself a URL, as method clause 3.6 allows, the [Detector] prints that URL and has done what this clause asks.\" The reference to method clause 3.6 points to a document I was not given, so I could not check what the URL case requires.\n- 5.3: \"a report that only adds detail to those same findings, such as a code snippet, need not be named in the output.\" I had to read this twice to work out whether the exemption applies to the HTML report.","ttft_ms":36336,"type":"result","duration_ms":43707,"uuid":"d8eb230c-62d7-45b5-85e8-32fa5ba9c795","ttft_stream_ms":1407,"time_to_request_ms":380,"first_content_frame_ms":1408,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":50507,"stop_reason":"end_turn","session_id":"92598fc9-5e64-4f3e-a3bd-ecc2fcec4f8c","total_cost_usd":0.008196829999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11238,"cache_read_input_tokens":2153,"output_tokens":11855,"output_tokens_details":{"thinking_tokens":9687},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11238,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11855,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11238,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11238},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11855,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11238,"webSearchRequests":0,"costUSD":0.008196829999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":9687,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, register them, and run them with the same standing as bundled rules (4.1).\n- It must offer a harness that runs one rule against supplied code and shows whether it fired and what it printed (4.2).\n- Each rule carries a stable identifier chosen by its author, not derived from its path, class name, or position, and the detector prints it unaltered with every finding (4.3).\n- The check must run locally with no infrastructure, on a subset such as one file (5.1, 5.2). Results must appear in the command's own output (5.3), and no finding may be reportable only through a hosted service, licence tier, or CI-only mode (5.4).\n- A printed identifier must resolve to its documentation. For bundled rules that means from the identifier alone, offline, from docs shipped with the installed version (6.1 to 6.3). For a project's own rules, the identifier is printed unaltered (6.1).\n- Any inline suppression route must be switchable off or detectable (7.1). Requiring a reason for it is a SHOULD (7.2).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document can conform, because conformance is judged by checking clauses, not by a declaration. \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence\" and \"It is how a maintainer claims [Conformance]; it is not a condition of it.\" The defining sentence is \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\"\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Doing either one is enough: \"For each one it MUST do at least one of two things, and either alone satisfies this clause.\" One caveat applies to the detectable option: \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\" So for an ignore comment, the configuration switch or a documented mechanical check is the route that remains.\n\n**2c.** The documentation must be reachable from the installed copy with no network access: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\" It must ship with the rule at a version tracked together: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" A catalogue on a website does not satisfy this: \"A catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong place.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | \"a Zig module that implements the `Rule` interface and listing it in `lintomatic.toml`; project rules are loaded on every run and are first class in every report.\" |\n| 4.2 | Yes | \"`lintomatic check --only <identifier> <path>` runs a single rule\" and exits 1 when it fires, 0 when it does not, and 2 when the name is unknown. The fixture does not say outright that `--only` prints the finding lines, so that part is inferred from the one-line output format of `check`. |\n| 4.3 | Yes, with a caveat | Bundled identifiers are \"fixed at the rule's first release\", and project identifiers are \"the name the project gives them\", with \"Lintomatic does not add or rewrite any part of the name.\" Default output prints them, as in `proj.no-raw-sql`. The fixture names no machine-readable format, and it does not say whether the HTML report prints identifiers, so the \"every machine-readable format\" limb is not shown. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | \"`lintomatic check <path>` analyses a directory or a single file.\" |\n| 5.3 | Yes | Each finding is printed as \"one line per finding to standard output\" with its location and identifier. That leaves no remainder, so the HTML detail need not be named in the output. |\n| 5.4 | Yes | The hosted dashboard is extra, and \"every finding it shows is also printed by the command line.\" \"The same binary is what CI runs.\" |\n| 6.1 | Yes | \"`lintomatic explain <identifier>` prints the documentation for a bundled rule\", and for project rules it prints the declared `doc` string or \"No documentation declared.\" |\n| 6.2 | Yes | \"prints the documentation for a bundled rule from the installed package… there is no separate website.\" |\n| 6.3 | **No** | \"Two of the forty rules currently print `No documentation declared`.\" Per the clause, \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | \"The comment can be disabled project-wide with `ignore_comments = false`.\" |\n\n**Conformance (section 8):** Lintomatic does not conform. Clause 6.3 is a MUST and fails on two bundled rules. Section 8 requires every MUST in sections 4 to 7 to be met, and \"Partial [Conformance] MUST NOT be described as [Conformance].\" The verdict would be the same even if every other clause were Yes.\n\nOutside the list you asked for, 7.2 (a SHOULD) is also unmet, since \"The comment takes no reason.\" That does not affect the verdict.\n\n**Effect of 6.4:** It does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture says Lintomatic's CI runs `lintomatic check src` but \"does not check that every `LM-NNNN` identifier has an `explain` entry,\" so the release does not fail on missing documentation. That is a SHOULD gap, and the verdict stays No. The document also says the toolchain and detector verdicts are separate: \"the two verdicts are separate and neither implies the other.\" Any obligation that 6.4 would make a MUST on a toolchain belongs to that toolchain's verdict, not to this one.\n\n## 4. Confusion\n\n- **5.3:** \"a report that only adds detail to those same findings, such as a code snippet, need not be named in the output.\" The sentence is parseable, but the subject of \"need not be named\" took me two readings to settle.\n- **4.3:** \"in its default output and in every machine-readable format it offers.\" The clause does not say what counts as machine-readable, so I could not tell whether the HTML report is covered.\n- **6.4:** \"the [toolchain specification]'s self-audit makes this check a MUST for the [Toolchain].\" This points to a document I was not given, so I could not check what it requires.","ttft_ms":42855,"type":"result","duration_ms":50898,"uuid":"71de8257-4207-47cd-b7e2-32ab8e4f6bc6","ttft_stream_ms":3143,"time_to_request_ms":389,"first_content_frame_ms":3145,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":49799,"stop_reason":"end_turn","session_id":"920f8653-ec34-419c-b6bd-b007c83317b6","total_cost_usd":0.00854573,"usage":{"input_tokens":2,"cache_creation_input_tokens":11240,"cache_read_input_tokens":2153,"output_tokens":12552,"output_tokens_details":{"thinking_tokens":10348},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11240,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12552,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11240,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11240},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12552,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11240,"webSearchRequests":0,"costUSD":0.00854573,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10348,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules and register them with the same standing as bundled rules (4.1).\n- It must offer a harness that runs a single rule, bundled or bespoke, against supplied code (4.2).\n- Each rule carries an identifier the rule author chooses once. It must be stable, not derived from path, class name or position, and printed unaltered with every finding (4.3). A self-check rule for this is a SHOULD (4.4).\n- It must run locally with no infrastructure, on a subset down to a single file, and its findings must appear in the output of the command the practitioner ran. No finding may be reportable only through a hosted service, licence tier or CI-only mode (5.1–5.4).\n- Every printed identifier must resolve to documentation. For bundled rules, that means from the installed copy, offline, with documentation shipped alongside the rule at the same version, and no identifier left without a page (6.1–6.3). For project rules, the identifier is printed unaltered (6.1).\n- Any inline suppression route must be disableable by configuration or detectable (7.1). A required written reason is a SHOULD (7.2).\n\n## 2. Load-bearing statements\n\nQuotes drop the document's link markup, so `[Detector]` appears as `Detector`.\n\n**2a.** Conformance means satisfying every MUST in sections 4 to 7. Yes, a detector written before the document can conform. Declaring conformance is optional and is not a condition of it.\n\n> \"A Detector Conforms if it satisfies every MUST in sections 4 to 7.\" (Section 8)\n\n> \"A Detector that predates this document, or whose maintainer has never read it, MAY be graded Conforming on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any Detector, declared or not, rests on that check and not on the claim.\" (8.1)\n\n> \"It is how a maintainer claims Conformance; it is not a condition of it.\" (8.1)\n\n**2b.** The detector must do at least one of two things: make the route disableable by configuration, or make it detectable. Doing one of those is enough.\n\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke Rule the project writes for the Detector under clause 4.1 or by a mechanical check the Detector documents.\" (7.1)\n\nThe detectable-by-rule route only works where the detector's rules can see comments, so it is not always open. Disabling by configuration has no such limit.\n\n**2c.** The documentation must live in the installed copy, shipped with the rule at a version tracked with it, and must be reachable without network access.\n\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\" (6.2)\n\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" (6.3)\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | \"A project can add its own rules by writing a Zig module that implements the `Rule` interface and listing it in `lintomatic.toml`; project rules … are first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` \"runs a single rule\", accepting bundled or project names, and exits 1 or 0 on whether it fired. |\n| 4.3 | Yes | Bundled identifiers are \"fixed at the rule's first release\"; project names come from configuration, and \"Lintomatic does not add or rewrite any part of the name.\" The one-line output prints the identifier. The fixture does not say whether the HTML report carries identifiers, but it is not described as machine-readable, so I did not count that against it. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line form is \"printed whether or not the HTML report is enabled.\" Each line gives location and identifier, so there is no remainder. The HTML adds only a snippet, which 5.3 says need not be named. |\n| 5.4 | Yes | \"every finding it shows is also printed by the command line,\" and \"the same binary is what CI runs.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the identifier as printed and takes no other input. The two undocumented bundled rules fail 6.3, not this clause. |\n| 6.2 | Yes | `explain` \"prints the documentation for a bundled rule from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | No | Two of the forty bundled rules \"print `No documentation declared`.\" The clause says \"One Identifier that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `ignore_comments = false` in `lintomatic.toml` disables the `// lintomatic-ignore` route project-wide. Disableability alone is enough. |\n\n**Conformance under section 8: No.** Clause 6.3 is a MUST in section 4 to 7 and fails. The fixture's own statement that two bundled rules print `No documentation declared` is the failure. Section 8 does not allow partial conformance to be called conformance, so Lintomatic is not Conforming, whatever else it satisfies. The fixture does not say Lintomatic declares a version under 8.1. If it did, the 6.3 gap would have to appear in `known-gaps`.\n\n**Does 6.4 change the verdict? No.** Clause 6.4 is a SHOULD, and section 8 counts only MUSTs in sections 4 to 7. The fixture also shows that 6.4 is not met, since Lintomatic's CI does not check that every identifier has an `explain` entry. That is a shortfall in a SHOULD and does not change the conformance verdict. If Lintomatic shipped inside a Toolchain, the toolchain's self-audit would make this check a MUST at the toolchain level. The fixture does not say it is in one, and section 9 keeps the detector and toolchain verdicts separate in any case.\n\n## 4. Confusion\n\nOn my one reading, this was the passage I found hardest to pin down:\n\n> \"A Detector that predates this document, or whose maintainer has never read it, MAY be graded Conforming on evidence\" (8.1)\n\nI could not tell at first whether \"MAY\" gave the grader a permission or described what such a detector is eligible for. The following sentence, \"anyone may grade it … and a verdict on any Detector, declared or not, rests on that check and not on the claim,\" is what settled it for me.","ttft_ms":42775,"type":"result","duration_ms":50194,"uuid":"0e6871e8-0588-4516-a8ef-982959b0a558","ttft_stream_ms":1143,"time_to_request_ms":394,"first_content_frame_ms":1143,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":52025,"stop_reason":"end_turn","session_id":"8880f256-4f6c-4f8e-81c1-9223493a6964","total_cost_usd":0.00876453,"usage":{"input_tokens":2,"cache_creation_input_tokens":11239,"cache_read_input_tokens":2153,"output_tokens":12990,"output_tokens_details":{"thinking_tokens":10874},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11239,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12990,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11239,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11239},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12990,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11239,"webSearchRequests":0,"costUSD":0.00876453,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10874,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let a project write its own rules, registered with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and shows whether it fired and what it printed (4.2).\n- Every rule carries a stable identifier that is not derived from file path, class name, or position. The detector prints it unaltered with every finding (4.3).\n- It must run locally with no infrastructure, including on a single file (5.1, 5.2). Results must appear in the output of the command run, and no finding may be reportable only through a hosted, licence-tier, or CI-only route (5.3, 5.4).\n- Every identifier a bundled rule can print must resolve, from the installed copy and without network access, to documentation shipped with the rule at a tracked version (6.1 to 6.3). A project rule's identifier is printed unaltered for the project's own lookup.\n- An inline suppression route must be either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. Yes, a detector written before the document can conform, because a declaration is optional and grading rests on checking the clauses. §8: \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\" §8.1: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\" Also: \"It is how a maintainer claims [Conformance]; it is not a condition of it.\"\n\n**2b.** The detector must make the route either disableable by configuration or detectable. One of these is enough. §7.1: \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a mechanical check the [Detector] documents.\" Also: \"A route that can be neither switched off nor seen does not [Conform].\"\n\n**2c.** The documentation must ship with the installed rule, at a version tracked together with it, and must resolve without network access. §6.3: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" §6.2: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\" §6.2 rationale: \"A catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong place.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are written as Zig modules implementing `Rule`, listed in `lintomatic.toml`, and are \"first class in every report.\" |\n| 4.2 | Yes | `check --only <identifier> <path>` runs one rule against a path, with exit 1/0 for fired/not fired and 2 for unknown. The doc does not say `--only` prints findings; I take that from `check`'s stdout description. |\n| 4.3 | Yes | Bundled `LM-NNNN` identifiers are fixed at first release. Project names come from configuration and are not rewritten, and the one-line output prints the identifier for each finding. The doc names no other machine-readable format, so there is nothing else to fail. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line stdout form prints location and identifier for every finding, so there is no remainder. The HTML report only adds detail. |\n| 5.4 | Yes | The hosted dashboard shows only findings that \"is also printed by the command line,\" and CI runs the same binary. |\n| 6.1 | Yes | `explain <identifier>` takes the identifier alone. It resolves bundled rules to their documentation and prints a project rule's `doc` string or \"No documentation declared.\" |\n| 6.2 | Yes | `explain` reads \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | **No** | Documentation is versioned with the package, but two of the forty bundled rules print \"No documentation declared.\" I infer these are bundled because they are among the forty and carry `LM-NNNN` identifiers. §6.3: \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `ignore_comments = false` disables `// lintomatic-ignore` project-wide, which satisfies the disableable route. |\n\n**Conformance (§8):** Lintomatic does **not** conform. §8 requires every MUST in sections 4 to 7, and 6.3 is a MUST that fails. Two bundled identifiers resolve to no page, which is enough on its own.\n\n**Does 6.4 change the verdict?** No. 6.4 is a SHOULD (\"The detector SHOULD fail its own release if a bundled rule lacks resolvable documentation\"), and §8 counts only MUSTs. The fixture says the repository does not check this, so the SHOULD is also unmet, and that check would have caught the 6.3 failure before release. §9 also says a detector's verdict is separate from any toolchain verdict, and the fixture does not say whether Lintomatic ships inside one.\n\nOutside the MUST grading: §7.2 (SHOULD require a reason) is unmet, since the comment \"takes no reason.\" The fixture does not describe 4.4, so I cannot grade it.\n\n## 4. Confusion\n\n- §6.1: \"Where the [Identifier] is itself a URL, as method clause 3.6 allows, the [Detector] prints that URL and has done what this clause asks.\" I cannot check method clause 3.6 from the material I was given, so I could not tell what it permits.\n- §7.1: \"That way is open only where the [Detector]'s [Rules] can see the route: a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\" I could not tell from the document what it means for a rule to \"see\" a comment, so I could not apply this sentence to Lintomatic. I did not need it, because the disableable route satisfies 7.1.","ttft_ms":44911,"type":"result","duration_ms":52436,"uuid":"f5efd22b-8500-46eb-994e-8d7a10366cd7","ttft_stream_ms":1098,"time_to_request_ms":414,"first_content_frame_ms":1098,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":57265,"stop_reason":"end_turn","session_id":"8963af0e-7ae2-4320-ba32-22a97721e81f","total_cost_usd":0.00924213,"usage":{"input_tokens":2,"cache_creation_input_tokens":11242,"cache_read_input_tokens":2153,"output_tokens":13944,"output_tokens_details":{"thinking_tokens":11755},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11242,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13944,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11242,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11242},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13944,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11242,"webSearchRequests":0,"costUSD":0.00924213,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11755,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A Detector must let the project write its own rules and register them with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and reports whether it fired and what it printed (4.2).\n- Each rule must carry a stable Identifier, not derived from its path, class name or position, printed unaltered with every finding (4.3).\n- It must run locally with no infrastructure, on at least a single file, and report results in the command's own output, never only through a hosted, licence-tier or CI-only channel (5.1 to 5.4).\n- For bundled rules it must resolve a printed Identifier to documentation, offline, from the installed copy, with every printable Identifier documented (6.1 to 6.3). For a project's own rules it must print the Identifier unaltered (6.1).\n- If it offers inline suppression, that route must be disableable or detectable (7.1). The SHOULDs add a written reason for suppressions, a self-check for 4.3, and a release check for 6.3.\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document can conform. \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7\" (8.1). The declaration \"is not a condition of it\" (8.1).\n\n**2b.** The detector must make the route disableable by configuration, or detectable. \"For each one it MUST do at least one of two things, and either alone satisfies this clause\" (7.1). So doing one of them is enough. Detection by a bespoke rule has a limit: \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way\" (7.1). A route that is neither switchable nor visible \"does not [Conform]\" (7.1).\n\n**2c.** The documentation must ship in the installed package, at a version tracked with the rule. \"A bundled rule's documentation MUST ship with the rule, at a version tracked together\" (6.3). Resolution must work offline: \"MUST work from the installed copy, without network access\" (6.2). It is keyed on the Identifier as printed (6.1). A website catalogue does not satisfy 6.2: \"A catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong place\" (6.2).\n\n## 3. Application\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | \"A project can add its own rules by writing a Zig module that implements the `Rule` interface and listing it in `lintomatic.toml`; project rules are loaded on every run and are first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, and exits 1 when it fires and 0 when it does not. The fixture does not explicitly say `--only` prints findings. I read it as printing them, as `check` does. |\n| 4.3 | Yes | Bundled IDs are `LM-NNNN`, \"fixed at the rule's first release\"; project names come from configuration and \"Lintomatic does not add or rewrite any part of the name\"; both are printed in the one-line output. The fixture describes no machine-readable format, so the clause's second limb is not engaged on what is written. |\n| 5.1 | Yes | \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | \"`lintomatic check <path>` analyses a directory or a single file.\" |\n| 5.3 | Yes | The stdout line gives location, Identifier and message for every finding, \"whether or not the HTML report is enabled.\" Nothing is left as a remainder, so the HTML report need not be named. |\n| 5.4 | Yes | \"every finding it shows is also printed by the command line,\" and \"the same binary is what CI runs.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the Identifier alone and returns the documentation for a bundled rule, or the `doc` string for a project rule. The two rules with no documentation fail 6.3, not 6.1, under 6.1's own rule. |\n| 6.2 | Yes | `explain` \"prints the documentation for a bundled rule from the installed package,\" and the documentation is \"versioned with the package; there is no separate website.\" |\n| 6.3 | No | The repository note says \"two of the forty rules currently print `No documentation declared`.\" The forty are bundled rules. \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` \"can be disabled project-wide with `ignore_comments = false`,\" which is disableable by configuration. One limb is enough. |\n\n**Conformance (section 8): No.** Lintomatic fails 6.3, a MUST in section 6, and \"A [Detector] [Conforms] if it satisfies every MUST in sections 4 to 7.\" The other MUSTs pass, but one failure is enough. Partial conformance \"MUST NOT be described as [Conformance].\"\n\n**Does 6.4 change the verdict? No.** 6.4 is a SHOULD, and section 8 counts only MUSTs. The verdict rests on 6.3. The fixture does show the gap 6.4 describes: the repository runs `lintomatic check src` in CI but \"does not check that every `LM-NNNN` identifier has an `explain` entry.\" Nothing in the fixture makes that check mandatory, since Lintomatic is not said to ship inside a Toolchain.\n\n*Fixture inconsistency, relevant to 6.3:* the `explain` paragraph says `No documentation declared` is what a project rule prints when it has no doc string. The repository note places the same message on two bundled `LM-NNNN` rules. I graded on the repository note, because it is the only passage that says which rules print the message and it refers to bundled ones.\n\n## 4. Confusion\n\n- **§1 governing principle versus 6.1, project rules.** §1 says \"a [Conforming] [Detector] MUST make that possible without the project building the mechanism first.\" 6.1 says that for a project's own rule, \"the lookup is the [Toolchain]'s to give,\" and \"The lookup for such a [Rule] is an obligation on the project's assembled [Toolchain].\" For a project rule in a detector that is not shipped inside a Toolchain, I could not tell which of these governs.\n\n- *Fixture, not a clause:* the `explain` paragraph and the repository note disagree about which rules print `No documentation declared` (see section 3).","ttft_ms":50121,"type":"result","duration_ms":57634,"uuid":"1c328851-7f6a-44a6-a066-00a0a3b40e8b","ttft_stream_ms":992,"time_to_request_ms":373,"first_content_frame_ms":993,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 063: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

The exact prompt every reader received, part 1 of 1

===== FILE: QUESTIONS.md =====
# Questions for a cold reader of DETECTOR-SPEC.md

You have been given `DETECTOR-SPEC.md` and the fixture `fixtures/lintomatic.md`, and nothing
else. Read the document once, then answer every question below in order. Quote the document
where a question asks for a quotation. Do not consult anything outside what you were given.

## 1. Restatement

In your own words and in at most six bullets, what does this document require of a detector?

## 2. Load-bearing statements

Answer each part of each question in a sentence or two, then quote the sentence or sentences of
the document you are relying on.

- 2a. What does it mean for a detector to conform, and can a detector that was written before
  this document existed, and has never heard of it, conform?
- 2b. A detector ships an inline ignore comment. What must the detector do about that route for
  it to conform, and is doing one of those things enough?
- 2c. Where must the documentation for a bundled rule's identifier live, at what version, and
  must it be reachable without network access?

## 3. Application

Grade Lintomatic 4.2, as described in the fixture, against every MUST clause in sections [4](../../DETECTOR-SPEC.md#4-authoring-rules) to [7](../../DETECTOR-SPEC.md#7-suppression):
[4.1](../../DETECTOR-SPEC.md#41-the-detector-must-support-bespoke-rules-written-by-the-project-that-runs-it), [4.2](../../DETECTOR-SPEC.md#42-the-detector-must-provide-a-harness-that-runs-a-single-rule-against-supplied-code), [4.3](../../DETECTOR-SPEC.md#43-the-detector-must-allow-a-rule-to-carry-a-stable-identifier-and-must-print-it-with-every-finding), [5.1](../../DETECTOR-SPEC.md#51-the-detector-must-be-invocable-by-the-practitioner-locally-with-no-infrastructure), [5.2](../../DETECTOR-SPEC.md#52-the-detector-must-support-invocation-over-a-subset-at-minimum-a-single-file), [5.3](../../DETECTOR-SPEC.md#53-the-result-must-reach-the-practitioner-in-the-output-of-the-command-they-ran), [5.4](../../DETECTOR-SPEC.md#54-a-finding-must-not-be-reportable-only-through-a-hosted-service-licence-tier-or-ci-only-mode-the-practitioner-cannot-invoke-locally), [6.1](../../DETECTOR-SPEC.md#61-the-detector-must-provide-a-mechanism-that-resolves-a-printed-identifier-to-its-documentation), [6.2](../../DETECTOR-SPEC.md#62-resolution-of-a-bundled-rules-identifier-must-work-from-the-installed-copy-without-network-access), [6.3](../../DETECTOR-SPEC.md#63-a-bundled-rules-documentation-must-ship-with-the-rule-at-a-version-tracked-together), [7.1](../../DETECTOR-SPEC.md#71-a-detector-may-offer-an-inline-suppression-route-but-must-make-it-detectable-or-disableable). For each give Yes, Partial or No and one
line of reasoning. Then state whether Lintomatic conforms under section [8](../../DETECTOR-SPEC.md#8-conformance), and why. Finally,
state whether clause [6.4](../../DETECTOR-SPEC.md#64-the-detector-should-fail-its-own-release-if-a-bundled-rule-lacks-resolvable-documentation) changes the verdict, and why.

## 4. Confusion

Quote any passage you found confusing on your one reading, with its clause number. Do not say what
would make it clearer and do not propose any change. Write "none" if there was none.

===== FILE: DETECTOR-SPEC.md =====
# Defence Before Fix: Detector Specification

**Version**: 1.0.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the toolchain specification](TOOLING-SPEC.md), version 0.2.0
**Author**: [Joseph Edmonds](https://ltscommerce.dev), [Edmonds Commerce](https://edmondscommerce.co.uk)
**Coined**: 22 February 2026, in [the original article](https://ltscommerce.dev/articles/defence-before-fix-static-analysis)

## 1. What this document is for

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are to be interpreted as
described in RFC 2119.

[The method specification](SPEC.md) states what a [Practitioner] does when a
[Defect] is found. This document states what a [Detector] must offer so that they
can do it: write a [Rule], prove it, run it and resolve what it prints. It is addressed to
whoever maintains a [Detector], which the method specification defines as a tool that reads
code without executing it and reports occurrences of a pattern.

A [Detector] is one part of a project's [Toolchain], and this document judges it
on what it offers alone. What the assembled [Toolchain] of a project must add on top, the
[Project record], the listing of active [Defences] and the
governance of [Suppression], is stated in [the toolchain specification](TOOLING-SPEC.md).
The two are separable because they are built by different people: a [Detector] is authored once
and installed into projects its maintainer will never see, whilst governance is decided by each
project for itself. A document that asked a [Detector] to enforce a project's governance would
fail every [Detector] in use and would not make any project better governed.

**The governing principle**: where the method specification requires a [Practitioner] to do
something with a [Rule], a [Conforming] [Detector] MUST make that possible
without the project building the mechanism first. A [Detector] that leaves the project to
construct the means has moved the obligation rather than met it.

## 2. Terminology

Terms from the method specification carry over unchanged. Every capitalised term links to its
definition; the ones this document leans on most are, in short:

| Term           | In one line                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| [Detector]     | A tool that reads code without executing it and reports what it finds          |
| [Rule]         | One check a [Detector] evaluates                                               |
| [Message]      | The text a [Rule] prints when it fires                                         |
| [Identifier]   | The stable name printed with a finding that leads to its documentation         |
| [Practitioner] | Whoever is doing the work, a person or an [Agent]                              |
| [Toolchain]    | Everything a project assembles to run its checks through, [Detectors] included |
| [Suppression]  | Making a finding go away without fixing it                                     |
| [Baseline]     | A recorded set of existing findings a [Rule] is told to ignore                 |

These are additional.

#### Rule author

Whoever writes a [Rule]. May be the [Detector]'s maintainer, a [Toolchain]'s maintainer or the project that runs it.

#### Bundled rule

A [Rule] the [Detector] ships, or fetches on the [Practitioner]'s behalf from a source the [Detector]'s maintainer controls. Its [Rule author] will never see the codebases it runs in, so everything a [Practitioner] needs in order to act on it has to travel with it.

#### Harness

The route by which one [Rule] is run against supplied code and its findings observed, without the project's own test suite and without every other [Rule] running alongside it.

The distinction between a [Bundled rule] and a project's own [Rule] matters throughout.
The [Detector] owns the documentation of the first and can be held to shipping it; it cannot
know the documentation of the second, and what it owes there is the mechanism that lets the project
attach its own.

## 3. The division of responsibility

Each mechanism the method needs has two halves. Stating only one of them is what produces a
[Detector] that is *nearly* usable.

| Requirement                          | The [Detector] MUST provide                             | The [Rule author] supplies                              |
| ------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------- |
| Bespoke [Rules]                      | The authoring and registration route                    | The [Rules]                                             |
| The red proof                        | A [Harness]                                             | The [Fixture] and the red run                           |
| Running the [Rule]                   | A local invocation, including subsets                   | Running it                                              |
| The [Identifier]                     | A place to carry it, and printing it with every finding | Choosing it once                                        |
| Resolution of a [Bundled rule]       | The lookup, and the documentation, on disk              | Nothing                                                 |
| Resolution of a project's own [Rule] | The [Identifier] printed unaltered                      | The documentation and, with the [Toolchain], the lookup |
| Inline [Suppression]                 | A route the project can detect or disable               | The decision whether to forbid it                       |

Read down the middle column and the shape of a [Conforming] [Detector] is already
visible. Read across any row and the failure mode is visible too: either half alone leaves the
[Practitioner] stuck.

## 4. Authoring rules

### 4.1 The detector MUST support bespoke rules written by the project that runs it

Configuration of an existing [Rule] set is not sufficient. The project must be able to express a
pattern the [Detector]'s authors have never anticipated, and register it so that it runs with
the same standing as a [Bundled rule].

**Why**: the method turns a specific [Defect] into a [Class] [Defence], and the
[Classes] that matter most to a project are the ones peculiar to it. A [Detector] offering
only a fixed catalogue can defend against the industry's known [Hazards] and none of the
project's own, which is the half that carries its institutional knowledge.

### 4.2 The detector MUST provide a harness that runs a single rule against supplied code

A [Harness] reports, for a given input, whether the [Rule] fired and what it printed, without
executing the project's own test suite and without the other [Rules] obscuring the answer.
This applies to every [Rule] the [Detector] runs, bundled or bespoke; a
[Detector] failing 4.1 is graded here on its [Bundled rules].

**Why**: clause 3.3 of the method specification requires the [Rule] to be proven by making it go
red. A [Practitioner] who can only observe a [Rule]'s behaviour by running every
[Rule] over the whole codebase cannot demonstrate that a [Rule] fires on the pattern rather
than on something incidental.

### 4.3 The detector MUST allow a rule to carry a stable identifier, and MUST print it with every finding

The [Identifier] MUST be stable across releases and MUST NOT be derived from the [Rule]'s
file path, [Class] name or position in a configuration file. The [Rule author] chooses it
once. The [Detector] MUST print it, unaltered, alongside every finding the [Rule]
reports, in its default output and in every machine-readable format it offers. A prefix the
[Detector] adds from the invoking directory or the [Rule]'s location is derived from
the file path. A namespace the [Rule author] assigns once in configuration is not.

| [Identifier]       | Where it comes from                                                         | Stable? |
| ------------------ | --------------------------------------------------------------------------- | ------- |
| `proj.no-raw-sql`  | Written once by the [Rule author] in configuration, printed as is           | Yes     |
| `LM-0107`          | Assigned once by the [Detector]'s maintainer at the [Rule]'s first release  | Yes     |
| `rules/no-raw-sql` | Produced from where the [Rule]'s file sits; changes when the file moves     | No      |
| `NoRawSqlRule`     | The [Rule]'s [Class] name; changes when the [Rule] is renamed               | No      |
| `rule 7`           | The [Rule]'s position in a configuration file; changes when one is inserted | No      |

**Why**: the [Identifier] is the only string that reaches the [Practitioner] and the
only key their lookup can use. An [Identifier] that changes when a [Rule] is renamed
silently breaks every reference to it, including references written down by people who have left.
An [Identifier] the [Detector] carries but does not print is one the
[Practitioner] was never given.

### 4.4 The detector SHOULD enforce 4.3 with a rule of its own

A [Rule] over the [Rules], failing any [Rule] that reports without a stable
[Identifier].

**Why**: this is the method applied to the [Detector] itself, and it is cheap. The worked
example is `php-qa-ci`'s `RequireRuleIdentifierConstantRule`, a [Rule] hosted in PHPStan by a
[Toolchain] built on it: it rejects a magic-string [Identifier] and names the
constant to declare instead. Nothing about it needed to live outside the [Detector].

## 5. Reporting

### 5.1 The detector MUST be invocable by the practitioner, locally, with no infrastructure

**Why**: method specification clause 8.1. An [Agent] that cannot check its own work cannot
iterate against a [Defence], so the loop never closes in the turn where it is cheap to close.

### 5.2 The detector MUST support invocation over a subset, at minimum a single file

**Why**: 5.1 is satisfied in principle by a whole-codebase run and defeated in practice by one.
Checking a single edited file has to be fast enough to do on every edit, or it will not be done on
any.

### 5.3 The result MUST reach the practitioner in the output of the command they ran

Where the [Detector] writes fuller detail elsewhere, the invoked command's own output MUST
carry both a usable summary and the location of the remainder. The remainder is the findings
the summary leaves out. Where the output prints every finding, each with where it is and its
[Identifier], there is no remainder, and a report that only adds detail to those same findings,
such as a code snippet, need not be named in the output.

**Why**: method specification clause 8.2. A report the [Practitioner] has to go and find is a
report that arrives after the decision it was meant to inform.

### 5.4 A finding MUST NOT be reportable only through a hosted service, licence tier or CI-only mode the practitioner cannot invoke locally

A finding that the [Detector] reports only through a hosted service, a licence tier or a
continuous-integration-only mode the [Practitioner] cannot invoke locally does not
[Conform], whatever the same [Rule] reports there.

**Why**: a [Rule] that fires only in an environment the [Practitioner] has no access to
teaches nobody anything and blocks them anyway, which is the worst combination available.

## 6. Resolving an identifier

### 6.1 The detector MUST provide a mechanism that resolves a printed identifier to its documentation

Two cases, by who wrote the [Rule]:

| The [Rule]        | Who supplies the documentation | What this clause asks of the [Detector]                                   |
| ----------------- | ------------------------------ | ------------------------------------------------------------------------- |
| A [Bundled rule]  | The [Detector]                 | Resolve the [Identifier], presented alone, to that documentation          |
| The project's own | The project                    | Print the [Identifier] unaltered; the lookup is the [Toolchain]'s to give |

In both, the mechanism is keyed on **the [Identifier] exactly as printed**. A command, an index
file or a URL are all acceptable forms. This clause asks for the mechanism, not for every page:
where the mechanism works but a [Bundled rule]'s [Identifier] has no documentation to resolve
to, that fails clause 6.3, not this clause. Each case in turn:

**For a [Bundled rule]**, the [Detector] supplies the documentation and the
lookup, and clauses 6.2 and 6.3 say where. The mechanism MUST resolve an [Identifier]
presented alone, because the reader who needs it most has the [Identifier] from a log, a
ticket or a colleague and not the [Message]. A documentation path printed in the [Message] is
therefore not enough on its own: it helps only a reader who has the [Message], and the
[Identifier] alone still leads nowhere.

**For a project's own [Rule]**, the [Detector] cannot know the documentation, so what
it owes is the half it can give: the [Identifier] printed unaltered under clause 4.3, and no
transformation of it. Where the [Identifier] is itself a URL, as method clause 3.6 allows,
the [Detector] prints that URL and has done what this clause asks. What this clause forbids is
a documentation path printed alongside a shorter [Identifier] that cannot be looked up on its
own. The lookup for such
a [Rule] is an obligation on the project's assembled [Toolchain], under clause 4.2
of the [toolchain specification](TOOLING-SPEC.md), and a [Detector] that offers it as well has
gone further than this clause asks.

**Why**: method specification clause 8.3 requires the [Identifier] to resolve without a human.
An index keyed on anything else does not resolve it. This is the most commonly failed clause in this
document and it fails in a specific way: documentation exists, is genuinely good, and is keyed on the
[Rule]'s [Class] or file name, which is a string the [Practitioner] was never
given. The lookup they can actually perform is the only one that counts.

### 6.2 Resolution of a bundled rule's identifier MUST work from the installed copy, without network access

**Why**: an [Agent] working offline, behind a proxy, or against a URL that has since moved needs
the answer to be on disk. A dependency the project already installed is on disk by definition. A
catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong
place.

### 6.3 A bundled rule's documentation MUST ship with the rule, at a version tracked together

Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1,
to a page in that shipped documentation. One [Identifier] that does not resolve fails this
clause, however many others do. A page per [Identifier] satisfies this; a page per family of
[Identifiers] MAY be used instead, under clause 6.5.

**Why**: method specification clause 3.6. A [Bundled rule] travels into codebases its author
will never see. If its documentation lives only in the [Detector]'s repository or on its
website, then every project that installs it is one link rot away from a [Rule] that blocks
without explaining.

The failure to guard against is not the absent document but the **dangling one**: a reference to
documentation that was planned and never written is worse than no reference, because it consumes
the [Practitioner]'s attention before failing them.

### 6.4 The detector SHOULD fail its own release if a bundled rule lacks resolvable documentation

An automated check over every [Identifier] a [Bundled rule] can print, applying the
family list or pattern of clause 6.5 where one is used, that blocks the release when any of them
lands on no page.

**Why**: clause 6.3 is the clause most easily believed to be satisfied whilst being broken, because
the documentation is written by the same person who wrote the [Rule] and its absence is
invisible from the inside. Where the [Detector] is shipped inside a [Toolchain],
the [toolchain specification](TOOLING-SPEC.md)'s self-audit makes this check a MUST for the [Toolchain]; a
[Detector] released on its own is asked for it as a SHOULD because the same [Class] of
[Defect], a [Rule] that blocks without explaining, is detectable mechanically there too.

### 6.5 One page MAY document a family of identifiers, and SHOULD name its members so a check can confirm them

Where several [Bundled rules] share a prefix, one page MAY document them all. Such a page
SHOULD let the check clause 6.4 asks for confirm that each member resolves to it. Two forms do
that and one does not:

| The page                                                                                                  | A check can confirm each member?          |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Lists every full [Identifier] in the family, `LM-0100`, `LM-0101`, and so on                              | Yes                                       |
| Carries a regular expression the check can run, `^LM-01[0-9]{2}$`, matching every member and nothing else | Yes                                       |
| Says in prose that everything under `LM-01` is documented here                                            | No: a person can infer it, a check cannot |

The list or the regular expression lives in the installed file, since clause 6.2 requires
resolution to work from the installed copy, not only in a rendered web page.

**Why**: a family page is a convenience for the author, and the cost of it must not fall on the
check. A page that a person can see covers `LM-0107` but a check cannot leaves clause 6.4 with
nothing to run.

## 7. Suppression

### 7.1 A detector MAY offer an inline suppression route, but MUST make it detectable or disableable

An inline ignore comment, a per-line directive and a generated [Baseline] are all such
routes. The [Detector] MAY ship them. For each one it MUST do at least one of two things, and either
alone satisfies this clause: make the route disableable by configuration; or make the route
detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a
mechanical check the [Detector] documents. Either lets a project which decides to forbid the
route enforce that decision. A route that can be neither switched off nor seen does not [Conform].

A route is detectable when the project can find every use of it. The first way is a bespoke
[Rule]: the project registers a [Rule] of its own, as clause 4.1 provides for, that matches the
route wherever it is used, and the [Detector] runs it like any other bespoke [Rule]; the
[Detector] ships no such [Rule] itself, and need not. That way is open only where the
[Detector]'s [Rules] can see the route: a [Detector] whose [Rules] never see comments cannot make
an ignore comment detectable this way. The second way is a mechanical check the [Detector]
documents, such as a text search for the route's spelling that the [Detector]'s documentation
gives.

**Why**: the method specification's position is that [Suppression] is an [Owner]
decision under its clause 3.4 and section 4, and an [Owner] cannot decide something they are
never shown. The [Detector] is not the [Owner] and does not know the project's
governance, so it is not asked to enforce it; what it is asked is not to hide the route. Every
[Detector] in wide use ships an inline ignore, and a clause that forbade them would fail all of
them without governing any project better. Whether the route is forbidden is the project's decision,
enforced through its [Toolchain] under clause 4.3 of the [toolchain specification](TOOLING-SPEC.md).

### 7.2 An inline suppression route SHOULD require a written reason

The [Detector] SHOULD reject, or be configurable to reject, an inline [Suppression]
that carries no reason, and SHOULD NOT supply a default one, including each entry of a generated
[Baseline].

**Why**: a [Suppression] without a reason is indistinguishable from one nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence costs the author a
minute at the moment they have the reason in mind, and it is the only thing that makes the
[Suppression] reviewable later. PHPStan's `reportIgnoresWithoutComments` is the shape of it.

## 8. Conformance

**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Detector]
that satisfies most of this document is in a normal and respectable condition; it is not
[Conforming], and describing it as such removes the only value the word has.

This document defines one level. The clauses of the method specification's section 8 that reach
beyond what sections 4 to 7 here already secure, the listing of active [Defences] and the
summary for an [Agent]'s context, are obligations on a project's assembled [Toolchain]
and are stated in the [toolchain specification](TOOLING-SPEC.md), so there is no separate [Agent]-support level
for a [Detector].

### 8.1 A maintainer MAY declare the version of this document the detector conforms to, and the declaration records known gaps

The declaration is machine-readable, in whatever form the [Detector]'s ecosystem uses to
record dependencies. The same declaration is where a gap against this document is recorded once it is
known: a [Detector] that declares a version and has learnt, from its own checks or from a
[Practitioner]'s report under the method's clause 3.2, that it fails a MUST in sections 4 to 7
MUST record that gap alongside that version, in the same file or one it names. A declaration
with a non-empty gap record is a statement of where the [Detector] stands and is not a claim of
[Conformance].

The declaration is optional, and so the duty above falls only on a [Detector] that has one; a
gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case. It is how a
maintainer claims [Conformance]; it is not a condition of it. A [Detector] that predates this document, or whose maintainer has never read
it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each
clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that
check and not on the claim. A declaration tells the reader what the maintainer believes and what they know to be missing;
the reader still runs the [Harness].

The shape is illustrative rather than prescribed. In a Composer manifest:

```json
"extra": {
  "defence-before-fix": {
    "method": "1.0.1",
    "detector": "1.0.0",
    "toolchain": null,
    "known-gaps": []
  }
}
```

In a package.json, the equivalent is a top-level `defenceBeforeFix` object with the same keys. A
[Detector] that is not also shipped as a [Toolchain] leaves `toolchain` empty;
a project that ships both declares both. Each entry in `known-gaps` names the clause and states the
gap in a sentence.

**Why**: a [Conformance] claim in a README is a sentence; a claim in a manifest is a fact about
a specific installed artefact, checkable by anyone, including mechanically, and it fixes what
"[Conforming]" meant at the point the claim was made. Making the claim a condition of
[Conformance], though, would mean a [Detector] with every mechanism in place could
never [Conform] until its maintainer had heard of this document, which grades the
maintainer's reading rather than the [Detector].

## 9. Relationship to the other specifications

This document adds no obligations to a [Practitioner] and relaxes none. Every clause here
exists to make a clause of the method specification achievable with a [Detector] in hand.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes one piece of the equipment.

The [toolchain specification](TOOLING-SPEC.md) states what a project's assembled [Toolchain] must offer beyond
what each [Detector] in it offers, and it requires every [Detector] a [Defence]
is routed through to [Conform] to this one. A [Detector] shipped inside a
[Toolchain] is measured here as a [Detector] and there as part of the
[Toolchain]; the two verdicts are separate and neither implies the other.

Nothing here requires a project to use a [Conforming] [Detector]. A project can
[Conform] to the method specification on a [Detector] that [Conforms] to
none of this, at the cost of building the missing mechanisms itself. This document exists so that it
does not have to.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[bundled rule]: #bundled-rule
[bundled rules]: #bundled-rule
[class]: SPEC.md#class
[classes]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[fixture]: SPEC.md#fixture
[harness]: #harness
[hazards]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[project record]: TOOLING-SPEC.md#project-record
[rule]: SPEC.md#rule
[rule author]: #rule-author
[rules]: SPEC.md#rule
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain

===== FILE: fixtures/lintomatic.md =====
# Fixture: Lintomatic 4.2

A fictional detector, described only as far as its documentation would describe it. Grade it
against the document you were given. Where the description does not say, answer from what is
written, not from what a real tool would probably do.

## What the documentation says

Lintomatic is a static analyser for the Zig language. It ships forty rules. A project can add its
own rules by writing a Zig module that implements the `Rule` interface and listing it in
`lintomatic.toml`; project rules are loaded on every run and are first class in every report.

The command `lintomatic check <path>` analyses a directory or a single file and prints one line
per finding to standard output:

```
src/db.zig:41:7  LM-0107  Result of fallible call discarded
src/db.zig:88:3  proj.no-raw-sql  Query built by string concatenation
```

Fuller detail, including a snippet, is written to `.lintomatic/report.html`. The one-line form is
printed whether or not the HTML report is enabled.

`lintomatic check --only <identifier> <path>` runs a single rule. It accepts any rule name,
bundled or project, and exits 1 when the rule fires, 0 when it does not, and 2 when the rule name
is unknown.

Rule identifiers for bundled rules are of the form `LM-NNNN` and are fixed at the rule's first
release. Project rules are identified by the name the project gives them in `lintomatic.toml`,
which the documentation recommends prefixing with `proj.`; Lintomatic does not add or rewrite
any part of the name.

`lintomatic explain <identifier>` prints the documentation for a bundled rule from the installed
package: what the rule finds, why, and the recommended construction. For a project rule it prints
the `doc` string the rule module declares, or `No documentation declared` when there is none.
The documentation is versioned with the package; there is no separate website.

Lintomatic honours the comment `// lintomatic-ignore <identifier>` on the line before a finding.
The comment can be disabled project-wide with `ignore_comments = false` in `lintomatic.toml`.
The comment takes no reason and the documentation does not mention one.

The tool runs locally with no account, no server and no network, and the same binary is what CI
runs. There is a hosted dashboard, sold separately, that aggregates reports across repositories;
every finding it shows is also printed by the command line.

Lintomatic's own repository runs `lintomatic check src` in CI but does not check that every
`LM-NNNN` identifier has an `explain` entry; two of the forty rules currently print
`No documentation declared`.

[LTSCommerce]

Run 066: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Command and working directory

ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt, each reader in a fresh empty directory made by mktemp -d outside the repository

Model version each reader reported

reader 1: claude-haiku-5-5
reader 2: claude-haiku-5-5
reader 3: claude-haiku-5-5
reader 4: claude-haiku-5-5
reader 5: claude-haiku-5-5

The delegated marker's task prompt

MODE: mark

Worktree: <worktree> (branch `editor/detector-route-rule`). The readers read commit 44fdd9e. Read, at that commit and in that worktree: ACCEPTANCE.md in full (it is the process as pull request 22 proposes it, merged into this branch; the run is made under that process change before it merges, at commit 9907492, named here before the readers started), acceptance/runs/README.md, acceptance/detector/QUESTIONS.md, acceptance/detector/KEY.md, acceptance/fixtures/lintomatic.md and DETECTOR-SPEC.md. You may read acceptance/runs/063-detector-route-rule-run-2.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 066. Document: DETECTOR-SPEC.md. Change: detector route rule (clause 7.1's detectable route is a bespoke rule the project writes for the detector under clause 4.1, with a paragraph on what detectable means; clause 8.1's gap duty falls only on a detector that declares a version; clause 5.3 says what the remainder is; clause 6.1 says it asks for the mechanism, a missing page failing 6.3, and that a path in the message is not enough on its own; section 2's table gains a Message row), revised after run 63 in clause 5.3's sentence on a fuller report elsewhere. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 3 (runs 60 and 63 came before). Record file to write: <worktree>/acceptance/runs/066-detector-route-rule-run-3.md. Do not commit it.

Sheets: <run-dir>/sheet-1.md to sheet-5.md, each the `result` of reader-N.json. Prompt the readers received: <run-dir>/prompt.txt; its sha256 is 5f991fd47d3b8d092464ca41bfdfd9f5707647f46e3b274929a0c5a44f5a50c4, and it is byte for byte the question set, DETECTOR-SPEC.md and the fixture at 44fdd9e, each after one `===== FILE: <name> =====` line, one blank line between files. Model: every reader reported claude-haiku-5-5 (<run-dir>/models.txt); the cohort's model named for the run is claude-haiku-5-5. Every reader's JSON has is_error false and subtype success; no reader is set aside.

Facts the editor supplies for the record: cohort of five readers, none reused from any earlier run; each a separate `claude -p` process started through the `ccy-claude` wrapper (which only reattaches the session's credential) in a fresh empty directory made by `mktemp -d` outside any repository, with the packet on standard input, command `ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt`; no tools, no settings, no project context, no saved session; the machine applies no managed settings; the editor attests the rest of the isolation. Marked by a delegated marker, a fresh `dbf-spec-editor` agent (Claude Opus) given this instruction and its agent definition, having seen neither the drafting nor the review.

Text the change wrote or altered, for "Where a finding lies": the output of `git -C <worktree> diff 9e914fe 44fdd9e -- DETECTOR-SPEC.md` (9e914fe is the merge base with `next`). Run it and read it. A finding in a paragraph that diff adds, rewords, moves, deletes a sentence from, or changes a word, term or link in, or that a reader sets against such a paragraph, blocks; any other finding is routed to acceptance/ROUTED.md, and the record says so for each.

Mark every sheet, keyed item by keyed item, by ACCEPTANCE.md's Marking section and the key alone. Write the record stating what acceptance/runs/README.md lists, in its order, with the marks table, each miss with the reader's reasoning in brief, every passage named under question 4 with its words or description, clause and readers, each finding and where it lies, any open point and the direction you marked it, the process-change commit 9907492, the verdict, and a placeholder line for the link to the posted sheets. Reply with the verdict and the findings only, under thirty lines.

The agent definition the marker ran under

---
name: dbf-spec-editor
description: Drafts, reviews, key-updates, marks or records a change to the Defence Before Fix specification, one mode per dispatch, following the specification repository's CONTRIBUTING.md, SCOPE.md and ACCEPTANCE.md exactly. Dispatched by the dbf-spec-change skill; it cannot run a cohort itself.
tools: Read, Write, Edit, Grep, Glob, Bash
model: opus
---

You work on one change to the Defence Before Fix specification, in the worktree path you are
given. The process is defined by that repository's `CONTRIBUTING.md`, `SCOPE.md`,
`ACCEPTANCE.md` and `acceptance/README.md`; read the ones your mode needs, in full, before you
act. You invent no steps. You never merge, push to `next` or `main`, release, tag or publish,
and you never change a question, threshold or fixture. Your prompt names one mode.

Write as the specification is written: British spelling, no em dashes, defined terms linked as
`spec-qa.py` requires, every clause or section number linked to its heading. Commit on the
worktree's branch.

## MODE: draft

1. Read `SCOPE.md`, `DECLINED.md`, and every clause the change touches, with the terminology
   entries they use.
2. Decide the kind. A change to the sentences carrying MUST, SHOULD or MAY in a numbered section
   or appendix is an obligation; anything else is a clarity edit.
3. For an obligation, answer the five SCOPE tests in a sentence or two each, and name the
   section the obligation extends. If a test fails, or an existing clause already covers it, say
   so and stop without editing.
4. Make the smallest edit that does the job, in the clause that owns the subject.
5. Add one line under `Unreleased` in `CHANGELOG.md`, saying what changed and why, with a
   placeholder `run NNN`. Change no version.
6. If Appendix A changed, run `python3 build-agent-surfaces.py` and commit its outputs.
7. Run `python3 spec-qa.py` and `python3 -m unittest discover -s tools -p 'test_*.py'`; both
   clean.
8. Reply with: kind, SCOPE answers, files changed, commit, QA result, and a filled
   `.github/PULL_REQUEST_TEMPLATE.md` body. Under forty lines.

## MODE: review

You have not seen the drafting. Read the whole changed document and the diff against
`origin/next`. Report, numbered, with clause numbers: contradictions with other clauses, terms
used outside their definition, a sentence a reader could take two ways, an obligation an owner
could not verify from the record. Do not edit.

## MODE: keys

Read `acceptance/README.md` and the `KEY.md` for each changed document. Update every quotation of
a changed sentence to the new wording, verbatim, in a new commit; run `python3 spec-qa.py` until
`key-quote-stale` is gone. If the change adds a load-bearing obligation no keyed question
covers, propose the question and its key in your reply; add it only if your prompt says the owner
has decided to.

## MODE: mark

You have not seen the drafting or the review. Read `ACCEPTANCE.md` in full, the `KEY.md` for the
document, the document at the commit named, and the sheets under `<run-dir>/`.

- Mark each sheet against the key, keyed item by keyed item, by the rules under "Marking" in
  `ACCEPTANCE.md` and nothing else: the key's required elements, accepted grades, conditions and
  wrong readings. Invent no judgement; where neither the rules nor the key settles a mark, mark
  it in the direction the open-point rule gives and record the point.
- A single miss under questions 1 and 3 counts against the document only where the key names
  that reading; say which.
- For question 4, record every passage named, with its words or description and its clause.
  Group the passages by paragraph, count the readers, and for each finding say whether it lies in
  text the change wrote or altered, read against the diff the prompt gives you, or is routed to
  `acceptance/ROUTED.md`. Ignore any suggestion a reader volunteers.
- Apply the pass criteria exactly.
- Write `acceptance/runs/NNN-<slug>-run-<k>.md` stating what `acceptance/runs/README.md` lists,
  in its order. Do not commit it. Reply with the verdict and the findings only.

## MODE: record

Commit the run record, replace the `run NNN` placeholder in `Unreleased` with a link to it, and
for an obligation set the document header to `<next version>-dev, unpublished` in the same
commit if it still names a published version. Run `python3 spec-qa.py` and
`python3 tools/changes.py --base origin/next`; both clean. Reply with the commit.

[LTSCommerce]

Run 066: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Answer sheets, each reader's whole output as its process returned it

reader-1

{"duration_api_ms":44873,"stop_reason":"end_turn","session_id":"1b311e02-4fbb-48fd-8891-bb266642cfdd","total_cost_usd":0.00776283,"usage":{"input_tokens":2,"cache_creation_input_tokens":11268,"cache_read_input_tokens":2153,"output_tokens":10975,"output_tokens_details":{"thinking_tokens":9011},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11268,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":10975,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11268,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11268},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":10975,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11268,"webSearchRequests":0,"costUSD":0.00776283,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":9011,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- Let the project write its own rules, registered with the same standing as bundled rules (4.1).\n- Provide a harness that runs one rule against supplied code and reports whether it fired and what it printed (4.2).\n- Carry a stable identifier that the rule author chooses, not derived from path, class name or position, and print it unaltered with every finding (4.3).\n- Run locally with no infrastructure, including on a single file, and put findings in the invoked command's output, not only in a hosted service, licence tier or CI-only mode (5.1–5.4).\n- Resolve a printed identifier alone to its documentation. For bundled rules, the documentation ships on disk with the rule, at the same version, and works offline. Every identifier the rule can print must resolve (6.1–6.3).\n- Any inline suppression route must be either disableable by configuration or detectable by the project (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document, and unaware of it, can conform. Section 8 says: \"A [Detector] [Conforms] if it satisfies every MUST in sections 4 to 7.\" Section 8 also says: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\"\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Doing one of those is enough. The document says: \"For each one it MUST do at least one of two things, and either alone satisfies this clause.\" It adds: \"A route that can be neither switched off nor seen does not [Conform].\" Detectability by a bespoke rule only works if the detector's rules can see comments.\n\n**2c.** The documentation must ship with the installed rule, at a version tracked together with it, and must resolve without network access. Clause 6.3 says: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" Clause 6.2 says: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\" It also says: \"A catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong place.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are Zig modules implementing the `Rule` interface, listed in `lintomatic.toml`, and are \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, \"bundled or project,\" with exit codes 1/0/2. The fixture doesn't spell out the printed output under `--only`, but it is a flag on `check`, which prints findings. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, fixed at first release. Project identifiers are the configured name, which Lintomatic \"does not add or rewrite.\" Both are printed in the default output. The fixture describes no machine-readable format, so that half is unverifiable here. |\n| 5.1 | Yes | \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line output prints every finding with location and identifier, \"whether or not the HTML report is enabled,\" so there is no remainder. The HTML report only adds detail. |\n| 5.4 | Yes | Findings are printed by the local command. The dashboard shows only findings that \"are also printed by the command line.\" CI runs the same binary. |\n| 6.1 | Yes | `lintomatic explain <identifier>` resolves the identifier as printed. The mechanism works for all 40 bundled rules, even though two lack documentation (see 6.3). |\n| 6.2 | Yes | Documentation comes \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | **No** | Two of the forty bundled rules print \"No documentation declared.\" Clause 6.3 says \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | The `// lintomatic-ignore` route \"can be disabled project-wide with `ignore_comments = false`,\" which is disableable by configuration. |\n\n**Conformance:** Lintomatic does not conform. Clause 6.3 is a MUST and fails. Section 8 says Partial Conformance \"MUST NOT be described as [Conformance],\" so the verdict is No, not \"mostly conforming.\" The other MUSTs are met, and the verdict rests on the 6.3 failure alone.\n\n**Does 6.4 change the verdict?** No. Clause 6.4 is a SHOULD, and section 8 counts only MUSTs. The missing release check is a gap against a SHOULD. The verdict was already No from 6.3, and the check would only have caught the failure earlier. Separately, the toolchain specification makes this check a MUST for a project's assembled toolchain. That is a different verdict, and the fixture doesn't say whether Lintomatic is shipped inside a toolchain. The detector verdict doesn't depend on it.\n\n## 4. Confusion\n\n- Clause 6.1: \"Where the [Identifier] is itself a URL, as method clause 3.6 allows, the [Detector] prints that URL and has done what this clause asks.\" It cites method clause 3.6, which I was not given, so I could not tell what it requires.\n- Clause 6.1: \"The lookup for such a [Rule] is an obligation on the project's assembled [Toolchain], under clause 4.2 of the [toolchain specification](TOOLING-SPEC.md).\" It cites the toolchain specification, which I was not given, so I could not verify the obligation.","ttft_ms":38347,"type":"result","duration_ms":45263,"uuid":"fc5fa7e8-fe63-40db-8e15-cd548a29583e","ttft_stream_ms":979,"time_to_request_ms":384,"first_content_frame_ms":979,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":34805,"stop_reason":"end_turn","session_id":"674ceb3b-7596-4695-9661-333c02565eb9","total_cost_usd":0.00649483,"usage":{"input_tokens":2,"cache_creation_input_tokens":11268,"cache_read_input_tokens":2153,"output_tokens":8439,"output_tokens_details":{"thinking_tokens":6741},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11268,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":8439,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11268,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11268},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":8439,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11268,"webSearchRequests":0,"costUSD":0.00649483,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":6741,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, register them alongside bundled rules, and run them with the same standing (4.1).\n- It must offer a harness that runs one rule against supplied code and reports whether it fired and what it printed (4.2).\n- Every rule needs a stable identifier, chosen once and printed unaltered with every finding (4.3).\n- It must run locally with no infrastructure, on a subset down to a single file, with results in the command's own output and no findings reachable only through a hosted, licence-gated or CI-only route (5.1–5.4).\n- A printed identifier must resolve to its documentation. For bundled rules that lookup works offline from the installed copy, and every identifier the rule can print must resolve (6.1–6.3).\n- An inline suppression route must be either disableable by configuration or detectable (7.1). A detector conforms if it meets every MUST in sections 4 to 7 (8).\n\n## 2. Load-bearing statements\n\n**2a.** Conformance means satisfying every MUST in sections 4 to 7. A detector that predates the document and has never heard of it can conform. Section 8 says it \"satisfies every MUST in sections 4 to 7,\" and 8.1 says: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\"\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Doing one of these is enough. 7.1 says: \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] … or by a mechanical check the [Detector] documents.\"\n\n**2c.** The documentation must ship inside the installed rule package, at a version tracked together with the rule. It must also resolve without network access. 6.3: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" 6.2: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | `lintomatic.toml` lets a project register its own Zig `Rule` module, which is \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, with exit codes 1/0/2. The document does not explicitly say the printed finding text appears in `--only` output. I take that from `check` printing findings, which is an inference. |\n| 4.3 | Yes | `LM-NNNN` is \"fixed at the rule's first release,\" and project names are \"the name the project gives them,\" with no rewriting. Findings print the identifier on each line. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | \"The one-line form is printed whether or not the HTML report is enabled.\" Every finding is in the output, so there is no remainder. |\n| 5.4 | Yes | The dashboard is \"sold separately,\" but \"every finding it shows is also printed by the command line.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` resolves an identifier presented alone. Where a bundled rule has no documentation, 6.1 assigns that failure to 6.3. |\n| 6.2 | Yes | `explain` prints \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | No | Two of the forty bundled rules \"currently print `No documentation declared`.\" 6.3 says: \"One [Identifier] that does not resolve fails this clause, however many others do.\" The fixture's `explain` output stands in for \"a page,\" which is my reading. |\n| 7.1 | Yes | `ignore_comments = false` in `lintomatic.toml` makes the `// lintomatic-ignore` route disableable. |\n\n**Conformance (section 8):** Lintomatic does not conform. It fails 6.3, which is a MUST, and section 8 requires every MUST in sections 4 to 7. It is partial conformance, and per section 8 it \"MUST NOT be described as [Conformance].\"\n\n**Clause 6.4:** No, it does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. The verdict already rests on 6.3. The fixture shows the failure that 6.4 is meant to catch: Lintomatic's CI does not check that every `LM-NNNN` has an `explain` entry. That absence explains why the gap persists, but its absence is not itself a MUST failure.\n\n## 4. Confusion\n\n- **4.3:** \"A prefix the [Detector] adds from the invoking directory or the [Rule]'s location is derived from the file path. A namespace the [Rule author] assigns once in configuration is not.\"","ttft_ms":28807,"type":"result","duration_ms":35147,"uuid":"da20f858-3558-4b1f-9025-35efdcd044de","ttft_stream_ms":1276,"time_to_request_ms":348,"first_content_frame_ms":1277,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":48788,"stop_reason":"end_turn","session_id":"150bb4b2-11b9-46cf-9e5a-af793da901bb","total_cost_usd":0.008264529999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11269,"cache_read_input_tokens":2153,"output_tokens":11978,"output_tokens_details":{"thinking_tokens":9914},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11269,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11978,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11269,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11269},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11978,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11269,"webSearchRequests":0,"costUSD":0.008264529999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":9914,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, registered with the same standing as bundled rules (4.1).\n- A detector must offer a harness that runs one rule against supplied code and reports whether it fired and what it printed (4.2).\n- Every rule needs a stable identifier, not derived from its path, class name, or position, and the detector must print it unaltered with every finding (4.3).\n- The detector must run locally with no infrastructure, on a subset such as a single file, and put findings in the output of the command run. No finding may be reportable only through a hosted, licence-tier, or CI-only route (5.1–5.4).\n- Every identifier a bundled rule can print must resolve, from the installed copy and without network access, to documentation shipped with the rule (6.1–6.3).\n- An inline suppression route may exist, but it must be switchable off by configuration or detectable (7.1). A detector conforms when it meets every MUST in sections 4 to 7 (8).\n\n## 2. Load-bearing statements\n\n**2a.** Conformance means satisfying every MUST in sections 4 to 7. Yes, a detector that predates the document can conform. Section 8 says: \"A Detector that predates this document, or whose maintainer has never read it, MAY be graded Conforming on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any Detector, declared or not, rests on that check and not on the claim.\" Clause 8.1 adds: \"It is how a maintainer claims Conformance; it is not a condition of it.\"\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Either one alone is enough. Clause 7.1 says: \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable…\" The detectable route through a bespoke rule is closed if the detector's rules cannot see comments: \"a Detector whose Rules never see comments cannot make an ignore comment detectable this way.\"\n\n**2c.** The documentation must ship with the rule, at a version tracked together with it (6.3: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\"). It must be reachable offline. Clause 6.2 says: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are written as Zig modules implementing `Rule`, listed in `lintomatic.toml`, and are \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` \"runs a single rule,\" accepts bundled or project rules, and exits 1 or 0 on firing. The fixture does not say outright that `--only` prints the finding lines, but it is presented as a form of `check`, which does. |\n| 4.3 | Yes | Bundled identifiers are \"fixed at the rule's first release\"; project names come from `lintomatic.toml` and \"Lintomatic does not add or rewrite any part of the name\"; the one-line output prints them. The fixture names no machine-readable format, so that limb cannot be checked and is satisfied only in the sense that none is offered. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | \"`lintomatic check <path>` analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line form is printed to stdout \"whether or not the HTML report is enabled.\" Each line carries location and identifier, so there is no remainder. The HTML report only adds detail. |\n| 5.4 | Yes | \"every finding it shows is also printed by the command line,\" and the same binary runs locally and in CI. |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone. For project rules it prints the declared `doc` string or \"No documentation declared.\" |\n| 6.2 | Yes | `explain` prints \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | **No** | \"two of the forty rules currently print `No documentation declared`.\" Their identifiers resolve to no page, and one unresolved identifier fails the clause. |\n| 7.1 | Yes | `ignore_comments = false` disables the `// lintomatic-ignore` route project-wide. |\n\nI read \"No documentation declared\" as the `explain` output for those two bundled identifiers. The fixture states the phrase in the project-rule paragraph, then applies it to \"every `LM-NNNN` identifier\" in the repository paragraph. If that inference were wrong, 6.3 would need re-grading.\n\n**Conformance under section 8: Lintomatic does not conform.** Clause 6.3 is a MUST and fails. Section 8 is explicit that partial conformance \"MUST NOT be described as Conformance.\" The other MUSTs in sections 4 to 7 are the ones listed above, so the failure of 6.3 alone decides the verdict.\n\n**Clause 6.4: it does not change the verdict.** 6.4 is a SHOULD, not a MUST, so section 8 does not test it. Lintomatic's repository does not perform the check 6.4 describes, which is a gap against that SHOULD. It is also the reason the 6.3 failure went unnoticed. The fixture does not say Lintomatic ships inside a Toolchain, so 6.4's note about the Toolchain's self-audit does not apply here. The verdict stays No.\n\n## 4. Confusion\n\n- **6.3**: \"The failure to guard against is not the absent document but the **dangling one**,\" set against the MUST \"Every Identifier a Bundled rule can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\" I could not tell whether the MUST covers absent documentation or only dangling references. I graded it as covering absence.\n- **6.1**: \"What this clause forbids is a documentation path printed alongside a shorter Identifier that cannot be looked up on its own.\" I could not tell what \"shorter\" is measured against.\n- **2 (Terminology)**: \"These are additional.\" I could not tell what the terms are additional to.","ttft_ms":41740,"type":"result","duration_ms":49132,"uuid":"06419023-05dd-4a3a-b626-6e0c2d94e781","ttft_stream_ms":1159,"time_to_request_ms":349,"first_content_frame_ms":1160,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":52865,"stop_reason":"end_turn","session_id":"a41c46c9-92a8-43ae-a6cb-dbc1453d16f8","total_cost_usd":0.008743029999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11269,"cache_read_input_tokens":2153,"output_tokens":12935,"output_tokens_details":{"thinking_tokens":10808},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11269,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12935,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11269,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11269},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12935,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11269,"webSearchRequests":0,"costUSD":0.008743029999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10808,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, registered with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and reports whether it fired and what it printed, for bundled and project rules alike (4.2).\n- Each rule must carry a stable identifier, not derived from its path, class name or position, and the detector must print that identifier unaltered with every finding (4.3).\n- It must run locally with no infrastructure, accept a single file as input, and put every finding in the invoked command's own output, with nothing reportable only through a hosted service, licence tier or CI-only mode (5.1 to 5.4).\n- It must resolve a printed identifier to its documentation. For bundled rules that works from the identifier alone, offline, from documentation shipped at the same version, and every identifier the rules can print must resolve (6.1 to 6.3).\n- If it offers an inline suppression route, it must make that route disableable or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms if it satisfies every MUST in sections 4 to 7. A detector written before the document can conform, because conformance is graded on evidence and a declaration is not required.\n- \"A [Detector] [Conforms] if it satisfies every MUST in sections 4 to 7.\" (§8)\n- \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\" (§8.1)\n- \"It is how a maintainer claims [Conformance]; it is not a condition of it.\" (§8.1)\n\n**2b.** The detector must do at least one of two things: make the route disableable by configuration, or make it detectable. Doing one of them is enough.\n- \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable…\" (7.1)\n- \"A route that can be neither switched off nor seen does not [Conform].\" (7.1)\n- The bespoke-rule route to detectability is only open if the detector's rules can see comments: \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\" (7.1)\n\n**2c.** The documentation must ship with the installed rule, at a version tracked together with it, and must resolve offline.\n- \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" (6.3)\n- \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (6.2)\n- Every identifier the bundled rule can print \"MUST resolve, under clause 6.1, to a page in that shipped documentation.\" (6.3)\n\n## 3. Application\n\nThe listed clauses are all the MUSTs in sections 4 to 7. The SHOULD and MAY clauses (4.4, 6.5, 7.2) are excluded, and 6.4 is answered separately.\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules implement the `Rule` interface, are listed in `lintomatic.toml`, and are \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, and exits 1, 0 or 2. The fixture does not say the one-line output appears under `--only`; I have taken it to, since `--only` restricts `check`. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, fixed at first release. Project names are not rewritten, and each finding line prints its identifier. The fixture names no machine-readable format, so the requirement applies only to the default output. |\n| 5.1 | Yes | \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` accepts \"a single file.\" |\n| 5.3 | Yes | Every finding is printed as a line with location and identifier, whether or not the HTML report is enabled, so there is no remainder. |\n| 5.4 | Yes | The dashboard shows only findings that \"are also printed by the command line,\" and no CI-only finding is described. |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone and prints bundled documentation. Project rules print their `doc` string or \"No documentation declared.\" |\n| 6.2 | Yes | Documentation is printed \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | **No** | Two of the forty bundled rules \"currently print `No documentation declared`,\" so their identifiers resolve to no page. One unresolved identifier fails the clause. |\n| 7.1 | Yes | `ignore_comments = false` disables `// lintomatic-ignore` by configuration, which alone satisfies the clause. |\n\n**Conformance (§8):** Lintomatic does not conform. It satisfies every listed MUST except 6.3, and §8 requires every MUST in sections 4 to 7. It is partial conformance, which §8 says must not be described as conformance.\n\n**Clause 6.4:** It does not change the verdict. 6.4 is a SHOULD, and §8 counts only MUSTs. Lintomatic's repository does not run the check, so it falls short of 6.4, but that is the mechanism that would have caught the 6.3 failure, not a separate failure. If Lintomatic ships inside a toolchain, the toolchain specification makes this check a MUST for the toolchain. That is a separate verdict under §9, and I was not given that specification, so I cannot grade it. If Lintomatic declares a version, §8.1 requires the 6.3 gap to be recorded.\n\n## 4. Confusion\n\n- 7.1: \"That way is open only where the [Detector]'s [Rules] can see the route: a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\" The document never says what a bespoke rule can see, so I could not tell whether this route applies to Lintomatic. I therefore relied only on the configuration route in grading 7.1.\n- 6.1: \"What this clause forbids is a documentation path printed alongside a shorter [Identifier] that cannot be looked up on its own.\" The comparison behind \"shorter\" is not stated.","ttft_ms":45939,"type":"result","duration_ms":53265,"uuid":"3185f7f1-9a1b-4167-a802-4d5f485a9d35","ttft_stream_ms":1154,"time_to_request_ms":404,"first_content_frame_ms":1154,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":43848,"stop_reason":"end_turn","session_id":"47762f47-9472-4382-a3a2-95b6ccfe7511","total_cost_usd":0.007643529999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11269,"cache_read_input_tokens":2153,"output_tokens":10736,"output_tokens_details":{"thinking_tokens":8725},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11269,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":10736,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11269,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11269},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":10736,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11269,"webSearchRequests":0,"costUSD":0.007643529999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":8725,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- Let the project write its own rules and register them with the same standing as bundled rules (4.1).\n- Provide a harness that runs one rule against supplied code and reports whether it fired and what it printed (4.2).\n- Let each rule carry a stable identifier, not derived from its path, class name or position, and print it unaltered with every finding (4.3).\n- Run locally with no infrastructure, including on a single file, and put the results in the output of the command the practitioner ran (5.1 to 5.3). Never report a finding only through a hosted service, licence tier or CI-only mode (5.4).\n- Resolve a bundled rule's identifier, presented alone, to documentation that ships in the installed copy, works offline and covers every identifier the rule can print (6.1 to 6.3). For a project's own rules, print the identifier unaltered.\n- Any inline suppression route must be either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector that predates the document and has never heard of it can still conform, because grading rests on checking the clauses, not on a declaration. Quotes: \"A [Detector] **Conforms** if it satisfies every MUST in sections 4 to 7.\" and \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7\".\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Doing one of these is enough. Quote: \"For each one it MUST do at least one of two things, and either alone satisfies this clause.\" The detectable route is only available where the detector's rules can see the route: \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\"\n\n**2c.** The documentation must ship with the rule at a version tracked together with it (heading of 6.3). It must be reachable from the installed copy without network access (heading of 6.2). Quote: \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n| --- | --- | --- |\n| 4.1 | Yes | Project rules are Zig modules implementing the `Rule` interface, listed in `lintomatic.toml`, and are \"first class in every report.\" Any pattern can be expressed. |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, and exits 1, 0 or 2. The fixture does not say explicitly that `--only` prints the finding text. I have assumed it does, since it uses the same output as `check`. If it does not, this is No. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, \"fixed at the rule's first release.\" Project identifiers come from configuration and \"Lintomatic does not add or rewrite any part of the name.\" Every finding line prints the identifier. The fixture describes no machine-readable format, and the HTML report's contents are not described, so this rests on the one-line output. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | One line per finding, with location and identifier, is printed to standard output \"whether or not the HTML report is enabled.\" The HTML is extra detail, which 5.3 permits the output to omit. |\n| 5.4 | Yes | The hosted dashboard shows nothing the command line does not print: \"every finding it shows is also printed by the command line.\" The same binary runs in CI. |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the identifier alone. For a project rule it prints the declared `doc` string. The \"No documentation declared\" case is a failure of 6.3, not 6.1. |\n| 6.2 | Yes | `explain` reads \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | **No** | Two bundled rules print \"No documentation declared.\" Their identifiers resolve to nothing. Quote: \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` can be turned off with `ignore_comments = false`, which is a disable route. This alone satisfies the clause. |\n\n**Verdict under section 8:** Lintomatic does not conform. It fails 6.3, a MUST, and section 8 requires every MUST in sections 4 to 7 to be met. The other graded MUSTs pass, but \"Partial [Conformance] MUST NOT be described as [Conformance].\" The SHOULDs and MAY in these sections (4.4, 6.4, 6.5, 7.2) are not counted, so the Lintomatic repository's missing identifier check and the absence of a reason requirement on the comment do not change the verdict.\n\n**Effect of 6.4:** No, it does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. The 6.3 failure stands on its own. 6.4 would have caught it mechanically, as the fixture's repository does not check it. The fixture does not say whether Lintomatic is shipped inside a toolchain, so any toolchain-level MUST is outside what I can grade here.\n\n## 4. Confusion\n\n- **7.2:** \"The [Detector] SHOULD NOT supply a default one, including each entry of a generated [Baseline].\" It is unclear what \"one\" refers back to. I read it as a default reason, but the sentence does not name one.\n- **8.1:** \"a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case.\" It is unclear where that record is kept when the detector has no declaration, since the sentence before says the duty \"falls only on a [Detector] that has one.\"","ttft_ms":36989,"type":"result","duration_ms":44319,"uuid":"c17c5fcb-070b-4281-9833-8f21f6554ef6","ttft_stream_ms":1029,"time_to_request_ms":470,"first_content_frame_ms":1030,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 066: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

The exact prompt every reader received, part 1 of 1

===== FILE: QUESTIONS.md =====
# Questions for a cold reader of DETECTOR-SPEC.md

You have been given `DETECTOR-SPEC.md` and the fixture `fixtures/lintomatic.md`, and nothing
else. Read the document once, then answer every question below in order. Quote the document
where a question asks for a quotation. Do not consult anything outside what you were given.

## 1. Restatement

In your own words and in at most six bullets, what does this document require of a detector?

## 2. Load-bearing statements

Answer each part of each question in a sentence or two, then quote the sentence or sentences of
the document you are relying on.

- 2a. What does it mean for a detector to conform, and can a detector that was written before
  this document existed, and has never heard of it, conform?
- 2b. A detector ships an inline ignore comment. What must the detector do about that route for
  it to conform, and is doing one of those things enough?
- 2c. Where must the documentation for a bundled rule's identifier live, at what version, and
  must it be reachable without network access?

## 3. Application

Grade Lintomatic 4.2, as described in the fixture, against every MUST clause in sections [4](../../DETECTOR-SPEC.md#4-authoring-rules) to [7](../../DETECTOR-SPEC.md#7-suppression):
[4.1](../../DETECTOR-SPEC.md#41-the-detector-must-support-bespoke-rules-written-by-the-project-that-runs-it), [4.2](../../DETECTOR-SPEC.md#42-the-detector-must-provide-a-harness-that-runs-a-single-rule-against-supplied-code), [4.3](../../DETECTOR-SPEC.md#43-the-detector-must-allow-a-rule-to-carry-a-stable-identifier-and-must-print-it-with-every-finding), [5.1](../../DETECTOR-SPEC.md#51-the-detector-must-be-invocable-by-the-practitioner-locally-with-no-infrastructure), [5.2](../../DETECTOR-SPEC.md#52-the-detector-must-support-invocation-over-a-subset-at-minimum-a-single-file), [5.3](../../DETECTOR-SPEC.md#53-the-result-must-reach-the-practitioner-in-the-output-of-the-command-they-ran), [5.4](../../DETECTOR-SPEC.md#54-a-finding-must-not-be-reportable-only-through-a-hosted-service-licence-tier-or-ci-only-mode-the-practitioner-cannot-invoke-locally), [6.1](../../DETECTOR-SPEC.md#61-the-detector-must-provide-a-mechanism-that-resolves-a-printed-identifier-to-its-documentation), [6.2](../../DETECTOR-SPEC.md#62-resolution-of-a-bundled-rules-identifier-must-work-from-the-installed-copy-without-network-access), [6.3](../../DETECTOR-SPEC.md#63-a-bundled-rules-documentation-must-ship-with-the-rule-at-a-version-tracked-together), [7.1](../../DETECTOR-SPEC.md#71-a-detector-may-offer-an-inline-suppression-route-but-must-make-it-detectable-or-disableable). For each give Yes, Partial or No and one
line of reasoning. Then state whether Lintomatic conforms under section [8](../../DETECTOR-SPEC.md#8-conformance), and why. Finally,
state whether clause [6.4](../../DETECTOR-SPEC.md#64-the-detector-should-fail-its-own-release-if-a-bundled-rule-lacks-resolvable-documentation) changes the verdict, and why.

## 4. Confusion

Quote any passage you found confusing on your one reading, with its clause number. Do not say what
would make it clearer and do not propose any change. Write "none" if there was none.

===== FILE: DETECTOR-SPEC.md =====
# Defence Before Fix: Detector Specification

**Version**: 1.0.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the toolchain specification](TOOLING-SPEC.md), version 0.2.0
**Author**: [Joseph Edmonds](https://ltscommerce.dev), [Edmonds Commerce](https://edmondscommerce.co.uk)
**Coined**: 22 February 2026, in [the original article](https://ltscommerce.dev/articles/defence-before-fix-static-analysis)

## 1. What this document is for

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are to be interpreted as
described in RFC 2119.

[The method specification](SPEC.md) states what a [Practitioner] does when a
[Defect] is found. This document states what a [Detector] must offer so that they
can do it: write a [Rule], prove it, run it and resolve what it prints. It is addressed to
whoever maintains a [Detector], which the method specification defines as a tool that reads
code without executing it and reports occurrences of a pattern.

A [Detector] is one part of a project's [Toolchain], and this document judges it
on what it offers alone. What the assembled [Toolchain] of a project must add on top, the
[Project record], the listing of active [Defences] and the
governance of [Suppression], is stated in [the toolchain specification](TOOLING-SPEC.md).
The two are separable because they are built by different people: a [Detector] is authored once
and installed into projects its maintainer will never see, whilst governance is decided by each
project for itself. A document that asked a [Detector] to enforce a project's governance would
fail every [Detector] in use and would not make any project better governed.

**The governing principle**: where the method specification requires a [Practitioner] to do
something with a [Rule], a [Conforming] [Detector] MUST make that possible
without the project building the mechanism first. A [Detector] that leaves the project to
construct the means has moved the obligation rather than met it.

## 2. Terminology

Terms from the method specification carry over unchanged. Every capitalised term links to its
definition; the ones this document leans on most are, in short:

| Term           | In one line                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| [Detector]     | A tool that reads code without executing it and reports what it finds          |
| [Rule]         | One check a [Detector] evaluates                                               |
| [Message]      | The text a [Rule] prints when it fires                                         |
| [Identifier]   | The stable name printed with a finding that leads to its documentation         |
| [Practitioner] | Whoever is doing the work, a person or an [Agent]                              |
| [Toolchain]    | Everything a project assembles to run its checks through, [Detectors] included |
| [Suppression]  | Making a finding go away without fixing it                                     |
| [Baseline]     | A recorded set of existing findings a [Rule] is told to ignore                 |

These are additional.

#### Rule author

Whoever writes a [Rule]. May be the [Detector]'s maintainer, a [Toolchain]'s maintainer or the project that runs it.

#### Bundled rule

A [Rule] the [Detector] ships, or fetches on the [Practitioner]'s behalf from a source the [Detector]'s maintainer controls. Its [Rule author] will never see the codebases it runs in, so everything a [Practitioner] needs in order to act on it has to travel with it.

#### Harness

The route by which one [Rule] is run against supplied code and its findings observed, without the project's own test suite and without every other [Rule] running alongside it.

The distinction between a [Bundled rule] and a project's own [Rule] matters throughout.
The [Detector] owns the documentation of the first and can be held to shipping it; it cannot
know the documentation of the second, and what it owes there is the mechanism that lets the project
attach its own.

## 3. The division of responsibility

Each mechanism the method needs has two halves. Stating only one of them is what produces a
[Detector] that is *nearly* usable.

| Requirement                          | The [Detector] MUST provide                             | The [Rule author] supplies                              |
| ------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------- |
| Bespoke [Rules]                      | The authoring and registration route                    | The [Rules]                                             |
| The red proof                        | A [Harness]                                             | The [Fixture] and the red run                           |
| Running the [Rule]                   | A local invocation, including subsets                   | Running it                                              |
| The [Identifier]                     | A place to carry it, and printing it with every finding | Choosing it once                                        |
| Resolution of a [Bundled rule]       | The lookup, and the documentation, on disk              | Nothing                                                 |
| Resolution of a project's own [Rule] | The [Identifier] printed unaltered                      | The documentation and, with the [Toolchain], the lookup |
| Inline [Suppression]                 | A route the project can detect or disable               | The decision whether to forbid it                       |

Read down the middle column and the shape of a [Conforming] [Detector] is already
visible. Read across any row and the failure mode is visible too: either half alone leaves the
[Practitioner] stuck.

## 4. Authoring rules

### 4.1 The detector MUST support bespoke rules written by the project that runs it

Configuration of an existing [Rule] set is not sufficient. The project must be able to express a
pattern the [Detector]'s authors have never anticipated, and register it so that it runs with
the same standing as a [Bundled rule].

**Why**: the method turns a specific [Defect] into a [Class] [Defence], and the
[Classes] that matter most to a project are the ones peculiar to it. A [Detector] offering
only a fixed catalogue can defend against the industry's known [Hazards] and none of the
project's own, which is the half that carries its institutional knowledge.

### 4.2 The detector MUST provide a harness that runs a single rule against supplied code

A [Harness] reports, for a given input, whether the [Rule] fired and what it printed, without
executing the project's own test suite and without the other [Rules] obscuring the answer.
This applies to every [Rule] the [Detector] runs, bundled or bespoke; a
[Detector] failing 4.1 is graded here on its [Bundled rules].

**Why**: clause 3.3 of the method specification requires the [Rule] to be proven by making it go
red. A [Practitioner] who can only observe a [Rule]'s behaviour by running every
[Rule] over the whole codebase cannot demonstrate that a [Rule] fires on the pattern rather
than on something incidental.

### 4.3 The detector MUST allow a rule to carry a stable identifier, and MUST print it with every finding

The [Identifier] MUST be stable across releases and MUST NOT be derived from the [Rule]'s
file path, [Class] name or position in a configuration file. The [Rule author] chooses it
once. The [Detector] MUST print it, unaltered, alongside every finding the [Rule]
reports, in its default output and in every machine-readable format it offers. A prefix the
[Detector] adds from the invoking directory or the [Rule]'s location is derived from
the file path. A namespace the [Rule author] assigns once in configuration is not.

| [Identifier]       | Where it comes from                                                         | Stable? |
| ------------------ | --------------------------------------------------------------------------- | ------- |
| `proj.no-raw-sql`  | Written once by the [Rule author] in configuration, printed as is           | Yes     |
| `LM-0107`          | Assigned once by the [Detector]'s maintainer at the [Rule]'s first release  | Yes     |
| `rules/no-raw-sql` | Produced from where the [Rule]'s file sits; changes when the file moves     | No      |
| `NoRawSqlRule`     | The [Rule]'s [Class] name; changes when the [Rule] is renamed               | No      |
| `rule 7`           | The [Rule]'s position in a configuration file; changes when one is inserted | No      |

**Why**: the [Identifier] is the only string that reaches the [Practitioner] and the
only key their lookup can use. An [Identifier] that changes when a [Rule] is renamed
silently breaks every reference to it, including references written down by people who have left.
An [Identifier] the [Detector] carries but does not print is one the
[Practitioner] was never given.

### 4.4 The detector SHOULD enforce 4.3 with a rule of its own

A [Rule] over the [Rules], failing any [Rule] that reports without a stable
[Identifier].

**Why**: this is the method applied to the [Detector] itself, and it is cheap. The worked
example is `php-qa-ci`'s `RequireRuleIdentifierConstantRule`, a [Rule] hosted in PHPStan by a
[Toolchain] built on it: it rejects a magic-string [Identifier] and names the
constant to declare instead. Nothing about it needed to live outside the [Detector].

## 5. Reporting

### 5.1 The detector MUST be invocable by the practitioner, locally, with no infrastructure

**Why**: method specification clause 8.1. An [Agent] that cannot check its own work cannot
iterate against a [Defence], so the loop never closes in the turn where it is cheap to close.

### 5.2 The detector MUST support invocation over a subset, at minimum a single file

**Why**: 5.1 is satisfied in principle by a whole-codebase run and defeated in practice by one.
Checking a single edited file has to be fast enough to do on every edit, or it will not be done on
any.

### 5.3 The result MUST reach the practitioner in the output of the command they ran

Where the [Detector] writes fuller detail elsewhere, the invoked command's own output MUST
carry both a usable summary and the location of the remainder. The remainder is the findings
the summary leaves out. Where the output prints every finding, each with where it is and its
[Identifier], there is no remainder. A fuller report written elsewhere, such as a page with a
code snippet for each finding, only adds detail to findings the output already carries; it is
not a remainder, and the output need not name it.

**Why**: method specification clause 8.2. A report the [Practitioner] has to go and find is a
report that arrives after the decision it was meant to inform.

### 5.4 A finding MUST NOT be reportable only through a hosted service, licence tier or CI-only mode the practitioner cannot invoke locally

A finding that the [Detector] reports only through a hosted service, a licence tier or a
continuous-integration-only mode the [Practitioner] cannot invoke locally does not
[Conform], whatever the same [Rule] reports there.

**Why**: a [Rule] that fires only in an environment the [Practitioner] has no access to
teaches nobody anything and blocks them anyway, which is the worst combination available.

## 6. Resolving an identifier

### 6.1 The detector MUST provide a mechanism that resolves a printed identifier to its documentation

Two cases, by who wrote the [Rule]:

| The [Rule]        | Who supplies the documentation | What this clause asks of the [Detector]                                   |
| ----------------- | ------------------------------ | ------------------------------------------------------------------------- |
| A [Bundled rule]  | The [Detector]                 | Resolve the [Identifier], presented alone, to that documentation          |
| The project's own | The project                    | Print the [Identifier] unaltered; the lookup is the [Toolchain]'s to give |

In both, the mechanism is keyed on **the [Identifier] exactly as printed**. A command, an index
file or a URL are all acceptable forms. This clause asks for the mechanism, not for every page:
where the mechanism works but a [Bundled rule]'s [Identifier] has no documentation to resolve
to, that fails clause 6.3, not this clause. Each case in turn:

**For a [Bundled rule]**, the [Detector] supplies the documentation and the
lookup, and clauses 6.2 and 6.3 say where. The mechanism MUST resolve an [Identifier]
presented alone, because the reader who needs it most has the [Identifier] from a log, a
ticket or a colleague and not the [Message]. A documentation path printed in the [Message] is
therefore not enough on its own: it helps only a reader who has the [Message], and the
[Identifier] alone still leads nowhere.

**For a project's own [Rule]**, the [Detector] cannot know the documentation, so what
it owes is the half it can give: the [Identifier] printed unaltered under clause 4.3, and no
transformation of it. Where the [Identifier] is itself a URL, as method clause 3.6 allows,
the [Detector] prints that URL and has done what this clause asks. What this clause forbids is
a documentation path printed alongside a shorter [Identifier] that cannot be looked up on its
own. The lookup for such
a [Rule] is an obligation on the project's assembled [Toolchain], under clause 4.2
of the [toolchain specification](TOOLING-SPEC.md), and a [Detector] that offers it as well has
gone further than this clause asks.

**Why**: method specification clause 8.3 requires the [Identifier] to resolve without a human.
An index keyed on anything else does not resolve it. This is the most commonly failed clause in this
document and it fails in a specific way: documentation exists, is genuinely good, and is keyed on the
[Rule]'s [Class] or file name, which is a string the [Practitioner] was never
given. The lookup they can actually perform is the only one that counts.

### 6.2 Resolution of a bundled rule's identifier MUST work from the installed copy, without network access

**Why**: an [Agent] working offline, behind a proxy, or against a URL that has since moved needs
the answer to be on disk. A dependency the project already installed is on disk by definition. A
catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong
place.

### 6.3 A bundled rule's documentation MUST ship with the rule, at a version tracked together

Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1,
to a page in that shipped documentation. One [Identifier] that does not resolve fails this
clause, however many others do. A page per [Identifier] satisfies this; a page per family of
[Identifiers] MAY be used instead, under clause 6.5.

**Why**: method specification clause 3.6. A [Bundled rule] travels into codebases its author
will never see. If its documentation lives only in the [Detector]'s repository or on its
website, then every project that installs it is one link rot away from a [Rule] that blocks
without explaining.

The failure to guard against is not the absent document but the **dangling one**: a reference to
documentation that was planned and never written is worse than no reference, because it consumes
the [Practitioner]'s attention before failing them.

### 6.4 The detector SHOULD fail its own release if a bundled rule lacks resolvable documentation

An automated check over every [Identifier] a [Bundled rule] can print, applying the
family list or pattern of clause 6.5 where one is used, that blocks the release when any of them
lands on no page.

**Why**: clause 6.3 is the clause most easily believed to be satisfied whilst being broken, because
the documentation is written by the same person who wrote the [Rule] and its absence is
invisible from the inside. Where the [Detector] is shipped inside a [Toolchain],
the [toolchain specification](TOOLING-SPEC.md)'s self-audit makes this check a MUST for the [Toolchain]; a
[Detector] released on its own is asked for it as a SHOULD because the same [Class] of
[Defect], a [Rule] that blocks without explaining, is detectable mechanically there too.

### 6.5 One page MAY document a family of identifiers, and SHOULD name its members so a check can confirm them

Where several [Bundled rules] share a prefix, one page MAY document them all. Such a page
SHOULD let the check clause 6.4 asks for confirm that each member resolves to it. Two forms do
that and one does not:

| The page                                                                                                  | A check can confirm each member?          |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Lists every full [Identifier] in the family, `LM-0100`, `LM-0101`, and so on                              | Yes                                       |
| Carries a regular expression the check can run, `^LM-01[0-9]{2}$`, matching every member and nothing else | Yes                                       |
| Says in prose that everything under `LM-01` is documented here                                            | No: a person can infer it, a check cannot |

The list or the regular expression lives in the installed file, since clause 6.2 requires
resolution to work from the installed copy, not only in a rendered web page.

**Why**: a family page is a convenience for the author, and the cost of it must not fall on the
check. A page that a person can see covers `LM-0107` but a check cannot leaves clause 6.4 with
nothing to run.

## 7. Suppression

### 7.1 A detector MAY offer an inline suppression route, but MUST make it detectable or disableable

An inline ignore comment, a per-line directive and a generated [Baseline] are all such
routes. The [Detector] MAY ship them. For each one it MUST do at least one of two things, and either
alone satisfies this clause: make the route disableable by configuration; or make the route
detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a
mechanical check the [Detector] documents. Either lets a project which decides to forbid the
route enforce that decision. A route that can be neither switched off nor seen does not [Conform].

A route is detectable when the project can find every use of it. The first way is a bespoke
[Rule]: the project registers a [Rule] of its own, as clause 4.1 provides for, that matches the
route wherever it is used, and the [Detector] runs it like any other bespoke [Rule]; the
[Detector] ships no such [Rule] itself, and need not. That way is open only where the
[Detector]'s [Rules] can see the route: a [Detector] whose [Rules] never see comments cannot make
an ignore comment detectable this way. The second way is a mechanical check the [Detector]
documents, such as a text search for the route's spelling that the [Detector]'s documentation
gives.

**Why**: the method specification's position is that [Suppression] is an [Owner]
decision under its clause 3.4 and section 4, and an [Owner] cannot decide something they are
never shown. The [Detector] is not the [Owner] and does not know the project's
governance, so it is not asked to enforce it; what it is asked is not to hide the route. Every
[Detector] in wide use ships an inline ignore, and a clause that forbade them would fail all of
them without governing any project better. Whether the route is forbidden is the project's decision,
enforced through its [Toolchain] under clause 4.3 of the [toolchain specification](TOOLING-SPEC.md).

### 7.2 An inline suppression route SHOULD require a written reason

The [Detector] SHOULD reject, or be configurable to reject, an inline [Suppression]
that carries no reason, and SHOULD NOT supply a default one, including each entry of a generated
[Baseline].

**Why**: a [Suppression] without a reason is indistinguishable from one nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence costs the author a
minute at the moment they have the reason in mind, and it is the only thing that makes the
[Suppression] reviewable later. PHPStan's `reportIgnoresWithoutComments` is the shape of it.

## 8. Conformance

**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Detector]
that satisfies most of this document is in a normal and respectable condition; it is not
[Conforming], and describing it as such removes the only value the word has.

This document defines one level. The clauses of the method specification's section 8 that reach
beyond what sections 4 to 7 here already secure, the listing of active [Defences] and the
summary for an [Agent]'s context, are obligations on a project's assembled [Toolchain]
and are stated in the [toolchain specification](TOOLING-SPEC.md), so there is no separate [Agent]-support level
for a [Detector].

### 8.1 A maintainer MAY declare the version of this document the detector conforms to, and the declaration records known gaps

The declaration is machine-readable, in whatever form the [Detector]'s ecosystem uses to
record dependencies. The same declaration is where a gap against this document is recorded once it is
known: a [Detector] that declares a version and has learnt, from its own checks or from a
[Practitioner]'s report under the method's clause 3.2, that it fails a MUST in sections 4 to 7
MUST record that gap alongside that version, in the same file or one it names. A declaration
with a non-empty gap record is a statement of where the [Detector] stands and is not a claim of
[Conformance].

The declaration is optional, and so the duty above falls only on a [Detector] that has one; a
gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case. It is how a
maintainer claims [Conformance]; it is not a condition of it. A [Detector] that predates this document, or whose maintainer has never read
it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each
clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that
check and not on the claim. A declaration tells the reader what the maintainer believes and what they know to be missing;
the reader still runs the [Harness].

The shape is illustrative rather than prescribed. In a Composer manifest:

```json
"extra": {
  "defence-before-fix": {
    "method": "1.0.1",
    "detector": "1.0.0",
    "toolchain": null,
    "known-gaps": []
  }
}
```

In a package.json, the equivalent is a top-level `defenceBeforeFix` object with the same keys. A
[Detector] that is not also shipped as a [Toolchain] leaves `toolchain` empty;
a project that ships both declares both. Each entry in `known-gaps` names the clause and states the
gap in a sentence.

**Why**: a [Conformance] claim in a README is a sentence; a claim in a manifest is a fact about
a specific installed artefact, checkable by anyone, including mechanically, and it fixes what
"[Conforming]" meant at the point the claim was made. Making the claim a condition of
[Conformance], though, would mean a [Detector] with every mechanism in place could
never [Conform] until its maintainer had heard of this document, which grades the
maintainer's reading rather than the [Detector].

## 9. Relationship to the other specifications

This document adds no obligations to a [Practitioner] and relaxes none. Every clause here
exists to make a clause of the method specification achievable with a [Detector] in hand.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes one piece of the equipment.

The [toolchain specification](TOOLING-SPEC.md) states what a project's assembled [Toolchain] must offer beyond
what each [Detector] in it offers, and it requires every [Detector] a [Defence]
is routed through to [Conform] to this one. A [Detector] shipped inside a
[Toolchain] is measured here as a [Detector] and there as part of the
[Toolchain]; the two verdicts are separate and neither implies the other.

Nothing here requires a project to use a [Conforming] [Detector]. A project can
[Conform] to the method specification on a [Detector] that [Conforms] to
none of this, at the cost of building the missing mechanisms itself. This document exists so that it
does not have to.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[bundled rule]: #bundled-rule
[bundled rules]: #bundled-rule
[class]: SPEC.md#class
[classes]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[fixture]: SPEC.md#fixture
[harness]: #harness
[hazards]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[project record]: TOOLING-SPEC.md#project-record
[rule]: SPEC.md#rule
[rule author]: #rule-author
[rules]: SPEC.md#rule
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain

===== FILE: fixtures/lintomatic.md =====
# Fixture: Lintomatic 4.2

A fictional detector, described only as far as its documentation would describe it. Grade it
against the document you were given. Where the description does not say, answer from what is
written, not from what a real tool would probably do.

## What the documentation says

Lintomatic is a static analyser for the Zig language. It ships forty rules. A project can add its
own rules by writing a Zig module that implements the `Rule` interface and listing it in
`lintomatic.toml`; project rules are loaded on every run and are first class in every report.

The command `lintomatic check <path>` analyses a directory or a single file and prints one line
per finding to standard output:

```
src/db.zig:41:7  LM-0107  Result of fallible call discarded
src/db.zig:88:3  proj.no-raw-sql  Query built by string concatenation
```

Fuller detail, including a snippet, is written to `.lintomatic/report.html`. The one-line form is
printed whether or not the HTML report is enabled.

`lintomatic check --only <identifier> <path>` runs a single rule. It accepts any rule name,
bundled or project, and exits 1 when the rule fires, 0 when it does not, and 2 when the rule name
is unknown.

Rule identifiers for bundled rules are of the form `LM-NNNN` and are fixed at the rule's first
release. Project rules are identified by the name the project gives them in `lintomatic.toml`,
which the documentation recommends prefixing with `proj.`; Lintomatic does not add or rewrite
any part of the name.

`lintomatic explain <identifier>` prints the documentation for a bundled rule from the installed
package: what the rule finds, why, and the recommended construction. For a project rule it prints
the `doc` string the rule module declares, or `No documentation declared` when there is none.
The documentation is versioned with the package; there is no separate website.

Lintomatic honours the comment `// lintomatic-ignore <identifier>` on the line before a finding.
The comment can be disabled project-wide with `ignore_comments = false` in `lintomatic.toml`.
The comment takes no reason and the documentation does not mention one.

The tool runs locally with no account, no server and no network, and the same binary is what CI
runs. There is a hosted dashboard, sold separately, that aggregates reports across repositories;
every finding it shows is also printed by the command line.

Lintomatic's own repository runs `lintomatic check src` in CI but does not check that every
`LM-NNNN` identifier has an `explain` entry; two of the forty rules currently print
`No documentation declared`.

[LTSCommerce]

Run 073: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Command and working directory

ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt, each reader in a fresh empty directory made by mktemp -d outside the repository

Model version each reader reported

reader 1: claude-haiku-5-5
reader 2: claude-haiku-5-5
reader 3: claude-haiku-5-5
reader 4: claude-haiku-5-5
reader 5: claude-haiku-5-5

The delegated marker's task prompt

MODE: mark

Worktree: <worktree> (branch `editor/detector-route-rule`). The readers read commit d67174c. Read, at that commit and in that worktree: ACCEPTANCE.md in full (it is the process as pull request 22 proposes it, merged into this branch; the run is made under that process change before it merges, at commit bc6ae14, named here before the readers started), acceptance/runs/README.md, acceptance/detector/QUESTIONS.md, acceptance/detector/KEY.md, acceptance/fixtures/lintomatic.md and DETECTOR-SPEC.md. You may read acceptance/runs/066-detector-route-rule-run-3.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 073. Document: DETECTOR-SPEC.md. Change: detector route rule, pull request 23 (clause 7.1's detectable route is a bespoke rule the project writes for the detector under clause 4.1, with a paragraph on what detectable means; clause 8.1's gap duty falls only on a detector that declares a version; clause 5.3 says what the remainder is; clause 6.1 says it asks for the mechanism, a missing page failing 6.3, and that a path in the message is not enough on its own; section 2's table gains a Message row). Run 66 passed; the text then changed after run 69, a cohort of another change with this one merged in, in clause 5.3's obligation sentence (the location of the remainder owed only where the summary leaves a finding out) and clause 8.1's second paragraph (where a practitioner's record of a gap lives; a detector without a declaration can still be found to conform), so this is a fresh run. Pull request: 23, https://github.com/Defence-Before-Fix/defence-before-fix.github.io/pull/23. Run within the pull request: 4 (runs 60, 63 and 66 came before). Record file to write: <worktree>/acceptance/runs/073-detector-route-rule-run-4.md. Do not commit it.

Sheets: <run-dir>/sheet-1.md to sheet-5.md, each the `result` of reader-N.json. Prompt the readers received: <run-dir>/prompt.txt; its sha256 is 0df0b01c02c5d2fd83b37d218f88785980384c3a0ecadce92abf7088211c9249, and it is byte for byte the question set, DETECTOR-SPEC.md and the fixture at d67174c, each after one `===== FILE: <name> =====` line, one blank line between files. Model: every reader reported claude-haiku-5-5 (<run-dir>/models.txt); the cohort's model named for the run is claude-haiku-5-5. Every reader's JSON has is_error false and subtype success; no reader is set aside.

Facts the editor supplies for the record: cohort of five readers, none reused from any earlier run; each a separate `claude -p` process started through the `ccy-claude` wrapper (which only reattaches the session's credential) in a fresh empty directory made by `mktemp -d` outside any repository, with the packet on standard input, command `ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt`; no tools, no settings, no project context, no saved session; the machine applies no managed settings; the editor attests the rest of the isolation. Marked by a delegated marker, a fresh `dbf-spec-editor` agent (Claude Opus) given this instruction and its agent definition, having seen neither the drafting nor the review.

Text the change wrote or altered, for "Where a finding lies": the output of `git -C <worktree> diff 9e914fe d67174c -- DETECTOR-SPEC.md` (9e914fe is the merge base with `next`). Run it and read it. A finding in a paragraph that diff adds, rewords, moves, deletes a sentence from, or changes a word, term or link in, or that a reader sets against such a paragraph, blocks; any other finding is routed to acceptance/ROUTED.md, and the record says so for each.

Mark every sheet, keyed item by keyed item, by ACCEPTANCE.md's Marking section and the key alone. Write the record stating what acceptance/runs/README.md lists, in its order, with the marks table, each miss with the reader's reasoning in brief, every passage named under question 4 with its words or description, clause and readers, each finding and where it lies, any open point and the direction you marked it, the process-change commit bc6ae14, the verdict, and a placeholder line for the link to the posted sheets. Reply with the verdict and the findings only, under thirty lines.

The agent definition the marker ran under

---
name: dbf-spec-editor
description: Drafts, reviews, key-updates, marks or records a change to the Defence Before Fix specification, one mode per dispatch, following the specification repository's CONTRIBUTING.md, SCOPE.md and ACCEPTANCE.md exactly. Dispatched by the dbf-spec-change skill; it cannot run a cohort itself.
tools: Read, Write, Edit, Grep, Glob, Bash
model: opus
---

You work on one change to the Defence Before Fix specification, in the worktree path you are
given. The process is defined by that repository's `CONTRIBUTING.md`, `SCOPE.md`,
`ACCEPTANCE.md` and `acceptance/README.md`; read the ones your mode needs, in full, before you
act. You invent no steps. You never merge, push to `next` or `main`, release, tag or publish,
and you never change a question, threshold or fixture. Your prompt names one mode.

Write as the specification is written: British spelling, no em dashes, defined terms linked as
`spec-qa.py` requires, every clause or section number linked to its heading. Commit on the
worktree's branch.

## MODE: draft

1. Read `SCOPE.md`, `DECLINED.md`, and every clause the change touches, with the terminology
   entries they use.
2. Decide the kind. A change to the sentences carrying MUST, SHOULD or MAY in a numbered section
   or appendix is an obligation; anything else is a clarity edit.
3. For an obligation, answer the five SCOPE tests in a sentence or two each, and name the
   section the obligation extends. If a test fails, or an existing clause already covers it, say
   so and stop without editing.
4. Make the smallest edit that does the job, in the clause that owns the subject.
5. Add one line under `Unreleased` in `CHANGELOG.md`, saying what changed and why, with a
   placeholder `run NNN`. Change no version.
6. If Appendix A changed, run `python3 build-agent-surfaces.py` and commit its outputs.
7. Run `python3 spec-qa.py` and `python3 -m unittest discover -s tools -p 'test_*.py'`; both
   clean.
8. Reply with: kind, SCOPE answers, files changed, commit, QA result, and a filled
   `.github/PULL_REQUEST_TEMPLATE.md` body. Under forty lines.

## MODE: review

You have not seen the drafting. Read the whole changed document and the diff against
`origin/next`. Report, numbered, with clause numbers: contradictions with other clauses, terms
used outside their definition, a sentence a reader could take two ways, an obligation an owner
could not verify from the record. Do not edit.

## MODE: keys

Read `acceptance/README.md` and the `KEY.md` for each changed document. Update every quotation of
a changed sentence to the new wording, verbatim, in a new commit; run `python3 spec-qa.py` until
`key-quote-stale` is gone. If the change adds a load-bearing obligation no keyed question
covers, propose the question and its key in your reply; add it only if your prompt says the owner
has decided to.

## MODE: mark

You have not seen the drafting or the review. Read `ACCEPTANCE.md` in full, the `KEY.md` for the
document, the document at the commit named, and the sheets under `<run-dir>/`.

- Mark each sheet against the key, keyed item by keyed item, by the rules under "Marking" in
  `ACCEPTANCE.md` and nothing else: the key's required elements, accepted grades, conditions and
  wrong readings. Invent no judgement; where neither the rules nor the key settles a mark, mark
  it in the direction the open-point rule gives and record the point.
- A single miss under questions 1 and 3 counts against the document only where the key names
  that reading; say which.
- For question 4, record every passage named, with its words or description and its clause.
  Group the passages by paragraph, count the readers, and for each finding say whether it lies in
  text the change wrote or altered, read against the diff the prompt gives you, or is routed to
  `acceptance/ROUTED.md`. Ignore any suggestion a reader volunteers.
- Apply the pass criteria exactly.
- Write `acceptance/runs/NNN-<slug>-run-<k>.md` stating what `acceptance/runs/README.md` lists,
  in its order. Do not commit it. Reply with the verdict and the findings only.

## MODE: record

Commit the run record, replace the `run NNN` placeholder in `Unreleased` with a link to it, and
for an obligation set the document header to `<next version>-dev, unpublished` in the same
commit if it still names a published version. Run `python3 spec-qa.py` and
`python3 tools/changes.py --base origin/next`; both clean. Reply with the commit.

[LTSCommerce]

Run 073: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Answer sheets, each reader's whole output as its process returned it

reader-1

{"duration_api_ms":33419,"stop_reason":"end_turn","session_id":"1cd3150e-033d-477a-83eb-34f1fc7f0253","total_cost_usd":0.0063135299999999995,"usage":{"input_tokens":2,"cache_creation_input_tokens":11309,"cache_read_input_tokens":2153,"output_tokens":8060,"output_tokens_details":{"thinking_tokens":6071},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11309,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":8060,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11309,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11309},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":8060,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11309,"webSearchRequests":0,"costUSD":0.0063135299999999995,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":6071,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- Let a project write its own rules and run them with the same standing as bundled rules (4.1).\n- Provide a harness that runs one rule against supplied code and shows whether it fired and what it printed (4.2).\n- Let each rule carry a stable identifier, not derived from its path, class name or position, and print it unaltered with every finding, including in every machine-readable format (4.3).\n- Run locally, including on a single file, put results in the invoked command's output, and never make a finding reportable only through a hosted, licence-tier or CI-only route (5.1–5.4).\n- Resolve a printed identifier on its own to its documentation. For bundled rules, that documentation ships on disk at the installed version, works offline, and covers every identifier the rule can print (6.1–6.3).\n- If an inline suppression route is offered, make it disableable or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document existed can conform, because conformance is judged by checking it against the clauses, not by whether its maintainer claims it.\n> \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\" (§8)\n\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\" (§8.1)\n\n**2b.** The detector must make the inline ignore route either disableable by configuration or detectable by a project rule or a documented mechanical check. Either one alone is enough, so disableability satisfies the clause without detectability.\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable…\" (§7.1)\n\n> \"A route that can be neither switched off nor seen does not [Conform].\" (§7.1)\n\n**2c.** The documentation for a bundled rule's identifier must ship with the installed rule, at a version tracked together with it, and must be reachable without network access.\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (§6.2)\n\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" (§6.3)\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | \"A project can add its own rules by writing a Zig module that implements the `Rule` interface and listing it in `lintomatic.toml`; project rules are loaded on every run and are first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` \"runs a single rule\" and exits 1 or 0 for fired or not fired. The fixture does not explicitly say `--only` prints its findings, but it describes `check` as printing one line per finding, so I read the output as included. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, \"fixed at the rule's first release\". Project names are chosen in configuration and \"Lintomatic does not add or rewrite any part of the name.\" The one-line form prints the identifier \"whether or not the HTML report is enabled.\" The fixture names no machine-readable format, so there is nothing to fail there. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | \"`lintomatic check <path>` analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line form on standard output carries every finding with its location and identifier, so there is no remainder. The HTML report only adds detail. |\n| 5.4 | Yes | \"every finding it shows is also printed by the command line\", and \"the same binary is what CI runs.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` resolves the identifier as printed, on its own. The mechanism works for all forty rules. Two of them resolve to \"No documentation declared\", which the spec assigns to 6.3, not 6.1. |\n| 6.2 | Yes | `explain` prints \"from the installed package\", and the documentation is \"versioned with the package; there is no separate website.\" |\n| 6.3 | No | Two bundled rules print `No documentation declared`. Read as bundled rules, since the forty rules are the bundled set, these identifiers resolve to no page. \"One Identifier that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `ignore_comments = false` in `lintomatic.toml` disables `// lintomatic-ignore`. Disableability alone satisfies the clause. |\n\n**Verdict under §8:** Lintomatic does not conform. It meets every MUST in sections 4 to 7 except 6.3, and §8 requires all of them. Under §8 it is therefore partial conformance, which the document says must not be described as conformance.\n\n**Effect of 6.4:** It does not change the verdict. 6.4 is a SHOULD, and §8 counts only MUSTs. Its absence (the fixture says the repository does not check that every identifier has an `explain` entry) is a second, separate gap that does not undo the 6.3 failure, and 6.3 would fail even if 6.4 were met. The toolchain specification would make the same check a MUST if Lintomatic were shipped inside a toolchain, but that is a separate verdict under a separate document.\n\n## 4. Confusion\n\n- §8.1: \"The same declaration is where a gap against this document is recorded once it is known: a [Detector] that declares a version and has learnt… that it fails a MUST in sections 4 to 7 MUST record that gap…\" A MUST sits in §8, while §8 defines conformance as meeting the MUSTs in sections 4 to 7. I could not tell from the text whether §8.1's MUST counts toward conformance.","ttft_ms":26695,"type":"result","duration_ms":34069,"uuid":"f3eda716-bab1-4ddb-9417-660b896dd12e","ttft_stream_ms":1288,"time_to_request_ms":643,"first_content_frame_ms":1288,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":51629,"stop_reason":"end_turn","session_id":"8351e281-49b3-4d18-a535-b31b04f16676","total_cost_usd":0.00863803,"usage":{"input_tokens":2,"cache_creation_input_tokens":11309,"cache_read_input_tokens":2153,"output_tokens":12709,"output_tokens_details":{"thinking_tokens":10842},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11309,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12709,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11309,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11309},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12709,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11309,"webSearchRequests":0,"costUSD":0.00863803,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10842,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules and register them with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code, bundled or bespoke (4.2).\n- Every rule carries a stable identifier, not derived from its path, class name, or position, and the detector prints it unaltered with every finding (4.3).\n- It must run locally with no infrastructure, including on a single file (5.1, 5.2), and every finding must reach the output of that command, not only a hosted service or CI-only mode (5.3, 5.4).\n- Each printed identifier must resolve to documentation. For bundled rules, the identifier alone must resolve offline from the installed copy, and every identifier the detector can print must have a page (6.1 to 6.3).\n- Any inline suppression route must be either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document, by a maintainer who has never read it, can conform. Its conformance is judged by checking it against the clauses, not by its own claim.\n\n> \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\"\n>\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7\"\n>\n> \"a [Detector] without one can still be found to [Conform].\"\n\n**2b.** The detector must make the route disableable by configuration or make it detectable. Either one alone is enough. Detectability by a bespoke rule is only available if the detector's rules can see comments. The 7.2 requirement for a written reason is a SHOULD, so it does not affect conformance.\n\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a mechanical check the [Detector] documents.\"\n>\n> \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\"\n\n**2c.** The documentation must ship inside the installed package, at the same version as the rule. It must be resolvable without network access. Every identifier the bundled rule can print must resolve to a page there.\n\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\"\n>\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together\"\n>\n> \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\"\n\n## 3. Application\n\nI take the fixture's \"forty rules\" to be the bundled rules, so the two that print `No documentation declared` are bundled.\n\n- **4.1: Yes.** Project rules are written as Zig modules, listed in `lintomatic.toml`, loaded every run, and \"first class in every report.\"\n- **4.2: Yes.** `--only` runs one rule on a given path and exits 1 or 0. The fixture does not explicitly say the printed output is limited to that rule, but the exit status answers \"did it fire.\"\n- **4.3: Yes.** Bundled IDs are fixed at first release, project IDs are the project's own config names printed as written, and the default output prints them. The fixture names no machine-readable format, and it does not say whether the HTML report carries identifiers.\n- **5.1: Yes.** \"runs locally with no account, no server and no network.\"\n- **5.2: Yes.** `lintomatic check <path>` accepts \"a single file.\"\n- **5.3: Yes.** The one-line form prints every finding with its location and identifier \"whether or not the HTML report is enabled,\" so there is no remainder.\n- **5.4: Yes.** The dashboard is sold separately, but \"every finding it shows is also printed by the command line,\" and CI runs the same binary.\n- **6.1: Yes.** `lintomatic explain <identifier>` is keyed on the identifier as printed, takes it alone, and covers both bundled and project rules.\n- **6.2: Yes.** `explain` reads \"from the installed package,\" and \"there is no separate website.\"\n- **6.3: No.** Two bundled identifiers resolve to \"No documentation declared,\" which is not a page. \"One [Identifier] that does not resolve fails this clause, however many others do.\"\n- **7.1: Yes.** `ignore_comments = false` in `lintomatic.toml` disables the route, which alone satisfies the clause.\n\n**Section 8:** Lintomatic does not conform, because 6.3 is a MUST that fails. The 6.3 failure is enough on its own.\n\n**Clause 6.4:** It does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture shows the failure 6.4 describes: the repository checks `check src` in CI but not that each `LM-NNNN` has an `explain` entry. Section 9 says the toolchain verdict is separate, and the fixture does not say whether Lintomatic ships inside a toolchain, so I did not grade that.\n\n## 4. Confusion\n\n- Clause 5.3: \"the invoked command's own output MUST carry a usable summary.\" The document does not say what makes a summary \"usable.\"\n- Clause 7.1: \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\" I could not tell from the text alone whether this is a property of the detector's API or of its rules.","ttft_ms":45470,"type":"result","duration_ms":52155,"uuid":"3956595f-dbd3-4da2-b383-2d75ebe2437f","ttft_stream_ms":1256,"time_to_request_ms":523,"first_content_frame_ms":1256,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":45457,"stop_reason":"end_turn","session_id":"a3a90b82-0bf9-457c-b439-abbc0c9077d7","total_cost_usd":0.007865029999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11309,"cache_read_input_tokens":2153,"output_tokens":11163,"output_tokens_details":{"thinking_tokens":9205},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11309,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11163,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11309,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11309},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11163,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11309,"webSearchRequests":0,"costUSD":0.007865029999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":9205,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, registered with the same standing as bundled rules (4.1).\n- A detector must provide a harness that runs a single rule against supplied code, for bundled or project rules (4.2).\n- Each rule carries a stable identifier, not derived from its path, class name or position, and the detector prints it unaltered with every finding (4.3).\n- The detector runs locally with no infrastructure, on a subset including a single file, and its findings appear in the output of the command the practitioner ran. No finding may be reportable only through a hosted service, licence tier or CI-only mode (5.1 to 5.4).\n- A mechanism resolves a printed identifier to its documentation. For bundled rules it works from the identifier alone, offline, and every identifier the detector can print must resolve to shipped documentation (6.1 to 6.3).\n- An inline suppression route, if offered, must be either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document, by a maintainer who has never read it, can still conform, because grading does not depend on the maintainer's claim.\n- \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\" (8)\n- \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7\" (8.1)\n\n**2b.** The detector must make the route either disableable by configuration or detectable. Doing one of these is enough, because either alone satisfies the clause. Detection by a bespoke rule only works if the detector's rules can see comments.\n- \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] … or by a mechanical check the [Detector] documents.\" (7.1)\n- \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\" (7.1)\n\n**2c.** The documentation must ship with the rule, at a version tracked together with it, and must be reachable from the installed copy without network access. Every identifier the rule can print must resolve to a page in that shipped documentation.\n- \"A [Bundled rule]'s documentation MUST ship with the rule, at a version tracked together\" (6.3)\n- \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\" (6.3)\n- \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (6.2)\n\n## 3. Application\n\nGrading uses only the fixture. The two rules that print `No documentation declared` are taken to be bundled rules, since the fixture says the detector ships forty rules and that the two are among the forty.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are Zig modules implementing the `Rule` interface, so they can express any pattern, and they are \"first class in every report.\" |\n| 4.2 | Partial | `--only` runs one rule, accepts bundled or project names, and exits 1 when it fires. The clause also requires the harness to report \"what it printed,\" and the fixture never says `--only` prints the finding line. This is the close call: it becomes Yes if `--only` output includes the finding. |\n| 4.3 | Yes | Project identifiers are written in configuration and printed as-is (\"Lintomatic does not add or rewrite any part of the name\"). Bundled `LM-NNNN` identifiers are \"fixed at the rule's first release.\" The fixture names no machine-readable format, so the machine-readable limb is vacuous as written. I do not count the HTML report as machine-readable, and the fixture does not say it carries identifiers. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line output \"prints one line per finding\" with location and identifier, so no remainder exists. The HTML report is only \"fuller detail.\" |\n| 5.4 | Yes | \"every finding it shows is also printed by the command line,\" and \"the same binary is what CI runs.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone. Project rules print their `doc` string or `No documentation declared`, and identifiers are printed unaltered. |\n| 6.2 | Yes | `explain` \"prints the documentation for a bundled rule from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | No | Two of the forty bundled rules print `No documentation declared`. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `ignore_comments = false` disables `// lintomatic-ignore` project-wide, which satisfies the clause alone. |\n\n**Conformance:** Lintomatic does not conform. Section 8 requires every MUST in sections 4 to 7 to hold, and 6.3 fails on two identifiers. It can be described as partly conforming, but not as conforming.\n\n**Effect of 6.4:** It does not change the verdict. 6.4 is a SHOULD, and section 8 tests only MUSTs, so the repository's lack of a release check is a separate gap. The verdict rests on the 6.3 failure. Section 6.4 also applies as a MUST only to a toolchain, and the fixture does not describe one.\n\n## 4. Confusion\n\nnone\n\nI did have to resolve the 4.2 close call above, but that comes from the fixture not stating what `--only` prints, not from the document.","ttft_ms":39245,"type":"result","duration_ms":45974,"uuid":"94737c2a-1659-41bf-9028-97302cb5562e","ttft_stream_ms":1251,"time_to_request_ms":510,"first_content_frame_ms":1251,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":53601,"stop_reason":"end_turn","session_id":"6532a9e2-6982-416e-aae2-38460d9dde88","total_cost_usd":0.009107029999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11309,"cache_read_input_tokens":2153,"output_tokens":13647,"output_tokens_details":{"thinking_tokens":11540},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11309,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13647,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11309,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11309},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13647,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11309,"webSearchRequests":0,"costUSD":0.009107029999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11540,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- Let the project write its own rules, registered with the same standing as bundled rules (4.1).\n- Provide a harness that runs one rule against supplied code and shows whether it fired and what it printed, for bundled and project rules (4.2).\n- Give each rule a stable identifier, not derived from its path, class name or position, and print it unaltered with every finding, in default and machine-readable output (4.3).\n- Run locally with no infrastructure, including on a single file, and put findings in the output of the command that was run (5.1 to 5.3).\n- Never make a finding reportable only through a hosted service, licence tier or CI-only mode (5.4).\n- Resolve a printed identifier to its documentation: for bundled rules, from the installed copy offline, with every identifier they can print resolving to a shipped page; for project rules, print the identifier unaltered. Offer inline suppression only if it can be disabled or detected (6.1 to 6.3, 7.1).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document can conform, because grading rests on evidence, not on the maintainer's claim. Section 8 says: \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\" And: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\"\n\n**2b.** For the inline ignore route, the detector must make it either disableable by configuration or detectable. Doing one of those is enough. Section 7.1 says: \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a mechanical check the [Detector] documents.\" The reason requirement in 7.2 is a SHOULD and does not bear on conformance.\n\n**2c.** The documentation must ship with the rule, at a version tracked with it, in a page per identifier or a family page under 6.5. Section 6.3 is headed: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" It must also be reachable offline. Section 6.2 is headed: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\" A website catalogue does not satisfy this: \"A catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong place.\"\n\n## 3. Application\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are written as a Zig module, listed in `lintomatic.toml`, and \"are first class in every report.\" |\n| 4.2 | Yes | `check --only` runs one rule, accepts bundled or project names, and exits 1 when it fires. The fixture does not say `--only` prints the finding lines, so I have assumed it prints them as `check` does. |\n| 4.3 | Yes | Bundled identifiers are fixed at first release. Project names are set in config and printed as given, with no rewriting. The fixture describes no machine-readable format beyond the one-line output, so nothing contradicts the clause. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line form is printed to standard output whether or not the HTML report is enabled, so no remainder pointer is needed. |\n| 5.4 | Yes | The same binary runs locally and in CI, and every dashboard finding is also printed by the command line. |\n| 6.1 | Yes | `explain <identifier>` takes the identifier alone. Project rules get their `doc` string or \"No documentation declared.\" The two bundled rules that print \"No documentation declared\" are a 6.3 matter, as 6.1 itself says. |\n| 6.2 | Yes | \"The documentation is versioned with the package; there is no separate website,\" and `explain` reads from the installed package. |\n| 6.3 | No | Two bundled rules' identifiers resolve to \"No documentation declared\" rather than to a page. Per the clause, \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `ignore_comments = false` disables the `// lintomatic-ignore` route by configuration. |\n\nI have taken the two rules printing \"No documentation declared\" to be bundled rules, because the fixture's sentence about them concerns `LM-NNNN` identifiers.\n\n**Conformance: No.** Section 8 requires every MUST in sections 4 to 7 to be met, and 6.3 is a MUST that fails.\n\n**Clause 6.4: it does not change the verdict.** It is a SHOULD, and section 8 counts only MUSTs. The fixture shows the gap it describes: Lintomatic's repository \"does not check that every `LM-NNNN` identifier has an `explain` entry.\" That is a SHOULD not met, which is not what breaks conformance. The fixture does not say whether Lintomatic ships inside a Toolchain. If it does, the toolchain specification would make 6.4 a MUST for that Toolchain, but I have not been given that specification, so I cannot judge the Toolchain.\n\n## 4. Confusion\n\n- **Section 1, \"The governing principle\":** \"a [Conforming] [Detector] MUST make that possible without the project building the mechanism first.\" This is a MUST, but it is unnumbered, sits outside sections 4 to 7, and section 8 counts only MUSTs in 4 to 7. I could not tell whether it bears on conformance.\n- **7.1:** \"That way is open only where the [Detector]'s [Rules] can see the route: a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\" The passage does not say whether a bespoke rule can see comments in a given detector, so I could not tell whether the detectable route was open to Lintomatic. This did not affect the grade, because 7.1 is met by the disableable route.","ttft_ms":47567,"type":"result","duration_ms":54068,"uuid":"e107a494-3f48-429a-b474-8da0d17d9393","ttft_stream_ms":1203,"time_to_request_ms":469,"first_content_frame_ms":1203,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":45159,"stop_reason":"end_turn","session_id":"b4c63768-4bcb-482d-86fe-4c056b51ee04","total_cost_usd":0.00794203,"usage":{"input_tokens":2,"cache_creation_input_tokens":11309,"cache_read_input_tokens":2153,"output_tokens":11317,"output_tokens_details":{"thinking_tokens":9364},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11309,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11317,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11309,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11309},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11317,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11309,"webSearchRequests":0,"costUSD":0.00794203,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":9364,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write and register its own rules, which then run with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and reports whether it fired and what it printed (4.2).\n- Each rule must carry a stable identifier, not derived from its file path, class name or config position, printed unaltered with every finding (4.3).\n- It must run locally with no infrastructure, on a subset down to a single file, with findings in the command's own output and not gated behind a hosted service, licence tier or CI-only mode (5.1–5.4).\n- A printed identifier must resolve to documentation. Bundled rules' docs ship with the rule at a version tracked together, resolve offline from the installed copy, and every identifier they can print must resolve (6.1–6.3).\n- Any inline suppression route must be disableable by configuration or detectable (7.1).\n\nA detector conforms when it satisfies every MUST in sections 4 to 7 (8).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document can conform, because the declaration is optional and the verdict rests on checking each clause.\n\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\"\n\n> \"The declaration is how a maintainer claims [Conformance]; it is not a condition of it, and a [Detector] without one can still be found to [Conform].\"\n\n**2b.** The detector must either make the route disableable by configuration or make it detectable. Doing either one is enough.\n\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a mechanical check the [Detector] documents.\"\n\nThe bespoke-rule route only works if the detector's rules can see comments: \"a [Detector] whose [Rules] never see comments cannot make an ignore comment detectable this way.\"\n\n**2c.** The documentation must ship with the rule, at the same version, and must be reachable from the installed copy without network access.\n\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\"\n\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together\"\n\n## 3. Application\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | A Zig module implementing `Rule`, listed in `lintomatic.toml`, is \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, and exits 1 when it fires. The fixture does not say the `--only` form prints finding lines, so I am assuming it does, as `check` does. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, fixed at first release. Project names are chosen once in config and \"Lintomatic does not add or rewrite any part of the name.\" Every one-line finding prints the identifier. No machine-readable format is described, so none is missed. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | One line per finding goes to standard output \"whether or not the HTML report is enabled.\" That output prints every finding, so there is no remainder. |\n| 5.4 | Yes | The same binary runs in CI. The dashboard shows only findings \"also printed by the command line.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone and also handles project rules. The two undocumented bundled rules fail 6.3, not this clause. |\n| 6.2 | Yes | \"The documentation is versioned with the package; there is no separate website,\" and `explain` reads from the installed package. |\n| 6.3 | No | \"Two of the forty rules currently print `No documentation declared`.\" Those two bundled identifiers resolve to no page. The clause says one unresolved identifier fails it \"however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` can be disabled with `ignore_comments = false`. |\n\n**Verdict under section 8:** Lintomatic does not conform. Clause 6.3 is a MUST and fails, and section 8 requires every MUST to be met. Partial conformance cannot be described as conformance. Clause 7.2 is a SHOULD and is not graded here.\n\n**Clause 6.4:** It does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture shows Lintomatic falls short of 6.4 as well, since its CI does not check for missing `explain` entries, but that is not a conformance failure. The fixture does not say Lintomatic ships inside a toolchain. If it did, the toolchain's self-audit would make the check a MUST for the toolchain, but section 9 keeps that verdict separate from the detector's.\n\n## 4. Confusion\n\n- **4.2:** \"a [Detector] failing 4.1 is graded here on its [Bundled rules].\" This sits oddly beside the sentence before it, which says the clause applies to every rule. I read it as a grading rule for a detector that fails 4.1, but I was not sure whether it changes what 4.2 demands.\n- **5.3:** \"The remainder is the findings the summary leaves out.\" I had to work out whether a fuller HTML report counts as a remainder. The sentences after it settle the point, but this definition did not do that on its own.","ttft_ms":39246,"type":"result","duration_ms":45475,"uuid":"d2926f15-9617-435d-b0e1-9f2e6f2b2613","ttft_stream_ms":986,"time_to_request_ms":310,"first_content_frame_ms":987,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 073: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

The exact prompt every reader received, part 1 of 1

===== FILE: QUESTIONS.md =====
# Questions for a cold reader of DETECTOR-SPEC.md

You have been given `DETECTOR-SPEC.md` and the fixture `fixtures/lintomatic.md`, and nothing
else. Read the document once, then answer every question below in order. Quote the document
where a question asks for a quotation. Do not consult anything outside what you were given.

## 1. Restatement

In your own words and in at most six bullets, what does this document require of a detector?

## 2. Load-bearing statements

Answer each part of each question in a sentence or two, then quote the sentence or sentences of
the document you are relying on.

- 2a. What does it mean for a detector to conform, and can a detector that was written before
  this document existed, and has never heard of it, conform?
- 2b. A detector ships an inline ignore comment. What must the detector do about that route for
  it to conform, and is doing one of those things enough?
- 2c. Where must the documentation for a bundled rule's identifier live, at what version, and
  must it be reachable without network access?

## 3. Application

Grade Lintomatic 4.2, as described in the fixture, against every MUST clause in sections [4](../../DETECTOR-SPEC.md#4-authoring-rules) to [7](../../DETECTOR-SPEC.md#7-suppression):
[4.1](../../DETECTOR-SPEC.md#41-the-detector-must-support-bespoke-rules-written-by-the-project-that-runs-it), [4.2](../../DETECTOR-SPEC.md#42-the-detector-must-provide-a-harness-that-runs-a-single-rule-against-supplied-code), [4.3](../../DETECTOR-SPEC.md#43-the-detector-must-allow-a-rule-to-carry-a-stable-identifier-and-must-print-it-with-every-finding), [5.1](../../DETECTOR-SPEC.md#51-the-detector-must-be-invocable-by-the-practitioner-locally-with-no-infrastructure), [5.2](../../DETECTOR-SPEC.md#52-the-detector-must-support-invocation-over-a-subset-at-minimum-a-single-file), [5.3](../../DETECTOR-SPEC.md#53-the-result-must-reach-the-practitioner-in-the-output-of-the-command-they-ran), [5.4](../../DETECTOR-SPEC.md#54-a-finding-must-not-be-reportable-only-through-a-hosted-service-licence-tier-or-ci-only-mode-the-practitioner-cannot-invoke-locally), [6.1](../../DETECTOR-SPEC.md#61-the-detector-must-provide-a-mechanism-that-resolves-a-printed-identifier-to-its-documentation), [6.2](../../DETECTOR-SPEC.md#62-resolution-of-a-bundled-rules-identifier-must-work-from-the-installed-copy-without-network-access), [6.3](../../DETECTOR-SPEC.md#63-a-bundled-rules-documentation-must-ship-with-the-rule-at-a-version-tracked-together), [7.1](../../DETECTOR-SPEC.md#71-a-detector-may-offer-an-inline-suppression-route-but-must-make-it-detectable-or-disableable). For each give Yes, Partial or No and one
line of reasoning. Then state whether Lintomatic conforms under section [8](../../DETECTOR-SPEC.md#8-conformance), and why. Finally,
state whether clause [6.4](../../DETECTOR-SPEC.md#64-the-detector-should-fail-its-own-release-if-a-bundled-rule-lacks-resolvable-documentation) changes the verdict, and why.

## 4. Confusion

Quote any passage you found confusing on your one reading, with its clause number. Do not say what
would make it clearer and do not propose any change. Write "none" if there was none.

===== FILE: DETECTOR-SPEC.md =====
# Defence Before Fix: Detector Specification

**Version**: 1.0.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the toolchain specification](TOOLING-SPEC.md), version 0.2.0
**Author**: [Joseph Edmonds](https://ltscommerce.dev), [Edmonds Commerce](https://edmondscommerce.co.uk)
**Coined**: 22 February 2026, in [the original article](https://ltscommerce.dev/articles/defence-before-fix-static-analysis)

## 1. What this document is for

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are to be interpreted as
described in RFC 2119.

[The method specification](SPEC.md) states what a [Practitioner] does when a
[Defect] is found. This document states what a [Detector] must offer so that they
can do it: write a [Rule], prove it, run it and resolve what it prints. It is addressed to
whoever maintains a [Detector], which the method specification defines as a tool that reads
code without executing it and reports occurrences of a pattern.

A [Detector] is one part of a project's [Toolchain], and this document judges it
on what it offers alone. What the assembled [Toolchain] of a project must add on top, the
[Project record], the listing of active [Defences] and the
governance of [Suppression], is stated in [the toolchain specification](TOOLING-SPEC.md).
The two are separable because they are built by different people: a [Detector] is authored once
and installed into projects its maintainer will never see, whilst governance is decided by each
project for itself. A document that asked a [Detector] to enforce a project's governance would
fail every [Detector] in use and would not make any project better governed.

**The governing principle**: where the method specification requires a [Practitioner] to do
something with a [Rule], a [Conforming] [Detector] MUST make that possible
without the project building the mechanism first. A [Detector] that leaves the project to
construct the means has moved the obligation rather than met it.

## 2. Terminology

Terms from the method specification carry over unchanged. Every capitalised term links to its
definition; the ones this document leans on most are, in short:

| Term           | In one line                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| [Detector]     | A tool that reads code without executing it and reports what it finds          |
| [Rule]         | One check a [Detector] evaluates                                               |
| [Message]      | The text a [Rule] prints when it fires                                         |
| [Identifier]   | The stable name printed with a finding that leads to its documentation         |
| [Practitioner] | Whoever is doing the work, a person or an [Agent]                              |
| [Toolchain]    | Everything a project assembles to run its checks through, [Detectors] included |
| [Suppression]  | Making a finding go away without fixing it                                     |
| [Baseline]     | A recorded set of existing findings a [Rule] is told to ignore                 |

These are additional.

#### Rule author

Whoever writes a [Rule]. May be the [Detector]'s maintainer, a [Toolchain]'s maintainer or the project that runs it.

#### Bundled rule

A [Rule] the [Detector] ships, or fetches on the [Practitioner]'s behalf from a source the [Detector]'s maintainer controls. Its [Rule author] will never see the codebases it runs in, so everything a [Practitioner] needs in order to act on it has to travel with it.

#### Harness

The route by which one [Rule] is run against supplied code and its findings observed, without the project's own test suite and without every other [Rule] running alongside it.

The distinction between a [Bundled rule] and a project's own [Rule] matters throughout.
The [Detector] owns the documentation of the first and can be held to shipping it; it cannot
know the documentation of the second, and what it owes there is the mechanism that lets the project
attach its own.

## 3. The division of responsibility

Each mechanism the method needs has two halves. Stating only one of them is what produces a
[Detector] that is *nearly* usable.

| Requirement                          | The [Detector] MUST provide                             | The [Rule author] supplies                              |
| ------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------- |
| Bespoke [Rules]                      | The authoring and registration route                    | The [Rules]                                             |
| The red proof                        | A [Harness]                                             | The [Fixture] and the red run                           |
| Running the [Rule]                   | A local invocation, including subsets                   | Running it                                              |
| The [Identifier]                     | A place to carry it, and printing it with every finding | Choosing it once                                        |
| Resolution of a [Bundled rule]       | The lookup, and the documentation, on disk              | Nothing                                                 |
| Resolution of a project's own [Rule] | The [Identifier] printed unaltered                      | The documentation and, with the [Toolchain], the lookup |
| Inline [Suppression]                 | A route the project can detect or disable               | The decision whether to forbid it                       |

Read down the middle column and the shape of a [Conforming] [Detector] is already
visible. Read across any row and the failure mode is visible too: either half alone leaves the
[Practitioner] stuck.

## 4. Authoring rules

### 4.1 The detector MUST support bespoke rules written by the project that runs it

Configuration of an existing [Rule] set is not sufficient. The project must be able to express a
pattern the [Detector]'s authors have never anticipated, and register it so that it runs with
the same standing as a [Bundled rule].

**Why**: the method turns a specific [Defect] into a [Class] [Defence], and the
[Classes] that matter most to a project are the ones peculiar to it. A [Detector] offering
only a fixed catalogue can defend against the industry's known [Hazards] and none of the
project's own, which is the half that carries its institutional knowledge.

### 4.2 The detector MUST provide a harness that runs a single rule against supplied code

A [Harness] reports, for a given input, whether the [Rule] fired and what it printed, without
executing the project's own test suite and without the other [Rules] obscuring the answer.
This applies to every [Rule] the [Detector] runs, bundled or bespoke; a
[Detector] failing 4.1 is graded here on its [Bundled rules].

**Why**: clause 3.3 of the method specification requires the [Rule] to be proven by making it go
red. A [Practitioner] who can only observe a [Rule]'s behaviour by running every
[Rule] over the whole codebase cannot demonstrate that a [Rule] fires on the pattern rather
than on something incidental.

### 4.3 The detector MUST allow a rule to carry a stable identifier, and MUST print it with every finding

The [Identifier] MUST be stable across releases and MUST NOT be derived from the [Rule]'s
file path, [Class] name or position in a configuration file. The [Rule author] chooses it
once. The [Detector] MUST print it, unaltered, alongside every finding the [Rule]
reports, in its default output and in every machine-readable format it offers. A prefix the
[Detector] adds from the invoking directory or the [Rule]'s location is derived from
the file path. A namespace the [Rule author] assigns once in configuration is not.

| [Identifier]       | Where it comes from                                                         | Stable? |
| ------------------ | --------------------------------------------------------------------------- | ------- |
| `proj.no-raw-sql`  | Written once by the [Rule author] in configuration, printed as is           | Yes     |
| `LM-0107`          | Assigned once by the [Detector]'s maintainer at the [Rule]'s first release  | Yes     |
| `rules/no-raw-sql` | Produced from where the [Rule]'s file sits; changes when the file moves     | No      |
| `NoRawSqlRule`     | The [Rule]'s [Class] name; changes when the [Rule] is renamed               | No      |
| `rule 7`           | The [Rule]'s position in a configuration file; changes when one is inserted | No      |

**Why**: the [Identifier] is the only string that reaches the [Practitioner] and the
only key their lookup can use. An [Identifier] that changes when a [Rule] is renamed
silently breaks every reference to it, including references written down by people who have left.
An [Identifier] the [Detector] carries but does not print is one the
[Practitioner] was never given.

### 4.4 The detector SHOULD enforce 4.3 with a rule of its own

A [Rule] over the [Rules], failing any [Rule] that reports without a stable
[Identifier].

**Why**: this is the method applied to the [Detector] itself, and it is cheap. The worked
example is `php-qa-ci`'s `RequireRuleIdentifierConstantRule`, a [Rule] hosted in PHPStan by a
[Toolchain] built on it: it rejects a magic-string [Identifier] and names the
constant to declare instead. Nothing about it needed to live outside the [Detector].

## 5. Reporting

### 5.1 The detector MUST be invocable by the practitioner, locally, with no infrastructure

**Why**: method specification clause 8.1. An [Agent] that cannot check its own work cannot
iterate against a [Defence], so the loop never closes in the turn where it is cheap to close.

### 5.2 The detector MUST support invocation over a subset, at minimum a single file

**Why**: 5.1 is satisfied in principle by a whole-codebase run and defeated in practice by one.
Checking a single edited file has to be fast enough to do on every edit, or it will not be done on
any.

### 5.3 The result MUST reach the practitioner in the output of the command they ran

Where the [Detector] writes fuller detail elsewhere, the invoked command's own output MUST
carry a usable summary and, where the summary leaves any finding out, the location of the
remainder. The remainder is the findings the summary leaves out. Where the output prints every finding, each with where it is and its
[Identifier], there is no remainder. A fuller report written elsewhere, such as a page with a
code snippet for each finding, only adds detail to findings the output already carries; it is
not a remainder, and the output need not name it.

**Why**: method specification clause 8.2. A report the [Practitioner] has to go and find is a
report that arrives after the decision it was meant to inform.

### 5.4 A finding MUST NOT be reportable only through a hosted service, licence tier or CI-only mode the practitioner cannot invoke locally

A finding that the [Detector] reports only through a hosted service, a licence tier or a
continuous-integration-only mode the [Practitioner] cannot invoke locally does not
[Conform], whatever the same [Rule] reports there.

**Why**: a [Rule] that fires only in an environment the [Practitioner] has no access to
teaches nobody anything and blocks them anyway, which is the worst combination available.

## 6. Resolving an identifier

### 6.1 The detector MUST provide a mechanism that resolves a printed identifier to its documentation

Two cases, by who wrote the [Rule]:

| The [Rule]        | Who supplies the documentation | What this clause asks of the [Detector]                                   |
| ----------------- | ------------------------------ | ------------------------------------------------------------------------- |
| A [Bundled rule]  | The [Detector]                 | Resolve the [Identifier], presented alone, to that documentation          |
| The project's own | The project                    | Print the [Identifier] unaltered; the lookup is the [Toolchain]'s to give |

In both, the mechanism is keyed on **the [Identifier] exactly as printed**. A command, an index
file or a URL are all acceptable forms. This clause asks for the mechanism, not for every page:
where the mechanism works but a [Bundled rule]'s [Identifier] has no documentation to resolve
to, that fails clause 6.3, not this clause. Each case in turn:

**For a [Bundled rule]**, the [Detector] supplies the documentation and the
lookup, and clauses 6.2 and 6.3 say where. The mechanism MUST resolve an [Identifier]
presented alone, because the reader who needs it most has the [Identifier] from a log, a
ticket or a colleague and not the [Message]. A documentation path printed in the [Message] is
therefore not enough on its own: it helps only a reader who has the [Message], and the
[Identifier] alone still leads nowhere.

**For a project's own [Rule]**, the [Detector] cannot know the documentation, so what
it owes is the half it can give: the [Identifier] printed unaltered under clause 4.3, and no
transformation of it. Where the [Identifier] is itself a URL, as method clause 3.6 allows,
the [Detector] prints that URL and has done what this clause asks. What this clause forbids is
a documentation path printed alongside a shorter [Identifier] that cannot be looked up on its
own. The lookup for such
a [Rule] is an obligation on the project's assembled [Toolchain], under clause 4.2
of the [toolchain specification](TOOLING-SPEC.md), and a [Detector] that offers it as well has
gone further than this clause asks.

**Why**: method specification clause 8.3 requires the [Identifier] to resolve without a human.
An index keyed on anything else does not resolve it. This is the most commonly failed clause in this
document and it fails in a specific way: documentation exists, is genuinely good, and is keyed on the
[Rule]'s [Class] or file name, which is a string the [Practitioner] was never
given. The lookup they can actually perform is the only one that counts.

### 6.2 Resolution of a bundled rule's identifier MUST work from the installed copy, without network access

**Why**: an [Agent] working offline, behind a proxy, or against a URL that has since moved needs
the answer to be on disk. A dependency the project already installed is on disk by definition. A
catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong
place.

### 6.3 A bundled rule's documentation MUST ship with the rule, at a version tracked together

Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1,
to a page in that shipped documentation. One [Identifier] that does not resolve fails this
clause, however many others do. A page per [Identifier] satisfies this; a page per family of
[Identifiers] MAY be used instead, under clause 6.5.

**Why**: method specification clause 3.6. A [Bundled rule] travels into codebases its author
will never see. If its documentation lives only in the [Detector]'s repository or on its
website, then every project that installs it is one link rot away from a [Rule] that blocks
without explaining.

The failure to guard against is not the absent document but the **dangling one**: a reference to
documentation that was planned and never written is worse than no reference, because it consumes
the [Practitioner]'s attention before failing them.

### 6.4 The detector SHOULD fail its own release if a bundled rule lacks resolvable documentation

An automated check over every [Identifier] a [Bundled rule] can print, applying the
family list or pattern of clause 6.5 where one is used, that blocks the release when any of them
lands on no page.

**Why**: clause 6.3 is the clause most easily believed to be satisfied whilst being broken, because
the documentation is written by the same person who wrote the [Rule] and its absence is
invisible from the inside. Where the [Detector] is shipped inside a [Toolchain],
the [toolchain specification](TOOLING-SPEC.md)'s self-audit makes this check a MUST for the [Toolchain]; a
[Detector] released on its own is asked for it as a SHOULD because the same [Class] of
[Defect], a [Rule] that blocks without explaining, is detectable mechanically there too.

### 6.5 One page MAY document a family of identifiers, and SHOULD name its members so a check can confirm them

Where several [Bundled rules] share a prefix, one page MAY document them all. Such a page
SHOULD let the check clause 6.4 asks for confirm that each member resolves to it. Two forms do
that and one does not:

| The page                                                                                                  | A check can confirm each member?          |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Lists every full [Identifier] in the family, `LM-0100`, `LM-0101`, and so on                              | Yes                                       |
| Carries a regular expression the check can run, `^LM-01[0-9]{2}$`, matching every member and nothing else | Yes                                       |
| Says in prose that everything under `LM-01` is documented here                                            | No: a person can infer it, a check cannot |

The list or the regular expression lives in the installed file, since clause 6.2 requires
resolution to work from the installed copy, not only in a rendered web page.

**Why**: a family page is a convenience for the author, and the cost of it must not fall on the
check. A page that a person can see covers `LM-0107` but a check cannot leaves clause 6.4 with
nothing to run.

## 7. Suppression

### 7.1 A detector MAY offer an inline suppression route, but MUST make it detectable or disableable

An inline ignore comment, a per-line directive and a generated [Baseline] are all such
routes. The [Detector] MAY ship them. For each one it MUST do at least one of two things, and either
alone satisfies this clause: make the route disableable by configuration; or make the route
detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a
mechanical check the [Detector] documents. Either lets a project which decides to forbid the
route enforce that decision. A route that can be neither switched off nor seen does not [Conform].

A route is detectable when the project can find every use of it. The first way is a bespoke
[Rule]: the project registers a [Rule] of its own, as clause 4.1 provides for, that matches the
route wherever it is used, and the [Detector] runs it like any other bespoke [Rule]; the
[Detector] ships no such [Rule] itself, and need not. That way is open only where the
[Detector]'s [Rules] can see the route: a [Detector] whose [Rules] never see comments cannot make
an ignore comment detectable this way. The second way is a mechanical check the [Detector]
documents, such as a text search for the route's spelling that the [Detector]'s documentation
gives.

**Why**: the method specification's position is that [Suppression] is an [Owner]
decision under its clause 3.4 and section 4, and an [Owner] cannot decide something they are
never shown. The [Detector] is not the [Owner] and does not know the project's
governance, so it is not asked to enforce it; what it is asked is not to hide the route. Every
[Detector] in wide use ships an inline ignore, and a clause that forbade them would fail all of
them without governing any project better. Whether the route is forbidden is the project's decision,
enforced through its [Toolchain] under clause 4.3 of the [toolchain specification](TOOLING-SPEC.md).

### 7.2 An inline suppression route SHOULD require a written reason

The [Detector] SHOULD reject, or be configurable to reject, an inline [Suppression]
that carries no reason, and SHOULD NOT supply a default one, including each entry of a generated
[Baseline].

**Why**: a [Suppression] without a reason is indistinguishable from one nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence costs the author a
minute at the moment they have the reason in mind, and it is the only thing that makes the
[Suppression] reviewable later. PHPStan's `reportIgnoresWithoutComments` is the shape of it.

## 8. Conformance

**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Detector]
that satisfies most of this document is in a normal and respectable condition; it is not
[Conforming], and describing it as such removes the only value the word has.

This document defines one level. The clauses of the method specification's section 8 that reach
beyond what sections 4 to 7 here already secure, the listing of active [Defences] and the
summary for an [Agent]'s context, are obligations on a project's assembled [Toolchain]
and are stated in the [toolchain specification](TOOLING-SPEC.md), so there is no separate [Agent]-support level
for a [Detector].

### 8.1 A maintainer MAY declare the version of this document the detector conforms to, and the declaration records known gaps

The declaration is machine-readable, in whatever form the [Detector]'s ecosystem uses to
record dependencies. The same declaration is where a gap against this document is recorded once it is
known: a [Detector] that declares a version and has learnt, from its own checks or from a
[Practitioner]'s report under the method's clause 3.2, that it fails a MUST in sections 4 to 7
MUST record that gap alongside that version, in the same file or one it names. A declaration
with a non-empty gap record is a statement of where the [Detector] stands and is not a claim of
[Conformance].

The declaration is optional, and so the duty above falls only on a [Detector] that has one; a
gap a [Practitioner] finds is recorded in their own project's record under the method's clause
3.2 in any case. The declaration is how a maintainer claims [Conformance]; it is not a condition
of it, and a [Detector] without one can still be found to [Conform]. A [Detector] that predates
this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence:
anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on
any [Detector], declared or not, rests on that check and not on the claim. A declaration tells the reader what the maintainer believes and what they know to be missing;
the reader still runs the [Harness].

The shape is illustrative rather than prescribed. In a Composer manifest:

```json
"extra": {
  "defence-before-fix": {
    "method": "1.0.1",
    "detector": "1.0.0",
    "toolchain": null,
    "known-gaps": []
  }
}
```

In a package.json, the equivalent is a top-level `defenceBeforeFix` object with the same keys. A
[Detector] that is not also shipped as a [Toolchain] leaves `toolchain` empty;
a project that ships both declares both. Each entry in `known-gaps` names the clause and states the
gap in a sentence.

**Why**: a [Conformance] claim in a README is a sentence; a claim in a manifest is a fact about
a specific installed artefact, checkable by anyone, including mechanically, and it fixes what
"[Conforming]" meant at the point the claim was made. Making the claim a condition of
[Conformance], though, would mean a [Detector] with every mechanism in place could
never [Conform] until its maintainer had heard of this document, which grades the
maintainer's reading rather than the [Detector].

## 9. Relationship to the other specifications

This document adds no obligations to a [Practitioner] and relaxes none. Every clause here
exists to make a clause of the method specification achievable with a [Detector] in hand.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes one piece of the equipment.

The [toolchain specification](TOOLING-SPEC.md) states what a project's assembled [Toolchain] must offer beyond
what each [Detector] in it offers, and it requires every [Detector] a [Defence]
is routed through to [Conform] to this one. A [Detector] shipped inside a
[Toolchain] is measured here as a [Detector] and there as part of the
[Toolchain]; the two verdicts are separate and neither implies the other.

Nothing here requires a project to use a [Conforming] [Detector]. A project can
[Conform] to the method specification on a [Detector] that [Conforms] to
none of this, at the cost of building the missing mechanisms itself. This document exists so that it
does not have to.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[bundled rule]: #bundled-rule
[bundled rules]: #bundled-rule
[class]: SPEC.md#class
[classes]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[fixture]: SPEC.md#fixture
[harness]: #harness
[hazards]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[project record]: TOOLING-SPEC.md#project-record
[rule]: SPEC.md#rule
[rule author]: #rule-author
[rules]: SPEC.md#rule
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain

===== FILE: fixtures/lintomatic.md =====
# Fixture: Lintomatic 4.2

A fictional detector, described only as far as its documentation would describe it. Grade it
against the document you were given. Where the description does not say, answer from what is
written, not from what a real tool would probably do.

## What the documentation says

Lintomatic is a static analyser for the Zig language. It ships forty rules. A project can add its
own rules by writing a Zig module that implements the `Rule` interface and listing it in
`lintomatic.toml`; project rules are loaded on every run and are first class in every report.

The command `lintomatic check <path>` analyses a directory or a single file and prints one line
per finding to standard output:

```
src/db.zig:41:7  LM-0107  Result of fallible call discarded
src/db.zig:88:3  proj.no-raw-sql  Query built by string concatenation
```

Fuller detail, including a snippet, is written to `.lintomatic/report.html`. The one-line form is
printed whether or not the HTML report is enabled.

`lintomatic check --only <identifier> <path>` runs a single rule. It accepts any rule name,
bundled or project, and exits 1 when the rule fires, 0 when it does not, and 2 when the rule name
is unknown.

Rule identifiers for bundled rules are of the form `LM-NNNN` and are fixed at the rule's first
release. Project rules are identified by the name the project gives them in `lintomatic.toml`,
which the documentation recommends prefixing with `proj.`; Lintomatic does not add or rewrite
any part of the name.

`lintomatic explain <identifier>` prints the documentation for a bundled rule from the installed
package: what the rule finds, why, and the recommended construction. For a project rule it prints
the `doc` string the rule module declares, or `No documentation declared` when there is none.
The documentation is versioned with the package; there is no separate website.

Lintomatic honours the comment `// lintomatic-ignore <identifier>` on the line before a finding.
The comment can be disabled project-wide with `ignore_comments = false` in `lintomatic.toml`.
The comment takes no reason and the documentation does not mention one.

The tool runs locally with no account, no server and no network, and the same binary is what CI
runs. There is a hosted dashboard, sold separately, that aggregates reports across repositories;
every finding it shows is also printed by the command line.

Lintomatic's own repository runs `lintomatic check src` in CI but does not check that every
`LM-NNNN` identifier has an `explain` entry; two of the forty rules currently print
`No documentation declared`.

[LTSCommerce]

Run 077: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Command and working directory

ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt, each reader in a fresh empty directory made by mktemp -d outside the repository

Model version each reader reported

reader 1: claude-haiku-5-5
reader 2: claude-haiku-5-5
reader 3: claude-haiku-5-5
reader 4: claude-haiku-5-5
reader 5: claude-haiku-5-5

The delegated marker's task prompt

MODE: mark

Worktree: <worktree> (branch `editor/detector-route-rule`). The readers read commit dbdf841. Read, at that commit and in that worktree: ACCEPTANCE.md in full (it is the process as pull request 22 proposes it, merged into this branch; the run is made under that process change before it merges, at commit bc6ae14, named here before the readers started), acceptance/runs/README.md, acceptance/detector/QUESTIONS.md, acceptance/detector/KEY.md, acceptance/fixtures/lintomatic.md and DETECTOR-SPEC.md. You may read acceptance/runs/073-detector-route-rule-run-4.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 077. Document: DETECTOR-SPEC.md. Change: detector route rule, pull request 23 (clause 7.1's detectable route is a bespoke rule the project writes for the detector under clause 4.1, with a paragraph on what detectable means; clause 8.1's gap duty falls only on a detector that declares a version; clause 5.3 says what the remainder is; clause 6.1 says it asks for the mechanism, a missing page failing 6.3, and that a path in the message is not enough on its own; section 2's table gains a Message row). Run 73 failed on two findings, and the text then changed in the two paragraphs named: clause 5.3's paragraph now defines a usable summary (each finding carries where it is and its Identifier) and the remainder (the findings the summary leaves out; none where the output prints every finding; a fuller report written elsewhere is not one and need not be named), and clause 7.1's second paragraph now states the two ways a route is detectable in one paragraph (a bespoke Rule registered under clause 4.1, or a mechanical check the Detector documents), so this is a fresh run. Pull request: 23, https://github.com/Defence-Before-Fix/defence-before-fix.github.io/pull/23. Run within the pull request: 5 (runs 60, 63, 66 and 73 came before). Record file to write: <worktree>/acceptance/runs/077-detector-route-rule-run-5.md. Do not commit it.

Sheets: <run-dir>/sheet-1.md to sheet-5.md, each the `result` of reader-N.json. Prompt the readers received: <run-dir>/prompt.txt; its sha256 is 2a96d5b0c6339f5402c9883018d35c0353c42dfad581c94d9b80a8b428882bc9, and it is byte for byte the question set, DETECTOR-SPEC.md and the fixture at dbdf841, each after one `===== FILE: <name> =====` line, one blank line between files. Model: every reader reported claude-haiku-5-5 (<run-dir>/models.txt); the cohort's model named for the run is claude-haiku-5-5. Every reader's JSON has is_error false and subtype success; no reader is set aside.

Facts the editor supplies for the record: cohort of five readers, none reused from any earlier run; each a separate `claude -p` process started through the `ccy-claude` wrapper (which only reattaches the session's credential) in a fresh empty directory made by `mktemp -d` outside any repository, with the packet on standard input, command `ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt`; no tools, no settings, no project context, no saved session; the machine applies no managed settings; the editor attests the rest of the isolation. Marked by a delegated marker, a fresh `dbf-spec-editor` agent (Claude Opus) given this instruction and its agent definition, having seen neither the drafting nor the review.

Text the change wrote or altered, for "Where a finding lies": the output of `git -C <worktree> diff 9e914fe dbdf841 -- DETECTOR-SPEC.md` (9e914fe is the merge base with `next`). Run it and read it. A finding in a paragraph that diff adds, rewords, moves, deletes a sentence from, or changes a word, term or link in, or that a reader sets against such a paragraph, blocks; any other finding is routed to acceptance/ROUTED.md, and the record says so for each.

Mark every sheet, keyed item by keyed item, by ACCEPTANCE.md's Marking section and the key alone. Write the record stating what acceptance/runs/README.md lists, in its order, with the marks table, each miss with the reader's reasoning in brief, every passage named under question 4 with its words or description, clause and readers, each finding and where it lies, any open point and the direction you marked it, the process-change commit bc6ae14, the verdict, and a placeholder line for the link to the posted sheets. Reply with the verdict and the findings only, under thirty lines.

The agent definition the marker ran under

---
name: dbf-spec-editor
description: Drafts, reviews, key-updates, marks or records a change to the Defence Before Fix specification, one mode per dispatch, following the specification repository's CONTRIBUTING.md, SCOPE.md and ACCEPTANCE.md exactly. Dispatched by the dbf-spec-change skill; it cannot run a cohort itself.
tools: Read, Write, Edit, Grep, Glob, Bash
model: opus
---

You work on one change to the Defence Before Fix specification, in the worktree path you are
given. The process is defined by that repository's `CONTRIBUTING.md`, `SCOPE.md`,
`ACCEPTANCE.md` and `acceptance/README.md`; read the ones your mode needs, in full, before you
act. You invent no steps. You never merge, push to `next` or `main`, release, tag or publish,
and you never change a question, threshold or fixture. Your prompt names one mode.

Write as the specification is written: British spelling, no em dashes, defined terms linked as
`spec-qa.py` requires, every clause or section number linked to its heading. Commit on the
worktree's branch.

## MODE: draft

1. Read `SCOPE.md`, `DECLINED.md`, and every clause the change touches, with the terminology
   entries they use.
2. Decide the kind. A change to the sentences carrying MUST, SHOULD or MAY in a numbered section
   or appendix is an obligation; anything else is a clarity edit.
3. For an obligation, answer the five SCOPE tests in a sentence or two each, and name the
   section the obligation extends. If a test fails, or an existing clause already covers it, say
   so and stop without editing.
4. Make the smallest edit that does the job, in the clause that owns the subject.
5. Add one line under `Unreleased` in `CHANGELOG.md`, saying what changed and why, with a
   placeholder `run NNN`. Change no version.
6. If Appendix A changed, run `python3 build-agent-surfaces.py` and commit its outputs.
7. Run `python3 spec-qa.py` and `python3 -m unittest discover -s tools -p 'test_*.py'`; both
   clean.
8. Reply with: kind, SCOPE answers, files changed, commit, QA result, and a filled
   `.github/PULL_REQUEST_TEMPLATE.md` body. Under forty lines.

## MODE: review

You have not seen the drafting. Read the whole changed document and the diff against
`origin/next`. Report, numbered, with clause numbers: contradictions with other clauses, terms
used outside their definition, a sentence a reader could take two ways, an obligation an owner
could not verify from the record. Do not edit.

## MODE: keys

Read `acceptance/README.md` and the `KEY.md` for each changed document. Update every quotation of
a changed sentence to the new wording, verbatim, in a new commit; run `python3 spec-qa.py` until
`key-quote-stale` is gone. If the change adds a load-bearing obligation no keyed question
covers, propose the question and its key in your reply; add it only if your prompt says the owner
has decided to.

## MODE: mark

You have not seen the drafting or the review. Read `ACCEPTANCE.md` in full, the `KEY.md` for the
document, the document at the commit named, and the sheets under `<run-dir>/`.

- Mark each sheet against the key, keyed item by keyed item, by the rules under "Marking" in
  `ACCEPTANCE.md` and nothing else: the key's required elements, accepted grades, conditions and
  wrong readings. Invent no judgement; where neither the rules nor the key settles a mark, mark
  it in the direction the open-point rule gives and record the point.
- A single miss under questions 1 and 3 counts against the document only where the key names
  that reading; say which.
- For question 4, record every passage named, with its words or description and its clause.
  Group the passages by paragraph, count the readers, and for each finding say whether it lies in
  text the change wrote or altered, read against the diff the prompt gives you, or is routed to
  `acceptance/ROUTED.md`. Ignore any suggestion a reader volunteers.
- Apply the pass criteria exactly.
- Write `acceptance/runs/NNN-<slug>-run-<k>.md` stating what `acceptance/runs/README.md` lists,
  in its order. Do not commit it. Reply with the verdict and the findings only.

## MODE: record

Commit the run record, replace the `run NNN` placeholder in `Unreleased` with a link to it, and
for an obligation set the document header to `<next version>-dev, unpublished` in the same
commit if it still names a published version. Run `python3 spec-qa.py` and
`python3 tools/changes.py --base origin/next`; both clean. Reply with the commit.

[LTSCommerce]

Run 077: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Answer sheets, each reader's whole output as its process returned it

reader-1

{"duration_api_ms":53217,"stop_reason":"end_turn","session_id":"7b7be6a8-313a-4628-a191-41cfe9c41e68","total_cost_usd":0.00880073,"usage":{"input_tokens":2,"cache_creation_input_tokens":11255,"cache_read_input_tokens":2153,"output_tokens":13056,"output_tokens_details":{"thinking_tokens":10427},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11255,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13056,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11255,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11255},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13056,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11255,"webSearchRequests":0,"costUSD":0.00880073,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10427,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules and register them so they run with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and reports whether it fired and what it printed, for bundled and project rules alike (4.2).\n- Every rule has a stable identifier that is not derived from file path, class name or position. The detector prints it unaltered with every finding, in default and machine-readable output (4.3).\n- It must run locally with no infrastructure, over a subset down to a single file, and put a usable summary with each finding's location and identifier in the command's own output. No finding may be reportable only through a hosted, licence-tier or CI-only route (5.1–5.4).\n- A printed identifier must resolve to documentation via a lookup keyed on the identifier exactly as printed. Bundled rules' documentation ships in the installed package, works offline, and covers every identifier the rule can print (6.1–6.3).\n- An inline suppression route may exist, but it must be switchable off by configuration or detectable. A route that is neither does not conform (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document, by a maintainer who has never read it, can conform. Declaring a version is optional and is not a condition of conformance.\n\n- §8: \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\"\n- 8.1: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\"\n- 8.1: \"The declaration is how a maintainer claims [Conformance]; it is not a condition of it, and a [Detector] without one can still be found to [Conform].\"\n\n**2b.** The detector must do at least one of two things: make the route disableable by configuration, or make it detectable. Either one alone is enough.\n\n- 7.1: \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a mechanical check the [Detector] documents.\"\n- 7.1: \"A route that can be neither switched off nor seen does not [Conform].\"\n\nThe reason requirement in 7.2 is a SHOULD and does not bear on this.\n\n**2c.** The documentation must ship inside the installed package, at the same version as the rule, and must be reachable without network access. Lookup is keyed on the identifier as printed.\n\n- 6.3 heading: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\"\n- 6.2 heading: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\"\n- 6.1: \"the mechanism is keyed on **the [Identifier] exactly as printed**\" and \"The mechanism MUST resolve an [Identifier] presented alone.\"\n\n## 3. Application\n\nAssumption: the fixture says Lintomatic ships forty rules, so I read \"two of the forty rules currently print `No documentation declared`\" as referring to bundled rules.\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | \"A project can add its own rules by writing a Zig module that implements the `Rule` interface and listing it in `lintomatic.toml`; project rules are loaded on every run and are first class in every report.\" |\n| 4.2 | Yes | `--only <identifier> <path>` runs one rule, bundled or project, and exits 1, 0 or 2. The fixture does not explicitly say `--only` prints the finding line. I take it as the single-rule form of `check`, which prints one line per finding. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, \"fixed at the rule's first release\". Project identifiers are the name given in `lintomatic.toml`, and \"Lintomatic does not add or rewrite any part of the name.\" The one-line output prints them. No machine-readable format is mentioned, so the \"every machine-readable format\" limb has nothing to check. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | One line per finding on stdout, each with location and identifier. \"The one-line form is printed whether or not the HTML report is enabled.\" No findings are left out, so no remainder needs naming. |\n| 5.4 | Yes | The dashboard is sold separately, but \"every finding it shows is also printed by the command line\", and \"the same binary is what CI runs.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the identifier as printed. It returns bundled docs, or the project's `doc` string, and project names are printed unaltered. The two undocumented bundled rules are a 6.3 failure, not a 6.1 failure. |\n| 6.2 | Yes | \"The documentation is versioned with the package; there is no separate website.\" `explain` reads \"from the installed package.\" |\n| 6.3 | No | Two of the forty bundled rules print \"No documentation declared\". The clause states: \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `ignore_comments = false` in `lintomatic.toml` disables the route by configuration. |\n\nEvery MUST in sections 4 to 7 is in this table. The remaining clauses are SHOULDs or MAYs, so they do not affect the verdict. For information: 4.4 (identifier-checking rule) is not mentioned in the fixture, 6.4 (release check) is not done by Lintomatic's CI, and 7.2 (written reason) is not met, since the comment \"takes no reason.\"\n\n**Verdict under §8:** Lintomatic does not conform. It fails 6.3, and §8 requires every MUST in sections 4 to 7 to be met. Under §8 it is partial conformance, which must not be described as conformance.\n\n**Does 6.4 change the verdict?** No. Clause 6.4 is a SHOULD, so it is not part of the §8 definition. It would have caught the 6.3 failure, but the verdict already fails on 6.3, and adding a release check would not repair the missing documentation. The toolchain route in 6.4 does not apply, because the fixture does not say Lintomatic ships inside a Toolchain. Even if it did, §9 says \"the two verdicts are separate and neither implies the other,\" so a Toolchain obligation would not change the Detector's verdict.\n\n## 4. Confusion\n\n- **7.1, second paragraph:** \"The first way needs the [Detector]'s [Rules] to be able to match the route's text, so a [Detector] whose [Rules] never see comments offers only the second for an ignore comment.\" I could not tell cleanly how a project's bespoke rule relates to the detector's rule-matching capability here, given the earlier \"need not ship itself.\"\n- **6.4:** \"Where the [Detector] is shipped inside a [Toolchain], the [toolchain specification](TOOLING-SPEC.md)'s self-audit makes this check a MUST for the [Toolchain]; a [Detector] released on its own is asked for it as a SHOULD.\" The text does not say whether a Detector inside a Toolchain still carries the SHOULD for itself.\n- **Fixture, `explain` paragraph:** it says that for a project rule `explain` prints \"`No documentation declared` when there is none\", and later that two of the forty rules \"currently print `No documentation declared`.\" I read the second as bundled rules, which is load-bearing for the 6.3 grade.","ttft_ms":44619,"type":"result","duration_ms":53622,"uuid":"b01d7129-c811-426a-b999-73da4072ff4f","ttft_stream_ms":997,"time_to_request_ms":409,"first_content_frame_ms":997,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":47016,"stop_reason":"end_turn","session_id":"ad177ced-4a9c-4517-8bcc-045642f8ace3","total_cost_usd":0.00791103,"usage":{"input_tokens":2,"cache_creation_input_tokens":11254,"cache_read_input_tokens":2153,"output_tokens":11277,"output_tokens_details":{"thinking_tokens":9301},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11254,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11277,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11254,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11254},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11277,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11254,"webSearchRequests":0,"costUSD":0.00791103,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":9301,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, register them with the same standing as bundled rules, and run any single rule on supplied code (4.1, 4.2).\n- Each rule's identifier must be stable, chosen by its author, and printed unaltered with every finding, including in every machine-readable format (4.3).\n- The detector must run locally with no infrastructure, on a single file as well as a directory, and must print each finding with its location and identifier in the command's own output (5.1 to 5.3).\n- No finding may be reportable only through a hosted service, licence tier, or CI-only mode (5.4).\n- A printed identifier must resolve to its documentation when presented alone, and for bundled rules that documentation must be on disk, work offline, and ship with the rule at a tracked version, with every printable identifier covered (6.1 to 6.3).\n- An inline suppression route must be either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document, and never checked against it, can still conform, because grading rests on the evidence, not on the maintainer's claim.\n> \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\"\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\"\n\n**2b.** The detector must do at least one of two things: make the route disableable by configuration, or make it detectable. Doing either one is enough.\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] … or by a mechanical check the [Detector] documents.\"\n> \"A route that can be neither switched off nor seen does not [Conform].\"\n\n**2c.** The documentation for a bundled rule's identifier must be shipped with the rule, at a version tracked together with it, on disk. It must be reachable without network access.\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\"\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\"\n\n## 3. Application\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are written as Zig modules implementing `Rule`, registered in `lintomatic.toml`, and \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, and exits 1 or 0 on firing. The text does not explicitly say that `--only` prints the findings, so this rests on the same command printing them. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, \"fixed at the rule's first release.\" Project names come from configuration, and Lintomatic \"does not add or rewrite any part of the name.\" The one-line output prints them. The text describes no machine-readable format, so nothing offered is missing one. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | One line per finding goes to stdout, each with location and identifier. Nothing is left out, so no remainder needs naming. |\n| 5.4 | Yes | Every dashboard finding \"is also printed by the command line,\" and CI runs \"the same binary.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone and resolves it for bundled rules. For project rules it prints the declared doc string or `No documentation declared`. |\n| 6.2 | Yes | Documentation is \"from the installed package,\" \"versioned with the package,\" and \"there is no separate website.\" |\n| 6.3 | No | The forty bundled rules include two whose identifiers print `No documentation declared`, so those identifiers resolve to no shipped page. The clause says: \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` can be disabled project-wide with `ignore_comments = false`, which is disableable by configuration. |\n\n**Verdict:** Lintomatic does not conform. Under section 8 a detector conforms only if it satisfies every MUST in sections 4 to 7. Clause 6.3 is a MUST and fails, so the verdict stands even though the other MUSTs pass. Partial conformance cannot be described as conformance: \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Clause 6.4:** It does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. Lintomatic does not meet it either, since its repository \"does not check that every `LM-NNNN` identifier has an `explain` entry.\" That is the check that would have caught the 6.3 failure. The fixture does not say Lintomatic ships inside a toolchain, so I did not apply the toolchain-level MUST that the document mentions.\n\n## 4. Confusion\n\n- **5.3:** \"The remainder is the findings the summary leaves out: where the output prints every finding there is none, and a fuller report written elsewhere, such as a page with a code snippet for each finding, is not one and need not be named.\"\n\n  On my reading, \"is not one\" could refer to \"the remainder\" or to \"a summary.\" I resolved it by treating the fuller report as neither.\n\nSeveral defined terms, including [Conform], [Owner] and [Class], link to SPEC.md, which I did not have. I graded from DETECTOR-SPEC.md's own usage and did not rely on those definitions.","ttft_ms":40401,"type":"result","duration_ms":47437,"uuid":"612c846a-0b95-4596-a6ae-eaf51c443238","ttft_stream_ms":1142,"time_to_request_ms":416,"first_content_frame_ms":1143,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":51124,"stop_reason":"end_turn","session_id":"e37bd33a-ffe8-4e8b-a9c2-5a8f16998a54","total_cost_usd":0.00855153,"usage":{"input_tokens":2,"cache_creation_input_tokens":11254,"cache_read_input_tokens":2153,"output_tokens":12558,"output_tokens_details":{"thinking_tokens":10478},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11254,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12558,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11254,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11254},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12558,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11254,"webSearchRequests":0,"costUSD":0.00855153,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10478,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- Let the project write its own rules and register them with the same standing as bundled rules (4.1).\n- Provide a harness that runs one rule against supplied code, for bundled and project rules alike (4.2).\n- Give each rule a stable identifier, not derived from file path, class name or position, and print it unaltered with every finding (4.3).\n- Run locally with no infrastructure, down to a single file, and print results in the command's own output (5.1 to 5.3).\n- Never make a finding reportable only through a hosted service, licence tier or CI-only mode (5.4).\n- Resolve a printed identifier to its documentation. Bundled rules' documentation ships with the install, works offline, and covers every identifier the rule can print (6.1 to 6.3).\n- Make any inline suppression route either disableable or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document, and unaware of it, can still conform, because conformance can be graded on evidence rather than on the maintainer's claim.\n\n> \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\"\n>\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7\"\n\n**2b.** The detector must make the ignore comment either disableable by configuration or detectable, and doing either one is enough. A route that is neither switched off nor visible does not conform.\n\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause\"\n>\n> \"A route that can be neither switched off nor seen does not [Conform].\"\n\n**2c.** The documentation must ship with the rule, at a version tracked together with it, so it lives in the installed copy. It must be reachable with no network access, and every identifier the bundled rule can print must resolve to a page in it.\n\n> \"A [Bundled rule]'s documentation MUST ship with the rule, at a version tracked together\"\n>\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\"\n>\n> \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\"\n\n## 3. Application\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | A project writes a Zig module implementing `Rule`, lists it in `lintomatic.toml`, and it is \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, against a file or directory, and exits 1 on fire or 0 when it does not. |\n| 4.3 | Yes | Bundled `LM-NNNN` identifiers are fixed at first release, project names come from configuration, and Lintomatic does not rewrite them. The one-line output prints them. The fixture does not say whether the HTML report or the dashboard carries them, or whether any machine-readable format exists, so I graded on the default output. |\n| 5.1 | Yes | It \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | Each line gives file, line, column, identifier and message, and every finding is printed, so no remainder needs naming. |\n| 5.4 | Yes | \"The one-line form is printed whether or not the HTML report is enabled,\" and every dashboard finding \"is also printed by the command line.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone and resolves bundled rules to their docs and project rules to their `doc` string. The two undocumented bundled rules fail 6.3, not this clause. |\n| 6.2 | Yes | Documentation is read \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | No | Two of the forty bundled rules print `No documentation declared`, which resolves to no page. \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` can be switched off project-wide with `ignore_comments = false`. |\n\n**Verdict under section 8:** Lintomatic does not conform. Section 8 requires every MUST in sections 4 to 7 to hold, and 6.3 fails. The most Lintomatic can claim is partial conformance, which must not be described as conformance.\n\nOne point about the fixture needs stating. Its explain section says `No documentation declared` is printed for project rules, but its final paragraph says two of the forty bundled rules print it. I read the final paragraph as authoritative, because it names `LM-NNNN` identifiers and the forty rules are the bundled ones. If those two were project rules, 6.3 would pass and the verdict would change.\n\n**Clause 6.4:** It does not change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. Lintomatic's CI does not check explain coverage, so 6.4 is not met, which is a SHOULD gap. The 6.3 failure stands whether or not that check exists, since the defect is the dangling identifiers themselves.\n\n## 4. Confusion\n\n- **5.3:** \"The remainder is the findings the summary leaves out: where the output prints every finding there is none, and a fuller report written elsewhere, such as a page with a code snippet for each finding, is not one and need not be named.\" The double negative and the \"is not one\" pronoun took a second reading.\n- **6.1:** \"The lookup for such a [Rule] is an obligation on the project's assembled [Toolchain], under clause 4.2 of the [toolchain specification](TOOLING-SPEC.md).\" I had only `DETECTOR-SPEC.md`, so I could not check the referenced clause.\n- **7.1:** \"the method specification's position is that [Suppression] is an [Owner] decision under its clause 3.4 and section 4.\" It depends on definitions in `SPEC.md`, which I was not given. I inferred the meaning of [Owner] and [Class] from context.","ttft_ms":44439,"type":"result","duration_ms":51460,"uuid":"8c9883d2-4d4a-4603-b19d-d616d7ea52c2","ttft_stream_ms":938,"time_to_request_ms":336,"first_content_frame_ms":939,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":43089,"stop_reason":"end_turn","session_id":"1636d1e0-62a6-4a1f-93b2-62c3a307f004","total_cost_usd":0.00759083,"usage":{"input_tokens":2,"cache_creation_input_tokens":11253,"cache_read_input_tokens":2153,"output_tokens":10637,"output_tokens_details":{"thinking_tokens":8559},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11253,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":10637,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11253,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11253},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":10637,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11253,"webSearchRequests":0,"costUSD":0.00759083,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":8559,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let a project write its own rules, registered with the same standing as bundled rules (4.1), and must provide a harness that runs a single rule against supplied code (4.2).\n- Each rule carries a stable identifier chosen once by its author, not derived from its path, class name or position, and the detector prints it unaltered with every finding (4.3).\n- A practitioner must be able to run the detector locally, with no infrastructure, over a subset such as one file, and the command's own output must carry each finding with its location and identifier (5.1–5.3). No finding may be reportable only through a hosted service, licence tier or CI-only mode (5.4).\n- A printed identifier must resolve to its documentation. For bundled rules, the identifier alone must resolve, offline, from the installed copy, and every identifier the rule can print must have a page in shipped documentation at a tracked version (6.1–6.3).\n- If the detector offers an inline suppression route, it must be either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document, and unaware of it, can still conform, because grading rests on checking the detector against each clause, not on a declaration.\n> \"A [Detector] [Conforms] if it satisfies every MUST in sections 4 to 7.\" (§8)\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7\" (§8.1)\n> \"a [Detector] without one can still be found to [Conform].\" (§8.1)\n\n**2b.** The detector must do at least one of two things. It can make the route disableable by configuration, or make it detectable. Doing either one is enough. If its rules never see comments, the only detectability route for an ignore comment is a documented mechanical check.\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause\" (§7.1)\n> \"a [Detector] whose [Rules] never see comments offers only the second for an ignore comment.\" (§7.1)\n\n**2c.** The documentation must ship inside the installed package, at a version tracked together with the rule. It must be readable without network access. Every identifier the bundled rule can print must resolve to a page in that shipped documentation.\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (§6.2)\n> \"A bundled rule's documentation MUST ship with the rule, at a version tracked together\" (§6.3)\n> \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\" (§6.3)\n\n## 3. Application\n\nThe document's MUST clauses in sections 4 to 7 are 4.1, 4.2, 4.3, 5.1–5.4, 6.1–6.3 and 7.1. Clauses 4.4, 6.4, 6.5 and 7.2 are SHOULD or MAY, so they are not graded here.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | \"A project can add its own rules by writing a Zig module that implements the `Rule` interface ... project rules are loaded on every run and are first class in every report.\" |\n| 4.2 | Partial | `--only` runs a single rule and exits 1 when it fires, which covers \"whether the Rule fired\". The documentation never says a single-rule run prints its findings, so \"what it printed\" is not established by the text. |\n| 4.3 | Yes | `LM-NNNN` is \"fixed at the rule's first release\", project names come from configuration, and \"Lintomatic does not add or rewrite any part of the name\". The one-line output prints the identifier. No other machine-readable format is described. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | \"`lintomatic check <path>` analyses a directory or a single file.\" |\n| 5.3 | Yes | Each output line gives location and identifier, and \"one line per finding\" is printed \"whether or not the HTML report is enabled\", so nothing is left out and no remainder pointer is needed. |\n| 5.4 | Yes | The same binary runs in CI, and \"every finding [the hosted dashboard] shows is also printed by the command line.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` resolves a bundled rule's identifier presented alone, and for project rules prints the declared `doc` string or `No documentation declared`. |\n| 6.2 | Yes | Documentation is read \"from the installed package\", \"versioned with the package; there is no separate website.\" |\n| 6.3 | No | The package ships forty rules, and \"two of the forty rules currently print `No documentation declared`\". Those are bundled identifiers that resolve to no documentation. The clause says one unresolved identifier fails it. |\n| 7.1 | Yes | The inline comment `// lintomatic-ignore` \"can be disabled project-wide with `ignore_comments = false`\", which is disableable by configuration. |\n\n**Conformance:** Lintomatic does not conform. Section 8 requires every MUST in sections 4 to 7 to be satisfied, and 6.3 is not. Two bundled identifiers resolve to no documentation. This is the only MUST failure I found.\n\n**Does 6.4 change the verdict?** No. 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture says Lintomatic's CI \"does not check that every `LM-NNNN` identifier has an `explain` entry\", so 6.4's SHOULD is unmet as well. That is the check that would have caught the 6.3 failure, but it does not add a second ground for non-conformance. The fixture also doesn't say Lintomatic ships inside a Toolchain, so 6.4's MUST variant does not apply here.\n\n## 4. Confusion\n\n- §5.3: \"where the output prints every finding there is none, and a fuller report written elsewhere, such as a page with a code snippet for each finding, is not one and need not be named.\" On my reading, \"one\" refers to the remainder, but the word is ambiguous here.","ttft_ms":36080,"type":"result","duration_ms":43462,"uuid":"b3609de4-7922-487d-b509-6b3da3ef7280","ttft_stream_ms":964,"time_to_request_ms":369,"first_content_frame_ms":964,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":42526,"stop_reason":"end_turn","session_id":"28156719-dc0d-4f44-9d1e-039af6553289","total_cost_usd":0.0074350300000000005,"usage":{"input_tokens":2,"cache_creation_input_tokens":11254,"cache_read_input_tokens":2153,"output_tokens":10325,"output_tokens_details":{"thinking_tokens":8212},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11254,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":10325,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11254,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11254},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":10325,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11254,"webSearchRequests":0,"costUSD":0.0074350300000000005,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":8212,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- Let the project write its own rules, register them, and run them with the same standing as bundled rules (4.1).\n- Provide a harness that runs one rule against supplied code and reports whether it fired and what it printed, for bundled and bespoke rules alike (4.2).\n- Give each rule a stable identifier, not derived from its path, class name or position, and print it unaltered with every finding (4.3).\n- Be runnable locally with no infrastructure, on a subset down to a single file, with results in the command's own output, and never reportable only through a hosted, licence-tier or CI-only route (5.1–5.4).\n- Resolve a printed identifier to its documentation. For bundled rules, resolve the identifier alone, from the installed copy, with no network, using documentation shipped with the rule at a tracked version, and every identifier the rule can print must resolve (6.1–6.3).\n- If an inline suppression route is offered, make it either disableable by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document, by a maintainer who has never read it, can conform, because it can be graded on evidence.\n> \"**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.\"\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\"\n\n**2b.** For an inline ignore comment, the detector must do at least one of two things: make the route disableable by configuration, or make it detectable. Doing either one is enough.\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a mechanical check the [Detector] documents.\"\n\n**2c.** The documentation must ship with the rule, at a version tracked together with it, and it must resolve without network access from the installed copy. Every identifier the rule can print must resolve.\n> \"A [Bundled rule]'s documentation MUST ship with the rule, at a version tracked together.\"\n> \"Resolution of a [Bundled rule]'s [Identifier] MUST work from the installed copy, without network access.\"\n> \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\"\n\n## 3. Application\n\nTwo assumptions: the two rules printing `No documentation declared` are among the forty bundled rules, since the fixture says Lintomatic \"ships forty rules\". Clause 4.2 is also graded on the `--only` flag's output, which the fixture does not explicitly describe.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are Zig modules implementing `Rule`, listed in `lintomatic.toml`, \"first class in every report\". |\n| 4.2 | Yes | `check --only <identifier> <path>` runs one rule and exits 1 on fire, 0 on no fire, 2 if unknown. The fixture does not say the `--only` run prints findings, but `check` prints one line per finding, so this is an inference. |\n| 4.3 | Yes | Bundled `LM-NNNN` identifiers are fixed at first release. Project identifiers are the configured name, which Lintomatic \"does not add or rewrite\". The one-line output prints them. The fixture describes no other machine-readable format. |\n| 5.1 | Yes | \"runs locally with no account, no server and no network\". |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file\". |\n| 5.3 | Yes | Stdout gives one line per finding with file, line, column and identifier. Nothing is left out, so no remainder needs naming. |\n| 5.4 | Yes | \"every finding it shows is also printed by the command line\"; the CI binary is the same as the local one. |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the identifier alone, and the project-rule case prints the declared `doc` string. |\n| 6.2 | Yes | Documentation is printed \"from the installed package\" and \"there is no separate website\". |\n| 6.3 | **No** | Two bundled identifiers resolve to `No documentation declared`, which is not a page. Under 6.3, \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` can be disabled with `ignore_comments = false`, which satisfies the clause on its own. |\n\n**Conformance (section 8): No.** Clause 6.3 is a MUST and fails. Section 8 requires every MUST in sections 4 to 7 to hold. The MUSTs in those sections are the ones graded above, so 6.3 alone is enough. Lintomatic is partial conformance, which must not be described as conformance.\n\n**Clause 6.4: no change to the verdict.** 6.4 is a SHOULD (\"The [Detector] SHOULD fail its own release if a [Bundled rule] lacks resolvable documentation\"), and section 8 counts only MUSTs. The fixture's note that the repository \"does not check that every `LM-NNNN` identifier has an `explain` entry\" is exactly the gap 6.4 describes, and it is why the 6.3 failure shipped unnoticed. It is a SHOULD gap, and if it were recorded it would go under 8.1's known-gaps. The fixture does not say whether Lintomatic ships inside a toolchain. The toolchain specification was not provided, so I cannot say whether 6.4 becomes a MUST for a toolchain.\n\n## 4. Confusion\n\n- **5.3:** \"The remainder is the findings the summary leaves out: where the output prints every finding there is none, and a fuller report written elsewhere, such as a page with a code snippet for each finding, is not one and need not be named.\"\n\nThe double negative and the pronoun-like \"one\" (referring back to \"remainder\") meant I had to reread it to confirm that a fuller report is not a remainder.","ttft_ms":35180,"type":"result","duration_ms":42935,"uuid":"a63d673e-f6ba-4edd-a4f7-d849e20f68b6","ttft_stream_ms":1034,"time_to_request_ms":409,"first_content_frame_ms":1034,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 077: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

The exact prompt every reader received, part 1 of 1

===== FILE: QUESTIONS.md =====
# Questions for a cold reader of DETECTOR-SPEC.md

You have been given `DETECTOR-SPEC.md` and the fixture `fixtures/lintomatic.md`, and nothing
else. Read the document once, then answer every question below in order. Quote the document
where a question asks for a quotation. Do not consult anything outside what you were given.

## 1. Restatement

In your own words and in at most six bullets, what does this document require of a detector?

## 2. Load-bearing statements

Answer each part of each question in a sentence or two, then quote the sentence or sentences of
the document you are relying on.

- 2a. What does it mean for a detector to conform, and can a detector that was written before
  this document existed, and has never heard of it, conform?
- 2b. A detector ships an inline ignore comment. What must the detector do about that route for
  it to conform, and is doing one of those things enough?
- 2c. Where must the documentation for a bundled rule's identifier live, at what version, and
  must it be reachable without network access?

## 3. Application

Grade Lintomatic 4.2, as described in the fixture, against every MUST clause in sections [4](../../DETECTOR-SPEC.md#4-authoring-rules) to [7](../../DETECTOR-SPEC.md#7-suppression):
[4.1](../../DETECTOR-SPEC.md#41-the-detector-must-support-bespoke-rules-written-by-the-project-that-runs-it), [4.2](../../DETECTOR-SPEC.md#42-the-detector-must-provide-a-harness-that-runs-a-single-rule-against-supplied-code), [4.3](../../DETECTOR-SPEC.md#43-the-detector-must-allow-a-rule-to-carry-a-stable-identifier-and-must-print-it-with-every-finding), [5.1](../../DETECTOR-SPEC.md#51-the-detector-must-be-invocable-by-the-practitioner-locally-with-no-infrastructure), [5.2](../../DETECTOR-SPEC.md#52-the-detector-must-support-invocation-over-a-subset-at-minimum-a-single-file), [5.3](../../DETECTOR-SPEC.md#53-the-result-must-reach-the-practitioner-in-the-output-of-the-command-they-ran), [5.4](../../DETECTOR-SPEC.md#54-a-finding-must-not-be-reportable-only-through-a-hosted-service-licence-tier-or-ci-only-mode-the-practitioner-cannot-invoke-locally), [6.1](../../DETECTOR-SPEC.md#61-the-detector-must-provide-a-mechanism-that-resolves-a-printed-identifier-to-its-documentation), [6.2](../../DETECTOR-SPEC.md#62-resolution-of-a-bundled-rules-identifier-must-work-from-the-installed-copy-without-network-access), [6.3](../../DETECTOR-SPEC.md#63-a-bundled-rules-documentation-must-ship-with-the-rule-at-a-version-tracked-together), [7.1](../../DETECTOR-SPEC.md#71-a-detector-may-offer-an-inline-suppression-route-but-must-make-it-detectable-or-disableable). For each give Yes, Partial or No and one
line of reasoning. Then state whether Lintomatic conforms under section [8](../../DETECTOR-SPEC.md#8-conformance), and why. Finally,
state whether clause [6.4](../../DETECTOR-SPEC.md#64-the-detector-should-fail-its-own-release-if-a-bundled-rule-lacks-resolvable-documentation) changes the verdict, and why.

## 4. Confusion

Quote any passage you found confusing on your one reading, with its clause number. Do not say what
would make it clearer and do not propose any change. Write "none" if there was none.

===== FILE: DETECTOR-SPEC.md =====
# Defence Before Fix: Detector Specification

**Version**: 1.0.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the toolchain specification](TOOLING-SPEC.md), version 0.2.0
**Author**: [Joseph Edmonds](https://ltscommerce.dev), [Edmonds Commerce](https://edmondscommerce.co.uk)
**Coined**: 22 February 2026, in [the original article](https://ltscommerce.dev/articles/defence-before-fix-static-analysis)

## 1. What this document is for

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are to be interpreted as
described in RFC 2119.

[The method specification](SPEC.md) states what a [Practitioner] does when a
[Defect] is found. This document states what a [Detector] must offer so that they
can do it: write a [Rule], prove it, run it and resolve what it prints. It is addressed to
whoever maintains a [Detector], which the method specification defines as a tool that reads
code without executing it and reports occurrences of a pattern.

A [Detector] is one part of a project's [Toolchain], and this document judges it
on what it offers alone. What the assembled [Toolchain] of a project must add on top, the
[Project record], the listing of active [Defences] and the
governance of [Suppression], is stated in [the toolchain specification](TOOLING-SPEC.md).
The two are separable because they are built by different people: a [Detector] is authored once
and installed into projects its maintainer will never see, whilst governance is decided by each
project for itself. A document that asked a [Detector] to enforce a project's governance would
fail every [Detector] in use and would not make any project better governed.

**The governing principle**: where the method specification requires a [Practitioner] to do
something with a [Rule], a [Conforming] [Detector] MUST make that possible
without the project building the mechanism first. A [Detector] that leaves the project to
construct the means has moved the obligation rather than met it.

## 2. Terminology

Terms from the method specification carry over unchanged. Every capitalised term links to its
definition; the ones this document leans on most are, in short:

| Term           | In one line                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| [Detector]     | A tool that reads code without executing it and reports what it finds          |
| [Rule]         | One check a [Detector] evaluates                                               |
| [Message]      | The text a [Rule] prints when it fires                                         |
| [Identifier]   | The stable name printed with a finding that leads to its documentation         |
| [Practitioner] | Whoever is doing the work, a person or an [Agent]                              |
| [Toolchain]    | Everything a project assembles to run its checks through, [Detectors] included |
| [Suppression]  | Making a finding go away without fixing it                                     |
| [Baseline]     | A recorded set of existing findings a [Rule] is told to ignore                 |

These are additional.

#### Rule author

Whoever writes a [Rule]. May be the [Detector]'s maintainer, a [Toolchain]'s maintainer or the project that runs it.

#### Bundled rule

A [Rule] the [Detector] ships, or fetches on the [Practitioner]'s behalf from a source the [Detector]'s maintainer controls. Its [Rule author] will never see the codebases it runs in, so everything a [Practitioner] needs in order to act on it has to travel with it.

#### Harness

The route by which one [Rule] is run against supplied code and its findings observed, without the project's own test suite and without every other [Rule] running alongside it.

The distinction between a [Bundled rule] and a project's own [Rule] matters throughout.
The [Detector] owns the documentation of the first and can be held to shipping it; it cannot
know the documentation of the second, and what it owes there is the mechanism that lets the project
attach its own.

## 3. The division of responsibility

Each mechanism the method needs has two halves. Stating only one of them is what produces a
[Detector] that is *nearly* usable.

| Requirement                          | The [Detector] MUST provide                             | The [Rule author] supplies                              |
| ------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------- |
| Bespoke [Rules]                      | The authoring and registration route                    | The [Rules]                                             |
| The red proof                        | A [Harness]                                             | The [Fixture] and the red run                           |
| Running the [Rule]                   | A local invocation, including subsets                   | Running it                                              |
| The [Identifier]                     | A place to carry it, and printing it with every finding | Choosing it once                                        |
| Resolution of a [Bundled rule]       | The lookup, and the documentation, on disk              | Nothing                                                 |
| Resolution of a project's own [Rule] | The [Identifier] printed unaltered                      | The documentation and, with the [Toolchain], the lookup |
| Inline [Suppression]                 | A route the project can detect or disable               | The decision whether to forbid it                       |

Read down the middle column and the shape of a [Conforming] [Detector] is already
visible. Read across any row and the failure mode is visible too: either half alone leaves the
[Practitioner] stuck.

## 4. Authoring rules

### 4.1 The detector MUST support bespoke rules written by the project that runs it

Configuration of an existing [Rule] set is not sufficient. The project must be able to express a
pattern the [Detector]'s authors have never anticipated, and register it so that it runs with
the same standing as a [Bundled rule].

**Why**: the method turns a specific [Defect] into a [Class] [Defence], and the
[Classes] that matter most to a project are the ones peculiar to it. A [Detector] offering
only a fixed catalogue can defend against the industry's known [Hazards] and none of the
project's own, which is the half that carries its institutional knowledge.

### 4.2 The detector MUST provide a harness that runs a single rule against supplied code

A [Harness] reports, for a given input, whether the [Rule] fired and what it printed, without
executing the project's own test suite and without the other [Rules] obscuring the answer.
This applies to every [Rule] the [Detector] runs, bundled or bespoke; a
[Detector] failing 4.1 is graded here on its [Bundled rules].

**Why**: clause 3.3 of the method specification requires the [Rule] to be proven by making it go
red. A [Practitioner] who can only observe a [Rule]'s behaviour by running every
[Rule] over the whole codebase cannot demonstrate that a [Rule] fires on the pattern rather
than on something incidental.

### 4.3 The detector MUST allow a rule to carry a stable identifier, and MUST print it with every finding

The [Identifier] MUST be stable across releases and MUST NOT be derived from the [Rule]'s
file path, [Class] name or position in a configuration file. The [Rule author] chooses it
once. The [Detector] MUST print it, unaltered, alongside every finding the [Rule]
reports, in its default output and in every machine-readable format it offers. A prefix the
[Detector] adds from the invoking directory or the [Rule]'s location is derived from
the file path. A namespace the [Rule author] assigns once in configuration is not.

| [Identifier]       | Where it comes from                                                         | Stable? |
| ------------------ | --------------------------------------------------------------------------- | ------- |
| `proj.no-raw-sql`  | Written once by the [Rule author] in configuration, printed as is           | Yes     |
| `LM-0107`          | Assigned once by the [Detector]'s maintainer at the [Rule]'s first release  | Yes     |
| `rules/no-raw-sql` | Produced from where the [Rule]'s file sits; changes when the file moves     | No      |
| `NoRawSqlRule`     | The [Rule]'s [Class] name; changes when the [Rule] is renamed               | No      |
| `rule 7`           | The [Rule]'s position in a configuration file; changes when one is inserted | No      |

**Why**: the [Identifier] is the only string that reaches the [Practitioner] and the
only key their lookup can use. An [Identifier] that changes when a [Rule] is renamed
silently breaks every reference to it, including references written down by people who have left.
An [Identifier] the [Detector] carries but does not print is one the
[Practitioner] was never given.

### 4.4 The detector SHOULD enforce 4.3 with a rule of its own

A [Rule] over the [Rules], failing any [Rule] that reports without a stable
[Identifier].

**Why**: this is the method applied to the [Detector] itself, and it is cheap. The worked
example is `php-qa-ci`'s `RequireRuleIdentifierConstantRule`, a [Rule] hosted in PHPStan by a
[Toolchain] built on it: it rejects a magic-string [Identifier] and names the
constant to declare instead. Nothing about it needed to live outside the [Detector].

## 5. Reporting

### 5.1 The detector MUST be invocable by the practitioner, locally, with no infrastructure

**Why**: method specification clause 8.1. An [Agent] that cannot check its own work cannot
iterate against a [Defence], so the loop never closes in the turn where it is cheap to close.

### 5.2 The detector MUST support invocation over a subset, at minimum a single file

**Why**: 5.1 is satisfied in principle by a whole-codebase run and defeated in practice by one.
Checking a single edited file has to be fast enough to do on every edit, or it will not be done on
any.

### 5.3 The result MUST reach the practitioner in the output of the command they ran

Where the [Detector] writes fuller detail elsewhere, the invoked command's own output MUST
carry a usable summary and, where the summary leaves any finding out, the location of the
remainder. A summary is usable when each finding in it carries where it is and its
[Identifier]. The remainder is the findings the summary leaves out: where the output prints
every finding there is none, and a fuller report written elsewhere, such as a page with a code
snippet for each finding, is not one and need not be named.

**Why**: method specification clause 8.2. A report the [Practitioner] has to go and find is a
report that arrives after the decision it was meant to inform.

### 5.4 A finding MUST NOT be reportable only through a hosted service, licence tier or CI-only mode the practitioner cannot invoke locally

A finding that the [Detector] reports only through a hosted service, a licence tier or a
continuous-integration-only mode the [Practitioner] cannot invoke locally does not
[Conform], whatever the same [Rule] reports there.

**Why**: a [Rule] that fires only in an environment the [Practitioner] has no access to
teaches nobody anything and blocks them anyway, which is the worst combination available.

## 6. Resolving an identifier

### 6.1 The detector MUST provide a mechanism that resolves a printed identifier to its documentation

Two cases, by who wrote the [Rule]:

| The [Rule]        | Who supplies the documentation | What this clause asks of the [Detector]                                   |
| ----------------- | ------------------------------ | ------------------------------------------------------------------------- |
| A [Bundled rule]  | The [Detector]                 | Resolve the [Identifier], presented alone, to that documentation          |
| The project's own | The project                    | Print the [Identifier] unaltered; the lookup is the [Toolchain]'s to give |

In both, the mechanism is keyed on **the [Identifier] exactly as printed**. A command, an index
file or a URL are all acceptable forms. This clause asks for the mechanism, not for every page:
where the mechanism works but a [Bundled rule]'s [Identifier] has no documentation to resolve
to, that fails clause 6.3, not this clause. Each case in turn:

**For a [Bundled rule]**, the [Detector] supplies the documentation and the
lookup, and clauses 6.2 and 6.3 say where. The mechanism MUST resolve an [Identifier]
presented alone, because the reader who needs it most has the [Identifier] from a log, a
ticket or a colleague and not the [Message]. A documentation path printed in the [Message] is
therefore not enough on its own: it helps only a reader who has the [Message], and the
[Identifier] alone still leads nowhere.

**For a project's own [Rule]**, the [Detector] cannot know the documentation, so what
it owes is the half it can give: the [Identifier] printed unaltered under clause 4.3, and no
transformation of it. Where the [Identifier] is itself a URL, as method clause 3.6 allows,
the [Detector] prints that URL and has done what this clause asks. What this clause forbids is
a documentation path printed alongside a shorter [Identifier] that cannot be looked up on its
own. The lookup for such
a [Rule] is an obligation on the project's assembled [Toolchain], under clause 4.2
of the [toolchain specification](TOOLING-SPEC.md), and a [Detector] that offers it as well has
gone further than this clause asks.

**Why**: method specification clause 8.3 requires the [Identifier] to resolve without a human.
An index keyed on anything else does not resolve it. This is the most commonly failed clause in this
document and it fails in a specific way: documentation exists, is genuinely good, and is keyed on the
[Rule]'s [Class] or file name, which is a string the [Practitioner] was never
given. The lookup they can actually perform is the only one that counts.

### 6.2 Resolution of a bundled rule's identifier MUST work from the installed copy, without network access

**Why**: an [Agent] working offline, behind a proxy, or against a URL that has since moved needs
the answer to be on disk. A dependency the project already installed is on disk by definition. A
catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong
place.

### 6.3 A bundled rule's documentation MUST ship with the rule, at a version tracked together

Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1,
to a page in that shipped documentation. One [Identifier] that does not resolve fails this
clause, however many others do. A page per [Identifier] satisfies this; a page per family of
[Identifiers] MAY be used instead, under clause 6.5.

**Why**: method specification clause 3.6. A [Bundled rule] travels into codebases its author
will never see. If its documentation lives only in the [Detector]'s repository or on its
website, then every project that installs it is one link rot away from a [Rule] that blocks
without explaining.

The failure to guard against is not the absent document but the **dangling one**: a reference to
documentation that was planned and never written is worse than no reference, because it consumes
the [Practitioner]'s attention before failing them.

### 6.4 The detector SHOULD fail its own release if a bundled rule lacks resolvable documentation

An automated check over every [Identifier] a [Bundled rule] can print, applying the
family list or pattern of clause 6.5 where one is used, that blocks the release when any of them
lands on no page.

**Why**: clause 6.3 is the clause most easily believed to be satisfied whilst being broken, because
the documentation is written by the same person who wrote the [Rule] and its absence is
invisible from the inside. Where the [Detector] is shipped inside a [Toolchain],
the [toolchain specification](TOOLING-SPEC.md)'s self-audit makes this check a MUST for the [Toolchain]; a
[Detector] released on its own is asked for it as a SHOULD because the same [Class] of
[Defect], a [Rule] that blocks without explaining, is detectable mechanically there too.

### 6.5 One page MAY document a family of identifiers, and SHOULD name its members so a check can confirm them

Where several [Bundled rules] share a prefix, one page MAY document them all. Such a page
SHOULD let the check clause 6.4 asks for confirm that each member resolves to it. Two forms do
that and one does not:

| The page                                                                                                  | A check can confirm each member?          |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Lists every full [Identifier] in the family, `LM-0100`, `LM-0101`, and so on                              | Yes                                       |
| Carries a regular expression the check can run, `^LM-01[0-9]{2}$`, matching every member and nothing else | Yes                                       |
| Says in prose that everything under `LM-01` is documented here                                            | No: a person can infer it, a check cannot |

The list or the regular expression lives in the installed file, since clause 6.2 requires
resolution to work from the installed copy, not only in a rendered web page.

**Why**: a family page is a convenience for the author, and the cost of it must not fall on the
check. A page that a person can see covers `LM-0107` but a check cannot leaves clause 6.4 with
nothing to run.

## 7. Suppression

### 7.1 A detector MAY offer an inline suppression route, but MUST make it detectable or disableable

An inline ignore comment, a per-line directive and a generated [Baseline] are all such
routes. The [Detector] MAY ship them. For each one it MUST do at least one of two things, and either
alone satisfies this clause: make the route disableable by configuration; or make the route
detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a
mechanical check the [Detector] documents. Either lets a project which decides to forbid the
route enforce that decision. A route that can be neither switched off nor seen does not [Conform].

A route is detectable when the project can find every use of it, in either of two ways: by a
bespoke [Rule] the project registers under clause 4.1 that matches the route wherever it is
used, which the [Detector] runs like any other bespoke [Rule] and need not ship itself; or by a
mechanical check the [Detector] documents, such as a text search for the route's spelling. The
first way needs the [Detector]'s [Rules] to be able to match the route's text, so a [Detector]
whose [Rules] never see comments offers only the second for an ignore comment.

**Why**: the method specification's position is that [Suppression] is an [Owner]
decision under its clause 3.4 and section 4, and an [Owner] cannot decide something they are
never shown. The [Detector] is not the [Owner] and does not know the project's
governance, so it is not asked to enforce it; what it is asked is not to hide the route. Every
[Detector] in wide use ships an inline ignore, and a clause that forbade them would fail all of
them without governing any project better. Whether the route is forbidden is the project's decision,
enforced through its [Toolchain] under clause 4.3 of the [toolchain specification](TOOLING-SPEC.md).

### 7.2 An inline suppression route SHOULD require a written reason

The [Detector] SHOULD reject, or be configurable to reject, an inline [Suppression]
that carries no reason, and SHOULD NOT supply a default one, including each entry of a generated
[Baseline].

**Why**: a [Suppression] without a reason is indistinguishable from one nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence costs the author a
minute at the moment they have the reason in mind, and it is the only thing that makes the
[Suppression] reviewable later. PHPStan's `reportIgnoresWithoutComments` is the shape of it.

## 8. Conformance

**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Detector]
that satisfies most of this document is in a normal and respectable condition; it is not
[Conforming], and describing it as such removes the only value the word has.

This document defines one level. The clauses of the method specification's section 8 that reach
beyond what sections 4 to 7 here already secure, the listing of active [Defences] and the
summary for an [Agent]'s context, are obligations on a project's assembled [Toolchain]
and are stated in the [toolchain specification](TOOLING-SPEC.md), so there is no separate [Agent]-support level
for a [Detector].

### 8.1 A maintainer MAY declare the version of this document the detector conforms to, and the declaration records known gaps

The declaration is machine-readable, in whatever form the [Detector]'s ecosystem uses to
record dependencies. The same declaration is where a gap against this document is recorded once it is
known: a [Detector] that declares a version and has learnt, from its own checks or from a
[Practitioner]'s report under the method's clause 3.2, that it fails a MUST in sections 4 to 7
MUST record that gap alongside that version, in the same file or one it names. A declaration
with a non-empty gap record is a statement of where the [Detector] stands and is not a claim of
[Conformance].

The declaration is optional, and so the duty above falls only on a [Detector] that has one; a
gap a [Practitioner] finds is recorded in their own project's record under the method's clause
3.2 in any case. The declaration is how a maintainer claims [Conformance]; it is not a condition
of it, and a [Detector] without one can still be found to [Conform]. A [Detector] that predates
this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence:
anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on
any [Detector], declared or not, rests on that check and not on the claim. A declaration tells the reader what the maintainer believes and what they know to be missing;
the reader still runs the [Harness].

The shape is illustrative rather than prescribed. In a Composer manifest:

```json
"extra": {
  "defence-before-fix": {
    "method": "1.0.1",
    "detector": "1.0.0",
    "toolchain": null,
    "known-gaps": []
  }
}
```

In a package.json, the equivalent is a top-level `defenceBeforeFix` object with the same keys. A
[Detector] that is not also shipped as a [Toolchain] leaves `toolchain` empty;
a project that ships both declares both. Each entry in `known-gaps` names the clause and states the
gap in a sentence.

**Why**: a [Conformance] claim in a README is a sentence; a claim in a manifest is a fact about
a specific installed artefact, checkable by anyone, including mechanically, and it fixes what
"[Conforming]" meant at the point the claim was made. Making the claim a condition of
[Conformance], though, would mean a [Detector] with every mechanism in place could
never [Conform] until its maintainer had heard of this document, which grades the
maintainer's reading rather than the [Detector].

## 9. Relationship to the other specifications

This document adds no obligations to a [Practitioner] and relaxes none. Every clause here
exists to make a clause of the method specification achievable with a [Detector] in hand.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes one piece of the equipment.

The [toolchain specification](TOOLING-SPEC.md) states what a project's assembled [Toolchain] must offer beyond
what each [Detector] in it offers, and it requires every [Detector] a [Defence]
is routed through to [Conform] to this one. A [Detector] shipped inside a
[Toolchain] is measured here as a [Detector] and there as part of the
[Toolchain]; the two verdicts are separate and neither implies the other.

Nothing here requires a project to use a [Conforming] [Detector]. A project can
[Conform] to the method specification on a [Detector] that [Conforms] to
none of this, at the cost of building the missing mechanisms itself. This document exists so that it
does not have to.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[bundled rule]: #bundled-rule
[bundled rules]: #bundled-rule
[class]: SPEC.md#class
[classes]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[fixture]: SPEC.md#fixture
[harness]: #harness
[hazards]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[project record]: TOOLING-SPEC.md#project-record
[rule]: SPEC.md#rule
[rule author]: #rule-author
[rules]: SPEC.md#rule
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain

===== FILE: fixtures/lintomatic.md =====
# Fixture: Lintomatic 4.2

A fictional detector, described only as far as its documentation would describe it. Grade it
against the document you were given. Where the description does not say, answer from what is
written, not from what a real tool would probably do.

## What the documentation says

Lintomatic is a static analyser for the Zig language. It ships forty rules. A project can add its
own rules by writing a Zig module that implements the `Rule` interface and listing it in
`lintomatic.toml`; project rules are loaded on every run and are first class in every report.

The command `lintomatic check <path>` analyses a directory or a single file and prints one line
per finding to standard output:

```
src/db.zig:41:7  LM-0107  Result of fallible call discarded
src/db.zig:88:3  proj.no-raw-sql  Query built by string concatenation
```

Fuller detail, including a snippet, is written to `.lintomatic/report.html`. The one-line form is
printed whether or not the HTML report is enabled.

`lintomatic check --only <identifier> <path>` runs a single rule. It accepts any rule name,
bundled or project, and exits 1 when the rule fires, 0 when it does not, and 2 when the rule name
is unknown.

Rule identifiers for bundled rules are of the form `LM-NNNN` and are fixed at the rule's first
release. Project rules are identified by the name the project gives them in `lintomatic.toml`,
which the documentation recommends prefixing with `proj.`; Lintomatic does not add or rewrite
any part of the name.

`lintomatic explain <identifier>` prints the documentation for a bundled rule from the installed
package: what the rule finds, why, and the recommended construction. For a project rule it prints
the `doc` string the rule module declares, or `No documentation declared` when there is none.
The documentation is versioned with the package; there is no separate website.

Lintomatic honours the comment `// lintomatic-ignore <identifier>` on the line before a finding.
The comment can be disabled project-wide with `ignore_comments = false` in `lintomatic.toml`.
The comment takes no reason and the documentation does not mention one.

The tool runs locally with no account, no server and no network, and the same binary is what CI
runs. There is a hosted dashboard, sold separately, that aggregates reports across repositories;
every finding it shows is also printed by the command line.

Lintomatic's own repository runs `lintomatic check src` in CI but does not check that every
`LM-NNNN` identifier has an `explain` entry; two of the forty rules currently print
`No documentation declared`.

[LTSCommerce]

Run 078: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Command and working directory

ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt, each reader in a fresh empty directory made by mktemp -d outside the repository

Model version each reader reported

reader 1: claude-haiku-5-5
reader 2: claude-haiku-5-5
reader 3: claude-haiku-5-5
reader 4: claude-haiku-5-5
reader 5: claude-haiku-5-5

The delegated marker's task prompt

MODE: mark

Worktree: <worktree> (branch `editor/detector-route-rule`). The readers read commit ac14996. Read, at that commit and in that worktree: ACCEPTANCE.md in full (it is the process as pull request 22 proposes it, merged into this branch; the run is made under that process change before it merges, at commit 13b497b, named here before the readers started), acceptance/runs/README.md, acceptance/detector/QUESTIONS.md, acceptance/detector/KEY.md, acceptance/fixtures/lintomatic.md and DETECTOR-SPEC.md. You may read acceptance/runs/077-detector-route-rule-run-5.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 078. Document: DETECTOR-SPEC.md. Change: detector route rule, pull request 23 (clause 7.1's detectable route is a bespoke rule the project writes for the detector under clause 4.1, with a paragraph on what detectable means; clause 8.1's gap duty falls only on a detector that declares a version; clause 5.3 says what the remainder is; clause 6.1 says it asks for the mechanism, a missing page failing 6.3, and that a path in the message is not enough on its own; section 2's table gains a Message row). Run 77 failed on one finding, clause 5.3's remainder sentence, and that sentence is now three plain sentences (the remainder is the findings the summary leaves out; where the output prints every finding there is no remainder; a fuller report written elsewhere is not a remainder and the output need not name it), so this is a fresh run. Pull request: 23, https://github.com/Defence-Before-Fix/defence-before-fix.github.io/pull/23. Run within the pull request: 6 (runs 60, 63, 66, 73 and 77 came before). Record file to write: <worktree>/acceptance/runs/078-detector-route-rule-run-6.md. Do not commit it.

Sheets: <run-dir>/sheet-1.md to sheet-5.md, each the `result` of reader-N.json. Prompt the readers received: <run-dir>/prompt.txt; its sha256 is 9d52a2f0c2c15cb1f4d1b7d628fc403560534fa35cdde941e26efe717846f35c, and it is byte for byte the question set, DETECTOR-SPEC.md and the fixture at ac14996, each after one `===== FILE: <name> =====` line, one blank line between files. Model: every reader reported claude-haiku-5-5 (<run-dir>/models.txt); the cohort's model named for the run is claude-haiku-5-5. Every reader's JSON has is_error false and subtype success; no reader is set aside.

Facts the editor supplies for the record: cohort of five readers, none reused from any earlier run; each a separate `claude -p` process started through the `ccy-claude` wrapper (which only reattaches the session's credential) in a fresh empty directory made by `mktemp -d` outside any repository, with the packet on standard input, command `ccy-claude -p --model haiku --safe-mode --tools '' --setting-sources '' --strict-mcp-config --no-session-persistence --output-format json < prompt.txt`; no tools, no settings, no project context, no saved session; the machine applies no managed settings; the editor attests the rest of the isolation. Marked by a delegated marker, a fresh `dbf-spec-editor` agent (Claude Opus) given this instruction and its agent definition, having seen neither the drafting nor the review.

Text the change wrote or altered, for "Where a finding lies": the output of `git -C <worktree> diff 9e914fe ac14996 -- DETECTOR-SPEC.md` (9e914fe is the merge base with `next`). Run it and read it. A finding in a paragraph that diff adds, rewords, moves, deletes a sentence from, or changes a word, term or link in, or that a reader sets against such a paragraph, blocks; any other finding is routed to acceptance/ROUTED.md, and the record says so for each.

Mark every sheet, keyed item by keyed item, by ACCEPTANCE.md's Marking section and the key alone. Write the record stating what acceptance/runs/README.md lists, in its order, with the marks table, each miss with the reader's reasoning in brief, every passage named under question 4 with its words or description, clause and readers, each finding and where it lies, any open point and the direction you marked it, the process-change commit 13b497b, the verdict, and a placeholder line for the link to the posted sheets. Reply with the verdict and the findings only, under thirty lines.

The agent definition the marker ran under

---
name: dbf-spec-editor
description: Drafts, reviews, key-updates, marks or records a change to the Defence Before Fix specification, one mode per dispatch, following the specification repository's CONTRIBUTING.md, SCOPE.md and ACCEPTANCE.md exactly. Dispatched by the dbf-spec-change skill; it cannot run a cohort itself.
tools: Read, Write, Edit, Grep, Glob, Bash
model: opus
---

You work on one change to the Defence Before Fix specification, in the worktree path you are
given. The process is defined by that repository's `CONTRIBUTING.md`, `SCOPE.md`,
`ACCEPTANCE.md` and `acceptance/README.md`; read the ones your mode needs, in full, before you
act. You invent no steps. You never merge, push to `next` or `main`, release, tag or publish,
and you never change a question, threshold or fixture. Your prompt names one mode.

Write as the specification is written: British spelling, no em dashes, defined terms linked as
`spec-qa.py` requires, every clause or section number linked to its heading. Commit on the
worktree's branch.

## MODE: draft

1. Read `SCOPE.md`, `DECLINED.md`, and every clause the change touches, with the terminology
   entries they use.
2. Decide the kind. A change to the sentences carrying MUST, SHOULD or MAY in a numbered section
   or appendix is an obligation; anything else is a clarity edit.
3. For an obligation, answer the five SCOPE tests in a sentence or two each, and name the
   section the obligation extends. If a test fails, or an existing clause already covers it, say
   so and stop without editing.
4. Make the smallest edit that does the job, in the clause that owns the subject.
5. Add one line under `Unreleased` in `CHANGELOG.md`, saying what changed and why, with a
   placeholder `run NNN`. Change no version.
6. If Appendix A changed, run `python3 build-agent-surfaces.py` and commit its outputs.
7. Run `python3 spec-qa.py` and `python3 -m unittest discover -s tools -p 'test_*.py'`; both
   clean.
8. Reply with: kind, SCOPE answers, files changed, commit, QA result, and a filled
   `.github/PULL_REQUEST_TEMPLATE.md` body. Under forty lines.

## MODE: review

You have not seen the drafting. Read the whole changed document and the diff against
`origin/next`. Report, numbered, with clause numbers: contradictions with other clauses, terms
used outside their definition, a sentence a reader could take two ways, an obligation an owner
could not verify from the record. Do not edit.

## MODE: keys

Read `acceptance/README.md` and the `KEY.md` for each changed document. Update every quotation of
a changed sentence to the new wording, verbatim, in a new commit; run `python3 spec-qa.py` until
`key-quote-stale` is gone. If the change adds a load-bearing obligation no keyed question
covers, propose the question and its key in your reply; add it only if your prompt says the owner
has decided to.

## MODE: mark

You have not seen the drafting or the review. Read `ACCEPTANCE.md` in full, the `KEY.md` for the
document, the document at the commit named, and the sheets under `<run-dir>/`.

- Mark each sheet against the key, keyed item by keyed item, by the rules under "Marking" in
  `ACCEPTANCE.md` and nothing else: the key's required elements, accepted grades, conditions and
  wrong readings. Invent no judgement; where neither the rules nor the key settles a mark, mark
  it in the direction the open-point rule gives and record the point.
- A single miss under questions 1 and 3 counts against the document only where the key names
  that reading; say which.
- For question 4, record every passage named, with its words or description and its clause.
  Group the passages by paragraph, count the readers, and for each finding say whether it lies in
  text the change wrote or altered, read against the diff the prompt gives you, or is routed to
  `acceptance/ROUTED.md`. Ignore any suggestion a reader volunteers.
- Apply the pass criteria exactly.
- Write `acceptance/runs/NNN-<slug>-run-<k>.md` stating what `acceptance/runs/README.md` lists,
  in its order. Do not commit it. Reply with the verdict and the findings only.

## MODE: record

Commit the run record, replace the `run NNN` placeholder in `Unreleased` with a link to it, and
for an obligation set the document header to `<next version>-dev, unpublished` in the same
commit if it still names a published version. Run `python3 spec-qa.py` and
`python3 tools/changes.py --base origin/next`; both clean. Reply with the commit.

[LTSCommerce]

Run 078: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

Answer sheets, each reader's whole output as its process returned it

reader-1

{"duration_api_ms":40432,"stop_reason":"end_turn","session_id":"b9a2b8ac-8749-4dd0-b19b-ada0c18c39df","total_cost_usd":0.007023529999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":11264,"cache_read_input_tokens":2153,"output_tokens":9498,"output_tokens_details":{"thinking_tokens":7652},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11264,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":9498,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11264,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11264},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":9498,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11264,"webSearchRequests":0,"costUSD":0.007023529999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":7652,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, register them, and run them with the same standing as bundled rules (4.1).\n- It must provide a harness that runs one rule against supplied code and reports whether that rule fired and what it printed (4.2).\n- Each rule needs a stable identifier, not derived from file path, class name, or position, and the detector must print it unaltered with every finding (4.3).\n- The detector must run locally with no infrastructure, on at least a single file, and put findings in the output of the command the practitioner ran. Findings reachable only through a hosted, licence-tier, or CI-only route don't count (5.1 to 5.4).\n- Every printed identifier must resolve to its documentation. For bundled rules, that means on-disk documentation that works offline, with every identifier covered (6.1 to 6.3).\n- An inline suppression route must be either disableable by configuration or detectable (7.1).\n- A detector conforms only if it meets every MUST in sections 4 to 7. Partial conformance may not be called conformance (8).\n\n## 2. Load-bearing statements\n\n**2a.** Conformance means satisfying every MUST in sections 4 to 7. A detector written before the document, by a maintainer who has never read it, can still conform, because it can be graded on evidence. From section 8: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7.\" Section 8 also says \"A [Detector] **Conforms** if it satisfies every MUST in sections 4 to 7.\"\n\n**2b.** The detector must either make the route disableable by configuration or make it detectable. Doing one is enough. From 7.1: \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] … or by a mechanical check the [Detector] documents.\"\n\n**2c.** The documentation must ship with the rule, at a version tracked together with it, and must be reachable offline. From 6.3: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" Every identifier must resolve \"to a page in that shipped documentation.\" From 6.2: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\"\n\n## 3. Application\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are written as a Zig module implementing `Rule`, listed in `lintomatic.toml`, and \"first class in every report.\" |\n| 4.2 | Partial | `--only` \"exits 1 when the rule fires, 0 when it does not,\" so whether it fired is reported. The fixture never says `--only` prints what the rule printed, and 4.2 requires that. |\n| 4.3 | Yes | Bundled identifiers are \"fixed at the rule's first release.\" Project names come from configuration, and \"Lintomatic does not add or rewrite any part of the name.\" The one-line output prints them. No machine-readable format is described, so the \"every machine-readable format\" limb has nothing to fail. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line form prints \"one line per finding\" to stdout, with location and identifier, so there is no remainder. The HTML report is extra. |\n| 5.4 | Yes | The dashboard is optional, and \"every finding it shows is also printed by the command line.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone and resolves it for bundled rules. Project rules print their identifier unaltered. |\n| 6.2 | Yes | Documentation is \"versioned with the package; there is no separate website,\" and `explain` reads \"from the installed package.\" |\n| 6.3 | No | The repository note says \"two of the forty rules currently print `No documentation declared`.\" Those identifiers resolve to no page. Under 6.3, \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | The comment \"can be disabled project-wide with `ignore_comments = false`,\" which satisfies the disableable limb. |\n\n**Verdict:** Lintomatic does not conform under section 8. It fails 6.3 outright, and it is at best Partial on 4.2, which also prevents conformance because section 8 requires every MUST to be met. The 6.3 failure alone is enough.\n\n**Effect of 6.4:** It doesn't change the verdict. 6.4 is a SHOULD, and section 8 counts only MUSTs. The fixture also doesn't say Lintomatic ships inside a toolchain, so 6.4 isn't a MUST through the toolchain route. The missing release check is why the two undocumented rules went unnoticed, and it is a real gap, but it doesn't alter the conformance verdict.\n\n## 4. Confusion\n\n- 6.1, the table row for a project's own rule (\"Print the [Identifier] unaltered; the lookup is the [Toolchain]'s to give\") sits beside the clause's MUST, \"The detector MUST provide a mechanism that resolves a printed identifier to its documentation.\" On my reading those two don't obviously agree about what the detector owes for project rules.\n- 4.2: \"a [Detector] failing 4.1 is graded here on its [Bundled rules].\"","ttft_ms":34362,"type":"result","duration_ms":40953,"uuid":"473a874f-462b-4fb5-8202-4f415023bb51","ttft_stream_ms":1444,"time_to_request_ms":524,"first_content_frame_ms":1444,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":48469,"stop_reason":"end_turn","session_id":"dd68fe99-bcdd-448c-bf1b-2fb9f20cbd71","total_cost_usd":0.00613647,"usage":{"input_tokens":2,"cache_creation_input_tokens":340,"cache_read_input_tokens":13077,"output_tokens":11875,"output_tokens_details":{"thinking_tokens":9645},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":340,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11875,"cache_read_input_tokens":13077,"cache_creation_input_tokens":340,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":340},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11875,"cacheReadInputTokens":13077,"cacheCreationInputTokens":340,"webSearchRequests":0,"costUSD":0.00613647,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":9645,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A detector must let the project write its own rules, registered with the same standing as bundled rules (4.1).\n- A detector must offer a harness that runs one rule against supplied code and shows whether it fired, for bundled and project rules alike (4.2).\n- Every rule has an identifier that is stable, not derived from its path, class name or position, and is printed unaltered with every finding (4.3).\n- A practitioner can run the detector locally, including on a single file, and sees findings in the command's own output. No finding may be reportable only through a hosted, licence-tier or CI-only route (5.1–5.4).\n- A printed identifier resolves to its documentation. For bundled rules, the documentation ships with the installed copy, works offline, and covers every identifier the rule can print (6.1–6.3).\n- Any inline suppression route must be switchable off by configuration or detectable (7.1).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. Yes, a detector written before the document and never read against it can conform. Section 8 says it \"satisfies every MUST in sections 4 to 7\", and 8.1 says \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7.\" It also says \"a [Detector] without one can still be found to [Conform].\"\n\n**2b.** The detector must either make the route disableable by configuration or make it detectable. Doing one of those is enough. Section 7.1 says \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable…\" It adds: \"A route that can be neither switched off nor seen does not [Conform].\" The reason clause (7.2) is a SHOULD, so it is not needed for conformance.\n\n**2c.** The documentation must ship inside the installed rule package, at the same version as the rule, and must be reachable without network access. Section 6.3 says \"Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1, to a page in that shipped documentation.\" Section 6.2 says \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\" Section 6.5 adds that any family list or pattern \"lives in the installed file\".\n\n## 3. Application\n\nThe listed clauses cover every MUST in sections 4 to 7. The SHOULDs (4.4, 6.4, 7.2) and the optional 6.5 are not graded here.\n\n| Clause | Grade | Reasoning |\n|---|---|---|\n| 4.1 | Yes | Project rules are written as a Zig module implementing `Rule`, listed in `lintomatic.toml`, and \"are first class in every report.\" |\n| 4.2 | Yes | `check --only` \"accepts any rule name, bundled or project\" and exits 1, 0 or 2. The fixture does not spell out the printed output for `--only`, so I infer it is the same finding lines. |\n| 4.3 | Yes | Bundled `LM-NNNN` identifiers are \"fixed at the rule's first release\", and Lintomatic \"does not add or rewrite any part of the name.\" Identifiers are printed on the one-line output. No machine-readable format is described, and the fixture does not say whether the HTML report prints identifiers. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | One line per finding goes to standard output, with location and identifier, \"whether or not the HTML report is enabled.\" That output prints every finding, so there is no remainder. |\n| 5.4 | Yes | The hosted dashboard is optional, and \"every finding it shows is also printed by the command line.\" CI runs the same binary. |\n| 6.1 | Yes | `explain <identifier>` is keyed on the identifier alone, and project rules print their `doc` string or `No documentation declared`. A missing doc is a 6.3 failure, not a 6.1 one. |\n| 6.2 | Yes | `explain` \"prints the documentation … from the installed package\", \"versioned with the package; there is no separate website.\" |\n| 6.3 | **No** | \"Two of the forty rules currently print `No documentation declared`.\" The forty are bundled rules, so two bundled identifiers resolve to no page. Under 6.3, \"One Identifier that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` can be disabled with `ignore_comments = false` in `lintomatic.toml`, which is the disableable route. |\n\n**Conformance under section 8:** Lintomatic does not conform. Every other MUST is met, but 6.3 fails, and section 8 requires every MUST to be satisfied. It is in the partial condition the document describes, and that must not be called conformance.\n\n**Does 6.4 change the verdict?** No. 6.4 is a SHOULD, and section 8 defines conformance by MUSTs only. The fixture also does not say Lintomatic ships inside a toolchain, so 6.4 applies as a SHOULD and not as the toolchain self-audit MUST. The fixture's own CI gap is the one 6.4 describes: the release check that would have caught the two undocumented rules does not exist. That does not change the verdict, but it explains why the 6.3 failure has gone unnoticed. The fixture also mentions no declaration under 8.1, so no declared-gap duty is triggered.\n\n## 4. Confusion\n\n- **8.1 (example):** The JSON example sets `\"method\": \"1.0.1\"`, but the document header names the companion method specification as version 1.1.0. I could not tell whether the field means the method version this detector conforms to, or something else. The passage: `\"method\": \"1.0.1\"`.\n- **6.1:** \"Where the [Identifier] is itself a URL, as method clause 3.6 allows…\" The method specification was not provided, so I could not check this cross-reference.\n- **7.1:** \"the method specification's position is that [Suppression] is an [Owner] decision under its clause 3.4 and section 4.\" The terms [Owner], [Class] and [Hazard] are used throughout but defined only in the method specification, which I was not given.\n- **4.2:** \"a [Detector] failing 4.1 is graded here on its [Bundled rules].\" On one reading, a detector that fails 4.1 has no bespoke rules to test, so 4.2 is applied to the bundled rules alone. I found the sentence's purpose unclear until I reached that reading.","ttft_ms":41284,"type":"result","duration_ms":49430,"uuid":"bd0b6d4f-f210-403c-acfb-6c6cc978e34e","ttft_stream_ms":1452,"time_to_request_ms":960,"first_content_frame_ms":1452,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":44098,"stop_reason":"end_turn","session_id":"dc269027-100d-432a-973c-5ca84faa1392","total_cost_usd":0.0076205299999999995,"usage":{"input_tokens":2,"cache_creation_input_tokens":11264,"cache_read_input_tokens":2153,"output_tokens":10692,"output_tokens_details":{"thinking_tokens":8532},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11264,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":10692,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11264,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11264},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":10692,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11264,"webSearchRequests":0,"costUSD":0.0076205299999999995,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":8532,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A Detector must let the project write its own rules and register them with the same standing as bundled rules (4.1).\n- It must offer a harness that runs one rule against supplied code and shows whether it fired and what it printed (4.2).\n- Every rule carries a stable identifier, not derived from its path, class name or position. The identifier is printed unaltered with every finding (4.3). A self-enforcing rule for this is a SHOULD (4.4).\n- It must run locally with no infrastructure, over a subset down to a single file. The command's own output must carry a usable summary, with location and identifier for each finding, and no finding may be reachable only through a hosted, licence-tier or CI-only route (5.1–5.4).\n- A printed identifier must resolve on its own to its documentation. For bundled rules, that documentation must be on disk, usable without network access, and shipped at a tracked version, with every identifier the rule can print resolving to a page (6.1–6.3). Failing the release when that is untrue is a SHOULD (6.4).\n- An inline suppression route must be either disableable by configuration or detectable (7.1). Requiring a written reason is a SHOULD (7.2).\n\n## 2. Load-bearing statements\n\n**2a.** Conformance means satisfying every MUST in sections 4 to 7. A detector written before the document, and unaware of it, can conform, because it can be graded on evidence rather than on a declaration. From section 8: \"A Detector Conforms if it satisfies every MUST in sections 4 to 7.\" From 8.1: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence\" and \"a [Detector] without one can still be found to [Conform].\"\n\n**2b.** The detector must make the route either disableable by configuration or detectable, meaning a project can find every use of it through a bespoke rule or a documented mechanical check. One of those is enough: \"For each one it MUST do at least one of two things, and either alone satisfies this clause\" (7.1). For ignore comments specifically, a detector \"whose [Rules] never see comments offers only the second,\" which is the mechanical check.\n\n**2c.** The documentation must ship with the rule, in the installed package, at a version tracked together with it: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together\" (6.3). It must also resolve without network access: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (6.2).\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n| --- | --- | --- |\n| 4.1 | Yes | A project writes a Zig module implementing `Rule`, lists it in `lintomatic.toml`, and it is \"first class in every report.\" `--only` also accepts project rules. |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, exits 1, 0 or 2, and applies to bundled rules too. The fixture gives only the exit code for `--only`. That it prints the findings is inferred from `check`'s output. |\n| 4.3 | Yes | Bundled identifiers are `LM-NNNN`, \"fixed at the rule's first release.\" Project names come from configuration, and \"Lintomatic does not add or rewrite any part of the name.\" The identifier is on every line of default output. No machine-readable format is described, so there is no other output to check. |\n| 5.1 | Yes | The tool \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` accepts \"a directory or a single file.\" |\n| 5.3 | Yes | One line per finding goes to stdout with location and identifier, \"whether or not the HTML report is enabled.\" Every finding is printed, so there is no remainder. |\n| 5.4 | Yes | The hosted dashboard shows nothing the command line does not print: \"every finding it shows is also printed by the command line.\" CI runs the same binary. |\n| 6.1 | Yes | `lintomatic explain <identifier>` is keyed on the identifier as printed and covers bundled and project rules. The two undocumented rules fail 6.3, not this clause. |\n| 6.2 | Yes | Documentation is \"versioned with the package; there is no separate website,\" and `explain` reads \"from the installed package.\" |\n| 6.3 | No | Two of the forty bundled rules \"currently print `No documentation declared`\", so their identifiers resolve to no page. \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | The `// lintomatic-ignore` route is disableable with `ignore_comments = false` in `lintomatic.toml`. |\n\nTwo readings are mine. First, I took the two undocumented rules to be bundled, since the fixture counts them among \"the forty rules.\" Second, I took the explain message to apply to them, though the fixture only mentions that message for project rules. I did not consult `TOOLING-SPEC.md`, which I was not given, so nothing here addresses toolchain-level obligations.\n\n**Conformance: No.** Section 8 requires every MUST in sections 4 to 7 to hold, and 6.3 is a MUST that fails. Lintomatic is partially conforming, and under section 8 that cannot be described as conformance.\n\n**Clause 6.4: it does not change the verdict.** 6.4 is a SHOULD, and section 8 counts only MUSTs. Lintomatic does not meet 6.4: its repository runs `check src` in CI but does not check that every `LM-NNNN` has an `explain` entry. That is a real gap, and it is the check that would have caught the 6.3 failure. It is still a process gap rather than a change to the verdict. If Lintomatic declared a version under 8.1, the 6.3 gap would have to be recorded in `known-gaps`.\n\n## 4. Confusion\n\nSection 8.1: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on any [Detector], declared or not, rests on that check and not on the claim.\"\n\nIt sits under a heading about the optional maintainer declaration, but it states how every detector is graded. \"MAY be graded\" is a permission addressed to a grader, while the preceding sentences make conformance a matter of meeting MUSTs. On my reading, I could not tell at first whether a detector's status depends on the grading or on the declaration.","ttft_ms":37370,"type":"result","duration_ms":44616,"uuid":"687502fd-024a-4db0-bdbb-2f7c1468c26e","ttft_stream_ms":1303,"time_to_request_ms":519,"first_content_frame_ms":1303,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":58067,"stop_reason":"end_turn","session_id":"7d2ebec1-8381-44a5-a4b9-2c1374578405","total_cost_usd":0.00944273,"usage":{"input_tokens":2,"cache_creation_input_tokens":11265,"cache_read_input_tokens":2153,"output_tokens":14336,"output_tokens_details":{"thinking_tokens":12068},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11265,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14336,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11265,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11265},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14336,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11265,"webSearchRequests":0,"costUSD":0.00944273,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12068,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- A project must be able to write its own rules and register them with the same standing as bundled rules (4.1).\n- Any rule, bundled or project-written, must be runnable on its own against supplied code (4.2).\n- Every rule carries a stable identifier, not derived from its file path, class name or position, and the identifier is printed unaltered with every finding in default and machine-readable output (4.3).\n- The detector runs locally with no infrastructure, including on a single file, and its command output carries a usable summary with location and identifier for each finding, plus a pointer to any findings it leaves out (5.1–5.4).\n- A printed identifier resolves to its documentation, keyed on the identifier exactly as printed. For bundled rules, this works offline from the installed copy, and every identifier the rule can print has documentation shipped at the same version (6.1–6.3).\n- Any inline suppression route must be disableable by configuration or detectable (7.1). A detector conforms only if it meets every MUST in sections 4 to 7 (8).\n\n## 2. Load-bearing statements\n\n**2a.** Conforming means satisfying every MUST in sections 4 to 7. A detector written before the document, and never read against it, can still conform, because the verdict rests on checking it, not on a declaration.\n> \"A [Detector] **[Conforms]** if it satisfies every MUST in sections 4 to 7.\" (§8)\n\n> \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence: anyone may grade it, by checking it against each clause of sections 4 to 7\" (§8.1)\n\n> \"The declaration is how a maintainer claims [Conformance]; it is not a condition of it, and a [Detector] without one can still be found to [Conform].\" (§8.1)\n\n**2b.** The detector must do at least one of two things: make the route disableable by configuration, or make it detectable. Doing one of them is enough.\n> \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable, by a bespoke [Rule] … or by a mechanical check the [Detector] documents.\" (§7.1)\n\n> \"A route that can be neither switched off nor seen does not [Conform].\" (§7.1)\n\nRequiring a written reason for the suppression is a SHOULD (§7.2), so it is not needed for conformance.\n\n**2c.** The documentation must ship with the rule, at a version tracked together with it, and it must resolve from the installed copy with no network access. A website does not count.\n> \"A [Bundled rule]'s documentation MUST ship with the rule, at a version tracked together.\" (§6.3)\n\n> \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access\" (§6.2)\n\n> \"A catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong place.\" (§6.2, Why)\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | Yes | \"A project can add its own rules by writing a Zig module that implements the `Rule` interface and listing it in `lintomatic.toml`; project rules are loaded on every run and are first class in every report.\" Arbitrary patterns can be expressed, with the same standing. |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, bundled or project, and exits 1, 0 or 2 to report fired, not fired or unknown. Caveat: the fixture does not say explicitly that `--only` prints the finding lines. I have read it as using the same one-line output as `check`. |\n| 4.3 | Yes | `LM-NNNN` is \"fixed at the rule's first release.\" Project names are assigned in `lintomatic.toml`, and \"Lintomatic does not add or rewrite any part of the name.\" Identifiers are printed on each finding line. No machine-readable format is described, so that limb cannot be tested. I have not counted it against the detector. |\n| 5.1 | Yes | \"The tool runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | \"`lintomatic check <path>` analyses a directory or a single file.\" |\n| 5.3 | Yes | The one-line form is printed \"whether or not the HTML report is enabled.\" Each line carries location and identifier. Every finding is printed, so there is no remainder. |\n| 5.4 | Yes | \"every finding it shows is also printed by the command line.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone, keyed on it as printed, and project identifiers are not rewritten. The two bundled rules that print \"No documentation declared\" are a 6.3 failure, per 6.1's own wording, not a 6.1 failure. |\n| 6.2 | Yes | `explain` prints \"from the installed package,\" and \"The documentation is versioned with the package; there is no separate website.\" |\n| 6.3 | No | \"two of the forty rules currently print `No documentation declared`.\" Under 6.3, \"One [Identifier] that does not resolve fails this clause, however many others do.\" This is the absent-documentation failure the clause names. |\n| 7.1 | Yes | The comment can be disabled with `ignore_comments = false` in `lintomatic.toml`, which is disableable by configuration and so satisfies the clause alone. |\n\n**Conformance under §8: No.** §8 requires every MUST in sections 4 to 7, and 6.3 fails. Lintomatic is therefore not Conforming. Under §8, a partial result must not be described as Conformance.\n\n**Does 6.4 change the verdict? No.** Clause 6.4 is a SHOULD, and §8 counts only MUSTs. The fixture says Lintomatic's own repository does not check that every `LM-NNNN` has an `explain` entry, so its release does not fail on the missing documentation. That is a gap against a SHOULD. It is also the check that would have caught the 6.3 failure. The verdict would be the same even if 6.4 were a MUST, because 6.3 already fails.\n\nThe other SHOULDs and MAYs (4.4, 6.5, 7.2) do not affect the verdict. The fixture says the inline comment takes no reason, which is a SHOULD gap under 7.2.\n\n## 4. Confusion\n\nOne passage I could not resolve from the document alone:\n\n> \"Where the [Identifier] is itself a URL, as method clause 3.6 allows\" (§6.1)\n\nThe method specification was not provided, so I could not check what clause 3.6 allows. The same applies to the other references to method clauses, such as 4.2's \"clause 3.3 of the method specification\" and 8.1's \"the method's clause 3.2\", and to terms such as *Class* and *Owner*, which are defined there. I took these references at face value.","ttft_ms":50905,"type":"result","duration_ms":58490,"uuid":"0db62a2c-a418-43ca-97a3-be6e9090b231","ttft_stream_ms":965,"time_to_request_ms":417,"first_content_frame_ms":965,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":55543,"stop_reason":"end_turn","session_id":"4eeae747-7b64-4d2e-8590-b08c29743b7d","total_cost_usd":0.00900283,"usage":{"input_tokens":2,"cache_creation_input_tokens":11263,"cache_read_input_tokens":2153,"output_tokens":13457,"output_tokens_details":{"thinking_tokens":11441},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":11263,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13457,"cache_read_input_tokens":2153,"cache_creation_input_tokens":11263,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":11263},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13457,"cacheReadInputTokens":2153,"cacheCreationInputTokens":11263,"webSearchRequests":0,"costUSD":0.00900283,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11441,"canonicalModel":"claude-haiku-5-5","provider":"firstParty","costBasis":"list"}},"permission_denials":[],"terminal_reason":"completed","fast_mode_state":"off","fast_mode_disabled_reason":"sdk_opt_in_required","subagent_stats":{"spawned":0,"requested":{"background":0,"foreground":0,"unset":0},"started_in_background":0,"max_depth":0,"spawned_by_subagents":0,"completed":0,"failed":0,"killed":{"parent":0,"user":0,"system":0},"refused":{"depth_limit":0,"concurrency_limit":0,"budget":0},"by_type":{}},"safety_stops":0,"is_error":false,"num_turns":1,"subtype":"success","api_error_status":null,"result":"## 1. Restatement\n\n- Let a project write its own rules and register them with the same standing as bundled rules (4.1).\n- Provide a harness that runs one rule against supplied code and reports whether it fired and what it printed (4.2).\n- Give each rule a stable identifier, chosen by its author and not derived from file path, class name or position, and print it unaltered with every finding (4.3).\n- Run locally with no infrastructure, on a single file as well as a whole codebase, with a usable summary and identifiers in the command's own output. No finding may be reportable only through a hosted service, licence tier or CI-only mode (5.1–5.4).\n- Resolve a printed identifier to its documentation, keyed on the identifier exactly as printed. A bundled rule's documentation ships with the installed rule at a tracked version, every identifier it can print resolves, and this works offline (6.1–6.3).\n- Offer any inline suppression route only if it can be disabled by configuration or detected (7.1). A written reason is SHOULD (7.2).\n\n## 2. Load-bearing statements\n\n**2a.** A detector conforms when it satisfies every MUST in sections 4 to 7. A detector written before the document, and never checked against it, can still conform. Conformance is judged by checking the detector against each clause, not by a claim. The document says: \"A [Detector] that predates this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence\". It also says: \"a [Detector] without one can still be found to [Conform].\"\n\n**2b.** The detector must do at least one of two things for the inline route: make it disableable by configuration, or make it detectable. One of these is enough. The document says: \"For each one it MUST do at least one of two things, and either alone satisfies this clause: make the route disableable by configuration; or make the route detectable…\". It also says \"A route that can be neither switched off nor seen does not [Conform].\" A reason requirement is only SHOULD under 7.2, so a comment with no reason does not by itself break conformance.\n\n**2c.** The documentation must ship with the installed rule, at a version tracked together with it, and must be reachable without network access. Clause 6.3 says: \"A bundled rule's documentation MUST ship with the rule, at a version tracked together.\" Clause 6.2 says: \"Resolution of a bundled rule's identifier MUST work from the installed copy, without network access.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n| --- | --- | --- |\n| 4.1 | Yes | Projects write a Zig module implementing `Rule` and list it in `lintomatic.toml`. Project rules are \"first class in every report.\" |\n| 4.2 | Yes | `lintomatic check --only <identifier> <path>` runs one rule, \"bundled or project\", and exits 1 or 0 for fired or not. Its output shows what printed. |\n| 4.3 | Yes | `LM-NNNN` is \"fixed at the rule's first release\". Project names are the configured name, which \"Lintomatic does not add or rewrite.\" The identifier is printed on the one-line output. See §4 on the HTML report. |\n| 5.1 | Yes | \"runs locally with no account, no server and no network.\" |\n| 5.2 | Yes | `lintomatic check <path>` \"analyses a directory or a single file.\" |\n| 5.3 | Yes | One line per finding on standard output, with location and identifier, \"whether or not the HTML report is enabled.\" Every finding is printed, so there is no remainder. |\n| 5.4 | Yes | The local output carries every finding. The dashboard shows only findings \"also printed by the command line,\" and \"the same binary is what CI runs.\" |\n| 6.1 | Yes | `lintomatic explain <identifier>` takes the identifier alone. Bundled rules return their documentation, and project rules return their `doc` string or \"No documentation declared.\" |\n| 6.2 | Yes | Documentation comes \"from the installed package,\" and \"there is no separate website.\" |\n| 6.3 | **No** | The fixture says \"two of the forty rules currently print `No documentation declared`.\" That message is not a page, so those two identifiers do not resolve. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 7.1 | Yes | `// lintomatic-ignore` can be disabled with `ignore_comments = false`, which is disableable by configuration. |\n\n**Conformance under §8:** Lintomatic does not conform. Section 8 says a detector \"Conforms if it satisfies every MUST in sections 4 to 7.\" Lintomatic meets ten of the eleven MUSTs listed and fails 6.3. Its status is partial conformance, and per §8, \"Partial [Conformance] MUST NOT be described as [Conformance].\" The fixture has no conformance declaration. Under 8.1 that is optional and does not change the verdict.\n\n**Effect of 6.4:** No, it does not change the verdict. Clause 6.4 is SHOULD, and §8 counts only MUSTs. The verdict already rests on 6.3. Lintomatic's failure to run the check in 6.4 is a separate SHOULD gap. The fixture notes that the repository \"does not check that every `LM-NNNN` identifier has an `explain` entry\", which is the check 6.4 describes. The document also says that where a detector ships inside a toolchain, the toolchain spec makes this check a MUST for the toolchain. That affects the toolchain's verdict, not the detector's, and I was not given the toolchain spec to grade it.\n\n## 4. Confusion\n\n- **4.3:** \"The [Detector] MUST print it, unaltered, alongside every finding the [Rule] reports, in its default output and in every machine-readable format it offers.\"\n\n  On my reading, it is unclear whether the HTML report counts as a \"machine-readable format\" the detector offers. \"Machine-readable\" is not defined, and 5.3 calls the HTML a \"fuller report.\" The fixture does not say whether the HTML report includes identifiers. My grade of Yes for 4.3 assumes the HTML report is not a machine-readable format.","ttft_ms":48689,"type":"result","duration_ms":56004,"uuid":"a2efb742-8d57-4398-920e-7fc73201eae2","ttft_stream_ms":1047,"time_to_request_ms":464,"first_content_frame_ms":1047,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 078: evidence under ACCEPTANCE.md, The record. Posted once; never edited, hidden or deleted.

The exact prompt every reader received, part 1 of 1

===== FILE: QUESTIONS.md =====
# Questions for a cold reader of DETECTOR-SPEC.md

You have been given `DETECTOR-SPEC.md` and the fixture `fixtures/lintomatic.md`, and nothing
else. Read the document once, then answer every question below in order. Quote the document
where a question asks for a quotation. Do not consult anything outside what you were given.

## 1. Restatement

In your own words and in at most six bullets, what does this document require of a detector?

## 2. Load-bearing statements

Answer each part of each question in a sentence or two, then quote the sentence or sentences of
the document you are relying on.

- 2a. What does it mean for a detector to conform, and can a detector that was written before
  this document existed, and has never heard of it, conform?
- 2b. A detector ships an inline ignore comment. What must the detector do about that route for
  it to conform, and is doing one of those things enough?
- 2c. Where must the documentation for a bundled rule's identifier live, at what version, and
  must it be reachable without network access?

## 3. Application

Grade Lintomatic 4.2, as described in the fixture, against every MUST clause in sections [4](../../DETECTOR-SPEC.md#4-authoring-rules) to [7](../../DETECTOR-SPEC.md#7-suppression):
[4.1](../../DETECTOR-SPEC.md#41-the-detector-must-support-bespoke-rules-written-by-the-project-that-runs-it), [4.2](../../DETECTOR-SPEC.md#42-the-detector-must-provide-a-harness-that-runs-a-single-rule-against-supplied-code), [4.3](../../DETECTOR-SPEC.md#43-the-detector-must-allow-a-rule-to-carry-a-stable-identifier-and-must-print-it-with-every-finding), [5.1](../../DETECTOR-SPEC.md#51-the-detector-must-be-invocable-by-the-practitioner-locally-with-no-infrastructure), [5.2](../../DETECTOR-SPEC.md#52-the-detector-must-support-invocation-over-a-subset-at-minimum-a-single-file), [5.3](../../DETECTOR-SPEC.md#53-the-result-must-reach-the-practitioner-in-the-output-of-the-command-they-ran), [5.4](../../DETECTOR-SPEC.md#54-a-finding-must-not-be-reportable-only-through-a-hosted-service-licence-tier-or-ci-only-mode-the-practitioner-cannot-invoke-locally), [6.1](../../DETECTOR-SPEC.md#61-the-detector-must-provide-a-mechanism-that-resolves-a-printed-identifier-to-its-documentation), [6.2](../../DETECTOR-SPEC.md#62-resolution-of-a-bundled-rules-identifier-must-work-from-the-installed-copy-without-network-access), [6.3](../../DETECTOR-SPEC.md#63-a-bundled-rules-documentation-must-ship-with-the-rule-at-a-version-tracked-together), [7.1](../../DETECTOR-SPEC.md#71-a-detector-may-offer-an-inline-suppression-route-but-must-make-it-detectable-or-disableable). For each give Yes, Partial or No and one
line of reasoning. Then state whether Lintomatic conforms under section [8](../../DETECTOR-SPEC.md#8-conformance), and why. Finally,
state whether clause [6.4](../../DETECTOR-SPEC.md#64-the-detector-should-fail-its-own-release-if-a-bundled-rule-lacks-resolvable-documentation) changes the verdict, and why.

## 4. Confusion

Quote any passage you found confusing on your one reading, with its clause number. Do not say what
would make it clearer and do not propose any change. Write "none" if there was none.

===== FILE: DETECTOR-SPEC.md =====
# Defence Before Fix: Detector Specification

**Version**: 1.0.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the toolchain specification](TOOLING-SPEC.md), version 0.2.0
**Author**: [Joseph Edmonds](https://ltscommerce.dev), [Edmonds Commerce](https://edmondscommerce.co.uk)
**Coined**: 22 February 2026, in [the original article](https://ltscommerce.dev/articles/defence-before-fix-static-analysis)

## 1. What this document is for

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are to be interpreted as
described in RFC 2119.

[The method specification](SPEC.md) states what a [Practitioner] does when a
[Defect] is found. This document states what a [Detector] must offer so that they
can do it: write a [Rule], prove it, run it and resolve what it prints. It is addressed to
whoever maintains a [Detector], which the method specification defines as a tool that reads
code without executing it and reports occurrences of a pattern.

A [Detector] is one part of a project's [Toolchain], and this document judges it
on what it offers alone. What the assembled [Toolchain] of a project must add on top, the
[Project record], the listing of active [Defences] and the
governance of [Suppression], is stated in [the toolchain specification](TOOLING-SPEC.md).
The two are separable because they are built by different people: a [Detector] is authored once
and installed into projects its maintainer will never see, whilst governance is decided by each
project for itself. A document that asked a [Detector] to enforce a project's governance would
fail every [Detector] in use and would not make any project better governed.

**The governing principle**: where the method specification requires a [Practitioner] to do
something with a [Rule], a [Conforming] [Detector] MUST make that possible
without the project building the mechanism first. A [Detector] that leaves the project to
construct the means has moved the obligation rather than met it.

## 2. Terminology

Terms from the method specification carry over unchanged. Every capitalised term links to its
definition; the ones this document leans on most are, in short:

| Term           | In one line                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| [Detector]     | A tool that reads code without executing it and reports what it finds          |
| [Rule]         | One check a [Detector] evaluates                                               |
| [Message]      | The text a [Rule] prints when it fires                                         |
| [Identifier]   | The stable name printed with a finding that leads to its documentation         |
| [Practitioner] | Whoever is doing the work, a person or an [Agent]                              |
| [Toolchain]    | Everything a project assembles to run its checks through, [Detectors] included |
| [Suppression]  | Making a finding go away without fixing it                                     |
| [Baseline]     | A recorded set of existing findings a [Rule] is told to ignore                 |

These are additional.

#### Rule author

Whoever writes a [Rule]. May be the [Detector]'s maintainer, a [Toolchain]'s maintainer or the project that runs it.

#### Bundled rule

A [Rule] the [Detector] ships, or fetches on the [Practitioner]'s behalf from a source the [Detector]'s maintainer controls. Its [Rule author] will never see the codebases it runs in, so everything a [Practitioner] needs in order to act on it has to travel with it.

#### Harness

The route by which one [Rule] is run against supplied code and its findings observed, without the project's own test suite and without every other [Rule] running alongside it.

The distinction between a [Bundled rule] and a project's own [Rule] matters throughout.
The [Detector] owns the documentation of the first and can be held to shipping it; it cannot
know the documentation of the second, and what it owes there is the mechanism that lets the project
attach its own.

## 3. The division of responsibility

Each mechanism the method needs has two halves. Stating only one of them is what produces a
[Detector] that is *nearly* usable.

| Requirement                          | The [Detector] MUST provide                             | The [Rule author] supplies                              |
| ------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------- |
| Bespoke [Rules]                      | The authoring and registration route                    | The [Rules]                                             |
| The red proof                        | A [Harness]                                             | The [Fixture] and the red run                           |
| Running the [Rule]                   | A local invocation, including subsets                   | Running it                                              |
| The [Identifier]                     | A place to carry it, and printing it with every finding | Choosing it once                                        |
| Resolution of a [Bundled rule]       | The lookup, and the documentation, on disk              | Nothing                                                 |
| Resolution of a project's own [Rule] | The [Identifier] printed unaltered                      | The documentation and, with the [Toolchain], the lookup |
| Inline [Suppression]                 | A route the project can detect or disable               | The decision whether to forbid it                       |

Read down the middle column and the shape of a [Conforming] [Detector] is already
visible. Read across any row and the failure mode is visible too: either half alone leaves the
[Practitioner] stuck.

## 4. Authoring rules

### 4.1 The detector MUST support bespoke rules written by the project that runs it

Configuration of an existing [Rule] set is not sufficient. The project must be able to express a
pattern the [Detector]'s authors have never anticipated, and register it so that it runs with
the same standing as a [Bundled rule].

**Why**: the method turns a specific [Defect] into a [Class] [Defence], and the
[Classes] that matter most to a project are the ones peculiar to it. A [Detector] offering
only a fixed catalogue can defend against the industry's known [Hazards] and none of the
project's own, which is the half that carries its institutional knowledge.

### 4.2 The detector MUST provide a harness that runs a single rule against supplied code

A [Harness] reports, for a given input, whether the [Rule] fired and what it printed, without
executing the project's own test suite and without the other [Rules] obscuring the answer.
This applies to every [Rule] the [Detector] runs, bundled or bespoke; a
[Detector] failing 4.1 is graded here on its [Bundled rules].

**Why**: clause 3.3 of the method specification requires the [Rule] to be proven by making it go
red. A [Practitioner] who can only observe a [Rule]'s behaviour by running every
[Rule] over the whole codebase cannot demonstrate that a [Rule] fires on the pattern rather
than on something incidental.

### 4.3 The detector MUST allow a rule to carry a stable identifier, and MUST print it with every finding

The [Identifier] MUST be stable across releases and MUST NOT be derived from the [Rule]'s
file path, [Class] name or position in a configuration file. The [Rule author] chooses it
once. The [Detector] MUST print it, unaltered, alongside every finding the [Rule]
reports, in its default output and in every machine-readable format it offers. A prefix the
[Detector] adds from the invoking directory or the [Rule]'s location is derived from
the file path. A namespace the [Rule author] assigns once in configuration is not.

| [Identifier]       | Where it comes from                                                         | Stable? |
| ------------------ | --------------------------------------------------------------------------- | ------- |
| `proj.no-raw-sql`  | Written once by the [Rule author] in configuration, printed as is           | Yes     |
| `LM-0107`          | Assigned once by the [Detector]'s maintainer at the [Rule]'s first release  | Yes     |
| `rules/no-raw-sql` | Produced from where the [Rule]'s file sits; changes when the file moves     | No      |
| `NoRawSqlRule`     | The [Rule]'s [Class] name; changes when the [Rule] is renamed               | No      |
| `rule 7`           | The [Rule]'s position in a configuration file; changes when one is inserted | No      |

**Why**: the [Identifier] is the only string that reaches the [Practitioner] and the
only key their lookup can use. An [Identifier] that changes when a [Rule] is renamed
silently breaks every reference to it, including references written down by people who have left.
An [Identifier] the [Detector] carries but does not print is one the
[Practitioner] was never given.

### 4.4 The detector SHOULD enforce 4.3 with a rule of its own

A [Rule] over the [Rules], failing any [Rule] that reports without a stable
[Identifier].

**Why**: this is the method applied to the [Detector] itself, and it is cheap. The worked
example is `php-qa-ci`'s `RequireRuleIdentifierConstantRule`, a [Rule] hosted in PHPStan by a
[Toolchain] built on it: it rejects a magic-string [Identifier] and names the
constant to declare instead. Nothing about it needed to live outside the [Detector].

## 5. Reporting

### 5.1 The detector MUST be invocable by the practitioner, locally, with no infrastructure

**Why**: method specification clause 8.1. An [Agent] that cannot check its own work cannot
iterate against a [Defence], so the loop never closes in the turn where it is cheap to close.

### 5.2 The detector MUST support invocation over a subset, at minimum a single file

**Why**: 5.1 is satisfied in principle by a whole-codebase run and defeated in practice by one.
Checking a single edited file has to be fast enough to do on every edit, or it will not be done on
any.

### 5.3 The result MUST reach the practitioner in the output of the command they ran

Where the [Detector] writes fuller detail elsewhere, the invoked command's own output MUST
carry a usable summary and, where the summary leaves any finding out, the location of the
remainder. A summary is usable when each finding in it carries where it is and its
[Identifier]. The remainder is the findings the summary leaves out. Where the output prints
every finding, there is no remainder. A fuller report written elsewhere, such as a page with a
code snippet for each finding, is not a remainder, and the output need not name it.

**Why**: method specification clause 8.2. A report the [Practitioner] has to go and find is a
report that arrives after the decision it was meant to inform.

### 5.4 A finding MUST NOT be reportable only through a hosted service, licence tier or CI-only mode the practitioner cannot invoke locally

A finding that the [Detector] reports only through a hosted service, a licence tier or a
continuous-integration-only mode the [Practitioner] cannot invoke locally does not
[Conform], whatever the same [Rule] reports there.

**Why**: a [Rule] that fires only in an environment the [Practitioner] has no access to
teaches nobody anything and blocks them anyway, which is the worst combination available.

## 6. Resolving an identifier

### 6.1 The detector MUST provide a mechanism that resolves a printed identifier to its documentation

Two cases, by who wrote the [Rule]:

| The [Rule]        | Who supplies the documentation | What this clause asks of the [Detector]                                   |
| ----------------- | ------------------------------ | ------------------------------------------------------------------------- |
| A [Bundled rule]  | The [Detector]                 | Resolve the [Identifier], presented alone, to that documentation          |
| The project's own | The project                    | Print the [Identifier] unaltered; the lookup is the [Toolchain]'s to give |

In both, the mechanism is keyed on **the [Identifier] exactly as printed**. A command, an index
file or a URL are all acceptable forms. This clause asks for the mechanism, not for every page:
where the mechanism works but a [Bundled rule]'s [Identifier] has no documentation to resolve
to, that fails clause 6.3, not this clause. Each case in turn:

**For a [Bundled rule]**, the [Detector] supplies the documentation and the
lookup, and clauses 6.2 and 6.3 say where. The mechanism MUST resolve an [Identifier]
presented alone, because the reader who needs it most has the [Identifier] from a log, a
ticket or a colleague and not the [Message]. A documentation path printed in the [Message] is
therefore not enough on its own: it helps only a reader who has the [Message], and the
[Identifier] alone still leads nowhere.

**For a project's own [Rule]**, the [Detector] cannot know the documentation, so what
it owes is the half it can give: the [Identifier] printed unaltered under clause 4.3, and no
transformation of it. Where the [Identifier] is itself a URL, as method clause 3.6 allows,
the [Detector] prints that URL and has done what this clause asks. What this clause forbids is
a documentation path printed alongside a shorter [Identifier] that cannot be looked up on its
own. The lookup for such
a [Rule] is an obligation on the project's assembled [Toolchain], under clause 4.2
of the [toolchain specification](TOOLING-SPEC.md), and a [Detector] that offers it as well has
gone further than this clause asks.

**Why**: method specification clause 8.3 requires the [Identifier] to resolve without a human.
An index keyed on anything else does not resolve it. This is the most commonly failed clause in this
document and it fails in a specific way: documentation exists, is genuinely good, and is keyed on the
[Rule]'s [Class] or file name, which is a string the [Practitioner] was never
given. The lookup they can actually perform is the only one that counts.

### 6.2 Resolution of a bundled rule's identifier MUST work from the installed copy, without network access

**Why**: an [Agent] working offline, behind a proxy, or against a URL that has since moved needs
the answer to be on disk. A dependency the project already installed is on disk by definition. A
catalogue on the [Detector]'s website, however complete, is the right documentation in the wrong
place.

### 6.3 A bundled rule's documentation MUST ship with the rule, at a version tracked together

Every [Identifier] a [Bundled rule] can print MUST resolve, under clause 6.1,
to a page in that shipped documentation. One [Identifier] that does not resolve fails this
clause, however many others do. A page per [Identifier] satisfies this; a page per family of
[Identifiers] MAY be used instead, under clause 6.5.

**Why**: method specification clause 3.6. A [Bundled rule] travels into codebases its author
will never see. If its documentation lives only in the [Detector]'s repository or on its
website, then every project that installs it is one link rot away from a [Rule] that blocks
without explaining.

The failure to guard against is not the absent document but the **dangling one**: a reference to
documentation that was planned and never written is worse than no reference, because it consumes
the [Practitioner]'s attention before failing them.

### 6.4 The detector SHOULD fail its own release if a bundled rule lacks resolvable documentation

An automated check over every [Identifier] a [Bundled rule] can print, applying the
family list or pattern of clause 6.5 where one is used, that blocks the release when any of them
lands on no page.

**Why**: clause 6.3 is the clause most easily believed to be satisfied whilst being broken, because
the documentation is written by the same person who wrote the [Rule] and its absence is
invisible from the inside. Where the [Detector] is shipped inside a [Toolchain],
the [toolchain specification](TOOLING-SPEC.md)'s self-audit makes this check a MUST for the [Toolchain]; a
[Detector] released on its own is asked for it as a SHOULD because the same [Class] of
[Defect], a [Rule] that blocks without explaining, is detectable mechanically there too.

### 6.5 One page MAY document a family of identifiers, and SHOULD name its members so a check can confirm them

Where several [Bundled rules] share a prefix, one page MAY document them all. Such a page
SHOULD let the check clause 6.4 asks for confirm that each member resolves to it. Two forms do
that and one does not:

| The page                                                                                                  | A check can confirm each member?          |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Lists every full [Identifier] in the family, `LM-0100`, `LM-0101`, and so on                              | Yes                                       |
| Carries a regular expression the check can run, `^LM-01[0-9]{2}$`, matching every member and nothing else | Yes                                       |
| Says in prose that everything under `LM-01` is documented here                                            | No: a person can infer it, a check cannot |

The list or the regular expression lives in the installed file, since clause 6.2 requires
resolution to work from the installed copy, not only in a rendered web page.

**Why**: a family page is a convenience for the author, and the cost of it must not fall on the
check. A page that a person can see covers `LM-0107` but a check cannot leaves clause 6.4 with
nothing to run.

## 7. Suppression

### 7.1 A detector MAY offer an inline suppression route, but MUST make it detectable or disableable

An inline ignore comment, a per-line directive and a generated [Baseline] are all such
routes. The [Detector] MAY ship them. For each one it MUST do at least one of two things, and either
alone satisfies this clause: make the route disableable by configuration; or make the route
detectable, by a bespoke [Rule] the project writes for the [Detector] under clause 4.1 or by a
mechanical check the [Detector] documents. Either lets a project which decides to forbid the
route enforce that decision. A route that can be neither switched off nor seen does not [Conform].

A route is detectable when the project can find every use of it, in either of two ways: by a
bespoke [Rule] the project registers under clause 4.1 that matches the route wherever it is
used, which the [Detector] runs like any other bespoke [Rule] and need not ship itself; or by a
mechanical check the [Detector] documents, such as a text search for the route's spelling. The
first way needs the [Detector]'s [Rules] to be able to match the route's text, so a [Detector]
whose [Rules] never see comments offers only the second for an ignore comment.

**Why**: the method specification's position is that [Suppression] is an [Owner]
decision under its clause 3.4 and section 4, and an [Owner] cannot decide something they are
never shown. The [Detector] is not the [Owner] and does not know the project's
governance, so it is not asked to enforce it; what it is asked is not to hide the route. Every
[Detector] in wide use ships an inline ignore, and a clause that forbade them would fail all of
them without governing any project better. Whether the route is forbidden is the project's decision,
enforced through its [Toolchain] under clause 4.3 of the [toolchain specification](TOOLING-SPEC.md).

### 7.2 An inline suppression route SHOULD require a written reason

The [Detector] SHOULD reject, or be configurable to reject, an inline [Suppression]
that carries no reason, and SHOULD NOT supply a default one, including each entry of a generated
[Baseline].

**Why**: a [Suppression] without a reason is indistinguishable from one nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence costs the author a
minute at the moment they have the reason in mind, and it is the only thing that makes the
[Suppression] reviewable later. PHPStan's `reportIgnoresWithoutComments` is the shape of it.

## 8. Conformance

**A [Detector] [Conforms]** if it satisfies every MUST in sections 4 to 7.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Detector]
that satisfies most of this document is in a normal and respectable condition; it is not
[Conforming], and describing it as such removes the only value the word has.

This document defines one level. The clauses of the method specification's section 8 that reach
beyond what sections 4 to 7 here already secure, the listing of active [Defences] and the
summary for an [Agent]'s context, are obligations on a project's assembled [Toolchain]
and are stated in the [toolchain specification](TOOLING-SPEC.md), so there is no separate [Agent]-support level
for a [Detector].

### 8.1 A maintainer MAY declare the version of this document the detector conforms to, and the declaration records known gaps

The declaration is machine-readable, in whatever form the [Detector]'s ecosystem uses to
record dependencies. The same declaration is where a gap against this document is recorded once it is
known: a [Detector] that declares a version and has learnt, from its own checks or from a
[Practitioner]'s report under the method's clause 3.2, that it fails a MUST in sections 4 to 7
MUST record that gap alongside that version, in the same file or one it names. A declaration
with a non-empty gap record is a statement of where the [Detector] stands and is not a claim of
[Conformance].

The declaration is optional, and so the duty above falls only on a [Detector] that has one; a
gap a [Practitioner] finds is recorded in their own project's record under the method's clause
3.2 in any case. The declaration is how a maintainer claims [Conformance]; it is not a condition
of it, and a [Detector] without one can still be found to [Conform]. A [Detector] that predates
this document, or whose maintainer has never read it, MAY be graded [Conforming] on evidence:
anyone may grade it, by checking it against each clause of sections 4 to 7, and a verdict on
any [Detector], declared or not, rests on that check and not on the claim. A declaration tells the reader what the maintainer believes and what they know to be missing;
the reader still runs the [Harness].

The shape is illustrative rather than prescribed. In a Composer manifest:

```json
"extra": {
  "defence-before-fix": {
    "method": "1.0.1",
    "detector": "1.0.0",
    "toolchain": null,
    "known-gaps": []
  }
}
```

In a package.json, the equivalent is a top-level `defenceBeforeFix` object with the same keys. A
[Detector] that is not also shipped as a [Toolchain] leaves `toolchain` empty;
a project that ships both declares both. Each entry in `known-gaps` names the clause and states the
gap in a sentence.

**Why**: a [Conformance] claim in a README is a sentence; a claim in a manifest is a fact about
a specific installed artefact, checkable by anyone, including mechanically, and it fixes what
"[Conforming]" meant at the point the claim was made. Making the claim a condition of
[Conformance], though, would mean a [Detector] with every mechanism in place could
never [Conform] until its maintainer had heard of this document, which grades the
maintainer's reading rather than the [Detector].

## 9. Relationship to the other specifications

This document adds no obligations to a [Practitioner] and relaxes none. Every clause here
exists to make a clause of the method specification achievable with a [Detector] in hand.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes one piece of the equipment.

The [toolchain specification](TOOLING-SPEC.md) states what a project's assembled [Toolchain] must offer beyond
what each [Detector] in it offers, and it requires every [Detector] a [Defence]
is routed through to [Conform] to this one. A [Detector] shipped inside a
[Toolchain] is measured here as a [Detector] and there as part of the
[Toolchain]; the two verdicts are separate and neither implies the other.

Nothing here requires a project to use a [Conforming] [Detector]. A project can
[Conform] to the method specification on a [Detector] that [Conforms] to
none of this, at the cost of building the missing mechanisms itself. This document exists so that it
does not have to.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[bundled rule]: #bundled-rule
[bundled rules]: #bundled-rule
[class]: SPEC.md#class
[classes]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[fixture]: SPEC.md#fixture
[harness]: #harness
[hazards]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[project record]: TOOLING-SPEC.md#project-record
[rule]: SPEC.md#rule
[rule author]: #rule-author
[rules]: SPEC.md#rule
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain

===== FILE: fixtures/lintomatic.md =====
# Fixture: Lintomatic 4.2

A fictional detector, described only as far as its documentation would describe it. Grade it
against the document you were given. Where the description does not say, answer from what is
written, not from what a real tool would probably do.

## What the documentation says

Lintomatic is a static analyser for the Zig language. It ships forty rules. A project can add its
own rules by writing a Zig module that implements the `Rule` interface and listing it in
`lintomatic.toml`; project rules are loaded on every run and are first class in every report.

The command `lintomatic check <path>` analyses a directory or a single file and prints one line
per finding to standard output:

```
src/db.zig:41:7  LM-0107  Result of fallible call discarded
src/db.zig:88:3  proj.no-raw-sql  Query built by string concatenation
```

Fuller detail, including a snippet, is written to `.lintomatic/report.html`. The one-line form is
printed whether or not the HTML report is enabled.

`lintomatic check --only <identifier> <path>` runs a single rule. It accepts any rule name,
bundled or project, and exits 1 when the rule fires, 0 when it does not, and 2 when the rule name
is unknown.

Rule identifiers for bundled rules are of the form `LM-NNNN` and are fixed at the rule's first
release. Project rules are identified by the name the project gives them in `lintomatic.toml`,
which the documentation recommends prefixing with `proj.`; Lintomatic does not add or rewrite
any part of the name.

`lintomatic explain <identifier>` prints the documentation for a bundled rule from the installed
package: what the rule finds, why, and the recommended construction. For a project rule it prints
the `doc` string the rule module declares, or `No documentation declared` when there is none.
The documentation is versioned with the package; there is no separate website.

Lintomatic honours the comment `// lintomatic-ignore <identifier>` on the line before a finding.
The comment can be disabled project-wide with `ignore_comments = false` in `lintomatic.toml`.
The comment takes no reason and the documentation does not mention one.

The tool runs locally with no account, no server and no network, and the same binary is what CI
runs. There is a hosted dashboard, sold separately, that aggregates reports across repositories;
every finding it shows is also printed by the command line.

Lintomatic's own repository runs `lintomatic check src` in CI but does not check that every
`LM-NNNN` identifier has an `explain` entry; two of the forty rules currently print
`No documentation declared`.