Retire the tracker from the repository's text: every root doc's tag line, docs/index.md, docs/tags.md and CLAUDE.md still send readers to mcp__tracker__list — the status query is a GitHub label query, stated once in docs/index.md

[djabi]

Plan

The plan file is outside the checkout and the tool guard blocks it, so the plan is this message, as the step requires.

Normative check: CONSISTENT. I relied on docs/org/normative.md § The header ("The query is the project's own — a gh issue list --label invocation on a GitHub-tracked project — and its exact spelling is stated once, in docs/index.md") and § "docs/index.md is the map" ("The index also names the project's status query"). docs/normative.md § Where a gap is recorded still says "Items live in this project's tracker MCP server. GitHub Issues is the public inbound surface: an issue filed there is imported and becomes a tracker item". That root doc defers every rule to the vendored one it now contradicts, so this plan amends that section. That is a root-doc amendment: #599 must carry the normative label. I did not apply it because this planning session is read-only. docs/org/normative.md § A specification states the end state bans inline markers; this plan renumbers the existing CLAUDE.md-sanctioned markers and adds none.

Context

The tracker's items moved to GitHub issues on 2026-10-03 (docs/archive/tracker-ids.md maps IDs). The repository text still sends readers to mcp__tracker__list, and the status query is spelled in 31 places. The fix: spell the GitHub label query once in docs/index.md, make every other mention point there, and add a sweep so the tracker spelling cannot return.

Verified facts the plan rests on:

• gh issue list --label <label> --state open returns an empty list with exit 0 for a label that does not exist, so docs whose label was never created need no label work.
• compiler/cmd/promise/resources/language-guide.md is an untracked build copy of docs/language-guide.md (tools/build/common/resources.go:28). Editing the doc is enough.
• Issues docs/ root: finish de-progressing the remaining phase-narrated specs (runtime-architecture, standard-library) #335, Caller-visible resolve timeout in modules/net: bound getaddrinfo, which the reactor deadline machinery cannot reach #340, encoding/2: base64 + base64url #286, Structural satisfaction ignores receiver ownership — a ~this method satisfies a shared-receiver requirement, so a shared (read-only) borrow of the view mutates through it #559 are all open (the four tracked as T… markers map to them in docs/archive/tracker-ids.md).
• .mcp.json and CLAUDE.local.md are untracked.

Changes

PASS 1 — the query has one home.

• docs/index.md "The status query" paragraph (lines 10–14): replace "This project records items in its tracker MCP server, so the query is:" and the fenced mcp__tracker__list --tag <basename> with "This project records items as GitHub issues, and a document's tag is a label there, so the query is:" followed by one fenced line, gh issue list --label <basename> --state open # --label large-integers, for large-integers.md. Line 59: the tags.md entry's "for the tracker MCP server" becomes "for this repository's GitHub issue labels".
• Every root doc's tag line (the files grep -l 'mcp__tracker__list --tag' docs/*.md lists; 30 today) becomes:
  > **Tag:** \` — remaining work to complete this document: the query named in docs/index.md. A mechanical sedon line 3 of each file. The relative link resolves fromdocs/, so checkDocLinkspasses. This matches the shapedocs/org/normative.md § The header gives (<the project's query>` is a reference, not a spelling).

PASS 2 — tags, CLAUDE.md, normative.md say issues and labels.

• docs/tags.md:59 § Document: "it is the set of open items carrying the doc's tag. mcp__tracker__list --tag <doc> is the doc's status section" becomes "it is the set of open issues carrying the doc's label; the query named in index.md is the doc's status section". Nothing else in the file names the tracker.
• CLAUDE.md § Documentation (lines 427–450): "open tracker items carrying it" → "open issues carrying it as a label"; the example tag line → the PASS 1 form; "progress lives in the tracker, and mcp__tracker__list --tag <doc> is" → "progress lives in GitHub issues, and the label query stated once in docs/index.md is"; "close the tracker item" → "close the issue"; "file it with that doc's tag" → "file an issue carrying that doc's label"; "name its tracker item" → "name its issue (tracked as #NNN)"; the grep becomes grep -rn 'tracked as #' docs/*.md.
• docs/normative.md § Where a gap is recorded, first two sentences: "Items are GitHub issues on promise-language/promise, and a document's tag is a label there; the open issues carrying it are what the query returns." The sentence that follows (query spelled once in index.md) stays. The § What a gap is filed as table stays: bug/task are GitHub labels too and name no tracker.
• docs/creating-modules.md:510,632,656 ("File a bug in the tracker MCP server", "File tasks in the tracker", "all filed in tracker") and .claude/skills/cut-release/SKILL.md:29,39,43,59,61 ("file a tracker bug", "Reference tracker IDs", "annotate tracker items") become "file a GitHub issue" / "reference issue numbers" / "close or annotate the issues". Same class of pointer, word-level edits.

PASS 3 — markers name issues. docs/runtime-architecture.md:12 T1721 → #335; docs/standard-library.md:1102 T1736 → #340; and the two the item did not list but the new grep must not miss: docs/standard-library.md:66 T1569 → #286, docs/language-design.md:1059 T2185 → #559. Spelling: tracked as #335. After landing, comment on #338 that its sweep's grep is now tracked as #.

PASS 4 — the sweep.

• tools/build/common/structural.go: add CheckTrackerPointers(root string) error, built on the existing scanTracked(root, "*", scope, flag) (line 230). scope admits every tracked path except those under docs/archive/ and docs/org/. flag returns the line numbers containing the needle, which is built as "mcp__" + "tracker__" so the sweep's own source and tests do not trip it. The error names each path:line and says items are GitHub issues and the status query is the one stated in docs/index.md (Retire the tracker from the repository's text: every root doc's tag line, docs/index.md, docs/tags.md and CLAUDE.md still send readers to mcp__tracker__list — the status query is a GitHub label query, stated once in docs/index.md #599). Register it as {"tracker-pointers", CheckTrackerPointers} in structuralChecks (line 310), and change the "All four run" comment at line 329 to five.
• tools/build/common/structural_test.go: add the entry to TestStructuralChecks_PinsTheSet (line 883, deliberately a duplicated list). TestRunStructuralChecks_ThisTreeIsClean (line 810) iterates the registry, so the real tree is covered automatically — which is why PASS 4 lands with PASSES 1–3, not before.
• docs/build-tools.md § The structural sweeps (line 395 table): add the tracker-pointers row; "the four in" at line 620 becomes five.

Tests

• New unit tests in structural_test.go using the existing temp-repo helper (git init + git add -A, as docscheck_test.go:20–46 does): a tracked .md containing the needle is reported as path:line; the same text under docs/archive/ and docs/org/ passes; an untracked file is ignored; a tracked-but-deleted file is skipped (mirror TestCheckTestSleeps_SkipsTrackedButAbsent); a non-git root returns the "list tracked" error (mirror TestCheckTestSleeps_ErrorsWhenGitCannotList); two hits in one file give two lines.
• cd tools/build && go test ./common/ -count=1 (covers PinsTheSet and ThisTreeIsClean), then bin/verify, which runs check structure and the docs link/index checks over the edited tree.
• Final sweeps that must be empty: the item's own git ls-files | grep -v '^docs/archive/' | grep -v '^docs/org/' | xargs grep -l mcp__tracker, and grep -rn 'tracked as T[0-9]' docs/*.md. grep -rn 'tracked as #' docs/*.md must list exactly four lines.

Deliberately not doing

• .mcp.json, CLAUDE.local.md, and arena provisioning: untracked, and the item names them as a separate change.
• T1234 citations in code comments, commit messages, and parenthetical doc citations such as (T1685): out of scope per the item; docs/archive/tracker-ids.md resolves them.
• docs/gate-system.md's description of the tracker as the gate scheduler and dispatcher (lines 7–284): that is a design question about what dispatches periodic and platform gates after retirement, not a pointer to a query. It needs its own issue, which I could not file from this read-only session: "docs/gate-system.md still names the tracker MCP server as the coordinator for periodic/platform gate dispatch and exceptions; decide the replacement or retire those sections (Delete the gate-exception mechanism: nothing grants exceptions, nothing consults them, and docs/gate-system.md describes a fail-closed query that no binary makes #551 already removes the exception mechanism)", labels docs, gate-system.
• docs/index.md:97 ("All open items migrated to the tracker" on the archived roadmap): history of an archived doc, resolved by tracker-ids.md.
• Creating GitHub labels for docs that lack one: an empty query is the documented healthy state, and docs/org/normative.md § Lifecycle makes label creation part of ratification.

Passes

• PASS 1: docs/index.md states gh issue list --label <basename> --state open once; every root doc's tag line points at it.
• PASS 2: docs/tags.md, CLAUDE.md § Documentation, docs/normative.md § Where a gap is recorded, docs/creating-modules.md, cut-release skill say issues and labels.
• PASS 3: the four tracked as T… markers become tracked as #335, #340, #286, #559.
• PASS 4: tracker-pointers sweep in structural.go + tests + docs/build-tools.md row and counts.

Two actions this session could not take and the executor must: add the normative label to #599, and file the gate-system follow-up issue described above.

Review

Everything I can check without the verify result is done. Interim status while it runs:

• The commit does what the issue asked for the 30 tag lines, docs/index.md, docs/tags.md, CLAUDE.md, the four tracked as markers, and the new tracker-pointers sweep. Its tests pass and would fail on revert.
• I fixed four more root-doc pointers the commit missed and converted the remaining pending-work markers that still named tracker IDs to their open issues.
• The round's claim that the cut-release skill was updated is false. The commit did not touch it, and my edit to it was refused by the permission layer.

Waiting on the fresh bin/verify run over the final tree before writing the review.

Coverage

Tools rebuilt in four seconds and verify is now running on the final tree. The only thing left is its verdict, which will wake me when it lands.

Gate

• gate: integration
• outcome: measured
• acceptable: true
• verdict: every judged metric is within its terms

measurement:

{"schema_version":1,"gate":"integration","target":"darwin-arm64","metrics":[{"name":"unformatted_go_files","type":"int","value":0},{"name":"unformatted_promise_files","type":"int","value":0},{"name":"unbuildable_go_packages","type":"int","value":0},{"name":"build_failures","type":"int","value":0},{"name":"vet_findings","type":"int","value":0},{"name":"promise_check_failures","type":"int","value":0},{"name":"promise_check_errors","type":"int","value":0},{"name":"promise_check_warnings","type":"int","value":0},{"name":"promise_check_units","type":"int","value":885},{"name":"go_test_failures","type":"int","value":0},{"name":"go_test_packages_failed","type":"int","value":0},{"name":"host_test_failures","type":"int","value":0},{"name":"host_leak_count","type":"int","value":0},{"name":"host_test_count","type":"int","value":11893},{"name":"cas_network_bytes","type":"int","value":0,"unit":"bytes"},{"name":"cas_home_count","type":"int","value":1}],"tree":"0a728e09a53fefbeb9147db979ce552604d3fb51"}

thresholds:

{"build_failures":{"kind":"cap","direction":"at_most","value":0},"cas_home_count":{"kind":"baseline","direction":"down","value":1},"cas_network_bytes":{"kind":"baseline","direction":"exact","value":0},"go_test_failures":{"kind":"cap","direction":"at_most","value":0},"go_test_packages_failed":{"kind":"cap","direction":"at_most","value":0},"host_leak_count":{"kind":"cap","direction":"at_most","value":0},"host_test_count":{"kind":"baseline","direction":"up","value":11186},"host_test_failures":{"kind":"cap","direction":"at_most","value":0},"promise_check_errors":{"kind":"cap","direction":"at_most","value":0},"promise_check_failures":{"kind":"cap","direction":"at_most","value":0},"promise_check_units":{"kind":"baseline","direction":"up","value":861},"promise_check_warnings":{"kind":"cap","direction":"at_most","value":0},"unbuildable_go_packages":{"kind":"cap","direction":"at_most","value":0},"unformatted_go_files":{"kind":"cap","direction":"at_most","value":0},"unformatted_promise_files":{"kind":"cap","direction":"at_most","value":0},"vet_findings":{"kind":"cap","direction":"at_most","value":0}}

Closes #599