docs: recenter Truth docs and planning lifecycle#26
Merged
flyingrobots merged 9 commits intomainfrom Mar 30, 2026
Merged
Conversation
|
Important Review skippedThis PR was authored by the user configured for CodeRabbit reviews. CodeRabbit does not review PRs authored by this user. It's recommended to use a dedicated user account to post CodeRabbit review feedback. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR is documentation-centric: it rewrites ARCHITECTURE.md into a system/layer model, adds a canonical threat model, formalizes doc/workflow lifecycles with archive dirs, updates API/SECURITY/CHANGELOG, and marks many design/backlog docs as Landed with retrospectives. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (3)
docs/legends/RL-relay.md (1)
83-86: Consider normalizing empty-backlog phrasing for consistency.Line 85 (
- none currently) works, but title-case/sentence-style wording would read cleaner in this docs set (e.g.,- None currently.).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/legends/RL-relay.md` around lines 83 - 86, Change the backlog item string "- none currently" to use sentence-style capitalization and punctuation for consistency with the docs (replace "- none currently" with "- None currently.").ARCHITECTURE.md (2)
271-284: Add cross-reference to the new threat model document.The "Reading This With Other Docs" section provides helpful navigation to adjacent documentation. However, it's missing a reference to
docs/THREAT_MODEL.md, which TR-002 establishes as the canonical threat model document. Given that the threat model defines assets, attackers, and trust boundaries—all architectural concerns—it would be valuable to include it here.📝 Suggested addition
- [SECURITY.md](./SECURITY.md) - crypto and security guidance +- [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md) + - threat model, assets, and trust boundaries - [WORKFLOW.md](./WORKFLOW.md) - current planning and delivery model🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@ARCHITECTURE.md` around lines 271 - 284, Add a new bullet under the "Reading This With Other Docs" section pointing to docs/THREAT_MODEL.md so readers can find the canonical threat model (TR-002); follow the existing bullet format (a link plus a short descriptor) and place it with the other adjacent-doc entries to ensure the threat model is discoverable from the architecture overview.
44-67: Clarify which domain services are publicly exported.The document lists CasService, KeyResolver, VaultService, rotateVaultPassphrase, and CasError as "Current key domain pieces." However, only CasService and VaultService are exported from
index.js. KeyResolver, rotateVaultPassphrase, and CasError are internal-only services.While the document doesn't explicitly claim all listed services are public exports, the structure (Facade → Domain → Ports → Infrastructure) could lead readers to assume everything listed is part of the public API. Consider adding a brief note distinguishing exported services from internal domain services, or restructuring to make the public API boundary more explicit.
📝 Suggested clarification
### Domain The domain lives under `src/domain/`. -Current key domain pieces: +Current key domain pieces (exported services in **bold**): - `Manifest` and `Chunk` - value objects that describe stored content and chunk metadata -- `CasService` +- **`CasService`** - the main content orchestration service - handles store, restore, tree creation, manifest reads, inspection, and recipient/key operations - `KeyResolver` - resolves key sources, passphrase-derived keys, and envelope recipient DEK wrapping and unwrapping -- `VaultService` +- **`VaultService`** - manages the GC-safe vault ref and its commit-backed slug index - `rotateVaultPassphrase` - coordinates vault-wide passphrase rotation across existing entries - `CasError` - the canonical domain error type with stable codes and metadata🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@ARCHITECTURE.md` around lines 44 - 67, Clarify public vs internal domain services in ARCHITECTURE.md by adding a short note after the "Current key domain pieces" list stating which symbols are exported from the package entry (index.js) and which are internal-only; explicitly name CasService and VaultService as exported, and KeyResolver, rotateVaultPassphrase, and CasError as internal/internal-only, and update the Facade → Domain → Ports → Infrastructure description to call out the public API boundary so readers don’t assume all listed items are exported.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@ARCHITECTURE.md`:
- Around line 271-284: Add a new bullet under the "Reading This With Other Docs"
section pointing to docs/THREAT_MODEL.md so readers can find the canonical
threat model (TR-002); follow the existing bullet format (a link plus a short
descriptor) and place it with the other adjacent-doc entries to ensure the
threat model is discoverable from the architecture overview.
- Around line 44-67: Clarify public vs internal domain services in
ARCHITECTURE.md by adding a short note after the "Current key domain pieces"
list stating which symbols are exported from the package entry (index.js) and
which are internal-only; explicitly name CasService and VaultService as
exported, and KeyResolver, rotateVaultPassphrase, and CasError as
internal/internal-only, and update the Facade → Domain → Ports → Infrastructure
description to call out the public API boundary so readers don’t assume all
listed items are exported.
In `@docs/legends/RL-relay.md`:
- Around line 83-86: Change the backlog item string "- none currently" to use
sentence-style capitalization and punctuation for consistency with the docs
(replace "- none currently" with "- None currently.").
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9f89cc9e-e4e4-4900-87fb-d0888f755404
📒 Files selected for processing (35)
ARCHITECTURE.mdCHANGELOG.mdSECURITY.mdWORKFLOW.mddocs/API.mddocs/BACKLOG/README.mddocs/BACKLOG/TR-003-benchmark-baselines.mddocs/BACKLOG/TR-005-casservice-decomposition-plan.mddocs/THREAT_MODEL.mddocs/archive/BACKLOG/README.mddocs/archive/BACKLOG/RL-001-agent-recipient-list.mddocs/archive/BACKLOG/RL-002-agent-recipient-mutations.mddocs/archive/BACKLOG/RL-003-agent-rotate.mddocs/archive/BACKLOG/RL-004-agent-vault-rotate.mddocs/archive/BACKLOG/RL-005-agent-vault-lifecycle.mddocs/archive/BACKLOG/TR-001-architecture-reality-gap.mddocs/archive/BACKLOG/TR-002-threat-model.mddocs/archive/BACKLOG/TR-004-design-doc-lifecycle.mddocs/archive/README.mddocs/archive/design/README.mddocs/design/0001-m18-relay-agent-cli.mddocs/design/0002-m18-relay-write-flows.mddocs/design/0003-m18-relay-tree-creation.mddocs/design/README.mddocs/design/RL-001-agent-recipient-list.mddocs/design/RL-002-agent-recipient-mutations.mddocs/design/RL-003-agent-rotate.mddocs/design/RL-004-agent-vault-rotate.mddocs/design/RL-005-agent-vault-lifecycle.mddocs/design/TR-001-architecture-reality-gap.mddocs/design/TR-002-threat-model.mddocs/design/TR-004-design-doc-lifecycle.mddocs/legends/README.mddocs/legends/RL-relay.mddocs/legends/TR-truth.md
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/legends/TR-truth.md (1)
89-89: Consider simplifying "under strain" to "strained".The phrase "under strain" could be shortened to "strained" for conciseness, though both are acceptable.
Optional simplification
-- evaluating service decomposition where the current boundary is under strain +- evaluating service decomposition where the current boundary is strained🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/legends/TR-truth.md` at line 89, Replace the phrase "under strain" with the more concise "strained" in the sentence "evaluating service decomposition where the current boundary is under strain" inside the TR-truth.md content; update that exact text to read "evaluating service decomposition where the current boundary is strained" to improve conciseness while preserving meaning.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/legends/TR-truth.md`:
- Line 89: Replace the phrase "under strain" with the more concise "strained" in
the sentence "evaluating service decomposition where the current boundary is
under strain" inside the TR-truth.md content; update that exact text to read
"evaluating service decomposition where the current boundary is strained" to
improve conciseness while preserving meaning.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 5de2cea9-2955-414f-ba88-f73f8430d385
📒 Files selected for processing (12)
WORKFLOW.mddocs/API.mddocs/BACKLOG/README.mddocs/archive/BACKLOG/README.mddocs/archive/BACKLOG/TR-001-architecture-reality-gap.mddocs/archive/BACKLOG/TR-002-threat-model.mddocs/archive/BACKLOG/TR-004-design-doc-lifecycle.mddocs/design/README.mddocs/design/TR-001-architecture-reality-gap.mddocs/design/TR-002-threat-model.mddocs/design/TR-004-design-doc-lifecycle.mddocs/legends/TR-truth.md
✅ Files skipped from review due to trivial changes (9)
- docs/BACKLOG/README.md
- docs/archive/BACKLOG/README.md
- docs/archive/BACKLOG/TR-002-threat-model.md
- docs/archive/BACKLOG/TR-001-architecture-reality-gap.md
- docs/archive/BACKLOG/TR-004-design-doc-lifecycle.md
- docs/design/README.md
- WORKFLOW.md
- docs/design/TR-001-architecture-reality-gap.md
- docs/design/TR-004-design-doc-lifecycle.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/API.md
- docs/design/TR-002-threat-model.md
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/legends/TR-truth.md (1)
94-94: Optional: tighten wording at Line 94.“Under strain” reads slightly vague here; a more concrete phrase improves scanability.
✏️ Suggested wording tweak
-- evaluating service decomposition where the current boundary is under strain +- evaluating service decomposition where the current boundary no longer fits🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/legends/TR-truth.md` at line 94, Replace the vague phrase "evaluating service decomposition where the current boundary is under strain" with a more concrete alternative—e.g., "evaluating service decomposition where the current boundary is experiencing high load or frequent contention"—so readers immediately understand the trigger conditions; update the line containing that exact phrase in TR-truth.md to the new wording.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/legends/TR-truth.md`:
- Line 94: Replace the vague phrase "evaluating service decomposition where the
current boundary is under strain" with a more concrete alternative—e.g.,
"evaluating service decomposition where the current boundary is experiencing
high load or frequent contention"—so readers immediately understand the trigger
conditions; update the line containing that exact phrase in TR-truth.md to the
new wording.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 93524617-c1ec-4bdc-885e-f68e999e6b69
📒 Files selected for processing (7)
docs/BACKLOG/README.mddocs/BACKLOG/TR-006-docs-maintainer-checklist.mddocs/BACKLOG/TR-007-security-doc-discoverability-audit.mddocs/BACKLOG/TR-008-empty-state-phrasing-consistency.mddocs/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.mddocs/BACKLOG/TR-010-planning-index-consistency-review.mddocs/legends/TR-truth.md
✅ Files skipped from review due to trivial changes (5)
- docs/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md
- docs/BACKLOG/TR-007-security-doc-discoverability-audit.md
- docs/BACKLOG/TR-006-docs-maintainer-checklist.md
- docs/BACKLOG/TR-010-planning-index-consistency-review.md
- docs/BACKLOG/TR-008-empty-state-phrasing-consistency.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/BACKLOG/README.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Included cycles
Review order
Notes
Summary by CodeRabbit