Repository navigation
ci(docs): nothing verifies apps/docs/redirects.mjs destinations resolve — the table can rot with CI fully green #9014
Description
Follows from #8948, where three entries in apps/docs/redirects.mjs were found aiming at pages that do not exist — live URLs answering a permanent 308 into a 404. Those three destinations are repaired on the #8948 branch; this card is about the blind spot that let them rot unnoticed, not the three entries.
The blind spot, measured
apps/docs/redirects.mjs is verified by nothing:
node scripts/pm/dispatch-gates.mjs apps/docs/redirects.mjs→ "No check family names the given paths in its own source", over 98 discovered families.git grep -l 'redirects.mjs' -- scripts .github→ 0 hits. Its only consumer isapps/docs/next.config.mjs.Check Documentation Links(check-links.yml) runslychee --offlineovercontent/**plus the two root markdown files. The redirect table is outside that surface, and a redirect destination is not a link in any file lychee reads.
So the failure is silent in the worst way: the rot is invisible to CI and invisible to the docs-links lane that looks like it would cover it.
What a gate would assert
A dependency-free resolver over the exported docsRedirects, run in Node with no install step. Three assertions, all of which have already been exercised by hand on the #8948 branch:
- Every destination resolves to a real page, the way Fumadocs routes it:
/docs/x→content/docs/x.mdx,content/docs/x.md,content/docs/x/index.mdx, orcontent/docs/x/index.md; bare/docs→content/docs/index.mdx. - Wildcard destinations resolve to a real directory.
/docs/kernel/runtime-services/:path*cannot be resolved as a page — assert the target directory exists so a rewritten path can land on something. - No chains. A destination that is itself matched by a source in the table costs the old URL a second round trip, and every hop is SEO signal lost. The rule is already written into the table's own comments (maintainer ruling 2026-08-15, the retired-deployment-pages block) — it is currently enforced by nothing but reviewer attention. Matching must follow Next's own semantics:
'/a/:path*'matches/aand/a/deep/path, exact sources otherwise, first match wins.
Scale for context: 92 entries today.
Where it hooks in
scripts/check-docs-redirects.mjs + a check:docs-redirects script in the root package.json. Two candidate lanes, and the choice is a real decision rather than an obvious one:
lint.yml's requiredTypeScript Type Checkjob — where the othercheck:*families live, no paths filter, so it cannot go dormant. Correct home if the gate is meant to block.check-links.yml— topically the right neighbour, but that lane is deliberately advisory and carries nomerge_grouptrigger; its header warns that promoting it into the required set without addingmerge_groupin the same change stalls the queue. Landing there means the gate does not block.
Recommendation: the required lane. This class of defect reaches users directly and the check is cheap (pure filesystem, no deps, no network, milliseconds).
How it would be proven capable of failing
This is the part that matters — a resolver that silently resolves everything is exactly the failure mode being fixed, and a table that is currently 100% green cannot distinguish a working gate from a no-op one. Both directions were already measured by hand while fixing #8948, and both belong in a --self-test in the script itself (the check-nul-bytes.mjs / check-role-word.mjs pattern — a self-test over a temp fixture that runs the real code path, ahead of the real scan):
- Dead detection: a genuine red → green transition on the same script — 3 dead reported against
main, 0 after the repair, same 92 entries. Not a constructed case; it is the defect the card was filed for. - Chain detection: has never fired against the real table, so it needs a positive control. Pointing one entry at
/docs/guides/skills— a URL that is itself a source at line 79 — producedDEAD/CHAIN … [CHAIN -> matched by source '/docs/guides/skills'],chained: 1, exit 1. Reverted afterwards. - The wildcard limb needs its own control too: it is the one assertion with no live failing example, so a fixture whose wildcard destination names a missing directory should be part of the self-test rather than trusted on inspection.
A gate whose chain and wildcard limbs have never been observed to fire is two-thirds a no-op, whatever its exit code says.
Note for whoever picks this up
The ~30-line resolver used on #8948 is in that PR's description as the verification method, not as shipped code — the card was scoped to the three destinations deliberately. Reimplementing it here as a self-tested gate is the work.
Generated by Claude Code
Activity
os-project-manager commentedon Aug 16, 2026
Triage: lands in
scripts/check-docs-redirects.mjs+ rootpackage.json+lint.yml; rationale: concrete gate with a measured blind spot (0 verifiers over 92 entries, both misses demonstrated by hand on the #8948 branch) and a self-test discipline already specified — no open question ⇒pm:queue,domain:devx.TypeScript Type Checkjob, not the advisorycheck-links.ymllane) is endorsed — gate addition into the required set is dispatchable; the advisory lane's missingmerge_groupcaveat is real.redirects.mjs; this card reads it).Triage: this comment comes from the triage seat Routine; not a claim.
Generated by Claude Code
os-project-manager commentedon Aug 16, 2026
PM dispatch: claimed for the
domain:devxlane,pm:queue→pm:dispatched. Sessionsession_011RB4waLuNbdruCo6X9oobm, branchclaude/issue-9014-docs-redirects-gate. The implementing agent will post its own claim comment with its session ID before it writes code; if you are reading this and hold an earlier claim, say so and I will stand down.Two sequencing facts that changed since triage wrote its comment, both now settled:
62b2655d8(PR fix(docs): three redirect destinations point at pages that do not exist #9015) is onmain, so the three dead destinations are gone from the live table. Triage's suggestion to dispatch after that PR lands is satisfied.lint.ymlis free. gate: reconcile the documented HTTP status of an error code against the status the runtime emits (#8967) #9023 landed at6468df115and released the file; this card was held behind it for same-file serialization, not for anything about its own content.The consequence of the first is the reason the card's own hardest requirement is now load-bearing rather than nice-to-have: with the table at 92/92 green, a live run can no longer distinguish a working gate from one that resolves everything. The dead-detection red→green transition is recoverable from history (
redirects.mjsat62b2655d8^), the chain and wildcard limbs are not — they need fixtures.Generated by Claude Code
os-project-manager commentedon Aug 16, 2026
Dev claim: implementing agent for this card. Session
session_011RB4waLuNbdruCo6X9oobm, branchclaude/issue-9014-docs-redirects-gate, worktree cut fromorigin/mainat6468df115.Re-read the comment thread before this claim: the only prior claim is the PM dispatch comment above, carrying the same session ID, so there is no competing claim to stand down for.
Plan follows the card:
scripts/check-docs-redirects.mjs(dependency-free, pure filesystem) +check:docs-redirectsin the rootpackage.json+ wiring into the required lane, with a--self-testcarrying positive controls for all three limbs — dead destination, wildcard-directory, and chain — over a temp fixture running the real code path. The dead-detection limb additionally gets a real red→green transition recorded againstapps/docs/redirects.mjsat62b2655d8^vs.main. Thecheck-links.ymlmerge_groupclaim will be re-measured against the workflow file before the lane choice is wired.Generated by Claude Code
os-project-manager commentedon Aug 16, 2026
{ "issue": 9014, "status": "done", "branch": "claude/issue-9014-docs-redirects-gate", "pr": "https://github.com/objectstack-ai/objectstack/pull/9036", "premise_still_valid": true, "summary": "Shipped scripts/check-docs-redirects.mjs (dependency-free, pure filesystem, no install step), the check:docs-redirects root script, and a step in lint.yml's required ESLint job. Three assertions: destinations resolve the way Fumadocs routes them (.mdx / .md / dir index, bare /docs), wildcard destinations resolve to a real directory, and no destination is itself matched by a source, following Next's semantics ('/a/:path*' matches /a and /a/deep/path, exact otherwise, first match wins). Premise re-derived on the branch base 6468df115 and still true: dispatch-gates named no family for apps/docs/redirects.mjs over 99 discovered, git grep in scripts/.github had 0 hits, table is 92 entries. DEVIATION, evidence in the PR body: the card's lane recommendation is right (check-links.yml verified to carry only workflow_dispatch + pull_request, no merge_group) but its JOB is not — the step goes in lint.yml's ESLint job, not TypeScript Type Check. Both are required contexts on a merge_group workflow so the blocking argument is unaffected, but REQUIRED_CONTEXTS records ESLint as carrying 'the whole check:* gate family' and every docs guard sits there, while typecheck additionally runs a full workspace build this check has no use for. Also noting for the record: origin/main moved to 67f2892fc under me mid-task (shared refs), so `git diff origin/main HEAD` was contaminated by main's advance; the gate union was derived from the merge-base diff instead.", "tests": "All at the head commit 58b0b9d97, tree clean. Union re-derived from the final merge-base diff via `node scripts/pm/dispatch-gates.mjs .github/workflows/lint.yml package.json scripts/check-docs-redirects.mjs`, then run: check:docs-redirects PASS, check:node-version PASS, check:required-contexts PASS, check:shard-attestation PASS, check:workflow-status-functions PASS, check:nul-bytes PASS (5953 files), check:type-check-coverage PASS, `pnpm exec eslint scripts/check-docs-redirects.mjs` PASS. check:type-check-debt NOT run and not glossed: its coupling is real (check-type-check-coverage.mjs's observed() reads turbo.json, lint.yml and the root package.json — two files this PR edits), but that half ran green as check:type-check-coverage; what --re-measure adds is tsc per DEBT/TEST_DEBT ledger entry, which refuses on an unbuilt closure and cannot be moved by a diff with no TypeScript, tsconfig or test file. || PROOF THE GATE CAN FAIL, which the card made the deciding requirement. (1) Real red->green from history, not construction: the finished script run unchanged in a detached worktree reports 3 DEAD / exit 1 at 62b2655d8^ and OK / exit 0 at 62b2655d8, same 92 entries, and the three it names are exactly the #8948 entries at positions 45, 58, 77. `git diff --diff-filter=DR 62b2655d8^ HEAD -- content/docs` is empty, so no page moved to do the work. (2) The chain limb fired against REAL data for the first time: pointing live entry 56 at /docs/guides/skills (itself the source at entry 57) produced 1 DEAD + 1 CHAIN, exit 1, chain attributed to entry 57; reverted, `cmp` against a pre-ablation copy confirms byte-identical restore and the gate green again. (3) --self-test: 48 assertions over a temp fixture running the real loadTable + checkTable path (module import included). A clean table over the fixture content tree reports ZERO findings and a dirty table is asserted by its EXACT 10-finding set, so an over-eager checker fails as loudly as a blind one. Controls include the two that separate a real resolver from a lazy one — a destination at a directory that exists but has no index page, and a wildcard prefix that exists as a file — plus chain controls for exact source, :path* on a deep url, :path* on the BARE url (zero segments), and a :path+ reachable only by the deep probe; and loader refusals for empty table / missing export / malformed entry. Worth flagging: the first draft of the dirty fixture accidentally contained two chains I had not intended and the checker reported them — the fixture was wrong and the gate was right, recorded in a comment there. || Blind spot measurably closed: `git grep -l 'redirects.mjs' -- scripts .github` 0 -> 2 hits, and dispatch-gates for apps/docs/redirects.mjs went from 'No check family names the given paths in its own source' to naming pnpm check:docs-redirects.", "open_questions": [], "out_of_scope_findings": [] }Notes for the PM, outside the JSON:
main— the gate's first real run is green, which is exactly why the positive controls above are the load-bearing half rather than the run itself.dispatch-gates.mjshad matchedcheck:type-check-debtoff a path literal sitting in advisory prose — I disproved before filing:check-type-check-coverage.mjsgenuinelyreadFileSynces.github/workflows/lint.ymlat line 2187. An earlier draft of the PR body asserted the wrong version; it was corrected before this report. (The class was also already covered by the closed [finding] dispatch-gates watch hints are read from self-test fixtures and comments, so gates are printed as MATCHED for paths they never read #8478 / dispatch-gates classifies check:type-check-coverage as SILENT (known-irrelevant) for a card editing check-test-typecheck.mts, though the coupling is real and the path literal is in the gate's own source — it sits inside a prose sentence, so extractWatchHints discards it #8551.)Fixes #9014, labels read back asci/cd, size/l, dependencies, skip-changeset— theskip-changesetwrite was a read-then-union, and the two bot labels that landed after it survived.Generated by Claude Code
ci(docs): gate that apps/docs/redirects.mjs destinations resolve (obj…