[LTSCommerce]

What this changes

TOOLING-SPEC.md, the contradictions cold cohorts of other changes kept naming in text those changes had not touched, each a row of acceptance/ROUTED.md:

• Section 9 against clause 9.1 on what section 8 is: a toolchain is graded against this document under section 9, and the project's remediations against section 7 of the method specification.
• Clause 4.2 against the Defence row of section 2: the clause now says what it requires of every blocking rule the toolchain runs, the project's own and the bundled alike, keyed on the identifier as printed, with the remediation docs shipped at a version tracked together; and section 2 closes with a paragraph saying that a blocking rule whose documentation is missing is not yet a defence, that clause 5.1 does not require it to be listed, and that clause 4.2 reaches it. The 4.2 heading reads "a blocking rule it routes" in place of "a defence it routes".
• Clause 8.1 on the same point, and clause 9.2's gap duty against the optional declaration.
• Clause 4.3's heading against its body: "forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own".
• Clause 4.1's count of the detector specification's MUSTs and its point 2: the clause holds the detector to every MUST of that document's sections 4 to 7, the restated sentences being where a grader looks first and not the whole test, and a grader without that document to hand checks only them and says so. Section 1's "How to read this document" says the same.

The section 3 table's Remediation docs row follows clause 4.2.

The observed case

Runs 33 to 55 of the defined-terms change and runs 19 to 30 of the semantic detectors change had two or more readers quote each passage above as confusing, in text those changes had not touched; acceptance/ROUTED.md lists them with the runs.

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)

Clause 4.2's obligation is reworded to say what it already required of every blocking rule a toolchain routes, and clause 4.3's heading to match its body; tools/changes.py is clean against next because each reworded obligation keeps its keyword and most of its words. No obligation is added or removed: the observed case is readers unable to tell which of two readings an existing obligation carried, and the change settles it on the reading the surrounding clauses already assumed.

Where it goes

Section 1, section 2, the section 3 table, clauses 4.1, 4.2, 4.3, 8.1, 9.1 and 9.2, and section 9.

Acceptance

Under the process of pull request 22, merged into this branch: runs 57, 58, 62, 65, 67, 68, 72, 76, 81, 82, 83, 84 and 85 failed, each on the wording of this change's own text, which was revised after each; run 86 passed. Each run's record is under acceptance/runs/, and its answer sheets are posted as comments below. Version lines are untouched: the entry is under Unreleased.

🤖 Generated with Claude Code

[LTSCommerce]

Run 068: 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/toolchain-contradictions`). The readers read commit 0080b8e. 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 f3ec69e, named here before the readers started), acceptance/runs/README.md, acceptance/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/067-toolchain-contradictions-run-5.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 068. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 67 in clause 4.2 (rewritten in three paragraphs), section 2's table (a Remediation docs row) and section 1's "How to read this document". Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 6 (runs 57, 58, 62, 65 and 67 came before). Record file to write: <worktree>/acceptance/runs/068-toolchain-contradictions-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 dbce8540d4259779cdced1129c5fa71306bbe31597700618177c4a5f48662919, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at 0080b8e, 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 0080b8e -- TOOLING-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 f3ec69e, 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 068: 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":46422,"stop_reason":"end_turn","session_id":"ff88f421-4239-4f73-9fea-8cf8b4f446c1","total_cost_usd":0.00859153,"usage":{"input_tokens":2,"cache_creation_input_tokens":14944,"cache_read_input_tokens":2153,"output_tokens":11162,"output_tokens_details":{"thinking_tokens":8974},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14944,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11162,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14944,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14944},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11162,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14944,"webSearchRequests":0,"costUSD":0.00859153,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":8974,"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's toolchain must make the method's mechanisms available without the project building them, whether the parts come from third parties, first parties or the project itself.\n- Every defence routed through a detector must go through a detector that conforms to the detector specification. Wrapping can fill a gap, but cannot excuse one.\n- Every blocking rule the toolchain runs must resolve its identifier to documentation on disk, offline, and that documentation must say how to construct the correct code.\n- Suppression routes that bypass the project record (inline ignores, silent baselines) must be disabled or made to fail a blocking defence. Irreducible cases go to the project record.\n- The entry point must run detectors before runners, stop on a detector failure, and print detector identifiers unaltered and locally.\n- The toolchain must list active defences without running them, derive that list from the loaded configuration, and include the project's own defences. The project record must have a location the toolchain reads, reject generic justifications, and be listed the same way as defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks through. From section 1: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" Section 1 adds: \"[Conformance] is a property of the assembled whole.\"\n\n**2b.** One project-level grade. The individual parts are evidence for that grade, not grades in their own right. From section 9: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Section 1 also says the parts \"may be third-party, first-party or project-level, in any combination.\" Under clause 4.1, a detector plus its wrapping is judged as one pair.\n\n**2c.** Two grades, if the company's project actually ships the package. One is the project grade for its own repository, and the other is the artefact grade for what it ships. Neither implies the other. From clause 9.1: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" It also says: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic has two enabled bundled rules with no documentation. Nothing in the project or zig-qa resolves them, and the detector-spec gap is not wrapped. The clause's own table says \"Two [Bundled rules] have no documentation / Nothing for those two / Fails.\" I could not check detector-spec sections 4 to 7 directly, but this one named gap is enough to fail the clause. |\n| 4.2 | No | The same two undocumented blocking rules print identifiers that resolve to nothing. The fixture does not say whether they block, but they are listed as active defences, and by the document's definition a defence is blocking. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 4.3 | Yes | `ignore_comments = false` disables the only described bypass route. Exceptions go to `quality-exceptions.toml`. The fixture does not mention a baseline route, so this is a Yes on the facts given. |\n| 4.4 | Yes | `zig-qa run` runs locally, takes `<path>` for a subset, prints Lintomatic's output unchanged, and needs no service. Identifiers pass through unaltered. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs these scripts. |\n| 5.1 | Partial | `zig-qa list` lists active rules without running them, with identifier, summary and path. But for the two undocumented rules the path is `(none)`, and the clause requires \"the route to each one's full documentation.\" This is the same root gap as 4.2. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, which is the configuration the toolchain loads, so a newly added rule should appear. The fixture does not say where the one-line summary comes from. |\n| 5.3 | Yes | The four `proj.*` rules are included in `zig-qa list`, and each has a page in `docs/defences/`. |\n| 6.1 | Yes | `zig-qa run` loads `quality-exceptions.toml`, which is a defined location the toolchain reads. The fixture does not say where calibrations or conventions live, so this grade covers exceptions only. |\n| 6.2 | No | The only check is that `reason` is non-empty, and clause 6.2 says \"A field that is merely present and non-empty does not satisfy this clause.\" There is no check that rejects generic text such as \"needed for now\", \"legacy\" or \"TODO\", and no documented check of that kind. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries \"in the same format as the rule listing,\" through the same kind of command. |\n\n**Project grade under section 9.** No. Clauses 4.1, 4.2 and 6.2 fail, and 5.1 is partial. Partial conformance cannot be described as conformance.\n\n**Conformance with agent support.** No. The project grade fails, so agent support cannot apply. Separately, Zigpipe publishes no defence summary (7.1) and has no `AGENTS.md` or delivery mechanism (7.2).\n\n**Section 8.** It does not apply to Zigpipe. Section 8 \"bears on the artefact grade of clause 9.1 and not on this project grade,\" and Zigpipe ships no tooling. zig-qa is the company's shipped package, and its artefact grade would be judged separately, not as part of Zigpipe's verdict.\n\n**Effect of the absence of a declaration.** None. Clause 9.2 says \"The declaration is optional,\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The verdict above rests on the clauses, not on a declaration.\n\n## 4. Confusion\n\n- Clause 4.2: \"The [Toolchain] resolves an [Identifier] by a mechanism of its own, a command, an index file or a URL scheme, keyed on the [Identifier] exactly as printed.\" The clause heading requires resolution \"from the installed copy, without network access,\" and the same clause says the docs \"MUST ship with the project or with the [Toolchain].\" A URL scheme does not fit either requirement, and I could not tell which reading the clause intends.","ttft_ms":38573,"type":"result","duration_ms":46829,"uuid":"b0d929c2-2ef4-4928-b9b6-cad97edb6f8a","ttft_stream_ms":1008,"time_to_request_ms":408,"first_content_frame_ms":1009,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":62343,"stop_reason":"end_turn","session_id":"1a6552ce-9643-4cce-b4df-9414279c1aef","total_cost_usd":0.01047003,"usage":{"input_tokens":2,"cache_creation_input_tokens":14944,"cache_read_input_tokens":2153,"output_tokens":14919,"output_tokens_details":{"thinking_tokens":12638},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14944,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14919,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14944,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14944},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14919,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14944,"webSearchRequests":0,"costUSD":0.01047003,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12638,"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's toolchain is judged as the whole it assembles to run its checks: detectors, runners, and the parts that route, list, record and resolve, from any source.\n- Defences may only be routed through detectors that conform to the detector specification. Wrapping can fill a gap but cannot excuse one.\n- Every identifier a blocking rule can print must resolve, offline, to documentation on disk, including the project's own rules.\n- Suppression routes that bypass the project record must be disabled or made to fail a blocking defence. Irreducible cases go to the project record with a justification.\n- The entry point runs detectors before runners, stops on a detector failure, and prints results and identifiers unaltered.\n- The toolchain must list active defences and the project record without running anything, derived from configuration, and must read the project record from a defined location. It must reject generic exception justifications. An agent summary is recommended but not required.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the level of the project's assembled toolchain, whatever its parts and their sources.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve. Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2b.** One grade. The parts are evidence for that grade, not grades of their own.\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n> \"A project's [Toolchain] [Conforms] if every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from\"\n\n**2c.** Two grades: a project grade for the company's repository, and an artefact grade for the package it ships. One does not imply the other.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n> \"where the project also ships a [Detector] or a [Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this project grade.\"\n\n## 3. Application to Zigpipe\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic's two undocumented bundled rules fail its offline-resolution requirement, and zig-qa's documentation covers only `zq.*` and `proj.*`, so wrapping does not reach them. This matches the table's \"Nothing for those two: Fails\" row. One failing MUST is enough. I did not have the detector specification, so I could not check its other MUSTs; that does not change the No. |\n| 4.2 | No | Two bundled identifiers resolve to nothing: `lintomatic explain` has no page for them and `zig-qa list` prints `(none)`. The fixture does not say whether they are Blocking, but they are enabled and a Lintomatic failure stops the run, so I treat them as blocking. \"One Identifier that does not resolve fails this clause, however many others do.\" |\n| 4.3 | Yes | `ignore_comments = false` disables the inline ignore, the only suppression route the fixture describes, and exceptions go into `quality-exceptions.toml`. The fixture is silent on other Lintomatic routes such as a baseline; if one exists, this verdict is unverified. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts `<path>` down to a single file, and prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs these scripts. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints each active rule's identifier, summary and documentation path without running anything. The two undocumented rules are not Defences, since a Defence has documentation; their missing route is a 4.2 failure. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, and no hand-maintained list is described. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, with paths to their pages in `docs/defences/`. |\n| 6.1 | Yes | `quality-exceptions.toml` is a defined location and `zig-qa run` loads it. The fixture does not say where calibrations or conventions, which the glossary also counts as part of the record, are kept. Clause 6.1 is met for the record that exists. |\n| 6.2 | No | `zig-qa run` only refuses an empty `reason`. The document says \"A field that is merely present and non-empty does not satisfy this clause,\" and nothing described rejects generic text such as \"TODO\". |\n| 6.3 | Yes | `zig-qa list --exceptions` prints exceptions in the same format as the rule listing. |\n\n**Section 9 conformance: No.** Clauses 4.1, 4.2 and 6.2 each fail, and any one is enough. Under section 9, partial conformance must not be described as conformance.\n\n**Conformance with agent support: No.** Agent support is only available \"in addition\" to conformance, so it cannot be reached. Zigpipe also publishes no agent summary (7.1) and has no delivery into `AGENTS.md` (7.2). Both are SHOULDs and do not change the verdict.\n\n**Section 8: does not apply.** Zigpipe ships no tooling, so clause 9.1's artefact grade does not exist for it, and section 8.2 says a project that assembles without shipping \"has no release and no Consuming project.\" zig-qa is shipped by the company, so its artefact grade would fall under section 8 if assessed, but that is a separate grade and not Zigpipe's.\n\n**Declaration: no effect on the verdict.** Under 9.2 the declaration is optional, and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The gaps still need recording under method clause 3.2, whether or not the project declares anything.\n\n## 4. Confusion\n\n- **4.1**: The clause takes its MUSTs from sections 4 to 7 of the detector specification, which was not among the documents I was given. I graded 4.1 from the summary and the wrapping table, which is enough for a No but leaves the remaining detector MUSTs unchecked.\n- **4.2**: The clause says the documentation \"MUST ship with the project or with the [Toolchain]\", and later that a third-party native catalogue \"is not re-shipped here.\" Reading those together required a judgement about which sentence governs for Lintomatic.\n- **6.2**: The list \"'needed for now', 'legacy', 'TODO' and their like\" ends with an open phrase, and I could not tell where \"and their like\" stops, so I cannot say for certain whether a given justification counts as generic.","ttft_ms":55400,"type":"result","duration_ms":62826,"uuid":"13ab023f-67cb-4ed6-93a9-409ca4042b76","ttft_stream_ms":1265,"time_to_request_ms":480,"first_content_frame_ms":1265,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":58373,"stop_reason":"end_turn","session_id":"272b4af8-012a-4e55-89a5-aeb88fc6a417","total_cost_usd":0.00985383,"usage":{"input_tokens":2,"cache_creation_input_tokens":14943,"cache_read_input_tokens":2153,"output_tokens":13687,"output_tokens_details":{"thinking_tokens":11613},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14943,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13687,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14943,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14943},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13687,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14943,"webSearchRequests":0,"costUSD":0.00985383,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11613,"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's toolchain must route each defence only through a detector that conforms to the detector specification, and must wrap any detector gap it fills.\n- Every blocking rule's identifier must resolve offline to documentation on disk, and that documentation must say how to construct the correct code.\n- Suppression routes that bypass the project record must be disabled or guarded by a blocking defence. Irreducible cases go to the project record.\n- The entry point must run detectors before runners, stop on a detector failure, and report results locally, down to one file, with identifiers printed unaltered.\n- The toolchain must list active defences without running them, derive that list from the loaded configuration, and include the project's own defences.\n- The toolchain must define and load a project record. Every exception needs a written justification naming the hazard and scope, and generic ones must be rejected. The record must be enumerable the same way as the defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The parts are evidence for that grade and do not earn grades of their own.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n> \"...a project that ships nothing has only the one.\"\n\n**2c.** The project has two grades, one for the project and one for the shipped artefact. Neither implies the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nThe detector specification was not supplied, so 4.1 is judged from the clause's own summary and the fixture.\n\n| Clause | Verdict | Reasoning |\n| --- | --- | --- |\n| 4.1 | No | Two of Lintomatic's bundled rules have no documentation, and neither zig-qa nor the project supplies any, so the wrapped pair fails the table's \"Two Bundled rules have no documentation\" row. |\n| 4.2 | No | The two undocumented bundled rules are enabled, and their identifiers resolve to `(none)`, which the clause says fails it. |\n| 4.3 | Yes | `ignore_comments = false` disables Lintomatic's inline comment, and the fixture describes no other bypass route. |\n| 4.4 | Yes | `zig-qa run` runs locally, accepts `<path>` for a subset, and prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the tests, and stops when Lintomatic fails. CI runs it. |\n| 5.1 | Yes | `zig-qa list` reads the config and prints identifier, summary and documentation path without running any rule. (See the note below.) |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, the same file the run uses. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules alongside the bundled ones. |\n| 6.1 | Partial | The exceptions file is defined and loaded by `zig-qa run`, but the fixture gives no defined, loaded location for calibrations or conventions, which section 2 also places in the project record. |\n| 6.2 | No | The `reason` field only has to be non-empty, and the clause says a non-empty field does not satisfy it. No generic-justification check is described. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries in the same format as the rule listing. |\n\n**Note on 5.1:** I read \"Defence\" as the document defines it, a rule with its documentation, in force and blocking. The two undocumented rules are therefore not Defences, and clause 4.2 is where they are caught. If you read 5.1 as covering every active rule, the two `(none)` entries would make it Partial.\n\n**Conformance (section 9):** The toolchain does **not** conform. Clauses 4.1, 4.2 and 6.2 are No, and 6.1 is Partial. Section 9 requires every MUST in sections 4 to 6 to hold.\n\n**Conformance with agent support:** No. The toolchain does not conform, and it has no agent summary (7.1) and no delivery into `AGENTS.md` or equivalent (7.2), as the fixture states.\n\n**Section 8:** Does not apply. Section 8 bears only on an artefact grade, and the fixture says \"It does not ship any tooling to other projects.\" The `zig-qa` package belongs to the company, so its artefact grade is the company's, not Zigpipe's.\n\n**Declaration:** The absence of a declaration does not affect the verdict. Clause 9.2 says the declaration is optional, and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\"\n\n## 4. Confusion\n\n- Clause 4.1: \"That document's MUSTs are those of its sections 4 to 7, and this clause holds the [Detector] to every one of them. The sentences that follow summarise the ones most often failed, so that a reader with this document alone can see what the clause mostly turns on; they are a summary, not the test.\" I could only test the summary, since the detector specification was not supplied.\n- Section 2 defines \"[Defence]\" as \"A [Rule] with its documentation, in force and [Blocking]\", but clause 4.2 covers \"every [Blocking] [Rule]\" and says it names blocking rules \"rather than [Defences] because the failure it catches is a [Rule] that blocks without the documentation that would make it a [Defence]\". Clause 5.1 says \"every [Defence] active\", so it is unclear whether an undocumented blocking rule falls under it.\n- Clause 6.1 says \"The [Toolchain] MUST define where the [Project record] lives and MUST load it\", while section 2 defines the project record as covering \"[Calibrations], [Exceptions] and conventions\". The clause gives no location for the last two.","ttft_ms":51529,"type":"result","duration_ms":58733,"uuid":"16843f05-f468-445c-8fff-c11400b57c72","ttft_stream_ms":1130,"time_to_request_ms":359,"first_content_frame_ms":1131,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":45113,"stop_reason":"end_turn","session_id":"7f2850b1-986c-4645-83b8-e4d92404362b","total_cost_usd":0.008328529999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":14944,"cache_read_input_tokens":2153,"output_tokens":10636,"output_tokens_details":{"thinking_tokens":8496},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14944,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":10636,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14944,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14944},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":10636,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14944,"webSearchRequests":0,"costUSD":0.008328529999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":8496,"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's toolchain, meaning whatever it assembles to run its checks, must be able to route each defence through a conforming detector and forbid bypasses of the project record.\n- It must resolve every identifier that a blocking rule can print, from files on disk, without network access.\n- Its entry point must run detectors before runners and stop on a detector failure.\n- It must list active defences and the project record from the active configuration, without running anything, including the project's own defences.\n- It must define a location for the project record, read it itself, and require a specific written justification on every exception.\n- A project may also declare conformance, and conformance is graded at the project level and, for a project that ships an artefact, separately at the artefact level.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks through, including the detectors, runners, and the parts that route, list, record and resolve. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" It adds: \"[Conformance] is a property of the assembled whole.\"\n\n**2b.** One grade. The parts (third-party, first-party, project-level) are evidence for that grade, not grades of their own. The document says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Clause 9 also says conformance holds \"across the assembled parts, wherever each part came from.\" A second grade appears only if the project ships an artefact (clause 9.1), which this assembly does not do.\n\n**2c.** Two grades: a project grade for how the company's own repository runs its assembled toolchain, and an artefact grade for the published package. Neither implies the other. Clause 9.1 says: \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nGrading the toolchain as the fixture describes it: Lintomatic 4.2 (detector), zig-qa (first-party package with `run` and `list`), and the project's `proj.*` rules and `quality-exceptions.toml`. The DETECTOR-SPEC was not provided, so the 4.1 and 4.4 verdicts rest on the summary MUSTs in TOOLING-SPEC and the fixture's own description of Lintomatic.\n\n| Clause | Verdict | Reasoning |\n| --- | --- | --- |\n| 4.1 | No | Two bundled Lintomatic rules print identifiers with no documentation anywhere, and nothing in the project or zig-qa supplies it, so the wrapped pair does not resolve every identifier offline. This fails whether or not those rules are blocking. |\n| 4.2 | No | The two enabled undocumented rules print identifiers that `zig-qa list` shows as `(none)`. The fixture does not say whether they are Blocking. I have assumed they are, since they are enabled and `zig-qa run` stops when Lintomatic fails. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline ignore route project-wide, and exceptions go through `quality-exceptions.toml`. The fixture mentions no baseline or other route. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts `<path>` down to a single file, prints Lintomatic output unchanged, and the result appears in the command's output. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first, stops when it fails, and is what CI runs. |\n| 5.1 | Yes | `zig-qa list` reads the configuration and prints identifiers, summaries and doc paths without running any rule. The two undocumented rules are not Defences under section 2's definition, so this clause does not reach them. Their shortfall falls under 4.2. |\n| 5.2 | Yes | The listing is generated by reading `lintomatic.toml`, not hand-maintained. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, and each has a documentation page in `docs/defences/`. |\n| 6.1 | Yes | `quality-exceptions.toml` is a defined location, loaded by `zig-qa run` and read by `zig-qa list --exceptions`. The fixture does not say where calibrations or conventions are recorded, so this verdict covers exceptions only. |\n| 6.2 | No | The only check is that `reason` is non-empty, which the clause says is not enough. The fixture describes no check that the justification names the hazard and scope, and no rejection of generic text such as \"legacy\" or \"TODO\". |\n| 6.3 | Yes | `zig-qa list --exceptions` uses the same format as the rule listing. |\n\n**Conformance under section 9:** No. Clauses 4.1, 4.2 and 6.2 fail, so the toolchain is not conforming, and partial conformance may not be called conformance.\n\n**Conformance with agent support:** No. It does not conform at all, and the fixture says it has no agent summary (7.1) and no delivery into `AGENTS.md` or equivalent (7.2).\n\n**Does section 8 apply:** No. Section 8 bears on the artefact grade. Zigpipe \"does not ship any tooling to other projects,\" so it has no artefact grade. Section 8's closing paragraph says a project that assembles its toolchain without shipping it has \"no release and no [Consuming project]\", so section 8 does not bear on its conformance.\n\n**Does the absence of a declaration affect the verdict:** No. Clause 9.2 says a declaration is optional, and \"a verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The missing declaration does not change the grade. It does mean no gap record is kept in a declaration, though gaps must still be recorded under method clause 3.2.\n\n## 4. Confusion\n\nClause 5.1 says the listing must include \"every [Defence] active in the project,\" and section 2 defines a Defence as \"A [Rule] with its documentation, in force and [Blocking].\" Under that definition the two undocumented rules are not Defences, yet the fixture shows them in the active listing with `(none)` as their path. I could not tell from the text whether 5.1 is meant to cover them.","ttft_ms":37440,"type":"result","duration_ms":45477,"uuid":"00c86f0d-6da0-444c-a629-a402f105e026","ttft_stream_ms":1070,"time_to_request_ms":362,"first_content_frame_ms":1070,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":80254,"stop_reason":"end_turn","session_id":"dac8bc29-4764-4d32-b57a-e1fcc32c6bac","total_cost_usd":0.01266503,"usage":{"input_tokens":2,"cache_creation_input_tokens":14944,"cache_read_input_tokens":2153,"output_tokens":19309,"output_tokens_details":{"thinking_tokens":16923},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14944,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":19309,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14944,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14944},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":19309,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14944,"webSearchRequests":0,"costUSD":0.01266503,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":16923,"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's toolchain is graded as one assembled whole, whatever its parts came from.\n- Every detector a defence is routed through must conform to the detector specification, and every blocking rule's identifier must resolve to documentation on disk, offline.\n- Suppression routes that bypass the project record (inline ignores, silently generated baselines) must be disabled or made to fail via a blocking defence. Irreducible cases go in the project record with a justification.\n- The entry point runs detectors before runners, stops on a detector failure, prints identifiers unaltered, and can run locally on a single file.\n- Active defences can be listed without being run, derived from the active configuration and including the project's own. The project record has a location the toolchain reads, is listed the same way, and every exception needs a specific justification.\n- Conformance is one project grade. A shipped artefact gets a separate grade. Agent summaries and a declaration are SHOULD or MAY, not conditions.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks. \"A Toolchain is measured at the project level. It is whatever the project assembles to run its checks through: the Detectors and Runners, and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade and do not get grades of their own. \"Conforms if every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from.\" And: \"The project-level verdict is a single grade; which part of the Toolchain satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** The company's project has two grades: a project grade under section 9, and an artefact grade under 9.1 for the package it ships. Neither implies the other. \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic is routed through and has two bundled rules with no documentation. The 4.1 table says \"Two Bundled rules have no documentation → Nothing for those two → Fails\", and nothing in zig-qa or the project supplies docs for them. |\n| 4.2 | No | The two enabled undocumented bundled rules print identifiers that resolve to `(none)`, and \"One Identifier that does not resolve fails this clause.\" The fixture says they are enabled but not whether they block. I have assumed they do. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline ignore route, and exceptions live in `quality-exceptions.toml`, which is the project record. The fixture does not mention baselines, so I graded only the routes it describes. |\n| 4.4 | Yes | `zig-qa run` runs locally, accepts `<path>` to limit the run, prints Lintomatic's output unchanged, and is what CI runs. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints each rule's identifier, summary and doc path without running anything. The two `(none)` rows are not Defences under the glossary, and their gap belongs to 4.2. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, the configuration Lintomatic loads, so a newly added rule appears without anyone editing the listing. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, and their documentation is in `docs/defences/`. |\n| 6.1 | Yes | `zig-qa run` loads `quality-exceptions.toml`, which is defined as the location. The fixture names a location only for exceptions and says nothing about calibrations or conventions. |\n| 6.2 | No | The only check is that `reason` is non-empty. The clause says \"A field that is merely present and non-empty does not satisfy this clause\", and there is no hazard or scope requirement and no rejection of generic text. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries in the same format as the rule listing. |\n\nFor 4.1 and 4.2 I had only the summary in 4.1 and not sections 4 to 7 of the detector specification. The verdicts rest on the bundled-rule resolution gap, which the summary states directly, so they do not depend on that missing text.\n\n- **Section 9:** The toolchain does **not** conform. It is Partial, because 4.1, 4.2 and 6.2 fail. Under section 9, \"Partial conformance MUST NOT be described as Conformance.\"\n- **Conformance with agent support:** No. Conformance with agent support requires conformance first, and the project also lacks the section 7 summary and delivery. Those are SHOULDs, but they are absent.\n- **Section 8:** It does not apply to this project's grade. Zigpipe ships nothing to other projects, so section 8 bears only on an artefact grade. \"A project that assembles its Toolchain without shipping it has no release and no Consuming project, so this section does not bear on its Conformance.\"\n- **Declaration:** The absence has no effect on the verdict. \"The declaration is optional,\" and \"A verdict on any Toolchain, declared or not, rests on that exercise and not on the claim.\"\n\n## 4. Confusion\n\n1. **Clause 4.2 and the glossary's \"Defence\".** The glossary says \"A Rule with its documentation, in force and Blocking.\" Clause 4.2 says it \"names Blocking Rules rather than Defences because the failure it catches is a Rule that blocks without the documentation that would make it a Defence.\" Clause 5.1 then lists \"every Defence active\", and the zig-qa listing includes the two undocumented rules as active rules. I could not tell whether those two are Defences.\n\n2. **Clause 4.2, mechanism and title.** The clause says the toolchain resolves an identifier \"by a mechanism of its own, a command, an index file or a URL scheme\", and its title requires resolution \"from the installed copy, without network access.\" I could not see how a URL scheme meets both.\n\n3. **Clause 6.2, heading and check.** The heading requires a justification that \"names the hazard and the scope\". The body says the toolchain must reject text that \"could be pasted onto any Exception unchanged, by a check it documents: 'needed for now', 'legacy', 'TODO' and their like.\" I could not tell how a phrase check is meant to establish that a hazard and a scope are named.\n\n4. **Clause 4.3, whose decision.** It says: \"This clause is where the project's decision is made and enforced, and the decision is no.\" The method is described as making suppression \"an Owner decision\", and I could not tell whether the toolchain decides on the owner's behalf.\n\n5. **Clause 4.1, point 2.** It refers to the detector specification's \"clause 8.1\" for how the wrapped pair is exercised. That document was not provided, so I could not check that part of the test.","ttft_ms":72461,"type":"result","duration_ms":80740,"uuid":"f18940f8-b835-4d4b-9ba2-8035f7caf723","ttft_stream_ms":1060,"time_to_request_ms":483,"first_content_frame_ms":1060,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 068: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone. Where a
clause rests on the [detector specification](DETECTOR-SPEC.md), as clauses 4.1, 4.2 and 4.4 do,
the clause says in its own words what that document requires of the [Detector]. The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them. The sentences
that follow summarise the ones most often failed, so that a reader with this document alone can
see what the clause mostly turns on; they are a summary, not the test. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. A [Detector] that fails any
one of that document's MUSTs, summarised here or not, fails this clause after wrapping. Three
points govern how that is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. The [Rules] in scope are every [Blocking] [Rule] the [Toolchain]
runs, bundled or the project's own; a [Rule] that only warns is outside this clause. The clause
names [Blocking] [Rules] rather than [Defences] because the failure it catches is a [Rule] that
blocks without the documentation that would make it a [Defence]. One [Identifier] that does not
resolve fails this clause, however many others do.

The [Toolchain] resolves an [Identifier] by a mechanism of its own, a command, an index file or
a URL scheme, keyed on the [Identifier] exactly as printed. Those [Remediation docs] MUST ship
with the project or with the [Toolchain], at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open. That document holds a
[Detector] to on-disk resolution of its own [Bundled rules] and
no further, because it cannot know a project's documentation; this clause reaches the project's
own [Rules] as well. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is not
re-shipped here: an [Identifier] the [Detector] resolves under that document's clause 6 meets
this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.

[LTSCommerce]

Run 072: 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/toolchain-contradictions`). The readers read commit cb9b4e5. 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/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/068-toolchain-contradictions-run-6.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 072. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 68 in clause 4.2 (which now states only what it requires, with no sentence on defences and no list of mechanisms), clause 4.1's first paragraph and section 1's "How to read this document". Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 7 (runs 57, 58, 62, 65, 67 and 68 came before). Record file to write: <worktree>/acceptance/runs/072-toolchain-contradictions-run-7.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 6c9683df16a39ddd12169c438fe1f9c8a32050bd5346a81de4edb1c0d6990472, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at cb9b4e5, 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 cb9b4e5 -- TOOLING-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 072: 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":55255,"stop_reason":"end_turn","session_id":"d495366a-59c8-4525-9699-e98f3790aa84","total_cost_usd":0.00959003,"usage":{"input_tokens":2,"cache_creation_input_tokens":14814,"cache_read_input_tokens":2153,"output_tokens":13211,"output_tokens_details":{"thinking_tokens":10710},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14814,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13211,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14814,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14814},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13211,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14814,"webSearchRequests":0,"costUSD":0.00959003,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10710,"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- Route each check through detectors that conform to the detector specification, and wrap a detector only where the wrapping closes its gaps.\n- Make every blocking rule's identifier resolve offline from the installed copy, with a place for its documentation and text that states the correct construction.\n- Forbid suppression routes that bypass the project record, either by disabling them or by a blocking defence that fails on their use.\n- Run detectors before runners in the entry point, stop on a detector failure, and let every defence be run locally on a subset down to one file.\n- List every active defence without running it, derived from the loaded configuration, including the project's own. Define a project record the toolchain reads itself, reject generic exception justifications, and list the record the same way as the defences.\n- Grade the project level and any shipped artefact separately. Shipped toolchains also self-audit their documentation and run their own rules on their own source.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through, meaning its detectors and runners and the parts that route, list, record and resolve.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. Individual parts are evidence for that grade and are not graded separately.\n\n> \"A project's [Toolchain] [Conforms] if every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from\"\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** The project has two grades: a project grade, which every project has, and an artefact grade for the package it ships. Neither implies the other.\n\n> \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application to Zigpipe\n\nZigpipe's toolchain is Lintomatic plus zig-qa plus its own `proj.*` rules. Zigpipe ships nothing, so it has only a project grade.\n\n**4.1 — No.** Lintomatic's two undocumented bundled rules have no docs in Lintomatic, zig-qa or the project, so the wrapped pair fails the detector's on-disk resolution requirement.\n> \"Two [Bundled rules] have no documentation | Nothing for those two | Fails\"\n\n**4.2 — No.** Two enabled Lintomatic rules print identifiers that nothing resolves. The fixture doesn't say whether those rules are blocking, so this verdict assumes they are, as enabled rules are; if they were warnings only, the clause would not reach them.\n> \"One [Identifier] that does not resolve fails this clause, however many others do.\"\n\n**4.3 — Yes.** Inline ignores are disabled with `ignore_comments = false`, and exceptions go through `quality-exceptions.toml`. The fixture does not say whether Lintomatic offers any other suppression route, such as a baseline, so this verdict assumes it does not.\n> \"The routes are the ones each [Detector] offers: where a [Detector]'s only route is an ignore comment, this clause is met for that [Detector] once the comment is disabled\"\n\n**4.4 — Yes.** `zig-qa run` works locally, accepts `<path>`, and prints Lintomatic's identifiers unchanged, so every defence it routes meets the reporting clauses.\n> \"The entry point MUST also print every [Identifier] its [Detectors] print, unaltered\"\n\n**4.5 — Yes.** `zig-qa run` runs Lintomatic before the tests and stops when Lintomatic fails, and CI runs the same command.\n> \"The invocation the project uses to accept changes MUST evaluate its [Detectors] before its [Runners].\"\n\n**5.1 — Partial.** `zig-qa list` lists every active rule without running it, with identifier, summary and documentation path. For the two undocumented rules it prints `(none)`, so there is no route to their documentation.\n> \"It MUST provide the route to each one's full documentation.\"\n\n**5.2 — Yes.** The listing reads `lintomatic.toml`, the same configuration the run uses.\n> \"The listing MUST be generated from the configuration the [Toolchain] actually loads.\"\n\n**5.3 — Yes.** The `proj.*` rules and the `zq.*` rules appear in `zig-qa list` alongside the bundled rules.\n> \"A project's own defences MUST appear in the listing alongside bundled ones.\"\n\n**6.1 — Partial.** The toolchain defines and loads `quality-exceptions.toml`, but the fixture does not say where calibrations or conventions, which section 2 includes in the project record, are written or loaded.\n> \"The [Toolchain] MUST define where the [Project record] lives and MUST load it.\"\n\n**6.2 — No.** The toolchain checks only that `reason` is non-empty, and the spec says a present, non-empty field does not satisfy this clause. The fixture describes no rejection of generic text such as \"TODO\" or \"legacy\".\n> \"A field that is merely present and non-empty does not satisfy this clause.\"\n\n**6.3 — Yes.** `zig-qa list --exceptions` uses the same tool and format as the rule listing.\n> \"Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.\"\n\n**Conformance under section 9 — No.** Clauses 4.1, 4.2 and 6.2 fail, and 5.1 and 6.1 are partial. Partial conformance is not conformance.\n> \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support — No.** The project does not conform, and it also has neither the summary (7.1) nor the delivery (7.2) that section 7 recommends. Agent support is defined as \"in addition\" to conformance, so it cannot hold without it.\n\n**Section 8 — Does not apply.** Section 8 bears on shipped toolchains, and Zigpipe ships nothing. zig-qa is a company package that Zigpipe consumes, so its own grade and section 8 belong to that package, which the fixture does not grade.\n> \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\"\n\n**Declaration — No effect on the verdict.** The declaration is optional, and the verdict rests on the clauses, not on a claim.\n> \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\"\n\n## 4. Confusion\n\n- Section 2, the entry for [Defence] — \"A [Rule] with its documentation, in force and [Blocking]\" — read beside clause 4.2 (\"every [Identifier] its [Blocking] [Rules] print\") and clause 5.1 (\"every [Defence] active in the project\"). On the definition, a rule without documentation is not a defence, yet 4.2 covers it and 5.1 may or may not. I could not tell which clause governs the two undocumented rules.\n- Clause 9.2: \"A project or a shipped artefact MAY declare\" is followed by \"A project that ships an artefact carries both levels of clause 9.1 in that declaration.\" I read the second sentence as applying only to a project that declares, but it is written as an unconditional statement.","ttft_ms":47032,"type":"result","duration_ms":55595,"uuid":"74b379d3-ed44-4973-85d2-af2fdab3b50b","ttft_stream_ms":954,"time_to_request_ms":341,"first_content_frame_ms":954,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":53543,"stop_reason":"end_turn","session_id":"187823e9-907f-4c92-95f1-4813ba08ba75","total_cost_usd":0.00940353,"usage":{"input_tokens":2,"cache_creation_input_tokens":14814,"cache_read_input_tokens":2153,"output_tokens":12838,"output_tokens_details":{"thinking_tokens":10676},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14814,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12838,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14814,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14814},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12838,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14814,"webSearchRequests":0,"costUSD":0.00940353,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10676,"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's toolchain, meaning all its detectors, runners, and the parts that route, list, record and resolve, is judged as one assembled whole, wherever each part came from.\n- Every detector that routes a defence must meet the detector specification. Wrapping can supply a missing mechanism but cannot excuse a gap.\n- Every blocking rule's identifier must resolve offline to documentation on disk, including the project's own rules.\n- Suppression routes that bypass the project record must be disabled or caught by a blocking defence. The entry point runs detectors before runners and stops on a detector failure.\n- Active defences must be listable without running them, derived from the live configuration, and the project's own defences must appear alongside bundled ones.\n- The project record must have a location the toolchain reads itself. Every exception needs a specific written justification, and the record must be listable the same way as the defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** One grade. The assembly is graded as a whole, and each part is only evidence for that grade. The document says: \"**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from\" and \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Zigpipe ships nothing, so it has only this one grade (9.1: \"a project that ships nothing has only the one\").\n\n**2c.** Two grades: a project grade and an artefact grade. Neither implies the other. The document says: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\" It also says: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application\n\nGrading is from the fixture. The detector specification was not provided, so for 4.1 I graded only the points clause 4.1 restates.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic meets the restated points except offline resolution. Two bundled rules have no documentation, and nothing in the project or zig-qa supplies it, so wrapping does not close the gap. |\n| 4.2 | No | The two enabled bundled rules print identifiers whose documentation path is `(none)`, and one non-resolving identifier fails the clause. The fixture does not state their severity, but `zig-qa run` stops when Lintomatic fails, so I read them as blocking. |\n| 4.3 | Yes | The only described suppression route, `// lintomatic-ignore`, is disabled by `ignore_comments = false`, and exceptions go through the record. The fixture is silent on baselines and on whether a rule can be switched off in `lintomatic.toml` without a record entry. |\n| 4.4 | Yes | `zig-qa run` runs locally, takes a path to limit the run, and prints Lintomatic's output unchanged, so identifiers arrive unaltered. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic before the test suite and stops when Lintomatic fails, and CI runs it. |\n| 5.1 | Partial | `zig-qa list` lists every active rule without running it, but the two undocumented rules have no route to documentation. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, the configuration Lintomatic loads. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list` with a summary and a documentation path, and each has its own page in `docs/defences/`. |\n| 6.1 | Yes | `zig-qa run` loads `quality-exceptions.toml` itself. The fixture describes only exceptions, not calibrations or conventions. |\n| 6.2 | No | The only check is that `reason` is non-empty, which the clause says does not satisfy it. Nothing rejects generic justifications. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing. |\n\n**Conforms under section 9?** No. Clauses 4.1, 4.2 and 6.2 fail, and 5.1 is partial. Partial conformance cannot be described as conformance.\n\n**Conforms with agent support?** No. It does not conform at all, and it does none of what section 7 recommends: there is no agent summary and no `AGENTS.md`.\n\n**Does section 8 apply?** No. Zigpipe ships no tooling to other projects, so section 8 bears only on an artefact grade it does not have. The document says a project that \"assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" The company's `zig-qa` package is a separate artefact and is not graded here.\n\n**Does the absence of a declaration affect the verdict?** No. Clause 9.2 says the declaration is \"optional\" and \"not a condition of conformance\", and that \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" Gaps still have to be recorded under method clause 3.2 whether or not a declaration exists.\n\nI did not grade 6.4 or section 7, since 6.4 is a SHOULD and was not in the requested list.\n\n## 4. Confusion\n\n- **§1, \"How to read this document\", against clause 4.1.** Section 1 says: \"A [Toolchain] can be graded from this document alone.\" Clause 4.1 says a detector \"that fails any one of that document's MUSTs, restated here or not, fails this clause\", and that the detector specification's \"MUSTs are those of its sections 4 to 7\". I could not tell how to grade 4.1 from this document alone, so I graded only its restated points.\n- **§2 definition of [Defence], against clause 5.1.** The table defines a Defence as \"A [Rule] with its documentation, in force and [Blocking]\". Clause 5.1 says the listing \"MUST provide the route to each one's full documentation.\" I could not tell whether the two undocumented bundled rules are Defences at all. If they are not, 5.1 has nothing to fail on for them. If they are, 5.1 fails.","ttft_ms":46896,"type":"result","duration_ms":53911,"uuid":"4fd7aec8-4fd6-417c-9092-db6e13c6cf7b","ttft_stream_ms":1130,"time_to_request_ms":368,"first_content_frame_ms":1130,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":61741,"stop_reason":"end_turn","session_id":"e8d29901-fdc2-4c1b-9ebd-466ffa2ad42f","total_cost_usd":0.01055793,"usage":{"input_tokens":2,"cache_creation_input_tokens":14816,"cache_read_input_tokens":2153,"output_tokens":15146,"output_tokens_details":{"thinking_tokens":12901},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14816,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":15146,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14816,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14816},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":15146,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14816,"webSearchRequests":0,"costUSD":0.01055793,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12901,"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- Conformance is judged on the whole toolchain a project assembles, whether its parts are third-party, first-party or project-level.\n- Defences may be routed only through detectors that conform to the detector specification. Wrapping can close a gap, but an unclosed gap fails the clause.\n- Every identifier a blocking rule can print must resolve offline to on-disk documentation that states the correct construction, and the toolchain must provide a place for that documentation.\n- Suppression routes that bypass the project record must be disabled or made to fail the run, and the entry point must run detectors before runners and stop on a detector failure.\n- Active defences, including the project's own, must be listable without running them, from the active configuration, with identifier, summary and documentation route.\n- Exceptions must sit in a location the toolchain reads, each with a specific justification the toolchain checks, and the project record must be listable the same way as defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" It also says: \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n**2b.** The assembly receives one grade. The parts are evidence for that grade, not grades of their own. The document says: \"Those parts may be third-party, first-party or project-level, in any combination.\" And: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** That project has two grades, and one does not imply the other. Its project grade is the assembled toolchain's grade under section 9. Its artefact grade is what it ships, graded for consumers. The document says: \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application to Zigpipe\n\nThe detector specification is not in the packet. For 4.1 I graded only the restated points and the fixture's description of Lintomatic.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic is the only detector routed through. Two of its forty bundled rules have no documentation, and neither the project nor zig-qa supplies any. The wrapping table says \"Two [Bundled rules] have no documentation \\| Nothing for those two \\| Fails.\" |\n| 4.2 | No | The two undocumented bundled rules are enabled, `zig-qa list` prints their path as `(none)`, and nothing resolves their identifiers. The fixture does not say they are Blocking. I treated them as Blocking because `zig-qa run` stops when Lintomatic fails. |\n| 4.3 | Yes | The only route the fixture names is the inline `// lintomatic-ignore` comment, and `ignore_comments = false` disables it. Exceptions go to `quality-exceptions.toml`, which is the project record. The fixture mentions no baseline or other route, so I assessed none. |\n| 4.4 | Yes | `zig-qa run` is local with no service, `zig-qa run <path>` limits the run to a directory or file, and its output is \"Lintomatic's output unchanged, one line per finding\", so identifiers print unaltered. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and \"stops when Lintomatic fails\". CI runs these scripts. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` without running anything and prints identifier, summary and documentation path. The two `(none)` entries are not Defences under the section 2 definition, which requires documentation, so no route is owed for them. Their failure is the 4.2 failure. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, the configuration Lintomatic runs with. Nothing is hand-maintained. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules, documented under `docs/defences/`, alongside the bundled and `zq.*` rules. |\n| 6.1 | Yes | `zig-qa run` loads `quality-exceptions.toml` from a fixed path before it runs Lintomatic. |\n| 6.2 | No | Only an empty `reason` is rejected. The fixture describes no check for generic text such as \"TODO\" or \"legacy\", and nothing requires a named hazard or scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the entries \"in the same format as the rule listing.\" |\n\n**Conformance under section 9.** Zigpipe does not conform. Clauses 4.1, 4.2 and 6.2 fail, and section 9 requires every MUST in sections 4 to 6 to hold. Partial conformance cannot be described as conformance.\n\n**Conformance with agent support.** No. Agent support requires conformance first, and the fixture also shows that 7.1 and 7.2 are not done: there is no agent summary, no `AGENTS.md`, and no delivery mechanism.\n\n**Section 8.** It does not apply. Section 8 bears on the artefact grade, and Zigpipe ships no tooling to other projects. `zig-qa` is published by the company, and the fixture does not say Zigpipe ships it, so it is not part of Zigpipe's artefact grade.\n\n**Effect of the missing declaration.** None. Section 9.2 says \"The declaration is optional\" and that \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The verdict above rests on the exercise of the clauses.\n\n## 4. Confusion\n\n- Section 2 defines a Defence as \"A [Rule] with its documentation, in force and [Blocking]\". Clause 5.1 then says the listing must \"list every [Defence] active in the project\". Whether a documentation-less rule is part of that listing was not clear to me on my one reading.\n- Clause 6.2 says the toolchain \"MUST NOT supply a default\" for an exception justification. Clause 6.4 says the toolchain \"SHOULD state its own defaults for anything the method leaves to the project\". I could not tell from the text whether exception justifications fall under 6.4.\n- Section 1 says: \"A [Toolchain] can be graded from this document alone.\" Clause 4.1 says a detector \"that fails any one of that document's MUSTs, restated here or not, fails this clause\". I could not tell how far grading from this document alone was meant to reach under 4.1.","ttft_ms":54519,"type":"result","duration_ms":62300,"uuid":"ee750ba5-47cd-4183-9cdb-97f96bc0c357","ttft_stream_ms":1113,"time_to_request_ms":558,"first_content_frame_ms":1113,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":69378,"stop_reason":"end_turn","session_id":"57e8b4ff-6a22-4e79-a156-d02c89f746f8","total_cost_usd":0.01116773,"usage":{"input_tokens":2,"cache_creation_input_tokens":14815,"cache_read_input_tokens":2153,"output_tokens":16366,"output_tokens_details":{"thinking_tokens":14004},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14815,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":16366,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14815,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14815},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":16366,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14815,"webSearchRequests":0,"costUSD":0.01116773,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":14004,"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's toolchain, measured as a whole, must let a practitioner run every check, see every active defence, and find every recorded decision without building the mechanisms itself.\n- Every detector routed a defence must conform to the detector specification. Wrapping can add a missing mechanism but cannot excuse a gap.\n- Every blocking rule's identifier must resolve to on-disk documentation offline, and that documentation must state the correct construction.\n- Suppression routes that bypass the project record must be disabled or made to fail the run. The entry point must run detectors before runners and stop on a detector failure, and must print identifiers unaltered.\n- The active defences must be listable without running them, derived from the loaded configuration, and must include the project's own defences.\n- Exceptions live in a project record the toolchain reads, each with a justification naming the hazard and scope, and generic justifications are rejected. The record is listed the same way as the defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks: the detectors and runners, plus the parts that route, list, record and resolve.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n> \"[Conformance] is a property of the assembled whole, because that is where it counts\"\n\n**2b.** Zigpipe's assembly gets one grade, because it ships no tooling. The individual parts are evidence toward that grade, not separate grades, and their origin does not matter.\n\n> \"every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from\"\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n> \"a project that ships nothing has only the one.\"\n\n**2c.** That project has two grades, one for the project and one for the artefact it ships. One does not imply the other.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n**4.1: No.** Lintomatic is the only detector routed through, and two of its bundled rules have no documentation that anything in the project or zig-qa supplies. The clause's own table reads \"Two [Bundled rules] have no documentation | Nothing for those two | Fails.\" One could argue the two undocumented rules are not defences, since a defence needs documentation, but the clause judges the detector the defences are routed through.\n\n**4.2: No.** The two undocumented identifiers print as `(none)` in `zig-qa list`. The fixture does not say the two rules are Blocking, so this assumes they are: they are enabled, and `zig-qa run` stops when Lintomatic fails. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\"\n\n**4.3: Yes, on the written evidence.** The only route the fixture describes is the inline `// lintomatic-ignore` comment, and `ignore_comments = false` disables it. The fixture does not say whether Lintomatic has other routes, such as a baseline, so this verdict holds only for what is written.\n\n**4.4: Yes.** `zig-qa run` prints Lintomatic's output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a file or directory. Both scripts run locally with no service.\n\n**4.5: Yes.** `zig-qa run` runs Lintomatic first, then the test suite, and \"stops when Lintomatic fails.\"\n\n**5.1: Yes.** `zig-qa list` reads `lintomatic.toml` and prints each active rule's identifier, summary and documentation path without running anything. The two `(none)` entries are rules without documentation, so they are not defences under section 2, and their gap is recorded under 4.2.\n\n**5.2: Yes.** The listing is generated from `lintomatic.toml`, the configuration that the run uses, and is not a hand-maintained document.\n\n**5.3: Yes.** The four `proj.*` rules appear in `zig-qa list` alongside the `zq.*` bundled rules, and each has a page in `docs/defences/`.\n\n**6.1: Yes.** `quality-exceptions.toml` is a defined path, and `zig-qa run` loads it before running Lintomatic. The fixture names only the exceptions file, though section 2 defines the project record as also covering calibrations and conventions, and the fixture says nothing about those.\n\n**6.2: No.** The only check is that `reason` is non-empty, which the clause states \"does not satisfy this clause.\" No documented check rejects generic justifications such as \"needed for now\", \"legacy\" or \"TODO\".\n\n**6.3: Yes.** `zig-qa list --exceptions` prints the exceptions in the same format as the rule listing.\n\n**Section 9, conformance: No.** Clauses 4.1, 4.2 and 6.2 fail, and \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support: No.** The toolchain does not conform at all, and it also does none of what section 7 recommends: there is no defence summary (7.1) and nothing is delivered into an agent file (7.2), with no `AGENTS.md` present.\n\n**Section 8: Does not apply.** Section 8 bears only on an artefact grade, and Zigpipe ships no tooling. Section 8's final paragraph says a project that assembles its toolchain without shipping it \"has no release and no [Consuming project], so this section does not bear on its [Conformance].\" The company's zig-qa package, if graded as an artefact, would bring section 8 into play for that package, but the fixture does not assess it.\n\n**Does the absence of a declaration affect the verdict? No.** Clause 9.2 makes the declaration optional and says a toolchain \"MAY be graded [Conforming] on evidence by anyone who exercises the clauses above.\" The verdict rests on the exercise, not on a claim. The absence does mean there is no declared version or gap record, but the duty to record a gap falls only on a project that declares, and gaps are still recorded under method clause 3.2.\n\n## 4. Confusion\n\n- **Clause 6.2.** I could not tell whether the toolchain must check that a justification names the hazard and the scope, or only reject generic text. The passage reads: \"The justification MUST name the [Hazard] being accepted and the scope of the [Exception]. The [Toolchain] MUST reject a justification that could be pasted onto any [Exception] unchanged, by a check it documents.\" The check described covers only generic phrases.\n- **Clause 5.1, with the section 2 definition of [Defence].** It was unclear whether an active rule with no documentation counts as a defence. Section 2 defines a [Defence] as \"A [Rule] with its documentation, in force and [Blocking]\", but clause 5.1 requires the listing to cover \"every [Defence] active in the project\", and the fixture's two undocumented rules are active.","ttft_ms":61027,"type":"result","duration_ms":69710,"uuid":"621265bb-745a-4a76-8b55-6757fb65f74c","ttft_stream_ms":1056,"time_to_request_ms":328,"first_content_frame_ms":1056,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":58035,"stop_reason":"end_turn","session_id":"bd2bfecb-e4dc-4768-a960-431f17bf4fbb","total_cost_usd":0.01006703,"usage":{"input_tokens":2,"cache_creation_input_tokens":14814,"cache_read_input_tokens":2153,"output_tokens":14165,"output_tokens_details":{"thinking_tokens":12041},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14814,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14165,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14814,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14814},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14165,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14814,"webSearchRequests":0,"costUSD":0.01006703,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12041,"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- The toolchain is whatever the project assembles to run its checks, whether the parts are third-party, first-party or project-level, and conformance is judged on the assembled whole.\n- Every defence must be routed through a detector that conforms to the detector specification. Wrapping can fill a gap, but a gap the wrapping does not fill fails the clause.\n- Every identifier a blocking rule can print must resolve to on-disk documentation, offline, with the correct construction stated.\n- Suppression routes that bypass the project record must be disabled or guarded by a blocking defence. The entry point must run detectors before runners and stop on a detector failure.\n- The active defences must be listable without running them, from the live configuration, including the project's own defences.\n- The project record must have a defined location that the toolchain reads, every exception must carry a specific justification, and the record must be listable the same way as the defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is everything the project assembles to run its checks, including the detectors, runners and the routing, listing, recording and resolving parts around them. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one conformance grade. The parts are evidence for that grade and do not receive grades of their own. The document says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" It also says: \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** The project has two grades: the project grade, which every project has, and the artefact grade, which a project that ships something also has. Neither implies the other. The document says: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\" It also says: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application to Zigpipe\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic meets the listed features, but its two undocumented bundled rules are a gap nothing in the project or zig-qa fills. The clause's table says \"Two [Bundled rules] have no documentation\" with \"Nothing for those two\" is \"Fails\". I graded on the restated points, since the full detector specification was not provided. |\n| 4.2 | No | The two bundled rules are enabled and print identifiers that `zig-qa list` shows as `(none)`. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" The other 38 resolve offline, and the `zq.*` and `proj.*` docs have defined places, but the fixture does not describe an identifier-keyed resolver for those two sets. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline route, and exceptions go to `quality-exceptions.toml`. The fixture names no other Lintomatic route, so this verdict holds only on what is written. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, prints Lintomatic's output unchanged, takes a path to limit the run, and is what CI runs. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first, then the test suite, and stops when Lintomatic fails. |\n| 5.1 | Yes | `zig-qa list` reads the config without running anything and prints identifier, one-line summary and path. The two `(none)` entries are rules without documentation, which the Defence definition excludes from \"Defence\". That gap is charged to 4.2. A reader who counts them as defences would grade this No. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, which is the configuration Lintomatic loads. Nothing is described as hand-maintained. |\n| 5.3 | Yes | The `proj.*` rules appear in `zig-qa list` with their documentation paths. Zigpipe ships nothing, so the shipped-toolchain paragraph does not apply. |\n| 6.1 | Partial | `quality-exceptions.toml` has a defined location that `zig-qa run` loads. The project record also covers calibrations and conventions, and the fixture describes no location the toolchain reads for either. |\n| 6.2 | No | The `reason` field is free text checked only for emptiness, and the clause says \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing requires the hazard and scope to be named, and no generic-phrase check is described. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries in the same format as the rule listing, from the same tool. |\n\n**Section 9 conformance: No.** Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is only partial. The document says \"Partial [Conformance] MUST NOT be described as [Conformance]\", so the project's toolchain does not conform.\n\n**Conformance with agent support: No.** That grade requires conformance first, and the fixture also says Zigpipe has no agent summary and no `AGENTS.md`, so the section 7 recommendations are not met either.\n\n**Section 8 applies: No.** Section 8 bears only on the artefact grade, and the fixture says Zigpipe \"does not ship any tooling to other projects.\" If the company ships zig-qa, that package's artefact grade is a separate question that the fixture does not put to Zigpipe's verdict.\n\n**Absence of a declaration: No effect on the verdict.** Clause 9.2 says the declaration \"is optional,\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" Zigpipe's known gaps are still to be recorded under method clause 3.2, whether or not it declares anything.\n\n## 4. Confusion\n\nClause 5.3: \"Where such a [Defence] is not expressible in the [Toolchain]'s own [Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived under clause 5.2 rather than hand-maintained.\" On my reading, \"wherever it is enabled\" could mean a configuration file, a script, or anywhere else, and I could not tell which of these the clause accepts.","ttft_ms":51142,"type":"result","duration_ms":58372,"uuid":"845ae0c9-6274-4448-81ca-1fe41ec5b8d8","ttft_stream_ms":1015,"time_to_request_ms":334,"first_content_frame_ms":1015,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 072: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone. Where a
clause rests on the [detector specification](DETECTOR-SPEC.md), as clauses 4.1, 4.2 and 4.4 do,
it restates what that document requires of the [Detector], far enough to grade what a
[Toolchain]'s evidence shows. The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them. The sentences
that follow restate the ones most often failed, far enough for a reader with this document
alone to grade what a [Toolchain]'s evidence shows. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. A [Detector] that fails any
one of that document's MUSTs, restated here or not, fails this clause after wrapping. Three
points govern how that is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. That is every [Blocking] [Rule] the [Toolchain] runs, the project's
own and the bundled alike. One [Identifier] that does not resolve fails this clause, however
many others do.

The resolving mechanism is keyed on the [Identifier] exactly as printed. Those
[Remediation docs] MUST ship with the project, with the [Toolchain] or with the [Detector]
whose [Rule] they document, at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open: that
document holds a [Detector] to on-disk resolution of its own [Bundled rules] and no further,
because it cannot know a project's documentation, and this clause reaches the project's own
[Rules] as well. An [Identifier] a third-party [Detector] resolves under that document's clause
6 meets this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.

[LTSCommerce]

Run 076: 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/toolchain-contradictions`). The readers read commit fa79f8a. 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/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/072-toolchain-contradictions-run-7.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 076. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 72: section 2 gains a paragraph under its table saying a blocking rule whose documentation is missing is not yet a defence and is what clauses 4.2, 5.1 and 8.1 exist to catch; clause 5.1 says the listing covers every blocking rule, documented or not, with a missing route showing; section 1's "How to read this document" and clause 4.1's first paragraph both say a verdict from this document alone rests on what is restated and a grader with the detector specification holds the detector to all of it. The key's 4.3 row now says which case the fixture presents, settling run 72's open point. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 8 (runs 57, 58, 62, 65, 67, 68 and 72 came before). Record file to write: <worktree>/acceptance/runs/076-toolchain-contradictions-run-8.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 18f9a24ca270450e83434b252e766ca54bcc6fa744f855bcc76bc0c59613fe3a, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at fa79f8a, 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 fa79f8a -- TOOLING-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 076: 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":64685,"stop_reason":"end_turn","session_id":"aae03b82-3240-4a5a-a76a-b2b0fcb17789","total_cost_usd":0.007837839999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":340,"cache_read_input_tokens":16814,"output_tokens":15203,"output_tokens_details":{"thinking_tokens":12934},"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":15203,"cache_read_input_tokens":16814,"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":15203,"cacheReadInputTokens":16814,"cacheCreationInputTokens":340,"webSearchRequests":0,"costUSD":0.007837839999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12934,"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's toolchain is judged as one assembled whole, whatever mix of third-party, first-party and project-level parts it uses.\n- The toolchain must make the method's requirements achievable without the project building the mechanisms itself.\n- It may route a defence only through a detector that conforms to the detector specification, and every identifier its blocking rules print must resolve to documentation on disk, offline.\n- It must disable or forbid suppression routes that bypass the project record, and its entry point must report every finding and run detectors before runners, stopping on a detector failure.\n- It must list active defences, including the project's own, from the live configuration without running them. Its project record must live at a location it reads itself, with every exception carrying a real justification, and the record must be listable the same way as the defences.\n- Shipped toolchains and artefacts have extra self-audit duties, and conformance is graded at two levels for a project that ships. Agent-context summaries are recommended but not required.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is everything the project assembles to run its checks. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" It adds: \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n**2b.** One grade. The parts are evidence for it, not grades of their own. The document says: \"Those parts may be third-party, first-party or project-level, in any combination.\" And: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** Two grades, and neither implies the other. The project grade applies to every project. The artefact grade applies because the company ships the package. The document says: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" It also says: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application to Zigpipe\n\nTwo limits first. I was not given the detector specification, so clause 4.1 is graded only on the gaps the fixture describes. Those gaps are enough for a No on their own. I also read \"Blocking\" into the two undocumented bundled rules and the `zq.*` and `proj.*` rules, because the fixture describes them as defences that stop the run but never says so directly.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic is the detector all defences route through, and it has two bundled rules with no documentation. Wrapping does not help: zig-qa documents only `zq.*`, and the fixture says \"nothing in the project or in zig-qa provides documentation for them.\" The table in 4.1 gives \"Two [Bundled rules] have no documentation \\| Nothing for those two \\| Fails.\" |\n| 4.2 | No | The two undocumented identifiers do not resolve, and \"One [Identifier] that does not resolve fails this clause, however many others do.\" The `zq.*` docs (in `docs/rules/`) and `proj.*` docs (in `docs/defences/`) are on disk. |\n| 4.3 | Yes | `ignore_comments = false` disables the only suppression route the fixture describes, and exceptions go through the project record. The fixture says nothing about other routes such as baselines, so I graded only what is described. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, `zig-qa run <path>` limits it to a file or directory, and Lintomatic's output is printed unchanged, one line per finding. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first and stops when it fails, and CI runs that same command. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and does not run anything. The two undocumented rules are still listed, with `(none)` as the path, and the clause allows that: \"a [Rule] whose route to documentation is missing is listed with that gap showing.\" |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, the configuration the toolchain loads. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules alongside the bundled and `zq.*` rules, with identifier, summary and documentation path. |\n| 6.1 | Yes | `zig-qa run` loads `quality-exceptions.toml` itself before it runs Lintomatic. The fixture mentions only exceptions in the record, not calibrations or conventions. |\n| 6.2 | No | The only check is that `reason` is non-empty. The clause says \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing rejects generic text such as \"needed for now\", and nothing checks for a named hazard and scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing, so the record is listed by the same tool. |\n\n**Conformance under section 9: No.** Section 9 requires that \"every MUST in sections 4 to 6 holds.\" Clauses 4.1, 4.2 and 6.2 fail.\n\n**Conformance with agent support: No.** That grade requires conformance plus the section 7 recommendations. Zigpipe does neither 7.1 (no summary) nor 7.2 (no delivery into `AGENTS.md`, which it does not have). The verdict would be No even if the other failures were absent.\n\n**Section 8 does not apply.** It \"bears on the artefact grade\" only. The fixture says Zigpipe \"does not ship any tooling to other projects\", so it has no artefact grade. The company's `zig-qa` package is graded on its own, as that company's artefact, not as Zigpipe's.\n\n**The absence of a declaration does not affect the verdict.** Section 9.2 says \"The declaration is optional\", and that a toolchain's verdict \"rests on that exercise and not on the claim.\" Zigpipe's verdict is No on the evidence alone. Its absence means only that the duty to record known gaps in a declaration does not arise, and that no artefact-level declaration is owed.\n\n## 4. Confusion\n\n- **\"The table in section 2 glosses every term it borrows.\"** (How to read this document, section 1.) On my reading the table does not gloss terms such as Suppression, Baseline, Agent, Conform, Warning or Fixture, and those terms appear in clauses I had to grade.\n- **\"a grader with that document to hand holds the [Detector] to every one of its MUSTs, restated here or not.\"** (Clause 4.1.) I did not have that document, and the clause also says a verdict from this document alone rests on the restated sentences, so I was unsure how far the standard reached.","ttft_ms":57730,"type":"result","duration_ms":66284,"uuid":"ddeba4d9-0143-4b9d-887e-e10dcef50da1","ttft_stream_ms":2398,"time_to_request_ms":1599,"first_content_frame_ms":2399,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":51774,"stop_reason":"end_turn","session_id":"bb4f8cb6-a96c-4249-9da3-c74565976c99","total_cost_usd":0.00923393,"usage":{"input_tokens":2,"cache_creation_input_tokens":15001,"cache_read_input_tokens":2153,"output_tokens":12424,"output_tokens_details":{"thinking_tokens":10269},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15001,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12424,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15001,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15001},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12424,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15001,"webSearchRequests":0,"costUSD":0.00923393,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10269,"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- Conformance is judged on the whole assembled toolchain at project level, whatever mix of third-party, first-party and project parts it uses.\n- Defences may only be routed through detectors that conform to the detector specification. Wrapping can fill a gap but cannot excuse one.\n- Every identifier a blocking rule can print must resolve to documentation on disk, offline, with the correct construction stated. The toolchain must provide a place for that documentation.\n- Suppression routes that bypass the project record must be disabled or made to fail a blocking defence. Irreducible cases go to the project record with a justification.\n- The entry point runs detectors before runners, stops on a detector failure, reports locally with per-file subsets, and prints identifiers unaltered.\n- The listing of active defences is derived from configuration, lists the project's own defences, and is produced without running them. The project record is read by the toolchain, rejects generic exception justifications, and is listed the same way. Agent summaries and defaults are SHOULDs.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the level of the project's assembled toolchain, which is \"whatever the project assembles to run its checks through\". That includes detectors, runners, and the parts that route, list, record and resolve.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve. Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2b.** There is one grade for the assembled whole. The third-party detector, the first-party package and the project rules are evidence toward that grade, not separate grades. A second, artefact grade exists only if the project ships something.\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** The project has two grades: a project grade for its own assembled toolchain, and an artefact grade for the package it publishes. Neither implies the other.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application to Zigpipe\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | **No** | Lintomatic is routed through and has two bundled rules with no documentation. The spec's table says that gap \"Fails\", and nothing in the project or zig-qa supplies that documentation. |\n| 4.2 | **No** | Two enabled bundled identifiers have no documentation on disk, and `zig-qa list` prints `(none)` for them. One unresolved identifier fails the clause. |\n| 4.3 | **Yes** | The only suppression route described is the inline comment, disabled by `ignore_comments = false`. Irreducible cases go to `quality-exceptions.toml`. The fixture is silent on other routes, so this holds only on the evidence given. |\n| 4.4 | **Yes** | `zig-qa run` is local with no service, `zig-qa run <path>` runs down to a single file, and Lintomatic's output is printed unchanged. |\n| 4.5 | **Yes** | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. |\n| 5.1 | **Yes** | `zig-qa list` reads `lintomatic.toml` and prints each rule's identifier, summary and documentation path without running the rules. Undocumented rules are shown with `(none)`. |\n| 5.2 | **Yes** | The listing is produced from `lintomatic.toml` at runtime, not from a hand-maintained file. |\n| 5.3 | **Yes** | The `proj.*` rules are included in `zig-qa list`, and their documentation is in `docs/defences/`. |\n| 6.1 | **Yes** | The record is `quality-exceptions.toml`, and `zig-qa run` loads it. The fixture does not say whether calibrations or conventions are recorded, but 6.1 does not require that. |\n| 6.2 | **No** | The only check is that `reason` is non-empty, which the clause expressly says does not satisfy it. Nothing rejects generic text such as \"legacy\" or \"TODO\", and the hazard and scope are not checked. |\n| 6.3 | **Yes** | `zig-qa list --exceptions` prints entries in the same format as the rule listing. |\n\n**Conformance under section 9:** No. Clauses 4.1, 4.2 and 6.2 fail, and \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support:** No. The fixture says Zigpipe publishes no agent summary and has no `AGENTS.md`, so neither 7.1 nor 7.2 holds. The verdict is moot in any case, since the project does not conform under section 9.\n\n**Whether section 8 applies:** No. Section 8 bears only on a shipped artefact. The fixture says Zigpipe \"does not ship any tooling to other projects\", and the spec says \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" The fixture is a little ambiguous, though. It describes zig-qa as a package the company publishes \"for all its Zig projects\", so zig-qa's own artefact grade would fall under section 8 if the company ships it. That grade is separate from Zigpipe's project grade.\n\n**Effect of the missing declaration:** None on the verdict. Declarations are optional under 9.2, and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The No stands on the clauses above. The only duty to record a known gap in a declaration applies to projects that have one, but a gap a practitioner finds is recorded under method clause 3.2 regardless.\n\n## 4. Confusion\n\n- **Section 4.1**: \"The sentences that follow restate the ones most often failed, and a verdict from this document alone rests on them; a grader with that document to hand holds the [Detector] to every one of its MUSTs, restated here or not.\" I could not tell whether the restated sentences are the complete basis for a grade from this document alone, or whether the detector specification's other MUSTs are also needed. I could only check Lintomatic against what the fixture states, and the detector specification was not provided.\n- **Section 2, unnumbered**: \"These are additional.\" It follows the terminology table, and I could not tell what it is additional to.","ttft_ms":44438,"type":"result","duration_ms":52114,"uuid":"d48be422-918a-4b27-aab9-993c15e322ed","ttft_stream_ms":1245,"time_to_request_ms":335,"first_content_frame_ms":1245,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":82236,"stop_reason":"end_turn","session_id":"e30007c7-3ce0-4b8d-b105-0c249cd21979","total_cost_usd":0.012973930000000002,"usage":{"input_tokens":2,"cache_creation_input_tokens":15001,"cache_read_input_tokens":2153,"output_tokens":19904,"output_tokens_details":{"thinking_tokens":17669},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15001,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":19904,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15001,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15001},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":19904,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15001,"webSearchRequests":0,"costUSD":0.012973930000000002,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":17669,"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- Conformance is judged on the whole toolchain at project level, whatever mix of third-party, first-party and project parts it is built from.\n- Defences may only run through detectors that conform to the detector specification. Wrapping can add a missing mechanism but cannot excuse a gap.\n- Every identifier a blocking rule prints must resolve offline to documentation on disk, with a place for that documentation and text that states the correct construction.\n- Suppression routes that bypass the project record must be disabled, or must fail a blocking defence when used. Irreducible cases go to the record.\n- The acceptance entry point runs detectors before runners, stops on a detector failure, prints identifiers unaltered, and can run on a single file.\n- Active defences and the project record must be listed without being run, derived from live configuration, with specific written justifications for every exception. Agent summaries and defaults are SHOULDs.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is everything the project assembles to run its checks. The document says: \"A [Toolchain] is measured at the project level. It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade, the project grade. The parts are evidence for it and do not get grades of their own. The document says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Section 1 gives the reason: \"a [Practitioner] arriving at the project cannot tell which package a mechanism came from, and does not need to.\" A second grade appears only if the project also ships an artefact (see 2c).\n\n**2c.** The project has two grades: the project grade, and an artefact grade for what it ships. Neither implies the other. The document says: \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application to Zigpipe\n\nI did not have `DETECTOR-SPEC.md`. For 4.1 and 4.4 I graded against the sentences restated in TOOLING-SPEC, which clause 4.1 says is enough for a verdict from this document alone. For 4.2 I assumed the two undocumented bundled rules are Blocking. The fixture does not say so, but they are enabled and run inside `zig-qa run`, which stops when Lintomatic fails. If they were not Blocking, 4.2 would hold, but 4.1 would still fail.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Two Lintomatic bundled rules have no documentation and nothing wraps them. The clause's own table marks that row \"Fails\", and zig-qa and the project rules run through Lintomatic. |\n| 4.2 | No | The two undocumented rules are enabled, `zig-qa list` shows their path as `(none)`, and one unresolved identifier fails the clause. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline route, exceptions go to `quality-exceptions.toml`, and the fixture describes no baseline route. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts a path for a single file, and prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic before the tests and stops when Lintomatic fails, and CI runs it. |\n| 5.1 | Yes | `zig-qa list` reads config without running anything, prints identifier, summary and documentation path, and shows the gap as `(none)`. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, the configuration the run uses. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules, whose pages say what is forbidden, why, and what to write instead. |\n| 6.1 | Yes | `quality-exceptions.toml` is a defined location that `zig-qa run` loads. See section 4 below on the wider record. |\n| 6.2 | No | Only an empty `reason` is rejected. Nothing described checks that a reason names the hazard and scope or rejects generic text. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing. |\n\n**Conformance under section 9:** No. The toolchain fails 4.1, 4.2 and 6.2, and section 9 requires every MUST in sections 4 to 6 to hold. Its partial conformance must not be described as conformance.\n\n**With agent support:** No. Agent support requires conformance first. Zigpipe also does none of the section 7 recommendations: it has no agent summary (7.1), no `AGENTS.md`, and no automatic delivery (7.2).\n\n**Section 8:** It does not apply to Zigpipe's grade. Section 8 bears only on an artefact grade, and the fixture says \"It does not ship any tooling to other projects.\" Clause 8.2 says: \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" One caveat: the company publishes zig-qa for all its Zig projects. If zig-qa is a shipped toolchain in its own right, it would get its own artefact grade and section 8 would apply to it. The fixture does not say where zig-qa is developed or graded.\n\n**Effect of the missing declaration:** None. Clause 9.2 says the declaration is optional, and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The gaps still have to be recorded under method clause 3.2 whether or not the project declares.\n\n## 4. Confusion\n\n- **4.3:** \"Irreducible cases MUST be directed to the [Project record], where clause 6.2 requires a justification.\" I could not tell what \"directed\" requires of a toolchain. I passed Zigpipe on the reading that its exceptions file is that direction, though the fixture never says the toolchain sends users there.\n- **6.1:** \"The [Toolchain] MUST define where the [Project record] lives and MUST load it.\" Section 2 defines the record as holding Calibrations, Exceptions and conventions. I could not tell whether 6.1 needs one location for the whole record or one for each kind. The fixture describes only exceptions.\n- **4.1:** \"a verdict from this document alone rests on them\" sits beside \"holds the [Detector] to every one of them.\" I could not tell which of the two is the test when the detector specification is not available.","ttft_ms":74864,"type":"result","duration_ms":82528,"uuid":"450310c9-629f-498f-b157-bb6b05756a2d","ttft_stream_ms":1240,"time_to_request_ms":289,"first_content_frame_ms":1240,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":53931,"stop_reason":"end_turn","session_id":"55a03ac2-d84e-4238-96ae-1668c4702546","total_cost_usd":0.009560929999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":15001,"cache_read_input_tokens":2153,"output_tokens":13078,"output_tokens_details":{"thinking_tokens":10922},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15001,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13078,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15001,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15001},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13078,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15001,"webSearchRequests":0,"costUSD":0.009560929999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10922,"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":"# Questions for a cold reader of TOOLING-SPEC.md\n\n## 1. Restatement\n\n- A project's toolchain is measured as one assembled whole, whatever mix of detectors, runners and routing, listing, recording and resolving parts it uses.\n- Every blocking rule the toolchain runs needs documentation that resolves from the installed copy, offline.\n- Every suppression route that bypasses the project record must be disabled, or must trigger a blocking defence.\n- The project's own invocation runs locally, can be scoped to one file, and prints findings and identifiers unaltered. It runs detectors before runners and stops on detector failure.\n- The list of active defences is derived from the active configuration, can be produced without running anything, and includes the project's own rules.\n- The project record has a defined location the toolchain loads. It can be listed the same way as the defences, and each exception needs a specific written justification that the toolchain checks for.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one conformance grade. The individual parts are evidence for that grade and are not graded separately.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\nThe grade covers the MUSTs \"across the assembled parts, wherever each part came from\" (section 9).\n\n**2c.** The company's project has two grades: a project grade, and an artefact grade for the package it publishes. One does not imply the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\nClause 9.1 also says the project grade \"every project has\", and the artefact grade \"only a project that ships has\".\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | The two undocumented bundled Lintomatic rules are not resolved by anything in the project or in zig-qa. The 4.1 table says \"Two [Bundled rules] have no documentation \\| Nothing for those two \\| Fails\". I do not have the detector specification, so this rests on the restatement, which the clause says a verdict from this document alone rests on. |\n| 4.2 | No | Two enabled bundled rules print identifiers that resolve to no documentation. The clause says \"One [Identifier] that does not resolve fails this clause.\" This assumes the two are Blocking. The fixture says they are \"enabled\" and that `zig-qa run` stops when Lintomatic fails, but it does not state their blocking status. |\n| 4.3 | Yes | `ignore_comments = false` disables the only suppression route the fixture describes. Exceptions go through `quality-exceptions.toml`, which is the project record. The fixture says nothing about a baseline mechanism, so I have not assessed one. |\n| 4.4 | Yes | `zig-qa run` runs locally, `zig-qa run <path>` scopes it to a file, and it prints Lintomatic's output unchanged, one line per finding, so identifiers print unaltered. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs it. |\n| 5.1 | Yes | `zig-qa list` prints every active rule with identifier, summary and documentation path, without running them. Undocumented rules show as `(none)`, so the gap is visible. |\n| 5.2 | Yes | The listing reads `lintomatic.toml`, the configuration Lintomatic loads. The fixture describes no hand-maintained list. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules alongside the `zq.*` and bundled ones. |\n| 6.1 | Yes | `quality-exceptions.toml` is a defined location, and `zig-qa run` loads it. Caveat: section 2 counts calibrations and conventions as part of the project record, and the fixture gives a location only for exceptions. |\n| 6.2 | No | Only an empty `reason` is rejected. The clause says \"A field that is merely present and non-empty does not satisfy this clause.\" The fixture describes no check against generic phrases such as \"needed for now\", and no requirement that the justification name the hazard and scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing, using the same script. |\n\n**Conformance under section 9: No.** Clauses 4.1, 4.2 and 6.2 fail, and section 9 requires that \"every MUST in sections 4 to 6 holds\". The fixture describes a substantial partial conformance, which the document says \"MUST NOT be described as [Conformance]\".\n\n**Conformance with agent support: No.** The project is not conforming, and it does none of section 7's recommendations: there is no summary for an agent (7.1), nothing delivers one into the project (7.2), and there is no `AGENTS.md`.\n\n**Section 8: does not apply.** Section 8 bears only on the artefact grade of a project that ships a detector or toolchain. The fixture says Zigpipe \"does not ship any tooling to other projects\". The self-audit clauses (8.1, 8.2) would apply to the company's zig-qa package, which is a separate project.\n\n**Declaration: no effect on the verdict.** Clause 9.2 says the declaration \"is optional\", and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The duty to record gaps in a declaration also falls only on a project that has one, and Zigpipe has none.\n\n## 4. Confusion\n\n- **Clause 4.1:** \"The sentences that follow restate the ones most often failed, and a verdict from this document alone rests on them; a grader with that document to hand holds the [Detector] to every one of its MUSTs, restated here or not.\" On my reading, I could not tell which governs when I do not have the detector specification: the restated sentences alone, or every MUST of that document.\n- **Clause 6.1:** \"The [Toolchain] MUST define where the [Project record] lives and MUST load it.\" Section 2 defines the project record as holding \"[Calibrations], [Exceptions] and conventions\", so I could not tell whether the one location must hold all three.","ttft_ms":46867,"type":"result","duration_ms":54307,"uuid":"5978988f-5945-4838-807f-2d4a7a64841f","ttft_stream_ms":1106,"time_to_request_ms":374,"first_content_frame_ms":1106,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":54662,"stop_reason":"end_turn","session_id":"5ede44a0-e830-4e8f-b630-dbf8f5f3b147","total_cost_usd":0.00962823,"usage":{"input_tokens":2,"cache_creation_input_tokens":15000,"cache_read_input_tokens":2153,"output_tokens":13213,"output_tokens_details":{"thinking_tokens":11078},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15000,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13213,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15000,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15000},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13213,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15000,"webSearchRequests":0,"costUSD":0.00962823,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11078,"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's toolchain is judged as the assembled whole it runs its checks through, whatever mix of third-party, first-party and project-written parts it contains.\n- Defences may be routed only through detectors that conform to the detector specification, and every blocking identifier must resolve offline from the installed copy, with a place for its documentation.\n- Suppression routes that bypass the project record must be disabled or caught by a blocking defence. Irreducible cases must go to the project record, where each exception needs a specific justification.\n- The entry point must print identifiers unaltered, run detectors before runners, and stop on a detector failure.\n- Active defences, including the project's own, must be listable without running them, from the active configuration. The project record must be loaded from a defined path and enumerable the same way.\n- Conformance is one project-level grade, reached only when every MUST in sections 4 to 6 holds. The agent summary (section 7) is SHOULD, and section 8 applies only to shipped artefacts.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is everything the project assembles to run its checks: its detectors and runners, plus the parts that route, list, record and resolve.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** One grade. The three sources are not graded separately. Each part is evidence toward the single assembled verdict, and a failure in any part that a clause touches fails that clause for the whole.\n> \"Those parts may be third-party, first-party or project-level, in any combination.\"\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** Two grades: the project grade, for the repository's own assembled toolchain, and the artefact grade, for the package it ships. Neither implies the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic is the routed detector. Two of its forty bundled rules have no documentation, and nothing in the project or zig-qa documents them, so wrapping adds nothing. The table in 4.1 says that case \"Fails.\" The other detector requirements are met. |\n| 4.2 | No | The two undocumented bundled rules are enabled, and `zig-qa list` prints their path as `(none)`. One unresolved identifier fails the clause. The fixture does not say whether these rules are Blocking. They run in the same stop-on-failure run, so I took them as Blocking. Even if they were not, 4.1 still fails. The project's `proj.*` and zig-qa's `zq.*` docs are on disk, so those resolve. |\n| 4.3 | Yes | The only described suppression route is `// lintomatic-ignore`, which is disabled by `ignore_comments = false`. Exceptions go to `quality-exceptions.toml`. The fixture does not describe any other Lintomatic route, so this is a yes on the evidence given, not a verified absence. |\n| 4.4 | Yes | `zig-qa run` and `zig-qa list` run locally with no service, `zig-qa run <path>` runs on a single file, and `zig-qa run` prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs these scripts. |\n| 5.1 | Yes | `zig-qa list` prints each active rule's identifier, one-line summary and doc path without running anything. It shows the gap for undocumented rules. |\n| 5.2 | Yes | The listing is generated by reading `lintomatic.toml`, the configuration the detector loads, so a newly added rule appears on the next run. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules alongside the bundled `zq.*` and Lintomatic rules. |\n| 6.1 | Yes | `quality-exceptions.toml` is a defined path, which `zig-qa run` loads before Lintomatic runs. |\n| 6.2 | No | The only check is that `reason` is non-empty, which the clause expressly says is not enough. There is no documented rejection of generic text like \"legacy\" or \"TODO\", and no requirement that the reason name the hazard and scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing. |\n\n**Conformance (section 9):** No. Clauses 4.1, 4.2 and 6.2 fail, so the project's toolchain does not conform. Partial conformance cannot be described as conformance.\n\n**Conformance with agent support:** No. It does not conform at all, and it has neither a defence summary (7.1) nor a delivery into `AGENTS.md` (7.2), since the fixture says it has no summary and no `AGENTS.md`.\n\n**Section 8 (self-audit):** It does not apply. Section 9 says section 8 bears on the artefact grade only, and clause 8.2 says a project that assembles its toolchain without shipping it has no release. The fixture says Zigpipe ships no tooling. The zig-qa package is the company's artefact, and section 8 applies to it under its own grade, not to Zigpipe.\n\n**Effect of no declaration:** None on the verdict. Section 9.2 makes the declaration optional and says a verdict \"rests on that exercise and not on the claim.\" The duty to record known gaps attaches only to a project that declares, but a gap a practitioner finds is still recorded under method clause 3.2. The verdict is non-conforming with or without a declaration.\n\n## 4. Confusion\n\n- **Clause 4.1:** \"The sentences that follow restate the ones most often failed, and a verdict from this document alone rests on them; a grader with that document to hand holds the [Detector] to every one of its MUSTs, restated here or not.\" On one reading, the verdict from this document alone rests on the restated sentences, but the grader must hold the detector to every MUST, which may go beyond them.\n- **Section 2:** \"These are additional.\" This line comes after the terminology table and before the new term definitions, and I could not tell what it was additional to.","ttft_ms":47687,"type":"result","duration_ms":55094,"uuid":"c334b229-4aa2-42a5-9f75-296563739d09","ttft_stream_ms":1244,"time_to_request_ms":431,"first_content_frame_ms":1245,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 076: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone, on the
evidence a project shows. Where a clause rests on the [detector specification](DETECTOR-SPEC.md),
as clauses 4.1, 4.2 and 4.4 do, it restates what that document requires of the [Detector], and a
grader with that document to hand holds the [Detector] to all of it. The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

A [Blocking] [Rule] whose documentation is missing is not yet a [Defence]. It is what clauses
4.2, 5.1 and 8.1 exist to catch, so where those clauses reach a [Toolchain]'s [Rules] they reach
every [Blocking] [Rule] it runs, documented or not.

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them. The sentences
that follow restate the ones most often failed, and a verdict from this document alone rests on
them; a grader with that document to hand holds the [Detector] to every one of its MUSTs,
restated here or not. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. A [Detector] that fails any
one of them, after wrapping, fails this clause. Three points govern how that is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. That is every [Blocking] [Rule] the [Toolchain] runs, the project's
own and the bundled alike. One [Identifier] that does not resolve fails this clause, however
many others do.

The resolving mechanism is keyed on the [Identifier] exactly as printed. Those
[Remediation docs] MUST ship with the project, with the [Toolchain] or with the [Detector]
whose [Rule] they document, at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open: that
document holds a [Detector] to on-disk resolution of its own [Bundled rules] and no further,
because it cannot know a project's documentation, and this clause reaches the project's own
[Rules] as well. An [Identifier] a third-party [Detector] resolves under that document's clause
6 meets this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.
The listing covers every [Blocking] [Rule] the [Toolchain] runs, documented or not, and a
[Rule] whose route to documentation is missing is listed with that gap showing.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.

[LTSCommerce]

Run 081: 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/toolchain-contradictions`). The readers read commit 0373a27. 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 389ef3f, named here before the readers started), acceptance/runs/README.md, acceptance/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/076-toolchain-contradictions-run-8.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 081. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 76: clause 4.1's first paragraph and section 1's "How to read this document" now give one test, a grader checks the restated sentences and takes a verdict already given on the detector under the detector specification as settled; and the paragraph on a blocking rule whose documentation is missing, which sat under section 2's table and parted "These are additional." from it, now ends section 2 after the Project record entry. ACCEPTANCE.md changed at 389ef3f after run 76 as well: a remark that another document was not supplied, or that a term is defined only there, is a note however much of the document it quotes; and a paragraph the pull request parts from what it refers to is the change's text. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 9 (runs 57, 58, 62, 65, 67, 68, 72 and 76 came before). Record file to write: <worktree>/acceptance/runs/081-toolchain-contradictions-run-9.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 09c3a3ba5bcd441d513797fcd973e2d0873473ca867aa774ff94643902147e6d, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at 0373a27, 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 0373a27 -- TOOLING-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, a paragraph the change parts from what it refers to, 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 389ef3f, 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 081: 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":59371,"stop_reason":"end_turn","session_id":"d65fbda9-d3ce-4051-98bb-5570e82f318f","total_cost_usd":0.010421529999999998,"usage":{"input_tokens":2,"cache_creation_input_tokens":15019,"cache_read_input_tokens":2153,"output_tokens":14792,"output_tokens_details":{"thinking_tokens":12743},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15019,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14792,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15019,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15019},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14792,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15019,"webSearchRequests":0,"costUSD":0.010421529999999998,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12743,"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's toolchain is judged as the whole it assembles, wherever each part came from.\n- Every detector a defence runs through must conform to the detector specification. Wrapping can add a missing mechanism but cannot excuse a gap.\n- Every identifier a blocking rule can print must resolve offline to documentation on disk, and the toolchain must provide a place for that documentation.\n- Suppression routes that bypass the project record must be disabled or made to fail a blocking defence. Irreducible cases go to the project record, with a justification.\n- The entry point runs detectors before runners, stops on a detector failure, and reports results in its own output, down to a single file.\n- The toolchain lists active defences without running them, derived from the active configuration and including the project's own. Its project record has a location it reads, every exception needs a specific justification, and the record is enumerable like the defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade, not grades of their own.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n> \"A project's [Toolchain] [Conforms] if every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from\"\n\nA second grade arises only if the project also ships an artefact (clause 9.1), and that grade is for the artefact, not the assembly.\n\n**2c.** Two grades: a project grade for the company's repository as a project, and an artefact grade for the published package. One does not imply the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic meets the restated list except offline resolution for its two undocumented bundled rules. Nothing in the project or zig-qa documents them, so the wrapped pair fails. |\n| 4.2 | No | The two bundled rules Lintomatic can print have no documentation anywhere, and \"One [Identifier] that does not resolve fails this clause.\" |\n| 4.3 | Yes | `ignore_comments = false` disables the inline ignore route. The fixture describes no other suppression route. |\n| 4.4 | Yes | `zig-qa run` works locally, accepts a path down to one file, and prints Lintomatic's output unchanged with its identifiers. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the tests, and stops when Lintomatic fails. CI runs these scripts. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` without running anything and prints identifier, summary and documentation path, showing `(none)` for the two undocumented rules. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml` on each run, not hand-maintained. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, with pages in `docs/defences/`. |\n| 6.1 | Partial | `quality-exceptions.toml` is defined and loaded by `zig-qa run`. The fixture names no location or loading for calibrations or conventions, which the section 2 definition of project record includes. |\n| 6.2 | No | The `reason` field is free text checked only for emptiness. Nothing rejects generic justifications, and nothing requires naming the hazard and scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries in the same format as the rule listing. |\n\nNotes on the grading:\n- I read the two undocumented Lintomatic rules as Blocking. They are enabled, and the fixture does not say they are non-blocking.\n- The detector specification was not provided, so 4.1 rests on the sentences the clause restates. I could not check the detector specification clauses it cites.\n\n**Section 9 (conformance):** No. Clauses 4.1, 4.2 and 6.2 fail and 6.1 is partial. Section 9 requires every MUST in sections 4 to 6 to hold, and partial conformance may not be called conformance.\n\n**Agent support:** No. Agent support is defined as conformance plus section 7. The fixture says there is no agent summary (7.1), no `AGENTS.md` and no automatic delivery (7.2).\n\n**Section 8:** It does not apply to Zigpipe's project grade. Section 8 bears on the artefact grade only (clauses 9 and 9.1), and the fixture says Zigpipe \"does not ship any tooling to other projects.\" There is a tension, though: `zig-qa` is published by the company \"for all its Zig projects.\" If that package is graded as an artefact, section 8 applies to it. The fixture does not describe that repository, so I give no verdict on it.\n\n**Declaration:** The absence of a declaration does not affect the verdict. Clause 9.2 makes the declaration optional, and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The verdict rests on the clauses above.\n\n## 4. Confusion\n\n- **Section 2, the \"Defence\" definition and clause 5.1.** The definition reads \"[Defence] | A [Rule] with its documentation, in force and [Blocking]\". Clause 5.1 says the listing of \"every [Defence] active in the project\" also \"covers every [Blocking] [Rule] the [Toolchain] runs, documented or not\".\n- **Section 2, the \"Project record\" definition and clause 6.1.** The definition says the record holds \"[Calibrations], [Exceptions] and conventions\". Clause 6.1 says \"The [Toolchain] MUST define where the [Project record] lives and MUST load it\", and clauses 6.1 to 6.3 mention only exceptions.","ttft_ms":53134,"type":"result","duration_ms":59945,"uuid":"9708713d-250b-435b-868a-b678b0d40bc6","ttft_stream_ms":1307,"time_to_request_ms":567,"first_content_frame_ms":1307,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":55390,"stop_reason":"end_turn","session_id":"a98e4463-4c6e-4e62-a0da-9f42ca8233db","total_cost_usd":0.00958873,"usage":{"input_tokens":2,"cache_creation_input_tokens":15020,"cache_read_input_tokens":2153,"output_tokens":13126,"output_tokens_details":{"thinking_tokens":10960},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15020,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13126,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15020,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15020},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13126,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15020,"webSearchRequests":0,"costUSD":0.00958873,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10960,"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's toolchain is measured as one assembled whole, whatever mix of third-party, first-party and project-written parts it uses.\n- Every detector a defence is routed through must conform to the detector specification, with wrapping allowed only if it closes the detector's gaps.\n- Every identifier a blocking rule can print must resolve offline to documentation on disk that states the correct construction.\n- Suppression routes that bypass the project record must be disabled or made to fail a blocking defence. Irreducible cases go to the project record with a justification.\n- The toolchain must list its active defences, including the project's own, without running them, from the active configuration. It must define and read a project record, and reject exceptions with generic justifications.\n- The entry point must run detectors before runners and stop on a detector failure. Agent-context summaries and their delivery are SHOULDs, and a conformance declaration is optional.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is everything the project assembles to run its checks through. \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" Section 1 adds: \"[Conformance] is a property of the assembled whole.\"\n\n**2b.** One grade. Each part is evidence for that grade and does not get its own. \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Section 1 says the parts \"may be third-party, first-party or project-level, in any combination.\" A project that ships nothing has only this project grade (clause 9.1: \"a project that ships nothing has only the one\").\n\n**2c.** Two grades: a project grade for the company's repository and an artefact grade for the published package, which is graded on what it supplies to consumers. Neither implies the other. \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" (clause 9.1)\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | The fixture's two undocumented Lintomatic bundled rules are the table row \"Two Bundled rules have no documentation \\| Nothing for those two \\| Fails\", and nothing in zig-qa or the project covers them. No verdict on Lintomatic under the detector specification is given, so I graded the wrapped pair from the fixture. |\n| 4.2 | No | The two undocumented enabled rules print identifiers that resolve to `(none)`. The clause says \"One [Identifier] that does not resolve fails this clause.\" I took enabled rules as blocking, since `zig-qa run` stops when Lintomatic fails. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline `// lintomatic-ignore` route, and exceptions go through `quality-exceptions.toml`. The fixture describes no other suppression route, so I graded on what is written. |\n| 4.4 | Yes | `zig-qa run` is local, runs over `zig-qa run <path>` down to one file, prints Lintomatic's output \"unchanged, one line per finding\", and is what CI runs. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first and \"stops when Lintomatic fails\", before the test suite. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` without running anything and prints identifier, summary and documentation path for each rule, showing `(none)` where documentation is missing. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, the same file `zig-qa run` loads. |\n| 5.3 | Yes | `zig-qa list` includes the `proj.*` rules alongside the bundled `zq.*` and Lintomatic rules. |\n| 6.1 | Partial | A location exists and is read by `zig-qa run` for exceptions. Section 1 defines the project record as also holding calibrations and conventions, and the fixture says nothing about where those live or whether they are read. |\n| 6.2 | No | The toolchain refuses an empty `reason`, but clause 6.2 says \"A field that is merely present and non-empty does not satisfy this clause\", and no check rejects generic justifications such as \"needed for now\". |\n| 6.3 | Partial | `zig-qa list --exceptions` lists exceptions in the same format as the rule listing. Calibrations and conventions are not described as enumerable, so the same gap as 6.1 applies. |\n\n**Overall.** The toolchain does not conform under section 9. Clauses 4.1, 4.2 and 6.2 are No, and 6.1 and 6.3 are Partial. It is in a partial condition, which section 9 says must not be described as conformance.\n\n**Agent support.** No. Section 9 defines agent-supported conformance as conformance plus everything section 7 recommends. Zigpipe has no agent summary (7.1), no `AGENTS.md`, and no delivery mechanism (7.2), so it fails that test too.\n\n**Section 8.** It does not apply to Zigpipe's project grade. Section 8 \"bears on the artefact grade\" only, and \"It does not ship any tooling to other projects.\" The company's published zig-qa package would be graded under section 8 as its own artefact, which the fixture does not grade.\n\n**Declaration.** The absence does not affect the verdict. Clause 9.2 says the declaration \"is optional\", and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The duty to record known gaps in a declaration applies only to declared projects. Gaps found by a practitioner are still recorded under method clause 3.2.\n\n## 4. Confusion\n\n- **6.1**, against the section 1 definition: \"**Project record** — The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.\" Clause 6.1 says \"The [Toolchain] MUST define where the [Project record] lives and MUST load it,\" while 6.2 and 6.3 speak only of exceptions. I could not tell from this whether the location in 6.1 must also hold calibrations and conventions.\n- **5.3**: \"Every [Defence] the project has written itself MUST appear in the listing clause 5.1 requires, meeting its content requirements in full.\" The content requirements are not stated in 5.3. I took them to be the listing contents in 5.1, but I had to infer that.","ttft_ms":47995,"type":"result","duration_ms":56085,"uuid":"8e733ff7-459c-4476-8c5b-46606f51bda7","ttft_stream_ms":1303,"time_to_request_ms":705,"first_content_frame_ms":1304,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":53839,"stop_reason":"end_turn","session_id":"8080cb33-2e4e-4de3-a1f2-4c700be30b77","total_cost_usd":0.00669413,"usage":{"input_tokens":2,"cache_creation_input_tokens":338,"cache_read_input_tokens":16833,"output_tokens":12916,"output_tokens_details":{"thinking_tokens":10744},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":338,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12916,"cache_read_input_tokens":16833,"cache_creation_input_tokens":338,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":338},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12916,"cacheReadInputTokens":16833,"cacheCreationInputTokens":338,"webSearchRequests":0,"costUSD":0.00669413,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10744,"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's toolchain, meaning the detectors, runners and the parts that route, list, record and resolve, is graded as one assembled whole (2, 9).\n- Every defence must run through a detector that conforms to the detector specification, and every blocking rule's identifier must resolve to on-disk documentation offline (4.1, 4.2).\n- Suppression routes that bypass the project record must be disabled or made to fail, and exceptions belong in the project record (4.3).\n- The project's own entry point must report locally and per file, print identifiers unaltered, and run detectors before runners, stopping on detector failure (4.4, 4.5).\n- The active defences must be listable without running them, derived from the loaded configuration, and include the project's own defences (5.1 to 5.3).\n- The project record must have a location the toolchain reads, exceptions must carry specific justifications, and the record must be listable like the defences (6.1 to 6.3).\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks through.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one conformance grade. The individual parts are evidence for that grade, not grades of their own.\n\n> \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** The project has two grades, a project grade and an artefact grade, and one does not imply the other.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nZigpipe does not ship tooling, so only the project grade applies. Lintomatic is the detector, zig-qa is the toolchain's first-party package, and the project rules are `proj.*`.\n\n- **4.1 — No.** Lintomatic's two undocumented bundled rules fail its resolve-offline requirement, and nothing in the project or zig-qa wraps them with documentation. The clause says a detector fails \"however much else the [Detector] does well.\"\n- **4.2 — No.** The two `(none)` identifiers print with nothing on disk to resolve to, and \"One [Identifier] that does not resolve fails this clause, however many others do.\" The fixture does not state that those two rules are Blocking. I took them as Blocking because `zig-qa run` stops when Lintomatic fails, but 4.1 fails either way.\n- **4.3 — Yes.** The only described suppression route is `// lintomatic-ignore`, and `ignore_comments = false` disables it. Exceptions go to `quality-exceptions.toml`. The fixture describes no baseline route, so nothing is owed for one.\n- **4.4 — Yes.** `zig-qa run` runs locally, takes `<path>` to limit the run, prints Lintomatic's output unchanged, and is what CI runs.\n- **4.5 — Yes.** `zig-qa run` runs Lintomatic first, then the test suite, and stops when Lintomatic fails.\n- **5.1 — Yes.** `zig-qa list` reads `lintomatic.toml` without running anything and lists each rule's identifier, summary and documentation path, showing `(none)` for the two undocumented rules.\n- **5.2 — Yes.** The listing is generated from `lintomatic.toml`, not from a hand-written document.\n- **5.3 — Yes.** The four `proj.*` rules appear in `zig-qa list` with their documentation paths, alongside the bundled rules.\n- **6.1 — Yes, with a caveat.** The record's location (`quality-exceptions.toml`) is defined and loaded by `zig-qa run`. The fixture describes only the exceptions file, so if calibrations or conventions are recorded elsewhere and never read, this would be Partial.\n- **6.2 — No.** `zig-qa run` only refuses an empty `reason`, and the clause says \"A field that is merely present and non-empty does not satisfy this clause.\" No check rejects generic justifications, and the fixture does not show that the justification must name the hazard and scope.\n- **6.3 — Yes.** `zig-qa list --exceptions` prints the record in the same format as the rule listing.\n\n**Conformance (section 9):** No. Clauses 4.1, 4.2 and 6.2 fail. Section 9 says \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support:** No. It requires conformance first, and the project has no defence summary (7.1) and no delivery into `AGENTS.md` or equivalent (7.2).\n\n**Section 8:** It does not apply to Zigpipe. The fixture says Zigpipe \"does not ship any tooling to other projects,\" and \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" zig-qa is published by the company, not by Zigpipe, so its own artefact grade is a separate question the fixture does not cover.\n\n**Absence of a declaration:** It has no effect on the verdict. Section 9.2 says \"The declaration is optional\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The verdict is No whether or not a declaration exists.\n\n## 4. Confusion\n\n- **4.1:** \"takes a verdict already given on the [Detector] under that document as settled.\" I was given no verdict on Lintomatic under the detector specification, so I could not tell whether this clause expects me to grade the detector itself or only the sentences it restates. I graded from the restated sentences.\n- **6.1 and section 2:** \"The [Toolchain] MUST define where the [Project record] lives,\" in the singular, while section 2 defines the record as holding \"[Calibrations], [Exceptions] and conventions.\" I could not tell whether one location is required for all three kinds of judgement.\n- **9.2:** \"A project or a shipped artefact MAY declare\" is followed by \"A project that ships an artefact carries both levels of clause 9.1 in that declaration,\" which reads as an obligation inside an optional provision. The next paragraph confirms the declaration is optional.","ttft_ms":46545,"type":"result","duration_ms":54579,"uuid":"24178a42-e716-4dfd-87f8-65efcc2caf7c","ttft_stream_ms":1579,"time_to_request_ms":747,"first_content_frame_ms":1580,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":59110,"stop_reason":"end_turn","session_id":"883aca73-8ac0-4bc3-a996-c8e616f6b4e4","total_cost_usd":0.01017773,"usage":{"input_tokens":2,"cache_creation_input_tokens":15020,"cache_read_input_tokens":2153,"output_tokens":14304,"output_tokens_details":{"thinking_tokens":12311},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15020,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14304,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15020,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15020},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14304,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15020,"webSearchRequests":0,"costUSD":0.01017773,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12311,"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- Conformance is judged on the whole toolchain the project assembles, wherever each part came from.\n- Every Defence must route through a Detector that conforms to the detector specification, with wrapping allowed.\n- Every Blocking rule's Identifier must resolve offline to documentation on disk, and the project must have a place for that documentation.\n- Suppression routes that bypass the project record must be disabled or made to fail a Blocking Defence. Irreducible cases go in the record.\n- The entry point must print Identifiers unaltered, run detectors before runners, and stop on a detector failure.\n- Active defences and the project record must be listable, derived from configuration, and enumerable by the same means. Exceptions need a specific written justification, and the toolchain must reject generic ones.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade, not grades of their own.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n> \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** The company's project has two grades: a project grade and an artefact grade. One does not imply the other.\n> \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application\n\n**4.1: No.** Lintomatic is the detector, and two of its bundled rules have no documentation that anything in the project or zig-qa supplies. The clause's own table lists \"Two [Bundled rules] have no documentation | Nothing for those two | Fails.\" The fixture gives no detector-spec verdict, so I graded from its description.\n\n**4.2: No.** The two enabled, undocumented bundled rules print Identifiers that resolve to `(none)`. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" The fixture does not say outright that these two are Blocking. I treated them as Blocking because they are enabled and `zig-qa run` stops when Lintomatic fails.\n\n**4.3: Yes.** `ignore_comments = false` disables the inline `// lintomatic-ignore` route, and exceptions live in `quality-exceptions.toml`. The fixture names no other route, such as a baseline. It does not say whether a rule can be switched off in `lintomatic.toml` without a record entry. If it can, that is an unaddressed route.\n\n**4.4: Yes.** `zig-qa run` runs locally with no service, `zig-qa run <path>` narrows the run to a directory or a single file, and it prints Lintomatic's output unchanged.\n\n**4.5: Yes.** `zig-qa run` runs Lintomatic first, then the test suite, and stops when Lintomatic fails. CI runs these scripts.\n\n**5.1: Yes.** `zig-qa list` reads `lintomatic.toml` without running anything, and prints each rule's identifier, summary and documentation path. The undocumented rules appear with `(none)`, so the gap shows.\n\n**5.2: Yes.** The listing comes from `lintomatic.toml`, which is the configuration Lintomatic is set up from, so a newly added rule appears on the next run. The fixture does not state outright that `zig-qa run` loads that same file.\n\n**5.3: Yes.** The four `proj.*` rules appear in `zig-qa list` with their documentation paths, alongside the bundled `zq.*` and Lintomatic rules.\n\n**6.1: Yes.** `quality-exceptions.toml` is a defined location, and `zig-qa run` loads it before Lintomatic runs. The fixture names no location for calibrations or conventions. If those belong to the project record, this would be Partial.\n\n**6.2: No.** The toolchain checks only that `reason` is non-empty. The clause says \"A field that is merely present and non-empty does not satisfy this clause,\" and the fixture describes no rejection of generic text such as \"TODO\" or \"legacy\".\n\n**6.3: Yes.** `zig-qa list --exceptions` prints the record \"in the same format as the rule listing.\"\n\n**Conformance under section 9: No.** Clauses 4.1, 4.2 and 6.2 fail. Section 9 says \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support: No.** The toolchain does not conform at all, and it also does none of section 7. It has no generated summary (7.1) and no delivery into an agent file (7.2), since it has no `AGENTS.md`.\n\n**Section 8: Does not apply.** Zigpipe ships nothing to other projects. Section 8 bears only on the artefact grade, and clause 9.1 says \"a project that ships nothing has only the one\" grade.\n\n**Effect of the missing declaration: None.** Clause 9.2 says \"The declaration is optional,\" and a verdict \"rests on that exercise and not on the claim.\" The gap still has to be recorded under the method's clause 3.2, whether or not a declaration exists.\n\n## 4. Confusion\n\n- Section 2, definition of **Project record**, and clause **6.1**. Section 2 says the project record is \"The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.\" Clause 6.1 says \"The [Toolchain] MUST define where the [Project record] lives and MUST load it… A path the [Toolchain] loads.\" Read together, it was unclear to me whether one path must hold all three kinds of judgement, or whether several files can together count as the record.","ttft_ms":52646,"type":"result","duration_ms":59701,"uuid":"f053c10c-b355-4efd-8cb7-2c801f2466cd","ttft_stream_ms":1325,"time_to_request_ms":596,"first_content_frame_ms":1326,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":66861,"stop_reason":"end_turn","session_id":"253eff31-2a50-4a59-8116-f606d9ffdde9","total_cost_usd":0.011210030000000003,"usage":{"input_tokens":2,"cache_creation_input_tokens":15019,"cache_read_input_tokens":2153,"output_tokens":16369,"output_tokens_details":{"thinking_tokens":14081},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15019,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":16369,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15019,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15019},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":16369,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15019,"webSearchRequests":0,"costUSD":0.011210030000000003,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":14081,"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's toolchain is measured as a whole, whatever mix of third-party, first-party and project-level parts it assembles.\n- Every rule a toolchain routes a defence through must come from a detector that meets the detector specification, with gaps closed by wrapping or by the toolchain's own additions.\n- Blocking rules must have resolvable documentation on disk, and suppression routes that bypass the project record must be disabled or made to fail.\n- The toolchain's entry point must run detectors before runners, stop on a detector failure, and print detector identifiers unaltered.\n- The toolchain must list active defences and the project record without running them, derived from the loaded configuration, and must read the project record from a defined location.\n- Every exception needs a specific written justification, and a shipped toolchain must check its own documentation and run its own rules on its own source.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks through. \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly gets one project grade. The individual parts are evidence for that grade and do not receive grades of their own. A second grade appears only if the project ships an artefact. \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Also: \"A project's [Toolchain] [Conforms] if every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from.\"\n\n**2c.** Two grades: the project grade, and the artefact grade for the shipped package. Neither implies the other. \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" Also: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | **No** | Lintomatic is the detector, and two of its forty bundled rules have no documentation. Nothing in zig-qa or the project provides documentation for them, so the wrapping table's \"Two Bundled rules have no documentation / Nothing for those two / Fails\" applies. The other listed properties appear met. I have not seen detector specification sections 4 to 7 in full, so I checked only the properties this clause lists. |\n| 4.2 | **No** | The two enabled, undocumented bundled identifiers do not resolve, and `zig-qa list` prints their path as `(none)`. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" The fixture does not say outright that these rules are Blocking, but `zig-qa run` stops when Lintomatic fails, so I read them as Blocking. |\n| 4.3 | **Yes** | The only described suppression route is the inline `// lintomatic-ignore` comment, disabled by `ignore_comments = false`, and exceptions go to `quality-exceptions.toml`. The fixture describes no baseline. It does not say whether toggling rules in `lintomatic.toml` counts as a route around the record, so this verdict rests on the described evidence. |\n| 4.4 | **Yes** | `zig-qa run` runs locally with no service, `zig-qa run <path>` narrows the run to a file, and Lintomatic's output is printed unchanged, so identifiers arrive unaltered in the command's output. |\n| 4.5 | **Yes** | `zig-qa run` runs Lintomatic, then the test suite, and \"stops when Lintomatic fails.\" CI runs the same script. |\n| 5.1 | **Yes** | `zig-qa list` reads `lintomatic.toml` without running rules and prints identifier, summary and documentation path. Undocumented rules appear with `(none)`. |\n| 5.2 | **Yes** | The listing is generated from `lintomatic.toml`, the configuration Lintomatic loads, so a newly added rule appears without other edits. |\n| 5.3 | **Yes** | The `proj.*` rules are included in `zig-qa list`, and their pages state what they forbid, why, and what to write instead. |\n| 6.1 | **Partial** | `quality-exceptions.toml` is defined and loaded by `zig-qa run`. Section 2 defines the project record as including calibrations and conventions, and the fixture names no location for either. If the project has neither, this becomes Yes. |\n| 6.2 | **No** | The only check described is that `reason` is non-empty, and the clause says that \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing rejects generic text such as \"needed for now\" or \"TODO\", and nothing requires the reason to name the hazard and scope. |\n| 6.3 | **Yes** | `zig-qa list --exceptions` uses the same script and the same format as the rule listing. |\n\n**Conformance under section 9: No.** Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is Partial. Under section 9, \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support: No.** The verdict does not arise because base conformance fails. The project also does neither thing section 7 recommends: it publishes no defence summary and has no `AGENTS.md` or equivalent.\n\n**Section 8: does not apply.** Section 8 bears on a shipped toolchain, and \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" Zigpipe ships nothing. The company's zig-qa package is a separate artefact, and any grade for it would be a separate artefact grade under 9.1. The fixture does not say that grade exists.\n\n**Absence of a declaration: no effect on the verdict.** Clause 9.2 says the declaration \"is optional,\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The duty to record known gaps in a declaration falls only on a project that has one. Gaps are still recorded under method clause 3.2 whether or not a declaration exists.\n\n## 4. Confusion\n\n- **Clause 5.1 and the section 2 note on undocumented rules.** Section 2 says: \"A [Blocking] [Rule] whose documentation is missing is not yet a [Defence].\" Clause 5.1 is framed as listing \"every [Defence] active in the project,\" but it then says: \"The listing covers every [Blocking] [Rule] the [Toolchain] runs, documented or not.\" Read together, the listing obligation applies to things the document has just said are not Defences, and I had to rely on the section 2 note to see that the two sentences are meant to apply together.","ttft_ms":59208,"type":"result","duration_ms":67550,"uuid":"623e043a-196c-44c5-ab9d-234e4b4f42f8","ttft_stream_ms":1323,"time_to_request_ms":698,"first_content_frame_ms":1324,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 081: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone, on the
evidence a project shows. Where a clause rests on the [detector specification](DETECTOR-SPEC.md),
as clauses 4.1, 4.2 and 4.4 do, it restates what the grader checks, and a verdict already given
on the [Detector] under that document is taken as settled. The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

A [Blocking] [Rule] whose documentation is missing is not yet a [Defence]. It is what clauses
4.2, 5.1 and 8.1 exist to catch, so where those clauses reach a [Toolchain]'s [Rules] they reach
every [Blocking] [Rule] it runs, documented or not.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them. A grader of this
clause checks the sentences that follow, which restate the ones most often failed, and takes a
verdict already given on the [Detector] under that document as settled: a [Detector] that
document finds not to [Conform] fails this clause, whether or not the sentences that follow
show why. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. A [Detector] that fails any
one of them, after wrapping, fails this clause. Three points govern how that is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. That is every [Blocking] [Rule] the [Toolchain] runs, the project's
own and the bundled alike. One [Identifier] that does not resolve fails this clause, however
many others do.

The resolving mechanism is keyed on the [Identifier] exactly as printed. Those
[Remediation docs] MUST ship with the project, with the [Toolchain] or with the [Detector]
whose [Rule] they document, at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open: that
document holds a [Detector] to on-disk resolution of its own [Bundled rules] and no further,
because it cannot know a project's documentation, and this clause reaches the project's own
[Rules] as well. An [Identifier] a third-party [Detector] resolves under that document's clause
6 meets this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.
The listing covers every [Blocking] [Rule] the [Toolchain] runs, documented or not, and a
[Rule] whose route to documentation is missing is listed with that gap showing.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.

[LTSCommerce]

Run 082: 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/toolchain-contradictions`). The readers read commit de34774. 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 0da928d, named here before the readers started), acceptance/runs/README.md, acceptance/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/081-toolchain-contradictions-run-9.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 082. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 81: clause 5.1 no longer says the listing covers every blocking rule, documented or not; it says a blocking rule whose route to documentation is missing is not yet a defence, that clause 4.2 fails it, and that the listing can show it with the gap showing; section 2's closing paragraph names clauses 4.2 and 8.1 as the clauses that catch such a rule. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 10 (runs 57, 58, 62, 65, 67, 68, 72, 76 and 81 came before). Record file to write: <worktree>/acceptance/runs/082-toolchain-contradictions-run-10.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 1fa098d5a7901d8211c09387ca7bffd0bcabcd05caba5565a489557ae5761028, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at de34774, 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 de34774 -- TOOLING-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, a paragraph the change parts from what it refers to, 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 0da928d, 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 082: 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":56185,"stop_reason":"end_turn","session_id":"385027db-e7f1-4e6a-9115-9e1155c38eca","total_cost_usd":0.00975673,"usage":{"input_tokens":2,"cache_creation_input_tokens":15005,"cache_read_input_tokens":2153,"output_tokens":13468,"output_tokens_details":{"thinking_tokens":11312},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15005,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13468,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15005,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15005},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13468,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15005,"webSearchRequests":0,"costUSD":0.00975673,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11312,"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's toolchain, meaning its detectors, runners, and the parts that route, list, record and resolve, is graded as one assembled whole at project level.\n- Every detector a defence is routed through must conform to the detector specification, and every blocking rule must resolve its identifier to documentation on disk, offline.\n- Suppression routes that bypass the project record must be disabled or caught by a blocking defence. Irreducible cases go into the record.\n- The entry point runs detectors before runners, stops on a detector failure, runs locally on a subset down to one file, and prints identifiers unaltered.\n- The defences and the project record must both be listed from the active configuration by the same kind of operation, with the project's own rules included.\n- The record needs a location the toolchain reads, and each exception needs a written justification that names the hazard and scope. Generic justifications must be rejected. A shipped artefact gets a second, separate grade.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n> \"[Conformance] is a property of the assembled whole, because that is where it counts\"\n\n**2b.** The assembly receives one project-level grade. The third-party detector, the first-party package and the project's own rules are evidence for that grade. They are not separate grades. Zigpipe ships nothing, so it has only that one grade.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n> \"a project that ships nothing has only the one.\"\n\n**2c.** The project has two grades: the project grade, and the artefact grade for the package it publishes. Neither implies the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n> \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nZigpipe's two undocumented bundled rules are the main gap. I took their blocking status from the fixture's statement that `zig-qa run` stops when Lintomatic fails and that the rules are enabled in that run. The fixture does not say so directly. Section 4.1 also relies on a detector-specification verdict that I was not given, so I graded that clause from the fixture and the table in 4.1 itself.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic has two bundled rules with no documentation, and nothing in the project or in zig-qa supplies it. The 4.1 table marks \"Two Bundled rules have no documentation\" with nothing added as \"Fails\". |\n| 4.2 | No | Two enabled, apparently blocking rules print identifiers that resolve to nothing, and `zig-qa list` shows `(none)`. One unresolved identifier fails the clause. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline ignore route, and exceptions go to `quality-exceptions.toml`. The fixture describes no other suppression route, though it does not say whether removing a rule in `lintomatic.toml` needs a record entry. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, `zig-qa run <path>` limits it to a file, and it prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first and stops when it fails, and CI runs the same script. |\n| 5.1 | Yes | `zig-qa list` prints every active rule without running it, with identifier, summary and documentation path. The two undocumented rules show `(none)`, which 5.1 allows: the listing \"can show it with that gap showing\". |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, so the listing is derived from the configuration. |\n| 5.3 | Yes | The `proj.*` rules are listed by `zig-qa list`, and their documentation is in `docs/defences/`. |\n| 6.1 | Yes | `quality-exceptions.toml` is a defined location, and `zig-qa run` loads it. |\n| 6.2 | No | The only check is that `reason` is non-empty, and 6.2 says a field that is \"merely present and non-empty does not satisfy this clause\". Nothing checks for hazard, scope, or generic text. |\n| 6.3 | Yes | `zig-qa list --exceptions` uses the same format and tool as the rule listing. |\n\n**Conformance under section 9:** Zigpipe does not conform. 4.1, 4.2 and 6.2 fail, and section 9 says every MUST in sections 4 to 6 must hold. Its status is partial, and partial conformance must not be described as conformance.\n\n**Conformance with agent support:** No. This requires conformance first. Zigpipe also has no defence summary (7.1) and no delivery into `AGENTS.md` or equivalent (7.2), and both are SHOULDs that section 9 asks for.\n\n**Section 8:** It does not apply to Zigpipe. Zigpipe ships no tooling to other projects, so section 8 \"does not bear on its [Conformance]\". Section 8 would apply to the company's `zig-qa` package when that package's publisher grades its artefact, and that is a separate question.\n\n**Absence of a declaration:** It does not affect the verdict. Section 9.2 says the declaration \"is optional\", and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\"\n\n## 4. Confusion\n\n- **5.1:** \"It MUST provide the route to each one's full documentation.\" and, in the same clause, \"the listing can show it with that gap showing.\" Read together, it is unclear whether an empty route still satisfies the MUST.\n- **6.2:** \"by a check it documents: 'needed for now', 'legacy', 'TODO' and their like.\" The test in the same sentence is whether a justification \"could be pasted onto any [Exception] unchanged\". The examples are phrase-based, and \"their like\" leaves the set open, so it is unclear which test governs.\n- **4.1:** \"takes a verdict already given on the [Detector] under that document as settled.\" No such verdict appears in the fixture, so I could not tell which verdict is meant.","ttft_ms":48885,"type":"result","duration_ms":56640,"uuid":"d8984f76-0c29-48e3-b6e9-c3de628256c4","ttft_stream_ms":1210,"time_to_request_ms":464,"first_content_frame_ms":1210,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":78703,"stop_reason":"end_turn","session_id":"e4747e68-4ce6-4419-ab1d-6a3087aac9fa","total_cost_usd":0.012744330000000002,"usage":{"input_tokens":2,"cache_creation_input_tokens":15008,"cache_read_input_tokens":2153,"output_tokens":19442,"output_tokens_details":{"thinking_tokens":16839},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15008,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":19442,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15008,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15008},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":19442,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15008,"webSearchRequests":0,"costUSD":0.012744330000000002,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":16839,"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":"# Answers\n\n## 1. Restatement\n\n- Conformance is a property of a project's whole assembled toolchain (detectors, runners, and the parts that route, list, record and resolve), wherever each part came from.\n- Every defence must run through detectors that conform to the detector specification, with wrapping allowed to fill gaps.\n- Every identifier a blocking rule can print must resolve to documentation on disk, offline, and the documentation must state the correct construction.\n- Suppression routes that bypass the project record must be disabled or must fail a blocking defence, and the entry point must run detectors before runners and stop on a detector failure.\n- The active defences and the project record must be listable without triggering anything, from the live configuration, including the project's own rules. Every exception needs a specific written justification that the toolchain checks for.\n- Defaults, an agent-context summary and its delivery are recommended (SHOULD). Shipped artefacts get a separate grade and a self-audit.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is everything the project assembles to run its checks. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade and do not get grades of their own. The document says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" It also says: \"**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from.\"\n\n**2c.** The project has two grades: a project grade, which every project has, and an artefact grade for the shipped package. One does not imply the other. The document says: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" It also says: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic is the detector the defences route through. Two of its forty bundled rules have no documentation, nothing in the project or zig-qa supplies it, so `lintomatic explain` cannot resolve those two identifiers. No wrapping fills that gap. No verdict on Lintomatic under the detector specification was given, so I graded from the restated sentences. |\n| 4.2 | No | The two enabled bundled rules print identifiers that resolve to nothing, and \"One [Identifier] that does not resolve fails this clause\". I am assuming these two rules are Blocking. The fixture does not say so explicitly, but `zig-qa run` stops when Lintomatic fails and the rules are enabled. If they are not Blocking, this clause does not reach them. The documentation for `zq.*` and for the 38 documented bundled rules is not described, so I could not check the \"correct construction\" requirement for those. |\n| 4.3 | Yes | `ignore_comments = false` disables the only suppression route the fixture describes. Exceptions go to `quality-exceptions.toml`. The fixture describes no baseline or other silent route, so I took the description as complete. |\n| 4.4 | Yes | Both scripts run locally with no service, `zig-qa run <path>` limits the run to a file, and Lintomatic's output is printed unchanged, so identifiers print unaltered. Clause 4.4 cites detector clauses 5.1 to 5.4, but restates only three properties. I did not have the detector specification, so I graded against the restated sentences. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic before the test suite and stops when Lintomatic fails. CI runs it. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints each rule's identifier, summary and documentation path without running anything. The two undocumented rules show `(none)`, which 5.1 allows the listing to show. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, the configuration the run loads. Nothing is hand-maintained. |\n| 5.3 | Yes | The four `proj.*` rules are included in `zig-qa list`, alongside the bundled and `zq.*` rules. Their pages say what, why and what to write instead. |\n| 6.1 | Partial | A location exists and is loaded for exceptions: `quality-exceptions.toml`, read by `zig-qa run` and `zig-qa list --exceptions`. Section 2 says the project record also holds calibrations and conventions, and the fixture describes no location or loading for either. If the exceptions file is the whole project record, this becomes Yes. |\n| 6.2 | No | The only check is that `reason` is not empty, and the clause says \"A field that is merely present and non-empty does not satisfy this clause.\" No check rejects generic phrases, and nothing requires a reason to name the hazard and scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` uses the same command and prints in the same format as the rule listing. |\n\n**Conformance under section 9:** No. Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is partial. The project's toolchain does not conform, and partial conformance may not be described as conformance.\n\n**Conformance with agent support:** No. The fixture says Zigpipe publishes no defence summary for agents and has no `AGENTS.md` or equivalent, so it does not do what section 7 recommends. That verdict would not hold in any case, since it presupposes conformance.\n\n**Whether section 8 applies:** No. Section 8 bears only on the artefact grade. Section 8 says that a project which \"assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" The fixture says Zigpipe ships no tooling. The `zig-qa` package is shipped by the company, so its own artefact grade and section 8 would apply to that package, but that is not Zigpipe's grade and I did not assess it.\n\n**Whether the absence of a declaration affects the verdict:** No. Clause 9.2 says \"The declaration is optional\", and a verdict on any toolchain, declared or not, rests on the evidence. Zigpipe has no declaration, so the verdict stands on the grading above.\n\n## 4. Confusion\n\n- **Clause 4.1:** \"takes a verdict already given on the [Detector] under that document as settled: a [Detector] that document finds not to [Conform] fails this clause, whether or not the sentences that follow show why.\" It was unclear what a grader does when no such verdict has been given, which is the case here.\n- **Clause 4.3:** \"This clause is where the project's decision is made and enforced, and the decision is no.\" The sentence does not say what the \"no\" is an answer to. I inferred that it refers to suppression routes.\n- **Clause 4.4:** \"The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the [detector specification] for every [Defence] it routes.\" The restatement that follows covers three properties and does not mention 5.4, so it was unclear whether 5.4 is graded.\n- **Clause 6.1:** \"The [Toolchain] MUST define where the [Project record] lives and MUST load it.\" Section 2 defines the project record as one place for calibrations, exceptions and conventions, but 6.1 and 6.2 only address exceptions. It was unclear whether one location must hold all three. This is why I graded 6.1 Partial.\n- **Section 2:** \"These are additional.\" It follows a table, and I could not tell what the terms are additional to.","ttft_ms":69859,"type":"result","duration_ms":79109,"uuid":"4a0758de-6cb3-4cbe-bd0f-5644a50e373e","ttft_stream_ms":1206,"time_to_request_ms":400,"first_content_frame_ms":1206,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":49424,"stop_reason":"end_turn","session_id":"1c84641c-f4e6-4e16-8e00-638e2e83e95d","total_cost_usd":0.00925193,"usage":{"input_tokens":2,"cache_creation_input_tokens":15006,"cache_read_input_tokens":2153,"output_tokens":12458,"output_tokens_details":{"thinking_tokens":10268},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15006,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12458,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15006,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15006},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12458,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15006,"webSearchRequests":0,"costUSD":0.00925193,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10268,"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- Toolchain conformance is measured on the whole project's assembled checks, whichever parts (third-party, first-party or project-level) supply them.\n- Every defence must run through a detector that conforms to the detector specification, and every blocking rule's identifier must resolve to documentation on disk, offline.\n- Suppression routes that bypass the project record (inline ignores, silent baselines) must be disabled or made to fail a blocking defence. Irreducible cases go to the project record.\n- The entry point must expose each detector's reporting (local, subsettable to one file, identifiers printed unaltered) and run detectors before runners, stopping on a detector failure.\n- The active defences must be listable without running them, derived from the loaded configuration, and include the project's own defences.\n- The project record must live at a location the toolchain loads, every exception must carry a specific written justification the toolchain enforces, and the record must be listable the same way as the defences. Agent summaries and their delivery are SHOULDs, and a project that ships tooling gets a second, artefact-level grade.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks: detectors, runners, and the parts that route, list, record and resolve.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The detector, the package and the project rules are evidence toward that single grade, not grades of their own.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\nSection 1 supports this: \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** The company's project has two grades: a project grade for its repository, and an artefact grade for the package it publishes. One does not imply the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n> \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic has two bundled rules with no documentation, and nothing in the project or zig-qa supplies it. The 4.1 table says a gap that wrapping does not cover (\"Nothing for those two\") fails, so the wrapped detector fails the offline-resolution requirement. |\n| 4.2 | No | The two enabled undocumented Lintomatic rules show `(none)` in `zig-qa list`, so their identifiers resolve to nothing. The fixture does not say they are Blocking, but `zig-qa run` stops on Lintomatic failure, so I treated them as Blocking. One unresolved identifier fails the clause. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline route project-wide. Exceptions go to `quality-exceptions.toml`. The fixture describes no other route, but it is silent on baselines, so if Lintomatic has a silent baseline this verdict would need checking. |\n| 4.4 | Yes | `zig-qa run` prints Lintomatic's output unchanged, one line per finding. `zig-qa run <path>` limits the run to a directory or file. Both scripts run locally with no service. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs these scripts. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints identifier, summary and documentation path without running any rule. The two undocumented rules appear with `(none)`, which 5.1 explicitly allows the listing to show. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, the configuration the toolchain loads, so the listing is derived from it. The fixture does not say how the `proj.*` rules reach that configuration, but it says the list includes them. |\n| 5.3 | Yes | The four `proj.*` rules are included in `zig-qa list`, and each has a page in `docs/defences/`. |\n| 6.1 | Partial | `zig-qa run` loads `quality-exceptions.toml` itself. Section 2 defines the project record as also holding calibrations and conventions, and the fixture gives no location or loader for those. This would be Yes if the exceptions file alone is the record the grade is about. |\n| 6.2 | No | The toolchain enforces only a non-empty `reason`, which the clause says is not enough. Nothing checks for a named hazard or scope, or rejects generic phrases such as \"needed for now\" or \"TODO\". |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the exceptions in the same format as the rule listing. |\n\n**Conformance under section 9: No.** Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is at best partial. Section 9 requires every MUST in sections 4 to 6 to hold, and partial conformance is not conformance.\n\n**Conformance with agent support: No.** The base grade is not met. The fixture also says there is no defence summary, no `AGENTS.md` and no delivery, so the section 7 SHOULDs are not done.\n\n**Section 8: does not apply.** Section 8 bears only on an artefact grade. The fixture says Zigpipe ships no tooling to other projects. The company publishes `zig-qa`, so its artefact grade belongs to that package's own project, not to Zigpipe.\n\n**Declaration: no effect on the verdict.** Under 9.2 the declaration is optional, and \"a verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The failures above stand without it.\n\n## 4. Confusion\n\nClause 5.1 reads: \"The [Toolchain] MUST list every [Defence] active in the project without running it.\" A few sentences later it says: \"A [Blocking] [Rule] whose route to documentation is missing is not yet a [Defence]: clause 4.2 fails it, and the listing can show it with that gap showing.\" On my reading, the MUST covers every defence, but the second sentence says an undocumented blocking rule is not a defence, and then uses \"can\" for whether the listing shows it. I could not tell whether the two undocumented Lintomatic rules are required to appear in the listing.","ttft_ms":42659,"type":"result","duration_ms":49922,"uuid":"faba4af3-3d4d-4aac-ad84-273b42227bfa","ttft_stream_ms":1281,"time_to_request_ms":486,"first_content_frame_ms":1282,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":53264,"stop_reason":"end_turn","session_id":"0ff1baaf-a873-4d2a-ab30-3acc2d12cc57","total_cost_usd":0.00682171,"usage":{"input_tokens":2,"cache_creation_input_tokens":339,"cache_read_input_tokens":16821,"output_tokens":13171,"output_tokens_details":{"thinking_tokens":10960},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":339,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13171,"cache_read_input_tokens":16821,"cache_creation_input_tokens":339,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":339},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13171,"cacheReadInputTokens":16821,"cacheCreationInputTokens":339,"webSearchRequests":0,"costUSD":0.00682171,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10960,"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's toolchain, meaning everything it assembles to run its checks, is graded as one whole, whoever wrote each part.\n- Every detector the toolchain routes a defence through must conform to the detector specification, with wrapping allowed (4.1).\n- Every identifier a blocking rule prints must resolve offline to documentation on disk, and the toolchain must provide a place for that documentation (4.2).\n- Suppression routes that bypass the project record must be disabled or made to fail a blocking defence (4.3).\n- The toolchain's own entry point must report detector output in full, run detectors before runners, and stop on a detector failure (4.4, 4.5).\n- Active defences must be listable without running them, derived from the loaded configuration, and include the project's own (5.1–5.3).\n- The project record must live at a location the toolchain reads, every exception needs a specific justification the toolchain enforces, and the record must be listable like the defences (6.1–6.3).\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" It adds: \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n**2b.** One grade. The parts contribute only evidence. The document says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" It also says a project conforms \"if every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from.\"\n\n**2c.** Two grades, one for the project and one for the artefact it ships. Neither implies the other. The document says: \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\" Because this company ships the package, it has both.\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic's two undocumented bundled rules are not covered by wrapping, since zig-qa and the project provide nothing for them. The document's table says: \"Two [Bundled rules] have no documentation \\| Nothing for those two \\| Fails.\" The fixture gives no detector-spec verdict, so I graded from the restated sentences. |\n| 4.2 | No | The two undocumented rules are enabled and `zig-qa list` shows their path as `(none)`. I took them as blocking because `zig-qa run` stops when Lintomatic fails, which the fixture does not say directly. The document says: \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 4.3 | Yes | `ignore_comments = false` disables the inline route, and exceptions go through `quality-exceptions.toml`. The fixture describes no other suppression route, so this is judged on the routes it describes. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts a path to limit the run, and prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic before the test suite and stops when Lintomatic fails, and CI runs the same script. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` without running anything and prints identifier, summary and documentation path for each rule. |\n| 5.2 | Yes | The listing is read from `lintomatic.toml`, the same configuration `zig-qa run` loads, so it is derived rather than hand-maintained. |\n| 5.3 | Yes | The `proj.*` rules appear in `zig-qa list` alongside the `zq.*` and bundled rules. |\n| 6.1 | Yes | `quality-exceptions.toml` is a defined path that `zig-qa run` and `zig-qa list --exceptions` both load. |\n| 6.2 | No | The only check is that `reason` is non-empty, and the document says \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing checks that the justification names the hazard and scope or rejects generic text such as \"TODO\". |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing. |\n\n**Conformance under section 9:** No. Clauses 4.1, 4.2 and 6.2 fail, and the document requires every MUST to hold. The document also says partial conformance \"MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support:** No. It is not conforming in the first place, and the fixture says there is no agent summary (7.1) and no delivery into `AGENTS.md` or equivalent (7.2), so neither SHOULD is met.\n\n**Whether section 8 applies:** No. Section 8 applies to a shipped toolchain, and the fixture says Zigpipe \"does not ship any tooling to other projects.\" Section 9 says section 8 \"bears on the artefact grade\" only. The company's zig-qa package would have its own artefact grade under 9.1, but the fixture gives no grade for it, and it does not change Zigpipe's project grade.\n\n**Whether the missing declaration affects the verdict:** No. The document says \"The declaration is optional\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The gap-recording duty applies only to projects that have a declaration, though the document also says a gap a practitioner finds is recorded \"in any case.\"\n\n## 4. Confusion\n\n- **6.2.** The heading and body require the justification to \"name the [Hazard] ... and the scope,\" and say the toolchain \"MUST reject a generic one.\" But the only mechanism described is a check for generic phrases (\"needed for now\", \"legacy\", \"TODO\" and their like), and the document also says that check \"cannot verify truth.\" I could not tell whether the toolchain is required to check that the hazard and scope are named, or only to reject generic phrases.\n- **Section 2, under \"Project record.\"** The paragraph beginning \"A [Blocking] [Rule] whose documentation is missing is not yet a [Defence]\" sits under the \"Project record\" definition rather than under \"Defence,\" so I could not tell which term it governs.\n- **9.1.** The phrase \"the project's remediations against section 7 of the method specification\" is unclear to me. Section 7 of the method is not in the materials I was given, so I could not work out what it requires of a project.","ttft_ms":46142,"type":"result","duration_ms":53768,"uuid":"76f9c716-d457-4ef3-b443-72373929bb18","ttft_stream_ms":1112,"time_to_request_ms":496,"first_content_frame_ms":1113,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":54451,"stop_reason":"end_turn","session_id":"51da1787-fac5-4227-83c4-c8b6d772835d","total_cost_usd":0.00947403,"usage":{"input_tokens":2,"cache_creation_input_tokens":15009,"cache_read_input_tokens":2153,"output_tokens":12901,"output_tokens_details":{"thinking_tokens":10628},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15009,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12901,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15009,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15009},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12901,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15009,"webSearchRequests":0,"costUSD":0.00947403,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":10628,"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's toolchain is graded as one assembled whole, with a single project-level verdict, regardless of which parts came from which package.\n- Every detector the toolchain routes a defence through must conform to the detector specification, with wrapping allowed to fill gaps but not to excuse them.\n- Every identifier a blocking rule can print must resolve, offline and on disk, to documentation that ships with the project, toolchain or detector, including the project's own rules.\n- Suppression routes that bypass the project record must be disabled or caught by a blocking defence, and any irreducible case goes into the project record with a justification.\n- The toolchain must list active defences from its loaded configuration without running them, include the project's own rules, and enumerate the project record the same way, with exceptions requiring a specific justification rather than a generic one.\n- The entry point must run detectors before runners and stop on a detector failure, and a project that ships a toolchain or detector gets a separate artefact grade.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The parts are evidence for that grade, not grades of their own. The document says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" It also says the parts \"may be third-party, first-party or project-level, in any combination.\" Section 9 applies the same rule: a project [Conforms] if \"every MUST in sections 4 to 6 holds across the assembled parts, wherever each part came from.\"\n\n**2c.** The company's project has two grades, one for the project and one for the artefact it ships. Neither implies the other. The document says: \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\" The fact that the company uses the package on its own repository does not merge the two grades.\n\n## 3. Application to Zigpipe\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic has two enabled bundled rules with no documentation, and nothing in zig-qa supplies it. The document's own table says that gap \"Fails\" even after wrapping. |\n| 4.2 | No | The two undocumented bundled rules are enabled and run inside `zig-qa run`, which stops when Lintomatic fails, so I treat them as Blocking. The fixture does not state their blocking status, and if they are non-blocking this clause would be Yes. |\n| 4.3 | Yes | The only Lintomatic suppression route described is `// lintomatic-ignore`, and `ignore_comments = false` disables it. The fixture does not mention a baseline or other routes, so the verdict assumes there are none. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts `<path>` to limit to a file or directory, and prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first, then the test suite, and stops when Lintomatic fails. CI runs this same command. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` without running anything and prints identifier, summary and documentation path for each active rule. The two `(none)` entries are the gap clause 4.2 already reports, which the clause allows the listing to show. |\n| 5.2 | Yes | The listing comes from `lintomatic.toml`, the same file `zig-qa run` loads. The fixture does not say whether bundled rules that are enabled by default but absent from that file would appear, so this has a caveat. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules alongside the bundled `zq.*` and Lintomatic rules. |\n| 6.1 | Partial | `quality-exceptions.toml` has a defined location and is loaded by `zig-qa run`. The document's project record also covers calibrations and conventions, and the fixture describes no location or loading for those. If the exceptions file is taken to be the whole record, this becomes Yes. |\n| 6.2 | No | The only check is that `reason` is non-empty, which the clause expressly says is not enough. Nothing rejects a generic justification such as \"TODO\" or \"legacy\", and nothing requires the hazard and scope to be named. |\n| 6.3 | Yes | `zig-qa list --exceptions` uses the same tool and the same output format as the rule listing. |\n\n**Conformance under section 9.** The toolchain does not conform. Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is partial. The document says \"Partial [Conformance] MUST NOT be described as [Conformance],\" so the honest verdict is that it is partially conforming.\n\n**Conformance with agent support.** No. Section 9 requires full conformance before agent support counts, and in any case the fixture says Zigpipe \"does not publish a summary of its defences for an agent and has no `AGENTS.md`,\" so clauses 7.1 and 7.2 are unmet.\n\n**Whether section 8 applies.** No. Section 8 \"bears on the artefact grade only,\" and the fixture says Zigpipe \"does not ship any tooling to other projects.\" The document also says a project that does not ship its toolchain \"has no release and no [Consuming project], so this section does not bear on its [Conformance].\" Zig-qa is the company's shipped artefact, so it has its own artefact grade, but this fixture does not grade it.\n\n**Whether the absence of a declaration affects the verdict.** No. Clause 9.2 says \"The declaration is optional,\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" Zigpipe has no declaration, so it has no gap-record duty under that clause. The verdict rests on the MUSTs above, and the gaps are still recorded under method clause 3.2 whether or not a declaration exists.\n\n## 4. Confusion\n\nOne passage I found unclear on my reading, clause 5.3:\n\n> \"Where such a [Defence] is not expressible in the [Toolchain]'s own [Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived under clause 5.2 rather than hand-maintained.\"\n\nI could not tell whether \"wherever it is enabled\" includes configuration outside the toolchain's own files. I resolved it by treating the four `proj.*` rules as covered, since the fixture says `zig-qa list` includes them.","ttft_ms":46556,"type":"result","duration_ms":54997,"uuid":"bdb5046f-a58b-4e30-a313-104fba050128","ttft_stream_ms":1471,"time_to_request_ms":543,"first_content_frame_ms":1472,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 082: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone, on the
evidence a project shows. Where a clause rests on the [detector specification](DETECTOR-SPEC.md),
as clauses 4.1, 4.2 and 4.4 do, it restates what the grader checks, and a verdict already given
on the [Detector] under that document is taken as settled. The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

A [Blocking] [Rule] whose documentation is missing is not yet a [Defence]. Clauses 4.2 and 8.1
exist to catch it, so where they reach a [Toolchain]'s [Rules] they reach every [Blocking]
[Rule] it runs, documented or not.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them. A grader of this
clause checks the sentences that follow, which restate the ones most often failed, and takes a
verdict already given on the [Detector] under that document as settled: a [Detector] that
document finds not to [Conform] fails this clause, whether or not the sentences that follow
show why. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. A [Detector] that fails any
one of them, after wrapping, fails this clause. Three points govern how that is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. That is every [Blocking] [Rule] the [Toolchain] runs, the project's
own and the bundled alike. One [Identifier] that does not resolve fails this clause, however
many others do.

The resolving mechanism is keyed on the [Identifier] exactly as printed. Those
[Remediation docs] MUST ship with the project, with the [Toolchain] or with the [Detector]
whose [Rule] they document, at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open: that
document holds a [Detector] to on-disk resolution of its own [Bundled rules] and no further,
because it cannot know a project's documentation, and this clause reaches the project's own
[Rules] as well. An [Identifier] a third-party [Detector] resolves under that document's clause
6 meets this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.
A [Blocking] [Rule] whose route to documentation is missing is not yet a [Defence]: clause 4.2
fails it, and the listing can show it with that gap showing.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.

[LTSCommerce]

Run 083: 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/toolchain-contradictions`). The readers read commit c770722. 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 ae6faf2, named here before the readers started), acceptance/runs/README.md, acceptance/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/082-toolchain-contradictions-run-10.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 083. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 82: clause 5.1 says nothing of undocumented rules any more; the paragraph on a blocking rule whose documentation is missing now ends section 2, after the paragraph on the distinction between a bundled defence and a project's own, and opens "Throughout this document"; clause 4.1 and section 1 name the verdict a grader takes as one the detector already holds under the detector specification's section 8, and clause 4.1 says that without one the restated sentences are the test. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 11 (runs 57, 58, 62, 65, 67, 68, 72, 76, 81 and 82 came before). Record file to write: <worktree>/acceptance/runs/083-toolchain-contradictions-run-11.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 1f981586432ce938dba63935e5be59cd7e1b36b1569fedc019b576877b34c06d, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at c770722, 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 c770722 -- TOOLING-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, a paragraph the change parts from what it refers to, 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 ae6faf2, 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 083: 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":58155,"stop_reason":"end_turn","session_id":"9c6b284b-2f4a-4b58-9146-5c0ef14e3bd5","total_cost_usd":0.01022523,"usage":{"input_tokens":2,"cache_creation_input_tokens":14980,"cache_read_input_tokens":2153,"output_tokens":14415,"output_tokens_details":{"thinking_tokens":12066},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14980,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14415,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14980,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14980},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14415,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14980,"webSearchRequests":0,"costUSD":0.01022523,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12066,"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's toolchain is graded as one assembled whole, whichever parts (detectors, runners, and the routing, listing, record and resolution around them) supply each mechanism.\n- Every detector the toolchain routes a defence through must conform to the detector specification, with wrapping allowed. Every identifier a blocking rule can print must resolve offline to documentation on disk, including the project's own rules.\n- Suppression routes that bypass the project record, such as inline ignores and silent baselines, must be disabled or made to fail a blocking defence.\n- The entry point runs detectors before runners and stops on a detector failure. It runs locally, can be limited to one file, and prints identifiers unaltered.\n- Active defences and the project record can be listed without running anything. The listing is derived from the configuration and includes the project's own rules.\n- Exceptions live in a location the toolchain reads. Each needs a written justification that names the hazard and scope, and generic justifications are rejected.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The third-party detector, the first-party package and the project rules are parts of it, and each part is evidence for that grade rather than a grade of its own. The document says: \"Those parts may be third-party, first-party or project-level, in any combination.\" It also says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** The project has two grades, a project grade and an artefact grade, and one does not imply the other. The document says: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" It also says: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic routes the `zq.*` and `proj.*` defences, and its two undocumented bundled rules cannot be resolved by it. The clause's own table marks \"Nothing for those two\" as \"Fails\", and neither zig-qa nor the project supplies documentation for them. |\n| 4.2 | No | Two enabled bundled identifiers do not resolve to on-disk documentation, and \"One [Identifier] that does not resolve fails this clause, however many others do.\" |\n| 4.3 | Yes | The only described route is the inline `// lintomatic-ignore` comment, and `ignore_comments = false` disables it. The fixture describes no other route. |\n| 4.4 | Yes | `zig-qa run` runs locally, `zig-qa run <path>` limits it to a directory or file, and it prints Lintomatic's output unchanged, one line per finding. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic before the test suite and stops when Lintomatic fails, and CI runs this same command. |\n| 5.1 | Yes | `zig-qa list` prints each active rule with its identifier, a one-line summary and a documentation path, and it reads `lintomatic.toml` without running anything. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, the configuration the toolchain loads. The fixture describes nothing hand-maintained. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list` with their documentation paths, alongside the bundled and `zq.*` rules. |\n| 6.1 | Partial | `quality-exceptions.toml` is a defined location that `zig-qa run` loads. Calibrations and conventions are also part of the record under the terminology, and the fixture says nothing about where they live or whether they are read. |\n| 6.2 | No | The only check is that `reason` is non-empty, which the clause says does not satisfy it. No check requires the hazard or scope to be named, and no check rejects generic justifications. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the entries in the same format as the rule listing. |\n\n**Assumptions I made:**\n- The fixture does not say whether the two undocumented Lintomatic rules are blocking. I treated them as blocking, because `zig-qa run` stops when Lintomatic fails and they are enabled.\n- `DETECTOR-SPEC.md` was not supplied. For 4.1 I judged only on the restated sentences inside clause 4.1 itself. One failing restated requirement is enough for the No.\n- The fixture describes only one suppression route for Lintomatic, so 4.3 is Yes on what is written.\n\n**Conformance (section 9): No.** The project fails 4.1, 4.2 and 6.2 and is only partial on 6.1. A toolchain that satisfies most of the document is not Conforming, and this one is not described as Conforming here.\n\n**Conformance with agent support: No.** The toolchain does not conform, and it also lacks both section 7 items, since there is no agent summary (7.1) and no `AGENTS.md` or equivalent delivery (7.2).\n\n**Section 8: Does not apply.** Section 8 bears only on the artefact grade under 9.1. Zigpipe \"does not ship any tooling to other projects\", so it has no artefact. The document says: \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" The company's zig-qa package would be graded on its own artefact grade, and that is outside this verdict.\n\n**Declaration: No effect on the verdict.** Section 9.2 says: \"The declaration is optional\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The verdict above rests on the clauses, not on any declaration. Zigpipe has none, which is a separate matter from grading.\n\n## 4. Confusion\n\n- Clause 4.1 says: \"Where it has not, the sentences that follow are the test.\" It also says: \"this clause holds the [Detector] to every one of them.\" On my reading I could not tell whether the restated sentences are the full test or only a sample of sections 4 to 7.\n- Section 2 says: \"a [Blocking] [Rule] whose documentation is missing is not yet a [Defence].\" Clause 5.1 requires the listing of \"every [Defence]\". I was unsure whether the two undocumented rules fall under 5.1's listing requirement at all.\n- Clause 6.2 says the toolchain must reject a justification that \"could be pasted onto any [Exception] unchanged, by a check it documents: 'needed for now', 'legacy', 'TODO' and their like.\" The test in the first half is about pasteability, and the examples given are phrases that a check could match. On my reading I could not tell which of these the check is meant to test.","ttft_ms":50446,"type":"result","duration_ms":58756,"uuid":"8984baf1-be49-4486-9742-a0a619a31352","ttft_stream_ms":1305,"time_to_request_ms":597,"first_content_frame_ms":1305,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":60848,"stop_reason":"end_turn","session_id":"5660637b-012d-42c8-a838-7221707b5aa4","total_cost_usd":0.01038073,"usage":{"input_tokens":2,"cache_creation_input_tokens":14980,"cache_read_input_tokens":2153,"output_tokens":14726,"output_tokens_details":{"thinking_tokens":12660},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14980,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14726,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14980,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14980},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14726,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14980,"webSearchRequests":0,"costUSD":0.01038073,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12660,"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's toolchain, meaning all the parts it assembles to run checks (detectors, runners, and the parts that route, list, record and resolve), is graded as one whole at project level.\n- Each detector it routes a defence through must meet the detector specification, with any wrapping counted as part of the detector.\n- Every blocking rule the toolchain runs must resolve its identifier to on-disk documentation offline, and the toolchain must block inline or silent suppression routes that bypass the project record.\n- The toolchain's entry point must report every identifier unaltered, run detectors before runners, and stop on a detector failure.\n- The toolchain must list every active defence, including the project's own, from the live configuration without running them, and must list the project record the same way.\n- The toolchain must define and read the project record, and must reject exceptions whose justification is generic or missing.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at project level, and the toolchain is everything the project assembles to run its checks through. \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" Also: \"[Conformance] is a property of the assembled whole.\"\n\n**2b.** One grade. The third-party detector, first-party package and project rules are evidence for that grade, not grades in their own right. \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" A second grade arises only for an artefact the project ships, and Zigpipe ships none.\n\n**2c.** Two grades. The project grade applies to every project, and the artefact grade applies because the company ships the package. Neither implies the other. \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nZigpipe's blocking-rule status is not stated in the fixture. I have treated the two undocumented Lintomatic rules as blocking, because the fixture says `zig-qa run` \"stops when Lintomatic fails.\"\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic meets most of the detector specification as described, but two of its bundled rules have no documentation, and nothing in zig-qa or the project supplies it. The wrapping adds nothing for those two, so the detector fails its offline-resolution requirement. |\n| 4.2 | No | Two enabled bundled rules print identifiers that resolve to nothing, and `zig-qa list` shows `(none)` for them. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" The other 38 bundled rules resolve via `lintomatic explain`, and the `zq.*` and `proj.*` docs are on disk. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline route. The only other exception route is `quality-exceptions.toml`, which `zig-qa run` loads, so it is the project record. The fixture describes no baseline or other route, so this grade covers only what is written. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts `<path>` for a subset, prints Lintomatic's output unchanged, and is the command CI runs. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic before the test suite and stops when Lintomatic fails. |\n| 5.1 | Partial | `zig-qa list` reads the config without running anything and prints identifier, one-line summary and documentation path. For the two undocumented rules the route is `(none)`, so there is no route to their documentation. The gap is the same one as in 4.2. |\n| 5.2 | Yes | The listing is produced by reading `lintomatic.toml`, so it is derived from the active configuration. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, each with a documentation path under `docs/defences/`. |\n| 6.1 | Yes | `zig-qa run` and `zig-qa list --exceptions` both load `quality-exceptions.toml` themselves. |\n| 6.2 | No | The only check is that `reason` is non-empty, and the clause says \"A field that is merely present and non-empty does not satisfy this clause.\" There is no check for generic phrases and no check that the reason names a hazard and scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` uses the same format and command family as the rule listing. |\n\n**Conformance under section 9:** Zigpipe does **not** conform. Clauses 4.1, 4.2 and 6.2 fail outright, and 5.1 is only partial. Under section 9, \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support:** No. The project does not conform at all, and it does none of what section 7 recommends: no generated summary (7.1) and no delivery into an agent file such as `AGENTS.md` (7.2).\n\n**Section 8:** Does not apply to Zigpipe's verdict. Section 8 bears on the artefact grade only, and Zigpipe \"does not ship any tooling to other projects.\" The company's zig-qa package would be graded separately as an artefact, if it were graded at all.\n\n**Declaration:** The absence does not affect the verdict. Section 9.2 says \"The declaration is optional,\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The verdict above rests on the evidence in the fixture.\n\n## 4. Confusion\n\n- **Clause 6.2:** \"It MUST NOT supply a default, and MUST reject an [Exception] that omits one.\"\n- **Clause 6.4:** \"Where the method specification delegates a judgement and the project has recorded nothing, a documented [Toolchain] default is what the [Practitioner] falls back to.\"\n\nOn my reading, it is unclear whether a justification for an exception counts as a delegated judgement that 6.4 lets a default fill, or whether 6.2's ban on defaults covers that case as well.","ttft_ms":53735,"type":"result","duration_ms":61466,"uuid":"826feba8-ae35-4c30-922c-5e9c97f82bfe","ttft_stream_ms":1324,"time_to_request_ms":615,"first_content_frame_ms":1325,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":60232,"stop_reason":"end_turn","session_id":"b2876838-843e-42db-b62a-0fd17258075c","total_cost_usd":0.01029133,"usage":{"input_tokens":2,"cache_creation_input_tokens":14978,"cache_read_input_tokens":2153,"output_tokens":14548,"output_tokens_details":{"thinking_tokens":12396},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14978,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14548,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14978,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14978},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14548,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14978,"webSearchRequests":0,"costUSD":0.01029133,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12396,"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- Conformance is judged on the whole toolchain a project assembles, whatever mix of third-party, first-party and project-written parts runs its checks.\n- Every detector the toolchain routes a defence through must conform to the detector specification, and every blocking rule's identifier must resolve to documentation on disk, offline.\n- Inline suppression routes that bypass the project record must be disabled or made to fail a blocking defence, and exceptions must be recorded in the project record.\n- The entry point runs detectors before runners, stops on a detector failure, and can run locally on a subset down to one file, printing identifiers unaltered.\n- The toolchain must list active defences and the project record from its live configuration without running anything, including the project's own defences. It must read the record itself and reject exceptions whose justification is generic.\n- Shipped toolchains must check their own documentation at release and run their bundled rules on their own source. Agent-facing summaries are SHOULDs.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one project-level grade. The individual parts are evidence for that grade and do not get grades of their own.\n> \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** The company's project has two grades, one for the project and one for the shipped artefact. Neither implies the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n> \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nZigpipe ships no tooling, so only its project grade applies. The verdicts below rest on the fixture. The detector specification was not provided, so the detector-level checks in 4.1 rely on the restated sentences in the clause.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic meets the restated tests except offline resolution, and two of its bundled rules have no documentation. Nothing wraps them, so the table's \"Fails\" row applies. |\n| 4.2 | No | `zig-qa list` shows `(none)` for two enabled identifiers, and no documentation is supplied for them. One unresolved identifier fails the clause. (See the caveat below.) |\n| 4.3 | Yes | `ignore_comments = false` disables the inline route, and exceptions are directed to `quality-exceptions.toml`. I took the fixture's listed routes as the only ones. |\n| 4.4 | Yes | `zig-qa run` works locally, accepts `<path>`, and prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first, then the test suite, and stops if Lintomatic fails. CI runs this same script. |\n| 5.1 | Yes | `zig-qa list` reads the config and prints identifier, summary and doc path without running any rule. The two undocumented rules are not Defences under section 2, so this clause is not failed by them. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, the configuration the run loads. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, alongside the bundled `zq.*` rules. |\n| 6.1 | Partial | `quality-exceptions.toml` is a defined location that the toolchain reads. Section 2 includes calibrations and conventions in the project record, and the fixture defines no location for them. If `lintomatic.toml` is read as the calibration location, this becomes Yes, but the fixture does not say that. |\n| 6.2 | No | The only check is that `reason` is non-empty, and the clause says a non-empty field does not satisfy it. Nothing requires the hazard or the scope, and nothing rejects generic text. |\n| 6.3 | Yes | `zig-qa list --exceptions` is a flag on the same script and prints in the same format as the rule listing. |\n\n**Conformance (section 9):** No. Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is partial. Partial conformance may not be described as conformance, so Zigpipe's toolchain does not conform.\n\n**Conformance with agent support:** No. It does not conform at all, and the fixture says there is no defence summary and no `AGENTS.md`, so neither 7.1 nor 7.2 is met.\n\n**Section 8:** It does not apply to Zigpipe's grade. Zigpipe ships no tooling to other projects, and the fixture says the company, not Zigpipe, publishes `zig-qa`. Any artefact grade for `zig-qa` falls under section 8, but the fixture does not describe that repository, so I have not graded it.\n\n**Declaration:** The absence of a declaration does not affect the verdict. Section 9.2 says the declaration is optional and that a verdict rests on the evidence, not on the claim. The gaps above stand regardless.\n\n**Caveat on 4.2:** The fixture does not say whether the two undocumented rules are Blocking. I read them as Blocking because they are enabled and `zig-qa run` stops when Lintomatic fails. If they are warnings, 4.2 would not reach them, but 4.1 would still fail because the restated test covers all blocking identifiers.\n\n## 4. Confusion\n\n- **6.2 and 6.4, on \"default\":** Clause 6.2 says \"It MUST NOT supply a default, and MUST reject an [Exception] that omits one.\" Clause 6.4 says \"The [Toolchain] SHOULD state its own defaults for anything the method leaves to the project.\" The two use the word in apparently opposite directions, and I could only settle it by reading them as covering different things.\n- **9.1 and 9.2, on the declaration:** Clause 9.1 says \"The two verdicts MUST be graded and declared separately.\" Clause 9.2 says \"The declaration is optional.\" On my reading, 9.1 seems to require a declaration that 9.2 says is optional.","ttft_ms":52856,"type":"result","duration_ms":60689,"uuid":"b01e3fff-2b58-4002-8ecd-cb0b3bcc3646","ttft_stream_ms":1249,"time_to_request_ms":458,"first_content_frame_ms":1250,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":57338,"stop_reason":"end_turn","session_id":"5e05105c-1400-4e54-b452-1bbde5b9567a","total_cost_usd":0.00993353,"usage":{"input_tokens":2,"cache_creation_input_tokens":14979,"cache_read_input_tokens":2153,"output_tokens":13832,"output_tokens_details":{"thinking_tokens":11793},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14979,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13832,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14979,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14979},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13832,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14979,"webSearchRequests":0,"costUSD":0.00993353,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11793,"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's toolchain is measured as one assembled whole, whatever parts it comes from.\n- Every detector a defence is routed through must conform to the detector specification, with wrapping allowed.\n- Every identifier a blocking rule can print must resolve to documentation on disk, offline, with the correct fix stated.\n- Every suppression route that bypasses the project record must be disabled or made to fail a blocking defence.\n- The toolchain's entry point must run detectors before runners, stop on a detector failure, and list active defences from the live config, including the project's own.\n- The project record must live at a path the toolchain reads, and its exceptions need specific justifications.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks. \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade, not grades of their own. \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** The project has two grades, one for the project and one for the artefact it ships, and neither implies the other. \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic is the only detector Zigpipe routes defences through, and it cannot resolve two of its bundled identifiers. The wrapping table says that when a detector has no documentation for two bundled rules and nothing is added for them, the clause \"Fails\". |\n| 4.2 | No | Two enabled bundled rules print identifiers that resolve to nothing; `zig-qa list` shows `(none)`, and neither the project nor zig-qa provides documentation for them. I am assuming the enabled rules are blocking, since `zig-qa run` stops when Lintomatic fails. The fixture does not state it directly. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline `// lintomatic-ignore` route, and exceptions go to `quality-exceptions.toml`. The fixture describes no baseline or other bypass route. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, `zig-qa run <path>` limits it to one file, and it prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the tests, and stops when Lintomatic fails. CI runs it. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints identifiers, one-line summaries and documentation paths without running any rule. The two `(none)` entries are not Defences under section 2, so I read this clause as not reaching them. Clause 4.2 does. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, which the toolchain loads. |\n| 5.3 | Yes | The four `proj.*` rules are documented and appear in `zig-qa list`. The `zq.*` rules belong to zig-qa, not to the project, so they are not covered here. |\n| 6.1 | Partial | `quality-exceptions.toml` is a defined location, and `zig-qa run` loads it. Section 2 defines the project record to include calibrations and conventions too, and the fixture names no location or loader for either. |\n| 6.2 | No | The toolchain checks only that `reason` is non-empty. Clause 6.2 says \"A field that is merely present and non-empty does not satisfy this clause\", and nothing in the fixture checks for generic justifications or for a named hazard and scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` uses the same script and the same output format as the rule listing. |\n\n**Section 9 conformance:** No. Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is only partial. A toolchain that satisfies most of the document is not conforming, and Zigpipe should not be described as conforming.\n\n**Conformance with agent support:** No. It does not conform, and it has no agent summary (7.1) and no delivery into `AGENTS.md` or an equivalent (7.2).\n\n**Section 8:** It does not apply. Section 8 bears only on the artefact grade. Zigpipe ships no tooling to other projects, so it has a single project grade. The zig-qa package is published by the company, but that is a different artefact, and this fixture does not describe its own grade.\n\n**Declaration:** The absence has no effect on the verdict. Clause 9.2 says \"The declaration is optional\", and a verdict \"rests on that exercise and not on the claim.\" The absence of a declaration does not change any MUST that failed above.\n\n## 4. Confusion\n\n- **Section 2 and clause 5.1.** Section 2 says \"a [Blocking] [Rule] whose documentation is missing is not yet a [Defence]\", while clause 5.1 says \"The [Toolchain] MUST list every [Defence] active in the project.\" I could not tell whether undocumented blocking rules fall under 5.1's listing duty. I graded 5.1 on the reading that they do not.\n- **Section 2, \"Consuming project\" and \"Bundled defence\".** The definition says a consuming project is \"A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else\", and the fixture describes zig-qa as a first-party package the company publishes. I could not tell whether Zigpipe's `zq.*` rules count as bundled defences.\n- **Clause 6.1, \"MUST define a location for the project record\".** The singular \"a location\" sits against section 2's definition, which covers calibrations, exceptions and conventions together. I could not tell whether one location is required for all three.","ttft_ms":50703,"type":"result","duration_ms":57795,"uuid":"92aa59b0-0d59-4e36-b16e-382d1d32b705","ttft_stream_ms":1327,"time_to_request_ms":453,"first_content_frame_ms":1328,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":57773,"stop_reason":"end_turn","session_id":"f4f0846e-520b-46ef-ba0a-64b2c87c4c70","total_cost_usd":0.00996473,"usage":{"input_tokens":2,"cache_creation_input_tokens":14980,"cache_read_input_tokens":2153,"output_tokens":13894,"output_tokens_details":{"thinking_tokens":11668},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14980,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13894,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14980,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14980},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13894,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14980,"webSearchRequests":0,"costUSD":0.00996473,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11668,"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's toolchain is judged as a whole, whatever mix of third-party, first-party and project-written parts it assembles to run its checks.\n- Every defence must run through detectors that meet the detector specification. Every identifier a blocking rule can print must resolve offline from documentation on disk.\n- Inline suppression routes that bypass the project record must be disabled or made to fail the run. Irreducible cases go to the project record.\n- The toolchain's own entry point must run detectors before runners, stop on a detector failure, and show every finding and identifier locally, including on a single file.\n- The toolchain must list active defences without running them, derived from its live configuration and including the project's own, and the project record must be enumerable the same way.\n- The project record must have a location the toolchain reads, and every exception needs a written justification that names the hazard and scope and is not generic. Shipped artefacts get a separate grade, and the self-audit in section 8 applies only to them.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through: its detectors and runners, plus the parts that route, list, record and resolve.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade, not grades of their own.\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n>\n> \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** Two grades. The project grade is the one the company's Zig projects receive as projects. The artefact grade is the one the package receives as something shipped to consumers. Neither implies the other.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nI graded the clauses from the text of the toolchain document and the fixture alone. I did not have the detector specification, so 4.1 and 4.4 are checked against the restatements the toolchain document gives.\n\n| Clause | Grade | Reasoning |\n| --- | --- | --- |\n| 4.1 | No | Lintomatic's two undocumented bundled rules fail the wrapped pair. The table in 4.1 says \"Two [Bundled rules] have no documentation \\| Nothing for those two \\| Fails\", and the fixture says nothing in the project or zig-qa documents them. |\n| 4.2 | No | The same two enabled rules print identifiers that resolve to nothing, and `zig-qa list` shows their path as `(none)`. The fixture does not say whether they are warnings. I have treated them as blocking, since §2 says a blocking rule with no documentation is caught by 4.2. The other identifiers resolve. |\n| 4.3 | Partial | The inline ignore route is closed by `ignore_comments = false`, and exceptions go to `quality-exceptions.toml`. The fixture does not say whether Lintomatic has any other route, such as a silent baseline, so I cannot confirm the clause covers every route. |\n| 4.4 | Yes | `zig-qa run` prints Lintomatic's output unchanged, runs locally with no service, and accepts `<path>` down to a single file. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the tests, and \"stops when Lintomatic fails\". CI runs these same scripts. |\n| 5.1 | Partial | `zig-qa list` names every active rule with identifier, summary and path, and runs nothing. But two active rules have the route `(none)`, and 5.1 requires a route to each one's documentation. If §2 means those two are not yet Defences, the Defence listing is complete, and the grade turns on that reading. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, the configuration the toolchain loads. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules alongside the bundled `zq.*` and Lintomatic rules. |\n| 6.1 | Partial | `quality-exceptions.toml` is a defined location, and `zig-qa run` loads it. The project record also holds calibrations and conventions, and the fixture describes no location for those. |\n| 6.2 | No | The only check is that `reason` is non-empty, and §6.2 says \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing rejects generic text such as \"TODO\" or \"legacy\". |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record \"in the same format as the rule listing\". |\n\n**Overall conformance (section 9):** No. 4.1, 4.2 and 6.2 fail, and 4.3, 5.1 and 6.1 are partial, so the toolchain does not conform. Partial conformance may not be described as conformance.\n\n**Conformance with agent support:** No. It is not conforming, and it misses the section 7 SHOULDs. The fixture says there is no agent summary and no `AGENTS.md`, and neither 7.1 nor 7.2 is met.\n\n**Section 8:** It does not apply to Zigpipe's project grade. The fixture says Zigpipe \"does not ship any tooling to other projects\", and §9 says section 8 \"bears on the artefact grade of clause 9.1 and not on this project grade\". `zig-qa` is a company package, so its artefact grade would be a separate grading, and section 8 would apply there. I have not graded it.\n\n**Does the missing declaration affect the verdict?** No. §9.2 says \"The declaration is optional\", and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The verdict above comes from the clauses alone.\n\n## 4. Confusion\n\n- **§2, \"Defence\" and blocking rules:** \"Throughout this document, a [Blocking] [Rule] whose documentation is missing is not yet a [Defence]. Clauses 4.2 and 8.1 exist to catch it, so where they reach a [Toolchain]'s [Rules] they reach every [Blocking] [Rule] it runs, documented or not.\"\n- **§5.1, the listing:** \"The [Toolchain] MUST list every [Defence] active in the project without running it.\" Read with §2, I could not tell whether an undocumented blocking rule falls within this listing duty. That is why 5.1 is marked Partial.","ttft_ms":50130,"type":"result","duration_ms":58230,"uuid":"6d3a9a75-1e30-40b5-ad0a-2a2a1c9003db","ttft_stream_ms":1618,"time_to_request_ms":488,"first_content_frame_ms":1619,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 083: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone, on the
evidence a project shows. Where a clause rests on the [detector specification](DETECTOR-SPEC.md),
as clauses 4.1, 4.2 and 4.4 do, it restates what the grader checks, and a verdict the [Detector]
already holds under that document's section 8 counts too. The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

Throughout this document, a [Blocking] [Rule] whose documentation is missing is not yet a
[Defence]. Clauses 4.2 and 8.1 exist to catch it, so where they reach a [Toolchain]'s [Rules]
they reach every [Blocking] [Rule] it runs, documented or not.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them. A grader of this
clause checks the sentences that follow, which restate the ones most often failed. Where the
[Detector] has already been graded against that document, under its section 8, that verdict
counts too: a [Detector] found not to [Conform] fails this clause whether or not the sentences
that follow show why. Where it has not, the sentences that follow are the test. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. A [Detector] that fails any
one of them, after wrapping, fails this clause. Three points govern how that is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. That is every [Blocking] [Rule] the [Toolchain] runs, the project's
own and the bundled alike. One [Identifier] that does not resolve fails this clause, however
many others do.

The resolving mechanism is keyed on the [Identifier] exactly as printed. Those
[Remediation docs] MUST ship with the project, with the [Toolchain] or with the [Detector]
whose [Rule] they document, at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open: that
document holds a [Detector] to on-disk resolution of its own [Bundled rules] and no further,
because it cannot know a project's documentation, and this clause reaches the project's own
[Rules] as well. An [Identifier] a third-party [Detector] resolves under that document's clause
6 meets this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.

[LTSCommerce]

Run 084: 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/toolchain-contradictions`). The readers read commit c2e3249. 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 a095fa7, named here before the readers started), acceptance/runs/README.md, acceptance/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/083-toolchain-contradictions-run-11.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 084. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 83 in section 2's closing paragraph alone: it now says that nothing this document asks of defences, clause 5.1's listing included, is asked of a blocking rule whose documentation is missing, and that a toolchain running one has failed clause 4.2 whether or not its listing shows it. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 12 (runs 57, 58, 62, 65, 67, 68, 72, 76, 81, 82 and 83 came before). Record file to write: <worktree>/acceptance/runs/084-toolchain-contradictions-run-12.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 eb3d2cc18c08b54960dd96080fcac5066e04ef556aaa983194c13e79bef930dc, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at c2e3249, 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 c2e3249 -- TOOLING-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, a paragraph the change parts from what it refers to, 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 a095fa7, 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 084: 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":50579,"stop_reason":"end_turn","session_id":"5094c795-0469-4f32-805a-a491020c43ba","total_cost_usd":0.00904763,"usage":{"input_tokens":2,"cache_creation_input_tokens":15052,"cache_read_input_tokens":2153,"output_tokens":12031,"output_tokens_details":{"thinking_tokens":9757},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15052,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":12031,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15052,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15052},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":12031,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15052,"webSearchRequests":0,"costUSD":0.00904763,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":9757,"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- Judge a project's toolchain as one assembled whole, whichever parts (third-party, first-party or project-level) supply each mechanism.\n- Route each Defence only through Detectors that meet the detector specification, with any wrapping counted as part of that Detector, and make every Blocking rule's identifier resolve to documentation on disk, offline.\n- Forbid inline ignores, silent baselines and other suppression routes that bypass the project record, and run Detectors before Runners so that a Detector failure stops the run.\n- Give the entry point local runs down to a single file, with the Detectors' identifiers printed unaltered.\n- Produce a listing of active Defences, derived from the loaded configuration and including the project's own, that can be generated without running them.\n- Define a project record location that the toolchain reads, reject exceptions whose justifications are missing or generic, and make the record enumerable the same way as the Defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks through, meaning its Detectors, Runners, and the parts that route, list, record and resolve.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one project-level grade under section 9. The individual parts are evidence for that grade and do not get grades of their own.\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n> \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** The company's project has two grades, because it ships an artefact. The project grade is one, and the artefact grade is the other. One does not imply the other.\n\n> \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application\n\nZigpipe ships no tooling, so section 8 does not bear on its project grade. I graded the clauses from the fixture's description. For clauses 4.1 and 4.4 the detector specification is cited, but I was not given it, so I judged only the restated sentences in clauses 4.1 and 4.4 and the fixture's description of what the tools do.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic meets the restated tests: it hosts bespoke rules, runs a single rule on a single file, prints stable identifiers, runs locally, and has its ignore comment disabled. It fails the offline resolution test for its two undocumented bundled rules, and zig-qa supplies nothing for them, so the wrapped pair fails under the table's \"Two Bundled rules have no documentation / Nothing for those two / Fails\" row. One failing gap is enough, so this verdict does not depend on what I could not check in the detector specification. |\n| 4.2 | No | Two Blocking bundled rules are enabled and print identifiers that resolve to no documentation (`zig-qa list` shows `(none)`). The clause says one unresolved identifier fails it, however many others resolve. |\n| 4.3 | Yes | `ignore_comments = false` disables the only suppression route the fixture describes. Exceptions go through `quality-exceptions.toml`, which is the project record. The fixture mentions no other route, and the clause owes nothing for a route the Detector does not have. |\n| 4.4 | Yes | `zig-qa run` is local and needs no service. `zig-qa run <path>` runs on a directory or a single file. It prints Lintomatic's output unchanged. I could not check the detector specification's clauses 5.1 to 5.4 directly. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs it. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints each active rule with its identifier, a one-line summary and its documentation path, without running them. The two undocumented rules are shown as `(none)`, but they are not Defences under section 2, so this clause does not reach them. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, which is the configuration the run loads. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, with their documentation paths. |\n| 6.1 | Yes | The location is `quality-exceptions.toml`, and `zig-qa run` loads it. |\n| 6.2 | No | The toolchain checks only that `reason` is non-empty. The clause says a non-empty field does not satisfy it. There is no check that the justification names a hazard and a scope, and no rejection of generic phrasing such as \"needed for now\", \"legacy\" or \"TODO\". |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing, through the same tool. |\n\n**Section 9 (conformance):** Zigpipe does not conform. Clauses 4.1, 4.2 and 6.2 fail. Section 9 says partial conformance must not be described as conformance, and the fixture shows a substantial but incomplete toolchain.\n\n**Conformance with agent support:** No. Section 9 requires conformance first, and the project also does neither of what section 7 recommends: it publishes no summary for agents (7.1) and has no `AGENTS.md` or equivalent delivery (7.2).\n\n**Section 8:** Does not apply to Zigpipe. Section 8 bears only on the artefact grade, and Zigpipe ships no tooling. The zig-qa package, published by the company, has its own artefact grade, which is separate from Zigpipe's.\n\n**Absence of a declaration:** It does not affect the verdict. Section 9.2 makes the declaration optional. A verdict on any toolchain rests on the exercise of the clauses, not on the claim. The gap-recording duty applies only to a project that has a declaration. Gaps a practitioner finds should still be recorded under method clause 3.2 whether or not a declaration exists, but the missing declaration does not change this grade.\n\n## 4. Confusion\n\n- **6.2 and 6.4:** Clause 6.2 says the toolchain \"MUST NOT supply a default\" for an exception's justification. Clause 6.4 says the toolchain \"SHOULD state its own defaults for anything the method leaves to the project\", and exceptions are among the project-record judgements listed in section 2 under \"Project record\". I could not tell whether a default for an exception justification is barred by 6.2 or invited by 6.4.","ttft_ms":42915,"type":"result","duration_ms":51302,"uuid":"3ee38ead-52b8-4dec-9eea-dfaf170aa7ae","ttft_stream_ms":1444,"time_to_request_ms":722,"first_content_frame_ms":1445,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":68325,"stop_reason":"end_turn","session_id":"37bdab44-a432-4da4-bca1-478c843b9a40","total_cost_usd":0.01144553,"usage":{"input_tokens":2,"cache_creation_input_tokens":15049,"cache_read_input_tokens":2153,"output_tokens":16828,"output_tokens_details":{"thinking_tokens":14871},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15049,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":16828,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15049,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15049},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":16828,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15049,"webSearchRequests":0,"costUSD":0.01144553,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":14871,"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's toolchain is the whole assembly it runs its checks through, and conformance is judged on that assembly as one grade, whatever mix of third-party, first-party and project parts it uses.\n- Every defence must run through a detector that meets the detector specification, with wrapping allowed to add missing mechanisms but not to excuse gaps.\n- Every identifier that a blocking rule can print must resolve to on-disk documentation, offline, from the installed copy, and that documentation must state the correct construction.\n- Suppression routes that bypass the project record must be disabled or made to fail a blocking defence, and every exception needs a written justification that names the hazard and scope and is not generic.\n- The entry point must run detectors before runners, stop on a detector failure, and print detector output and identifiers unchanged.\n- The toolchain must list active defences and the project record without running them, derive that listing from the active configuration, and include the project's own defences. The summary for agents and its delivery are SHOULDs.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through, which includes detectors, runners, and the parts that route, list, record and resolve.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one conformance grade. The individual parts are evidence for that grade and do not receive grades of their own.\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n> \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** The project has two grades if it ships the package, and neither implies the other. The project grade applies to every project. The artefact grade applies only where the project ships something. Publishing the package and using it on its own repository means the repository's project grade and the package's artefact grade are separate verdicts.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n> \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nThe detector specification was not supplied, so I graded 4.1 and 4.4 from the restatements in the clauses themselves. I took the two bundled Lintomatic rules to be blocking, since the fixture says they are enabled but does not say whether they are blocking.\n\n- **4.1: No.** Lintomatic is the detector routed through, and two of its bundled rules have no documentation. Nothing in the project or zig-qa covers them, so wrapping adds nothing for those two.\n- **4.2: No.** Two enabled bundled identifiers do not resolve, and \"One [Identifier] that does not resolve fails this clause, however many others do.\" The `proj.*` docs in `docs/defences/` and the `zq.*` docs in `docs/rules/` are in place.\n- **4.3: Yes.** `ignore_comments = false` disables the only suppression route the fixture describes, and exceptions go through the project record.\n- **4.4: Yes.** `zig-qa run` works locally, accepts `<path>` for a single file, and prints Lintomatic's output unchanged, so the identifiers reach the practitioner.\n- **4.5: Yes.** `zig-qa run` runs Lintomatic first and stops when it fails, and CI runs the same script.\n- **5.1: Yes.** `zig-qa list` reads the config without running any rule and prints each rule's identifier, summary and documentation path. The two undocumented rules show `(none)`, but under section 2 they are not defences, so 5.1 does not require a route for them.\n- **5.2: Yes.** The listing is generated from `lintomatic.toml`, the same file Lintomatic loads, so a newly added rule appears on the next run.\n- **5.3: Yes.** The four `proj.*` rules appear in `zig-qa list` with their documentation paths.\n- **6.1: Yes.** `quality-exceptions.toml` is a defined location, and `zig-qa run` loads it. The fixture describes this file only for exceptions and says nothing about where calibrations or conventions live.\n- **6.2: No.** The only check is that `reason` is non-empty, and the clause says a field that is \"merely present and non-empty does not satisfy this clause.\" Nothing requires the hazard or scope to be named, and nothing rejects generic text.\n- **6.3: Yes.** `zig-qa list --exceptions` prints entries in the same format as the rule listing.\n\n**Conformance under section 9: No.** It fails 4.1, 4.2 and 6.2, and section 9 requires every MUST in sections 4 to 6 to hold.\n\n**Conformance with agent support: No.** It is not conforming, and it does not publish a summary (7.1) or deliver one into an agent file (7.2).\n\n**Section 8: does not apply.** Section 8 bears only on the artefact grade. Zigpipe \"does not ship any tooling to other projects,\" so it has no artefact. `zig-qa` is the company's package, and Zigpipe is a consuming project of it.\n\n**Declaration: no effect on the verdict.** Section 9.2 says a declaration \"is not a condition of conformance\" and is optional. The verdict rests on the exercise of the clauses, not on a claim.\n\n## 4. Confusion\n\nThe clause 4.1 test is unclear on one reading. The clause first says the sentences that follow are the test, then says the test is every MUST of the detector specification:\n\n> \"Where it has not, the sentences that follow are the test.\"\n\n> \"Does the [Detector] meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md), exercised as its clause 8.1 describes?\"","ttft_ms":61849,"type":"result","duration_ms":68881,"uuid":"aab607f4-1f08-4542-bdd6-d7510f1fe69b","ttft_stream_ms":1171,"time_to_request_ms":563,"first_content_frame_ms":1172,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":58576,"stop_reason":"end_turn","session_id":"1075d0fa-ad70-4d1f-bddc-2883de2ae573","total_cost_usd":0.010185429999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":15051,"cache_read_input_tokens":2153,"output_tokens":14307,"output_tokens_details":{"thinking_tokens":12264},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15051,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14307,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15051,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15051},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14307,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15051,"webSearchRequests":0,"costUSD":0.010185429999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12264,"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's toolchain is judged as one assembled whole, whoever wrote each part.\n- Every detector a defence is routed through must meet the detector specification, and every blocking rule's identifier must resolve offline to documentation on disk.\n- Inline or baseline suppression routes that bypass the project record must be disabled or made to fail a blocking defence.\n- The entry point must run detectors before runners and stop when a detector fails.\n- Active defences must be listable without running them, generated from the live configuration, with the project's own defences included.\n- The project record must live at a path the toolchain reads, every exception must carry a specific justification, and the record must be listable the same way as defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is everything the project assembles to run its checks. The document says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" It adds: \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n**2b.** One grade. The parts are evidence for it, not grades of their own. The document says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" It also says: \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** Two grades, one at project level and one at artefact level, and neither implies the other. The document says: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" It defines the levels as follows: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic has two bundled rules with no documentation, and nothing in the project or zig-qa supplies it, so the wrapped pair fails the resolution test in 4.1's table. I judged only the restated sentences, since the detector specification's section 8 verdict was not provided. |\n| 4.2 | No | The two undocumented bundled rules are enabled and print identifiers that resolve to nothing. The fixture does not say they are Blocking, but `zig-qa run` stops when Lintomatic fails, so I treated them as Blocking. One unresolved identifier fails the clause. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline route project-wide. The fixture describes no baseline or other suppression route, so nothing else is owed on what is written. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts `<path>` for a subset, prints Lintomatic's output unchanged, and is what CI runs. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs it. |\n| 5.1 | Yes | `zig-qa list` prints each rule's identifier, summary and documentation path without running anything. The two undocumented rules show `(none)`, but they are not Defences under section 2, so 5.1 does not reach them. 4.2 catches them. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml` directly, so the listing is generated from the loaded configuration. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, and their pages in `docs/defences/` say what the rule forbids, why, and what to write instead. |\n| 6.1 | Yes | The record is `quality-exceptions.toml`, a fixed path that `zig-qa run` loads itself. |\n| 6.2 | No | Only an empty `reason` is rejected. The clause says \"A field that is merely present and non-empty does not satisfy this clause.\" No check against generic phrases is described, and nothing requires the hazard and scope to be named. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing. |\n\n**Conformance under section 9:** No. Clauses 4.1, 4.2 and 6.2 fail, and section 9 says \"A project's [Toolchain] [Conforms] if every MUST in sections 4 to 6 holds\". Partial conformance is not conformance.\n\n**Conformance with agent support:** No. It is not conforming, and it does none of the section 7 items: it publishes no agent summary (7.1) and delivers none into the project (7.2), and there is no `AGENTS.md`.\n\n**Section 8:** Does not apply to Zigpipe. Section 8 \"bears on the artefact grade\" under 9.1, and Zigpipe \"does not ship any tooling to other projects.\" Section 8 would apply to zig-qa's artefact grade for the company, which is a separate grading subject and is not graded here.\n\n**Effect of the missing declaration:** None. Section 9.2 is headed \"The declaration is the claim and the known-gap record, not a condition of conformance,\" and it says \"The declaration is optional.\" The verdict is No because of the failed MUSTs, not because of the missing declaration. The 9.2 duty to record known gaps does not attach, since there is no declaration to record them in.\n\n## 4. Confusion\n\n- **4.1:** The clause says \"this clause holds the [Detector] to every one of them\" (every MUST of sections 4 to 7), but also \"A grader of this clause checks the sentences that follow\" and \"Where it has not, the sentences that follow are the test.\" On my reading I could not tell which of these sets the test, so I graded against the restated sentences.\n- **Section 2 (the paragraph beginning \"Throughout this document, a [Blocking] [Rule] whose documentation is missing\"):** It says such a rule is \"not yet a [Defence]\" and that \"clause 5.1's listing included\" is not asked of it. Read alongside 5.1's \"MUST list every [Defence] active,\" I could not tell whether the listing must show undocumented blocking rules at all. I read them as outside 5.1.","ttft_ms":52329,"type":"result","duration_ms":59082,"uuid":"492e2bbf-e09d-47c1-b4da-68b1135620b4","ttft_stream_ms":1129,"time_to_request_ms":507,"first_content_frame_ms":1130,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":65874,"stop_reason":"end_turn","session_id":"48929946-4da5-4511-8621-3e0cda6a9dde","total_cost_usd":0.01098963,"usage":{"input_tokens":2,"cache_creation_input_tokens":15052,"cache_read_input_tokens":2153,"output_tokens":15915,"output_tokens_details":{"thinking_tokens":13676},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15052,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":15915,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15052,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15052},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":15915,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15052,"webSearchRequests":0,"costUSD":0.01098963,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":13676,"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's toolchain is judged as the whole set of detectors, runners and routing, listing, recording and resolving parts it assembles, whoever wrote each part.\n- Every defence must run through a detector that conforms to the detector specification, or that is wrapped until it does. Every blocking rule's identifier must resolve to documentation on disk, offline.\n- Any suppression route that bypasses the project record must be disabled, or must make a blocking defence fail. Exceptions must be recorded in the project record.\n- The entry point runs detectors before runners and stops on a detector failure. Findings print locally, can be run on a single file, and keep their identifiers unaltered.\n- The toolchain must list active defences, including the project's own, from the live configuration without running them. It must list the project record the same way.\n- Exceptions need a specific written justification, and the toolchain must reject generic ones. A shipping artefact gets its own grade. A declaration is optional, and an agent summary is a SHOULD.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. Each part is evidence toward that grade, and where a part came from does not matter.\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n> \"[Conformance] is a property of the assembled whole.\"\n\nZigpipe ships nothing, so it has only the project grade. The zig-qa package is the company's shipped artefact, and it is graded on its own, not as part of Zigpipe's assembly.\n\n**2c.** The project has two grades, and neither implies the other.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n| --- | --- | --- |\n| 4.1 | No | Lintomatic's two undocumented bundled rules print identifiers that do not resolve offline. Nothing in the project or in zig-qa wraps them, so the wrapped pair fails the detector specification's resolution requirement. This is the table's \"Two Bundled rules have no documentation … Fails\" row. |\n| 4.2 | No | Two enabled Lintomatic rules show documentation path `(none)`, and nothing provides it. The fixture does not say those rules are Blocking. I read them as Blocking because `zig-qa run` stops when Lintomatic fails. Clause 4.1 fails regardless of that reading. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline route project-wide. No baseline route is described, and exceptions go to `quality-exceptions.toml`. The fixture describes only one suppression route, and it does not address disabling a rule in `lintomatic.toml`. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts `<path>` for a single file or directory, and prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs it. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints each rule's identifier, a one-line summary and its documentation path, without running anything. The two undocumented rules are not Defences under section 2, so 5.1 does not reach them. Their failure is recorded under 4.2. |\n| 5.2 | Yes | The listing is generated from the same `lintomatic.toml` that Lintomatic loads. |\n| 5.3 | Yes | The `proj.*` rules appear in `zig-qa list` alongside the bundled and `zq.*` rules. |\n| 6.1 | Partial | `zig-qa run` defines and loads `quality-exceptions.toml`. Section 2 defines the project record as also holding calibrations and conventions, and the fixture does not say where those are located. |\n| 6.2 | No | The only check is that `reason` is non-empty, which the clause says does not satisfy it. No hazard or scope requirement is described, and no generic-justification rejection is described. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries in the same format as the rule listing. |\n\n**Section 9 conformance:** No. Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is only partial. The document says partial conformance \"MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support:** No. It requires conformance first, and Zigpipe has no defence summary, no `AGENTS.md`, and no delivery mechanism for either (clauses 7.1 and 7.2).\n\n**Section 8:** Does not apply. Zigpipe ships no tooling to other projects, so it has no artefact grade, and section 8 bears only on artefact grades under clause 9.1. The zig-qa package would be graded under section 8 by its own publisher.\n\n**Absence of a declaration:** No effect on the verdict. Clause 9.2 says a declaration \"MAY\" be made, and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The gap-record duty applies only to a project that has a declaration. Gaps a practitioner finds are recorded under method clause 3.2 either way.\n\n## 4. Confusion\n\n- **Clause 4.3**: \"A route bypasses the [Project record] when a finding can be silenced through it without an entry appearing in the [Project record].\" Section 2 defines an [Exception] as \"a recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied.\" I could not tell whether disabling a whole rule in configuration counts as a suppression route under 4.3, since 4.3 speaks of silencing findings.\n- **Clause 6.1**: \"The [Toolchain] MUST define where the [Project record] lives and MUST load it.\" Section 2 defines the project record as holding \"[Calibrations], [Exceptions] and conventions.\" Clauses 6.2 and 6.3 speak only of exceptions, so I could not tell whether one location is required for all three.\n- **Clause 4.1**: \"exercised as its clause 8.1 describes.\" This refers to the detector specification, which I was not given. I relied on the restatement in 4.1 itself.","ttft_ms":58628,"type":"result","duration_ms":66373,"uuid":"b1c5b6a4-a6ef-4ecc-b927-61a2fde66595","ttft_stream_ms":1298,"time_to_request_ms":498,"first_content_frame_ms":1299,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":63172,"stop_reason":"end_turn","session_id":"55b5b782-ecfd-4615-9602-3d68ab368ad1","total_cost_usd":0.010554129999999998,"usage":{"input_tokens":2,"cache_creation_input_tokens":15052,"cache_read_input_tokens":2153,"output_tokens":15044,"output_tokens_details":{"thinking_tokens":12800},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":15052,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":15044,"cache_read_input_tokens":2153,"cache_creation_input_tokens":15052,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":15052},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":15044,"cacheReadInputTokens":2153,"cacheCreationInputTokens":15052,"webSearchRequests":0,"costUSD":0.010554129999999998,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12800,"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's toolchain, meaning its detectors, runners and the parts that route, list, record and resolve, is measured as one assembled whole.\n- Every defence must route through a detector that conforms to the detector specification, and every blocking rule's identifier must resolve to documentation on disk, offline.\n- The toolchain must disable or police inline and baseline suppression routes that bypass the project record, and must run detectors before runners and stop on a detector failure.\n- The entry point must run locally, on a subset down to one file, and print identifiers unaltered.\n- The toolchain must list active defences without running them, derived from the loaded configuration and including the project's own, and the project record must be a loaded file whose exceptions each carry a specific justification.\n- The project record must be enumerable the same way as the defences. A shipped toolchain also has an artefact grade, separate from the project grade.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks through. Quote: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** One grade. The parts are evidence for that grade, not grades of their own, and they may come from any source. Quotes: \"[Conformance] is a property of the assembled whole, because that is where it counts.\" \"Those parts may be third-party, first-party or project-level, in any combination.\" \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** Two grades: the project grade for the repository's assembled toolchain, and the artefact grade for the package it ships. One does not imply the other. Quote: \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application to Zigpipe\n\n**4.1 — No.** Lintomatic enables two bundled rules that have no documentation, so it fails the detector specification's offline-resolution requirement, and neither zig-qa nor the project supplies documentation for them, so wrapping does not cure it.\n\n**4.2 — No.** The two undocumented bundled rules print identifiers that resolve to `(none)`, and \"One [Identifier] that does not resolve fails this clause, however many others do.\" I have treated those rules as Blocking, which the fixture does not state outright. I inferred it because they are enabled and `zig-qa run` stops when Lintomatic fails. If they were warnings, this clause would not reach them.\n\n**4.3 — Yes.** The only route described, the inline `// lintomatic-ignore` comment, is disabled by `ignore_comments = false`, and exceptions go through the recorded file. The fixture does not describe any other Lintomatic suppression route, such as a baseline, so this verdict rests on what is written.\n\n**4.4 — Yes.** `zig-qa run` runs locally with no service, accepts `<path>` down to a single file, and prints Lintomatic's output unchanged, one line per finding, so the result appears in the command's own output.\n\n**4.5 — Yes.** `zig-qa run` runs Lintomatic first and \"stops when Lintomatic fails\", before the test suite.\n\n**5.1 — Yes.** `zig-qa list` prints each active rule's identifier, a one-line summary and a documentation path without running anything. The two `(none)` entries are not Defences under section 2, so this clause is not asked of them. Clause 4.2 is what catches them.\n\n**5.2 — Yes.** `zig-qa list` reads `lintomatic.toml`, the same configuration `zig-qa run` executes Lintomatic against, so the listing is derived rather than hand-maintained.\n\n**5.3 — Yes.** The four `proj.*` rules, with their pages in `docs/defences/`, appear in `zig-qa list` alongside the bundled `zq.*` defences.\n\n**6.1 — Yes.** `quality-exceptions.toml` is defined as the record's location and is loaded by `zig-qa run` before Lintomatic runs. The fixture mentions only exceptions, not calibrations or conventions, so this rests on the record as described.\n\n**6.2 — No.** The only check described is that `reason` is non-empty, and the clause states that \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing rejects generic justifications such as \"needed for now\", \"legacy\" or \"TODO\".\n\n**6.3 — Yes.** `zig-qa list --exceptions` prints the record in the same format as the rule listing, through the same tool.\n\n**Conformance under section 9 — No.** Clauses 4.1, 4.2 and 6.2 fail, and \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support — No.** That grade requires conformance first. The fixture also has no defence summary (7.1) and no delivery into the project (7.2), though those are SHOULDs and do not decide the question.\n\n**Section 8 — Does not apply.** Section 8 \"bears on the artefact grade only\", and Zigpipe \"does not ship any tooling to other projects\", so it has one grade and no artefact grade. The company's `zig-qa` package does ship, and its artefact grade would fall under section 8, but that is a separate grade and not Zigpipe's.\n\n**Declaration — No effect.** The declaration is optional, and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The three failures stand regardless. Without a declaration, no gap record is kept there, but the gaps are still recorded under method clause 3.2.\n\n## 4. Confusion\n\n- **Clause 4.1.** The clause first says \"A grader of this clause checks the sentences that follow\", which restate \"the ones most often failed\". It then says the clause holds the detector to \"every one of them\" (sections 4 to 7), and a later passage asks whether it meets \"every MUST of sections 4 to 7 … exercised as its clause 8.1 describes\". I could not tell which of these is the test.\n- **Clause 9.1 and 9.2.** Clause 9.1 says the two verdicts \"MUST be graded and declared separately\", but clause 9.2 says \"The declaration is optional\". I could not tell whether a shipping project is required to declare its two grades.\n- **Section 2, the paragraph on blocking rules without documentation.** The sentence \"where they reach a [Toolchain]'s [Rules] they reach every [Blocking] [Rule] it runs, documented or not\" leaves me unsure which clauses \"they\" refers to.","ttft_ms":55409,"type":"result","duration_ms":63641,"uuid":"5c23574f-0c2c-496c-ae80-659550239c87","ttft_stream_ms":1137,"time_to_request_ms":460,"first_content_frame_ms":1138,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 084: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone, on the
evidence a project shows. Where a clause rests on the [detector specification](DETECTOR-SPEC.md),
as clauses 4.1, 4.2 and 4.4 do, it restates what the grader checks, and a verdict the [Detector]
already holds under that document's section 8 counts too. The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

Throughout this document, a [Blocking] [Rule] whose documentation is missing is not yet a
[Defence], and nothing this document asks of [Defences], clause 5.1's listing included, is asked
of it. It is what clauses 4.2 and 8.1 exist to catch: where they reach a [Toolchain]'s [Rules]
they reach every [Blocking] [Rule] it runs, documented or not, and a [Toolchain] that runs such
a [Rule] has failed clause 4.2 whether or not its listing shows it.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them. A grader of this
clause checks the sentences that follow, which restate the ones most often failed. Where the
[Detector] has already been graded against that document, under its section 8, that verdict
counts too: a [Detector] found not to [Conform] fails this clause whether or not the sentences
that follow show why. Where it has not, the sentences that follow are the test. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. A [Detector] that fails any
one of them, after wrapping, fails this clause. Three points govern how that is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. That is every [Blocking] [Rule] the [Toolchain] runs, the project's
own and the bundled alike. One [Identifier] that does not resolve fails this clause, however
many others do.

The resolving mechanism is keyed on the [Identifier] exactly as printed. Those
[Remediation docs] MUST ship with the project, with the [Toolchain] or with the [Detector]
whose [Rule] they document, at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open: that
document holds a [Detector] to on-disk resolution of its own [Bundled rules] and no further,
because it cannot know a project's documentation, and this clause reaches the project's own
[Rules] as well. An [Identifier] a third-party [Detector] resolves under that document's clause
6 meets this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.

[LTSCommerce]

Run 085: 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/toolchain-contradictions`). The readers read commit 58924a8. 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 852dcd8, named here before the readers started), acceptance/runs/README.md, acceptance/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/084-toolchain-contradictions-run-12.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 085. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 84: clause 4.1's first paragraph now has one test, every MUST of the detector specification's sections 4 to 7, with the restated sentences as where a grader looks first and not the whole test, a grader without that document checking only them and saying so; section 1's "How to read this document" says the same; section 2's closing paragraph says in plain sentences that clause 5.1 does not require an undocumented blocking rule to be listed and that clauses 4.2 and 8.1 reach it. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 13 (runs 57, 58, 62, 65, 67, 68, 72, 76, 81, 82, 83 and 84 came before). Record file to write: <worktree>/acceptance/runs/085-toolchain-contradictions-run-13.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 6d37cc625287ae0258a845657c48a96b7a53c698d998d6cde43c5c9e064a53ea, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at 58924a8, 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 58924a8 -- TOOLING-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, a paragraph the change parts from what it refers to, 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 852dcd8, 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 085: 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":62994,"stop_reason":"end_turn","session_id":"02663f04-2a47-4401-9d05-1749c33be2ac","total_cost_usd":0.010562529999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":14974,"cache_read_input_tokens":2153,"output_tokens":15092,"output_tokens_details":{"thinking_tokens":12899},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14974,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":15092,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14974,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14974},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":15092,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14974,"webSearchRequests":0,"costUSD":0.010562529999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12899,"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":"# Answers to QUESTIONS.md\n\n## 1. Restatement\n\n- The project's assembled toolchain, whoever wrote each part, is what is graded.\n- Every defence must run through a detector that meets the detector specification. Every identifier a blocking rule can print must resolve offline to documentation on disk, and the toolchain must provide a place for that documentation.\n- Suppression routes that bypass the project record must be disabled or made to fail a blocking defence. The entry point must run detectors before runners and stop on a detector failure. Its output must be local, usable on a subset, and unaltered.\n- Active defences must be listable without running them. The listing must be derived from the loaded configuration and must include the project's own defences.\n- The project record must have a defined, loaded location. Every exception needs a justification naming its hazard and scope, and generic justifications must be rejected. The record must be enumerable the same way defences are.\n- Conformance is a single project-level grade over sections 4 to 6. A shipped artefact gets a second grade under section 8. The section 6.4 and section 7 items are SHOULDs, and the declaration is optional.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks: the detectors and runners, plus the parts that route, list, record and resolve.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve. Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade and do not earn separate grades.\n\n> \"Conformance is a property of the assembled whole, because that is where it counts\"\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** The project has two grades: a project grade and an artefact grade. Neither implies the other.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application to Zigpipe\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic is the routed detector. Two of its bundled rules have no documentation, and nothing in the project or in zig-qa supplies any. The 4.1 table marks that row \"Fails.\" I did not have the detector specification, so I graded only the restated points and say so here. |\n| 4.2 | No | The two undocumented bundled rules are enabled, so they are blocking. One identifier that does not resolve fails the clause. I took \"enabled\" to mean \"blocking\" because the fixture gives no non-blocking mode and `zig-qa run` stops when Lintomatic fails. The `zq.*` and `proj.*` pages and `lintomatic explain` appear to resolve. The fixture does not say whether the `zq.*` pages state the correct construction. |\n| 4.3 | Yes | `ignore_comments = false` disables the only suppression route the fixture names. Exceptions go through `quality-exceptions.toml`, which is the project record. I am relying on the fixture naming no other route. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, is what CI runs, accepts a path to limit the run, and prints Lintomatic's output unchanged. I judged this on the fixture's description, not on detector-specification clauses 5.1 to 5.4. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first and stops when it fails. CI runs this command. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and runs nothing. It prints each rule's identifier, a one-line summary and a documentation path. |\n| 5.2 | Yes | `zig-qa list` reads the same `lintomatic.toml` that `zig-qa run` loads, so a newly registered rule appears on the next listing. |\n| 5.3 | Yes | The four `proj.*` rules are documented and appear in `zig-qa list`. |\n| 6.1 | Partial | `quality-exceptions.toml` is a defined path that `zig-qa run` loads. The project record also holds calibrations and conventions, and the fixture describes no location or loading for those. |\n| 6.2 | No | The toolchain checks only that `reason` is non-empty. The spec says a present, non-empty field does not satisfy the clause. Nothing checks for a named hazard or scope, and nothing rejects generic phrases. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries in the same format as the rule listing. |\n\n**Project grade.** Zigpipe does not conform. Clauses 4.1, 4.2 and 6.2 fail and 6.1 is partial. Section 9 requires every MUST in sections 4 to 6 to hold, so the toolchain is not conforming. It is in the \"most of this document\" condition that section 9 describes as respectable but not conforming.\n\n**Conformance with agent support.** No. The toolchain is not conforming, so the agent-support grade cannot apply. It also fails section 7: there is no defence summary (7.1), no delivery into an agent file (7.2), and no `AGENTS.md`.\n\n**Section 8.** It does not apply. Zigpipe ships no tooling to other projects. The section 8 closing paragraph says a project that assembles its toolchain without shipping it has no release, so section 8 does not bear on its conformance. `zig-qa` is published by the company, not by Zigpipe, so it is a part Zigpipe consumes and not an artefact Zigpipe ships. Zigpipe therefore has only the project grade.\n\n**Effect of the missing declaration.** None. Section 9.2 says the declaration is optional and \"not a condition of conformance.\" The verdict rests on the clauses checked above. Section 9.2 also says a gap a practitioner finds is recorded under method clause 3.2 whether or not the project declares, so the failures above still need recording.\n\n## 4. Confusion\n\n- **6.2 / 6.4:** Clause 6.2 says \"It MUST NOT supply a default,\" and clause 6.4 says \"The toolchain SHOULD state its own defaults for anything the method leaves to the project.\" Read in one pass, I had to work out that the first refers to justification text for exceptions and the second to project-level judgements.","ttft_ms":55782,"type":"result","duration_ms":63635,"uuid":"1e5ae603-ae8d-460e-a6fa-7f7657594e3b","ttft_stream_ms":1245,"time_to_request_ms":639,"first_content_frame_ms":1246,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":59333,"stop_reason":"end_turn","session_id":"0b56cdbc-52c0-43ac-8225-0ff8a1a522d1","total_cost_usd":0.01021303,"usage":{"input_tokens":2,"cache_creation_input_tokens":14974,"cache_read_input_tokens":2153,"output_tokens":14393,"output_tokens_details":{"thinking_tokens":11972},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14974,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14393,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14974,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14974},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14393,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14974,"webSearchRequests":0,"costUSD":0.01021303,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11972,"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- Measure toolchain conformance at the level of the whole assembled toolchain, whichever parts (third-party, first-party or project-written) supply each mechanism.\n- Every detector a defence is routed through must itself conform to the detector specification, with wrapping allowed to fill its gaps.\n- Every identifier a blocking rule can print must resolve to on-disk documentation, for the project's own rules as well as the bundled ones, and that documentation must state the correct construction.\n- Disable or block any suppression route that bypasses the project record, and keep every exception in a file the toolchain itself reads, with a specific written justification.\n- The entry point must run detectors before runners, stop on a detector failure, and print detector output unaltered, down to a single file.\n- Provide a listing of active defences and of the project record that is derived from configuration and runs without triggering anything. Agent summaries and defaults are SHOULDs.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through. Quoting section 1: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The parts are evidence for that grade, not grades of their own. Quoting section 9: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Section 1 adds: \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n**2c.** The project has two grades: a project grade, which every project has, and an artefact grade, which a project that ships something also has. One does not imply the other. Quoting clause 9.1: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application\n\nZigpipe's toolchain is Lintomatic 4.2 (third-party detector), zig-qa (first-party package) and four project rules, with `quality-exceptions.toml` and `zig-qa run`/`list` as the routing, listing and recording parts.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | **No** | Lintomatic has two bundled rules with no documentation, and nothing in the project or zig-qa supplies it. Section 4.1's wrapping table marks \"Two [Bundled rules] have no documentation | Nothing for those two | Fails\". *Caveat:* the detector specification was not provided, so I checked only the restated points. The other restated points (single-rule runs, identifiers, local running, inline-suppression handling) are described as met. |\n| 4.2 | **No** | Two enabled bundled identifiers do not resolve. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" *Assumption:* the fixture says these rules are enabled but not whether they are blocking. I treated them as blocking because enabled rules fail the run under Lintomatic. If they were warnings, this verdict would depend on other evidence. Clause 4.1 fails regardless. |\n| 4.3 | **Yes** | `ignore_comments = false` disables the inline route, and exceptions go to `quality-exceptions.toml`. The fixture does not mention any other suppression route, such as a baseline, so I graded only what it describes. |\n| 4.4 | **Yes** | `zig-qa run` runs locally with no service, `zig-qa run <path>` limits it to a file, and Lintomatic's output is printed unchanged. *Caveat:* detector clauses 5.1 to 5.4 were not provided, so this rests on the restated points. |\n| 4.5 | **Yes** | `zig-qa run` runs Lintomatic, then the tests, and \"stops when Lintomatic fails\". The fixture says CI runs these scripts. |\n| 5.1 | **Yes** | `zig-qa list` reads `lintomatic.toml` and prints each rule's identifier, summary and documentation path without running any rule. |\n| 5.2 | **Yes** | The listing is produced by reading the configuration `lintomatic.toml`, not from a hand-kept document. |\n| 5.3 | **Yes** | The four `proj.*` rules appear in `zig-qa list`, alongside the `zq.*` and bundled rules. Their documentation states what each forbids, why, and what to write instead. |\n| 6.1 | **Yes** | The record is `quality-exceptions.toml`, and `zig-qa run` loads it. |\n| 6.2 | **No** | The only check is that `reason` is non-empty, and the clause states that \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing describes a check for the hazard or scope, or for generic phrases like \"legacy\" or \"TODO\". |\n| 6.3 | **Yes** | `zig-qa list --exceptions` prints entries \"in the same format as the rule listing.\" |\n\n**Section 9 (conformance):** No. Clauses 4.1, 4.2 and 6.2 are MUST failures.\n\n**Section 9 with agent support:** No. Two reasons: the toolchain does not conform, and it does none of the section 7 items. There is no summary and no `AGENTS.md`.\n\n**Section 8 (self-audit):** Does not apply to Zigpipe. Section 8 \"bears on the artefact grade only\" (clause 9.1). The fixture says Zigpipe \"does not ship any tooling to other projects\", and zig-qa is the company's package that Zigpipe consumes. Quoting section 8: \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" If zig-qa has its own repository and is graded as an artefact, section 8 would apply to that separate grade.\n\n**Absence of a declaration:** It does not affect the verdict. Clause 9.2 says \"The declaration is optional,\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The absence only means the duty to record gaps in a declaration does not arise. The two undocumented rules are still gaps that clause 9.2 says a practitioner's report records under method clause 3.2, whether or not the project declares.\n\n## 4. Confusion\n\n- **Clauses 6.2 and 6.4.** Clause 6.2 says: \"It MUST NOT supply a default, and MUST reject an [Exception] that omits one.\" Clause 6.4 says: \"a documented [Toolchain] default is what the [Practitioner] falls back to.\" I could not tell whether the \"default\" in 6.2 is the same thing 6.4 means, or whether 6.4's SHOULD reaches exception justifications, which 6.2 treats as the Owner's judgement.\n- **Section 3, \"Identifier resolution\" row, and clause 4.2.** The table assigns \"clause 4.2 here for the rest\", meaning the non-bundled rules. Clause 4.2 begins: \"every [Blocking] [Rule] the [Toolchain] runs, the project's own and the bundled alike.\" I could not reconcile the table's split with clause 4.2's stated reach.","ttft_ms":51148,"type":"result","duration_ms":59889,"uuid":"b6d6a7ac-6915-4101-a304-77a6a8460905","ttft_stream_ms":1245,"time_to_request_ms":550,"first_content_frame_ms":1245,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":53589,"stop_reason":"end_turn","session_id":"069d10d9-a612-459d-aaa4-d1d835f4fba0","total_cost_usd":0.00959273,"usage":{"input_tokens":2,"cache_creation_input_tokens":14975,"cache_read_input_tokens":2153,"output_tokens":13152,"output_tokens_details":{"thinking_tokens":11023},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14975,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":13152,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14975,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14975},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":13152,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14975,"webSearchRequests":0,"costUSD":0.00959273,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":11023,"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- Conformance is measured on the whole toolchain a project assembles, at project level, whichever package or script each part comes from.\n- Every detector a defence is routed through must conform to the detector specification, and the toolchain must resolve every identifier its blocking rules print from installed docs, offline.\n- The toolchain must forbid inline or baseline suppression routes that bypass the project record, and its entry point must expose the detectors' reporting, run detectors before runners, and stop on detector failure.\n- The toolchain must list active defences, derived from the loaded configuration, without running them, including the project's own.\n- The project record must live at a location the toolchain itself reads, every exception must carry a non-generic written justification, and the record must be enumerable the same way as the defences.\n- A project that ships a detector or toolchain gets a separate artefact grade, the declaration is optional, and agent support (section 7) is an additional tier that the document only recommends.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through, meaning the detectors and runners plus the parts that route, list, record and resolve.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** One grade. The third-party detector, the first-party package and the project rules are all parts of one assembled whole, and each part is evidence toward that single grade, not a grade of its own.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n> \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** Two grades: the company's repository gets a project grade, and the published package gets an artefact grade. One does not imply the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application to Zigpipe\n\n| Clause | Verdict | Reasoning |\n| --- | --- | --- |\n| 4.1 | No | Lintomatic's offline resolution covers 38 of 40 bundled rules. The two undocumented ones get nothing from zig-qa or the project, and the wrapping table marks that case \"Fails\". This restated test is enough for the verdict. I did not have the detector specification, so I checked only the restated parts and say so. |\n| 4.2 | No | The two enabled bundled rules print identifiers that resolve to `(none)`. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" The fixture does not state that they are Blocking. I read \"enabled\", together with zig-qa stopping when Lintomatic fails, as Blocking. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline ignore route, and the project record handles exceptions. The fixture describes no other suppression route, such as a baseline or an exclude list. I answered from what is written. |\n| 4.4 | Yes | `zig-qa run` runs locally, `zig-qa run <path>` narrows it to a file, and it prints Lintomatic's output unchanged, one line per finding. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic before the test suite and stops when Lintomatic fails. CI runs these same scripts. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` without running anything and prints each rule's identifier, a one-line summary and its documentation path. The fixture does not show the summary text, so I take it to be the terse statement the clause asks for. |\n| 5.2 | Yes | `zig-qa list` reads the same `lintomatic.toml` that Lintomatic loads, and it prints `(none)` for the undocumented rules, so the listing is not hand-maintained. |\n| 5.3 | Yes | The four `proj.*` rules are included in `zig-qa list`, with paths to their pages in `docs/defences/`. |\n| 6.1 | Yes | `quality-exceptions.toml` is the defined location, and `zig-qa run` loads it. |\n| 6.2 | No | The only check is that `reason` is non-empty, and the clause says \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing rejects generic justifications such as \"needed for now\", \"legacy\" or \"TODO\". |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing. |\n\n**Conformance under section 9:** No. Clauses 4.1, 4.2 and 6.2 fail, and the document says \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support:** No. The project is not conforming, and it has no agent-context summary (7.1) and no delivery into an `AGENTS.md` or equivalent (7.2).\n\n**Section 8:** Does not apply. Zigpipe ships no tooling to other projects. Section 8 bears only on shipped artefacts, and the document says that \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" If the company's zig-qa package were graded as an artefact, section 8 would apply to that grade, but the fixture does not grade it.\n\n**Effect of the missing declaration:** None on the verdict. Section 9.2 makes the declaration optional and says a toolchain \"MAY be graded [Conforming] on evidence by anyone who exercises the clauses above against it.\" The verdict rests on the failing MUSTs above, not on the absence of a declaration.\n\n## 4. Confusion\n\nSection 2, the paragraph beginning \"Throughout this document\":\n> \"Clauses 4.2 and 8.1 reach every [Blocking] [Rule] a [Toolchain] runs, documented or not, and a [Toolchain] that runs such a [Rule] fails clause 4.2.\"\n\nClause 8.1:\n> \"A third-party [Detector]'s native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside this audit\"\n\nI read these two passages as conflicting for a third-party detector's blocking rules.","ttft_ms":46484,"type":"result","duration_ms":54158,"uuid":"95ee0658-d3b0-417f-ba0c-786af0a40b74","ttft_stream_ms":1168,"time_to_request_ms":567,"first_content_frame_ms":1169,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":46638,"stop_reason":"end_turn","session_id":"42dc9fa5-dfd9-476d-b141-17d059320a70","total_cost_usd":0.00860393,"usage":{"input_tokens":2,"cache_creation_input_tokens":14976,"cache_read_input_tokens":2153,"output_tokens":11174,"output_tokens_details":{"thinking_tokens":8771},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14976,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":11174,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14976,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14976},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":11174,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14976,"webSearchRequests":0,"costUSD":0.00860393,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":8771,"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- Judge a project's toolchain as one assembled whole, whichever parts (third-party, first-party or project-written) supply each mechanism.\n- Make every mechanism the method needs available without the project building it, including detectors that can host, run and prove rules, and resolve their identifiers offline.\n- Forbid suppression routes that bypass the project record, and run detectors before runners, stopping on a detector failure.\n- Let a project list its active defences from its live configuration without running them, including its own, and list its project record the same way.\n- Define a project record location that the toolchain reads itself, and require a specific written justification on every exception.\n- Grade the project and any shipped artefact separately. A conformance declaration is optional and is a claim, not a condition of conformance.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks through.\n\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one conformance grade. The individual parts are evidence for that grade, not grades of their own.\n\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\nZigpipe ships nothing, so it has only this one grade. The sentence that says so: \"a project that ships nothing has only the one.\"\n\n**2c.** The company's project has two grades, one at project level and one for the artefact it ships. Neither implies the other.\n\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nOnly the restated sentences of the detector specification were available to me, so clauses 4.1 and 4.4 are graded on those alone.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | **No** | Lintomatic is routed through by every zig-qa and proj defence. Its two undocumented bundled rules fail the table's \"Two Bundled rules have no documentation … Fails\" row, and the fixture says nothing in the project or zig-qa documents them. The restated checks otherwise pass, but the grader only checked restated sentences. |\n| 4.2 | **No** | The `zq.*` pages ship in the package, the `proj.*` pages are in `docs/defences/`, and `lintomatic explain` resolves the other 38 bundled identifiers offline. The two undocumented bundled rules are enabled, and `zig-qa run` \"stops when Lintomatic fails\", so they are Blocking, and their identifiers resolve to nothing. |\n| 4.3 | **Yes** | The only route the fixture describes is the inline `// lintomatic-ignore` comment, and `ignore_comments = false` disables it. The exceptions file is the project record, which covers irreducible cases. The fixture does not say whether Lintomatic has any other suppression route, so this verdict rests on the route described. |\n| 4.4 | **Yes** | `zig-qa run` runs locally with no service, accepts `<path>` for a single file, prints Lintomatic's output unchanged, and is what CI runs. The restated reporting checks pass. |\n| 4.5 | **Yes** | `zig-qa run` runs Lintomatic before the test suite and stops when Lintomatic fails. CI runs the same script. |\n| 5.1 | **Yes** | `zig-qa list` prints each active rule with its identifier, a one-line summary and a documentation path, and it reads `lintomatic.toml` without running anything. The two undocumented rules print `(none)`, but they are not Defences under section 2 (a Blocking rule without documentation \"is not yet a Defence\"), so clause 5.1 does not require them to be listed. |\n| 5.2 | **Yes** | `zig-qa list` reads `lintomatic.toml`, which is the configuration the toolchain loads. Adding a rule there would appear on the next run. |\n| 5.3 | **Yes** | The four `proj.*` rules are listed by `zig-qa list`, alongside the bundled ones, and their documentation is in `docs/defences/`. |\n| 6.1 | **Yes** | The record is `quality-exceptions.toml`, and `zig-qa run` loads it itself before running Lintomatic. The fixture describes only exceptions in the record, so calibrations and conventions are unaddressed. |\n| 6.2 | **No** | The toolchain rejects an empty `reason`, but the clause says \"a field that is merely present and non-empty does not satisfy this clause.\" The `reason` field is free text, nothing requires it to name a hazard and scope, and nothing rejects generic phrases such as \"needed for now\", \"legacy\" or \"TODO\". |\n| 6.3 | **Yes** | `zig-qa list --exceptions` prints the record in the same format as the rule listing, through the same script. |\n\n**Section 9 (conformance):** Zigpipe does **not** conform. Clauses 4.1, 4.2 and 6.2 each fail, and section 9 requires every MUST in sections 4 to 6 to hold.\n\n**Conformance with agent support:** No. This requires conformance first. It also requires section 7, and the fixture says Zigpipe has no agent summary (7.1) and no delivery into `AGENTS.md` or equivalent (7.2).\n\n**Section 8 (self-audit):** It does not apply. Section 8 bears only on a shipped artefact, and the fixture says Zigpipe \"does not ship any tooling to other projects.\" Clause 8 says a project that \"assembles its [Toolchain] without shipping it has no release … so this section does not bear on its [Conformance].\" The `zig-qa` package belongs to the company, and its own grade does not transfer to Zigpipe.\n\n**Absence of a declaration:** It does not affect the verdict. Section 9.2 makes the declaration optional and says a toolchain \"MAY be graded [Conforming] on evidence by anyone who exercises the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\"\n\n## 4. Confusion\n\n- Section 6.2: \"That check cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified it.\" The \"it\" could refer to the check, the truth, or the justification.\n- Section 6.2: \"MUST reject a justification that could be pasted onto any [Exception] unchanged, by a check it documents: 'needed for now', 'legacy', 'TODO' and their like.\" I could not tell whether the phrases are examples or the full set, or where \"their like\" ends.\n- Section 2, Terminology: \"a [Blocking] [Rule] whose documentation is missing is not yet a [Defence]. Clause 5.1 does not require it to be listed, because that clause lists [Defences].\" This sits beside the table definition of Defence (\"A [Rule] with its documentation, in force and [Blocking]\"), and I read them as consistent only after checking both.","ttft_ms":38087,"type":"result","duration_ms":47204,"uuid":"8cc359d3-fb6f-40e0-9e52-243cdd18a2da","ttft_stream_ms":1166,"time_to_request_ms":560,"first_content_frame_ms":1166,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":66870,"stop_reason":"end_turn","session_id":"30dd18e9-9b7c-4df8-938b-3d0c8a6cc8f7","total_cost_usd":0.011196230000000001,"usage":{"input_tokens":2,"cache_creation_input_tokens":14975,"cache_read_input_tokens":2153,"output_tokens":16359,"output_tokens_details":{"thinking_tokens":13920},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14975,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":16359,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14975,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14975},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":16359,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14975,"webSearchRequests":0,"costUSD":0.011196230000000001,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":13920,"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- Conformance is measured on the whole toolchain as the project assembles it, wherever each part comes from.\n- Every detector a defence is routed through must meet the detector specification. Wrapping can supply a missing mechanism but cannot excuse a gap.\n- Every blocking rule's identifier must resolve offline to documentation on disk, including the project's own rules. The toolchain provides the place for that documentation, and the documentation must state the correct construction.\n- Suppression routes that bypass the project record must be disabled or made to fail a blocking defence. Every exception needs a written justification that names the hazard and scope, and generic justifications must be rejected.\n- The active defences and the project record must be listable without running anything, with the listing derived from the active configuration. The toolchain must read the project record itself.\n- The entry point runs detectors before runners and stops on a detector failure. Reporting must work locally, down to one file. Shipped artefacts get a separate grade and a self-audit, and the agent summary and its delivery are SHOULDs.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks. \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve. Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2b.** One grade. The individual parts are evidence for that grade, not grades of their own. Section 9 says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Section 1 adds: \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n**2c.** Two grades, and neither implies the other. The project's own assembled toolchain gets the project grade, and the shipped package gets the artefact grade. Section 9.1 says: \"The two verdicts MUST be graded and declared separately, and neither implies the other. The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\"\n\n## 3. Application\n\nGrading uses the fixture only. I did not have the detector specification, so for 4.1 I checked only the restated points, as clause 4.1 allows, and I say so in its verdict.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic has two bundled rules with no documentation, and nothing in the project or in zig-qa documents them. The clause's own table says that \"Nothing for those two\" fails. The restated points I could check otherwise hold (bespoke rules, single-rule and single-file runs, stable identifiers, local running, a disableable ignore comment). The detector specification's full MUSTs were not available to me. |\n| 4.2 | No | The two undocumented bundled rules are enabled, and no on-disk documentation resolves their identifiers. \"One [Identifier] that does not resolve fails this clause, however many others do.\" The fixture does not say whether these two are Blocking. I read them as Blocking because `zig-qa run` stops when Lintomatic fails. If they were Warnings, this clause would not apply to them. |\n| 4.3 | Yes | `ignore_comments = false` disables the only suppression route the fixture describes, and irreducible cases go to `quality-exceptions.toml`. The fixture does not say whether Lintomatic or zig-qa has other routes, such as a baseline, so this verdict covers only what is described. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts `<path>` down to one file, prints Lintomatic's output \"unchanged, one line per finding\", and is what CI runs. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first, then the test suite, and \"stops when Lintomatic fails\". |\n| 5.1 | Yes | `zig-qa list` prints each active rule with its identifier, a one-line summary and a documentation path, and it does not run the rules. The two undocumented rules print `(none)`, but section 2 says they are not yet defences, so 5.1 does not require them. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, the same configuration that Lintomatic enforces from. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list` alongside the bundled and `zq.*` rules. The second paragraph of 5.3 concerns shipped toolchains, which Zigpipe is not. |\n| 6.1 | Partial | The exceptions file is defined and loaded by `zig-qa run`, and `list --exceptions` reads it. But section 2 defines the project record as covering calibrations and conventions too, and the fixture gives no location and no reader for those. |\n| 6.2 | No | The `reason` field is free text, and the only check is that it is non-empty. The clause says \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing requires the justification to name the hazard and scope, and nothing rejects generic phrases. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the exceptions in the same format as the rule listing, using the same command family. |\n\n**Section 9 (conformance):** No. Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is only partial. Section 9 requires that \"every MUST in sections 4 to 6 holds across the assembled parts.\" A partial result cannot be described as conformance.\n\n**Conformance with agent support:** No. The clause applies only \"in addition\" to conformance, and Zigpipe does not conform. It also does neither 7.1 nor 7.2: it has \"no summary of its defences for an agent\", and \"no `AGENTS.md` or equivalent.\"\n\n**Section 8 (self-audit):** It does not apply. Section 8 bears on the artefact grade, and Zigpipe ships nothing: \"It does not ship any tooling to other projects.\" Clause 8.2 says that \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" Zig-qa is a company package, and its own grade would be a separate artefact grade that this fixture does not cover.\n\n**Absence of a declaration:** It does not affect the verdict. Clause 9.2 says \"The declaration is optional, and so the duty above falls only on a project or artefact that has one,\" and \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The verdict is No whether or not Zigpipe declares, and the gaps still belong in the record under method clause 3.2.\n\n## 4. Confusion\n\n- **Section 2, after the terminology table:** \"Clauses 4.2 and 8.1 reach every [Blocking] [Rule] a [Toolchain] runs, documented or not.\" This conflicts with clause 8.1, which says: \"A third-party [Detector]'s native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside this audit.\" On my reading, 8.1 does not reach every blocking rule the toolchain runs, so the statement in section 2 is wrong or the exclusion is.","ttft_ms":58314,"type":"result","duration_ms":67345,"uuid":"3217c613-6136-4d81-85ac-d6d3d6435841","ttft_stream_ms":1245,"time_to_request_ms":471,"first_content_frame_ms":1246,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 085: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone, on the
evidence a project shows. Where a clause rests on the [detector specification](DETECTOR-SPEC.md),
as clauses 4.1, 4.2 and 4.4 do, it says what it holds the [Detector] to and restates the parts
most often failed; a grader without that document to hand checks what is restated and says so.
The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

Throughout this document, a [Blocking] [Rule] whose documentation is missing is not yet a
[Defence]. Clause 5.1 does not require it to be listed, because that clause lists [Defences].
Clauses 4.2 and 8.1 reach every [Blocking] [Rule] a [Toolchain] runs, documented or not, and a
[Toolchain] that runs such a [Rule] fails clause 4.2.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them: a [Detector]
that fails any of them, after wrapping, fails this clause. The sentences that follow restate
the ones most often failed, so that a grader knows where to look first; they are not the whole
test, and a grader without that document to hand can check only them, and says so in the
verdict. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. Three points govern how that
is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. That is every [Blocking] [Rule] the [Toolchain] runs, the project's
own and the bundled alike. One [Identifier] that does not resolve fails this clause, however
many others do.

The resolving mechanism is keyed on the [Identifier] exactly as printed. Those
[Remediation docs] MUST ship with the project, with the [Toolchain] or with the [Detector]
whose [Rule] they document, at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open: that
document holds a [Detector] to on-disk resolution of its own [Bundled rules] and no further,
because it cannot know a project's documentation, and this clause reaches the project's own
[Rules] as well. An [Identifier] a third-party [Detector] resolves under that document's clause
6 meets this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.

[LTSCommerce]

Run 086: 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/toolchain-contradictions`). The readers read commit 6da7409. 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 568e323, named here before the readers started), acceptance/runs/README.md, acceptance/toolchain/QUESTIONS.md, acceptance/toolchain/KEY.md, acceptance/fixtures/zigpipe.md and TOOLING-SPEC.md. You may read acceptance/runs/085-toolchain-contradictions-run-13.md for the shape of a record only; ACCEPTANCE.md says a judgement an earlier run recorded is not a rule.

Run: 086. Document: TOOLING-SPEC.md. Change: toolchain contradictions (section 9 against clause 9.1 on section 8; clauses 4.2 and 8.1 on a blocking rule whose documentation is missing; clause 9.2's gap duty against the optional declaration; clause 4.3's heading against its body; clause 4.1's count of the detector specification's MUSTs and its point 2 on what is judged), revised after run 85 in section 2's closing paragraph alone: it now names clause 4.2 alone as the clause that reaches every blocking rule a toolchain runs, documented or not; clause 8.1 is no longer named there. Pull request: not yet opened; it will be opened on this branch. Run within the pull request: 14 (runs 57, 58, 62, 65, 67, 68, 72, 76, 81, 82, 83, 84 and 85 came before). Record file to write: <worktree>/acceptance/runs/086-toolchain-contradictions-run-14.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 60c864ced29d5011fb73ca0f35139b8bfcc146303dd001952fb43a99bcaa910e, and it is byte for byte the question set, TOOLING-SPEC.md and the fixture at 6da7409, 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 6da7409 -- TOOLING-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, a paragraph the change parts from what it refers to, 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 568e323, 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 086: 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":60361,"stop_reason":"end_turn","session_id":"2dc73369-833a-44a7-91e2-1b9c0cec5767","total_cost_usd":0.01028983,"usage":{"input_tokens":2,"cache_creation_input_tokens":14968,"cache_read_input_tokens":2153,"output_tokens":14549,"output_tokens_details":{"thinking_tokens":12616},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14968,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14549,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14968,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14968},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14549,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14968,"webSearchRequests":0,"costUSD":0.01028983,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12616,"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's toolchain is judged as one assembled whole, whoever wrote each part, and must provide the mechanisms the method needs.\n- Every detector the toolchain routes a defence through must conform to the detector specification, and every blocking rule it runs must have its identifier resolve to documentation on disk, offline.\n- Suppression routes that bypass the project record must be disabled, or guarded by a blocking defence.\n- The toolchain's entry point must run detectors before runners, stop on a detector failure, and print detector identifiers unaltered and locally.\n- The toolchain must list active defences, and the project's own rules, from its active configuration without running them.\n- The toolchain must define and load the project record itself, reject exceptions without a specific justification, and list the record the same way it lists defences.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one project-level grade. Its parts are evidence for that grade, not grades of their own.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\nSection 1 supports this: \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n**2c.** The project has two grades, because it ships an artefact. One grade is for the project's own toolchain and the other is for the package it ships. Neither implies the other.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\nSection 9 adds: \"The artefact a project ships is graded on its own, and that grade is the second level clause 9.1 names; a project that ships nothing has only the one.\"\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n| --- | --- | --- |\n| 4.1 | No | Lintomatic has two bundled rules with no documentation, and neither the project nor zig-qa supplies any, which is the table's \"Fails\" row. |\n| 4.2 | No | The two undocumented identifiers do not resolve, and `zig-qa list` prints `(none)` for them; I assume they are Blocking, since the fixture does not say per rule but `zig-qa run` stops on Lintomatic failure. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline ignore route; the fixture describes no other Lintomatic route, so this rests on that description. |\n| 4.4 | Yes | `zig-qa run` is local, takes a file or directory path, and prints Lintomatic's output unchanged; only the restated points of detector clauses 5.1–5.4 can be checked, since that document was not supplied. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic first, stops when it fails, and is what CI runs. |\n| 5.1 | Yes | `zig-qa list` prints each active rule's identifier, summary and documentation path, and reads configuration without running anything. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, the configuration the toolchain loads. |\n| 5.3 | Yes | The four `proj.*` rules appear in `zig-qa list`, and their pages cover what, why and what to write instead. |\n| 6.1 | Partial | `quality-exceptions.toml` is defined and loaded by `zig-qa run`, but the project record as defined also holds calibrations and conventions, and the fixture shows no location for those. |\n| 6.2 | No | `zig-qa run` only refuses an empty `reason`, which is the presence check the clause rules out; nothing checks for a named hazard and scope or rejects generic text. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries in the same format as the rule listing. |\n\n**Conformance under section 9:** Zigpipe does not conform. Clauses 4.1, 4.2 and 6.2 fail, and 6.1 is only partial. Section 9 requires every MUST in sections 4 to 6 to hold.\n\n**Conformance with agent support:** No. The project does not conform at all, and it has no agent summary or delivery mechanism, so it does none of what section 7 recommends.\n\n**Section 8:** It does not apply. Zigpipe does not ship tooling to other projects. Section 8 bears only on an artefact grade. Zig-qa is the company's shipped artefact and is graded on its own, not as part of Zigpipe's verdict. Section 8 states that \"a project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\"\n\n**Declaration:** Its absence does not affect the verdict. Section 9.2 says \"The declaration is optional,\" and that \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The duty to record known gaps attaches only to a project that has a declaration, though section 9.2 also says a gap a practitioner finds \"is recorded under the method's clause 3.2 in any case.\"\n\n## 4. Confusion\n\n- **6.1**, with the definition in section 2: The \"Project record\" definition covers \"Calibrations, Exceptions and conventions,\" but clause 6.1 speaks of \"where the Project record lives\" in the singular, and the document never says whether calibrations and conventions fall under it. This is why I graded 6.1 Partial.\n- **5.3**, last sentence: \"its entry MAY be sourced from wherever it is enabled\" does not say whether that means the Toolchain's own Detectors, the config file, or somewhere else.","ttft_ms":53518,"type":"result","duration_ms":60893,"uuid":"5df89e92-52c3-40a1-8f81-dd56f33bb994","ttft_stream_ms":1108,"time_to_request_ms":561,"first_content_frame_ms":1108,"queued_turn_count":0,"result_index":0}

reader-2

{"duration_api_ms":68701,"stop_reason":"end_turn","session_id":"855cd255-26ae-4dd8-b0a3-2301ada6eacf","total_cost_usd":0.011532530000000001,"usage":{"input_tokens":2,"cache_creation_input_tokens":14969,"cache_read_input_tokens":2153,"output_tokens":17034,"output_tokens_details":{"thinking_tokens":14784},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14969,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":17034,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14969,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14969},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":17034,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14969,"webSearchRequests":0,"costUSD":0.011532530000000001,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":14784,"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's assembled toolchain, including its detectors, runners, and the parts that route, list, record and resolve, is graded as one whole, whatever its parts' sources.\n- Every defence must run through a detector that conforms to the detector specification. Wrapping can add a missing mechanism but cannot excuse a gap.\n- Every identifier a blocking rule prints must resolve offline to documentation on disk, including the project's own rules, and that documentation must state the correct construction.\n- Suppression routes that bypass the project record must be disabled or caught by a blocking defence. Exceptions must live in a record the toolchain reads, each with a specific justification, and generic justifications must be rejected.\n- The toolchain must list active defences and project-record entries without running them, derived from live configuration. Its entry point must run detectors before runners and stop on a detector failure.\n- Agent summaries (7.1, 7.2) are SHOULDs. A shipping project has two separately graded levels, and the declaration is optional.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is whatever the project assembles to run its checks. \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade and do not receive grades of their own. \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Section 1 supports this: \"Those parts may be third-party, first-party or project-level, in any combination.\" Section 9 says the MUSTs hold \"across the assembled parts, wherever each part came from.\"\n\n**2c.** The project has two grades. Its project grade applies to its assembled toolchain as used on its own repository, and its artefact grade applies to what it ships. \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" Also: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\" So the project grade and the artefact grade are separate, and neither one implies the other.\n\n## 3. Application\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic's two undocumented bundled rules get nothing from the project or zig-qa, which the wrapping table marks as \"Fails.\" |\n| 4.2 | No | The two enabled bundled identifiers print with no documentation on disk (`zig-qa list` shows `(none)`), and one unresolved identifier fails the clause \"however many others do.\" |\n| 4.3 | Yes | The only route the fixture describes, `// lintomatic-ignore`, is disabled by `ignore_comments = false`, and the fixture describes no other route, so I assume none. |\n| 4.4 | Yes | `zig-qa run` runs locally, accepts `<path>`, and prints Lintomatic's output unchanged, which covers the `zq.*` and `proj.*` defences. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic before the test suite and stops when Lintomatic fails, and CI runs it. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints identifier, summary and documentation path without running any rule. The `(none)` entries are not Defences, so they are outside 5.1. |\n| 5.2 | Yes | The listing is produced from `lintomatic.toml`, which `zig-qa run` also loads. |\n| 5.3 | Yes | `zig-qa list` includes the four `proj.*` rules alongside the bundled ones, and each has a documentation page. |\n| 6.1 | Yes | `zig-qa run` and `zig-qa list --exceptions` load `quality-exceptions.toml` themselves. |\n| 6.2 | No | The only check is that `reason` is non-empty, which the clause says does not satisfy it. No hazard or scope check, and no rejection of generic phrasing, is described. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing. |\n\nGrading note: 4.1 and 4.2 refer to the detector specification, which I was not given. I checked only the sentences restated in this document. The 4.1 failure is on a restated point, the two undocumented bundled rules, so the verdict stands on the checkable part. The 4.4 verdict is likewise checked against its restated content only.\n\n**Section 9 conformance:** No. It fails 4.1, 4.2 and 6.2, which are MUSTs. Under section 9, \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support:** No. Agent support requires conformance first, and the project also does none of the things section 7 recommends. It has no defence summary and no `AGENTS.md`, so neither 7.1 nor 7.2 is met.\n\n**Section 8:** It does not apply. Section 8 covers a shipped toolchain, and the fixture says \"Zigpipe does not ship any tooling to other projects.\" Section 8 states: \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" The fixture describes zig-qa as published by the company, not by Zigpipe. If that package has its own repository, its artefact grade would be a separate grading of that repository, which this fixture does not cover.\n\n**Absence of a declaration:** It does not affect the verdict. Section 9.2 says: \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The gap-recording duty falls only on a project that declares, but the failing gaps are still recorded under the method's clause 3.2 whether or not the project declares.\n\n## 4. Confusion\n\n- **4.1:** \"with the wrapping in place, does the [Detector] meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md), exercised as its clause 8.1 describes?\" I could not tell what the exercise is, because the detector specification was not in what I was given.\n- **4.5:** \"A [Blocking] failure at the [Detector] level MUST stop the levels below it from being treated as meaningful, in the order method section 5 states.\" The clause does not define the levels below a detector beyond runners, and method section 5 was not given.\n- **6.2:** \"It MUST NOT supply a default.\" Read next to 6.4, which SHOULDs a documented toolchain default, I could not tell whether this prohibition covers only the justification field or the record as a whole.","ttft_ms":61293,"type":"result","duration_ms":69148,"uuid":"ce9833e1-67c8-4474-acce-95dd1b5468bc","ttft_stream_ms":1335,"time_to_request_ms":450,"first_content_frame_ms":1335,"queued_turn_count":0,"result_index":0}

reader-3

{"duration_api_ms":58601,"stop_reason":"end_turn","session_id":"b6d349f9-7ad1-4845-940f-a53f25fc84cd","total_cost_usd":0.010059529999999999,"usage":{"input_tokens":2,"cache_creation_input_tokens":14969,"cache_read_input_tokens":2153,"output_tokens":14088,"output_tokens_details":{"thinking_tokens":12072},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14969,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":14088,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14969,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14969},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":14088,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14969,"webSearchRequests":0,"costUSD":0.010059529999999999,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":12072,"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's toolchain, whatever parts it is assembled from, must run its detectors and runners in the right order, stopping on detector failure, and print every finding with its identifier unaltered.\n- Every detector a defence is routed through must conform to the detector specification, with wrapping permitted to fill gaps.\n- Every blocking rule's identifier must resolve offline to documentation on disk that states the correct construction.\n- Inline and baseline suppression routes that bypass the project record must be disabled or guarded by a blocking defence. Irreducible cases go to the project record, which the toolchain must locate and read.\n- Every exception needs a justification naming its hazard and scope, and the toolchain must reject generic ones.\n- The toolchain must list active defences, including the project's own, from its live configuration without running them. It must list the project record the same way.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks.\n> \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The third-party, first-party and project parts are evidence toward that grade, not grades of their own.\n> \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\nSection 9.1 adds a second, artefact grade, but only for a project that ships a detector or toolchain. Zigpipe ships none, so it has one grade.\n\n**2c.** The company's project has two grades: a project grade, and an artefact grade for the package it publishes.\n> \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\nPassing one does not establish the other.\n\n## 3. Application\n\nI had only `TOOLING-SPEC.md` and the fixture, not `SPEC.md` or `DETECTOR-SPEC.md`. Clauses 4.1, 4.2 and 4.4 rest partly on the detector specification, so for those I checked only the restated points and say so.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic's two undocumented bundled rules are not supplied by zig-qa or the project, and the clause's own table says that \"Fails\". Verdict checks only restated points; the rest of the detector specification was not in hand. |\n| 4.2 | No | The two undocumented bundled rules are enabled, so an identifier they print leads to no documentation. |\n| 4.3 | Yes | `ignore_comments = false` disables Lintomatic's inline ignore project-wide, and exceptions live in `quality-exceptions.toml`. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, accepts a path, and prints Lintomatic's output unchanged. Verdict checks only the restated points (local, subset, output in the command's own output). |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the tests, and stops when Lintomatic fails. CI runs it. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints each rule with identifier, summary and documentation path, without running anything. The two undocumented rules print `(none)`, but they are not Defences under section 2, so 5.1 does not require a route for them. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, the configuration Lintomatic loads. |\n| 5.3 | Yes | The `proj.*` rules are in the same `zig-qa list` output as the bundled ones. |\n| 6.1 | Yes | The record is `quality-exceptions.toml`, and `zig-qa run` loads it. |\n| 6.2 | No | The only check is that `reason` is non-empty, which the clause says is not enough. Nothing rejects generic justifications or requires a hazard and scope. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints the record in the same format as the rule listing. |\n\n**Conformance (section 9).** No. The project fails 4.1, 4.2 and 6.2, and section 9 requires every MUST in sections 4 to 6 to hold. Partial conformance may not be described as conformance.\n\n**Conformance with agent support.** No. That grade requires full conformance first, and Zigpipe also has no agent summary and no delivery into an agent file (section 7.1 and 7.2 are SHOULDs, but the agent-support grade requires them).\n\n**Section 8.** It does not apply. Section 8.2 says \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" Zigpipe ships no tooling. Whether section 8 applies to `zig-qa` depends on where it is published from, which the fixture does not say, so I have not graded it.\n\n**Effect of the missing declaration.** None. Section 9.2 says \"The declaration is optional, and so the duty above falls only on a project or artefact that has one.\" The verdict rests on the clauses above, not on a declaration.\n\n**Robustness.** The verdict does not depend on my reading of the undocumented rules as blocking. Clause 4.1 fails regardless of blocking status, and so does section 9.\n\n## 4. Confusion\n\nIn section 4.1, two passages sat uneasily together on my reading:\n> \"The sentences that follow restate the ones most often failed, so that a grader knows where to look first; they are not the whole test, and a grader without that document to hand can check only them, and says so in the verdict.\"\n\n> \"does the [Detector] meet every MUST of sections 4 to 7 of the [detector specification], exercised as its clause 8.1 describes?\"\n\nThe first says a grader without the detector specification can check only the restated sentences. The second makes the full detector specification the test. I could not tell which governed a grader in my position, so I checked the restated points and said so.","ttft_ms":51645,"type":"result","duration_ms":59165,"uuid":"4ff06bcf-7217-4287-b799-3d28dd047823","ttft_stream_ms":1254,"time_to_request_ms":568,"first_content_frame_ms":1255,"queued_turn_count":0,"result_index":0}

reader-4

{"duration_api_ms":70743,"stop_reason":"end_turn","session_id":"73a33f52-034d-40b1-8c7d-374dfd2008e3","total_cost_usd":0.011381130000000001,"usage":{"input_tokens":2,"cache_creation_input_tokens":14967,"cache_read_input_tokens":2153,"output_tokens":16732,"output_tokens_details":{"thinking_tokens":14455},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14967,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":16732,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14967,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14967},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":16732,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14967,"webSearchRequests":0,"costUSD":0.011381130000000001,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":14455,"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's toolchain is measured as one assembled whole, whichever part came from which package (§1, §9).\n- Every defence must run through a detector that conforms to the detector specification. Wrapping can fill a gap but cannot excuse one (§4.1).\n- Every identifier a blocking rule can print must resolve offline from the installed copy, and the project must have a place for its own rule documentation (§4.2).\n- Suppression routes that bypass the project record must be disabled or made to fail. Detectors run before runners, and the run stops on a detector failure (§4.3–4.5).\n- Active defences and the project record must be listable without running anything, from the live configuration, and must include the project's own rules (§5, §6.3).\n- The project record must live at a path the toolchain reads, and generic exception justifications must be rejected. Agent summaries and auto-delivery are SHOULDs (§6–7).\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level, and the toolchain is everything the project assembles to run its checks through, including detectors, runners, and the parts that route, list, record and resolve. §1: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\" It adds: \"[Conformance] is a property of the assembled whole, because that is where it counts.\"\n\n**2b.** One grade. The individual parts are evidence for that grade and do not earn grades of their own. §9: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\"\n\n**2c.** Two grades, graded and declared separately, and neither implies the other. The project grade covers how the company's repository follows the method with its own toolchain. The artefact grade covers what the package gives consumers. §9.1: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\" §9 also says that for a project that ships, \"every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this project grade.\"\n\n## 3. Application: Zigpipe\n\nZigpipe is a consuming project. It ships nothing, so it has only a project grade. Lintomatic is the third-party detector, zig-qa is the first-party package, and the `proj.*` rules are its own.\n\n| Clause | Verdict | Reason |\n|---|---|---|\n| 4.1 | No | Lintomatic routes Zigpipe's defences, and its two undocumented bundled rules are a gap the 4.1 table names: \"Two [Bundled rules] have no documentation \\| Nothing for those two \\| Fails.\" Nothing in the project or zig-qa documents them. I only have the restated parts of the detector specification, so this verdict rests on those and the other detector MUSTs are unchecked. |\n| 4.2 | No | The `zq.*` docs ship in the package and the `proj.*` docs in `docs/defences/`, and `lintomatic explain` resolves 38 of 40 bundled identifiers offline. The two undocumented ones fail: \"One [Identifier] that does not resolve fails this clause, however many others do.\" The fixture does not say whether those two are Blocking. I took enabled bundled rules to be Blocking. The fixture also does not describe whether the `zq.*` pages state the correct construction. |\n| 4.3 | Yes | The only described inline route, `// lintomatic-ignore`, is disabled with `ignore_comments = false`. Exceptions go through `quality-exceptions.toml`. The fixture does not describe any other Lintomatic suppression route, such as a baseline. |\n| 4.4 | Yes | `zig-qa run` runs locally, takes a directory or single file as an argument, and prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. CI runs these scripts. |\n| 5.1 | Yes | `zig-qa list` prints each active rule's identifier, a one-line summary and a documentation path, and it reads the configuration rather than running the rules. |\n| 5.2 | Yes | `zig-qa list` reads `lintomatic.toml`, the configuration that is loaded. |\n| 5.3 | Yes | `zig-qa list` includes the `proj.*` rules alongside the bundled ones. Their docs say what is forbidden, why, and what to write instead. |\n| 6.1 | Partial | `zig-qa run` defines and loads `quality-exceptions.toml`. The project record in §2 also covers calibrations and conventions, and the fixture does not say where those live. |\n| 6.2 | No | The only check is that `reason` is non-empty. §6.2 says \"A field that is merely present and non-empty does not satisfy this clause,\" and the fixture describes no check for generic phrasing or for naming the hazard and scope. |\n| 6.3 | Partial | `zig-qa list --exceptions` lists exceptions in the same format as the rule listing. Calibrations and conventions are not described, so they cannot be shown to be enumerable. |\n\n**Section 9 (conformance): does not conform.** §9 requires every MUST in sections 4 to 6 to hold. 4.1, 4.2 and 6.2 are No, and 6.1 and 6.3 are Partial. §9 also says \"Partial [Conformance] MUST NOT be described as [Conformance].\"\n\n**Conformance with agent support: no.** It is not conforming, and it does nothing section 7 recommends. The fixture says Zigpipe \"does not publish a summary of its defences for an agent and has no `AGENTS.md` or equivalent.\"\n\n**Section 8 (self-audit): does not apply.** Section 8 bears on shipped toolchains. §8 says: \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project], so this section does not bear on its [Conformance].\" Zigpipe ships nothing. zig-qa is the company's published package, so section 8 would bear on that package's artefact grade. It does not bear on Zigpipe's grade.\n\n**Does the missing declaration affect the verdict? No.** §9.2 makes the declaration optional, and it says: \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\" The No verdicts above rest on the fixture's description, not on a declaration.\n\n## 4. Confusion\n\n**§6.2 and §6.4.** §6.2 says the toolchain \"MUST NOT supply a default\" for an exception justification. §6.4 says the toolchain \"SHOULD state its own defaults for anything the method leaves to the project.\" An exception is a judgement the method leaves to the project, so these two can be read as contradicting each other.","ttft_ms":62841,"type":"result","duration_ms":71195,"uuid":"bc24ece4-80bf-4054-90a8-b46ab8996578","ttft_stream_ms":1549,"time_to_request_ms":455,"first_content_frame_ms":1550,"queued_turn_count":0,"result_index":0}

reader-5

{"duration_api_ms":70755,"stop_reason":"end_turn","session_id":"977b8267-b003-421c-ae5f-b633d42369ab","total_cost_usd":0.011642830000000002,"usage":{"input_tokens":2,"cache_creation_input_tokens":14968,"cache_read_input_tokens":2153,"output_tokens":17255,"output_tokens_details":{"thinking_tokens":14952},"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":14968,"ephemeral_5m_input_tokens":0},"inference_geo":"global","iterations":[{"input_tokens":2,"output_tokens":17255,"cache_read_input_tokens":2153,"cache_creation_input_tokens":14968,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":14968},"type":"message"}],"speed":"standard","fallback_credit":null},"modelUsage":{"claude-haiku-5-5":{"inputTokens":2,"outputTokens":17255,"cacheReadInputTokens":2153,"cacheCreationInputTokens":14968,"webSearchRequests":0,"costUSD":0.011642830000000002,"contextWindow":1000000,"maxOutputTokens":128000,"thinkingTokens":14952,"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's toolchain, taken as one assembled whole, must run its checks through detectors that conform to the detector specification. Wrapping may add a missing mechanism but cannot excuse a gap.\n- Every identifier a blocking rule can print must resolve offline, from files on disk, to documentation that states the correct construction.\n- Suppression routes that bypass the project record must be disabled, or must make a blocking defence fail. Irreducible cases go to the project record.\n- The entry point must report locally, down to one file, with results in its own output. It must print identifiers unaltered and run detectors before runners, stopping on a detector failure.\n- Active defences, including the project's own, must be listable without running them, derived from the active configuration. The project record must be enumerable by the same means.\n- The project record must live at a location the toolchain reads. Every exception needs a written justification naming its hazard and scope, and generic justifications must be rejected. Agent summaries and defaults are SHOULDs.\n\n## 2. Load-bearing statements\n\n**2a.** Conformance is measured at the project level. The toolchain is whatever the project assembles to run its checks. Section 1 says: \"**A [Toolchain] is measured at the project level.** It is whatever the project assembles to run its checks through: the [Detectors] and [Runners], and the parts around them that route, list, record and resolve.\"\n\n**2b.** The assembly receives one grade. The individual parts are evidence for that grade and are not graded separately. Section 9 says: \"The project-level verdict is a single grade; which part of the [Toolchain] satisfied each clause is evidence for that grade, not a second grade.\" Section 1 adds: \"Those parts may be third-party, first-party or project-level, in any combination.\"\n\n**2c.** The project has two grades, and one does not imply the other. Clause 9.1 says: \"The two levels are the project grade of section 9, which every project has, and the artefact grade, which only a project that ships has.\" It continues: \"The two verdicts MUST be graded and declared separately, and neither implies the other.\"\n\n## 3. Application to Zigpipe\n\nI was not given the detector specification, so the verdict on 4.1 rests only on the parts the toolchain document restates. The verdict says so.\n\n| Clause | Verdict | Reasoning |\n|---|---|---|\n| 4.1 | No | Lintomatic is the detector, and its gap is offline resolution. Two bundled rules have no documentation, and the fixture says nothing in the project or in zig-qa covers them. The wrapping table says \"Two [Bundled rules] have no documentation / Nothing for those two / Fails.\" |\n| 4.2 | No | The two undocumented bundled rules are enabled, and `zig-qa list` prints their path as `(none)`. The clause says \"One [Identifier] that does not resolve fails this clause, however many others do.\" The fixture does not state the blocking level of these two rules. I read them as blocking because they are enabled and Lintomatic's failure stops `zig-qa run`. |\n| 4.3 | Yes | `ignore_comments = false` disables the inline ignore project-wide, and irreducible cases go to `quality-exceptions.toml`. The fixture does not say whether Lintomatic has other routes, such as a baseline file. This verdict covers only what is described. |\n| 4.4 | Yes | `zig-qa run` runs locally with no service, `zig-qa run <path>` limits it to one file, and it prints Lintomatic's output unchanged. |\n| 4.5 | Yes | `zig-qa run` runs Lintomatic, then the test suite, and stops when Lintomatic fails. The fixture says both scripts are what CI runs. |\n| 5.1 | Yes | `zig-qa list` reads `lintomatic.toml` and prints each rule's identifier, summary and documentation path without running anything. |\n| 5.2 | Yes | The listing is generated from `lintomatic.toml`, which the toolchain loads. |\n| 5.3 | Yes | The four `proj.*` rules are included in `zig-qa list`, and their pages are in `docs/defences/`. |\n| 6.1 | Partial | A location is defined and read for exceptions. Section 2 defines the project record as also covering calibrations and conventions, and the fixture gives neither a location nor a load for those. If \"project record\" is read as exceptions only, this is Yes. |\n| 6.2 | No | `zig-qa run` refuses only an empty `reason`. The clause says \"A field that is merely present and non-empty does not satisfy this clause.\" Nothing checks that the reason names a hazard and a scope, and nothing rejects generic phrases. |\n| 6.3 | Yes | `zig-qa list --exceptions` prints entries \"in the same format as the rule listing.\" |\n\nSection 4.2 has a further gap that the verdict does not depend on. The fixture describes paths for `zq.*` and `proj.*` identifiers in `zig-qa list`, but it does not describe a lookup from a printed identifier to its page. It also does not say that the `zq.*` pages state the correct construction.\n\n**Conformance under section 9: No.** Clauses 4.1 and 4.2 fail, 6.2 fails, and 6.1 is partial. Section 9 says \"Partial [Conformance] MUST NOT be described as [Conformance].\" Zigpipe is in a respectable partial state and is not conforming.\n\n**Conformance with agent support: No.** Section 9 requires full conformance before agent support can apply, and the project does not have it. Separately, the project publishes no defence summary and has no `AGENTS.md`, so 7.1 and 7.2 are also absent.\n\n**Section 8 does not apply.** Section 9 says section 8 \"bears on the artefact grade of clause 9.1 and not on this project grade.\" Clause 8.2 adds that \"A project that assembles its [Toolchain] without shipping it has no release and no [Consuming project].\" The fixture says Zigpipe \"does not ship any tooling to other projects.\" The shipped artefact is zig-qa, which the company publishes, and it is not Zigpipe's artefact.\n\n**The absence of a declaration does not affect the verdict.** Clause 9.2 says \"The declaration is optional, and so the duty above falls only on a project or artefact that has one.\" It adds: \"A verdict on any [Toolchain], declared or not, rests on that exercise and not on the claim.\"\n\n## 4. Confusion\n\nClause 6.1 says: \"The [Toolchain] MUST define where the [Project record] lives and MUST load it. Not a documentation convention. A path the [Toolchain] loads.\" Section 2 defines the project record as \"Calibrations, Exceptions and conventions,\" but clauses 6.1 to 6.3 discuss only exceptions. On my one reading I could not tell whether \"the Project record\" in 6.1 covers all three categories or only exceptions, and that uncertainty is why I graded 6.1 Partial.","ttft_ms":63749,"type":"result","duration_ms":71430,"uuid":"bf9a64c7-15a7-48e8-bbda-775172e0a0b5","ttft_stream_ms":1454,"time_to_request_ms":712,"first_content_frame_ms":1454,"queued_turn_count":0,"result_index":0}

[LTSCommerce]

Run 086: 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 TOOLING-SPEC.md

You have been given `TOOLING-SPEC.md` and the fixture `fixtures/zigpipe.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 project's
toolchain?

## 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. At what level is toolchain conformance measured, and what is the toolchain?
- 2b. A project's tooling is assembled from a third-party detector, a first-party package and
  the project's own rules. How many conformance grades does that assembly receive, and what is
  the role of the individual parts in reaching it?
- 2c. A company publishes a toolchain package and also uses it on the package's own repository.
  How many conformance grades does that project have, and does one imply the other?

## 3. Application

Grade the Zigpipe project's toolchain, as described in the fixture, against every MUST clause in
sections [4](../../TOOLING-SPEC.md#4-the-detectors-a-toolchain-routes-defences-through) to [6](../../TOOLING-SPEC.md#6-the-project-record): [4.1](../../TOOLING-SPEC.md#41-every-detector-the-toolchain-routes-a-defence-through-must-conform-to-the-detector-specification), [4.2](../../TOOLING-SPEC.md#42-the-toolchain-must-resolve-every-identifier-a-blocking-rule-it-routes-can-print-from-the-installed-copy-without-network-access), [4.3](../../TOOLING-SPEC.md#43-the-toolchain-must-forbid-every-suppression-route-that-bypasses-the-project-record-by-disabling-it-or-by-a-defence-of-its-own), [4.4](../../TOOLING-SPEC.md#44-the-toolchains-own-invocation-must-satisfy-the-detector-specifications-reporting-clauses-for-every-defence-it-routes), [4.5](../../TOOLING-SPEC.md#45-the-toolchains-entry-point-must-run-detectors-before-runners-and-must-stop-on-a-detector-failure), [5.1](../../TOOLING-SPEC.md#51-the-toolchain-must-be-able-to-list-the-defences-active-in-a-project-without-triggering-them), [5.2](../../TOOLING-SPEC.md#52-the-listing-must-be-derived-from-the-active-configuration), [5.3](../../TOOLING-SPEC.md#53-a-projects-own-defences-must-appear-in-the-listing-alongside-bundled-ones), [6.1](../../TOOLING-SPEC.md#61-the-toolchain-must-define-a-location-for-the-project-record-and-must-read-it-itself), [6.2](../../TOOLING-SPEC.md#62-every-exception-in-the-project-record-must-carry-a-written-justification-that-names-the-hazard-and-the-scope-and-the-toolchain-must-reject-a-generic-one), [6.3](../../TOOLING-SPEC.md#63-the-project-record-must-be-enumerable-by-the-same-means-as-the-defences). For each give Yes,
Partial or No and one line of reasoning. Then state whether the toolchain conforms under section
[9](../../TOOLING-SPEC.md#9-conformance) and why, whether it conforms with agent support and why, and whether section [8](../../TOOLING-SPEC.md#8-self-audit) applies to it
and why. Finally, state whether the absence of a declaration affects 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: TOOLING-SPEC.md =====
# Defence Before Fix: Toolchain Specification

**Version**: 0.2.0, published 2026-09-08
**Companion to**: [the method specification](SPEC.md), version 1.1.0, and [the detector specification](DETECTOR-SPEC.md), version 1.0.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.
[The detector specification](DETECTOR-SPEC.md) states what each [Detector] must offer so that they
can write, prove, run and resolve a [Rule] in it. This document states what a project's
[Toolchain] must offer beyond that, so that the [Rules] become [Defences]
the project governs.

**A [Toolchain] is measured at the project level.** It is whatever the project assembles to
run its checks through: the [Detectors] and [Runners], and the parts around them
that route, list, record and resolve. Those parts may be third-party, first-party or project-level,
in any combination. A third-party [Toolchain] such as `php-qa-ci` can supply all of it. A project
can also meet this document with its own scripts around a bare [Detector]. [Conformance]
is a property of the assembled whole, because that is where it counts: a [Practitioner]
arriving at the project cannot tell which package a mechanism came from, and does not need to.

The three documents are separable because they fail separately, and all three failures have been
observed. A project can follow the method faithfully on a [Toolchain] that gives it nowhere to
record what it decided. A [Toolchain] can offer every mechanism the method needs whilst the
project using it writes no [Rules] at all. A [Detector] can be the best host for
a [Rule] in its language whilst shipping an inline ignore that the project has never decided
whether to allow. Conflating them produces a specification that blames a project for a gap in its
[Toolchain], credits a [Toolchain] for discipline the project supplied itself, or
fails a [Detector] for governance that was never its to decide.

**The governing principle**: where the method specification requires a [Practitioner] to do
something, a [Conforming] [Toolchain] MUST make that possible without the project
building the mechanism first. A [Toolchain] that leaves the project to construct the means has
moved the obligation rather than met it. Where the project builds the means itself, those scripts are
part of its [Toolchain] and are judged as such.

**How to read this document.** A [Toolchain] can be graded from this document alone, on the
evidence a project shows. Where a clause rests on the [detector specification](DETECTOR-SPEC.md),
as clauses 4.1, 4.2 and 4.4 do, it says what it holds the [Detector] to and restates the parts
most often failed; a grader without that document to hand checks what is restated and says so.
The
table in section 2 glosses every term it borrows. Each clause states its obligation in its heading
and first sentence, and the **Why** paragraph beneath is reasoning, not a further requirement. A
link is there for depth and is not a prerequisite for the sentence that carries it.

## 2. Terminology

Terms from the method specification and the [detector specification](DETECTOR-SPEC.md) 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                               |
| [Runner]           | A tool that executes code, a test suite or a compilation, and reports what happened                 |
| [Rule]             | One check a [Detector] evaluates                                                                    |
| [Defence]          | A [Rule] with its documentation, in force and [Blocking]                                            |
| [Identifier]       | The stable name printed with a finding that leads to its documentation                              |
| [Remediation docs] | The documentation an [Identifier] leads to: what the [Rule] is about, why, and how to fix a finding |
| [Blocking]         | Fails the run rather than issuing a [Warning]                                                       |
| [Exception]        | A recorded, justified decision to leave an [Instance] unfixed or a [Rule] unapplied                 |
| [Practitioner]     | Whoever is doing the work, a person or an [Agent]                                                   |
| [Owner]            | The human who decides what the codebase may keep                                                    |
| [Bundled rule]     | A [Rule] a [Detector] ships rather than one the project wrote                                       |
| [Harness]          | The route by which one [Rule] is run against supplied code on its own                               |

These are additional.

#### Consuming project

A codebase that installs a [Detector] or a [Toolchain] shipped by somebody else. The maintainer of what is installed does not control it and cannot inspect it.

#### Bundled defence

A [Defence] a shipped [Toolchain] carries and enables by default in every [Consuming project]. A [Bundled rule] is the [Detector]-level counterpart; a [Bundled defence] is one with its documentation, [Blocking], and routed through the [Toolchain]'s own entry point.

#### Project record

The place a project writes down the judgements the method specification delegates to it: [Calibrations], [Exceptions] and conventions.

The distinction between a [Bundled defence] and a project's own is significant throughout. A bundled
[Defence] is authored once and runs in codebases its author will never see, so everything a
[Practitioner] needs in order to act on it has to travel with it.

Throughout this document, a [Blocking] [Rule] whose documentation is missing is not yet a
[Defence]. Clause 5.1 does not require it to be listed, because that clause lists [Defences].
Clause 4.2 reaches every [Blocking] [Rule] a [Toolchain] runs, documented or not, and a
[Toolchain] that runs such a [Rule] fails clause 4.2.

## 3. The division of responsibility

Almost every requirement in section 8 of the method specification has two halves. Stating only one
of them is what produces a [Toolchain] that is *nearly* usable. The middle column says which
document states the mechanism half; the assembled [Toolchain] MUST provide every row, whichever
part of it does so.

| Requirement             | The mechanism, and where it is stated                                                                       | The project supplies                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Bespoke [Defences]      | The authoring and registration route, [detector specification](DETECTOR-SPEC.md) 4.1                        | The [Rules]                          |
| The red proof           | A [Harness], [detector specification](DETECTOR-SPEC.md) 4.2                                                 | The [Fixture] and the red run        |
| Running the [Defence]   | A local invocation, including subsets, [detector specification](DETECTOR-SPEC.md) 5                         | Running it                           |
| [Identifier] resolution | The lookup, [detector specification](DETECTOR-SPEC.md) 6 for [Bundled rules], clause 4.2 here for the rest  | The documentation content            |
| Correct construction    | A place for it to live, clause 4.2 here                                                                     | The remediation text                 |
| Enumeration             | The listing, section 5 here                                                                                 | The [Defences] listed                |
| [Agent]-context summary | Generation and delivery, section 7 here                                                                     | The terse lines                      |
| Recorded decisions      | A location it reads itself, section 6 here                                                                  | The decisions                        |
| [Suppression]           | A route that can be forbidden, [detector specification](DETECTOR-SPEC.md) 7; forbidding it, clause 4.3 here | The decision, under method section 4 |

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

## 4. The detectors a toolchain routes defences through

### 4.1 Every detector the toolchain routes a defence through MUST conform to the [detector specification](DETECTOR-SPEC.md)

A [Toolchain] MUST NOT route a [Defence] through a [Detector] that does not
[Conform] to [the detector specification](DETECTOR-SPEC.md). That document's MUSTs are those of
its sections 4 to 7, and this clause holds the [Detector] to every one of them: a [Detector]
that fails any of them, after wrapping, fails this clause. The sentences that follow restate
the ones most often failed, so that a grader knows where to look first; they are not the whole
test, and a grader without that document to hand can check only them, and says so in the
verdict. The
[Detector] hosts bespoke [Rules]. It runs one [Rule] on its own against supplied
code. It prints a stable [Identifier] with every finding. It runs locally, down to one file, with
the result in the command's own output and nothing reportable only through a hosted service. It
resolves every [Identifier] a [Bundled rule] can print to documentation shipped with it, offline.
It makes any inline [Suppression] route detectable or disableable. Three points govern how that
is met.

1. **Wrapping is permitted.** The [Toolchain] MAY supply a mechanism the
   [Detector] lacks by wrapping it, with a [Harness] script or a
   resolver of its own. The [Detector] together with that wrapping is then what the
   [Practitioner] uses and what is judged.

2. **How the wrapped pair is judged.** Start from the gap, not from what the [Detector] does
   well:

   | The [Detector]'s gap                       | What the [Toolchain] adds                                     | This clause |
   | ------------------------------------------ | ------------------------------------------------------------- | ----------- |
   | Resolves none of its [Identifiers] offline | A resolver keyed on the [Identifier], covering all of them    | Holds       |
   | Two [Bundled rules] have no documentation  | Nothing for those two                                         | Fails       |
   | Two [Bundled rules] have no documentation  | Its own documentation for those two, resolved by [Identifier] | Holds       |

   Behind the table is one question. With the wrapping in place, does the [Detector]
   meet every MUST of sections 4 to 7 of the [detector specification](DETECTOR-SPEC.md),
   exercised as its clause 8.1 describes? If yes, this clause holds. If no, it fails, however
   much else the [Detector] does well, and whether or not a later clause of this document, such
   as clause 4.2 on resolution, names the same gap again. Wrapping can add a mechanism; it
   cannot excuse a gap. What this clause judges is the
   wrapped pair; the [Detector]'s own grade under that document, as an artefact on its own, is a
   separate verdict that the wrapping does not change. Satisfying most of that document is not
   [Conformance] to it, any more than satisfying most of this one is.

3. **What cannot be wrapped.** A [Detector] that cannot host a bespoke [Rule] at all
   cannot be wrapped into [Conformance], and no [Defence] is routed through it.
   It MAY still run as one of the [Toolchain]'s checks, as a formatter or a
   [Runner] does.

**Why**: the method's clauses 3.1 to 3.6 are carried out in a [Detector], and everything this
document adds presumes those clauses can be followed there. A [Toolchain] that lists, records
and resolves beautifully around a [Detector] in which no [Rule] can be written or proven
has governed nothing. The wrapping is permitted because a [Practitioner] cannot tell where a
mechanism lives, and the method does not care. It is bounded because a mechanism the [Detector]
does not offer and the [Toolchain] does not add is a gap the project writes down under method
clause 3.2. A gap recorded is not a gap closed.

### 4.2 The toolchain MUST resolve every identifier a blocking rule it routes can print, from the installed copy, without network access

The [Toolchain] MUST resolve every [Identifier] its [Blocking] [Rules] print to
[Remediation docs] on disk. That is every [Blocking] [Rule] the [Toolchain] runs, the project's
own and the bundled alike. One [Identifier] that does not resolve fails this clause, however
many others do.

The resolving mechanism is keyed on the [Identifier] exactly as printed. Those
[Remediation docs] MUST ship with the project, with the [Toolchain] or with the [Detector]
whose [Rule] they document, at a version tracked together. The
[Toolchain] MUST also give that documentation a place to live, so that a
[Rule author] adding a [Rule] knows where its documentation goes.
The documentation an [Identifier] resolves to MUST state the correct construction, not
only the prohibition, specifically enough to act on, as method clause 8.4 requires. The
[Toolchain] supplies the place and the [Rule author] the text.

This clause closes what the [detector specification](DETECTOR-SPEC.md) leaves open: that
document holds a [Detector] to on-disk resolution of its own [Bundled rules] and no further,
because it cannot know a project's documentation, and this clause reaches the project's own
[Rules] as well. An [Identifier] a third-party [Detector] resolves under that document's clause
6 meets this clause, and one that nothing resolves fails it.

**Why**: method specification clauses 3.6 and 8.3. The [Identifier] has to resolve for the
reader, which for an [Agent] means mechanically and on disk, and the project's own
[Rules] are the ones that carry its knowledge. A [Detector] that prints the
[Identifier] faithfully has done its half; a project in which that string then leads nowhere
has a [Message] that names a pattern without leading anywhere, which method clause 3.6 says
does not [Conform].

### 4.3 The toolchain MUST forbid every suppression route that bypasses the project record, by disabling it or by a defence of its own

A [Conforming] [Toolchain] MUST disable every [Suppression]
route that bypasses the [Project record], or MUST run a [Blocking]
[Defence] that fails on its use. A route bypasses the [Project record] when a finding can be
silenced through it without an entry appearing in the [Project record]: an inline
[Suppression] comment, a per-line ignore and a silently generated [Baseline] all do. The
obligation covers every such route in every [Detector] the [Toolchain] routes a
[Defence] through. The routes are the ones each [Detector] offers: where a [Detector]'s only
route is an ignore comment, this clause is met for that [Detector] once the comment is disabled
or a [Blocking] [Defence] fails on its use, and nothing is owed for a route it does not have.
Irreducible cases MUST be directed to the [Project record],
where clause 6.2 requires a justification.

The [detector specification](DETECTOR-SPEC.md) permits a [Detector] to ship such a route provided
it can be detected or disabled. This clause is where the project's decision is made and enforced,
and the decision is no. A [Baseline] an [Owner] has adopted under method section
4 is therefore kept in the [Project record], or read from a file the record names. It is
never a file the [Detector] generates unseen.

**Why**: a governance mechanism whose escape hatch is an unreviewed comment is not a governance
mechanism. This is the one place this document is stricter than the [Detectors] it assembles
are by default, and it is deliberate. The method specification's position is that
[Suppression] is an [Owner] decision, and an [Owner] cannot decide something
they are never shown. The [Detector] is not asked to forbid the route because the
[Detector] is not the project; the [Toolchain] is the project's, so it is.

The reference implementations both do this. `ts-qa-ci` bans every `eslint-disable` and
`@ts-expect-error` form outright; `php-qa-ci`'s `ForbidInlinePhpstanIgnoreRule` bans inline
`@phpstan-ignore` and directs irreducible cases to the configuration file, where they are visible.

### 4.4 The toolchain's own invocation MUST satisfy the detector specification's reporting clauses for every defence it routes

The [Toolchain]'s own entry point MUST meet clauses 5.1 to 5.4 of the
[detector specification](DETECTOR-SPEC.md) for every [Defence] it routes. That means invocable
locally with no infrastructure, over a subset down to one file, and with the result in the output of
the command the [Practitioner] ran. No [Defence] may be reportable only
through a mode they cannot run. The entry point MUST also print every [Identifier] its
[Detectors] print, unaltered, so that clause 4.3 of the
[detector specification](DETECTOR-SPEC.md) holds through the wrapping. The [Detector]'s verdict
under that clause is on its own output. The [Toolchain]'s is on what reaches the
[Practitioner].

**Why**: method clause 3.5 asks the [Practitioner] to demonstrate enforcement through the
project's own entry point, not through the [Detector] directly. A [Detector] that
[Conforms] on its own, wrapped in a command that runs only the whole codebase or only
elsewhere, has had its reporting clauses undone by the wrapping. The [Practitioner]
is then back to a loop that does not close.

### 4.5 The toolchain's entry point MUST run detectors before runners, and MUST stop on a detector failure

The invocation the project uses to accept changes MUST evaluate its [Detectors] before its
[Runners]. A [Blocking] failure at the [Detector] level MUST stop the
levels below it from being treated as meaningful, in the order method section 5 states. How the
project expresses that sequence, and where it runs, remain out of scope under method section 8.

**Why**: method section 5. A [Detector] is preventive and a test is diagnostic, and a failure
at the [Detector] level produces confusing results at every level above it. The method makes
the ordering a property of the project rather than of any one remediation, which is exactly the
kind of property that lives in the [Toolchain] and nowhere else.

## 5. Enumeration

### 5.1 The toolchain MUST be able to list the defences active in a project, without triggering them

The [Toolchain] MUST list every [Defence] active in the project without
running it. The listing MUST include each [Defence]'s [Identifier] and a terse
statement of what it forbids or requires. It MUST provide the route to each one's full documentation.

**Why**: method specification clause 8.5. An [Agent] arriving at a codebase has no colleague to ask.
Without a listing, a project's standards can only be learned by violating them one at a time.

### 5.2 The listing MUST be derived from the active configuration

The listing MUST be generated from the configuration the [Toolchain] actually loads. It
MUST NOT be a hand-maintained document that happens to describe the configuration. The test is
what happens when a [Rule] is added to the configuration and nobody edits anything else: a
derived listing shows it on the next run, and a hand-maintained one does not.

**Why**: a hand-maintained list drifts, and it drifts silently and in the dangerous direction. The
observed failure is a [Rule] that is registered, active, [Blocking], and absent from
the list of [Rules], whilst the list states its own count with confidence. A derived listing cannot
diverge from what is enforced, because the thing enforced is what produced it.

### 5.3 A project's own defences MUST appear in the listing alongside bundled ones

Every [Defence] the project has written itself MUST appear in the listing clause 5.1
requires, meeting its content requirements in full, alongside every [Bundled defence].

For a shipped [Toolchain], the case is the same and worth spelling out. Its
[Defences] against its own source, the ones only its contributors can trigger, are that
project's own [Defences] for this purpose. They MUST appear in the same listing clause 5.1
requires, meeting its content requirements in full, when the [Toolchain] is run on itself,
however they are enabled. Where such a [Defence] is not expressible in the [Toolchain]'s own
[Detectors], its entry MAY be sourced from wherever it is enabled, provided the listing stays derived
under clause 5.2 rather than hand-maintained.

**Why**: the [Practitioner] does not care which package a [Rule] came from. They care what defends the
code in front of them, and a listing that covers only what a shipped [Toolchain] carries describes somebody
else's project.

## 6. The project record

This section exists because of a gap found by cold readers of the method specification, repeatedly
and independently. The method delegates several judgements to project level, and a [Practitioner]
arriving at a project that has recorded none of them has no legal move. That is a [Toolchain]
obligation. The method specification cannot fix it, because the method specification does not own a
file in the project.

### 6.1 The toolchain MUST define a location for the project record, and MUST read it itself

The [Toolchain] MUST define where the [Project record] lives and MUST load it.
Not a documentation convention. A path the [Toolchain] loads.

**Why**: a [Project record] the [Toolchain] does not read can be wrong without anything noticing.
When the [Toolchain] reads it, the written decision and the enforced decision are the same object, and
neither can drift from the other.

### 6.2 Every exception in the project record MUST carry a written justification that names the hazard and the scope, and the toolchain MUST reject a generic one

The [Toolchain] MUST require a written justification on every [Exception].
It MUST NOT supply a default, and MUST reject an [Exception] that omits one. A field that is
merely present and non-empty does not satisfy this clause.

**Why**: an [Exception] without a reason is indistinguishable from an [Exception] nobody would defend,
and the person who could tell them apart is usually gone. Requiring the sentence is the whole
mechanism: it costs the author a minute at the moment they have the reason in mind, and it is the
only thing that makes an [Exception] reviewable later.

`ts-qa-ci`'s `tier-a-exemptions.json` is the reference implementation, and its own two entries
demonstrate the standard: both explain the scope limit as well as the reason.

The justification MUST name the [Hazard] being accepted and the scope of the [Exception].
The [Toolchain] MUST reject a justification that could be pasted onto any [Exception]
unchanged, by a check it documents: "needed for now", "legacy", "TODO" and their like. That check
cannot verify truth, and a [Toolchain]'s [Conformance] MUST NOT be read as having verified
it. Whether the sentence is true is the [Owner]'s judgement under section 4 of the method
specification. That is why clause 6.3 puts every justification in one listing, where a vacuous
one is seen next to its neighbours.

### 6.3 The project record MUST be enumerable by the same means as the defences

Listing the [Defences] and listing the [Project record] MUST be the same kind of operation.

**Why**: method specification clause 8.7. A decision nobody can find will be re-opened by every
[Practitioner] who arrives after it, which converts a settled question into a recurring one.

### 6.4 The toolchain SHOULD state its own defaults for anything the method leaves to the project

Where the method specification delegates a judgement and the project has recorded nothing, a
documented [Toolchain] default is what the [Practitioner] falls back to.

**Why**: this is the deadlock this section exists to break. "The project decides" combined with "the
project has decided nothing" leaves an [Agent] choosing between guessing and stopping. A default
turns the first project-level decision from a prerequisite into a refinement, and the project's
first day is exactly when it has recorded least and can afford the interruption least.

## 7. Agent context

### 7.1 The toolchain SHOULD generate a summary of the active defences suitable for an agent's context

One terse line per [Defence], phrased as a standing instruction rather than as a failure report, each
carrying its [Identifier] and the route to its documentation. Generated from the active configuration,
per clause 5.2.

### 7.2 The toolchain SHOULD deliver that summary into the project automatically

Into the file the project's [Agents] already load, refreshed on install and update, in a delimited
region marked as generated.

**Why**: 7.1 and 7.2 are separate clauses because they are separately missed, and the two reference
implementations miss opposite halves. `php-qa-ci` writes an auto-generated, auto-refreshed block
into every [Consuming project]'s [Agent] instructions and does not put a [Rule] table in it; `ts-qa-ci`
maintains an excellent [Rule] catalogue and has no mechanism to deliver it. Each has built the half
the other lacks. A summary that exists but is never loaded and a delivery channel carrying
everything except the [Rules] are the same outcome from opposite directions.

Together these are the only clauses in any of the three specifications that operate **before** the
mistake rather than after it, which is why they are worth stating even as SHOULDs.

## 8. Self-audit

### 8.1 A shipped toolchain MUST fail its own release if a bundled defence lacks resolvable documentation

The [Toolchain] MUST run an automated check that blocks its own release. The check covers
every [Identifier] printed by a [Rule] the [Toolchain] authors or bundles
as its own, whatever kind of [Detector] carries it, and a missing page is what the check exists
to find. Where a documentation
page covers a family of [Identifiers] by a pattern, as clause 6.5 of the
[detector specification](DETECTOR-SPEC.md) allows, this audit MUST apply the pattern to every
[Identifier] printed and confirm it lands on that page. A member added to the
[Rule] and not to the page then fails the release. A third-party [Detector]'s
native catalogue, which the [Toolchain] orchestrates without claiming as its own, is outside
this audit; whether that catalogue resolves is judged under the
[detector specification](DETECTOR-SPEC.md)'s clause 6, as clause 4.2 says. The [detector specification](DETECTOR-SPEC.md)'s
clause 6.3 names the dangling reference as the failure to guard against above all others. This is the
guard, and a [Toolchain] is not held to less than it holds its
[Practitioners] to.

**Why**: clause 4.2 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. A check that blocks the release is the difference between honouring the clause and asserting it.
It is also the method applied to the [Toolchain]: the [Class] of [Defect] is "a [Rule] that blocks without
explaining", and it is detectable mechanically.

### 8.2 A shipped toolchain MUST run its own bundled defences on its own source

Every [Rule] the [Toolchain] ships to [Consuming projects] MUST also be
active when the [Toolchain] analyses itself, and a [Toolchain] release MUST fail when
they are not.

**Why**: a mechanism that delivers [Rules] to installed packages and not to the root package
leaves the [Toolchain] as the one project in which its own [Defences] never run. A
[Defect] in a [Rule]'s own code then goes unseen by every [Rule] built to see it. A
self-check that reports clean is believed, by the [Rule author] and by anyone checking their
work, because nobody expects a clean run to have run nothing. This clause was found by an execution
test in which both the [Practitioner] and the reviewer cited exactly such a run as evidence.

A project that assembles its [Toolchain] without shipping it has no release and no
[Consuming project], so this section does not bear on its [Conformance]. Its
own [Defences] already run on its own source, because that is the only source there is.

## 9. Conformance

**A project's [Toolchain] [Conforms]** if every MUST in sections 4 to 6 holds across the
assembled parts, wherever each part came from; where the project also ships a [Detector] or a
[Toolchain], every MUST in section 8 bears on the artefact grade of clause 9.1 and not on this
project grade. The project-level verdict is a single grade; which part of the
[Toolchain] satisfied each clause is evidence for that grade, not a second grade. The artefact
a project ships is graded on its own, and that grade is the second level clause 9.1 names; a
project that ships nothing has only the one.

**A [Toolchain] [Conforms] with [Agent] support** if, in addition, it does each thing section 7
of this document recommends.

Partial [Conformance] MUST NOT be described as [Conformance]. A [Toolchain] 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.

### 9.1 A project that ships a detector or a toolchain has two levels of conformance, graded separately

As a project, it follows the method with its own assembled [Toolchain], like any other
project: that [Toolchain] is graded against this document, under section 9, and the project's
remediations against section 7 of the method specification, as any project's are. As an artefact, what it ships is graded for its consumers: a [Detector] against
[the detector specification](DETECTOR-SPEC.md), a [Toolchain] against this document, on what the
shipped [Toolchain] itself supplies once installed into a [Consuming project], counting nothing
the [Consuming project] adds around it. The two
verdicts MUST be graded and declared separately, and neither implies the other. The two levels
are the project grade of section 9, which every project has, and the artefact grade, which only
a project that ships has. Section 8 bears on the artefact grade only; clause 5.3 is its
project-level counterpart.

**Why**: the two questions have different readers. A contributor to the artefact wants to know
whether the project practises what it ships; a [Consuming project] wants to know what it
will get. A single grade answers neither, and the observed failure is a [Toolchain] whose own
source was the one place its [Bundled defences] never ran, which a consumer-facing grade
alone would never have shown.

### 9.2 The declaration is the claim and the known-gap record, not a condition of conformance

A project or a shipped artefact MAY declare, machine-readably in whatever form its ecosystem uses to
record dependencies, the version of the method specification it follows and the version of this
document or the [detector specification](DETECTOR-SPEC.md) it [Conforms] to. A project that ships an artefact
carries both levels of clause 9.1 in that declaration, each named separately.

The same declaration is where a gap is recorded once it is known. A project or artefact that
declares a version and has learnt that it fails a MUST of the document it declares against MUST
record that gap alongside that version, in the same file or one it names. It may learn that from
its own self-audit under section 8 or from a [Practitioner]'s report under the method's clause
3.2. A declaration with a non-empty gap record is a statement of where the project stands and is
not a claim of [Conformance]. A mechanism gap is by its nature one the [Toolchain] could not
detect for itself, so the record is the only place its [Owner] and its consumers can learn of it.

The declaration is optional, and so the duty above falls only on a project or artefact that has
one; a gap a [Practitioner] finds is recorded under the method's clause 3.2 in any case, whether
or not the project declares. A [Toolchain] assembled before this document existed, or by a
project that has never read it, MAY be graded [Conforming] on evidence by anyone who exercises
the clauses above against it. A verdict on any [Toolchain], declared or not, rests on that
exercise and not on the claim.

**Why**: a [Conformance] claim in a README is a sentence; a [Conformance] claim in a manifest is a fact
about a specific installed artefact, checkable by anyone, including mechanically. It also fixes what
"[Conforming]" meant at the point the claim was made, which a claim against a moving document cannot.
Making the claim a condition, though, would grade the maintainer's reading rather than the
[Toolchain], and would leave every project that met the method before hearing of it unable
to say so.

## 10. Relationship to the method and detector 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.

Where this document and the method specification disagree, the method specification governs. It
describes the method, which is the thing being specified; this describes the equipment. Where this
document and the [detector specification](DETECTOR-SPEC.md) disagree about a [Detector], the [detector specification](DETECTOR-SPEC.md)
governs, because it is the document a [Detector]'s maintainer works from; what this document
asks of a [Detector] is that it [Conform] there.

Nothing here requires a project to use a [Conforming] [Toolchain] shipped by anyone. A project can [Conform] to the method
specification on a [Toolchain] that [Conforms] to none of this, at the cost of building the missing
mechanisms itself, and once built they are its [Toolchain] and are graded here. This document exists so that it
does not have to build them alone.

<!-- Term link definitions -->

[agent]: SPEC.md#agent
[agents]: SPEC.md#agent
[baseline]: SPEC.md#baseline
[blocking]: SPEC.md#blocking
[bundled defence]: #bundled-defence
[bundled defences]: #bundled-defence
[bundled rule]: DETECTOR-SPEC.md#bundled-rule
[bundled rules]: DETECTOR-SPEC.md#bundled-rule
[calibrations]: SPEC.md#calibration
[class]: SPEC.md#class
[conform]: SPEC.md#conform
[conformance]: SPEC.md#conform
[conforming]: SPEC.md#conform
[conforms]: SPEC.md#conform
[consuming project]: #consuming-project
[consuming projects]: #consuming-project
[defect]: SPEC.md#defect
[defence]: SPEC.md#defence
[defences]: SPEC.md#defence
[detector]: SPEC.md#detector
[detectors]: SPEC.md#detector
[exception]: SPEC.md#exception
[exceptions]: SPEC.md#exception
[fixture]: SPEC.md#fixture
[harness]: DETECTOR-SPEC.md#harness
[hazard]: SPEC.md#hazard
[identifier]: SPEC.md#identifier
[identifiers]: SPEC.md#identifier
[instance]: SPEC.md#instance
[message]: SPEC.md#message
[owner]: SPEC.md#owner
[practitioner]: SPEC.md#practitioner
[practitioners]: SPEC.md#practitioner
[project record]: #project-record
[remediation docs]: SPEC.md#remediation-docs
[rule]: SPEC.md#rule
[rule author]: DETECTOR-SPEC.md#rule-author
[rules]: SPEC.md#rule
[runner]: SPEC.md#runner
[runners]: SPEC.md#runner
[suppression]: SPEC.md#suppression
[toolchain]: SPEC.md#toolchain
[warning]: SPEC.md#warning

===== FILE: fixtures/zigpipe.md =====
# Fixture: the Zigpipe project

A fictional project and the tooling it has assembled, described only as far as its own
documentation and configuration would show. Grade the project's toolchain against the document
you were given. Where the description does not say, answer from what is written.

## What the project's documentation says

Zigpipe is a Zig service. Its quality checks are assembled from three sources:

- **Lintomatic 4.2**, a third-party detector. It hosts bespoke rules, runs a single rule against
  a single file, prints a stable identifier with every finding, resolves bundled identifiers
  offline with `lintomatic explain`, and its inline `// lintomatic-ignore` comment can be
  disabled project-wide. Two of its forty bundled rules currently have no documentation.
- **zig-qa**, a first-party package the company publishes for all its Zig projects. It ships six
  defences of its own as Lintomatic rules with identifiers `zq.*`, a script `zig-qa run` that
  runs Lintomatic and then the test suite in that order and stops when Lintomatic fails, and a
  script `zig-qa list` that reads `lintomatic.toml` and prints every active rule with its
  identifier, a one-line summary and the path to its documentation. The six `zq.*` rules'
  documentation ships in the package under `docs/rules/`. `zig-qa run` prints Lintomatic's
  output unchanged, one line per finding, and `zig-qa run <path>` limits the run to a directory or
  a single file. Both scripts run locally with no service and are what CI runs.
- **Project rules**, four Lintomatic rules the Zigpipe team wrote, identifiers `proj.*`,
  documented in `docs/defences/` in the repository, one page per identifier, each saying what
  the rule forbids, why, and what to write instead. `zig-qa list` includes them.

Zigpipe's `lintomatic.toml` sets `ignore_comments = false`. Exceptions are kept in
`quality-exceptions.toml`, which `zig-qa run` loads before it runs Lintomatic; each entry has an
identifier, a path and a free-text `reason` field. `zig-qa run` refuses to start when an entry's
`reason` is empty. `zig-qa list --exceptions` prints the file's entries in the same format as the
rule listing.

The two undocumented Lintomatic bundled rules are enabled in `lintomatic.toml`; nothing in the
project or in zig-qa provides documentation for them, and `zig-qa list` prints their
documentation path as `(none)`.

Zigpipe does not publish a summary of its defences for an agent and has no `AGENTS.md` or
equivalent. It does not ship any tooling to other projects. It has no machine-readable
declaration of which specification version it follows.