Add Dialogue feature specification + deferred-specs policy

CLAUDE.md

@@ -328,6 +328,8 @@ When starting a task:
 
 - `docs/architecture/relay-cloud-architecture.md` — full architecture (23 sections, reviewed 5+ rounds)
 - `docs/architecture/relay-cloud-decomposition.md` — task decomposition (30 tasks, 5 waves)
+- `docs/architecture/dialogue.md` — Dialogue feature spec (structured chat UI for agent sessions; EPIC #250) — **deferred, snapshot 2026-04-18**
+- `docs/architecture/dialogue-events.md` — Claude Code stream-json event catalog (parser contract for Dialogue) — **deferred, snapshot 2026-04-18; re-verify against current CLI before implementation**
 - `docs/testplans/` — 114 test cases across 14 files (see `docs/testplans/00-strategy.md`)
 - `runner/README.md` — runner setup guide
 
@@ -399,8 +401,45 @@ Documentation lives in `docs/` and component-level READMEs (e.g., `runner/README
 ### Rules
 - Update docs **in the same PR** as the code change — not as a follow-up
 - Docs describe what IS (based on code), not what was planned
+- **Exception:** deferred feature specs (see §Deferred feature specs below) intentionally document planned state — the deferred-spec banner + re-verification obligation substitute for the "describe what IS" rule until implementation begins
 - When closing an issue or merging a feature PR, verify affected docs are current
 
+### Deferred feature specs
+
+When a feature is decomposed into a GitHub epic + child issues but implementation is **deferred** (will happen later, not immediately), the complete specification MUST be committed to `docs/architecture/<feature-slug>.md` (plus auxiliary files like `<feature-slug>-events.md` for wire protocols, etc.). Research artefacts in `swarm-report/` are ephemeral and should not be relied on as a source of truth — they live in development worktrees and disappear with them.
+
+A deferred spec is a **snapshot in time**. The codebase continues to evolve while the spec sleeps; when implementation finally starts, the spec may drift from `main`. The rules below protect against picking up stale designs.
+
+#### Mandatory status banner
+
+Every deferred spec file places a prominent banner immediately after the H1 title (no other content between `# Title` and the banner):
+
+```markdown
+> ⚠️ **Status: Deferred — specification only, not yet implemented.**
+>
+> Snapshot as of **YYYY-MM-DD**. Implementation tracked in [EPIC #N](link).
+> Until work starts, this document may drift from the current codebase.
+>
+> **Before picking up the first child task:** re-verify this spec against
+> current `main`. Update affected sections in the same PR that begins
+> implementation. Once the MVP lands, remove this banner and replace with
+> `Status: Implemented` + a "Last updated" date.
+```
+
+The banner communicates three things: (1) the doc is aspirational, not yet shipped; (2) the date of the snapshot, so drift is measurable; (3) the re-verification obligation on the first implementation PR.
+
+#### Lifecycle rules
+
+- **One spec file per feature** in `docs/architecture/` — named `<slug>.md`. Auxiliary spec files share the slug prefix (e.g., `dialogue-events.md`).
+- **Epic references the doc**, doc references the epic — both ways linked (`docs/architecture/dialogue.md` cites `EPIC #250`, epic body cites the doc path).
+- **Status banner is mandatory** on any deferred spec — see format above. Not optional.
+- **Re-verify before implementation** — the first child-task PR includes an audit: check that modules, APIs, dependencies, and risks cited in the spec still match `main`. Any drift is fixed in the same PR, not deferred further.
+- **Spec is living after implementation begins** — updated in the same PR as any child-issue PR that deviates from or clarifies the design. Docs describe what IS, not what was planned.
+- **Status transitions** — when the MVP acceptance criteria are met, replace the `Deferred` banner with `Status: Implemented` + `Last updated: YYYY-MM-DD`. When the feature ships a new major iteration, update the "Last updated" date.
+- **Epic + docs are the durable artefact** after the worktree is cleaned up. The research report in `swarm-report/` may be removed along with its worktree at any time; everything that must persist already lives on main.
+- **Cleanup after decomposition** — when the decomposition PR merges and no implementation is planned in the immediate session, remove the research worktree (`git worktree remove .worktree/<slug>`). Before removing, audit `swarm-report/<slug>*` in the worktree: everything that must persist (spec, diagrams, decisions) has to be in `docs/architecture/` or referenced from an issue body. Anything else is ephemeral and gets discarded with the worktree. The branch can stay for history or be deleted; the spec on main is canonical.
+- **Retirement** — if a deferred spec is abandoned (product decision to never build, or superseded by a different approach), don't silently delete — replace the banner with `Status: Archived — superseded by <ref>` or `Status: Archived — not pursued`, keep the file for historical context. Remove after one release cycle if no references remain.
+
 ### Quality gate
 Before merging, verify:
 - If the change adds/modifies a feature → corresponding docs updated