@jstn-sdk/ma 0.1.12 → 0.14.0

package/scripts/context-hydration-hook.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createBudgetedContext } from "../src/runtime/context-economy-core.js";
+import { maskSensitiveText } from "../src/runtime/redaction-gateway.js";
+
+const root = path.resolve(process.env.MA_ROOT || process.cwd());
+const contextRoot = path.join(root, ".ma", "context");
+
+async function read(relative, fallback = null) {
+  try {
+    return await fs.readFile(path.join(contextRoot, relative), "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+const [project, brief, commands, learning] = await Promise.all([
+  read("project-index.json"),
+  read("agent-brief.md", ""),
+  read("commands.json"),
+  fs.readFile(path.join(root, ".ma", "learning", "records.jsonl"), "utf8").catch(() => ""),
+]);
+const preferences = await fs
+  .readFile(path.join(root, ".ma", "memory", "preferences.json"), "utf8")
+  .catch(() => "{}");
+const records = learning
+  .split("\n")
+  .filter(Boolean)
+  .slice(-3)
+  .map((line) => {
+    try {
+      const value = JSON.parse(line);
+      return { claim: value.claim, status: value.status, authority: "learning_memory" };
+    } catch {
+      return null;
+    }
+  })
+  .filter(Boolean);
+
+const result = {
+  record_type: "context_hydration",
+  root,
+  loaded: {
+    projectIndex: Boolean(project),
+    agentBrief: Boolean(brief),
+    commands: Boolean(commands),
+    learningRecords: records.length,
+    preferences: preferences !== "{}",
+  },
+  skipped: ["repository-wide source scan", "full Obsidian vault"],
+  stale: project
+    ? (() => {
+        try {
+          return JSON.parse(project).freshness?.status === "stale";
+        } catch {
+          return true;
+        }
+      })()
+    : true,
+  authority: "generated_context",
+  context: {
+    project: project ? maskSensitiveText(project).sanitizedText : null,
+    brief: maskSensitiveText(brief).sanitizedText,
+    commands: commands ? maskSensitiveText(commands).sanitizedText : null,
+    learning: records,
+    preferences: (() => {
+      try {
+        return JSON.parse(preferences).preferences ?? {};
+      } catch {
+        return {};
+      }
+    })(),
+  },
+};
+const budgeted = createBudgetedContext({
+  budgetChars: Number(process.env.MA_CONTEXT_BUDGET_CHARS || 12000),
+  topic: process.env.MA_CONTEXT_TOPIC,
+  items: [
+    { id: "agent-brief", tier: 1, topic: "brief", text: brief },
+    { id: "commands", tier: 3, topic: "commands", text: commands ?? "" },
+    { id: "learning", tier: 4, topic: "learning", text: JSON.stringify(records) },
+    { id: "preferences", tier: 4, topic: "preferences", text: preferences },
+    { id: "project-index", tier: 5, topic: "project", text: project ?? "" },
+  ],
+});
+result.budget = budgeted;
+process.stdout.write(`${JSON.stringify(result)}\n`);

package/scripts/demo-smoke.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  createContextEconomyView,
+  createDefaultLearningLoopCore,
+  createDefaultPromptStrategyCore,
+  createDiscoveredEnvironmentAwarenessCore,
+  createObsidianNote,
+  createRalphPrdContract,
+  evaluateLearningLoopReadiness,
+  indexObsidianVault,
+  readObsidianNote,
+  runIdea,
+  runInit,
+  updateObsidianNote,
+  validatePromptStrategyCore,
+  validateRalphPrdContract,
+  writeObsidianVaultIndex,
+} from "../index.js";
+import { loadRuntimeSnapshot } from "../src/runtime/runtime-state.js";
+import { runMaestro } from "../src/skills.js";
+import { createTestNamespace } from "../src/test-fixtures.js";
+
+const demoIdea =
+  "Northstar Logistics wants to harden an existing dispatch analytics workspace for a production release. MA must inspect current runtime context, use Obsidian vault notes as brain context, route through relevant roles, preserve security gates, and produce a release-safe next action instead of asking for permission.";
+
+async function writeFile(file, content) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, content, "utf8");
+}
+
+async function seedWorkspace(root) {
+  await writeFile(
+    path.join(root, "package.json"),
+    `${JSON.stringify(
+      {
+        name: "northstar-dispatch-analytics",
+        version: "2.4.0",
+        type: "module",
+        scripts: {
+          test: "node --test",
+          check: "node --check src/index.js",
+          release: "node scripts/release-check.js",
+        },
+        dependencies: {
+          "@modelcontextprotocol/sdk": "^1.0.0",
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  await writeFile(
+    path.join(root, "src", "index.js"),
+    "export const serviceName = 'northstar-dispatch-analytics';\n",
+  );
+  await writeFile(
+    path.join(root, "mcp", "servers.json"),
+    `${JSON.stringify(
+      {
+        mcpServers: {
+          "obsidian-api Docs": {
+            url: "https://gitmcp.io/obsidianmd/obsidian-api",
+          },
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+async function seedVault(vaultPath) {
+  await writeFile(
+    path.join(vaultPath, "Northstar", "Dispatch Release Objective.md"),
+    `---
+ma_records_as: vault_context
+ma_project: northstar-dispatch-analytics
+ma_capabilities:
+  - maestro
+  - obsidian
+  - learning-loop
+ma_source_workspace: northstar-dispatch-analytics
+---
+# Dispatch Release Objective
+
+Northstar Logistics needs a production-safe release plan for dispatch analytics.
+
+## Pain Points
+
+- Missed gate ownership causes late release rollback risk. #release
+- Unstructured knowledge lives in operations notes and is not visible to build planning. #knowledge
+- Security and DX review happen after implementation instead of before build execution. #security #dx
+
+## Links
+
+- [[Northstar/Risk Register]]
+- [[Meta-Architect/Core Brain Context]]
+`,
+  );
+  await writeFile(
+    path.join(vaultPath, "Northstar", "Risk Register.md"),
+    `---
+ma_records_as: vault_context
+ma_project: northstar-dispatch-analytics
+---
+# Risk Register
+
+Known risks:
+
+- Third-party carrier API failures can block dispatch reconciliation.
+- Customer PII must not be copied into prompt-bound release artifacts.
+- [[Northstar/Dispatch Release Objective]] owns the business target.
+`,
+  );
+  await writeFile(
+    path.join(vaultPath, "Meta-Architect", "Core Brain Context.md"),
+    `---
+ma_records_as: vault_context
+ma_project: northstar-dispatch-analytics
+---
+# Core Brain Context
+
+MA should treat this vault as semantic brain context only.
+Authoritative build evidence must return through $maestro or the owning lane.
+`,
+  );
+}
+
+function assertNoDemoBranding(value) {
+  const serialized = JSON.stringify(value);
+  assert.doesNotMatch(serialized, /Demo Account|Test Company|Sample Co|Acme/i);
+}
+
+async function main() {
+  const originalCwd = process.cwd();
+  const workspace = createTestNamespace("ma-real-demo");
+  const vaultPath = path.join(workspace, "Northstar Vault");
+  await seedWorkspace(workspace);
+  await seedVault(vaultPath);
+
+  process.chdir(workspace);
+  try {
+    await runInit();
+    await runIdea(demoIdea);
+    await runMaestro();
+
+    const createdNote = await createObsidianNote({
+      vaultPath,
+      notePath: "Meta-Architect/Release Gate Plan.md",
+      overwrite: true,
+      content: `---
+ma_records_as: vault_context
+ma_project: northstar-dispatch-analytics
+ma_source_workspace: northstar-dispatch-analytics
+---
+# Release Gate Plan
+
+This note records the MA demo path for Northstar Logistics.
+
+- Start at [[Meta-Architect/Map of Content]]
+- Use [[Northstar/Dispatch Release Objective]] for buyer context
+- Keep build evidence in MA lane artifacts
+`,
+    });
+    await updateObsidianNote({
+      vaultPath,
+      notePath: "Meta-Architect/Release Gate Plan.md",
+      content: `${createdNote.relative_path ? "" : ""}---
+ma_records_as: vault_context
+ma_project: northstar-dispatch-analytics
+ma_source_workspace: northstar-dispatch-analytics
+---
+# Release Gate Plan
+
+This note records the MA demo path for Northstar Logistics.
+
+- Start at [[Meta-Architect/Map of Content]]
+- Use [[Northstar/Dispatch Release Objective]] for buyer context
+- Use [[Northstar/Risk Register]] for security and rollback concerns
+- Keep build evidence in MA lane artifacts
+`,
+    });
+    const readNote = await readObsidianNote({
+      vaultPath,
+      notePath: "Meta-Architect/Release Gate Plan.md",
+    });
+    const vaultIndex = await writeObsidianVaultIndex({ vaultPath });
+    const directVaultIndex = await indexObsidianVault({ vaultPath });
+
+    const learningReadiness = evaluateLearningLoopReadiness(createDefaultLearningLoopCore());
+    const promptStrategy = validatePromptStrategyCore(createDefaultPromptStrategyCore());
+    const contextEconomy = createContextEconomyView({
+      text: "The architecture lane should preserve exact commands, risk language, and verification gaps while compressing low-value filler for the live demo operator.",
+      level: "full",
+    });
+    const environmentAwareness = await createDiscoveredEnvironmentAwarenessCore({ cwd: workspace });
+    const ralphContract = validateRalphPrdContract(
+      createRalphPrdContract({
+        project: "northstar-dispatch-analytics",
+        branchName: "ralph/northstar-release-gates",
+        description: "Prepare release-safe dispatch analytics execution handoff.",
+        buildSlice: [
+          "Verify MA release gates before Ralph-style execution begins.",
+          "Preserve Obsidian context as vault_context, not build_evidence.",
+        ],
+        verificationPlan: [
+          "$arch, $sage, $flow, $vet, and $vibe are represented before $build.",
+          "Obsidian context is tagged as vault_context, not build_evidence.",
+        ],
+      }),
+    );
+    const runtimeSnapshot = await loadRuntimeSnapshot();
+
+    const proof = {
+      record_type: "ma_real_demo_smoke_proof",
+      workspace,
+      vaultPath,
+      idea: demoIdea,
+      maestro: {
+        global_status: runtimeSnapshot.maestroState.global_status,
+        track_count: Object.keys(runtimeSnapshot.maestroState.runtime_tracks).length,
+        next_plan_exists: true,
+      },
+      obsidian: {
+        note_count: vaultIndex.note_count,
+        records_as: vaultIndex.records_as,
+        build_evidence: vaultIndex.build_evidence,
+        graph_map_present: vaultIndex.notes.some(
+          (note) => note.relative_path === "Meta-Architect/Map of Content.md",
+        ),
+        linked_release_plan: readNote.content.includes("[[Meta-Architect/Map of Content]]"),
+        direct_index_note_count: directVaultIndex.note_count,
+      },
+      learning: {
+        domain_count: learningReadiness.domains,
+        verified_domain_count: learningReadiness.verified_domains,
+        ready: learningReadiness.ready,
+      },
+      prompt_strategy: {
+        lane_count: Object.keys(promptStrategy.lane_policy).length,
+      },
+      context_economy: {
+        mode: contextEconomy.mode,
+        preserved_exact_count: contextEconomy.preserved_exact.length,
+      },
+      environment_awareness: {
+        capability_count: environmentAwareness.capabilities.length,
+        capability_types: [
+          ...new Set(environmentAwareness.capabilities.map((item) => item.capability_type)),
+        ].sort(),
+      },
+      ralph: {
+        story_count: ralphContract.userStories.length,
+        authority: ralphContract.authority,
+      },
+    };
+
+    assert.equal(proof.obsidian.records_as, "vault_context");
+    assert.equal(proof.obsidian.build_evidence, false);
+    assert.equal(proof.obsidian.graph_map_present, true);
+    assert.equal(proof.obsidian.linked_release_plan, true);
+    assert.equal(proof.learning.ready, true);
+    assert.equal(proof.ralph.story_count, 1);
+    assertNoDemoBranding(proof);
+
+    await writeFile(
+      path.join(workspace, ".ma", "evidence", "real-demo-smoke-proof.json"),
+      `${JSON.stringify(proof, null, 2)}\n`,
+    );
+    console.log(JSON.stringify(proof, null, 2));
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+try {
+  await main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/scripts/doctor.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { printDoctorStatuses } from "../src/runtime/doctor-report.js";
 import {
   getDebArtifactName,
   getPacmanArtifactName,
@@ -28,7 +29,24 @@ const checks = [
   [".codex/hooks.json", fs.existsSync(".codex/hooks.json")],
   [".ma/decisions.json", fs.existsSync(".ma/decisions.json")],
   [".ma/release.json", fs.existsSync(".ma/release.json")],
+  [
+    ".ma/context/helper-orchestration-core.json",
+    fs.existsSync(".ma/context/helper-orchestration-core.json"),
+  ],
+  [
+    ".ma/context/environment-awareness-core.json",
+    fs.existsSync(".ma/context/environment-awareness-core.json"),
+  ],
+  [
+    ".ma/context/universal-plugin-broker-core.json",
+    fs.existsSync(".ma/context/universal-plugin-broker-core.json"),
+  ],
   ["docs/release-spec.md", fs.existsSync("docs/release-spec.md")],
+  ["DEMO.md", fs.existsSync("DEMO.md")],
+  ["COVERAGE.md", fs.existsSync("COVERAGE.md")],
+  ["data/clone-data.proof.json", fs.existsSync("data/clone-data.proof.json")],
+  ["data/clone-data.ledger.json", fs.existsSync("data/clone-data.ledger.json")],
+  ["data/clone-data.rvf", fs.existsSync("data/clone-data.rvf")],
   [".agents/plugins/marketplace.json", fs.existsSync(".agents/plugins/marketplace.json")],
   ["plugins/meta-architect/.app.json", fs.existsSync("plugins/meta-architect/.app.json")],
   [
@@ -36,21 +54,18 @@ const checks = [
     fs.existsSync("plugins/meta-architect/.codex-plugin/plugin.json"),
   ],
   ["plugins/meta-architect/.mcp.json", fs.existsSync("plugins/meta-architect/.mcp.json")],
-  [
-    "missions/collaborative-whiteboard/mission.md",
-    fs.existsSync("missions/collaborative-whiteboard/mission.md"),
-  ],
   ["prompts/architect.md", fs.existsSync("prompts/architect.md")],
 ];
 
-let failures = 0;
+const statuses = [];
 for (const [label, ok] of checks) {
-  if (ok) {
-    console.log(`[OK] ${label}`);
-  } else {
-    console.log(`[MISSING] ${label}`);
-    failures += 1;
-  }
+  statuses.push({
+    kind: ok ? "OK" : "BLOCKED",
+    label,
+    detail: ok ? "present" : "missing release artifact",
+  });
 }
 
-process.exitCode = failures === 0 ? 0 : 1;
+console.log("Scope: maintainer release/package artifacts (not installed environment health)");
+const result = printDoctorStatuses("Meta-Architect Package Doctor", statuses);
+process.exitCode = result === "READY" ? 0 : 1;

package/scripts/install.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env sh
+set -eu
+
+MA_PACKAGE="${MA_PACKAGE:-@jstn-sdk/ma@0.14.0}"
+CODEX_PACKAGE="${CODEX_PACKAGE:-@openai/codex@latest}"
+NO_SETUP=0
+NO_SKILLS=0
+DRY_RUN=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --no-setup) NO_SETUP=1 ;;
+    --no-skills) NO_SKILLS=1 ;;
+    --dry-run) DRY_RUN=1 ;;
+    *) echo "meta-architect install: unknown option: $arg" >&2; exit 2 ;;
+  esac
+done
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "meta-architect install: missing required command: $1" >&2
+    exit 1
+  }
+}
+
+need_cmd npm
+need_cmd node
+
+echo "meta-architect install: plan"
+echo "  install: $CODEX_PACKAGE $MA_PACKAGE"
+echo "  setup: $([ "$NO_SETUP" -eq 1 ] && echo disabled || echo enabled)"
+echo "  skills: $([ "$NO_SKILLS" -eq 1 ] && echo disabled || echo enabled)"
+echo "  undo: npm uninstall -g $MA_PACKAGE $CODEX_PACKAGE"
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  echo "meta-architect install: dry-run complete"
+  exit 0
+fi
+
+if [ "$NO_SKILLS" -eq 1 ]; then export MA_SKIP_SKILLS=1; fi
+npm i -g "$CODEX_PACKAGE" "$MA_PACKAGE"
+echo "meta-architect install: versions"
+node --version
+npm --version
+command -v codex >/dev/null 2>&1 && codex --version || echo "codex: unavailable"
+
+if command -v ma >/dev/null 2>&1 && [ "$NO_SETUP" -eq 0 ]; then
+  echo "meta-architect install: seeding local MA runtime"
+  ma setup
+  echo "meta-architect install: ready"
+  echo "start: ma --madmax --high"
+elif [ "$NO_SETUP" -eq 1 ]; then
+  echo "meta-architect install: setup disabled by --no-setup"
+else
+  echo "meta-architect install: ma command not found after npm install" >&2
+  exit 1
+fi

package/scripts/install.sh.sha256

@@ -0,0 +1 @@
+0a18d94ded8872eae750cd2cc4a5b6ab05a6c48796def3634bc2414b3d48f7f7  scripts/install.sh

package/scripts/linux-package-smoke.mjs

@@ -3,9 +3,9 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import process from "node:process";
+import { createTestNamespace } from "../src/test-fixtures.js";
 import {
   getDebArtifactPath,
   getPacmanArtifactPath,
@@ -61,7 +61,7 @@ async function main() {
     throw new Error("Native Linux package smoke validation is supported only on Linux hosts");
   }
 
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "meta-architect-linux-smoke-"));
+  const tempRoot = createTestNamespace("meta-architect-linux-smoke");
   const debExtractRoot = path.join(tempRoot, "deb");
   const pacmanExtractRoot = path.join(tempRoot, "pacman");
   const rpmExtractRoot = path.join(tempRoot, "rpm");

package/scripts/package-size-check.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+
+const budget = Number(process.env.MA_PACKAGE_SIZE_BUDGET ?? 5 * 1024 * 1024);
+const result = spawnSync("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"], {
+  encoding: "utf8",
+});
+if (result.status !== 0) throw new Error(result.stderr || "npm pack inspection failed");
+const pack = JSON.parse(result.stdout)[0];
+const excludedMedia = pack.files.filter((file) => /docs\/assets\//.test(file.path));
+if (excludedMedia.length > 0)
+  throw new Error(
+    `Heavy demo media included: ${excludedMedia.map((file) => file.path).join(", ")}`,
+  );
+const unexpectedExecutables = pack.files.filter(
+  (file) =>
+    file.mode === 493 && !file.path.startsWith("bin/") && !/^scripts\/[^/]+\.sh$/.test(file.path),
+);
+if (unexpectedExecutables.length > 0) {
+  throw new Error(
+    `Unexpected executable package files: ${unexpectedExecutables.map((file) => file.path).join(", ")}`,
+  );
+}
+console.log(`package size: ${pack.size} bytes (budget ${budget})`);
+if (pack.size > budget) throw new Error(`Package exceeds ${budget} byte budget`);

package/scripts/plugin-sync.js

@@ -3,6 +3,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 
 const repoRoot = process.cwd();
 const skillsRoot = path.join(repoRoot, "skills");
@@ -30,10 +31,23 @@ async function copyDir(src, dest) {
   }
 }
 
+async function linkOrCopyDir(src, dest) {
+  if (process.env.MA_PLUGIN_SYNC_MODE !== "copy") {
+    try {
+      await fs.symlink(path.relative(path.dirname(dest), src), dest, "dir");
+      return "symlink";
+    } catch {
+      // Restricted worktrees and Windows may reject directory links.
+    }
+  }
+  await copyDir(src, dest);
+  return "copy";
+}
+
 async function listSkillDirs(root) {
-  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  const entries = await fs.readdir(root, { withFileTypes: true });
   return entries
-    .filter((entry) => entry.isDirectory())
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
     .map((entry) => entry.name)
     .sort();
 }
@@ -53,24 +67,74 @@ async function syncPluginSkills() {
     const src = path.join(skillsRoot, name);
     const dest = path.join(pluginSkillsRoot, name);
     await fs.rm(dest, { recursive: true, force: true });
-    await copyDir(src, dest);
+    await linkOrCopyDir(src, dest);
   }
 
   return skillDirs;
 }
 
-async function verifyPluginSkills() {
-  const skillDirs = await listSkillDirs(skillsRoot);
-  const pluginDirs = await listSkillDirs(pluginSkillsRoot);
-  if (skillDirs.length !== pluginDirs.length) {
-    throw new Error("Plugin skill mirror drift: directory count mismatch");
+async function listFiles(root, current = root, files = []) {
+  const entries = await fs.readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(current, entry.name);
+    if (entry.isDirectory() || entry.isSymbolicLink()) {
+      await listFiles(root, absolutePath, files);
+    } else if (entry.isFile()) {
+      files.push(path.relative(root, absolutePath));
+    }
+  }
+  return files.sort();
+}
+
+export async function verifyPluginSkills(sourceRoot = skillsRoot, mirrorRoot = pluginSkillsRoot) {
+  await fs.access(sourceRoot);
+  await fs.access(mirrorRoot);
+  const sourceSkillDirs = await listSkillDirs(sourceRoot);
+  const mirrorSkillDirs = await listSkillDirs(mirrorRoot);
+  const filesForSkillDirs = async (root, skillDirs) => {
+    const files = [];
+    for (const skillDir of skillDirs) {
+      for (const relativePath of await listFiles(path.join(root, skillDir))) {
+        files.push(path.join(skillDir, relativePath));
+      }
+    }
+    return files.sort();
+  };
+  const sourceFiles = await filesForSkillDirs(sourceRoot, sourceSkillDirs);
+  const mirrorFiles = await filesForSkillDirs(mirrorRoot, mirrorSkillDirs);
+  if (JSON.stringify(sourceFiles) !== JSON.stringify(mirrorFiles)) {
+    throw new Error("Plugin skill mirror drift: file set mismatch");
   }
 
-  for (let index = 0; index < skillDirs.length; index += 1) {
-    if (skillDirs[index] !== pluginDirs[index]) {
-      throw new Error(
-        `Plugin skill mirror drift: expected ${skillDirs[index]}, found ${pluginDirs[index]}`,
-      );
+  for (const relativePath of sourceFiles) {
+    const sourcePath = path.join(sourceRoot, relativePath);
+    const mirrorPath = path.join(mirrorRoot, relativePath);
+    const [source, mirror, sourceStat, mirrorStat] = await Promise.all([
+      fs.readFile(sourcePath),
+      fs.readFile(mirrorPath),
+      fs.stat(sourcePath),
+      fs.stat(mirrorPath),
+    ]);
+    if (!source.equals(mirror)) {
+      throw new Error(`Plugin skill mirror drift: content mismatch at ${relativePath}`);
+    }
+    if ((sourceStat.mode & 0o777) !== (mirrorStat.mode & 0o777)) {
+      throw new Error(`Plugin skill mirror drift: mode mismatch at ${relativePath}`);
+    }
+  }
+  for (const skillDir of sourceSkillDirs) {
+    const mirrorPath = path.join(mirrorRoot, skillDir);
+    const mirrorStat = await fs.lstat(mirrorPath);
+    if (mirrorStat.isSymbolicLink()) {
+      const [sourceRealPath, mirrorRealPath] = await Promise.all([
+        fs.realpath(path.join(sourceRoot, skillDir)),
+        fs.realpath(mirrorPath),
+      ]);
+      if (sourceRealPath !== mirrorRealPath) {
+        throw new Error(`Plugin skill mirror drift: invalid symlink target at ${skillDir}`);
+      }
+    } else if (!mirrorStat.isDirectory()) {
+      throw new Error(`Plugin skill mirror drift: invalid mirror entry at ${skillDir}`);
     }
   }
 }
@@ -87,7 +151,9 @@ async function main() {
   console.log(pluginSkillsRoot);
 }
 
-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;
+  });
+}