docs: record what the rules refuse to report, and how to accept a finding

[bgard68]

The documentation described a scanner that reports every match. Three rules now establish need before reporting, findings can be accepted in the workflow that carries them, and none of that was written down anywhere.

README

Stale counts. It claimed 117 .NET tests, 4 frontend tests. The real figures are 322 and 28 — a strange thing to undersell by 3× on the one page anyone actually reads. The engineering log line said eleven defects; it holds twenty-six.

Two new sections.

What it refuses to report — because not reporting the already-correct configuration is the harder half, and it is the part that distinguishes this from every tool that flags each write grant. It covers all three rules, the severity recalibration, and why suppression is the expensive direction.

Accepting a finding — the sentinel:accept syntax and the three refusals that keep it a judgement recorder rather than a mute button.

docs/accepting-findings.md (new)

A user-facing feature had zero documentation. This covers the syntax, why the decision lives in the workflow rather than a config file of rule/line/reason entries, what the mechanism refuses to do and why each refusal exists, and how an accepted finding is presented without disappearing.

docs/architecture/rules.md

The severity column asserted one value for GHA002 and GHA004, which now vary by scope and by whether untrusted code runs. A new Establishing need section covers the three rules, the 24-action table, and the five properties that stop the table becoming a blanket exemption.

GHA012 is noted as not a rule — it is reported by the analysis service against the acceptance mechanism itself, so it belongs outside the rule table.

docs/engineering-log.md

Entry 26, in the format of the rest. The point worth recording:

The exemption table was the defect report. It had been there long enough to be maintained, and it read as a list of accepted risks rather than as three instances of one rule being wrong about the same thing.

CHANGELOG

Unreleased entries for the acceptance mechanism, acknowledgements, the three rules, and the severity recalibration.

Verification

322 backend tests pass, including RepositoryWorkflowsTests and the repository-validation gate that checks documentation links. Every new link resolves.

🤖 Generated with Claude Code

https://claude.ai/code/session_01N7HjzX5e8Wv7PKENDo2Uj7

---

Generated by Claude Code