Skip to content

ADR supersede chain has no terminal state — reading any single ADR gives wrong dispatch model #308

@ooloth

Description

@ooloth

Current state

A developer reading any ADR in the 005 → 006 → 009 → 012 → 013 → 014 chain concludes a different (and wrong) mental model of how task dispatch works. ADR 005 concludes "TUI keypress → tmux split"; ADR 012 supersedes it with the task dispatch loop; ADR 013 partially supersedes 012; ADR 014 partially supersedes 013. Each ADR's addendum points to the next ADR in the chain — not to a current authoritative document — so the chain never terminates. A developer researching dispatch or session launch reads the chain, draws a plausible model, and implements against integration points that don't match the current code. This affects dispatch, session launch, completion detection, and prompt injection — exactly the high-risk areas most likely to be touched.

Ideal state

  • docs/architecture/task-dispatch.md is the single authoritative description of dispatch as currently built.
  • Each ADR in the chain (005, 006, 009, 012, 013, 014) has its addendum updated to point to docs/architecture/task-dispatch.md rather than to the next ADR, so the chain terminates at a readable, current document.
  • A developer reading any ADR in the chain immediately sees "for the current implementation, read docs/architecture/task-dispatch.md."

Out of scope

  • Rewriting or deleting ADRs — they document rationale history and should be preserved.
  • Restructuring the docs/ directory.

Starting points

  • docs/decisions/005-agents-and-prompts.md — first ADR in the chain
  • docs/architecture/task-dispatch.md — the architecture document that should be the terminal reference

QA plan

  1. Open docs/decisions/005-agents-and-prompts.md — expect its supersede note to link to docs/architecture/task-dispatch.md.
  2. Open docs/decisions/012-task-dispatch-loop.md — expect the same.
  3. Open docs/decisions/013-session-file-signals.md — expect the same.
  4. Open docs/architecture/task-dispatch.md — expect it to describe the dispatch system as currently built, not a planned state.

Done when

Any ADR in the 005–014 supersede chain redirects the reader directly to docs/architecture/task-dispatch.md, which describes the system as currently implemented.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions