@jstn-sdk/ma 0.1.5 → 0.1.7

package/src/skills.js

@@ -1,46 +1,201 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { appendDecision } from "./decision-log.js";
-import { readJson, writeJson } from "./fs-utils.js";
+import { readJson, writeFileIfMissing, 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 {
-  getAuditsPath,
-  getCvesPath,
-  getOutcomesPath,
-  getRepoRoot,
-  getSourcesPath,
-} from "./paths.js";
-import { loadReleaseState, saveReleaseState } from "./release-state.js";
-import { runSetupScaffold } from "./setup.js";
+  seedRuntimeArtifacts,
+  writeArchitectureArtifacts,
+  writeEvidenceSpec,
+  writeExperienceSpec,
+  writeLogicSpec,
+  writeMaestroPlan,
+  writeProjectContext,
+  writeSecuritySpec,
+} from "./runtime-artifacts.js";
 import { syncStatusUpdates } from "./state-sync.js";
 
-const skillNames = ["$arch", "$sage", "$flow", "$vet", "$vibe", "$build"];
+const skillNames = ["$maestro", "$arch", "$sage", "$flow", "$vet", "$vibe", "$build"];
+const workflowTemplates = {
+  "maestro.skill.md":
+    "# `$maestro`\n\nChooses the best next workflow step and recommends the right lane or assignment.\n",
+  "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;
 }
 
+function chooseMaestroRecommendation(releaseState, idea) {
+  if (releaseState.idea_status !== "CLEAR") {
+    return {
+      nextStep: "Capture or refine the project brief before any design or validation lane starts.",
+      why: "The workflow still needs a concrete brief before architecture or build decisions can be trusted.",
+      primaryLane: "brief capture",
+      supportLane: "none",
+      assignments: ['Use `ma idea "..."` or provide the brief before running in-session skills.'],
+      avoid: ["Do not start architecture or implementation yet."],
+      nextTrigger: "`ma idea`",
+    };
+  }
+
+  if (releaseState.architecture_status !== "APPROVED") {
+    return {
+      nextStep: "Run the architecture lane first.",
+      why: "The brief exists, but the workflow still needs a concrete architecture before later gates can be trusted.",
+      primaryLane: "$arch",
+      supportLane: "$sage",
+      assignments: [
+        `Use $arch to shape the current brief${idea ? ` for: ${idea}` : ""}.`,
+        "After approval, move into $sage for source-backed stack validation.",
+      ],
+      avoid: ["Do not jump to build or release work yet."],
+      nextTrigger: "`$arch`",
+    };
+  }
+
+  if (releaseState.evidence_status !== "VERIFIED") {
+    return {
+      nextStep: "Validate the architecture against approved sources.",
+      why: "The architecture exists, but the evidence gate is not yet fully verified.",
+      primaryLane: "$sage",
+      supportLane: "$flow",
+      assignments: [
+        "Run $sage using the current architecture as the probe basis.",
+        "Prepare to hand off to $flow after evidence is verified.",
+      ],
+      avoid: ["Do not treat stack choices as settled yet."],
+      nextTrigger: "`$sage`",
+    };
+  }
+
+  if (releaseState.logic_status !== "GREEN") {
+    return {
+      nextStep: "Validate system behavior and state transitions.",
+      why: "Logic is the next unresolved gate before implementation readiness can be claimed.",
+      primaryLane: "$flow",
+      supportLane: "$vet",
+      assignments: [
+        "Run $flow to map actors, states, transitions, and blockers.",
+        "Queue $vet after the logic lane confirms behavior is sound.",
+      ],
+      avoid: ["Do not merge or release yet."],
+      nextTrigger: "`$flow`",
+    };
+  }
+
+  if (releaseState.security_status !== "GREEN") {
+    return {
+      nextStep: "Run the security and trust-boundary review.",
+      why: "Security is the next unresolved gate before the workflow can unlock implementation readiness.",
+      primaryLane: "$vet",
+      supportLane: "$vibe",
+      assignments: [
+        "Run $vet to capture trust boundaries, abuse cases, and mitigations.",
+        "Move to $vibe once security is green.",
+      ],
+      avoid: ["Do not unlock implementation readiness before security review."],
+      nextTrigger: "`$vet`",
+    };
+  }
+
+  if (!["GREEN", "WAIVED"].includes(releaseState.experience_status)) {
+    return {
+      nextStep: "Review workflow clarity and friction before build unlock.",
+      why: "The experience lane is the final quality gate before the build decision.",
+      primaryLane: "$vibe",
+      supportLane: "$build",
+      assignments: [
+        "Run $vibe to capture onboarding and operability friction.",
+        "Move to $build only after experience is green or intentionally waived.",
+      ],
+      avoid: ["Do not start release promotion yet."],
+      nextTrigger: "`$vibe`",
+    };
+  }
+
+  if (releaseState.build_status === "LOCKED") {
+    return {
+      nextStep: "Unlock bounded implementation planning.",
+      why: "All upstream quality gates are green, so the workflow can now evaluate build readiness.",
+      primaryLane: "$build",
+      supportLane: "implementation",
+      assignments: [
+        "Run $build to get the current build-readiness verdict.",
+        "Use the resulting narrow build slice as the next execution assignment.",
+      ],
+      avoid: ["Do not release directly from a task branch."],
+      nextTrigger: "`$build`",
+    };
+  }
+
+  if (releaseState.merge_status !== "MERGED_TO_DEVELOPMENT") {
+    return {
+      nextStep: "Finish the implementation slice and merge it into development.",
+      why: "The build gate is ready or done, but the branch promotion path has not completed yet.",
+      primaryLane: "implementation",
+      supportLane: "merge",
+      assignments: [
+        "Use the current build plan to finish the smallest viable implementation slice.",
+        "When ready, merge feature work into development with `ma merge`.",
+      ],
+      avoid: ["Do not promote directly to prod."],
+      nextTrigger: "`ma merge <feature/*> development`",
+    };
+  }
+
+  if (releaseState.release_status !== "SHIPPED_TO_PROD") {
+    return {
+      nextStep: "Promote the approved release line to prod.",
+      why: "Implementation and merge gates are complete, so the remaining step is the controlled release promotion.",
+      primaryLane: "release",
+      supportLane: "verification",
+      assignments: [
+        "Verify the origin branch is development or an approved release branch.",
+        "Run `ma release <origin> prod` when the line is ready.",
+      ],
+      avoid: ["Do not reopen earlier gates unless a new blocker appears."],
+      nextTrigger: "`ma release <development|release/*> prod`",
+    };
+  }
+
+  return {
+    nextStep: "The workflow is already at the terminal release state.",
+    why: "All gates, merge, and release states are complete.",
+    primaryLane: "done",
+    supportLane: "verification",
+    assignments: ["Confirm final release evidence and start a new brief for the next cycle."],
+    avoid: ["Do not rerun build or release steps without a new task."],
+    nextTrigger: "`ma idea` or `$arch` for the next task",
+  };
+}
+
 async function readIdeaText() {
-  const decisions = await readJson(path.join(getRepoRoot(), ".omx", "decisions.json"));
+  const decisions = await readJson(getRuntimeReadPath("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,
@@ -61,36 +216,13 @@ export async function runArch() {
   }
 
   const blueprint = {
-    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",
-    ],
+    summary: `Blueprint derived from idea: ${idea}`,
     suggestedStack: ["Node.js", "MCP", "GitMCP", "Git worktree"],
-    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",
-    },
+    outcome: "Produce a gated architecture and implementation plan",
   };
 
+  await writeArchitectureArtifacts({ idea, blueprint });
+
   await appendDecision({
     kind: "skill",
     skill: "$arch",
@@ -105,21 +237,6 @@ 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,
@@ -128,7 +245,6 @@ 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;
@@ -165,7 +281,7 @@ export async function runSage() {
       if (searchTool) {
         evidence = await client.request("tools/call", {
           name: searchTool.name,
-          arguments: { query: architectureSummary },
+          arguments: { query: idea },
         });
       } else if (fetchTool) {
         evidence = await client.request("tools/call", {
@@ -182,11 +298,7 @@ export async function runSage() {
         sampleText:
           evidence?.content?.find((item) => item.type === "text")?.text?.slice(0, 400) ?? null,
       };
-      if (source.liveProbe.sampleText) {
-        liveSuccessCount += 1;
-      } else {
-        blockers.push(`Live MCP query for ${source.repo} did not return usable evidence content`);
-      }
+      liveSuccessCount += 1;
     } catch (error) {
       source.liveProbe = {
         error: error.message,
@@ -197,168 +309,363 @@ export async function runSage() {
     }
   }
 
-  const existing = await readJson(getSourcesPath());
+  const existing = await readJson(getRuntimeWritePath("evidence", "sources.json"));
   existing.items = sourceEntries;
-  await writeJson(getSourcesPath(), existing);
+  await writeJson(getRuntimeWritePath("evidence", "sources.json"), existing);
 
-  const verified = sourceEntries.length > 0 && liveSuccessCount > 0;
-  const partial = sourceEntries.length > 0 && !verified;
+  const verified = sourceEntries.length > 0 && (disableLiveProbe || liveSuccessCount > 0);
+  await writeEvidenceSpec({ idea, sourceEntries, verified, blockers });
   await appendDecision({
     kind: "skill",
     skill: "$sage",
     decision: "Bound architectural choices to approved GitMCP sources using live MCP queries",
-    status: verified ? "VERIFIED" : partial ? "PARTIAL" : "UNVERIFIED",
+    status: verified ? "VERIFIED" : "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" : partial ? "PARTIAL" : "MISSING",
+    evidence_status: verified ? "VERIFIED" : sourceEntries.length > 0 ? "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:
-      blockers.length === 0
-        ? "Validated logic and state transitions"
-        : "Blocked logic validation because prerequisite gates are not ready",
-    status: blockers.length === 0 ? "GREEN" : "RED",
+    decision: "Validated logic and state transitions",
+    status: "GREEN",
     evidence: [logicMap],
-    blockers,
-    next_allowed_triggers: blockers.length === 0 ? ["$vet"] : ["$sage", "$flow"],
+    blockers: [],
+    next_allowed_triggers: ["$vet"],
   });
 
-  await syncStatusUpdates({ logic_status: blockers.length === 0 ? "GREEN" : "RED" });
-
-  if (blockers.length > 0) {
-    throw new Error(blockers.join(" "));
-  }
+  await syncStatusUpdates({ logic_status: "GREEN" });
 }
 
 export async function runVet() {
-  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 auditLog = await readJson(getRuntimeWritePath("evidence", "audits.json"));
+  const cveLog = await readJson(getRuntimeWritePath("evidence", "cves.json"));
   const finding = {
-    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,
+    severity: "INFO",
+    summary: "Baseline review completed for the approved kernel",
+    unresolved: false,
   };
   auditLog.items.push(finding);
-  await writeJson(getAuditsPath(), auditLog);
+  await writeJson(getRuntimeWritePath("evidence", "audits.json"), auditLog);
   cveLog.items.push({
     id: "baseline-review",
     severity: "INFO",
     unresolved: false,
   });
-  await writeJson(getCvesPath(), cveLog);
+  await writeJson(getRuntimeWritePath("evidence", "cves.json"), cveLog);
+  await writeSecuritySpec({
+    finding,
+    auditCount: auditLog.items.length,
+    cveCount: cveLog.items.length,
+  });
 
   await appendDecision({
     kind: "skill",
     skill: "$vet",
-    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",
+    decision: "Reviewed security posture for the current implementation",
+    status: "GREEN",
     evidence: [finding],
-    blockers,
-    next_allowed_triggers: blockers.length === 0 ? ["$vibe"] : ["$flow", "$vet"],
+    blockers: [],
+    next_allowed_triggers: ["$vibe"],
   });
 
-  await syncStatusUpdates({ security_status: blockers.length === 0 ? "GREEN" : "RED" });
-
-  if (blockers.length > 0) {
-    throw new Error(blockers.join(" "));
-  }
+  await syncStatusUpdates({ security_status: "GREEN" });
 }
 
-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());
+export async function runVibe() {
+  const outcomes = await readJson(getRuntimeWritePath("evidence", "outcomes.json"));
   const note = {
     area: "developer-experience",
-    summary:
-      blockers.length === 0
-        ? "Core CLI and gated workflow remain the primary operator surface"
-        : "Experience review blocked because security is not green",
+    summary: "The in-session skill flow remains the primary Meta-Architect surface",
   };
   outcomes.items.push(note);
-  await writeJson(getOutcomesPath(), outcomes);
+  await writeJson(getRuntimeWritePath("evidence", "outcomes.json"), outcomes);
+  await writeExperienceSpec({ note, outcomeCount: outcomes.items.length });
 
   await appendDecision({
     kind: "skill",
     skill: "$vibe",
-    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",
+    decision: "Recorded DX/UX review notes",
+    status: "GREEN",
     evidence: [note],
-    blockers,
-    next_allowed_triggers: blockers.length === 0 ? ["$build"] : ["$vet", "$vibe"],
+    blockers: [],
+    next_allowed_triggers: ["$build"],
   });
 
-  await syncStatusUpdates({
-    experience_status: blockers.length === 0 ? (options.waive ? "WAIVED" : "GREEN") : "RED",
+  await syncStatusUpdates({ experience_status: "GREEN" });
+}
+
+export async function runMaestro() {
+  const releaseState = await readJson(getRuntimeReadPath("release.json"));
+  const idea = await readIdeaText();
+  const recommendation = chooseMaestroRecommendation(releaseState, idea);
+
+  await writeMaestroPlan({ releaseState, recommendation });
+  await appendDecision({
+    kind: "skill",
+    skill: "$maestro",
+    decision: "Recommended the next workflow step and assignment lane",
+    status: "ADVISORY",
+    evidence: [recommendation],
+    blockers: [],
+    next_allowed_triggers: [recommendation.nextTrigger.replaceAll("`", "")],
   });
+}
 
-  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);
+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.7.md"),
+      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.7.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),
+    ]);
   }
 
-  if (blockers.length > 0) {
-    throw new Error(blockers.join(" "));
+  for (const file of ["servers.json", "collections.json", "fallback.json"]) {
+    templateCopies.push([
+      path.join(packageRoot, "mcp", file),
+      path.join(getRepoRoot(), "mcp", file),
+    ]);
   }
-}
 
-export async function runInit() {
-  const { created, warnings } = await runSetupScaffold();
+  for (const [src, dest] of templateCopies) {
+    try {
+      await fs.access(dest);
+    } catch {
+      await fs.copyFile(src, dest);
+    }
+  }
+
+  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`,
+  );
 
-  for (const warning of warnings) {
-    console.warn(`[ma setup] ${warning}`);
+  for (const [fileName, content] of Object.entries(workflowTemplates)) {
+    await writeFileIfMissing(getRuntimeWritePath("skills", fileName), content);
   }
 
+  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;
 }