@ericrisco/rsc 1.1.6 → 1.2.0

package/scripts/originality-check.js

@@ -0,0 +1,137 @@
+import {
+  existsSync, readdirSync, readFileSync, statSync, writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { stackAgents } from '../targets/agent-catalog.js';
+import { allAgentNames } from '../targets/agents.js';
+import { resolveCommands } from '../targets/commands.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const META_PATH = join(ROOT, 'schema', 'ecc-originality.json');
+const DATA_PATH = join(ROOT, 'schema', 'ecc-originality.u64');
+const NGRAM_SIZE = 8;
+const EXEMPTION_CATEGORIES = new Set(['name', 'error', 'tool-command', 'language-term']);
+
+export function normalizeTokens(text) {
+  return String(text || '').normalize('NFKC').toLowerCase().match(/[\p{L}\p{N}_+.#/-]+/gu) || [];
+}
+
+function fingerprint(tokens, offset, size = NGRAM_SIZE) {
+  return createHash('sha256').update(tokens.slice(offset, offset + size).join(' ')).digest('hex').slice(0, 16);
+}
+
+function fingerprintsOf(text, size = NGRAM_SIZE) {
+  const tokens = normalizeTokens(text);
+  const out = [];
+  for (let offset = 0; offset <= tokens.length - size; offset += 1) {
+    out.push({ fingerprint: fingerprint(tokens, offset, size), offset });
+  }
+  return out;
+}
+
+function walk(directory) {
+  if (!existsSync(directory)) throw new Error(`originality: corpus directory missing: ${directory}`);
+  return readdirSync(directory).sort().flatMap((name) => {
+    const path = join(directory, name);
+    return statSync(path).isDirectory() ? walk(path) : [path];
+  });
+}
+
+function catalogDocuments() {
+  const skillIds = readdirSync(join(ROOT, 'skills')).filter((id) => {
+    try { return statSync(join(ROOT, 'skills', id, 'SKILL.md')).isFile(); } catch { return false; }
+  });
+  const commands = resolveCommands({
+    target: 'cursor', skills: skillIds, agents: allAgentNames(), memoryMode: 'full',
+  });
+  return [
+    ...stackAgents().map((agent) => ({ id: `agent:${agent.name}`, text: `${agent.desc}\n${agent.body}` })),
+    ...commands.map((command) => ({ id: `command:${command.name}`, text: `${command.description}\n${command.body}` })),
+  ];
+}
+
+export function fingerprintCorpus(metaPath = META_PATH, dataPath = DATA_PATH) {
+  const metadata = JSON.parse(readFileSync(metaPath, 'utf8'));
+  if (metadata.ngramSize !== NGRAM_SIZE) throw new Error(`originality: unsupported n-gram size ${metadata.ngramSize}`);
+  for (const exemption of metadata.exemptions || []) {
+    if (!EXEMPTION_CATEGORIES.has(exemption.category) || !/^[0-9a-f]{16}$/.test(exemption.fingerprint || '')) {
+      throw new Error('originality: every exemption needs a valid fingerprint and closed category');
+    }
+  }
+  const bytes = readFileSync(dataPath);
+  if (bytes.length % 8 !== 0 || bytes.length / 8 !== metadata.fingerprintCount) {
+    throw new Error('originality: fingerprint corpus length does not match its receipt');
+  }
+  const digest = createHash('sha256').update(bytes).digest('hex');
+  if (digest !== metadata.dataSha256) throw new Error('originality: fingerprint corpus failed its integrity receipt');
+  const fingerprints = new Set();
+  for (let offset = 0; offset < bytes.length; offset += 8) fingerprints.add(bytes.subarray(offset, offset + 8).toString('hex'));
+  return { metadata, fingerprints };
+}
+
+export function checkCatalogOriginality({ corpus = fingerprintCorpus(), documents = catalogDocuments() } = {}) {
+  const exempt = new Set((corpus.metadata.exemptions || []).map((entry) => entry.fingerprint));
+  const matches = [];
+  for (const document of documents) {
+    for (const candidate of fingerprintsOf(document.text, corpus.metadata.ngramSize)) {
+      if (corpus.fingerprints.has(candidate.fingerprint) && !exempt.has(candidate.fingerprint)) {
+        matches.push({ document: document.id, tokenOffset: candidate.offset, fingerprint: candidate.fingerprint });
+      }
+    }
+  }
+  return {
+    ngramSize: corpus.metadata.ngramSize,
+    corpusRevision: corpus.metadata.revision,
+    documents: documents.length,
+    exemptions: exempt.size,
+    matches,
+  };
+}
+
+function refresh(corpusRoot) {
+  const files = ['agents', 'commands'].flatMap((directory) => walk(join(corpusRoot, directory)));
+  const hashes = new Set();
+  for (const path of files) {
+    for (const candidate of fingerprintsOf(readFileSync(path, 'utf8'))) hashes.add(candidate.fingerprint);
+  }
+  const sorted = [...hashes].sort();
+  const bytes = Buffer.alloc(sorted.length * 8);
+  sorted.forEach((hash, index) => Buffer.from(hash, 'hex').copy(bytes, index * 8));
+  writeFileSync(DATA_PATH, bytes);
+  const revision = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: corpusRoot, encoding: 'utf8' }).trim();
+  const metadata = {
+    schemaVersion: 1,
+    source: 'https://github.com/affaan-m/everything-claude-code',
+    revision,
+    generatedAt: new Date().toISOString().slice(0, 10),
+    included: ['agents/**', 'commands/**'],
+    ngramSize: NGRAM_SIZE,
+    normalization: 'NFKC lowercase; Unicode letters/numbers plus _+.#/-; whitespace joined',
+    fingerprintFormat: 'first 64 bits of SHA-256, sorted big-endian; collisions fail closed',
+    fingerprintCount: sorted.length,
+    dataSha256: createHash('sha256').update(bytes).digest('hex'),
+    exemptions: [],
+  };
+  writeFileSync(META_PATH, `${JSON.stringify(metadata, null, 2)}\n`);
+  return metadata;
+}
+
+function main() {
+  if (process.argv[2] === '--refresh') {
+    if (!process.argv[3]) throw new Error('Usage: node scripts/originality-check.js --refresh <ecc-checkout>');
+    const metadata = refresh(process.argv[3]);
+    console.log(`originality corpus refreshed (${metadata.fingerprintCount} fingerprints at ${metadata.revision})`);
+    return;
+  }
+  const result = checkCatalogOriginality();
+  if (result.matches.length) {
+    for (const match of result.matches) console.error(`${match.document}: shared ${result.ngramSize}-token fingerprint ${match.fingerprint} at token ${match.tokenOffset}`);
+    process.exit(1);
+  }
+  console.log(`originality OK (${result.documents} documents vs ${fingerprintCorpus().metadata.fingerprintCount} corpus fingerprints; ${result.exemptions} exemptions)`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/scripts/rsc.js

@@ -4,7 +4,8 @@ import { detectTarget, resolveTargets, TARGETS } from '../targets/index.js';
 import { detectRepo } from './detect-repo.js';
 import { rank } from './consult.js';
 import { expandRecommends, toOutcomes, hasOutcome } from './lib/recommend.js';
-import { applyInstall, listInstalled, uninstall, syncInstalled, purge, collisions } from './install-apply.js';
+import { applyInstall, listInstalled, listInstalledAgents, listInstalledCommands, uninstall, syncInstalled, purge, collisions } from './install-apply.js';
+import { stackAgentNames } from '../targets/agents.js';
 import { doctor } from './doctor.js';
 import { say, select, pickFrom, banner, confirm, isInteractive } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
@@ -20,6 +21,54 @@ const cmd = argv[0];
 
 const targetLabel = (id) => TARGETS.find((t) => t.id === id)?.label || id;
 
+function requestedIds(start = 1) {
+  const valueFlags = new Set(['--target', '--profile', '--without']);
+  const ids = [];
+  for (let i = start; i < argv.length; i++) {
+    if (valueFlags.has(argv[i])) { i++; continue; }
+    if (argv[i].startsWith('--')) continue;
+    ids.push(argv[i]);
+  }
+  return ids;
+}
+
+function editDistance(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const above = prev[j];
+      prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diagonal = above;
+    }
+  }
+  return prev[b.length];
+}
+
+function classifyRequested(ids) {
+  const skills = new Set(loadManifest().skills.map((skill) => skill.id));
+  const agents = new Set(stackAgentNames());
+  const out = { skills: [], agents: [], unknown: [] };
+  for (const id of ids) {
+    if (skills.has(id)) out.skills.push(id);
+    else if (agents.has(id)) out.agents.push(id);
+    else out.unknown.push(id);
+  }
+  return out;
+}
+
+function reportUnknown(ids) {
+  if (!ids.length) return false;
+  const candidates = [...loadManifest().skills.map((skill) => skill.id), ...stackAgentNames()];
+  for (const id of ids) {
+    const close = [...candidates].sort((a, b) => editDistance(id, a) - editDistance(id, b) || a.localeCompare(b)).slice(0, 3);
+    console.error(`rsc: unknown skill or agent '${id}'. Closest: ${close.join(', ')}`);
+  }
+  process.exitCode = 1;
+  return true;
+}
+
 // Commands that act ON one assistant. Only these stop when two are installed and no
 // flag says which: `purge` sweeps every target by design, and the catalog/consult
 // side barely touches one, so blocking them would be a regression, not a safeguard.
@@ -113,6 +162,8 @@ function printNextSteps(targets, ids) {
   say('\n   Add something by hand anytime:    npx @ericrisco/rsc add <skill>');
   say('   Browse the catalog / get picks:   npx @ericrisco/rsc consult "whatever you need"');
   say('────────────────────────────────────────────────────────');
+  if (targets.includes('codex')) say('   Codex: review and trust the project lifecycle hook once with `/hooks`; until then memory is reported as requiring trust.');
+  if (targets.includes('cursor')) say('   Cursor: startup memory is assisted because its sessionStart hook is fire-and-forget; the installed always-on rule performs the read-before-action fallback.');
   printAgentHandoff();
 }
 
@@ -268,15 +319,12 @@ async function main() {
     case undefined:
       return wizard(f ? targets : null);
     case 'add': {
-      // Positional args = skill ids; skip flags and any flag value (the token after a --flag).
-      const requested = [];
-      for (let i = 1; i < argv.length; i++) {
-        if (argv[i].startsWith('--')) { i++; continue; }
-        requested.push(argv[i]);
-      }
-      const ids = withDefaultSkillFloor(requested);
+      const requested = requestedIds();
+      const selected = classifyRequested(requested);
+      if (reportUnknown(selected.unknown)) return;
+      const ids = withDefaultSkillFloor(selected.skills);
       if (!argv.includes('--force') && !(await guardCollisions(targets, ids))) return;
-      for (const t of targets) await applyInstall({ skillIds: ids, target: t });
+      for (const t of targets) await applyInstall({ skillIds: ids, agentIds: selected.agents, target: t });
       say(`✅ Installed for ${targets.join(', ')}: ${requested.join(', ')}`);
       return void say('   ↻ Reload/restart your assistant so the new skill activates.');
     }
@@ -328,14 +376,66 @@ async function main() {
       else say('\n(no harness wiki here — printed above only; run `harness` to keep a written record)');
       return;
     }
-    case 'list':
-      return void say(listInstalled({ target }).join('\n') || '(nothing installed)');
+    case 'list': {
+      const skills = listInstalled({ target }).map((id) => `skill\t${id}`);
+      const agents = listInstalledAgents({ target }).map((agent) => `agent\t${agent.id}\t${agent.source}${agent.skills.length ? `:${agent.skills.join(',')}` : ''}`);
+      const commands = listInstalledCommands({ target }).map((command) => `command\t${command.id}\t${command.path}`);
+      return void say([...skills, ...agents, ...commands].join('\n') || '(nothing installed)');
+    }
     case 'doctor': {
       const report = doctor({ target });
       if (argv.includes('--json')) return void say(JSON.stringify(report, null, 2));
       printContextBudget(report.contextBudget);
       return void say(JSON.stringify({ ...report, contextBudget: undefined }, null, 2));
     }
+    case 'memory': {
+      const sub = argv[1] || 'status';
+      const root = process.cwd();
+      if (sub === 'on' || sub === 'off') {
+        const { readManifest, writeManifest } = await import('./lib/manifest-file.js');
+        const current = readManifest(root) || { version: 1, targets: targets || [], skills: [], agents: [], ownSkills: [], optOuts: [] };
+        writeManifest(root, { ...current, memory: sub === 'off' ? false : { enabled: true } });
+        for (const t of targets) await syncInstalled({ target: t, cwd: root });
+        say(`rsc memory ${sub}: ${sub === 'on' ? 'enabled' : 'disabled'} for this project (${targets.join(', ') || 'declaration only'}).`);
+        return;
+      }
+      const M = await import('../targets/session-memory-core.mjs');
+      if (sub === 'status') {
+        const reports = targets.map((t) => doctor({ target: t, cwd: root }).memory);
+        return void say(JSON.stringify(reports.length === 1 ? reports[0] : reports, null, 2));
+      }
+      if (sub === 'resume') {
+        const result = M.resume({ cwd: root });
+        return void say(argv.includes('--json') ? JSON.stringify(result, null, 2) : (result.context || '(no local continuation for this branch/worktree)'));
+      }
+      if (sub === 'save') {
+        const result = M.capture({
+          cwd: root,
+          sessionId: typeof flag('session') === 'string' ? flag('session') : `manual-${Date.now()}`,
+          target: target || 'manual',
+          event: 'save',
+          force: true,
+        });
+        return void say(JSON.stringify(result, null, 2));
+      }
+      if (sub === 'learn') {
+        const value = (name) => { const v = flag(name); return typeof v === 'string' && !v.startsWith('--') ? v : undefined; };
+        const result = M.learn({
+          cwd: root,
+          text: value('text'),
+          evidence: value('evidence'),
+          scope: value('scope') || 'project',
+          confidence: value('confidence'),
+          approved: argv.includes('--approve'),
+        });
+        if (!result.saved) process.exitCode = 1;
+        return void say(JSON.stringify(result, null, 2));
+      }
+      if (sub === 'metrics') return void say(JSON.stringify(M.metricsSummary({ cwd: root }), null, 2));
+      say('Use: npx @ericrisco/rsc memory on|off|status|save [--session id]|resume [--json]|learn --text "…" --evidence "…" --scope project|global --confidence 0..1 --approve|metrics');
+      process.exitCode = 1;
+      return;
+    }
     case 'sync': {
       const dry = argv.includes('--dry-run');
       for (const t of targets) {
@@ -446,6 +546,13 @@ async function main() {
         } else {
           say(`# ${caps.target} has no file-based agents — the agent option does not apply here`);
         }
+        if (caps.commandsSupported) {
+          for (const command of caps.commands) say(`command\t${command.id}\tproject\t${command.path}`);
+          if (!caps.commands.length) say('# no managed command files found (this target supports them)');
+        } else {
+          say(`# ${caps.target} has no supported project command surface`);
+        }
+        say(`memory\t${caps.memory.mode}\t${caps.memory.status}\t${caps.memory.reason}`);
       }
       if (!full) say('# catalog shown as ids; add --full for descriptions, or use `catalog --available` to match by meaning');
       return;
@@ -623,8 +730,9 @@ async function main() {
       const dry = argv.includes('--dry-run');
       // `uninstall --all` is an alias for a full purge.
       if (argv.includes('--all')) return void (await runPurge(dry, argv.includes('--with-docs')));
-      const ids = argv.slice(1).filter((a) => !a.startsWith('--'));
-      const removed = await uninstall({ skillIds: ids, target, dryRun: dry });
+      const selected = classifyRequested(requestedIds());
+      if (reportUnknown(selected.unknown)) return;
+      const removed = await uninstall({ skillIds: selected.skills, agentIds: selected.agents, target, dryRun: dry });
       return void say((dry ? 'Would remove:\n' : 'Removed:\n') + (removed.join('\n') || '(nothing)'));
     }
     case 'repair': {
@@ -652,7 +760,7 @@ async function main() {
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | sello <on|off|status|…> | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
+      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
       say('Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)');
       say('   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.');
       process.exitCode = 1;

package/targets/agent-catalog.js

@@ -0,0 +1,220 @@
+const REVIEW_TOOLS = Object.freeze(['read', 'search']);
+const RESOLVER_TOOLS = Object.freeze(['read', 'search', 'edit', 'shell']);
+
+const reviewerBody = ({ label, scope, probes, escalation = '' }) => `You are the ${label} reviewer. Review the requested diff or pull request; do not edit files.
+
+Boundary: ${scope}
+
+Work from changed lines outward just far enough to verify callers, imports, guards, and tests. Record an **attack list** even when every attack is clean. For each proposed finding, answer before reporting:
+1. What exact changed line supports it?
+2. What concrete input and state produce what wrong result?
+3. Which caller, import, and relevant test did you inspect?
+4. Why do existing guards not reduce the severity?
+
+HIGH and CRITICAL findings require the exact line and the full failure path. If either is missing, lower the severity or omit the finding. Prefer a clean verdict with a useful attack list over speculative volume.
+
+Stack attacks:
+${probes.map((probe) => `- ${probe}`).join('\n')}
+${escalation ? `\n${escalation}\n` : ''}
+Return: scope, attack list, findings ordered by severity, and verdict. A finding names file:line, failure mode, evidence, and the smallest test that would expose it.`;
+
+const resolverBody = ({ label, scope, signals, attempts = 3 }) => `You are the ${label} build resolver. Diagnose and repair one failing build with the smallest stack-correct change.
+
+Boundary: ${scope}
+
+1. Reproduce the named failure and preserve its exact command and first causal diagnostic.
+2. Trace that diagnostic to configuration, dependency, generated code, compiler, linker, or runtime setup.
+3. Change only what is needed for that cause; do not refactor, upgrade broadly, or clean unrelated warnings.
+4. Re-run the narrow failing command, then the nearest relevant test/build gate.
+5. Stop after ${attempts} unsuccessful repair attempts or as soon as the next step requires a refactor or product choice.
+
+Signals to distinguish:
+${signals.map((signal) => `- ${signal}`).join('\n')}
+
+Return the root cause, commands run, files changed, proof of the result, and any remaining blocker.`;
+
+const reviewer = ({ name, label, skills, not, probes, should, shouldNot, tier = 'balanced', escalation }) => ({
+  name,
+  role: 'reviewer',
+  tier,
+  tools: [...REVIEW_TOOLS],
+  skills,
+  desc: `${label} reviewer: inspects changed code for stack-specific failure modes and reports evidence without editing. NOT ${not}.`,
+  routing: { should, shouldNot },
+  body: reviewerBody({ label, scope: `Use for ${skills.join(' or ')} code. NOT ${not}.`, probes, escalation }),
+});
+
+const resolver = ({ name, label, skills, not, signals, should, shouldNot, tier = 'balanced' }) => ({
+  name,
+  role: 'build-resolver',
+  tier,
+  tools: [...RESOLVER_TOOLS],
+  skills,
+  desc: `${label} build resolver: reproduces a failing build and applies the minimum verified repair. NOT ${not}.`,
+  routing: { should, shouldNot },
+  body: resolverBody({ label, scope: `Use for ${skills.join(' or ')} build failures. NOT ${not}.`, signals }),
+});
+
+const REVIEWERS = [
+  reviewer({
+    name: 'django-reviewer', label: 'Django', skills: ['django'], not: 'general Python review or build repair',
+    probes: ['QuerySet evaluation, N+1 reads, and accidental full-table work.', 'Transaction boundaries, row locking, retries, and side effects inside atomic blocks.', 'Migration reversibility, historical models, nullable transitions, and deploy ordering.', 'Authorization at object/query boundaries rather than only at the view.'],
+    should: ['Review a Django ORM diff for query and transaction defects.'], shouldNot: ['Fix a failing Django migration command.'],
+  }),
+  reviewer({
+    name: 'java-reviewer', label: 'Java and Spring', skills: ['java', 'spring-boot'], not: 'Android/Kotlin review or generic build repair',
+    probes: ['Nullability and Optional contracts across public boundaries.', 'Equality, hashing, mutability, and collection aliasing.', 'Spring proxy boundaries: transactions, self-invocation, scopes, and configuration binding.', 'Thread ownership, blocking work, interruption, and resource closure.'],
+    should: ['Review a Spring transaction change.'], shouldNot: ['Repair a Gradle dependency resolution failure.'],
+  }),
+  reviewer({
+    name: 'kotlin-reviewer', label: 'Kotlin Android', skills: ['kotlin-android'], not: 'Java server review or Gradle repair',
+    probes: ['Coroutine scope ownership, cancellation, dispatcher choice, and exception propagation.', 'Lifecycle collection, recomposition stability, and state restoration.', 'Nullable/platform types and sealed-state exhaustiveness.', 'Context/activity retention and Android resource lifetime.'],
+    should: ['Review a coroutine-driven Android screen.'], shouldNot: ['Resolve an Android Gradle Plugin mismatch.'],
+  }),
+  reviewer({
+    name: 'flutter-reviewer', label: 'Flutter', skills: ['flutter'], not: 'native Android review or Flutter build repair',
+    probes: ['Widget identity, keys, rebuild scope, and stale BuildContext use.', 'Controller, subscription, isolate, and animation disposal.', 'Async mounted checks and state changes after teardown.', 'Platform-channel contracts and divergent iOS/Android behavior.'],
+    should: ['Review a Flutter widget state diff.'], shouldNot: ['Fix a CocoaPods build failure.'],
+  }),
+  reviewer({
+    name: 'react-reviewer', label: 'React and Next.js', skills: ['react', 'nextjs'], not: 'Vue review or frontend build repair',
+    probes: ['Render purity, hook dependency identity, stale closures, and effect cleanup.', 'Server/client boundaries, serialization, caching, and request-scoped data.', 'Concurrent rendering races, transitions, hydration, and optimistic rollback.', 'Keys, controlled state, accessibility semantics, and error/loading states.'],
+    should: ['Review a Next.js server/client boundary.'], shouldNot: ['Repair a webpack or Turbopack build.'],
+  }),
+  reviewer({
+    name: 'rust-reviewer', label: 'Rust', skills: ['rust'], not: 'C++ review or Cargo build repair',
+    probes: ['Ownership workarounds that hide lifetime or aliasing defects.', 'Unsafe blocks: stated invariant, pointer provenance, layout, and synchronization.', 'Error propagation, panic reachability, and poisoned/shared state.', 'Async cancellation, Send/Sync assumptions, locks across await, and task lifetime.'],
+    should: ['Review an unsafe Rust boundary.'], shouldNot: ['Fix a Cargo feature conflict.'],
+  }),
+  reviewer({
+    name: 'swift-reviewer', label: 'Swift iOS', skills: ['swift-ios'], not: 'Kotlin review or Xcode build repair',
+    probes: ['Actor isolation, Sendable claims, cancellation, and main-thread ownership.', 'Reference cycles, escaping closures, and resource lifetime.', 'Value/reference semantics, copy-on-write, and mutation through shared state.', 'View identity, navigation state, persistence, and platform availability.'],
+    should: ['Review Swift concurrency changes in an iOS app.'], shouldNot: ['Resolve a signing or linker failure.'],
+  }),
+  reviewer({
+    name: 'go-reviewer', label: 'Go', skills: ['go'], not: 'generic service review or Go build repair',
+    probes: ['Goroutine lifetime, cancellation ownership, channel closure, and races.', 'Error wrapping and identity where callers use errors.Is or errors.As.', 'Interface nil values, slice/map aliasing, loop capture, and deferred cleanup lifetime.', 'API and doc-comment contracts, zero values, receiver choice, and lock copying.'],
+    should: ['Review Go concurrency and error handling.'], shouldNot: ['Repair a missing Go module or compile error.'],
+  }),
+  reviewer({
+    name: 'cpp-reviewer', label: 'C++', skills: ['cpp'], not: 'Rust review or compiler/linker repair',
+    probes: ['Ownership expressed through RAII and any raw pointer whose lifetime is unstated.', 'Dangling views/references, moved-from values, invalidation, and destructor behavior.', 'Bounds, narrowing, signedness, undefined behavior, and exception guarantees.', 'Synchronization, data races, virtual destruction, and unsafe casts.'],
+    should: ['Review a C++ ownership or lifetime diff.'], shouldNot: ['Resolve a CMake or linker failure.'],
+  }),
+  reviewer({
+    name: 'vue-reviewer', label: 'Vue and Nuxt', skills: ['vue-nuxt'], not: 'React review or Vue build repair',
+    probes: ['Reactive identity, destructuring, watcher cleanup, and computed side effects.', 'SSR/client divergence, hydration, route middleware, and request-scoped state.', 'Composable lifetime, provide/inject contracts, and error/loading states.', 'Template keys, accessibility semantics, and unsafe rendered content.'],
+    should: ['Review a Nuxt SSR and hydration diff.'], shouldNot: ['Fix a Vite build.'],
+  }),
+  reviewer({
+    name: 'csharp-reviewer', label: 'C# and .NET', skills: ['csharp-dotnet'], not: 'Java review or dotnet build repair',
+    probes: ['Async cancellation, sync-over-async, disposal, and scoped service lifetime.', 'Nullable annotations versus runtime validation and serializer behavior.', 'LINQ query translation, repeated enumeration, tracking, and transaction scope.', 'Records/equality, mutable shared state, authorization, and configuration binding.'],
+    should: ['Review an ASP.NET or EF Core change.'], shouldNot: ['Repair a NuGet restore failure.'],
+  }),
+  reviewer({
+    name: 'php-reviewer', label: 'PHP and Laravel', skills: ['laravel', 'php'], not: 'Django review or Composer/build repair',
+    probes: ['Request validation, mass assignment, policy scope, and tenant isolation.', 'Eloquent loading, query count, transactions, and queued work after commit.', 'PHP type coercion, nullable boundaries, array shape assumptions, and error conversion.', 'Migration deploy ordering, cache/config behavior, and serialization.'],
+    should: ['Review Laravel authorization and ORM code.'], shouldNot: ['Resolve a Composer dependency error.'],
+  }),
+  reviewer({
+    name: 'typescript-reviewer', label: 'TypeScript', skills: ['typescript'], not: 'framework-specific UI review or TypeScript build repair',
+    probes: ['Runtime validation at boundaries where static types disappear.', 'Unsound assertions, any/unknown narrowing, variance, and optional-property semantics.', 'Promise ownership, rejection paths, cancellation, and event-listener cleanup.', 'Module/export contracts and type/value divergence across build targets.'],
+    should: ['Review a TypeScript library API diff.'], shouldNot: ['Fix tsconfig or bundler errors.'],
+  }),
+  reviewer({
+    name: 'fastapi-reviewer', label: 'FastAPI', skills: ['fastapi'], not: 'generic Python review or environment repair',
+    probes: ['Dependency lifetime and cleanup, override leakage, and request-scoped state.', 'Async blocking, cancellation, background task ownership, and exception mapping.', 'Pydantic input/output boundaries, partial updates, and response data exposure.', 'Authorization per resource, transaction completion, and OpenAPI contract drift.'],
+    should: ['Review a FastAPI endpoint and dependency change.'], shouldNot: ['Repair a Python package installation.'],
+  }),
+  reviewer({
+    name: 'python-reviewer', label: 'Python', skills: ['python'], not: 'FastAPI/Django-specific review or environment repair',
+    probes: ['Async tasks that are never awaited, cancellation loss, and TaskGroup failure propagation.', 'Mutable defaults, late binding, descriptor/protocol behavior, and truthiness edge cases.', 'Context-manager and iterator cleanup, exception chaining, and generator finalization.', 'Shared mutable state, import-time effects, typing/runtime gaps, and process/thread boundaries.'],
+    should: ['Review Python language and asyncio correctness.'], shouldNot: ['Review Django ORM behavior.'],
+  }),
+  reviewer({
+    name: 'postgres-reviewer', label: 'PostgreSQL', skills: ['postgresdb'], not: 'application ORM review or migration execution',
+    probes: ['Lock strength/order, long transactions, deadlocks, and concurrent DDL behavior.', 'Index/operator compatibility, selectivity, null semantics, and query-plan regressions.', 'RLS policy coverage, SECURITY DEFINER/search_path, grants, and tenant isolation.', 'Migration reversibility, constraint validation, backfill batching, and replication effects.'],
+    should: ['Review a PostgreSQL migration and policy diff.'], shouldNot: ['Run or repair application migrations.'],
+  }),
+  reviewer({
+    name: 'rag-reviewer', label: 'RAG', skills: ['rag'], not: 'general ML training review or retrieval implementation',
+    probes: ['Evaluation set leakage, temporal leakage, and mismatch between offline and live queries.', 'Chunk/metadata identity, permission filtering before retrieval, and deletion propagation.', 'Recall/rerank trade-offs, empty retrieval, citation grounding, and abstention.', 'Embedding/model/index version compatibility and rollback behavior.'],
+    should: ['Review a retrieval pipeline for leakage and grounding.'], shouldNot: ['Tune a neural training loop.'],
+  }),
+  reviewer({
+    name: 'mle-reviewer', label: 'production ML', skills: ['machine-learning'], not: 'notebook style review or model training implementation', tier: 'heavy',
+    probes: ['Temporal/entity leakage in splits and features available only after prediction time.', 'Training-serving schema skew, data contracts, null/category drift, and feature ownership.', 'Promotion gates that fail open, canary comparability, monitoring delay, and rollback without retraining.', 'Reproducible artifacts: data/code/model lineage, seeds, environment, and deterministic evaluation.'],
+    should: ['Review an ML promotion and rollback pipeline.'], shouldNot: ['Implement or tune the model.'],
+  }),
+];
+
+const RESOLVERS = [
+  resolver({ name: 'django-build-resolver', label: 'Django', skills: ['django'], not: 'ORM performance review or feature refactoring', signals: ['Migration graph conflicts versus unapplied migrations.', 'Settings/import errors versus database connectivity.', 'Static collection/template failures versus application tests.'], should: ['Fix a failing Django migrate/check command.'], shouldNot: ['Review an ORM diff for N+1 queries.'] }),
+  resolver({ name: 'java-build-resolver', label: 'Java and Spring', skills: ['java', 'spring-boot'], not: 'code review or broad dependency upgrades', signals: ['Compiler diagnostics versus annotation/generated-source failures.', 'Maven/Gradle resolution versus toolchain/JDK mismatch.', 'Spring context/bootstrap failures versus test assertion failures.'], should: ['Fix a Gradle/Maven/Spring build failure.'], shouldNot: ['Review transaction correctness.'] }),
+  resolver({ name: 'kotlin-build-resolver', label: 'Kotlin Android', skills: ['kotlin-android'], not: 'UI/coroutine review or project modernization', signals: ['Kotlin/AGP/Gradle/JDK compatibility.', 'KSP/KAPT/generated source failures.', 'Manifest/resource merge versus compiler diagnostics.'], should: ['Repair an Android Gradle build.'], shouldNot: ['Review Compose state.'] }),
+  resolver({ name: 'flutter-build-resolver', label: 'Flutter', skills: ['flutter'], not: 'widget review or package modernization', signals: ['Dart analyzer/compile errors versus generated-code drift.', 'CocoaPods/Xcode signing versus Android Gradle failures.', 'Plugin platform constraints versus app code failures.'], should: ['Repair a Flutter build failure.'], shouldNot: ['Review widget lifecycle.'] }),
+  resolver({ name: 'react-build-resolver', label: 'React and Next.js', skills: ['react', 'nextjs'], not: 'UI review or broad package upgrades', signals: ['Type/lint failure versus bundler/module resolution.', 'Server/client boundary or static rendering diagnostics.', 'Environment/config presence versus application logic.'], should: ['Repair a Next.js or React production build.'], shouldNot: ['Review hydration correctness.'] }),
+  resolver({ name: 'rust-build-resolver', label: 'Rust', skills: ['rust'], not: 'unsafe-code review or dependency modernization', signals: ['Borrow/type diagnostics versus feature unification.', 'Build-script/native library/linker failures.', 'Toolchain/edition mismatch versus source error.'], should: ['Repair a Cargo build failure.'], shouldNot: ['Review unsafe invariants.'] }),
+  resolver({ name: 'swift-build-resolver', label: 'Swift iOS', skills: ['swift-ios'], not: 'concurrency review or signing-policy changes', signals: ['Swift compiler/generic diagnostics versus package resolution.', 'Linker/module map/generated interface failure.', 'Simulator/device availability versus signing/provisioning.'], should: ['Repair an Xcode or SwiftPM build.'], shouldNot: ['Review actor isolation.'] }),
+  resolver({ name: 'go-build-resolver', label: 'Go', skills: ['go'], not: 'concurrency review or module-wide upgrades', signals: ['Compiler/type error versus generated code drift.', 'Module/version/sum failure versus private module credentials.', 'CGO/toolchain/linker failure versus test failure.'], should: ['Repair a go build failure.'], shouldNot: ['Review goroutine lifetime.'] }),
+  resolver({ name: 'cpp-build-resolver', label: 'C++', skills: ['cpp'], not: 'ownership review or build-system modernization', signals: ['Compiler diagnostic versus template instantiation cause.', 'CMake/configuration/generator failure versus source failure.', 'Undefined reference/ABI/library order versus runtime test failure.'], should: ['Repair a CMake/compiler/linker failure.'], shouldNot: ['Review C++ lifetime safety.'] }),
+  resolver({ name: 'pytorch-build-resolver', label: 'PyTorch', skills: ['machine-learning'], not: 'model-quality review or training redesign', signals: ['Python package/import mismatch versus compiled extension ABI.', 'CUDA/driver/toolkit/architecture incompatibility.', 'Distributed launcher/environment failure versus model code failure.'], should: ['Repair a PyTorch environment or extension build.'], shouldNot: ['Review data leakage or model promotion.'] }),
+];
+
+const SPEC_MINER = {
+  name: 'spec-miner',
+  role: 'spec-miner',
+  tier: 'heavy',
+  tools: ['read', 'search', 'edit'],
+  skills: [],
+  desc: 'Brownfield spec miner: extracts an anchored SDD draft from existing code under a bounded read budget. NOT feature planning or overwriting an approved spec.',
+  routing: {
+    should: ['Extract an initial SDD spec from an existing repository with no specs.'],
+    shouldNot: ['Design a new feature or amend an approved spec in place.'],
+  },
+  body: `You are the brownfield spec miner. Produce an **extracted draft**, never a claim that undocumented intent is approved.
+
+Read at most 40 files or 20,000 lines. Start from entry points, public interfaces, tests, schemas, migrations, configuration, and user-facing documentation. For every inferred invariant, cite a stable repository anchor (symbol plus path; line only as a convenience). Separate observed behavior, inferred requirement, contradiction, and unknown.
+
+Write a new SDD-shaped draft with problem, users, observable behavior, invariants, non-goals, acceptance criteria, source anchors, and open points. Mark status extracted-draft. If the intended slug already has an approved spec, do not edit it: propose a new slug or a revision artifact. Do not plan implementation or invent product intent absent from evidence.
+
+Return the read budget used, artifacts inspected, confidence per requirement, and the draft path.`,
+};
+
+const STACK_AGENTS = Object.freeze([...REVIEWERS, ...RESOLVERS, SPEC_MINER]);
+
+export const STACK_AGENT_BY_SKILL = Object.freeze(Object.fromEntries(
+  ['django', 'java', 'spring-boot', 'kotlin-android', 'flutter', 'react', 'nextjs', 'rust', 'swift-ios', 'go', 'cpp', 'vue-nuxt', 'csharp-dotnet', 'laravel', 'php', 'typescript', 'fastapi', 'python', 'postgresdb', 'rag', 'machine-learning']
+    .map((skill) => [skill, STACK_AGENTS.filter((agent) => agent.skills.includes(skill)).map((agent) => agent.name)]),
+));
+
+export const stackAgents = () => STACK_AGENTS.map((agent) => ({ ...agent, tools: [...agent.tools], skills: [...agent.skills], routing: { should: [...agent.routing.should], shouldNot: [...agent.routing.shouldNot] } }));
+export const stackAgentNames = () => STACK_AGENTS.map((agent) => agent.name);
+export const stackAgentByName = (name) => STACK_AGENTS.find((agent) => agent.name === name);
+
+export function resolveStackAgentNames(skillIds = [], explicitAgentIds = []) {
+  const names = new Set();
+  for (const skill of skillIds) for (const name of STACK_AGENT_BY_SKILL[skill] || []) names.add(name);
+  for (const name of explicitAgentIds) if (stackAgentByName(name)) names.add(name);
+  return [...names].sort();
+}
+
+export function validateAgentCatalog(definitions = STACK_AGENTS) {
+  const errors = [];
+  const seen = new Set();
+  const allowedRoles = new Set(['reviewer', 'build-resolver', 'spec-miner']);
+  for (const agent of definitions) {
+    const prefix = agent?.name || '<unnamed>';
+    if (!agent?.name || seen.has(agent.name)) errors.push(`${prefix}: unique name required`);
+    seen.add(agent?.name);
+    if (!agent?.desc?.includes('NOT ')) errors.push(`${prefix}: description requires a NOT boundary`);
+    if (!allowedRoles.has(agent?.role)) errors.push(`${prefix}: invalid role`);
+    if (!['balanced', 'heavy'].includes(agent?.tier)) errors.push(`${prefix}: tier must be balanced or heavy`);
+    if (!agent?.routing?.should?.length || !agent?.routing?.shouldNot?.length) errors.push(`${prefix}: routing cases required`);
+    if (Buffer.byteLength(agent?.body || '', 'utf8') > 6500) errors.push(`${prefix}: body exceeds 6500 bytes`);
+    if (/everything[- ]claude|affaan|worldflow|\.claude\/plugins\/ecc/iu.test(`${agent?.desc || ''}\n${agent?.body || ''}`)) errors.push(`${prefix}: foreign project vocabulary`);
+    if (agent?.role === 'reviewer' && JSON.stringify(agent.tools) !== JSON.stringify(REVIEW_TOOLS)) errors.push(`${prefix}: reviewer tools must be read-only`);
+    if (agent?.role === 'build-resolver' && JSON.stringify(agent.tools) !== JSON.stringify(RESOLVER_TOOLS)) errors.push(`${prefix}: resolver tools must be bounded`);
+  }
+  return errors;
+}

package/targets/agent-sources.json

@@ -0,0 +1,48 @@
+[
+  {
+    "agent": "go-reviewer",
+    "researchedAt": "2026-09-02",
+    "sources": [
+      {
+        "url": "https://go.dev/wiki/CodeReviewComments",
+        "coverage": ["error identity and wrapping", "goroutine lifetime", "interface values", "receiver and API review"]
+      },
+      {
+        "url": "https://go.dev/doc/comment",
+        "coverage": ["public API comments", "package and symbol contracts"]
+      },
+      {
+        "url": "https://go.dev/doc/contribute",
+        "coverage": ["review evidence and change scope"]
+      }
+    ]
+  },
+  {
+    "agent": "cpp-reviewer",
+    "researchedAt": "2026-09-02",
+    "sources": [
+      {
+        "url": "https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines.html",
+        "coverage": ["RAII and ownership", "lifetime and bounds safety", "concurrency", "exception guarantees"]
+      }
+    ]
+  },
+  {
+    "agent": "python-reviewer",
+    "researchedAt": "2026-09-02",
+    "sources": [
+      {
+        "url": "https://docs.python.org/3.14/library/asyncio-dev.html",
+        "coverage": ["un-awaited coroutines", "blocking async code", "thread boundaries"]
+      },
+      {
+        "url": "https://docs.python.org/3.14/library/asyncio-task.html",
+        "coverage": ["TaskGroup failure propagation", "cancellation", "task lifetime"]
+      },
+      {
+        "url": "https://docs.python.org/3.14/reference/datamodel.html",
+        "coverage": ["descriptors and protocols", "object and iterator lifetime"]
+      }
+    ]
+  }
+]