docs: finalize agent knowledge-base spec as ready with caveats

I ratified all seven decisions: the org-roam KB is the shared agent substrate, the write boundary is read-shared write-scoped (work never writes), nodes are per-fact, agent writes land freely in the KB only, and harness memory stays as the ephemeral capture layer. The spec moves to docs/agent-knowledge-base-spec.org in spec-create format, superseding the 2026-06-05 draft.

A work-root denylist classifier routes writes: personal projects write, work and unknown projects refuse and report the redacted fact. Implementation is broken into three phases and waits on confirming the denylist contents.

1 files changed, 48 insertions, 13 deletions

diff --git a/todo.org b/todo.org
index d14307c..9d04b66 100644
--- a/todo.org
+++ b/todo.org
@@ -52,13 +52,8 @@ The checkpoint+resume halves already shipped as /flush. This is the remaining au
 
 ** TODO [#C] Check that memories are sync'd across machines via git :spec:
 :PROPERTIES:
-:LAST_REVIEWED: 2026-06-02
+:LAST_REVIEWED: 2026-06-10
 :END:
-*** 2026-05-16 Sat @ 01:12:52 -0500 Spec
-#+begin_src cj: comment
-write the spec here. 
-#+end_src
-
 *** 2026-05-14 Thu @ 19:14:11 -0500 Investigate current memory storage
 
 Memory files live at
@@ -94,10 +89,45 @@ Cancelled the follow-up brainstorm and undid the dedicated-repo migration at Cra
 *** 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.
+Wrote a one-page spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (originally docs/design/2026-06-05-org-roam-knowledge-base-spec.org; superseded by the 2026-06-10 spec-create rewrite at the new path). 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.
+
+*** 2026-06-10 Wed @ 14:29:20 -0500 Spec ratified — write boundary is option C; rewritten to spec-create format
+Craig answered via cj annotations in the spec (2026-06-10): DECISION 5 is option C (read-shared, write-scoped — work agents never write the KB). Syncthing does replicate ~/sync/ to a work machine and Craig is fine with how C handles it. Node granularity: per-fact nodes. Write review: agent writes land freely in the KB only — explicitly not permission to post to email, Linear, or any public channel without review and consent. The spec was rewritten into the spec-create format at [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (old draft removed). Implementation explicitly held pending Craig's go-ahead; one decision still open (D7, next VERIFY).
+
+*** 2026-06-10 Wed @ 14:35:40 -0500 Spec review — not ready
+Review written at docs/agent-knowledge-base-spec-review.org (deleted on disposition completion; content summarized in the spec's Review dispositions). Rubric: =Not ready=. Blockers: resolve D7 (keep vs retire harness memory) and define the executable personal/work/unknown write-boundary classifier plus work-side write/refusal destination. Medium notes: use concrete ripgrep commands that exclude =*.sync-conflict-*= files, and define seed-node approval/rollback.
+
+*** 2026-06-10 Wed @ 14:44:00 -0500 D7 resolved — keep harness memory as the capture layer
+Craig ratified "keep" in chat (2026-06-10). Harness memory stays the ephemeral, auto-recalled capture layer; the KB holds promoted durable facts; Phase 3's wrap-up promotion cadence is mandatory. Spec D7 flipped to accepted; D2 stands as written.
+
+*** 2026-06-10 Wed @ 14:44:00 -0500 Project classification defined — work-root denylist, unknown refuses
+Resolved in the spec-response pass: =knowledge-base.md= carries an explicit work-root denylist (initially =~/projects/work=) as the source of truth. Personal = under a known project parent (=~/code/=, =~/projects/=, =~/.emacs.d=) and not denylisted → KB writes allowed. Work or unknown → no KB write; the agent reports the refusal with a one-line redacted summary of the fact. v1 adds no new work-side store — work projects keep their existing project-tree conventions. See the "Project classification and write routing" section of [[file:docs/agent-knowledge-base-spec.org][the spec]]. Denylist completeness is the one open caveat (next VERIFY).
+
+*** 2026-06-10 Wed @ 14:44:00 -0500 Codex review incorporated — spec ready with caveats
+Spec-response pass processed the 2026-06-10 Codex review with D7 = keep as a pre-agreed input. Both blockers cleared (D7 accepted; classification/write-routing section added). Mediums accepted: canonical rg commands with conflict-file exclusion, Phase 2 seed-node approval/rollback mechanics, Makefile no-change note, Testing/Verification section. Three recommendations modified, none rejected — see the spec's Review dispositions. Review file deleted per the workflow. Rubric: ready with caveats (denylist confirmation). Implementation tasks broken out below; implementation itself awaits Craig's go.
+
+*** VERIFY Confirm the work-root denylist contents for knowledge-base.md
+The v1 classifier denylists =~/projects/work=. Is that complete — is archangel (or any other project) work-scoped? Phase 1 ships the rule only after this list is confirmed.
+
+*** TODO Agent KB Phase 1 — pointer rule :feature:
+Write =claude-rules/knowledge-base.md=: KB path, canonical query commands (conflict-file exclusion baked in), the D4 write schema, the classification denylist + write routing, the refusal contract, and the D5/D6 boundary. The existing Makefile RULES glob installs it — no Makefile change. Blocked on the denylist VERIFY above. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 1).
+
+*** TODO Agent KB Phase 2 — seed node + index verification :feature:
+Craig supplies or approves one durable fact; write exactly one =:agent:= node under =~/sync/org/roam/= per the schema; Craig runs =org-roam-db-sync= and confirms it indexes and displays. Rollback on schema failure: delete the one timestamped file. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 2).
+
+*** TODO Agent KB Phase 3 — promotion cadence :feature:solo:
+Add the "anything worth promoting to the KB?" check to the wrap-up workflow (canonical claude-templates + mirror) and document the capture/promote cadence in =knowledge-base.md=. Verifiable via workflow-integrity + lint. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 3).
+
+*** TODO Agent KB — manual testing and validation :test:
+What we're verifying: the v1 acceptance surface that needs Craig's eyes or a live cross-project session. Run after Phases 1-2 land.
+- Seed node appears in org-roam after =org-roam-db-sync= and in the =rg '#\+filetags:.*:agent:'= inventory.
+- In the work project, a durable-storage request produces no write under =~/sync/org/roam/= and the refusal report names the fact.
+- In an unknown project (outside =~/code/=, =~/projects/=, =~/.emacs.d=), the agent refuses or asks rather than guessing.
+Expected: all three behave per the spec's refusal contract; any miss promotes to a bug task. (Agent-runnable checks — make install link, rg finds a known note, conflict-file exclusion — are verified inside Phases 1-2.)
+
+*** TODO [#D] Agent KB hygiene reports for =:agent:= nodes :feature:
+vNext from [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] and its review: report orphaned, stale, or otherwise review-worthy =:agent:= nodes so Craig can curate agent-authored KB content cheaply after writes have accumulated. Further conditional vNext lives in the spec's scope tiers: a =/promote= command if the wrap-up prompt proves insufficient, an =:agent:inbox:= staging tag if free writes prove too noisy.
 
-*** 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
@@ -1026,7 +1056,7 @@ skill should be driven by a concrete contract need, not aspiration.
 
 ** TODO [#C] Token-rotation helper for =@a-bonus/google-docs-mcp= OAuth refresh :feature:quick:
 :PROPERTIES:
-:LAST_REVIEWED: 2026-05-28
+:LAST_REVIEWED: 2026-06-10
 :END:
 
 When a Google refresh token gets revoked (re-grant scopes, removed Connected App, account password reset), recovery is currently manual: run =npx -y @a-bonus/google-docs-mcp= with the right env, follow the URL in a browser, kill the process, base64-encode the new =token.json=, decrypt =secrets.env.gpg=, replace the var, re-encrypt. A small =mcp/refresh-google-docs-token.sh <profile>= would chain that into one command.
@@ -1053,7 +1083,7 @@ Decision (Craig, 2026-05-31): *hold until a token rotation is imminent.* The OAu
 
 ** TODO [#C] Generic agent runtime support — Codex spec v0 :spec:design:
 :PROPERTIES:
-:LAST_REVIEWED: 2026-05-28
+:LAST_REVIEWED: 2026-06-10
 :END:
 Codex drafted a v0 design doc for making rulesets runtime-neutral rather than Claude-Code-specific. Motivating cases: offline operation with a local LLM, and two LLMs running in the same project at the same time without trampling each other's session-context.
 
@@ -1063,13 +1093,18 @@ Immediate correctness issue Codex flagged: the singleton .ai/session-context.org
 
 Broader refactor proposes runtimes/ adapter manifests, generic install commands, language-bundle split (common/ + runtimes/<runtime>/), launcher refactor, local model service via llama.cpp/ollama. Big surface area, six phases.
 
-Before any implementation: needs a real review pass on the spec, and a decision on whether to do Phase 1 alone (low risk, fixes the race) vs commit to the larger arc.
+Before any implementation: needs a real review pass on the spec, and a decision on whether to commit to the larger arc (phases 2-6).
 
-** TODO [#C] Build Craig's writing voice profile from real corpora :spec:
+*** 2026-06-10 Wed @ 14:13:55 -0500 Noted Phase 1 already shipped; narrowed scope to the phases 2-6 decision
+Phase 1 (the correctness fix) is live: protocols.org documents the AI_AGENT_ID-scoped session-context path (=.ai/session-context.d/<id>.org=) and =.ai/scripts/session-context-path= resolves it. The singleton race Codex flagged is closed. What remains is the spec review plus a go/no-go on the broader runtime-neutral refactor: runtimes/ adapter manifests, generic install commands, language-bundle split, launcher refactor, local model service.
+
+** DONE [#C] Build Craig's writing voice profile from real corpora :spec:
+CLOSED: [2026-06-10 Wed]
 :PROPERTIES:
 :CREATED: [2026-05-29 Fri]
 :LAST_REVIEWED: 2026-05-29
 :END:
+Shipped across 2026-05-29 → 2026-06-10. =voice/references/voice-profile.org= is the canonical paired file: Phases 1-2 corpora measured (commit bodies 128k words + email/PR/review registers), all 45 patterns carry entries with basis and history, and every reconciliation delta landed in =voice/SKILL.md= (#13/#33 self-discipline reframing, #7 soft flag, new corpus-derived #43-#45). Extension corpora (Slack, long-form, syntactic fragment detection) deliberately not pursued.
 
 Build a grounded profile of Craig's actual writing voice by mining the corpora he's produced over time. The =voice/SKILL.md= patterns today are observation-derived (em-dash zero-tolerance, semicolon → period, contractions kept, sentence-fragment rewrite, felt-experience cut, etc.). Some are spot-on; others are intuition. A real corpus pass would tell us which patterns are genuinely Craig's voice and which were guesses, plus surface idioms, sentence structures, and vocabulary the current ruleset misses.