@jstn-sdk/ma 0.1.11 → 0.1.13

package/README.md

@@ -18,9 +18,30 @@
 </div>
 
 > [!IMPORTANT]
-> Meta-Architect `v0.1.11` is a production-grade skills line.
+> Meta-Architect `v0.1.13` is a production-grade skills line.
 > It is not a lightweight demo branch.
-> From `v0.1.11` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
+> From `v0.1.13` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
+
+## Navigate
+
+<table>
+  <tr>
+    <td><strong>Start</strong></td>
+    <td><a href="#cli-install">CLI Install</a> · <a href="#quick-start">Quick Start</a> · <a href="#setup">Setup</a></td>
+  </tr>
+  <tr>
+    <td><strong>Operate</strong></td>
+    <td><a href="#skill-surface">Skill Surface</a> · <a href="#gated-lanes">Gated Lanes</a> · <a href="#gate-model">Gate Model</a> · <a href="#learning-loop-core">Learning Loop Core</a></td>
+  </tr>
+  <tr>
+    <td><strong>Ship</strong></td>
+    <td><a href="#release-and-packaging">Release and Packaging</a> · <a href="#package-surface">Package Surface</a> · <a href="#release-hygiene">Release Hygiene</a></td>
+  </tr>
+  <tr>
+    <td><strong>Reference</strong></td>
+    <td><a href="#repository-structure">Repository Structure</a> · <a href="#documentation">Documentation</a> · <a href="#core-maintainers">Core Maintainers</a></td>
+  </tr>
+</table>
 
 ## Overview
 
@@ -31,21 +52,31 @@ It adds:
 - an architecture-first lane before implementation
 - evidence-backed OSS selection through GitMCP-connected sources
 - explicit logic, security, and DX/UX review gates
+- a singular `$maestro` bounded autonomous manager plus non-gating helper skills for alignment, diagnosis, test-first work, and cleanup
 - installable skills and a reproducible package surface
 
 > [!NOTE]
 > Meta-Architect does not replace your coding runtime.
 > It wraps that runtime with architecture, evidence, gate enforcement, and release-sensitive workflow control.
 
+## Acknowledgement
+
+Meta-Architect was shaped in part by ideas surfaced through the `oh-my-codex` ecosystem.
+Acknowledgement is due for the inspiration around Codex-native workflow packaging, skill distribution, and practical delivery surfaces that helped inform this project.
+
 ## Support
 
 - [GitHub Sponsors](https://github.com/sponsors/JustineDevs)
 - [Buy Me A Coffee](https://www.buymeacoffee.com/justinedevs)
 
 <table>
+  <tr>
+    <td><strong>Linux-native packages</strong></td>
+    <td><code>.deb</code> for Debian-family distros, <code>.pkg.tar.xz</code> for Arch-family distros, and <code>.rpm</code> for Fedora/openSUSE-style distros</td>
+  </tr>
   <tr>
     <td><strong>npm package</strong></td>
-    <td><code>@jstn-sdk/ma</code></td>
+    <td><code>@jstn-sdk/ma</code> (fallback install path)</td>
   </tr>
   <tr>
     <td><strong>Helper command</strong></td>
@@ -57,7 +88,7 @@ It adds:
   </tr>
   <tr>
     <td><strong>Release line</strong></td>
-    <td><code>v0.1.11</code></td>
+    <td><code>v0.1.13</code></td>
   </tr>
   <tr>
     <td><strong>License</strong></td>
@@ -97,11 +128,70 @@ It adds:
 > [!TIP]
 > The most reliable default environment is a Unix-like shell with Git, Node.js, and an MCP-capable runtime already configured.
 
-## Recommended Default Flow
+## CLI Install
+
+macOS, Linux, WSL, and Git-Bash:
 
-Meta-Architect is intended to be consumed as an installed package, not primarily as a git clone.
+```bash
+# One-line install (POSIX shells only; see Windows note below)
+curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh
+```
+
+This jsDelivr-backed installer runs the canonical package install:
+
+```bash
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+```
 
-Primary product path:
+Then it seeds the local MA runtime with `ma setup`. Start with:
+
+```bash
+ma --madmax --high
+```
+
+Windows note: use WSL or Git-Bash for the one-line POSIX installer. In PowerShell, use the npm fallback command directly.
+
+## Default Install Surfaces
+
+Meta-Architect is a Codex-native session workflow. The jsDelivr CLI installer is the recommended quick-start path for POSIX shells; Linux distro packages remain available for distro-managed installs.
+
+<details>
+<summary><strong>Platform package commands</strong></summary>
+
+### Debian, Ubuntu, Linux Mint, Pop!_OS
+
+Download the GitHub release `.deb` asset and install it with your normal package command:
+
+```bash
+sudo apt install ./meta-architect_<version>_all.deb
+```
+
+### Arch, Manjaro, EndeavourOS
+
+Download the GitHub release pacman package asset and install it with:
+
+```bash
+sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xz
+```
+
+### Fedora, RHEL-family, openSUSE
+
+Download the GitHub release RPM asset and install it with your distro-native command:
+
+```bash
+sudo dnf install ./meta-architect-<version>-1.noarch.rpm
+# or
+sudo zypper install ./meta-architect-<version>-1.noarch.rpm
+```
+
+These packages install the Meta-Architect payload and expose `ma` / `meta-architect`, but the product still runs inside a Codex-native session. They do not create a separate desktop or terminal product.
+
+</details>
+
+<details open>
+<summary><strong>npm fallback and runtime assumptions</strong></summary>
+
+### npm fallback
 
 ```bash
 # Install
@@ -125,8 +215,9 @@ What this assumes:
 - the product experience happens through the skill workflow inside Codex
 
 > [!IMPORTANT]
-> The recommended default flow is package-first.
-> The git clone path is for contributors and maintainers, not the main user-facing install story.
+> The jsDelivr installer is a POSIX-shell convenience wrapper around the canonical npm install. Use the distro packages when you specifically need distro-managed install assets.
+
+</details>
 
 ## Repository Branch Strategy
 
@@ -147,7 +238,25 @@ Meta-Architect’s repository workflow follows a stricter release posture focuse
 
 ### Package setup
 
-Install the consumer package directly:
+Debian-family install:
+
+```bash
+sudo apt install ./meta-architect_<version>_all.deb
+```
+
+Arch-family install:
+
+```bash
+sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xz
+```
+
+Fedora/openSUSE install:
+
+```bash
+sudo dnf install ./meta-architect-<version>-1.noarch.rpm
+```
+
+npm fallback:
 
 ```bash
 # Install
@@ -230,7 +339,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.11
+8. Delivery plan for v0.1.13
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -238,10 +347,12 @@ Required output:
 
 ### 3. Run the full trigger sequence inside Codex
 
-After `$arch`, continue exactly like the usage workflow:
+The singular umbrella in-session entry point is `$maestro`. It is the bounded autonomous manager for the in-session workflow. The package does not ship a separate `$meta-architect` skill.
+
+The release-gated sequence stays fixed:
 
 ```text
-$maestro
+$arch
 $sage
 $flow
 $vet
@@ -249,6 +360,15 @@ $vibe
 $build
 ```
 
+Optional publishable non-gating helper skills available around that sequence:
+
+```text
+$align
+$diagnose
+$tdd
+$cleanup
+```
+
 See [example/usage-workflow.md](./example/usage-workflow.md) for the full prompt templates for each step.
 
 ### 4. Secondary helper path
@@ -294,17 +414,17 @@ Example:
 
 ```json
 {
-  "category": "meta-list",
-  "repo": "sindresorhus/awesome",
-  "endpoint": "https://gitmcp.io/sindresorhus/awesome"
+  "category": "candidate",
+  "repo": "owner/repo",
+  "endpoint": "https://gitmcp.io/owner/repo"
 }
 ```
 
-Recommended starter endpoints:
+Recommended source-selection posture:
 
-- `https://gitmcp.io/sindresorhus/awesome`
-- `https://gitmcp.io/dzharii/awesome-typescript`
-- `https://gitmcp.io/sbilly/awesome-security`
+- use packaged native references to narrow candidate families first
+- map serious candidates to exact upstream GitMCP endpoints
+- verify final choices against upstream repos and official docs before approval
 
 Core discovery standard:
 
@@ -322,6 +442,12 @@ Core discovery standard:
 - use Open-source Projects for curated OSS discovery and detailed project writeups
 - treat all of these as discovery acceleration, then convert promising finds into exact upstream GitMCP mappings and official-doc checks for `$sage`
 
+Useful native references:
+
+- `skills/maestro/references/native-ingest-map.md`
+- `skills/sage/references/source-selection.md`
+- `skills/vet/references/security-playbooks.md`
+
 Canonical `$sage` order:
 
 1. Start with the upstream repo and official docs if you already know them.
@@ -339,7 +465,7 @@ Canonical `$sage` order:
 If you need scripted repo-local validation rather than the interactive runtime workflow:
 
 ```bash
-ma idea "Build a real-time collaborative whiteboard for product teams"
+ma idea "Prepare Meta-Architect v0.1.13 for a production package release with real install docs, Obsidian brain-context support, learning-loop reliability, and package proof artifacts."
 ma run '$arch'
 ma run '$sage'
 ma run '$flow'
@@ -370,11 +496,11 @@ Expected helper-path build output:
 ```text
 Build gate is green.
 Suggested branches:
-- feature/ui
-- feature/api
+- feature/implementation
+- feature/verification
 Optional worktree commands:
-git worktree add ../ui feature/ui
-git worktree add ../api feature/api
+git worktree add ../implementation feature/implementation
+git worktree add ../verification feature/verification
 ```
 
 ### 7. Simple command guide
@@ -384,6 +510,8 @@ Meta-Architect has two surfaces.
 - terminal helper commands
 - in-session skills
 
+The umbrella in-session entry point is `$maestro`. There is no separate shipped `$meta-architect` skill surface.
+
 Terminal commands are normal shell commands you run in the terminal:
 
 ```bash
@@ -391,7 +519,10 @@ ma setup
 ma init
 ma idea "Build a product"
 ma status
+ma status --maestro-view
+ma verify --architect
 ma run '$arch'
+ma run '$maestro' --auto-heal --parallel
 ```
 
 In-session skills are prompts you use inside the Codex conversation after launch:
@@ -404,12 +535,21 @@ $flow
 $vet
 $vibe
 $build
+$align
+$diagnose
+$tdd
+$cleanup
 ```
 
 Plain-language difference:
 - `ma ...` = helper commands in the terminal
 - `$...` = the product experience inside Codex
 
+Autonomous-manager contract:
+- `$maestro` is the only umbrella in-session surface
+- it manages the next allowed step and lane handoff, but it does not replace the gated outputs owned by `$arch -> $sage -> $flow -> $vet -> $vibe -> $build`
+- `$align`, `$diagnose`, `$tdd`, and `$cleanup` are publishable helper skills that do not move release gates
+
 What `ma setup` and `ma init` do:
 - both currently do the same thing
 - they create the local support files and folders
@@ -429,13 +569,36 @@ What `ma doctor` does:
 
 What to use when:
 - use Codex and run the skills in-session
-- use `$maestro` when you want Meta-Architect to choose the best next step for you
+- use `$maestro` when you want Meta-Architect to choose the best next step for you or act as the bounded autonomous manager for the umbrella workflow
 - use `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` inside the Codex session
+- use `$align`, `$diagnose`, `$tdd`, or `$cleanup` when a helper is enough and the release gate should stay where it is
 - use `ma bootstrap` when you want the lazy-user setup path
 - use `ma doctor` when you want a check-only environment report
 - use `ma setup` or `ma init` only when you want local scaffolding or scripted helper automation from the terminal
 - use `ma sdk-path` when you need the exact installed support-bundle path for packaged prompts, MCP files, sprint files, scripts, plugin metadata, or templates
 
+## Skill Surface
+
+> [!TIP]
+> Remember the surface as **manager -> gated lanes -> helpers**.
+> `$maestro` coordinates, gated lanes move release state, and helper skills support without unlocking build.
+
+Meta-Architect’s in-session surface has three layers:
+
+- umbrella autonomous manager: `$maestro`
+- fixed gated lanes: `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
+- non-gating helper skills: `$align`, `$diagnose`, `$tdd`, `$cleanup`
+
+Helper skills are publishable surfaces, but they do not own release-state transitions.
+
+> [!NOTE]
+> MA also discovers existing repo-local skills, MCP configs, and plugin manifests through the Environment Awareness Core.
+> Discovered capabilities are `available_capability` context only: MA may select them when task-relevant, but it does not auto-run, mutate, or treat them as build evidence.
+
+> [!NOTE]
+> Universal Plugin Broker Core uses a hybrid model for cross-agent plugins: MCP stdio tooling for hosts that support MCP config injection, and `.agents/skills` context payloads for the broader supported-agent surface.
+> Plugin broker receipts are compatibility configuration, not build evidence or lane approval.
+
 ## Core Maintainers
 
 <table>
@@ -451,47 +614,118 @@ What to use when:
   </tr>
 </table>
 
-## Core Triggers
+## Gated Lanes
+
+> [!IMPORTANT]
+> Read this as a release runway: **design -> evidence -> logic -> security -> experience -> build**.
+> Do not skip lanes when the release gate is still locked.
+
+<details open>
+<summary><strong>Release-gated lane map</strong></summary>
 
 | Trigger | Purpose | Main output | Gate effect |
 | --- | --- | --- | --- |
 | `$arch` | Produce the first-pass architecture blueprint | decision entry | `architecture_status = APPROVED` |
 | `$sage` | Ground major choices in configured GitMCP evidence | evidence records | `evidence_status = VERIFIED | PARTIAL | MISSING` |
-| `$flow` | Review baseline logic and state transitions | logic review entry | `logic_status = GREEN | RED` |
-| `$vet` | Run baseline security and dependency review | audit and CVE records | `security_status = GREEN | RED` |
-| `$vibe` | Review developer and user experience implications | DX/UX outcome record | `experience_status = GREEN | RED | WAIVED` |
-| `$build` | Unlock bounded build planning | build-ready decision + `.ma/plans/build.md` | `build_status = READY` |
+| `$flow` | Review baseline logic and state transitions | logic review entry | `logic_status = PENDING | GREEN | RED` |
+| `$vet` | Run baseline security and dependency review | audit and CVE records | `security_status = PENDING | GREEN | RED` |
+| `$vibe` | Review developer and user experience implications | DX/UX outcome record | `experience_status = PENDING | GREEN | RED | WAIVED` |
+| `$build` | Run a bounded build-readiness loop | build-ready decision + `.ma/plans/build.md` | `build_status = READY | RUNNING | DONE` |
+
+</details>
+
+## Helper Skills
+
+<details>
+<summary><strong>Non-gating helper skill map</strong></summary>
+
+| Trigger | Purpose | Gate effect |
+| --- | --- | --- |
+| `$align` | Normalize terminology, tighten scope, and improve prompt or docs clarity | none |
+| `$diagnose` | Decompose blocked-lane symptoms into hypotheses and next probes | none |
+| `$tdd` | Lock behavior with regression-first or test-first scaffolding | none |
+| `$cleanup` | Simplify noisy output and run a final-pass anti-slop cleanup | none |
+
+> [!NOTE]
+> Helper skills are backed by `helper_orchestration_core`.
+> They write helper receipts, return authority to `$maestro` or the owning lane, and never record as gate approval.
+
+</details>
 
 ## Gate Model
 
 Meta-Architect is intentionally fail-closed.
 
+> [!NOTE]
+> Green states allow the next safe move.
+> Red or locked states preserve the blocker instead of pretending the workflow is ready.
+
+<details open>
+<summary><strong>Status vocabulary</strong></summary>
+
 | Status | Meaning |
 | --- | --- |
 | `CLEAR` | enough input exists to proceed |
 | `APPROVED` | the architecture lane produced an acceptable first-pass blueprint |
 | `VERIFIED` | live evidence was grounded through approved GitMCP sources |
 | `PARTIAL` | evidence is configured but live proof is incomplete or unavailable |
+| `PENDING` | the lane has recorded interim review state but not final approval or rejection yet |
 | `GREEN` | the current baseline review passed |
 | `RED` | the lane is blocked or failed |
 | `WAIVED` | the lane was intentionally waived with a recorded reason |
 | `LOCKED` | downstream work is not allowed yet |
-| `READY` | the next gated step is allowed |
+| `READY` | the next bounded gated step is prepared |
+| `RUNNING` | the bounded build substep is active |
+| `DONE` | the current bounded build substep completed with recorded evidence |
+
+</details>
 
 > [!CAUTION]
 > `$build` must stay locked until the upstream release state in `.ma/release.json` satisfies the gate contract.
 > Meta-Architect is designed to stop on blockers rather than silently continue.
 > Rich runtime artifacts live in `.ma/context/`, `.ma/specs/`, `.ma/plans/`, and `.ma/runbook.md`.
 
+## Learning Loop Core
+
+> [!NOTE]
+> Meta-Architect records learnings as candidates first.
+> A learning can influence future context only after it has source, evidence, authority, and a next verification path.
+
+<details open>
+<summary><strong>Reliability domains</strong></summary>
+
+| Domain | What improves over time |
+| --- | --- |
+| Core & Orchestration | manager runs, lane handoffs, and autonomous routing |
+| Memory & Knowledge | project notes, Obsidian vault context, and semantic receipts |
+| Intelligence & Learning | prompt strategy, context budgeting, and rehearsal outcomes |
+| Code Quality & Testing | test failures, build results, and execution learnings |
+| Security & Compliance | trust-boundary findings, exposure scans, and redaction receipts |
+| Architecture & Methodology | decisions, tradeoffs, and reusable patterns |
+| DevOps & Observability | release checks, package smokes, runtime traces, and hook audits |
+| Extensibility | skills, plugins, MCP policy, and host compatibility |
+| Domain-Specific | stack facts, project domain notes, and trusted source context |
+
+</details>
+
 ## Release and Packaging
 
-Meta-Architect has two related but different distribution surfaces.
+Meta-Architect has three related but different distribution surfaces.
+
+> [!TIP]
+> Use **npm** for the public package, **Linux packages** for distro-managed installs, and **skills bundle** when only the skill payload is needed.
+
+<details open>
+<summary><strong>Distribution surfaces</strong></summary>
 
 | Surface | Purpose | Produced by |
 | --- | --- | --- |
+| Linux native packages | distro-managed install assets for Debian-family and Arch-family environments | `npm run linux:packages:build` and GitHub release assets |
 | npm package | public package containing the installable Meta-Architect skills/plugin system, docs, scripts, and canonical skills | `npm publish` or `npm pack` |
 | skills bundle | narrower tarball containing `skills/` only | `npm run skills:pack` |
 
+</details>
+
 Required packaging commands:
 
 ```bash
@@ -499,6 +733,8 @@ npm run skills:manifest
 npm run skills:validate
 npm run skills:pack
 npm run skills:install -- --path ./dist/installed-skills
+npm run linux:packages:build
+npm run release:assets
 npm run pack:inspect
 ```
 
@@ -507,6 +743,9 @@ Pre-publish rules:
 - `skills/index.json` must be current
 - `npm run skills:validate` must pass
 - `dist/meta-architect-skills.tgz` must exist
+- `dist/meta-architect_<version>_all.deb` must exist for Debian-family installs
+- `dist/meta-architect-<version>-1-any.pkg.tar.xz` must exist for Arch-family installs
+- `dist/meta-architect-<version>-1.noarch.rpm` must exist for Fedora/openSUSE-style installs
 - `npm pack --dry-run` must show only intended public files
 - docs must match the real skills/plugin and release behavior
 
@@ -521,11 +760,13 @@ Maintainer version-bump flow:
 3. Run `npm run release:verify`
 4. Run `npm run release:check`
 5. Create and push tag `v<version>`
-6. Preferred publish path: publish from `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
+6. Build and smoke-check the Linux native packages with `npm run linux:packages:build`, `npm run linux:packages:smoke`, and `npm run release:assets` on Linux
+7. Preferred publish path: publish from `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
 7. Local shell fallback when not publishing from GitHub Actions or GitLab CI/CD:
    - Stable publish: `npm publish --access public`
    - Prerelease publish: `npm publish --access public --tag <lane>`
 8. Verify publish state with `npm view @jstn-sdk/ma version dist-tags time --json`
+9. Confirm the GitHub release includes `dist/meta-architect-skills.tgz`, `meta-architect_<version>_all.deb`, `meta-architect-<version>-1-any.pkg.tar.xz`, and `meta-architect-<version>-1.noarch.rpm`
 
 Provenance note:
 - `npm publish --provenance` requires a supported cloud CI/CD provider
@@ -547,7 +788,7 @@ Release automation:
 <table>
   <tr>
     <td><strong>Included</strong></td>
-    <td><code>bin/</code>, <code>skills/</code>, <code>docs/</code>, <code>scripts/</code>, <code>index.js</code>, <code>README.md</code>, <code>LICENSE</code></td>
+    <td><code>bin/</code>, <code>skills/</code>, <code>docs/</code>, <code>data/</code>, <code>scripts/</code>, <code>index.js</code>, <code>README.md</code>, <code>DEMO.md</code>, <code>COVERAGE.md</code>, <code>LICENSE</code></td>
   </tr>
   <tr>
     <td><strong>Excluded</strong></td>
@@ -557,6 +798,9 @@ Release automation:
 
 ## Repository Structure
 
+> [!NOTE]
+> The repository is split by responsibility: runtime prompts, public skills, plugin distribution, docs, MCP evidence config, and release tooling stay in separate folders.
+
 <table>
   <tr>
     <td><strong>Path</strong></td>
@@ -598,6 +842,9 @@ Release automation:
 
 ## Documentation
 
+<details open>
+<summary><strong>Primary docs and evidence surfaces</strong></summary>
+
 | Surface | Purpose |
 | --- | --- |
 | [Getting Started](./docs/getting-started.md) | end-to-end local onboarding |
@@ -606,9 +853,12 @@ Release automation:
 | [Skills Publishing](./docs/skills-publishing.md) | source-to-package pipeline |
 | [MCP Setup](./docs/mcp-setup.md) | evidence endpoint policy |
 | [Plugin README](./plugins/meta-architect/README.md) | plugin distribution surface |
-| [Collaborative Whiteboard Mission](./missions/collaborative-whiteboard/mission.md) | concrete scenario walkthrough |
+| [Production Demo Guide](./DEMO.md) | real MA release-hardening walkthrough |
+| [Coverage Matrix](./COVERAGE.md) | current verified capability and package proof map |
 | [Release Spec](./docs/release-spec.md) | release and gate policy |
-| [Release Readiness](./docs/qa/release-readiness-0.1.11.md) | QA evidence for the `v0.1.11` line |
+| [Release Readiness](./docs/qa/release-readiness-0.1.13.md) | QA evidence for the `v0.1.13` line |
+
+</details>
 
 ## Release Hygiene