Repository navigation
mcpx docs: refdoc slices 2-4 -- command/global-flag + /v1/MCP/protocol emitters, drift-check wiring (#1846 follow-up, #1903 tracker) #4982
Description
Why this exists
#1846 (code map of nix#145: markdown emitters + drift check) was closed 2026-10-30T01:16Z as completed after only slice 1 merged (PR #2441, dc57d483). The slice-2 → slice-4 remainder — the part that actually makes the reference unable to drift — was never filed anywhere else, so it is currently untracked. This issue takes that remainder so tracker #1903 has a live successor.
What already landed (verified on main, 2026-11-03)
pkgs/mcpx/internal/refdoc/exists (md.go,md_test.go) — the leaf Table/Code/Region emitter from slice 1.pkgs/mcpx/docs/configuration.mdanddocs/environment.mdcarryBEGIN GENERATEDregions with golden tests (internal/settings/docs_test.go,scriptenv_test.go).pkgs/mcpx/docs/parity.mdis generated byParityDoc(internal/cli/parity.go) and guarded byTestParityDocumentIsCurrent.mcpx config --schema --format text|json|markdownworks.
What is still missing
- Slice 2 — commands & global flags. Generated top-level help,
GlobalFlags()as data, describe-mode flag capture,ManualMarkdown+man --format markdown. Gated on#1883items 1 (Commands() is not the one list) and 8 (hand-declared flags). - Slice 3 —
/v1, MCP tools, protocol, parity emitters.Op.CLI/Op.Pluginfields, protocol page emitter, and the absent-row-is-a-failure parity rule (collision 18).pkgs/mcpx/docs/protocol.mdstill has no generated markers onmain. - Slice 4 — drift check & build wiring. Marker regions in
configuration.md/parity.md/protocol.md, the golden-regions test with-update, retirement of the ad-hocdocs_testhelpers,package.nixcheckPhase/postInstall. This is the slice that satisfies the tracker's "cannot drift" acceptance.
Acceptance criteria
mcpxcan emit every reference page named by#1903(settings, env vars, flags, CLI commands,/v1, MCP tools, protocol and parity matrices, man page) from the code's own definitions by one documented command.- A CI drift check fails when any committed generated region is stale, including when a row is absent.
- Regenerating on a clean tree produces byte-identical output.
Ordering and gates
- Slice 2 gates on
#1883items 1 and 8; slices 3–4 can proceed independently of each other, but slice 4 completes last. - Decision record:
#1843(Approach C confirmed). Tracker:#1903. Source-truth defects:#1883. - Program rule: this is a permanent-feature prerequisite path, so it gets its own review round rather than being folded into a tracker close-out.
Activity
developing-today commentedon Nov 3, 2026
agent-note:v1
state: reviewed (coverage loop-back)
Coverage pass 2026-11-03, loop-back review: this issue was re-reviewed (drift / overlap / already-handled / stale / blockers / ordering) so every open issue in the four repos is reviewed and in the system. Verdict: still live; in the system as task 8138 (small_fix, queued, priority 40) in repo-health-code-pilot. Labels audited and synced. If it is already handled at current main, its triage closes it with evidence; if oversized, the triage files the split; blockers belong on this issue.
Found via: coverage loop-back 2026-11-03
dezren39 commentedon Nov 3, 2026
🤖 Agent note · handed off
7 remaining items
dezren39 commentedon Nov 3, 2026
agent-note:v1
state: claimed
task: 8138 (repo-health-code-pilot, lane bf419306-c4ef-470f-a553-beabf93239de)
worker: repo-worker-code
Resumed from the parked checkpoint. Fresh main now satisfies the #1883 source-truth gate: Commands() is composed from handCommands()+opCommands(), and the CLI reference says flags are generated from the registry; the #1883 review records PRs #2844/#2867 merged. Issue #4982 remains open, PR #2441 is merged, no competing PR or hard-stop labels found. PR #4922 is Drew-owned and unrelated, left untouched. Existing worktree is clean; no implementation edits yet.
dezren39 commentedon Nov 3, 2026
agent-note:v1
state: parked
task: 8138 (repo-health-code-pilot, lane bf419306-c4ef-470f-a553-beabf93239de)
worker: repo-worker-code
The prior blocked-gate checkpoint was stale: fresh main confirms #1883 items 1 and 8 are resolved, including PRs #2844/#2867. The task branch is now fast-forwarded to f34b6fd and clean. No implementation edits or tests yet; the slices 2-4 implementation is multi-surface and will continue in a later launch.
Resume: start from /home/user/git/fleet/task-8138-4982-refdoc-slices-2-4 on queue/8138-4982-refdoc-slices-2-4; implement shared command/global-flag Markdown source, static /v1/MCP/protocol emitters, then marker-region drift harness and package.nix wiring. Freshly confirm #4982 remains open and no hard-stop labels; do not repeat the already-resolved #1883 source gate investigation. PR #4922 remains Drew-owned and untouched.
dezren39 commentedon Nov 4, 2026
🤖 Agent note · picked up
queue/8138-4982-refdoc-slices-2-4at/home/user/git/fleet/task-8138-4982-refdoc-slices-2-4.dezren39 commentedon Nov 4, 2026
🤖 Agent note · triage disposition
72efce0bda94a4e37c96f8610979037536871268; its body explicitly implements mcpx docs: finish the generated reference — per-command and global-flag pages, /v1 and MCP-tools pages, protocol tables (remainder of #1846) #4909, the remainder of mcpx docs: markdown emitters in the binary and a drift check for every generated page #1846 slices 2–4. mcpx docs: finish the generated reference — per-command and global-flag pages, /v1 and MCP-tools pages, protocol tables (remainder of #1846) #4909 is CLOSED after that merge. Current maina51be0e220c247dde5cfdef2d95b38984386cee3has the command/global-flag reference tree, /v1 and MCP emitters, generated protocol tables, shared golden check (regions_test.gocovers configuration, parity, and protocol), andpackage.nixcheck/install wiring.queue/8138-4982-refdoc-slices-2-4at/home/user/git/fleet/task-8138-4982-refdoc-slices-2-4, clean at current main; no edits by this lane.