mirror-mind 0.0.1 → 0.32.1

package/docs/releases/v0.26.0.md

@@ -0,0 +1,139 @@
+---
+digest: >
+  v0.26.0 completes the Soul Mode integration arc. Soul Mode can now close a
+  ritual with a Closing Rite, ask whether living material should remain as part
+  of Mirror identity, render a multi-layer Integration Proposal, and apply
+  confirmed Self, Shadow, Ego, or persona integrations only after explicit
+  confirmation. Confirmed integrations are additive: existing identity content is
+  preserved, each integration is recorded individually, and the prompt-facing
+  identity document receives a layer-appropriate section rather than being
+  overwritten.
+---
+
+# v0.26.0 — Soul Mode Integration
+
+**Date:** 2026-06-09
+
+## Highlights
+
+- Adds the Soul Mode Closing Rite.
+- Adds the multi-layer `☾ INTEGRATION PROPOSAL` surface.
+- Makes post-closing integration explicit: living material may remain as part of Mirror identity only if the user chooses to integrate it.
+- Keeps Integration Proposal proposal-only: `proposal only — nothing changed`.
+- Supports confirmed Self, Shadow, Ego, and persona integrations through `memory soul apply`.
+- Requires `--confirm APPLY` before any identity mutation.
+- Preserves existing identity content by default.
+- Adds atomic `identity_integrations` records for confirmed integrations.
+- Appends confirmed integrations under layer-specific sections instead of replacing whole identity documents.
+- Keeps journey identity out of Soul Mode Integration.
+
+## Where We Started
+
+Soul Mode could already open a ritual, hear multiple voices, mature a fruit, and
+save a harvest to the journal. What was still missing was the threshold after
+harvest: a way to close the field, see what remained alive, and decide whether
+anything should become part of Mirror's identity without turning Soul Mode into an
+automatic identity editor.
+
+The first design separated review, proposal, and apply too sharply. In real
+validation, the review surface already felt like a proposal. The release
+therefore collapsed the review/proposal step into a single multi-layer
+Integration Proposal and kept mutation as a separate, explicit confirmation step.
+
+## What Changed
+
+Soul Mode now has a Closing Rite. After a harvest is saved, Mirror can render a
+`☾ CLOSING RITE` card that gathers what was harvested, what still echoes, what
+remains open, and what may want integration. The rite is not itself a journal
+save and not identity mutation. It is a threshold surface.
+
+After closing, Mirror asks:
+
+```text
+There is living material that may want to remain as part of your Mirror identity. Do you want to integrate it now?
+```
+
+If the user says yes, Mirror renders `☾ INTEGRATION PROPOSAL`. The proposal may
+include origin, Self, Shadow, Ego behavior, persona, and leave-open material. The
+identity sections are directly registerable, while origin and leave-open remain
+context. The card ends with:
+
+```text
+proposal only — nothing changed
+```
+
+The post-proposal prompt is direct:
+
+```text
+Do you want to record it this way in your identity? Or we can adjust anything you want.
+```
+
+If the user wants adjustment, Mirror should render an adjusted Integration
+Proposal before applying anything. If the user confirms, Mirror applies only the
+exact confirmed text for the selected identity sections.
+
+Confirmed apply is now additive and provenance-preserving. The new
+`identity_integrations` table stores each confirmed integration as an individual
+record with layer, key, content, origin, optional conversation/journal provenance,
+status, and metadata. The prompt-facing identity document remains the current
+synthesized layer, but it is no longer overwritten by a short Soul Mode fragment.
+
+Confirmed integrations append under layer-specific sections:
+
+```text
+self    → ## New Incorporated Principles
+shadow  → ## New Hidden Needs Recognized
+ego     → ## New Operational Patterns Identified
+persona → ## New Participation Patterns Revealed
+```
+
+This release also tightened the ritual contract for Fruit In Maturation. New
+material should thicken the fruit instead of replacing it with the latest insight.
+The fruit remains singular in form but plural in root: one living phrase that can
+carry multiple elements from the lineage of the session.
+
+Finally, Self integration language was made more affirmative. Self proposals
+state adopted first-person principles, not mere possibilities. For example:
+
+```text
+I care for bonds without turning immediate availability into moral proof of love; my inner measure also belongs to care.
+```
+
+## Conscious Exclusions
+
+- No automatic identity mutation.
+- No journey identity or journey-pattern integration.
+- No replacement-mode identity mutation.
+- No automatic re-synthesis engine for identity documents.
+- No rich Web Soul Mode UI.
+- No Passagem.
+- No Return To Center.
+- No Closing Day or Daily Soul Ritual.
+- No new Soul voices.
+- No local Wisdom/Beauty source library.
+
+## What We Learned
+
+The integration surface works best when it is already a proposal, not a neutral
+review followed by another proposal. Once the user sees Self, Shadow, Ego, and
+persona material together, asking for a second proposal introduces friction and
+uncertainty. The right boundary is not review versus proposal; it is proposal
+versus mutation.
+
+We also learned that safe identity mutation requires two representations. The
+identity `content` field is the current synthesized prompt-facing document, but
+it should not be the only record of what entered the psyche. Individual
+integration records preserve provenance, make future review possible, and prevent
+short ritual insights from erasing long-standing identity material.
+
+The fruit-maturation refinement clarified the ritual grammar: maturation is not
+selection of the newest insight. It is condensation. A mature fruit can carry
+more than one root while remaining one phrase.
+
+## Next Horizon
+
+The next Soul Mode horizon is the web experience: making the ritual and its
+integration records visible in a richer interface without weakening the
+confirmation boundary. Future work may also add identity re-synthesis from
+integration records, but replacement and automatic consolidation should remain
+explicit, inspectable operations rather than hidden Soul Mode behavior.

package/docs/releases/v0.26.1.md

@@ -0,0 +1,65 @@
+---
+digest: >
+  v0.26.1 is a Soul Mode integration language patch. It normalizes hard-coded
+  Soul Mode confirmation and integration copy to Mirror Mind's English baseline,
+  including the Pi skill contract and identity integration section headings.
+  The patch does not add localization; it keeps the framework internally
+  consistent until explicit i18n exists.
+---
+
+# v0.26.1 — Soul Mode English Integration Copy
+
+**Date:** 2026-06-10
+
+## Highlights
+
+- Replaces Portuguese hard-coded Soul Mode integration prompts with English baseline copy.
+- Updates additive identity integration section headings to English defaults.
+- Aligns CV19 docs, release notes, and focused Soul Mode tests with the English baseline.
+- Preserves the v0.26.0 Soul Mode Integration behavior and scope.
+
+## Where We Started
+
+A live Soul Mode test conducted in English exposed several Portuguese prompts in
+confirmation and integration flow. The issue was not localization, because Mirror
+Mind does not have an i18n layer yet. The problem was simpler: framework-level
+hard-coded copy had been written in Portuguese inside an English-baseline
+runtime.
+
+## What Changed
+
+The Pi Soul Mode skill now asks closing, integration, confirmation, and
+post-apply questions in English. The layer-language examples in the skill were
+also translated so future proposals are guided by the same baseline language.
+
+The additive identity integration headings written by `memory soul apply` now use
+English section titles:
+
+```text
+self    → ## New Incorporated Principles
+shadow  → ## New Hidden Needs Recognized
+ego     → ## New Operational Patterns Identified
+persona → ## New Participation Patterns Revealed
+```
+
+The CV19 story docs, tests, and v0.26.0 release note were reconciled so the
+record no longer teaches Portuguese as the framework default.
+
+## Conscious Exclusions
+
+- No localization system.
+- No dynamic language detection.
+- No migration of previously written user identity content.
+- No change to Soul Mode ritual behavior beyond baseline copy and section headings.
+
+## What We Learned
+
+When localization is absent, the framework still needs one clear base language.
+For Mirror Mind internals and hard-coded runtime contracts, that language is
+English. User-authored material may remain in any language, but product copy and
+runtime defaults should not drift into mixed-language behavior.
+
+## Next Horizon
+
+Future localization can make Soul Mode speak in the user's preferred language.
+Until then, hard-coded Mirror Mind surfaces should remain consistently English.

package/docs/releases/v0.26.2.md

@@ -0,0 +1,43 @@
+---
+digest: >
+  v0.26.2 is an emergency web maintenance patch. It brings selected bulk
+  conversation actions to the main Conversations view, so users can assign many
+  conversations to a journey or delete many conversations in one operation
+  without going through one conversation at a time.
+---
+
+# v0.26.2 — Web Conversation Bulk Actions
+
+**Date:** 2026-06-14
+
+## Highlights
+
+- Adds selected bulk assignment to the main web Conversations view.
+- Adds selected bulk deletion to the main web Conversations view.
+- Reuses the existing safe bulk APIs for journey assignment and conversation deletion.
+- Keeps the existing Unassigned conversations maintenance flow working with the same controls.
+
+## Where We Started
+
+The web app already had server support for selected conversation assignment and deletion, and the Unassigned conversations maintenance view exposed those controls. The main Conversations view still forced users to handle conversations one at a time, which made emergency cleanup and reclassification slow when many conversations needed the same action.
+
+## What Changed
+
+The main Conversations view now renders a bulk action panel above the grouped conversation list. Each conversation row includes a checkbox. After selecting one or more conversations, the user can choose a journey and assign the selected conversations in one click, or delete the selected conversations after an explicit browser confirmation.
+
+After either operation, the current conversation surface reloads in place. The same shared behavior preserves the existing Unassigned conversations workflow while making the broader Conversations view useful for bulk maintenance.
+
+## Conscious Exclusions
+
+- No inline journey creation inside the bulk assignment panel.
+- No new backend mutation path beyond the existing bulk assignment and deletion APIs.
+- No undo flow for deleted conversations.
+- No change to conversation metadata extraction, repair, or journey inference.
+
+## What We Learned
+
+The maintenance affordance belonged at the place where the user sees the full field, not only at the filtered edge. The safe API already existed; the missing product behavior was exposing that capability where operational pressure actually appears.
+
+## Next Horizon
+
+Future web maintenance work can add richer selection affordances such as select-all by day, filter-aware selection, or inline creation-and-assign flows. This patch stays deliberately small for emergency release.

package/docs/releases/v0.27.0.md

@@ -0,0 +1,63 @@
+---
+digest: >
+  v0.27.0 is the Ariad Builder lifecycle runtime release. It turns Builder Mode
+  from context loading plus partial Ariad support into an end-to-end delivery
+  environment with deterministic surfaces, method gates, story packages,
+  validation acceptance, Debt Review, Coherence, Done, and conservative
+  higher-autonomy cadence. The release intentionally stops short of durable debt
+  ledger automation and project-local method preference overrides, which remain
+  planned as the next governance layers.
+---
+
+# v0.27.0 — Ariad Builder Lifecycle Runtime
+
+**Date:** 2026-06-14
+
+## Highlights
+
+- Adds the full Ariad Builder lifecycle from Pull through Done.
+- Makes Ariad surfaces deterministic runtime artifacts with verbatim transport.
+- Enforces hard gates for Plan approval, implementation permission, Navigator validation acceptance, Debt Review, Coherence, and Done.
+- Adds complete story package materialization for implementable User/Technical Stories.
+- Adds conservative cadence profiles: `stepwise`, `checkpoint`, `accelerated`, and explicit-limit `autonomous`.
+- Adds a full sandbox reset fixture for repeatable dogfooding in `/Users/alissonvale/Code/sandbox-pet-store`.
+
+## Where We Started
+
+Builder Mode could load a journey and Ariad could exist as method data, but the delivery lifecycle was still partly conversational. The Driver could inspect, pull, or plan work, but the method did not yet govern the whole path from roadmap choice to story closure. Dogfooding exposed the danger: if a gate lived only in prose, the agent could summarize, skip, or reinterpret it.
+
+DS4 set out to make Ariad operational as runtime behavior. The goal was not autonomy for its own sake. The goal was a Driver that can move with discipline while preserving the Navigator's decisions at the points where product judgment, validation, debt, history, and release boundaries matter.
+
+## What Changed
+
+Builder now supports the complete Ariad story lifecycle:
+
+```text
+Pull -> Prepare -> Expand -> Plan -> Approve -> Implement -> Validate -> Debt Review -> Coherence -> Done
+```
+
+Delivery Stories are no longer directly implementable. Pulling a Delivery Story prepares and expands it into implementable User/Technical Stories, materializes the relevant story package, and stops for the next story confirmation. Plan belongs only to implementable stories, creates `index.md`, `plan.md`, and `test-guide.md`, and blocks implementation until `approve-plan` records an explicit approval event.
+
+Post-implementation gates are now deterministic. `validate-item` separates automated checks, E2E evidence, Navigator validation route, and explicit Navigator acceptance. `review-item` names debt findings and the Navigator debt decision before Coherence. `coherence-item` verifies process, project, and product alignment. `done-item` records history action, roadmap/story package update, and next Ariad movement.
+
+Surfaces became method-level runtime artifacts. The Ariad surface transport contract says that marked surfaces are returned verbatim and interpretation comes only after the block. This closed the gap where a successful runtime transition could be summarized conversationally instead of shown as the deterministic evidence surface.
+
+Cadence also became explicit. `stepwise` supports phase-by-phase dogfooding, `checkpoint` supports ordinary hard-gate flow, `accelerated` can continue through safe soft stops, and `autonomous` requires explicit Navigator limits. Higher-autonomy cadence changes stop frequency; it does not weaken Plan approval, validation acceptance, debt decisions, unsafe-operation boundaries, push/release policy, or Done/history boundaries.
+
+## Conscious Exclusions
+
+- No durable versioned debt ledger yet. DS5 continues with ledger and Refactor-loop work.
+- No pay-now Refactor loop yet. Pay-now debt remains blocked before Coherence until that loop exists.
+- No project-local `.ariad/config.yml` preference overrides yet. DS8 owns method preferences and effective policy resolution.
+- No release automation or push-policy enforcement beyond the current runtime and process boundaries.
+- No retroactive migration of every existing CV20 story artifact into Ariad's final story package shape.
+
+## What We Learned
+
+Dogfooding was not a side activity; it was the design method. The most important fixes came from places where the agent behaved plausibly but not methodologically: treating a Delivery Story as directly plannable, counting a validation route as validation acceptance, or summarizing a surface instead of transporting it. Each time, the fix was to move the rule from conversational habit into runtime state, method data, or deterministic surface protocol.
+
+The cadence work also clarified a useful principle: autonomy is not permission to cross judgment. Ariad can move faster when evidence is present, but the Navigator's gates remain the structure that makes the speed safe.
+
+## Next Horizon
+
+The next natural layers are governance, not basic lifecycle. DS5 can make technical debt durable through a versioned ledger and Refactor loop. DS8 can make Navigator and project preferences first-class method configuration through canonical defaults, local overrides, and effective-policy inspection. After this release, the Builder Mode Evolution journey itself is ready to adopt Ariad prospectively and dogfood those next stories with the runtime it just produced.

package/docs/releases/v0.28.0.md

@@ -0,0 +1,59 @@
+---
+digest: >
+  v0.28.0 is the Ariad Delivery Story lifecycle release. It makes
+  delivery_story flow a first-class Builder Mode path: the Navigator can choose
+  Delivery Story cadence, approve an aggregate DS Plan, validate and close the
+  DS as one lifecycle unit, and inspect canonical checkpoint artifacts and
+  visual Ariad surfaces throughout the flow.
+---
+
+# v0.28.0 — Ariad Delivery Story Lifecycle
+
+**Date:** 2026-06-16
+
+## Highlights
+
+- Adds Navigator flow-unit selection between `story_by_story` and `delivery_story`.
+- Persists Delivery Story lifecycle state, child work packages, and aggregate checkpoint status.
+- Adds aggregate Delivery Story Plan, approval, validation, debt review, coherence, and done runtime checkpoints.
+- Materializes DS-level `plan.md`, `validation.md`, `review.md`, `coherence.md`, and `done.md` artifacts in canonical roadmap packages.
+- Brings DS-level Ariad surfaces into the visual card grammar, including Builder resume, pull candidates, flow-unit selection, DS Plan, and DS closure.
+- Hardens the sandbox reset fixture so `/Users/alissonvale/Code/sandbox-pet-store` reliably includes its operational `REFERENCE.md`.
+
+## Where We Started
+
+`v0.27.0` made Ariad operational for story-by-story Builder delivery, but Delivery Stories still behaved mostly as expansion containers. That preserved safety, yet it created friction for cohesive work where the Navigator wants to validate the whole Delivery Story rather than approve and close every child User or Technical Story separately.
+
+Dogfooding made the missing layer visible. A Delivery Story needed to become a selectable Navigator-facing flow unit without erasing child story traceability. The runtime also needed to stop treating DS-level checkpoints as transient console output: Plan and closure evidence had to land in the same canonical package where the roadmap says the DS lives.
+
+## What Changed
+
+Builder now supports two Ariad Navigator flow units:
+
+```text
+story_by_story  -> child User/Technical Stories are Navigator-facing lifecycle units
+delivery_story  -> parent Delivery Story is the Navigator-facing lifecycle unit
+```
+
+In `delivery_story` flow, child stories remain visible as Driver work packages and evidence units, while the Navigator approves the aggregate DS Plan and validates the aggregate DS outcome. The runtime persists the chosen flow unit, child work items, and aggregate checkpoint status in the delivery cursor so Builder can resume the DS lifecycle coherently.
+
+The DS Plan and closure lifecycle is now materialized. `plan-delivery-story` writes `plan.md`; DS validation, review, coherence, and done write `validation.md`, `review.md`, `coherence.md`, and `done.md` in the canonical Delivery Story package. Path resolution prefers existing roadmap packages so the runtime does not create synthetic fallback paths when canonical docs already exist.
+
+The release also tightens Navigator experience. Previously some newer Ariad surfaces were valid transport blocks but rendered as plain structured text. They now use the same visual card grammar as the core lifecycle surfaces, including `BUILDER_RESUME`, `PULL_CANDIDATES`, `NAVIGATOR_FLOW_UNIT`, `DELIVERY_STORY_PLAN_CHECKPOINT`, and `DELIVERY_STORY_CLOSURE_CHECKPOINT`.
+
+## Conscious Exclusions
+
+- No automated push or release policy is introduced here. CV20.DS6 owns commit/push/release governance.
+- No durable debt ledger or pay-now Refactor loop is introduced here. CV20.DS7 owns that layer.
+- No project-local Ariad preference override file is introduced here. CV20.DS8 owns method preferences and effective-policy resolution.
+- Delivery Story flow does not erase child story evidence; it changes the Navigator-facing lifecycle unit only.
+
+## What We Learned
+
+The important distinction is now explicit: User/Technical Stories can be Driver work packages while the Delivery Story is the Navigator's validation surface. That lets Builder preserve engineering traceability without forcing the Navigator to experience every internal unit as a separate product checkpoint.
+
+The dogfood session also exposed a visual-contract lesson. Marked Ariad blocks are necessary but not sufficient; a Navigator-facing surface should also follow the visual grammar. Several surfaces were corrected during validation, which suggests a future refactor toward a shared Ariad card renderer instead of module-local formatting helpers.
+
+## Next Horizon
+
+The next release boundary is governance. CV20.DS6 should make commit, push, and release intent explicit in Builder Mode, separating local history from remote publication and stable promotion. After that, CV20.DS7 can make technical debt decisions durable through a ledger and Refactor loop.

package/docs/releases/v0.29.0.md

@@ -0,0 +1,61 @@
+---
+digest: >
+  v0.29.0 is the Ariad Refinement Workbench release. It makes Refinement a
+  first-class Builder Mode work field beside Delivery: Builder Home shows
+  Workbench state, Refinement Stories and Change Requests persist durably,
+  Navigators can compose and pull RSs, traverse CR cycles, and close RS arcs
+  with validation evidence preserved while roadmap Delivery remains untouched.
+---
+
+# v0.29.0 — Ariad Refinement Workbench
+
+**Date:** 2026-06-17
+
+## Highlights
+
+- Adds Builder Home work fields for Delivery and Refinement, with Workbench state visible during activation.
+- Persists Refinement Stories, Change Requests, and active Refinement cursor state in durable SQLite tables.
+- Adds conversational and CLI support for creating RSs, capturing CRs, attaching CRs, showing RS overviews, and pulling an RS into active Refinement Work.
+- Adds CR lifecycle transitions: select, confirm, plan, mark implemented, validate, and done note.
+- Adds RS lifecycle transitions: review, coherence, and close.
+- Guards RS closure so unfinished CRs cannot be closed silently; CRs must be done, parked, rejected, or promoted.
+- Extends sandbox reset so Workbench stories, change requests, and cursors clear between dogfooding runs.
+
+## Where We Started
+
+`v0.28.0` made Delivery Story flow a first-class Ariad Builder path, but every adjustment still had to live either in roadmap Delivery or in conversational memory. Dogfooding exposed a different kind of work: small or emergent care for existing capability. These requests were real enough to need confirmation, validation, and closure, but too local to deserve roadmap weight.
+
+Ariad already had the conceptual pressure for a third work area. Builder needed the runtime shape: an orientation surface, durable Workbench storage, a way to compose and pull Refinement Stories, a CR cycle for mutations, and RS-level review/coherence/close for the whole refinement arc.
+
+## What Changed
+
+Builder activation now renders a Workbench-aware home surface. The Navigator can see the Delivery field and Refinement field before choosing work. Activation remains orientation only: it does not pull Delivery Work, pull Refinement Work, select CRs, or execute lifecycle work automatically.
+
+The Workbench is durable. Refinement Stories and Change Requests are stored outside roadmap files, with ordering, status, provenance, outcome notes, and active cursor state. Sandbox reset clears this state so dogfooding can start from a clean Workbench.
+
+Refinement composition is now explicit. The Navigator can create an RS, capture CRs, attach existing CRs, inspect an RS overview, and pull an RS into active Refinement Work. Pulling an RS sets the active Refinement Story but deliberately leaves the active Change Request empty.
+
+The CR cycle is now stateful. A CR moves through select, confirm, plan, implementation evidence, validation evidence, and done note. Surfaces show current phase, active cursor state, next conversational move, and the boundary that non-implementation transitions do not mutate files or touch Delivery Work.
+
+The RS can now close coherently. Review and coherence are RS-level checkpoints that do not mutate files. Close requires coherence first and refuses unfinished CRs. When the RS closes, active Refinement state clears while CR outcomes and done notes remain stored.
+
+## Conscious Exclusions
+
+- No release, push, tag, or stable promotion policy was added. That remains the next Builder governance layer.
+- No full debt ledger or pay-now Refactor loop was added. Follow-up CRs remain in the Workbench until the debt-ledger story provides durable debt workflow.
+- No automatic CR clustering or AI-suggested RS composition was added.
+- No web UI for the Workbench was added.
+- No quick-refinement shortcut was added as a single atomic command; the composed path is available through RS create, CR capture, and RS pull.
+- Refinement does not promote CRs to Delivery automatically. Promotion remains an explicit Navigator decision.
+
+## What We Learned
+
+Refinement is not lighter because it is less disciplined. It is lighter because the unit of commitment is smaller and the roadmap stays clean. The Workbench gives Builder a place to hold care without inflating every friction into Delivery.
+
+The key boundary is the active field. Roadmap items enter Delivery Work. Workbench items enter Refinement Work. Builder Home became the place where that distinction is visible before execution begins.
+
+The dogfood cycle also confirmed that surfaces need to carry state, not just report commands. The Navigator needs to see which CR phase or RS phase is active, what evidence was recorded, what the next move is, and whether files or Delivery state changed.
+
+## Next Horizon
+
+The next release boundary is release and push governance. Builder now has Delivery and Refinement lifecycle closure, but ordinary Done must remain separate from commit, push, tag, stable promotion, and release authorization. CV20.DS7 should make those policies explicit and inspectable.

package/docs/releases/v0.29.1.md

@@ -0,0 +1,59 @@
+---
+digest: >
+  v0.29.1 is a Windows compatibility hardening patch. It preserves Mirror's
+  Claude Code and plugin skill surfaces on filesystems that cannot store colon
+  characters, keeps UTF-8 runtime output safer on Windows consoles, and adds an
+  explicit backup-gated repair command for historical Portuguese mojibake in
+  local SQLite text. It also normalizes path rendering in runtime, Builder,
+  Explorer, extension, and web surfaces without changing the public command
+  names users invoke.
+---
+
+# v0.29.1 — Windows Compatibility Hardening
+
+**Date:** 2026-06-25
+
+## Highlights
+
+- Renames committed Claude skill directories from `mm:*` to Windows-safe `mm-*` while preserving `name: "mm:*"` in each `SKILL.md`.
+- Generates the canonical Claude plugin with Windows-safe skill directories while preserving the same Claude command names in skill frontmatter.
+- Adds Windows-safe external extension skill materialization, including opportunistic cleanup from legacy `ext:*` directories to `ext-*` directories when the legacy directory belongs to Mirror.
+- Prefers UTF-8 stdout and stderr at the `python -m memory` entrypoint so Unicode runtime surfaces remain printable on Windows consoles.
+- Adds `python -m memory repair-encoding` as an explicit dry-run/apply command for reversible UTF-8/Windows mojibake in user text, with backup before mutation.
+- Normalizes path display in runtime, Builder, Explorer handoff, web command, and web preference surfaces so rendered contracts use forward-slash paths consistently.
+
+## Where We Started
+
+A Windows local installation exposed two compatibility gaps. The repository still carried Claude skill directories such as `.claude/skills/mm:build`, which are valid on macOS and Linux but invalid on NTFS. The runtime also surfaced historical Portuguese text that had been stored as mojibake, for example `é`, `ç`, and `ã`, after older Windows/local-runtime combinations decoded UTF-8 through legacy code pages.
+
+The first risk was structural: solving Windows by deleting Claude skills would make the checkout portable but weaken the Claude runtime surface for everyone. The second risk was data-related: repairing mojibake automatically during startup or update would mutate user-owned memory without review.
+
+## What Changed
+
+Mirror now separates command identity from filesystem identity. Claude command names remain `mm:*` in `SKILL.md` frontmatter and user-facing documentation, but the committed directories use Windows-safe `mm-*` names. The same rule applies to the canonical Claude plugin generated under `plugins/mirror-mind/skills/`.
+
+External extension materialization now uses filesystem-safe directories too. A Claude extension command such as `ext:review-copy` is stored under `ext-review-copy` on disk while the catalog continues to record the runtime command name. Install, expose, and uninstall paths know how to remove legacy `ext:*` directories when the legacy `SKILL.md` declares the same command or safe label, avoiding duplicate stale surfaces without deleting unrelated user-authored directories.
+
+The runtime entrypoint now prefers UTF-8 output streams when possible. This keeps Mirror's Unicode cards, symbols, and Portuguese text printable in Windows console contexts while leaving capture streams and already-UTF-8 environments alone.
+
+The new `repair-encoding` command handles historical database text explicitly. It scans known user-text columns, previews each reversible repair by default, and applies changes only with `--apply`. The apply path creates a database backup first unless the user explicitly opts out with `--no-backup`.
+
+Several rendered path fields now use forward-slash display consistently. This keeps Ariad and web/runtime surfaces stable across platforms while leaving real filesystem operations under `Path` control.
+
+## Conscious Exclusions
+
+- No automatic database text repair runs during startup, diagnosis, or runtime update.
+- No attempt is made to repair irrecoverable replacement-character corruption or arbitrary extension tables.
+- No user-facing Claude command names were changed; `/mm:build`, `/mm:mirror`, and the rest remain the semantic command surface.
+- No hosted or cross-device Windows synchronization behavior was added.
+- No broader TypeScript port or runtime packaging change is included in this patch.
+
+## What We Learned
+
+Windows compatibility is not only an operating-system detail. It forces a clearer boundary between semantic names and filesystem names. Command names can keep the language users and runtimes understand, while directories use a portable representation.
+
+Data repair needs a different posture from runtime hardening. Encoding defaults can be improved automatically because they affect future output. Historical user text belongs to the user, so repair must remain visible, previewable, and backup-gated.
+
+## Next Horizon
+
+The next compatibility horizon is release-channel validation: stable updates should carry the Windows-safe skill layout and repair command through the same self-update path real users run. Longer term, CV21 and CV22 continue the runtime packaging and TypeScript-port work that will reduce platform-specific seams further.

package/docs/releases/v0.29.2.md

@@ -0,0 +1,59 @@
+---
+digest: >
+  v0.29.2 is the Ariad Builder flow refinement release. It sharpens the
+  Refinement and Delivery surfaces introduced in the previous Builder releases,
+  replacing metadata-heavy cards with compact Navigator-facing orientation,
+  stable RS/CR display codes, deterministic lifecycle ribbons, and clearer
+  handoffs through validation, debt review, Done, and project position. It also
+  separates raw roadmap inspection from narrative project orientation while
+  preserving artifact traceability and release/push boundaries.
+---
+
+# v0.29.2 — Ariad Builder Flow Refinement
+
+**Date:** 2026-07-02
+
+## Highlights
+
+- Adds stable human-readable Refinement Story and Change Request display codes such as `RS001` and `CR021`, backed by a database migration while preserving internal ids for storage and diagnostics.
+- Simplifies Refinement Work and Delivery Work surfaces so lifecycle ribbons appear only on real flow events and cards prioritize Navigator orientation over form-like metadata.
+- Adds `PROJECT_POSITION` as the narrative orientation surface for Builder activation and Done completion while preserving `ROADMAP_SNAPSHOT` as the raw roadmap inspection surface.
+- Centralizes artifact reporting through `ARTIFACTS_MATERIALIZED`, keeping lifecycle cards readable while retaining created/updated/existing file traceability.
+- Folds Delivery Coherence into Done verification, clarifies validation-to-debt-review and no-action-debt-to-Done handoffs, and requires confirmation before final Done closure.
+- Adds development/test environment visibility to the status line so local dogfooding sessions are easier to distinguish from production use.
+
+## Where We Started
+
+`v0.29.0` made Ariad Refinement Work real inside Builder Mode. Dogfooding immediately exposed a second-order problem: the system could move through the right states, but many cards still felt like internal records rather than conversational orientation surfaces. Opaque ids leaked into Navigator-facing views, lists mixed active work with closed work, lifecycle ribbons appeared on surfaces that were only inspections, and Delivery closure still treated Coherence as a separate stage instead of a Done responsibility.
+
+At the same time, Builder activation and Done completion needed a better sense of position. Showing a raw roadmap table was useful when explicitly inspecting the roadmap, but it was too blunt as the final word after a story closed. The Navigator needed a compact answer to: where are we now, what just moved, and what looks next?
+
+## What Changed
+
+Refinement Work now speaks in stable display codes. Refinement Stories and Change Requests receive persisted `RS###` and `CR###` codes, with migrations that backfill existing Workbench rows and unique indexes per journey. The runtime still keeps opaque internal ids for storage and CLI/debug cases, but Navigator-facing surfaces use the readable codes.
+
+The Refinement cards were tightened around flow semantics. Overview, capture, query, and orientation surfaces no longer pretend to be lifecycle events. Real transitions still show ribbons, but static inspection surfaces stay quiet. Done items render after active/actionable work, and status marks use consistent colored square grammar.
+
+Delivery Work received the same dogfooding pressure. Plan approval now explicitly begins implementation, plan and validation cards are more compact, artifact paths moved out of lifecycle cards into `ARTIFACTS_MATERIALIZED`, and flow-unit selection became a scope confirmation rather than duplicated state output. Validation acceptance can hand off to Debt Review, no-action Debt Review can hand off to Done confirmation, and Done now performs the coherence responsibility internally.
+
+The roadmap/orientation split is now explicit. `ROADMAP_SNAPSHOT` remains the raw inspection surface for commands that ask to see the roadmap. `PROJECT_POSITION` is the narrative orientation surface used at Builder activation and at the end of Done. Done completion can now say what just moved and still leave the Navigator oriented toward the next pull.
+
+A small runtime orientation improvement also entered this release: the status line now shows `development` or `test` when the runtime environment is not production. That change is intentionally included because this release was driven by local dogfooding and needs clearer environment awareness.
+
+## Conscious Exclusions
+
+- This release does not publish new Delivery Story functionality beyond the Builder/Ariad flow refinements described here.
+- Refinement Work is not yet fully governed by Ariad method DSL data; CV20.DS11 records that as the next governance story.
+- Refinement phase outputs are not yet materialized as durable project artifacts; CV20.DS12 records that artifact trail as future work.
+- The global project-wide `mypy src` debt is not resolved here. Focused mypy on the touched Builder/runtime modules is clean, and the global diagnostics were confirmed to be preexisting.
+- Push, tag creation, stable promotion, and GitHub Release publication remain explicit release operations, not Builder Done side effects.
+
+## What We Learned
+
+Dogfooding surfaces is different from proving state machines. The underlying lifecycle can be correct while the Navigator still feels lost. A good Builder surface should not expose every field the runtime knows; it should preserve the current decision, the boundary, and the next possible move.
+
+The work also clarified the distinction between inspection and orientation. A roadmap table is valuable when the user asks for the roadmap. At an activation or Done boundary, the better surface is narrative position: the current focus, the movement that just happened, and the available path.
+
+## Next Horizon
+
+The next Builder horizon is governance and durability. CV20.DS11 should move Refinement lifecycle semantics into inspectable Ariad method data, and CV20.DS12 should give Refinement Work a durable artifact trail comparable to Delivery Story packages. Release and push policy also remain visible as a separate governance layer: Builder can close work, but public publication stays an explicit human-authorized operation.