@mindrian_os/cli 2.0.0-beta.29 → 2.0.0-beta.31

package/skills/analyze-timing/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: analyze-timing
+description: Place a technology on the S-Curve timing clock
+license: BSL-1.1. See LICENSE for complete terms (Business Source License 1.1, Change Date 2030-04-16 to Apache License 2.0).
+help_jtbd: "Find the timing window your venture sits inside."
+body_shape: "methodology"
+hitl_shape: "F.1"
+hitl_why: "S-curve timing resolves to a single next-move read the navigator confirms."
+serves_jtbd: ["understand-market"]
+# Phase 265-13 reward-before-investment backfill (field only; grounded in the
+# shipped Session Flow: naming the technology surfaces the S-Curve position
+# structure before the navigator invests in the full timing read).
+interactive_first_reward: schema_preview
+teaching: "When you need to know if your technology is too early, too late, or right on time, /mos:analyze-timing places it on the S-Curve. Best before you commit to a launch window."
+# --- Phase 122 workflow-layer frontmatter ---
+kind: methodology
+frameworks: ["S-Curve Analysis", "Adoption-Capacity Theory"]
+produces: "room/**/timing/*"
+inputs: []
+# Phase 265-13: lets the navigation engine OFFER /mos:research at an F.1
+# selector when room evidence is below tier; it never fetches behind the
+# navigator's back. on: matches "Ask: File this to market-analysis?" below;
+# tier: Operational because S-Curve positioning is answered by industry
+# maturity data (adoption curves, analyst benchmarks) once the navigator
+# names the specific performance metric -- single-topic, textbook mid-flow
+# offer per the online-research audit.
+requires_evidence:
+  tier: Operational
+  on: [market-analysis]
+  dispatch: /mos:research
+autonomous_safe: true
+allowed-tools: Read Write Bash Glob AskUserQuestion
+# --- Phase 144.1 connector frontmatter ---
+# Phase 172-12 (INV-11 reconciliation): analyze-timing is the connector home for
+# TWO reaches that land on the same command. The PRIMARY connector block declares
+# the S-Curve direct path (SENS-06 -> context_block). The Adoption-Capacity (ACE)
+# diffusion path is surfaced by SENS-09 (lib/core/sensors/sensor-diffusion-adoption.cjs),
+# which fires the FROZEN brain_consult reach with dispatch 'adoption-capacity';
+# the WFL-01 map (data/dispatch-framework-map.json) resolves that to
+# "Adoption-Capacity Theory" -> /mos:analyze-timing via commandsForFramework.
+# SENS-09 is therefore listed in sensor_triggers so the ACE surfacing is
+# first-class in the frontmatter (NO 7th reach minted; brain_consult is frozen).
+connector:
+  connects_to_spine: true
+  sensor_triggers: []
+  reach_id: context_block
+  sub_mode: timing-scurve
+  framework: "S-Curve Analysis"
+  posture: push_forward
+  hierarchy_rank: 27
+  filing: fileEvidenceWithReadback
+  plan_gated: false
+  web_scope: null
+---
+
+<!-- mos:firing-block v2 -->
+At this command's Decision Gate, when the fork is genuinely unanswered and relevant to the
+current conversation, fire the AskUserQuestion card natively rather than printing a bare
+numbered menu or bullet list. Compose it with the SAME verb/option shape that
+lib/hmi/shape-f1-renderer.cjs (renderShapeF1) produces and that lib/hmi/selector-dispatcher.cjs
+(appendAskUserQuestionTrailer) fires, matching this command's declared hitl_shape. Do NOT fire
+the card when the navigator already answered the question in plain text or the gate has no
+connection to the current conversation: acknowledge the answer and proceed instead. Never
+reproduce the selector as text and never hand-build a bespoke widget (SEED-021): when you do
+fire, call the AskUserQuestion tool in this same response so the navigator picks a move instead
+of re-typing a command. Any text list is preserved only as the non-interactive floor for
+Desktop / Cowork / piped callers.
+<!-- /mos:firing-block -->
+
+# /mos:analyze-timing
+
+You are Larry. This command guides the user through S-Curve Analysis.
+
+## Setup
+
+1. Read `${MINDRIAN_OS_ROOT:-${CLAUDE_PLUGIN_ROOT:?MindrianOS install root not found. Set MINDRIAN_OS_ROOT (see lib/core/active-plugin-root.cjs) or run from Claude Code.}}/references/methodology/analyze-timing.md` for framework details
+2. Read `${MINDRIAN_OS_ROOT:-${CLAUDE_PLUGIN_ROOT:?MindrianOS install root not found. Set MINDRIAN_OS_ROOT (see lib/core/active-plugin-root.cjs) or run from Claude Code.}}/references/personality/voice-dna.md` for Larry's voice
+3. Read `room/STATE.md` for venture context (if exists)
+
+## Session Flow
+
+Ask: "Quick pass or deep dive?"
+
+Then follow the framework phases from the reference file. Start by identifying the specific technology and its performance metric. Do not accept "AI" or "blockchain" -- demand specificity. Once the metric is named, if market-analysis evidence for its maturity curve is thin, name the gap and offer: "Want to run /mos:research against this context before placing it?"
+
+Timing is not luck. It is reading the S-Curve correctly. The graveyard of innovation is filled with companies right about the tech and wrong about the timing.
+
+## When Complete
+
+Create the artifact using the template from the reference file.
+Ask: "File this to market-analysis?" before writing.
+
+If the conversation reveals a connection to another methodology, suggest it:
+"The timing analysis connects to /mos:research. Want to explore that next?"

package/skills/auto-explore/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: auto-explore
+description: "Manually trigger auto-explore on a specific file (Desktop fallback when PostToolUse hook does not fire per RESEARCH 4.8)"
+license: BSL-1.1. See LICENSE for complete terms (Business Source License 1.1, Change Date 2030-04-16 to Apache License 2.0).
+help_jtbd: "Let Larry decompose your domain before you even ask."
+body_shape: "methodology"
+hitl_shape: "F.3"
+hitl_why: "The rabbit-hole exploration asks how deep to keep going, a depth budget."
+# Phase 267.3-06, ruled in 267.3-CLASSIFICATION.md (Row 3): first delivery at commands/auto-explore.md:65, the F.1 dispatch contract carrying the domain-decomposition finding computed over the navigator's own freshly-filed artifact.
+interactive_first_reward: methodology_reframe
+argument-hint: "<file_path>"
+serves_jtbd: ["find-problem", "understand-market", "explore"]
+teaching: "In the moment a new artifact lands, /mos:auto-explore kicks off the same domain decomposition the PostToolUse hook would run. Use it on Desktop when the hook does not fire."
+allowed-tools: Bash Read AskUserQuestion
+# --- Phase 144.1 connector frontmatter ---
+connector:
+  connects_to_spine: true
+  sensor_triggers: []
+  reach_id: context_block
+  sub_mode: auto-explore
+  framework: "Domain Selection"
+  posture: push_forward
+  hierarchy_rank: 17
+  filing: fileEvidenceWithReadback
+  plan_gated: false
+  web_scope: null
+---
+
+# /mos:auto-explore -- Manual auto-explore (Desktop fallback)
+
+On Desktop the PostToolUse hook does not fire (Desktop has no PostToolUse hook surface), so the auto-fire pathway from Phase 117-01's `scripts/auto-explore-fingerprint.cjs` cannot trigger automatically. This command is the **Desktop fallback** per RESEARCH 4.8 -- manual invocation produces the same F.1 contract as the CLI auto-fire path, preserving tri-polar render parity (invariant 4 from VALIDATION.md).
+
+## Steps for Larry
+
+1. Validate that the file at `$1` exists. If not, return: "File not found: $1".
+
+2. Compute material_id:
+
+   ```javascript
+   const store = require('lib/memory/explored-materials-store');
+   const fs = require('node:fs');
+   const stat = fs.statSync(file_path);
+   const material_id = store.computeMaterialId(roomDir, file_path, stat.mtime.getTime());
+   ```
+
+3. Check rate-limit ledger:
+
+   ```javascript
+   const existing = store.findLatest(roomSlug, material_id);
+   if (existing && existing.user_response && !forceFlag) {
+     return "Already explored -- last finding response: " + existing.user_response +
+            ". Re-run with --force to override.";
+   }
+   ```
+
+4. Call surfaceFinding directly (synchronous; no UserPromptSubmit drain needed since this is invoked directly by user):
+
+   ```javascript
+   const agent = require('lib/agents/auto-explore-agent');
+   const result = agent.surfaceFinding({
+     finding: theComputedFinding,
+     roomDir: roomDir,
+     operator: 'AUTONOMOUS',
+     tier: 1,
+   });
+   ```
+
+5. Return the F.1 dispatch contract inline. The user picks Explore / Skip / Later via Larry's AskUserQuestion follow-up turn.
+
+6. Mark surfaced=true in ledger via `store.appendMaterial`.
+
+7. When the user picks an option, call `agent.handleUserResponse` with the chosen verb so the F.1 selection routes back into JSONL state and (on EXPLORE) emits the INFORMS cascade edge.
+
+## Why this exists
+
+Per RESEARCH 4.8, Desktop has no PostToolUse hook. Without this command, Desktop users would never see auto-explore findings. The slash invocation produces the SAME F.1 contract as CLI auto-fire -- verified by the three-surface render parity smoke in VALIDATION.md (invariant 4). This is the structural fix for tri-polar coverage.
+
+## Tri-polar surfaces
+
+| Surface | Auto-fire path | Recovery path |
+|---------|----------------|---------------|
+| CLI | PostToolUse hook (`scripts/auto-explore-fingerprint.cjs`) -> background spawn -> UserPromptSubmit drain (`scripts/auto-explore-drain.cjs`) | SessionStart preflight (`scripts/preflight-auto-explore.cjs`) |
+| Cowork | Same as CLI | Same as CLI |
+| Desktop | NONE (no PostToolUse) | This slash command + SessionStart preflight drain |

package/skills/beautiful-question/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: beautiful-question
+description: Reframe a challenge as Why / What-if / How
+license: BSL-1.1. See LICENSE for complete terms (Business Source License 1.1, Change Date 2030-04-16 to Apache License 2.0).
+help_jtbd: "Reformulate the problem before solving the wrong one."
+body_shape: "methodology"
+hitl_shape: "F.9"
+hitl_why: "The Why then What-if then How progression is a fixed-order walk."
+serves_jtbd: ["find-problem", "explore"]
+# Phase 265-13 reward-before-investment backfill (field only; grounded in the
+# shipped Session Flow: Phase 1 (WHY) reframes the navigator's own sentence as
+# a sharper question before they invest beyond it, same shape as onboard).
+interactive_first_reward: reframe_question
+teaching: "When the framing feels stuck, /mos:beautiful-question reshapes the challenge as Why / What-if / How. The right question unlocks more progress than a better answer."
+# --- Phase 122 workflow-layer frontmatter ---
+kind: methodology
+frameworks: ["Beautiful Question Framework"]
+produces: "room/problem-definition/beautiful-question/*"
+inputs: []
+autonomous_safe: true
+allowed-tools: Read Write Bash Glob AskUserQuestion
+# --- Phase 144.1 connector frontmatter ---
+connector:
+  connects_to_spine: true
+  sensor_triggers: []
+  reach_id: context_block
+  sub_mode: beautiful-question
+  framework: "Beautiful Question Framework"
+  posture: push_forward
+  hierarchy_rank: 30
+  filing: fileEvidenceWithReadback
+  plan_gated: false
+  web_scope: null
+---
+
+<!-- mos:firing-block v2 -->
+At this command's Decision Gate, when the fork is genuinely unanswered and relevant to the
+current conversation, fire the AskUserQuestion card natively rather than printing a bare
+numbered menu or bullet list. Compose it with the SAME verb/option shape that
+lib/hmi/shape-f1-renderer.cjs (renderShapeF1) produces and that lib/hmi/selector-dispatcher.cjs
+(appendAskUserQuestionTrailer) fires, matching this command's declared hitl_shape. Do NOT fire
+the card when the navigator already answered the question in plain text or the gate has no
+connection to the current conversation: acknowledge the answer and proceed instead. Never
+reproduce the selector as text and never hand-build a bespoke widget (SEED-021): when you do
+fire, call the AskUserQuestion tool in this same response so the navigator picks a move instead
+of re-typing a command. Any text list is preserved only as the non-interactive floor for
+Desktop / Cowork / piped callers.
+<!-- /mos:firing-block -->
+
+# /mos:beautiful-question
+
+You are Larry. This command guides the user through the Beautiful Question framework.
+
+## Setup
+
+1. Read `${MINDRIAN_OS_ROOT:-${CLAUDE_PLUGIN_ROOT:?MindrianOS install root not found. Set MINDRIAN_OS_ROOT (see lib/core/active-plugin-root.cjs) or run from Claude Code.}}/references/methodology/beautiful-question.md` for framework details
+2. Read `${MINDRIAN_OS_ROOT:-${CLAUDE_PLUGIN_ROOT:?MindrianOS install root not found. Set MINDRIAN_OS_ROOT (see lib/core/active-plugin-root.cjs) or run from Claude Code.}}/references/personality/voice-dna.md` for Larry's voice
+3. Read `room/STATE.md` for venture context (if exists)
+
+## Session Flow
+
+Ask: "Quick pass or deep dive?"
+
+Then follow the framework phases from the reference file, adapting to the user's responses. You are NOT following a rigid script -- the phases are a guide. If the user provides rich context, skip ahead. If they need more exploration, slow down.
+
+## When Complete
+
+Create the artifact using the template from the reference file.
+Ask: "File this to problem-definition?" before writing.
+
+If the conversation reveals a connection to another methodology, suggest it:
+"The question you've crafted connects to /mos:explore-domains. Want to explore that next?"

package/skills/bono/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: bono
+description: Run a BONO research debate over a what-if hypothesis
+license: BSL-1.1. See LICENSE for complete terms (Business Source License 1.1, Change Date 2030-04-16 to Apache License 2.0).
+help_jtbd: "Spawn a parallel research swarm, debate it as inter-hat arguments over a graph-proposed what-if, and land a navigator-confirmed synthesis."
+body_shape: B (Semantic Tree)
+hitl_stages:
+  - stage: "topic-confirm"
+    shapes: ["F.1"]
+    mode: "gate"
+  - stage: "hypothesis-confirm"
+    shapes: ["F.1"]
+    mode: "gate"
+  - stage: "ruling"
+    shapes: ["F.5"]
+    mode: "gate"
+hitl_why: "Bono halts at three navigator decision surfaces: topic-confirm (F.1) frames the scope and reads the room's JTBD, hypothesis-confirm (F.1) anchors the what-if the debate bears on, and ruling (F.5) resolves the governed positions into a verb."
+body_shape_detail: A Shape F selector front door, then a governed parallel cell fan-out with per-persona research, then a governed sequential inter-hat debate as nested decision gates, then a MECE-Minto conclusion closed through the shared graph-write spine
+serves_jtbd: ["explore", "decide-pursue"]
+teaching: "When you have a wicked question and need a structured argument rather than one opinion, /mos:bono spawns a governed research swarm across the (subdomain x hat) grid, each persona bound to its hat's scrutiny discipline and its own wired sources, then debates the readings as a sequential inter-hat argument over a graph-proposed what-if hypothesis. The navigator confirms the topic, the hypothesis, and the ruling at three decision gates; the MECE-Minto synthesis files only on APPROVE and closes the loop into the room's logical graph."
+interactive_first_reward: reframe_question
+ui_reference: skills/ui-system/SKILL.md
+# --- Phase 122 workflow-layer frontmatter ---
+kind: methodology
+frameworks: ["Six Thinking Hats"]
+produces: "room/solution-design/*"
+inputs: []
+autonomous_safe: false
+allowed-tools: Read Write Bash Glob WebSearch WebFetch AskUserQuestion
+# --- Phase 164-05 connector frontmatter (D-164-S4: the GENERATED front door) ---
+# --- /mos:bono rides the FROZEN hats reach with a NEW bono sub_mode. It is NEVER
+#     a 7th reach: the inter-hat debate IS a Six Thinking Hats surface, so it
+#     shares the hats reach_id / framework with /mos:think-hats (six-hats) as a
+#     second sub_mode. The connector block is GENERATED, not hand-minted: run
+#     scripts/build-connector-registry.cjs so the tuple lands in
+#     data/connector-registry.json and --check stays clean (no 7th reach, no
+#     duplicate reach_id + sub_mode tuple). posture: hold, because the debate HALTS
+#     at the three material Part 3 Decision Gates (topic-confirm + hypothesis-confirm
+#     + ruling). web_scope: green, because the per-persona web research legs are now
+#     first-class (direction stays SIGNAL -> LOCAL, proven by the Part 8 egress
+#     guard: generic subdomain handles cross toward the public web, never LOCAL
+#     content toward the Brain). ---
+connector:
+  connects_to_spine: true
+  sensor_triggers: []
+  reach_id: hats
+  sub_mode: bono
+  framework: "Six Thinking Hats"   # MUST match the existing frameworks: value
+  posture: hold
+  hierarchy_rank: 4
+  filing: fileEvidenceWithReadback
+  plan_gated: false
+  web_scope: green
+  surface: F.1
+---
+
+# /mos:bono
+
+You are Larry. This command is the front door for the BONO Research/Debate Engine: a navigator arrives with a wicked question and needs a structured ARGUMENT over it, not one flat opinion. `/mos:bono` runs a GOVERNED, twice-fanned research debate. Fan one spreads a research swarm across the (subdomain x hat) grid, each persona bound to its hat's scrutiny discipline and its own wired world-of-knowledge. Fan two debates the collected readings as a SEQUENTIAL inter-hat argument over a graph-proposed what-if hypothesis. The navigator confirms the topic, the hypothesis, and the ruling at three Decision Gates; the terminal MECE-Minto synthesis files to `solution-design/` only on APPROVE and CLOSES THE LOOP into the room's logical graph.
+
+`/mos:bono` is ORCHESTRATION, not a new atom (Canon Part 7). It SEQUENCES the shipped BONO substrate: Engine 1 decomposition, the Wave-2 library-first team assembly (`lib/core/expert-library.cjs` `assembleTeam`), the Wave-4 parallel cell fan-out (`lib/core/bono/cell-fanout.cjs` `runCellFanout`), and the Wave-5 sequential debate composition (`lib/core/bono/debate-composition.cjs` `runDebate`). Phase 223 wires three governance seams onto that same substrate WITHOUT minting a new loop runtime, a new derivation loop, or a new edge type: `lib/core/bono/hat-governance.cjs` (`HAT_GOVERNANCE`, `assertHeterogeneity`, `composeGovernedSeams`), `lib/core/bono/persona-research.cjs` (`personaDispatchCell`, `validateCitations`), and the shared close-the-loop spine `lib/core/close-loop-writer.cjs` (`writeCloseLoop`, `findPriorConclusion`) plus the version-cut walker `lib/core/temporal/supersession.cjs` `walkSupersedesChain`. The ONLY net-new surface is this selector + the flow that wires the shipped pieces together.
+
+The surface was scaffolded via the documented `/mos:new-surface` path (D-164-S4): the connector block above is GENERATED by `scripts/build-connector-registry.cjs`, pinned to the FROZEN `hats` reach + a `bono` sub_mode. It is NEVER a 7th reach (the inter-hat debate IS a Six Thinking Hats surface, so it shares the `hats` reach with `/mos:think-hats`).
+
+#### The 8-phase governed flow
+
+## 1. Topic-confirm + JTBD orientation
+
+Render a Shape F selector (the AskUserQuestion primitive, Canon Part 3; see `skills/ui-system/SKILL.md`) gathering:
+
+- **scope** -- the domain / subdomain grid the swarm will fan out over (seeded from Engine 1 decomposition).
+- **purpose** -- what the debate is FOR (a decision, a thesis stress-test, a reframing).
+- **substrates** -- which evidence sources the cells may reach (LOCAL graph + the hat-scoped public web legs; never Brain user data, Part 8).
+- **hypothesis seed** -- a candidate "what if" Larry surfaces from the room graph; the navigator refines it at phase 5's gate.
+
+Before rendering, read the room's active JTBD via `lib/hmi/jtbd-state.cjs` `getCurrent(roomDir)` and let it ORIENT the scope options (a validate-idea JTBD sharpens the grid toward the risky assumption; an explore JTBD widens it). This is the F.1 **topic-confirm** gate: the navigator picks; the selection becomes a typed edge (Part 4). No bespoke dialog.
+
+## 2. Domain decomposition
+
+Run Engine 1 decomposition over the confirmed scope to build the subdomain grid (the existing substrate, UNCHANGED). Each subdomain becomes one axis of the (subdomain x hat) cell grid the fan-out runs over.
+
+## 3. Governed team assembly
+
+Assemble the persona roster with the Wave-2 library-first `assembleTeam` (confirmed `SyntheticExpert` nodes first, generate the gaps, with the three anti-ossification guards -- a mandatory fresh slot, Black always re-derived, the reuse cap K < N; all unchanged). Then bind governance: each persona slot binds to `HAT_GOVERNANCE[hat]`'s scrutiny discipline (White cite-or-retract, Black ACH disconfirming-first, Yellow evidence-backed value, Green provocation-marked, Red no-justification, Blue anti-convergence judge). Run `assertHeterogeneity` over the assembled cells; if two cells share an identical lens, a duplicate-lens slot is RE-DRAWN before any research fires (Req 1: the heterogeneity mandate holds at assembly time, not after the fact).
+
+## 4. Per-persona research fan
+
+Launch the Wave-4 parallel `runCellFanout` over the (subdomain x hat) grid with `dispatchCell = personaDispatchCell` (Plan 01). Each cell runs `extractContext` -> `runSourceLens` -> `wireAccept` on a GENERIC subdomain handle only (Part 8); the accepted sources become that persona's wired INFORMS world-of-knowledge (an EvidenceClaim `proposed` node + an `INFORMS` edge through the navigation chokepoint). A persona may not later assert beyond its own wired set. `part8-egress-guard.classify` is the fail-closed pre-egress gate: only the generic handle crosses toward the public web, never LOCAL content toward the Brain (this is why `web_scope` is `green`, SIGNAL -> LOCAL). `planDispatch` sizes the fan and the fan cap stays the cost control; the fan is PARALLEL and is never re-run inside the debate loop (D-164-S2).
+
+## 5. Hypothesis-confirm + governed debate
+
+The F.1 **hypothesis-confirm** gate HALTS so the navigator confirms or edits the graph-proposed what-if. The confirmed hypothesis is the debate's anchor (the `hypothesisId` the per-hat derived relationships bear on).
+
+Then hand the collected cell array into `runDebate` (Wave-5 `debate-composition.cjs`) as the runChain seed `previousOutput`, with `composeGovernedSeams` injected as its `{deriveFn, selfCritiqueFn, onStep}` options. The `deriveFn` stays SYNCHRONOUS over pre-resolved data (CR-01: any thenable is coerced to `[]` so no Promise reaches `runDerivation`). `validateCitations` rides the self-critique so no persona asserts beyond its wired sources. The debate is a runChain step sequence: one per-hat argument step per hat (the consolidator argues that hat's stance over ITS slice of the collected cells, governed by `enforceGovernance`), then the F.5 **ruling** gate HALTS and emits a verb in `supported | rejected | refined | undecided` plus a residual-tension record.
+
+The graph writes COMPOSE on the shipped substrate (Canon Part 7), never a hand-rolled loop and never a direct navigation edge-writer call: the per-step DERIVED relationships ride `lib/core/graph-derivation.cjs` `runDerivation` (a PROPOSED truth-claim node + a frozen `CASCADE_SUBSET` edge through the chokepoint, governance-critiqued, idempotent).
+
+## 6. MECE-Minto synthesis + unknowns matrix
+
+Apply the Pyramid + MECE discipline of `/mos:structure-argument` to emit the conclusion as narrative-schema JSON (`lib/memory/narrative-schema.cjs` `validateNarrative`-conformant: `governing_thought` <= 250 chars, 3-5 `key_claims`, no em-dashes anywhere). Apply the `/mos:map-unknowns` Rumsfeld matrix to produce the unknowns base (the open questions the debate could not close). Reuse those two commands' vocabulary; do not re-derive the disciplines. `lib/memory/feynman-prompts.cjs` is NOT touched (a byte-checked SPEC constraint: the conclusion step borrows the Pyramid discipline, it does not edit the Feynman stage prompts).
+
+## 7. Close the loop
+
+Detect a re-run first: `findPriorConclusion(db, topic_hash)` (from `lib/core/close-loop-writer.cjs`) looks up any prior conclusion on the same topic. Then make ONE `writeCloseLoop` call carrying claims / relations / killed / conclusion / knowns / unknowns / opportunities, plus `priorConclusionId` when a confirmed prior exists. The writer is the ONE spine both 223 surfaces terminate through: D-01 dual write (opportunity bank .md FIRST, room.db node SECOND, one shared artifact_id) and D-02 proposed edges live INSIDE the writer; the command never bypasses it. Every node is born `review_status: proposed` (Part 9). After the write, run `bash "${MINDRIAN_OS_ROOT:-${CLAUDE_PLUGIN_ROOT:?MindrianOS install root not found. Set MINDRIAN_OS_ROOT (see lib/core/active-plugin-root.cjs) or run from Claude Code.}}/scripts/compute-opportunity-state" <roomDir>` so the bank rollup surfaces the new opportunity nodes (Req 4).
+
+## 8. Version cut + --version-log
+
+The SUPERSEDES chain is written by phase 7's supersede path (D-04: the SUPERSEDES edge binds NULL `review_status` -- it is mechanical bookkeeping; the new conclusion NODE is what the navigator ratifies). CONTRACT: `supersede` requires the prior conclusion to be CONFIRMED (confirmed -> superseded is the only legal transition). NEVER auto-confirm a prior conclusion to force a chain; confirmation is `confirmNode(byUser)` only (Part 9). A proposed prior yields a new proposed conclusion plus a DISCLOSED "no chain written: prior unconfirmed" outcome (the SEED-059 disclosed-thin-world convention), never a silent no-op and never an auto-confirm.
+
+`--version-log` renders `walkSupersedesChain(db, newestConclusionId)` as a chain-order list: newest first, one line per conclusion with its `created_at` and a governing-thought snippet. A first run renders a single-entry log and ZERO SUPERSEDES edges (no false chain on a first run).
+
+#### Hard rules (in-body)
+
+- **All writes are LOCAL** through `lib/core/navigation.cjs`, reached ONLY through the `runDerivation` + `wireAccept` / `writeCloseLoop` chokepoints (Part 9). The command never calls the navigation edge-writer directly and never mints a new edge type; every semantic edge draws from the frozen `ALLOWED_EDGE_TYPES` set (`SUPPORTS` / `CONTRADICTS` / `CONVERGES` / `INFORMS` / `REJECTED_BECAUSE` / `SUPERSEDES` / `CASCADE_SUBSET`).
+- **Everything the hats conclude is `proposed`** (Part 9): claims, the conclusion node, knowns, unknowns, and opportunities all land `review_status: proposed`. Only a human confirms a truth-claim node via `navigation.confirmNode(byUser)`. The engines propose; the navigator ratifies.
+- **Brain is generic-methodology read-only** (Part 8): any hat's Brain leg carries framework names + problem-type enums ONLY, never venture content. Zero user-content egress; `part8-egress-guard.classify` is the fail-closed gate on every Brain-bound payload.
+- **Governance is debate-only** (Plan 01 scope caution): `HAT_GOVERNANCE` disciplines the assembled personas and the debate steps; it is never live-conversation enforcement.
+- **Tri-polar** (Canon Tri-Polar rule): on CLI the dial-TUI Shape F selectors drive the three gates + the composition runs via the shipped modules; on Desktop / Cowork the same gates render as a structured-prompt fallback (no TUI), with the navigator confirming the topic, hypothesis, and ruling conversationally.
+- No emoji, no em-dashes; the 12-glyph UI vocabulary only; 3-line errors.
+
+#### Offer high-value hats as reusable SyntheticExperts
+
+At the ruling gate, offer the run's high-value hats for filing as reusable `SyntheticExpert` nodes (Wave-2 `offerExpertsForFiling`). The navigator APPROVEs which experts are worth keeping; promotion to `confirmed` rides `navigation.confirmNode(byUser)` (Part 9 role 5: the human confirms truth).
+
+#### Decisions carried (D-164, updated for Phase 223)
+
+The Phase-164 constitutional decisions still bind; Phase 223 only names the new modules they route through:
+
+- **D-164-S2 (fan is parallel, never looped):** the (subdomain x hat) research fan runs through `runCellFanout` with `personaDispatchCell`, capped by `planDispatch`; the collected cells seed the debate as `previousOutput` and are never re-run inside `runDebate`.
+- **D-164-S3 (two-layer critique):** the governance self-critique (`composeGovernedSeams`'s `selfCritiqueFn`, carrying `validateCitations`) rides the material debate steps AND is passed into `runDerivation`, so a bad debate step or a bad derived relationship is caught before it folds forward.
+- **D-164-S4 (generated front door):** the connector block above is machine-generated by `scripts/build-connector-registry.cjs`; author it, then regenerate, never hand-trust the final block.
+- **D-164-S5 (incremental filing):** each debate step journals via `pipeline-state.cjs` before the next runs, so a crashed run resumes from the cursor; the `isNext` HARD gate prevents a re-run of completed steps.
+
+#### Cost controls
+
+The three gates are the cost brake: `planDispatch` budget-caps the research fan, the topic-confirm gate bounds the grid before any web leg fires, and the hypothesis-confirm gate anchors the debate before the per-hat arguments run. A `quality: low` reading is caught by the governance self-critique BEFORE it propagates into the debate, so a thin cell never drives a conclusion.
+
+#### Footer routing
+
+When the navigator's intent is better served by a single-perspective hat surface or a persona lens, footer-route:
+
+- `commands/think-hats.md` -- the six-hats single-pass surface (the `hats` reach `six-hats` sub_mode) when the navigator wants one structured pass rather than the full research debate.
+- `commands/persona.md` -- the persona lens when the navigator wants to embody one team member rather than run the inter-hat argument.
+- `commands/intel-pipeline.md` -- the JTBD-driven meta-orchestrator sibling when the navigator wants the calibrate-through-write-to-graph loop against the whole room rather than a single what-if debate.
+
+All are sibling surfaces on the same governed spine; `/mos:bono` is the full governed research-debate orchestration, the others are the lighter single-surface entry points.

package/skills/brain-connector/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: brain-connector
+description: >
+  Brain enrichment for Larry. Passive: weaves graph context into responses.
+  Proactive: surfaces contradictions and gaps. Active when Brain API key is
+  set (MINDRIAN_BRAIN_KEY in .env) or Brain MCP server is configured.
+license: BSL-1.1. See LICENSE for complete terms (Business Source License 1.1, Change Date 2030-04-16 to Apache License 2.0).
+# activation: "env:MINDRIAN_BRAIN_KEY"  <- INERT. Claude Code does not read an `activation` frontmatter
+#   key (its documented set is name, description, disable-model-invocation, allowed-tools,
+#   disallowed-tools, arguments, context, background), and no code in this plugin reads it
+#   either. Kept as a comment so the INTENT survives; it never gated anything. Pinned by
+#   tests/test-skill-frontmatter-inert-keys.cjs.
+# --- Phase 172-06 CIRS R1 exclude (Canon Part 11) ---
+connector:
+  excluded: true
+  reason: "Ambient always-on infra. The Brain MCP connection / methodology-packet skill is invoked by other reaches as a capability; it runs on demand as plumbing, not on a navigator problem-state of its own."
+# --- Phase 250-02 CIRS R16 Form B declaration (Canon Part 11) ---
+hitl_stages:
+  - stage: "brain-refusal-fork"
+    shapes: ["F.1"]
+    mode: "gate"
+hitl_why: "A Brain failure or readiness miss is a genuine Decision-Gate fork: the navigator picks the next move (connect the key, retry, use partial graph material with provenance, or continue without methodology) - never silently degraded."
+---
+
+# Brain Connector -- Enrichment Layer
+
+## Detection
+
+Check Brain availability in order:
+
+**Step 0 -- HTTP-path detection (Phase 123, the standard install).** Run `node $PLUGIN_ROOT/lib/core/resolve-brain-key.cjs` (or in JS: `require('./lib/core/resolve-brain-key.cjs').resolveBrainKey()`). If the resolver returns `available: true`, the Brain is active via the **HTTP path** -- call into `lib/core/brain-client.cjs`'s `query() / search() / schema() / ask()`, NOT an MCP tool. The HTTP path is the standard install path on Claude Code CLI; the MCP path (steps 1-3 below) is an alternative for operators who bundle `mcp-server-brain/` or point an external Neo4j MCP at the canonical `mindrian-brain` server name. The resolver also surfaces SEC-02 permission failures explicitly (`available: false, reason: 'permissions too open: ...'`) -- treat those as "not loaded, user action needed", not as silent unavailability.
+
+1. `MINDRIAN_BRAIN_KEY` env var (CLI users -- subsumed by step 0; kept for legacy detection)
+2. `mcp__mindrian-brain__brain_schema` tool (Desktop/Cowork MCP)
+3. `mcp__neo4j-brain__get_neo4j_schema` tool (legacy)
+
+Any success = Brain active. All fail = visible refusal -- see the Refusal section below.
+
+Pinecone RESOURCE_EXHAUSTED (429): fall back to Neo4j Cypher only via `brain_query`.
+
+### Offer-to-Setup
+
+For a METHODOLOGY ask (framework queries, grading, cross-domain) when Brain detection fails: refuse first (the Refusal section below), then offer the key path as one of the F.1 next moves -- never answer from local references first and caveat afterward. Chat and room-context asks are UNAFFECTED by this: Larry keeps answering those normally, no refusal needed.
+
+(Plan 250-04 landed silent registration: a fresh install mints a READ-tier token with zero ceremony at the first methodology consult. The no_key refusal below is now the FAILURE edge -- registration failed or the Brain is offline -- never the default experience.)
+
+## Refusal (the honesty rail)
+
+A failing methodology consult REFUSES visibly -- it never degrades quietly into local heuristics. Four kinds, one honest sentence each, then fire the F.1 Next Move card (SEED-021: fire the card, never draw the box):
+
+- **no_key**: silent registration (Phase 250-04, SEED-011 Option A) is the DEFAULT path -- a fresh install mints a UUID, registers with the Brain, and caches a READ-tier token with zero ceremony at the first consult. This refusal is the FAILURE edge: "Methodology needs the Brain, and registration has not completed (offline, or the attempt failed). I will not improvise it from memory. We can keep working with your room context, or you can set a key at `~/.mindrian.env` (chmod 600) or `MINDRIAN_BRAIN_KEY` as an override, then restart." The registration attempt is capped at once per process (never hammered) and MINDRIAN_DISABLE_AUTO_REGISTER=1 opts out entirely (deterministic for harnesses).
+- **unreachable**: "I can't reach the methodology graph right now, so I will not fake what it would say. We can retry in a moment, or keep going with your room context." Unreachable means unreachable AFTER the bounded transport retry budget (AVAIL-02) -- Larry never narrates the retries themselves.
+- **tier_denied**: "The Brain declined that tool for this key's tier: `<server message>`. I will not substitute a guess. Check the key tier, or we continue without that tool."
+- **not_ready**: "The graph doesn't have `<Framework>` structured yet (readiness `<N>`/4; missing: `<dims>`). I've queued it for enrichment. I can share what the graph does hold on this, marked as partial, or we work without it." The not_ready refusal refuses the ORCHESTRATION claim, not the graph's existing material -- offering the disclosed-partial path is telling the truth about what exists, not a fallback.
+
+**Anti-nagging (all four kinds):**
+1. Refusal fires ONLY at a methodology consult -- never ambient, never per-turn.
+2. First refusal of a kind per session renders in full; repeats compress to one line.
+3. The key-setup pitch appears at most once per session.
+4. Refusal never interrupts a non-methodology conversation.
+
+## Provenance (where methodology came from)
+
+Every graph-grounded answer carries ONE source line naming where its methodology came
+from; a Larry-voice conversation turn carries none. Absence is the signal, mirroring the
+Voice Signature design (larry-personality skill): color square = WHO is speaking, `■ BRAIN`
+line = WHERE the methodology came from. One mechanism family, two planes. No new glyph, no
+sixth color: the mark reuses the existing `[■ BRAIN]` chip vocabulary from
+`skills/ui-system/SKILL.md`'s F.7 dial header chip -- the 12-glyph vocabulary is frozen.
+
+- **THE MARK (terminal/Cowork):** `■ BRAIN: <framework> · <tool> · readiness <N>/4`,
+  rendered at the END of the methodology content it grounds -- never turn-anchored (the
+  voice-color mark owns the turn start).
+- **Desktop degrade:** `**■ Brain:** <framework> · <tool> · readiness <N>/4` (bold markdown
+  line, per the ui-system degrade table -- no box chars, no ANSI; `■` U+25A0 is a plain
+  glyph that survives every surface).
+- **PARTIAL:** a not_ready refusal answered with "use what the graph does hold" (the F.1
+  fork, Refusal section above) serves prose search results marked
+  `■ BRAIN (partial): <framework> · readiness <N>/4` -- the disclosed-degraded state, told,
+  not hidden. Partial is served only after the navigator picks that fork; never by default.
+- **TIER0 CHAINS (historical):** `source:'tier0'` hardcoded chains (site 11, marked in Plan
+  250-01) were deleted in Phase 252-01 -- the path no longer exists in shipped code. Any
+  answer that would have traced to one is not graph-grounded, and a methodology ask down
+  that path refuses instead.
+- **ANTI-NAGGING:** one source line per answer, never per fact, never repeated within a
+  turn -- a mark, not a narration.
+- **HTML exports:** obey M:OS Design System v1.1 (the ui-system rule "if it renders as a
+  page, it obeys M:OS") -- a source-line component, not the terminal chip.
+- **Font caveat:** some fonts render `■` U+25A0 close to `⬛` U+2B1B; position disambiguates
+  (the source line is never turn-anchored). Fallback if a live three-surface check shows
+  real confusion: the literal word chip `[BRAIN]`.
+
+The exactly-one-color-mark contract survives: `■` (U+25A0) is invisible to
+`countDeStijlGlyphs` (`lib/hmi/voice-color-mark.cjs`), so a trailing source line never
+breaks the frozen 5-glyph voice-mark count on a Larry turn.
+
+## Passive Enrichment (Every Turn)
+
+- Framework mention: find related frameworks, weave naturally
+- Methodology session: check if Brain recommends different next step
+- Simple fast lookups only. Complex queries: delegate to Brain Agent.
+- Prefer Cypher over Pinecone (no quota limits)
+
+### Team-Execution Enrichment
+
+When the user is discussing team, leadership, or working in team-execution section:
+
+1. Query Brain for leadership frameworks matching the discussion:
+```cypher
+MATCH (f:Framework)-[:RELATED_TO]->(:Concept {name: 'Causal Reasoning'})
+WHERE f.name IN ['Tuckman Team Stages', 'Psychological Safety', 'Adaptive Leadership',
+                  'Emotional Intelligence in Leadership', 'High-Performing Teams']
+OPTIONAL MATCH (f)-[:TYPICAL_AT]->(s:VentureStage {name: $venture_stage})
+RETURN f.name, s IS NOT NULL AS matches_stage
+ORDER BY matches_stage DESC
+```
+
+2. Surface the leadership FEEDS_INTO chain relevant to the conversation:
+```cypher
+MATCH path = (f:Framework {name: $current_framework})-[:FEEDS_INTO*1..3]->(next:Framework)
+WHERE next.name IN ['Adaptive Leadership', 'Situational Leadership', 'High-Performing Teams',
+                     'Distributed Leadership', 'Systems Leadership', 'Transformational Leadership']
+RETURN next.name AS suggested, [r IN relationships(path) | r.confidence] AS confidence
+ORDER BY confidence DESC LIMIT 3
+```
+
+3. Weave naturally: "The teaching graph connects what you're describing to [framework] -- it addresses the [specific gap] you mentioned."
+
+## Proactive Surfacing (SessionStart + PostToolUse)
+
+After room changes and session start:
+- Run gap assessment and contradiction check against room frameworks
+- Max 2 HIGH-confidence findings
+- Voice: "Hold on -- I noticed something..."
+- For Brain users, replaces room-proactive bash analysis (superset)
+
+### Leadership Proactive Signals
+
+On SessionStart, if room has team-execution entries:
+
+1. Check if any leadership frameworks from the graph have been used vs. available:
+```cypher
+MATCH (f:Framework)-[:TYPICAL_AT]->(s:VentureStage {name: $stage})
+WHERE f.name IN ['Tuckman Team Stages', 'Psychological Safety', 'Adaptive Leadership',
+                  'Emotional Intelligence in Leadership', 'High-Performing Teams',
+                  'Servant Leadership', 'Distributed Leadership', 'Transformational Leadership']
+RETURN f.name AS available_framework
+```
+
+2. Compare against frameworks already applied in room (from STATE.md `frameworks_used`)
+3. If 3+ unused leadership frameworks are available for the current stage, surface: "Your team section has data but you haven't used [N] leadership frameworks that match your stage. /mos:leadership to explore."
+
+## Gating Rules
+
+- Max 2 proactive findings per greeting
+- HIGH confidence only for auto-surfacing
+- Never interrupt methodology sessions
+- Visible refusal on all failures; render once per consult, never repeat ambient
+- Pinecone quota exhausted: use Neo4j only
+
+## Brain-Powered Command Suggestions
+
+**The command for a framework is whatever `command-resolver.commandsForFramework(<framework>)` returns** (`lib/workflow/command-resolver.cjs`, reading the generated `data/command-registry.json`) -- or, if none, "run <framework> manually -- there is no /mos: for it". For a chain, use `composeWorkflow(<framework-chain>)`. **Commands NEVER live in the Brain (Canon Part 8): the Brain holds methodology -- the FEEDS_INTO chains -- and the `recommendFrameworkChain` traversal in `lib/brain/chain-recommender.cjs` carries framework names + problem-type enums only, never a command string, never user content; the plugin-local registry holds the framework-to-command mapping.** Larry never names a `/mos:` from memory. If the resolver returns nothing, the answer is "run <framework> manually".
+
+The Brain ranks WHICH frameworks to suggest next (the FEEDS_INTO traversal in `lib/brain/chain-recommender.cjs`); turning a recommended framework into a `/mos:` command is the resolver's job, not the Brain's, not memory. When the Brain is unreachable: local Room heuristics from the navigation engine + the `larry-personality` skill may still drive CONVERSATION and command resolution -- never presented as methodology -- still resolving any command through `lib/workflow/command-resolver.cjs`. A methodology ask itself refuses visibly (the Refusal section above); local heuristics never stand in for it.
+
+See `docs/WORKFLOWS.md` for the full Brain <-> registry <-> Larry join and the Canon Part 8 boundary.
+
+## Enrichment-Queue Auto-Append (Phase 249, ENRICH-01, Larry-direct leg)
+
+On Desktop/Cowork, Larry reaches the Brain via the `pws-brain-mcp` MCP tools directly (`orchestration_readiness`, `discover_structure`) -- bypassing `brain-client.cjs` entirely, so the plugin's own capture seams never fire for this path. This is the ONE place that gap is closed:
+
+**When a methodology consult returns `orchestration_readiness` 0-2/4, or `discover_structure` with `grounded: false`,** run the one-line append CLI so the miss lands in the same enrichment queue the plugin's wrapper chokepoint writes to:
+
+```bash
+node <plugin-root>/scripts/enrichment-queue-append.cjs \
+  --room <current room directory> \
+  --framework "<canonical framework name>" \
+  --score <the readiness_score integer, or omit for a discover_structure miss> \
+  --missing <comma-separated dims from pattern_type,structure,techniques,flow> \
+  --source live_reach
+```
+
+For a REFUSAL-triggered append (the not_ready kind, Refusal section above), use `--source refusal` instead of `--source live_reach` -- `refusal` is pre-validated in `ALLOWED_SOURCES`, same CLI, same queue, one write surface (Part 7).
+
+Content-free by construction (Canon Part 8): only the canonical framework name, the integer score, the closed-enum dimension tokens, and the fixed `source` string (`live_reach` or `refusal`) ever cross into the call -- NEVER the user's turn text, the conversation content, or any artifact body. This bookkeeping stays silent ONLY when it accompanies a SUCCESSFUL serve (score 0-2 but material still served with provenance), same posture as every other passive/proactive enrichment behavior on this page. When the append accompanies a REFUSAL, the queueing is SAID as part of the refusal copy itself ("I've queued it for enrichment", Refusal section above) -- it is never quiet there.
+
+This is the SAME queue and the SAME append CLI the CLI-path wrapper chokepoint (`lib/core/brain-client.cjs`'s `orchestrationReadiness`/`discoverStructure`) and Phase 250's visible-refusal auto-queue both write through -- one queue, one write surface, per Part 7 (never a second enrichment mechanism).
+
+## Delegation
+
+Delegate to `agents/brain-query.md` for: 2+ graph hops, explicit connection exploration, cross-domain discovery, multi-venture patterns, deep proactive reasoning.
+
+## Primary Tool: brain_ask
+
+Always use `brain_ask` first -- natural language, auto-routes Pinecone/Neo4j, handles fallback. Only use `brain_query` (raw Cypher) for specific complex queries.
+
+## Tool Names
+
+| Surface | Smart | Neo4j | Pinecone | Schema |
+|---------|-------|-------|----------|--------|
+| CLI (HTTP via brain-client.cjs) | `brain-client.ask()` | `brain-client.query()` | `brain-client.search()` | `brain-client.schema()` |
+| mindrian-brain (MCP) | brain_ask | brain_query | brain_search | brain_schema |
+| neo4j-brain (legacy MCP) | N/A | read_neo4j_cypher | search-records | get_neo4j_schema |
+
+The first row is the HTTP path (Phase 123 step 0). When `lib/core/resolve-brain-key.cjs` resolves a key, call directly into `lib/core/brain-client.cjs` -- no MCP server required. The bottom two rows are the MCP-path alternatives.