@bonesofspring/ai-rules 0.2.26 → 0.2.27

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+### Over-abstraction guardrails + aligned always-on budget
+
+- **Shared core** `quality/code-quality-and-refactoring` gains an **Over-abstraction guardrails** section: no unnecessary constants, no invented one-off utilities (Rule of Three), decompose over conditionals. Propagated to all 10 stacks (Cursor + Claude; Mavis / OpenCode regenerated).
+- **UI rules** add a **Conditional rendering** section (decompose branches into child components, early returns for loading/empty/error, no nested ternaries): `react-ui` (next, with Incorrect/Correct pair), `vue-ui` (nuxt), `svelte-ui` (svelte), `compose-ui` (android-kotlin), `swiftui-ui` (ios-swift). Backend stacks get the stack-agnostic bullet from shared core.
+- **Token budget raised and aligned** across platforms: Cursor / Claude / Mavis / OpenCode always-on count is now **3–5** (was Cursor ≤4, Claude exactly 3, Mavis/OpenCode ≤4); session-start body cap is **200** lines (stretch **170**) and combined Mavis/OpenCode entry cap is **200** nonempty lines (was 140/170). Enforced by `check-preset-token-budget.sh`, `check-{mavis,opencode}-token-budget.mjs`, `test-{mavis,opencode}-context-budget.mjs`; policy in `preset-token-budget` / `preset-pr-checklist`, `docs/PRESET-CONTRIBUTION.md`, and every `build-verifier` / `rules/README.md`.
+- Consumers: re-run `npx @bonesofspring/ai-rules init <tool|multi> --preset <stack>` to pick up the new rule bodies and policy text.
+
 ### Shared `.ai.local/team/` pipelines (breaking)
 
 - `/task` artifacts (`pipeline.json`, `status.json`, `metrics.json`, receipts) now live at **`.ai.local/team/tasks/<slug>/`**, shared across Cursor, Claude, Mavis, and OpenCode (including `init multi`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Volchenkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -46,7 +46,7 @@ npx @bonesofspring/ai-rules init multi --preset nuxt
 
 Help: `ai-rules --help`.
 
-Skills of note: `write-adr` (all); `spec-authoring` / `/spec-start`; `mockup-review` and `ux-design` on UI stacks; `react-performance` (next), `vue-performance` (nuxt), `svelte-performance` (svelte).
+Skills of note: `write-adr` (all except `mcp-ts`); `spec-authoring` / `/spec-start`; `mockup-review` and `ux-design` on UI stacks; `react-performance` (next), `vue-performance` (nuxt), `svelte-performance` (svelte).
 
 ## Product specs and OpenSpec
 

package/bin/cli.js

@@ -2,11 +2,13 @@
 /**
  * @bonesofspring/ai-rules CLI
  */
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { cmdInitMavis, cmdCleanMavis } = require('./mavis-install');
 const { cmdInitOpencode, cmdCleanOpencode } = require('./opencode-install');
 const { seedAiLocalTeam } = require('./lib/seed-ai-local-team');
+const { assertSafeDest, resolveManagedPath } = require('./lib/safe-path');
 
 /** Single path segment: letters, digits, dot, underscore, hyphen; no separators or "..". */
 const PRESET_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
@@ -147,7 +149,7 @@ function parseArgs(argv) {
     }
     if (a === '--preset') {
       const value = argv[i + 1];
-      if (value === undefined || value.startsWith('-')) {
+      if (value === undefined || value === '' || value.startsWith('-')) {
         args.presetError =
           'Missing value for --preset (use --preset <name> or --preset=<name>)';
         continue;
@@ -169,6 +171,10 @@ function parseArgs(argv) {
       args.help = true;
       continue;
     }
+    if (a.startsWith('-') && a !== '-') {
+      args.unknownOption = a;
+      continue;
+    }
     args._.push(a);
   }
   return args;
@@ -202,6 +208,9 @@ function normalizeInitClean(parsed) {
     }
   }
 
+  if (command === 'init' && parsed.preset === undefined && positional[2] === '') {
+    parsed.presetError = 'Missing value for --preset (use --preset <name> or --preset=<name>)';
+  }
   const preset = parsed.preset || presetFromPositional;
   return { command, tool, preset };
 }
@@ -240,6 +249,14 @@ function ownKeys(object) {
   return Object.keys(object).filter((key) => Object.hasOwn(object, key));
 }
 
+/** Write via a temp file + rename so an interrupted write cannot corrupt the destination. */
+function writeFileAtomic(destAbs, content) {
+  fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+  const tmp = `${destAbs}.ai-rules-tmp`;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, destAbs);
+}
+
 function backupMcpFile(mcpDestAbs) {
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
   const bak = `${mcpDestAbs}.bak.${stamp}`;
@@ -249,7 +266,9 @@ function backupMcpFile(mcpDestAbs) {
 
 function replaceMcpWithPreset(mcpFrom, mcpDestAbs, reason) {
   const bak = backupMcpFile(mcpDestAbs);
-  fs.copyFileSync(mcpFrom, mcpDestAbs);
+  const tmp = `${mcpDestAbs}.ai-rules-tmp`;
+  fs.copyFileSync(mcpFrom, tmp);
+  fs.renameSync(tmp, mcpDestAbs);
   console.warn(`${reason}; backed up to ${bak} and replaced with the preset file.`);
 }
 
@@ -327,8 +346,7 @@ function installMcpJson(mcpFrom, mcpDestAbs, destLabel) {
       `Existing ${destLabel} mcpServers was not a JSON object; backed up to ${bak} and merging as empty extras.`,
     );
   }
-  fs.mkdirSync(path.dirname(mcpDestAbs), { recursive: true });
-  fs.writeFileSync(mcpDestAbs, `${JSON.stringify(merged, null, 2)}\n`);
+  writeFileAtomic(mcpDestAbs, `${JSON.stringify(merged, null, 2)}\n`);
   if (extrasKept.length > 0) {
     console.log(
       `Merged ${path.basename(mcpFrom)} → ${destLabel} (kept extra servers: ${extrasKept.join(', ')})`,
@@ -368,6 +386,7 @@ function seedDocsSpecsIfAbsent(packageRoot, cwd) {
     console.log('Skipped docs/specs seed (directory already exists)');
     return false;
   }
+  assertSafeDest(cwd, destRoot, 'docs/specs');
   const assetsRoot = path.join(
     packageRoot,
     'presets',
@@ -396,15 +415,90 @@ function getOptionalDirs(cfg) {
   return cfg.optionalCursorDirs || cfg.optionalClaudeDirs || [];
 }
 
-function removeDirIfExists(dir) {
-  if (fs.existsSync(dir)) {
-    fs.rmSync(dir, { recursive: true, force: true });
+function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+/** Relative (forward-slash) file paths under a directory, sorted. */
+function walkFilesUnder(root) {
+  const out = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(full);
+      } else if (entry.isFile()) {
+        out.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  if (fs.existsSync(root)) {
+    visit(root);
+  }
+  return out.sort();
+}
+
+function getPackageVersion(packageRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/** Remove empty directories bottom-up without ever traversing a symlink. */
+function removeEmptyDirsSafe(dir) {
+  if (!dir || !fs.existsSync(dir)) {
+    return;
+  }
+  let stat;
+  try {
+    stat = fs.lstatSync(dir);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    return;
+  }
+  for (const name of fs.readdirSync(dir)) {
+    removeEmptyDirsSafe(path.join(dir, name));
+  }
+  if (fs.readdirSync(dir).length === 0) {
+    fs.rmdirSync(dir);
+  }
+}
+
+/** Remove only the preset-shipped keys from an MCP config, keeping consumer extras. */
+function stripShippedMcpKeys(mcpAbs, shippedIds, rootKey) {
+  if (!fs.existsSync(mcpAbs) || shippedIds.length === 0) {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(mcpAbs, 'utf8'));
+  } catch {
+    return;
+  }
+  if (!isPlainObject(parsed) || !isPlainObject(parsed[rootKey])) {
+    return;
+  }
+  const next = { ...parsed[rootKey] };
+  for (const id of shippedIds) {
+    delete next[id];
   }
+  writeFileAtomic(mcpAbs, `${JSON.stringify({ ...parsed, [rootKey]: next }, null, 2)}\n`);
 }
 
-function removeFileIfExists(filePath) {
-  if (fs.existsSync(filePath)) {
-    fs.unlinkSync(filePath);
+function readInstallManifest(cwd, toolRoot) {
+  const manifestAbs = resolveManagedPath(cwd, `${toolRoot}/.ai-rules-install.json`);
+  if (!manifestAbs || !fs.existsSync(manifestAbs)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestAbs, 'utf8'));
+    return isPlainObject(parsed) && isPlainObject(parsed.managedFiles) ? parsed : null;
+  } catch {
+    return null;
   }
 }
 
@@ -615,19 +709,27 @@ function cmdInit(tool, preset, cwdOption) {
   const toolRoot = tool === 'cursor' ? '.cursor' : '.claude';
   const toolRootAbs = path.join(cwd, toolRoot);
 
+  // Capture existence BEFORE mkdir: rollback must only remove the tool root when
+  // this run created it, never a pre-existing consumer directory.
+  const toolRootExisted = fs.existsSync(toolRootAbs);
+  try {
+    assertSafeDest(cwd, toolRootAbs, toolRoot);
+  } catch (err) {
+    console.error(`init failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
   fs.mkdirSync(toolRootAbs, { recursive: true });
 
   let copiedSteps = 0;
-  // Track newly created paths so we can roll back on partial failure.
-  // Only deletes paths that did not exist before this run — never consumer files.
-  const toolRootExisted = fs.existsSync(toolRootAbs);
+  // Track paths that did not exist before this run so we can roll them back on
+  // partial failure. Directories are tracked before the copy so a mid-copy failure
+  // still removes the (newly created) directory and its partial contents.
   const createdPaths = new Set();
   const docsSpecsDir = path.join(cwd, 'docs', 'specs');
   const docsSpecsExisted = fs.existsSync(docsSpecsDir);
 
   const trackDir = (dir) => {
-    if (!fs.existsSync(dir)) return;
-    createdPaths.add(dir);
+    if (!fs.existsSync(dir)) createdPaths.add(dir);
   };
 
   try {
@@ -736,6 +838,83 @@ function cmdInit(tool, preset, cwdOption) {
     if (teamResult.created || teamResult.migrated || teamResult.refreshed) {
       copiedSteps++;
     }
+
+    // Write the ownership manifest so `clean` only ever deletes files this tool
+    // installed and left unchanged. Without it, clean is fail-safe (no deletions).
+    const prior = readInstallManifest(cwd, toolRoot);
+    const manifestRel = `${toolRoot}/.ai-rules-install.json`;
+    const manifestAbs = path.join(cwd, manifestRel);
+    const managedFiles = {};
+    for (const rel of walkFilesUnder(toolRootAbs)) {
+      const relFromCwd = `${toolRoot}/${rel}`;
+      if (relFromCwd === manifestRel) {
+        continue;
+      }
+      managedFiles[relFromCwd] = sha256File(path.join(toolRootAbs, rel));
+    }
+    if (cfg.mcpJsonDest) {
+      const mcpAbs = path.join(cwd, cfg.mcpJsonDest);
+      if (fs.existsSync(mcpAbs)) {
+        managedFiles[cfg.mcpJsonDest] = sha256File(mcpAbs);
+      }
+    }
+    for (const destRel of Object.values(cfg.repoRootFiles || {})) {
+      const abs = path.join(cwd, destRel);
+      if (fs.existsSync(abs)) {
+        managedFiles[destRel] = sha256File(abs);
+      }
+    }
+
+    // Prune files owned by a previous install that the preset no longer ships.
+    // Only unchanged, tool-root files are removed; shared AGENTS.md is left alone.
+    if (prior) {
+      for (const [rel, priorHash] of Object.entries(prior.managedFiles)) {
+        if (rel in managedFiles || !rel.startsWith(`${toolRoot}/`)) {
+          continue;
+        }
+        const abs = resolveManagedPath(cwd, rel);
+        if (!abs || !fs.existsSync(abs) || !fs.lstatSync(abs).isFile()) {
+          continue;
+        }
+        if (sha256File(abs) === priorHash) {
+          fs.unlinkSync(abs);
+          console.log(`Pruned stale managed file ${rel}`);
+        }
+      }
+    }
+
+    let shippedMcpServerIds = [];
+    if (cfg.mcpJsonSrc) {
+      const mcpFrom = path.join(base, cfg.mcpJsonSrc);
+      if (fs.existsSync(mcpFrom)) {
+        try {
+          const parsed = JSON.parse(fs.readFileSync(mcpFrom, 'utf8'));
+          if (isPlainObject(parsed.mcpServers)) {
+            shippedMcpServerIds = ownKeys(parsed.mcpServers);
+          }
+        } catch {
+          shippedMcpServerIds = [];
+        }
+      }
+    }
+    const managedDirectories = [cfg.rulesDir, cfg.commandsDir];
+    for (const name of getOptionalDirs(cfg)) {
+      managedDirectories.push(`${toolRoot}/${name}`);
+    }
+    const manifest = {
+      schemaVersion: 1,
+      packageVersion: getPackageVersion(packageRoot),
+      platform: tool,
+      preset: presetName,
+      installedAt: new Date().toISOString(),
+      managedFiles,
+      managedDirectories,
+      shippedMcpServerIds,
+    };
+    if (!fs.existsSync(manifestAbs)) {
+      createdPaths.add(manifestAbs);
+    }
+    writeFileAtomic(manifestAbs, `${JSON.stringify(manifest, null, 2)}\n`);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     rollbackInit(createdPaths, toolRootExisted, toolRootAbs);
@@ -813,47 +992,82 @@ function cmdClean(tool, cwdOption) {
   }
   const cwd = resolveTargetCwd(cwdOption);
   const toolRoot = tool === 'cursor' ? '.cursor' : '.claude';
-  const removedParts = [cfg.rulesDir, cfg.commandsDir];
-
-  removeDirIfExists(path.join(cwd, cfg.rulesDir));
-  removeDirIfExists(path.join(cwd, cfg.commandsDir));
-
-  const optionalDirs = getOptionalDirs(cfg);
-  for (const name of optionalDirs) {
-    removeDirIfExists(path.join(cwd, toolRoot, name));
-    removedParts.push(`${toolRoot}/${name}`);
+  const manifestRel = `${toolRoot}/.ai-rules-install.json`;
+  const manifestAbs = resolveManagedPath(cwd, manifestRel);
+  if (!manifestAbs || !fs.existsSync(manifestAbs)) {
+    console.error(`clean ${tool}: missing ${manifestRel}; nothing removed (fail-safe).`);
+    process.exit(1);
   }
-
-  if (cfg.claudeMdSrc) {
-    removeFileIfExists(path.join(cwd, toolRoot, 'CLAUDE.md'));
-    removedParts.push(`${toolRoot}/CLAUDE.md`);
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestAbs, 'utf8'));
+  } catch {
+    console.error(`clean ${tool}: invalid ${manifestRel}; nothing removed (fail-safe).`);
+    process.exit(1);
+  }
+  if (!isPlainObject(manifest) || manifest.platform !== tool || !isPlainObject(manifest.managedFiles)) {
+    console.error(`clean ${tool}: install manifest is not a ${tool} ownership record; nothing removed.`);
+    process.exit(1);
   }
 
-  if (cfg.hooksJsonSrc) {
-    removeFileIfExists(path.join(cwd, toolRoot, 'hooks.json'));
-    removedParts.push(`${toolRoot}/hooks.json`);
+  const preserved = [];
+  for (const [rel, installedHash] of Object.entries(manifest.managedFiles)) {
+    if (rel === manifestRel) {
+      continue;
+    }
+    // Never delete outside the target or through a symlink, even if the manifest says so.
+    const abs = resolveManagedPath(cwd, rel);
+    if (!abs) {
+      console.warn(`Ignored unsafe manifest entry ${rel} (outside target or symlinked)`);
+      continue;
+    }
+    if (!fs.existsSync(abs)) {
+      continue;
+    }
+    if (!fs.lstatSync(abs).isFile()) {
+      console.warn(`Ignored non-file manifest entry ${rel}`);
+      continue;
+    }
+    if (rel === 'AGENTS.md' && otherToolInstallPresent(cwd, toolRoot)) {
+      console.log('Kept shared AGENTS.md (another tool install is still present)');
+      continue;
+    }
+    if (sha256File(abs) === installedHash) {
+      fs.unlinkSync(abs);
+    } else {
+      preserved.push(rel);
+      console.warn(`Preserved modified managed file ${rel}`);
+    }
   }
 
-  if (cfg.mcpJsonDest) {
-    removeFileIfExists(path.join(cwd, cfg.mcpJsonDest));
-    removedParts.push(cfg.mcpJsonDest);
+  if (cfg.mcpJsonDest && preserved.includes(cfg.mcpJsonDest) && Array.isArray(manifest.shippedMcpServerIds)) {
+    const mcpAbs = resolveManagedPath(cwd, cfg.mcpJsonDest);
+    if (mcpAbs) {
+      stripShippedMcpKeys(mcpAbs, manifest.shippedMcpServerIds, 'mcpServers');
+    }
   }
 
-  for (const name of cfg.toolRootFiles || []) {
-    removeFileIfExists(path.join(cwd, toolRoot, name));
-    removedParts.push(`${toolRoot}/${name}`);
+  for (const dirRel of [...(manifest.managedDirectories || [])].sort((a, b) => b.length - a.length)) {
+    const dirAbs = resolveManagedPath(cwd, dirRel);
+    if (dirAbs) {
+      removeEmptyDirsSafe(dirAbs);
+    }
   }
 
-  for (const destRel of Object.values(cfg.repoRootFiles || {})) {
-    if (destRel === 'AGENTS.md' && otherToolInstallPresent(cwd, toolRoot)) {
-      console.log('Kept shared AGENTS.md (another tool install is still present)');
-      continue;
+  fs.unlinkSync(manifestAbs);
+  const toolRootAbs = resolveManagedPath(cwd, toolRoot);
+  if (toolRootAbs) {
+    removeEmptyDirsSafe(toolRootAbs);
+    if (fs.existsSync(toolRootAbs) && fs.readdirSync(toolRootAbs).length === 0) {
+      fs.rmdirSync(toolRootAbs);
     }
-    removeFileIfExists(path.join(cwd, destRel));
-    removedParts.push(destRel);
   }
 
-  console.log(`Removed ${removedParts.join(', ')} (if present)`);
+  console.log(
+    preserved.length > 0
+      ? `clean ${tool}: removed unchanged managed files; preserved ${preserved.join(', ')}`
+      : `clean ${tool}: removed unchanged managed files`,
+  );
 }
 
 function main() {
@@ -869,6 +1083,10 @@ function main() {
     process.exit(0);
   }
 
+  if (parsed.unknownOption) {
+    console.error(`Unknown option: ${parsed.unknownOption}`);
+    process.exit(1);
+  }
   if (parsed.presetError) {
     console.error(parsed.presetError);
     process.exit(1);

package/bin/lib/safe-path.js

@@ -0,0 +1,93 @@
+/**
+ * Path-safety helpers shared by the installers.
+ *
+ * Two threats are handled:
+ *   1. A destination path (from the CLI, the platform contract, or an install
+ *      manifest) escaping the resolved `--cwd` via `..` or an absolute path.
+ *   2. A destination path traversing a symlinked component, which would make a
+ *      write or `rmSync` operate outside the install scope.
+ */
+const fs = require('fs');
+const path = require('path');
+
+function lstatOrNull(target) {
+  try {
+    return fs.lstatSync(target);
+  } catch {
+    return null;
+  }
+}
+
+/** True when `target` is itself a symlink (dangling links included). */
+function isSymlink(target) {
+  const stat = lstatOrNull(target);
+  return Boolean(stat && stat.isSymbolicLink());
+}
+
+/**
+ * Resolve `target` under `cwd` and refuse it when it escapes or traverses an
+ * existing symlink. Missing components are allowed: the caller creates them.
+ *
+ * @param {string} cwd  Target project directory (already resolved).
+ * @param {string} target  Absolute or relative destination path.
+ * @param {string} label  Human-readable name used in error messages.
+ * @returns {string} The resolved absolute path.
+ */
+function assertSafeDest(cwd, target, label) {
+  const root = path.resolve(cwd);
+  const resolved = path.resolve(root, target);
+  const rel = path.relative(root, resolved);
+  if (rel === '') {
+    return resolved;
+  }
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`${label} escapes the target directory: ${resolved}`);
+  }
+  let current = root;
+  for (const part of rel.split(path.sep)) {
+    current = path.join(current, part);
+    if (isSymlink(current)) {
+      throw new Error(`${label} is a symlink; refusing to write through it: ${current}`);
+    }
+    if (!fs.existsSync(current)) {
+      break;
+    }
+  }
+  return resolved;
+}
+
+/** `mkdir -p` after {@link assertSafeDest}. */
+function safeMkdir(cwd, dir, label) {
+  assertSafeDest(cwd, dir, label);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Resolve a manifest entry (relative path) under `cwd`. Returns `null` when the
+ * entry is absolute, escapes `cwd`, is empty, or traverses a symlink.
+ */
+function resolveManagedPath(cwd, rel) {
+  if (typeof rel !== 'string' || rel === '' || path.isAbsolute(rel)) {
+    return null;
+  }
+  const root = path.resolve(cwd);
+  const resolved = path.resolve(root, rel);
+  const relative = path.relative(root, resolved);
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) {
+    return null;
+  }
+  let current = root;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    if (isSymlink(current)) {
+      return null;
+    }
+    if (!fs.existsSync(current)) {
+      break;
+    }
+  }
+  return resolved;
+}
+
+module.exports = { assertSafeDest, safeMkdir, resolveManagedPath, isSymlink, lstatOrNull };

package/bin/lib/seed-ai-local-team.js

@@ -9,6 +9,7 @@
  */
 const fs = require('fs');
 const path = require('path');
+const { assertSafeDest } = require('./safe-path');
 
 const LEGACY_TOOLS = ['cursor', 'claude', 'mavis', 'opencode'];
 const POINTER_README = `# Agent team artifacts moved
@@ -395,6 +396,10 @@ function migrateLegacyTeams(cwd, dest) {
  */
 function seedAiLocalTeam({ cwd, presetTeamSrc }) {
   const dest = destTeamRoot(cwd);
+  // `.ai.local` / `.ai.local/team` must be real paths under cwd: seeding through a
+  // symlink would write the shared runtime tree outside the install scope.
+  assertSafeDest(cwd, dest, '.ai.local/team');
+  assertSafeDest(cwd, path.join(cwd, '.ai.local', 'conventions.md'), '.ai.local/conventions.md');
   const destExisted = fs.existsSync(dest);
   const destHasSlugs = hasConsumerTaskSlugs(path.join(dest, 'tasks'));
   const hadLegacy = LEGACY_TOOLS.some((tool) =>

package/bin/mavis-install.js

@@ -4,6 +4,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const { assertSafeDest, resolveManagedPath } = require('./lib/safe-path');
 
 const MANIFEST_REL = path.join('.mavis', '.ai-rules-install.json');
 const CONTRACT_REL = path.join('presets', 'mavis', 'platform-contract.json');
@@ -221,6 +222,14 @@ function cmdInitMavis({ preset, cwdOption, helpers }) {
   }
 
   const mavisRoot = path.join(cwd, contract.managedRoot);
+  // Refuse to install through a symlinked `.mavis` (or any symlinked ancestor):
+  // writes would land outside the resolved --cwd.
+  try {
+    assertSafeDest(cwd, mavisRoot, contract.managedRoot);
+  } catch (err) {
+    console.error(`init failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
   const mavisExisted = fs.existsSync(mavisRoot);
   const docsSpecsDir = path.join(cwd, 'docs', 'specs');
   const docsSpecsExisted = fs.existsSync(docsSpecsDir);
@@ -384,8 +393,8 @@ function removeEmptyDirs(dir) {
 function cmdCleanMavis({ cwdOption, helpers }) {
   const { resolveTargetCwd, otherToolInstallPresent } = helpers;
   const cwd = resolveTargetCwd(cwdOption);
-  const manifestPath = path.join(cwd, MANIFEST_REL);
-  if (!fs.existsSync(manifestPath)) {
+  const manifestPath = resolveManagedPath(cwd, MANIFEST_REL);
+  if (!manifestPath || !fs.existsSync(manifestPath)) {
     console.error(
       'clean mavis: missing .mavis/.ai-rules-install.json; nothing removed (fail-safe).',
     );
@@ -412,10 +421,19 @@ function cmdCleanMavis({ cwdOption, helpers }) {
     if (rel === MANIFEST_REL) {
       continue;
     }
-    const abs = path.join(cwd, rel);
+    // Reject entries that escape cwd or traverse a symlink before touching disk.
+    const abs = resolveManagedPath(cwd, rel);
+    if (!abs) {
+      console.warn(`Ignored unsafe manifest entry ${rel} (outside target or symlinked)`);
+      continue;
+    }
     if (!fs.existsSync(abs)) {
       continue;
     }
+    if (!fs.lstatSync(abs).isFile()) {
+      console.warn(`Ignored non-file manifest entry ${rel}`);
+      continue;
+    }
     const current = sha256File(abs);
     if (rel === 'AGENTS.md' && otherToolInstallPresent && otherToolInstallPresent(cwd, '.mavis')) {
       console.log('Kept shared AGENTS.md (another tool install is still present)');
@@ -430,17 +448,26 @@ function cmdCleanMavis({ cwdOption, helpers }) {
   }
 
   if (preserved.includes('.mavis/mcp.json') && Array.isArray(manifest.shippedMcpServerIds)) {
-    stripShippedMcp(path.join(cwd, '.mavis', 'mcp.json'), manifest.shippedMcpServerIds);
+    const mcpAbs = resolveManagedPath(cwd, '.mavis/mcp.json');
+    if (mcpAbs) {
+      stripShippedMcp(mcpAbs, manifest.shippedMcpServerIds);
+    }
   }
 
   for (const dirRel of [...(manifest.managedDirectories || [])].sort((a, b) => b.length - a.length)) {
-    removeEmptyDirs(path.join(cwd, dirRel));
+    const dirAbs = resolveManagedPath(cwd, dirRel);
+    if (dirAbs) {
+      removeEmptyDirs(dirAbs);
+    }
   }
 
   fs.unlinkSync(manifestPath);
-  removeEmptyDirs(path.join(cwd, '.mavis'));
-  if (fs.existsSync(path.join(cwd, '.mavis')) && fs.readdirSync(path.join(cwd, '.mavis')).length === 0) {
-    fs.rmdirSync(path.join(cwd, '.mavis'));
+  const managedRoot = resolveManagedPath(cwd, '.mavis');
+  if (managedRoot) {
+    removeEmptyDirs(managedRoot);
+    if (fs.existsSync(managedRoot) && fs.readdirSync(managedRoot).length === 0) {
+      fs.rmdirSync(managedRoot);
+    }
   }
 
   console.log(