Document runtime authority hard-cut plan

[TraderSamwise]

Summary

• add the runtime-core hard-cut roadmap for topology/exchange authority
• inventory runtime, coordination, projection, remote, and migration authority domains
• add dead-path audit commands for future implementation phases

Verification

• yarn typecheck && yarn lint && yarn test

Summary by CodeRabbit

• Documentation
  • Added a hard-cut roadmap outlining the plan, execution epics, risks, and recommended order for consolidating to a single authoritative runtime model.
  • Added an authority inventory with standardized status labels, authority types, and a domain matrix for current vs. target authority.
  • Added a dead-path audit checklist with step-by-step guidance to locate, demote, or remove legacy authority-bearing paths and a completion gate for verification.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 52855436-4231-44a8-9cf2-eca77117b4b2

📥 Commits

Reviewing files that changed from the base of the PR and between 41b82b3 and 72d54b7.

📒 Files selected for processing (2)

• docs/runtime-authority-dead-paths.md
• docs/runtime-core-hard-cut-roadmap.md

✅ Files skipped from review due to trivial changes (2)

• docs/runtime-core-hard-cut-roadmap.md
• docs/runtime-authority-dead-paths.md

---

📝 Walkthrough

Walkthrough

This PR adds three documentation files: a roadmap defining the target runtime authority model and execution epics, an authority inventory mapping domains to target authority and audit columns, and a dead-path checklist with domain-by-domain guidance and a completion gate.

Changes

Runtime-Core Hard-Cut Planning and Audit

Layer / File(s)	Summary
Runtime hard-cut roadmap and target architecture docs/runtime-core-hard-cut-roadmap.md	Defines the target end-state authority split (topology, exchange, projection clients), lists current vs pending cut status, and enumerates ten execution epics from authority inventory through migration tooling and dead-path audits, with recommended sequencing and risk notes covering communication semantics, security, metadata hazards, and lifecycle recoverability.
Authority inventory and domain mapping docs/runtime-authority-inventory.md	Introduces standardized status labels and authority type vocabulary, then provides a domain matrix table specifying per-domain current authority, target authority, readers/writers, and what should remain as projection/cache versus what must be removed or demoted, covering lifecycle through relay infrastructure.
Dead-path audit checklist organized by domain docs/runtime-authority-dead-paths.md	Provides domain-by-domain audit guidance specifying acceptable legacy patterns and concrete removal criteria for agent lifecycle, tmux bindings, team/role routing, services, worktrees, exchange state, plans, continuity, tasks/reviews, inbox/waiting, projections, GUI/CLI/API surfaces, daemon/remote/presence, and debug/migration constraints, with final verification gates.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 I hopped through docs, a tidy trail,
A roadmap, inventory, checklist to hail,
Dead paths marked, projections kept light,
One authoritative runtime now in sight,
🥕 onward to the cut—clean and bright.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main change: adding comprehensive documentation for the runtime authority hard-cut plan, including roadmap, inventory, and dead-path audit guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch audit/runtime-authority-inventory

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

docs/runtime-authority-dead-paths.md (1)

214-221: 💤 Low value

Align completion gate verification with PR verification steps.

The completion gate requires "yarn build before manual runtime testing" (line 221), but the PR description lists verification steps as yarn typecheck && yarn lint && yarn test without mentioning yarn build. Consider either adding yarn build to the standard verification sequence or clarifying when build verification is required versus optional.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/runtime-authority-dead-paths.md` around lines 214 - 221, Update the
Completion Gate wording so the verification steps match the PR verification
checklist: either add "yarn build" to the standard verification sequence
referenced in the PR (replace or extend `yarn typecheck && yarn lint && yarn
test` to include `&& yarn build`) or explicitly state that "yarn build" is only
required before manual runtime testing (keep PR checks as-is but add a
parenthetical note under "Completion Gate" clarifying when build verification is
mandatory). Reference the "Completion Gate" heading and the exact commands `yarn
build` and `yarn typecheck && yarn lint && yarn test` to make the change clear.

docs/runtime-core-hard-cut-roadmap.md (1)

217-228: 💤 Low value

Consider removing or enhancing the "Recommended Order" section.

This section currently just repeats the epic numbers and titles in order 1-10, which is already the presentation order in "Execution Epics." Either add meaningful sequencing rationale (e.g., dependencies, parallel tracks, risk-driven ordering) or remove the redundant section.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/runtime-core-hard-cut-roadmap.md` around lines 217 - 228, The
"Recommended Order" section currently duplicates the "Execution Epics" list;
either remove the entire "Recommended Order" heading and its numbered list or
replace it with a short rationale that explains sequencing (for example,
dependency-driven ordering, parallel tracks, risk/prioritization criteria, and
which epics must precede others). Update the text under the "Recommended Order"
heading to reference specific epic names/numbers from the "Execution Epics"
(e.g., "Authority map and dead-path inventory", "Topology and exchange schema
completion", "Agent lifecycle hard cut") and describe why those items are
ordered or which can be executed in parallel, or delete the section if no
additional sequencing rationale is provided.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/runtime-authority-dead-paths.md`:
- Around line 214-221: Update the Completion Gate wording so the verification
steps match the PR verification checklist: either add "yarn build" to the
standard verification sequence referenced in the PR (replace or extend `yarn
typecheck && yarn lint && yarn test` to include `&& yarn build`) or explicitly
state that "yarn build" is only required before manual runtime testing (keep PR
checks as-is but add a parenthetical note under "Completion Gate" clarifying
when build verification is mandatory). Reference the "Completion Gate" heading
and the exact commands `yarn build` and `yarn typecheck && yarn lint && yarn
test` to make the change clear.

In `@docs/runtime-core-hard-cut-roadmap.md`:
- Around line 217-228: The "Recommended Order" section currently duplicates the
"Execution Epics" list; either remove the entire "Recommended Order" heading and
its numbered list or replace it with a short rationale that explains sequencing
(for example, dependency-driven ordering, parallel tracks, risk/prioritization
criteria, and which epics must precede others). Update the text under the
"Recommended Order" heading to reference specific epic names/numbers from the
"Execution Epics" (e.g., "Authority map and dead-path inventory", "Topology and
exchange schema completion", "Agent lifecycle hard cut") and describe why those
items are ordered or which can be executed in parallel, or delete the section if
no additional sequencing rationale is provided.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ad7705ef-d07e-4a23-9fae-1c4f580ae143

📥 Commits

Reviewing files that changed from the base of the PR and between 298d5a1 and 41b82b3.

📒 Files selected for processing (3)

• docs/runtime-authority-dead-paths.md
• docs/runtime-authority-inventory.md
• docs/runtime-core-hard-cut-roadmap.md