(plan) system review and break down plans

2026-08-19 09:52:07 -07:00
commit 9d28b63ff2
46 changed files with 5620 additions and 0 deletions
@@ -0,0 +1,98 @@
+# M0.1 — Cargo workspace + crate skeletons
+
+| Field | Value |
+|---|---|
+| Phase | M0 — Read-only spine |
+| Size | S — under 1 day |
+| Status | ⬜ Not started |
+| Flags | — |
+| Spec | inlined below |
+| Blocks | — |
+
+## Goal
+
+The six-crate workspace, building clean, with the dependency direction fixed
+before any code exists to violate it.
+
+## Facts (inlined — no spec read needed)
+
+```
+crates/
+  mem-core/     domain types; Level; gate-response parser; the gated loop
+  mem-chunk/    RecordSource trait; ChunkPolicy; FlushTrigger
+  mem-llm/      gateway client — chat, embeddings, rerank
+  mem-ingest/   source adapters: pi sessions, claude transcripts
+  mem-store/    JSONL log; pgvector repo; Obsidian projector
+  mem-cli/      binary `mem`
+```
+
+Dependency direction, enforced from the start:
+
+```
+mem-cli  ->  mem-ingest, mem-store, mem-llm, mem-chunk, mem-core
+mem-store ->  mem-core
+mem-ingest -> mem-chunk, mem-core
+mem-chunk ->  mem-core
+mem-llm   ->  mem-core
+mem-core  ->  (nothing in this workspace)
+```
+
+`mem-core` depends on no sibling. It holds the types every other crate speaks,
+so a dependency out of it is a cycle waiting to happen.
+
+Workspace deps to pin now, so versions do not drift per crate: `tokio`,
+`futures`, `serde`, `serde_json`, `serde_yaml`, `anyhow`, `thiserror`,
+`sha2`, `clap`, `reqwest`, `tracing`.
+
+## Steps
+
+1. `Cargo.toml` at the repo root with `[workspace] members = [...]` and a
+   `[workspace.dependencies]` block holding every shared crate version.
+2. Six member crates, each declaring deps as `foo.workspace = true`.
+3. `mem-cli` is the only `[[bin]]`; the rest are libraries.
+4. Add `rust-toolchain.toml` pinning a version, so CI and laptop agree.
+5. `.gitignore`: `target/`, `vault/` — but **not** `log/` and **not**
+   `memory-tasks/`. The log is authoritative and the board carries acceptance
+   criteria; both are tracked.
+6. Wire a CI job running `cargo build --workspace` and `cargo clippy --workspace
+   -- -D warnings`.
+
+## Acceptance
+
+- `cargo build --workspace` succeeds from a clean checkout.
+- `cargo clippy --workspace -- -D warnings` is clean.
+- `mem-core` has zero intra-workspace dependencies.
+
+## Verify
+
+**Harness:** cargo itself, plus a dependency assertion that does not trust the
+manifests to be read by a human.
+
+**Integration test** — `tests/it_workspace.rs` in the root:
+1. `a1_all_members_build` — shell out to `cargo build --workspace`, assert exit 0.
+2. `a2_mem_core_has_no_sibling_deps` — parse `crates/mem-core/Cargo.toml`, assert
+   no dependency name starts with `mem-`.
+3. `a3_dependency_direction` — parse every member manifest, build the edge set,
+   assert it is a subset of the table above and that the graph is acyclic.
+4. `a4_log_and_tasks_are_tracked` — assert `.gitignore` matches neither
+   `log/` nor `memory-tasks/`.
+
+**Command:** `cargo test --workspace workspace`
+
+**False pass:**
+- Asserting the graph is acyclic **only**. Acyclic permits `mem-core ->
+  mem-store`, which is backwards and still acyclic. Assertion 3 must check the
+  edge set against the table, not just for cycles.
+- A CI job that runs `cargo build` in the root without `--workspace`. It builds
+  the virtual manifest and can miss a member that does not compile.
+
+## Traps
+
+- Per-crate dependency versions instead of `workspace.dependencies`. They drift,
+  and two versions of `serde` in one tree is a confusing type error much later.
+- Gitignoring `log/`. It is the authoritative record; ignoring it makes the whole
+  authority model a fiction.
+
+---
+
+Background: [DESIGN.md](../DESIGN.md) — Repository layout