docs: point every numbered-ADR reference at docs/adr - #211
Merged
Merged
Conversation
buildFactoryExecutionPlan pushed RedesignIntegrityReceiptStage after
ReleaseReceiptFinalizerStage and HandoffEmitterStage. For an end-to-end
REDESIGN_IMPROVE run the emitted order was:
... visual-qa, release-receipt-finalizer, handoff-emitter,
redesign-integrity-receipt, terminal-convergence
The finalizer writes status: "succeeded" to the release receipt and the
emitter performs the external POST to SEO-Bot plus recordWebsiteRelease
(externalMutation: true). A gate in that position can only reject a run
that has already been recorded as successful and handed off — it cannot
prevent one. An invalid redesign was therefore publishable.
The gate now runs after visual-qa, whose ctx.qualityEvidence.visualQa it
reads, and before the finalizer and emitter. It stays outside the
end-to-end guard on purpose: REDESIGN_ADDED_MANDATORY makes
redesign-integrity-receipt mandatory in every mode, so folding it into
that branch would make requireMandatoryConvergence throw on plan,
local-proof and publish-proof redesign runs.
No stage, receipt type, or handoff contract is added — this is a reorder.
The gate reads only context produced upstream of its new position and
declares no evidence block, so it imposes no runner ordering constraint.
The COPY end-to-end stage list is unchanged; the existing deepEqual
assertion in tests/unit/factory-execution-plan.test.ts passes unmodified.
Two intended consequences:
- On the visual-QA-not-passed path a redesign end-to-end run now fails as
REDESIGN_PIPELINE_INCOMPLETE rather than RELEASE_EVIDENCE_INCOMPLETE.
That is the fail-closed-earlier behaviour, not a regression.
- executed_stages in the emitted receipt no longer lists
release-receipt-finalizer or handoff-emitter, since it snapshots
ctx.stageResults at emit time. Nothing validates that field.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
…plan The durable path computed ctx.buildIntent from the spec and then built its execution plan without it, so buildFactoryExecutionPlan always derived redesign === false there. A REDESIGN_IMPROVE spec submitted through Inngest therefore ran the COPY topology: no seo-build-intelligence-preflight, no competitive-intelligence, the legacy content/schema stages instead of the redesign authority chain, and no redesign-integrity-receipt stage at all. The build context said one thing and the plan built another. This also bounds the preceding commit. Reordering the integrity gate ahead of the finalizer and emitter fixes the plan builder, but on this path the gate was never in the plan to begin with, so that fix would have been inert here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
There was no regression coverage for the terminal ordering of a redesign
plan. The two existing REDESIGN_IMPROVE tests assert only the head of the
pipeline (preflight before competitive-intelligence, competitive-intelligence
before design-intelligence), and redesign-integrity-receipt.test.ts asserts
that the stage is present, not where. All of them passed with the gate sitting
after the finalizer and the external handoff.
This asserts the chain that actually matters:
visual-qa < redesign-integrity-receipt < release-receipt-finalizer
< handoff-emitter < terminal-convergence
Verified to discriminate: against the parent commit's plan builder it fails
(8 pass / 1 fail); against the reordered one it passes (9 pass). A test that
cannot fail proves nothing, so it was run both ways before being committed.
The COPY end-to-end deepEqual assertion is deliberately left untouched — it
is the byte-identity guard proving the reorder did not disturb the non-redesign
topology, and editing it would destroy the evidence.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
executed_stages and the STAGES list that drives synthetic checkpoint timestamps both hard-code the pipeline's terminal order as static data rather than deriving it from buildFactoryExecutionPlan. They still carried the pre-fix tail, with redesign-integrity-receipt trailing the finalizer and the handoff emitter. Nothing fails as a result — the golden oracle checks a relative ordered subsequence that omits both of those stages, so it is satisfied by either order. That is precisely the problem: the fixtures would have gone on describing an ordering the code no longer has, and a reviewer re-deriving a fixture would have been misled by it. Data-only; no generator logic changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
validation/validation_report.yaml is per-run output of scripts/validation-executor.ts, but it was tracked. Every `npm run site:validate` — and therefore every `verify:all` and every `make pr` — rewrote it with a fresh run_id, fresh timestamps, the local absolute target_roots and the running user's git identity. That is not cosmetic. It hard-blocks the sanctioned publish path: the L4 release receipt is bound to a tree digest, so `make pr` runs `pr-check`, `pr-check` dirties this file, and the L4 remote check then rejects the push as a stale receipt. The gate invalidates the authorization it is about to verify, and no amount of re-authorizing escapes it, because the next run dirties the tree again. Untracking it is the repo's own established convention, not a new one: .gitignore already ignores validation/launch_env_report.json and validation/deploy_secrets_report.json, which are the same class of per-run artifact from the same directory. Nothing consumes the committed copy. scripts/validation-executor.ts only writes it, no test or script reads it, and build-and-validate.yml generates its own at the repository root and uploads that as a workflow artifact. The file stays on disk; only the index entry is removed. As a side benefit the committed copy stops leaking one contributor's worktree path and email address into the repository. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
This repo is npm-only: .github/workflows/l9-lint-test.yml and l9-lint-test-node.yml both pin PACKAGE_MANAGER="npm", regen-lockfile.yml knows only `npm install --package-lock-only`, and four package-lock.json files are tracked. .gitignore carried no lockfile entries at all, so a stray pnpm-lock.yaml sat untracked and committable. It is container debris — never tracked on any ref, and its mtime matches every other file in the clone rather than any commit. Left unignored it is one `git add -A` away from landing, and the dormant pnpm/yarn arms of the lint workflows would treat it as load-bearing the moment PACKAGE_MANAGER moved. Appended at end of file rather than in the secrets block: PR #207 deletes .gitignore:41, and a hunk there would overlap one written nearby. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L (cherry picked from commit 3bf384caca440a43d4e5466957c671b35c353057)
`evidence/` was unanchored, so it matched a directory of that name at any
depth. `git ls-files -ci --exclude-standard` therefore reported 255 tracked
files as ignored, and 148 of those were not debris at all:
- src/pipeline/evidence/*.ts — 21 files, the pipeline's evidence layer
(EvidenceStore, ReleaseReceipt, RedesignExecutionIntegrityReceipt, ...)
- docs/reports_and_test_results/**/evidence/** — 127 files, dated report
bundles someone committed deliberately
Nothing was broken while they stayed tracked, because .gitignore does not
apply to files already in the index. The hazard is the cleanup: a
mechanically derived `git rm --cached $(git ls-files -ci)` would have
untracked the pipeline's evidence layer, and local validation would still
have passed because the files remain on disk. Only a fresh clone would have
failed.
Anchoring to /evidence/ confines the rule to the repository root, which is
where the Safe Haven per-run evidence it was written for actually lives. The
count drops 255 -> 107, and every remaining entry is genuine generated
output.
This lands as its own commit, before any untracking, so the delete list in
the next commit can be derived mechanically from a rule that is already
correct.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
105 files whose directories .gitignore already names, but which were added
to the index before or despite those rules. Ignore rules do not apply to
tracked files, so they kept accumulating:
- build/** 99 files across 61 golden run directories (~9.2 MB): 62
pipeline.log files and 20 PNG captures, several over 1 MB. .gitignore:12
says `build/` and README.md:193 says the same in prose.
- evidence/** 4 files. .gitignore:45 names the directory as per-run Safe
Haven output.
- astro_template/validation/*.jsonl 2 files, named at .gitignore:23.
Write-only: nothing reads them.
The list was derived mechanically from `git ls-files -ci --exclude-standard`
rather than hand-written, which is what makes a 105-file delete reviewable —
it is exactly the set git itself reports as tracked-but-ignored. That is only
safe because the preceding commit anchored `evidence/`; run against the old
rule the same command would have removed src/pipeline/evidence/*.ts.
Two entries are excluded deliberately, both tracked on purpose:
- .l9/ci.json, re-included by `!.l9/ci.json` as the consumer-owned CI class
declaration org-ci.yml reads
- tests/golden/safehaven/fixtures/positive-receipt.json, which
tests/golden/safehaven/RUNBOOK.md documents as a built fixture
Index-only: every file stays on disk and regenerates from its own tooling.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
Four files, none referenced by any script, test, workflow or document.
Root run-artifacts, captured from one local run and committed:
- validation_node_check.txt — 0 bytes, the only empty tracked file in the
repository
- validation_command_results.txt — 30 bytes, entirely
`verify_launch_env_exit_code=1`
- launch_env_fail_closed_output.json — a dated per-run report
(timestamp_utc 2026-06-13). .gitignore:21 already ignores
validation/launch_env_report.json, the same class of artifact from the
same tool; this one just happened to be written at the repository root
instead.
docs/recursive_optimization_report.md — a duplicate. docs/archive/ holds a
copy with different content that was archived deliberately in #125 and is
listed in docs/archive/README.md against ADR-0017. This root copy carries no
archive banner, is referenced by nothing, arrived incidentally in an
unrelated llm-router commit, and opens by naming a path that does not exist
in this repository:
## Artifact Group: /home/ubuntu/l9-website-bot (full repo)
The archived copy is the one the index points at and is untouched.
ROOT_FILE_VALIDATION.md is deliberately NOT updated. Its "Files in final
pack: 19" counts a curated documentation pack rather than tracked root files
(the real root count was already 35 before this commit), and none of the
files removed here are enumerated in it. It is a dated point-in-time record;
editing its numbers to match today would falsify it rather than correct it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
Audit finding F4. The numbered ADR series lives in docs/adr/, and
ARCHITECTURE.md:7 says so — "That directory is the only canonical ADR
location". Eighteen references across ten files said otherwise, and fourteen
of them were not merely misleading but dead: every
docs/architecture/ADR-XXXX-*.md target was verified absent. docs/architecture/
holds four design notes and no numbered ADR at all.
Dead links repointed (docs/architecture/ADR-* -> docs/adr/ADR-*): the five
archived-doc banner lines under docs/archive/, the five-row extraction table in
docs/archive/README.md, TODO.md:49 and :51, and MANIFEST.md:30 — the last
being the worst of them, since MANIFEST.md presents that block as the overlay's
file inventory and so asserted the existence of a file the repository does not
contain. All nine distinct targets now resolve; zero dead.
Prose pointers corrected:
- ARCHITECTURE.md:67 contradicted its own line 7, sixty lines apart
- AGENTS.md:5 — the highest blast radius of the set: the Mission line calls
itself "binding guidance for AI coding agents", so every agent entering
this repository was handed the wrong ADR home in its first instruction,
while AGENTS.md:74 cited docs/adr correctly
- README.md:198 named docs/architecture as the ADR home and omitted
docs/adr from the repository layout entirely, so a README reader could
not learn the canonical directory exists
- docs/archive/README.md:4 said "the numbered ADRs under docs/architecture/"
- MANIFEST.md:12
- docs/adr/README.md:4 forbade adding ADRs under `adr/`, which reads as
forbidding the very directory it declares canonical; the intended referent
is SEO-Bot's adr/ series, now named explicitly
Also indexes ADR-0019-client-design-reference-...md, an accepted 8.7 KB
decision record that was missing from docs/adr/README.md's table and therefore
undiscoverable from the canonical index. It collides on number with
ADR-0019-retire-five-push-campaign-pack.md; the collision is flagged in place
rather than resolved, because renumbering is an ADR decision and the losing
document's inbound references move with it.
Pointers only. No ADR is moved, renumbered or created, and no third authority
location is introduced.
Nothing in the verify:all chain validates documentation links, which is how
eighteen of them drifted undetected. Worth adding.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Both hard-coded stage lists in the safehaven fixture builder went seo-build-intelligence-preflight -> competitive-intelligence, skipping design-reference-acquisition. The real REDESIGN_IMPROVE plan puts it between those two (FactoryExecutionPlan.ts:275-279), and it is listed in REDESIGN_ADDED_MANDATORY, so it is mandatory for every redesign run in every mode. The fixture declares mode: "end-to-end" with build_intent: "REDESIGN_IMPROVE" and claims to represent a green run of exactly that plan, so a stage the plan cannot omit was missing from the record. executed_stages fed the emitted receipt and STAGES drives the synthetic checkpoint files and the SQLite stage_runs rows, so both the receipt and the simulated stage history described a run that could not occur. Verified against the plan builder rather than by eye: an end-to-end REDESIGN_IMPROVE plan emits ["seo-build-intelligence-preflight", "design-reference-acquisition", "competitive-intelligence"] at that point, which is now what both lists contain. Found by Copilot's review on the stacked PR #210. It is a pre-existing gap rather than one the preceding fixture commit introduced — that commit corrected the tail of these lists — but the file is this PR's to get right, and a fixture that misdescribes the pipeline is worse than no fixture. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
There was a problem hiding this comment.
🟡 Changes recommended
The docs index has an incorrect ADR date entry and the PR’s stated “documentation only” scope does not match the non-doc code/artifact changes currently included in the diff.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
This pull request primarily repoints documentation references so numbered ADR links consistently target docs/adr/ (the canonical ADR location), and updates related prose to distinguish numbered ADRs from non-ADR design notes. However, the current diff also includes non-doc changes (pipeline execution-plan ordering and Inngest plan wiring) plus removal/ignoring of generated artifacts, which makes the PR’s stated “docs-only” scope inaccurate as currently presented.
Changes:
- Update ADR links and prose across repo docs to consistently reference
docs/adr/(and clarifydocs/architecture/as design notes). - Add/adjust pipeline execution-plan behavior and tests (redesign integrity gate ordering; pass
buildIntentinto plan building on durable path). - Remove and/or newly ignore various generated artifacts (validation reports, golden build outputs, evidence artifacts, astro_template validation JSONL).
File summaries
| File | Description |
|---|---|
TODO.md |
Repoints ADR links from docs/architecture/ to docs/adr/. |
README.md |
Updates repository layout description to reflect docs/adr/ as canonical ADR directory and clarifies docs/architecture/. |
MANIFEST.md |
Repoints Release Evidence Spine ADR path to docs/adr/. |
ARCHITECTURE.md |
Corrects “Architecture decisions” section to point to docs/adr/ and distinguishes design notes. |
AGENTS.md |
Fixes mission statement to reference ADRs in docs/adr/. |
docs/archive/README.md |
Updates archived-doc index links to ADRs under docs/adr/. |
docs/archive/autonomy-architecture.md |
Updates archived banner link to the living ADR under docs/adr/. |
docs/archive/factory-upgrade-build-plan.md |
Updates archived banner link to the living ADR under docs/adr/. |
docs/archive/image-asset-pipeline.md |
Updates archived banner link to the living ADR under docs/adr/. |
docs/archive/release-evidence-spine-build-spec.md |
Updates archived banner link to the living ADR under docs/adr/. |
docs/archive/recursive_optimization_report.md |
Updates archived banner links to ADRs under docs/adr/. |
docs/adr/README.md |
Updates canonical-location wording; adds missing ADR-0019 entry and flags number collision; (currently) leaves one ADR date blank. |
src/pipeline/FactoryExecutionPlan.ts |
Reorders end-to-end stages so redesign integrity gate runs before success finalization and handoff. |
src/inngest/website-pipeline.ts |
Passes ctx.buildIntent into buildFactoryExecutionPlan on the durable path. |
tests/unit/factory-execution-plan.test.ts |
Adds regression test asserting redesign integrity gate ordering relative to finalization/handoff. |
scripts/golden-safehaven/fixtures/build-fixtures.mjs |
Updates golden fixture stage ordering to match the updated execution plan. |
.gitignore |
Ignores validation/validation_report.yaml, anchors /evidence/ ignore to repo root, and ignores non-npm lockfiles. |
validation/validation_report.yaml |
Removed generated validation report from repo history (now gitignored). |
validation_command_results.txt |
Removed generated artifact. |
validation_node_check.txt |
Removed generated artifact. |
launch_env_fail_closed_output.json |
Removed generated artifact. |
docs/recursive_optimization_report.md |
Removed duplicate/out-of-place doc (archived copy remains under docs/archive/). |
evidence/golden-positive-control.json |
Removed generated evidence artifact. |
evidence/golden-negative-controls.json |
Removed generated evidence artifact. |
evidence/synthetic-real-mode-rejection.json |
Removed generated evidence artifact. |
astro_template/validation/preflight_checks.jsonl |
Removed generated astro_template validation output (pattern already gitignored). |
astro_template/validation/source_checks.jsonl |
Removed generated astro_template validation output (pattern already gitignored). |
build/golden/golden-20260825-r61/GOLDEN-REPORT.md |
Removed generated build artifact (under build/, now treated as generated). |
build/golden/golden-20260825-r61/candidate-serve.log |
Removed generated build artifact. |
build/golden/golden-20260825-r61/golden-oracle-result.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/site-integrity.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/visual/manifest.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/visual/aggregated/aggregate.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/seo-bot-evidence/fetch-meta.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/seo-bot-evidence/health.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/seo-bot-evidence/identity-snapshot.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/seo-bot-evidence/missing.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/seo-bot-evidence/preflight.json |
Removed generated build artifact. |
build/golden/golden-20260825-r61/seo-bot-evidence/sequence.json |
Removed generated build artifact. |
build/golden/golden-20260824/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r2/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r3/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r4/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r12/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r13/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r27/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r35/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r36/pipeline.log |
Removed generated build artifact. |
build/golden/golden-20260824-r37/pipeline.log |
Removed generated build artifact. |
Review details
- Files reviewed: 15/127 changed files
- Comments generated: 3
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…hygiene-untrack-generated-v2
…audit-f4-adr-pointers
Both from Copilot's review on #211, both correct. The index row for ADR-0019-client-design-reference-... carried "—" for its date. The ADR declares `## Date 2026-09-03`. I indexed that file without reading its date field, and an index that invents an unknown where the source states a fact is worse than the omission it replaced. README.md:198 read "numbered Architecture Decision Records — the canonical decision record", which describes a directory as though it were a single record. It is the canonical ADR directory. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
Audit finding F2 of website-bot-all-open-prs-2026-09-17, against this PR. docs/reports_and_test_results/08-18-2026/GOLDEN_E2E_FINAL_REPORT.md is a retained report that cites two artifacts as its evidence — and calls them "never hand-edited" and "never edited by hand", which is the whole point of citing them: build/golden/golden-20260825-r61/pipeline.log build/golden/golden-20260825-r61/golden-oracle-result.json This PR untracked both as generated output under build/, so the report's evidence trail resolved to nothing. Before untracking I checked that no script, test or workflow READS those files, and none does. I never checked whether a retained document CITES them, which is exactly what a golden-run proof report does. That was the gap. Both are relocated verbatim from origin/main into evidence/ beside the report that depends on them, and the three citations are repointed. Byte-identity is the property that matters here, so it was verified rather than assumed: the recovered files hash to 3b52732 and eeba265, the same blobs origin/main carries. A regenerated substitute would have satisfied the link and destroyed the claim. docs/reports_and_test_results/**/evidence/ is the existing home for this (08-15-2026 already uses it) and is tracked again since this PR anchored the `evidence/` rule, so no new evidence location is introduced. .gitignore needed one addition: `*.log` at line 11 matches at any depth, so the relocated pipeline.log was silently not staged. `git add -f` would have tracked it while leaving it ignored — precisely the tracked-but-ignored state this PR exists to eliminate, and how 255 files accumulated in the first place. The negation instead follows the repo's own precedent for retained logs (!reports/test-runs/**/*.log) and is scoped to report evidence: build/, root evidence/ and astro_template/ stay ignored, and `git ls-files -ci` still returns only the two deliberate re-inclusions. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Hmr3SKRhYQ56omTzNFZ4L
This was referenced Sep 18, 2026
…audit-f4-adr-pointers
|
20 tasks
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
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.
Summary
Closes audit
website-bot-core-pipeline-2026-09-17finding F4. The numbered ADR series lives indocs/adr/, andARCHITECTURE.md:7says so — "That directory is the only canonical ADR location." Eighteen references across ten files said otherwise, and fourteen were dead links: everydocs/architecture/ADR-XXXX-*.mdtarget was verified absent.docs/architecture/holds four design notes and no numbered ADR at all.Type of change
type:docs— documentation onlyArea
area:backend— src/, packages/ (closest available; this PR is documentation only and has no runtime surface)Checklist
npm run verify:allpasses locallynpx tsc --noEmitpasses (no type errors)VALIDATION.mdupdated — not applicableDECISION_LOG.mdupdated — not applicableReading this PR
Stacked on #210; it shows 10 commits and only the last is this PR's (
2f95707). The chain is #208 → #209 → #210 → this, each cut from the previous head because each needs #208'svalidation/validation_report.yamluntracking in order to publish at all. Once the parents merge, this diff collapses to its single commit.Dead links repointed
docs/architecture/ADR-*→docs/adr/ADR-*in: the five archived-doc banner lines underdocs/archive/, the five-row extraction table indocs/archive/README.md,TODO.md:49and:51, andMANIFEST.md:30.MANIFEST.md:30was the worst of them — that block is presented as the overlay's file inventory, so it asserted the existence of a file this repository does not contain.All nine distinct link targets now resolve; zero dead.
Prose pointers corrected
ARCHITECTURE.md:67AGENTS.md:5AGENTS.md:74citeddocs/adrcorrectlyREADME.md:198docs/architectureas the ADR home and omitteddocs/adrfrom the repository layout entirely, so a README reader could not learn the canonical directory existsdocs/archive/README.md:4docs/architecture/"MANIFEST.md:12docs/adr/README.md:4adr/— which reads as forbidding the very directory it declares canonical. The intended referent is SEO-Bot'sadr/series, now named explicitlyOne judgment call — needs your decision
ADR-0019-client-design-reference-acquisition-and-run-bound-intelligence-persistence.mdis an accepted 8.7 KB decision record that was missing fromdocs/adr/README.md's index, so it was undiscoverable from the canonical table. It is now listed.It collides on number with
ADR-0019-retire-five-push-campaign-pack.md. I flagged the collision in the index rather than silently listing a duplicate number as though it were fine: a bare citation of "ADR-0019" is ambiguous, and the next author reading that table will assign ADR-0020 and bake the clash in permanently. Renumbering is an ADR decision, not a pointer fix — whichever document is renumbered takes its inbound references with it, so it is deliberately left to a human.Recommended follow-up
Nothing in the
verify:allchain validates documentation links. That is how eighteen of them drifted undetected, and it is why fixing them by hand today does not stop it recurring. A link-check step would.Verification
npm run verify:allpasses on2f95707. Everydocs/adr/ADR-*and../adr/ADR-*link target was checked to resolve on disk (9 resolve, 0 dead), and a repository-wide grep confirms nodocs/architecture/ADR-reference survives outside the untracked local planning artifacts.Publication note
make prran the full gate — L4 release check,pr-check, main-bound ancestry and the overlap probe — and pushed this branch. It could not compose the PR body:open_pr_after_gate.shrequiresops/config/root-file-protection.jsonunder the workspace root, and Website-Bot has noops/directory. Same consumer-side governance wiring gap as #208, #209 and #210.Generated by Claude Code
Correction — stack topology (audit
website-bot-all-open-prs-2026-09-17, F3)An earlier version of this description claimed a linear chain
#208 → #209 → #210 → #211. That was wrong, and Git disproves it. Verified withgit rev-list --left-right --count:#210 was cut from #208's head, not #209's, so it never contained #209's normalizer delta. The accurate dependency model is:
#209 and #210 do not require a linear relationship with each other.
#209 is additionally one commit behind #208 — it lacks the fixture fix
f67f02d, which I merged forward into #210 and #211 but not #209, while stating it had reached all of them. #209 does not touchbuild-fixtures.mjs, so nothing there is functionally wrong; the claim was simply inaccurate. #209 should be refreshed against #208 once that lands.Generated by Claude Code