@jstn-sdk/ma 0.1.12 → 0.14.0

package/scripts/postinstall.js

@@ -1,20 +1,27 @@
 #!/usr/bin/env node
 
+import fs from "node:fs/promises";
 import process from "node:process";
-import { installSkills, installSupportBundle } from "../src/skill-installer.js";
 
 async function main() {
-  if (process.env.MA_SKIP_AUTO_INSTALL === "1") {
-    console.log("meta-architect: skipped Codex skill auto-install");
+  const dryRun = process.env.MA_POSTINSTALL_DRY_RUN === "1";
+  const skipSkills = process.env.MA_SKIP_SKILLS === "1";
+  const receiptPath = process.env.MA_POSTINSTALL_RECEIPT;
+  console.log(
+    `meta-architect: postinstall skills=${skipSkills ? "disabled" : "enabled"} dry-run=${dryRun ? "yes" : "no"}`,
+  );
+  if (dryRun || skipSkills || process.env.MA_SKIP_AUTO_INSTALL === "1") {
+    console.log("meta-architect: deferred host selection until first interactive launch");
     return;
   }
-
-  const [
-    { targetRoot: skillRoot, installed: skills },
-    { targetRoot: bundleRoot, installed: assets },
-  ] = await Promise.all([installSkills(), installSupportBundle()]);
-  console.log(`meta-architect: installed ${skills.length} Codex skills into ${skillRoot}`);
-  console.log(`meta-architect: installed ${assets.length} support assets into ${bundleRoot}`);
+  console.log("meta-architect: host selection deferred until first interactive launch");
+  if (receiptPath) {
+    await fs.writeFile(
+      receiptPath,
+      `${JSON.stringify({ schemaVersion: "0.1.0", deferred: true }, null, 2)}\n`,
+    );
+    console.log(`meta-architect: receipt ${receiptPath}`);
+  }
 }
 
 main().catch((error) => {

package/scripts/prepack.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+execFileSync(process.execPath, ["./scripts/plugin-sync.js"], {
+  stdio: "inherit",
+  env: { ...process.env, MA_PLUGIN_SYNC_MODE: "copy" },
+});

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

@@ -31,6 +31,8 @@ const WATCHED_FILES = new Set([
 function parseArgs(argv) {
   const args = {
     bump: "",
+    version: "",
+    refreshFrom: "",
     fromRef: "",
     toRef: "",
     githubOutput: "",
@@ -44,6 +46,16 @@ function parseArgs(argv) {
       index += 1;
       continue;
     }
+    if (token === "--version") {
+      args.version = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+    if (token === "--refresh-from") {
+      args.refreshFrom = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
     if (token === "--from-ref") {
       args.fromRef = argv[index + 1] ?? "";
       index += 1;
@@ -184,6 +196,12 @@ function updateCurrentSurfaceFile(file, oldVersion, nextVersion) {
   writeText(file, content);
 }
 
+function syncReadmeReleaseSurface(_nextVersion) {
+  const readmePath = "README.md";
+  // The README uses a dynamic GitHub release badge; no version replacement is needed.
+  writeText(readmePath, readText(readmePath));
+}
+
 function syncPackageVersion(nextVersion) {
   const pkg = readJson("package.json");
   const lock = readJson("package-lock.json");
@@ -196,6 +214,14 @@ function syncPackageVersion(nextVersion) {
   writeJson("package-lock.json", lock);
 }
 
+function syncSupportBundleVersion(nextVersion) {
+  const manifestPath = "support-bundle.json";
+  if (!fs.existsSync(manifestPath)) return;
+  const manifest = readJson(manifestPath);
+  manifest.bundleVersion = nextVersion;
+  writeJson(manifestPath, manifest);
+}
+
 function syncPluginVersions(nextVersion) {
   for (const file of [
     path.join("plugins", "meta-architect", ".app.json"),
@@ -215,9 +241,13 @@ function syncPluginVersions(nextVersion) {
 function syncCurrentReleaseFiles(oldVersion, nextVersion) {
   for (const file of [
     "README.md",
+    "DEMO.md",
+    "COVERAGE.md",
     "RELEASE.md",
     path.join("docs", "README.md"),
     path.join("docs", "getting-started.md"),
+    path.join("docs", "onboarding.md"),
+    path.join("docs", "skills.md"),
     path.join("docs", "release-spec.md"),
     path.join("plugins", "meta-architect", "README.md"),
   ]) {
@@ -228,16 +258,17 @@ function syncCurrentReleaseFiles(oldVersion, nextVersion) {
   const nextQa = path.join("docs", "qa", `release-readiness-${nextVersion}.md`);
   fs.renameSync(oldQa, nextQa);
   updateCurrentSurfaceFile(nextQa, oldVersion, nextVersion);
+
+  const oldIssueGates = path.join("docs", "qa", `release-issue-gates-${oldVersion}.json`);
+  const nextIssueGates = path.join("docs", "qa", `release-issue-gates-${nextVersion}.json`);
+  if (fs.existsSync(oldIssueGates)) {
+    fs.renameSync(oldIssueGates, nextIssueGates);
+    updateCurrentSurfaceFile(nextIssueGates, oldVersion, nextVersion);
+  }
 }
 
 function syncSupportingCode(oldVersion, nextVersion) {
   const replacements = [
-    {
-      file: path.join("src", "skills.js"),
-      search: `release-readiness-${oldVersion}.md`,
-      replacement: `release-readiness-${nextVersion}.md`,
-      label: "skills QA path",
-    },
     {
       file: path.join("test", "package-install-smoke.test.js"),
       search: `jstn-sdk-ma-${oldVersion}.tgz`,
@@ -259,6 +290,9 @@ function syncSupportingCode(oldVersion, nextVersion) {
 
   const mcpLiveClientFile = path.join("src", "mcp-live-client.js");
   const mcpLiveClient = readText(mcpLiveClientFile);
+  if (/resolveMcpClientVersion\(packageMetadata\)/.test(mcpLiveClient)) {
+    return;
+  }
   if (!/version: "[0-9]+\.[0-9]+\.[0-9]+(?:-dev)?"/.test(mcpLiveClient)) {
     throw new Error("Expected to find mcp live client version declaration");
   }
@@ -271,6 +305,27 @@ function syncSupportingCode(oldVersion, nextVersion) {
   );
 }
 
+function refreshCurrentReleaseFiles(oldVersion, currentVersion) {
+  for (const file of [
+    "README.md",
+    "DEMO.md",
+    "COVERAGE.md",
+    "RELEASE.md",
+    path.join("docs", "README.md"),
+    path.join("docs", "getting-started.md"),
+    path.join("docs", "onboarding.md"),
+    path.join("docs", "skills.md"),
+    path.join("docs", "release-spec.md"),
+    path.join("plugins", "meta-architect", "README.md"),
+    path.join("docs", "qa", `release-readiness-${currentVersion}.md`),
+    path.join("docs", "qa", `release-issue-gates-${currentVersion}.json`),
+    path.join("scripts", "install.sh"),
+    path.join("plugins", "meta-architect", "obsidian", "manifest.json"),
+  ]) {
+    if (fs.existsSync(file)) updateCurrentSurfaceFile(file, oldVersion, currentVersion);
+  }
+}
+
 function rewriteReleaseState(nextVersion, previousVersion) {
   const releasePath = "RELEASE.md";
   const qaPath = path.join("docs", "qa", `release-readiness-${nextVersion}.md`);
@@ -319,6 +374,13 @@ function main() {
   const args = parseArgs(process.argv.slice(2));
   const pkg = readJson("package.json");
   const currentVersion = pkg.version;
+  if (args.refreshFrom) {
+    refreshCurrentReleaseFiles(args.refreshFrom, currentVersion);
+    console.log(
+      JSON.stringify({ updated: true, refreshed: true, version: currentVersion }, null, 2),
+    );
+    return;
+  }
   const changedFiles = getChangedFiles(args);
   const relevantChanges = args.force ? ["<forced>"] : changedFiles.filter(isWatchedPath);
 
@@ -342,12 +404,15 @@ function main() {
   }
 
   const bumpKind = args.bump || "patch";
-  const nextVersion = bumpVersion(currentVersion, bumpKind);
+  const nextVersion = args.version || bumpVersion(currentVersion, bumpKind);
+  parseVersion(nextVersion);
 
   syncPackageVersion(nextVersion);
+  syncSupportBundleVersion(nextVersion);
   syncPluginVersions(nextVersion);
   prependChangelog(nextVersion);
   syncCurrentReleaseFiles(currentVersion, nextVersion);
+  syncReadmeReleaseSurface(nextVersion);
   syncSupportingCode(currentVersion, nextVersion);
   rewriteReleaseState(nextVersion, currentVersion);
 

package/scripts/release-verify.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
 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";
@@ -38,12 +41,19 @@ function parseVersion(version) {
   return match.groups;
 }
 
+function latestCdnInstall() {
+  return "curl -fsSLo install.sh https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh && curl -fsSLo install.sh.sha256 https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh.sha256 && sed 's#scripts/install.sh#install.sh#' install.sh.sha256 | sha256sum -c - && sh install.sh";
+}
+
 function verifyInstallBlock(file) {
   const content = readText(file);
-  if (!content.includes(CANONICAL_INSTALL)) {
+  const cdnInstall = latestCdnInstall();
+  if (!content.includes(CANONICAL_INSTALL) && !content.includes(cdnInstall)) {
     return;
   }
 
+  assert(content.includes(cdnInstall), `${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 +62,230 @@ 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 verifyDistPolicy() {
+  const tracked = execFileSync("git", ["ls-files", "dist/"], { encoding: "utf8" }).trim();
+  assert(!tracked, `dist/: generated release artifacts must not be tracked:\n${tracked}`);
+}
+
+function verifyInstallerIntegrity() {
+  const installer = readText("scripts/install.sh");
+  const checksum = readText("scripts/install.sh.sha256").trim().split(/\s+/)[0];
+  const actual = crypto.createHash("sha256").update(installer).digest("hex");
+  assert(checksum === actual, "scripts/install.sh.sha256: checksum does not match installer");
+  assert(
+    !installer.includes("raw.githubusercontent.com") && !installer.includes("jsdelivr"),
+    "scripts/install.sh: must not fetch mutable installer sources at runtime",
+  );
+}
+
+function verifyDemoDoc({ version, gitTag }) {
+  const cdnInstall = latestCdnInstall();
+  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(cdnInstall), "DEMO.md: missing versioned 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 verifyReadmeReleaseSurface({ gitTag }) {
+  const content = readText("README.md");
+  const demoImage = `<img src="https://raw.githubusercontent.com/JustineDevs/meta-architect/${gitTag}/docs/assets/DEMO_VIDEO.gif" alt="Meta-Architect demo video" width="800">`;
+  const logoImage = `<img src="https://raw.githubusercontent.com/JustineDevs/meta-architect/${gitTag}/docs/assets/meta-architect-logo.svg" alt="Meta-Architect: quality gates and evidence verification for AI coding agents" width="1024" height="240">`;
+  assert(content.includes("> [!NOTE]"), "README.md: missing product-positioning note admonition");
+  assert(
+    content.includes(
+      "> Meta-Architect is a workflow layer for teams that want architecture, evidence, review, and release discipline before build execution.",
+    ),
+    "README.md: missing workflow-layer positioning note",
+  );
+  assert(
+    content.includes("> Meta-Architect does not replace your coding runtime."),
+    "README.md: missing runtime-wrapper boundary note",
+  );
+  assert(
+    content.includes(
+      "> It wraps that runtime with architecture, evidence, gate enforcement, and release-sensitive workflow control.",
+    ),
+    "README.md: missing runtime-wrapper behavior note",
+  );
+  assert(content.includes(demoImage), "README.md: missing requested 800px demo GIF");
+  assert(
+    content.includes("<summary><strong>🔌 All 33 plugins & features</strong></summary>"),
+    "README.md: missing all 33 plugins/features toggle",
+  );
+  assert(
+    content.includes(
+      "https://img.shields.io/github/v/release/JustineDevs/meta-architect?display_name=tag&sort=semver",
+    ),
+    "README.md: missing GitHub release badge",
+  );
+  assert(content.includes(logoImage), "README.md: release-pinned logo missing");
+  assert(
+    !content.includes("raw.githubusercontent.com/JustineDevs/meta-architect/main/"),
+    "README.md: stable docs must not reference mutable main",
+  );
+}
+
+function verifyRealDemoKit() {
+  const runbook = readText(path.join("docs", "demo", "REAL_DEMO_RUNBOOK.md"));
+  const story = readText(path.join("docs", "demo", "DEMO_STORY.md"));
+  const checklist = readText(path.join("docs", "demo", "PROSPECT_CHECKLIST.md"));
+  assert(fs.existsSync(path.join("scripts", "demo-smoke.js")), "scripts/demo-smoke.js: missing");
+  assert(
+    runbook.includes("npm run demo:smoke"),
+    "REAL_DEMO_RUNBOOK.md: missing demo smoke command",
+  );
+  assert(runbook.includes("$maestro"), "REAL_DEMO_RUNBOOK.md: missing maestro scenario");
+  assert(
+    runbook.includes("vault_context"),
+    "REAL_DEMO_RUNBOOK.md: missing Obsidian context boundary",
+  );
+  assert(story.includes("Northstar Logistics"), "DEMO_STORY.md: missing realistic buyer story");
+  assert(story.includes("npm run release:verify"), "DEMO_STORY.md: missing release proof close");
+  assert(
+    checklist.includes("Remove `Demo Account`, `Test Company`, `Sample Co`"),
+    "PROSPECT_CHECKLIST.md: missing no-test-branding check",
+  );
+  for (const forbidden of ["Demo Account", "Test Company", "Sample Co"]) {
+    assert(
+      !runbook.includes(forbidden) && !story.includes(forbidden),
+      `demo docs: forbidden visible demo branding ${forbidden}`,
+    );
+  }
+}
+
+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 ${gitTag} 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 +302,17 @@ 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();
+  verifyDistPolicy();
+  verifyInstallerIntegrity();
+  verifyDemoDoc({ version, gitTag });
+  verifyCoverageDoc({ version, gitTag });
+  verifyReadmeReleaseSurface({ gitTag });
+  verifyRealDemoKit();
+  verifyCanonicalSemanticSurfaces({ version, gitTag });
 
   const changelog = readText("CHANGELOG.md");
   assert(changelog.includes(`## ${gitTag}`), "CHANGELOG.md: missing current version heading");
@@ -95,6 +340,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,12 +365,14 @@ 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"),
     path.join("plugins", "meta-architect", "README.md"),
   ]) {
-    verifyInstallBlock(file);
+    verifyInstallBlock(file, gitTag);
   }
 
   const envTag =

package/scripts/setup-npmrc.js

@@ -1,39 +1,64 @@
 #!/usr/bin/env node
 
+import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 
-function normalizeRegistry(registryUrl) {
-  return registryUrl.endsWith("/") ? registryUrl : `${registryUrl}/`;
+export async function createTemporaryNpmConfig({
+  token,
+  registry = "https://registry.npmjs.org/",
+  scope = "",
+  tempRoot = process.env.RUNNER_TEMP || os.tmpdir(),
+} = {}) {
+  if (!token) return null;
+  const normalizedRegistry = registry.endsWith("/") ? registry : `${registry}/`;
+  const host = new URL(normalizedRegistry).host;
+  const configPath = path.join(tempRoot, `meta-architect-npmrc-${randomUUID()}`);
+  const content = [
+    `registry=${normalizedRegistry}`,
+    ...(scope ? [`${scope}:registry=${normalizedRegistry}`] : []),
+    `//${host}/:_authToken=${token}`,
+    "",
+  ].join("\n");
+
+  await fs.writeFile(configPath, content, { encoding: "utf8", mode: 0o600 });
+  await fs.chmod(configPath, 0o600);
+  return configPath;
+}
+
+export async function cleanupTemporaryNpmConfig(configPath) {
+  if (!configPath) return false;
+  await fs.rm(configPath, { force: true });
+  return true;
 }
 
 async function main() {
   const token = process.env.NPM_TOKEN || process.env.NODE_AUTH_TOKEN;
   if (!token) {
-    console.log("No npm token detected. Skipping .npmrc generation.");
+    console.log("No npm token detected. Skipping temporary npm auth config.");
     return;
   }
 
-  const registry = normalizeRegistry(process.env.NPM_REGISTRY_URL || "https://registry.npmjs.org/");
-  const scope = process.env.NPM_SCOPE || "";
-  const host = new URL(registry).host;
-  const npmrcPath = path.join(process.cwd(), ".npmrc");
-
-  const content = [
-    `registry=${registry}`,
-    ...(scope ? [`${scope}:registry=${registry}`] : []),
-    `//${host}/:_authToken=${token}`,
-    "",
-  ].join("\n");
-
-  await fs.writeFile(npmrcPath, content, "utf8");
-  console.log(
-    `Wrote CI .npmrc for ${scope ? `scope ${scope}` : "the canonical unscoped package"}.`,
-  );
+  const configPath = await createTemporaryNpmConfig({
+    token,
+    registry: process.env.NPM_REGISTRY_URL || "https://registry.npmjs.org/",
+    scope: process.env.NPM_SCOPE || "",
+  });
+  if (process.env.GITHUB_ENV) {
+    await fs.appendFile(process.env.GITHUB_ENV, `NPM_CONFIG_USERCONFIG=${configPath}\n`);
+  }
+  console.log("Created temporary npm auth config outside the workspace.");
+  if (!process.env.GITHUB_ENV) {
+    console.log(`Use NPM_CONFIG_USERCONFIG=${configPath} for the current command.`);
+  }
 }
 
-main().catch((error) => {
-  console.error(error.message);
-  process.exitCode = 1;
-});
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/skills-install.js

@@ -1,22 +1,29 @@
 #!/usr/bin/env node
 
 import process from "node:process";
-import { installSkills } from "../src/skill-installer.js";
+import { installSkills, rollbackInstalledAssets } from "../src/skill-installer.js";
 
 function parseArgs(argv) {
-  const args = { path: null };
+  const args = { path: null, rollback: false };
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (token === "--path") {
       args.path = argv[index + 1];
       index += 1;
     }
+    if (token === "--rollback") args.rollback = true;
   }
   return args;
 }
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  if (args.rollback) {
+    console.log(
+      JSON.stringify(await rollbackInstalledAssets({ targetRoot: args.path ?? undefined })),
+    );
+    return;
+  }
   const { installed } = await installSkills({ targetRoot: args.path ?? undefined });
   for (const skill of installed) {
     console.log(`installed ${skill.name} -> ${skill.dest}`);