@bonesofspring/ai-rules 0.2.27 → 0.2.28

package/scripts/lib/generate-adapter-common.mjs

@@ -402,3 +402,185 @@ export function strongTierCell(profile) {
   }
   return base;
 }
+
+/**
+ * Short glosses for the rule stems most commonly cited in subagent prompts.
+ * Glosses are stack-neutral; per-platform stems (e.g. `react-ui`) only appear in
+ * the stacks that ship them.
+ */
+const RULE_GLOSS = {
+  'architecture-boundaries': 'layer boundaries and allowed imports',
+  'public-imports': '@/types, @/api barrels',
+  'react-ui': 'UI component style (no FC, no spread, decomposition)',
+  'store-rtk': 'Redux Toolkit patterns',
+  'react-next-anti-hallucination': 'phantom import banlist',
+  'feature-delivery-workflow': 'layer order, mockup gate, ux-design gate',
+  'reference-features': 'analog files first',
+  'anti-sycophancy-discipline': 'procedural anti-sycophancy rules',
+  'post-change-lint': 'lint/type-check after code edits',
+  'mcp-usage': 'when verifying third-party APIs (Context7)',
+};
+
+export const RULES_TO_LOAD_HEADING = '## Rules to load (subagent context)';
+
+const RULES_TO_LOAD_CLOSING_PREFIX = 'Also read matching ';
+
+/** Platform intro lines. One string per adapter so generators, the Claude codemod, and CI cannot drift. */
+export const PLATFORM_RULES_INTRO = {
+  claude:
+    'This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:',
+  opencode:
+    'This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:',
+  mavis:
+    'This subagent runs standalone (`mcode exec --file`) and inherits no global context. Read these rules explicitly before acting:',
+};
+
+/**
+ * Build the "## Rules to load (subagent context)" block injected into every
+ * generated agent. Subagents (OpenCode `Task`, Mavis `mcode exec --file`,
+ * Claude Code subagents) start blank and inherit no always-on context, so this
+ * block enumerates the rules the agent must Read explicitly before acting.
+ *
+ * Filtered to stems that exist for the stack (caller passes `availableStems`).
+ * Always-on rules are listed first, then zone rules. Bullet text is produced
+ * only here — callers use `expectedRulesToLoadBlock`.
+ *
+ * @param {{
+ *   rulesPath: string,          // flat rules dir, e.g. '.opencode/rules' or '.mavis/rules'.
+ *                                // Ignored when `pathForStem` is provided.
+ *   alwaysOn: string[],
+ *   zoneRules: string[],
+ *   availableStems: Set<string>,
+ *   intro: string,              // platform-specific single-sentence intro line
+ *   pathForStem?: (stem: string) => string | undefined,  // Claude uses nested layout
+ * }} params
+ */
+export function buildRulesToLoadBlock({
+  rulesPath,
+  alwaysOn,
+  zoneRules,
+  availableStems,
+  intro,
+  pathForStem,
+}) {
+  const seen = new Set();
+  const ordered = [];
+  for (const stem of [...(alwaysOn || []), ...(zoneRules || [])]) {
+    if (seen.has(stem)) continue;
+    if (!availableStems.has(stem)) continue;
+    seen.add(stem);
+    ordered.push(stem);
+  }
+  const bullets = ordered
+    .map((stem) => {
+      const gloss = RULE_GLOSS[stem];
+      const resolved = typeof pathForStem === 'function' ? pathForStem(stem) : undefined;
+      const ref = resolved || `${rulesPath}/${stem}.md`;
+      return gloss ? `- \`${ref}\` — ${gloss}` : `- \`${ref}\``;
+    })
+    .join('\n');
+  return [
+    RULES_TO_LOAD_HEADING,
+    '',
+    intro,
+    '',
+    bullets,
+    '',
+    'Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.',
+  ].join('\n');
+}
+
+/**
+ * Expected «Rules to load» block for one agent. Generators, the Claude inject
+ * codemod, and `check-claude-agent-blocks` all call this so bullet text cannot
+ * fork. `zoneRules` is the already-resolved list (profile zones, or
+ * `getZoneRulesForAgent` once roles apply).
+ */
+export function expectedRulesToLoadBlock(params) {
+  return buildRulesToLoadBlock(params);
+}
+
+const CLAUDE_MAPPING_ROW = /^\|\s*`([^`]+?\.mdc)`\s*\|\s*`([^`]+?\.md)`\s*\|/;
+
+/**
+ * Cursor stem → Claude topic path, from `rules/README.md` «Cursor → Claude mapping».
+ * Filename stems are not enough: twins such as `code-quality.md` keep the
+ * Cursor stem `code-quality-and-refactoring`. A row counts only when the file exists.
+ */
+export function indexClaudeRuleStems(claudeRulesDir) {
+  const stemToRelPath = new Map();
+  const availableStems = new Set();
+  const readmePath = path.join(claudeRulesDir, 'README.md');
+  if (fs.existsSync(readmePath)) {
+    let section = fs.readFileSync(readmePath, 'utf8');
+    const marker = '## Cursor → Claude mapping';
+    const markerAt = section.indexOf(marker);
+    if (markerAt >= 0) {
+      section = section.slice(markerAt);
+      const nextHeading = section.slice(marker.length).search(/\n## (?!#)/);
+      if (nextHeading >= 0) {
+        section = section.slice(0, marker.length + nextHeading);
+      }
+    }
+    for (const line of section.split('\n')) {
+      const match = line.match(CLAUDE_MAPPING_ROW);
+      if (!match) continue;
+      const stem = match[1].slice(0, -'.mdc'.length);
+      const relPath = match[2];
+      if (!fs.existsSync(path.join(claudeRulesDir, relPath))) continue;
+      if (!stemToRelPath.has(stem)) {
+        stemToRelPath.set(stem, relPath);
+        availableStems.add(stem);
+      }
+    }
+  }
+  const pathForStem = (stem) => {
+    const rel = stemToRelPath.get(stem);
+    return rel ? `.claude/rules/${rel}` : undefined;
+  };
+  return { availableStems, pathForStem };
+}
+
+/** Section from the heading through the closing "Also read matching" line, or ''. */
+export function extractRulesToLoadBlock(text) {
+  const start = text.indexOf(RULES_TO_LOAD_HEADING);
+  if (start < 0) return '';
+  const lines = text.slice(start).split('\n');
+  const end = lines.findIndex((line) => line.startsWith(RULES_TO_LOAD_CLOSING_PREFIX));
+  if (end < 0) return '';
+  return lines.slice(0, end + 1).join('\n');
+}
+
+/**
+ * Insert or replace the rules block immediately after YAML frontmatter.
+ * Returns null when the opening `---` is missing. Repairs a missing closer
+ * when a previous insert left the heading inside the frontmatter.
+ * Does not rewrite the agent body.
+ */
+export function upsertRulesToLoadBlock(markdown, block) {
+  if (!markdown.startsWith('---\n')) return null;
+  const rest = markdown.slice(4);
+  const headingAt = rest.indexOf(`\n${RULES_TO_LOAD_HEADING}`);
+  const closeAt = rest.indexOf('\n---\n');
+  let frontmatter;
+  let body;
+  if (closeAt >= 0 && (headingAt < 0 || closeAt < headingAt)) {
+    frontmatter = rest.slice(0, closeAt).replace(/\s+$/, '');
+    body = rest.slice(closeAt + '\n---\n'.length).replace(/^\n/, '');
+  } else if (headingAt >= 0) {
+    frontmatter = rest.slice(0, headingAt).replace(/\s+$/, '');
+    body = rest.slice(headingAt + 1);
+  } else {
+    return null;
+  }
+  const existing = extractRulesToLoadBlock(body);
+  if (existing) {
+    const at = body.indexOf(existing);
+    const before = body.slice(0, at).replace(/\s+$/, '');
+    const after = body.slice(at + existing.length).replace(/^\n+/, '');
+    body = `${before ? `${before}\n\n` : ''}${block}\n\n${after}`;
+  } else {
+    body = `${block}\n\n${body.replace(/^\n+/, '')}`;
+  }
+  return `---\n${frontmatter}\n---\n\n${body}`.replace(/\s+$/, '\n');
+}

package/scripts/lib/generate-mavis-adapter.mjs

@@ -5,6 +5,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  expectedRulesToLoadBlock,
+  PLATFORM_RULES_INTRO,
   countAgentRoleFiles,
   deriveAdapterStack,
   dropLeadingHeading,
@@ -25,7 +27,7 @@ import {
   stripFrontmatter,
   stripInstallSection,
 } from './generate-adapter-common.mjs';
-import { getStackProfile, parseStackArg } from './stack-platform-profiles.mjs';
+import { getStackProfile, getZoneRulesForAgent, parseStackArg } from './stack-platform-profiles.mjs';
 
 const libDirectory = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.join(libDirectory, '..', '..');
@@ -173,6 +175,19 @@ ${essential}
 
 See \`.mavis/rules/README.md\` for the full catalog and loading strategy.
 
+## Harness wiring
+
+- **Subagent rules** are re-declared inside every \`.mavis/agents/*.md\` via
+  the \`## Rules to load (subagent context)\` block (always-on + zone rules
+  filtered to stems that exist for this stack). Subagents run via
+  \`mcode exec --file\` and inherit no global context, so the block is the
+  authoritative mechanism.
+- **MiniMax Code has no permission/instructions config schema** (no analog
+  of OpenCode's \`opencode.json\` \`permission.bash\` or Claude Code's
+  \`.claude/settings.json\`). Universal \`git commit/push deny\` and
+  package-manager guards live in the agent prompt bodies; harness-level
+  enforcement is intentionally omitted.
+
 **Platform docs:** published with the \`@bonesofspring/ai-rules\` package
 (\`docs/MAVIS.md\`, \`docs/MAVIS-COMPATIBILITY.md\`) — **not** copied into
 the consumer repo. Source: https://github.com/bonesofspring/ai-rules
@@ -345,6 +360,16 @@ export function generateMavisStack(stack, { root = packageRoot } = {}) {
   const alwaysOn = new Set(profile.alwaysOn);
   const rewriteProse = (text) => finalizeMavisProse(text, stack);
 
+  const cursorRulesDir = path.join(root, 'presets', 'cursor', stack, 'rules');
+  const availableStems = new Set();
+  if (fs.existsSync(cursorRulesDir)) {
+    for (const entry of fs.readdirSync(cursorRulesDir)) {
+      if (entry.endsWith('.mdc')) {
+        availableStems.add(entry.slice(0, -'.mdc'.length));
+      }
+    }
+  }
+
   return deriveAdapterStack({
     platform: 'mavis',
     stack,
@@ -400,14 +425,25 @@ export function generateMavisStack(stack, { root = packageRoot } = {}) {
       },
       {
         match: (source) => source.startsWith('agents/') && source.endsWith('.md'),
-        map: ({ source, sourceText }) => ({
-          target: source,
-          content: transformMarkdown(sourceText, stack, { allowEmbedEntry: false }),
-          category: 'agents',
-          disposition: 'transform',
-          loadMode: 'manual',
-          reason: 'Native workspace agent discovery is unknown; attach with mcode exec --file',
-        }),
+        map: ({ source, sourceText }) => {
+          const body = transformMarkdown(sourceText, stack, { allowEmbedEntry: false });
+          const stem = path.basename(source, '.md');
+          const rulesBlock = expectedRulesToLoadBlock({
+            rulesPath: '.mavis/rules',
+            alwaysOn: profile.alwaysOn,
+            zoneRules: getZoneRulesForAgent(stack, stem),
+            availableStems,
+            intro: PLATFORM_RULES_INTRO.mavis,
+          });
+          return {
+            target: source,
+            content: `${rulesBlock}\n\n${body}`,
+            category: 'agents',
+            disposition: 'transform',
+            loadMode: 'manual',
+            reason: 'Native workspace agent discovery is unknown; attach with mcode exec --file',
+          };
+        },
       },
       {
         match: (source) => source.startsWith('skills/') && source.endsWith('/SKILL.md'),

package/scripts/lib/generate-opencode-adapter.mjs

@@ -5,6 +5,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  expectedRulesToLoadBlock,
+  PLATFORM_RULES_INTRO,
   countAgentRoleFiles,
   deriveAdapterStack,
   dropLeadingHeading,
@@ -27,6 +29,7 @@ import {
 } from './generate-adapter-common.mjs';
 import {
   AGENT_WRITE_SCOPES,
+  getZoneRulesForAgent,
   getStackProfile,
   parseStackArg,
   REVIEW_AGENTS,
@@ -131,7 +134,7 @@ function yamlEditPermission(canEditProduction, extraScopes) {
   return `permission:\n  edit:\n    "*": deny\n${globLines}`;
 }
 
-function transformAgent(source, sourceText, stack, developerAgents) {
+function transformAgent(source, sourceText, stack, developerAgents, profile, availableStems) {
   const { frontmatter, body } = stripFrontmatter(sourceText);
   const fields = parseFrontmatterFields(frontmatter);
   const stem = path.basename(source, '.md');
@@ -141,7 +144,14 @@ function transformAgent(source, sourceText, stack, developerAgents) {
   const description = fields.description || stem;
   const header = `---\nname: ${stem}\ndescription: ${yamlString(description)}\nmode: subagent\n${permission}\n---\n\n`;
   const transformed = finalizeOpencodeProse(body, stack);
-  let withNote = transformed;
+  const rulesBlock = expectedRulesToLoadBlock({
+    rulesPath: '.opencode/rules',
+    alwaysOn: profile?.alwaysOn ?? [],
+    zoneRules: getZoneRulesForAgent(stack, stem),
+    availableStems: availableStems ?? new Set(),
+    intro: PLATFORM_RULES_INTRO.opencode,
+  });
+  let withNote = `${rulesBlock}\n\n${transformed}`;
   if (!canEditProduction) {
     let leadIn;
     if (extraScopes.length > 0) {
@@ -152,7 +162,7 @@ function transformAgent(source, sourceText, stack, developerAgents) {
     } else {
       leadIn = 'Write only team artifacts under `.ai.local/team/**`. Do not edit production code.';
     }
-    withNote = `${leadIn}\n\n${transformed}`;
+    withNote = `${leadIn}\n\n${rulesBlock}\n\n${transformed}`;
   }
   return `${header}${withNote.endsWith('\n') ? withNote : `${withNote}\n`}`;
 }
@@ -188,7 +198,7 @@ function transformCommand(sourceText, stack) {
   return `${header}${next.endsWith('\n') ? next : `${next}\n`}`;
 }
 
-function cursorMcpToOpencode(sourceText) {
+function cursorMcpToOpencode(sourceText, profile, availableStems) {
   const parsed = JSON.parse(sourceText);
   const mcp = {};
   for (const [id, server] of Object.entries(parsed.mcpServers || {})) {
@@ -208,7 +218,25 @@ function cursorMcpToOpencode(sourceText) {
       mcp[id] = mapped;
     }
   }
-  return `${JSON.stringify({ $schema: 'https://opencode.ai/config.json', mcp }, null, 2)}\n`;
+  // Compact instructions: always-on rule paths + .opencode/AGENTS.md (root
+  // AGENTS.md is auto-loaded natively). Filter to stems that exist for the
+  // stack so consumers don't see phantom references. Permission.bash enforces
+  // the harness-level "no commit/push" and JS-stack package-manager rules.
+  // mergeOpencodeConfig unions preset instruction paths and fills missing
+  // bash keys on re-init; consumer extras and same-key overrides win.
+  const instructions = [
+    '.opencode/AGENTS.md',
+    ...(profile?.alwaysOn ?? [])
+      .filter((stem) => availableStems?.has(stem))
+      .map((stem) => `.opencode/rules/${stem}.md`),
+  ];
+  const out = {
+    $schema: 'https://opencode.ai/config.json',
+    instructions,
+    permission: { bash: profile?.bashPermission ?? {} },
+    mcp,
+  };
+  return `${JSON.stringify(out, null, 2)}\n`;
 }
 
 function opencodeEntryTitle(sourceText) {
@@ -253,6 +281,19 @@ ${essential}
 
 See \`.opencode/rules/README.md\` for the full catalog and loading strategy.
 
+## Harness wiring
+
+- \`opencode.json\` carries a compact \`instructions\` list (always-on rule
+  paths + \`.opencode/AGENTS.md\`) and a harness-level \`permission.bash\`
+  block. On re-init, \`mergeOpencodeConfig\` unions preset instruction paths
+  into the consumer list and fills missing bash keys. Extra paths and
+  same-key overrides stay.
+- **Subagent rules** are re-declared inside every \`.opencode/agents/*.md\`
+  via the \`## Rules to load (subagent context)\` block (always-on + zone
+  rules filtered to stems that exist for this stack). \`Task\`-launched
+  subagents do not inherit the parent's \`instructions\`, so this block
+  is the authoritative mechanism.
+
 **Platform docs:** published with the \`@bonesofspring/ai-rules\` package
 (\`docs/OPENCODE.md\`, \`docs/OPENCODE-COMPATIBILITY.md\`) — **not** copied into
 the consumer repo. Source: https://github.com/bonesofspring/ai-rules
@@ -267,7 +308,8 @@ npx @bonesofspring/ai-rules init opencode --preset ${stack}
 
 Copies rules, commands, agents, hooks, skills, \`OPENCODE.md\` →
 \`.opencode/AGENTS.md\`, \`MCP.md\`, \`opencode.json\` → project \`opencode.json\`
-(\`mcp\` merge), plus \`REPO_AGENTS.md\` → root \`AGENTS.md\`. Seeds \`.ai.local/team/\`.
+(\`mcp\` merge, instruction-path union, missing bash keys), plus
+\`REPO_AGENTS.md\` → root \`AGENTS.md\`. Seeds \`.ai.local/team/\`.
 `;
 }
 
@@ -377,8 +419,13 @@ Plain Markdown. OpenCode does **not** auto-load these files. Root \`AGENTS.md\`
 and \`.opencode/AGENTS.md\` list four essential paths to Read immediately; the
 rest are lazy-loaded when the task matches.
 
-Do not put this catalog into \`opencode.json\` \`instructions\` as the only
-always-on path (V2 may ignore that field).
+Subagent tasks (\`Task\`/\`@name\`) start blank and never read these rule files;
+the **authoritative** mechanism is the \`## Rules to load (subagent context)\`
+block injected into every \`.opencode/agents/*.md\`. The preset also adds a
+compact \`opencode.json\` \`instructions\` list (alwaysOn paths +
+\`.opencode/AGENTS.md\`) as a hedge for the parent context, with
+\`bin/opencode-install.js\` filling-if-absent on re-init; do **not** treat
+\`instructions\` as the only always-on path (V2 may ignore the field).
 
 ## Essential (entry-critical)
 
@@ -427,6 +474,16 @@ export function generateOpencodeStack(stack, { root = packageRoot } = {}) {
   const developerAgents = new Set(profile.developerAgents);
   const rewriteProse = (text) => finalizeOpencodeProse(text, stack);
 
+  const cursorRulesDir = path.join(root, 'presets', 'cursor', stack, 'rules');
+  const availableStems = new Set();
+  if (fs.existsSync(cursorRulesDir)) {
+    for (const entry of fs.readdirSync(cursorRulesDir)) {
+      if (entry.endsWith('.mdc')) {
+        availableStems.add(entry.slice(0, -'.mdc'.length));
+      }
+    }
+  }
+
   return deriveAdapterStack({
     platform: 'opencode',
     stack,
@@ -484,7 +541,7 @@ export function generateOpencodeStack(stack, { root = packageRoot } = {}) {
         match: (source) => source.startsWith('agents/') && source.endsWith('.md'),
         map: ({ source, sourceText }) => ({
           target: source,
-          content: transformAgent(source, sourceText, stack, developerAgents),
+          content: transformAgent(source, sourceText, stack, developerAgents, profile, availableStems),
           category: 'agents',
           disposition: 'transform',
           loadMode: 'native-team',
@@ -534,11 +591,11 @@ export function generateOpencodeStack(stack, { root = packageRoot } = {}) {
         match: (source) => source === 'mcp.json',
         map: ({ sourceText }) => ({
           target: 'opencode.json',
-          content: cursorMcpToOpencode(sourceText),
+          content: cursorMcpToOpencode(sourceText, profile, availableStems),
           category: 'mcp',
           disposition: 'transform',
           loadMode: 'manual',
-          reason: 'Cursor mcp.json → opencode.json mcp (local/remote types)',
+          reason: 'Cursor mcp.json → opencode.json mcp (local/remote types); emits permission.bash + compact instructions',
         }),
       },
       {