docs: add standalone architecture document and harness-derived goals#42
docs: add standalone architecture document and harness-derived goals#42
Conversation
Create docs/architecture.md with layer diagram, module map, dependency direction rules, forbidden dependencies, cross-cutting concerns, and key invariants for the muzzle workspace. Extracts architecture from CLAUDE.md into warm-context documentation per harness.md Phase 0d. Update GOALS.md with 7 new harness-derived directives (21-27) and mark directive 21 as complete.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughNew documentation and metadata were added: a cycle-history entry for cycle 17, seven new goals (21–27) in Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Greptile SummaryThis PR is a docs-only change that creates Confidence Score: 5/5Safe to merge — docs-only change with no code modifications; prior review concerns are fully resolved. Both previously identified issues (serde_derive naming error and missing diagram edge) are confirmed fixed. The only remaining item is a trivial P2 schema inconsistency in the cycle history log (missing canonical_sha), which does not block functionality. Convergence across review rounds is good. .agents/evolve/cycle-history.jsonl — missing canonical_sha in cycle 17 entry. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
subgraph hooks["muzzle-hooks"]
B["Binaries\nsession-start · permissions\nchangelog · session-end\nensure-worktree"]
C["Core Modules\nsandbox · gitcheck\nsession · worktree/"]
I["Infrastructure\nconfig · output · changelog\nlog · mcp"]
B -->|imports| C
B -->|imports| I
C -->|imports| I
end
subgraph memory["muzzle-memory (independent)"]
M["store · capture · inject · main"]
end
Reviews (4): Last reviewed commit: "fix(docs): label storage paths as defaul..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/architecture.md (1)
9-9: Add language identifiers to fenced code blocks (markdownlint MD040).Please add a language hint to each code fence at Line 9, Line 24, and Line 45 to keep docs lint-clean.
Suggested markdown cleanup
-``` +```text muzzle (workspace) ├── hooks/ muzzle-hooks 5 binaries Session isolation + sandbox enforcement └── memory/ muzzle-memory 1 binary Persistent cross-project memory (SQLite + FTS5)-
+text
┌─────────────────────────────────────────────────┐
│ Binaries (bin/) │
...
└─────────────────────────────────────────────────┘-``` +```text binaries ──→ core modules ──→ infrastructure │ ▲ └────────────────────┘</details> Also applies to: 24-24, 45-45 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/architecture.mdat line 9, The fenced code blocks in
docs/architecture.md are missing language identifiers which triggers
markdownlint MD040; update each triple-backtick fence (the three code blocks
that render the ASCII tree and diagrams) to include a language hint such as
"text" (e.g., changetotext) so the linter recognizes them; locate the
three fenced blocks that contain the ASCII diagrams and add the language
identifier to each opening fence (maintain the existing contents and closing
fences unchanged).</details> </blockquote></details> <details> <summary>GOALS.md (1)</summary><blockquote> `237-241`: **Add a language identifier to the WHAT/FIX/REF code fence (MD040).** Line 237 should use a fenced language (for example `text`) to satisfy markdown linting. <details> <summary>Suggested markdown fix</summary> ```diff -``` +```text WHAT: <what was violated> FIX: <specific instruction the agent can execute> REF: <pointer to relevant doc or config> ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@GOALS.mdaround lines 237 - 241, The fenced code block containing the
WHAT/FIX/REF template uses a plain triple-backtick fence without a language tag;
update that fence to include a language identifier (e.g., change the opening
"" to "text") so the block is recognized by Markdown linters (MD040) —
modify the fenced block shown with the lines "WHAT: FIX:
REF: " to start with a language like "text".</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@docs/architecture.md:
- Around line 122-132: The runtime dependency summary string "5 runtime crates
total (hooks: 5, memory: 1 additional)" is inconsistent with the table that
lists six crates (serde,serde_json,regex,flate2,libc,rusqlite);
update that summary to reflect the actual counts (e.g., "6 runtime crates total
(hooks: 5, memory: 1 additional)") so the header matches the table entries.- Around line 96-97: The doc line stating "No proc macros —
serdederive is
viaserde_core(no proc-macro crate)" is inaccurate; update the "No proc
macros" section to reflect that the workspace usesserde = { version = "1", features = ["derive"] }which pulls in theserde_deriveproc-macro crate
(confirmed in Cargo.lock). Replace the incorrect claim aboutserde_core/no
proc-macro with a corrected statement thatserdederive usesserde_derive(a
proc-macro) or remove the absolute "No proc macros" constraint and note the
exception forserdederive.
Nitpick comments:
In@docs/architecture.md:
- Line 9: The fenced code blocks in docs/architecture.md are missing language
identifiers which triggers markdownlint MD040; update each triple-backtick fence
(the three code blocks that render the ASCII tree and diagrams) to include a
language hint such as "text" (e.g., changetotext) so the linter
recognizes them; locate the three fenced blocks that contain the ASCII diagrams
and add the language identifier to each opening fence (maintain the existing
contents and closing fences unchanged).In
@GOALS.md:
- Around line 237-241: The fenced code block containing the WHAT/FIX/REF
template uses a plain triple-backtick fence without a language tag; update that
fence to include a language identifier (e.g., change the opening "" to "text") so the block is recognized by Markdown linters (MD040) — modify the
fenced block shown with the lines "WHAT: FIX: REF: " to
start with a language like "text".</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `5dadc003-b71a-47e4-a63e-7346f7959e39` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 13120716ff56ee99ed187190acee280b4eac5613 and f7f61f1de201d185c6e7b8e6a86e543063125694. </details> <details> <summary>📒 Files selected for processing (3)</summary> * `.agents/evolve/cycle-history.jsonl` * `GOALS.md` * `docs/architecture.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
- Fix dependency diagram: show direct binaries → infra edge - Fix proc-macro claim: serde_derive is a proc macro, not serde_core - Fix dep count: 6 runtime crates, not "5 + 1 additional"
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/architecture.md (2)
9-13: Consider adding language identifier to fenced code block.The ASCII tree diagram could specify a language identifier (e.g.,
textorascii) for better rendering and accessibility.♻️ Proposed fix
-``` +```text muzzle (workspace) ├── hooks/ muzzle-hooks 5 binaries Session isolation + sandbox enforcement └── memory/ muzzle-memory 1 binary Persistent cross-project memory (SQLite + FTS5)</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/architecture.mdaround lines 9 - 13, Update the fenced code block
containing the ASCII tree (the block that begins withand the lines starting "muzzle (workspace)" and "├── hooks/" / "└── memory/") to include a language identifier such as "text" or "ascii" (e.g., change the opening fence fromtoblock contents unchanged aside from the fence header.
24-49: Consider adding language identifiers to ASCII diagrams.Both the layer diagram and dependency direction diagram use fenced code blocks without language specifiers. Adding
textorasciiidentifiers would improve rendering consistency.♻️ Proposed fix
-``` +```text ┌─────────────────────────────────────────────────┐ │ Binaries (bin/) │And for the dependency diagram:
-``` +```text binaries ──→ core modules ──→ infrastructure🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture.md` around lines 24 - 49, Update the two fenced code blocks containing the ASCII diagrams by adding a language identifier (e.g., `text`) after the opening backticks so they render consistently; specifically modify the block that starts with "┌─────────────────────────────────────────────────┐" (the layer diagram) and the block that starts with "binaries ──→ core modules ──→ infrastructure" (the Dependency Direction diagram) to use ```text as the fence opener for each.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/architecture.md`:
- Line 80: The table row describing the `inject` option currently uses lowercase
"markdown"; update the description for `inject` (the "Format memories as
markdown for SessionStart injection" cell) to capitalize "Markdown" as a proper
noun so it reads "Format memories as Markdown for SessionStart injection",
ensuring the `inject` and `SessionStart` identifiers remain unchanged.
---
Nitpick comments:
In `@docs/architecture.md`:
- Around line 9-13: Update the fenced code block containing the ASCII tree (the
block that begins with ``` and the lines starting "muzzle (workspace)" and "├──
hooks/" / "└── memory/") to include a language identifier such as "text" or
"ascii" (e.g., change the opening fence from ``` to ```text) so the diagram
renders/accessibility metadata is explicit; leave the block contents unchanged
aside from the fence header.
- Around line 24-49: Update the two fenced code blocks containing the ASCII
diagrams by adding a language identifier (e.g., `text`) after the opening
backticks so they render consistently; specifically modify the block that starts
with "┌─────────────────────────────────────────────────┐" (the layer diagram)
and the block that starts with "binaries ──→ core modules ──→ infrastructure"
(the Dependency Direction diagram) to use ```text as the fence opener for each.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e01a52db-91ec-4c12-a1bb-090416604296
📒 Files selected for processing (1)
docs/architecture.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/architecture.md`:
- Around line 9-13: The three fenced code blocks that contain the ASCII diagrams
(the block starting with "muzzle (workspace) ...", the large box beginning
"┌─────────────────────────────────────────────────┐", and the flow diagram
"binaries ──→ core modules ──→ infrastructure") are missing language identifiers
and trigger markdownlint MD040; add the language tag (e.g., ```text) to the
opening fence of each of those blocks and do the same for the other ASCII/code
fences mentioned in the review (the additional diagram blocks later in the file)
so all fenced blocks include a language identifier.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 195fe74d-4504-4c0a-af8c-34b2bea60c38
📒 Files selected for processing (1)
docs/architecture.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/architecture.md`:
- Around line 107-108: Update the "State storage" and "Memory storage" rows in
the table so the paths are shown as defaults/examples rather than fixed
locations: change the entries for "State storage" (`~/.local/state/muzzle/`) and
"Memory storage" (`~/.muzzle/memory.db`) to explicitly label them as "default"
or "example" paths and mention that actual locations are XDG-configurable (or
overridden via configuration), so readers know these are not invariant across
environments.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 33cea5ee-904d-48d0-9fc0-f9f8e4fbdcf3
📒 Files selected for processing (1)
docs/architecture.md
1 participant
Summary
docs/architecture.mdwith layer diagram, module map, dependency direction rules, forbidden dependencies, cross-cutting concerns, and key invariants (directive 21).agents/research/harness.mdanalysisNew Directives
Test plan
cargo buildpassescargo clippypasses🤖 Generated with Claude Code