@jstn-sdk/ma 0.1.10 → 0.1.12

package/README.md

@@ -18,9 +18,9 @@
 </div>
 
 > [!IMPORTANT]
-> Meta-Architect `v0.1.10` is a production-grade skills line.
+> Meta-Architect `v0.1.12` is a production-grade skills line.
 > It is not a lightweight demo branch.
-> From `v0.1.10` 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.12` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
 
 ## Overview
 
@@ -31,6 +31,7 @@ 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]
@@ -43,9 +44,13 @@ It adds:
 - [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 +62,7 @@ It adds:
   </tr>
   <tr>
     <td><strong>Release line</strong></td>
-    <td><code>v0.1.10</code></td>
+    <td><code>v0.1.12</code></td>
   </tr>
   <tr>
     <td><strong>License</strong></td>
@@ -97,11 +102,39 @@ 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
+## Default Install Surfaces
+
+Meta-Architect is a Codex-native session workflow. On Linux, the primary install surface is now distro-style package installation, not a standalone binary shell.
+
+### 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
+```
 
-Meta-Architect is intended to be consumed as an installed package, not primarily as a git clone.
+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.
 
-Primary product path:
+### npm fallback
 
 ```bash
 # Install
@@ -125,8 +158,8 @@ 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.
+> On Linux, distro-native package install is the default surface.
+> npm remains available as a fallback path.
 
 ## Repository Branch Strategy
 
@@ -147,7 +180,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 +281,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.10
+8. Delivery plan for v0.1.12
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -238,10 +289,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 +302,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 +356,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 +384,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.
@@ -370,11 +438,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 +452,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
@@ -404,12 +474,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 +508,24 @@ 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
+
+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.
+
 ## Core Maintainers
 
 <table>
@@ -451,7 +541,7 @@ What to use when:
   </tr>
 </table>
 
-## Core Triggers
+## Gated Lanes
 
 | Trigger | Purpose | Main output | Gate effect |
 | --- | --- | --- | --- |
@@ -462,6 +552,15 @@ What to use when:
 | `$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` |
 
+## Helper Skills
+
+| 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 |
+
 ## Gate Model
 
 Meta-Architect is intentionally fail-closed.
@@ -485,10 +584,11 @@ Meta-Architect is intentionally fail-closed.
 
 ## Release and Packaging
 
-Meta-Architect has two related but different distribution surfaces.
+Meta-Architect has three related but different distribution surfaces.
 
 | 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` |
 
@@ -499,6 +599,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 +609,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 +626,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
@@ -608,7 +715,7 @@ Release automation:
 | [Plugin README](./plugins/meta-architect/README.md) | plugin distribution surface |
 | [Collaborative Whiteboard Mission](./missions/collaborative-whiteboard/mission.md) | concrete scenario walkthrough |
 | [Release Spec](./docs/release-spec.md) | release and gate policy |
-| [Release Readiness](./docs/qa/release-readiness-0.1.10.md) | QA evidence for the `v0.1.10` line |
+| [Release Readiness](./docs/qa/release-readiness-0.1.12.md) | QA evidence for the `v0.1.12` line |
 
 ## Release Hygiene
 

package/bin/ma.js

@@ -1,11 +1,6 @@
 #!/usr/bin/env node
 
 import { runBootstrap, runDoctor } from "../src/bootstrap.js";
-import {
-  evaluateBuildGate,
-  formatBuildBlockers,
-  formatNextAllowedTriggers,
-} from "../src/build-gate.js";
 import { appendDecision } from "../src/decision-log.js";
 import { runCodex, shouldDelegateToCodex } from "../src/launcher.js";
 import {
@@ -15,7 +10,8 @@ import {
   validateReleaseOrigin,
 } from "../src/policy.js";
 import { loadReleaseState } from "../src/release-state.js";
-import { writeBuildPlanArtifact } from "../src/runtime-artifacts.js";
+import { evaluateRuntimeBuildReadiness } from "../src/runtime/build-readiness.js";
+import { createRuntimeSummary, loadRuntimeSnapshot } from "../src/runtime/runtime-state.js";
 import {
   ensureSkillsInstalled,
   ensureSupportBundleInstalled,
@@ -24,6 +20,7 @@ import {
 import {
   listSkills,
   runArch,
+  runBuildLane,
   runFlow,
   runIdea,
   runInit,
@@ -50,7 +47,7 @@ function printUsage() {
   console.error("  ma release <origin-branch> <target-branch>");
 }
 
-function printStatus(releaseState) {
+async function printStatus(releaseState) {
   console.log("Meta-Architect Status");
   console.log("=====================");
   console.log(`Idea: ${releaseState.idea_status}`);
@@ -61,9 +58,10 @@ function printStatus(releaseState) {
   console.log(`Experience: ${releaseState.experience_status}`);
   console.log(`Build: ${releaseState.build_status}`);
 
-  const evaluation = evaluateBuildGate(releaseState);
+  const runtimeSummary = createRuntimeSummary(await loadRuntimeSnapshot());
+  const evaluation = evaluateRuntimeBuildReadiness(releaseState, runtimeSummary);
   console.log("Next allowed triggers:");
-  const triggers = formatNextAllowedTriggers(evaluation);
+  const triggers = evaluation.nextTriggers;
   if (triggers.length === 0) {
     console.log("$build");
     return;
@@ -74,71 +72,26 @@ function printStatus(releaseState) {
   }
 }
 
-async function runBuild(releaseState) {
-  const evaluation = evaluateBuildGate(releaseState);
-
-  if (!evaluation.allowed) {
-    const blockers = formatBuildBlockers(evaluation);
-    await writeBuildPlanArtifact({
-      allowed: false,
-      blockers,
-      nextTriggers: formatNextAllowedTriggers(evaluation),
-    });
-    await appendDecision({
-      decision: "Blocked build execution",
-      status: "BLOCKED",
-      evidence: [
-        {
-          kind: "release-state",
-          path: ".ma/release.json",
-        },
-      ],
-      blockers,
-      next_allowed_triggers: formatNextAllowedTriggers(evaluation),
-    });
-
+async function runBuild() {
+  const result = await runBuildLane();
+  if (result.status !== "READY") {
     console.error("Build is locked.");
-    for (const blocker of blockers) {
+    for (const blocker of result.blockers) {
       console.error(`- ${blocker}`);
     }
     process.exitCode = 1;
     return;
   }
 
-  const suggestedBranches = ["feature/ui", "feature/api"];
-  await writeBuildPlanArtifact({
-    allowed: true,
-    blockers: [],
-    nextTriggers: ["$build"],
-    suggestedBranches,
-  });
-  await appendDecision({
-    kind: "skill",
-    skill: "$build",
-    decision: "Build gate ready",
-    status: "READY",
-    evidence: [
-      {
-        kind: "release-state",
-        path: ".ma/release.json",
-      },
-      {
-        branches: ["feature/ui", "feature/api"],
-      },
-    ],
-    blockers: [],
-    next_allowed_triggers: ["$build"],
-  });
-
-  await syncStatusUpdates({ build_status: "READY" });
-
+  const suggestedBranches = result.suggestedBranches ?? [];
   console.log("Build gate is green.");
   console.log("Suggested branches:");
-  console.log(`- ${suggestedBranches[0]}`);
-  console.log(`- ${suggestedBranches[1]}`);
+  for (const branch of suggestedBranches) {
+    console.log(`- ${branch}`);
+  }
   console.log("Optional worktree commands:");
-  console.log("git worktree add ../ui feature/ui");
-  console.log("git worktree add ../api feature/api");
+  console.log("git worktree add ../implementation feature/implementation");
+  console.log("git worktree add ../verification feature/verification");
 }
 
 async function runMerge(sourceBranch, targetBranch) {
@@ -266,7 +219,7 @@ async function main() {
 
   if (command === "status") {
     const releaseState = await loadReleaseState();
-    printStatus(releaseState);
+    await printStatus(releaseState);
     return;
   }
 
@@ -288,9 +241,12 @@ async function main() {
     return;
   }
 
+  if (command === "run" && arg === "$meta-architect") {
+    throw new Error("$meta-architect has been removed as a separate surface; use $maestro");
+  }
+
   if (command === "run" && arg === "$build") {
-    const releaseState = await loadReleaseState();
-    await runBuild(releaseState);
+    await runBuild();
     return;
   }
 

package/docs/README.md

@@ -7,17 +7,20 @@ Meta-Architect documentation is organized by operator task.
 - [Getting Started](./getting-started.md)
 - [Release Spec](./release-spec.md)
 - [Skills Reference](./skills.md)
+- umbrella, gated lanes, and helper skill distinctions live in the Skills Reference
 - [Installed Support Bundle](./installed-sdk.md)
 
 ## Packaging and installation
 
 - [Skills Publishing](./skills-publishing.md)
+- published helper-skill and plugin-mirror expectations live in Skills Publishing
+- Linux-native distro package expectations live in the Release Spec and release-readiness docs
 - [MCP Setup](./mcp-setup.md)
 - [Plugin Bundle](../plugins/meta-architect/README.md)
 
 ## QA and readiness
 
-- [Release Readiness 0.1.10](./qa/release-readiness-0.1.10.md)
+- [Release Readiness 0.1.12](./qa/release-readiness-0.1.12.md)
 
 ## Repo structure references