@jstn-sdk/ma 0.1.3 → 0.1.5

package/src/skills.js

@@ -1,54 +1,46 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { appendDecision } from "./decision-log.js";
-import { readJson, writeFileIfMissing, writeJson } from "./fs-utils.js";
+import { readJson, writeJson } from "./fs-utils.js";
 import { validateMcpServers } from "./mcp-config.js";
 import { McpSseClient } from "./mcp-live-client.js";
-import { getRepoRoot, getRuntimeReadPath, getRuntimeWritePath, packageRoot } from "./paths.js";
 import {
-  seedRuntimeArtifacts,
-  writeArchitectureArtifacts,
-  writeEvidenceSpec,
-  writeExperienceSpec,
-  writeLogicSpec,
-  writeProjectContext,
-  writeSecuritySpec,
-} from "./runtime-artifacts.js";
+  getAuditsPath,
+  getCvesPath,
+  getOutcomesPath,
+  getRepoRoot,
+  getSourcesPath,
+} from "./paths.js";
+import { loadReleaseState, saveReleaseState } from "./release-state.js";
+import { runSetupScaffold } from "./setup.js";
 import { syncStatusUpdates } from "./state-sync.js";
 
 const skillNames = ["$arch", "$sage", "$flow", "$vet", "$vibe", "$build"];
-const workflowTemplates = {
-  "arch.skill.md":
-    "# `$arch`\n\nProduces blueprint architecture, stack rationale, subsystem design, and tradeoffs.\n",
-  "sage.skill.md":
-    "# `$sage`\n\nMaps architectural choices to approved OSS candidates from GitMCP-backed collections.\n",
-  "vet.skill.md": "# `$vet`\n\nAudits security posture, CVE signals, and safer alternatives.\n",
-  "flow.skill.md": "# `$flow`\n\nValidates logic, state transitions, and unresolved blockers.\n",
-  "vibe.skill.md":
-    "# `$vibe`\n\nReviews developer and user experience risks before build execution.\n",
-  "build.skill.md": "# `$build`\n\nChecks gates and plans bounded build execution.\n",
-  "sync.skill.md":
-    "# `$sync`\n\nReserved for refreshing mapped MCP sources and availability records.\n",
-};
 
 export function listSkills() {
   return skillNames;
 }
 
 async function readIdeaText() {
-  const decisions = await readJson(getRuntimeReadPath("decisions.json"));
+  const decisions = await readJson(path.join(getRepoRoot(), ".omx", "decisions.json"));
   const ideaDecision = [...decisions.decisions].reverse().find((entry) => entry.kind === "idea");
   return ideaDecision?.idea ?? null;
 }
 
+async function readLatestArchitectureSummary() {
+  const decisions = await readJson(path.join(getRepoRoot(), ".omx", "decisions.json"));
+  const architectureDecision = [...decisions.decisions]
+    .reverse()
+    .find((entry) => entry.kind === "skill" && entry.skill === "$arch");
+
+  return architectureDecision?.evidence?.[0]?.summary ?? null;
+}
+
 export async function runIdea(idea) {
   const trimmed = idea.trim();
   if (!trimmed) {
     throw new Error("Idea text is required");
   }
 
-  await writeProjectContext(trimmed);
-
   await appendDecision({
     kind: "idea",
     idea: trimmed,
@@ -69,13 +61,36 @@ export async function runArch() {
   }
 
   const blueprint = {
-    summary: `Blueprint derived from idea: ${idea}`,
+    summary: `Architecture blueprint derived from idea: ${idea}`,
+    targetArchitecture: {
+      orchestration: "Codex-compatible CLI orchestrator",
+      evidence: "GitMCP-backed MCP sources with explicit endpoint allowlist",
+      releaseModel: "Gated build, merge, and release states stored locally",
+    },
+    components: [
+      "CLI entrypoint",
+      "state and decision storage",
+      "MCP configuration",
+      "publishable skills bundle",
+      "release and packaging surfaces",
+    ],
     suggestedStack: ["Node.js", "MCP", "GitMCP", "Git worktree"],
-    outcome: "Produce a gated architecture and implementation plan",
+    tradeoffs: [
+      "Favor explicit file contracts over hidden runtime magic",
+      "Favor bounded build planning over unconstrained generation",
+      "Favor evidence-backed recommendation over convenience-only defaults",
+    ],
+    evidenceRequirements: [
+      "Major package and framework choices must be backed by configured GitMCP sources",
+    ],
+    downstreamHandoff: {
+      sage: "Verify stack choices against approved sources",
+      flow: "Model state transitions and blockers",
+      vet: "Check security risks and dependency posture",
+      build: "Stay locked until evidence, logic, security, and experience are green",
+    },
   };
 
-  await writeArchitectureArtifacts({ idea, blueprint });
-
   await appendDecision({
     kind: "skill",
     skill: "$arch",
@@ -90,6 +105,21 @@ export async function runArch() {
 }
 
 export async function runSage() {
+  const releaseState = await loadReleaseState();
+  if (releaseState.architecture_status !== "APPROVED") {
+    await appendDecision({
+      kind: "skill",
+      skill: "$sage",
+      decision: "Blocked evidence binding because architecture is not approved",
+      status: "UNVERIFIED",
+      evidence: [],
+      blockers: ["architecture_status must be APPROVED before $sage runs"],
+      next_allowed_triggers: ["$arch"],
+    });
+    await syncStatusUpdates({ evidence_status: "MISSING" });
+    throw new Error("Cannot run $sage before architecture is approved");
+  }
+
   const config = await validateMcpServers();
   const sourceEntries = config.servers.map((server) => ({
     repo: server.repo,
@@ -98,6 +128,7 @@ export async function runSage() {
   }));
   const blockers = [];
   const idea = (await readIdeaText()) ?? "software architecture";
+  const architectureSummary = (await readLatestArchitectureSummary()) ?? idea;
   const disableLiveProbe = process.env.MA_DISABLE_LIVE_MCP === "1";
   const probeCandidates = sourceEntries.slice(0, 1);
   let liveSuccessCount = 0;
@@ -134,7 +165,7 @@ export async function runSage() {
       if (searchTool) {
         evidence = await client.request("tools/call", {
           name: searchTool.name,
-          arguments: { query: idea },
+          arguments: { query: architectureSummary },
         });
       } else if (fetchTool) {
         evidence = await client.request("tools/call", {
@@ -151,7 +182,11 @@ export async function runSage() {
         sampleText:
           evidence?.content?.find((item) => item.type === "text")?.text?.slice(0, 400) ?? null,
       };
-      liveSuccessCount += 1;
+      if (source.liveProbe.sampleText) {
+        liveSuccessCount += 1;
+      } else {
+        blockers.push(`Live MCP query for ${source.repo} did not return usable evidence content`);
+      }
     } catch (error) {
       source.liveProbe = {
         error: error.message,
@@ -162,346 +197,168 @@ export async function runSage() {
     }
   }
 
-  const existing = await readJson(getRuntimeWritePath("evidence", "sources.json"));
+  const existing = await readJson(getSourcesPath());
   existing.items = sourceEntries;
-  await writeJson(getRuntimeWritePath("evidence", "sources.json"), existing);
+  await writeJson(getSourcesPath(), existing);
 
-  const verified = sourceEntries.length > 0 && (disableLiveProbe || liveSuccessCount > 0);
-  await writeEvidenceSpec({ idea, sourceEntries, verified, blockers });
+  const verified = sourceEntries.length > 0 && liveSuccessCount > 0;
+  const partial = sourceEntries.length > 0 && !verified;
   await appendDecision({
     kind: "skill",
     skill: "$sage",
     decision: "Bound architectural choices to approved GitMCP sources using live MCP queries",
-    status: verified ? "VERIFIED" : "UNVERIFIED",
+    status: verified ? "VERIFIED" : partial ? "PARTIAL" : "UNVERIFIED",
     evidence: sourceEntries,
     blockers: sourceEntries.length > 0 ? blockers : ["No approved GitMCP sources configured"],
     next_allowed_triggers: verified ? ["$flow"] : ["mcp/servers.json", "$sage"],
   });
 
   await syncStatusUpdates({
-    evidence_status: verified ? "VERIFIED" : sourceEntries.length > 0 ? "PARTIAL" : "MISSING",
+    evidence_status: verified ? "VERIFIED" : partial ? "PARTIAL" : "MISSING",
   });
 }
 
 export async function runFlow() {
+  const releaseState = await loadReleaseState();
+  const blockers = [];
+  if (releaseState.architecture_status !== "APPROVED") {
+    blockers.push("architecture_status must be APPROVED before $flow runs");
+  }
+  if (!["VERIFIED", "PARTIAL"].includes(releaseState.evidence_status)) {
+    blockers.push("evidence_status must be VERIFIED or PARTIAL before $flow runs");
+  }
+
   const logicMap = {
     states: ["idea", "architecture", "evidence", "logic", "security", "experience", "build"],
-    blockers: [],
+    blockers,
   };
 
-  await writeLogicSpec(logicMap);
-
   await appendDecision({
     kind: "skill",
     skill: "$flow",
-    decision: "Validated logic and state transitions",
-    status: "GREEN",
+    decision:
+      blockers.length === 0
+        ? "Validated logic and state transitions"
+        : "Blocked logic validation because prerequisite gates are not ready",
+    status: blockers.length === 0 ? "GREEN" : "RED",
     evidence: [logicMap],
-    blockers: [],
-    next_allowed_triggers: ["$vet"],
+    blockers,
+    next_allowed_triggers: blockers.length === 0 ? ["$vet"] : ["$sage", "$flow"],
   });
 
-  await syncStatusUpdates({ logic_status: "GREEN" });
+  await syncStatusUpdates({ logic_status: blockers.length === 0 ? "GREEN" : "RED" });
+
+  if (blockers.length > 0) {
+    throw new Error(blockers.join(" "));
+  }
 }
 
 export async function runVet() {
-  const auditLog = await readJson(getRuntimeWritePath("evidence", "audits.json"));
-  const cveLog = await readJson(getRuntimeWritePath("evidence", "cves.json"));
+  const releaseState = await loadReleaseState();
+  const blockers = [];
+  if (releaseState.logic_status !== "GREEN") {
+    blockers.push("logic_status must be GREEN before $vet runs");
+  }
+
+  const auditLog = await readJson(getAuditsPath());
+  const cveLog = await readJson(getCvesPath());
   const finding = {
-    severity: "INFO",
-    summary: "Baseline review completed for the approved kernel",
-    unresolved: false,
+    severity: blockers.length === 0 ? "INFO" : "HIGH",
+    summary:
+      blockers.length === 0
+        ? "Baseline review completed for the approved kernel"
+        : "Security review blocked because logic prerequisites are incomplete",
+    unresolved: blockers.length > 0,
   };
   auditLog.items.push(finding);
-  await writeJson(getRuntimeWritePath("evidence", "audits.json"), auditLog);
+  await writeJson(getAuditsPath(), auditLog);
   cveLog.items.push({
     id: "baseline-review",
     severity: "INFO",
     unresolved: false,
   });
-  await writeJson(getRuntimeWritePath("evidence", "cves.json"), cveLog);
-  await writeSecuritySpec({
-    finding,
-    auditCount: auditLog.items.length,
-    cveCount: cveLog.items.length,
-  });
+  await writeJson(getCvesPath(), cveLog);
 
   await appendDecision({
     kind: "skill",
     skill: "$vet",
-    decision: "Reviewed security posture for the current implementation",
-    status: "GREEN",
+    decision:
+      blockers.length === 0
+        ? "Reviewed security posture for the current implementation"
+        : "Blocked security review because logic is not green",
+    status: blockers.length === 0 ? "GREEN" : "RED",
     evidence: [finding],
-    blockers: [],
-    next_allowed_triggers: ["$vibe"],
+    blockers,
+    next_allowed_triggers: blockers.length === 0 ? ["$vibe"] : ["$flow", "$vet"],
   });
 
-  await syncStatusUpdates({ security_status: "GREEN" });
+  await syncStatusUpdates({ security_status: blockers.length === 0 ? "GREEN" : "RED" });
+
+  if (blockers.length > 0) {
+    throw new Error(blockers.join(" "));
+  }
 }
 
-export async function runVibe() {
-  const outcomes = await readJson(getRuntimeWritePath("evidence", "outcomes.json"));
+export async function runVibe(options = {}) {
+  const releaseState = await loadReleaseState();
+  const blockers = [];
+  if (releaseState.security_status !== "GREEN") {
+    blockers.push("security_status must be GREEN before $vibe runs");
+  }
+
+  const outcomes = await readJson(getOutcomesPath());
   const note = {
     area: "developer-experience",
-    summary: "The in-session skill flow remains the primary Meta-Architect surface",
+    summary:
+      blockers.length === 0
+        ? "Core CLI and gated workflow remain the primary operator surface"
+        : "Experience review blocked because security is not green",
   };
   outcomes.items.push(note);
-  await writeJson(getRuntimeWritePath("evidence", "outcomes.json"), outcomes);
-  await writeExperienceSpec({ note, outcomeCount: outcomes.items.length });
+  await writeJson(getOutcomesPath(), outcomes);
 
   await appendDecision({
     kind: "skill",
     skill: "$vibe",
-    decision: "Recorded DX/UX review notes",
-    status: "GREEN",
+    decision:
+      blockers.length === 0
+        ? options.waive
+          ? "Recorded DX/UX waiver decision"
+          : "Recorded DX/UX review notes"
+        : "Blocked experience review because security is not green",
+    status: blockers.length === 0 ? (options.waive ? "WAIVED" : "GREEN") : "RED",
     evidence: [note],
-    blockers: [],
-    next_allowed_triggers: ["$build"],
+    blockers,
+    next_allowed_triggers: blockers.length === 0 ? ["$build"] : ["$vet", "$vibe"],
   });
 
-  await syncStatusUpdates({ experience_status: "GREEN" });
-}
-
-export async function runInit() {
-  const created = [];
-  const targets = [
-    ".codex/agents",
-    ".codex/prompts",
-    ".ma/skills",
-    ".ma/evidence",
-    ".ma/context",
-    ".ma/specs",
-    ".ma/plans",
-    "mcp",
-    "docs",
-    "docs/qa",
-    "sprint",
-  ];
-
-  for (const relative of targets) {
-    const target = path.join(getRepoRoot(), relative);
-    await fs.mkdir(target, { recursive: true });
-    created.push(relative);
-  }
-
-  const templateCopies = [
-    [
-      path.join(packageRoot, ".codex", "agents", "Architect.toml"),
-      path.join(getRepoRoot(), ".codex", "agents", "Architect.toml"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "agents", "Sage.toml"),
-      path.join(getRepoRoot(), ".codex", "agents", "Sage.toml"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "agents", "Auditor.toml"),
-      path.join(getRepoRoot(), ".codex", "agents", "Auditor.toml"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "agents", "Flow.toml"),
-      path.join(getRepoRoot(), ".codex", "agents", "Flow.toml"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "agents", "Vibe.toml"),
-      path.join(getRepoRoot(), ".codex", "agents", "Vibe.toml"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "agents", "Builder.toml"),
-      path.join(getRepoRoot(), ".codex", "agents", "Builder.toml"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "hooks.json"),
-      path.join(getRepoRoot(), ".codex", "hooks.json"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "prompts", "enforcement.md"),
-      path.join(getRepoRoot(), ".codex", "prompts", "enforcement.md"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "prompts", "release-rules.md"),
-      path.join(getRepoRoot(), ".codex", "prompts", "release-rules.md"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "prompts", "skill-contract.md"),
-      path.join(getRepoRoot(), ".codex", "prompts", "skill-contract.md"),
-    ],
-    [
-      path.join(packageRoot, ".codex", "prompts", "onboarding.md"),
-      path.join(getRepoRoot(), ".codex", "prompts", "onboarding.md"),
-    ],
-    [path.join(packageRoot, "docs", "README.md"), path.join(getRepoRoot(), "docs", "README.md")],
-    [
-      path.join(packageRoot, "docs", "getting-started.md"),
-      path.join(getRepoRoot(), "docs", "getting-started.md"),
-    ],
-    [path.join(packageRoot, "docs", "skills.md"), path.join(getRepoRoot(), "docs", "skills.md")],
-    [
-      path.join(packageRoot, "docs", "mcp-setup.md"),
-      path.join(getRepoRoot(), "docs", "mcp-setup.md"),
-    ],
-    [
-      path.join(packageRoot, "docs", "release-spec.md"),
-      path.join(getRepoRoot(), "docs", "release-spec.md"),
-    ],
-    [
-      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.3.md"),
-      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.3.md"),
-    ],
-  ];
-
-  const sprintFiles = [
-    "00-idea.md",
-    "01-architecture.md",
-    "02-oss-evidence.md",
-    "03-logic.md",
-    "04-security.md",
-    "05-dx-ux.md",
-    "06-build-plan.md",
-    "07-release.md",
-  ];
-
-  for (const file of sprintFiles) {
-    templateCopies.push([
-      path.join(packageRoot, "sprint", file),
-      path.join(getRepoRoot(), "sprint", file),
-    ]);
-  }
+  await syncStatusUpdates({
+    experience_status: blockers.length === 0 ? (options.waive ? "WAIVED" : "GREEN") : "RED",
+  });
 
-  for (const file of ["servers.json", "collections.json", "fallback.json"]) {
-    templateCopies.push([
-      path.join(packageRoot, "mcp", file),
-      path.join(getRepoRoot(), "mcp", file),
-    ]);
+  if (blockers.length === 0 && options.waive) {
+    const nextRelease = {
+      ...(await loadReleaseState()),
+      waiver: {
+        reason: options.reason ?? "DX/UX waiver approved for the current build",
+        actor: "ma run $vibe --waive",
+        timestamp: new Date().toISOString(),
+      },
+    };
+    await saveReleaseState(nextRelease);
   }
 
-  for (const [src, dest] of templateCopies) {
-    try {
-      await fs.access(dest);
-    } catch {
-      await fs.copyFile(src, dest);
-    }
+  if (blockers.length > 0) {
+    throw new Error(blockers.join(" "));
   }
+}
 
-  await seedRuntimeArtifacts();
-
-  await writeFileIfMissing(
-    getRuntimeWritePath("decisions.json"),
-    `${JSON.stringify(
-      {
-        schemaVersion: "0.1.0",
-        idea_status: "DRAFT",
-        architecture_status: "DRAFT",
-        evidence_status: "MISSING",
-        logic_status: "PENDING",
-        security_status: "PENDING",
-        experience_status: "PENDING",
-        build_status: "LOCKED",
-        merge_status: "LOCKED",
-        release_status: "LOCKED",
-        decisions: [],
-      },
-      null,
-      2,
-    )}\n`,
-  );
-
-  await writeFileIfMissing(
-    getRuntimeWritePath("release.json"),
-    `${JSON.stringify(
-      {
-        schemaVersion: "0.1.0",
-        idea_status: "DRAFT",
-        architecture_status: "DRAFT",
-        evidence_status: "MISSING",
-        logic_status: "PENDING",
-        security_status: "PENDING",
-        experience_status: "PENDING",
-        build_status: "LOCKED",
-        merge_status: "LOCKED",
-        release_status: "LOCKED",
-        waiver: null,
-        updatedAt: new Date().toISOString(),
-      },
-      null,
-      2,
-    )}\n`,
-  );
+export async function runInit() {
+  const { created, warnings } = await runSetupScaffold();
 
-  for (const [fileName, content] of Object.entries(workflowTemplates)) {
-    await writeFileIfMissing(getRuntimeWritePath("skills", fileName), content);
+  for (const warning of warnings) {
+    console.warn(`[ma setup] ${warning}`);
   }
 
-  await writeFileIfMissing(
-    path.join(getRepoRoot(), "mcp", "servers.json"),
-    `${JSON.stringify({ schemaVersion: "0.1.0", servers: [] }, null, 2)}\n`,
-  );
-  await writeFileIfMissing(
-    path.join(getRepoRoot(), "mcp", "collections.json"),
-    `${JSON.stringify({ schemaVersion: "0.1.0", collections: {} }, null, 2)}\n`,
-  );
-  await writeFileIfMissing(
-    path.join(getRepoRoot(), "mcp", "fallback.json"),
-    `${JSON.stringify(
-      {
-        schemaVersion: "0.1.0",
-        fallback: {
-          endpoint: "https://gitmcp.io/docs",
-          policy: "Use only when no approved exact endpoint exists.",
-        },
-      },
-      null,
-      2,
-    )}\n`,
-  );
-  await writeFileIfMissing(
-    getRuntimeWritePath("evidence", "sources.json"),
-    `${JSON.stringify(
-      {
-        schemaVersion: "0.1.0",
-        items: [],
-      },
-      null,
-      2,
-    )}\n`,
-  );
-  await writeFileIfMissing(
-    getRuntimeWritePath("evidence", "audits.json"),
-    `${JSON.stringify(
-      {
-        schemaVersion: "0.1.0",
-        items: [],
-      },
-      null,
-      2,
-    )}\n`,
-  );
-  await writeFileIfMissing(
-    getRuntimeWritePath("evidence", "outcomes.json"),
-    `${JSON.stringify(
-      {
-        schemaVersion: "0.1.0",
-        items: [],
-      },
-      null,
-      2,
-    )}\n`,
-  );
-  await writeFileIfMissing(
-    getRuntimeWritePath("evidence", "cves.json"),
-    `${JSON.stringify(
-      {
-        schemaVersion: "0.1.0",
-        items: [],
-      },
-      null,
-      2,
-    )}\n`,
-  );
-
-  await writeFileIfMissing(
-    path.join(getRepoRoot(), "docs", "onboarding.md"),
-    "# Onboarding\n\nMeta-Architect initializes the core scaffold, MCP config, and canonical .ma runtime files.\n",
-  );
-
   return created;
 }

package/templates/AGENTS.md

@@ -80,11 +80,11 @@ Major technology recommendations must be supported by evidence from configured M
 
 Architecture decisions, evidence, audits, and release-relevant outcomes should be written to repository-visible local files where applicable, especially:
 
-- `.ma/decisions.json`
-- `.ma/release.json`
-- `.ma/evidence/sources.json`
-- `.ma/evidence/audits.json`
-- `.ma/evidence/cves.json`
+- `.omx/decisions.json`
+- `.omx/release.json`
+- `.omx/evidence/sources.json`
+- `.omx/evidence/audits.json`
+- `.omx/evidence/cves.json`
 
 ## Skill routing
 
@@ -104,7 +104,7 @@ When working in this repository:
 - prefer explicit reasoning and explicit file changes
 - do not skip validation steps silently
 - do not weaken hooks or gates for convenience
-- do not commit runtime `.ma` state
+- do not commit runtime `.omx` state
 - do not treat release-sensitive changes as trivial edits
 
 ## Contributor expectation

package/templates/model-instructions/core.md

@@ -6,7 +6,7 @@ Use these instructions when generating or applying repository content to the Met
 
 - Keep Meta-Architect skills, gates, evidence, and release behavior explicit.
 - Prefer inspectable files over hidden side effects.
-- Do not bypass the `.ma` gate model.
+- Do not bypass the `.omx` gate model.
 - Treat CLI, skill contracts, plugin surfaces, and docs as one coherent product system.
 
 ## Kernel rule

package/.agents/plugins/marketplace.json

@@ -1,20 +0,0 @@
-{
-  "name": "meta-architect-local",
-  "interface": {
-    "displayName": "Meta-Architect Local Plugins"
-  },
-  "plugins": [
-    {
-      "name": "meta-architect",
-      "source": {
-        "source": "local",
-        "path": "./plugins/meta-architect"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Developer Tools"
-    }
-  ]
-}