docs: unify ADR/RFC trees into one lifecycle-organized RFC tree

Collapse docs/adr/ and docs/rfc/ into a single docs/rfc/ with proposed/,
implemented/, and rejected/ subfolders. Every file is renamed to
yyyy-mm-dd-topic-title.md, where the date is when the topic was first
proposed (from git history). ADRs and RFCs that covered exactly the same
topic are merged (property-based testing, session persistence); the
umbrella RFC 005 stays split across its three implemented decisions, and
RFC 006's deferred part-3 (API extractor reports) splits into its own
proposed RFC. All cross-references become machine-checkable relative
links instead of bare "ADR NNNN" / "RFC NNN" prose.

Add a verify-md-links doc-sync gate (scripts/verify-md-links.ts) that
checks every relative Markdown cross-link resolves, wired into doc-sync
alongside verify-md-wrap. This makes the reorganization self-verifying:
the same change that rewrote ~forty inter-doc links adds the check that
proves none dangle. Document the cross-link convention in a new
docs/AGENTS.md and record the gate as an implemented RFC.

doc-sync, typecheck, lint, and the full test suite (667) all pass.

packages/agent-loop/README.md

@@ -13,7 +13,7 @@ This is the only package in the harness that contains concrete loop logic. Every
 `AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):
 
 - `ctx.agents.create({ agentId, sessionId, meta?, agentOptions? })` — programmatic create on a caller-supplied `sessionId` (e.g. an ACP-generated id), NOT `${id}-session`.
-- `ctx.agents.resume({ agentId, resumeSessionId, agentOptions? })` — load a persisted session via `ctx.sessionPersistence` (RFC 009) and resume an agent on it. The live session id is the resumed id; turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent).
+- `ctx.agents.resume({ agentId, resumeSessionId, agentOptions? })` — load a persisted session via `ctx.sessionPersistence` ([session persistence](../../docs/rfc/implemented/2026-06-14-session-persistence.md)) and resume an agent on it. The live session id is the resumed id; turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent).
 
 ### Injected services
 

packages/agent-loop/src/loop.ts

@@ -119,7 +119,7 @@ export interface LoopHandle {
  *     drain queued → 'turn/start' → session('user/message'…) → emit agent/turn-start
  *     STEP loop:
  *       drain steering → session('steering/message')  ⟵ catches late steering
- *       session('step/start'); emit agent/step-start    ⟵ append before emit (ADR 0003)
+ *       session('step/start'); emit agent/step-start    ⟵ append before emit (the event-sourcing RFC)
  *       assembly = ctx.systemPrompt.assemble()        ⟵ waterfall system-prompt/assemble
  *       req = {model, system, tools, messages: session.deriveMessages(), signal}
  *       req = waterfall agent/request                 ⟵ hooks/compaction/model-switch
@@ -161,7 +161,7 @@ export async function runLoop(ctx: Context, agent: LoopAgent, handle: LoopHandle
       // before turn/start) — no turn/start was appended, so no turn is open and
       // none is owed. A session `error` here would land outside any turn (after
       // the previous turn/end), where the persistence backend drops it as a
-      // crash tail (ADR 0017). Report via agent/error + the logger only; the
+      // crash tail (the turn-enclosure RFC). Report via agent/error + the logger only; the
       // driver survives and moves on.
       const err = toError(error)
       ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${err.message}`)
@@ -202,7 +202,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
   // Close the open step exactly once (idempotent via stepOpen). The
   // agent/step-end emit is contained: a throwing step-end listener must not
   // abort finalization and strand the turn open (turn/end balance > notifying
-  // one bad listener). Appended before the emit (ADR 0003 append-before-emit).
+  // one bad listener). Appended before the emit (the event-sourcing RFC append-before-emit).
   const closeStep = (): void => {
     if (!stepOpen) return
     stepOpen = false
@@ -241,7 +241,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
     // turn has already ended — the only way here is a throwing agent/turn-end
     // listener after closeTurn(true) already appended turn/end — appending now
     // would land the error AFTER the last turn/end, where the persistence
-    // backend treats it as a crash tail and drops it on resume (ADR 0017). In
+    // backend treats it as a crash tail and drops it on resume (the turn-enclosure RFC). In
     // that case report via agent/error + the logger only; the turn is balanced.
     if (!turnEnded) {
       // Set `reason` BEFORE the append: Session.append pushes the error event
@@ -346,7 +346,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
       }
 
       // The successful step's finish reason carries forward: a `max-tokens`
-      // step makes the whole turn end `max-tokens` (RFC 010's rule "any
+      // step makes the whole turn end `max-tokens` (the ACP RFC's rule "any
       // max-tokens step surfaces as max-tokens"). `stepFinishReason` returns
       // `max-tokens` or `undefined`, so a later ordinary step never resets a
       // max-tokens turn back to completed, and a never-truncated turn keeps the
@@ -393,7 +393,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
     // so a throwing listener on the `turn/start` append leaves turn/start in the
     // log even though execution never reached the lines after that append.
     // Gating on a "turn started" boolean would skip turn/end and leave a
-    // permanently OPEN turn that poisons the next turn/replay (ADR 0017). We
+    // permanently OPEN turn that poisons the next turn/replay (the turn-enclosure RFC). We
     // check the log for THIS turn's turn/start: present means a turn/end is owed
     // (or was already appended — closeTurn/failTurn are idempotent, so running
     // them again is a safe no-op that still preserves the disposed/error reason
@@ -428,7 +428,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
     // AFTER turn/end to be a checkpoint — so there is no in-turn position left
     // for a session `error` event. Appending one here would land it after the
     // last turn/end, where the persistence backend treats it as a crash tail
-    // and drops it on resume (ADR 0017: every event is turn-enclosed). Report
+    // and drops it on resume (the turn-enclosure RFC: every event is turn-enclosed). Report
     // the failure via agent/error + the logger only; persistence keeps the
     // buffered events for the next flush/dispose, so nothing is lost.
     const err = toError(error)
@@ -568,7 +568,7 @@ export function lastTurnNumber(session: Session): number {
  * before `turn/start`, or the post-`turn/end` flush window before status
  * returns to idle), so status is not a reliable open-turn signal. Used by
  * `inject()` to choose between appending into an open turn vs. wrapping the
- * injection in its own one-shot turn (ADR 0017).
+ * injection in its own one-shot turn (the turn-enclosure RFC).
  */
 export function isTurnOpen(session: Session): boolean {
   const last = session.events.findLast(e => e.type === 'turn/start' || e.type === 'turn/end')

packages/agent-loop/tests/coverage-edges.spec.ts

@@ -301,7 +301,7 @@ describe('disposed vs aborted branching', () => {
   })
 })
 
-describe('structured tool error propagation (RFC 005 pt 2)', () => {
+describe('structured tool error propagation (the runtime-validation RFC, part 2)', () => {
   it('forwards a tool HarnessError onto the tool/result session event', async () => {
     const { HarnessError } = await import('@deepseek-ai/dsh-llm')
     // First model turn calls the tool; second turn (after the tool result is

packages/agent-loop/tests/properties.spec.ts

@@ -1,8 +1,8 @@
 /**
- * Property-based tests for the agent loop's inbox/turn scheduling (RFC 001 →
- * ADR 0013). Deterministic by construction: schedules are driven through the
- * `agent/status` settle signal (no wall-clock sleeps), so a flake is a finding,
- * not timing noise.
+ * Property-based tests for the agent loop's inbox/turn scheduling (the
+ * property-testing RFC). Deterministic by construction: schedules are driven
+ * through the `agent/status` settle signal (no wall-clock sleeps), so a flake
+ * is a finding, not timing noise.
  *
  * Invariants: every sent message appears exactly once in the log (none lost);
  * turn numbers strictly increase; status transitions follow the legal machine

packages/agent-loop/tests/resume.spec.ts

@@ -39,7 +39,7 @@ function waitForIdle(ctx: Context, agent: LoopAgent): Promise<void> {
   })
 }
 
-describe('RFC 009: AgentLoop factory create/resume', () => {
+describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
   it('createAgent uses the caller-supplied sessionId (not ${id}-session)', async () => {
     const adapter = new MockAdapter([textResponse('hi')])
     const { ctx } = await persistentHarness(adapter)
@@ -128,7 +128,7 @@ describe('RFC 009: AgentLoop factory create/resume', () => {
 
   it('an idle inject() is flushed durably on its own (survives without explicit flush/dispose)', async () => {
     // Lifecycle 1: run a turn, then inject context while idle. The idle inject
-    // wraps its context/message in a one-shot turn AND checkpoints it (ADR 0017)
+    // wraps its context/message in a one-shot turn AND checkpoints it (the turn-enclosure RFC)
     // — without an explicit flush or clean dispose, the notice must still reach
     // disk, since a crash before the next turn would otherwise lose it.
     const adapter1 = new MockAdapter([textResponse('answer')])

packages/agent-loop/tests/review-fixes.spec.ts

@@ -619,7 +619,7 @@ describe('P1-6: step/start is appended before agent/step-start is emitted', () =
     const agent = ctx.agentLoop.create('a-step-order', { model: 'mock' })
 
     // Capture, at the moment agent/step-start fires, whether the matching
-    // step/start event is already in the log (append-before-emit, ADR 0003).
+    // step/start event is already in the log (append-before-emit, the event-sourcing RFC).
     const observed: { turn: number; step: number; lastEventType: string | undefined; sawStepStart: boolean }[] = []
     ctx.on('agent/step-start', (subject, turn, step) => {
       if (subject !== agent) return
@@ -828,7 +828,7 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
     // loop must therefore still owe (and append) a turn/end — deciding "owed"
     // from the log via isTurnOpen, not a "turn started" flag that the throw
     // skipped. Otherwise the turn stays permanently open and poisons the next
-    // turn/replay (ADR 0017). (Uses the plain harness — NOT the invariants
+    // turn/replay (the turn-enclosure RFC). (Uses the plain harness — NOT the invariants
     // oracle — because the throwing listener is itself a session/event
     // subscriber.)
     const adapter = new MockAdapter([textResponse('turn 2')])
@@ -868,7 +868,7 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
     // Regression: a normal turn completes, closeTurn(true) appends turn/end and
     // emits agent/turn-end whose listener throws. The error must NOT be appended
     // as a session event after turn/end — that would sit past the commit
-    // boundary and be dropped as a crash tail on resume (ADR 0017). It is
+    // boundary and be dropped as a crash tail on resume (the turn-enclosure RFC). It is
     // surfaced via agent/error instead, and the log's last event is turn/end.
     const adapter = new MockAdapter([textResponse('done'), textResponse('next ok')])
     const ctx = await balancedHarness(adapter)