diff options
| -rw-r--r-- | docs/agent-knowledge-base-spec.org | 9 | ||||
| -rw-r--r-- | todo.org | 27 |
2 files changed, 21 insertions, 15 deletions
diff --git a/docs/agent-knowledge-base-spec.org b/docs/agent-knowledge-base-spec.org index cf69c35..78ff9bd 100644 --- a/docs/agent-knowledge-base-spec.org +++ b/docs/agent-knowledge-base-spec.org @@ -3,7 +3,7 @@ #+DATE: 2026-06-10 * Metadata -| Status | ready — Codex review incorporated; D7 keep, denylist =~/projects/work= only, D8 transport = git all ratified (Craig, 2026-06-10); implementation awaiting Craig's go | +| Status | implemented — v1 (Phases 0-4) shipped 2026-06-10 on Craig's go; manual validation + other-machine clones outstanding (todo.org) | | Owner | Craig Jennings | | Reviewer | Craig Jennings; Codex (2026-06-10) | | Related | [[file:../todo.org][todo.org — "Check that memories are sync'd across machines via git"]] | @@ -177,7 +177,7 @@ A new =claude-rules/knowledge-base.md= rule (auto-installs via the Makefile RULE * Implementation phases -Not started — Craig has explicitly held implementation pending his go-ahead. +All five phases shipped 2026-06-10 (Craig's go, no-approvals batch). Completion details per phase live under the parent task in todo.org; what remains is the manual-testing child and the other personal machines' one-time clone + timer setup. ** Phase 0 — Transport migration (D8) Resolve or delete the 63 =*.sync-conflict-*= files, move the directory out of the =~/sync/org= share to the new path, =git init= + =.gitignore= + initial commit + push to the cjennings.net remote, clone on the other personal machines (not the work machine), and set up the auto-sync timer. Update =roam-dir= in =org-roam-config.el= (handoff to the =.emacs.d= project) and sweep references to the old path (the =protocols.org= task-list pointer at =~/sync/org/roam/inbox.org=, among others) per the keep-links-current rule; a transition symlink at the old location covers stragglers. Verify: Syncthing no longer tracks the tree, org-roam indexes the new location, and an edit round-trips between two machines via the timer. @@ -300,6 +300,11 @@ Modified recommendations from the 2026-06-10 Codex review, with reasons. Everyth - Why: the original verification proved mechanism but not success; migration and maintenance were unspecified; and Syncthing's no-history / no-gate / conflict-fork costs were the design's weakest accepted risks — git removes them for the price of a one-time migration. The phone constraint that might have blocked Shape A dissolved: Craig's mobile pattern is on-demand doc drops, not whole-roam sync. - Artifacts: this file; todo.org phase tasks updated (Phase 0, 1.5, and 4 added). Implementation remains held pending Craig's go. +** 2026-06-10 Wed @ 18:21:33 -0500 — Claude (rulesets, no-approvals batch) — v1 implemented +- What: all five phases shipped on Craig's go. Phase 0: roam migrated to =~/org/roam= as a git repo (roam.git on cjennings.net), 63 conflict files resolved by deletion (tarball backup kept), transition symlink at the old path, Emacs constants updated live, roam-sync timer running, old-path references swept. Phase 1: =knowledge-base.md= written and linked machine-wide. Phase 1.5: rulesets memories swept (3 promoted, 2 rule-encoded kept local, 1 de-staled); sweep handoff broadcast to the 10 other memory-bearing personal projects. Phase 2: the seed/doc node written and verified indexed (420 nodes). Phase 3: wrap-up promotion check + the =KB:= receipt line. Phase 4: =kb-hygiene.sh= + monthly timer, live-run verified. +- Why: spec status was ready with all decisions ratified; Craig authorized the full batch. +- Artifacts: rulesets commits fcf554a, d071f1f, 242b95e, b014095 (+ todo.org/spec bookkeeping); roam.git initial history; handoffs to .emacs.d, archsetup, and the 10 sweep targets. Outstanding: the manual-testing checklist and other-machine clones. + ** 2026-06-10 Wed @ 17:31:10 -0500 — Codex — reviewer - What changed or was recommended: re-ran the spec-review workflow after the caveat resolution. Rubric: ready. No new blocking or medium-priority findings; no review file written. Confirmed the implementation phases and test-surface tasks are already represented under the existing parent task in todo.org. - Why: the prior blockers are dispositioned, the work-root denylist is confirmed, the pointer-rule install path matches the current Makefile RULES glob, and v1's manual/agent-runnable verification surface is explicit. @@ -50,10 +50,11 @@ Add a SessionStart hook (matcher: clear) in settings.json that auto-injects "rea The checkpoint+resume halves already shipped as /flush. This is the remaining automation piece. Out of a work-project handoff 2026-06-09 (process tooling, belongs in rulesets not the work project). -** TODO [#C] Check that memories are sync'd across machines via git :spec: +** DOING [#C] Check that memories are sync'd across machines via git :spec: :PROPERTIES: :LAST_REVIEWED: 2026-06-10 :END: +v1 implemented end-to-end 2026-06-10 (Phases 0-4 below, no-approvals batch). Remaining before DONE: the manual testing and validation child, plus the other personal machines' one-time clone + timer setup (archsetup handoff). *** 2026-05-14 Thu @ 19:14:11 -0500 Investigate current memory storage Memory files live at @@ -112,20 +113,20 @@ Craig confirmed (2026-06-10, in chat): the denylist is just =~/projects/work=. A *** 2026-06-10 Wed @ 17:57:08 -0500 Spec amended — D8 git transport + migration/metrics/docs/maintenance folds Craig's five design questions answered and folded into the spec, and D8 ratified (Shape A): the KB moves out of the =~/sync/org= Syncthing share into its own git repo on cjennings.net, with an =agents/= subdirectory for agent writes, a systemd auto-sync timer for Craig's edits, opt-in-by-clone replication (work machine doesn't clone), and the phone staying on the on-demand =~/sync/phone= pattern. Folded in: inclusion criteria + a Phase 1.5 guided memory sweep, a Success metrics section with a 30-day checkpoint, the seed node redefined as the KB's own documentation, and Phase 4 maintenance automation. Phases renumbered 0-4; tasks below updated. Implementation still held. -*** TODO Agent KB Phase 0 — transport migration to git :feature: -Clean the 63 sync-conflict files, move roam out of the =~/sync/org= share to the new path (proposed =~/org/roam=), git init + cjennings.net remote + clones on personal machines (not work), systemd auto-sync timer, =roam-dir= update (handoff to the .emacs.d project), link sweep for the old path (the protocols.org task-list pointer among others) + a transition symlink. Verify: Syncthing no longer tracks it; an edit round-trips between machines via the timer. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 0 / D8). +*** 2026-06-10 Wed @ 18:21:33 -0500 Phase 0 done — roam migrated to git +Backed up (~/roam-backup-2026-06-10.tar.gz), copied to =~/org/roam=, 63 conflict files deleted (424 org files), git repo with origin =git@cjennings.net:roam.git= (initial commit 515693d), old location replaced with a transition symlink. Emacs =roam-dir= updated in user-constants.el + live-reloaded (db rebuilt, 416 nodes); handoff to .emacs.d for the commit. =roam-sync.sh= (6 bats green) on a 15-min systemd user timer, installed + enabled + round-trip verified. Old-path references repointed (protocols task-list pointer, journal workflow, notes template). archsetup handoff covers dotfiles adoption + other-machine clones. rulesets commit fcf554a. -*** TODO Agent KB Phase 1 — pointer rule :feature: -Write =claude-rules/knowledge-base.md=: the KB path (post-migration), canonical query commands, the D4 write schema with the =agents/= subdirectory, the pull-before-query / commit+push-after-write discipline, the inclusion criteria (what goes in / stays out), the classification denylist + write routing, the refusal contract, and the D5/D6 boundary. The existing Makefile RULES glob installs it — no Makefile change. Denylist confirmed 2026-06-10 (=~/projects/work= only). Follows Phase 0. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 1). +*** 2026-06-10 Wed @ 18:21:33 -0500 Phase 1 done — knowledge-base.md rule live +=claude-rules/knowledge-base.md= written (path, git discipline, query commands, agents/ write schema, denylist + refusal contract, inclusion criteria, capture-then-promote). =make install= linked it machine-wide; verified the link, a known-note query, and conflict-glob exclusion with a planted file. Commit d071f1f. -*** TODO Agent KB Phase 1.5 — guided memory migration sweep :feature: -One-time per project: read the project's harness-memory dir, classify each fact against the inclusion criteria (KB-worthy / stays local / stale-delete), propose the batch for Craig's approval, write approved facts as =agents/= nodes. =reference=-type and durable =feedback=-type memories are the natural candidates; most =project=-type entries stay local. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 1.5). +*** 2026-06-10 Wed @ 18:21:33 -0500 Phase 1.5 done — rulesets swept, 10 projects broadcast +Rulesets' 6 memories classified: 3 promoted as =agents/= nodes (notify-attention pattern, pdftools venv, gpg-agent SSH TTL trap), 2 kept local (rule-encoded in verification.md / interaction.md), 1 kept + de-staled (ai-scripts-canonical updated for the claude-templates subtree fold). Sweep handoff broadcast to the 10 other memory-bearing projects (archsetup, org-drill, pearl, .emacs.d, elibrary, finances, health, home, jr-estate, kit); work skipped by the boundary; the orphaned =linear-emacs= memory dir (project retired, likely pearl's predecessor) noted for Craig. -*** TODO Agent KB Phase 2 — seed node + index verification :feature: -The seed node doubles as the KB's user-facing documentation: a "How the agent knowledge base works" node (what agents write, the =:agent:= tag, the inventory command, what Craig can prune). Write it per the schema under =agents/=; Craig confirms it indexes and displays (autosync is on, no manual sync step). Rollback on schema failure: delete or revert the one node. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 2). +*** 2026-06-10 Wed @ 18:21:33 -0500 Phase 2 done — seed/doc node written and indexed +=agents/20260610181640-how-the-agent-knowledge-base-works.org= written: the KB's user-facing guide (what agents do, how it syncs, finding/pruning agent content, the rule pointer). Index verified programmatically: =org-roam-node-from-title-or-alias= resolves it with tags (agent reference); node count 416 → 420. Craig's visual check remains in the manual-testing child. -*** TODO Agent KB Phase 3 — promotion cadence + usage instrumentation :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=. Wrap-up also records one line in the session summary — "KB: promoted N / consulted yes-no" — the input to the spec's 30-day Success-metrics checkpoint. Verifiable via workflow-integrity + lint. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 3). +*** 2026-06-10 Wed @ 18:21:33 -0500 Phase 3 done — wrap-up promotes + records the KB receipt +wrap-it-up.org Step 1 gains the promotion check (inclusion-criteria bar) and the mandatory "KB: promoted N / consulted yes-no" Summary line; validation checklist enforces it. Mirror synced, integrity OK (44), parse OK. Commit 242b95e. *** 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 0-2 land. @@ -135,8 +136,8 @@ What we're verifying: the v1 acceptance surface that needs Craig's eyes or a liv - After Phase 0: an edit made on one machine appears on another within the auto-sync timer interval, no new sync-conflict files appear, and the work machine has no KB clone. Expected: all four behave per the spec; 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 0-2.) -*** TODO [#D] Agent KB Phase 4 — monthly hygiene automation :feature: -Promoted from vNext to Phase 4 in the 2026-06-10 amendment: a monthly agent-run hygiene pass — =:agent:= inventory, orphan/duplicate detection, node-count trend — reported to the rulesets inbox with deletions proposed for approval (auto-cleanup only for =:agent:=-tagged nodes). 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. Spec: [[file:docs/agent-knowledge-base-spec.org][agent-knowledge-base-spec.org]] (Phase 4). +*** 2026-06-10 Wed @ 18:21:33 -0500 Phase 4 done — monthly hygiene automation live +=scripts/kb-hygiene.sh= (6 bats green, shellcheck clean, read-only by design) inventories =:agent:= nodes, flags orphans / duplicate titles / conflict files, and writes an org report into the rulesets inbox; =roam-hygiene.timer= (monthly, Persistent) installed + enabled. Live run against the real KB verified (4 agent nodes, 428 files, 0 conflicts). Conditional vNext stays 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. Commit b014095. ** TODO [#C] Build =create-documentation= skill for high-quality project/product docs :feature: :PROPERTIES: |