mirror-mind 0.0.1 → 0.32.1

package/AGENTS.md

@@ -0,0 +1,188 @@
+# Mirror Mind — Operating Instructions
+
+<!-- This file ships in the mirror-mind package and is read by every runtime:
+     Pi and Codex read it from the project root natively, Claude Code and
+     Gemini CLI through the @AGENTS.md import in CLAUDE.md, and an installed
+     package's Pi session receives it from the extension (CV22.DS10.US3, D13).
+     It holds nothing about this repository; that is CLAUDE.md's part. -->
+
+---
+
+## Mirror Operating Instructions
+
+Applies to all sessions, regardless of project.
+
+### Operating Modes
+
+The mirror operates in four modes, chosen automatically based on context:
+Mirror, Builder, Explorer, and Soul.
+
+Each skill below is named three ways: `/mm-<skill>` in Pi and Gemini CLI,
+`$mm-<skill>` in Codex, `/mm:<skill>` in Claude Code. A Claude Code **plugin**
+install prefixes the plugin's name — `/mirror-mind:mm:<skill>` in the menu,
+`mirror-mind:mm-<skill>` as the skill's own name — and the forms below refer to
+the same skill.
+
+**Mirror Mode** — activate for: life decisions, feelings, business strategy,
+writing, mentoring, health, existential questions, sensemaking, psychological
+tensions, class preparation, product launches, or any topic asking for personal
+reflection or positioning.
+
+How to operate: load the mirror skill (`/mm-mirror`, `$mm-mirror`, or
+`/mm:mirror`). Load identity, route persona, search attachments, answer in first
+person, and record the response.
+
+**Builder Mode** — activate for: code, project structure, YAML editing, bugs,
+implementation, architecture, or any software engineering task.
+
+How to operate: read code, edit files, run commands, propose technical
+solutions, keep docs updated when code changes. For a journey, use `/mm-build
+<slug>` / `$mm-build <slug>` / `/mm:build <slug>` — loads journey context and
+project docs.
+
+**Explorer Mode** — activate for the uncertain middle before construction:
+exploring a possibility space, holding uncertainty before committing to build,
+developing an Exploratory Story, surfacing attractors, proposing small
+experiments, or preparing a Builder handoff.
+
+How to operate: use `/mm-explore <slug>` / `$mm-explore <slug>` / `/mm:explore
+<slug>` to activate Explorer Mode for a journey and resume the active Exploratory
+Story when one exists. Follow `.pi/skills/mm-explore/SKILL.md`: render required
+story surfaces before interpretation, thicken the story as the narrative changes,
+and keep exploration durable. Explorer Mode preserves uncertainty — it does not
+implement. For operational mutation requests, name the `△ EXPLORER → BUILDER
+BOUNDARY` and route them through Builder Mode via an explicit handoff. Deactivate
+with `/mm-explore deactivate`, which returns to Mirror Mode while preserving
+sticky journey context.
+
+**Soul Mode** — activate when the user asks to enter Soul Mode, open Soul Mode,
+or continue an active Soul Mode ritual.
+
+How to operate: use `/mm-soul [slug]` / `$mm-soul [slug]` / `/mm:soul [slug]`
+to render the entry surface. While Soul Mode is active, follow
+`.pi/skills/mm-soul/SKILL.md`: listen to the user's answer as living field,
+withhold Possible Listenings when the material is thin, and when living matter
+appears call the front door's `soul listen ...` (the exact invocation is in the
+skill) to render the Possible Listenings surface at the end of the response. This renderer call is required
+Soul Mode behavior, not optional tool use. Soul Mode must not mutate files,
+implement stories, run implementation commands, package releases, or change
+project state. For operational requests, name the `☾ SOUL → BUILDER BOUNDARY`
+and ask whether to switch to Builder Mode for the same journey.
+
+Builder activation boundary: activating Builder Mode or loading a journey is
+context setup only. After loading the context and required docs, stop and ask
+what work should be done next. Do not edit files, create tests, run
+implementation, start TDD, or mutate project state until the user gives an
+explicit implementation or documentation instruction, such as implement, fix,
+edit, create, run tests, or names a specific story to execute. Context
+activation is not execution consent.
+
+Ariad surface transport invariant: when command output contains marked Ariad
+surface blocks (`<<<ARIAD:...>>>` through `<<<END:...>>>`), preserve every marked
+block verbatim in the assistant response before commentary. Do not summarize,
+translate, reorder, trim, rewrap, re-indent, reformat, or replace marked surfaces
+with prose. This is a general rendering rule for Ariad surfaces, not a
+phase-specific behavior.
+
+**Ambiguity:** if the mode is unclear, ask whether the user wants personal
+reflection or project construction.
+
+**Journey Status** — shortcut within Mirror Mode. Activate when the user asks
+"How are we doing?", "What's the status of X?", or any question about progress
+or roadmap. Dispatch to `/mm-journey` or `/mm-journeys`. When the user asks for
+the journey list in natural language, use `/mm-journeys` and preserve its
+hierarchical rendering without flattening or reformatting it.
+
+**Commits:** use descriptive English commit messages. Explain the WHY, not just
+what was done. Prefer small commits with clear review boundaries.
+
+### Ego-Persona Model
+
+The mirror has one voice: the ego. Personas are specialized lenses activated by
+the ego according to context.
+
+**Automatic routing:** activate a persona when the topic clearly belongs to a
+specialized domain, the depth required exceeds the generic ego repertoire, or
+the user explicitly asks for a persona.
+
+**Routing protocol:** persona routing is data-driven. Each persona in the
+database carries `routing_keywords` and a routing descriptor. At runtime,
+`detectPersona` (`ts/src/persona/detectPersona.ts`) scores the query against
+those keywords. If no persona scores above threshold, the ego answers alone. To
+inspect active routing:
+`mirror detect-persona "<query>"`.
+
+**Signature format:**
+
+When the ego answers alone — no signature.
+
+When a persona is active:
+```text
+◇ persona-name
+
+[first-person answer, unified voice]
+```
+
+When switching personas:
+```text
+◇ product-designer
+
+[analysis...]
+
+◇ therapist
+
+[reflection...]
+```
+
+Rules: `◇` plus persona name on its own line; voice stays first person and unified.
+
+### Hard Constraints
+
+- **Truth:** do not invent data. If uncertain, say so.
+- **Service:** intellectual partner, not task executor. Question, refine, align —
+  do not execute without thinking.
+
+### Available Skills
+
+**Core modes:**
+- `mm-mirror` — activates Mirror Mode — `.pi/skills/mm-mirror/SKILL.md`
+- `mm-build` — activates Builder Mode for a journey — `.pi/skills/mm-build/SKILL.md`
+- `mm-explore` — activates Explorer Mode for a journey — `.pi/skills/mm-explore/SKILL.md`
+- `mm-soul` — activates Soul Mode ritual entry — `.pi/skills/mm-soul/SKILL.md`
+
+**Journeys and tasks:**
+- `mm-journeys` — compact journey list — `.pi/skills/mm-journeys/SKILL.md`
+- `mm-journey` — detailed journey status — `.pi/skills/mm-journey/SKILL.md`
+- `mm-tasks` — task management by journey — `.pi/skills/mm-tasks/SKILL.md`
+- `mm-week` — weekly planning — `.pi/skills/mm-week/SKILL.md`
+
+**Memory and inspection:**
+- `mm-memories` — recorded memories — `.pi/skills/mm-memories/SKILL.md`
+- `mm-conversations` — recent conversations list — `.pi/skills/mm-conversations/SKILL.md`
+- `mm-recall` — load messages from a previous conversation — `.pi/skills/mm-recall/SKILL.md`
+
+**Content:**
+- `mm-journal` — personal journal entry — `.pi/skills/mm-journal/SKILL.md`
+
+**Identity:**
+- `mm-seed` — seed identity YAML files into the database — `.pi/skills/mm-seed/SKILL.md`
+- `mm-identity` — read and update identity in the database — `.pi/skills/mm-identity/SKILL.md`
+
+**Session control:**
+- `mm-mute` — toggle conversation logging — `.pi/skills/mm-mute/SKILL.md`
+- `mm-new` — start a new conversation — `.pi/skills/mm-new/SKILL.md`
+- `mm-discard` — discard the current conversation before quitting — `.pi/skills/mm-discard/SKILL.md`
+
+**Memory cultivation:**
+- `mm-consolidate` — scan memories for patterns and propose consolidation — `.pi/skills/mm-consolidate/SKILL.md`
+- `mm-shadow` — surface and promote shadow-layer observations — `.pi/skills/mm-shadow/SKILL.md`
+
+**Utilities:**
+- `mm-consult` — ask other LLMs through OpenRouter — `.pi/skills/mm-consult/SKILL.md`
+- `mm-backup` — memory database backup — `.pi/skills/mm-backup/SKILL.md`
+- `mm-welcome` — render the state-aware welcome card on demand — `.pi/skills/mm-welcome/SKILL.md`
+- `mm-release-notes` — show Mirror Mind release notes — `.pi/skills/mm-release-notes/SKILL.md`
+- `mm-update` — update the local Mirror runtime — `.pi/skills/mm-update/SKILL.md`
+- `mm-help` — list available commands — `.pi/skills/mm-help/SKILL.md`
+
+Full command reference: [REFERENCE.md](REFERENCE.md)

package/README.md

@@ -1,12 +1,129 @@
-# mirror-mind
+# Mirror Mind
 
-**This name is reserved for Mirror Mind.** Version `0.0.1` is a placeholder: it
-installs nothing runnable and provides no `mirror` command.
+![A person reviews a blueprint with one lead contractor while a coordinated specialist team builds different parts of a house behind them, representing Mirror Mind as one unified AI interface with many expert lenses.](docs/assets/mirror-mind-contractor-team-1200px.jpg)
 
-Mirror Mind is a local-first memory and identity framework for agentic AI
-runtimes — Pi, Claude Code, Gemini CLI, and Codex — with one TypeScript core
-run by Node.js and a SQLite database on your machine.
+Imagine hiring a contractor to build a house. A good contractor doesn't show up
+alone — they bring a team: the architect, the structural engineer, the
+electrician, the plumber, the finish carpenter. Each one is exceptional in their
+domain. They've worked together before. They hand off cleanly. You talk to one
+person; the coordination is their problem, not yours.
 
-The project lives at <https://github.com/mirror-mind-ai/mirror>. The first
-release under this name will put `mirror` on your `PATH`; until then, the
-repository's README and getting-started guide are the place to start.
+Mirror Mind gives you that team for knowledge work. A strategist for business
+decisions. An engineer for code. A therapist for the tensions underneath the
+surface. A writer for the moments when voice matters. A researcher when you need
+to go deep. Each activated by context, each exceptional in their domain, all
+speaking with one unified voice — because they're all expressions of the same
+intelligence: yours.
+
+The AI tools most people use today are the equivalent of hiring contractors one
+at a time, separately, with no shared context. Each one starts cold. They don't
+know what the others decided. They don't know your constraints, your past
+decisions, your current stage. You are the coordinator — doing the integration
+work that should not be yours to do.
+
+Mirror Mind changes this. Your team is briefed on your projects. They know where
+you are in each one, what's been decided, what's unresolved. The second session
+is faster than the first. The tenth is faster still. They don't start from zero
+— because they were there.
+
+---
+
+![Before and after illustration: a person faces an opaque AI mirror that cannot reflect them, then a polished Mirror Mind reflection that carries their identity, memory, projects, and preferences.](docs/assets/mirror-mind-before-after-cartoon-600px.jpg)
+
+But what makes this team exceptional is not just coordination. It's that they
+know *you*.
+
+Every time you open a new AI session, you re-explain yourself. You re-establish
+your context. You repeat your values, your constraints, your situation — again.
+And the AI, no matter how capable, responds as if it's meeting you for the first
+time. The advice it gives could fit anyone. It doesn't know that you made that
+decision three months ago and why. It doesn't know what you're navigating right
+now, what tensions are unresolved, what you committed to last week. It answers in
+a vacuum. That's not a team. That's a very smart set of strangers.
+
+Mirror Mind accumulates. Every conversation is analyzed and the signal is
+extracted: decisions, insights, commitments, patterns. The intelligence compounds.
+Your team doesn't just know your projects — they know your voice, your values,
+your recurring tensions, the way you think. The strategist gives you advice
+calibrated to your risk profile. The therapist surfaces the tension you circled
+around three sessions ago. The engineer remembers why you made the architectural
+call that shaped everything downstream.
+
+That's what the mirror is: a conscious, accumulative reflection of your own
+intelligence — sharpened by every conversation, carried across time. The
+contractor metaphor explains how you interact with it. The mirror explains why
+it works.
+
+This is not a chatbot with memory. This is a mirror — and yours.
+
+---
+
+## How It Works
+
+Local-first. SQLite. Four supported runtimes: Pi, Gemini CLI, Codex, Claude
+Code. One TypeScript core, run by Node.js. Jungian architecture: Self, Ego,
+Personas, Shadow.
+Context-activated modes — Mirror, Builder, Explorer, and Soul. The identity lives
+in your machine, not a server.
+
+→ Get started in ten minutes: [Getting Started](docs/getting-started.md)  
+→ Full command reference: [REFERENCE.md](REFERENCE.md)
+
+---
+
+## Prerequisites
+
+- [Node.js 24+](https://nodejs.org/) — runs Mirror Mind's core
+  (`node --version` must be ≥ v24; POSIX/macOS/Linux supported). Nothing
+  else to install: there is no Python and no build step
+- [OpenRouter](https://openrouter.ai) account with at least $5 in credits —
+  embeddings, memory extraction, and multi-LLM
+- An AI runtime subscription:
+  [Codex Plus](https://openai.com/codex/) (recommended),
+  [Claude Code Pro](https://code.claude.com/docs), or
+  [Gemini AI Pro](https://geminicli.com/)
+- [Pi](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)
+  — recommended harness (multi-model, not locked to one provider)
+
+---
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — step-by-step onboarding for new users
+- [REFERENCE.md](REFERENCE.md) — command reference and configuration
+- [Architecture](docs/product/architecture.md) — system design, layers, and data model
+- [Project Briefing](docs/project/briefing.md) — foundational architectural decisions
+- [Decisions](docs/project/decisions.md) — incremental decision log
+- [Roadmap](docs/project/roadmap/index.md) — current and planned capability values
+- [Development Guide](docs/process/development-guide.md) — how to work on this codebase
+
+---
+
+## Origins and Credits
+
+Mirror Mind began as [Alisson Vale](https://github.com/alissonvale/)'s original
+`mirror-mind` — a Portuguese-language,
+Claude Code-only implementation built around his own identity and circumstances.
+He created the concept and the Jungian architecture.
+
+[Vinícius Teles](https://github.com/viniciusteles) extended that foundation into
+this repository, turning a personal experiment into a reusable framework:
+
+- **English** — full migration from Portuguese across code, CLI, schema, identity, and docs
+- **Framework/user separation** — user identity and memory live privately under `~/.mirror/<user>/`, outside the repository
+- **Multi-runtime** — from Claude Code only to four runtimes: Pi, Gemini CLI, Codex, and Claude Code
+- **Multi-user** — independent mirrors for multiple users on the same machine
+- **Multi-session** — concurrent sessions tracked safely in a database-backed session registry
+- **Intelligence depth** — hybrid semantic and lexical search, honest reinforcement, two-pass extraction, memory consolidation, and shadow cultivation
+- **Extension system** — a stable contract for adding user-specific capabilities outside the core; extensions own their own SQLite tables, CLI subcommands, and Mirror Mode context providers without touching the framework
+
+The move toward Pi as the preferred runtime was inspired by
+[Henrique Bastos](https://github.com/henriquebastos) and his early work in
+[henriquebastos/mirror-mind](https://github.com/henriquebastos/mirror-mind),
+which showed a strong path toward a more model-flexible runtime.
+
+---
+
+## License
+
+MIT

package/bin/loader.js

@@ -0,0 +1,67 @@
+// The one loader shim behind every Mirror bin. CV22.DS10.US3, decisions D15 and D5.
+//
+// The program is TypeScript run directly by Node -- no build step -- and that
+// holds in a checkout and through `npm link`, where the files' real path is
+// outside `node_modules`. It does not hold for `npm install -g`: Node refuses
+// to strip types for anything under `node_modules`
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), a policy with no flag.
+//
+// So each bin is a JavaScript file that calls `boot` with its entry. `boot`
+// registers a load hook that strips types for `.ts` files UNDER THIS PACKAGE
+// ROOT ONLY -- never a dependency, never the user's project -- and then
+// imports the entry and runs it. Every shipped path stays what it is in the
+// checkout (D2); the installed tree differs from a clone by the `bin/`
+// directory alone, and the checkout carries it too, so `npm link` and the
+// install run the same entries.
+//
+// Two bins share this file rather than each carrying the shim: `mirror`
+// (`frontDoor/cli.ts`) and `mirror-hook` (`hooks/main.ts`, D5). The hook
+// wrappers run the second one wherever they are -- in a checkout, under
+// `npm root -g`, or copied into Claude Code's plugin cache.
+//
+// `registerHooks` and `stripTypeScriptTypes` are experimental in the Node 24
+// floor, the same stability class as `node:sqlite`, which the core already
+// stands on; `scripts/smoke_npm_package.sh` runs both bins from a real global
+// install on CI's Node 24.
+//
+// The warning filter below is the shim's own copy, because the hook emits its
+// ExperimentalWarning before the core's filter can be imported through it.
+
+import { readFileSync } from "node:fs";
+import { registerHooks, stripTypeScriptTypes } from "node:module";
+import { fileURLToPath } from "node:url";
+
+process.removeAllListeners("warning");
+process.on("warning", (warning) => {
+  if (warning.name === "ExperimentalWarning") return;
+  process.stderr.write(`${warning.name}: ${warning.message}\n`);
+});
+
+const packageRoot = new URL("../", import.meta.url).href;
+
+registerHooks({
+  load(url, context, nextLoad) {
+    if (url.startsWith(packageRoot) && url.endsWith(".ts")) {
+      const source = readFileSync(fileURLToPath(url), "utf8");
+      return {
+        format: "module",
+        source: stripTypeScriptTypes(source, { mode: "strip" }),
+        shortCircuit: true,
+      };
+    }
+    return nextLoad(url, context);
+  },
+});
+
+/**
+ * Import the entry at `entryPath` (relative to the package root) and run its
+ * `runAsEntry()`, which every Mirror entry exports: it loads configuration,
+ * silences the sqlite warning, and returns the exit code.
+ *
+ * @param {string} entryPath
+ * @returns {Promise<number>}
+ */
+export async function boot(entryPath) {
+  const { runAsEntry } = await import(new URL(entryPath, packageRoot).href);
+  return runAsEntry();
+}

package/bin/mirror-hook.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The `mirror-hook` bin: the hook entry every wrapper runs. CV22.DS10.US3, D5.
+// The shim it runs on, and why there is one, is `loader.js`.
+
+import { boot } from "./loader.js";
+
+process.exitCode = await boot("ts/src/hooks/main.ts");

package/bin/mirror.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The `mirror` bin: the front door. CV22.DS10.US3, decision D15.
+// The shim it runs on, and why there is one, is `loader.js`.
+
+import { boot } from "./loader.js";
+
+process.exitCode = await boot("ts/src/frontDoor/cli.ts");

package/docs/releases/index.md

@@ -0,0 +1,99 @@
+[< Docs](../index.md)
+
+# Releases
+
+Narrative release notes for Mirror Mind live here from the adoption of CV9.E5 onward.
+
+Release notes are prospective. Historical versions through `v0.7.0` remain valid project history, recorded in Git tags and the [worklog](../process/worklog.md), but they are not retroactively reinterpreted by the new [versioning rule](../process/versioning.md).
+
+Future release notes should use the structure defined in [Release Notes](../process/release-notes.md): digest, highlights, narrative context, what changed, conscious exclusions, lessons, and next horizon.
+
+---
+
+## Releases
+
+- [v0.32.1 — The Release That Shipped](v0.32.1.md) — patch release that is the published CV22 release: `v0.32.0` was tagged and its publication refused by the retired-surface tripwire over one sentence in Getting Started, now rephrased. No code, behavior, or schema differs from `v0.32.0`; read that note for the release itself.
+- [v0.32.0 — One Language, One Install](v0.32.0.md) — minor release that closes CV22, the TypeScript Core Port. Mirror Mind is one TypeScript package run by Node.js 24, installed with `npm install -g mirror-mind` and wired to Pi, Claude Code, Gemini CLI, or Codex by one documented step each; no Python remains in the repository or the shipped artifact; every command answers as it did. Eleven surfaces are retired with cutoffs, recorded in [Pending Cutoffs](pending-cutoffs.md), which this note carries. A new home imports only the Pi sessions newer than itself.
+- [v0.31.14 — Change Request Resume](v0.31.14.md) — patch release that adds the public Ariad Workbench `change-request resume` verb so a non-terminal advanced Change Request that lost the active pointer can continue without direct SQLite edits or artificial status regression. Resume preserves the CR record, restores only the Refinement cursor, allows `implemented` to proceed to `validate` and `validated` to proceed to `done`, and keeps terminal CRs closed.
+- [v0.31.13 — Explicit Append and Lifecycle Recovery](v0.31.13.md) — patch release that adds the public `conversations append` JSON boundary with atomic exact-Journey persistence, caller-owned idempotency, bounded receipts, and no runtime-session routing or late-append semantic refresh; it also restores Ariad Coherence reentry after evidence correction and pays D-016's lazy SQLite WAL recovery defect without changing model pins or prompts.
+- [v0.31.12 — Bounded Authority and Journey Integrity](v0.31.12.md) — patch release that makes Builder delegation exact and durable: natural and cadence-declared story Plan authority remains generation-bound, single-use, and stopped at Navigator Validation; Driver-authored Plans survive approval; release intent grants no publication authority; transactional model-free Journey administration protects hierarchy and history; and Delivery Story Done refuses false coherence while authored roadmap status is stale.
+- [v0.31.11 — Confined Operational Relative Links](v0.31.11.md) — security-preserving hotfix that resolves authored Markdown links from their containing document and accepts parent-relative traversal only when the canonical target remains inside the registered Journey root. Canonical escapes, absolute/URI/backslash targets, symlink escapes, and missing-target publication failures remain bounded; the last valid projection pair is preserved.
+- [v0.31.10 — Journey Projection Contract](v0.31.10.md) — patch release that implements `mirror.journey-projections@1.0` in the Python Core with registered-root confinement, per-Journey cross-process linearizability, immutable receipts, deterministic Ariad Operational compilation, post-commit lifecycle refresh, and Extension API `1.1`. The unchanged consumer-owned probe passes against isolated synthetic state; installed-runtime acceptance remains explicit through the consumer return record.
+- [v0.31.9 — Recursive Journey Hierarchy](v0.31.9.md) — patch release that removes the artificial two-level journey limit while preserving organizational-only parentage. Textual and web surfaces render arbitrary depth and full lineage; cycles are rejected; moves preserve ids, paths, and filesystem content; removal refuses parents and associated leaves without cascade. The TypeScript strangler now tracks an explicit moving Python product command by command instead of freezing user-facing evolution for the duration of the migration.
+- [v0.31.8 — Windows Desktop Frame](v0.31.8.md) — patch release that makes the native Windows Frame the primary installed experience while preserving the terminal recovery path. Guided onboarding, tabbed Pi/ConPTY sessions, exact Pi `0.83.0` convergence, all-PTY update gating, fail-closed packaging, packaged Electron smoke, and real non-ASCII profile validation establish the first releasable desktop boundary; installer `0.31.0` remains unsigned and Mirror-core updates still arrive through a complete new installer.
+- [v0.31.7 — Collaborative Refinement Work](v0.31.7.md) — patch release that makes the document-first Workbench usable across contributors and their Mirrors. File-first inspection now renders a standard read-only view; active CRs can record a human Driver and branch/PR Delivery reference; and a project-owned protocol defines capture, selection, planning, assignment, validation, terminal closure, return handoff, and ordinary Git conflict handling without adding a parser, shared database, lock, watcher, synchronizer, or custom Git protocol.
+- [v0.31.6 — Document-First Refinement Authority](v0.31.6.md) — patch release that replaces journey-local SQLite as the shared source of Refinement truth whenever a project declares `docs/project/refinement/index.md`. The canonical Markdown index now owns RS/CR focus, order, and status; linked files own narrative and evidence; Git owns collaboration and recovery. Builder surfaces and Pi/Gemini/Codex guidance follow the project files without inspecting stale Workbench rows, while projects without the index retain the legacy SQLite path. The release preserves migrations `015`/`016`, performs no implicit migration or dual-write, and records the abandoned projection/recovery/handoff architecture as an archived experiment rather than production machinery.
+- [v0.31.5 — One Code, One Package](v0.31.5.md) — maintenance patch that closes the roadmap-resolution class v0.31.4 only partially fixed. One shared resolver (`memory.builder.story_paths`) now backs both Ariad Expand and the CLI's Plan/checkpoint lookup, superseding v0.31.4's narrower, same-day `_resolve_existing_item_directory` fix (discovered independently on `kia-desktop`) while this release's own investigation traced a second occurrence of the CR048 defect (CV22.DS7). Two packages sharing a code, or a resolved package whose candidate table can't be parsed, now render a first-class `EXPAND_BLOCKED` refusal instead of resolving silently or fabricating a generic story; a new CI check makes "one code, one package" a build-time guarantee. Closes D-012 (candidate-table code-cell path sanitization) as a direct consequence of touching the functions its revisit trigger named. Reconciled with v0.31.4 by rebase, keeping its regression test as additional coverage.
+- [v0.31.4 — Roadmap-Aligned Story Expansion](v0.31.4.md) — maintenance patch that stops Ariad's Builder from materializing a phantom, parallel story-package tree when expanding a Delivery Story. `_artifact_directory` derived roadmap folders from code plus title, but hand-authored roadmaps use CV/DS slugs (`cv3-build-de-producao`) no title derivation can reproduce, so expanding CV3.DS22 wrote a boilerplate `cv3-manage-100-funcional/cv3-ds22/` tree instead of the real `cv3-build-de-producao/cv3-ds22-manage-100-funcional/` node. Expand now resolves the existing folder by matching each `index.md`'s `# CODE — Title` heading to the item code (the same scan the pull inspector uses) and only falls back to title derivation for genuinely new items. Pinned by a nested-folder regression test and validated against the live kia-desktop roadmap.
+- [v0.31.3 — Ariad DS-Plan Artifact Integrity](v0.31.3.md) — maintenance patch that makes the Ariad Delivery Story plan lifecycle's artifacts trustworthy. Fixes phantom `ARTIFACTS_MATERIALIZED` rows for a never-written `test-guide.md` and a falsely "updated" `index.md` (AF-002, AF-006) by driving the surface from the writer's real manifest and materializing the full package without clobbering authored content. Scaffolds every `plan_contract` section in `plan.md` (AF-003), then — after a six-lens technical review chose pure-preserve over a surgical status patcher — removes mutable status from the document so `approve-delivery-story-plan` preserves the authored plan instead of regenerating it, and flags any section left unfilled. Records the warn-not-block choice and the D-012 code-segment sanitization gap as conscious exclusions.
+- [v0.31.2 — Filesystem-Safe Slug Consolidation](v0.31.2.md) — maintenance patch that fixes an `OSError [Errno 63]` (File name too long) crash in `build pull-item` when a Delivery Story candidate title is paragraph-length, by consolidating four drifted kebab `_slugify` copies into one accent-stripping, length-capped `memory.utils.kebab_slug`. Closes the same latent `mkdir` crash in the Explorer handoff writer, makes the roadmap package writer and locator derive the same path by construction, and adds an empty-slug guard. Reviewed through five personas before implementation; records D-012 (code-cell path-separator sanitization) and D-013 (the `transcript_export` slug sibling) as conscious debt.
+- [v0.31.1 — Change Request Terminal Verbs](v0.31.1.md) — patch release that adds `change-request park/reject/promote` (and `refinement-story park`) to the Ariad Refinement Workbench, closing the gap that forced an off-contract production storage write for CR023. Planned through a six-persona review before implementation; fixes a latent `_flow_event` bug, a surface-marker injection path, and a progress-surface trust bug found during that review. CR023 is Navigator-confirmed reconciled; an open roadmap-parser investigation is closed in documentation; TD-002 is registered.
+- [v0.31.0 — Stabilization & Robustness](v0.31.0.md) — minor release that delivers the bulk of the CV9.E2 Stabilization & Robustness epic: extraction failure isolation/quarantine and idempotency, lexical-only search degradation, explicit call timeouts, content-mediated injection fencing across all five model surfaces, an identity-write allowlist, metadata-default cost observability, and an `eval --all` release gate — plus the AI Engineering Audit P0 tier and most P1/P2 findings. CV9.E2.S2 is deferred; the model-behavior gate is satisfied by a recorded D-005 waiver.
+- [v0.30.2 — Network-Appropriate Git Timeouts](v0.30.2.md) — patch release that gives runtime git push/fetch operations a 120-second network timeout instead of sharing the 2-second local-inspection timeout, fixing a false-failure report from `release-promote --push` during the v0.30.1 promotion.
+- [v0.30.1 — Runtime State Home Containment](v0.30.1.md) — patch release that contains all user-scoped runtime state inside the resolved mirror home for every environment, makes unconfigured resolution fail loudly instead of writing to the homes root, unifies core and extension database resolution, contains the Pi logger's log, and teaches `runtime diagnose` to report legacy root artifacts.
+- [v0.30.0 — Windows Installer Distribution](v0.30.0.md) — first public Windows installer distribution release, turning the native installer into a release-backed `.exe` asset path while keeping generated binaries out of the repository and preserving runtime self-update for existing installs.
+- [v0.29.3 — Pi External-Skill Discovery Fix](v0.29.3.md) — maintenance patch that fixes Pi external-skill discovery on the `~/.mirror-minds` home layout by resolving the mirror home like the core, records the resulting cross-language resolution duplication as TD-001, and hardens the Gemini smoke test's production-DB guard.
+- [v0.29.2 — Ariad Builder Flow Refinement](v0.29.2.md) — patch release that refines Ariad Builder surfaces, RS/CR display codes, Project Position orientation, artifact materialization reporting, and Delivery Done handoffs after dogfooding.
+- [v0.29.1 — Windows Compatibility Hardening](v0.29.1.md) — patch release that preserves Windows-safe Claude/plugin skill paths, UTF-8 console output, explicit mojibake repair, and cross-platform path rendering.
+- [v0.29.0 — Ariad Refinement Workbench](v0.29.0.md) — minor release that makes Refinement a first-class Builder Mode work field with Workbench storage, Refinement Stories, Change Requests, CR cycles, and RS review/coherence/close.
+- [v0.28.0 — Ariad Delivery Story Lifecycle](v0.28.0.md) — minor release that makes Delivery Story flow a first-class Ariad Builder path with aggregate DS Plan/Validation/Review/Coherence/Done, canonical checkpoint artifacts, and visual surfaces.
+- [v0.27.0 — Ariad Builder Lifecycle Runtime](v0.27.0.md) — minor release that adds the full Ariad Builder lifecycle from Pull through Done, deterministic surfaces, hard gates, story packages, validation acceptance, Debt Review, Coherence, Done, and conservative higher-autonomy cadence.
+- [v0.26.2 — Web Conversation Bulk Actions](v0.26.2.md) — emergency patch release that adds selected bulk assignment and deletion to the main web Conversations view.
+- [v0.26.1 — Soul Mode English Integration Copy](v0.26.1.md) — patch release that normalizes hard-coded Soul Mode integration prompts and additive identity section headings to the English baseline.
+- [v0.26.0 — Soul Mode Integration](v0.26.0.md) — minor release that adds Closing Rite, multi-layer Integration Proposal, explicit confirmation-only identity integration, additive identity updates, and atomic integration records.
+- [v0.25.0 — Soul Mode More Voices](v0.25.0.md) — minor release that adds active Wisdom Voice and Beauty Voice listening lenses, full voice-card utterances, source/aesthetic bridge guidance, and non-mutating Soul Mode voice boundaries.
+- [v0.24.0 — Soul Mode First Ritual](v0.24.0.md) — minor release that adds the first complete Soul Mode ritual: entry, Possible Listenings, Self and Shadow listening lenses, Fruit In Maturation, Harvested Fruit, journal persistence, and pre-release web/journal refinements.
+- [v0.23.0 — Durable Explorer Mode](v0.23.0.md) — minor release that completes the first Explorer Mode release with durable stories, source-evidence handoff artifacts, required surface rendering, Builder boundary routing, and session-scoped Pi mode status.
+- [v0.22.1 — Mode Orientation CI Formatting](v0.22.1.md) — validation patch that preserves v0.22.0 behavior and restores green CI formatting.
+- [v0.22.0 — Mode Orientation and Test Hygiene](v0.22.0.md) — minor release that adds explicit mode lifecycle, status-line orientation, transition surfaces, experimental Explorer activation, and `/mm-discard` for test-session cleanup.
+- [v0.21.1 — Mirror Mode Conversation Continuity](v0.21.1.md) — patch release that prevents repeated Mirror Mode context loads from splitting one active runtime session into many conversations.
+- [v0.21.0 — Scene Workspace Home](v0.21.0.md) — minor release that adds Current Scene, persisted grounded Scene Orientation, narrative global Workspace surfaces, compact all-conversations navigation, and focused orientation tabs.
+- [v0.20.0 — Hierarchical Journey Organization](v0.20.0.md) — minor release that adds one-level parent journeys, hierarchical web/text rendering, journey settings title/status/parent editing, and display-only hierarchy semantics.
+- [v0.19.1 — Web Console Maintenance CI Formatting](v0.19.1.md) — validation patch that preserves v0.19.0 behavior and restores green CI formatting.
+- [v0.19.0 — Web Console Conversation and Journey Maintenance](v0.19.0.md) — minor release that adds web journey creation, explicit conversation deletion, bulk selected deletion, and broader selected-journey conversation visibility.
+- [v0.18.2 — Conversation Journey Assignment](v0.18.2.md) — patch release that adds unassigned conversation visibility, manual/bulk journey assignment, and conservative journey backfill.
+- [v0.18.1 — Empty Conversation Cleanup](v0.18.1.md) — patch release that expands cleanup to empty conversation records while preserving dry-run, approval, and backup boundaries.
+- [v0.18.0 — Conversation Metadata Lifecycle](v0.18.0.md) — minor release that finalizes conversation metadata at close time and adds web metadata maintenance, historical backfill, resume scopes, and orphan cleanup.
+- [v0.17.3 — Builder Guard Non-Mirror Projects](v0.17.3.md) — patch release that restricts the Builder production-clone guard to Mirror Mind checkouts so ordinary journey projects load normally.
+- [v0.17.2 — Builder Guard CI Formatting](v0.17.2.md) — validation patch that keeps the Builder project-path guard behavior and restores green CI formatting.
+- [v0.17.1 — Builder Project-Path Guard](v0.17.1.md) — patch release that scopes Builder Mode's production-clone guard to the selected journey project path.
+- [v0.17.0 — Conversation Title Hardening](v0.17.0.md) — minor release that hardens conversation titles across runtime close, startup maintenance, Pi backfill, and bounded web batch retitle operations.
+- [v0.16.2 — Runtime Update Validation Stub](v0.16.2.md) — minimal stable release used to validate the corrected v0.16.1 updater executing a normal production update.
+- [v0.16.1 — Runtime Update Preflight Resilience](v0.16.1.md) — patch release that publishes the updater hardening fix for core migration drift and SQLite WAL sidecar status recovery.
+- [v0.16.0 — Async Operations and Agentic Web Console](v0.16.0.md) — minor release that closes CV13 with asynchronous operation runs, durable event timelines, controlled command execution, cancellation, approval checkpoints, and a bounded agent-run prototype with a polished run console.
+- [v0.15.0 — Web Operations Runner](v0.15.0.md) — minor release that closes CV13.E5 with allowlisted synchronous web operations, runtime health, database backup, conversation repair, local audit evidence, and the first visible Operations surface.
+- [v0.14.0 — Conversation Intelligence](v0.14.0.md) — minor release that closes CV13.E4 with readable transcripts, explicit title improvement, configuration references, and read-only journey attachments.
+- [v0.13.0 — Configuration Console](v0.13.0.md) — minor release that closes CV13.E3 with read-only Mirror/runtime configuration, masked environment boundaries, and safe journey metadata editing from Workspace.
+- [v0.12.0 — Multi-Mirror and Preferences](v0.12.0.md) — minor release that closes CV13.E2 with safe local Mirror switching and per-Mirror profile/theme preferences.
+- [v0.11.0 — Read-only Web Refinement](v0.11.0.md) — minor release that closes CV13.E1 with Workspace-first navigation, Identity memory drilldowns, read-only search, and refined conversation cards.
+- [v0.10.17 — Update Notice Tone](v0.10.17.md) — patch release that makes update notices informational and prefixes them with ✨.
+- [v0.10.16 — Update Action Routing Validation Stub](v0.10.16.md) — minimal stable release used to validate v0.10.15 update-action routing.
+- [v0.10.15 — Update Action Routing](v0.10.15.md) — patch release that routes `update my Mirror` to the safe runtime updater.
+- [v0.10.14 — Update Prompt Wording](v0.10.14.md) — patch release that changes the welcome update prompt to "what's new in this update?".
+- [v0.10.13 — Pending Notes Ref Refresh Validation Stub](v0.10.13.md) — minimal stable release used to validate v0.10.12 pending-notes ref refresh.
+- [v0.10.12 — Pending Release Notes Ref Refresh](v0.10.12.md) — patch release that safely fetches stable refs before rendering cumulative pending release notes.
+- [v0.10.11 — Pending Notes Prompt Validation Stub](v0.10.11.md) — minimal stable release used to validate v0.10.10 welcome pending-notes prompt routing.
+- [v0.10.10 — Pending Release Notes Prompt](v0.10.10.md) — patch release that routes welcome update prompts to cumulative pending release notes.
+- [v0.10.9 — Release Awareness Validation Stub](v0.10.9.md) — minimal stable release used to validate v0.10.8 welcome update detection.
+- [v0.10.8 — Welcome Release Awareness](v0.10.8.md) — patch release that refreshes stable-channel welcome awareness after cached up-to-date checks.
+- [v0.10.7 — Runtime Operations Documentation](v0.10.7.md) — patch release that reconciles updater and release-management docs/help with the current command surface.
+- [v0.10.6 — Update Status Recovery](v0.10.6.md) — patch release that retries update status after safely bootstrapping an unavailable production database.
+- [v0.10.5 — Cumulative Release Notes](v0.10.5.md) — patch release that lists every pending release note for users more than one version behind.
+- [v0.10.4 — Pi Startup Lifecycle](v0.10.4.md) — patch release that fully detaches Pi startup maintenance so the startup counter can complete.
+- [v0.10.3 — Pi Startup Maintenance](v0.10.3.md) — patch release that moves expensive Pi conversation maintenance out of the blocking startup path.
+- [v0.10.2 — Fresh Release Awareness](v0.10.2.md) — patch release that refreshes visible welcome update notices when stable advances again inside the cache window.
+- [v0.10.1 — Welcome Startup Clarity](v0.10.1.md) — patch release that clarifies Pi startup status and gives new-version availability stronger welcome emphasis.
+- [v0.10.0 — Web Visibility](v0.10.0.md) — closes CV9.E6 with read-only Identity and Workspace perspectives, object detail with Source Context, and a Pi Builder journey-association repair path.
+- [v0.9.1 — Welcome Release Awareness](v0.9.1.md) — patch release that makes stable release availability visible in the welcome and Pi status bar through network-tolerant update awareness.
+- [v0.9.0 — Self-Update Done](v0.9.0.md) — closes the release-aware self-update arc with stable update notices, release-note skill parity, release promotion doctor, controlled promotion, and fresh-user stable smoke evidence.
+- [v0.8.0 — Stable Self-Update Foundation](v0.8.0.md) — first prospective stable-channel release; establishes safe runtime self-update, updater self-recovery, stable/main channels, welcome version visibility, and runtime release-note access.
+
+---
+
+## Historical Boundary
+
+- Pre-adoption versions: `v0.2.0` through `v0.7.0`, recorded by Git tags and worklog entries.
+- Process adoption: CV9.E5.
+- First prospective major boundary: CV9 completion may become `v1.0.0`, because CV9 is the public-release readiness boundary for Mirror Mind 1.0.
+
+Retroactive release notes may be added later as archival work, but they are not required for the process to operate from here forward.