@bonesofspring/ai-rules 0.2.26 → 0.2.28

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
@@ -254,6 +255,43 @@ function seedConventions(presetTeamSrc, cwd) {
   return true;
 }
 
+/**
+ * Seed `.ai.local/rules-library/` from `presets/<opt>/<stack>/ai-local/rules-library/`.
+ * Opt-in discipline rules the consumer enables by moving a file into
+ * `.ai.local/rules/` (consumer-owned; never overwritten).
+ *
+ * Refuses symlinks anywhere along the source path so `rmSync` and copy
+ * can't escape the install scope.
+ */
+function seedAiLocalRules(presetTeamSrc, cwd) {
+  if (!presetTeamSrc) {
+    return false;
+  }
+  const libraryDir = path.join(path.dirname(presetTeamSrc), 'ai-local', 'rules-library');
+  if (!fs.existsSync(libraryDir) || !fs.statSync(libraryDir).isDirectory()) {
+    return false;
+  }
+  const destDir = path.join(cwd, '.ai.local', 'rules-library');
+  assertSafeDest(cwd, destDir, '.ai.local/rules-library');
+  let copied = 0;
+  let skipped = 0;
+  for (const entry of fs.readdirSync(libraryDir)) {
+    if (!entry.endsWith('.md')) continue;
+    const src = path.join(libraryDir, entry);
+    const dest = path.join(destDir, entry);
+    if (fs.existsSync(dest)) {
+      skipped += 1;
+      continue;
+    }
+    copyFile(src, dest);
+    copied += 1;
+  }
+  if (copied > 0) {
+    console.log(`Seeded .ai.local/rules-library/ (${copied} rules; ${skipped} already present)`);
+  }
+  return copied > 0;
+}
+
 /**
  * Resolve a legacy `.<tool>/team` directory, refusing symlinks and anything whose
  * real path escapes the resolved `cwd`. `rmSync` through a link would delete the
@@ -391,10 +429,14 @@ function migrateLegacyTeams(cwd, dest) {
 
 /**
  * @param {{ cwd: string, presetTeamSrc?: string }} options
- * @returns {{ created: boolean, migrated: boolean, refreshed: boolean, conventionsSeeded: boolean }}
+ * @returns {{ created: boolean, migrated: boolean, refreshed: boolean, conventionsSeeded: boolean, rulesLibrarySeeded: boolean }}
  */
 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) =>
@@ -403,13 +445,14 @@ function seedAiLocalTeam({ cwd, presetTeamSrc }) {
 
   if (!destExisted && !hadLegacy && (!presetTeamSrc || !fs.existsSync(presetTeamSrc))) {
     console.log('Skipped .ai.local/team seed (preset team/ missing)');
-    return { created: false, migrated: false, refreshed: false, conventionsSeeded: false };
+    return { created: false, migrated: false, refreshed: false, conventionsSeeded: false, rulesLibrarySeeded: false };
   }
 
   fs.mkdirSync(dest, { recursive: true });
   const migrated = migrateLegacyTeams(cwd, dest);
   copyTemplates(presetTeamSrc, dest);
   const conventionsSeeded = seedConventions(presetTeamSrc, cwd);
+  const rulesLibrarySeeded = seedAiLocalRules(presetTeamSrc, cwd);
 
   if (migrated) {
     console.log('Migrated legacy .{tool}/team → .ai.local/team');
@@ -417,7 +460,7 @@ function seedAiLocalTeam({ cwd, presetTeamSrc }) {
 
   if (!destExisted && !hadLegacy) {
     console.log('Seeded .ai.local/team/');
-    return { created: true, migrated: false, refreshed: false, conventionsSeeded };
+    return { created: true, migrated: false, refreshed: false, conventionsSeeded, rulesLibrarySeeded };
   }
 
   if (destHasSlugs || destExisted) {
@@ -426,10 +469,10 @@ function seedAiLocalTeam({ cwd, presetTeamSrc }) {
         ? 'Refreshed .ai.local/team templates (tasks preserved)'
         : 'Refreshed .ai.local/team (no consumer task slugs)',
     );
-    return { created: false, migrated, refreshed: true, conventionsSeeded };
+    return { created: false, migrated, refreshed: true, conventionsSeeded, rulesLibrarySeeded };
   }
 
-  return { created: false, migrated, refreshed: false, conventionsSeeded };
+  return { created: false, migrated, refreshed: false, conventionsSeeded, rulesLibrarySeeded };
 }
 
 module.exports = { seedAiLocalTeam, destTeamRoot };

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(

package/bin/opencode-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('.opencode', '.ai-rules-install.json');
 const CONTRACT_REL = path.join('presets', 'opencode', 'platform-contract.json');
@@ -189,6 +190,57 @@ function mergeServerEntry(existingEntry, presetEntry) {
   return merged;
 }
 
+function stringList(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+
+function mergeInstructionList(existingInstructions, presetInstructions) {
+  const presetList = stringList(presetInstructions);
+  if (existingInstructions == null) {
+    return presetList.length > 0 ? presetList : undefined;
+  }
+  if (!Array.isArray(existingInstructions)) {
+    return existingInstructions;
+  }
+  const merged = [];
+  const seen = new Set();
+  for (const item of existingInstructions) {
+    if (typeof item === 'string') {
+      if (seen.has(item)) continue;
+      seen.add(item);
+    }
+    merged.push(item);
+  }
+  for (const item of presetList) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    merged.push(item);
+  }
+  return merged;
+}
+
+function mergePermission(existingPermission, presetPermission) {
+  const presetPerm = isPlainObject(presetPermission) ? presetPermission : null;
+  const presetBash = presetPerm && isPlainObject(presetPerm.bash) ? presetPerm.bash : null;
+  if (existingPermission == null) {
+    if (!presetPerm) return undefined;
+    return presetBash ? { ...presetPerm, bash: { ...presetBash } } : { ...presetPerm };
+  }
+  if (!isPlainObject(existingPermission) || !presetBash) {
+    return existingPermission;
+  }
+  const merged = { ...existingPermission };
+  if (merged.bash == null) {
+    merged.bash = { ...presetBash };
+    return merged;
+  }
+  if (!isPlainObject(merged.bash)) {
+    return merged;
+  }
+  merged.bash = { ...presetBash, ...merged.bash };
+  return merged;
+}
+
 function mergeOpencodeConfig(presetObj, existingObj) {
   const preset = isPlainObject(presetObj) ? presetObj : {};
   const existing = isPlainObject(existingObj) ? existingObj : {};
@@ -206,6 +258,13 @@ function mergeOpencodeConfig(presetObj, existingObj) {
     merged.$schema = preset.$schema;
   }
   merged.mcp = mergedMcp;
+  // Re-init re-asserts preset instruction paths and missing bash keys so an
+  // upgrade is picked up. Consumer extras and same-key bash overrides stay.
+  // A non-array `instructions` or non-object `permission` is left untouched.
+  const instructions = mergeInstructionList(merged.instructions, preset.instructions);
+  if (instructions !== undefined) merged.instructions = instructions;
+  const permission = mergePermission(merged.permission, preset.permission);
+  if (permission !== undefined) merged.permission = permission;
   return { merged, extrasKept, existingServersInvalid };
 }
 
@@ -316,6 +375,13 @@ function cmdInitOpencode({ preset, cwdOption, helpers }) {
   }
 
   const managedRoot = path.join(cwd, contract.managedRoot);
+  // Refuse to install through a symlinked `.opencode` (or any symlinked ancestor).
+  try {
+    assertSafeDest(cwd, managedRoot, contract.managedRoot);
+  } catch (err) {
+    console.error(`init failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
   const rootExisted = fs.existsSync(managedRoot);
   const docsSpecsDir = path.join(cwd, 'docs', 'specs');
   const docsSpecsExisted = fs.existsSync(docsSpecsDir);
@@ -472,8 +538,8 @@ function removeEmptyDirs(dir) {
 function cmdCleanOpencode({ 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 opencode: missing .opencode/.ai-rules-install.json; nothing removed (fail-safe).',
     );
@@ -500,10 +566,19 @@ function cmdCleanOpencode({ 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, '.opencode')) {
       console.log('Kept shared AGENTS.md (another tool install is still present)');
@@ -518,20 +593,26 @@ function cmdCleanOpencode({ cwdOption, helpers }) {
   }
 
   if (preserved.includes('opencode.json') && Array.isArray(manifest.shippedMcpServerIds)) {
-    stripShippedMcp(path.join(cwd, 'opencode.json'), manifest.shippedMcpServerIds);
+    const mcpAbs = resolveManagedPath(cwd, 'opencode.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, '.opencode'));
-  if (
-    fs.existsSync(path.join(cwd, '.opencode')) &&
-    fs.readdirSync(path.join(cwd, '.opencode')).length === 0
-  ) {
-    fs.rmdirSync(path.join(cwd, '.opencode'));
+  const managedRoot = resolveManagedPath(cwd, '.opencode');
+  if (managedRoot) {
+    removeEmptyDirs(managedRoot);
+    if (fs.existsSync(managedRoot) && fs.readdirSync(managedRoot).length === 0) {
+      fs.rmdirSync(managedRoot);
+    }
   }
 
   console.log(

package/docs/LOCAL-OVERLAY.md

@@ -0,0 +1,186 @@
+# Local overlay (`.ai.local/`)
+
+Consumer-owned rules with priority over `@bonesofspring/ai-rules` presets. Works for **Cursor**, **Claude Code**, **Mavis**, and **OpenCode** from the same files.
+
+## TL;DR
+
+Put a `.ai.local/` directory in your repo. Write rules as plain markdown. The `ai-local-overlay` preset rule (installed by `init`) tells the model to read and apply your files **with priority** over preset rules.
+
+```text
+.ai.local/
+├── rules/
+│   ├── our-stack.md        # applied like a rule
+│   └── testing-policy.md   # applied like a rule
+├── conventions.md          # living gotchas (highest priority)
+└── team/                   # shared agent-team pipeline artifacts (not rules)
+    ├── README.md
+    ├── fixtures/
+    └── tasks/<slug>/
+```
+
+No IDE config, no `@include`, no codegen. Same files work in Cursor, Claude Code, Mavis, and OpenCode.
+
+## How it works
+
+1. `init cursor|claude|mavis|opencode --preset <stack>` (or `init multi`) installs `ai-local-overlay`. Cursor: `alwaysApply: true`. Claude: `paths:` on `**/.ai.local/**`. Mavis/OpenCode: listed as a root-entry rule in `AGENTS.md` / `.mavis/AGENTS.md` / `.opencode/AGENTS.md`.
+2. On session start the rule asks the model to probe `.ai.local/` and read every file under `rules/` and `conventions.md`. Do **not** load `team/**` as rules — that tree is the shared `/task` pipeline (Cursor, Claude, Mavis, and OpenCode). `team/` lives only at the **repo root** `.ai.local/team/`, not in nested package overlays.
+3. If a local rule conflicts with a preset rule, **the local rule wins**.
+4. **Deeper wins** in monorepos: walk `packages/*/.ai.local/` and apply all levels; the model treats the deepest one as the most recent guidance.
+
+## How to write `.ai.local/rules/*.md`
+
+One file = one rule. Plain markdown. **No YAML frontmatter** — the format is shared across IDEs, so each file uses a tiny markdown header for scoping.
+
+### Skeleton
+
+```markdown
+# <Short title>
+
+<One-paragraph summary of what this rule is for.>
+
+## When to apply
+
+<globs or "always-on">
+
+## Body
+
+<The actual rule. Same style as `packages/ai-rules/presets/_shared/core/quality/*.md`: short sections, bullets, code examples.>
+
+## Why
+
+<Optional: link to an ADR, issue, or one-line rationale.>
+```
+
+### `## When to apply` — the only meta you need
+
+| You want | Write |
+|---|---|
+| Only on matching files | `globs: app/src/api/**` |
+| On matching files in multiple folders | `globs: app/src/api/**, app/src/types/api/**` |
+| Always (until the context gets crowded) | `glob: always` |
+| Replace a preset rule entirely | `glob: <same as preset>`, body says "use this instead of <preset rule>" |
+| Disable a preset rule | `glob: <same as preset>`, body contains `override: kill <preset-rule-name>` |
+
+Lines before `## Body` are removed automatically by the model and used as scope. Everything from `## Body` onward is the rule body.
+
+### What to put in the body
+
+- **Start with an imperative opening line.** Models comply better with explicit "do this" than with descriptive prose. Use one of:
+  - `Apply this rule on every turn.`
+  - `Never do X when Y.`
+  - `When X, always do Y.`
+- Match the style of preset rules: short sections, bullets, code examples.
+- Cite the preset rule you're overriding (e.g. "supersedes `code-quality-and-refactoring#principles`").
+- Keep it under ~120 lines. If it grows, split into multiple files.
+- Avoid `any` and unverifiable third-party API references — same discipline as preset rules.
+
+### Mandatory patterns (recommended)
+
+If your rule is **always-on** (most local rules are), use this header verbatim so the model treats it as mandatory:
+
+```markdown
+# <Short title>
+
+**Apply this rule on every turn. Do not skip.**
+
+## When to apply
+
+glob: always
+
+## Body
+
+<rule>
+```
+
+The combination of:
+- imperative first paragraph
+- `glob: always`
+- explicit "do not skip"
+
+gets the highest compliance in practice. If the rule is **on-demand**, replace `glob: always` with `globs: <comma-separated globs>` and keep the imperative opening.
+
+### Worked example
+
+`.ai.local/rules/our-monorepo.md`:
+
+```markdown
+# Our monorepo layout
+
+**Apply this rule on every turn when working in `apps/` or `packages/`.**
+
+This repo is a pnpm + Turbo monorepo. Apps live in `apps/*`, shared packages in `packages/*`.
+
+## When to apply
+
+globs: apps/**/*, packages/**/*
+
+## Body
+
+- Use workspace protocol (`workspace:*`) for cross-package dependencies.
+- Do not import from `apps/*` into `packages/*` — packages are leaf-level.
+- Tests: each package owns its own runner; never run `pnpm test` at the root.
+- Migration scripts live in `scripts/migrations/` and must be idempotent.
+
+## Why
+
+Decision: monorepo split (ADR-0042). The "apps vs packages" boundary is enforced by ESLint, not by folder names alone.
+```
+
+## How to write `.ai.local/conventions.md`
+
+A single markdown file (no header conventions). Three sections, in this order:
+
+```markdown
+# Local conventions
+
+## Gotchas
+
+- <One bullet per non-obvious trap.>
+
+## Patterns
+
+- <Local patterns beyond the preset's `reference-features.md`.>
+
+## Decisions
+
+- <Short links to ADRs / product choices that affect code.>
+```
+
+This is the **upgrade path** of the old per-tool `.cursor/team/conventions.md` (and Claude/Mavis/OpenCode twins). If both exist, `.ai.local/conventions.md` wins. Pipeline task slugs live in `.ai.local/team/`, not in `conventions.md`.
+
+### Migration backups
+
+When `init` relocates a legacy per-tool `team/` directory it copies every entry to `.ai.local/.rollback/legacy-team-<timestamp>/<tool>/` before removing the original. That directory ships its own `.gitignore`, so backups never reach a commit and your root `.gitignore` is left alone.
+
+Backups are not pruned automatically. They do not accumulate on their own — once a legacy directory has been drained, later `init` runs find only the pointer `README.md` and back nothing up — but if you repeatedly re-create legacy `team/` directories you will collect one stamped directory per migration. Delete `.ai.local/.rollback/` by hand once you have confirmed the move.
+
+## Monorepos
+
+Drop `.ai.local/` at any nesting depth. The model walks from root to leaf and applies all levels; deeper wins.
+
+```text
+.ai.local/                                # global: applies everywhere
+packages/web/.ai.local/                   # override: only for `packages/web`
+packages/worker/.ai.local/                # override: only for the worker
+```
+
+If the same rule name appears in two levels, the deeper one wins.
+
+## Limitations
+
+- Cursor, Claude, Mavis, and OpenCode do **not** natively read `.ai.local/`. The `ai-local-overlay` rule makes the model do it. Reliability is high but not 100%.
+- Changes to `.ai.local/` mid-session require a session restart.
+- "Priority" is **contextual**, not enforced. If the model already internalized a preset rule, the local rule may not fully override it.
+- Local rules consume your context window. Keep them tight.
+
+## When to upgrade to a preset change
+
+If you find yourself writing the same `.ai.local` rule across multiple repos, **propose it as a preset rule** in `packages/ai-rules/presets/_shared/core/` (or stack-specific). Local overlay is for repo-specific overrides, not for re-distributing preset rules.
+
+## See also
+
+- `packages/ai-rules/presets/cursor/next/rules/ai-local-overlay.mdc`
+- `packages/ai-rules/presets/claude/next/rules/tooling-and-review/ai-local-overlay.md`
+- `packages/ai-rules/presets/mavis/next/rules/ai-local-overlay.md`
+- `packages/ai-rules/presets/opencode/next/rules/ai-local-overlay.md`
+- `packages/ai-rules/docs/PRESET-CONTRIBUTION.md` — for contributing to the preset itself