@mindrian_os/install 1.13.0-beta.11 → 1.13.0-beta.12

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mos",
   "description": "MindrianOS -- Your AI innovation co-founder. Larry thinks with you through PWS methodology, builds your Data Room as you explore, and chains frameworks intelligently. Install and go.",
-  "version": "1.13.0-beta.11",
+  "version": "1.13.0-beta.12",
   "author": {
     "name": "Jonathan Sagir",
     "url": "https://mindrian.ai"

package/CHANGELOG.md

@@ -9,17 +9,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- When onboarding: true, the onboard_steps list is shown to returning users in the What's New flow -->
 <!-- This allows new releases to automatically surface relevant guidance without code changes -->
 
-## [Unreleased] -- v1.13.0-beta.11 (in progress)
+## [1.13.0-beta.12] - 2026-05-12
 
-beta.11 is the v1.13.0 CAPSTONE -- its headline content is the **Workflow Layer** (framework <-> command registry + reliable invocation; spec at `.planning/WORKFLOW-LAYER-SPEC.md`), not yet built. The items below are what has landed on `main` toward the capstone so far; the entry will be finalized (dated, full feature list) when the Workflow Layer ships. The capstone was re-numbered from beta.10 to beta.11 on 2026-05-12: `1.13.0-beta.10` had already been published to npm that day as a token-validation build (dist-tag `@next`, no git tag, not on the marketplace), so the tagged + marketplace'd capstone takes the next number.
+The v1.13.0 CAPSTONE release -- headline content is the **Workflow Layer** (Phase 122: framework <-> command registry + reliable invocation; spec at `.planning/WORKFLOW-LAYER-SPEC.md`, doc at `docs/WORKFLOWS.md`) plus the npm-installer overhaul (`npx @mindrian_os/install` is now a real one-command installer), the `@mindrian_os/cli` -> `@mindrian_os/install` rename, and the install-machinery fixes a Windows live test surfaced (doctor/update path resolution, the statusline pre-release blind spot, and the single plugin-root resolver that retires that whole bug family). Version trail to here: `1.13.0-beta.10` (a token-validation npm publish on 2026-05-12 -- now deprecated), `1.13.0-beta.11` (the real npm installer + the package rename, npm-only -- now deprecated, doctor path bug), `1.13.0-beta.12` (this release: the capstone, tagged `v1.13.0-beta.12`, marketplace `source.ref` pinned, `@mindrian_os/install` published with the `@next` dist-tag).
 
 ### Added
 
+- **The Workflow Layer (Phase 122) -- the framework-to-command registry + reliable invocation.** Larry can now turn "the methodology suggests framework X" into "run `/mos:x`" as a CI-enforced guarantee, not model recall:
+  - **`data/command-registry.json`** -- the generated, committed framework-to-command registry (`{ ontology_ref, commands[], framework_index, curated_chains[] }`), built from each `commands/*.md` frontmatter; never hand-edited. Plus `data/framework-names.json` -- the FEEDS_INTO-linked Brain `:Framework` name slice (+ a small curated whitelist), the only Brain-derived artifact in this loop.
+  - **`scripts/build-command-registry.cjs`** -- the generator + the `--check` drift tripwire (fails on a stale registry or an unresolvable framework name) + `--refresh-names` (a read-only build-time Brain query that snapshots the allowlist). The `--check` is wired into the pre-commit hook (when any `commands/*.md` / `data/command-registry.json` / `data/framework-names.json` is staged) and the Feynman test runner.
+  - **`lib/workflow/command-resolver.cjs`** -- the SOLE deterministic framework-to-command door (`commandsForFramework`, `frameworksForCommand`, `composeWorkflow`, `validateChainAutonomy`); reads only `data/command-registry.json`; zero Brain calls; degrades to empty results / `{ command: null, optional: true }` on a missing registry or a command-less framework (degrade, do not fabricate).
+  - **`lib/brain/chain-recommender.cjs`** -- `recommendFrameworkChain({problemType?, currentFramework?, roomState?}) -> [frameworkName]` via the Brain's `FEEDS_INTO` traversal (framework names + problem-type enums only, never a command string, never user content); degrades to `[seed]`.
+  - **The five new `/mos:` command frontmatter keys** -- `kind` (`methodology | utility | meta`), `frameworks[]` (the exact Brain `:Framework` name(s)), `produces`, `inputs`, `autonomous_safe` -- retrofitted across 44 commands (the algorithmic cohort first). Contract: `docs/COMMAND-FRONTMATTER.md`.
+  - **`/mos:pipeline --from-problem-type <x>` / `--from-framework <x>`** -- Brain-derive the chain, compose commands, print the `/mos:` run order. **`/mos:act --chain`** -- runs the composed workflow but `validateChainAutonomy` first and STOPS at the first non-`autonomous_safe` (or command-less) step with a "needs you here" gate (the Canon Part 3 "human confirms" clause made literal). **`/mos:suggest-next`** -- now returns a step-numbered command sequence, not just a framework list.
+  - **The pre-commit registry-drift tripwire** -- `build-command-registry.cjs --check` runs in `.git/hooks/pre-commit`; the Feynman runner runs it too.
+  - **`docs/WORKFLOWS.md`** -- the Brain <-> registry <-> Larry join, the five reliability rules, the Canon Part 8 boundary (commands never enter the Brain -- no `Command` node, ever), and the resolver/recommender surface. `docs/THE-BRAIN.md` and `docs/CANON-PHASE-MAP.md` point at it.
+  - **`lib/memory/workflow-layer-e2e.test.cjs`** -- walks frontmatter -> `build-command-registry --check` -> `resolver.composeWorkflow(the spec's acceptance example)` -> the command-less degrade case -> the `validateChainAutonomy` stop-point, then runs the Canon Part 8 zero-Brain-mutation grep sweep. Registered in the Feynman runner + `tests/run-all-122.sh`.
 - **`npx @mindrian_os/install` is a real one-command installer, not a printout.** Previously `npx @mindrian_os/cli install` only echoed the marketplace commands for the user to paste into Claude Code by hand ("no side effects, just guidance"). It now drives Claude Code's own plugin CLI: it checks that `claude` is on PATH (and prints how to install Claude Code if not), runs `claude plugin marketplace add jsagir/mindrian-marketplace`, then `claude plugin install mos@mindrian-marketplace`. Running it with no subcommand -- or with only flags, e.g. `npx @mindrian_os/install --version 1.13.0-beta.9` -- does the install; flags pass through to `claude plugin install`. `doctor` and `update` are still explicit subcommands. The Brain key stays a printed hint -- writing it to the environment is the one side effect left to the user. This unblocks un-gating the npm-quick-install card on the install site (`mindrianos-install-site.vercel.app`). (`bin/cli.js`.)
+  - Post-beta.11 follow-up (2026-05-12, after a Windows live test): `mindrian-os doctor` / `update` were resolving the plugin at the legacy `~/.claude/plugins/mindrian-os/` path, which does not exist for a `claude plugin install` -- the plugin is named `mos` and lives at `~/.claude/plugins/cache/<marketplace>/mos/<version>/`. So `npx @mindrian_os/install doctor` was throwing a raw node `MODULE_NOT_FOUND` stack. `bin/cli.js` now resolves the plugin root in order (MINDRIAN_OS_ROOT -> newest marketplace-cache `mos/<version>/` with a `scripts/doctor.cjs` -> legacy clone -> not-found), prints a plain "not installed -- run `npx @mindrian_os/install`" message when truly absent, and `update` uses `claude plugin marketplace update` + `claude plugin update mos@mindrian-marketplace` for a marketplace install (the `git pull` + `install.sh` path is kept only for a dev clone / MINDRIAN_OS_ROOT). The `install` flow also now runs `claude plugin marketplace update` then `claude plugin install` + `claude plugin update` (so an already-installed plugin gets moved to the current ref rather than just reported "already installed", which was the misleading message in the Windows test where the version actually moved 1.12.0 -> 1.13.0-beta.9). Lands in the next `@mindrian_os/install` npm publish.
+  - Same Windows test surfaced a pre-release blind spot in `scripts/statusline-mos` (the self-healing statusline resolver): it picked the "latest" cache version with `grep -E '^[0-9]+\.[0-9]+\.[0-9]+$'`, which rejects `-beta.N` suffixes. A box with `1.12.0` + `1.13.0-beta.9` in the marketplace cache picked `1.12.0`, rendered the stale statusline from there, and exported `MINDRIAN_OS_ROOT` pointing at it -- so the version banner / room-context lookup / focus glyph were all computed from the wrong version. Widened the anchor to `^[0-9]+(\.[0-9]+)+(-[A-Za-z0-9.]+)?$` (`sort -V` already orders pre-releases correctly: `1.12.0 < 1.13.0-beta.9 < 1.13.0`). Ships in the next plugin release; the deployed `~/.claude/statusline-mos` (or the `register_statusline` block in `~/.claude/settings.json` that points at `<install-dir>/scripts/statusline-mos`) picks it up when the plugin re-stamps on next install/update. Immediate workaround on an affected box: delete the stale lower-version cache dir under `~/.claude/plugins/cache/mindrian-marketplace/mos/`.
+  - Root-cause fix (the three above were band-aids on three independent guessers): **`lib/core/active-plugin-root.cjs`** -- the ONE plugin-root resolver. Precedence: `MINDRIAN_OS_ROOT` env -> `~/.claude/plugins/installed_plugins.json` (Claude Code's own registry of the *active* `mos@mindrian-marketplace` install; temporal truth -- right even when "highest semver" isn't the active version) -> newest pre-release-tolerant `~/.claude/plugins/cache/<marketplace>/mos/<version>/` -> legacy `~/.claude/plugins/mindrian-os/` -> not-found. Usable as a module (`resolveActivePluginRoot()`) and as a CLI (`node active-plugin-root.cjs` prints the path; `--json` for `{root, source}`). `bin/cli.js` (doctor/update) now delegates to it; `scripts/statusline-mos` shells out to its CLI form (with the cache-scan as a fallback for older deployed copies of the wrapper). Reads LOCAL files only (Canon Part 8). Still TODO (separate, lower-risk pass): have `scripts/session-start` re-stamp the `register_statusline` block in `~/.claude/settings.json` from this resolver on every run, so the deployed wrapper / settings pointer can never drift.
 
 ### Changed
 
-- **npm package renamed (twice): `@mindrian/os` -> `@mindrian_os/cli` -> `@mindrian_os/install`.** First rename (2026-05-11): the `@mindrian` npm scope never existed (`{"error":"Scope not found"}`), so `@mindrian/os` could never be published; the maintainer created the `@mindrian_os` org and the package moved to `@mindrian_os/cli`; first npm publish was `@mindrian_os/cli@1.13.0-beta.10` on 2026-05-12 (a token-validation build, dist-tag `@next`, no git tag, not on the marketplace) -- now deprecated. Second rename (2026-05-12): `@mindrian_os/cli` implied "a CLI tool" / a guidance printer, which is exactly what it had been; once `install` became a real installer the package name should be the verb, so it moved to `@mindrian_os/install` -- `npx @mindrian_os/install` reads as "install MindrianOS". The `bin` entry stays `mindrian-os` (the post-install command for `doctor`/`update`). `package.json` + `.claude-plugin/plugin.json` are at `1.13.0-beta.11`; once `@mindrian_os/install@1.13.0-beta.11` is published, the v1.13.0 capstone (Phase 122 / Workflow Layer) takes the next number, `1.13.0-beta.12`. Forward-looking references that named `@mindrian_os/cli` (`scripts/release.sh`, `docs/install/PACKAGING-PATHS.md`, `tests/manual/95.6-windows-cold-install-acceptance.md`, `tests/test-release-npm-gate.sh`, the install site's npm-quick-install card) need updating to `@mindrian_os/install`. (The `[1.13.0-beta.9]` entry below is left intact as the historical record of the pre-rename release -- which shipped to GitHub and the marketplace as `v1.13.0-beta.9` but was never published to npm.)
+- **`/mos:suggest-next` returns a command sequence**, not just a framework list; **`framework-chain-composer.proposeNextFramework` routes through `lib/workflow/command-resolver.cjs`** (the only door -- `command:null` degrade for a command-less next framework); **the `pws-methodology` and `brain-connector` skills point at the resolver** (framework routing goes through `command-resolver.commandsForFramework` / `composeWorkflow`, never a `/mos:` named from memory). **The three remaining hand-maintained framework-to-command maps were pruned:** `framework-chain-composer.FRAMEWORK_TO_COMMAND_SLUG` is now an empty back-compat export, `lib/hmi/jtbd-taxonomy.json:methodology_hooks` is marked informational-only (the resolver is authoritative), and `references/methodology/index.md` is now just a pointer to `docs/COMMAND-FRONTMATTER.md` / `data/command-registry.json` / `docs/WORKFLOWS.md` -- it no longer hand-maintains a routing table.
+- **npm package renamed (twice): `@mindrian/os` -> `@mindrian_os/cli` -> `@mindrian_os/install`.** First rename (2026-05-11): the `@mindrian` npm scope never existed (`{"error":"Scope not found"}`), so `@mindrian/os` could never be published; the maintainer created the `@mindrian_os` org and the package moved to `@mindrian_os/cli`; first npm publish was `@mindrian_os/cli@1.13.0-beta.10` on 2026-05-12 (a token-validation build, dist-tag `@next`, no git tag, not on the marketplace) -- now deprecated. Second rename (2026-05-12): `@mindrian_os/cli` implied "a CLI tool" / a guidance printer, which is exactly what it had been; once `install` became a real installer the package name should be the verb, so it moved to `@mindrian_os/install` -- `npx @mindrian_os/install` reads as "install MindrianOS". The `bin` entry stays `mindrian-os` (the post-install command for `doctor`/`update`). `package.json` + `.claude-plugin/plugin.json` ship as `1.13.0-beta.12` (this release); the npm-only intermediate publishes `@mindrian_os/cli@1.13.0-beta.10` and `@mindrian_os/install@1.13.0-beta.11` are deprecated. The install site's npm-quick-install card already names `@mindrian_os/install`; `scripts/release.sh` still says `@mindrian_os/cli` (Step 9.5) and only handles clean `X.Y.Z` bumps (it choked on the pre-release version, so this release was hand-rolled per the CLAUDE.md release process) -- both worth a follow-up. `docs/install/PACKAGING-PATHS.md`, `tests/manual/95.6-windows-cold-install-acceptance.md`, `tests/test-release-npm-gate.sh` still name `@mindrian_os/cli` and need updating to `@mindrian_os/install`. (The `[1.13.0-beta.9]` entry below is left intact as the historical record of the pre-rename release -- which shipped to GitHub and the marketplace as `v1.13.0-beta.9` but was never published to npm.)
+
+### Fixed
+
+- **The hallucinated-command failure mode.** Larry could name a non-existent or semantically wrong command -- e.g. `/mos:jtbd` for the JTBD *methodology* when `/mos:analyze-needs` is the framework command (`/mos:jtbd` is the active-JTBD management command, not a methodology runner). With the Workflow Layer, every command Larry surfaces comes back from `lib/workflow/command-resolver.cjs` reading the generated registry -- `composeWorkflow(["Jobs to Be Done (JTBD)"])` returns `/mos:analyze-needs`. A hallucinated command cannot be emitted.
+- **A latent Canon Part 8 breach in prose.** `skills/brain-connector/SKILL.md` carried dead "Brain has Command nodes linked to Frameworks ... `brain_proactive_command` ... `FOLLOWS_FRAMEWORK -> Command`" prose, and `references/brain/command-triggers-schema.md` was a whole dead "commands are first-class Neo4j nodes" schema doc -- both asserted that plugin commands live in the Brain, which the live Brain never implemented (no `Command` label) and which Canon Part 8 forbids. Both were deleted; the `command-triggers-schema.md` path now carries a `REMOVED` tombstone pointing at the Workflow Layer. The `lib/memory/workflow-layer-e2e.test.cjs` grep sweep now fails the build if a `Command`-node assertion ever returns anywhere in `skills/`, `agents/`, or `references/`.
+
+### Maintainer Notes
+
+- **Release steps (maintainer-gated -- NOT performed in this phase):** cut the `v1.13.0-beta.11` tag, pin `~/mindrian-marketplace/.claude-plugin/marketplace.json` `source.ref` to the tag, and `npm publish @mindrian_os/install` with the `@next` dist-tag -- per the CLAUDE.md release process and the `feedback_release_lockstep_npm` rule (every plugin release publishes the npm package in lockstep). Phase 122 only finalized this CHANGELOG block and shipped the Workflow Layer code/docs/tests; it did not bump any version, did not `git tag`, did not `npm publish`, and did not edit `marketplace.json`.
 
 ### Notes
 

package/bin/cli.js

@@ -10,53 +10,83 @@
  * flags, e.g. `npx @mindrian_os/install --version 1.13.0-beta.9`) does the
  * install. `doctor` and `update` are still explicit subcommands.
  *
- *   install   Path B. Actually install MindrianOS by driving Claude Code's
- *             own plugin CLI: registers the Mindrian marketplace, then runs
- *             `claude plugin install mos@mindrian-marketplace`. Requires the
- *             `claude` CLI on PATH (prints how to get it if missing). Any
- *             flags after `install` pass through to `claude plugin install`
- *             (e.g. `mindrian-os install --version 1.13.0-beta.9`). The Brain
- *             key stays a printed hint -- writing it to the environment is the
- *             one side effect we leave to the user.
- *   doctor    Path C. Run /mos:doctor's diagnostic logic from OUTSIDE Claude
- *             Code so users catch install/drift problems before a session.
- *             Spawns `node <pluginRoot>/scripts/doctor.cjs` with any extra
- *             args passed through (e.g. `mindrian-os doctor --all --fix`).
- *             Exits with doctor.cjs's exit code.
- *   update    Mirror /mos:update. `git -C <pluginRoot> pull --ff-only`, then
- *             re-run `bash <pluginRoot>/install.sh` to re-register agents,
- *             hooks, settings.json, and the statusLine block.
+ *   install   Install (or bring current) MindrianOS by driving Claude Code's
+ *             own plugin CLI: registers the Mindrian marketplace, refreshes the
+ *             catalog, then `claude plugin install` + `claude plugin update` on
+ *             mos@mindrian-marketplace. Requires the `claude` CLI on PATH (prints
+ *             how to get it if missing). Flags pass through to `claude plugin
+ *             install` (e.g. `--version 1.13.0-beta.9`); when a version is pinned
+ *             the update step is skipped. The Brain key stays a printed hint --
+ *             writing it to the environment is the one side effect left to you.
+ *   doctor    Run /mos:doctor's diagnostic from OUTSIDE Claude Code so you catch
+ *             install/drift problems before a session. Resolves the installed
+ *             plugin (marketplace cache, dev clone, or MINDRIAN_OS_ROOT), then
+ *             `node <pluginRoot>/scripts/doctor.cjs <args...>`. If the plugin is
+ *             not installed, says so plainly instead of throwing a node stack.
+ *   update    Bring MindrianOS current. For a marketplace install: `claude plugin
+ *             marketplace update` + `claude plugin update mos@mindrian-marketplace`.
+ *             For a dev clone (MINDRIAN_OS_ROOT set): `git -C <root> pull --ff-only`
+ *             + `bash <root>/install.sh`.
  *
  * GSD pattern: pure CJS, node built-ins only, zero npm deps. No CLI framework
  * (no commander/yargs/meow). process.argv switch-case routing, mirroring
  * bin/mindrian-tools.cjs and ~/.claude/get-shit-done/bin/gsd-tools.cjs.
  *
- * PLUGIN_ROOT resolution: MINDRIAN_OS_ROOT env var if set (tests, dev boxes),
- * else the canonical install cache at ~/.claude/plugins/mindrian-os.
+ * Plugin-root resolution is delegated to lib/core/active-plugin-root.cjs (the
+ * single source of truth: MINDRIAN_OS_ROOT -> installed_plugins.json -> newest
+ * marketplace-cache mos/<version>/ -> legacy clone -> not-found). doctor and
+ * update both read from it; scripts/statusline-mos shells out to its CLI form.
  */
 
 const { spawnSync } = require('node:child_process');
 const path = require('node:path');
 const os = require('node:os');
+const fs = require('node:fs');
+// The ONE plugin-root resolver: installed_plugins.json (temporal truth) first,
+// then the pre-release-tolerant marketplace-cache scan, then a legacy clone.
+const { resolveActivePluginRoot } = require('../lib/core/active-plugin-root.cjs');
 
-const PLUGIN_ROOT = process.env.MINDRIAN_OS_ROOT
-  || path.join(os.homedir(), '.claude', 'plugins', 'mindrian-os');
+const MARKETPLACE = 'jsagir/mindrian-marketplace';
+const PLUGIN_SPEC = 'mos@mindrian-marketplace';
 
 function run(cmd, args, opts) {
   return spawnSync(cmd, args, { stdio: 'inherit', ...opts });
 }
 
+function ok(result) {
+  return result && typeof result.status === 'number' && result.status === 0;
+}
+
 function exitFrom(result) {
   // spawnSync sets status=null when the process was killed by a signal or
   // failed to launch; treat that as a generic failure.
   process.exit(result && typeof result.status === 'number' ? result.status : 1);
 }
 
+function hasDoctor(dir) {
+  try {
+    return !!dir && fs.existsSync(path.join(dir, 'scripts', 'doctor.cjs'));
+  } catch {
+    return false;
+  }
+}
+
 function printUsage() {
   console.log('mindrian-os <install|doctor|update>   (no subcommand = install)');
-  console.log('  install   install MindrianOS via Claude Code (adds the marketplace, installs the mos plugin)');
-  console.log('  doctor    run the MindrianOS install/drift diagnostic (Path C; passes flags through to /mos:doctor)');
-  console.log('  update    pull the latest plugin and re-run install registration');
+  console.log('  install   install / bring current via Claude Code (marketplace add + plugin install/update)');
+  console.log('  doctor    run the MindrianOS install/drift diagnostic (passes flags through to /mos:doctor)');
+  console.log('  update    bring MindrianOS current (marketplace update + plugin update; or git pull for a dev clone)');
+}
+
+function requireClaudeCli() {
+  const check = spawnSync('claude', ['--version'], { stdio: 'ignore' });
+  if (ok(check)) return true;
+  console.error('Claude Code is not installed (no `claude` command on your PATH).');
+  console.error('Install it first:');
+  console.error('  npm install -g @anthropic-ai/claude-code');
+  console.error('Then re-run:');
+  console.error('  npx @mindrian_os/install');
+  return false;
 }
 
 // No subcommand, or flags only (e.g. `npx @mindrian_os/install --version 1.13.0-beta.9`),
@@ -70,68 +100,95 @@ if (!sub || sub.startsWith('-')) {
 
 switch (sub) {
   case 'doctor': {
-    // Path C: run /mos:doctor's logic from outside Claude Code.
-    const doctorPath = path.join(PLUGIN_ROOT, 'scripts', 'doctor.cjs');
-    const r = run(process.execPath, [doctorPath, ...process.argv.slice(3)]);
+    const { root } = resolveActivePluginRoot();
+    if (!root || !hasDoctor(root)) {
+      console.error('MindrianOS does not appear to be installed (could not find scripts/doctor.cjs).');
+      console.error('Looked under: ' + path.join(os.homedir(), '.claude', 'plugins') + (process.env.MINDRIAN_OS_ROOT ? ' and $MINDRIAN_OS_ROOT' : ''));
+      console.error('Install it first:');
+      console.error('  npx @mindrian_os/install');
+      process.exit(1);
+    }
+    const r = run(process.execPath, [path.join(root, 'scripts', 'doctor.cjs'), ...process.argv.slice(argOffset)]);
     exitFrom(r);
     break;
   }
 
   case 'update': {
-    // Mirror /mos:update: fast-forward the plugin clone, then re-run install.sh
-    // so agents, hooks, settings.json, and the statusLine block get re-stamped.
-    run('git', ['-C', PLUGIN_ROOT, 'pull', '--ff-only']);
-    const r = run('bash', [path.join(PLUGIN_ROOT, 'install.sh')]);
-    exitFrom(r);
+    // Dev clone (MINDRIAN_OS_ROOT or a legacy hand-clone): git pull + re-run install.sh.
+    const { root } = resolveActivePluginRoot();
+    const isDevClone = !!process.env.MINDRIAN_OS_ROOT
+      || (root && fs.existsSync(path.join(root, '.git')) && fs.existsSync(path.join(root, 'install.sh')));
+    if (isDevClone && root) {
+      run('git', ['-C', root, 'pull', '--ff-only']);
+      const r = run('bash', [path.join(root, 'install.sh')]);
+      exitFrom(r);
+      break;
+    }
+    // Marketplace install: use Claude Code's own update path.
+    if (!requireClaudeCli()) process.exit(1);
+    console.log('Refreshing the marketplace catalog...');
+    run('claude', ['plugin', 'marketplace', 'update']);
+    console.log('Updating the MindrianOS plugin...');
+    const r = run('claude', ['plugin', 'update', PLUGIN_SPEC]);
+    if (!ok(r)) {
+      console.error('');
+      console.error('`claude plugin update ' + PLUGIN_SPEC + '` did not complete.');
+      console.error('Try inside Claude Code:  /plugin marketplace update   then   /plugin update ' + PLUGIN_SPEC);
+      exitFrom(r);
+    }
+    console.log('');
+    console.log('MindrianOS is up to date. Run `claude plugin list` to confirm the version.');
+    console.log('Verify:  mindrian-os doctor   (or /mos:doctor inside Claude Code)');
+    process.exit(0);
     break;
   }
 
   case 'install': {
-    // Path B: actually install MindrianOS by driving Claude Code's plugin CLI.
-    // Registers the Mindrian marketplace, then `claude plugin install mos@...`.
     // Flags after `install` (or leading flags when `install` is implied) pass
-    // through to `claude plugin install` (e.g. `... install --version 1.13.0-beta.9`).
+    // through to `claude plugin install` (e.g. `... --version 1.13.0-beta.9`).
     const passthrough = process.argv.slice(argOffset);
+    const pinned = passthrough.some((a) => a === '--version' || a.startsWith('--version='));
 
-    // 1. Claude Code must be on PATH -- it does the actual plugin install.
-    const claudeCheck = spawnSync('claude', ['--version'], { stdio: 'ignore' });
-    if (!claudeCheck || claudeCheck.status !== 0) {
-      console.error('Claude Code is not installed (no `claude` command on your PATH).');
-      console.error('Install it first:');
-      console.error('  npm install -g @anthropic-ai/claude-code');
-      console.error('Then re-run:');
-      console.error('  npx @mindrian_os/install');
-      process.exit(1);
-    }
+    if (!requireClaudeCli()) process.exit(1);
 
-    // 2. Register the Mindrian marketplace. Best-effort: if it is already
-    //    registered Claude Code may exit non-zero with "already added" -- that
-    //    is fine, the install step below still works.
+    // Register the Mindrian marketplace (idempotent) and refresh its catalog so
+    // we resolve the current ref. Both are best-effort -- "already added" /
+    // "already up to date" exit non-zero on some Claude Code versions; fine.
     console.log('Adding the Mindrian marketplace...');
-    run('claude', ['plugin', 'marketplace', 'add', 'jsagir/mindrian-marketplace']);
+    run('claude', ['plugin', 'marketplace', 'add', MARKETPLACE]);
+    console.log('Refreshing the marketplace catalog...');
+    run('claude', ['plugin', 'marketplace', 'update']);
 
-    // 3. Install (or update) the plugin. This one's exit code matters.
+    // Install. On an already-installed plugin Claude Code reports "already
+    // installed" and still exits 0 -- the update step below then moves it
+    // forward to the current ref (unless the caller pinned a version).
     console.log('Installing the MindrianOS plugin...');
-    const inst = run('claude', ['plugin', 'install', 'mos@mindrian-marketplace', ...passthrough]);
-    if (!inst || inst.status !== 0) {
+    const inst = run('claude', ['plugin', 'install', PLUGIN_SPEC, ...passthrough]);
+    let updated = false;
+    if (!pinned) {
+      console.log('Bringing the plugin to the current build...');
+      const upd = run('claude', ['plugin', 'update', PLUGIN_SPEC]);
+      updated = ok(upd);
+    }
+
+    if (!ok(inst) && !updated) {
       console.error('');
-      console.error('`claude plugin install mos@mindrian-marketplace` did not complete.');
+      console.error('Installing ' + PLUGIN_SPEC + ' did not complete.');
       console.error('Finish it by hand inside Claude Code:');
-      console.error('  /plugin marketplace add jsagir/mindrian-marketplace');
-      console.error('  /plugin install mos@mindrian-marketplace');
+      console.error('  /plugin marketplace add ' + MARKETPLACE);
+      console.error('  /plugin install ' + PLUGIN_SPEC);
       exitFrom(inst);
     }
 
-    // 4. Done. Point at the Brain key + first run.
     console.log('');
-    console.log('MindrianOS installed.');
+    console.log('MindrianOS is installed and current. Run `claude plugin list` to see the version.');
     console.log('');
     console.log('Optional -- connect the Brain for enriched intelligence:');
     console.log('  inside Claude Code:  /mos:setup   (choose "Configure Brain", paste your key)');
     console.log('  or set it directly:  export MINDRIAN_BRAIN_KEY="<your-key>"   (or add it to ~/.claude/.env)');
     console.log('');
     console.log('Verify:  mindrian-os doctor   (or /mos:doctor inside Claude Code)');
-    console.log('Start:   run `claude`, then  /mos:onboard');
+    console.log('Start:   open a fresh Claude Code session, then  /mos:onboard');
     process.exit(0);
     break;
   }

package/commands/act.md

@@ -211,9 +211,23 @@ Display the thinking trace (Step 4) and the execution plan following the dry-run
      Run /mos:act to execute this plan.
 ```
 
-### Chain Mode (`/mos:act --chain`)
+### Chain Mode (`/mos:act --chain`) -- the autonomy gate
 
-1. Select 3-5 frameworks using the chain selection logic:
+**Before anything else in `--chain` mode, plan + autonomy-gate the chain through the resolver:**
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/act-command.cjs" --chain --room ./room
+```
+
+The helper picks the framework chain for the room state via `lib/brain/chain-recommender.cjs` `recommendFrameworkChain` (a FEEDS_INTO traversal -- framework names + problem-type enums only; Canon Part 8: never a command string, never user content), composes it into `/mos:` commands via `lib/workflow/command-resolver.cjs` `composeWorkflow` (the SOLE framework -> command path, reading only the generated `data/command-registry.json`), calls `validateChainAutonomy(workflow)` FIRST, then walks the steps in order. At the FIRST step whose command is not `autonomous_safe: true` (or whose framework has no `/mos:` command at all), it STOPS and renders a "needs you here" gate (a Shape F.0 / E action report: "[GATE] Chain reached step N: /mos:x for <framework>. This step is not autonomous_safe -- it needs your eyes. [continue] [stop]"). You then:
+- run the `autonomous_safe` prefix steps unattended (dispatch `agents/framework-runner.md` per step, with the checkpoint pause between steps as below),
+- at the gate step, do NOT run it autonomously -- surface the gate to the user and wait. `[continue]` = the user runs that step themselves (or approves running it), then resume the chain from the next step. `[stop]` = halt; what ran above is filed.
+
+You NEVER name a `/mos:` command in `--chain` mode from memory and you NEVER decide a step is safe to run unattended from memory -- the command came back from the resolver and the autonomy decision came back from `validateChainAutonomy` / `data/command-registry.json`'s `autonomous_safe` field. `--chain --from-framework <x>` / `--chain --problem-type <x>` seed the chain explicitly.
+
+Then, for the steps the helper greenlit:
+
+1. Select 3-5 frameworks using the chain selection logic (the helper already did this via the recommender; this list is the same chain):
    - First framework: targets weakest section or most pressing gap
    - Subsequent frameworks: build on previous, guided by Brain `FEEDS_INTO` relationships or natural progression (Exploration -> Analysis -> Synthesis -> Validation)
    - Never select redundant frameworks

package/commands/pipeline.md

@@ -1,7 +1,7 @@
 ---
 name: pipeline
 description: Chain a multi-step methodology pipeline
-argument-hint: [pipeline-name]
+argument-hint: '[pipeline-name] [--from-problem-type <x>] [--from-framework <x>]'
 serves_jtbd: ["plan-execution"]
 # --- Phase 122 workflow-layer frontmatter ---
 kind: meta
@@ -20,6 +20,18 @@ allowed-tools:
 
 You are Larry. This command orchestrates multi-step methodology chains -- connected sequences where each framework's output feeds the next as structured input.
 
+## Brain-Derived Chains -- `--from-problem-type <x>` / `--from-framework <x>`
+
+`/mos:pipeline --from-problem-type ill-defined` (or `--from-framework "Beautiful Question Framework"`) does NOT run a static named pipeline -- it Brain-derives the framework chain and runs the resolver-composed `/mos:` command sequence end to end:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-command.cjs" --from-problem-type ill-defined --room ./room
+```
+
+The helper calls `lib/brain/chain-recommender.cjs` `recommendFrameworkChain` (a FEEDS_INTO traversal -- framework names + problem-type enums only; Canon Part 8: never a command string, never user content), composes that chain into `/mos:` commands via `lib/workflow/command-resolver.cjs` `composeWorkflow` (the SOLE framework -> command path, reading only the generated `data/command-registry.json`), and prints the run order. Then run the printed `/mos:` commands in sequence using the Stage Execution Loop machinery below -- one resolved command per step. For a step whose framework has no `/mos:` command, the helper prints "no /mos: for <framework> -- run it manually; continuing"; skip that step (or run the framework manually) and continue. Every command the helper prints exists in the registry -- the resolver only ever returns registered commands, so you never invoke a `/mos:` that does not exist.
+
+`--from-problem-type` accepts the canonical `UDP` / `IDP` / `WDP` tokens and the `undefined` / `ill-defined` / `well-defined` aliases. With neither flag and no named pipeline, the helper falls back to the room's `ProblemType` from `room/STATE.md`.
+
 ## Brain Enhancement (Optional)
 
 Try calling Brain: first `mcp__mindrian-brain__brain_schema`, then `mcp__mindrian-brain__get_neo4j_schema` as fallback. If it succeeds, Brain mode is active. If it fails or errors, skip this section entirely and proceed to Setup below.
@@ -45,6 +57,9 @@ Proceed to Setup below with this additional context. Static chains remain the de
 
 ### Chain Selection
 
+**If user passes `--from-problem-type <x>` or `--from-framework <x>`:**
+Run the helper above (`scripts/pipeline-command.cjs`) to Brain-derive the chain and get the resolver-composed `/mos:` run order, then execute those commands in sequence via the Stage Execution Loop. This is the dynamic, graph-derived path -- no `CHAIN.md` file involved.
+
 **If user specifies a pipeline name** (e.g., `/mos:pipeline discovery`):
 Load `pipelines/{name}/CHAIN.md` and proceed to Stage 1.
 

package/commands/suggest-next.md

@@ -17,9 +17,23 @@ allowed-tools:
 
 # /mos:suggest-next
 
-You are Larry. This command uses the Brain graph to recommend what the user should work on next based on their current room state and framework chains.
+You are Larry. This command recommends what the user should work on next as a COMMAND SEQUENCE, not just a list of frameworks: it reads the room's ProblemType (and active JTBD), Brain-derives the framework chain, and composes that chain into the exact `/mos:` commands to run, in order.
 
-**Requires Brain MCP.** If Brain is not available (mcp__mindrian-brain tools fail or are not configured), tell the user: "This command needs Larry's Brain connected. Run `/mos:setup brain` to set it up." Then stop.
+## The resolver is the only door
+
+Run the helper to get the resolver-composed command sequence:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/suggest-next-command.cjs" --room ./room
+```
+
+It reads `room/STATE.md` for the ProblemType / active JTBD (or pass `--problem-type <x>` / `--from-framework <x>` explicitly), calls `lib/brain/chain-recommender.cjs` `recommendFrameworkChain` (a FEEDS_INTO traversal -- framework names + problem-type enums only; Canon Part 8: never a command string, never user content), composes the chain into `/mos:` commands via `lib/workflow/command-resolver.cjs` `composeWorkflow` (the SOLE framework -> command path, reading only the generated `data/command-registry.json`), and prints BOTH the framework chain AND the step-numbered command sequence. A framework with no `/mos:` yet renders as "(no /mos: for this -- run it manually)" -- degrade, do not fabricate.
+
+**Larry NEVER names a `/mos:` command from memory.** Every command you surface came back from the resolver via this helper. If you find yourself about to type a `/mos:` you have not seen the resolver return, stop -- run the helper first. Render in Shape B (Semantic Tree) per `skills/ui-system/SKILL.md`; do not invent a format.
+
+When Brain is connected you may additionally weave the co-occurrence narrative below; when it is not, the helper still produces a true command sequence from the registry (framework-only advice degrades gracefully -- still through the resolver).
+
+**Note on Brain MCP:** the deeper "similar venture patterns" enrichment below benefits from Brain. If Brain is not available, skip those queries -- the resolver-composed sequence above still stands.
 
 ## Setup
 
@@ -61,7 +75,7 @@ Combine both query results. Present 2-3 next steps ranked by:
 - Co-occurrence patterns from similar ventures
 
 For each recommendation:
-- **What to do:** Name the framework and the specific `/mos:` command to run
+- **What to do:** Name the framework AND the specific `/mos:` command -- but take the command from the helper's resolver-composed sequence above (or `lib/workflow/command-resolver.cjs` `commandsForFramework(<framework>)`), never from memory. If a framework has no command, say "run <framework> manually -- there is no /mos: for it" rather than inventing one.
 - **Why this sequence:** Cite the relationship type from the graph (e.g., "Explore Domains FEEDS_INTO Analyze Needs with 0.85 confidence -- mapping the landscape first sharpens your customer discovery")
 - **What similar ventures did:** Reference co-occurrence data ("Projects that used Beautiful Question most commonly followed with Explore Domains or Map Unknowns")
 

package/lib/core/active-plugin-root.cjs

@@ -0,0 +1,142 @@
+'use strict';
+/*
+ * lib/core/active-plugin-root.cjs -- the ONE resolver for "where is the active
+ * MindrianOS plugin install on this machine?"
+ *
+ * Background: before this module, three different places guessed independently
+ * (bin/cli.js hardcoded a legacy path; scripts/statusline-mos did `ls cache |
+ * sort -V` with a pure-semver regex that rejected `-beta.N`; context-monitor
+ * inherited whatever those picked). Three guessers, three failure modes -- a box
+ * with 1.12.0 + 1.13.0-beta.9 in the cache ended up rendering the statusline,
+ * the version banner, and MINDRIAN_OS_ROOT from the wrong (older) version. This
+ * collapses them into one source of truth.
+ *
+ * Precedence (first hit wins):
+ *   1. MINDRIAN_OS_ROOT env var          -- tests, dev boxes, hand clones.
+ *   2. ~/.claude/plugins/installed_plugins.json
+ *                                        -- Claude Code's own registry of the
+ *                                           ACTIVE install of mos@mindrian-marketplace.
+ *                                           Temporal truth: it knows which one is
+ *                                           current even when "highest semver" is not
+ *                                           the active one (e.g. a pinned older version).
+ *   3. ~/.claude/plugins/cache/<marketplace>/mos/<version>/
+ *                                        -- newest valid version dir; pre-release
+ *                                           tolerant (`sort -V` ordering). Fallback
+ *                                           for when installed_plugins.json is missing
+ *                                           or unparseable.
+ *   4. ~/.claude/plugins/mindrian-os/    -- legacy hand-clone layout.
+ *   5. null                              -- not installed.
+ *
+ * Use as a module:
+ *   const { resolveActivePluginRoot } = require('<...>/lib/core/active-plugin-root.cjs');
+ *   const { root, source } = resolveActivePluginRoot();   // root may be null
+ *
+ * Use as a CLI (so a bash wrapper -- e.g. scripts/statusline-mos -- can shell out):
+ *   node active-plugin-root.cjs          -> prints the resolved path, or nothing; exit 0 if found, 1 if not
+ *   node active-plugin-root.cjs --json   -> prints {"root": "<path|null>", "source": "<...>"}
+ *
+ * Canon Part 8: this reads LOCAL files only (~/.claude/plugins/). Zero network.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const PLUGIN_KEYS = ['mos', 'mindrian-os']; // accept either marketplace plugin name
+
+// A valid plugin install dir has a .claude-plugin/plugin.json.
+function isPluginDir(dir) {
+  try {
+    return !!dir && fs.statSync(dir).isDirectory() && fs.existsSync(path.join(dir, '.claude-plugin', 'plugin.json'));
+  } catch {
+    return false;
+  }
+}
+
+function fromInstalledPlugins(home) {
+  // Shape (Claude Code 2.x):
+  //   { "version": N, "plugins": { "mos@mindrian-marketplace": [ { "installPath": "...", ... } ], ... } }
+  // Defensive: the key might be just "mos"; the value might be an object not a
+  // 1-element array; the path field might be installPath / path / dir.
+  const file = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+  const plugins = (data && (data.plugins || data)) || {};
+  for (const key of Object.keys(plugins)) {
+    const name = String(key).split('@')[0];
+    if (!PLUGIN_KEYS.includes(name)) continue;
+    let entry = plugins[key];
+    if (Array.isArray(entry)) entry = entry[0];
+    if (!entry || typeof entry !== 'object') continue;
+    const p = entry.installPath || entry.path || entry.dir;
+    if (p && isPluginDir(p)) return p;
+  }
+  return null;
+}
+
+function fromMarketplaceCache(home) {
+  const cacheBase = path.join(home, '.claude', 'plugins', 'cache');
+  let marketplaces;
+  try {
+    marketplaces = fs.readdirSync(cacheBase, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const found = [];
+  for (const mk of marketplaces) {
+    if (!mk.isDirectory()) continue;
+    for (const pluginName of PLUGIN_KEYS) {
+      const pluginDir = path.join(cacheBase, mk.name, pluginName);
+      let versions;
+      try {
+        versions = fs.readdirSync(pluginDir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const v of versions) {
+        if (!v.isDirectory()) continue;
+        const candidate = path.join(pluginDir, v.name);
+        if (isPluginDir(candidate)) found.push({ dir: candidate, ver: v.name });
+      }
+    }
+  }
+  if (!found.length) return null;
+  // `localeCompare` numeric ordering matches `sort -V` for the cases we care
+  // about: 1.12.0 < 1.12.5.1 < 1.13.0-beta.9 < 1.13.0-beta.11 < 1.13.0.
+  found.sort((a, b) => String(a.ver).localeCompare(String(b.ver), undefined, { numeric: true }));
+  return found[found.length - 1].dir;
+}
+
+function fromLegacyClone(home) {
+  const legacy = path.join(home, '.claude', 'plugins', 'mindrian-os');
+  return isPluginDir(legacy) ? legacy : null;
+}
+
+function resolveActivePluginRoot() {
+  const envRoot = process.env.MINDRIAN_OS_ROOT;
+  if (envRoot) return { root: envRoot, source: 'MINDRIAN_OS_ROOT' };
+
+  const home = os.homedir();
+  let r;
+  if ((r = fromInstalledPlugins(home))) return { root: r, source: 'installed_plugins.json' };
+  if ((r = fromMarketplaceCache(home))) return { root: r, source: 'marketplace-cache' };
+  if ((r = fromLegacyClone(home))) return { root: r, source: 'legacy-clone' };
+  return { root: null, source: 'not-found' };
+}
+
+module.exports = { resolveActivePluginRoot };
+
+// CLI entry point.
+if (require.main === module) {
+  const out = resolveActivePluginRoot();
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(out) + '\n');
+  } else if (out.root) {
+    process.stdout.write(out.root + '\n');
+  }
+  process.exit(out.root ? 0 : 1);
+}