@mangold/rvault 0.1.0

package/templates/research-vault/VAULT_PROTOCOL.md

@@ -0,0 +1,432 @@
+# Research Vault Protocol
+
+> **Purpose**: Convert idle coding-agent capacity into durable, decision-ready intellectual capital through autonomous research, synthesis, and self-critique — with minimal human supervision.
+
+> **Safety envelope**: Agents operating under this protocol MAY perform web searches, read project files, and write to the vault directory. They MUST NOT modify project source code, run arbitrary executables, or access sensitive credentials. All outputs are markdown files in the vault tree.
+
+> **Governance**: This protocol is subordinate to `VAULT_CONSTITUTION.md`. The constitution defines inviolable principles, the amendment process, and roles (such as the Constitutional Reviewer) that oversee this protocol's soundness. Read the constitution first.
+
+---
+
+## 1. Directory Structure
+
+```
+research-vault/
+├── VAULT_CONSTITUTION.md      ← read first, always — governs the protocol
+├── VAULT_PROTOCOL.md          ← operational procedures (subordinate to constitution)
+├── MANIFEST.md                ← live index of all vault state
+├── governance/
+│   └── DESIGN_ORIGINS.md      ← founding motivations and design rationale
+├── project-context/
+│   ├── GOALS.md
+│   ├── PROBLEMS.md
+│   ├── DECISIONS.md
+│   ├── REFERENCES.md          ← local reference document manifest
+│   └── FIELD_NOTES.md         ← development feedback for vault agents
+├── research-queue/
+│   ├── QUEUE.md
+│   └── briefs/
+│       └── YYYY-MM-DD_<slug>.md
+├── inbox/
+│   └── YYYY-MM-DD_<slug>/
+│       ├── report.md
+│       ├── provenance.md
+│       └── pre-brief.md
+├── distilled/
+│   └── YYYY-MM-DD_<slug>.md
+├── integrated/
+│   ├── <concern-slug>.md
+│   └── CONTRADICTIONS.md
+├── decision-briefs/
+│   └── <decision-slug>.md
+├── ideas/
+│   └── YYYY-MM-DD_<slug>.md
+├── archive/
+│   └── ...
+└── logs/
+    ├── activity.log
+    ├── session-YYYY-MM-DD-HHMMSS.md
+    └── constitutional-review-YYYY-MM-DD.md
+```
+
+### Naming conventions
+- Dates: `YYYY-MM-DD` prefix for chronological sorting.
+- Slugs: lowercase, hyphen-separated, ≤40 chars. Descriptive of content.
+- All files are UTF-8 markdown unless otherwise noted.
+
+---
+
+## 2. Agent Roles
+
+Each role is a **hat** — the same underlying agent (e.g., Claude Code) assumes a role by reading the relevant section below. Multiple roles can run in parallel where noted.
+
+### 2.1 Researcher
+**Trigger**: Items exist in `research-queue/QUEUE.md` with status `pending`.
+**Inputs**: A queue entry + the corresponding pre-brief.
+**Process**:
+1. Read the pre-brief to understand scope and relevance.
+2. Check `project-context/REFERENCES.md` for local reference documents relevant to the topic. Search within them before web searches — local references are authoritative primary sources.
+3. Conduct web searches. Aim for 3–8 high-quality sources per topic.
+4. Write a structured report to `inbox/YYYY-MM-DD_<slug>/report.md`.
+5. Write `provenance.md` (original prompt, search queries used, source URLs, timestamps).
+6. Copy the pre-brief into the report directory.
+7. Update `QUEUE.md`: set status to `researched`. Update `MANIFEST.md`.
+8. Append to `logs/activity.log`. If this topic is tagged `meta`, include the tag `[meta]` in the log entry (e.g., `[meta] Researched: <topic>`). This tag is used to compute meta-research compliance.
+9. Update the relevant Cycle Counters in MANIFEST.md. Increment `Total research sessions completed`, `Sessions since last meta-review`, and `Sessions since last constitutional review`. Each researcher execution counts as one research session — if 3 researchers run in parallel, the total increments by 3. In orchestrated parallel mode, the orchestrator handles counter increments; the researcher skips counter updates and reports changes in `logs/activity.log` instead.
+
+**Report structure**:
+```markdown
+# <Topic Title>
+## Summary (3-5 sentences)
+## Key Findings (bulleted, each tagged with confidence: high/medium/low)
+## Sources (numbered, with URL and retrieval date)
+## Open Questions (what this report does NOT answer)
+## Relevance to Project (how this connects to GOALS.md / PROBLEMS.md)
+```
+
+**Parallelism**: ✅ Fully parallel. Multiple researchers can run simultaneously on different queue items. Use unique directory names (timestamp + slug) to avoid collisions.
+
+### 2.2 Critic
+**Trigger**: Reports exist in `inbox/` that have not yet been distilled (check `MANIFEST.md`).
+**Inputs**: One raw report + `project-context/GOALS.md` + `project-context/PROBLEMS.md`. When a report makes claims about the project's own code, hardware, or configuration, the project source code is a valid and preferred source of ground truth. Read the relevant source files to verify — do not take the report's word for implementation details.
+**Process**:
+1. Evaluate the report against its own pre-brief: did it answer the stated question?
+2. Assess relevance to current project goals. Score: `critical / relevant / tangential / off-topic`.
+3. **Impact test**: Answer the question: "If this finding were removed from the vault entirely, what decision or action would be affected?" Document the answer. If the answer is "none," "unclear," or only vaguely connected to a goal, flag the report for deprioritization regardless of its quality score. Record the flag in the distilled finding under a `## Impact` section.
+4. Assess quality: are sources credible? Are claims supported? Any logical gaps? Where claims reference project internals (packet formats, pin assignments, control loop behavior), verify against source code.
+5. Extract the 3–5 most important claims. Tag each with confidence level.
+6. Flag any claims that contradict existing content in `integrated/` or `distilled/`.
+7. Write a distilled finding to `distilled/YYYY-MM-DD_<slug>.md`.
+8. If relevance is `off-topic`, note this prominently and recommend archival.
+9. Update `MANIFEST.md`. Append to `logs/activity.log`.
+10. Update the relevant Cycle Counters in MANIFEST.md. Increment `Reports distilled since last synthesis`.
+
+**Distilled finding structure**:
+```markdown
+# <Topic Title> — Distilled
+## Relevance: <critical|relevant|tangential|off-topic>
+## Key Claims
+- Claim 1 (confidence: high) — [source]
+- Claim 2 (confidence: medium) — [source]
+## Contradictions (if any)
+- Contradicts: <reference to existing integrated knowledge>
+- Assessment: <which claim has stronger evidence and why>
+## Impact
+- Decision/action affected: <specific decision or "none/unclear">
+- Deprioritization flag: <yes/no>
+## Recommendation
+<What to do with this: integrate, investigate further, archive, discard>
+```
+
+**Parallelism**: ✅ Parallel per-report. Each critic instance works on one report independently.
+
+### 2.3 Synthesizer
+**Trigger**: ≥3 distilled findings exist that have not been integrated (check `Reports distilled since last synthesis` in MANIFEST.md Cycle Counters), OR a scheduled synthesis cycle is due.
+**Inputs**: All un-integrated distilled findings + all current `integrated/*.md` files + `project-context/`.
+**Process**:
+1. Read all pending distilled findings.
+2. For each, determine which project concern it belongs to (reference `GOALS.md`, `PROBLEMS.md`).
+3. Merge findings into the appropriate `integrated/<concern>.md` file:
+   - Add new knowledge with source attribution and date.
+   - Remove or archive superseded claims.
+   - Preserve the strongest version of each claim (prefer higher-confidence, more recent).
+4. Update `integrated/CONTRADICTIONS.md` if new conflicts are found.
+5. Mark distilled findings as integrated in `MANIFEST.md`.
+6. Move corresponding `inbox/` reports to `archive/` if all their findings are now integrated.
+7. Append to `logs/activity.log`.
+8. Update the relevant Cycle Counters in MANIFEST.md. Reset `Reports distilled since last synthesis` to 0. Increment `Findings integrated since last ideation` by the number of distilled findings processed this session (not by 1).
+
+**Integrated knowledge structure** (per concern file):
+```markdown
+# <Concern Title>
+## Current Understanding (last updated: YYYY-MM-DD)
+<Narrative summary, 1-3 paragraphs>
+## Key Claims
+- Claim (confidence, date, source chain)
+## Open Questions
+## Related Concerns
+```
+
+**Parallelism**: ⚠️ Sequential recommended. Multiple synthesizers writing to the same concern file will conflict. If parallelizing, partition by concern (each synthesizer owns different concern files).
+
+### 2.4 Contradiction Analyst
+**Trigger**: `integrated/CONTRADICTIONS.md` has unresolved entries, OR the synthesizer flagged new contradictions.
+**Inputs**: The contradicting claims + their source reports + any additional web research needed. Project source code is a valid and preferred source of ground truth when contradictions involve claims about the project's own implementation. Read the relevant source files to resolve factual disputes — code trumps reports.
+**Process**:
+1. For each unresolved contradiction, assess evidence strength on both sides.
+2. If resolvable: recommend which claim to retain, with justification. Update the integrated file.
+3. If not resolvable: document the disagreement clearly, note what evidence would resolve it, and add a targeted research topic to `research-queue/QUEUE.md`.
+4. Update `CONTRADICTIONS.md`. Append to `logs/activity.log`.
+5. Update MANIFEST.md: add to recent activity and update the queue status table if new topics were added. The contradiction analyst does not increment or reset any cycle counter.
+
+**Parallelism**: ✅ Parallel per-contradiction (as long as each instance works on different contradictions).
+
+### 2.5 Ideator
+**Trigger**: Scheduled ideation cycle, OR ≥5 new findings integrated since last ideation run (check `Findings integrated since last ideation` counter in MANIFEST.md Cycle Counters).
+**Inputs**: Recent distilled and integrated knowledge + `project-context/GOALS.md` + `project-context/PROBLEMS.md`.
+**Process**:
+1. Scan recent findings for unexpected connections — especially cross-domain links.
+2. For each idea, write a short proposal to `ideas/YYYY-MM-DD_<slug>.md`:
+   - The connection observed.
+   - Why it might matter for the project.
+   - A concrete next step or experiment to test it.
+   - What evidence would confirm or refute it.
+3. Review existing ideas: any that are now supported or refuted by new evidence should be updated.
+4. Append to `logs/activity.log`.
+5. Update the relevant Cycle Counters in MANIFEST.md. Reset `Findings integrated since last ideation` to 0.
+
+**Idea structure**:
+```markdown
+# Idea: <Title>
+## Connection
+<What findings or knowledge items prompted this>
+## Hypothesis
+<The speculative claim>
+## Relevance to Project
+<Which goal or problem this serves>
+## Proposed Test
+<How to validate — could be more research, a prototype, an experiment>
+## Falsification Criteria
+<What evidence would kill this idea>
+```
+
+**Parallelism**: ✅ Fully parallel. Multiple ideators can run; duplicates are cheap to detect and merge.
+
+### 2.6 Meta-Reviewer (Vault Health)
+**Trigger**: Scheduled review cycle (check `Sessions since last meta-review` in MANIFEST.md Cycle Counters; trigger when ≥5).
+**Inputs**: The entire vault state — `MANIFEST.md`, all integrated knowledge, the queue, activity logs.
+**Process**:
+1. **Scope drift check**: Is recent research aligned with `GOALS.md`? Quantify: what fraction of last N reports scored `critical` or `relevant` vs. `tangential` or `off-topic`?
+2. **Diminishing returns check**: Are recent reports on topic X producing new claims, or just confirming what's already integrated? If converged, deprioritize in queue.
+3. **Coverage gap check**: Are any items in `PROBLEMS.md` under-researched relative to their priority?
+4. **Vault hygiene**: Flag stale content (>30 days un-referenced), oversized files, orphaned reports. Archive inbox reports older than 30 days that were never distilled, with a note "Archived by meta-reviewer: undistilled after 30 days."
+5. **Decision brief drafting**: If any topic has enough integrated knowledge to support a decision, draft a brief in `decision-briefs/` presenting the options, tradeoffs, and the meta-reviewer's recommendation. This is a proposal for the human, not a commitment.
+6. **Human advisory**: Write a summary for the human supervisor:
+   - What's going well.
+   - What's drifting or stale.
+   - Recommended priority changes for `QUEUE.md`.
+   - Any decisions that are now well-enough informed to make.
+7. Place the advisory in `logs/session-YYYY-MM-DD-HHMMSS.md` and update `MANIFEST.md`.
+8. Update the relevant Cycle Counters in MANIFEST.md. Reset `Sessions since last meta-review` to 0.
+
+**Parallelism**: 🚫 Sequential. Only one meta-reviewer at a time (reads and potentially modifies global state).
+
+### 2.7 Constitutional Reviewer
+
+This role is defined and governed by `VAULT_CONSTITUTION.md`, Article III §3.2. It is summarized here for completeness:
+
+**Trigger**: Every 10–15 research sessions (check `Sessions since last constitutional review` in MANIFEST.md Cycle Counters; trigger when ≥10), or on human request, or when the Meta-Reviewer flags systemic issues that operational roles cannot resolve.
+
+**Purpose**: Evaluate whether the protocol itself is sound, coherent, and aligned with the constitution and the human's original design intent. Reads `governance/DESIGN_ORIGINS.md` as primary evidence of intent.
+
+**Outputs**: Constitutional review report in `logs/constitutional-review-YYYY-MM-DD.md`.
+
+**Post-process**: Update the relevant Cycle Counters in MANIFEST.md. Reset `Sessions since last constitutional review` to 0.
+
+**Parallelism**: 🚫 Sequential. Only one constitutional reviewer at a time. Must not run concurrently with the Meta-Reviewer.
+
+For the full process specification, see the constitution.
+
+---
+
+## 3. Workflows
+
+### 3.1 Research Cycle (the default loop)
+
+```
+Human sets GOALS.md, PROBLEMS.md, and seeds QUEUE.md
+              │
+              ▼
+┌──────────────────────────┐
+│  Pre-brief (per topic)   │  Agent writes justification for each queue item
+└────────────┬─────────────┘
+             │
+             ▼
+┌──────────────────────────┐
+│  Research (parallel)     │  N agents execute queue items simultaneously
+└────────────┬─────────────┘
+             │
+             ▼
+┌──────────────────────────┐
+│  Critique (parallel)     │  Per-report quality + relevance assessment
+└────────────┬─────────────┘
+             │
+             ▼
+┌──────────────────────────┐
+│  Synthesis (sequential)  │  Merge findings into integrated knowledge
+└────────────┬─────────────┘
+             │
+             ▼
+┌────────────┴─────────────┐
+│  Ideation    │ Contradict.│  Can run in parallel with each other
+│  (parallel)  │ Analysis   │
+└────────────┬─────────────┘
+             │
+             ▼
+┌──────────────────────────┐
+│  Meta-Review (periodic)  │  Vault health, scope drift, human advisory
+└──────────────────────────┘
+```
+
+### 3.2 Quick-Burn Session (maximize token usage in limited time)
+
+When the human has, say, 70% of a rate window remaining and is stepping away:
+
+1. **Human**: Review `QUEUE.md`, adjust priorities if desired. Or just say "run the vault."
+2. **Launch N parallel researchers** on the top N queue items.
+3. **As reports land in inbox**, launch parallel critics immediately (don't wait for all research to finish).
+4. **Once ≥3 distilled findings exist**, launch one synthesizer.
+5. **Concurrently with synthesis**, launch an ideator on the already-distilled findings.
+6. **If tokens remain**, loop: check queue for more items, or have the meta-reviewer run and suggest new research topics to add to the queue, then research those.
+
+**Approximate token budget** (rough, will vary):
+| Role | Tokens per execution | Parallelism |
+|------|---------------------|-------------|
+| Pre-brief | ~500–1K | Parallel |
+| Researcher | ~3K–8K (depends on search depth) | Parallel |
+| Critic | ~1K–3K | Parallel |
+| Synthesizer | ~2K–5K | Sequential |
+| Ideator | ~1K–3K | Parallel |
+| Meta-Reviewer | ~2K–5K | Sequential |
+
+### 3.3 Human Re-entry
+
+When the human returns:
+
+1. Read the latest `logs/session-*.md` for the meta-reviewer's advisory.
+2. Scan `decision-briefs/` for any decisions that are now well-informed.
+3. Review `ideas/` for anything exciting.
+4. Adjust `GOALS.md`, `PROBLEMS.md`, `QUEUE.md` as needed.
+5. Optionally promote an idea to a queue item, or a decision brief to an actual project decision in `DECISIONS.md`.
+6. If you did implementation work since your last vault interaction, append a field note to `project-context/FIELD_NOTES.md` describing what you tried and what happened. Or use `/vault-fieldnote`.
+
+---
+
+## 4. MANIFEST.md Specification
+
+The manifest is the coordination hub. All agents read and update it.
+
+```markdown
+# Vault Manifest
+Last updated: YYYY-MM-DD HH:MM UTC
+
+## Queue Status
+| Topic | Status | Priority | Pre-brief | Tag |
+|-------|--------|----------|-----------|-----|
+| topic-slug | pending/in-progress/researched/distilled/integrated/archived | 1-5 | yes/no | meta or — |
+
+## Recent Activity (last 10 entries)
+- YYYY-MM-DD HH:MM — Role: <role> — Action: <what was done>
+
+## Cycle Counters
+- Total research sessions completed: <N>
+- Reports distilled since last synthesis: <N>
+- Findings integrated since last ideation: <N>
+- Sessions since last meta-review: <N>
+- Sessions since last constitutional review: <N>
+- Meta-research compliance (last 10 sessions): <computed>
+  (DO NOT maintain this as a running counter. Compute it fresh
+  each time by counting meta-tagged research entries in the last
+  10 sessions from activity.log. The orchestrator and meta-reviewer
+  compute this; other roles do not need to update it.)
+
+## Vault Health
+- Total reports: N (inbox: X, distilled: Y, integrated: Z, archived: W)
+- Unresolved contradictions: N
+- Last meta-review: YYYY-MM-DD
+- Coverage gaps: <list or "none identified">
+```
+
+**Concurrency note**: When the orchestrator dispatches multiple parallel agents, the orchestrator owns all MANIFEST.md updates. Individual agents skip their manifest update step and instead report their changes in `logs/activity.log`, which the orchestrator reads when consolidating the manifest at session end. When an agent runs alone (not orchestrated in parallel), it updates the manifest itself per the standard role process.
+
+In the rare case of a write conflict, the next agent to run can reconcile. Lost updates are recoverable from `logs/activity.log`.
+
+---
+
+## 5. Quality Controls
+
+### 5.1 Relevance gate
+No research begins without a pre-brief that ties the topic to a specific entry in `GOALS.md` or `PROBLEMS.md`. If the connection is weak, the agent should note this and flag it for human approval rather than proceeding.
+
+### 5.2 Diminishing returns detection
+If the last 3 reports on a topic produced no new claims beyond what's already integrated, the topic is marked `converged` in the queue and deprioritized. The meta-reviewer enforces this.
+
+### 5.3 Contradiction register
+Contradictions are never silently resolved. They are always documented in `CONTRADICTIONS.md` with the evidence assessment. The human has final say on which claim wins if evidence is balanced.
+
+### 5.4 Staleness policy
+- Integrated knowledge older than 90 days without corroboration or reference: flagged for re-verification.
+- Inbox reports older than 30 days that were never distilled: the meta-reviewer archives them with a note "Archived by meta-reviewer: undistilled after 30 days."
+- Decision briefs acted upon: moved to `project-context/DECISIONS.md` with outcome.
+
+### 5.5 Scope creep detection
+The meta-reviewer computes a rolling relevance ratio: (critical + relevant reports) / (total reports) over the last N sessions. If this drops below 0.6, it triggers a human advisory recommending queue pruning.
+
+---
+
+## 6. Bootstrapping
+
+To initialize the vault for a new project:
+
+1. Create the directory structure above.
+2. Write `GOALS.md`: 3–7 ranked project goals.
+3. Write `PROBLEMS.md`: known open questions or blockers.
+4. Seed `QUEUE.md` with 5–15 initial research topics, each with a priority 1–5.
+5. Write pre-briefs for the top 5 topics.
+6. Run the first research cycle.
+
+The vault is self-sustaining after bootstrapping: the meta-reviewer and ideator will suggest new research topics, the synthesizer will maintain integrated knowledge, and the critic will prune irrelevant work.
+
+---
+
+## 7. Agent Instructions (copy-paste for agent prompt)
+
+When instructing a coding agent to work on the vault, use a prompt like:
+
+```
+You are operating the Research Vault for this project.
+
+Read these documents in order:
+1. `research-vault/VAULT_CONSTITUTION.md` (governing principles)
+2. `research-vault/VAULT_PROTOCOL.md` (operational procedures)
+3. `research-vault/MANIFEST.md` (current state)
+
+The constitution governs the protocol. If you encounter a conflict
+between them, follow the constitution and document the conflict in
+the activity log.
+
+Your role this session: <ROLE NAME>
+
+Follow the process for your role exactly. Update MANIFEST.md and
+activity.log when done. Do not modify any project source code.
+Only write to the research-vault/ directory.
+
+If you encounter ambiguity about scope or relevance, err on the
+side of documenting your uncertainty rather than guessing.
+```
+
+For a quick-burn parallel session:
+
+```
+You are operating the Research Vault. Read the constitution first,
+then the protocol, then the manifest. Execute the Quick-Burn
+workflow (protocol §3.2). You may assume <N> parallel agents are
+available. Prioritize breadth of research first, then shift to
+critique and synthesis as reports accumulate. Stop when you have
+exhausted the queue or run low on capacity.
+
+Reminder: at least 10% of research cycles must be allocated to
+meta-research topics (tagged `meta` in the queue). See
+constitution Article V.
+```
+
+---
+
+## 8. Design Principles
+
+1. **Compression over accumulation.** The vault's value is in T2–T3 outputs, not raw reports. Prune aggressively.
+2. **Provenance is mandatory.** Every claim traces back to a source, a date, and a confidence level. No orphan assertions.
+3. **Contradiction is signal, not failure.** Disagreements between reports mean the topic is under-determined. Investigate, don't suppress.
+4. **Human-in-the-loop for decisions, not for research.** Agents research and synthesize autonomously. Humans set goals, resolve ties, and act on decision briefs.
+5. **Parallel by default, sequential when necessary.** Only synthesis and meta-review require serialization. Everything else can run concurrently.
+6. **Fail toward documentation.** When uncertain, write down the uncertainty rather than making a silent judgment call. The next agent (or the human) can resolve it.

package/templates/research-vault/governance/DESIGN_ORIGINS.md

@@ -0,0 +1,214 @@
+# Vault Design Origins
+
+> This document records the motivations, design decisions, and
+> governing philosophy behind the Research Vault system. It was
+> assembled from the founding conversation between the human
+> supervisor and Claude (Opus 4.6), March 2026. The constitutional
+> reviewer should treat this as primary evidence of human intent
+> when evaluating whether the vault's operation has drifted from
+> its purpose.
+
+---
+
+## 1. The Motivating Problem
+
+The human supervisor maintains subscriptions to coding agents
+(primarily Claude Code on the Anthropic Max plan) that provide
+substantial token budgets on rolling windows (e.g., 5-hour usage
+periods). In practice, these tokens frequently go unused because:
+
+- The supervisor works a full-time job five days per week and is
+  often too fatigued in the evenings to direct agent work.
+- Weekends are consumed by life maintenance, leaving little time
+  for project work.
+- Ideas are abundant when energy is high but there is no
+  mechanism to capitalize on available capacity during low-energy
+  or away-from-desk periods.
+- The result is a persistent feeling of wasted subscription value
+  — the capacity exists but decays unused.
+
+**The vault exists to solve this specific problem**: converting
+idle agent capacity into durable intellectual capital that
+compounds over time, so that when the human *does* engage, they
+start from a higher baseline rather than from scratch.
+
+---
+
+## 2. The Sleep Consolidation Metaphor
+
+The human explicitly compared the vault to the brain's offline
+consolidation during sleep: the automatic process of correlating
+experiences, pruning noise, strengthening important connections,
+and surfacing insights — all without conscious supervision.
+
+This metaphor is not decorative. It implies specific design
+requirements:
+
+- **Autonomous operation**: The vault must be able to run
+  productively without the human present.
+- **Compression, not accumulation**: Just as sleep consolidation
+  reduces the day's experiences into durable memory, the vault
+  must reduce raw research into integrated knowledge. Volume
+  growth without compression is a failure state.
+- **Correlation as a first-class activity**: Agents should
+  actively look for connections between findings, not just file
+  them independently. The Ideator role exists for this reason.
+- **Low re-entry cost**: When the human returns, they should be
+  able to understand what happened and what matters quickly (via
+  session logs and decision briefs), analogous to waking up with
+  consolidated understanding rather than a pile of raw notes.
+
+---
+
+## 3. The Trust Problem
+
+The deeper motivation behind the governance layer (the
+constitution, constitutional reviewer, etc.) is **trust**. The
+human needs to be able to trust the vault's outputs enough to act
+on them without re-verifying everything from scratch. If every
+re-engagement requires the human to audit all work done in their
+absence, the vault has failed — it has merely displaced effort
+rather than reducing it.
+
+Trust is built by:
+
+- Transparent provenance (every claim traceable to a source).
+- Adversarial self-correction (agents that critique each other).
+- Process governance (the constitutional reviewer checking whether
+  the rules themselves are sound).
+- Honest self-assessment (the vault recommending its own
+  downsizing if it's not producing value — failure mode F10).
+
+---
+
+## 4. Key Design Decisions and Their Rationale
+
+### 4.1 Tiered compression (T0 → T3)
+
+Raw reports (T0) are working memory. Distilled findings (T1) are
+reviewed extracts. Integrated knowledge (T2) is the living
+understanding organized by project concern. Decision briefs (T3)
+are the human-facing actionable outputs.
+
+**Rationale**: Without explicit tiers, research accumulates as a
+write-only knowledge base. The human identified "too much text"
+and "noise for the repo" as primary concerns early in the design
+conversation. The tiers enforce that every piece of research must
+be compressed before it earns a permanent place.
+
+### 4.2 Council of agents (single agent, multiple roles)
+
+Rather than a monolithic agent process, the system uses distinct
+roles (Researcher, Critic, Synthesizer, etc.) that the same
+underlying agent assumes at different times.
+
+**Rationale**: The human proposed a "council of agents" where
+"one agent wearing different hats" would critique research in
+different ways. This maps to the multi-agent debate pattern
+(Du et al., 2023) which empirically improves factual accuracy.
+The role separation ensures that the agent that *produced*
+research is not the same cognitive frame that *evaluates* it.
+
+### 4.3 Constitution separate from protocol
+
+The constitution is a short, principled, stable document. The
+protocol is a longer operational manual. The constitution governs
+the protocol, not the other way around.
+
+**Rationale**: The human raised the concern that self-correcting
+agents following a fixed protocol could still drift if the
+protocol itself becomes misaligned. The constitution provides a
+stable reference point against which the protocol is periodically
+evaluated. The separation also creates appropriate friction:
+changing a workflow step should be easy; changing a governing
+principle should be deliberate.
+
+### 4.4 Human-as-ratifier (not human-as-operator)
+
+Agents propose amendments and surface decisions. The human
+approves, rejects, or modifies. The human is compared to a
+president who signs or vetoes bills.
+
+**Rationale**: The human explicitly stated that agents should not
+autonomously change the governing documents. This is the one
+hard firewall against drift. The human does not need to *direct*
+every action, but they must *approve* every structural change.
+
+### 4.5 Parallelization by design
+
+The system is designed so that most roles can run concurrently.
+Research is embarrassingly parallel. Critique is parallel per-
+report. Synthesis is the sequential bottleneck.
+
+**Rationale**: The motivating problem is token utilization. If
+the human has 70% of a rate window remaining, they want to burn
+through it productively. Sequential processing wastes capacity.
+The lock-free coordination model (unique filenames, no shared
+mutable state except the manifest) enables parallel execution
+without complex synchronization.
+
+### 4.6 Protected meta-research (10% floor)
+
+At least 10% of research cycles are reserved for meta-research
+about the vault methodology itself. This allocation cannot be
+deprioritized by operational roles.
+
+**Rationale**: The human identified this as a potential solution
+to the governance problem: "maybe the solution is to just make
+it another research topic." The protected floor ensures it
+actually happens rather than being perpetually deferred in favor
+of project-specific research.
+
+---
+
+## 5. Failure Modes the Human Is Most Concerned About
+
+In order of emphasis during the design conversation:
+
+1. **Noise accumulation** — too much text, reports that disagree
+   or confuse rather than clarify.
+2. **Coherent drift** — everything working correctly according
+   to rules that no longer serve the project.
+3. **Process overhead exceeding value** — the vault becoming
+   bureaucratic busywork.
+4. **Agents unable to follow the protocol correctly** — the
+   documents being too ambiguous or too complex for coding agents
+   to interpret reliably.
+5. **Self-preservation bias** — the vault continuing to justify
+   its own existence when tokens would be better spent on direct
+   implementation.
+
+---
+
+## 6. Long-Term Vision
+
+The human intends to deploy a vault for every active project,
+including work projects, if this first instance proves valuable.
+This implies:
+
+- The system must be lightweight enough to justify per-project
+  overhead.
+- The constitution and protocol should be project-agnostic (they
+  are — project specifics live in `project-context/`).
+- Lessons learned from this first vault should be captured and
+  transferable.
+- Success criteria: the human feels that re-engagement after
+  absence is *easier* with the vault than without it, and that
+  decisions are better-informed.
+
+---
+
+## 7. What Would Change the Human's Assessment
+
+The human would likely reconsider the vault approach if:
+
+- The overhead of maintaining vault structure exceeds ~40% of
+  total token usage without proportional improvement in output
+  quality.
+- Integrated knowledge is frequently wrong or misleading,
+  requiring the human to re-verify most claims anyway.
+- The system produces research that feels productive but doesn't
+  translate into project decisions or code changes.
+- Re-entry cost remains high despite the vault's operation (the
+  session logs and decision briefs aren't actually reducing the
+  time to get oriented).