ai-codebase-registry 1.0.0

package/README.md

@@ -0,0 +1,137 @@
+# ai-codebase-registry
+
+Registry-driven AI-agent infrastructure for codebases. Auto-generates machine-readable metadata, dependency graphs, side-effects tracking, and query APIs for AI coding agents.
+
+Supports **TypeScript**, **Swift**, **Kotlin**, and **Python** projects.
+
+## Installation
+
+```bash
+npm install --save-dev ai-codebase-registry
+```
+
+## Quick Start
+
+```bash
+# Initialize config file
+npx ai-registry init
+
+# Generate registry from source
+npx ai-registry generate
+
+# Validate @ai-meta coverage
+npx ai-registry validate
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `ai-registry init` | Scaffold `ai-registry.config.mjs` for a new project |
+| `ai-registry generate` | Rebuild all registry files from source |
+| `ai-registry validate` | Check `@ai-meta` coverage and report gaps |
+| `ai-registry query` | Query registry data (files, deps, impact, coverage) |
+| `ai-registry add-headers` | Auto-add `@ai-meta` headers to files missing them |
+
+## Configuration
+
+Create `ai-registry.config.mjs` in your project root:
+
+### TypeScript / JavaScript
+
+```js
+export default {
+  name: 'my-project',
+  scanDirs: [{ dir: 'src', prefix: 'src' }],
+  extensions: ['.ts', '.tsx'],
+  skipDirs: ['node_modules', 'dist'],
+  aliases: { '@/': 'src/' },
+  registryDir: '_registry',
+};
+```
+
+### Swift (iOS / macOS)
+
+```js
+export default {
+  name: 'my-ios-app',
+  scanDirs: [
+    { dir: 'Sources', prefix: 'Sources' },
+    { dir: 'Tests', prefix: 'Tests' },
+  ],
+  extensions: ['.swift'],
+  skipDirs: ['build', 'Pods', '.build', 'DerivedData'],
+  language: 'swift',
+  fieldMap: { mutations: 'side-effects', dependencies: 'depends-on' },
+  generators: ['manifest', 'semantic-ids', 'side-effects', 'features'],
+  registryDir: '_registry',
+};
+```
+
+## Config Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | string | `'my-project'` | Project name |
+| `description` | string | `''` | Project description |
+| `scanDirs` | array | `[{ dir: 'src', prefix: 'src' }]` | Directories to scan |
+| `extensions` | array | `['.ts', '.tsx']` | File extensions to include |
+| `skipDirs` | array | `['node_modules', ...]` | Directories to skip |
+| `language` | string | `'typescript'` | `'typescript'` \| `'swift'` \| `'kotlin'` \| `'python'` |
+| `fieldMap` | object | `{}` | Field name normalization map |
+| `generators` | array\|null | `null` (all) | Which generators to run |
+| `aliases` | object | `{}` | Import alias map (TS only) |
+| `router` | string | `'none'` | Router type for route extraction |
+| `dataStore` | string | `'none'` | Data store type |
+| `registryDir` | string | `'_registry'` | Output directory |
+| `agent` | string | `'claude-code'` | Target AI agent |
+| `claudemd` | boolean | `true` | Generate CLAUDE.md references |
+
+## Multi-Language Support
+
+The parser auto-detects the comment style from file content:
+
+| Language | Comment Style | Field Syntax |
+|----------|--------------|--------------|
+| TypeScript/JS | `/** @ai-meta ... */` | `@field value` |
+| Swift | `/// @ai-meta ...` | `field: value` |
+| Kotlin/Go | `// @ai-meta ...` | `field: value` or `@field value` |
+
+### Field Normalization
+
+Use `fieldMap` to map project-specific field names to canonical ones:
+
+```js
+fieldMap: {
+  mutations: 'side-effects',    // Swift uses "mutations:", canonical is "side-effects"
+  dependencies: 'depends-on',   // Swift uses "dependencies:", canonical is "depends-on"
+}
+```
+
+## Generated Registry Files
+
+| File | Description |
+|------|-------------|
+| `manifest.json` | Every source file with domain, type, purpose, imports |
+| `semantic-ids.json` | Stable entity ID to file path mapping |
+| `deps.json` | Import dependency graph (TypeScript only) |
+| `side-effects.json` | Mutation/trigger to downstream effects graph |
+| `features.json` | Feature inventory by domain |
+
+## Deep Import Paths
+
+| Import Path | Purpose |
+|-------------|---------|
+| `ai-codebase-registry` | Main entry (re-exports) |
+| `ai-codebase-registry/core/file-discovery` | Recursive file scanning |
+| `ai-codebase-registry/core/ai-meta-parser` | `@ai-meta` header parsing |
+| `ai-codebase-registry/core/domain-detector` | Domain detection from paths |
+| `ai-codebase-registry/core/type-detector` | File type detection |
+| `ai-codebase-registry/core/semantic-id` | Semantic ID generation |
+| `ai-codebase-registry/parsers` | Parser barrel export |
+| `ai-codebase-registry/generators` | Generator barrel export |
+| `ai-codebase-registry/query` | Registry query engine |
+
+## License
+
+MIT

package/bin/add-headers.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:cli-add-headers
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects writes:filesystem:source-files
+ * @stability medium
+ * @complexity complex
+ * @token-budget 300
+ * @purpose CLI command: auto-add @ai-meta headers to source files missing them
+ *
+ * @filechangelog
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Created add-headers CLI stub
+ */
+
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { loadConfig } from '../lib/core/config-loader.mjs';
+import { collectFiles } from '../lib/core/file-discovery.mjs';
+
+const C = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m',
+};
+
+const isDryRun = process.argv.includes('--dry-run');
+
+async function main() {
+  const rootDir = resolve('.');
+  const config = await loadConfig(rootDir);
+
+  console.log(`${C.bold}ai-codebase-registry add-headers${C.reset}`);
+  console.log(isDryRun ? `${C.yellow}DRY RUN — no files will be modified${C.reset}\n` : '\n');
+
+  // Discover files
+  const allFiles = [];
+  const extensions = new Set(config.extensions);
+  const skipDirs = new Set(config.skipDirs);
+
+  for (const { dir, prefix } of config.scanDirs) {
+    if (existsSync(dir)) {
+      allFiles.push(...collectFiles(dir, prefix, { extensions, skipDirs }));
+    }
+  }
+
+  console.log(`Scanned ${allFiles.length} files`);
+  console.log(`${C.dim}Note: For full header injection, use the project's scripts/add-ai-meta-headers.mjs${C.reset}`);
+  console.log(`${C.dim}This command provides the framework; the actual injection logic is in the project script.${C.reset}`);
+
+  // Count files without @ai-meta
+  let missing = 0;
+  for (const { fullPath } of allFiles) {
+    try {
+      const { readFileSync } = await import('fs');
+      const content = readFileSync(fullPath, 'utf-8');
+      if (!content.includes('@ai-meta')) missing++;
+    } catch {
+      // skip
+    }
+  }
+
+  console.log(`\nFiles without @ai-meta: ${missing}`);
+  if (missing === 0) {
+    console.log(`${C.green}All files have @ai-meta headers!${C.reset}`);
+  } else {
+    console.log(`${C.yellow}Run 'node scripts/add-ai-meta-headers.mjs' to add headers${C.reset}`);
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/bin/cli.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:cli
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects none
+ * @stability medium
+ * @complexity moderate
+ * @token-budget 200
+ * @purpose Unified CLI entry point for ai-codebase-registry — dispatches to init, generate, query, validate, add-headers
+ *
+ * @filechangelog
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Created CLI dispatcher
+ */
+
+const COMMANDS = {
+  init: './init.mjs',
+  generate: './generate.mjs',
+  query: './query.mjs',
+  validate: './validate.mjs',
+  'add-headers': './add-headers.mjs',
+};
+
+function printUsage() {
+  console.log(`
+\x1b[1mai-codebase-registry\x1b[0m — Registry-driven AI agent infrastructure
+
+\x1b[1mUsage:\x1b[0m
+  ai-registry <command> [options]
+
+\x1b[1mCommands:\x1b[0m
+  init          Scaffold registry for a new project
+  generate      Rebuild all registry files from source
+  query         Query registry data (files, deps, impact, coverage)
+  validate      Check @ai-meta coverage and completeness
+  add-headers   Auto-add @ai-meta headers to files missing them
+
+\x1b[1mExamples:\x1b[0m
+  ai-registry init
+  ai-registry generate
+  ai-registry query --domain trip --type hook
+  ai-registry query --impact functions/src/services/projectionService.ts
+  ai-registry query --coverage
+  ai-registry validate
+  ai-registry add-headers --dry-run
+
+Run \x1b[1mai-registry <command> --help\x1b[0m for command-specific help.
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!COMMANDS[command]) {
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run 'ai-registry --help' for available commands.`);
+    process.exit(1);
+  }
+
+  // Forward remaining args
+  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
+
+  try {
+    await import(COMMANDS[command]);
+  } catch (err) {
+    if (err.code === 'ERR_MODULE_NOT_FOUND') {
+      console.error(`Command '${command}' is not yet implemented.`);
+      console.error(`Module not found: ${COMMANDS[command]}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+main();

package/bin/generate.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:cli-generate
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects writes:filesystem:_registry
+ * @stability medium
+ * @complexity complex
+ * @token-budget 300
+ * @purpose CLI command: rebuild all registry files from source files — supports multi-language projects
+ *
+ * @filechangelog
+ * @changelog 2026-02-23T10:00 [feat] [Claude Opus 4.6] Add fieldMap pass-through, language-aware deps skip, conditional generators
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Created generate CLI command
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { loadConfig } from '../lib/core/config-loader.mjs';
+import { collectFiles } from '../lib/core/file-discovery.mjs';
+import { createDomainDetector } from '../lib/core/domain-detector.mjs';
+import { generateManifest } from '../lib/generators/manifest.mjs';
+import { generateDeps } from '../lib/generators/deps.mjs';
+import { generateSemanticIds } from '../lib/generators/semantic-ids.mjs';
+import { generateSideEffects } from '../lib/generators/side-effects.mjs';
+import { generateFeatures } from '../lib/generators/features.mjs';
+
+const C = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  green: '\x1b[32m', cyan: '\x1b[36m', yellow: '\x1b[33m',
+};
+
+/** Languages that support textual import parsing */
+const IMPORT_GRAPH_LANGUAGES = new Set(['typescript', 'javascript']);
+
+async function main() {
+  const rootDir = resolve('.');
+  const config = await loadConfig(rootDir);
+
+  const enabledGenerators = config.generators
+    ? new Set(config.generators)
+    : null; // null = all
+
+  const shouldGenerate = (name) => !enabledGenerators || enabledGenerators.has(name);
+  const canGenerateDeps = IMPORT_GRAPH_LANGUAGES.has(config.language || 'typescript');
+
+  console.log(`${C.bold}ai-codebase-registry generate${C.reset}`);
+  console.log(`Project: ${config.name}`);
+  if (config.language && config.language !== 'typescript') {
+    console.log(`Language: ${config.language}`);
+  }
+  console.log('');
+
+  // 1. Discover files
+  console.log('Scanning codebase...');
+  const allFiles = [];
+  const extensions = new Set(config.extensions);
+  const skipDirs = new Set(config.skipDirs);
+
+  for (const { dir, prefix } of config.scanDirs) {
+    if (existsSync(dir)) {
+      const files = collectFiles(dir, prefix, { extensions, skipDirs });
+      allFiles.push(...files);
+      console.log(`  ${prefix}: ${files.length} files`);
+    } else {
+      console.log(`  ${prefix}: directory not found, skipping`);
+    }
+  }
+  console.log(`  Total: ${allFiles.length} files\n`);
+
+  // 2. Build manifest
+  console.log('Building manifest...');
+  const detectDomain = createDomainDetector();
+  const { manifest, importGraph, stats } = generateManifest(allFiles, {
+    aliasMap: config.aliases,
+    detectDomain,
+    fieldMap: config.fieldMap,
+    skipImportParsing: !canGenerateDeps,
+  });
+  console.log(`  @ai-meta coverage: ${stats.coverage}`);
+  console.log(`  With @purpose: ${stats.purposeCount}\n`);
+
+  // 3. Generate registry files
+  console.log('Generating registry files...');
+
+  const outputs = [];
+
+  if (shouldGenerate('manifest')) {
+    const manifestOutput = {
+      generated: new Date().toISOString(),
+      fileCount: Object.keys(manifest).length,
+      aiMetaCoverage: stats.coverage,
+      files: manifest,
+    };
+    outputs.push(['manifest.json', manifestOutput]);
+  }
+
+  if (shouldGenerate('deps') && canGenerateDeps) {
+    const importGraphSets = {};
+    for (const [key, value] of Object.entries(importGraph)) {
+      importGraphSets[key] = value;
+    }
+    const deps = generateDeps(importGraphSets);
+    outputs.push(['deps.json', deps]);
+  } else if (shouldGenerate('deps') && !canGenerateDeps) {
+    console.log(`  ${C.yellow}skip${C.reset} deps.json (no import graph for ${config.language})`);
+  }
+
+  if (shouldGenerate('semantic-ids')) {
+    const semanticIds = generateSemanticIds(manifest);
+    outputs.push(['semantic-ids.json', semanticIds]);
+  }
+
+  if (shouldGenerate('side-effects')) {
+    const sideEffects = generateSideEffects(manifest);
+    outputs.push(['side-effects.json', sideEffects]);
+  }
+
+  if (shouldGenerate('features')) {
+    const features = generateFeatures(manifest);
+    outputs.push(['features.json', features]);
+  }
+
+  // 4. Write output
+  const registryDir = config.registryDir;
+  if (!existsSync(registryDir)) {
+    mkdirSync(registryDir, { recursive: true });
+  }
+
+  for (const [filename, data] of outputs) {
+    const filePath = resolve(registryDir, filename);
+    writeFileSync(filePath, JSON.stringify(data, null, 2));
+    console.log(`  ${C.green}wrote${C.reset} ${filename}`);
+  }
+
+  console.log(`\n${C.bold}Registry generation complete!${C.reset}`);
+  console.log(`  Files: ${Object.keys(manifest).length}`);
+
+  // Find generated data for summary
+  const semanticIds = outputs.find(([n]) => n === 'semantic-ids.json')?.[1];
+  const sideEffects = outputs.find(([n]) => n === 'side-effects.json')?.[1];
+  const features = outputs.find(([n]) => n === 'features.json')?.[1];
+
+  if (semanticIds) console.log(`  Semantic IDs: ${semanticIds.explicitCount} explicit, ${semanticIds.derivedCount} derived`);
+  if (sideEffects) console.log(`  Side-effects: ${sideEffects.documentedCount} documented, ${sideEffects.missingCount} missing`);
+  if (features) console.log(`  Domains: ${features.domainCount}`);
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/bin/init.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:cli-init
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects writes:filesystem:_registry,writes:filesystem:ai-registry.config.mjs
+ * @stability medium
+ * @complexity complex
+ * @token-budget 300
+ * @purpose CLI command: scaffold registry infrastructure for a new project (config, directories, starter files)
+ *
+ * @filechangelog
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Created init CLI command with interactive prompts
+ */
+
+import { createInterface } from 'readline';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { resolve, join } from 'path';
+
+const C = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m',
+};
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+const ask = (q) => new Promise((res) => rl.question(q, res));
+
+async function main() {
+  console.log(`\n${C.bold}ai-codebase-registry init${C.reset}`);
+  console.log(`${C.dim}Scaffold AI agent infrastructure for your project${C.reset}\n`);
+
+  const rootDir = resolve('.');
+
+  // Check for existing config
+  if (existsSync(join(rootDir, 'ai-registry.config.mjs'))) {
+    console.log(`${C.yellow}ai-registry.config.mjs already exists.${C.reset}`);
+    const overwrite = await ask('Overwrite? (y/N) ');
+    if (overwrite.toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      rl.close();
+      return;
+    }
+  }
+
+  // Gather info
+  const name = await ask(`${C.cyan}Project name${C.reset} [${rootDir.split('/').pop()}]: `) || rootDir.split('/').pop();
+  const description = await ask(`${C.cyan}Description${C.reset}: `);
+  const srcDir = await ask(`${C.cyan}Source directory${C.reset} [src]: `) || 'src';
+  const extraDirs = await ask(`${C.cyan}Additional source directories${C.reset} (comma-separated, or empty): `);
+  const router = await ask(`${C.cyan}Router framework${C.reset} (react-router/nextjs/expo-router/express/none) [none]: `) || 'none';
+  const dataStore = await ask(`${C.cyan}Data store${C.reset} (firestore/postgres/mongodb/none) [none]: `) || 'none';
+
+  rl.close();
+
+  // Build scanDirs
+  const scanDirs = [{ dir: srcDir, prefix: srcDir }];
+  if (extraDirs.trim()) {
+    for (const d of extraDirs.split(',').map(s => s.trim()).filter(Boolean)) {
+      scanDirs.push({ dir: d, prefix: d });
+    }
+  }
+
+  // Generate config file
+  const configContent = `/** @type {import('ai-codebase-registry').Config} */
+export default {
+  name: ${JSON.stringify(name)},
+  description: ${JSON.stringify(description)},
+
+  scanDirs: ${JSON.stringify(scanDirs, null, 4).replace(/\n/g, '\n  ')},
+  extensions: ['.ts', '.tsx'],
+  skipDirs: ['node_modules', 'dist', '.next', 'coverage', '__tests__', '__mocks__'],
+
+  aliases: {
+    '@/': '${srcDir}/',
+  },
+
+  router: '${router}',
+  routerEntryFile: ${router === 'react-router' ? `'${srcDir}/App.tsx'` : 'null'},
+  routeBuilderFile: ${router === 'react-router' ? `'${srcDir}/routes.ts'` : 'null'},
+
+  dataStore: '${dataStore}',
+
+  registryDir: '_registry',
+  agent: 'claude-code',
+  claudemd: true,
+};
+`;
+
+  writeFileSync(join(rootDir, 'ai-registry.config.mjs'), configContent);
+  console.log(`\n  ${C.green}created${C.reset} ai-registry.config.mjs`);
+
+  // Create _registry directory
+  const registryDir = join(rootDir, '_registry');
+  if (!existsSync(registryDir)) {
+    mkdirSync(registryDir, { recursive: true });
+  }
+  console.log(`  ${C.green}created${C.reset} _registry/`);
+
+  // Create starter relationships.json
+  const relationships = {
+    _meta: {
+      description: `Cross-cutting relationship graph for ${name}`,
+      generated: new Date().toISOString().split('T')[0],
+      version: '1.0.0',
+    },
+    firestore_paths: {},
+    change_impact_rules: [],
+  };
+  writeFileSync(join(registryDir, 'relationships.json'), JSON.stringify(relationships, null, 2));
+  console.log(`  ${C.green}created${C.reset} _registry/relationships.json`);
+
+  // Create starter patterns.json
+  const patterns = {
+    version: '1.0',
+    generated: new Date().toISOString(),
+    patternCount: 0,
+    patterns: {},
+  };
+  writeFileSync(join(registryDir, 'patterns.json'), JSON.stringify(patterns, null, 2));
+  console.log(`  ${C.green}created${C.reset} _registry/patterns.json`);
+
+  // Create starter nav-exceptions.json
+  const navExceptions = {
+    _meta: { description: 'Routes that intentionally have no nav entry point' },
+    exceptions: {},
+  };
+  writeFileSync(join(registryDir, 'nav-exceptions.json'), JSON.stringify(navExceptions, null, 2));
+  console.log(`  ${C.green}created${C.reset} _registry/nav-exceptions.json`);
+
+  // Generate CLAUDE.md section
+  const claudeMdSection = generateClaudeMdSection(name, scanDirs);
+  const claudeMdPath = join(rootDir, 'CLAUDE.md');
+  if (existsSync(claudeMdPath)) {
+    console.log(`\n  ${C.yellow}CLAUDE.md already exists — appending AI agent infrastructure section${C.reset}`);
+    const existing = (await import('fs')).readFileSync(claudeMdPath, 'utf-8');
+    if (!existing.includes('AI-Agent-First Architecture')) {
+      writeFileSync(claudeMdPath, existing + '\n\n' + claudeMdSection);
+      console.log(`  ${C.green}updated${C.reset} CLAUDE.md`);
+    } else {
+      console.log(`  ${C.dim}CLAUDE.md already has agent infrastructure section${C.reset}`);
+    }
+  } else {
+    writeFileSync(claudeMdPath, `# CLAUDE.md\n\n${claudeMdSection}`);
+    console.log(`  ${C.green}created${C.reset} CLAUDE.md`);
+  }
+
+  console.log(`
+${C.bold}Next steps:${C.reset}
+  1. Run ${C.cyan}ai-registry generate${C.reset} to build initial registry
+  2. Run ${C.cyan}ai-registry add-headers${C.reset} to add @ai-meta headers to source files
+  3. Run ${C.cyan}ai-registry validate${C.reset} to check coverage
+  4. Add to pre-commit hook: ${C.cyan}ai-registry generate${C.reset}
+`);
+}
+
+function generateClaudeMdSection(name) {
+  return `## AI-Agent-First Architecture Mandate
+
+${name} uses a registry-driven architecture where every source file carries machine-readable metadata.
+AI agents MUST consult the registry before searching the filesystem.
+
+### Registry Loading Order
+\`semantic-ids.json\` -> \`manifest.json\` -> \`side-effects.json\` -> \`patterns.json\`
+
+### \`@ai-meta\` Headers (MANDATORY)
+
+Every source file MUST have an \`@ai-meta\` JSDoc header with these mandatory fields:
+- \`@id\` — format: \`type:domain:kebab-name\`
+- \`@domain\` — business domain this file belongs to
+- \`@type\` — file type (hook, component, page, service, util, etc.)
+- \`@side-effects\` — what this file mutates (\`none\` if pure)
+- \`@stability\` — how often this changes (low/medium/high)
+- \`@complexity\` — code complexity (trivial/moderate/complex)
+- \`@token-budget\` — estimated tokens for AI agent to process
+- \`@purpose\` — one-line description
+
+### Side-Effect Documentation
+
+Before modifying any mutation, trigger, or data write:
+1. Query \`_registry/side-effects.json\` for the entity
+2. If NOT listed, add it before writing code
+3. After modifying: update \`@side-effects\` AND \`side-effects.json\`
+
+### Agent Session Protocol
+
+At session start:
+1. Load: \`_registry/semantic-ids.json\` -> \`manifest.json\` -> \`side-effects.json\` -> \`patterns.json\`
+2. Check \`TODO.md\` for open items
+3. Auto-select highest-severity unblocked item
+`;
+}
+
+main().catch(err => {
+  console.error(err);
+  rl.close();
+  process.exit(1);
+});