mirror-mind 0.0.1 → 0.33.0

package/docs/releases/v0.29.3.md

@@ -0,0 +1,93 @@
+---
+digest: >
+  v0.29.3 is a maintenance patch that fixes Pi external-skill discovery on the
+  current ~/.mirror-minds home layout. The Pi logger extension hardcoded the
+  legacy ~/.mirror root and never loaded the per-workspace .env, so machines on
+  the new home silently discovered zero installed external skills. The fix
+  replicates the Python core's mirror-home resolution contract inside the
+  extension. The release also records the resulting Python/TypeScript resolution
+  duplication as accepted technical debt (TD-001) and hardens the Gemini smoke
+  test's production-DB guard so it protects the database the workspace actually
+  uses.
+---
+
+# v0.29.3 — Pi External-Skill Discovery Fix
+
+**Date:** 2026-07-04
+
+## Highlights
+
+- Fixes Pi external-skill discovery on the `~/.mirror-minds` home layout: the Pi logger extension now resolves the mirror home the same way the Python core does, instead of hardcoding the legacy `~/.mirror` root.
+- Replicates the core's resolution contract in the extension — shell env > `.env` (upward walk, same parse rules as `config.py`) > single-catalog auto-scan — preferring the new `~/.mirror-minds` home and falling back to legacy `~/.mirror` only when the new one is absent.
+- Returns null on ambiguity instead of guessing, so a multi-home machine requires an explicit `MIRROR_USER`/`MIRROR_HOME` rather than silently picking the wrong home.
+- Records the resulting Python/TypeScript resolution duplication as accepted, tracked technical debt (TD-001) with an explicit revisit trigger.
+- Hardens the Gemini smoke test's production-DB guard to resolve the DB path through the core so it protects the database the workspace actually uses, degrading to a no-op if resolution fails.
+
+## Where We Started
+
+`v0.29.2` closed the Ariad Builder flow refinement arc. Dogfooding on a machine
+using the current `~/.mirror-minds` home layout then surfaced a quiet but real
+regression: Pi reported **zero** installed external skills even when extensions
+were installed.
+
+The cause was a divergence between two implementations of one contract. The
+Python core resolves the mirror home through `resolve_mirror_home` — honoring
+shell environment, a per-workspace `.env`, `MIRROR_HOME`/`MIRROR_USER`, and the
+`~/.mirror-minds` default with legacy `~/.mirror` fallback. The Pi logger
+extension, written in TypeScript and unable to import `memory.config`, instead
+hardcoded the legacy `~/.mirror` root and never loaded the workspace `.env`. On
+`~/.mirror-minds` machines it read a non-existent catalog and, because runtime
+extensions are designed to fail quietly, exposed no external skills with no
+visible error.
+
+## What Changed
+
+The Pi logger extension now replicates the core's mirror-home resolution
+contract: shell environment first, then an upward `.env` walk using the same
+parse rules as `config.py`, then a single-catalog auto-scan. It prefers the new
+`~/.mirror-minds` home and falls back to legacy `~/.mirror` only when the new one
+is absent. On an ambiguous multi-home machine it returns null instead of
+guessing, forcing an explicit `MIRROR_USER`/`MIRROR_HOME` rather than picking the
+wrong home. The home-directory names are centralized as constants and
+`_resolveMemoryDir`'s fallback is aligned with `config.DEFAULT_MEMORY_DIR`.
+
+Because a Pi (TypeScript) extension cannot import the Python `memory.config`
+constants, the fix necessarily duplicates the resolution contract across two
+languages. That duplication is recorded as **TD-001** in the technical-debt
+ledger with an explicit revisit trigger: any change to the core's mirror-home
+resolution semantics (new precedence, a new `MIRROR_*` variable, or another
+home-directory rename), or the next time a non-Python runtime surface needs to
+resolve the home, should promote the resolution to a single source of truth
+rather than adding a third copy.
+
+The same mirror-home audit surfaced a parallel defect in the Gemini smoke test.
+Its production-DB guard hardcoded `~/.mirror/<user>/memory.db` to checksum the
+"real" production database before and after the smoke run. On `~/.mirror-minds`
+machines that path is a stale legacy database or absent, so the guard silently
+checksummed the wrong database — or nothing — leaving the in-use production
+database unprotected while reporting success. The guard now resolves the path
+through the core (`resolve_mirror_home` + `default_db_path_for_home`), runs before
+the `DB_PATH`/`MEMORY_ENV` exports, and degrades to a no-op if resolution fails.
+
+## Conscious Exclusions
+
+- This release does not consolidate the duplicated mirror-home resolution into a single cross-language source of truth. That is deliberately deferred and tracked as TD-001; this patch centralizes the contract on each side instead.
+- No new user-facing features ship in this release. It is a correctness and test-hardening maintenance patch.
+- Push, tag creation, stable promotion, and GitHub Release publication remain explicit release operations, not side effects of the fix.
+
+## What We Learned
+
+Fail-quietly runtime extensions trade visibility for session safety, and that
+trade has a cost: a home-resolution divergence can expose zero external skills
+for a long time with no signal. Duplicated contracts across languages are a
+standing drift risk — the right response here was to make the duplication
+correct and explicitly tracked, not to pretend it does not exist.
+
+## Next Horizon
+
+The tracked follow-up is TD-001: when the core's home-resolution semantics next
+change, or another non-Python runtime surface needs to resolve the home, promote
+the resolution to a single source of truth — a core-exposed resolved-home command
+or a language-neutral config the extension can call — rather than maintaining a
+third copy, and add a regression check asserting Node and Python agree for
+representative env/`.env` cases.

package/docs/releases/v0.30.0.md

@@ -0,0 +1,75 @@
+---
+digest: >
+  v0.30.0 is the first public Windows installer distribution release. It turns
+  the recently merged Inno Setup installer work into an official release surface:
+  the repository now builds a native Windows .exe from source, publishes it as a
+  CI artifact, and makes the release path ready for GitHub Release attachment.
+  New Windows users get a guided bootstrapper for Mirror Mind + Pi, while
+  existing installs continue to update through the runtime updater instead of
+  reinstalling the executable. The release also teaches the installer workflow to
+  run on version tags so future releases can produce a matching installer
+  artifact from the tagged source.
+---
+
+# v0.30.0 — Windows Installer Distribution
+
+**Date:** 2026-07-05
+
+## Highlights
+
+- Publishes the first official native Windows installer path for Mirror Mind + Pi.
+- Keeps installer source under `installer/` and generated `.exe` binaries outside the repository tree.
+- Adds release-tag CI support so the Windows Installer workflow runs for `v*` tags and can produce a tag-matched installer artifact.
+- Clarifies the distribution model: new Windows users download the `.exe` from GitHub Releases; existing users update Mirror through `uv run python -m memory runtime update`.
+- Preserves the installer as a bootstrapper with its own version in `installer/VERSION`, decoupled from the Mirror runtime version.
+
+## Where We Started
+
+The Windows installer had landed on `main`, but the user path was still unclear.
+A new Windows user arriving at the GitHub repository would not see a committed
+`.exe`, because generated binaries are intentionally excluded from the source
+tree. The installer existed as source and as a GitHub Actions artifact, which is
+acceptable for maintainers but confusing for public onboarding.
+
+That exposed the missing release boundary: the installer needed to become a
+published release asset, not just a CI artifact hidden under Actions.
+
+## What Changed
+
+This release makes the Windows installer distribution model explicit and
+release-backed. The repository continues to version the installer source,
+including `installer/mirror.iss`, PowerShell bootstrap/configure scripts, the
+launcher, tests, assets, and documentation. The compiled `.exe` remains a build
+artifact, not a committed file.
+
+The Windows Installer workflow now also runs on version tags. That means a
+promoted release can produce an installer artifact from the exact tagged source,
+which can then be attached to the matching GitHub Release. This keeps the public
+asset aligned with the release tag rather than with an arbitrary branch run.
+
+For users, the intended path is now simple: go to the GitHub Releases page,
+download `MirrorMind-Setup-<installer-version>.exe`, run it, provide a Mirror
+user name and OpenRouter key, then open Mirror Mind and run `/login` in Pi for
+the chat-model subscription. For existing users, the `.exe` is not the update
+mechanism; the runtime updater remains the path for Mirror updates.
+
+## Conscious Exclusions
+
+- The installer `.exe` is still not committed to the repository tree. Generated binaries belong to CI artifacts and GitHub Releases.
+- This release does not code-sign the Windows installer. SmartScreen warnings remain expected until signing is added.
+- The installer version remains decoupled from the Mirror runtime version. `installer/VERSION` changes only when the installer itself changes.
+- Existing Windows users do not need to reinstall for ordinary Mirror runtime updates.
+
+## What We Learned
+
+A working installer is not the same thing as a distributable installer. Source,
+CI artifact, release asset, and user-facing download link are four different
+surfaces. The public onboarding path only becomes coherent when the generated
+binary is attached to a release users can actually find.
+
+## Next Horizon
+
+The next refinement is to make release publication smoother: keep generating the
+installer from the tagged source, attach it to every relevant GitHub Release, and
+later add code signing so Windows trust prompts match the intended public
+onboarding experience.

package/docs/releases/v0.30.1.md

@@ -0,0 +1,93 @@
+---
+digest: >
+  v0.30.1 contains all user-scoped runtime state inside the resolved mirror
+  home. Development and test environments no longer write databases to the
+  homes root (~/.mirror-minds), unconfigured runs fail with an actionable
+  one-line hint instead of silently creating root databases, extension
+  dispatch resolves the same environment-aware database as the core, the Pi
+  mirror-logger writes its log inside the mirror home, and runtime diagnose
+  reports legacy root artifacts with a documented manual relocation route.
+---
+
+# v0.30.1 — Runtime State Home Containment
+
+**Date:** 2026-07-12
+
+## Highlights
+
+- The runtime directory is the resolved mirror home for **every**
+  `MEMORY_ENV`; the environment selects only the database name
+  (`memory.db`, `memory_dev.db`, `memory_test.db`).
+- Unconfigured resolution fails loudly: a one-line actionable hint
+  (`Mirror home is not configured. Set MIRROR_HOME or MIRROR_USER…`),
+  exit code 2, no traceback, and no silent homes-root writes.
+- Extension dispatch and the core share one `(mirror home, environment) →
+  database` mapping (`db_path_for_home`), so a single session can no longer
+  straddle two database files.
+- The Pi mirror-logger writes to `<mirror home>/mirror-logger.log`; the
+  homes root remains only as the bootstrap error channel when no mirror
+  home is resolvable.
+- `runtime diagnose` reports `legacy_root_runtime_state` findings for
+  databases, logs, locks, and backups sitting directly in the homes root,
+  with a manual relocation route documented in REFERENCE.
+
+## Where We Started
+
+A field investigation during a `mirror`-journey session found the homes root
+(`~/.mirror-minds`) accumulating live runtime state alongside the per-user
+mirror homes: an orphan production `memory.db` holding 190 conversations
+bulk-imported in a 22-second burst with no resolvable mirror home, a live
+root `memory_dev.db` carrying the framework repository's own development
+sessions, the Pi `mirror-logger.log`, bootstrap locks, and a `backups/`
+directory.
+
+The root cause was pre-CV4 flat-layout semantics that survived inside
+`config.py`: the mirror home was honored only in production, so development
+and test environments — and any run with an unresolvable home — silently
+targeted the homes root. The same split let extension state and session
+registration land in two different databases, which had caused a
+wrong-session export earlier the same day.
+
+## What Changed
+
+`config.py` now separates the two axes it had entangled. The runtime
+directory always resolves to the mirror home; `MEMORY_ENV` picks only the
+database name. Explicit `MEMORY_PROD_DIR`, `MEMORY_DIR`, and `DB_PATH`
+overrides keep winning and are never second-guessed. When nothing is
+configured, database-touching commands raise
+`MirrorHomeNotConfiguredError` — surfaced by the CLI as a single actionable
+line with exit code 2 — instead of materializing databases in the root.
+
+Extension dispatch (`memory ext`) opens the database through the shared
+`db_path_for_home` mapping. The Pi logger resolves its log destination with
+the same precedence as data routing (`MEMORY_DIR` > resolved mirror home >
+homes-root bootstrap fallback), reusing the resolution machinery introduced
+in v0.29.3 rather than adding a third copy (TD-001 scope note recorded).
+`runtime diagnose` gains detection for legacy root artifacts, and REFERENCE
+documents the manual relocation route.
+
+## Conscious Exclusions
+
+- **No automatic migration.** Existing root databases are detected and
+  reported, never moved or merged automatically — diverged histories require
+  a human decision. An assisted relocation command is a candidate follow-up.
+- **`EXPORT_DIR` homes-root fallback** is unchanged (no root artifact
+  observed in the wild); recorded in the story's refactoring notes.
+- **No automated tests for the Pi extension's TypeScript path resolution** —
+  the Pi extension has no test harness; the behavior was validated manually.
+  The duplicated resolution contract remains tracked as TD-001.
+
+## Lessons
+
+The leak survived because failure was silent: development and test writes
+"worked", just in the wrong place, for months. The loud-failure rule would
+have surfaced the orphan production database the day it was created.
+Stabilization principles apply to configuration resolution, not only to
+provider errors — silence, not the wrong path, was the root defect.
+
+## Next Horizon
+
+CV9.E2 continues with embedding resilience (S1) and external extension
+runtime surface parity (S2); CV9.DS7 conversation metadata lifecycle still
+has apply behavior open; Boundary Hardening (CV9.E1) remains ahead of the
+full CV9 done condition.

package/docs/releases/v0.30.2.md

@@ -0,0 +1,66 @@
+---
+digest: >
+  v0.30.2 gives Mirror's runtime git operations a timeout appropriate to
+  what they actually do. Every git subprocess previously shared one
+  2-second timeout, which is correct for local inspections but too short
+  for network operations: during the v0.30.1 promotion, release-promote
+  --push reported failure while the tag push had actually landed on the
+  remote, forcing a manual recovery. Local commands keep the 2-second
+  default; push and fetch call sites now use a 120-second network timeout,
+  with a test asserting the network timeout stays meaningfully larger than
+  the local one.
+---
+
+# v0.30.2 — Network-Appropriate Git Timeouts
+
+**Date:** 2026-07-13
+
+## Highlights
+
+- `_run_git` no longer serves every git subprocess with a single
+  2-second timeout.
+- Local inspection call sites (`status`, `rev-parse`, `branch`, and
+  similar) keep the 2-second default.
+- Network call sites — `_git_push_ref`, `_git_fetch`, and the
+  release-notes fetch path — now use a 120-second timeout.
+- Six focused tests pin the behavior, including a guard that keeps the
+  network timeout meaningfully larger than the local one.
+
+## Where We Started
+
+During the v0.30.1 promotion, `release-promote --push` reported failure
+even though the tag push had actually landed on the remote. The runtime's
+git helper served every subprocess call — local inspections and network
+operations alike — with the same 2-second timeout. That budget is
+reasonable for `git status` or `git rev-parse` on a local repository, but
+it is not reasonable for `git push` or `git fetch` over the network, where
+latency and remote-side processing can easily exceed a couple of seconds.
+The mismatch turned a successful push into a false failure, forcing a
+manual recovery step during an otherwise clean release.
+
+## What Changed
+
+`_run_git` call sites were split along one axis: local versus network.
+Local inspection commands keep the existing 2-second timeout, since
+correctness there depends on staying fast and responsive. Push (`_git_push_ref`)
+and fetch (`_git_fetch`), along with the release-notes fetch path, now pass
+an explicit 120-second network timeout. Six tests in
+`tests/unit/memory/cli/test_runtime_git_timeout.py` pin this split,
+including a guard test that fails if the network timeout is ever
+tightened to be close to or smaller than the local timeout, preventing an
+accidental regression back to the original bug.
+
+## Conscious Exclusions
+
+- No retry or backoff logic was added for network git operations — this
+  release only corrects the timeout budget, not resilience against
+  transient network failures.
+- No change was made to how failures are reported downstream; a genuine
+  timeout still surfaces as a failure, now simply after a budget that
+  matches the operation's real network cost.
+
+## Next Horizon
+
+CV9 continues toward its done condition; this patch closes out the
+release-promote reliability gap surfaced during the v0.30.1 promotion
+without expanding scope beyond the timeout fix itself.

package/docs/releases/v0.31.0.md

@@ -0,0 +1,122 @@
+---
+digest: >
+  v0.31.0 delivers the CV9.E2 Stabilization & Robustness epic: the memory
+  pipeline now fails safely and observably instead of corrupting state or
+  losing memories silently. One poison-pill conversation can no longer halt
+  all pending extraction; search degrades to lexical-only when embeddings
+  are unavailable; extraction is idempotent across partial failure; and
+  every model-in-the-loop surface that embeds untrusted transcript content
+  — extraction, scene synthesis, shadow, consolidation, and conversation
+  titles/tags/summaries — is now fenced against content-mediated prompt
+  injection. It also lands the model-in-the-loop reliability backlog from
+  the AI Engineering Audit: explicit call timeouts, model-pin overrides
+  with a reachability probe, metadata-default cost observability, and an
+  `eval --all` release gate with a model-upgrade playbook. CV9.E2.S2
+  (external extension runtime surface) is deferred to a later increment.
+---
+
+# v0.31.0 — Stabilization & Robustness
+
+**Date:** 2026-07-23
+
+## Highlights
+
+- **Extraction survives failure.** A failing conversation (provider outage,
+  oversized or poison-pill transcript, auth error) is isolated and
+  quarantined instead of crashing the batch and starving every conversation
+  queued behind it. Extraction is idempotent across partial failure — a
+  retry re-spends nothing and duplicates no rows.
+- **Search degrades, it does not break.** When embeddings are unavailable
+  (no key, provider down), search falls back to lexical-only ranking rather
+  than returning nothing or recency noise. Every LLM and embedding call is
+  now bounded by an explicit timeout.
+- **Untrusted content is fenced everywhere it enters a prompt.** The
+  transcript is data, not instructions — enforced across extraction, scene
+  synthesis, shadow observations, consolidation, and conversation
+  title/tags/summary generation, each with an adversarial eval probe.
+  Model-chosen identity writes are constrained by a target-layer allowlist.
+- **The mirror can now account for itself.** LLM calls record
+  role/model/tokens/latency/estimated cost by default (metadata only, never
+  bodies unless opted in); embedding calls and provenance are logged; a
+  spend summary and consult ledger make cost visible.
+- **Behavior is now gated, not hoped.** An `eval --all` runner plus a
+  model-upgrade playbook make a prompt or model-pin change a checked
+  migration: no green run (or recorded waiver) means no release.
+- **Reliability details:** reinforcement reinforces only on genuine context
+  loads (not internal machinery); the search access-count N+1 is collapsed
+  to one batched query; a retrieval-relevance instrument measures whether
+  the ranker surfaces the right memories; model pins accept env overrides
+  with a `runtime diagnose` reachability probe.
+
+## Where We Started
+
+Mirror Mind already worked across its runtimes, but its behavior at the
+edges was undefined. A single conversation that reliably failed extraction
+could halt all pending extraction *forever*, silently, burning an LLM call
+every session start. Search had no offline story. Nothing bounded an LLM
+call's latency. The transcript — user- and third-party-controlled content —
+flowed into extraction, scene, shadow, consolidation, and title/tags/summary
+prompts unfenced, so an embedded instruction could steer what the mirror
+stored or displayed. And the system recorded almost nothing about what it
+did or what it cost, which is at odds with the project's own "evidence over
+vibes" posture. The [AI Engineering Audit](../project/ai-engineering-audit.md)
+named these as the model-in-the-loop reliability gap: the capability
+discipline had outrun the reliability discipline.
+
+## What Changed
+
+This release closes the bulk of **CV9.E2 — Stabilization & Robustness**, the
+operational-hardening epic, together with the audit's P0 tier and most of
+its P1/P2 findings:
+
+- **Failure isolation & idempotency (AI-01, AI-02, AI-03):** explicit
+  per-role call timeouts; per-conversation isolation with attempt-counting
+  and quarantine; staged embeddings so partial failure persists nothing.
+- **Safe degradation & signal integrity (AI-04, AI-12):** lexical-only
+  search fallback; reinforcement that fires only on genuine context loads.
+- **Boundary hardening & injection defense (AI-15, AI-16, AI-22, AI-23,
+  AI-25, D-009):** value validation and caps on extracted memories;
+  transcript fencing across all five model surfaces; a target-layer
+  allowlist on identity writes; reported-speech recognition in the
+  injection-resistance judge.
+- **Observability & cost (AI-07, AI-09, AI-10, AI-13, AI-14):** metadata-
+  default LLM-call logging with a single cost authority; embedding
+  provenance and call logging; extraction-status legibility; an N+1
+  collapse; a deterministic retrieval-relevance instrument.
+- **The eval gate (AI-11):** persisted eval runs with trend, adversarial
+  probes for every model surface, and an `eval --all` runner wired as a
+  release gate with a model-upgrade playbook.
+- **Product & tooling:** the 1.0 intelligence-flag posture is decided and
+  documented (AI-20); Ariad Builder reads Delivery-Story-grammar roadmaps
+  (CV20.DS13); and extension install/uninstall is env-aware and guarded
+  against symlink and catalog-truncation defects.
+
+The journey-and-≥4-messages extraction precondition (AI-21) is now
+documented as intended product behavior — a deliberate noise filter and
+data-minimization boundary — rather than invisible behavior.
+
+## Conscious Exclusions
+
+- **CV9.E2 is substantially, not fully, complete.** `CV9.E2.S2` (external
+  extension runtime surface parity) remains open and is deferred to a later
+  increment; this MINOR release marks the epic milestone, not its final
+  story.
+- **Model-behavior release gate — waiver recorded.** `prompts.py` changed in
+  this release, so `eval --all` was run on the release candidate: **11/12
+  evals pass**. The single failure is `routing`, which is the known,
+  documented **D-005** debt (stale persona fixtures in `evals/routing.py`),
+  unrelated to any behavior shipped here — every prompt-touching surface
+  (extraction, scene, shadow, consolidation, title/tags, summary) passes its
+  threshold. The gate is satisfied by conscious waiver, per the development
+  guide's model-behavior release rule.
+- **1.0 intelligence-flag posture holds:** two-pass and LLM summarization
+  stay off by default; reception stays on. This release does not change that
+  posture (AI-20).
+
+## Next Horizon
+
+CV9 continues toward its Mirror Mind 1.0 done condition — the remaining
+stabilization work including CV9.E2.S2, boundary hardening, and the
+conversation-metadata lifecycle apply path. In parallel, the CV22 TypeScript
+core port proceeds behind the database seam, inheriting each of these fixes
+on its next merge from `main`.

package/docs/releases/v0.31.1.md

@@ -0,0 +1,142 @@
+---
+digest: >
+  v0.31.1 closes CV20.DS14: Change Request `park`, `reject`, and `promote`
+  are now real Builder CLI verbs for the three terminal states the
+  Refinement Workbench domain already modeled but the runtime could not
+  reach. The gap had already forced one off-contract production storage
+  write (CR023, journey `kia-desktop`) to work around it. A six-persona
+  review ran before any code was written and surfaced three real defects
+  beyond the original handoff — an `outcome_notes` data-loss risk, a
+  surface-marker injection path, and a progress-surface trust bug — all
+  fixed in the same TDD pass. CR023 itself is now Navigator-confirmed
+  reconciled against the new verb's expected output shape, with no
+  migration needed. This release also closes an open Ariad roadmap-parser
+  investigation in documentation and registers a new operational debt item
+  found while preparing the release.
+---
+
+# v0.31.1 — Change Request Terminal Verbs
+
+**Date:** 2026-07-20
+
+## Highlights
+
+- Adds `change-request park` / `reject` / `promote` (and the symmetric
+  `refinement-story park`) as real Builder CLI verbs, closing the gap that
+  previously made a Refinement Story holding a deferred, declined, or
+  graduated Change Request unclosable through supported commands.
+- A six-persona review (quality-assurance, database-architect,
+  security-engineer, ai-engineer, devops-engineer, prompt-engineer) ran
+  against the written plan before implementation began, and its findings
+  were folded back into the plan rather than treated as commentary.
+- Fixes a latent `_flow_event` bug where a parked/rejected/promoted Change
+  Request was still reported as the *active* one.
+- Fences Ariad transport markers (`<<<ARIAD:`/`<<<END:`) inside rendered
+  Change Request free-text, closing a surface-injection path.
+- Fixes the Refinement Story progress surface so a terminal Change Request
+  is never shown as "remaining" while the same surface says no actionable
+  Change Requests are left.
+- CR023 (`kia-desktop`, `a6be8152`) — the production row that motivated this
+  release — is Navigator-confirmed reconciled against the new verb's output
+  shape via a read-only check. No migration was needed.
+- Closes an open Ariad roadmap-parser investigation in documentation:
+  CV20.DS13 had already fixed the underlying defects, but the ledger and
+  investigation record still read "Open," misleading anyone auditing the
+  Ariad runtime.
+- Registers TD-002: the `backup` CLI path ignores `MEMORY_ENV`/
+  `db_name_for_env()`, silently pointing at the wrong database file on a
+  development or test environment.
+
+## Where We Started
+
+A Navigator working the `kia-desktop` journey needed to park a Change
+Request — a deliberate build-1 defer, not a mistake and not a rejection.
+The Refinement Workbench domain already modeled `parked` as a terminal
+state, and the RS-close gate already depended on it. But no CLI verb
+reached it: only `done` was wired, and `discard` *deletes* a captured
+record — the wrong tool for a decision worth keeping. The only path was a
+raw write to the production storage layer, bypassing the service entirely:
+no validation of legal source state, no emitted surface, and a real risk of
+leaving the runtime cursor dangling had the Change Request been active.
+That is precisely the failure mode Ariad's "every transition emits a
+verbatim surface" contract exists to prevent.
+
+## What Changed
+
+The fix was planned before it was built. A written plan went through six
+professional lenses — quality-assurance, database-architect,
+security-engineer, ai-engineer, devops-engineer, and prompt-engineer — and
+each surfaced something the plan had not accounted for: parking a
+`validated` Change Request would have silently overwritten its validation
+evidence (database-architect), free-text `reason`/`notes`/`target` fields
+render into a transport surface that could be forged with a fake marker
+(security-engineer), and the Refinement Story progress surface would
+report a newly-terminal Change Request as both "remaining" and "no
+actionable Change Requests left" in the same output (quality-assurance).
+All three were designed around and fixed in the implementation, not left
+as follow-up debt.
+
+`park`, `reject`, and `promote` now mirror the existing `complete_change_request`
+vertical slice end to end: service functions with legal-state guards, a
+single authoritative terminal-status constant, surface entries for each new
+event, and CLI subparsers wired through the existing clean-error path. `park`
+requires both a reason and a revisit trigger; `reject` keeps the record
+(contrast `discard`, which deletes); `promote` records a delivery target
+without mutating the roadmap. Terminal outcome notes are prepend-preserved
+rather than overwritten, so a Change Request's prior lifecycle evidence
+survives its terminal transition. `mm-build/SKILL.md` now names the real
+commands and explicitly disambiguates `reject` from `discard` — the one
+confusion in this set with an irreversible wrong answer.
+
+Validation ran in the order the plan committed to: the full
+park/reject/promote → review/coherence/close route confirmed by the
+Navigator in Builder Mode, a four-phrase verb-routing probe confirming
+natural language never mis-routes `reject` to `discard`, and — the one
+production-touching step, run by the Navigator via a read-only script, not
+the agent — CR023 itself, matched against the new verb's expected shape on
+all four checks.
+
+Separately, this release closes the loop on an earlier defect fix:
+CV20.DS13 (Delivery Story grammar roadmap support) shipped the code fix for
+a roadmap-parser investigation but never marked the investigation or its
+dogfooding-ledger findings as resolved, leaving the written record actively
+misleading. That record now matches reality. TD-002 — a real bug found
+while preparing this release's own backup step, where `backup`'s CLI path
+never consults `MEMORY_ENV` — is registered in the technical debt ledger,
+not fixed here.
+
+## Conscious Exclusions
+
+- `promote` is deliberately minimal: it records a delivery target and
+  reaches a terminal state, and nothing more. It does not create or mutate
+  a roadmap item — Ariad does not act as an autonomous project manager.
+- No automated verb-routing eval shipped. The manual routing probe plus the
+  skill's reject-vs-discard disambiguation and a "never write storage
+  directly" guardrail mitigate the immediate risk; an automated golden-set
+  eval is registered on the roadmap Radar as a fast-follow.
+- Refinement Workbench commands remain Pi-only in the skills — the Claude
+  skill has no Change Request/Refinement Story commands, and Codex/Gemini
+  carry no `mm-build` surface at all. Also registered on the Radar.
+- TD-002 is registered, not fixed.
+- CV20 remains in progress. This release closes one Delivery Story;
+  CV20.DS7 (Release And Push Policies) and the remaining planned stories
+  are unaffected.
+
+## What We Learned
+
+Reviewing a plan from six professional lenses before writing a line of code
+found three real defects at zero implementation cost — the same class of
+defect that, unreviewed, becomes exactly the kind of production incident
+this release exists to close (CR023 itself). Separately, the DS13 cleanup
+was a reminder that fixing code and closing the record of the problem are
+two different acts: a harvest workflow that skips the second half leaves a
+technically-solved defect looking permanently open to the next person who
+reads the ledger.
+
+## Next Horizon
+
+CV20's primary arc continues toward CV20.DS7 (Release And Push Policies).
+The two items registered on this release's Radar — an automated
+verb-routing eval and Claude/Codex Refinement-skill parity — are the
+visible next steps for Refinement Work specifically. CV9, CV21, and CV22
+continue in parallel, unaffected by this release.