docs: publish a condensed public roadmap and retire the dead PRD pointers

[bioedca]

Second PR of the swarm pilot, claimed through the mutex as agent/issue-188, generation
38511096735, held across both authoritative writes.

What was already there

84147af is the inherited checkpoint (86c201d, 2026-07-26): docs/roadmap.md, its nav entry,
the landing-page link, and most of the pointer sweep. The plan recorded it as having spent 91 of the
150-line budget.

What this claimant added

Two mentions of docs/PRD.md were still live in published pages, and they are not the same kind
of thing. That distinction is the whole of the work here.

• docs/adr/0053 §More information pointed a reader at "docs/PRD.md §12.5" as bare text — in a
  list whose neighbouring entry is a link. mkdocs.yml excludes PRD.md from the site, so that
  pointer goes nowhere. Now the absolute blob URL, and it says outright that the site does not serve
  it. ADR records build under not_in_nav, so this was live on the published site.
• docs/agents/review.md names docs/PRD.md in the list of paths whose edits are material,
  beside AGENTS.md, docs/adr/** and .agents/**. That is a rule's operand, not a citation.
  Rewriting it as a hyperlink would misrepresent a glob as a reference. Deliberately left, and
  the guard below encodes the distinction rather than special-casing the file.

mkdocs build --strict cannot catch either: a bare mention is not a link, so nothing warns. That
is precisely why four pages accumulated dead pointers before #188 was filed — and why the sweep is
now a test instead of a grep run once. It pins both directions, so the distinction cannot rot
into "any mention passes".

It also pins what the roadmap must answer, structurally rather than by wording: the three sections
the issue specifies, and at least three explicit non-goals — a floor, since the exact count is
editorial and the floor is the promise.

Verified, not assumed

The roadmap claims v1.0.0-rc1 is the current public version. Checked against the repository:
v1.0.0-rc1 is the newest tag and a published pre-release (2026-07-21), and no stable v1.0.0
exists. The claim is accurate.

Budget — measured, with both findings reported

size:S, budget 150 added lines. scope_guard.py output:

base	added	verdict
84147af the checkpoint	132	0.88× — passes
main	223	1.49× over, charging this claimant for the checkpoint

One advisory finding worth stating rather than leaving to the workflow: from the checkpoint base the
proportional-test rule fires — 130 test lines against a cap of 80, because src_added is 2 (the
single ADR line) and the cap collapses to its floor. That rule is calibrated for code PRs; on a docs
PR whose deliverable is prose, "source lines" is close to meaningless. Reported, not worked around.

Verification

• pytest tests/test_docs_prd_pointers.py tests/test_adr_index.py — 19 passed
• mkdocs build --strict — green, and site/roadmap/index.html exists
• grep -rn 'docs/PRD.md' docs --include=*.md — 4 hits, 3 absolute blob URLs and 1 scope enumeration
• pre-commit run --all-files — green
• claim.py check --generation 38511096735 — held: true

Closes: #188

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: dc884de0-42ce-4082-bade-bdb583b9e955

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[bioedca]

Diff declared final at 2b3b142; all required checks are green. Review round 1 of 2.

Risk is low → Codex.

@codex review

The judgement call in this PR is the thing to attack:

1. Two mentions of docs/PRD.md, treated differently. docs/adr/0053's is a citation and
   became an absolute URL; docs/agents/review.md's is a rule's operand — the list of paths whose
   edits are material — and was deliberately left as a backticked path. If that distinction is
   wrong, the acceptance criterion ("no bare-text pointers remain") is not met and this PR claims it
   is. If it is right but the guard's encoding of it is too loose — _ALLOWED's second pattern
   recognises a scope enumeration by the punctuation around it — then a real dead pointer sitting
   inside a comma-separated list would slip through.
2. The positive fixtures are what make the absence-assertion mean anything. If you can write a
   dead pointer that test_the_guard_reports_a_bare_pointer does not report, the sweep is
   decorative.
3. The roadmap asserts a version. It states v1.0.0-rc1 is the current public version; I checked
   that against the tags and the published releases and it holds today. It is the kind of claim that
   rots, though — worth a second opinion on whether the page should assert a version at all rather
   than pointing at the releases page.

Budget is in the PR body: 0.88× against size:S from the checkpoint base, with the
proportional-test rule firing at 130 test lines against a floor of 80, because a docs PR has almost
no "source" lines for the cap to scale from. Reported rather than worked around.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2b3b142398

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[bioedca]

Round 1 answered at 131b4d4. One blocking finding, and it is the more damaging of the two
failure directions.

A guard that reports nothing while the criterion has regressed is worse than no guard: it turns
unchecked into checked and fine. Recognising a scope enumeration by the punctuation next to the
mention meant an entirely ordinary sentence passed as a rule's operand.

Two conditions now, both load-bearing: the comma-separated element holding the mention must be
exactly a backticked token, and it must keep company with at least two more. Codex's
counterexample is pinned verbatim, plus the parenthesised form and a one-companion case, and the real
list is asserted with the mention in two different positions so the check is not accidentally
sensitive to where it sits.

---

A pilot observation worth more than the fix. This is the fourth rule in this session whose
first formulation was too literal and had to be narrowed:

where	first rule	what it wrongly flagged (or missed)
#304	"no exception may name a direct dtype field"	curation_label, a genuine transform
#306	setuptools<comparator>	the module's own parser, and an f-string echoing it
#305	mention followed by , or )	missed a dead pointer in ordinary prose
#299	"auto-requesting one provider costs two rounds"	contradicted triage.py's own definition

In every case the first version was a pattern over syntax and the correct version was a check on
the construct. Three were caught by a reviewer, one by its own fixtures. That is a repeatable
lesson rather than four coincidences, and it is the strongest argument this pilot has produced for
the review gate being worth its cost.

No further review is requested. Round 1 of 2 is spent; this is the answer to it.