@jstn-sdk/ma 0.1.11 → 0.1.13

package/scripts/doctor.js

@@ -1,15 +1,51 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import {
+  getDebArtifactName,
+  getPacmanArtifactName,
+  getRpmArtifactName,
+} from "./linux-package-lib.mjs";
+
+const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
 
 const checks = [
   ["package.json", fs.existsSync("package.json")],
   ["skills/index.json", fs.existsSync("skills/index.json")],
   ["dist/meta-architect-skills.tgz", fs.existsSync("dist/meta-architect-skills.tgz")],
+  [
+    `dist/${getDebArtifactName(pkg.version)}`,
+    fs.existsSync(`dist/${getDebArtifactName(pkg.version)}`),
+  ],
+  [
+    `dist/${getPacmanArtifactName(pkg.version)}`,
+    fs.existsSync(`dist/${getPacmanArtifactName(pkg.version)}`),
+  ],
+  [
+    `dist/${getRpmArtifactName(pkg.version)}`,
+    fs.existsSync(`dist/${getRpmArtifactName(pkg.version)}`),
+  ],
   [".codex/hooks.json", fs.existsSync(".codex/hooks.json")],
   [".ma/decisions.json", fs.existsSync(".ma/decisions.json")],
   [".ma/release.json", fs.existsSync(".ma/release.json")],
+  [
+    ".ma/context/helper-orchestration-core.json",
+    fs.existsSync(".ma/context/helper-orchestration-core.json"),
+  ],
+  [
+    ".ma/context/environment-awareness-core.json",
+    fs.existsSync(".ma/context/environment-awareness-core.json"),
+  ],
+  [
+    ".ma/context/universal-plugin-broker-core.json",
+    fs.existsSync(".ma/context/universal-plugin-broker-core.json"),
+  ],
   ["docs/release-spec.md", fs.existsSync("docs/release-spec.md")],
+  ["DEMO.md", fs.existsSync("DEMO.md")],
+  ["COVERAGE.md", fs.existsSync("COVERAGE.md")],
+  ["data/clone-data.proof.json", fs.existsSync("data/clone-data.proof.json")],
+  ["data/clone-data.ledger.json", fs.existsSync("data/clone-data.ledger.json")],
+  ["data/clone-data.rvf", fs.existsSync("data/clone-data.rvf")],
   [".agents/plugins/marketplace.json", fs.existsSync(".agents/plugins/marketplace.json")],
   ["plugins/meta-architect/.app.json", fs.existsSync("plugins/meta-architect/.app.json")],
   [
@@ -17,10 +53,6 @@ const checks = [
     fs.existsSync("plugins/meta-architect/.codex-plugin/plugin.json"),
   ],
   ["plugins/meta-architect/.mcp.json", fs.existsSync("plugins/meta-architect/.mcp.json")],
-  [
-    "missions/collaborative-whiteboard/mission.md",
-    fs.existsSync("missions/collaborative-whiteboard/mission.md"),
-  ],
   ["prompts/architect.md", fs.existsSync("prompts/architect.md")],
 ];
 

package/scripts/install.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env sh
+set -eu
+
+MA_PACKAGE="${MA_PACKAGE:-@jstn-sdk/ma@latest}"
+CODEX_PACKAGE="${CODEX_PACKAGE:-@openai/codex@latest}"
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "meta-architect install: missing required command: $1" >&2
+    exit 1
+  }
+}
+
+need_cmd npm
+need_cmd node
+
+echo "meta-architect install: installing Codex + Meta-Architect"
+npm i -g "$CODEX_PACKAGE" "$MA_PACKAGE"
+
+if command -v ma >/dev/null 2>&1; then
+  echo "meta-architect install: seeding local MA runtime"
+  ma setup >/dev/null
+  echo "meta-architect install: ready"
+  echo "start: ma --madmax --high"
+else
+  echo "meta-architect install: ma command not found after npm install" >&2
+  exit 1
+fi

package/scripts/linux-package-lib.mjs

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+export const LINUX_PACKAGE_NAME = "meta-architect";
+export const LINUX_PACKAGE_REVISION = "1";
+
+export function getPackArtifactName(packageName, version) {
+  return `${packageName.replace(/^@/, "").replace("/", "-")}-${version}.tgz`;
+}
+
+export function getPackArtifactPath(distRoot, packageName, version) {
+  return path.join(distRoot, getPackArtifactName(packageName, version));
+}
+
+export function getDebArtifactName(version) {
+  return `${LINUX_PACKAGE_NAME}_${version}_all.deb`;
+}
+
+export function getDebArtifactPath(distRoot, version) {
+  return path.join(distRoot, getDebArtifactName(version));
+}
+
+export function getPacmanArtifactName(version) {
+  return `${LINUX_PACKAGE_NAME}-${version}-${LINUX_PACKAGE_REVISION}-any.pkg.tar.xz`;
+}
+
+export function getPacmanArtifactPath(distRoot, version) {
+  return path.join(distRoot, getPacmanArtifactName(version));
+}
+
+export function getRpmArtifactName(version) {
+  return `${LINUX_PACKAGE_NAME}-${version}-${LINUX_PACKAGE_REVISION}.noarch.rpm`;
+}
+
+export function getRpmArtifactPath(distRoot, version) {
+  return path.join(distRoot, getRpmArtifactName(version));
+}
+
+export function getLinuxPackageManifestPath(distRoot) {
+  return path.join(distRoot, "linux-package-manifest.json");
+}

package/scripts/linux-package-smoke.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import {
+  getDebArtifactPath,
+  getPacmanArtifactPath,
+  getRpmArtifactPath,
+  LINUX_PACKAGE_NAME,
+} from "./linux-package-lib.mjs";
+
+const repoRoot = process.cwd();
+const pkg = JSON.parse(await fs.readFile(path.join(repoRoot, "package.json"), "utf8"));
+const version = pkg.version;
+const distRoot = path.join(repoRoot, "dist");
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: "pipe",
+    ...options,
+  });
+}
+
+function runBinary(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: null,
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: "pipe",
+    ...options,
+  });
+}
+
+async function smokeExtractedRoot(extractRoot, label) {
+  const workRoot = path.join(extractRoot, `${label}-project`);
+  const codexHome = path.join(extractRoot, `${label}-codex-home`);
+  await fs.mkdir(workRoot, { recursive: true });
+  await fs.mkdir(codexHome, { recursive: true });
+  const maBin = path.join(extractRoot, "usr", "bin", "ma");
+  const env = {
+    ...process.env,
+    CODEX_HOME: codexHome,
+    MA_DISABLE_LIVE_MCP: "1",
+    META_ARCHITECT_PREFIX: extractRoot,
+  };
+  const setupResult = run(maBin, ["setup"], { cwd: workRoot, env });
+  assert.equal(setupResult.status, 0, setupResult.stderr || setupResult.stdout);
+  await fs.access(path.join(workRoot, ".ma", "release.json"));
+  await fs.access(path.join(workRoot, ".ma", "decisions.json"));
+  await fs.access(path.join(extractRoot, "usr", "bin", "meta-architect"));
+  const statusResult = run(maBin, ["status"], { cwd: workRoot, env });
+  assert.equal(statusResult.status, 0, statusResult.stderr || statusResult.stdout);
+}
+
+async function main() {
+  if (process.platform !== "linux") {
+    throw new Error("Native Linux package smoke validation is supported only on Linux hosts");
+  }
+
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "meta-architect-linux-smoke-"));
+  const debExtractRoot = path.join(tempRoot, "deb");
+  const pacmanExtractRoot = path.join(tempRoot, "pacman");
+  const rpmExtractRoot = path.join(tempRoot, "rpm");
+  await fs.mkdir(debExtractRoot, { recursive: true });
+  await fs.mkdir(pacmanExtractRoot, { recursive: true });
+  await fs.mkdir(rpmExtractRoot, { recursive: true });
+
+  const debArtifactPath = getDebArtifactPath(distRoot, version);
+  const pacmanArtifactPath = getPacmanArtifactPath(distRoot, version);
+  const rpmArtifactPath = getRpmArtifactPath(distRoot, version);
+  const extractDeb = run("dpkg-deb", ["-x", debArtifactPath, debExtractRoot], { cwd: repoRoot });
+  assert.equal(extractDeb.status, 0, extractDeb.stderr || extractDeb.stdout);
+  const extractPacman = run("tar", ["-xJf", pacmanArtifactPath, "-C", pacmanExtractRoot], {
+    cwd: repoRoot,
+  });
+  assert.equal(extractPacman.status, 0, extractPacman.stderr || extractPacman.stdout);
+  const archiveConversion = runBinary("rpm2archive", [rpmArtifactPath], { cwd: rpmExtractRoot });
+  assert.equal(
+    archiveConversion.status,
+    0,
+    archiveConversion.stderr?.toString("utf8") || archiveConversion.stdout?.toString("utf8"),
+  );
+  const rpmArchivePath = path.join(rpmExtractRoot, `${path.basename(rpmArtifactPath)}.tgz`);
+  await fs.writeFile(rpmArchivePath, archiveConversion.stdout);
+  const extractRpm = run("tar", ["-xzf", rpmArchivePath, "-C", rpmExtractRoot], { cwd: repoRoot });
+  assert.equal(extractRpm.status, 0, extractRpm.stderr || extractRpm.stdout);
+  await fs.access(path.join(pacmanExtractRoot, ".PKGINFO"));
+  await fs.access(path.join(pacmanExtractRoot, "usr", "lib", LINUX_PACKAGE_NAME, "bin", "ma.js"));
+  await fs.access(path.join(rpmExtractRoot, "usr", "lib", LINUX_PACKAGE_NAME, "bin", "ma.js"));
+
+  await smokeExtractedRoot(debExtractRoot, "deb");
+  await smokeExtractedRoot(pacmanExtractRoot, "pacman");
+  await smokeExtractedRoot(rpmExtractRoot, "rpm");
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/ralph/prompt.md

@@ -0,0 +1,35 @@
+# Meta-Architect Ralph Execution Core
+
+You are executing a Meta-Architect story contract, not an independent release authority.
+
+## Required Inputs
+
+1. Read `.ma/plans/prd.json`.
+2. Read `.ma/plans/progress.txt`.
+3. Pick the highest-priority story where `passes` is `false`.
+4. Execute exactly one bounded story per iteration.
+
+## MA Quality Gates
+
+Before marking a story passed, verify:
+
+- `$arch` architecture constraints remain satisfied.
+- `$sage` evidence and source claims remain valid.
+- `$flow` logic/state invariants remain valid.
+- `$vet` security blockers are absent or explicitly owned.
+- `$vibe` DX/UX constraints remain acceptable.
+- `$build` real-workspace checks pass for the changed slice.
+
+## Authority Boundaries
+
+- Do not mutate `.ma/release.json` or `.ma/decisions.json` directly.
+- Return authoritative status through `$maestro`, `$build`, or the owning lane.
+- Treat Obsidian/vault context as `vault_context`, never `build_evidence`.
+- Treat virtual workspace output as context only, never production proof.
+- Treat code-graph rehearsal as a read-only trajectory preview.
+
+## Completion Contract
+
+Update story `passes` only after fresh verification evidence exists.
+Append progress to `.ma/plans/progress.txt`.
+Record reusable learnings in scoped guidance without overwriting the base workspace contract.

package/scripts/release-sync.js

@@ -238,12 +238,6 @@ function syncSupportingCode(oldVersion, nextVersion) {
       replacement: `release-readiness-${nextVersion}.md`,
       label: "skills QA path",
     },
-    {
-      file: path.join("src", "mcp-live-client.js"),
-      search: `version: "${oldVersion}"`,
-      replacement: `version: "${nextVersion}"`,
-      label: "mcp live client version",
-    },
     {
       file: path.join("test", "package-install-smoke.test.js"),
       search: `jstn-sdk-ma-${oldVersion}.tgz`,
@@ -262,6 +256,19 @@ function syncSupportingCode(oldVersion, nextVersion) {
     const content = readText(entry.file);
     writeText(entry.file, replaceRequired(content, entry.search, entry.replacement, entry.label));
   }
+
+  const mcpLiveClientFile = path.join("src", "mcp-live-client.js");
+  const mcpLiveClient = readText(mcpLiveClientFile);
+  if (!/version: "[0-9]+\.[0-9]+\.[0-9]+(?:-dev)?"/.test(mcpLiveClient)) {
+    throw new Error("Expected to find mcp live client version declaration");
+  }
+  writeText(
+    mcpLiveClientFile,
+    mcpLiveClient.replace(
+      /version: "[0-9]+\.[0-9]+\.[0-9]+(?:-dev)?"/,
+      `version: "${nextVersion}-dev"`,
+    ),
+  );
 }
 
 function rewriteReleaseState(nextVersion, previousVersion) {

package/scripts/release-verify.js

@@ -3,9 +3,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
+import { validateReleaseIssueGates } from "../src/release-issue-gates.js";
 
 const CANONICAL_PACKAGE = "@jstn-sdk/ma";
 const CANONICAL_INSTALL = "npm i -g @openai/codex@latest @jstn-sdk/ma@latest";
+const CDN_INSTALL =
+  "curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh";
 const CANONICAL_LAUNCH = "ma --madmax --high";
 const UNINSTALL_MA = "npm uninstall -g @jstn-sdk/ma";
 const UNINSTALL_BOTH = "npm uninstall -g @jstn-sdk/ma @openai/codex";
@@ -40,10 +43,12 @@ function parseVersion(version) {
 
 function verifyInstallBlock(file) {
   const content = readText(file);
-  if (!content.includes(CANONICAL_INSTALL)) {
+  if (!content.includes(CANONICAL_INSTALL) && !content.includes(CDN_INSTALL)) {
     return;
   }
 
+  assert(content.includes(CDN_INSTALL), `${file}: missing jsDelivr POSIX installer command`);
+  assert(content.includes(CANONICAL_INSTALL), `${file}: missing canonical npm install command`);
   assert(content.includes(CANONICAL_LAUNCH), `${file}: missing canonical launch command`);
   assert(content.includes(UNINSTALL_MA), `${file}: missing uninstall Meta-Architect command`);
   assert(
@@ -52,6 +57,146 @@ function verifyInstallBlock(file) {
   );
 }
 
+function verifyNpmIgnore() {
+  assert(fs.existsSync(".npmignore"), ".npmignore: missing production package ignore file");
+  const content = readText(".npmignore");
+  for (const requiredPattern of [
+    ".ma/",
+    ".omx/",
+    "node_modules/",
+    ".npm-cache/",
+    "dist/",
+    "test/",
+    ".github/",
+    "*.tgz",
+  ]) {
+    assert(
+      content.includes(requiredPattern),
+      `.npmignore: missing required production ignore pattern ${requiredPattern}`,
+    );
+  }
+}
+
+function verifyDemoDoc({ version, gitTag }) {
+  assert(fs.existsSync("DEMO.md"), "DEMO.md: missing demo guide");
+  const content = readText("DEMO.md");
+  assert(content.includes(`Release line: \`${gitTag}\``), "DEMO.md: wrong release line");
+  assert(content.includes("Package: `@jstn-sdk/ma`"), "DEMO.md: missing package name");
+  assert(content.includes(CDN_INSTALL), "DEMO.md: missing jsDelivr installer");
+  assert(content.includes(CANONICAL_INSTALL), "DEMO.md: missing canonical npm install");
+  assert(content.includes(CANONICAL_LAUNCH), "DEMO.md: missing canonical launch");
+  assert(content.includes(UNINSTALL_MA), "DEMO.md: missing MA uninstall command");
+  assert(content.includes(UNINSTALL_BOTH), "DEMO.md: missing MA + Codex uninstall command");
+  assert(content.includes("npm run release:check"), "DEMO.md: missing full release demo command");
+  assert(
+    content.includes("Learning Loop Core") || content.includes("learning loop"),
+    "DEMO.md: missing learning loop coverage",
+  );
+  assert(content.includes("Obsidian"), "DEMO.md: missing Obsidian coverage");
+  assert(content.includes("Ralph"), "DEMO.md: missing Ralph execution coverage");
+  assert(content.includes("data/clone-data.proof.json"), "DEMO.md: missing clone-data proof");
+  assert(content.includes("COVERAGE.md"), "DEMO.md: missing coverage artifact");
+  assert(content.includes(`version line is \`${version}\``), "DEMO.md: missing current version");
+}
+
+function verifyCoverageDoc({ version, gitTag }) {
+  assert(fs.existsSync("COVERAGE.md"), "COVERAGE.md: missing coverage matrix");
+  const content = readText("COVERAGE.md");
+  assert(content.includes(`Target release: \`${gitTag}\``), "COVERAGE.md: wrong target release");
+  assert(
+    content.includes(`Package: \`@jstn-sdk/ma@${version}\``),
+    "COVERAGE.md: wrong package version",
+  );
+  assert(content.includes("Learning Loop Core"), "COVERAGE.md: missing learning-loop coverage");
+  assert(
+    content.includes("Helper Orchestration Core"),
+    "COVERAGE.md: missing helper orchestration coverage",
+  );
+  assert(
+    content.includes("Environment Awareness Core"),
+    "COVERAGE.md: missing environment awareness coverage",
+  );
+  assert(
+    content.includes("Universal Plugin Broker Core"),
+    "COVERAGE.md: missing universal plugin broker coverage",
+  );
+  assert(content.includes("Obsidian Integration Core"), "COVERAGE.md: missing Obsidian coverage");
+  assert(content.includes("Ralph Execution Core"), "COVERAGE.md: missing Ralph coverage");
+  assert(content.includes("36/36 passing"), "COVERAGE.md: missing current test count");
+  assert(
+    content.includes("This repository is not a toy demo."),
+    "COVERAGE.md: missing truth statement",
+  );
+  assert(!content.includes("@jstn-sdk/ma@0.1.0"), "COVERAGE.md: stale npm package version");
+  assert(!content.includes("v0.1.0 release bar"), "COVERAGE.md: stale release bar");
+}
+
+function verifyCanonicalSemanticSurfaces({ version, gitTag }) {
+  const usageWorkflow = readText(path.join("example", "usage-workflow.md"));
+  assert(
+    usageWorkflow.includes(`$maestro I want to harden Meta-Architect ${gitTag}`),
+    "example/usage-workflow.md: missing current $maestro release-hardening scenario",
+  );
+  for (const requiredTerm of ["Obsidian", "Ralph", "Caveman", "learning-loop"]) {
+    assert(
+      usageWorkflow.includes(requiredTerm),
+      `example/usage-workflow.md: missing ${requiredTerm} semantic-core term`,
+    );
+  }
+  for (const staleTerm of [
+    "Build a demo",
+    "demo app",
+    "collaborative whiteboard",
+    "smart contract security review",
+    "Timeline: 4 weeks",
+    "Delivery plan for v0.1.0",
+    "@jstn-sdk/ma@0.1.0",
+  ]) {
+    assert(
+      !usageWorkflow.includes(staleTerm),
+      `example/usage-workflow.md: stale current-facing term ${staleTerm}`,
+    );
+  }
+
+  const mission = readText(path.join("missions", "collaborative-whiteboard", "mission.md"));
+  assert(
+    mission.includes("# Mission: Semantic Release Hardening"),
+    "missions/collaborative-whiteboard/mission.md: stale mission title",
+  );
+  assert(
+    mission.includes("Obsidian is core vault-context infrastructure"),
+    "missions/collaborative-whiteboard/mission.md: missing Obsidian core mission contract",
+  );
+  assert(
+    mission.includes("Ralph is the execution loop"),
+    "missions/collaborative-whiteboard/mission.md: missing Ralph core mission contract",
+  );
+  assert(
+    !mission.toLowerCase().includes("real-time collaborative whiteboard"),
+    "missions/collaborative-whiteboard/mission.md: stale whiteboard mission text",
+  );
+
+  const currentQa = readText(path.join("docs", "qa", `release-readiness-${version}.md`));
+  assert(
+    currentQa.includes("Harden Meta-Architect v0.1.13 semantic core"),
+    `docs/qa/release-readiness-${version}.md: missing realistic semantic smoke idea`,
+  );
+  assert(
+    !currentQa.includes('ma idea "Build a demo app"'),
+    `docs/qa/release-readiness-${version}.md: stale demo-app helper path`,
+  );
+
+  const archPrompt = readText(path.join("prompts", "architect.md"));
+  assert(
+    !archPrompt.includes("v0.1.0` skills library"),
+    "prompts/architect.md: stale v0.1.0 skills-library wording",
+  );
+  assert(
+    archPrompt.includes("current Meta-Architect skills library"),
+    "prompts/architect.md: missing current library wording",
+  );
+}
+
 function main() {
   const pkg = readJson("package.json");
   const lock = readJson("package-lock.json");
@@ -68,6 +213,13 @@ function main() {
     pkg.publishConfig?.access === "public",
     "package.json: publishConfig.access must be public",
   );
+  assert(pkg.files?.includes("DEMO.md"), "package.json: files must include DEMO.md");
+  assert(pkg.files?.includes("COVERAGE.md"), "package.json: files must include COVERAGE.md");
+
+  verifyNpmIgnore();
+  verifyDemoDoc({ version, gitTag });
+  verifyCoverageDoc({ version, gitTag });
+  verifyCanonicalSemanticSurfaces({ version, gitTag });
 
   const changelog = readText("CHANGELOG.md");
   assert(changelog.includes(`## ${gitTag}`), "CHANGELOG.md: missing current version heading");
@@ -95,6 +247,17 @@ function main() {
   const qa = readText(qaPath);
   assert(qa.includes(`# Release Readiness ${version}`), `${qaPath}: wrong title version`);
 
+  const issueGatesPath = path.join("docs", "qa", `release-issue-gates-${version}.json`);
+  assert(fs.existsSync(issueGatesPath), `Missing release issue gate file: ${issueGatesPath}`);
+  const issueGates = validateReleaseIssueGates(readJson(issueGatesPath), {
+    version,
+    requirePassed: true,
+  });
+  assert(
+    issueGates.valid,
+    `${issueGatesPath}: release issue gates are not production-passed\n- ${issueGates.errors.join("\n- ")}`,
+  );
+
   const pluginApp = readJson(path.join("plugins", "meta-architect", ".app.json"));
   const pluginMcp = readJson(path.join("plugins", "meta-architect", ".mcp.json"));
   const pluginManifest = readJson(
@@ -109,6 +272,8 @@ function main() {
 
   for (const file of [
     "README.md",
+    "DEMO.md",
+    "COVERAGE.md",
     path.join("docs", "getting-started.md"),
     path.join("docs", "onboarding.md"),
     path.join("docs", "skills.md"),

package/skills/align/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: align
+description: "Use when the user needs scope alignment, shared language, or docs clarity before or between gated lanes."
+---
+
+# Align
+
+Use this skill inside Codex when the problem is ambiguity, drift, or mismatched language rather than missing implementation. `align` is a non-gating helper skill.
+
+## Output
+
+Produce:
+- current ambiguity or mismatch
+- normalized terminology
+- scope boundary and exclusions
+- acceptance checks or rewritten prompts
+- exact next trigger, usually `$maestro` or the lane that owns the next decision
+
+## Rules
+
+- Align language and scope without creating a new release gate.
+- Prefer tightening existing artifacts over inventing parallel docs.
+- Keep terminology Meta-Architect-native for user-facing surfaces.
+- Use `references/shared-language.md` for naming, taxonomy, and docs-clarity patterns.

package/skills/align/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "$align"
+  short_description: "Scope alignment and shared language helper"
+  default_prompt: "Use $align to resolve scope drift, normalize terminology, and tighten prompts or docs before handing work back to the owning gated lane."

package/skills/align/references/shared-language.md

@@ -0,0 +1,24 @@
+# Shared Language
+
+Use this reference pack with `align` when terminology, scope, or docs are drifting.
+
+## Naming rules
+
+- `$maestro` is the only umbrella surface.
+- `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` remains the fixed gated sequence.
+- `align`, `diagnose`, `tdd`, and `cleanup` are helper skills only.
+- User-facing guidance stays Meta-Architect-native; external source names may appear as evidence, not as product surfaces.
+
+## Alignment checklist
+
+- Name the current artifact, lane, and decision owner.
+- Replace vague nouns with one stable term.
+- Separate what is in scope, out of scope, and not yet decided.
+- Rewrite prompts or docs so the next trigger is obvious.
+
+## Docs-clarity patterns
+
+- Put the next trigger in one line.
+- Distinguish terminal helper commands from in-session skills.
+- Distinguish gated lanes from helper skills.
+- Prefer concise, high-signal wording over long catalogs or branding-heavy lists.

package/skills/arch/SKILL.md

@@ -11,9 +11,11 @@ Use this skill inside Codex to turn a product idea into a concrete architecture
 
 Produce:
 - problem framing
+- `decision`, `status`, `evidence`, `blockers`, `next_allowed_triggers`
 - user and workload assumptions
 - system architecture and subsystem boundaries
 - stack recommendation with tradeoffs
+- rejected alternatives with rationale
 - data model and storage choices
 - auth, security, and operational concerns
 - phased delivery plan

package/skills/build/SKILL.md

@@ -14,11 +14,14 @@ Produce:
 - blockers that still prevent implementation
 - the narrowest viable build slice
 - branch or worktree suggestions when relevant
+- bounded execution state when the build lane is already in progress
 - test and verification expectations
+- repair path when the bounded slice needs another pass
 - the exact next implementation step
 
 ## Rules
 
 - Do not claim readiness if architecture, evidence, logic, security, or DX/UX gaps remain unresolved.
 - Keep the recommended build slice small, testable, and reversible.
+- Treat `$build` as the sole owner of `.ma/plans/build.md` and `build_status`.
 - If the user wants code immediately and the path is clear, end with a concrete implementation plan rather than more review prose.

package/skills/cleanup/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: cleanup
+description: "Use when the user wants contract-preserving simplification, anti-slop cleanup, or a final-pass polish after the main decision is made."
+---
+
+# Cleanup
+
+Use this skill inside Codex when the core behavior is understood but the artifact still needs simplification, deslop work, or clearer prose. `cleanup` is a non-gating helper skill.
+
+## Output
+
+Produce:
+- removable complexity or noisy wording
+- behavior-preserving simplifications
+- residual risks after cleanup
+- exact next trigger, usually the owning lane or release verification
+
+## Rules
+
+- Prefer deletion over addition.
+- Preserve behavior and decision ownership while cleaning up.
+- Keep user-facing wording concise and product-native.
+- Use `references/style-and-deslop.md` for simplification and prose cleanup patterns.

package/skills/cleanup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "$cleanup"
+  short_description: "Anti-slop cleanup and final-pass polish"
+  default_prompt: "Use $cleanup to simplify noisy code or docs, remove avoidable slop, and polish wording without changing the owning lane."

package/skills/cleanup/references/style-and-deslop.md

@@ -0,0 +1,18 @@
+# Style And Deslop
+
+Use this reference pack with `cleanup` when an artifact works but still feels bloated, generic, or hard to trust.
+
+## Cleanup priorities
+
+- remove repeated framing
+- cut placeholder language and empty intensifiers
+- collapse duplicate concepts into one stable term
+- prefer shorter, sharper instructions when they preserve meaning
+- delete unused or non-essential surface area before adding more structure
+
+## Safe cleanup checks
+
+- behavior or contract is unchanged
+- the next trigger is still explicit
+- helper-vs-gated distinctions remain intact
+- no upstream brand names are introduced as product surfaces