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.

2 files changed, 95 insertions, 1 deletions

diff --git a/.ai/notes.org b/.ai/notes.org
index bf5e1b7..1ec9528 100644
--- a/.ai/notes.org
+++ b/.ai/notes.org
@@ -79,6 +79,6 @@ Format:
 Markers maintained by workflows to record when they last ran. Read by other workflows that gate their behavior on freshness.
 
 :LAST_AUDIT: 2026-05-28
-:LAST_INBOX_PROCESS: 2026-06-03
+:LAST_INBOX_PROCESS: 2026-06-05
 
 Format: one =:MARKER: YYYY-MM-DD= line per workflow. Workflows overwrite their own marker on completion.
diff --git a/.ai/sessions/2026-06-05-05-58-pattern-catalog-and-roam-memory-spec.org b/.ai/sessions/2026-06-05-05-58-pattern-catalog-and-roam-memory-spec.org
new file mode 100644
index 0000000..81642ad
--- /dev/null
+++ b/.ai/sessions/2026-06-05-05-58-pattern-catalog-and-roam-memory-spec.org
@@ -0,0 +1,94 @@
+#+TITLE: Session Context
+#+DATE: 2026-06-04
+
+* Summary
+
+** Active Goal
+
+Clean startup that turned into processing two work-project inbox handoffs (both rulesets-tooling improvements), then building the long-pending pattern catalog, then pivoting the memory-sync task onto a shared org-roam KB and drafting its spec. Three feature commits pushed; one spec drafted for review.
+
+** Decisions
+
+- *voice #38 elevated to a mandatory final pass* (handoff #1). The terse/Orwell cut runs as an explicit standalone last step before any draft is shown, not one of 41 walked mid-list. Reviewed the work agent's pre-staged edits, shipped them.
+- *make install folded into startup Phase A.0* (handoff #2). A skill added to rulesets + pushed reached files via git pull but not the ~/.claude symlink; now make install runs after the rulesets pull, idempotent, quiet on all-skip, with a Phase C surfacing bullet.
+- *Pattern catalog built and shipped.* Approved the spec as written (all 5 decisions + 3 open questions). Built six seed patterns + README + pointer rule.
+- *Catalog format: .org, not .md.* First drafted .md (justified from DECISION 1's "mirrors memory/ and claude-rules/"); Craig chose .org. Converted with #+KEYWORD frontmatter; pointer claude-rules/patterns.md stays .md (Makefile glob + rules layer require it).
+- *Memory-sync task pivoted to a shared org-roam KB.* Pressure-tested the two-tier idea, then Craig redirected: ~/sync/org/roam/ already exists (484 files, Syncthing-synced since 2023), so sync is already solved. Drafted a spec adopting it as the shared agent substrate. DECISION 5 (work/personal write boundary) left for Craig's ratification.
+
+** Data Collected / Findings
+
+- flush skill was linked at 00:20 (work agent's manual make install) — confirmed the gap was real; make install is idempotent (skip/link/WARN/relink).
+- All 7 catalog .org files parse via emacs --batch org-element-parse-buffer; cross-links resolve; each pattern has slug-matches-filename + 7 keyword fields; zero em-dashes.
+- ~/sync/org/roam/ = 484 org files, Syncthing-synced (not git). rulesets memory dir is unmanaged (7 files, no enclosing git); 13 per-project memory dirs total, all at-risk.
+- The dedicated-repo memory approach was built then reversed (pooled work + personal); no ~/.claude-memory clone remains.
+
+** Files Modified
+
+- voice/SKILL.md, voice/references/voice-profile.org, claude-rules/commits.md — #38 terse final pass (commit 4779ce8).
+- claude-templates/.ai/workflows/startup.org + .ai/ mirror — make install in Phase A.0 + Phase C surfacing (commit 3eed289).
+- patterns/ (6 .org seed patterns + README.org) + claude-rules/patterns.md pointer — the catalog (commit 83bf3cb).
+- docs/design/2026-06-05-org-roam-knowledge-base-spec.org — new spec, NOT yet committed (lands in the wrap-up commit).
+- todo.org — pattern catalog DONE + CLOSED; memories task pivoted with org-roam progress entry + VERIFY for DECISION 5.
+- .ai/notes.org — :LAST_INBOX_PROCESS: → 2026-06-05.
+- Replies sent to work's inbox for both handoffs; both rulesets inbox handoffs cleared.
+
+** Next Steps
+
+- *Memory/org-roam (the resume point):* Craig ratifies spec DECISION 5 (work/personal write boundary — options A/B/C, C recommended) plus the Syncthing-topology and node-granularity / harness-memory-fate / write-review open questions. Then implement claude-rules/knowledge-base.md + the write schema. See the VERIFY under the memories task in todo.org.
+- First real test of the pattern catalog: a consuming agent reaching for a pattern while designing a prompt flow.
+- The make install startup step takes effect on every project's next session; voice #38 and the catalog are live on this machine now.
+- Open [#C]s untouched: create-documentation skill, lint-org append-vs-converged question, the rotation batch.
+
+* Session Log
+
+** Startup + inbox handoff: elevate voice #38 to a mandatory final pass
+
+Clean startup (2026-06-04 23:53 CDT). No crash anchor, no reminders/pending decisions, zero stale tasks. One open A/B task surfaced: the pattern-catalog spec (#B), gated on Craig's review.
+
+Craig asked to re-check the inbox before moving on. A new handoff had landed at 00:04 from the work project (2026-06-05-0005-from-work-rulesets-note.org): elevate voice pattern #38 (terse / omit-needless-words cut) from one-of-41-walked-mid-list to a mandatory standalone *final* pass run right before any draft is shown. Trigger at work: a commit message went out needing two manual Orwell-walk requests before it read terse, even though /voice personal had run — the gap was execution position, not the rule text.
+
+The handoff's three claimed edits were already staged in this repo's working tree (the work agent edited them here). Verified all three against the diff:
+- voice/SKILL.md — new Process step 7 (standalone terse pass, prose+personal; general skips), "Present" bumped to step 8, Output Format item 7 added.
+- voice/references/voice-profile.org — §38 "Execution position" subsection + 2026-06-05 history entry (SKILL/profile pairing rule honored).
+- claude-rules/commits.md — one sentence appended to the Single-skill gate naming #38 as the last pass before printing.
+
+Craig chose option 1 (ship it). Ran the publish flow:
+- Step 0 reconcile: 0/0 clean.
+- Step 1 review-code --staged: Approve, no Critical/Important. One cosmetic Minor (Output Format item 4 "Final rewrite" slightly misnamed now that the true final comes from the terse pass) — left as-is. Verified the SKILL.md renumber introduced no stale step references.
+- Step 2: drafted commit msg, /voice personal (41 patterns; #33 semicolon split, #32 first-person, #38 terse trim; #39 names of SKILL.md/commits.md kept under the commits.md edge case — they're the change itself in their own repo). Craig approved.
+
+Committed 4779ce8 as Craig (c@cjennings.net), pushed 46e1d37..4779ce8 to origin/main.
+
+Verified live on this machine: ~/.claude/skills/voice and ~/.claude/rules/commits.md are symlinks into the rulesets checkout, so the change is already in effect — no re-install needed here. Other machines pick it up on next rulesets startup pull (symlinked free; copy-based would need make install there).
+
+Replied to work's inbox (2026-06-05-0016-from-rulesets-done...org) confirming. Removed the processed handoff from rulesets/inbox/; inbox clean (exit 0). Bumped :LAST_INBOX_PROCESS: 2026-06-03 → 2026-06-05 in notes.org (rides to wrap-up commit).
+
+** Started pattern-catalog walkthrough, interrupted by second work handoff: make install at startup
+
+Began walking Craig through the pattern-catalog spec (docs/design/2026-06-02-pattern-catalog-spec.org) — five DECISION calls + three open questions. My read: all five land where I'd put them, the three open-question leans are sensible, approve-and-build. Craig was about to decide when he asked to check the inbox again.
+
+Second work handoff (2026-06-05-0023): fold make install into startup Phase A.0. Root cause (verified): a skill added to rulesets + pushed reaches files via git pull but not the ~/.claude symlink — make install only links what's new and pull doesn't run it. flush sat uninstalled from 2026-06-02 until a manual install tonight (symlink ts 00:20). Verified make install is idempotent (skip/link/WARN/relink) and ran the exact proposed block live (prints "nothing new to link" on this fully-linked machine).
+
+Craig chose option 1 (implement now). Added to both canonical (claude-templates/.ai/workflows/startup.org) and the .ai/ mirror, byte-identical:
+- Phase A.0: new "*** Install rulesets symlinks into ~/.claude (idempotent)" subsection after the rulesets pull — guarded make -C "$HOME/code/rulesets" install, grep filters to link/relink/WARN, quiet "nothing new to link" otherwise, no cd.
+- Phase C: new "Newly-installed symlinks" surfacing bullet — link → check available-skills (registered=note available / absent=restart prompt), WARN=human collision, all-skip=silent.
+
+Publish flow: Step 0 reconcile 0/0. review-code --staged Approve, no Critical/Important, one cosmetic Minor (2>&1 into grep could mask a make-install error as "nothing new" — benign, left). /voice personal on commit msg (subject trimmed <72, #13 em-dash→colon, #33 semicolon→period, #35 split, #38 terse; #39 ~/.claude/.ai names kept under the own-repo edge case). Craig approved.
+
+Committed 3eed289, pushed 4779ce8..3eed289. Replied to work (2026-06-05-0028-from-rulesets-done...org), cleared handoff, inbox clean. Note: takes effect on every project's next session (it's a startup doc); no restart needed for the doc itself.
+
+Next: resume the pattern-catalog decision Craig was about to make.
+
+** Built the pattern catalog (approved as written, converted to org)
+
+Craig approved the spec as written (option 1). Read the four pearl source notes in docs/design/ for the real pattern content (didn't reconstruct from memory). Built patterns/ with 6 seed patterns + README + claude-rules/patterns.md pointer. First draft was .md (justified from DECISION 1's "mirrors memory/ and claude-rules/"); I flagged the .md-vs-.org call. Craig said convert to org.
+
+Converted all 6 patterns + README to .org with #+KEYWORD frontmatter (#+SLUG/#+PRINCIPLE/#+PROBLEM/#+TAGS/#+SOURCE/#+EXAMPLES), dropped em-dashes, org [[file:...]] links. The pointer claude-rules/patterns.md stays .md — the Makefile RULES glob is claude-rules/*.md and Claude Code loads .md rules, so a .org pointer wouldn't install or load. Verified: all 7 org files parse via emacs --batch org-element-parse-buffer; all cross-links resolve; every pattern has slug-matches-filename + 7 keyword fields; zero em-dashes.
+
+Publish flow (run on the .md draft, re-verified after org conversion): review-code --staged Approve, no Critical/Important, one Minor (pearl names in examples — fine for the private rulesets remote, watch downstream if cited in a deepsat artifact). /voice personal on commit msg (subject 69 chars, em-dash→colon/comma, 2 semicolons→periods, passive opener→active); after org conversion I corrected the last paragraph (.md→.org, README.md→README.org, dropped a new semicolon).
+
+todo.org: parent ** TODO [#B] Cross-project pattern catalog → DONE + CLOSED [2026-06-05 Fri]; the VERIFY rewritten to two dated log entries (spec approved + catalog built), both reflecting the .org decision.
+
+Committed 83bf3cb, pushed 3eed289..83bf3cb. todo.org + notes.org marker + session-context still unstaged — ride to wrap-up.
+
+Open: the .md-vs-.org choice is resolved (.org). Catalog's first real test is a consuming agent reaching for a pattern while designing a prompt flow.