chore: initialize POM 2 repo (docs guards green; release gates recorded NOT RUN pending install)

docs/ARCHITECTURE.md

@@ -0,0 +1,54 @@
+# Architecture
+
+## Responsibility boundary
+
+```text
+Oh My Pi
+├── models and thinking levels
+├── native tools and approvals
+├── task agents and IRC
+├── todo, sessions, compaction, memory
+├── extension lifecycle and TUI
+└── optional Swarm extension
+
+POM
+├── stage contracts and authoritative transitions
+├── evidence, blockers, decisions, and provenance
+├── prompt stack and personality composition
+├── Hive mission planning and synthesis records
+├── artifact manifest and semantic versions
+├── deterministic validators
+├── Obsidian/Quartz knowledge projection
+├── Git stage checkpoints
+└── verified archive delivery
+```
+
+OMP executes; POM governs. POM never invents a parallel task runner, chat network, todo database, or session tree.
+
+## Runtime layers
+
+| Layer | Modules | Responsibility |
+|---|---|---|
+| Host integration | `index.ts`, `events.ts`, `command.ts` | Register commands, tools, lifecycle hooks, routing, and policy |
+| Terminal | `ui.ts`, `visual.ts`, `renderers.ts`, `themes.ts` | HUD, status, overlay, cards, themes, and thinking annotation |
+| Domain | `domain.ts`, `state.ts` | Stage contracts, schemas, transitions, blockers, evidence, versions |
+| Execution planning | `studio.ts`, `swarm.ts`, `router.ts`, `tool-profiles.ts` | Native task batches, optional DAGs, model roles, active tools |
+| Knowledge and persistence | `prompts.ts`, `persistence.ts`, `paths.ts` | Prompt provenance, canonical files, vault, manifests, ledgers |
+| Assurance | `validators.ts`, `policy.ts`, `zip.ts`, `exporter.ts`, `git.ts` | Gates, path safety, command guard, checkpoints, archive verification |
+
+## Truth hierarchy
+
+1. System and explicit user requirements.
+2. Canonical project files and `00_admin/project_state.json`.
+3. Artifact manifest, evidence records, and append-only ledgers.
+4. Native OMP todo/task/IRC/session state for live execution.
+5. Generated vault notes as navigational projections.
+6. Memory as reusable heuristics only—never story canon.
+
+## Stage transition invariant
+
+A stage can pass only when it is actively running, all prerequisites are complete, every acceptance criterion has file-backed evidence, no blocker remains open, and deterministic validation produced a report path.
+
+## Persistence
+
+POM stores state both in OMP's append-only session entries and in the canonical project file. File writes use unique temporary paths followed by rename. Manifest and ledger mutation is serialized within the process. Files are resolved through canonical paths and symbolic-link escapes are rejected.