feat(docs): two markers for entries that do not apply everywhere
This tree is copied into every project and some of what it carries will not
apply to all of them. Rather than several templates, or scaffold profiles the
website's conformance reader would have to know about before it could tell a
legitimately-absent file from a missing one, entries say so inline.
Two markers, on axes that are deliberately not merged:
applicability -- *(only for a deployed service)*, *(only where money moves)*,
*(only where there are accounts)*. Does this project have to
do this at all?
provenance -- *(precautionary)*. Was the rule earned here, or borrowed?
They are independent, and one word cannot say both. Rate limiting is
universally applicable and has never bitten us. Money flowing backwards applies
only to projects that take money and is the most common defect in the audits it
came from. Applicability tells a reader whether to keep a rule; provenance tells
them whether to argue with it.
The instruction that travels with the marker is ClaudeQAPlan.md's rule about
passes, generalised: if it does not apply, delete it. A pass that never applies
is noise; a pass that is always skipped is a lie -- and so is a checklist row,
and so is a whole document. Deleting is safe because DOC_TRUST_MAP.md is the
trust map: what a project keeps is what it meant to keep.
Applied where it was already true: the authorisation group is conditional on
having accounts, and the header/TLS and test-environment rows on being a
deployed service. A library was being told it lacked a CSP.
closes #1
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
7d70828e48
commit
063b715c33
|
|
@ -105,6 +105,37 @@ the first sixteen lines of the file, and one carrying `Status` without
|
|||
`Review trigger` is reported as incomplete — that combination looks finished and
|
||||
is not.
|
||||
|
||||
## Two markers: does this apply, and who earned it
|
||||
|
||||
This tree is copied into every project, and some of what it carries will not
|
||||
apply to all of them. A static site has no refunds; a library has no uptime.
|
||||
Rather than shipping several templates, entries that are not universal say so
|
||||
inline, with **two markers on different axes**:
|
||||
|
||||
| Marker | Answers | Example |
|
||||
| --- | --- | --- |
|
||||
| *(only where money moves)*, *(only for a deployed service)* | does this project have to do this at all? | a payments QA pass; the operations runbook |
|
||||
| *(precautionary)* | was this rule earned here, or borrowed from outside? | rate limits; secrets in a shipped bundle |
|
||||
|
||||
**They are independent, and conflating them loses the distinction.** A rule can
|
||||
be universally applicable and precautionary — rate limiting applies to
|
||||
everything here and has never yet bitten us. Another can be narrowly conditional
|
||||
and thoroughly proven elsewhere — money flowing backwards applies only to
|
||||
projects that take money, and is the single most common defect in the audits it
|
||||
came from. One word cannot say both, and the reader needs both: applicability
|
||||
tells them whether to keep the rule, provenance tells them whether to argue with
|
||||
it.
|
||||
|
||||
**If it does not apply, delete it.** That is `docs/qa/ClaudeQAPlan.md`'s rule
|
||||
about passes — *a pass that never applies is noise; a pass that is always
|
||||
skipped is a lie* — and it holds for a checklist row and for a whole document
|
||||
just as well. A project that is not a deployed service deletes `OPERATIONS.md`
|
||||
rather than carrying its headings unanswered forever, because an empty runbook
|
||||
reads as one nobody wrote rather than one that never applied.
|
||||
|
||||
Deleting is safe here precisely because this file is the trust map: what a
|
||||
project keeps is what a project meant to keep.
|
||||
|
||||
## Declaring a document deliberately absent
|
||||
|
||||
A repository may decide it will not keep one of these documents in git — QA and
|
||||
|
|
|
|||
|
|
@ -34,6 +34,10 @@ unstated gets skipped the first time it is inconvenient.>
|
|||
|
||||
### Authorisation — the three questions login does not answer
|
||||
|
||||
*(only where there are accounts)* — a project with no users has none of these to
|
||||
get wrong, and deletes the group rather than ticking three boxes that mean
|
||||
nothing.
|
||||
|
||||
- [ ] Every authenticated endpoint refuses a logged-out caller — proves the check is on the server, not a hidden button
|
||||
- [ ] Every object fetched by id is scoped to the caller, and every list endpoint returns only that caller's rows — proves no IDOR, and that a response is not quietly serving the whole table
|
||||
- [ ] Every privileged route checks a role rather than a session — proves *authenticated* has not been mistaken for *permitted*
|
||||
|
|
@ -42,7 +46,7 @@ unstated gets skipped the first time it is inconvenient.>
|
|||
|
||||
- [ ] No secret in the built client bundle, not merely none in the repository — proves the scan reached the artifact users actually receive
|
||||
- [ ] Session tokens in `HttpOnly` cookies rather than `localStorage` — proves one XSS is not an account takeover
|
||||
- [ ] Response headers carry a CSP and a frame policy, and nothing is served over plain HTTP — proves clickjacking and injection meet resistance
|
||||
- [ ] *(only for a deployed service)* Response headers carry a CSP and a frame policy, and nothing is served over plain HTTP — proves clickjacking and injection meet resistance
|
||||
|
||||
### What a stranger can learn or exhaust
|
||||
|
||||
|
|
@ -52,7 +56,7 @@ unstated gets skipped the first time it is inconvenient.>
|
|||
### The compliance bar, which is not the launch bar
|
||||
|
||||
- [ ] There is a record of who changed what, and when — proves the question an auditor or a customer eventually asks can be answered at all
|
||||
- [ ] There is an environment that is not production to test against
|
||||
- [ ] *(only for a deployed service)* There is an environment that is not production to test against
|
||||
|
||||
The last two are a different bar from everything above them. The rest of this
|
||||
list gets a release out of the door; those two get it through the first
|
||||
|
|
|
|||
Loading…
Reference in New Issue