ci: route the base-std docs tree, skip deleted sources, report unrouted files

[soheimam]

What changed? Why?

base/base-std#213 (be6d045) restructured the upstream docs: it deleted docs/B20/*, docs/PolicyRegistry/README.md and docs/ActivationRegistry/README.md and added an audience-layered tree (overview.md, architecture.md, concepts/, guides/, reference/). Our route table mapped only the six deleted files, so the sync in #1928:

• edited 32 reference pages from an all-minus diff and added 13 <Warning> banners saying "the source file docs/B20/Asset.md has been removed" on pages generated from an unchanged Solidity interface (batch-mint.mdx even says the function is deleted upstream);
• introduced one factual error (update-ui-multiplier.mdx now says UIMultiplierUpdated fires when the schedule matures; upstream concepts/multipliers.md says it fires when the schedule is recorded and maturation emits nothing);
• dropped all fifteen new files without a trace. The provenance table cites only deleted files.

This PR fixes the automation so a re-dispatch of be6d045 produces the right PR. #1928 is closed in favor of that re-run.

Route table (scripts/sync-from-base-std/route-table.json)

• Retires the six dead rules and adds rules for the new tree. Destinations follow docs/ia-guidelines.md and docs/content-guidelines.md: chain-generic precompile mechanics → specifications/base-protocol/execution/precompiles.mdx; the B20 component map and key concepts → specification-overview.mdx; execution/versioning guarantees → invariants-tests.mdx; guides → the existing Build on Base task pages (apply-a-multiplier, announce-a-distribution, cancel-blocked-units, recover-funds, …); reference tables → constants-addresses.mdx / errors-events.mdx. No rule creates a page.
• New ignored kind for upstream scaffolding (READMEs, guide template, interface link index).

Workflow (.github/workflows/base-std-docs-sync.yml)

• "Derive trusted removed paths": reads the commit API for the verified sha and writes removed_paths into the payload (renames count their previous name). Never taken from client_payload. Best-effort: an API failure logs a warning and leaves it empty.
• "Open issue for unrouted source files": when a dispatch opens no PR but has unrouted files, the routing report is filed as an issue, one per source sha (needs issues: write, added to the apply job only).
• GUIDELINE_ROUTING repo variable passed through (propose default / apply / off).

Sync script (scripts/sync-from-base-std/)

• Removed files never route. classifyChangedPaths buckets every changed path as routed / ignored / unrouted / removed; the PR body gains Unrouted source files and Removed source files sections.
• Placement proposals: unrouted Markdown sources go through one Haiku call that reads the IA and content guidelines (already loaded for every prompt) plus the title/description of every existing page under docs/specifications/ and docs/build-on-base/, and returns the existing page each file belongs on with the guideline rule that decides it. Proposals are filtered back against the candidate list, so a hallucinated path is dropped. Rendered as Proposed placement (from IA guidelines) for a maintainer to turn into a route-table rule. GUIDELINE_ROUTING=apply also edits the proposed pages in the same run.
• validateCallouts (safety.mjs) rejects Warning/Note/Info/Tip/Check callouts that describe repository housekeeping (source files, restructures, "last known state", "verify against source"). Legitimate deprecation and behavior callouts pass. Prompt rules 10 and 11 say the same and let the sync replace a Generated B20 reference for … placeholder description.
• scripts/validate-docs-structure.js accepts the ignored kind.

Notes to reviewers

• Placement is guideline-derived, so there is deliberately no new "execution architecture" page: content-guidelines.md has no such page type, and its overview structure puts the architecture/component map on the spec overview. If the team wants a standalone page, that is a guideline change (Governance Owner gate), separate from this PR.
• specification-overview.mdx (10,045 chars) and errors-events.mdx (13,851) are above MAX_REGENERABLE_CHARS (10,000), so the re-run will skip them with a logged reason. The overview Architecture section, the invariants for storage/versioning, the precompiles section and the four missing constants (ALL_FEATURES_PAUSED, MAX_SUPPLY_CAP, WAD_PRECISION, MAX_UI_MULTIPLIER) need a human-authored follow-up PR.
• Pre-existing and untouched: the changelog page_template still targets docs/base-chain/specs/reference/b20/changelog/ while every other rule targets docs/specifications/b20/.
• The 13 housekeeping banners from docs: restructure B20 guides and rewrite execution architecture (base-std@be6d045) #1928 are the negative fixtures in validate-safety.test.mjs.

How has it been tested?

• npm test (80 pass) and npm --prefix scripts run test:base-std-sync (122 pass, 8 new tests: docs-tree routes against the real be6d045 file list, removed-path exclusion, classification buckets, proposal filtering, routing report, callout guard).
• node scripts/validate-docs-structure.js passes (every routed page exists and is reachable from docs.json).
• Workflow YAML parsed; the apply job has 18 steps and issues: write.
• Dry run of the script (no gateway key) against a payload with one unrouted file, one ignored file and one removed file: correct [routing] buckets, sync-review.md written with both sections, unrouted_count=1 and touched_count=0 in GITHUB_OUTPUT, placement call fails gracefully.
• Not exercised here: the live Haiku placement call and the issue-creation step need a real dispatch. After merge: close docs: restructure B20 guides and rewrite execution architecture (base-std@be6d045) #1928 (done), then re-dispatch be6d045 and check the new PR has no housekeeping Warnings, cites docs/concepts/* / docs/guides/* / docs/reference/* in provenance, and lists only the four ignored files as unrouted-or-ignored.

Screenshots

N/A (no user-facing changes)

🤖 Generated with Claude Code

https://claude.ai/code/session_01VNDYZpZXLaTr6iQraqkXyf

[cb-heimdall]

✅ Heimdall Review Status

Requirement	Status	More Info
Reviews	✅ 1/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1