docs(prd): v0.4 addendum resolving INTEGRITY-AUDIT D-02 / D-03 / D-06

[OM152002]

Closes #68. Branched from main; docs-only, independent of #89/#91/#92/#93.

A new agent opening PRD v0.2 today reads an accepted document telling them the test-bed is Grafana Cloud and the commercial anchor is Datadog. Both were superseded — and the PRD's own Open questions already concede it, in the same file as the stale text. That is not a fix: the stale document is the one people open.

The v0.2 body is unedited

docs/prd/PRD-trajectory-cache-v0.2.md | 10 ++++++++++
1 file changed, 10 insertions(+)      <- zero deletions

Every one of those ten lines is a redirect banner. No original sentence, number or verdict was changed. Rewriting an accepted document would destroy the audit trail that makes the two FAILs credible — the same reason the pivot brief superseded §8 by pointer rather than editing it.

A judgement call worth flagging for review: the issue says "do not edit the v0.2 body", and also that a reader landing on §8 or §9 must be redirected "before they can act on stale content". A top-of-file banner alone does not catch someone arriving via an anchor link. I added a one-line redirect immediately under the ## 8. and ## 9. headings as well — additive, clearly marked editorial, no claim touched. If you read the constraint more strictly, those two lines are the ones to drop; the top banner and frontmatter superseded_by stand on their own.

D-02 — the redirect table

PRD §8 says	Actually	Authority
Test-bed Grafana Cloud	Self-hosted Grafana OSS, eight pinned versions	ADR-0003
Anchor Datadog	No commercial anchor exists	A8 census FAIL — 2 survivors, 51 killed as FULLY_API
Gate task: install integration → alert rule	Build and save a TestData Stat dashboard, 12 steps	ADR-0006
Backup vertical: security-review portals	No vertical is locked	ADR-0004 (Track-2 FAIL)

A reader should leave §8 knowing there is no anchor, not guessing at one.

D-03 — resolved as a status label, not a number

The §9 thresholds are PROPOSED and UNVALIDATED. No document may cite them as accepted gates, as measured results, or as evidence the thesis holds or fails.

The addendum deliberately does not pick different numbers. D-03 is not a disagreement about what the thresholds should be — it is a disagreement about their status, and inventing a value here would be exactly the category-B failure the audit exists to catch.

It also answers the part the issue asked for: who accepts them (the founder — owner: founder on the PRD) and when (gate-memo time, on the first measurement clearing §9's own sampling protocol of ≥42 runs / ≥400 step-executions). Accepting a threshold before there is a measurement to test it against would make the gate unfalsifiable.

The kill-line question answers itself

The pivot brief's open questions ask which document controls: §9's four-part gate, or the pivot's single "~50%". It is answerable from the pivot brief itself, and the answer is §9. Three pieces of evidence, all in that document:

1. §5 states it outright — "Gate: unchanged from §9."
2. Its §7 supersession table enumerates what it replaces. Decision 2 is "§8 selection rule — Replaced". §9 appears nowhere in that table, matching its frontmatter (supersedes: … §8).
3. The "~50%" is introduced as "Kill condition, restated" and carries both of §9's kill clauses — < ~50% validity and repair cost ≈ fresh-reasoning. A document proposing a competing single-number gate would not reproduce the other document's second clause.

So the precedence rule is stated for the gate memo: §9 is the gate specification; the pivot's "~50%" is shorthand for §9's kill half; the pivot's framing governs how the number is obtained, not what it must clear. This had to be settled before the memo is written, or the memo argues with the spec while reporting the number.

D-06 — historical, and stricter than written

§8's "~6 survivors" was never the operative rule; A8 and C5 both applied ≤2. Worth stating plainly: the executed line was stricter, so both searches would have failed under either. It is a documentation defect, not a decision defect.

What this does not close, named rather than skipped

• Whether the §9 threshold values stay binding after two vertical FAILs — the founder's call, and PRD v0.2's own first open question. This addendum fixes the label, not the level.
• D-01 / D-05 / D-07 / D-08 — each with a reason. D-01 needs the deck walked and is FOUNDER-marked; I did not read those files and the addendum's authority comes from not overreaching into files it did not read.

Also raised as a new open question: whether "task-level success ≥ 90%" is reachable at all on a 12-step task that ADR-0006 predicts compiles to 5 strong / 7 weak assertions. That could make a §9 gate unreachable for reasons unrelated to the thesis.

Verification

docs/INTEGRITY-AUDIT.md marks D-02, D-03, D-06 resolved with links, and the category-D count now reads 8 (5 resolved) — matching the existing convention on category E rather than deleting rows.

Anchors checked by hand. lint:docs validates link targets but not fragments — I found that gap reviewing #79 — and a dead anchor in a documentation-integrity PR would be self-refuting. Every link and #fragment across all four changed files resolves against the actual heading slugs.

Reader-side test from the issue: walking v0.2 from the top hits the banner at line 14; landing directly on ## 8. or ## 9. hits a redirect on the next line.

npm run ci            # green — lint-docs clean (45 docs), secret-scan clean, 109 unit, 1 integration
npm run test:canary   # 6 pass

🤖 Generated with Claude Code

[myselfsiddharth]

Code review

This is a docs-only PR, so I reviewed it the way its own content demands: by fact-checking the claims against the actual source documents rather than trusting the PR body, and by programmatically verifying every link and cross-document #fragment rather than spot-checking.

Overview

Closes #68. Resolves INTEGRITY-AUDIT D-02 (Critical), D-03 (High), and D-06 (Medium) by adding a new docs/prd/PRD-v0.4-addendum.md rather than editing the accepted PRD v0.2 body — the v0.2 diff is 10 insertions, 0 deletions, confirmed: every changed line in that file is a superseded-banner or frontmatter pointer, no original sentence, number, or verdict touched.

Claims verified against source, not taken on faith

I pulled the actual referenced documents at this PR's merge-base and checked every substantive claim in the new addendum against them:

• D-02's redirect table (test-bed, anchor, gate task, selection rule, vertical lock, survivor line) — all six rows checked against ADR-0003, A8-DECISION.md, ADR-0006, pivot-brief-v0.3.md §3, and ADR-0004. All accurate.
• D-03's §9 quote — the addendum's condensed restatement of the four §9 gates matches PRD v0.2 §9 verbatim in substance. owner: founder on the PRD frontmatter is exactly right, and "this addendum fixes the label, not the level" tracks PRD v0.2's own first open question, quoted correctly.
• The kill-line precedence argument (§3 of the addendum) — I checked all three pieces of evidence directly against pivot-brief-v0.3.md: §5 does say "Gate: unchanged from §9" verbatim; the §7 decision table's Decision 2 is exactly "§8 selection rule — Replaced" with no §9 row; and "Kill condition, restated" does carry both of §9's kill clauses (< ~50% validity, repair cost ≈ fresh-reasoning). The argument holds up, and it's answering a question the pivot brief's own Open Questions section genuinely leaves open — I checked that too.
• D-06's "historical, stricter" claim — A8-DECISION.md states its gate threshold as "≤2 survivors → FAIL" outright (not "~6"), confirming the addendum's framing that the executed line was always stricter than §8's written "~6", so no outcome changed.
• The "8 (5 resolved)" category-D count — counted by hand against the full post-PR table: D-02, D-03, D-04, D-06, D-07 all carry "Resolved" somewhere in their row (D-04 and D-07 were already resolved by earlier PRs, unchanged here). 5 of 8. Arithmetically correct, and it mirrors the existing "(fixed or flagged)" annotation style already used on the category E row rather than inventing a new convention.
• All 75 non-external links across all four changed files, including every cross-document #fragment — wrote a script approximating GitHub's heading-slug algorithm and checked every link in all four files against actual generated slugs (fetched at the PR's commit, not my local main, so the new addendum file was resolvable). Zero broken links or fragments. This directly confirms the PR's own "anchors checked by hand" claim rather than just accepting it — appropriate given the PR is explicit that a dead anchor here would be self-refuting.

I did not find a factual, sourcing, or reference error anywhere in this PR.

The judgment call the author flagged for review

The author explicitly asks for a call on whether the two inline redirect banners placed directly under the ## 8. and ## 9. headings (in addition to the top-of-file banner) go too far, given the issue's "do not edit the v0.2 body" instruction.

I'd keep them. The top-of-file banner alone provably fails the stated goal — this repo cross-links to specific PRD sections elsewhere, so a reader arriving via #8-anchor--first-task... or #9-success-metrics... from another doc never sees it. The inline banners are the only mechanism that catches that reader before they act on stale content, which is the issue's explicit requirement. And this project already has an established, repeatedly-used precedent for exactly this kind of annotation-without-rewriting — I've watched it happen live in this session (architecture.md, gate/runner.md, and this repo's README all get ~~old text~~ **Fixed by #N** edits appended to already-committed docs as things resolve). A clearly-blockquoted, explicitly-labeled "text below unchanged" banner is the same pattern, not a departure from it. The audit-trail concern is about not rewriting substantive claims, not about literally freezing every byte — and zero substantive bytes changed here.

One minor gap, not blocking

docs/prd/README.md — the PRD folder's own local map — lists PRD-trajectory-cache-v0.2.md and pivot-brief-v0.3.md but wasn't updated to add a row for the new PRD-v0.4-addendum.md, even though it lives in that same folder. This won't fail lint:docs (that only enforces docs/README.md's top-level index, which was correctly updated), so it's not a build risk — just a small local-index completeness gap. One line to fix; not worth a tracked issue for something this trivial.

Process

CI green (lint-typecheck-test-secrets, docs-only so no test-suite risk). Frontmatter on the new addendum matches CONTRIBUTING's standard exactly (title/doc_type/status/owner/created/updated/confidence/supersedes/sources_verified), and it ends with a real, non-perfunctory "Open questions" section that correctly identifies what it does not resolve (D-01/D-05/D-07/D-08, the §9 values question, and a new, genuinely useful catch — whether "task-level success ≥ 90%" is even reachable given ADR-0006's own 5-strong/7-weak assertion mix).

---

Verdict: Merge

---

🤖 Reviewed with Claude Code