@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/scripts/check-local-overlay.sh

@@ -3,6 +3,13 @@
 # sides (Cursor `.mdc` and Claude `.md`) and that the body contains the
 # mandatory acknowledgement format.
 #
+# Also enforce the conventions-path contract: living gotchas live at
+# `.ai.local/conventions.md`; `.ai.local/team/**` is pipeline artifacts and is
+# never loaded as rules. No preset or doc may name a `team/conventions` path in
+# any form (`.ai.local/team/…`, legacy `.<tool>/team/…`, or the bare relative
+# `team/conventions.md` shorthand), and every stack must ship the
+# `ai-local/conventions.md` template the CLI seeder installs.
+#
 # Exit 0 on OK; exit 1 on any FAIL.
 set -euo pipefail
 
@@ -127,6 +134,71 @@ for stack in STACKS:
     failed += sf
     print()
 
+# --- Conventions-path contract -------------------------------------------
+# `.ai.local/conventions.md` is the living-conventions file the overlay probes.
+# `.ai.local/team/**` is the shared pipeline tree and must never be advertised
+# as the conventions location.
+print("=== conventions path ===")
+# Any `team/conventions` is wrong, in every form: the absolute
+# `.ai.local/team/conventions.md`, the legacy `.<tool>/team/conventions.md`, and
+# the bare relative `team/conventions.md` shorthand — a consumer resolves all
+# three to the pipeline-artifact tree. Legitimate mentions of that tree never
+# name a conventions file.
+#
+# The one exception is documentation that describes the *old* location as
+# history. Those are allowlisted by exact line count so new occurrences still
+# fail: bump a count only after confirming the line is upgrade-path prose, not
+# live guidance.
+FORBIDDEN = "team/conventions"
+LEGACY_DOC_ALLOWLIST = {
+    # "upgrade path of the old per-tool `.cursor/team/conventions.md`" — names
+    # the pre-migration location so a migrating consumer recognises it.
+    "docs/LOCAL-OVERLAY.md": 1,
+}
+package_root = presets.parent
+SCAN_ROOTS = (presets, package_root / "docs")
+SCAN_SUFFIXES = {".md", ".mdc", ".sh", ".json", ".mjs", ".js"}
+
+offenders: list[tuple[str, int, str]] = []
+for root in SCAN_ROOTS:
+    if not root.is_dir():
+        continue
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or path.suffix not in SCAN_SUFFIXES:
+            continue
+        text = path.read_text(encoding="utf-8", errors="ignore")
+        if FORBIDDEN not in text:
+            continue
+        rel = str(path.relative_to(package_root))
+        hits = [
+            (rel, lineno, line.strip())
+            for lineno, line in enumerate(text.splitlines(), start=1)
+            if FORBIDDEN in line
+        ]
+        allowed = LEGACY_DOC_ALLOWLIST.get(rel, 0)
+        if len(hits) == allowed:
+            continue
+        if len(hits) > allowed:
+            print(
+                f"  note: {rel} allowlists {allowed} legacy mention(s) but has {len(hits)}"
+            )
+        offenders.extend(hits)
+
+for rel, lineno, line in offenders:
+    print(f"FAIL: {rel}:{lineno} references `{FORBIDDEN}` (use `.ai.local/conventions.md`): {line}")
+failed += len(offenders)
+
+for stack in STACKS:
+    for platform in ("cursor", "claude"):
+        template = presets / platform / stack / "ai-local" / "conventions.md"
+        if not template.is_file():
+            print(f"FAIL: missing {template.relative_to(package_root)} (CLI seeds it to .ai.local/conventions.md)")
+            failed += 1
+
+if not offenders:
+    print("  OK: no `team/conventions` references in any form; conventions templates present")
+print()
+
 if failed:
     print(f"Result: FAIL ({failed} issue(s) across {sum(1 for v in stack_failed.values() if v > 0)} stack(s))")
     sys.exit(1)

package/scripts/check-mavis-adapter-map.mjs

@@ -11,6 +11,10 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  assertReleasedStacksMatchOnDisk,
+  loadReleasedStacks,
+} from './lib/generate-adapter-common.mjs';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.join(scriptDirectory, '..');
@@ -249,7 +253,7 @@ function runSelfTest() {
 }
 
 function parseArgs(argv) {
-  const options = { stack: 'next', selfTest: false };
+  const options = { stack: null, selfTest: false };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === '--self-test') {
@@ -273,12 +277,20 @@ function main() {
     }
   }
   if (!options.selfTest || exitCode === 0) {
-    const failures = checkLive(options.stack);
-    if (failures.length > 0) {
-      printFailures(`mavis/${options.stack}`, failures);
-      exitCode = 1;
-    } else {
-      console.log(`ok presets/mavis/${options.stack}/adapter-map.json`);
+    if (!options.stack) {
+      assertReleasedStacksMatchOnDisk(presetsRoot, 'mavis');
+    }
+    const stacks = options.stack
+      ? [options.stack]
+      : loadReleasedStacks(presetsRoot, 'mavis');
+    for (const stack of stacks) {
+      const failures = checkLive(stack);
+      if (failures.length > 0) {
+        printFailures(`mavis/${stack}`, failures);
+        exitCode = 1;
+      } else {
+        console.log(`ok presets/mavis/${stack}/adapter-map.json`);
+      }
     }
   }
   process.exit(exitCode);

package/scripts/check-mavis-platform-contract.mjs

@@ -70,7 +70,6 @@ const REQUIRED_DIRECTORY_SOURCES = [
   'skills',
   'commands',
   'hooks',
-  'team',
 ];
 const FORBIDDEN_PATH_RE =
   /(?:^|[\\/])\.minimax(?:[\\/]|$)|(?:^|[\\/])\.minimax-code(?:[\\/]|$)|~\/\.minimax|\$HOME\/\.minimax/i;

package/scripts/check-mavis-token-budget.mjs

@@ -10,7 +10,7 @@ import { loadReleasedMavisStacks } from './lib/discover-hooks.mjs';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const presetsRoot = path.join(scriptDirectory, '..', 'presets');
-const ROOT_ENTRY_CAP = 4;
+const ROOT_ENTRY_CAP = 5;
 
 const stacks = loadReleasedMavisStacks(presetsRoot);
 if (stacks.length === 0) {

package/scripts/check-opencode-adapter-map.mjs

@@ -11,6 +11,10 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  assertReleasedStacksMatchOnDisk,
+  loadReleasedStacks,
+} from './lib/generate-adapter-common.mjs';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.join(scriptDirectory, '..');
@@ -249,7 +253,7 @@ function runSelfTest() {
 }
 
 function parseArgs(argv) {
-  const options = { stack: 'next', selfTest: false };
+  const options = { stack: null, selfTest: false };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === '--self-test') {
@@ -273,12 +277,20 @@ function main() {
     }
   }
   if (!options.selfTest || exitCode === 0) {
-    const failures = checkLive(options.stack);
-    if (failures.length > 0) {
-      printFailures(`opencode/${options.stack}`, failures);
-      exitCode = 1;
-    } else {
-      console.log(`ok presets/opencode/${options.stack}/adapter-map.json`);
+    if (!options.stack) {
+      assertReleasedStacksMatchOnDisk(presetsRoot, 'opencode');
+    }
+    const stacks = options.stack
+      ? [options.stack]
+      : loadReleasedStacks(presetsRoot, 'opencode');
+    for (const stack of stacks) {
+      const failures = checkLive(stack);
+      if (failures.length > 0) {
+        printFailures(`opencode/${stack}`, failures);
+        exitCode = 1;
+      } else {
+        console.log(`ok presets/opencode/${stack}/adapter-map.json`);
+      }
     }
   }
   process.exit(exitCode);

package/scripts/check-opencode-platform-contract.mjs

@@ -70,7 +70,6 @@ const REQUIRED_DIRECTORY_SOURCES = [
   'skills',
   'commands',
   'hooks',
-  'team',
 ];
 const FORBIDDEN_PATH_RE =
   /(?:^|[\\/])\.config[\\/]opencode(?:[\\/]|$)|~\/\.config\/opencode|\$HOME\/\.config\/opencode|~\/\.opencode/i;

package/scripts/check-opencode-token-budget.mjs

@@ -10,7 +10,7 @@ import { loadReleasedOpencodeStacks } from './lib/discover-hooks.mjs';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const presetsRoot = path.join(scriptDirectory, '..', 'presets');
-const ROOT_ENTRY_CAP = 4;
+const ROOT_ENTRY_CAP = 5;
 
 const stacks = loadReleasedOpencodeStacks(presetsRoot);
 if (stacks.length === 0) {

package/scripts/check-preset-leakage.sh

@@ -8,6 +8,11 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
 export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
 
+if [[ ! -d "$AI_RULES_PRESETS_ROOT" ]]; then
+  echo "FAIL: presets root not found: $AI_RULES_PRESETS_ROOT"
+  exit 1
+fi
+
 python3 <<'PY'
 from __future__ import annotations
 
@@ -18,6 +23,9 @@ import sys
 from pathlib import Path
 
 presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
+if not presets.is_dir():
+    print(f"FAIL: presets root not found: {presets}")
+    sys.exit(1)
 PLATFORMS = ("cursor", "claude", "mavis", "opencode")
 STACKS = ("next", "nuxt", "svelte", "ios-swift", "android-kotlin", "go", "java", "mcp-ts", "php-hexagonal", "php-laravel")
 
@@ -494,6 +502,29 @@ for stack in released_opencode_stacks():
         elif other.is_file():
             print(f"OK: [opencode/{stack}] chain ≠ [{platform}/{stack}] chain")
 
+TEXT_SUFFIXES = {".sh", ".md", ".json", ".mjs", ".txt"}
+for platform in ("mavis", "opencode"):
+    root = presets / platform
+    if not root.is_dir():
+        continue
+    for path in root.rglob("*"):
+        if not path.is_file() or path.suffix not in TEXT_SUFFIXES:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        rel = path.relative_to(presets)
+        if "const PLATFORM = 'cursor'" in text:
+            print(f"FAIL: [{rel}] leaked const PLATFORM = 'cursor'")
+            failed += 1
+        if re.search(r"^## Frontmatter `readonly`", text, re.M):
+            print(f"FAIL: [{rel}] leftover ## Frontmatter `readonly`")
+            failed += 1
+        if re.search(r"claude-opus", text) or "[effort=" in text:
+            print(f"FAIL: [{rel}] leaked Cursor model pin (claude-opus / [effort=)")
+            failed += 1
+
 print()
 print(f"WARN count: {warned} (build-verifier packaging refs / chain skips)")
 print(

package/scripts/check-preset-structure.sh

@@ -47,6 +47,15 @@ else
 fi
 echo
 
+echo ">>> generated-drift"
+if node "$SCRIPT_DIR/check-generated-drift.mjs"; then
+  echo "<<< generated-drift: OK"
+else
+  echo "<<< generated-drift: FAIL"
+  status=1
+fi
+echo
+
 echo ">>> opencode-token-budget"
 if node "$SCRIPT_DIR/check-opencode-token-budget.mjs"; then
   echo "<<< opencode-token-budget: OK"
@@ -138,6 +147,24 @@ run_gate "chain-hook-coverage" "$SCRIPT_DIR/check-chain-hook-coverage.sh"
 run_gate "task-router-intents" "$SCRIPT_DIR/check-task-router-intents.sh"
 run_gate "i18n" "$SCRIPT_DIR/check-preset-i18n.sh" AI_RULES_I18N_FAIL=1 AI_RULES_I18N_SOFT=0
 
+echo ">>> frontmatter"
+if node "$SCRIPT_DIR/check-frontmatter.mjs"; then
+  echo "<<< frontmatter: OK"
+else
+  echo "<<< frontmatter: FAIL"
+  status=1
+fi
+echo
+
+echo ">>> probe-mavis-capabilities"
+if node "$SCRIPT_DIR/test-probe-mavis-capabilities.mjs"; then
+  echo "<<< probe-mavis-capabilities: OK"
+else
+  echo "<<< probe-mavis-capabilities: FAIL"
+  status=1
+fi
+echo
+
 echo ">>> cli-mcp-merge"
 if node "$SCRIPT_DIR/test-cli-mcp-merge.mjs"; then
   echo "<<< cli-mcp-merge: OK"

package/scripts/check-preset-token-budget.sh

@@ -16,8 +16,10 @@ from pathlib import Path
 
 presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
 STACKS = ("next", "nuxt", "svelte", "ios-swift", "android-kotlin", "go", "java", "mcp-ts", "php-hexagonal", "php-laravel")
-BODY_CAP = 140  # applied to 3-rule trios (Claude session-start, Cursor trio when len==3)
-BODY_CAP_CURSOR_4 = 170  # Cursor now allows 4 always-on (next-app-core, package-manager, code-quality, ai-local-overlay)
+MIN_ALWAYS_ON = 3  # base invariants every stack must keep session-start
+MAX_ALWAYS_ON = 5  # aligned cap for Cursor / Claude / Mavis / OpenCode always-on rules
+BODY_CAP = 200  # session-start body-sum cap (Cursor and Claude)
+BODY_CAP_STRETCH = 170  # informational stretch target
 # Slim-companion rules (UI-edit bundle, slim app-cores, slim tooling) may be
 # shorter than 15 lines **if and only if** their stem is in the allow-list and
 # body is <= MIN_SLIM_BODY_LINES. A slim rule whose body grows past this cap
@@ -134,7 +136,7 @@ failed = 0
 
 print("Preset token / session-start budget (Option A)")
 print(f"Presets: {presets}")
-print(f"Body line cap (Claude trio): {BODY_CAP}; (Cursor 4-set): {BODY_CAP_CURSOR_4}")
+print(f"Always-on count: {MIN_ALWAYS_ON}..{MAX_ALWAYS_ON}; body cap: {BODY_CAP} (stretch {BODY_CAP_STRETCH})")
 print()
 
 for stack in STACKS:
@@ -151,14 +153,13 @@ for stack in STACKS:
             print(f"FAIL: meta preset-* must not be alwaysApply: {p.name}")
             failed += 1
 
-    if len(always) not in (3, 4):
-        print(f"FAIL: Cursor alwaysApply count is {len(always)}, expected 3 or 4 (4th slot reserved for ai-local-overlay)")
+    if not (MIN_ALWAYS_ON <= len(always) <= MAX_ALWAYS_ON):
+        print(f"FAIL: Cursor alwaysApply count is {len(always)}, expected {MIN_ALWAYS_ON}..{MAX_ALWAYS_ON}")
         failed += 1
-    elif len(always) == 4:
-        # 4-set: ensure the 4th rule is ai-local-overlay (or declares itself as such).
-        extra = [p for p in always if p.stem not in {"code-quality-and-refactoring", "package-manager", "next-app-core", "nuxt-app-core", "svelte-app-core", "ios-app-core", "android-app-core", "go-app-core", "java-app-core", "mcp-ts-app-core", "php-app-core", "laravel-app-core", "architecture-boundaries", "mcp-server-boundaries"}]
-        if not any(p.stem == "ai-local-overlay" for p in always) and extra:
-            print(f"FAIL: Cursor alwaysApply=4 but no ai-local-overlay.mdc; the 4th slot is reserved for the local overlay rule")
+    elif len(always) > 3:
+        # Slots beyond the base invariants are reserved for ai-local-overlay.
+        if not any(p.stem == "ai-local-overlay" for p in always):
+            print(f"FAIL: Cursor alwaysApply={len(always)} but no ai-local-overlay.mdc; extra slots are reserved for the local overlay rule")
             failed += 1
 
     # --- Claude no-paths (excl README) ---
@@ -171,19 +172,17 @@ for stack in STACKS:
             print(f"FAIL: meta preset-* must not be session-start: {rel}")
             failed += 1
 
-    if len(session) != 3:
+    if not (MIN_ALWAYS_ON <= len(session) <= MAX_ALWAYS_ON):
         print(
             f"FAIL: Claude session-start count is {len(session)}, "
-            "expected exactly 3 (Option A excludes **/README.md)"
+            f"expected {MIN_ALWAYS_ON}..{MAX_ALWAYS_ON} (Option A excludes **/README.md)"
         )
         failed += 1
 
     # --- Body sum of intended session-start set (Cursor alwaysApply + Claude session) ---
-    # Cursor allows 3 or 4 rules (4th slot reserved for ai-local-overlay); Claude is exactly 3.
+    # Cursor and Claude allow 3..5 always-on rules; extra slots reserved for ai-local-overlay.
     for label, files in (("Cursor", always), ("Claude", session)):
-        if label == "Cursor" and len(files) not in (3, 4):
-            continue
-        if label == "Claude" and len(files) != 3:
+        if not (MIN_ALWAYS_ON <= len(files) <= MAX_ALWAYS_ON):
             continue
         total = 0
         for path in files:
@@ -193,7 +192,7 @@ for stack in STACKS:
             total += n
             name = path.name if label == "Cursor" else path.relative_to(claude_rules).as_posix()
             print(f"  {label} body lines {name}: {n}")
-        cap = BODY_CAP_CURSOR_4 if label == "Cursor" and len(always) == 4 else BODY_CAP
+        cap = BODY_CAP
         print(f"  {label} session-start body sum: {total} (cap {cap}, files={len(files)})")
         if total > cap:
             print(

package/scripts/check-shared-core-drift.sh

@@ -80,15 +80,20 @@ def consumers(stem: str) -> list[Path]:
                     out.append(path)
             except OSError:
                 continue
-    contract_path = presets / "mavis" / "platform-contract.json"
-    if contract_path.is_file():
+    # Generated platform trees are driven by their own contracts. Scan every
+    # released stack for both mavis and opencode so a core change that is not
+    # regenerated cannot slip through unnoticed.
+    for platform in ("mavis", "opencode"):
+        contract_path = presets / platform / "platform-contract.json"
+        if not contract_path.is_file():
+            continue
         try:
             contract = json.loads(contract_path.read_text(encoding="utf-8"))
             for stack in contract.get("releasedStacks") or []:
-                mavis_base = presets / "mavis" / stack
-                if not mavis_base.is_dir():
+                platform_base = presets / platform / stack
+                if not platform_base.is_dir():
                     continue
-                for path in mavis_base.rglob("*"):
+                for path in platform_base.rglob("*"):
                     if path.suffix not in {".md", ".mdc"}:
                         continue
                     try:

package/scripts/close-agent-task-human-gate.mjs

@@ -4,17 +4,17 @@
  * Prefer invoking the hook directly from /task-continue (see command Metrics section).
  *
  * Usage:
- *   node close-agent-task-human-gate.mjs [--cwd <repo>] [--platform cursor|claude] [--slug <slug>]
+ *   node close-agent-task-human-gate.mjs [--cwd <repo>] [--platform cursor|claude|mavis|opencode] [--slug <slug>] [--no-activate-next]
  */
 
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
+const PLATFORMS = new Set(['cursor', 'claude', 'mavis', 'opencode']);
+
 function parseArgs(argv) {
-  const options = { cwd: process.cwd(), platform: 'cursor', slug: null };
-  // Read the next token from argv for value-taking flags. Returns the value or null
-  // when the flag is missing its value; the caller exits with a friendly error.
+  const options = { cwd: process.cwd(), platform: 'cursor', slug: null, activateNext: true };
   function nextValue(flag, i) {
     const next = argv[i + 1];
     if (next === undefined || next.startsWith('-')) {
@@ -35,12 +35,16 @@ function parseArgs(argv) {
       options.slug = nextValue(arg, i);
       i += 1;
     } else if (arg === '--activate-next') {
-      /* always activate via hook payload */
+      options.activateNext = true;
+    } else if (arg === '--no-activate-next') {
+      options.activateNext = false;
     } else if (arg === '--team-root') {
-      // Compatibility with earlier docs: derive platform + cwd from team root.
       const teamRoot = path.resolve(nextValue(arg, i));
       options.cwd = path.resolve(teamRoot, '..', '..');
-      options.platform = path.basename(path.dirname(teamRoot)) === '.claude' ? 'claude' : 'cursor';
+      const parent = path.basename(path.dirname(teamRoot));
+      if (parent.startsWith('.') && PLATFORMS.has(parent.slice(1))) {
+        options.platform = parent.slice(1);
+      }
       i += 1;
     } else {
       console.error(`Unknown argument: ${arg}`);
@@ -51,6 +55,13 @@ function parseArgs(argv) {
 }
 
 const options = parseArgs(process.argv);
+if (!PLATFORMS.has(options.platform)) {
+  console.error(
+    `Unknown --platform ${options.platform}. Use cursor|claude|mavis|opencode.`,
+  );
+  process.exit(2);
+}
+
 const toolRoot = path.join(options.cwd, `.${options.platform}`);
 const hookPath = path.join(toolRoot, 'hooks', 'chain-team-phases.sh');
 if (!fs.existsSync(hookPath)) {
@@ -59,7 +70,7 @@ if (!fs.existsSync(hookPath)) {
 }
 
 if (options.slug) {
-  const activePath = path.join(toolRoot, 'team', 'active-task.json');
+  const activePath = path.join(options.cwd, '.ai.local', 'team', 'active-task.json');
   fs.mkdirSync(path.dirname(activePath), { recursive: true });
   fs.writeFileSync(activePath, `${JSON.stringify({ slug: options.slug }, null, 2)}\n`);
 }
@@ -67,7 +78,7 @@ if (options.slug) {
 const payload = JSON.stringify({
   status: 'completed',
   action: 'end_human_gate',
-  activateNext: true,
+  activateNext: options.activateNext,
 });
 
 const output = execFileSync('bash', [hookPath], {