fix(spec): repair 25 dead PROTOCOL_MAP links + gate them in CI#3144
Merged
Conversation
PROTOCOL_MAP.md is hand-written and nothing regenerates it, so renames orphan rows silently. 25 of its 132 `src/…` links pointed at files that no longer exist. The reported row was misdiagnosed, and the git history says why. The prose "Virtual capabilities for analytics datasets" was NOT a half-finished rewrite left by #1620 — it has been there verbatim since the map was created (ced379b), when `data/dataset.zod.ts` held the *seed* schema (object/externalId/mode/records). It never described that file. So this is one wrong row plus one absent row, not one half-updated row: - `data/dataset.zod.ts` -> `data/seed.zod.ts`, described as seed fixtures (renamed by #1620 to free `dataset` for analytics, ADR-0021). - the analytics dataset the old prose was reaching for is a real, unlisted schema: added as `ui/dataset.zod.ts` (ADR-0021 semantic layer). The sweep found the same rot everywhere, all from deliberate refactors that left the map behind: - `src/hub/**` (9 rows) — the directory no longer exists (142703d). Survivors rehomed: license/registry-config/tenant -> src/system, plugin-registry/plugin-security -> src/kernel; composer, marketplace, space, hub-federation and api/hub were deleted outright. Section 9 is therefore gone and Kernel renumbered 10 -> 9. - `src/ai` (10 rows) — narrowed by 629a716. Repointed where a successor exists (agent-action -> tool, cost -> usage, rag-pipeline -> knowledge-source); dropped nlq/orchestration/predictive/devops-agent/ feedback-loop/plugin-development/runtime-ops. - `identity/role` -> `identity/position` (ADR-0090 D3 renamed sys_role). - `security/policy` (#2387), `system/compliance` + `system/masking` (ADR-0056 D8) — removed as dead, rows dropped. Gate: scripts/protocol-map.test.ts asserts every link resolves. Proven to go red first — it listed exactly the 25 dead links before the fix. It rides Test Core (required); `core: packages/**` covers the file and turbo's $TURBO_DEFAULT$ inputs include it, so a map-only edit still re-runs the test rather than cache-hitting to a false green. A new workflow job would not have blocked merges (main requires only 4 checks), and check-links.yml is dormant (workflow_dispatch only) and does not cover packages/spec. Deliberately asserts links only, not completeness: the map is a curated digest, not a generated index. Sibling of #3138, which fixed the identical stale `data/dataset.zod.ts` pointer in build-skill-references.ts's SKILL_MAP. That one guards generated artifacts that ship to third parties; PROTOCOL_MAP.md is hand-written and repo-internal (not in the package's npm `files`), so it needs its own check. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
os-zhuang
added
the
skip-changeset
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 102 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
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
packages/spec/PROTOCOL_MAP.mdis hand-written and nothing regenerates it, so renames orphan rows silently. 25 of its 132src/…links pointed at files that no longer exist.The reported row was misdiagnosed
The issue suspected a half-update: path left on the old seed file, prose rewritten for the new analytics type. The history says otherwise — the prose "Virtual capabilities for analytics datasets" has been there verbatim since the map was created (
ced379b9e), back whendata/dataset.zod.tsheld the seed schema (object/externalId/mode/records). It never described that file. #1620 didn't half-update the row; the row was wrong from day one.So it's one wrong row + one absent row, and the fix is both:
data/dataset.zod.ts→data/seed.zod.ts, described as seed fixtures (fix(seed): complete Dataset->Seed rename + load published seed rows (locally verified) #1620 renamed it to freedatasetfor analytics, ADR-0021).ui/dataset.zod.ts(the ADR-0021 semantic layer thatreport/dashboardbind to).The sweep found the same rot everywhere
All from deliberate refactors that left the map behind:
src/hub/**(9)142703d54). Survivors rehomed: license/registry-config/tenant →src/system, plugin-registry/plugin-security →src/kernel. composer/marketplace/space/hub-federation/api/hubdeleted outright. Section 9 removed, Kernel renumbered 10→9.src/ai(10)629a7168e. Repointed where a successor exists: agent-action→tool, cost→usage, rag-pipeline→knowledge-source. Dropped nlq/orchestration/predictive/devops-agent/feedback-loop/plugin-development/runtime-ops.identity/roleidentity/position(ADR-0090 D3 renamedsys_role→sys_position).security/policy,system/compliance,system/maskingRepoint vs. drop was decided per row from the deleting commit, not guessed.
The gate
scripts/protocol-map.test.tsasserts every link resolves. Proven to go red first — it listed exactly the 25 dead links before the fix, then went green.Placement reasoning, since a gate that can't block is theatre:
core: packages/**covers the file, and turbo's$TURBO_DEFAULT$inputs include it — so a map-only edit re-runs the test instead of cache-hitting to a false green.check-links.ymlis dormant (workflow_dispatchonly) and doesn't coverpackages/spec.Relationship to #3138
Sibling, not duplicate. One #1620 rename had two victims:
data/dataset.zod.tspointer inbuild-skill-references.ts's SKILL_MAP — its gate comment even names this bug. It guards generated artifacts that ship to third parties, so it's a regenerate-and-diff check inlint.yml.PROTOCOL_MAP.md: hand-written, repo-internal, not in the package's npmfiles(never ships). fix(spec): regenerate drifted skill references + react-blocks contract, and gate them in CI #3138 deliberately left it alone to stay scoped, and its gate can't reach it.A plain assertion is the whole job here, so this needs no script or workflow step — and Test Core's
packages/**filter has no blind spot for spec changes.Verification
tsc --noEmitclean.Docs-only →
skip-changeset.🤖 Generated with Claude Code