docs(design): add org-roam knowledge-base spec for shared agent memory

The spec adopts the existing ~/sync/org/roam/ KB (Syncthing-synced, 484 files) as the shared store agents read from and write to, so cross-machine memory sync comes for free instead of needing new infrastructure. It recommends the mechanics (queried as files, capture in harness memory then promote durable facts to the KB, a claude-rules pointer, an :agent: write schema) and leaves the work/personal write boundary for ratification. Supersedes the dedicated-repo and two-tier approaches for the storage-and-sync half.

1 files changed, 35 insertions, 24 deletions

diff --git a/todo.org b/todo.org
index 248c900..212bf03 100644
--- a/todo.org
+++ b/todo.org
@@ -34,30 +34,6 @@ Tags are assigned and refreshed by =task-audit=; =task-review= keeps them honest
 
 * Rulesets Open Work
 
-** TODO [#B] Cross-project pattern catalog :spec:thinking:
-:PROPERTIES:
-:LAST_REVIEWED: 2026-06-02
-:END:
-
-From pearl handoffs [[file:docs/design/2026-05-27-pattern-catalog-pearl-notes.org][2026-05-27]] + [[file:docs/design/2026-05-28-pattern-catalog-no-empty-input.org][2026-05-28 follow-up]].
-
-Meta-question: how do good patterns travel from project A to project B? Pearl shipped three worked examples worth capturing — one-prompt picker with typed prefix (pearl-pick-source), magit-transient state buttons, and "no empty input as meaningful" (none-sentinel as first candidate). Each is a small principle with wide surface area; without a catalog, every project re-derives them from scratch.
-
-Open design questions before any implementation:
-- Catalog format — structured (one pattern per file with frontmatter) vs free-form doc
-- Surfacing mechanism — agent-driven (model spots opportunity) vs human-driven (Craig grep-searches)
-- Anti-patterns included or only what worked
-- Intake cadence — every time one lands, or batch review
-- Home — rulesets repo (agent visibility) vs Linear doc vs per-project cross-links
-
-Pearl recommends a one-page spec (problem + design + open questions + acceptance) before implementation. Pearl available to come back for spec-review iterations.
-
-*** 2026-05-28 Thu @ 08:12:55 -0500 Pearl shipped patterns 4-6, filed alongside the prior two
-Three more pearl handoffs landed and were filed during this audit. Filed: [[file:docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org][prompt-labels-and-defaults]] (patterns 4-5: label-matches-behavior, default-most-common with friction-proportional-to-consequence) and [[file:docs/design/2026-05-28-pattern-catalog-prompt-collapse.org][prompt-collapse]] (pattern 6: collapse N orthogonal prompts into one enriched prompt). The catalog's evidence base is now four pearl notes in =docs/design/= covering six patterns plus the synthesizing principle Pearl articulated — "choices on screen, accurately labeled, ordered by what the user most often wants, friction sized to the cost of being wrong."
-
-*** VERIFY Review the pattern-catalog spec (5 decisions + 3 open questions)
-One-page spec drafted 2026-06-02: [[file:docs/design/2026-06-02-pattern-catalog-spec.org][2026-06-02-pattern-catalog-spec.org]]. It makes a recommended call on each of the five open design questions — format (one file per pattern with frontmatter), home (a =patterns/= dir in rulesets), surfacing (a thin =claude-rules/patterns.md= pointer, agent-driven), anti-patterns (a field within each pattern), intake (capture-on-landing, promote-on-review) — plus three smaller open questions (directory name, generalize-now-vs-lazily, whether a =/pattern= skill is worth it). Implementation is gated on your review. Pearl is available for spec-review iterations.
-
 ** TODO [#C] Check that memories are sync'd across machines via git :spec:
 :PROPERTIES:
 :LAST_REVIEWED: 2026-06-02
@@ -98,6 +74,14 @@ Created bare =git@cjennings.net:claude-memory.git=, cloned to =~/.claude-memory=
 
 *** 2026-05-24 Sun @ 01:53:35 -0500 Reversed the migration — back to unmanaged per-project memory
 Cancelled the follow-up brainstorm and undid the dedicated-repo migration at Craig's call. Moved all 7 memory dirs back to =~/.claude/projects/<enc>/memory/= (content preserved), deleted the =~/.claude-memory= clone, and deleted the bare =claude-memory.git= on the server. Memory is back to its original at-risk state, so the task reopens at [#C] pending a direction. The brainstorm landed on a two-tier idea for whenever this resumes: promote general lessons into a rulesets-tracked file symlinked into =~/.claude/rules/= (loaded into every project natively, one repo), and keep project-specific memory under each project's own =.ai/memory/= (committed where =.ai/= is tracked, at-risk where it's gitignored). Not implemented.
+
+*** 2026-06-05 Fri @ 05:57:35 -0500 Pivot: adopt the existing org-roam KB as the shared agent substrate
+Pressure-tested the two-tier idea, then Craig redirected: a shared org-roam knowledge base any project can read and write makes this simpler. Ground truth verified: =~/sync/org/roam/= already exists (484 org files, curated since 2023, Syncthing-synced, not git). So cross-machine sync is already solved, and the task stops being "build a memory-sync system" and becomes "point agents at the KB that already syncs." The dedicated-repo and two-tier approaches are both superseded for the storage+sync half.
+
+Wrote a one-page spec: [[file:docs/design/2026-06-05-org-roam-knowledge-base-spec.org][2026-06-05-org-roam-knowledge-base-spec.org]]. Five decisions, mechanics recommended: (1) KB is a queried substrate accessed as files (ripgrep + follow =[[id:]]= by grep), not via the org-roam package; (2) capture in harness memory, promote durable facts into the KB (same cadence as the pattern catalog) — resolves the at-risk problem since the valuable knowledge moves to the synced KB; (3) a =claude-rules/knowledge-base.md= pointer rule carries path/query/write-schema/boundary; (4) write schema = roam-valid node + =:agent:= filetag so agent notes stay distinguishable and index on the next =org-roam-db-sync=. The rules layer (=claude-rules/=, =CLAUDE.md=) is untouched — the KB replaces the memory tier, not the rules tier.
+
+*** VERIFY Decide the work/personal write boundary (spec DECISION 5) + ratify the org-roam-KB spec
+The spec's central decision needs Craig's call: the shared KB is personal and on all personal machines, so a work (DeepSat) agent writing into it pools confidential work facts there. Three options in the spec: A — work walled off (personal-only KB); B — one KB tag-scoped (=:work:=/=:personal:=/=:general:=, agent forbidden to cross-surface); C (recommended) — read-shared, write-scoped (any project reads; personal projects write to the KB, work writes only to its own store). Recommendation C hinges on two facts only Craig has: how sensitive work memory is, and whether Syncthing replicates =~/sync/= to any work machine (if not, a work agent can't read it regardless, pushing work toward A). Other open questions in the spec: node granularity (per-fact vs per-project agent-notes node), harness memory's fate (keep thin hot-set vs retire), and whether agent writes land freely or via an =:agent:inbox:= review (Syncthing has no git gate). Once DECISION 5 lands, implement the pointer rule + write schema.
 ** TODO [#C] Build =create-documentation= skill for high-quality project/product docs :feature:
 :PROPERTIES:
 :LAST_REVIEWED: 2026-06-02
@@ -2497,3 +2481,30 @@ CLOSED: [2026-06-02 Tue]
 :LAST_REVIEWED: 2026-06-02
 :END:
 From Craig (2026-06-02). The Approach phase should consider whether the work needs a spec when one doesn't already exist. For a big task, this isn't a silent skip — the pre-confirmation summary must explicitly report why a spec isn't needed, so the decision is visible and challengeable at the gate rather than assumed. Small tasks can pass without comment. Edit the start-work skill's Approach-gate phase to add the spec-needed consideration and the big-task report-why-not requirement.
+** DONE [#B] Cross-project pattern catalog :spec:thinking:
+CLOSED: [2026-06-05 Fri]
+:PROPERTIES:
+:LAST_REVIEWED: 2026-06-02
+:END:
+
+From pearl handoffs [[file:docs/design/2026-05-27-pattern-catalog-pearl-notes.org][2026-05-27]] + [[file:docs/design/2026-05-28-pattern-catalog-no-empty-input.org][2026-05-28 follow-up]].
+
+Meta-question: how do good patterns travel from project A to project B? Pearl shipped three worked examples worth capturing — one-prompt picker with typed prefix (pearl-pick-source), magit-transient state buttons, and "no empty input as meaningful" (none-sentinel as first candidate). Each is a small principle with wide surface area; without a catalog, every project re-derives them from scratch.
+
+Open design questions before any implementation:
+- Catalog format — structured (one pattern per file with frontmatter) vs free-form doc
+- Surfacing mechanism — agent-driven (model spots opportunity) vs human-driven (Craig grep-searches)
+- Anti-patterns included or only what worked
+- Intake cadence — every time one lands, or batch review
+- Home — rulesets repo (agent visibility) vs Linear doc vs per-project cross-links
+
+Pearl recommends a one-page spec (problem + design + open questions + acceptance) before implementation. Pearl available to come back for spec-review iterations.
+
+*** 2026-05-28 Thu @ 08:12:55 -0500 Pearl shipped patterns 4-6, filed alongside the prior two
+Three more pearl handoffs landed and were filed during this audit. Filed: [[file:docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org][prompt-labels-and-defaults]] (patterns 4-5: label-matches-behavior, default-most-common with friction-proportional-to-consequence) and [[file:docs/design/2026-05-28-pattern-catalog-prompt-collapse.org][prompt-collapse]] (pattern 6: collapse N orthogonal prompts into one enriched prompt). The catalog's evidence base is now four pearl notes in =docs/design/= covering six patterns plus the synthesizing principle Pearl articulated — "choices on screen, accurately labeled, ordered by what the user most often wants, friction sized to the cost of being wrong."
+
+*** 2026-06-05 Fri @ 00:47:59 -0500 Spec approved as written — all 5 decisions + 3 open questions accepted
+Craig approved the spec ([[file:docs/design/2026-06-02-pattern-catalog-spec.org][2026-06-02-pattern-catalog-spec.org]]) as written. Confirmed: one file per pattern with frontmatter; home =patterns/= in rulesets; thin =claude-rules/patterns.md= pointer, agent-driven; anti-patterns as a per-pattern field; capture-on-landing/promote-on-review intake. Open questions resolved to the spec's leans: directory name =patterns/=; concrete-now, generalize-on-second-use; manual promote flow first, no =/pattern= skill yet. Built as =.org= files with =#+KEYWORD= frontmatter (Craig's call over the initial =.md= draft); the =claude-rules/patterns.md= pointer stays =.md= since the rules layer and the Makefile glob require it.
+
+*** 2026-06-05 Fri @ 00:47:59 -0500 Built the catalog — 6 seed patterns + pointer + README
+Created =patterns/= with the six seed patterns (one-prompt-picker-typed-prefix, transient-state-buttons, no-empty-input-as-meaningful, label-matches-behavior, default-most-common-friction-proportional, collapse-orthogonal-prompts), each carrying the frontmatter contract (name/principle/problem/tags/source/examples) plus Problem/Do/Anti-pattern/Applicability/Related sections. =patterns/README.org= states the root principle, the frontmatter contract, and the intake cadence. =claude-rules/patterns.md= is the agent-facing pointer, auto-installed via the Makefile RULES glob. Sourced from the four pearl notes in =docs/design/=.