Initialize DOX hierarchy for Tree Ring Memory

[TerminallyLazy]

Initialize the repository with the agent0ai/DOX instruction hierarchy: a tracked root contract, indexed crate and activation boundaries, plus packaging, scripts, docs, fixtures and marketing guidance. Preserve the existing Tree Ring reference block and keep project instructions separate from the generated .tree-ring/AGENTS.md memory guidance.

Validation: all 12 documents (including the existing downstream template) are reachable through 11 valid index links; child section order and root-reference preservation pass; package/ZIP validation and diff checks pass. Existing runtime tests remain covered by the activation-fix PR. The downstream template was intentionally unchanged because its consumer contract did not change.

High-level PR Summary

This PR establishes a comprehensive DOX (Documentation and Ownership eXplicit) instruction hierarchy across the Tree Ring Memory repository by adding 11 new AGENTS.md files. The hierarchy defines clear ownership boundaries, contracts, and work guidance for each major component: the Rust workspace crates (core, sqlite, cli), plugins, scripts, documentation, fixtures, and marketing materials. The root file preserves the existing Tree Ring reference block and establishes the framework's relationship with the runtime memory guidance in .tree-ring/AGENTS.md. All documents follow a consistent structure with Purpose, Ownership, Local Contracts, Work Guidance, Verification sections, and Child DOX Index links that form a navigable tree of 12 total documents.

⏱️ Estimated Review Time: 15-30 minutes

💡 Review Order Suggestion

Order	File Path
1	AGENTS.md
2	crates/AGENTS.md
3	crates/tree-ring-memory-core/AGENTS.md
4	crates/tree-ring-memory-sqlite/AGENTS.md
5	crates/tree-ring-memory-cli/AGENTS.md
6	crates/tree-ring-memory-cli/src/activation/AGENTS.md
7	plugins/AGENTS.md
8	scripts/AGENTS.md
9	docs/AGENTS.md
10	fixtures/AGENTS.md
11	marketing/AGENTS.md

[coderabbitai]

Warning

Review limit reached

Next included review available in 49 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 78aec41a-beab-437e-bad5-c707fdf4bfdb

📥 Commits

Reviewing files that changed from the base of the PR and between db2034a and 8b5425c.

📒 Files selected for processing (12)

• AGENTS.md
• crates/AGENTS.md
• crates/tree-ring-memory-cli/AGENTS.md
• crates/tree-ring-memory-cli/src/activation/AGENTS.md
• crates/tree-ring-memory-core/AGENTS.md
• crates/tree-ring-memory-sqlite/AGENTS.md
• docs/AGENTS.md
• docs/DOX-LICENSE.txt
• fixtures/AGENTS.md
• marketing/AGENTS.md
• plugins/AGENTS.md
• scripts/AGENTS.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Initialize DOX instruction hierarchy for Tree Ring Memory

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Establishes a tracked DOX root contract while preserving Tree Ring memory guidance.
• Indexes crate, activation, packaging, tooling, documentation, fixture, and marketing ownership
 boundaries.
• Leaves runtime code and the downstream template unchanged because their contracts remain stable.

Diagram

graph TD
  ROOT["Root Contract"] -->|indexes| CRATES["Crate Index"] -->|indexes| CLI["CLI Contract"] -->|indexes| ACT["Activation Contract"]
  CRATES -->|indexes| CORE["Core Contract"]
  CRATES -->|indexes| SQLITE["SQLite Contract"]
  ROOT -->|indexes| SUPPORT["Support Boundaries"]
  ROOT -->|references| TEMPLATE["Downstream Template"]

Loading

High-Level Assessment

The hierarchical approach is appropriate because repository-wide rules remain centralized while specialized contracts live at durable ownership boundaries. A single root-only contract would obscure crate and activation requirements, while replacing generated .tree-ring guidance would incorrectly merge project authority with runtime memory instructions.

Files changed (11) +328 / -0

Documentation (11) +328 / -0

AGENTS.mdAdd the repository-wide DOX root contract +76/-0

Add the repository-wide DOX root contract

• Defines repository authority, hierarchy maintenance, verification expectations, and instruction-memory separation. It preserves the marked Tree Ring reference block and indexes all child contracts, including the unchanged downstream template.

AGENTS.md

AGENTS.mdDefine shared Rust workspace instructions +27/-0

Define shared Rust workspace instructions

• Documents the core, SQLite, and CLI responsibility split, shared verification commands, and child contract links. It discourages duplicate action implementations across crates.

crates/AGENTS.md

AGENTS.mdDefine CLI orchestration contracts +25/-0

Define CLI orchestration contracts

• Establishes ownership and verification guidance for commands, onboarding, updates, evidence runners, and the TUI. It delegates lifecycle bridge behavior to the activation child contract.

crates/tree-ring-memory-cli/AGENTS.md

AGENTS.mdDefine lifecycle activation and receipt contracts +25/-0

Define lifecycle activation and receipt contracts

• Documents host event mapping, safe path handling, create-only bridge publication, and receipt-backed activation proof. It also prohibits transcript scraping and fabricated activation evidence.

crates/tree-ring-memory-cli/src/activation/AGENTS.md

AGENTS.mdDefine memory-domain contracts +25/-0

Define memory-domain contracts

• Documents ownership of models, validation, scoring, sensitivity, adapters, and evaluations. It requires schema compatibility, provenance preservation, and coordination with persistence or CLI consumers.

crates/tree-ring-memory-core/AGENTS.md

AGENTS.mdDefine persistence and recall contracts +25/-0

Define persistence and recall contracts

• Captures durability, idempotency, writer fencing, privacy filtering, and cross-session recall requirements. It identifies concurrency, historical-session, and performance verification expectations.

crates/tree-ring-memory-sqlite/AGENTS.md

AGENTS.mdDefine public documentation authority +25/-0

Define public documentation authority

• Distinguishes current protocol documentation from historical plans and prevents unsupported activation or release claims. It adds link, CLI reference, and packaging-related verification guidance.

docs/AGENTS.md

AGENTS.mdDefine synthetic fixture contracts +25/-0

Define synthetic fixture contracts

• Establishes fixture ownership and prohibits credentials, private stores, and real transcripts. Fixture changes must represent intentional contract changes and pass their owning tests.

fixtures/AGENTS.md

AGENTS.mdDefine marketing asset guidance +25/-0

Define marketing asset guidance

• Documents campaign and visual source ownership, attribution expectations, and privacy constraints. Public claims must reflect verified runtime and release capabilities.

marketing/AGENTS.md

AGENTS.mdDefine native plugin packaging contracts +25/-0

Define native plugin packaging contracts

• Documents lifecycle hook, archive permission, marketplace synchronization, and project-hook precedence requirements. It identifies package validation and unpacked hook probes as verification steps.

plugins/AGENTS.md

AGENTS.mdDefine validation and release tooling contracts +25/-0

Define validation and release tooling contracts

• Documents release version alignment, archive contents, checksums, platform constraints, and exact-head evidence requirements. It supplies package validation and shell syntax checks for tooling changes.

scripts/AGENTS.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Clean checkouts lack required guidance 🐞 Bug ≡ Correctness

Description

AGENTS.md unconditionally requires reading three .tree-ring files before substantive work, but
that ignored directory is absent from a clean checkout. Those files are created only by `tree-ring
init`, so every uninitialized clone starts with a mandatory prerequisite that cannot be completed.

Code

AGENTS.md[4]

+Read `.tree-ring/AGENTS.md`, `.tree-ring/SKILL.md`, and `.tree-ring/CLI.md` before substantive work. The project lifecycle hook runs receipt-backed recall at session boundaries and one strict automatic capture checkpoint before a session or subagent turn stops. Do not claim memory is active without a valid project-local recall receipt. Capture zero to three concise durable candidates; never store a transcript or invent memory.

Evidence

The added root instruction names all three files as mandatory, while the repository ignores the
entire .tree-ring directory and documents that initialization creates the files. Therefore, they
are unavailable in the normal pre-initialization checkout where this tracked root contract is first
read.

AGENTS.md[1-5]
.gitignore[7-11]
README.md[366-372]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The root contract requires generated `.tree-ring` guidance even when a clean checkout has not been initialized and those files do not exist.

## Fix Focus Areas
- AGENTS.md[4-4]

## Recommended Fix
Add an explicit clean-checkout fallback adjacent to the marker-owned block: read the three files only when they exist, and otherwise treat Tree Ring memory as inactive while continuing to follow the repository contract. Preserve the managed block markers and avoid initializing or modifying project-local state without authorization.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Cross-repo context — repo relationships

Review mode: ⚖️ Balanced: This adds repository-wide instruction and contract files across multiple ownership boundaries, with packaging, activation, security/privacy, and link/index correctness implications that warrant a complete review.

Tip of the day

💡 Did you know, you can reply 'qodo' on any finding to push back, ask questions, or dig deeper

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

1. Clean checkouts lack required guidance 🐞 Bug ≡ Correctness

AGENTS.md unconditionally requires reading three .tree-ring files before substantive work, but
that ignored directory is absent from a clean checkout. Those files are created only by `tree-ring
init`, so every uninitialized clone starts with a mandatory prerequisite that cannot be completed.

Agent Prompt

## Issue description
The root contract requires generated `.tree-ring` guidance even when a clean checkout has not been initialized and those files do not exist.

## Fix Focus Areas
- AGENTS.md[4-4]

## Recommended Fix
Add an explicit clean-checkout fallback adjacent to the marker-owned block: read the three files only when they exist, and otherwise treat Tree Ring memory as inactive while continuing to follow the repository contract. Preserve the managed block markers and avoid initializing or modifying project-local state without authorization.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools