Context
The official site for saw is being built in a separate repository. Its copy guidance is,
deliberately, to lead with strengths and not to volunteer shortfalls — the normal and correct
register for a public landing page.
The tool's own user-facing text is governed by the opposite obligation, and for good reason:
fail closed, warn loudly, and say exactly what a verdict does and does not cover.
Both are right in their own domain. Nothing in this repository currently writes down that they
are different domains.
The risk
A future contributor — or an AI agent working from the marketing brief, a CHANGELOG entry about
"findings say the same things in fewer words", or simply good instincts about concision — could
carry the marketing register into the codebase, soften or delete a disclosure, and reasonably
believe they were following house style. There would be nothing to point at to say otherwise.
This is not hypothetical for this codebase: brevity passes have already, correctly, touched exactly
these strings.
Surfaces this protects
All of these are our own code and docs, and all are already public:
saw scan's host note — that a clean repository scan is not a host all-clear.
saw audit's scope note, and its withholding of the all-clear when the start-up surface could not
be established.
- The "what
saw audit does not scan" table in docs/how-to/audit-a-machine.md.
- Exit
2 and exit 3 semantics — a target that could not be scanned never reads as clean.
Precedent, which is the point
Two recent changes were the right kind of edit, and they show the line already exists in practice
even though it is unwritten:
0.6.1 shortened findings considerably and moved the "does not scan" list into the documentation
— while deliberately keeping the caveat on screen and the link to it in the report.
0.6.2 fixed saw audit stating a rotation all-clear unconditionally a few lines above asking
the reader to confirm something.
Both were judged against an invariant that no document states.
Proposal
State the obligation explicitly, in .claude/skills/saw-overview/SKILL.md alongside the other
safety invariants, and as a line in CLAUDE.md:
User-facing disclosure of scope and uncertainty is a safety invariant, not a tone or brevity
decision. Work that shortens or rewrites user-facing text may change how a disclosure is
worded; it may not remove the claim, weaken a verdict, or move a scope statement off the run
that produced it. External or promotional copy is governed separately and never propagates
inward.
Acceptance
- The obligation is stated in the skill and in
CLAUDE.md.
- A reviewer can cite it by name when a diff shortens a disclosure out of existence.
- No behaviour change, no detection change; documentation and contribution guidance only.
Context
The official site for
sawis being built in a separate repository. Its copy guidance is,deliberately, to lead with strengths and not to volunteer shortfalls — the normal and correct
register for a public landing page.
The tool's own user-facing text is governed by the opposite obligation, and for good reason:
fail closed, warn loudly, and say exactly what a verdict does and does not cover.
Both are right in their own domain. Nothing in this repository currently writes down that they
are different domains.
The risk
A future contributor — or an AI agent working from the marketing brief, a CHANGELOG entry about
"findings say the same things in fewer words", or simply good instincts about concision — could
carry the marketing register into the codebase, soften or delete a disclosure, and reasonably
believe they were following house style. There would be nothing to point at to say otherwise.
This is not hypothetical for this codebase: brevity passes have already, correctly, touched exactly
these strings.
Surfaces this protects
All of these are our own code and docs, and all are already public:
saw scan's host note — that a clean repository scan is not a host all-clear.saw audit's scope note, and its withholding of the all-clear when the start-up surface could notbe established.
saw auditdoes not scan" table indocs/how-to/audit-a-machine.md.2and exit3semantics — a target that could not be scanned never reads as clean.Precedent, which is the point
Two recent changes were the right kind of edit, and they show the line already exists in practice
even though it is unwritten:
0.6.1shortened findings considerably and moved the "does not scan" list into the documentation— while deliberately keeping the caveat on screen and the link to it in the report.
0.6.2fixedsaw auditstating a rotation all-clear unconditionally a few lines above askingthe reader to confirm something.
Both were judged against an invariant that no document states.
Proposal
State the obligation explicitly, in
.claude/skills/saw-overview/SKILL.mdalongside the othersafety invariants, and as a line in
CLAUDE.md:Acceptance
CLAUDE.md.