kami/Maven

Files

T

kami e0d0244fa9 Fold SPEC/maven/ROADMAP into DESIGN.md and drop the stale session logs

15 root markdown files, ~4,900 lines against ~33,000 lines of Go, with at least
three pairs contradicting each other. When five documents describe the
architecture, the code becomes the only trustworthy one — which defeats the
point of having them. That drift is why the resident-model question had four
incompatible answers.

SPEC.md, maven.md and ROADMAP.md are deduped into DESIGN.md rather than
concatenated, with a "Superseded" section carrying eight retired decisions and
what replaced each: classifier-owns-the-route (the cascade is still the live
path, but as a stopgap, not a design to extend), faster-whisper/vosk/silero,
the small-model phrasing claim, sqlcipher, the Kotlin/Spring sketches,
obsidian->chroma, script deployment, and FloorEnrollment. Superseded material
is kept and marked rather than deleted, so it cannot read as current.

SESSION-05/06-07-2026.md and PLANS.md are removed outright — git history holds
them, and both were verified tracked before deletion.

Go doc comments citing the deleted files are repointed to the equivalent
DESIGN.md sections. Several asserted designs that were already retired, so the
claims are corrected and not just relinked: stt.go named faster-whisper as
production (it is whisper.cpp), tts.go named silero (it is piper), intent.go
still described the classifier as owning the route, and stale vosk/chroma
vocabulary is replaced. ECOSYSTEM-SPEC.md references are deliberately
untouched — that is a different document, and a naive grep for SPEC.md matches
it.

Root markdown drops from 4,880 to ~3,700 lines. The review's ~1,500 target is
not reachable while keeping the files it also said to keep — those alone are
2,553 lines — so trimming further needs a separate decision on
MAVEN_ECOSYSTEM_ARCHITECTURE.md and PROGRESS.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X5JApcrCRVGmqrxnhynSik

2026-07-30 23:39:56 +04:00

7.7 KiB

Raw Blame History

maven — feature ranking

dated 2026-07-03. companion to DESIGN.md (folded from the former maven.md). ranks everything discussed post-repo-state against the infra blockers, not a replacement for the build order.

infra — blocks everything below, in order

sqlcipher at-rest — auth chapter (cold-start = layer-3, key-in-core-only) is fiction without it. plain sqlite on disk right now, anyone with disk access reads everything.
mavweb / mavcaldav tests — zero coverage. mavweb carries passkey HTTP flow + the tools-enable surface, i.e. the actual privilege-escalation gate. webauthn crypto is tested; the handlers wiring it up aren't.
systemd units — core/module isolation ("crash-independent, key-free modules") is currently a claim, not enforced. still scripts+tmux.
go.mod tidy — trivial, do whenever.

nothing feature-level below should land before 1–2 are done. 3–4 can interleave.

features, ranked

mandatory

things that block correctness or safety of stuff already shipped — not new capability, just closing gaps in existing design.

destructive-confirm policy — open question in DESIGN.md § open questions, blocks correx and any new tool domain from having a coherent risk tier
quiet-hours definition — open question, blocks proactive delivery being trustworthy
schema migrations — sqlcipher rollout alone forces a schema touch. want this mechanism before that, not after.

easy

cheap, no dependencies, no new invariants.

grocery / list_items table — fourth append-only shape (item, status, list-tag), no predicate touches it, multi-adder just works for free
go.mod tidy
capability model (deepseek) — homelab.docker.restart instead of flat tool→enabled. cheap now, expensive to retrofit once tools surface passes ~15 entries. time-sensitive, not urgent.
conversation repair — already free: DESIGN.md has "misroute correction = new centroid example," this is just naming the existing mechanism as a feature
command history — read-only query over existing facts, no new mechanism
clarification templates — canned phrasing for the router's existing confidence-gate fallback, phraser-lane only
pronunciation dictionary — tts config, no architecture

doable

real work, scope is clear, no new invariant needed — reuses proposed→enabled / gate / append-only patterns already pinned.

correx integration — mechanism already sketched (task queue → correx → diff/PR → gated merge, same authority tier as any module, zero key access). stalls on destructive-confirm policy + mavweb hardening first.
systemd units (infra, feature-adjacent)
passkey persistence past restart — bounded fix, matters more once cold-start unlock routes through the passkey-authed page (otherwise chicken/egg: box reboots locked, unlock needs passkey, passkey needs re-enroll)
confidence propagation — flagged independently by deepseek + chatgpt, never tiered until now. touches store schema (confidence riding along derived facts, not just source facts)
rule trace / explanation engine / presence debugger — one feature, not three. "why did/didn't you nudge me" over existing predicate evals. worth doing before mandatory rules multiply
recurring reminders — real gap, reminders only fire once right now. "trash every tuesday" isn't representable yet
stale-reminder burst collapse — NOT a recovery bug: recovery already works. DueReminders is status='pending' AND fire_ts <= now with no lower bound, and the gatherer calls it every tick (gather.go:139), so on the first boot tick every reminder that came due while the daemon was down is still pending and fires. The only real gap is cosmetic: a pile of stale reminders all firing at once on boot could spam. Doable-tier polish (collapse/digest the boot burst), not mandatory. (was mis-filed as "missed-reminder recovery, one-shot, nothing catches up" — that premise was wrong)
revert (was "undo") — not a new mechanism, just a wrapper: void the latest row instead of hard delete. append-only already supports it
notification batching / digest mode — layer over existing sev routing, morning/evening rollup instead of per-event
memory decay / duplicate / conflict detection — chroma-side hygiene, no predicate touches it, low-risk to add
backup/restore automation — spec already says "backup is cp," this just scripts it properly
import/export, config versioning — easy-adjacent, mostly plumbing
barge-in (interrupt tts) — audio-stack level UX gap, not architecture-level
most integrations (email, rss, github, media players, package/update monitoring, docker/k8s status) — just allowlist entries, capability-gated same as everything else. volume, not novelty
testing infra (state snapshots, fake clock, replay, regression suite for rules) — should slot in right after mavweb tests. unit-testable predicates are wasted without the harness
timeline viewer / performance metrics / admin dashboard — UI on top of data that already exists. doable once mavweb has tests, not before

epic

real forks of the project. need their own design pass, not a bolt-on.

multi-user / namespace (gf) — presence, delivery, nudges restraint memory all assume a single subject end to end. touching all three, not a tag column. waits on deepseek's multi-user approach review + sqlcipher (namespacing means nothing if disk read = everything).
self-update via correx — needs task-queue location decided (own db, isolated from core's key-holding store) and correx already stable before it's worth the authority jump.
event bus (deepseek) — facts stop being writes, become projections over immutable events. rewrite, not addition.
goal management (deepseek) — new long-lived object (Goal), new relations to reminders/notes/observations. genuinely new subsystem, not an extension of existing three.
dependency graph between facts/rules/goals — needs the goal object to exist first
plugin api — third-party capability-injection point, worse than a single tool gap. needs its own auth-tier conversation before it's even a candidate
speaker adaptation / wake-word personalization — depends on multi-user existing first, same per-subject problem
multi-device audio routing — same shape as multi-user: presence/delivery need to know which device, not just if present. new dimension.
hot-reloadable rules — mild tension with "rules as code, not a DSL." reload-without-redeploy touches core's minimalism principle, needs a real look, not a free yes
mobile offline mode — router/stt/tts assume homesrv reachable over wg. real offline means shipping a model subset onto the phone
wearable integration — new presence signal (weight/τ pair) + new delivery channel
location-aware automations — needs a location fact type that doesn't exist yet, and gps is a much bigger privacy jump than wg handshake

rejected

explicitly not doing these, noted so they don't get re-proposed later.

federated assistants — multiple maven instances talking over network is "phones home" with extra steps

open dependency notes

correx and multi-user both stall on destructive-confirm policy — worth pinning that one first since two epics share the block
capability model's "easy" rating has a shelf life — same shape as the sqlcipher-before-cold-start window: cheap today, not cheap forever
rule trace / explanation / presence debugger got proposed three times under three names across the source lists — same feature, collapse it
schema migrations moved from "doable" to "mandatory" — sqlcipher forces the first real migration, want the mechanism before that lands, not built ad hoc during it

7.7 KiB Raw Blame History Unescape Escape