mirror-mind 0.0.1 → 0.33.0

package/.pi/skills/mm-consolidate/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: "mm-consolidate"
+description: Scans memories for recurring patterns and proposes consolidation (merge, identity update, or shadow candidate)
+user-invocable: true
+---
+
+# mm-consolidate
+
+Consolidation as integration — the operation that promotes raw extracted memories into
+structural identity content (CV7.E4.S3).
+
+Memories accumulate over time. Patterns repeat. The same insight lands in five conversations
+as five isolated memories, none of which reaches the identity layer where it could actually
+change how the mirror responds. Consolidation is the bridge. This skill surfaces those
+clusters, proposes a structural move, and waits for explicit acknowledgment before writing
+anything.
+
+**Promotion mechanism: manual-by-acknowledgment.** The scan is automatic; the promotion is not.
+Every proposal must be reviewed and accepted (or rejected) before it changes the database.
+This is intentional — identity updates are meaningful acts.
+
+---
+
+## Usage
+
+```
+/mm-consolidate [--journey <slug>] [--layer <layer>] [--limit <n>]
+/mm-consolidate apply <proposal_id>
+/mm-consolidate reject <proposal_id>
+/mm-consolidate list [--status pending|accepted|rejected]
+```
+
+---
+
+## 1. Scan for proposals
+
+> The scan answers from TypeScript against the live provider (CV22.DS8.TS2). Each cluster is one model call bounded by the extraction timeout (`MEMORY_LLM_TIMEOUT_EXTRACTION`, 60 s) with bounded retries, and every successful call leaves a priced `llm_calls` row before its proposal is parsed. A call that fails is logged by class (`outcome=transport_failed kind=…`) in `front-door.log` beside the database.
+
+```bash
+mirror consolidate scan \
+  [--journey <slug>] \
+  [--layer <layer>] \
+  [--limit 5] \
+  [--threshold 0.75]
+```
+
+This clusters semantically similar memories and calls the LLM to propose one of:
+- **merge**: distill a redundant cluster into one sharper memory
+- **identity_update**: encode a persistent pattern into an identity layer (ego/behavior, etc.)
+- **shadow_candidate**: mark a tension/avoidance cluster for the mm-shadow pass
+
+Each proposal is printed and stored with `status='pending'`.
+
+**Default filters:** no journey or layer filter (all memories). Threshold 0.75. Limit 5 proposals.
+
+---
+
+## 2. Present each proposal to the user
+
+For each proposal, show:
+- The source memories (title, type, date)
+- The proposed action and target (if identity_update: which layer/key)
+- The rationale
+- The proposed content
+
+Ask: **accept as-is / edit / reject?**
+
+---
+
+## 3. Apply or reject
+
+**Accept as-is:**
+```bash
+mirror consolidate apply <proposal_id>
+```
+
+**Accept with edited content:**
+```bash
+mirror consolidate apply <proposal_id> \
+  --content "User-revised version of the proposed content"
+```
+
+**Reject:**
+```bash
+mirror consolidate reject <proposal_id>
+```
+
+What happens on acceptance:
+- **merge**: creates a merged memory; source memories advance to `integrated`
+- **identity_update**: appends to the identity layer; source memories advance to `acknowledged`
+- **shadow_candidate**: source memories advance to `candidate` for the next mm-shadow pass
+
+Rejected proposals leave source memories unchanged.
+
+---
+
+## 4. List consolidation history
+
+```bash
+mirror consolidate list [--status pending|accepted|rejected] [--limit 20]
+```
+
+---
+
+## Notes
+
+- The skill uses the same model as extraction (Gemini Flash via OpenRouter). LLM calls are
+  logged to `llm_calls` when `MEMORY_LOG_LLM_CALLS=1`.
+- Proposal IDs can be abbreviated to their first 8 characters.
+- Memories with `readiness_state='integrated'` are excluded from clustering.
+- Run with `--threshold 0.65` to surface more (and looser) clusters; raise to `0.85` for tighter ones.
+- For shadow-specific work, use `mm-shadow` (CV7.E4.S4) after candidates are established.

package/.pi/skills/mm-consult/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: "mm-consult"
+description: Asks other LLMs through OpenRouter with Mirror identity context
+user-invocable: true
+---
+
+# Consult
+
+Sends prompts with Mirror identity context to other models through OpenRouter.
+
+## Syntax
+
+```
+/mm-consult <family> [tier] ["question"]
+/mm-consult credits
+```
+
+- **family:** `gemini`, `grok`, `deepseek`, `openai`, `claude`, `llama`, or a direct model ID
+- **tier:** `lite` (default), `mid`, `flagship`
+- **question present:** send it directly
+- **question missing:** synthesize the current conversation and create the prompt
+
+## Flow
+
+> The model call answers from TypeScript, bounded by the extraction timeout (`MEMORY_LLM_TIMEOUT_EXTRACTION`, 60 s) with bounded retries. (The 10-minute ceiling CR072 added applied only to the Python engine, which is gone.)
+
+### Explicit Question
+
+Analyze the message to determine persona and journey using Mirror routing.
+
+```bash
+mirror consult FAMILY TIER "QUESTION" \
+  [--persona PERSONA] [--journey JOURNEY] [--org]
+```
+
+**Examples:**
+- `/mm-consult gemini lite "draft an opening for this article"` → `mirror consult gemini lite "draft an opening for this article" --persona writer`
+- `/mm-consult deepseek "is this design overengineered?"` → `mirror consult deepseek "is this design overengineered?" --persona engineer`
+
+The script prints the response, cost, and balance. Always show the complete response to the user without summarizing or omitting it.
+
+### No Question
+
+When the user omits the question, synthesize Mirror Mode content (reflection, strategy, content — not Builder Mode code or architecture) into a self-contained prompt, then call:
+
+```bash
+mirror consult FAMILY TIER "SYNTHESIZED_PROMPT" \
+  [--persona PERSONA] [--journey JOURNEY] [--org]
+```
+
+The synthesized prompt must be self-contained — the external LLM has no access to the conversation.
+
+## Credits
+
+```bash
+mirror consult credits
+```
+
+Shows OpenRouter usage and remaining balance.
+
+## Available Families And Tiers
+
+| Family | Lite | Mid | Flagship |
+|---------|------|-----|----------|
+| gemini | gemini-2.5-flash-lite | gemini-2.5-flash | gemini-2.5-pro |
+| grok | grok-3-mini | grok-3 | grok-4.1-fast |
+| deepseek | deepseek-chat | deepseek-v3.2 | deepseek-r1 |
+| openai | gpt-5.4-nano | gpt-5.4-mini | gpt-5.4 |
+| claude | haiku-4.5 | sonnet-4.6 | opus-4.6 |
+| llama | llama-3.3-70b-instruct | llama-4-scout | llama-4-maverick |

package/.pi/skills/mm-conversations/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: "mm-conversations"
+description: Lists recent conversations from the memory database
+user-invocable: true
+---
+
+# Conversations
+
+When receiving `/mm-conversations [--limit N] [--journey SLUG] [--persona NAME]`: the plain
+listing is answered by the TS core (CV22.DS7.US1).
+
+```bash
+mirror conversations [args]
+```
+
+Present the output to the user without modification.

package/.pi/skills/mm-discard/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: "mm-discard"
+description: Discards the current runtime conversation from the Mirror database before quitting
+user-invocable: true
+---
+
+# Discard Current Conversation
+
+Use when the user wants to quit a test session without keeping the current
+conversation in the Mirror database.
+
+Natural language examples:
+
+```text
+sair descartando esta conversa
+fechar sem salvar esta conversa
+quit and discard this conversation
+```
+
+## 1. Discard Current Conversation
+
+Run:
+
+```bash
+mirror conversation-logger discard-current --interface pi
+```
+
+The command deletes the current conversation and marks the runtime session so the
+assistant confirmation is not logged as a new conversation.
+
+## 2. Tell the User to Quit
+
+After the command succeeds, answer briefly:
+
+```text
+Conversa atual descartada do banco. Pode sair com /quit.
+```
+
+Do not call `mirror log` for this skill.

package/.pi/skills/mm-explore/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: "mm-explore"
+description: Activates Explorer Mode for a journey and loads exploratory context
+user-invocable: true
+---
+
+# Explorer Mode
+
+Activates Explorer Mode for a specific journey. Explorer Mode is a Mirror-native
+lens for uncertainty before construction.
+
+Explorer Mode is active and supports durable exploration, story thickening,
+attractors, experiment proposals, and Builder handoff.
+
+## Usage
+
+Pi and Gemini CLI:
+
+```text
+/mm-explore <journey-slug>
+```
+
+Codex:
+
+```text
+$mm-explore <journey-slug>
+```
+
+Claude Code:
+
+```text
+/mm:explore <journey-slug>
+```
+
+Natural-language equivalents should be treated as the product interface:
+
+```text
+entrar em modo explorador nesta jornada
+abrir exploração em <journey-slug>
+```
+
+## 1. Activate Explorer Mode
+
+```bash
+mirror explore load <slug>
+```
+
+The command:
+
+- activates `△ Explorer Mode` for the journey;
+- renders the Mode Transition Surface (`△ EXPLORER MODE ACTIVE`);
+- sets the journey as sticky context;
+- loads Mirror identity and journey context;
+- resumes the active durable Exploratory Story when one exists;
+- renders `△ EXPLORATORY STORY RESUMED` when resuming;
+- prints Explorer Mode guidance with the active Explorer capability boundary.
+
+## 1.1 Required Surface Rendering
+
+The `explore load` output includes the conversational transition surface. Render
+that surface visibly to the user before continuing with exploratory work. Do not
+recreate it from scratch unless the command failed to render it; copy the
+rendered surface from the command output.
+
+After any `mirror explore story ...` command that returns a
+Mirror surface, paste the returned surface as the first visible block in the
+response. Do not summarize, interpret, or paraphrase before rendering it.
+
+Some Explorer story commands wrap required product surfaces with machine-readable
+contract markers:
+
+```text
+[[MIRROR_REQUIRED_SURFACE_BEGIN:<surface-id>]]
+...
+[[MIRROR_REQUIRED_SURFACE_END:<surface-id>]]
+```
+
+When markers are present, render the marked `Mirror` surface content first and do
+not render the marker lines themselves. The markers are a runtime contract, not
+user-facing product copy.
+
+For `story open`, `story thicken`, `story snapshot`, `story attractors`, `story
+experiment`, `story list`, `story archive`, and `story handoff`, the returned
+`△ ...` surface is the primary response. Render it before commentary. Commentary
+may follow only after the surface is visible.
+
+## 2. Work In Explorer Mode
+
+Explorer Mode is active and supports durable exploration, story thickening,
+attractors, experiment proposals, and Builder handoff.
+
+Explorer preserves uncertainty. Builder executes commitment.
+
+While Explorer Mode is active:
+
+- Treat new substantive material as part of the current Exploratory Story unless the user asks for a clear operational action.
+- Preserve tensions, hypotheses, corrections, and emerging story shape.
+- When an Exploratory Story begins, open it with:
+
+```bash
+mirror explore story open <slug> --story "..." --summary "..." --last-card "..."
+```
+
+- Before calling `story thicken`, classify the change as either `narrative/substantive` or `local/refinement`.
+
+- When material substantively changes the accumulated Exploratory Story, thicken it with:
+
+```bash
+mirror explore story thicken <slug> --story "..." --summary "..." --last-card "..." --changed "..."
+```
+
+Use `story thicken` for:
+
+- new or changed attractor;
+- new or changed exploratory hypothesis;
+- new or changed ritual, voice, scope, or product concept;
+- changed experiment or promotion boundary;
+- meaningful correction to the narrative arc.
+
+Do not use `story thicken` for local refinements:
+
+- icon choice;
+- microcopy;
+- wording polish;
+- visual label changes;
+- surface formatting;
+- small naming adjustments that do not change the story;
+- conversational elaboration of an already captured idea.
+
+For local refinements, continue the conversation without updating the story. If uncertain, ask the user whether to preserve the change in the Exploratory Story.
+
+- When the user asks for the attractor, or when a strong directional pull should be proposed visibly, render attractors with:
+
+```bash
+mirror explore story attractors <slug> --attractor "..." --description "..." --status proposed
+```
+
+- When the user corrects an attractor, replace it with the corrected attractor using the same command. Do not accumulate hidden competing interpretations.
+- When the user asks what small experiment tests the attractor, render an experiment proposal with:
+
+```bash
+mirror explore story experiment <slug> --title "..." --description "..." --status proposed
+```
+
+- When the user asks what is currently being explored, render a snapshot with:
+
+```bash
+mirror explore story snapshot <slug>
+```
+
+- When the user asks to see explorations for the active journey, render durable story visibility with:
+
+```bash
+mirror explore story list <slug>
+```
+
+- When the user asks to archive or close the active exploration without promoting it, archive the active story with:
+
+```bash
+mirror explore story archive <slug>
+```
+
+- Render the story surface returned by those commands visibly to the user.
+- Do not promote to Builder or Delivery without explicit user confirmation.
+
+## 2.1 Operational Boundary
+
+Explorer Mode must not directly execute clear operational mutation requests.
+When the user asks to edit files, apply a procedure to documents, create code,
+run implementation commands, mutate roadmap/docs/code, or otherwise change
+project state, do not call Explorer story commands and do not mutate files.
+
+Instead, name the boundary visibly and ask whether to switch to Builder Mode for
+the same journey. Use this response shape:
+
+```text
+△ EXPLORER → BUILDER BOUNDARY
+
+This is operational Builder work, not exploratory thickening. Explorer preserves uncertainty; Builder executes commitment. I can switch to Builder Mode for <slug> and do this there.
+```
+
+Only after the user confirms the switch should Mirror activate Builder Mode with:
+
+```bash
+mirror build load <slug>
+```
+
+Local refinements to the exploration itself, such as microcopy discussion,
+labels, wording, icons, or formatting, remain conversational unless the user
+explicitly asks to preserve them in the Exploratory Story.
+
+## 3. Deactivation
+
+The user should use natural language:
+
+```text
+sair do modo explorador
+voltar ao modo normal
+```
+
+Mirror should then call the contained Explorer operation:
+
+```bash
+mirror explore deactivate
+```
+
+Render the deactivation confirmation visibly to the user. Deactivation leaves the
+explicit Explorer lens and returns to Mirror Mode when journey context remains
+active. It does not clear sticky journey context or promote the exploration to
+Builder. Rendering and clearing the status bar are internal effects, not
+user-facing operations.
+
+## 4. Promotion Boundary
+
+When the user says:
+
+```text
+promover essa exploração para construção
+promover para builder
+isso já está pronto para virar Builder?
+```
+
+Do not switch to Builder silently. First produce a transfer document set and
+render the handoff proposal. If the user asks to include source conversations,
+confirm which conversations should be included before adding raw source evidence.
+When the user names the current or recent conversation rather than an id, inspect
+recent journey conversations with `mirror conversations --journey
+<slug> --limit 5`, show the candidate source evidence, and ask for confirmation.
+Use `--source-conversation <conversation-id>` for reviewed source evidence. Use
+`--include-full-conversation` only after explicit confirmation that raw
+conversation evidence should be written with privacy obfuscation.
+
+```bash
+mirror explore story handoff <slug> --title "..." --summary "..." --editorial-synthesis "..." --source-conversation "<conversation-id>:origin conversation" --include-full-conversation
+```
+
+Render `△ BUILDER HANDOFF PROPOSED` visibly, including the generated document
+paths under `docs/project/explorations/<exploratory-story-slug>/` when available:
+
+```text
+index.md
+exploratory-story.md
+handoff-info.md
+product-design-proposal.md
+full-conversation.md        # only after explicit confirmation
+```
+
+Ask for explicit confirmation. Only after the user confirms should Mirror call:
+
+```bash
+mirror explore story promote <slug>
+```
+
+Promotion activates Builder Mode through the normal Builder load path. If the
+user does not confirm, remain in Explorer Mode and continue thickening the story.

package/.pi/skills/mm-help/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: "mm-help"
+description: Shows available Mirror Mind commands on Pi and Gemini CLI
+user-invocable: true
+---
+
+# Help
+
+Show the user the available commands (same on Pi and Gemini CLI):
+
+## Operating Modes
+
+| Command | What it does |
+|---------|-------------|
+| `/mm-mirror` | Activates ◌ Mirror Mode |
+| | `--persona ID` · `--journey ID` · `--query "terms"` · `--org` |
+| `/mm-build <slug>` | Activates ■ Builder Mode for a journey |
+| `/mm-explore <slug>` | Activates △ Explorer Mode for a journey |
+| `/mm-soul [slug]` | Activates ☾ Soul Mode ritual entry |
+
+## Journeys
+
+| Command | What it does |
+|---------|-------------|
+| `/mm-journeys` | Lists journeys with status and current stage |
+| `/mm-journey [slug]` | Shows detailed status for one or all journeys |
+
+## Memories & Journal
+
+| Command | What it does |
+|---------|-------------|
+| `/mm-memories` | Lists recorded memories |
+| | `--type TYPE` · `--layer LAYER` · `--journey ID` · `--search "text"` · `--limit N` |
+| `/mm-journal "text"` | Records a personal journal entry |
+| | `--journey ID` |
+
+## Tasks
+
+| Command | What it does |
+|---------|-------------|
+| `/mm-tasks` | Lists open tasks |
+| | `--journey SLUG` · `--status STATUS` · `--all` |
+| `/mm-tasks add "title"` | Creates a task |
+| `/mm-tasks done ID` · `doing ID` · `block ID` · `delete ID` | Status changes |
+| `/mm-tasks import [slug]` | Imports tasks from journey paths |
+| `/mm-tasks sync [slug]` | Syncs tasks from external file |
+
+## Weekly Planning
+
+| Command | What it does |
+|---------|-------------|
+| `/mm-week` | Shows the current week view |
+| `/mm-week plan "text"` | Ingests a weekly plan |
+
+## Conversations & Logging
+
+| Command | What it does |
+|---------|-------------|
+| `/mm-conversations` | Lists recent conversations |
+| `/mm-recall ID` | Loads a previous conversation |
+| `/mm-save` | Export conversation (Claude Code only — no Pi transcript) |
+| `/mm-new` | Starts a new conversation |
+| `/mm-discard` | Discards the current conversation from the database before quitting |
+| `/mm-mute` | Toggles conversation logging |
+
+## System
+
+| Command | What it does |
+|---------|-------------|
+| `/mm-backup` | Backs up the memory database |
+| `/mm-seed` | Seeds identity files from the active user home into the database |
+| `/mm-release-notes [latest|vX.Y.Z]` | Shows Mirror Mind release notes |
+| `/mm-update` | Updates the local Mirror runtime through the safe updater |
+| `/mm-help` | Shows this list |

package/.pi/skills/mm-identity/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: "mm-identity"
+description: Read and update identity directly in the database
+user-invocable: true
+---
+
+# Identity
+
+After the initial seed, the database is the source of truth for identity.
+Use these commands to inspect and edit identity directly — no YAML files needed.
+
+## Usage
+
+```
+/mm-identity list [--layer LAYER]
+/mm-identity get <layer> <key>
+/mm-identity set <layer> <key> --content "..."
+/mm-identity edit <layer> <key>
+```
+
+---
+
+## Subcommands
+
+### list
+
+List all identity entries currently stored in the database. Answered by the TS core (CV22.DS7.US1).
+
+```bash
+mirror identity list [--layer LAYER] [--mirror-home PATH]
+```
+
+**Examples:**
+- `mirror identity list` — all entries
+- `mirror identity list --layer ego` — only ego layer
+
+Layers: `self`, `ego`, `user`, `organization`, `persona`, `journey`, `journey_path`
+
+---
+
+### get
+
+Print the full content of one identity entry. Answered by the TS core (CV22.DS7.US1).
+
+```bash
+mirror identity get <layer> <key> [--mirror-home PATH]
+```
+
+**Examples:**
+- `mirror identity get ego behavior`
+- `mirror identity get self soul`
+- `mirror identity get persona engineer`
+
+---
+
+### set
+
+Update identity content directly in the database.
+
+```bash
+mirror identity set <layer> <key> --content "..." [--mirror-home PATH]
+```
+
+If `--content` is omitted, content is read from stdin.
+
+A new `journey` or `persona` key must be kebab-case: lowercase letters, digits,
+and single hyphens, up to 80 characters, such as `product-launch`. Agents put
+these keys into commands, so `set` and `edit` refuse any other new key and name
+one that would work. A key created before this rule keeps working.
+
+**Examples:**
+- `mirror identity set ego behavior --content "Be direct."`
+- `cat new-soul.md | mirror identity set self soul`
+
+---
+
+### edit
+
+Open the current content in `$EDITOR`, edit it, and save back to the database on close.
+
+```bash
+mirror identity edit <layer> <key> [--mirror-home PATH]
+```
+
+**Examples:**
+- `mirror identity edit ego behavior`
+- `mirror identity edit self soul`
+- `mirror identity edit persona engineer`
+
+If no changes are detected, nothing is written. If the file is left empty, the edit is aborted.
+
+---
+
+## When receiving `/mm-identity [subcommand] [args]`
+
+Run the corresponding command above and present the output to the user.

package/.pi/skills/mm-journal/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: "mm-journal"
+description: Records a personal journal entry in the memory database
+user-invocable: true
+---
+
+# Journal
+
+When receiving `/mm-journal "entry text" [--journey SLUG]`:
+
+```bash
+mirror journal "entry text" [--journey SLUG]
+```
+
+The script records the entry, classifies it into a memory layer, and prints the result.
+Present the output to the user without modification.