fix(scripts): the doc pointers these tools print name files that exist (TASK-087) - #1805
Merged
Merged
Conversation
…exist (TASK-087)
`scripts/test-discord.sh` printed a "Documentation:" block naming
`docs/TEST_DISCORD_BOT.md` and `docs/design/DISCORD_INTEGRATION.md`; neither
has ever existed at those paths — the Discord docs live under `docs/discord/`.
`scripts/setup-demo.sh` pointed at `docs/yc/DEMO_RECORDING.md`, also absent,
and `backend/test-discord-integration.ts` carried the same dead setup-guide
path, so an operator who followed the tool's own output landed on nothing.
Every repaired target exists today and survives the docs wash:
`docs/discord/DISCORD_SETUP.md` ("Discord Integration Setup Guide"),
`docs/discord/DISCORD_INTEGRATION_ARCHITECTURE.md` ("Discord Integration
Architecture"), and `docs/DEMO_QUICKSTART.md` (which carries "## Recording
tips"). `docs/discord/DISCORD_INTEGRATION.md` is deliberately NOT the target
even though it is the closest name: #1802 deletes it.
Guarded by `backend/__tests__/unit/scripts/docReferences.test.js` — every
`docs/<path>.md` mentioned by code under `scripts/`, `backend/`, `cli/` or
`frontend/` must exist, which is the class this defect belongs to rather than
the three lines that happened to be found.
samxu01
force-pushed
the
kai/code-doc-pointer-repair
branch
from
September 20, 2026 02:25
63eb4b3 to
8b875c5
Compare
samxu01
pushed a commit
that referenced
this pull request
Sep 20, 2026
… the guard could not look there CLAUDE.md — the file an agent is told to read first — carried two dead pointers in its Key Documentation list: - **Discord Integration**: /docs/DISCORD_INTEGRATION_ARCHITECTURE.md - **PostgreSQL Migration**: /docs/POSTGRESQL_MIGRATION.md Both files exist one level down (docs/discord/, docs/database/). This is AX entry 57's shape: follow the pointer the front door gives you and find nothing. The guard that closed this class (#1805, TASK-087) could not see them, for two independent reasons, and both are fixed here: 1. its scope was code only — scripts/, backend/, cli/, frontend/ — so a pointer in CLAUDE.md was outside it. The repo-root CLAUDE.md is now scanned (AGENTS.md is a symlink to it, git mode 120000, so the target covers both without double-reporting each dead line). 2. DOC_REF's boundary `(?<![A-Za-z0-9_/.-])` rejected a leading slash, which is the form that section writes every pointer in. `\/?` is now optional in front of `docs/`, and extractDocReferences strips it before resolving — a URL tail is still excluded, because the lookbehind fails on both positions it could match at. The markdown scope stops at the root file: docs/ prose is still the docs room's inventory, as the guard's own comment says. Mutations (each new mechanism, one at a time, run against the real harness): M1 the dead anchor is back in CLAUDE.md RED (end-to-end catch) M2 CLAUDE.md is no longer scanned RED M3 the boundary rejects a leading slash again RED M4 the leading slash is not stripped before resolve RED restored, clean run rc=0, 5/5 Both dead-literal forms are kept out of the test file itself: the guard scans its own test, so the absent-path fixture is assembled from parts and the extraction fixture uses a doc that exists.
samxu01
pushed a commit
that referenced
this pull request
Sep 20, 2026
… the guard could not look there CLAUDE.md — the file an agent is told to read first — carried two dead pointers in its Key Documentation list: - **Discord Integration**: /docs/DISCORD_INTEGRATION_ARCHITECTURE.md - **PostgreSQL Migration**: /docs/POSTGRESQL_MIGRATION.md Both files exist one level down (docs/discord/, docs/database/). This is AX entry 57's shape: follow the pointer the front door gives you and find nothing. The guard that closed this class (#1805, TASK-087) could not see them, for two independent reasons, and both are fixed here: 1. its scope was code only — scripts/, backend/, cli/, frontend/ — so a pointer in CLAUDE.md was outside it. The repo-root CLAUDE.md is now scanned (AGENTS.md is a symlink to it, git mode 120000, so the target covers both without double-reporting each dead line). 2. DOC_REF's boundary `(?<![A-Za-z0-9_/.-])` rejected a leading slash, which is the form that section writes every pointer in. `\/?` is now optional in front of `docs/`, and extractDocReferences strips it before resolving — a URL tail is still excluded, because the lookbehind fails on both positions it could match at. The markdown scope stops at the root file: docs/ prose is still the docs room's inventory, as the guard's own comment says. Mutations (each new mechanism, one at a time, run against the real harness): M1 the dead anchor is back in CLAUDE.md RED (end-to-end catch) M2 CLAUDE.md is no longer scanned RED M3 the boundary rejects a leading slash again RED M4 the leading slash is not stripped before resolve RED restored, clean run rc=0, 5/5 Both dead-literal forms are kept out of the test file itself: the guard scans its own test, so the absent-path fixture is assembled from parts and the extraction fixture uses a doc that exists.
lilyshen0722
added a commit
that referenced
this pull request
Sep 20, 2026
… the guard could not look there (#1807) CLAUDE.md — the file an agent is told to read first — carried two dead pointers in its Key Documentation list: - **Discord Integration**: /docs/DISCORD_INTEGRATION_ARCHITECTURE.md - **PostgreSQL Migration**: /docs/POSTGRESQL_MIGRATION.md Both files exist one level down (docs/discord/, docs/database/). This is AX entry 57's shape: follow the pointer the front door gives you and find nothing. The guard that closed this class (#1805, TASK-087) could not see them, for two independent reasons, and both are fixed here: 1. its scope was code only — scripts/, backend/, cli/, frontend/ — so a pointer in CLAUDE.md was outside it. The repo-root CLAUDE.md is now scanned (AGENTS.md is a symlink to it, git mode 120000, so the target covers both without double-reporting each dead line). 2. DOC_REF's boundary `(?<![A-Za-z0-9_/.-])` rejected a leading slash, which is the form that section writes every pointer in. `\/?` is now optional in front of `docs/`, and extractDocReferences strips it before resolving — a URL tail is still excluded, because the lookbehind fails on both positions it could match at. The markdown scope stops at the root file: docs/ prose is still the docs room's inventory, as the guard's own comment says. Mutations (each new mechanism, one at a time, run against the real harness): M1 the dead anchor is back in CLAUDE.md RED (end-to-end catch) M2 CLAUDE.md is no longer scanned RED M3 the boundary rejects a leading slash again RED M4 the leading slash is not stripped before resolve RED restored, clean run rc=0, 5/5 Both dead-literal forms are kept out of the test file itself: the guard scans its own test, so the absent-path fixture is assembled from parts and the extraction fixture uses a doc that exists.
lilyshen0722
added a commit
that referenced
this pull request
Sep 20, 2026
…ory retires (#1810) The fixture for the root-relative form is the front door's own line, and it named docs/discord/DISCORD_INTEGRATION.md — a file the docs inventory's verdict deletes (#1802). This suite scans itself, so the fixture is a live reference rather than inert text, and on #1802's head the run is 1 failed / 4 passed: backend/__tests__/unit/scripts/docReferences.test.js ✕ every referenced doc exists + "backend/__tests__/unit/scripts/docReferences.test.js -> docs/discord/DISCORD_INTEGRATION.md" Retargeted (input, expected value, and the URL-tail case beside it) at the surviving architecture doc — which is also what CLAUDE.md's Discord line names, so the fixture stays a faithful miniature of the line it models. Measured rather than assumed: across the 1274 files this guard scans on #1802's head, this is the only reference it cannot resolve. Every product-code pointer, #1805's repairs included, already names a surviving doc. Mutations, run at #1802's head against the real harness: M1 fixture back on the retired doc RED every referenced doc exists M2 fixture on a doc that never existed RED every referenced doc exists M3 expectation no longer matches the input RED reads a real path… restored, clean, 5/5 Order matters: this must be on main before #1802, or main carries a red guard in the window between them.
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.
What
Five sites in three files print or name
docs/…mdpaths that are not in the tree. Raised by Vera's read ofscripts/test-discord.sh:44; a sweep of the class found the neighbours it did not mention (including the line directly above it).scripts/test-discord.sh:31,43docs/TEST_DISCORD_BOT.mdscripts/test-discord.sh:44docs/design/DISCORD_INTEGRATION.mddocs/discord/scripts/setup-demo.sh:153docs/yc/DEMO_RECORDING.mddocs/yc/at allbackend/test-discord-integration.ts:236docs/TEST_DISCORD_BOT.mdRepaired targets, each of which exists today and survives the docs wash (checked against #1802's head
488111f0):docs/discord/DISCORD_SETUP.md— heading# Discord Integration Setup Guidedocs/discord/DISCORD_INTEGRATION_ARCHITECTURE.md— heading# Discord Integration Architecturedocs/DEMO_QUICKSTART.md— carries## Recording tips(:263)docs/discord/DISCORD_INTEGRATION.mdis the closest name to one of the dead ones and is deliberately not used: #1802 deletes it. Pointing the fix at it would have created a dangling reference in the same motion as removing one.The class, measured (not just the flagged line)
Every
docs/<path>.mdreferenced from code underscripts/,backend/,cli/,frontend/— 29 distinct paths — checked on main and on #1802's head:Two things fall out of that table. The five dead sites are pre-existing — nothing to do with the wash; they were already broken. And the three wash-deleted paths have exactly the four code references #1804 carries and no others, which extends Vera's "no inbound link survives the deletions" gate from
README.md/docs//docs-site/to code references as well.Guard
backend/__tests__/unit/scripts/docReferences.test.js— everydocs/<path>.mdmentioned by a tracked file underscripts/,backend/,cli/,frontend/with a source extension must exist. Scope is deliberately code-only: prose insidedocs/is the docs room's inventory to keep, and this suite has to stay green while that wash runs.It caught something real before it was committed: the first draft of its own docstring quoted the three dead paths, and the guard flagged itself. A comment is a reference too — so the literals were removed from the source, not exempted from the scan, and they live in this body and on the row instead.
Evidence
Live run of the script whose block was fixed (
bash scripts/test-discord.sh, harness backend on:5000, exit 0):Mutation ledger — each applied alone, suite output saved (never grep-filtered), sources restored byte-identically (verified per file):
test-discord.shsetup-guide fixscripts/test-discord.sh -> docs/TEST_DISCORD_BOT.md.shfrom the scanned extensionssetup-demo.shrecording-guide fixscripts/setup-demo.sh -> docs/yc/DEMO_RECORDING.mdtest-discord-integration.tsfixbackend/test-discord-integration.ts -> docs/TEST_DISCORD_BOT.mdSurvivors: none. Each guard failure prints
file -> doc, so the person who reads the red run is told where to look rather than that something, somewhere, is wrong.Also:
bash -nclean on both scripts;eslintclean on the changed backend TypeScript (frombackend/, the gatedlint:tsscope); guard suite 3/3.No version slot:
scripts/, a backend test script and a test file — nothing undercli/srcorcommonly-mcp/src.