1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
# MANIFEST.md - What Is Canonical vs State
**Authority:** reference (canonical vs derived vs state)
**Layer:** Guides
**Binding:** No
**Scope:** clarify what is source vs derived vs state
**Non-goals:** defining authority or requirements
This file answers two questions:
1. What markdown is contractually important (canonical)?
2. What directories are state and should not be treated as docs?
---
## 1. Canonical Docs
### Primary Sources (Constitution)
- `specs/INTENT.md` - Intent-driven methodology contract
- `specs/SYSTEM.md` - System definition and proof doctrine
- `specs/SECURITY.md` - Security doctrine
- `specs/GIT.md` - Git workflow contract
- `specs/AMENDMENTS.md` - Change control
### Core Indices and Routers
- `core/DECAPOD.md` - Main router and navigation charter
- `core/INTERFACES.md` - Interface contracts index
- `core/METHODOLOGY.md` - Methodology guides index
- `core/PLUGINS.md` - Subsystem registry
- `core/GAPS.md` - Gap analysis methodology
- `core/DEMANDS.md` - User demands
- `core/DEPRECATION.md` - Deprecation contract
### Interface Contracts (Binding)
- `interfaces/CLAIMS.md` - Promises ledger
- `interfaces/CONTROL_PLANE.md` - Sequencing patterns
- `interfaces/DOC_RULES.md` - Doc compilation rules
- `interfaces/GLOSSARY.md` - Term definitions
- `interfaces/STORE_MODEL.md` - Store semantics
### Methodology Guides (Reference)
- `methodology/ARCHITECTURE.md` - Architecture practice
- `methodology/SOUL.md` - Agent identity
- `methodology/KNOWLEDGE.md` - Knowledge management
- `methodology/MEMORY.md` - Agent memory and learning
### Architecture Patterns (Reference)
- `architecture/DATA.md` - Data architecture
- `architecture/CACHING.md` - Caching patterns
- `architecture/MEMORY.md` - Memory management
- `architecture/WEB.md` - Web architecture
- `architecture/CLOUD.md` - Cloud patterns
- `architecture/FRONTEND.md` - Frontend architecture
- `architecture/ALGORITHMS.md` - Algorithms and data structures
- `architecture/SECURITY.md` - Security architecture
### Agent Entrypoints (Templates)
- `AGENTS.md` (or `templates/AGENTS.md`)
- `CLAUDE.md` (or `templates/CLAUDE.md`)
- `GEMINI.md` (or `templates/GEMINI.md`)
- `CODEX.md` (or `templates/CODEX.md`)
---
## 2. Derived Docs
These are generated from canonical sources:
- `docs/REPO_MAP.md` - Repository structure map
- `docs/DOC_MAP.md` - Document dependency graph
**Do not hand-edit derived docs.**
---
## 3. State (Not Docs)
State roots contain runtime data, not documentation:
- User store: `~/.decapod/` (blank slate by default)
- Repo store: `<repo>/.decapod/project/`
- Override: `<repo>/.decapod/OVERRIDE.md`
- Checksums: `<repo>/.decapod/data/`
The `.decapod/` directories primarily contain state and configuration.
---
## 4. Proof Surface
Minimal proof surface:
- `decapod validate` - Primary validation gate
---
## Links
### Core Router
- `core/DECAPOD.md` - **Router and navigation charter (START HERE)**
### Authority (Constitution Layer)
- `specs/INTENT.md` - **Methodology contract (READ FIRST)**
- `specs/SYSTEM.md` - System definition and authority doctrine
### Registry (Core Indices)
- `core/PLUGINS.md` - Subsystem registry
- `core/INTERFACES.md` - Interface contracts index
- `core/METHODOLOGY.md` - Methodology guides index
### Contracts (Interfaces Layer)
- `interfaces/DOC_RULES.md` - Doc compilation rules
- `interfaces/STORE_MODEL.md` - Store semantics
### Operations (Plugins Layer - This Document)
- `plugins/TODO.md` - Work tracking
- `plugins/VERIFY.md` - Validation subsystem
- `plugins/EMERGENCY_PROTOCOL.md` - Emergency protocols
### Derived References
- `docs/REPO_MAP.md` - Repository structure (derived)
- `docs/DOC_MAP.md` - Document graph (derived)