# Design Docs Audit

**Date:** 2026-02-11  
**Author:** usurobor (aka Axiom)  
**Contributors:** Sigma  
**Context:** Post cn_protocol.ml implementation (4 typed FSMs)  

---

## Summary

17 design docs audited. The FSM implementation in `cn_protocol.ml` supersedes 6 docs that described the same GTD/inbox/transport mechanics with different (now outdated) type definitions. Three overlap clusters identified.

## Audit Table

| Document | Status | Action | Notes |
|----------|--------|--------|-------|
| **ARCHITECTURE.md** | NEW | Created | Top-level entry point. See [../architecture/ARCHITECTURE.md](../architecture/ARCHITECTURE.md) |
| **MANIFESTO.md** | Current | Keep | Foundational values doc. Not a technical spec. |
| **WHITEPAPER.md** | Moved | Current | CN protocol spec (v3.0.0). §10 rewritten as relationship table. System thesis in `docs/THESIS.md`. |
| **WHITEPAPER-v2.0.3.pdf** | Current | Keep | PDF companion to whitepaper. |
| **PROTOCOL.md** | Current | Keep | FSM design spec. Matches `cn_protocol.ml` implementation exactly. |
| **AGILE-PROCESS.md** | Deleted (v3.15.2) | Removed | CDD supersedes; see CDD.md §4.1 lifecycle. |
| **EXECUTABLE-SKILLS.md** | Current | Keep | Vision paper (aspirational). Companion to whitepaper. |
| **CLI.md** | Partially current | Keep, update later | Command list partly matches implementation. Some commands unimplemented. |
| **DAEMON.md** | Current | Keep | Explicitly aspirational/future. |
| **LOGGING.md** | Partially current | Keep, update later | JSONL schema correct; JS examples outdated (now OCaml). |
| **SECURITY-MODEL.md** | Partially current | Keep, update later | Principles correct; some file paths stale. |
| **ACTOR-MODEL-DESIGN.md** | Superseded | Archive | Superseded by PROTOCOL.md. Incident RCA preserved in original. |
| **AGENT-MODEL.md** | Superseded | Archive | Superseded by PROTOCOL.md + cn_agent.ml implementation. |
| **CN-ACTIONS.md** | Superseded | Archive | Proposed action library never implemented. cn_agent.ml has different op types. |
| **CN-PROTOCOL.md** | Superseded | Archive | Action catalog superseded by PROTOCOL.md. |
| **INBOX-ARCHITECTURE.md** | Superseded | Archive | Triage model superseded by Actor FSM + Thread FSM. |
| **THREADS-MODEL.md** | Superseded | Archive | Directory paths and flow superseded by PROTOCOL.md. |
| **THREADS-UNIFIED.md** | Partially current | Archive | "Thread = unit of work" insight adopted; backlog-as-threads not implemented. |

### Status Legend

- **Current** — Actively reflects the codebase and design intent
- **Partially current** — Core ideas correct, some details stale
- **Superseded** — Replaced by newer doc or implementation
- **NEW** — Created in this audit

### Action Legend

- **Keep** — No changes needed
- **Keep, update later** — Correct enough to keep; queue updates for accuracy
- **Archive** — Move to `_archive/` with deprecation header
- **Created** — New document

## Overlap Clusters

### Cluster A: Agent Purity + GTD Model (6 docs)

ACTOR-MODEL-DESIGN, AGENT-MODEL, INBOX-ARCHITECTURE, THREADS-UNIFIED, CN-ACTIONS, CN-PROTOCOL

All describe: agent is pure, cn executes, decisions are GTD.
**Resolved by:** PROTOCOL.md (Thread FSM + Actor FSM) + `cn_protocol.ml`

### Cluster B: Inbox/Outbox Transport Flow (4 docs)

THREADS-MODEL, INBOX-ARCHITECTURE, ACTOR-MODEL-DESIGN, CLI

All describe: materialize-triage-execute pipeline.
**Resolved by:** PROTOCOL.md (Sender FSM + Receiver FSM) + `cn_mail.ml`

### Cluster C: Philosophy/Strategy (3 docs, low redundancy)

MANIFESTO, WHITEPAPER (now in identity/), EXECUTABLE-SKILLS

Each serves a distinct purpose (pitch, spec, vision). No action needed.

## Unique Content Preserved in Archived Docs

Content worth noting that lives only in archived docs:

| Content | Source | Recommendation |
|---------|--------|----------------|
| 2026-02-05 incident RCA | ACTOR-MODEL-DESIGN.md s1 | Preserved in archive; consider extracting to docs/beta/evidence/rca/ |
| "event = commit, trigger = hash" | ACTOR-MODEL-DESIGN.md s4.4 | Captured in PROTOCOL.md implementation |
| Cadence types (daily/weekly/monthly/quarterly/yearly) | AGENT-MODEL.md | Aspirational; not yet implemented |
| "Tokens for thinking, electrons for clockwork" | INBOX-ARCHITECTURE.md | Motto; preserved in archive |
| Protocol enforcement rules | CN-PROTOCOL.md | Consider adding to SECURITY-MODEL.md |
| Unix action composition patterns | CN-ACTIONS.md | Design pattern; preserved in archive |

## Post-Audit Structure

```
docs/
 +-- ARCHITECTURE.md              <-- NEW: top-level entry point
 +-- README.md                    <-- Updated with new hierarchy
 +-- design/
 |    +-- AUDIT.md                <-- THIS FILE
 |    +-- MANIFESTO.md         Keep
 |    +-- WHITEPAPER.md        Moved → explanation/WHITEPAPER.md
 |    +-- WHITEPAPER-v2.0.3.pdf Keep (companion to protocol paper)
 |    +-- PROTOCOL.md         Keep (matches implementation)
 |    +-- AGILE-PROCESS.md        Deleted (CDD supersedes)
 |    +-- EXECUTABLE-SKILLS.md Keep
 |    +-- CLI.md               Keep (update later)
 |    +-- DAEMON.md            Keep
 |    +-- LOGGING.md           Keep (update later)
 |    +-- SECURITY-MODEL.md       Keep (update later)
 |    +-- _archive/
 |         +-- ACTOR-MODEL-DESIGN.md
 |         +-- AGENT-MODEL.md
 |         +-- CN-ACTIONS.md
 |         +-- CN-PROTOCOL.md
 |         +-- INBOX-ARCHITECTURE.md
 |         +-- THREADS-MODEL.md
 |         +-- THREADS-UNIFIED.md
```
