@bonesofspring/ai-rules 0.2.21 → 0.2.23

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Mavis platform (MiniMax Code, experimental Next-only)
+
+- New platform **`mavis`** (`mcode` runtime): `npx @bonesofspring/ai-rules init mavis --preset next` installs **`.mavis/**`** plus root `AGENTS.md`. `clean mavis` is manifest/hash-safe. MCP merges to **`.mavis/mcp.json`** only — the CLI never writes `~/.minimax/**`.
+- Source: `presets/mavis/next/` derived from `presets/cursor/next` (`adapter-map.json`, `generate-mavis-next.mjs`). `platform-contract.json` `releasedStacks: ["next"]`; nine other stacks deferred (WP-F).
+- Semi-auto orchestration: `chain-team-phases.sh` on `.mavis/team`; no shipped `hooks.json`. Human gates via `task-continue` → hook `end_human_gate`. Agents upsert `artifact-manifest.json` only — hook owns `status.json` / `metrics.json`.
+- Docs: [`docs/MAVIS.md`](docs/MAVIS.md) (consumer), [`docs/MAVIS-COMPATIBILITY.md`](docs/MAVIS-COMPATIBILITY.md) (probe evidence). Gates: `check-mavis-*`, `test-mavis-*` wired into `check:preset-structure`.
+- Consumers: re-run `npx @bonesofspring/ai-rules init mavis --preset next` after publish. Cursor/Claude installs unchanged.
+
 ### Chain-team-phases hook coverage + pipeline race fixes
 
 - `chain-team-phases.sh` (all 20 stack × platform hooks) now covers every agent that ships in its stack's `agents/` directory:

package/README.md

@@ -1,6 +1,6 @@
 # @bonesofspring/ai-rules
 
-Presets for Cursor and Claude Code: rules, commands, plus optional `agents`, `hooks`, `skills`, team artifacts, and MCP configs when the preset includes them. For Claude: `CLAUDE.md`. Install from npm into a project so you don’t have to copy files out of the repo by hand.
+Presets for Cursor, Claude Code, and **Mavis / MiniMax Code (experimental Next-only)**:
 
 Node 18+.
 
@@ -8,7 +8,9 @@ Node 18+.
 # from the project root
 npx @bonesofspring/ai-rules init cursor --preset next
 npx @bonesofspring/ai-rules init claude --preset next
+npx @bonesofspring/ai-rules init mavis --preset next
 npx @bonesofspring/ai-rules clean cursor
+npx @bonesofspring/ai-rules clean mavis
 ```
 
 Global: `npm i -g @bonesofspring/ai-rules`, then `ai-rules ...`.
@@ -54,6 +56,8 @@ Where things go on `init`:
 | **repo-root agents** | `REPO_AGENTS.md` → **`<cwd>/AGENTS.md`** | same |
 | **docs/specs seed** | When `<cwd>/docs/specs/` is **absent**, copy INDEX stub + `_templates/*` from `presets/_shared/assets/docs-specs/` (never overwrite existing INDEX) | same |
 
+**Mavis (MiniMax Code, experimental Next-only):** `ai-rules init mavis --preset next` writes ai-rules-owned **`.mavis/**`** plus root `AGENTS.md`. MCP merges into **`.mavis/mcp.json`** only — the CLI never writes `~/.minimax/**`. `clean mavis` is manifest-owned: unchanged hashes are removed; modified files stay. See [`docs/MAVIS.md`](docs/MAVIS.md), [`presets/mavis/README.md`](presets/mavis/README.md), and [`docs/MAVIS-COMPATIBILITY.md`](docs/MAVIS-COMPATIBILITY.md).
+
 Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `mockup-review` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — Figma mockup reviewer via agent `mockup-reviewer`); `ux-design` (**next** / **nuxt** / **svelte** / **ios-swift** / **android-kotlin** — behavioral UX via `task-analyst`, no agent); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
 
 ## Product specs (`docs/specs/`)
@@ -121,6 +125,6 @@ Presets are developed in this monorepo under `presets/`. If you add or change ru
 - **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh). Published npm `files` include `scripts/` so consumers can run `check-product-specs.sh` from the package.
 - **Preset structure CI gates** (exit non-zero on FAIL): `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) — twin map, session-start budget (Option A), leakage, shared-core drift (`AI_RULES_DRIFT_FAIL=1`)
 - **Opt-in rule eval:** `yarn check:rule-eval` + `.github/workflows/rule-eval.yml` (`workflow_dispatch` + paths-scoped PR) — **not** wired into `check:preset-structure`
-- **CLI note:** `_shared` is not an installable `--preset`; `init` copies only `presets/cursor/<name>/` or `presets/claude/<name>/`
+- **CLI note:** `_shared` is not an installable `--preset`; `init` copies `presets/cursor/<name>/`, `presets/claude/<name>/`, or `presets/mavis/<name>/` when the stack is in `releasedStacks`
 
 MIT.

package/bin/cli.js

@@ -4,11 +4,12 @@
  */
 const fs = require('fs');
 const path = require('path');
+const { cmdInitMavis, cmdCleanMavis } = require('./mavis-install');
 
 /** Single path segment: letters, digits, dot, underscore, hyphen; no separators or "..". */
 const PRESET_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const DEFAULT_PRESET = 'next';
-const TOOLS = new Set(['cursor', 'claude']);
+const TOOLS = new Set(['cursor', 'claude', 'mavis']);
 
 const PRESETS = {
   cursor: {
@@ -51,9 +52,9 @@ function printHelp() {
   console.log(`@bonesofspring/ai-rules
 
 Usage:
-  ai-rules init <cursor|claude> [--preset <name>]
-  ai-rules init <cursor|claude> <preset-name>
-  ai-rules clean <cursor|claude> [--cwd <dir>]
+  ai-rules init <cursor|claude|mavis> [--preset <name>]
+  ai-rules init <cursor|claude|mavis> <preset-name>
+  ai-rules clean <cursor|claude|mavis> [--cwd <dir>]
 
 Options:
   --preset <name>   Preset name (default: ${DEFAULT_PRESET})
@@ -66,6 +67,7 @@ Notes:
   copied to a timestamped *.bak.* then replaced with the preset file. JSONC is not supported).
   Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
   Claude init copies rules, commands, skills, agents, hooks, team, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
+  Mavis init copies into .mavis/ (ai-rules-owned) plus REPO_AGENTS.md → <cwd>/AGENTS.md; MCP merges into .mavis/mcp.json only (never ~/.minimax/**).
   Both tools also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
   When <cwd>/docs/specs/ is absent, init also seeds INDEX.md stub + _templates/* from package assets (never overwrites an existing INDEX).
   clean removes tool dirs/files and <cwd>/AGENTS.md (shared across tools — re-init the other tool to restore).
@@ -93,6 +95,8 @@ Examples:
   npx @bonesofspring/ai-rules init claude --preset mcp-ts
   npx @bonesofspring/ai-rules init claude --preset php-hexagonal
   npx @bonesofspring/ai-rules init claude --preset php-laravel
+  npx @bonesofspring/ai-rules init mavis --preset next
+  npx @bonesofspring/ai-rules clean mavis
   npx @bonesofspring/ai-rules clean cursor
 `);
 }
@@ -484,9 +488,22 @@ function resolvePresetName(tool, preset, packageRoot) {
 }
 
 function cmdInit(tool, preset, cwdOption) {
+  if (tool === 'mavis') {
+    cmdInitMavis({
+      preset,
+      cwdOption,
+      helpers: {
+        resolveTargetCwd,
+        seedDocsSpecsIfAbsent,
+        installMcpJson,
+        getPackageRoot,
+      },
+    });
+    return;
+  }
   const cfg = PRESETS[tool];
   if (!cfg) {
-    console.error(`Unknown tool: ${tool}. Use cursor or claude.`);
+    console.error(`Unknown tool: ${tool}. Use cursor, claude, or mavis.`);
     process.exit(1);
   }
 
@@ -665,9 +682,16 @@ function rollbackInit(createdPaths, toolRootExisted, toolRootAbs) {
 }
 
 function cmdClean(tool, cwdOption) {
+  if (tool === 'mavis') {
+    cmdCleanMavis({
+      cwdOption,
+      helpers: { resolveTargetCwd },
+    });
+    return;
+  }
   const cfg = PRESETS[tool];
   if (!cfg) {
-    console.error(`Unknown tool: ${tool}. Use cursor or claude.`);
+    console.error(`Unknown tool: ${tool}. Use cursor, claude, or mavis.`);
     process.exit(1);
   }
   const cwd = resolveTargetCwd(cwdOption);
@@ -737,7 +761,7 @@ function main() {
 
   if (command === 'init') {
     if (!tool || !TOOLS.has(tool)) {
-      console.error('Missing or invalid tool. Use: init cursor|claude [--preset next]');
+      console.error('Missing or invalid tool. Use: init cursor|claude|mavis [--preset next]');
       process.exit(1);
     }
     cmdInit(tool, preset, parsed.cwd);
@@ -745,7 +769,7 @@ function main() {
   }
   if (command === 'clean') {
     if (!tool || !TOOLS.has(tool)) {
-      console.error('Missing or invalid tool. Use: clean cursor|claude');
+      console.error('Missing or invalid tool. Use: clean cursor|claude|mavis');
       process.exit(1);
     }
     cmdClean(tool, parsed.cwd);

package/bin/mavis-install.js

@@ -0,0 +1,441 @@
+/**
+ * Manifest-owned Mavis init/clean. Does not write ~/.minimax/**.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const MANIFEST_REL = path.join('.mavis', '.ai-rules-install.json');
+const CONTRACT_REL = path.join('presets', 'mavis', 'platform-contract.json');
+const SKIP_STACK_ROOT = new Set(['adapter-map.json', 'README.md']);
+
+function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function failPhase() {
+  return process.env.AI_RULES_MAVIS_FAIL_PHASE || '';
+}
+
+function throwIfPhase(name) {
+  if (failPhase() === name) {
+    throw new Error(`injected failure at ${name}`);
+  }
+}
+
+function loadJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function walkFiles(root) {
+  const files = [];
+  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()) {
+        files.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  if (fs.existsSync(root)) {
+    visit(root);
+  }
+  return files.sort();
+}
+
+function writeAtomicCopy(source, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.ai-rules-tmp`;
+  fs.copyFileSync(source, tmp);
+  if (dest.endsWith('.sh')) {
+    fs.chmodSync(tmp, 0o755);
+  }
+  fs.renameSync(tmp, dest);
+}
+
+function writeAtomicText(dest, text) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.ai-rules-tmp`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, dest);
+}
+
+function loadContract(packageRoot) {
+  const contractPath = path.join(packageRoot, CONTRACT_REL);
+  if (!fs.existsSync(contractPath)) {
+    throw new Error(`Mavis platform contract missing: ${contractPath}`);
+  }
+  return loadJson(contractPath);
+}
+
+function packageVersion(packageRoot) {
+  return loadJson(path.join(packageRoot, 'package.json')).version;
+}
+
+function buildPlan({ contract, sourceBase, cwd }) {
+  const files = [];
+  const seen = new Set();
+  const addFile = (source, destRel) => {
+    if (seen.has(destRel)) {
+      return;
+    }
+    seen.add(destRel);
+    files.push({
+      source,
+      dest: path.join(cwd, destRel),
+      rel: destRel,
+    });
+  };
+
+  for (const entry of contract.entryFiles || []) {
+    const source = path.join(sourceBase, entry.source);
+    if (fs.existsSync(source)) {
+      addFile(source, entry.destination);
+    }
+  }
+
+  for (const mapping of contract.directoryMappings || []) {
+    const sourceDir = path.join(sourceBase, mapping.source);
+    if (!fs.existsSync(sourceDir)) {
+      continue;
+    }
+    for (const rel of walkFiles(sourceDir)) {
+      addFile(path.join(sourceDir, rel), `${mapping.destination}/${rel}`);
+    }
+  }
+
+  const mcpMd = path.join(sourceBase, 'MCP.md');
+  if (fs.existsSync(mcpMd)) {
+    addFile(mcpMd, path.join(contract.managedRoot, 'MCP.md'));
+  }
+
+  const mcpSource = path.join(sourceBase, contract.mcp.source);
+  const mcp = fs.existsSync(mcpSource)
+    ? {
+        source: mcpSource,
+        dest: path.join(cwd, contract.mcp.fallbackDestination),
+        rel: contract.mcp.fallbackDestination,
+      }
+    : null;
+
+  for (const skip of SKIP_STACK_ROOT) {
+    const skipped = path.join(sourceBase, skip);
+    if (fs.existsSync(skipped)) {
+      const accidental = files.find((item) => item.source === skipped);
+      if (accidental) {
+        throw new Error(`refusing to install stack-root ${skip}`);
+      }
+    }
+  }
+
+  return { files, mcp };
+}
+
+function capabilityModes(contract) {
+  const modes = {};
+  for (const [key, value] of Object.entries(contract.nativeCapabilities || {})) {
+    modes[key] = value.status;
+  }
+  return modes;
+}
+
+function shippedMcpIds(mcpSource) {
+  if (!mcpSource || !fs.existsSync(mcpSource)) {
+    return [];
+  }
+  const parsed = loadJson(mcpSource);
+  if (!parsed || typeof parsed.mcpServers !== 'object' || parsed.mcpServers === null) {
+    return [];
+  }
+  return Object.keys(parsed.mcpServers);
+}
+
+function previousManifest(cwd) {
+  const manifestPath = path.join(cwd, MANIFEST_REL);
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    return loadJson(manifestPath);
+  } catch {
+    return null;
+  }
+}
+
+function restoreRollback(overwritten, created, rollbackRoot, mavisRoot, mavisExisted) {
+  for (const item of overwritten) {
+    try {
+      if (fs.existsSync(item.backup)) {
+        fs.mkdirSync(path.dirname(item.dest), { recursive: true });
+        fs.copyFileSync(item.backup, item.dest);
+      }
+    } catch {
+      // Best-effort restore; caller already reports the failure.
+    }
+  }
+  const createdPaths = [...created].sort((a, b) => b.length - a.length);
+  for (const dest of createdPaths) {
+    try {
+      if (!fs.existsSync(dest)) {
+        continue;
+      }
+      const stat = fs.lstatSync(dest);
+      if (stat.isDirectory()) {
+        fs.rmSync(dest, { recursive: true, force: true });
+      } else {
+        fs.unlinkSync(dest);
+      }
+    } catch {
+      // Best-effort.
+    }
+  }
+  if (fs.existsSync(rollbackRoot)) {
+    fs.rmSync(rollbackRoot, { recursive: true, force: true });
+  }
+  if (!mavisExisted && fs.existsSync(mavisRoot)) {
+    fs.rmSync(mavisRoot, { recursive: true, force: true });
+  } else if (mavisExisted && fs.existsSync(mavisRoot)) {
+    removeEmptyDirs(mavisRoot);
+  }
+}
+
+function cmdInitMavis({ preset, cwdOption, helpers }) {
+  const { resolveTargetCwd, seedDocsSpecsIfAbsent, installMcpJson, getPackageRoot } = helpers;
+  const packageRoot = getPackageRoot();
+  const cwd = resolveTargetCwd(cwdOption);
+  const contract = loadContract(packageRoot);
+  const stack = preset || 'next';
+  const releasedStacks = Array.isArray(contract.releasedStacks) ? contract.releasedStacks : [];
+  if (releasedStacks.length > 0 && !releasedStacks.includes(stack)) {
+    console.error(`Preset "${stack}" for mavis is not released yet.`);
+    console.error(`Released stacks: ${releasedStacks.join(', ')}`);
+    console.error('Additional stacks ship after the pilot human gate (WP-F).');
+    process.exit(1);
+  }
+  const sourceBase = path.join(packageRoot, contract.sourceRoot, stack);
+  if (!fs.existsSync(sourceBase)) {
+    console.error(`Preset "${stack}" for mavis not found.`);
+    console.error(`Looked in: ${sourceBase}`);
+    process.exit(1);
+  }
+
+  const mavisRoot = path.join(cwd, contract.managedRoot);
+  const mavisExisted = fs.existsSync(mavisRoot);
+  const docsSpecsDir = path.join(cwd, 'docs', 'specs');
+  const docsSpecsExisted = fs.existsSync(docsSpecsDir);
+  const prior = previousManifest(cwd);
+  const runId = new Date().toISOString().replace(/[:.]/g, '-');
+  const rollbackRoot = path.join(mavisRoot, '.rollback', runId);
+  const created = new Set();
+  const overwritten = [];
+
+  try {
+    throwIfPhase('validate');
+    const plan = buildPlan({ contract, sourceBase, cwd });
+    for (const item of plan.files) {
+      if (!fs.existsSync(item.source)) {
+        throw new Error(`Source missing: ${item.source}`);
+      }
+    }
+
+    throwIfPhase('snapshot');
+    for (const item of plan.files) {
+      if (!fs.existsSync(item.dest)) {
+        continue;
+      }
+      const backup = path.join(rollbackRoot, item.rel);
+      fs.mkdirSync(path.dirname(backup), { recursive: true });
+      fs.copyFileSync(item.dest, backup);
+      overwritten.push({ dest: item.dest, backup });
+      const priorHash = prior && prior.managedFiles ? prior.managedFiles[item.rel] : null;
+      const currentHash = sha256File(item.dest);
+      if (priorHash && priorHash !== currentHash) {
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const reported = `${item.dest}.bak.${stamp}`;
+        fs.copyFileSync(item.dest, reported);
+        console.warn(`Modified managed file ${item.rel} backed up to ${reported} before overwrite.`);
+      }
+    }
+    if (plan.mcp && fs.existsSync(plan.mcp.dest)) {
+      const backup = path.join(rollbackRoot, plan.mcp.rel);
+      fs.mkdirSync(path.dirname(backup), { recursive: true });
+      fs.copyFileSync(plan.mcp.dest, backup);
+      overwritten.push({ dest: plan.mcp.dest, backup });
+    }
+
+    throwIfPhase('write');
+    for (const item of plan.files) {
+      if (!fs.existsSync(item.dest)) {
+        created.add(item.dest);
+      }
+      writeAtomicCopy(item.source, item.dest);
+      console.log(`Copied ${path.basename(item.source)} → ${item.rel}`);
+    }
+
+    throwIfPhase('mcp');
+    if (plan.mcp) {
+      if (!fs.existsSync(plan.mcp.dest)) {
+        created.add(plan.mcp.dest);
+      }
+      installMcpJson(plan.mcp.source, plan.mcp.dest, plan.mcp.rel);
+      console.log(
+        'MCP fallback staged at .mavis/mcp.json. Import it in MiniMax Code MCP JSON mode; do not write ~/.minimax/mcp.json from this CLI.',
+      );
+    }
+
+    throwIfPhase('docs');
+    const seeded = seedDocsSpecsIfAbsent(packageRoot, cwd);
+    if (seeded && !docsSpecsExisted) {
+      created.add(docsSpecsDir);
+    }
+
+    throwIfPhase('manifest');
+    const managedFiles = {};
+    for (const item of plan.files) {
+      managedFiles[item.rel] = sha256File(item.dest);
+    }
+    if (plan.mcp && fs.existsSync(plan.mcp.dest)) {
+      managedFiles[plan.mcp.rel] = sha256File(plan.mcp.dest);
+    }
+    const manifest = {
+      schemaVersion: 1,
+      packageVersion: packageVersion(packageRoot),
+      platform: 'mavis',
+      preset: stack,
+      installedAt: new Date().toISOString(),
+      managedFiles,
+      managedDirectories: (contract.directoryMappings || []).map((entry) => entry.destination),
+      shippedMcpServerIds: plan.mcp ? shippedMcpIds(plan.mcp.source) : [],
+      docsSeed: seeded
+        ? { seeded: true }
+        : { seeded: false, reason: docsSpecsExisted ? 'directory-exists' : 'assets-missing' },
+      capabilityModes: capabilityModes(contract),
+    };
+    const manifestAbs = path.join(cwd, MANIFEST_REL);
+    if (!fs.existsSync(manifestAbs)) {
+      created.add(manifestAbs);
+    }
+    writeAtomicText(manifestAbs, `${JSON.stringify(manifest, null, 2)}\n`);
+
+    if (fs.existsSync(rollbackRoot)) {
+      fs.rmSync(rollbackRoot, { recursive: true, force: true });
+    }
+    const rollbackParent = path.join(mavisRoot, '.rollback');
+    if (fs.existsSync(rollbackParent) && fs.readdirSync(rollbackParent).length === 0) {
+      fs.rmdirSync(rollbackParent);
+    }
+  } catch (error) {
+    restoreRollback(overwritten, created, rollbackRoot, mavisRoot, mavisExisted);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`init failed: ${message}`);
+    process.exit(1);
+  }
+
+  console.log(`Done. .mavis installed at ${mavisRoot} (preset: ${stack})`);
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stripShippedMcp(mcpAbs, shippedIds) {
+  if (!fs.existsSync(mcpAbs) || shippedIds.length === 0) {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = loadJson(mcpAbs);
+  } catch {
+    console.warn(`Preserved ${mcpAbs} (not valid JSON); shipped MCP keys not stripped.`);
+    return;
+  }
+  if (!isPlainObject(parsed) || !isPlainObject(parsed.mcpServers)) {
+    return;
+  }
+  const nextServers = { ...parsed.mcpServers };
+  for (const id of shippedIds) {
+    delete nextServers[id];
+  }
+  writeAtomicText(mcpAbs, `${JSON.stringify({ ...parsed, mcpServers: nextServers }, null, 2)}\n`);
+}
+
+function removeEmptyDirs(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return;
+  }
+  for (const name of fs.readdirSync(dir)) {
+    removeEmptyDirs(path.join(dir, name));
+  }
+  if (fs.readdirSync(dir).length === 0) {
+    fs.rmdirSync(dir);
+  }
+}
+
+function cmdCleanMavis({ cwdOption, helpers }) {
+  const { resolveTargetCwd } = helpers;
+  const cwd = resolveTargetCwd(cwdOption);
+  const manifestPath = path.join(cwd, MANIFEST_REL);
+  if (!fs.existsSync(manifestPath)) {
+    console.error(
+      'clean mavis: missing .mavis/.ai-rules-install.json; nothing removed (fail-safe).',
+    );
+    process.exit(1);
+  }
+  let manifest;
+  try {
+    manifest = loadJson(manifestPath);
+  } catch {
+    console.error(
+      'clean mavis: invalid .mavis/.ai-rules-install.json; nothing removed (fail-safe).',
+    );
+    process.exit(1);
+  }
+  if (!manifest || manifest.platform !== 'mavis' || !isPlainObject(manifest.managedFiles)) {
+    console.error(
+      'clean mavis: install manifest is not a Mavis ownership record; nothing removed.',
+    );
+    process.exit(1);
+  }
+
+  const preserved = [];
+  for (const [rel, installedHash] of Object.entries(manifest.managedFiles)) {
+    if (rel === MANIFEST_REL) {
+      continue;
+    }
+    const abs = path.join(cwd, rel);
+    if (!fs.existsSync(abs)) {
+      continue;
+    }
+    const current = sha256File(abs);
+    if (current === installedHash) {
+      fs.unlinkSync(abs);
+    } else {
+      preserved.push(rel);
+      console.warn(`Preserved modified managed file ${rel}`);
+    }
+  }
+
+  if (preserved.includes('.mavis/mcp.json') && Array.isArray(manifest.shippedMcpServerIds)) {
+    stripShippedMcp(path.join(cwd, '.mavis', 'mcp.json'), manifest.shippedMcpServerIds);
+  }
+
+  for (const dirRel of [...(manifest.managedDirectories || [])].sort((a, b) => b.length - a.length)) {
+    removeEmptyDirs(path.join(cwd, dirRel));
+  }
+
+  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'));
+  }
+
+  console.log(
+    preserved.length > 0
+      ? `clean mavis: removed unchanged managed files; preserved ${preserved.join(', ')}`
+      : 'clean mavis: removed unchanged managed files',
+  );
+}
+
+module.exports = { cmdInitMavis, cmdCleanMavis, MANIFEST_REL };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -38,8 +38,15 @@
     "check:product-specs:dogfood": "bash scripts/check-product-specs.sh ../../dogfood/mcp-ts-sample",
     "check:rule-eval": "node scripts/check-rule-eval.mjs",
     "test:cli-mcp-merge": "node scripts/test-cli-mcp-merge.mjs",
+    "test:cli-init-clean": "node scripts/test-cli-init-clean.mjs",
     "test:chain-coverage": "node scripts/test-chain-team-phases-coverage.mjs",
-    "test:agent-task-metrics-hooks": "node scripts/test-agent-task-metrics-hooks.mjs"
+    "test:agent-task-metrics-hooks": "node scripts/test-agent-task-metrics-hooks.mjs",
+    "check:mavis-platform-contract": "node scripts/check-mavis-platform-contract.mjs --self-test",
+    "check:mavis-adapter-map": "node scripts/check-mavis-adapter-map.mjs --self-test",
+    "check:mavis-token-budget": "node scripts/check-mavis-token-budget.mjs",
+    "check:mavis-local-overlay": "node scripts/check-mavis-local-overlay.mjs",
+    "test:mavis-context-budget": "node scripts/test-mavis-context-budget.mjs",
+    "test:mavis-orchestration": "node scripts/test-mavis-orchestration.mjs"
   },
   "engines": {
     "node": ">=18"

package/presets/_shared/core/agent-team/agent-artifact-contracts.md

@@ -78,6 +78,8 @@ A producer finishes its step by upserting only its owned artifact entry and term
 
 `blocked` is terminal for the producer attempt but non-advancing for the pipeline: the hook persists `status.state` / `phase` as `blocked` and emits no next-agent handoff. A receipt must either carry the active `attemptId` or belong to the step's assigned output entry. Its terminal timestamp must be at or after the active attempt's `startedAt`; otherwise the hook keeps the attempt active in `awaiting_artifact_receipt` and does not advance or retry.
 
+> **Receipt binding (owner prompts).** Each owning-agent prompt (`feature-developer`, `build-verifier`, `code-reviewer`, `debugger`, `qa-tester` across `cursor/` and `claude/` platforms × 10 stacks) carries the same one-paragraph callout under `## On completion` (or appended as `## Receipt binding` when no `On completion` section exists). When writing the terminal receipt, set `entry.receipt.attemptId = <attemptId supplied by the orchestrator>`. The hook at `chain-team-phases.sh:readBoundReceiptOutcome` rejects entries whose `attemptId` does not match the current attempt, or whose `Date.parse(timestamps.completedAt) < Date.parse(attemptStartedAt)`. A missing or stale attemptId causes `awaiting_artifact_receipt` stalls.
+
 ## Ownership and writes
 
 - Agents own their output artifacts and their manifest entries/receipts. They merge by stable `id` and preserve all foreign entries.

package/presets/_shared/core/meta/preset-pr-checklist.md

@@ -7,6 +7,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **SoT:** edits in `packages/…` (not only root `.cursor/`)
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
 - [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
+- [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis-next.mjs` + `check-mavis-adapter-map.mjs` for `next`; see `preset-twin-sync` § Mavis derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
 - [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
 - [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.