Detailed design: add §23 Reference Implementation Map

Closes the traceability gap where baselineV1 §2 / decisions-round-1..3
mandate reusing mature reference-project code, but the detailed design and
class diagrams had消化d those references into own abstractions with zero
explicit "consult X here" pointers — risking context-isolated implementers
re-deriving renderers, diff engines, or skill formats from scratch.

New §23 maps each DD component to its reference project, with an explicit
reuse mode (npm-dep / fork/adapt / pattern / behavioral) and local path:
- TUI → @opentui/* (npm-dep) + OpenCode patterns (pattern)
- Provider → @opencode-ai/llm (fork/adapt)
- Execution discipline → Claude Code (behavioral)
- patch/test loop → OpenAI Codex (pattern, reference/openai-codex/)
- Knowledge/ExperienceMiner → Hermes (pattern)
- Skills → Anthropic Claude Skills (pattern, reference/anthropic-skills/)
- Logging/HUD/PTY → asciinema/Atuin/claude-hud (pattern)
- Message format → Claude Code blocks (behavioral)

Reuse rules preserve §2 import direction and §18.6 invariants; reference
internal models never leak across our boundaries (e.g. no OpenCode session
state). Freeze declaration renumbered §23 → §24. Pure documentation; zero
change to contracts, events, schema, or runtime semantics.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

AirPlan/docs/architecture/system-detailed-design.md

@@ -2355,7 +2355,51 @@ classDiagram
     ArchitectureDesigner --> EventIngestor
 ```
 
-## 23. Design Freeze Declaration
+## 23. Reference Implementation Map
+
+AirCoding is **self-owned, not a wrapper** (baselineV1 §1): the architecture and class
+design above are AirCoding's own. This section records, per baselineV1 §2 and
+`decisions-round-1/2/3`, **where an implementer should consult mature reference code**
+instead of designing a component from scratch, and the **reuse mode** for each. This is a
+guidance map, not a dependency contract — it never overrides §2 import direction or §18.6
+invariants.
+
+**Reuse modes:**
+
+- `npm-dep` — consume directly as a dependency; do not re-implement.
+- `fork/adapt` — copy and adapt source into our package; keep our own boundaries.
+- `pattern` — reference structure/patterns; implement independently.
+- `behavioral` — match observable behavior/quality; no code lineage.
+
+| DD component | Reference project (baselineV1 §2) | Reuse mode | Notes / local path |
+|---|---|---|---|
+| §13.2 TUI (`TuiApp`, components) | OpenTUI (`@opentui/solid` `@opentui/core` `@opentui/keymap`) | `npm-dep` | D-002/D-048: direct dependency; do not build a renderer. Theme/dialog/toast/keymap/layout/spinner/border/markdown/code/diff rendering adapted from OpenCode UI patterns. |
+| §13.2 TUI interaction layout | OpenCode TUI | `pattern` | D-048: reference visual/interaction patterns; **do not** reuse OpenCode SDK/sync/session business state. |
+| §12 Provider (`ProviderManager`, `ProviderAdapter`, converters) | `@opencode-ai/llm` | `fork/adapt` | D-002 list: provider/model abstraction may be forked/adapted; output stays Anthropic-canonical (D-046). |
+| §8.4 + §9.4 Execution discipline (read-before-edit, exact edit, verify-before-complete) | Claude Code CLI | `behavioral` | baselineV1 §2: quality benchmark only — edit safety, patch granularity, conflict handling, verification discipline. No code lineage. |
+| §9.4 `fs.edit`/`fs.patch` + §15 patch/test execution loop | OpenAI Codex (`reference/openai-codex/`) | `pattern` | baselineV1 §2: shell/patch/test direct-execution loop, tool orchestration, wider tool surface. |
+| §11.3 + §14 Knowledge / ExperienceMiner / Curator | Hermes Agent | `pattern` | D-024: Nudge Engine interval trigger (~10 turns/tool-calls), Curator dedup daemon, skill self-patch. |
+| §11.3 + runtime-semantics §11 Skills (`SKILL.md`, `scripts/`/`references/`/`assets/`) | Anthropic Claude Skills (`reference/anthropic-skills/`) | `pattern` | D-058: SKILL.md frontmatter + directory layout + trigger/retrieval descriptions; SkillGenerator output format. |
+| §16.2 Logging / HUD + future PTY capture | asciinema / Atuin / claude-hud | `pattern` | baselineV1 §2: PTY capture, command metadata/history indexing, HUD/statusline layout. |
+| §3 Message format (Anthropic canonical content blocks) | Claude Code message model | `behavioral` | D-016: Text/Thinking/ToolUse/ToolResult blocks; canonical internal format. |
+
+**Rules for reference reuse:**
+
+1. `npm-dep` items (`@opentui/*`) are real dependencies — implementers must not re-implement
+   them; see `packages/tui` (code-view §7).
+2. `fork/adapt` and `pattern` items: adapt into our own package layout (§2 import direction),
+   preserve our contracts (§3) and invariants (§18.6) verbatim. A reference's internal model
+   never leaks across our package boundaries — e.g. OpenCode session/sync state is **not**
+   adopted (D-048).
+3. `behavioral` items contribute **no code**; they set a quality bar verified by tests/evidence.
+4. License compliance for any copied/forked source is checked at the architecture gate before
+   merge.
+
+> **For context-isolated execution:** include the row(s) relevant to a subagent's slice in its
+> working context. The intent is to stop a partial-context implementer from re-deriving a diff
+> engine, TUI renderer, or skill format that a named reference already provides.
+
+## 24. Design Freeze Declaration
 
 **System Detailed Design is frozen as of 2026-06-01 (commit `2673e49` → this commit).**