docs(specs): compress references and code commentary

[nedtwigg]

Summary

• remove duplicate implementation maps, test catalogs, and maintainer checklists
• make generated CLI help and canonical TypeScript definitions own exact reference shapes
• consolidate parallel alert, Pocket push, and VS Code peer-link contracts into matrices
• trim duplicated module commentary while retaining local race and security constraints
• tighten the affected spec word-budget ratchets

Across the stack: 20 files changed, 190 insertions, 890 deletions.

Validation

• node scripts/spec-lint.mjs
• git diff --check 040bb98b..HEAD

Focused package tests did not execute locally because this clean worktree has no installed dependencies and registry access failed with ENOTFOUND; the executable-file changes are comment-only.

[dormouse-bot]

The compression reads well and the references hold up — I checked every backticked symbol added in the diff (wire.ts, terminal-state.ts, acl.ts) against the source and they all resolve and are exported. Four fixes inline, plus three losses that I think need a one-line form somewhere.

Deleting the eight Files / Code Map tables drops 24 paths out of the file→spec map. AGENTS.md — including the sentence this PR rewrites — says a spec's implementation map is exhaustive, by either a Files section or Source of truth: pointers. After this PR these appear in no spec at all:

Paths with no owning spec after this PR

lib/src/components/Baseboard.tsx
lib/src/components/Door.tsx
lib/src/components/KillConfirm.tsx
lib/src/components/MobileWall.tsx
lib/src/components/TerminalPane.tsx
lib/src/components/TodoPillBody.tsx
lib/src/components/WatchedCommandList.tsx
lib/src/components/wall/IllegalRenameWarning.tsx
lib/src/components/wall/MouseOverrideBanner.tsx
lib/src/components/wall/TerminalPanel.tsx
lib/src/components/wall/WorkspaceSelectionOverlay.tsx
lib/src/components/wall/keyboard/chords.ts
lib/src/components/wall/resolve-pane-element.ts
lib/src/components/wall/use-alert-speech.ts
lib/src/components/wall/use-dismiss-overlay.ts
lib/src/lib/selection-geometry.ts
lib/src/lib/selection-text.ts
lib/src/lib/terminal-buffer-read.ts
lib/src/lib/terminal-command-input.ts
lib/src/lib/terminal-prompt-shape.ts
lib/src/components/MobileTerminalUi.test.tsx
lib/src/components/MobileWall.test.tsx
lib/src/lib/mobile-gesture-menu.test.ts
server/test/harness/fake-host.mjs

Derived by extracting every backticked source path from the diff's removed lines and re-grepping the whole docs/specs/ tree plus AGENTS.md / SELF_HOST.md for each survivor.

Several are load-bearing rather than incidental: keyboard/chords.ts carried the copy-vs-paste modifier convention (§8.2 of mouse-and-clipboard.md), TodoPillBody.tsx was the "one implementation shared by header, Door, and mobile" claim, and terminal-prompt-shape.ts is the keystroke-fallback derivation whose test AGENTS.md cites by name. Folding each into a Source of truth: line in the section that owns it would keep the map exhaustive without bringing the tables back.

Two prohibitions from theme.md's deleted checklist have no surviving one-line form. mt- now appears zero times in theme.md, so Never reintroduce a pass-through --mt-* layer or one-off tokens for tabs, badges, accents, or button hovers is gone; and pickDoorPair / pickFocusRing appear zero times, so Never fork the dynamic picks is too. Both are exactly the shape AGENTS.md's boundary test protects — deleting the sentence lets a competent editor reintroduce the thing. The other checklist items are fine to drop: the CONSUMED_VSCODE_KEYS ↔ bundle-themes.mjs parity is pinned by lib/src/lib/themes/consumed-keys.test.ts, the @theme/body lockstep survives in the body, and Never put hardcoded color defaults or var(..., fallback) chains is still there.

Same in dor-browser.md: the deleted checklist's rule that any new proxy header rule belongs in the rewrite table and in STRIP_RESPONSE_HEADERS, and that neither the Host nor the conditional Origin gate may be relaxed without SECURITY.md → "Loopback Listeners", is gone — STRIP_RESPONSE_HEADERS now survives only inside a Source of truth: parenthetical. The AGENT_BROWSER_ALLOWED_SUBCOMMANDS row keeps enough to infer the rule, but it no longer says the host-side allowlist is the security boundary rather than the CLI.

Smaller things, not worth blocking on:

• server.md: HELLO_ROUTE is declared in server-lib-common/src/index.ts, not in wire.ts — the old wording (in server-lib-common) was right for all three constants.
• dor-cli.md: the list row drops "browser Surfaces never match, even when showing that URL" from the --port filter, which is the edge case a reader would actually get wrong.
• remote-api.md: the removed attach code block carried the only Reserved: marker for TerminalAttachResult growing additively (inflight, blocks). wire.ts's TerminalAttachResult has no comment either, so that additive-compat guarantee is now stated nowhere above the fold.
• terminal-escapes.md: the paragraph naming terminal-controls.ts and the alt-screen elision in terminal-state-store.ts as escape-aware modules downstream of the PTY boundary and owned elsewhere was a cross-spec ownership boundary, not a file list.

Not blocking, but I'd hold this for a human read rather than approve it — the mechanical checks all pass (spec-lint is green, every new symbol resolves), so what's left is a judgment call about how much normative text the compression is allowed to take with it, and that's yours rather than mine.

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	ec1b50e
Status:	✅  Deploy successful!
Preview URL:	https://ec4be3fa.mouseterm.pages.dev
Branch Preview URL:	https://spec-compress-further.mouseterm.pages.dev

View logs