@rryando/arcs 3.1.0 → 3.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rryando/arcs",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "ARCS — DAG-based task orchestration for AI agents. Persistent workflow continuity via graph-structured context.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/",
+    "scripts/",
     "templates/",
     "skills/",
     "opencode/"
@@ -38,8 +39,8 @@
     "start": "node dist/index.js",
     "dev": "tsc --watch",
     "test": "vitest run",
-    "postinstall": "npm run build && node scripts/arcs-init.mjs",
-    "init": "npm run build && node dist/index.js init",
+    "postinstall": "node scripts/arcs-init.mjs",
+    "init": "node dist/index.js init",
     "lint": "biome check src/ test/",
     "lint:fix": "biome check --fix src/ test/",
     "format": "biome format --write src/ test/",

package/scripts/arcs-init.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+// ARCS CLI global registration
+// Usage: node scripts/arcs-init.mjs [-g] [--uninstall]
+// Creates symlink ~/.local/bin/arcs → scripts/arcs-cli.mjs
+
+import { existsSync, lstatSync, mkdirSync, symlinkSync, unlinkSync, readlinkSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+// lstatSync-based check: works even for dangling symlinks (existsSync follows the target)
+function linkExists(p) {
+  try { lstatSync(p); return true; } catch { return false; }
+}
+
+function isCommandAvailable(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore", shell: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPath = resolve(__dirname, "arcs-cli.mjs");
+const binDir = resolve(process.env.HOME || "~", ".local/bin");
+const linkPath = resolve(binDir, "arcs");
+const uninstall = process.argv.includes("--uninstall");
+
+if (uninstall) {
+  if (linkExists(linkPath)) {
+    unlinkSync(linkPath);
+    console.log(`Removed: ${linkPath}`);
+  } else {
+    console.log("Nothing to remove.");
+  }
+  process.exit(0);
+}
+
+// Ensure bin dir
+if (!existsSync(binDir)) {
+  mkdirSync(binDir, { recursive: true });
+}
+
+// Remove stale symlink if exists
+if (linkExists(linkPath)) {
+  const current = readlinkSync(linkPath);
+  if (current === cliPath) {
+    console.log(`Already registered: ${linkPath} → ${cliPath}`);
+    process.exit(0);
+  }
+  unlinkSync(linkPath);
+}
+
+symlinkSync(cliPath, linkPath);
+console.log(`Registered: ${linkPath} → ${cliPath}`);
+
+// PATH check
+const pathDirs = (process.env.PATH || "").split(":");
+if (!pathDirs.includes(binDir)) {
+  console.warn(`\nWARNING: ${binDir} is not in PATH.`);
+  console.warn(`Add to your shell rc:  export PATH="$HOME/.local/bin:$PATH"`);
+}
+
+console.log(`\nUsage: arcs <command> [args]`);
+console.log(`Commands: context, task, plan, knowledge, search, diagram, batch, validate`);
+
+// Dependency checks
+console.log("");
+if (!isCommandAvailable("gh")) {
+  console.warn(`WARNING: gh (GitHub CLI) not found.`);
+  console.warn(`  Skills like deep-pr-review require it: https://cli.github.com/`);
+}
+
+if (!isCommandAvailable("rtk")) {
+  console.warn(`WARNING: rtk not found.`);
+  console.warn(`  RTK improves AI command usage tracking: https://github.com/rtk-ai/rtk`);
+  console.warn(`  Install: rtk init -g  (or rtk init -g --opencode for OpenCode)`);
+}

package/scripts/build-opencode-bundle.mjs

@@ -0,0 +1,178 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  normalizeRelativePath,
+  listDeclaredFiles,
+  validateDeclaredPath,
+} from "./lib/bundle-helpers.mjs";
+
+const repoRoot = resolve(import.meta.dirname, "..");
+const defaultManifestPath = resolve(repoRoot, "opencode/arcs/bundle-runtime.json");
+const defaultOutputRoot = resolve(repoRoot, "opencode/arcs");
+// Files that are repo-authored and must not be pruned. The repo bundle
+// directory IS the source of truth — there is no external mirror.
+const preservedOutputFiles = new Set([
+  "manifest.json",
+  "bundle-runtime.json",
+  ".opencode/plugins/arcs.js",
+  // ARCS-native skills (authored in this repo, no upstream source)
+  // init-project skill — ARCS-native (mirrors orchestrator INIT workflow with
+  // graphify sub-flow, typed-agent dispatch, knowledge categories).
+  "skills/init-project/SKILL.md",
+  // Caveman commit skill — adapted from https://github.com/JuliusBrussee/caveman (MIT).
+  "skills/caveman-commit/SKILL.md",
+  // Agent prompt files (repo-authored, referenced via {file:} in manifest.json)
+  "prompts/software-engineer.txt",
+  "prompts/tech-architect.txt",
+  "prompts/qa-analyst.txt",
+  "prompts/oncall-ops.txt",
+  "prompts/arcs-docs.txt",
+  "prompts/system-architect.txt",
+  "prompts/code-reviewer.txt",
+  "prompts/docs-researcher.txt",
+  "prompts/devil-advocate.txt",
+  // Orchestrator prompt files — generated from src/cli/arcs-orchestrate*.ts during
+  // bundle build (see generateOrchestratorPrompts() below). TS modules remain the
+  // canonical source; these .txt files are committed mirrors so the bundle is
+  // self-describing and all prompts live in one directory.
+  "prompts/arcs-orchestrate.txt",
+  "prompts/arcs-orchestrate-caveman.txt",
+]);
+
+function ensureParentDirectory(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+function pruneUndeclaredFiles(rootPath, allowedFiles) {
+  for (const entry of readdirSync(rootPath, { withFileTypes: true })) {
+    const entryPath = resolve(rootPath, entry.name);
+
+    if (entry.isDirectory()) {
+      pruneUndeclaredFiles(entryPath, allowedFiles);
+
+      if (readdirSync(entryPath).length === 0) {
+        rmSync(entryPath, { recursive: true, force: true });
+      }
+
+      continue;
+    }
+
+    const relativePath = normalizeRelativePath(relative(defaultOutputRootCurrent, entryPath));
+    if (!allowedFiles.has(relativePath)) {
+      rmSync(entryPath, { force: true });
+    }
+  }
+}
+
+let defaultOutputRootCurrent = defaultOutputRoot;
+
+/**
+ * Generates the ARCS Orchestrator and ARCS Caveman prompt .txt files into
+ * <outputRoot>/prompts/. The TypeScript modules src/cli/arcs-orchestrate.ts
+ * and src/cli/arcs-orchestrate-caveman.ts remain the canonical source; these
+ * .txt files are committed mirrors so the bundle is self-describing alongside
+ * the static sub-agent prompts.
+ *
+ * Requires `tsc` to have run first (dist/cli/arcs-orchestrate.js must exist).
+ * package.json's build:opencode-bundle chains `tsc` before this script.
+ */
+async function generateOrchestratorPrompts(outputRoot) {
+  const orchestrateModulePath = resolve(repoRoot, "dist/cli/arcs-orchestrate.js");
+  const cavemanModulePath = resolve(repoRoot, "dist/cli/arcs-orchestrate-caveman.js");
+
+  if (!existsSync(orchestrateModulePath) || !existsSync(cavemanModulePath)) {
+    throw new Error(
+      `Compiled orchestrator modules missing. Run \`npm run build\` before bundle build.\n` +
+        `  Expected: ${orchestrateModulePath}\n` +
+        `  Expected: ${cavemanModulePath}`,    );
+  }
+
+  const orchestrateModule = await import(pathToFileURL(orchestrateModulePath).href);
+  const cavemanModule = await import(pathToFileURL(cavemanModulePath).href);
+
+  const orchestrateText = orchestrateModule.ORCHESTRATE_PROMPT_TEXT;
+  const cavemanText = cavemanModule.ORCHESTRATE_CAVEMAN_PROMPT_TEXT;
+
+  if (typeof orchestrateText !== "string" || orchestrateText.length === 0) {
+    throw new Error("ORCHESTRATE_PROMPT_TEXT not exported as non-empty string");
+  }
+  if (typeof cavemanText !== "string" || cavemanText.length === 0) {
+    throw new Error("ORCHESTRATE_CAVEMAN_PROMPT_TEXT not exported as non-empty string");
+  }
+
+  const promptsDir = resolve(outputRoot, "prompts");
+  mkdirSync(promptsDir, { recursive: true });
+
+  const orchestratePath = resolve(promptsDir, "arcs-orchestrate.txt");
+  const cavemanPath = resolve(promptsDir, "arcs-orchestrate-caveman.txt");
+
+  // Banner prepended to every generated prompt file. Uses HTML comment syntax
+  // so it's invisible when rendered as markdown but obvious to anyone opening
+  // the .txt directly. LLMs treat HTML comments as out-of-band metadata, so
+  // the banner does not pollute the prompt's actionable instructions.
+  const banner = (sourceFile) =>
+    `<!--\n` +
+    `  AUTO-GENERATED — DO NOT EDIT.\n` +
+    `  Source of truth: ${sourceFile}\n` +
+    `  Regenerate: npm run build:opencode-bundle\n` +
+    `  Edits to this file will be overwritten on the next build.\n` +
+    `-->\n\n`;
+
+  writeFileSync(
+    orchestratePath,
+    `${banner("src/cli/arcs-orchestrate.ts")}${orchestrateText}\n`,
+    "utf-8",
+  );
+  writeFileSync(
+    cavemanPath,
+    `${banner("src/cli/arcs-orchestrate-caveman.ts")}${cavemanText}\n`,
+    "utf-8",
+  );
+}
+
+async function main() {
+  const manifestPath = process.env.ARCS_BUNDLE_RUNTIME_MANIFEST
+    ? resolve(repoRoot, process.env.ARCS_BUNDLE_RUNTIME_MANIFEST)
+    : defaultManifestPath;
+  const runtimeManifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  const outputRoot = process.env.ARCS_BUNDLE_OUTPUT_ROOT
+    ? resolve(repoRoot, process.env.ARCS_BUNDLE_OUTPUT_ROOT)
+    : defaultOutputRoot;
+
+  const declaredFiles = listDeclaredFiles(runtimeManifest);
+  const allowedOutputFiles = new Set([
+    ...declaredFiles.map((entry) => entry.declaredPath),
+    ...preservedOutputFiles,
+  ]);
+
+  defaultOutputRootCurrent = outputRoot;
+
+  // Validate that every manifest-declared file already exists in the bundle.
+  // The bundle directory IS the source of truth — files are authored here,
+  // not copied from anywhere external.
+  for (const { declaredPath, validationRoot } of declaredFiles) {
+    const relativePath = validateDeclaredPath(declaredPath, outputRoot, validationRoot);
+    const outputPath = resolve(outputRoot, relativePath);
+    if (!existsSync(outputPath)) {
+      throw new Error(`Missing declared bundle file: ${relativePath} (${outputPath})`);
+    }
+    ensureParentDirectory(outputPath);
+  }
+
+  mkdirSync(outputRoot, { recursive: true });
+  pruneUndeclaredFiles(outputRoot, allowedOutputFiles);
+
+  // Generate orchestrator prompt mirrors after prune so they always end up
+  // on disk fresh from the canonical TS sources.
+  await generateOrchestratorPrompts(outputRoot);
+}
+
+try {
+  await main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}

package/scripts/deploy-opencode-bundle.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+// Deploy opencode ARCS bundle bundle from repo to user config.
+//
+// Direction: repo → config ONLY. Never writes config → repo.
+//
+// Env vars:
+//   DEPLOY_BUNDLE_ROOT  — override bundle root (default: opencode/arcs)
+//   DEPLOY_CONFIG_ROOT  — override config root (default: ~/.config/opencode)
+//   DEPLOY_DRY_RUN      — "false" to actually copy; anything else = dry-run (default: dry-run)
+//
+// Outputs JSON to stdout: DeployResult
+// Exit code: 0 on success, 1 on error.
+
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, relative, resolve } from "node:path";
+
+const repoRoot = resolve(import.meta.dirname, "..");
+const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
+const defaultConfigRoot = resolve(homedir(), ".config/opencode");
+
+const bundleRoot = process.env.DEPLOY_BUNDLE_ROOT
+  ? resolve(repoRoot, process.env.DEPLOY_BUNDLE_ROOT)
+  : defaultBundleRoot;
+const configRoot = process.env.DEPLOY_CONFIG_ROOT
+  ? resolve(repoRoot, process.env.DEPLOY_CONFIG_ROOT)
+  : defaultConfigRoot;
+// Dry-run by default. Only DEPLOY_DRY_RUN=false (exact string) triggers real writes.
+const dryRun = process.env.DEPLOY_DRY_RUN !== "false";
+
+function listAllFiles(rootPath, currentPath = rootPath) {
+  if (!existsSync(currentPath)) return [];
+  const entries = readdirSync(currentPath, { withFileTypes: true });
+  return entries.flatMap((entry) => {
+    const entryPath = resolve(currentPath, entry.name);
+    if (entry.isDirectory()) return listAllFiles(rootPath, entryPath);
+    return [relative(rootPath, entryPath).replace(/\\/g, "/")];
+  });
+}
+
+function ensureParentDir(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+async function main() {
+  const manifestPath = resolve(bundleRoot, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`manifest.json not found at ${manifestPath}`);
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+
+  // Build mapping: config-relative path → bundle-absolute path
+  const deployMap = new Map();
+
+  // Skills: bundle skills/<name>/<file> → config skills/arcs/<name>/<file>
+  const skillsSourceDir = resolve(bundleRoot, manifest.skills.source);
+  if (existsSync(skillsSourceDir)) {
+    const skillFiles = listAllFiles(skillsSourceDir);
+    for (const file of skillFiles) {
+      const configRelative = `${manifest.skills.destination}/${file}`;
+      const bundleAbsolute = resolve(skillsSourceDir, file);
+      deployMap.set(configRelative, bundleAbsolute);
+    }
+  }
+
+  // Plugin
+  if (manifest.plugin && manifest.plugin.source) {
+    const pluginSource = resolve(bundleRoot, manifest.plugin.source);
+    if (existsSync(pluginSource)) {
+      deployMap.set(manifest.plugin.destination, pluginSource);
+    }
+  }
+
+  // Agents (sub-agent prompts) — bundle prompts/<file> → config prompts/<file>
+  for (const agent of manifest.agents ?? []) {
+    const agentSource = resolve(bundleRoot, agent.source);
+    if (existsSync(agentSource)) {
+      deployMap.set(agent.destination, agentSource);
+    }
+  }
+
+  // Pass 1: Determine file states (detection only — no writes yet)
+  const filesAdded = [];
+  const filesChanged = [];
+  const filesUnchanged = [];
+  let restartRequired = false;
+
+  for (const [configRelative, bundleAbsolute] of deployMap) {
+    const configAbsolute = resolve(configRoot, configRelative);
+    const sourceContent = readFileSync(bundleAbsolute, "utf-8");
+
+    const isNew = !existsSync(configAbsolute);
+    const isChanged =
+      !isNew && readFileSync(configAbsolute, "utf-8") !== sourceContent;
+
+    if (isNew) {
+      filesAdded.push(configRelative);
+    } else if (isChanged) {
+      filesChanged.push(configRelative);
+    } else {
+      filesUnchanged.push(configRelative);
+    }
+
+    // Plugin change/add → restart required
+    if (configRelative === manifest.plugin?.destination && (isNew || isChanged)) {
+      restartRequired = true;
+    }
+  }
+
+  // Detect files to remove: files in owned paths in config that are NOT in deployMap
+  const filesRemoved = [];
+  for (const ownedPath of manifest.ownedPaths ?? []) {
+    const ownedAbsolute = resolve(configRoot, ownedPath);
+    if (!existsSync(ownedAbsolute)) continue;
+
+    // Owned path may be a file or directory
+    if (!lstatSync(ownedAbsolute).isDirectory()) {
+      if (!deployMap.has(ownedPath)) {
+        filesRemoved.push(ownedPath);
+      }
+      continue;
+    }
+
+    const existingFiles = listAllFiles(ownedAbsolute);
+    for (const file of existingFiles) {
+      const configRelative = `${ownedPath}/${file}`;
+      if (!deployMap.has(configRelative)) {
+        filesRemoved.push(configRelative);
+      }
+    }
+  }
+
+  // Pass 2: Apply writes (only when not dry-run)
+  if (!dryRun) {
+    // Clean-delete the skills directory before copying to guarantee a fresh install.
+    // Prevents residual files from renamed/removed skills surviving across deploys.
+    const skillsDest = resolve(configRoot, manifest.skills.destination);
+    if (existsSync(skillsDest)) {
+      rmSync(skillsDest, { recursive: true, force: true });
+    }
+
+    // Write all files from deployMap (recreates skills dir + copies plugin + agents)
+    for (const [configRelative, bundleAbsolute] of deployMap) {
+      const configAbsolute = resolve(configRoot, configRelative);
+      ensureParentDir(configAbsolute);
+      copyFileSync(bundleAbsolute, configAbsolute);
+    }
+
+    // Remove orphans from other owned paths (skills dir already cleared above; force: true
+    // makes this a no-op for any skills paths that were already wiped)
+    for (const fileToRemove of filesRemoved) {
+      rmSync(resolve(configRoot, fileToRemove), { force: true });
+    }
+  }
+
+  // After successful deploy, ensure arcs CLI is globally registered
+  if (!dryRun) {
+    try {
+      const { execFileSync } = await import("node:child_process");
+      const initScript = resolve(repoRoot, "scripts/arcs-init.mjs");
+      if (existsSync(initScript)) {
+        execFileSync(process.execPath, [initScript], { stdio: "pipe" });
+      }
+    } catch {
+      // Non-fatal: CLI registration is a convenience, not a requirement
+    }
+  }
+
+  const result = {
+    dryRun,
+    source: bundleRoot,
+    destination: configRoot,
+    filesAdded,
+    filesChanged,
+    filesRemoved,
+    filesUnchanged,
+    restartRequired,
+    cliRegistered: !dryRun,
+    ...(restartRequired && {
+      restartGuidance: "Plugin file changed. Restart opencode for changes to take effect.",
+    }),
+  };
+
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}

package/scripts/lib/bundle-helpers.mjs

@@ -0,0 +1,172 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+export function normalizeRelativePath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+
+export function looksWindowsAbsolute(filePath) {
+  return /^[A-Za-z]:[\\/]/.test(filePath) || /^\\\\/.test(filePath);
+}
+
+export function assertNoReservedPathSegments(candidatePath, reportedPath = candidatePath) {
+  const normalizedPath = normalizeRelativePath(candidatePath);
+
+  if (!normalizedPath || normalizedPath === ".") {
+    throw new Error(`Invalid declared runtime path: ${reportedPath}`);
+  }
+
+  if (isAbsolute(normalizedPath) || looksWindowsAbsolute(normalizedPath)) {
+    throw new Error(`Invalid declared runtime path: ${reportedPath}`);
+  }
+
+  for (const segment of normalizedPath.split("/")) {
+    if (!segment || segment === "." || segment === "..") {
+      throw new Error(`Invalid declared runtime path: ${reportedPath}`);
+    }
+  }
+
+  return normalizedPath;
+}
+
+export function assertSafeOutputPath(candidatePath, reportedPath = candidatePath) {
+  const normalizedPath = normalizeRelativePath(candidatePath);
+
+  if (!normalizedPath || normalizedPath === ".") {
+    throw new Error(`Invalid declared runtime path: ${reportedPath}`);
+  }
+
+  if (isAbsolute(normalizedPath) || looksWindowsAbsolute(normalizedPath)) {
+    throw new Error(`Invalid declared runtime path: ${reportedPath}`);
+  }
+
+  return normalizedPath;
+}
+
+export function assertPathWithinCategoryRoot(candidatePath, categoryRoot, reportedPath = candidatePath) {
+  const normalizedPath = assertSafeOutputPath(candidatePath, reportedPath);
+  const normalizedCategoryRoot = assertNoReservedPathSegments(categoryRoot, reportedPath);
+  const categoryRelativePath = normalizeRelativePath(
+    relative(normalizedCategoryRoot, normalizedPath),
+  );
+
+  if (
+    normalizedPath !== normalizedCategoryRoot &&
+    (categoryRelativePath.startsWith("../") || categoryRelativePath === "..")
+  ) {
+    throw new Error(`Invalid declared runtime path: ${reportedPath}`);
+  }
+
+  return normalizedPath;
+}
+
+export function assertTopLevelMarkdownFile(candidatePath, categoryRoot, reportedPath = candidatePath) {
+  const normalizedPath = assertPathWithinCategoryRoot(candidatePath, categoryRoot, reportedPath);
+  const normalizedCategoryRoot = assertNoReservedPathSegments(categoryRoot, reportedPath);
+  const categoryRelativePath = normalizeRelativePath(
+    relative(normalizedCategoryRoot, normalizedPath),
+  );
+
+  if (
+    !categoryRelativePath ||
+    categoryRelativePath.includes("/") ||
+    !categoryRelativePath.endsWith(".md")
+  ) {
+    throw new Error(`Invalid declared runtime path: ${reportedPath}`);
+  }
+
+  return normalizedPath;
+}
+
+export function listDeclaredFiles(runtimeManifest) {
+  const declaredFiles = [];
+
+  for (const [skillName, skillFiles] of Object.entries(runtimeManifest.skills ?? {})) {
+    for (const skillFile of skillFiles) {
+      const normalizedSkillName = normalizeRelativePath(skillName);
+      const normalizedSkillFile = normalizeRelativePath(skillFile);
+      const declaredPath = `skills/${normalizedSkillName}/${normalizedSkillFile}`;
+
+      assertNoReservedPathSegments(normalizedSkillName, declaredPath);
+      assertNoReservedPathSegments(normalizedSkillFile, declaredPath);
+      assertSafeOutputPath(declaredPath);
+
+      declaredFiles.push({
+        declaredPath,
+        validationRoot: `skills/${normalizedSkillName}`,
+      });
+    }
+  }
+
+  for (const agentFile of runtimeManifest.agents ?? []) {
+    const declaredPath = assertTopLevelMarkdownFile(
+      assertNoReservedPathSegments(normalizeRelativePath(agentFile)),
+      "agents",
+      agentFile,
+    );
+
+    declaredFiles.push({
+      declaredPath,
+      validationRoot: "agents",
+    });
+  }
+
+  for (const pluginFile of runtimeManifest.plugin ?? []) {
+    const declaredPath = assertPathWithinCategoryRoot(
+      assertNoReservedPathSegments(normalizeRelativePath(pluginFile)),
+      ".opencode/plugins",
+      pluginFile,
+    );
+
+    declaredFiles.push({
+      declaredPath,
+      validationRoot: ".opencode/plugins",
+    });
+  }
+
+  return declaredFiles;
+}
+
+export function listSourceSkillNames(sourceRoot) {
+  // DEPRECATED: source-root mirroring removed. The repo bundle directory is
+  // the source of truth. This export is retained as a no-op for any external
+  // consumer (e.g. ad-hoc scripts) and can be deleted once no callers remain.
+  void sourceRoot;
+  return [];
+}
+
+export function listSourceAgentPaths(sourceRoot) {
+  // DEPRECATED: see listSourceSkillNames.
+  void sourceRoot;
+  return [];
+}
+
+export function assertSourceParity(runtimeManifest, sourceRoot, arcsNativeSkillNames) {
+  // DEPRECATED: source-root mirroring removed. The repo bundle directory is
+  // the source of truth — there is no external mirror to assert parity with.
+  // Retained as a no-op so any external caller continues to import cleanly.
+  void runtimeManifest;
+  void sourceRoot;
+  void arcsNativeSkillNames;
+}
+
+export function validateDeclaredPath(relativePath, outputRoot, validationRoot) {
+  const normalizedPath = assertSafeOutputPath(relativePath);
+  const normalizedValidationRoot = assertSafeOutputPath(validationRoot, relativePath);
+
+  const outputPath = resolve(outputRoot, normalizedPath);
+  const outputRelativePath = normalizeRelativePath(relative(outputRoot, outputPath));
+
+  if (outputRelativePath.startsWith("../") || outputRelativePath === "..") {
+    throw new Error(`Invalid declared runtime path: ${relativePath}`);
+  }
+
+  const validationRelativePath = normalizeRelativePath(
+    relative(normalizedValidationRoot, outputRelativePath),
+  );
+
+  if (validationRelativePath.startsWith("../") || validationRelativePath === "..") {
+    throw new Error(`Invalid declared runtime path: ${relativePath}`);
+  }
+
+  return normalizedPath;
+}

package/scripts/lint-bundle.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// Bundle linter — detects drift/issues in the opencode ARCS bundle without
+// overwriting anything. The repo bundle directory is the source of truth.
+//
+// Env vars:
+//   BUNDLE_LINT_BUNDLE_ROOT  — override bundle root (default: opencode/arcs)
+//
+// Outputs JSON to stdout: { issues: [...], summary: { errors, warnings } }
+// Exit code: 0 if no errors, 1 if errors found.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+
+const repoRoot = resolve(import.meta.dirname, "..");
+const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
+
+const bundleRoot = process.env.BUNDLE_LINT_BUNDLE_ROOT
+  ? resolve(repoRoot, process.env.BUNDLE_LINT_BUNDLE_ROOT)
+  : defaultBundleRoot;
+
+// Preserved files that are repo-authored, not sourced from manifest.
+const preservedFiles = new Set([
+  "manifest.json",
+  "bundle-runtime.json",
+  ".opencode/plugins/arcs.js",
+  "skills/loop/SKILL.md",
+  "skills/caveman-commit/SKILL.md",
+  "skills/caveman-review/SKILL.md",
+  "skills/init-project/SKILL.md",
+  // Sub-agent prompt files (repo-authored, referenced from manifest.json
+  // requiredMerges, not from bundle-runtime.json's `agents` array).
+  "prompts/software-engineer.txt",
+  "prompts/tech-architect.txt",
+  "prompts/qa-analyst.txt",
+  "prompts/oncall-ops.txt",
+  "prompts/arcs-docs.txt",
+  "prompts/system-architect.txt",
+  "prompts/code-reviewer.txt",
+  "prompts/docs-researcher.txt",
+  // Orchestrator prompt files — generated from src/cli/arcs-orchestrate*.ts
+  // by build-opencode-bundle.mjs. Committed mirrors so the bundle is
+  // self-describing alongside the static sub-agent prompts.
+  "prompts/arcs-orchestrate.txt",
+  "prompts/arcs-orchestrate-caveman.txt",
+]);
+
+/** @type {Array<{severity: 'error'|'warning', kind: string, message: string, file?: string, repair?: string}>} */const issues = [];
+
+function addIssue(severity, kind, message, file, repair) {
+  const issue = { severity, kind, message };
+  if (file) issue.file = file;
+  if (repair) issue.repair = repair;
+  issues.push(issue);
+}
+
+function listAllFiles(rootPath, currentPath = rootPath) {
+  if (!existsSync(currentPath)) return [];
+  const entries = readdirSync(currentPath, { withFileTypes: true });
+  return entries.flatMap((entry) => {
+    const entryPath = resolve(currentPath, entry.name);
+    if (entry.isDirectory()) return listAllFiles(rootPath, entryPath);
+    return [relative(rootPath, entryPath).replace(/\\/g, "/")];
+  });
+}
+
+// --- Read manifest ---
+const manifestPath = resolve(bundleRoot, "bundle-runtime.json");
+if (!existsSync(manifestPath)) {
+  addIssue("error", "manifest-missing", `bundle-runtime.json not found at ${manifestPath}`);
+  output();
+}
+
+const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+
+// --- Check 1: Every manifest-declared bundled file exists ---
+const declaredFiles = new Set();
+
+for (const [skillName, skillFiles] of Object.entries(manifest.skills ?? {})) {
+  for (const skillFile of skillFiles) {
+    const relativePath = `skills/${skillName}/${skillFile}`;
+    declaredFiles.add(relativePath);
+    if (!existsSync(resolve(bundleRoot, relativePath))) {
+      addIssue(
+        "error",
+        "missing-declared-file",
+        `Manifest declares ${relativePath} but file is missing`,
+        relativePath,
+        `Run bundle build or add the file`,
+      );
+    }
+  }
+}
+
+for (const agentFile of manifest.agents ?? []) {
+  declaredFiles.add(agentFile);
+  if (!existsSync(resolve(bundleRoot, agentFile))) {
+    addIssue("error", "missing-declared-file", `Manifest declares ${agentFile} but file is missing`, agentFile);
+  }
+}
+
+for (const pluginFile of manifest.plugin ?? []) {
+  declaredFiles.add(pluginFile);
+  if (!existsSync(resolve(bundleRoot, pluginFile))) {
+    addIssue("error", "missing-declared-file", `Manifest declares ${pluginFile} but file is missing`, pluginFile);
+  }
+}
+
+// --- Check 2: No extra undeclared files in bundle ---
+const allBundleFiles = listAllFiles(bundleRoot);
+const allowedFiles = new Set([...declaredFiles, ...preservedFiles]);
+
+for (const file of allBundleFiles) {
+  if (!allowedFiles.has(file)) {
+    addIssue(
+      "warning",
+      "undeclared-file",
+      `File ${file} exists in bundle but is not declared in manifest`,
+      file,
+      `Remove the file or add it to bundle-runtime.json`,
+    );
+  }
+}
+
+// --- Check 3: Every skill includes SKILL.md ---
+for (const [skillName, skillFiles] of Object.entries(manifest.skills ?? {})) {
+  if (!skillFiles.includes("SKILL.md")) {
+    addIssue(
+      "error",
+      "skill-missing-entry",
+      `Skill "${skillName}" does not include SKILL.md in its file list`,
+      `skills/${skillName}/SKILL.md`,
+      `Add "SKILL.md" to the skill's file array in bundle-runtime.json`,
+    );
+  }
+}
+
+// --- Check 4: .mjs scripts declared should be parseable ---
+for (const [skillName, skillFiles] of Object.entries(manifest.skills ?? {})) {
+  for (const skillFile of skillFiles) {
+    if (skillFile.endsWith(".mjs")) {
+      const filePath = resolve(bundleRoot, `skills/${skillName}/${skillFile}`);
+      if (existsSync(filePath)) {
+        // Quick syntax check — try to parse as module
+        try {
+          const content = readFileSync(filePath, "utf-8");
+          // Basic check: not empty
+          if (content.trim().length === 0) {
+            addIssue(
+              "warning",
+              "empty-script",
+              `Bundled script skills/${skillName}/${skillFile} is empty`,
+              `skills/${skillName}/${skillFile}`,
+            );
+          }
+        } catch (err) {
+          addIssue(
+            "error",
+            "unreadable-script",
+            `Cannot read bundled script: ${err.message}`,
+            `skills/${skillName}/${skillFile}`,
+          );
+        }
+      }
+    }
+  }
+}
+
+// --- Check 5: arcs-dashboard/package.json type field ---
+const dashboardPkgPath = resolve(bundleRoot, "skills/arcs-dashboard/package.json");
+if (existsSync(dashboardPkgPath)) {
+  try {
+    const pkg = JSON.parse(readFileSync(dashboardPkgPath, "utf-8"));
+    if (!pkg.type) {
+      addIssue(
+        "error",
+        "package-json-invalid",
+        `arcs-dashboard package.json missing "type" field (expected "commonjs")`,
+        "skills/arcs-dashboard/package.json",
+        `Add "type": "commonjs" to the package.json`,
+      );
+    }
+  } catch (err) {
+    addIssue(
+      "error",
+      "package-json-invalid",
+      `arcs-dashboard package.json is not valid JSON: ${err.message}`,
+      "skills/arcs-dashboard/package.json",
+    );
+  }
+}
+
+// --- Check 6: REMOVED. The repo bundle is the source of truth — there is no
+// external "config root" mirror to compare against. Drift detection against
+// ~/.config/opencode/ has been deleted; use `arcs deploy-superpowers --dry-run`
+// if you want to preview what would change in the deployment target.
+
+function output() {
+  const errors = issues.filter((i) => i.severity === "error").length;
+  const warnings = issues.filter((i) => i.severity === "warning").length;
+  const result = { issues, summary: { errors, warnings } };
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exitCode = errors > 0 ? 1 : 0;
+  process.exit();
+}
+
+output();