@jstn-sdk/ma 0.1.11 → 0.1.13

package/plugins/meta-architect/skills/maestro/references/native-ingest-map.md

@@ -0,0 +1,44 @@
+# Native Ingest Map
+
+Meta-Architect absorbs new pattern families as native product guidance without turning them into new umbrella brands or new release gates.
+
+## Publishable helper skills
+
+- `align`
+  - purpose: scope alignment, shared language, and docs clarity
+  - gate effect: none
+- `diagnose`
+  - purpose: failure decomposition, blocked-lane triage, and root-cause framing
+  - gate effect: none
+- `tdd`
+  - purpose: regression-first and test-first execution scaffolds
+  - gate effect: none
+- `cleanup`
+  - purpose: anti-slop cleanup, prose humanization, and final-pass polish
+  - gate effect: none
+
+## Existing-lane absorption
+
+- `$sage`
+  - owns source selection, upstream validation order, and evidence quality
+  - uses curated native reference packs instead of raw catalog browsing as the product surface
+- `$vet`
+  - owns security/trust-boundary review and security playbook application
+  - absorbs security playbook patterns without creating a second security umbrella
+- `$maestro`
+  - remains the only umbrella surface and bounded autonomous manager
+  - owns next-step recommendation, helper handoff decisions, and fixed-sequence management
+  - does not create new gate states and does not replace the outputs owned by gated lanes
+
+## Fixed gated sequence
+
+The release-owned sequence does not change in this ingest:
+
+1. `$arch`
+2. `$sage`
+3. `$flow`
+4. `$vet`
+5. `$vibe`
+6. `$build`
+
+Helper skills remain publishable but non-gating. They can prepare, unblock, or clean up work around those lanes, but they do not create new gate states and they do not own release-state transitions.

package/plugins/meta-architect/skills/sage/SKILL.md

@@ -5,14 +5,16 @@ description: "Use when the user wants evidence-backed technology choices, OSS ev
 
 # Sage
 
-Use this skill inside Codex to verify or challenge stack choices with real sources.
+Use this skill inside Codex to verify or challenge stack choices with real sources. `$sage` remains the evidence gate even as Meta-Architect absorbs more native curation and reference packs.
 
 ## Output
 
 Produce:
 - candidate tools, libraries, or services
+- `decision`, `status`, `evidence`, `blockers`, `next_allowed_triggers`
 - why each option fits or fails the architecture
 - source-backed evidence from official docs, upstream repos, or approved GitMCP sources
+- evidence grade and exact upstream mapping
 - recommendation with tradeoffs
 - unresolved gaps or missing evidence
 - exact next trigger, usually `$flow`
@@ -24,6 +26,7 @@ Produce:
   - use discovery accelerators to find or narrow candidates
   - map the selected candidate back to an exact upstream repo
   - verify against upstream repos and official docs before approving it
+- Use `references/source-selection.md` when you need the native source-selection contract, evidence ladder, or packaged discovery rules.
 - Use approved discovery accelerators when you need faster OSS candidate discovery:
   - Ossium (`https://ossium.live/home`) for trending, curated, YC-backed, and GSoC-linked OSS discovery
   - Trendshift (`https://trendshift.io/`) for rising GitHub engagement and topic momentum
@@ -31,6 +34,7 @@ Produce:
   - Libraries.io (`https://libraries.io/`) for package/dependency metadata, with caution because its public data is scraped and not validated/curated for accuracy
   - Open Hub (`https://openhub.net/`) for project activity, contributor, and comparison signals
   - Open-source Projects (`https://www.opensourceprojects.dev/`) for curated OSS discovery and detailed project writeups
+- Discovery accelerators are candidate-finding tools, not approval surfaces. The user-facing Meta-Architect product stays native even when evidence sources are external.
 - Do not invent package capabilities or maturity claims.
 - Prefer primary sources over summaries when validating technical details.
 - Do not treat discovery listings alone as VERIFIED evidence; promote candidates to upstream repos and official docs before approving them.

package/plugins/meta-architect/skills/sage/references/source-selection.md

@@ -0,0 +1,36 @@
+# Source Selection
+
+Use this reference pack inside `$sage` when the repo needs evidence-backed selection without turning raw catalogs into the product surface.
+
+## Evidence order
+
+1. Known upstream repo and official docs
+2. Discovery accelerator to find or narrow candidates
+3. Exact upstream repo mapping for the shortlisted candidate
+4. Upstream repo plus official-doc verification before approval
+
+## Discovery accelerator rules
+
+- Use accelerators to reduce search time, not to replace validation.
+- Treat listings, rankings, and trend signals as hints.
+- Promote any serious candidate to an exact upstream repo before calling it VERIFIED.
+- Keep user-facing guidance in Meta-Architect language rather than echoing catalog branding as if it were a first-class product surface.
+
+## Minimum approval bar
+
+- Exact upstream repo identified
+- Official docs available when relevant
+- Claimed capability verified from a primary source
+- Maturity caveats called out when evidence is weak
+
+## Evidence grades
+
+- `VERIFIED`: exact upstream mapping plus primary-source confirmation
+- `PARTIAL`: candidate is mapped, but live proof or maturity proof is incomplete
+- `MISSING`: no trustworthy exact upstream mapping yet
+
+Always expose the evidence grade and the exact upstream mapping in user-facing `$sage` output.
+
+## Native posture
+
+Meta-Architect ships curated guidance and playbooks. It does not ship a raw mirror of external catalogs. External sources remain evidence inputs, not user-facing skill identities.

package/plugins/meta-architect/skills/tdd/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: tdd
+description: "Use when the user wants regression-first or test-first scaffolding before implementation work expands."
+---
+
+# TDD
+
+Use this skill inside Codex when implementation should start by locking behavior with tests. `tdd` is a non-gating helper skill that supports execution once the relevant lane is ready.
+
+## Output
+
+Produce:
+- behavior to lock
+- minimal regression or failing test shape
+- implementation boundary
+- proof that the test belongs to the requested change
+- exact next trigger, usually the implementation lane or `$cleanup`
+
+## Rules
+
+- Prefer the smallest failing test that proves the requested behavior.
+- Lock current behavior before cleanup or refactor work when behavior is not already protected.
+- Do not treat `tdd` as a replacement for the build gate.
+- Keep test intent explicit so the next implementation step stays narrow.

package/plugins/meta-architect/skills/tdd/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "$tdd"
+  short_description: "Regression-first and test-first helper"
+  default_prompt: "Use $tdd to define the smallest test that locks the requested behavior before implementation expands."

package/plugins/meta-architect/skills/vet/SKILL.md

@@ -5,21 +5,25 @@ description: "Use when the user wants a security and trust-boundary review of th
 
 # Vet
 
-Use this skill inside Codex to review security posture before the build lane.
+Use this skill inside Codex to review security posture before the build lane. `$vet` remains the sole security gate even as Meta-Architect ships deeper native security playbooks.
 
 ## Output
 
 Produce:
+- `decision`, `status`, `evidence`, `blockers`, `next_allowed_triggers`
 - trust boundaries
 - authn/authz expectations
 - sensitive data paths
 - abuse cases and likely failure modes
 - concrete mitigations
+- accepted risks
 - release blockers vs acceptable risks
 - exact next trigger, usually `$vibe`
 
 ## Rules
 
 - Prioritize material risks over exhaustive but low-value checklists.
+- Use `references/security-playbooks.md` when you need the native security playbook set for common trust-boundary reviews.
+- Keep security guidance product-owned and lane-aware. Do not introduce a second umbrella or a separate security release gate.
 - Call out missing assumptions that affect security posture.
 - Distinguish between must-fix blockers and documented accepted risk.

package/plugins/meta-architect/skills/vet/references/security-playbooks.md

@@ -0,0 +1,30 @@
+# Security Playbooks
+
+Use this reference pack inside `$vet` for repeatable trust-boundary reviews that stay native to Meta-Architect.
+
+## Core review slices
+
+- identity and session boundaries
+- authorization and tenancy boundaries
+- secret handling and key rotation assumptions
+- dependency and supply-chain trust
+- inbound data validation and outbound data exposure
+- operational abuse cases and failure modes
+
+## How to use the playbooks
+
+- Start with the architecture and evidence already approved by `$arch` and `$sage`.
+- Focus on the highest-risk boundary first.
+- Distinguish blockers from accepted risk.
+- Route remediation back to the owning lane rather than creating a parallel security workflow.
+
+## Adversarial hardening
+
+- For higher-risk changes, run a bounded adversarial hardening pass before final approval.
+- Keep the hardening work inside the private scratchpad/runtime layer.
+- Return structured findings, not direct gate mutations.
+- If the hardening pass cannot resolve or clearly classify the risk, keep `$vet` in a non-terminal state instead of over-approving.
+
+## Product boundary
+
+This pack deepens `$vet`; it does not create a new security skill family. Security patterns are packaged as Meta-Architect guidance, not as mirrored external catalogs or branded upstream surfaces.

package/plugins/meta-architect/skills/vibe/SKILL.md

@@ -10,8 +10,10 @@ Use this skill inside Codex to review whether the system will feel coherent for
 ## Output
 
 Produce:
+- `decision`, `status`, `evidence`, `blockers`, `next_allowed_triggers`
 - developer workflow risks
 - user workflow risks
+- operator friction and user friction
 - complexity hotspots
 - onboarding or operability friction
 - simplifications that improve clarity

package/scripts/active-autonomy-hook.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  createDefaultActiveAutonomyCore,
+  detectPassivePermissionHandoff,
+} from "../src/runtime/active-autonomy-core.js";
+
+const DEFAULT_RESPONSE =
+  "AUTO-CONTINUE: continue the current safe branch, execute the next reversible step, then verify before reporting.";
+
+async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    return {
+      type: "invalid-hook-payload",
+      raw,
+      parseError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function extractAssistantText(payload) {
+  const candidates = [
+    payload.last_assistant_message,
+    payload["last-assistant-message"],
+    payload.message,
+    payload.text,
+    payload.output,
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate;
+    }
+  }
+
+  if (Array.isArray(payload.messages)) {
+    const assistant = [...payload.messages]
+      .reverse()
+      .find((message) => message?.role === "assistant" && typeof message.content === "string");
+    return assistant?.content ?? "";
+  }
+
+  return "";
+}
+
+async function appendAudit(cwd, entry) {
+  const auditDir = path.join(cwd, ".ma", "hooks");
+  await fs.mkdir(auditDir, { recursive: true });
+  await fs.appendFile(
+    path.join(auditDir, "audit.log"),
+    `${JSON.stringify({ timestamp: new Date().toISOString(), ...entry })}\n`,
+    "utf8",
+  );
+}
+
+const payload = await readStdinJson();
+const cwd = payload.cwd || payload.working_directory || process.env.MA_ROOT || process.cwd();
+const assistantText = extractAssistantText(payload);
+const blocked = detectPassivePermissionHandoff(assistantText, createDefaultActiveAutonomyCore());
+
+const result = blocked
+  ? {
+      decision: "block",
+      reason: DEFAULT_RESPONSE,
+      stopReason: "active_autonomy_passive_handoff",
+      systemMessage:
+        "Meta-Architect Active Autonomy blocked passive permission-handoff wording on an AUTO-CONTINUE branch.",
+    }
+  : {
+      decision: "approve",
+      reason: "active_autonomy_no_passive_handoff_detected",
+    };
+
+await appendAudit(cwd, {
+  hook: "active-autonomy",
+  event: payload.type || payload.event || "unknown",
+  decision: result.decision,
+  stopReason: result.stopReason,
+  assistantPreview: assistantText.slice(0, 200),
+});
+
+process.stdout.write(`${JSON.stringify(result)}\n`);

package/scripts/build-linux-packages.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import {
+  getDebArtifactPath,
+  getLinuxPackageManifestPath,
+  getPackArtifactPath,
+  getPacmanArtifactPath,
+  getRpmArtifactPath,
+  LINUX_PACKAGE_NAME,
+  LINUX_PACKAGE_REVISION,
+} from "./linux-package-lib.mjs";
+
+const repoRoot = process.cwd();
+const distRoot = path.join(repoRoot, "dist");
+const packageJson = JSON.parse(await fsp.readFile(path.join(repoRoot, "package.json"), "utf8"));
+const version = packageJson.version;
+const packageName = packageJson.name;
+const maintainer = packageJson.author;
+const homepage = packageJson.homepage;
+const description = packageJson.description;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: "pipe",
+    ...options,
+  });
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+  if (result.status !== 0) {
+    fail(`${command} ${args.join(" ")} failed with status ${result.status ?? 1}`);
+  }
+}
+
+async function copyDir(src, dest) {
+  await fsp.mkdir(dest, { recursive: true });
+  const entries = await fsp.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fsp.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function writeExecutable(filePath, content) {
+  await fsp.writeFile(filePath, content, { mode: 0o755 });
+  await fsp.chmod(filePath, 0o755);
+}
+
+async function getInstalledSizeBytes(root) {
+  let total = 0;
+  const entries = await fsp.readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      total += await getInstalledSizeBytes(entryPath);
+      continue;
+    }
+    const stat = await fsp.stat(entryPath);
+    total += stat.size;
+  }
+  return total;
+}
+
+async function createCommonRoot(root, packArtifactPath) {
+  const libRoot = path.join(root, "usr", "lib", LINUX_PACKAGE_NAME);
+  const binRoot = path.join(root, "usr", "bin");
+  await fsp.mkdir(libRoot, { recursive: true });
+  await fsp.mkdir(binRoot, { recursive: true });
+  run("tar", ["-xzf", packArtifactPath, "-C", libRoot, "--strip-components=1", "package"], {
+    cwd: repoRoot,
+  });
+
+  const wrapper = `#!/bin/sh
+PREFIX="\${META_ARCHITECT_PREFIX:-}"
+NODE_BIN="\${META_ARCHITECT_NODE_BIN:-node}"
+if ! command -v "$NODE_BIN" >/dev/null 2>&1; then
+  echo "meta-architect requires nodejs >= 20 on the host system." >&2
+  exit 127
+fi
+if ! command -v git >/dev/null 2>&1; then
+  echo "meta-architect requires git on the host system." >&2
+  exit 127
+fi
+exec "$NODE_BIN" "\${PREFIX}/usr/lib/${LINUX_PACKAGE_NAME}/bin/ma.js" "$@"
+`;
+  await writeExecutable(path.join(binRoot, "ma"), wrapper);
+  await writeExecutable(path.join(binRoot, "meta-architect"), wrapper);
+}
+
+async function buildDeb(commonRoot, artifactPath) {
+  const debRoot = `${commonRoot}-deb`;
+  await fsp.rm(debRoot, { recursive: true, force: true });
+  await copyDir(commonRoot, debRoot);
+  const controlRoot = path.join(debRoot, "DEBIAN");
+  await fsp.mkdir(controlRoot, { recursive: true });
+  await fsp.writeFile(
+    path.join(controlRoot, "control"),
+    `Package: ${LINUX_PACKAGE_NAME}
+Version: ${version}
+Section: devel
+Priority: optional
+Architecture: all
+Maintainer: ${maintainer}
+Depends: nodejs (>= 20), git
+Description: ${description}
+ Meta-Architect installs the Codex-native Meta-Architect workflow surface
+ without requiring npm package installation first.
+Homepage: ${homepage}
+`,
+  );
+  await fsp.rm(artifactPath, { force: true });
+  run("dpkg-deb", ["--root-owner-group", "--build", debRoot, artifactPath], { cwd: repoRoot });
+}
+
+async function buildPacman(commonRoot, artifactPath) {
+  const pacmanRoot = `${commonRoot}-pacman`;
+  await fsp.rm(pacmanRoot, { recursive: true, force: true });
+  await copyDir(commonRoot, pacmanRoot);
+  const installedSize = await getInstalledSizeBytes(path.join(pacmanRoot, "usr"));
+  const buildDate = Math.floor(Date.now() / 1000);
+  await fsp.writeFile(
+    path.join(pacmanRoot, ".PKGINFO"),
+    `pkgname = ${LINUX_PACKAGE_NAME}
+pkgbase = ${LINUX_PACKAGE_NAME}
+pkgver = ${version}-${LINUX_PACKAGE_REVISION}
+pkgdesc = ${description}
+url = ${homepage}
+builddate = ${buildDate}
+packager = ${maintainer}
+size = ${installedSize}
+arch = any
+license = MIT
+depend = nodejs
+depend = git
+`,
+  );
+  await fsp.writeFile(
+    path.join(pacmanRoot, ".BUILDINFO"),
+    `format = 2
+pkgname = ${LINUX_PACKAGE_NAME}
+pkgbase = ${LINUX_PACKAGE_NAME}
+pkgver = ${version}-${LINUX_PACKAGE_REVISION}
+pkgarch = any
+packager = ${maintainer}
+builddate = ${buildDate}
+`,
+  );
+  await fsp.rm(artifactPath, { force: true });
+  run(
+    "tar",
+    [
+      "--sort=name",
+      "--mtime=@0",
+      "--owner=0",
+      "--group=0",
+      "--numeric-owner",
+      "-cJf",
+      artifactPath,
+      "-C",
+      pacmanRoot,
+      ".PKGINFO",
+      ".BUILDINFO",
+      "usr",
+    ],
+    { cwd: repoRoot },
+  );
+}
+
+async function buildRpm(commonRoot, artifactPath) {
+  const rpmRoot = `${commonRoot}-rpmbuild`;
+  const topDir = path.join(rpmRoot, "topdir");
+  for (const dirName of ["BUILD", "BUILDROOT", "RPMS", "SOURCES", "SPECS", "SRPMS", "TMP", "DB"]) {
+    await fsp.mkdir(path.join(topDir, dirName), { recursive: true });
+  }
+
+  const sourceRootName = `${LINUX_PACKAGE_NAME}-${version}`;
+  const sourceRoot = path.join(rpmRoot, sourceRootName);
+  await fsp.rm(sourceRoot, { recursive: true, force: true });
+  await copyDir(commonRoot, sourceRoot);
+  const sourceTarPath = path.join(topDir, "SOURCES", `${sourceRootName}.tar.gz`);
+  run("tar", ["-czf", sourceTarPath, "-C", rpmRoot, sourceRootName], { cwd: repoRoot });
+
+  const specPath = path.join(topDir, "SPECS", `${LINUX_PACKAGE_NAME}.spec`);
+  await fsp.writeFile(
+    specPath,
+    `Name: ${LINUX_PACKAGE_NAME}
+Version: ${version}
+Release: ${LINUX_PACKAGE_REVISION}%{?dist}
+Summary: ${description}
+License: MIT
+URL: ${homepage}
+BuildArch: noarch
+Requires: nodejs >= 20
+Requires: git
+Source0: %{name}-%{version}.tar.gz
+
+%description
+Meta-Architect installs the Codex-native Meta-Architect workflow surface
+without requiring npm package installation first.
+
+%prep
+%setup -q
+
+%build
+
+%install
+rm -rf %{buildroot}
+mkdir -p %{buildroot}
+cp -a usr %{buildroot}/
+
+%files
+/usr/bin/ma
+/usr/bin/meta-architect
+/usr/lib/${LINUX_PACKAGE_NAME}
+`,
+  );
+
+  await fsp.rm(artifactPath, { force: true });
+  run(
+    "rpmbuild",
+    [
+      "--define",
+      `_topdir ${topDir}`,
+      "--define",
+      `_tmppath ${path.join(topDir, "TMP")}`,
+      "--define",
+      `_dbpath ${path.join(topDir, "DB")}`,
+      "-bb",
+      specPath,
+    ],
+    {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        HOME: rpmRoot,
+        TMPDIR: path.join(topDir, "TMP"),
+        QA_RPATHS: "0x0000",
+      },
+    },
+  );
+  const builtRpmPath = path.join(topDir, "RPMS", "noarch", path.basename(artifactPath));
+  await fsp.copyFile(builtRpmPath, artifactPath);
+}
+
+async function main() {
+  if (process.platform !== "linux") {
+    fail("Native Linux package builds are supported only on Linux hosts");
+  }
+
+  await fsp.mkdir(distRoot, { recursive: true });
+  const packArtifactPath = getPackArtifactPath(distRoot, packageName, version);
+  await fsp.rm(packArtifactPath, { force: true });
+  run(
+    "npm",
+    [
+      "pack",
+      ".",
+      "--ignore-scripts",
+      "--cache",
+      path.join(distRoot, ".npm-cache"),
+      "--pack-destination",
+      distRoot,
+    ],
+    { cwd: repoRoot },
+  );
+
+  const workRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "meta-architect-linux-packages-"));
+  const commonRoot = path.join(workRoot, "root");
+  await createCommonRoot(commonRoot, packArtifactPath);
+
+  const debArtifactPath = getDebArtifactPath(distRoot, version);
+  const pacmanArtifactPath = getPacmanArtifactPath(distRoot, version);
+  const rpmArtifactPath = getRpmArtifactPath(distRoot, version);
+  await buildDeb(commonRoot, debArtifactPath);
+  await buildPacman(commonRoot, pacmanArtifactPath);
+  await buildRpm(commonRoot, rpmArtifactPath);
+
+  await fsp.writeFile(
+    getLinuxPackageManifestPath(distRoot),
+    `${JSON.stringify(
+      {
+        version,
+        packageName,
+        linuxPackageName: LINUX_PACKAGE_NAME,
+        revision: LINUX_PACKAGE_REVISION,
+        artifacts: {
+          deb: path.basename(debArtifactPath),
+          pacman: path.basename(pacmanArtifactPath),
+          rpm: path.basename(rpmArtifactPath),
+        },
+        install: {
+          debian: `sudo apt install ./${path.basename(debArtifactPath)}`,
+          arch: `sudo pacman -U ./${path.basename(pacmanArtifactPath)}`,
+          rpm: `sudo dnf install ./${path.basename(rpmArtifactPath)}`,
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  console.log(debArtifactPath);
+  console.log(pacmanArtifactPath);
+  console.log(rpmArtifactPath);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});