docs(specs): give every spec a unique sequence number - #971

edwin-zvs · 2026-07-26T19:13:00Z

AGENTS.md asks for a stable sequence number per spec. It had drifted badly: 27 numbers were claimed by more than one spec, going back to 0013 in May. Triples at 0031, 0079, and 0093. Every collision came from the same cause — parallel branches each picking "the next number" and merging out of order.

This PR gives all 51 affected files a unique number. After it, ls specs/ | sed 's/-.*//' | sort | uniq -d is empty.

The rule

Within each collided group, the spec that owns the most inbound anchors keeps the number; the rest move to fresh numbers (0118–0148). Where a group had no anchors at all, the earliest-committed spec keeps it. The point is to minimize edits — every anchor left untouched is one that can't be got wrong.

The hard part: attributing bare anchors

Most specs are cited in code as a bare spec 0079 comment, and a bare number is ambiguous precisely because the number was shared. I read each of ~130 such comments and attributed it to the specific spec it actually describes. Fourteen belonged to a spec that moved, and were updated:

moved spec	new	anchors updated
`0031-claude-oauth-direct-api`	0125	2 — smith provider routing
`0076-program-selection-run-comment`	0137	6 — selection-Run fork records
`0079-harness-native-session-id-tracks-clear`	0138	3 — pi adapter + harness docs
`0079-fork-and-subagent-lineage-view`	0139	2 — lineage popup, fork merge
`0082-terminal-keyboard-disambiguation`	0140	1 — kitty keyboard protocol

Anchors belonging to a spec that kept its number were deliberately left alone.

Two attributions were genuinely ambiguous from the comment text and worth a reviewer's eye — both resolved by reading surrounding code, both landed on a keeper so neither produced an edit:

crates/daemon/src/session/events.rs:768 — "spec 0079's documented behavior", resolved to the subagent-mirrors spec (the surrounding block is about restoring archived mirrors).
crates/cli/src/app/minibuffer.rs:831 — "(spec 0079) so there is exactly one merge/discard code path", resolved to the lineage-view spec (the doc comment names the lineage popup's m/d keys).

Also

Every inbound spec-to-spec link updated (both [text](file.md) and [[wikilink]] forms).
One link in 0088-grok-native-discovery-excludes-sibling-sessions whose label still read 0079 after its target moved to 0138.

Verification

No duplicate numbers remain.
Every spec's H1 matches its filename.
No reference to any old slug survives anywhere in the tree.
Every specs/NNNN-slug.md path cited from code resolves to a real file.
Every intra-spec markdown link and wikilink resolves.
cargo build green.

No behavior change — file renames, comments, and docs only.

🤖 Generated with Claude Code

Two specs landed on the same sequence number today from parallel branches: 0113-model-routing-is-proxy-transported (#955) and 0113-split-layout-is-shared-daemon-state (#968). The routing spec keeps 0113: it heads a contiguous block (0113-0117) whose members already cross-reference it by number, so moving it would churn five files and their inbound links. The split-layout spec moves instead. It goes to 0118 rather than 0114 because 0114 is taken by 0114-session-route-is-durable-session-state, another member of that same routing block. Updates the spec heading, the two inbound spec links (0039, 0065), and the five bare "spec 0113" comments in the split-pane code. The router's own "spec 0113" comments are deliberately left alone.

Same rule as the 0113 split in the previous commit: where two specs share a number, the one with fewer inbound anchors moves, so the rename touches as little as possible. - 0109-smith-codex-prompt-cache-routing -> 0119 (0 code anchors; 0109-suggestion-deck holds 17 and keeps the number) - 0110-construct-new-harness-argv -> 0120 (0 code anchors; 0110-minibuffer-harness-completion-menu holds 1) - 0112-client-grid-matches-pty-geometry -> 0121 (1 code anchor, updated; 0112-tall-footer-slides-the-main-block holds 18 and keeps the number) Only 0121 needed a code edit: the mirror-hydration comment in the web UI that explains why a passive mirror never claims PTY geometry.

The sequence had 24 numbers claimed by more than one spec, going back to 0013 — triples at 0031, 0079, and 0093. All of them came from parallel branches picking the same next number and merging out of order. Same rule as the previous two commits, applied uniformly: within each collided group the spec that owns the most inbound anchors keeps the number, and the rest move to fresh numbers (0122-0148). Where a group had no anchors at all, the earliest-committed spec keeps the number. This minimizes edits, so there is less surface to get wrong. Attribution was done by reading each bare "spec NNNN" comment and deciding which of the collided specs it actually refers to — a bare number is ambiguous precisely because the number was shared. Fourteen such anchors belonged to a moved spec and were updated: - 0031-claude-oauth-direct-api -> 0125 (2, smith provider routing) - 0076-program-selection-run-comment -> 0137 (6, selection-Run fork) - 0079-harness-native-session-id-tracks-clear -> 0138 (3, pi + docs) - 0079-fork-and-subagent-lineage-view -> 0139 (2, lineage popup) - 0082-terminal-keyboard-disambiguation -> 0140 (1, kitty protocol) Anchors belonging to a spec that kept its number were left alone. Also updates every inbound spec-to-spec link and one link whose label still read the old number after its target moved. Verified: no duplicate numbers remain, every spec's H1 matches its filename, no reference to an old slug survives anywhere in the tree, and cargo build is green.

A concurrent commit on main claimed 0151 for ambient-feature status; keep sequence numbers unique (per #971) by moving the plugin-system spec to 0152 and updating every plugin-related code/doc reference.

…979) * feat(plugins): user-invocable actions and event hooks (phase 2) Builds on the spec-0151 manifest with two dynamic extension points: - [[actions]]: user-invocable commands listed via the new plugin.list_actions IPC method and run via plugin.run_action. The TUI populates its palette/slash surface from the daemon list at runtime — any unknown slash token is tried against it before rejection, so /<plugin>:<action> works without a client release; /plugins lists everything. session-context actions receive the invoking session's id. - [[events]]: the daemon spawns a hook's command when a handled session event matches its declarations (event type tag, or status:<state>), with CONSTRUCT_PLUGIN_EVENT + CONSTRUCT_PLUGIN_EVENT_JSON in the env, optional per-hook debounce_ms, fire-and-forget with logged exit. The event funnel pays a single has-hooks check when no plugin subscribes. Action/hook processes run with the plugin root as cwd, plugin identity env, CONSTRUCT_SOCKET (the daemon's actual socket, override-safe), and CONSTRUCT_BIN_PATH. Deferred (recorded in the spec): key-chord/MIDI binding to plugin actions (KeyAction is Copy across the TUI; needs its own design) and the web client surface (the web UI has no command palette yet). Plugin actions carry no default chords, so spec-0150 parity is unaffected. * chore(specs): renumber plugin spec 0151 -> 0152 A concurrent commit on main claimed 0151 for ambient-feature status; keep sequence numbers unique (per #971) by moving the plugin-system spec to 0152 and updating every plugin-related code/doc reference.

edwin-zvs added 3 commits July 26, 2026 12:12

edwin-zvs changed the title ~~docs(specs): renumber the split-layout spec 0113 -> 0118~~ docs(specs): give every spec a unique sequence number Jul 26, 2026

edwin-zvs merged commit 09d5f39 into main Jul 26, 2026
1 check passed

edwin-zvs deleted the spec-renumber-0118 branch July 26, 2026 22:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(specs): give every spec a unique sequence number - #971