@bonesofspring/ai-rules 0.2.22 → 0.2.23

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

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * Validate presets/mavis/platform-contract.json against architecture §3.4.
+ *
+ * Usage:
+ *   node scripts/check-mavis-platform-contract.mjs
+ *   node scripts/check-mavis-platform-contract.mjs --contract <path>
+ *   node scripts/check-mavis-platform-contract.mjs --self-test
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(scriptDirectory, '..');
+const defaultContractPath = path.join(
+  packageRoot,
+  'presets',
+  'mavis',
+  'platform-contract.json',
+);
+const fixtureDirectory = path.join(
+  scriptDirectory,
+  'fixtures',
+  'mavis-platform-contract',
+);
+
+const ALLOWED_STATUS = new Set([
+  'confirmed',
+  'partial',
+  'unknown',
+  'no-equivalent',
+]);
+const KNOWN_STACKS = new Set([
+  'next',
+  'nuxt',
+  'svelte',
+  'ios-swift',
+  'android-kotlin',
+  'go',
+  'java',
+  'mcp-ts',
+  'php-hexagonal',
+  'php-laravel',
+]);
+const REQUIRED_CAPABILITIES = [
+  'cliVersion',
+  'rootAgents',
+  'explicitAgentFile',
+  'structuredOutput',
+  'referencedRule',
+  'referencedSkill',
+  'freshInit',
+  'nativeProjectRules',
+  'nativeWorkspaceSkills',
+  'nativeWorkspaceAgents',
+  'projectMcp',
+  'projectHooks',
+  'slashCommands',
+  'pluginSkillMcp',
+  'nativeTeam',
+];
+const REQUIRED_ENTRY_PAIRS = [
+  { source: 'REPO_AGENTS.md', destination: 'AGENTS.md' },
+  { source: 'MAVIS.md', destination: '.mavis/AGENTS.md' },
+];
+const REQUIRED_DIRECTORY_SOURCES = [
+  'rules',
+  'agents',
+  'skills',
+  'commands',
+  'hooks',
+  'team',
+];
+const FORBIDDEN_PATH_RE =
+  /(?:^|[\\/])\.minimax(?:[\\/]|$)|(?:^|[\\/])\.minimax-code(?:[\\/]|$)|~\/\.minimax|\$HOME\/\.minimax/i;
+const VERSION_PIN_KEYS = new Set([
+  'requiredCliVersion',
+  'requiredDesktopVersion',
+  'minCliVersion',
+  'pinnedVersion',
+  'requiredVersion',
+]);
+const EVIDENCE_MARKER = 'MAVIS-COMPATIBILITY.md';
+
+export function validateContract(contract, options = {}) {
+  const failures = [];
+  const fail = (message) => {
+    failures.push(message);
+  };
+
+  if (contract === null || typeof contract !== 'object' || Array.isArray(contract)) {
+    return ['contract must be a JSON object'];
+  }
+
+  if (contract.schemaVersion !== 1) {
+    fail('schemaVersion must be 1');
+  }
+  if (contract.id !== 'mavis') {
+    fail('id must be "mavis"');
+  }
+  if (contract.runtimeExecutable !== 'mcode') {
+    fail('runtimeExecutable must be "mcode"');
+  }
+  if (contract.sourceRoot !== 'presets/mavis') {
+    fail('sourceRoot must be "presets/mavis"');
+  }
+  if (contract.managedRoot !== '.mavis') {
+    fail('managedRoot must be ".mavis"');
+  }
+  if (contract.cleanStrategy !== 'manifest-owned') {
+    fail('cleanStrategy must be "manifest-owned"');
+  }
+
+  for (const key of Object.keys(contract)) {
+    if (VERSION_PIN_KEYS.has(key)) {
+      fail(`forbidden version-pin key "${key}"`);
+    }
+  }
+
+  if (!Array.isArray(contract.releasedStacks)) {
+    fail('releasedStacks must be an array');
+  } else {
+    for (const stack of contract.releasedStacks) {
+      if (typeof stack !== 'string' || !KNOWN_STACKS.has(stack)) {
+        fail(`releasedStacks contains unknown stack "${stack}"`);
+        continue;
+      }
+      if (options.requireReleasedStackDir) {
+        const stackDir = path.join(packageRoot, 'presets', 'mavis', stack);
+        if (!fs.existsSync(stackDir)) {
+          fail(`released stack "${stack}" has no source directory ${stackDir}`);
+        }
+      }
+    }
+  }
+
+  if (!Array.isArray(contract.entryFiles)) {
+    fail('entryFiles must be an array');
+  } else {
+    const pairs = new Set(
+      contract.entryFiles.map((entry) => `${entry?.source}→${entry?.destination}`),
+    );
+    for (const required of REQUIRED_ENTRY_PAIRS) {
+      if (!pairs.has(`${required.source}→${required.destination}`)) {
+        fail(
+          `entryFiles must include ${required.source} → ${required.destination}`,
+        );
+      }
+    }
+    for (const [index, entry] of contract.entryFiles.entries()) {
+      if (!isSourceDestination(entry)) {
+        fail(`entryFiles[${index}] must have string source and destination`);
+        continue;
+      }
+      failIfForbiddenPath(fail, `entryFiles[${index}].destination`, entry.destination);
+      if (
+        entry.destination !== 'AGENTS.md' &&
+        !entry.destination.startsWith('.mavis/')
+      ) {
+        fail(
+          `entryFiles[${index}].destination must be AGENTS.md or under .mavis/`,
+        );
+      }
+    }
+  }
+
+  if (!Array.isArray(contract.directoryMappings)) {
+    fail('directoryMappings must be an array');
+  } else {
+    const sources = new Set(
+      contract.directoryMappings
+        .filter((entry) => entry && typeof entry.source === 'string')
+        .map((entry) => entry.source),
+    );
+    for (const source of REQUIRED_DIRECTORY_SOURCES) {
+      if (!sources.has(source)) {
+        fail(`directoryMappings must include source "${source}"`);
+      }
+    }
+    for (const [index, entry] of contract.directoryMappings.entries()) {
+      if (!isSourceDestination(entry)) {
+        fail(
+          `directoryMappings[${index}] must have string source and destination`,
+        );
+        continue;
+      }
+      failIfForbiddenPath(
+        fail,
+        `directoryMappings[${index}].destination`,
+        entry.destination,
+      );
+      if (!entry.destination.startsWith('.mavis/')) {
+        fail(
+          `directoryMappings[${index}].destination must start with .mavis/`,
+        );
+      }
+    }
+  }
+
+  const mcp = contract.mcp;
+  if (mcp === null || typeof mcp !== 'object' || Array.isArray(mcp)) {
+    fail('mcp must be an object');
+  } else {
+    if (mcp.source !== 'mcp.json') {
+      fail('mcp.source must be "mcp.json"');
+    }
+    if (mcp.fallbackDestination !== '.mavis/mcp.json') {
+      fail('mcp.fallbackDestination must be ".mavis/mcp.json"');
+    }
+    if (mcp.mode !== 'fallback-manual-import') {
+      fail('mcp.mode must be "fallback-manual-import"');
+    }
+    failIfForbiddenPath(fail, 'mcp.fallbackDestination', mcp.fallbackDestination);
+  }
+
+  const docsSeed = contract.docsSeed;
+  if (docsSeed === null || typeof docsSeed !== 'object' || Array.isArray(docsSeed)) {
+    fail('docsSeed must be an object');
+  } else {
+    if (docsSeed.source !== 'presets/_shared/assets/docs-specs') {
+      fail('docsSeed.source must be "presets/_shared/assets/docs-specs"');
+    }
+    if (docsSeed.behavior !== 'absent-only') {
+      fail('docsSeed.behavior must be "absent-only"');
+    }
+  }
+
+  const capabilities = contract.nativeCapabilities;
+  if (
+    capabilities === null ||
+    typeof capabilities !== 'object' ||
+    Array.isArray(capabilities)
+  ) {
+    fail('nativeCapabilities must be an object');
+  } else {
+    for (const key of REQUIRED_CAPABILITIES) {
+      if (!Object.hasOwn(capabilities, key)) {
+        fail(`nativeCapabilities missing required key "${key}"`);
+      }
+    }
+    for (const [key, capability] of Object.entries(capabilities)) {
+      if (capability === null || typeof capability !== 'object' || Array.isArray(capability)) {
+        fail(`nativeCapabilities.${key} must be an object`);
+        continue;
+      }
+      if (!ALLOWED_STATUS.has(capability.status)) {
+        fail(
+          `nativeCapabilities.${key}.status must be confirmed|partial|unknown|no-equivalent`,
+        );
+      }
+      if (
+        typeof capability.evidence !== 'string' ||
+        !capability.evidence.includes(EVIDENCE_MARKER)
+      ) {
+        fail(
+          `nativeCapabilities.${key}.evidence must reference ${EVIDENCE_MARKER}`,
+        );
+      }
+      const nativePath = capability.nativePath ?? null;
+      if (nativePath !== null && typeof nativePath !== 'string') {
+        fail(`nativeCapabilities.${key}.nativePath must be a string or null`);
+        continue;
+      }
+      if (
+        (capability.status === 'unknown' || capability.status === 'no-equivalent') &&
+        nativePath
+      ) {
+        fail(
+          `nativeCapabilities.${key} is ${capability.status} and cannot declare nativePath`,
+        );
+      }
+      if (nativePath) {
+        failIfForbiddenPath(fail, `nativeCapabilities.${key}.nativePath`, nativePath);
+      }
+    }
+  }
+
+  return failures;
+}
+
+function isSourceDestination(entry) {
+  return (
+    entry &&
+    typeof entry === 'object' &&
+    typeof entry.source === 'string' &&
+    entry.source.length > 0 &&
+    typeof entry.destination === 'string' &&
+    entry.destination.length > 0
+  );
+}
+
+function failIfForbiddenPath(fail, label, value) {
+  if (typeof value === 'string' && FORBIDDEN_PATH_RE.test(value)) {
+    fail(`${label} claims a MiniMax-native or home path: ${value}`);
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function printFailures(label, failures) {
+  for (const failure of failures) {
+    console.error(`FAIL ${label}: ${failure}`);
+  }
+}
+
+function runSelfTest() {
+  const cases = [
+    { name: 'valid.json', expectFail: false },
+    { name: 'invalid-unknown-native-path.json', expectFail: true },
+    { name: 'invalid-minimax-destination.json', expectFail: true },
+    { name: 'invalid-missing-capability.json', expectFail: true },
+    { name: 'invalid-released-unknown-stack.json', expectFail: true },
+    { name: 'invalid-version-pin.json', expectFail: true },
+  ];
+  let failed = 0;
+  for (const testCase of cases) {
+    const filePath = path.join(fixtureDirectory, testCase.name);
+    const failures = validateContract(readJson(filePath));
+    const didFail = failures.length > 0;
+    if (didFail !== testCase.expectFail) {
+      failed += 1;
+      console.error(
+        `FAIL self-test ${testCase.name}: expected ${
+          testCase.expectFail ? 'invalid' : 'valid'
+        }, got ${didFail ? 'invalid' : 'valid'}`,
+      );
+      printFailures(testCase.name, failures);
+    } else {
+      console.log(
+        `ok self-test ${testCase.name} (${didFail ? 'invalid' : 'valid'})`,
+      );
+    }
+  }
+  return failed;
+}
+
+function parseArgs(argv) {
+  const options = { contract: defaultContractPath, selfTest: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--self-test') {
+      options.selfTest = true;
+    } else if (arg === '--contract') {
+      options.contract = argv[index + 1];
+      index += 1;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  let exitCode = 0;
+
+  if (options.selfTest) {
+    exitCode = runSelfTest() === 0 ? 0 : 1;
+  }
+
+  if (!options.selfTest || exitCode === 0) {
+    const liveFailures = validateContract(readJson(options.contract), {
+      requireReleasedStackDir: options.contract === defaultContractPath,
+    });
+    if (liveFailures.length > 0) {
+      printFailures(path.relative(packageRoot, options.contract), liveFailures);
+      exitCode = 1;
+    } else if (!options.selfTest) {
+      console.log(`ok ${path.relative(packageRoot, options.contract)}`);
+    } else {
+      console.log('ok live platform-contract.json');
+    }
+  }
+
+  process.exit(exitCode);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`FAIL: ${error.message}`);
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Isolated Mavis token-budget analog. Does not change Cursor/Claude 3/4 caps.
+ * Root-entry rules in adapter-map.json must stay ≤ 4.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 stacks = loadReleasedMavisStacks(presetsRoot);
+if (stacks.length === 0) {
+  console.log('ok mavis token-budget: no released stacks');
+  process.exit(0);
+}
+
+let failed = 0;
+for (const stack of stacks) {
+  const mapPath = path.join(presetsRoot, 'mavis', stack, 'adapter-map.json');
+  if (!fs.existsSync(mapPath)) {
+    console.error(`FAIL mavis/${stack}: missing adapter-map.json`);
+    failed += 1;
+    continue;
+  }
+  const map = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
+  const rootRules = (map.entries || []).filter(
+    (entry) =>
+      entry.category === 'rules' &&
+      entry.loadMode === 'root-entry' &&
+      entry.target,
+  );
+  if (rootRules.length > ROOT_ENTRY_CAP) {
+    console.error(
+      `FAIL mavis/${stack}: ${rootRules.length} root-entry rules (cap ${ROOT_ENTRY_CAP})`,
+    );
+    failed += 1;
+  } else {
+    console.log(
+      `ok mavis/${stack}: ${rootRules.length} root-entry rules (cap ${ROOT_ENTRY_CAP})`,
+    );
+  }
+}
+
+process.exit(failed === 0 ? 0 : 1);

package/scripts/check-preset-leakage.sh

@@ -18,9 +18,21 @@ import sys
 from pathlib import Path
 
 presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
-PLATFORMS = ("cursor", "claude")
+PLATFORMS = ("cursor", "claude", "mavis")
 STACKS = ("next", "nuxt", "svelte", "ios-swift", "android-kotlin", "go", "java", "mcp-ts", "php-hexagonal", "php-laravel")
 
+
+def released_mavis_stacks() -> list[str]:
+    contract = presets / "mavis" / "platform-contract.json"
+    if not contract.is_file():
+        return []
+    try:
+        data = json.loads(contract.read_text(encoding="utf-8"))
+        return list(data.get("releasedStacks") or [])
+    except json.JSONDecodeError:
+        return []
+
+
 NEGATION_RE = re.compile(
     r"(?i)\b("
     r"never|do\s+not|don't|must\s+not|forbidden|ban(?:ned)?|avoid|"
@@ -325,7 +337,11 @@ for stack in STACKS:
     stack_negation = 0
     stack_fixture_skipped = 0
 
-    for platform in PLATFORMS:
+    platforms_for_stack = ["cursor", "claude"]
+    if stack in released_mavis_stacks():
+        platforms_for_stack.append("mavis")
+
+    for platform in platforms_for_stack:
         for script in iter_hook_scripts(stack, platform):
             text = script.read_text(encoding="utf-8")
             for pat in hard_patterns:
@@ -412,7 +428,7 @@ for stack in STACKS:
 
 # --- Chain fork: pairwise among stacks that have chain scripts ---
 print("=== chain fork ===")
-for platform in PLATFORMS:
+for platform in ("cursor", "claude"):
     chains: dict[str, Path] = {}
     for stack in STACKS:
         p = presets / platform / stack / "hooks" / "chain-team-phases.sh"
@@ -433,6 +449,22 @@ for platform in PLATFORMS:
             else:
                 print(f"OK: [{platform}] {a} chain ≠ {b} chain")
 
+for stack in released_mavis_stacks():
+    mavis_chain = presets / "mavis" / stack / "hooks" / "chain-team-phases.sh"
+    if not mavis_chain.is_file():
+        print(f"FAIL: [mavis/{stack}] missing chain-team-phases.sh")
+        failed += 1
+        continue
+    for platform in ("cursor", "claude"):
+        other = presets / platform / stack / "hooks" / "chain-team-phases.sh"
+        if other.is_file() and mavis_chain.read_bytes() == other.read_bytes():
+            print(
+                f"FAIL: [mavis/{stack}] chain is byte-identical to [{platform}/{stack}]"
+            )
+            failed += 1
+        elif other.is_file():
+            print(f"OK: [mavis/{stack}] chain ≠ [{platform}/{stack}] chain")
+
 print()
 print(f"WARN count: {warned} (build-verifier packaging refs / chain skips)")
 print(

package/scripts/check-preset-structure.sh

@@ -29,6 +29,60 @@ run_gate() {
   echo
 }
 
+echo ">>> mavis-platform-contract"
+if node "$SCRIPT_DIR/check-mavis-platform-contract.mjs" --self-test; then
+  echo "<<< mavis-platform-contract: OK"
+else
+  echo "<<< mavis-platform-contract: FAIL"
+  status=1
+fi
+echo
+
+echo ">>> mavis-adapter-map"
+if node "$SCRIPT_DIR/check-mavis-adapter-map.mjs" --self-test; then
+  echo "<<< mavis-adapter-map: OK"
+else
+  echo "<<< mavis-adapter-map: FAIL"
+  status=1
+fi
+echo
+
+echo ">>> mavis-token-budget"
+if node "$SCRIPT_DIR/check-mavis-token-budget.mjs"; then
+  echo "<<< mavis-token-budget: OK"
+else
+  echo "<<< mavis-token-budget: FAIL"
+  status=1
+fi
+echo
+
+echo ">>> mavis-local-overlay"
+if node "$SCRIPT_DIR/check-mavis-local-overlay.mjs"; then
+  echo "<<< mavis-local-overlay: OK"
+else
+  echo "<<< mavis-local-overlay: FAIL"
+  status=1
+fi
+echo
+
+echo ">>> mavis-context-budget"
+if node "$SCRIPT_DIR/test-mavis-context-budget.mjs"; then
+  echo "<<< mavis-context-budget: OK"
+else
+  echo "<<< mavis-context-budget: FAIL"
+  status=1
+fi
+echo
+
+echo ">>> mavis-orchestration"
+if node "$SCRIPT_DIR/test-mavis-orchestration.mjs"; then
+  echo "<<< mavis-orchestration: OK"
+else
+  echo "<<< mavis-orchestration: FAIL"
+  status=1
+fi
+echo
+
 run_gate "twin-map" "$SCRIPT_DIR/check-preset-twin-map.sh"
 run_gate "token-budget" "$SCRIPT_DIR/check-preset-token-budget.sh"
 run_gate "leakage" "$SCRIPT_DIR/check-preset-leakage.sh"
@@ -48,6 +102,15 @@ else
 fi
 echo
 
+echo ">>> cli-init-clean"
+if node "$SCRIPT_DIR/test-cli-init-clean.mjs"; then
+  echo "<<< cli-init-clean: OK"
+else
+  echo "<<< cli-init-clean: FAIL"
+  status=1
+fi
+echo
+
 echo ">>> chain-team-phases coverage"
 if node "$SCRIPT_DIR/test-chain-team-phases-coverage.mjs"; then
   echo "<<< chain-team-phases coverage: OK"

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

@@ -80,6 +80,24 @@ def consumers(stem: str) -> list[Path]:
                     out.append(path)
             except OSError:
                 continue
+    contract_path = presets / "mavis" / "platform-contract.json"
+    if contract_path.is_file():
+        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():
+                    continue
+                for path in mavis_base.rglob("*"):
+                    if path.suffix not in {".md", ".mdc"}:
+                        continue
+                    try:
+                        if needle in path.read_text(encoding="utf-8"):
+                            out.append(path)
+                    except OSError:
+                        continue
+        except (json.JSONDecodeError, OSError):
+            pass
     return out
 
 

package/scripts/check-task-router-intents.sh

@@ -30,15 +30,27 @@ export AI_RULES_PRESETS_ROOT="${AI_RULES_PRESETS_ROOT:-$ROOT/packages/ai-rules/p
 python3 <<'PY'
 from __future__ import annotations
 
+import json
 import os
 import re
 import sys
 from pathlib import Path
 
 presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
-PLATFORMS = ("cursor", "claude")
+PLATFORMS = ("cursor", "claude", "mavis")
 STACKS = ("next", "nuxt", "svelte", "ios-swift", "android-kotlin", "go", "java", "mcp-ts", "php-hexagonal", "php-laravel")
 
+
+def released_mavis_stacks() -> list[str]:
+    contract = presets / "mavis" / "platform-contract.json"
+    if not contract.is_file():
+        return []
+    try:
+        data = json.loads(contract.read_text(encoding="utf-8"))
+        return list(data.get("releasedStacks") or [])
+    except json.JSONDecodeError:
+        return []
+
 # Agents that are shipped for orchestration purposes but do not need to appear
 # in task-router.md intent rows (router-only / analyzer-only / orchestrator-only).
 ROUTER_EXEMPT_FROM_INTENT = frozenset({
@@ -59,7 +71,8 @@ failures: list[str] = []
 checks = 0
 
 for platform in PLATFORMS:
-    for stack in STACKS:
+    stacks = STACKS if platform != "mavis" else released_mavis_stacks()
+    for stack in stacks:
         agents_dir = presets / platform / stack / "agents"
         if not agents_dir.is_dir():
             continue