Maven/docs/roadmap.md

# Roadmap: the order the spec gets built in

*Last verified: 2026-08-15 @ 231248a*

`docs/spec.md` says what every capability is for and what done means.
This file says which order they land in, and why that order and not another.
`CLAUDE.md` carries the rules.

## The ordering rule

The audit ruled out a roadmap ordered by code work
(`docs/evals/2026-08-13-capability-audit.md`). None of the four broken
capabilities is a code defect. Weather has no configuration block. Nexus has no
data. The voice reach has no listener. Step-up has no WebAuthn credential.

So the order is by what would make her untrustworthy if it shipped later. A
capability she does badly costs more than one she does not have. From the outside
he cannot tell the difference. Honesty comes before reach, and reach comes before
breadth.

Two rules bind every milestone.

**A milestone closes its own documentation gaps.** The spec found seventeen
capabilities with no living doc. Those are not a milestone of their own. A
capability does not ship out of a milestone until the doc its spec entry points
at exists.

**A milestone writes its own scenarios.** Only five scenario files exist and 46
spec entries name one to write. The scenarios a milestone's DoD items cite are
part of that milestone.

## Honesty, in three milestones

She currently claims things that are not true. That is worse than a gap, because
a gap is visible and a false claim is not. Nothing else is worth building on top
of a turn that lies.

That is one theme and three separate jobs. M1 is the turn path. M2 is the memory
he cannot correct. M3 is a configuration job that is not honesty at all. They are
split because each is one session, and because M1 and M2 touch different code
with different docs owed.

None of the three touches voice. A dishonest turn spoken aloud is still
dishonest.

## M1: The turn does not lie

Every item is on the path from utterance to reply, and each is a false statement
rather than a missing one.

Lands: Route an utterance. Speak as herself. Answer from the world.

Gate:

- A question about what Maven remembers routes to query. Both audit probes pass.
- No masculine self-reference reaches the wire, checked on the outbound path and
  not only in the eval.
- A world answer that would invent content is refused instead of phrased. The
  audit's "почему небо голубое?" answer is the failing case.

Docs this milestone owes: none new. `docs/routing.md`, `docs/language.md` and
`docs/world.md` all exist and are corrected in place.

## M2: Memory he can correct

The store is the other place she claims something untrue, and the only place he
cannot fix it himself. It is separate from M1 because it is store and surface
work, and because it owes the largest doc in the spec.

Lands: Facts. Notes.

Gate:

- No confirmation claims a write that did not happen. The audit's "я записала
  информацию о тебе" wrote nothing.
- A note can be deleted by voice and from the web UI (V-494).
- A question is not stored as a statement.
- A superseding fact retires the old value and both are readable.

Docs this milestone owes: the memory doc covering facts, notes, the supersede
rule and the digestion worker's consolidation pass. It is the largest gap in the
spec, and it is why this is its own milestone.

## M3: Step-up is not fail-open

One bounded configuration-and-code job. It is not honesty and it does not belong
inside M1. It is the audit's only high-severity item and it gates the act path,
so it lands before anything reaches Hexis.

Lands: Passkey and step-up.

Gate:

- WebAuthn is configured and no step-up gate is fail-open, including
  `POST /api/chat` (V-683).
- Enrollment requires an existing credential once the first one exists. Anyone
  past the proxy can enroll today.
- Step-up is per-request, not process-global.

## M4: The four broken, none of them code

Cheap, and it unblocks two later milestones. Nexus with entities is what makes
the act path real. Weather is the capability he asked about first on the audit
day.

Lands: Weather. Nexus. Hexis. The deployed stack.

Gate:

- A `weather` block names a provider and a home city. The follow-up city parks
  as a clarify instead of dying with "Я тебя не разобрала".
- Nexus has entities, so free text resolves to a canonical entity id.
- One act runs through Hexis against a real target, with confirmation binding
  capability id, target, arguments, requester and expiry.
- All five compose services run the current build. Three were four days stale
  during the audit.

Not here: smart home and bluetooth. Both are blocked on the host, not on Nexus.

## M5: Voice is the spine

v1 is a voice assistant. Until a proactive message can reach him by speech, she
is a web app he can talk at. He reaches her by speaking, which is a pull. She has
no push.

Lands: Voice reach. Wake word to session. Hearing. Text to speech. Speech to text.

Gate:

- A proactive message reaches him by speech without him speaking first. Every
  proactive message during the audit fell through with "no live voice session".
- Waking her opens a session the proactive path can push into (V-515).
- A capture client runs on workpc and streams end to end from microphone to
  reply (V-514).
- `internal/ttsnorm` expands times and dates into `Europe/Samara` phrasing.
- The `mavsttd` floor arm is exercised on its own, not only behind the workstation.

The voice port stays on homesrv loopback and reaches workpc over ssh. This
milestone does not LAN-bind it.

Docs this milestone owes: what holds a live voice session open. `docs/protocol.md`
documents the wire and nothing documents the listener.

## M6: Proactive that arrives

Everything in this milestone exists and fails at the last step. The morning
routine builds a plan and drops it. Reminders fire and one reach failure loops.
Recurring is storage and delivery with no caller.

Lands: Reminders, including recurring. Morning routine. Interruption policy.
Digest of held nudges. Tasks. RSS and news.

Gate:

- A recurring reminder is set by voice and states its schedule back: meetings,
  pills, the dog, the vet, the kibble. `store.Reminder` carries `Cron` and no
  caller in `cmd/mavend` passes one.
- The morning plan reaches him inside its 08:00-11:00 window `Europe/Samara`, and
  falls back to the non-voice reaches when no voice session exists (V-280).
- The four presence-and-severity outcomes are written down before any of them
  changes (V-281).
- A failed delivery retries into another reach rather than once a minute until 03:05.
- One suppressed nudge is watched surfacing in a later digest, on the box (V-687).

Docs this milestone owes: the reminder lifecycle. Parking, firing, delivery,
retry and cancellation span three packages with no written contract.

## M7: Breadth she can already almost do

These have code and no path from an utterance. Each is one wiring job, not a
design job. They come after the spine because none of them changes whether she is
trustworthy or reachable.

Lands: Read an encyclopedia. Recall. See an image. Network scans. MCPs. Routine
proposals. Memory evaluation.

Gate:

- A Russian question lands on the Russian book, an English one on the English book.
- `TestONNXPersonalBoundary` is green and a recall miss says she does not remember.
- An image sent through Telegram gets a Russian description, and the vision call
  falls back silently when the workstation is down (V-667).
- A scan of the configured subnets is read back as prose.
- A configured MCP server's tools are callable through the act path, and only
  through the allowlist.
- The routine proposer's hand-written Russian verb list is replaced by
  `internal/lexicon` or the embedder (V-606).
- One memory evaluation run is observed and its notes read back (V-248).

## M8: The product decision, then the deploy

Email and calendar are built and neither is in `docker-compose.yml`.
`internal/email` with `mavmaild`, `internal/calendar` with `mavcaldav`. Deploying
either before deciding what she does with his mail writes the decision by
accident. That is why they sit behind a milestone boundary rather than inside M7.

Lands: Email triage. Calendar management.

Gate:

- The owner has decided what triage means: read-only summary, task extraction, or
  reply drafting.
- Mail-derived candidates stay candidates until he accepts one (V-130).
- An event is created by voice with the slot asked for rather than guessed, times
  in `Europe/Samara`.
- Both daemons are in compose, or their absence is deliberate and recorded.

## M9: Design pass, then the undesigned seven

Seven v1 capabilities have no design. They keep a DoD in the spec so the gap
stays visible, and each needs a design pass before any code. Every one of them
assumes a turn that is honest, reachable and proactive. Each gets cheaper once M1
through M6 have landed, which is why they come last.

Lands: Web crawling. Summaries. Webhooks. Cron jobs. Desk notifications, outbound
half. Learning the style. Learning from mistakes. Command chaining.

Two decisions this milestone opens with:

- **Cron jobs against routines against recurring reminders.** Three schedulers
  must not exist. `internal/routine` already carries a `Cron`, and M6 gives
  reminders one. What "cron jobs" adds beyond those two is undecided.
- **Which direction webhooks means.** The only webhook in the tree is Telegram's
  own inbound intake. Inbound as an event source and outbound as a fourth reach
  are different capabilities.

Learning means behavioral, not weights. Stored outcomes: dismissed nudges,
corrected phrasings, repaired routes. No adapter, no training set. Everything
learned is readable on a page and deletable.

## Deferred past v1

Owner's call, 2026-08-15. Four are audit rows the v1 list did not name.
Bluetooth control was on that list and comes off it. No bluez exists on the box
and the radio has no owner. Their spec entries stay, so the DoD is already
written when one comes back.

| capability | why deferred |
| --- | --- |
| Speaker recognition | Nothing depends on it until someone other than him speaks to her (V-255). |
| Smart home | Blocked on the host, not on code (V-256). |
| Bluetooth control | No bluez on the box (V-257). |
| Model swap | The resident model being whatever the config says is an acceptable answer (V-250). |
| Self-update | `mavupdate` cannot reach the containerized socket, and a manual deploy works (V-477). |

## What is not filed

Vikunja returned 503 across two sessions, so the following have no task id.
Filing them is the first thing to do when it comes back.

- The capability audit itself. It is headed "unfiled".
- The remember-versus-query misroute. Two of seven audit probes.
- The masculine reply on the wire, caught live while the eval passed.
- Recurring reminders having no caller.
- The seventeen capabilities with no living doc.
- The 46 scenario files the spec names and does not have.