docs: make the repo carry the audit state a new session needs - #10
Merged
Conversation
Wave 2 will be picked up in a fresh session, so the context it needs has to live
in the repository rather than in a conversation.
Adds `docs/audit-remediation-status.md` as the entry point for audit work, and
points `CLAUDE.md` at it. It records what is merged (Waves 0, 1 and most of 3,
DECISIONS §36–§43), the measured corpus baseline, exactly what each Wave 2 item
requires with file and line references, and the traps this codebase has for
anyone changing it — hazard-pinning tests that fail on purpose, `baseline.json`
assertions that are equality rather than floors, item ids being content-derived
but preserved, and the MCP transport's `StringDecoder` that must not be
"optimised" into manual concatenation.
It replaces status prose rather than adding to it (audit M11 counts documentation
at 4.1:1 against source).
`CLAUDE.md` corrections. Each of these was load-bearing — other notes in the same
file reason from them:
- "`token-hashing` is whole-item and `createContextBundle` makes a single-item
bundle for CLI/bench, so `R_AST` is a boolean" — false on both halves since
§43. Region elision is preferred, whole-item elision of a symbol-bearing item
is now refused outright, and `optimize` builds one item per file.
- "For code, `R_struct` is pinned at 1.0 — the only marker is `filepath:`" —
fixed by §40, with the note that the audit's proposed fix for it was measured
inert on its own, because an empty marker set defaults the ratio back to 1.0.
- Invariant 9's rationale restated: `emittedOutput` is no longer a
newline-joined blob but a delimited envelope. The invariant is unchanged —
neither form is a valid provider payload — only the reason given for it.
- The 19.27% figure marked as belonging to a smaller corpus, with a pointer to
the recorded baseline instead of a remembered number.
- `Commands` lists the multi-file and directory forms.
Corpus harness: `typescript` expectation 57 -> 59, the two files H5 added
(`src/cli/ingest.ts`, `src/core/render/index.ts`). `collect.js` would otherwise
refuse on the next run, which is it working as designed rather than a fault.
A clean post-wave baseline replaces the eight scattered measurement arms: Python
23.14% file / 22.66% stdin, TypeScript 25.35% file over 59 files, every other
bucket 0.00%. The TypeScript figure is deliberately *not* presented as comparable
to §43's 29.55% — same engine, larger denominator, which is the "this repo is its
own corpus" trap the harness exists to make visible.
No source changes. Typecheck, lint and 525/525 tests unaffected.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Preparation for picking up Wave 2 in a fresh session. No source changes — typecheck, lint and 525/525 tests unaffected.
Why
Wave 2 will be started in a new session, so the context it needs has to live in the repository rather than in a conversation. Three things stood in the way:
CLAUDE.mdasserted things that Waves 1–3 made false, the corpus harness would refuse to run, and the audit status was scattered across DECISIONS entries.docs/audit-remediation-status.md(new)The entry point for audit work, pointed at from
CLAUDE.md:dd540feIt replaces status prose rather than adding to it — audit M11 counts documentation at 4.1:1 against source.
CLAUDE.mdcorrectionsEach was load-bearing, because other notes in the same file reason from them:
createContextBundlemakes a single-item bundle for CLI/bench, soR_ASTis a boolean"R_structis pinned at 1.0 — the only marker isfilepath:"emittedOutputis a newline-joined blob"Commandsalso lists the multi-file and directory forms.Corpus harness
typescriptexpectation 57 → 59 — the two files H5 added (src/cli/ingest.ts,src/core/render/index.ts).collect.jswould otherwise refuse on the next run, which is it working as designed.A clean post-wave baseline replaces the eight scattered measurement arms:
That 25.35% is deliberately not presented as comparable to §43’s 29.55%. Same engine, larger denominator — the "this repo is its own corpus" trap the harness exists to make visible.
Also done outside this PR
Deleted the eight merged branches (
audit-*,phase-*). Two of them —audit-c1bandaudit-gateway— were not ancestors ofmainbecause #5 and #6 merged into them after they had already gone upstream; verified both held no unique content before removing them.originnow hasmainonly, plus this branch.🤖 Generated with Claude Code