@jstn-sdk/ma 0.1.12 → 0.14.0

package/.codex/agents/Architect.toml

@@ -1,4 +1,3 @@
 name = "Architect"
-role = "architecture-design"
-trigger = "$arch"
 description = "Produces blueprint architecture, stack rationale, tradeoffs, and subsystem design."
+developer_instructions = "Use repository evidence, preserve boundaries, and state verification gaps explicitly."

package/.codex/agents/Auditor.toml

@@ -1,4 +1,3 @@
 name = "Auditor"
-role = "security-review"
-trigger = "$vet"
 description = "Evaluates security posture, CVE signals, and safer alternatives."
+developer_instructions = "Audit trust boundaries, fail closed on unsafe behavior, and report concrete evidence."

package/.codex/agents/Builder.toml

@@ -1,4 +1,3 @@
 name = "Builder"
-role = "build-planning"
-trigger = "$build"
 description = "Checks gates, splits bounded work, and proposes branch/worktree execution paths."
+developer_instructions = "Implement only verified scope, keep changes reviewable, and run the required checks."

package/.codex/agents/Flow.toml

@@ -1,4 +1,3 @@
 name = "Flow"
-role = "logic-validation"
-trigger = "$flow"
 description = "Validates business logic, state transitions, and unresolved blockers."
+developer_instructions = "Trace state transitions end to end and identify blockers with reproducible evidence."

package/.codex/agents/Sage.toml

@@ -1,4 +1,3 @@
 name = "Sage"
-role = "oss-evidence"
-trigger = "$sage"
 description = "Maps architectural choices to approved OSS sources through GitMCP-backed collections."
+developer_instructions = "Prefer authoritative sources and keep external claims versioned and cited."

package/.codex/agents/Vibe.toml

@@ -1,4 +1,3 @@
 name = "Vibe"
-role = "experience-review"
-trigger = "$vibe"
 description = "Reviews developer and user experience risks before implementation."
+developer_instructions = "Review workflows for clarity, accessibility, and regressions using concrete checks."

package/.codex/hooks.json

@@ -1,15 +1,26 @@
 {
-  "version": 1,
-  "hooks": [
-    {
-      "event": "prebuild",
-      "action": "deny-unless-gates-green",
-      "source": ".ma/decisions.json"
-    },
-    {
-      "event": "prerelease",
-      "action": "deny-unless-release-origin-valid",
-      "allowedOrigins": ["development", "release/*"]
-    }
-  ]
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "ma hook context-hydration"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "ma hook context-hydration"
+      },
+      {
+        "type": "command",
+        "command": "ma hook active-autonomy"
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "node ./scripts/active-autonomy-hook.mjs"
+      }
+    ]
+  }
 }

package/.codex/prompts/enforcement.md

@@ -1,5 +1,9 @@
 # Meta-Architect Repo Enforcement Rules
 
+## Active Autonomy Core
+
+Use `AUTO-CONTINUE` for clear, safe, reversible, already-requested workspace work. `ASK` only for destructive, irreversible, credential-gated, external-production, materially scope-changing actions, or missing authority. Do not use permission-handoff phrasing on AUTO-CONTINUE branches. Terminal workflow replies must name `finished`, `blocked`, `failed`, `cancelled`, or `askuserQuestion` with evidence or blocker.
+
 You are operating inside Meta-Architect, a Codex skill system for verified project building.
 
 ## Mission

package/.codex/prompts/onboarding.md

@@ -5,6 +5,7 @@ Meta-Architect is a skills-first system for Codex with a strict kernel.
 ## What is implemented
 
 The primary product surface is the in-session skill flow:
+- `$maestro` (the umbrella manager and recommended first step)
 - `$arch`
 - `$sage`
 - `$flow`
@@ -13,6 +14,10 @@ The primary product surface is the in-session skill flow:
 - `$build`
 
 Secondary helper commands remain available through:
+- `ma setup`
+- `ma doctor`
+- `ma welcome`
+- `ma context refresh`
 - `ma init`
 - `ma idea`
 - `ma skills`
@@ -32,7 +37,7 @@ Secondary helper commands remain available through:
 2. Read `docs/getting-started.md`
 3. Read `docs/release-spec.md`
 4. Read `docs/skills.md`
-5. Start Codex context if needed, then use `$arch` before assuming the workflow is ready
+5. Start Codex context if needed, then use `$maestro` to select the next safe lane
 
 ## What not to do
 

package/.codex/prompts/skill-contract.md

@@ -1,5 +1,9 @@
 # Skill Contract
 
+## Active Autonomy Core
+
+Use `AUTO-CONTINUE` for clear, safe, reversible, already-requested workspace work. `ASK` only for destructive, irreversible, credential-gated, external-production, materially scope-changing actions, or missing authority. Do not use permission-handoff phrasing on AUTO-CONTINUE branches. Terminal workflow replies must name `finished`, `blocked`, `failed`, `cancelled`, or `askuserQuestion` with evidence or blocker.
+
 Every Meta-Architect skill result must include:
 - `decision`
 - `status`

package/COVERAGE.md

@@ -0,0 +1,211 @@
+# Meta-Architect Coverage Matrix
+
+Target release: `v0.14.0`
+Last verified: 2026-06-03
+Package: `@jstn-sdk/ma@0.14.0`
+
+This file is the canonical operator-facing coverage map for the current release line.
+It records what MA can prove today through repository tests, runtime artifacts, package dry-runs, and release gates.
+
+> [!IMPORTANT]
+> Coverage entries are production claims only when they point to concrete files, commands, or seeded runtime artifacts.
+> Candidate learnings and vault context may inform planning, but they do not become build evidence without owning-lane promotion.
+
+## Coverage summary
+
+| Category | Current state | Evidence |
+| --- | --- | --- |
+| Canonical install/launch contract | DONE | `README.md`, `DEMO.md`, `scripts/install.sh`, `scripts/release-verify.js` |
+| `ma` launcher into Codex | DONE | `bin/ma.js`, `test/cli-smoke.test.js`, `test/package-install-smoke.test.js` |
+| `$maestro` orchestration | DONE | `src/runtime/maestro-manager.js`, `src/runtime/maestro-state.js`, `test/runtime-state.test.js` |
+| Core skill surface | DONE | `skills/`, `skills/index.json`, `npm run skills:validate` |
+| Helper skill surface | DONE | `$align`, `$diagnose`, `$tdd`, `$cleanup` contracts in `skills/`, plugin mirror, and Helper Orchestration Core |
+| Build gate enforcement | DONE | `src/build-gate.js`, `test/build-gate.test.js`, `test/cli-smoke.test.js` |
+| Release issue gates | DONE | `src/release-issue-gates.js`, `docs/qa/release-issue-gates-0.14.0.json`, `test/release-issue-gates.test.js` |
+| Live GitMCP probe support | DONE | `src/mcp-live-client.js`, `src/skills.js`, `test/mcp-config.test.js` |
+| MCP policy and exposure control | DONE | `src/runtime/mcp-policy.js`, `src/runtime/exposure-catalog.js`, `test/mcp-policy.test.js`, `test/exposure-catalog.test.js` |
+| Plugin mirror discipline | DONE | `scripts/plugin-sync.js`, `npm run plugin:verify`, package dry-run |
+| Package dry-run | DONE | `npm run pack:inspect` |
+| Release check pipeline | DONE | `npm run release:check` |
+
+## Runtime and workflow coverage
+
+| Surface | Status | Notes |
+| --- | --- | --- |
+| `ma setup` scaffolding | DONE | seeds `.ma`, `.codex`, docs, sprint, MCP baseline files, and semantic runtime cores |
+| `ma bootstrap` | DONE | repairs packaged assets, support bundle, local runtime files, and optional starter MCP files |
+| `ma doctor` | DONE | reports check-only readiness without mutating local state |
+| `ma idea` | DONE | records a project brief and clears the idea gate |
+| `ma skills` | DONE | lists the 11 public runtime triggers |
+| `ma status --maestro-view` | DONE | reports release state, manager state, and next allowed actions |
+| `ma run '$maestro'` | DONE | bounded autonomous manager; coordinates without bypassing lane authority |
+| `ma run '$arch'` | DONE | architecture gate and spec artifacts |
+| `ma run '$sage'` | DONE | evidence gate with live MCP support and fallback classification |
+| `ma run '$flow'` | DONE | logic gate and transition review |
+| `ma run '$vet'` | DONE | security/compliance gate and package exposure intake |
+| `ma run '$vibe'` | DONE | DX/UX gate and outcome recording |
+| `ma run '$build'` | DONE | build-readiness gate with fail-closed prerequisites |
+| `ma merge` | DONE | branch policy enforcement |
+| `ma release` | DONE | release policy enforcement |
+
+## Semantic core coverage
+
+| Core | Status | Seeded artifact | Test evidence |
+| --- | --- | --- | --- |
+| Semantic Recording Core | DONE | `.ma/context/recording-core.json` | `test/runtime-state.test.js` |
+| Helper Orchestration Core | DONE | `.ma/context/helper-orchestration-core.json` | `test/helper-orchestration-core.test.js`, `test/full-flow.test.js` |
+| Environment Awareness Core | DONE | `.ma/context/environment-awareness-core.json` | `test/environment-awareness-core.test.js`, `test/runtime-state.test.js` |
+| Universal Plugin Broker Core | DONE | `.ma/context/universal-plugin-broker-core.json` | `test/universal-plugin-broker-core.test.js`, `test/runtime-state.test.js` |
+| Workspace Intelligence Runtime | DONE | `.ma/context/workspace-context-pack.json`, `.ma/context/workspace-effectiveness.json` | `test/workspace-intelligence-runtime.test.js` |
+| Learning Loop Core | DONE | `.ma/context/learning-loop-core.json` | `test/learning-loop-core.test.js` |
+| Active Autonomy Core | DONE | `.ma/context/active-autonomy-core.json` | `test/active-autonomy-contract.test.js` |
+| Context Economy Core | DONE | `.ma/context/context-economy-core.json` | `test/context-economy-core.test.js` |
+| Prompt Strategy Core | DONE | `.ma/context/prompt-strategy-core.json` | `test/prompt-strategy-core.test.js` |
+| Obsidian Integration Core | DONE | `.ma/context/obsidian-bridge.json`, `.ma/context/obsidian-vault-index.json` | `test/obsidian-integration-core.test.js` |
+| Obsidian Plugin Bridge | DONE | `plugins/meta-architect/obsidian/` | `test/obsidian-plugin-bridge.test.js` |
+| Ralph Execution Core | DONE | `scripts/ralph/prompt.md`, `.ma/plans/`, story contracts | `test/ralph-execution-core.test.js` |
+| Redaction Gateway | DONE | provider-bound redaction receipts | `test/redaction-gateway.test.js` |
+| Quorum Review Engine | DONE | review/confidence receipts | `test/quorum-review.test.js` |
+| Workspace Virtualizer | DONE | `.ma/context/workspace-virtualizer.json` | `test/workspace-virtualizer.test.js` |
+| Code Graph Rehearse | DONE | `.ma/context/code-graph-rehearse.json` | `test/code-graph-rehearse.test.js` |
+| Skills Registry Export | DONE | `.ma/context/skills-registry-export.json` | `test/skills-registry-export.test.js` |
+
+## Learning-loop reliability domains
+
+| Domain | Current coverage |
+| --- | --- |
+| Core & Orchestration | manager runs, lane handoffs, autonomy rules, and runtime-state repair |
+| Memory & Knowledge | `.ma/memory/notes.md`, semantic receipts, Obsidian vault context, project context |
+| Intelligence & Learning | prompt strategy, context economy, learning-loop records, workspace effectiveness checks |
+| Code Quality & Testing | sequential `node --test`, Biome checks, package install smoke, release check |
+| Security & Compliance | `$vet`, exposure catalog, MCP policy, redaction gateway, security playbooks |
+| Architecture & Methodology | `$arch`, decisions, architecture spec, native engineering patterns |
+| DevOps & Observability | hooks, audit logs, release sync, Linux package smoke, package dry-run |
+| Extensibility | skills, plugin mirror, MCP config, cross-agent skill export, Obsidian plugin |
+| Domain-Specific | MA release-hardening scenario, clone-data proof artifacts, trusted GitMCP source mapping |
+
+## Skill surface coverage
+
+Canonical public skills:
+
+- `maestro`
+- `arch`
+- `sage`
+- `flow`
+- `vet`
+- `vibe`
+- `build`
+- `align`
+- `diagnose`
+- `tdd`
+- `cleanup`
+
+Coverage state:
+
+- source skill contracts in `skills/`: DONE
+- generated manifest in `skills/index.json`: DONE
+- plugin-mirrored skill contracts in `plugins/meta-architect/skills/`: DONE
+- installable package skill surface via `postinstall`: DONE
+
+## Test coverage actually present
+
+| Test file | What it proves |
+| --- | --- |
+| `test/active-autonomy-contract.test.js` | anti-passive behavior contract and prompt surfaces |
+| `test/alignment-sentinel.test.js` | runtime drift detection and bounded recovery recommendations |
+| `test/build-gate.test.js` | build gate evaluation helpers |
+| `test/cli-smoke.test.js` | scaffold creation, build lock, launcher delegation, exit-code propagation |
+| `test/clone-data-artifacts.test.js` | production clone-data proof, ledger, RVF, and package visibility |
+| `test/code-graph-rehearse.test.js` | non-mutating code graph rehearsal and touchpoint extraction |
+| `test/context-economy-core.test.js` | context budget rules and exact-preserve safety boundaries |
+| `test/core-source-ingest.test.js` | local core-source ingest contracts |
+| `test/exposure-catalog.test.js` | package exposure and dependency-risk finding generation |
+| `test/environment-awareness-core.test.js` | existing skill, MCP, plugin, and opt-in global capability discovery with path redaction and non-evidence boundaries |
+| `test/full-flow.test.js` | full helper workflow reaches build-ready state |
+| `test/helper-orchestration-core.test.js` | `$align`, `$diagnose`, `$tdd`, `$cleanup` route composition, receipts, and non-gating boundaries |
+| `test/learning-loop-core.test.js` | nine-domain learning loop and fail-closed learning records |
+| `test/linux-package-artifacts.test.js` | Linux package artifact naming |
+| `test/mcp-config.test.js` | MCP endpoint validation and live-bridge behavior |
+| `test/mcp-policy.test.js` | runtime MCP policy validation |
+| `test/obsidian-integration-core.test.js` | vault-context indexing and graph-link behavior |
+| `test/obsidian-plugin-bridge.test.js` | in-app plugin bridge, metadata, queue, frontmatter, attachments, protocol helpers |
+| `test/package-exports.test.js` | public package API exports core runtime capabilities |
+| `test/package-install-smoke.test.js` | packed npm install, postinstall skill installation, launcher behavior, helper flow |
+| `test/policy.test.js` | merge/release branch policy enforcement |
+| `test/prompt-strategy-core.test.js` | prompt strategy policy and high-risk preservation |
+| `test/quorum-review.test.js` | review vote confidence and minority reports |
+| `test/ralph-execution-core.test.js` | PRD/story execution contract and progress loop |
+| `test/redaction-gateway.test.js` | provider-bound context redaction |
+| `test/release-issue-gates.test.js` | issue gate schema and production-pass requirements |
+| `test/release-state.test.js` | release-state persistence and validation |
+| `test/release-sync.test.js` | release metadata synchronization |
+| `test/runtime-state.test.js` | runtime snapshot, repair, seeded artifacts, manager state, Obsidian, learning-loop integration |
+| `test/skills-registry-export.test.js` | multi-agent skill export and compatibility matrix |
+| `test/universal-plugin-broker-core.test.js` | hybrid plugin broker manifest validation, local bundle isolation, MCP wrapper generation, vendor config injection, idempotency, and MA context skill export |
+| `test/workspace-intelligence-runtime.test.js` | capability composition, semantic receipts, workspace effectiveness |
+| `test/workspace-virtualizer.test.js` | bounded verification sandbox receipts |
+
+Current automated verification count:
+
+- 36 test files executed by `npm test`
+- 36/36 passing on the latest full release verification run
+
+## Packaging and plugin coverage
+
+| Surface | Status | Mechanism |
+| --- | --- | --- |
+| npm package identity | DONE | `@jstn-sdk/ma@0.14.0` |
+| public scoped package config | DONE | `publishConfig.access = public` |
+| package files allowlist | DONE | `package.json > files` |
+| production ignore policy | DONE | `.npmignore` plus `npm pack --dry-run` |
+| production data artifacts | DONE | `data/clone-data.proof.json`, `data/clone-data.ledger.json`, `data/clone-data.rvf` |
+| demo guide package visibility | DONE | `DEMO.md` included in dry-run package output |
+| skill bundle tarball | DONE | `npm run skills:pack` |
+| package dry-run | DONE | `npm run pack:inspect` |
+| plugin mirror sync | DONE | `npm run plugin:sync` |
+| plugin mirror verification | DONE | `npm run plugin:verify` |
+| plugin manifest | DONE | `plugins/meta-architect/.codex-plugin/plugin.json` |
+| local marketplace metadata | DONE | `.agents/plugins/marketplace.json` |
+
+## Release and docs coverage
+
+| Surface | Status | Notes |
+| --- | --- | --- |
+| `README.md` canonical install block | DONE | jsDelivr installer, npm fallback, `ma --madmax --high`, uninstall commands |
+| `DEMO.md` production demo | DONE | real MA release-hardening scenario and end-to-end smoke commands |
+| `docs/getting-started.md` onboarding | DONE | source checkout, helper path, gates, runtime artifacts |
+| `docs/skills.md` skill reference | DONE | trigger-by-trigger contract guide |
+| `docs/mcp-setup.md` evidence policy | DONE | GitMCP endpoint semantics and bridge guidance |
+| `docs/release-spec.md` release policy | DONE | `v0.14.0` aligned |
+| `docs/qa/release-readiness-0.14.0.md` | DONE | current QA evidence |
+| `scripts/release-verify.js` | DONE | checks install docs, demo doc, issue gates, package metadata, `.npmignore` |
+
+## Known limits
+
+These are explicit operating limits, not stale gaps:
+
+1. Live `$sage` verification depends on reachable GitMCP endpoints or a trusted local bridge.
+2. Obsidian context records as `vault_context`; it does not become `build_evidence` without owning-lane promotion.
+3. Candidate learning records can inform context, but cannot mutate release state or durable policy.
+4. Linux native package build/smoke checks require a Linux environment for full distro-package validation.
+5. A local shell publish cannot generate npm provenance; provenance requires a supported CI/CD provider.
+
+## Current truth statement
+
+Meta-Architect currently covers the `v0.14.0` release bar for:
+
+- canonical install and launch
+- Codex-hosted runtime entry
+- `$maestro` bounded orchestration
+- gated architecture/evidence/logic/security/DX/build workflow
+- helper skills backed by Helper Orchestration Core receipts that do not mutate release gates
+- existing workspace skill, MCP, and plugin discovery through Environment Awareness Core without auto-running or promoting capabilities to build evidence
+- universal plugin brokering through MCP vendor injection plus `.agents/skills` context payloads across supported agents
+- Obsidian as semantic brain context
+- learning-loop reliability across nine domains
+- Ralph-style story execution after gates
+- context economy and prompt strategy cores
+- plugin mirroring, MCP policy, skill packaging, package proof, and release verification
+
+This repository is not a toy demo.
+Coverage claims above are tied to concrete files, commands, tests, or package dry-run evidence.

package/DEMO.md

@@ -0,0 +1,274 @@
+# Meta-Architect Demo Guide
+
+Last verified: 2026-06-03
+Release line: `v0.14.0`
+Package: `@jstn-sdk/ma`
+
+This demo uses a real existing project: this Meta-Architect repository.
+It highlights how MA helps a workspace move from idea and context to gated architecture, evidence, review, build readiness, package proof, and release hygiene.
+
+## What this proves
+
+| Capability area | Real project surface |
+| --- | --- |
+| Core & Orchestration | `$maestro`, `.ma/state/manager-runs.json`, `.ma/state/maestro-state.json` |
+| Memory & Knowledge | `.ma/memory/notes.md`, `.ma/context/project.md`, `.ma/context/learning-loop-core.json` |
+| Intelligence & Learning | `.ma/context/prompt-strategy-core.json`, `.ma/context/context-economy-core.json`, `.ma/context/workspace-effectiveness.json` |
+| Code Quality & Testing | `npm test`, `npm run check`, `test/*` |
+| Security & Compliance | `$vet`, `.ma/specs/security.md`, `.ma/evidence/audits.json`, redaction gateway |
+| Architecture & Methodology | `$arch`, `.ma/specs/architecture.md`, `.ma/decisions.json` |
+| DevOps & Observability | `npm run release:check`, `.ma/hooks/audit.log`, `.ma/runbook.md` |
+| Extensibility | `skills/`, `plugins/meta-architect/`, `mcp/servers.json`, Obsidian plugin bridge |
+| Domain-Specific | real MA release/package workflow, clone-data proof files, Obsidian vault context boundaries |
+
+> [!IMPORTANT]
+> This is not a mock demo.
+> The commands below use the current package scripts, seeded `.ma` runtime files, real skill contracts, and package dry-run output.
+
+## 1. Install and enter MA
+
+Recommended POSIX install:
+
+```bash
+curl -fsSLo install.sh https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh && curl -fsSLo install.sh.sha256 https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh.sha256 && sed 's#scripts/install.sh#install.sh#' install.sh.sha256 | sha256sum -c - && sh install.sh
+```
+
+Canonical npm fallback:
+
+```bash
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+ma --madmax --high
+```
+
+Remove only MA:
+
+```bash
+npm uninstall -g @jstn-sdk/ma
+```
+
+Remove MA and Codex:
+
+```bash
+npm uninstall -g @jstn-sdk/ma @openai/codex
+```
+
+Expected result:
+
+- `ma` launches the Codex runtime posture.
+- the MA skill surface is installed into the active Codex home.
+- the in-session workflow can start with `$maestro`.
+
+## 2. Run the real repo-local setup
+
+Use this when demonstrating from a source checkout.
+
+```bash
+git clone https://github.com/JustineDevs/meta-architect.git
+cd meta-architect
+npm install
+npm link
+ma setup
+ma doctor
+ma status --maestro-view
+```
+
+Expected seeded runtime files include:
+
+| Runtime file | Why it matters |
+| --- | --- |
+| `.ma/release.json` | release gate source of truth |
+| `.ma/decisions.json` | lane decision log |
+| `.ma/context/recording-core.json` | semantic recording map |
+| `.ma/context/learning-loop-core.json` | verified-learning loop across reliability domains |
+| `.ma/context/obsidian-bridge.json` | Obsidian brain-context boundary |
+| `.ma/context/prompt-strategy-core.json` | prompt strategy policy |
+| `.ma/context/context-economy-core.json` | terse-output/context-budget policy |
+| `.ma/context/workspace-context-pack.json` | shared workspace intelligence |
+| `.ma/context/environment-awareness-core.json` | existing skill, MCP, and plugin capability inventory |
+| `.ma/context/universal-plugin-broker-core.json` | hybrid MCP + MA skill plugin broker contract |
+| `.ma/evidence/semantic-receipts.json` | semantic receipt registry |
+| `.ma/runbook.md` | local helper workflow |
+
+## 3. Demo the MA release-hardening workflow
+
+Scenario: make this repository release-ready without bypassing architecture, evidence, logic, security, DX, or build gates.
+
+Terminal helper path:
+
+```bash
+ma idea "Prepare Meta-Architect v0.14.0 for a production package release with real install docs, Obsidian brain-context support, learning-loop reliability, and package proof artifacts."
+ma run '$maestro'
+ma status --maestro-view
+```
+
+Direct in-session path inside Codex:
+
+```text
+$maestro
+$arch
+$sage
+$flow
+$vet
+$vibe
+$build
+```
+
+Expected behavior:
+
+- `$maestro` chooses the next safe lane instead of passively asking what to do.
+- `$arch` records architecture intent and constraints.
+- `$sage` separates technical evidence from discovery or vault context.
+- `$flow` checks logic/state transitions.
+- `$vet` preserves security and compliance blockers.
+- `$vibe` reviews developer/user experience risk.
+- `$build` stays locked until upstream gates are green.
+
+## 4. Demo learning loop reliability
+
+The learning loop turns verified outcomes into future reliability context.
+It does not auto-promote guesses.
+
+```bash
+node --test test/learning-loop-core.test.js
+node -e "import('./index.js').then(({createDefaultLearningLoopCore, evaluateLearningLoopReadiness}) => console.log(evaluateLearningLoopReadiness(createDefaultLearningLoopCore())))"
+```
+
+Expected:
+
+- all nine reliability domains exist
+- candidate learnings cannot mutate release state
+- verified learnings require source, evidence, authority, and next verification
+
+## 5. Demo Obsidian as brain context, not build evidence
+
+MA treats Obsidian notes as semantic brain context.
+They can inform planning and workspace understanding, but they are not build evidence unless an owning lane promotes a claim with proof.
+
+```bash
+node --test test/obsidian-integration-core.test.js test/obsidian-plugin-bridge.test.js
+```
+
+Expected:
+
+- vault notes are indexed as `vault_context`
+- graph links are represented with Obsidian wikilinks
+- plugin bridge APIs support active note context, frontmatter authority, request queue, attachments, protocol handling, rename-safe links, and metadata graph extraction
+- plugin-side actions do not directly mutate `.ma/release.json`, `.ma/decisions.json`, `.ma/plans/`, or `.ma/specs/`
+
+## 6. Demo Ralph-style execution handoff
+
+Ralph execution is a core execution contract after MA gates, not a separate release authority.
+
+```bash
+node --test test/ralph-execution-core.test.js
+```
+
+Expected:
+
+- approved PRD/story contracts are story-sized
+- progress is append-only and scoped
+- execution cannot bypass `$arch -> $sage -> $flow -> $vet -> $vibe -> $build`
+
+## 7. Demo context economy and prompt strategy
+
+MA uses first-party context economy and prompt strategy cores to keep responses concise without removing technical precision, security warnings, schemas, or verification gaps.
+
+```bash
+node --test test/context-economy-core.test.js test/prompt-strategy-core.test.js
+```
+
+Expected:
+
+- terse summaries preserve exact code, commands, warnings, and authority fields
+- prompt techniques are selected through MA lane policy
+- security and high-risk content bypasses unsafe compression
+
+## 8. Demo extensibility and package surfaces
+
+```bash
+npm run skills:manifest
+npm run plugin:sync
+npm run skills:validate
+npm run plugin:verify
+npm run skills:pack
+node --test test/skills-registry-export.test.js test/mcp-policy.test.js test/environment-awareness-core.test.js test/universal-plugin-broker-core.test.js
+```
+
+Expected:
+
+- `skills/index.json` is current
+- `plugins/meta-architect/skills/` mirrors `skills/`
+- all public skills validate
+- MCP policy prevents unsafe or ambiguous evidence surfaces
+- cross-agent skill export uses canonical `.agents/skills` semantics where applicable
+- Environment Awareness Core discovers repo-local skills, MCP servers, and plugin manifests as `available_capability`, never `build_evidence`
+- Universal Plugin Broker Core installs local plugin bundles into an isolated MA home, generates executable MCP wrappers, injects detected Claude Code / Antigravity / Cursor / Codex configs, and exports MA context skills
+
+## 9. Demo production package proof
+
+```bash
+npm run demo:smoke
+node scripts/release-verify.js
+npm run check
+npm test
+npm pack --dry-run --ignore-scripts --cache ./.npm-cache
+```
+
+Expected package proof:
+
+- package name is `@jstn-sdk/ma`
+- version line is `0.14.0`
+- `npm run demo:smoke` creates a realistic Northstar Logistics workspace and Obsidian vault under `/tmp/ma-real-demo-*`
+- the smoke writes `.ma/evidence/real-demo-smoke-proof.json` in that temporary workspace
+- `DEMO.md` is included
+- `COVERAGE.md` is included
+- `data/clone-data.proof.json`, `data/clone-data.ledger.json`, and `data/clone-data.rvf` are included
+- runtime state such as canonical `.ma/` (plus legacy `.omx/` orchestration state), `node_modules/`, `test/`, and local caches are excluded
+
+## 10. Full release demo
+
+For a buyer-facing walkthrough, use the real demo kit:
+
+- [Real Demo Runbook](./docs/demo/REAL_DEMO_RUNBOOK.md)
+- [Demo Story](./docs/demo/DEMO_STORY.md)
+- [Prospect Checklist](./docs/demo/PROSPECT_CHECKLIST.md)
+
+The strongest single command:
+
+```bash
+npm run release:check
+```
+
+What it proves:
+
+- release metadata is coherent
+- public install docs include jsDelivr and npm fallback paths
+- skills manifest, plugin mirror, skill validation, and skill packing work
+- Biome check passes
+- full sequential test suite passes
+- npm dry-run package contents are production-safe
+
+## Current verified inventory
+
+| Surface | Current reality |
+| --- | --- |
+| Release line | `v0.14.0` |
+| Package | `@jstn-sdk/ma` |
+| Public skills | 11 (`maestro`, `arch`, `sage`, `flow`, `vet`, `vibe`, `build`, `align`, `diagnose`, `tdd`, `cleanup`) |
+| Runtime namespace | `.ma/` |
+| Production data artifacts | `data/clone-data.proof.json`, `data/clone-data.ledger.json`, `data/clone-data.rvf` |
+| Coverage artifact | `COVERAGE.md` |
+| Obsidian plugin payload | `plugins/meta-architect/obsidian/` |
+| Learning loop artifact | `.ma/context/learning-loop-core.json` |
+| Helper orchestration artifact | `.ma/context/helper-orchestration-core.json` |
+| Environment awareness artifact | `.ma/context/environment-awareness-core.json` |
+| Universal plugin broker artifact | `.ma/context/universal-plugin-broker-core.json` |
+| Package hygiene | `.npmignore` plus `package.json#files` allowlist |
+
+## Troubleshooting
+
+- If `ma --madmax --high` does not launch Codex, confirm `@openai/codex` is installed globally and callable on `PATH`.
+- If `$sage` cannot verify evidence, inspect `mcp/servers.json` and use repository-form GitMCP endpoints such as `https://gitmcp.io/{owner}/{repo}`.
+- If `$build` stays locked, run `ma status --maestro-view` and resolve the blocking gate.
+- If Obsidian context looks empty, verify the vault path and that notes contain links, tags, headings, or frontmatter.
+- If package output includes runtime state, inspect `.npmignore`, `package.json#files`, and `npm pack --dry-run`.