@bonesofspring/ai-rules 0.2.26 → 0.2.28

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

@@ -5,9 +5,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  expectedRulesToLoadBlock,
+  PLATFORM_RULES_INTRO,
   countAgentRoleFiles,
   deriveAdapterStack,
   dropLeadingHeading,
+  extractStackNotesSection,
   isEmbedEntryBody,
   parseFrontmatterFields,
   readSiblingReadme,
@@ -26,6 +29,7 @@ import {
 } from './generate-adapter-common.mjs';
 import {
   AGENT_WRITE_SCOPES,
+  getZoneRulesForAgent,
   getStackProfile,
   parseStackArg,
   REVIEW_AGENTS,
@@ -85,7 +89,11 @@ function stripEmbeddedCatalogLine(body) {
   );
 }
 
-function transformMarkdown(sourceText, stack, { allowEmbedEntry = true } = {}) {
+function transformMarkdown(
+  sourceText,
+  stack,
+  { allowEmbedEntry = true, preserveStackNotes = true } = {},
+) {
   const rewriteProse = (text) => finalizeOpencodeProse(text, stack);
   const { body } = stripFrontmatter(sourceText);
   const stem =
@@ -99,7 +107,13 @@ function transformMarkdown(sourceText, stack, { allowEmbedEntry = true } = {}) {
     }
     const coreBody = fs.readFileSync(corePath, 'utf8').trimEnd();
     const marker = `<!-- shared-core: ${stem} -->`;
+    // Preserve the Cursor adapter's `## Stack notes` (stack-specific paths, runners,
+    // selectors) instead of replacing the whole body with the generic core.
+    const stackNotes = preserveStackNotes ? extractStackNotesSection(body) : '';
     next = `${marker}\n\n${coreBody}\n`;
+    if (stackNotes) {
+      next += `\n${stackNotes}\n`;
+    }
     next = rewriteConsumerPaths(next);
   } else {
     next = rewriteProse(body);
@@ -120,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');
@@ -130,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) {
@@ -141,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`}`;
 }
@@ -160,7 +181,7 @@ function transformSkill(sourceText, stack) {
   const fields = parseFrontmatterFields(frontmatter);
   const name = fields.name || '';
   const description = fields.description || '';
-  const header = `---\nname: ${name}\ndescription: ${description}\n---\n\n`;
+  const header = `---\nname: ${name}\ndescription: ${yamlString(description)}\n---\n\n`;
   const transformed = finalizeOpencodeProse(body, stack);
   return `${header}${transformed.endsWith('\n') ? transformed : `${transformed}\n`}`;
 }
@@ -173,11 +194,11 @@ function transformCommand(sourceText, stack) {
   if (!next.includes('$ARGUMENTS')) {
     next = `## Invocation arguments\n\n$ARGUMENTS\n\n${next}`;
   }
-  const header = `---\ndescription: ${description}\n---\n\n`;
+  const header = `---\ndescription: ${yamlString(description)}\n---\n\n`;
   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 || {})) {
@@ -197,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) {
@@ -242,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
@@ -256,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/\`.
 `;
 }
 
@@ -366,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)
 
@@ -416,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,
@@ -449,7 +517,11 @@ export function generateOpencodeStack(stack, { root = packageRoot } = {}) {
         match: (source) => source.startsWith('rules/') && source.endsWith('.mdc'),
         map: ({ source, sourceText }) => {
           const stem = path.basename(source, '.mdc');
-          let markdown = transformMarkdown(sourceText, stack);
+          // The orchestrator Stack notes carry Cursor-only model pins / packaging;
+          // transformOrchestrator injects a platform-neutral note instead.
+          let markdown = transformMarkdown(sourceText, stack, {
+            preserveStackNotes: stem !== 'agent-team-orchestrator',
+          });
           if (stem === 'agent-team-orchestrator') {
             markdown = transformOrchestrator(markdown);
           }
@@ -469,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',
@@ -519,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',
         }),
       },
       {

package/scripts/lib/stack-platform-profiles.mjs

@@ -34,7 +34,296 @@ const BACKEND_DEVELOPER_AGENTS = [
 
 const QUALITY_OVERLAY = ['code-quality-and-refactoring', 'ai-local-overlay'];
 
-/** @typedef {{ title: string, family: string, alwaysOn: string[], developerAgents: string[] }} StackProfile */
+/**
+ * Requestable-but-critical rules a subagent must Read explicitly, because a
+ * `Task`/`mcode exec`/Claude subagent starts blank and inherits no always-on
+ * context. Filtered to stems that exist for the stack at generation time.
+ */
+const NEXT_ZONE_RULES = [
+  'architecture-boundaries',
+  'public-imports',
+  'react-ui',
+  'store-rtk',
+  'react-next-anti-hallucination',
+  'no-props-spread',
+  'no-type-assertion-as-import-export',
+  'feature-delivery-workflow',
+  'reference-features',
+  'anti-sycophancy-discipline',
+  'post-change-lint',
+  'mcp-usage',
+];
+
+const UNIVERSAL_ZONE_RULES = [
+  'architecture-boundaries',
+  'feature-delivery-workflow',
+  'reference-features',
+  'anti-sycophancy-discipline',
+  'post-change-lint',
+  'mcp-usage',
+];
+
+/**
+ * Glob-only Next stems absent from NEXT_ZONE_RULES. Only the implementer role
+ * receives them — the roles that edit those zones — not every agent.
+ */
+const NEXT_GLOB_ONLY_ZONE_RULES = [
+  'architecture-boundaries-ui',
+  'arrow-functions',
+  'css-property-order-stylelint',
+  'layer-barrel-exports',
+  'navigation-router-stack',
+  'navigation-router-ui',
+  'next-app-router',
+  'react-a11y-coding',
+  'types-jsdoc',
+];
+
+const FRONTEND_API_ZONE_RULES = ['api-services', 'http-client'];
+const HEX_API_ZONE_RULES = ['api-http', 'api-grpc'];
+const HEX_DOMAIN_ZONE_RULES = [
+  'domain-layer',
+  'application-usecases',
+  'ports-interfaces',
+  'adapters-driven',
+  'adapters-driving',
+  'composition-root',
+  'module-public-api',
+  'persistence-adapters',
+  'messaging-adapters',
+];
+
+/** Domain stems beyond UNIVERSAL_ZONE_RULES for the implementer role. */
+const DOMAIN_ZONE_RULES = {
+  next: [
+    ...NEXT_ZONE_RULES.filter((stem) => !UNIVERSAL_ZONE_RULES.includes(stem)),
+    ...NEXT_GLOB_ONLY_ZONE_RULES,
+  ],
+  nuxt: [
+    'public-imports',
+    'vue-ui',
+    'store-pinia',
+    'vue-nuxt-anti-hallucination',
+    'no-v-bind-spread',
+    'no-type-assertion-as-import-export',
+    'architecture-boundaries-ui',
+    'css-property-order-stylelint',
+    'layer-barrel-exports',
+    'navigation-router-stack',
+    'navigation-router-ui',
+    'nuxt-pages-routing',
+    'vue-a11y-coding',
+    'types-jsdoc',
+    'script-setup-conventions',
+  ],
+  svelte: [
+    'public-imports',
+    'svelte-ui',
+    'store-svelte',
+    'svelte-sveltekit-anti-hallucination',
+    'no-rest-props-spread',
+    'no-type-assertion-as-import-export',
+    'architecture-boundaries-ui',
+    'css-property-order-stylelint',
+    'layer-barrel-exports',
+    'navigation-router-stack',
+    'navigation-router-ui',
+    'sveltekit-routing',
+    'svelte-a11y-coding',
+    'types-jsdoc',
+    'svelte-script-conventions',
+  ],
+  'ios-swift': [
+    'swiftui-ui',
+    'swift-conventions',
+    'state-and-viewmodels',
+    'navigation-coordinators',
+    'persistence-data',
+    'module-public-api',
+  ],
+  'android-kotlin': [
+    'compose-ui',
+    'kotlin-conventions',
+    'state-and-viewmodels',
+    'navigation-feature-launcher',
+    'persistence-data',
+    'module-public-api',
+    'di-dagger-feature-holders',
+  ],
+  go: [...HEX_DOMAIN_ZONE_RULES, 'go-conventions'],
+  java: [...HEX_DOMAIN_ZONE_RULES, 'java-conventions'],
+  'php-hexagonal': [...HEX_DOMAIN_ZONE_RULES, 'php-conventions'],
+  'php-laravel': [
+    'domain-layer',
+    'actions-services',
+    'eloquent-persistence',
+    'events-listeners',
+    'jobs-queues',
+    'laravel-conventions',
+    'module-public-api',
+    'policies-authorization',
+    'service-providers',
+  ],
+  'mcp-ts': [
+    'mcp-tool-design',
+    'mcp-contract-testing',
+    'mcp-auth-secrets',
+    'mcp-transport-packaging',
+    'mcp-ts-conventions',
+  ],
+};
+
+const API_ZONE_RULES = {
+  next: FRONTEND_API_ZONE_RULES,
+  nuxt: FRONTEND_API_ZONE_RULES,
+  svelte: FRONTEND_API_ZONE_RULES,
+  'ios-swift': ['networking-services'],
+  'android-kotlin': ['networking-data'],
+  go: HEX_API_ZONE_RULES,
+  java: HEX_API_ZONE_RULES,
+  'php-hexagonal': HEX_API_ZONE_RULES,
+  'php-laravel': ['http-layer', 'routes-api', 'form-requests'],
+  'mcp-ts': [],
+};
+
+const E2E_ZONE_RULES = {
+  next: ['playwright-agents', 'tests-e2e-structure'],
+  nuxt: ['playwright-agents', 'tests-e2e-structure'],
+  svelte: ['playwright-agents', 'tests-e2e-structure'],
+  'ios-swift': ['tests-ui'],
+  'android-kotlin': ['tests-ui'],
+  go: ['tests-integration', 'tests-e2e'],
+  java: ['tests-integration', 'tests-e2e'],
+  'php-hexagonal': ['tests-integration', 'tests-e2e'],
+  'php-laravel': ['tests-integration', 'tests-e2e'],
+  'mcp-ts': [],
+};
+
+const TOOLING_ZONE_RULES = {
+  next: [],
+  nuxt: [],
+  svelte: [],
+  'ios-swift': ['xcode-tooling', 'post-change-build'],
+  'android-kotlin': ['gradle-tooling', 'post-change-build'],
+  go: ['go-tooling', 'post-change-test'],
+  java: ['java-tooling', 'post-change-test'],
+  'php-hexagonal': ['php-tooling', 'post-change-test'],
+  'php-laravel': ['php-tooling', 'post-change-test'],
+  'mcp-ts': ['mcp-ts-tooling', 'post-change-test'],
+};
+
+const IMPLEMENTER_AGENTS = new Set(['feature-developer', 'debugger', 'ci-investigator']);
+
+function dedupeStems(stems) {
+  const seen = new Set();
+  const ordered = [];
+  for (const stem of stems) {
+    if (seen.has(stem)) continue;
+    seen.add(stem);
+    ordered.push(stem);
+  }
+  return ordered;
+}
+
+function zoneRulesForRole(stack, role) {
+  const domain = DOMAIN_ZONE_RULES[stack] ?? [];
+  const api = API_ZONE_RULES[stack] ?? [];
+  const tooling = TOOLING_ZONE_RULES[stack] ?? [];
+  const e2e = E2E_ZONE_RULES[stack] ?? [];
+  switch (role) {
+    case 'implementer':
+      return dedupeStems([...UNIVERSAL_ZONE_RULES, ...domain, ...api, ...tooling]);
+    case 'reviewer':
+      return dedupeStems([...UNIVERSAL_ZONE_RULES, 'code-review-mr']);
+    case 'unit-test':
+      return dedupeStems([...UNIVERSAL_ZONE_RULES, 'tests-unit']);
+    case 'e2e':
+      return dedupeStems([...UNIVERSAL_ZONE_RULES, ...e2e]);
+    case 'qa':
+      return dedupeStems([...UNIVERSAL_ZONE_RULES, 'tests-unit', ...e2e]);
+    case 'api-contract':
+      return dedupeStems([...UNIVERSAL_ZONE_RULES, ...api]);
+    case 'verifier':
+      return dedupeStems([...UNIVERSAL_ZONE_RULES, ...tooling]);
+    default:
+      return [...UNIVERSAL_ZONE_RULES];
+  }
+}
+
+const ROLE_KEYS = [
+  'implementer',
+  'reviewer',
+  'unit-test',
+  'e2e',
+  'qa',
+  'api-contract',
+  'verifier',
+  'default',
+];
+
+/** @type {Record<string, Record<string, string[]>>} */
+export const zoneRulesByRole = Object.fromEntries(
+  Object.keys(DOMAIN_ZONE_RULES).map((stack) => [
+    stack,
+    Object.fromEntries(ROLE_KEYS.map((role) => [role, zoneRulesForRole(stack, role)])),
+  ]),
+);
+
+/**
+ * Smallest stem→role map that keeps the 9 Next glob stems on production
+ * editors only. Test prefixes win over the developer-agent write list so
+ * unit-test roles do not inherit the UI bundle. qa-tester writes tests, not
+ * UI zones, so it is not an implementer.
+ */
+export function resolveAgentRole(agentStem) {
+  if (agentStem === 'code-reviewer') return 'reviewer';
+  if (agentStem.startsWith('unit-test-')) return 'unit-test';
+  if (
+    agentStem.startsWith('playwright-test-') ||
+    agentStem.startsWith('xcuitest-test-') ||
+    agentStem.startsWith('instrumentation-test-') ||
+    agentStem.startsWith('integration-test-')
+  ) {
+    return 'e2e';
+  }
+  if (agentStem === 'api-contract-reviewer') return 'api-contract';
+  if (agentStem === 'qa-tester') return 'qa';
+  if (agentStem === 'build-verifier') return 'verifier';
+  if (IMPLEMENTER_AGENTS.has(agentStem)) return 'implementer';
+  return 'default';
+}
+
+/**
+ * Universal harness-level `permission.bash` guards. Apply to every stack.
+ * `git commit/push` are universally denied to honor the "human commits" contract
+ * from root `AGENTS.md`; package-manager enforcement is stack-driven via
+ * `STACK_BASH_PERMISSIONS_OVERRIDES`.
+ */
+const UNIVERSAL_BASH_PERMISSION = {
+  '*': 'allow',
+  'git commit *': 'deny',
+  'git push *': 'deny',
+};
+
+const JS_STACK_PACKAGE_GUARDS = {
+  'npm *': 'ask',
+  'npx *': 'ask',
+  'pnpm *': 'ask',
+  'bun *': 'ask',
+  'npx jest*': 'deny',
+};
+
+const STACK_BASH_PERMISSIONS_OVERRIDES = {
+  next: { ...JS_STACK_PACKAGE_GUARDS },
+  nuxt: { ...JS_STACK_PACKAGE_GUARDS },
+  svelte: { ...JS_STACK_PACKAGE_GUARDS },
+};
+
+/**
+ * `zoneRules` is the pre-S1 homogeneous catalog (still the default shape of the
+ * profile). Subagent «Rules to load» blocks use `getZoneRulesForAgent` instead.
+ * @typedef {{ title: string, family: string, alwaysOn: string[], zoneRules: string[], developerAgents: string[], bashPermission: Record<string,string> }} StackProfile
+ */
 
 /** @type {Record<string, StackProfile>} */
 export const STACK_PROFILES = {
@@ -42,24 +331,32 @@ export const STACK_PROFILES = {
     title: 'Next.js',
     family: 'frontend',
     alwaysOn: ['next-app-core', 'package-manager', ...QUALITY_OVERLAY],
+    zoneRules: NEXT_ZONE_RULES,
     developerAgents: FRONTEND_DEVELOPER_AGENTS,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION, ...JS_STACK_PACKAGE_GUARDS },
   },
   nuxt: {
     title: 'Nuxt 3',
     family: 'frontend',
     alwaysOn: ['nuxt-app-core', 'package-manager', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
     developerAgents: FRONTEND_DEVELOPER_AGENTS,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION, ...JS_STACK_PACKAGE_GUARDS },
   },
   svelte: {
     title: 'SvelteKit',
     family: 'frontend',
     alwaysOn: ['svelte-app-core', 'package-manager', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
     developerAgents: FRONTEND_DEVELOPER_AGENTS,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION, ...JS_STACK_PACKAGE_GUARDS },
   },
   'ios-swift': {
     title: 'iOS Swift',
     family: 'ios',
     alwaysOn: ['ios-app-core', 'architecture-boundaries', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION },
     developerAgents: [
       ...MOBILE_DEVELOPER_BASE,
       'xcuitest-test-generator',
@@ -70,6 +367,8 @@ export const STACK_PROFILES = {
     title: 'Android Kotlin',
     family: 'android',
     alwaysOn: ['android-app-core', 'architecture-boundaries', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION },
     developerAgents: [
       ...MOBILE_DEVELOPER_BASE,
       'instrumentation-test-generator',
@@ -80,31 +379,41 @@ export const STACK_PROFILES = {
     title: 'Go hexagonal',
     family: 'backend',
     alwaysOn: ['go-app-core', 'architecture-boundaries', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION },
     developerAgents: BACKEND_DEVELOPER_AGENTS,
   },
   java: {
     title: 'Java hexagonal',
     family: 'backend',
     alwaysOn: ['java-app-core', 'architecture-boundaries', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION },
     developerAgents: BACKEND_DEVELOPER_AGENTS,
   },
   'php-hexagonal': {
     title: 'PHP hexagonal',
     family: 'backend',
     alwaysOn: ['php-app-core', 'architecture-boundaries', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION },
     developerAgents: BACKEND_DEVELOPER_AGENTS,
   },
   'php-laravel': {
     title: 'Laravel',
     family: 'backend',
     alwaysOn: ['laravel-app-core', 'architecture-boundaries', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION },
     developerAgents: BACKEND_DEVELOPER_AGENTS,
   },
   'mcp-ts': {
     title: 'TypeScript MCP',
     family: 'mcp-ts',
     alwaysOn: ['mcp-ts-app-core', 'mcp-server-boundaries', ...QUALITY_OVERLAY],
+    zoneRules: UNIVERSAL_ZONE_RULES,
     developerAgents: ['feature-developer'],
+    bashPermission: { ...UNIVERSAL_BASH_PERMISSION },
   },
 };
 
@@ -126,6 +435,17 @@ export function getStackProfile(stack) {
   return profile;
 }
 
+/** Role-trimmed zone stems for one agent. Filtered again to stems that exist at generation time. */
+export function getZoneRulesForAgent(stack, agentStem) {
+  getStackProfile(stack);
+  const role = resolveAgentRole(agentStem);
+  const rules = zoneRulesByRole[stack]?.[role];
+  if (!rules) {
+    throw new Error(`no zone rules for stack "${stack}" role "${role}"`);
+  }
+  return rules;
+}
+
 export function parseStackArg(argv, { required = true } = {}) {
   let stack;
   for (let index = 0; index < argv.length; index += 1) {

package/scripts/sync-claude-harness-wiring.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Append a "## Harness wiring" section to `presets/claude/<stack>/CLAUDE.md`
+ * for every released stack. Idempotent: skips files that already contain
+ * the heading. Claude presets are hand-maintained; this keeps them aligned
+ * with the cross-platform harness story (OpenCode/Mavis parity work).
+ *
+ * Usage: node scripts/sync-claude-harness-wiring.mjs
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadReleasedStacks } from './lib/generate-adapter-common.mjs';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(scriptDirectory, '..');
+const presetsRoot = path.join(packageRoot, 'presets');
+const HEADING = '## Harness wiring';
+
+const SECTION = `
+## Harness wiring
+
+- **Subagent rules** are re-declared inside every \`.claude/agents/*.md\` via
+  the \`## Rules to load (subagent context)\` block (always-on + zone rules
+  filtered to stems that exist for this stack, using the nested
+  \`.claude/rules/<topic>/<stem>.md\` paths). Claude Code subagents inherit
+  no parent context, so this block is the authoritative mechanism.
+- \`.claude/settings.json\` ships harness-level denials (universal
+  \`git commit/push deny\`; JS stacks also \`npx jest* deny\` and \`npm/npx/pnpm/bun\`
+  ask). Re-init overwrites the file (consumer can edit afterwards); mirror
+  with root \`AGENTS.md\` if you change the harness.
+`;
+
+function sync(stack) {
+  const dest = path.join(presetsRoot, 'claude', stack, 'CLAUDE.md');
+  if (!fs.existsSync(dest)) {
+    console.log(`skip claude/${stack}: no CLAUDE.md`);
+    return;
+  }
+  const text = fs.readFileSync(dest, 'utf8');
+  if (text.includes(HEADING)) {
+    console.log(`claude/${stack}: already has ${HEADING}`);
+    return;
+  }
+  const next = text.replace(/\n+$/, '\n') + SECTION;
+  fs.writeFileSync(dest, next);
+  console.log(`claude/${stack}: appended ${HEADING}`);
+}
+
+function main() {
+  for (const stack of loadReleasedStacks(presetsRoot, 'opencode')) {
+    sync(stack);
+  }
+}
+
+main();