From 063b715c3369384f1838abd94630931cc3a8c00a Mon Sep 17 00:00:00 2001 From: null Date: Mon, 17 Aug 2026 22:55:56 -0500 Subject: [PATCH] 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) --- docs/DOC_TRUST_MAP.md | 31 +++++++++++++++++++++++++++++ docs/security/SECURITY_CHECKLIST.md | 8 ++++++-- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/DOC_TRUST_MAP.md b/docs/DOC_TRUST_MAP.md index 71b8864..bee1c16 100644 --- a/docs/DOC_TRUST_MAP.md +++ b/docs/DOC_TRUST_MAP.md @@ -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 diff --git a/docs/security/SECURITY_CHECKLIST.md b/docs/security/SECURITY_CHECKLIST.md index 5ae6e69..e2c25b6 100644 --- a/docs/security/SECURITY_CHECKLIST.md +++ b/docs/security/SECURITY_CHECKLIST.md @@ -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