@ericrisco/rsc 1.1.6 → 1.2.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"]
+      }
+    ]
+  }
+]

package/targets/agents.js

@@ -10,6 +10,10 @@
 // written by `init` at onboarding and read here so re-syncs honor it.
 import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import {
+  stackAgents, stackAgentNames, stackAgentByName,
+  resolveStackAgentNames, validateAgentCatalog,
+} from './agent-catalog.js';
 
 // Concrete model per provider per tier. June 2026 defaults — EDIT to your account's
 // models; the TIER is the contract, the id is yours to change. `light` is deliberately
@@ -42,13 +46,15 @@ export function targetHasAgents(target) { return Boolean(AGENT_TARGETS[target]);
 // (decided in clarify 2026-08-18: a lens passed as a parameter reintroduces the
 // does-anyone-remember dependency this whole spec exists to remove) — but P5 says length is a cost,
 // so the contract they share is composed, not written three times.
-const REFUTER_CONTRACT = `Your mandate is to **refute readiness**, not confirm it. A reviewer looking for confirmation finds confirmation; the asymmetry is the point.
-
-**You get exactly four inputs, and nothing else:**
+export const REFUTER_FOUR_INPUTS = `**You get exactly four inputs, and nothing else:**
 1. The task contract — the original request **plus every scope change a human explicitly approved since**. Without the approved changes, a legitimate scope revision reads as a spec gap and you will report a confident false positive.
 2. The approved spec.
 3. The exact source state (commit SHA, or a tree hash when git is absent). A verdict attaches to the state you saw, not to the project.
-4. The entry point — the one command that reruns the checks.
+4. The entry point — the one command that reruns the checks.`;
+
+const REFUTER_CONTRACT = `Your mandate is to **refute readiness**, not confirm it. A reviewer looking for confirmation finds confirmation; the asymmetry is the point.
+
+${REFUTER_FOUR_INPUTS}
 
 **You do NOT get** the builder's conversation, reasoning, defences, or draft verdict. If a claim needs the builder's justification to stand, it is not proven.
 
@@ -56,6 +62,16 @@ const REFUTER_CONTRACT = `Your mandate is to **refute readiness**, not confirm i
 
 **The attack list is the deliverable, not just the findings.** "Nothing found" without saying where you looked is indistinguishable from not having looked.
 
+**Before reporting any finding, answer all four questions:**
+1. Can you cite the **exact changed line**?
+2. Can you state the **concrete input, state, and wrong result**? The concrete input and state must be explicit.
+3. Did you inspect the relevant **caller, import, and relevant test**?
+4. Can the severity survive the **existing guards** you verified?
+
+If an answer is no, lower the severity or omit the finding. Every **HIGH or CRITICAL** needs the line and failure mode in the report. **Zero findings with an attack list is valid.**
+
+**Common false positives to reject:** an equivalent mutant with no diverging input; a documented dummy value that never reaches a sink; a deliberate boundary already enforced by a caller; generated/vendor code outside the change; style preference presented as correctness; and a theoretical race with no shared state or overlapping lifetime.
+
 **A finding blocks only if it is caused by this change, is severe, and carries evidence** — a repro or a concrete failure scenario. A suspicion without one is a question, and questions do not block. You fix nothing: findings return through the normal loop, and a SPEC gap goes to the human, never to the builder to self-amend.`;
 
 const AGENTS = [
@@ -112,11 +128,18 @@ ${REFUTER_CONTRACT}
   },
 ];
 
+export const BASE_AGENT_NAMES = Object.freeze(AGENTS.map((agent) => agent.name));
+export { stackAgents, stackAgentNames, validateAgentCatalog };
+export const allAgentNames = () => [...BASE_AGENT_NAMES, ...stackAgentNames()];
+export function resolveAgentNames(skillIds = [], explicitAgentIds = []) {
+  return [...BASE_AGENT_NAMES, ...resolveStackAgentNames(skillIds, explicitAgentIds)];
+}
+
 // Back-compat: the tier file and its reader are named for `developer` because that is what they
 // configure. The refuters run at the same tier — a deliberate, reversible default: nobody has measured
 // whether a heavier model finds more here, and silently tripling tier-2 cost on an unmeasured hunch is
 // the wrong way to find out.
-const byName = (name) => AGENTS.find((a) => a.name === name);
+const byName = (name) => AGENTS.find((a) => a.name === name) || stackAgentByName(name);
 export const agentNames = () => AGENTS.map((a) => a.name);
 
 // `.rsc/developer.json` — the chosen tier (balanced default; never light). `init` writes
@@ -137,14 +160,16 @@ export function writeDeveloperTier(cwd, tier) {
 function renderMd(spec, model, agent) {
   const fm = ['---', `name: ${agent.name}`, `description: "${agent.desc}"`, `model: ${model}`];
   if (spec.mode) fm.push(`mode: ${spec.mode}`);
+  if (agent.tools) fm.push(`tools: [${agent.tools.join(', ')}]`);
   fm.push('---', '');
   return `${fm.join('\n')}${agent.body}\n`;
 }
-const renderJson = (model, agent) => `${JSON.stringify({ name: agent.name, description: agent.desc, model, prompt: agent.body }, null, 2)}\n`;
+const renderJson = (model, agent) => `${JSON.stringify({ name: agent.name, description: agent.desc, model, ...(agent.tools ? { tools: agent.tools } : {}), prompt: agent.body }, null, 2)}\n`;
 function renderToml(model, agent) {
   const esc = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
   // body as a TOML multiline LITERAL string ('''…''') — no escape processing.
-  return `name = "${agent.name}"\ndescription = "${esc(agent.desc)}"\nmodel = "${model}"\ndeveloper_instructions = '''\n${agent.body}\n'''\n`;
+  const tools = agent.tools ? `tools = [${agent.tools.map((tool) => `"${tool}"`).join(', ')}]\n` : '';
+  return `name = "${agent.name}"\ndescription = "${esc(agent.desc)}"\nmodel = "${model}"\n${tools}developer_instructions = '''\n${agent.body}\n'''\n`;
 }
 
 export function agentPath(target, cwd, name = 'developer') {
@@ -152,12 +177,15 @@ export function agentPath(target, cwd, name = 'developer') {
   return spec ? join(cwd, ...spec.dir.split('/'), `${name}${spec.ext}`) : null;
 }
 
-export function writeAgents(target, cwd, tier = readDeveloperTier(cwd)) {
+export function writeAgents(target, cwd, tier = readDeveloperTier(cwd), names = agentNames()) {
   const spec = AGENT_TARGETS[target];
   if (!spec) return [];
-  const model = spec.model(tier);
   const written = [];
-  for (const agent of AGENTS) {
+  for (const name of names) {
+    const agent = byName(name);
+    if (!agent) continue;
+    const effectiveTier = agent.tier === 'heavy' ? 'heavy' : tier;
+    const model = spec.model(effectiveTier);
     const content = spec.format === 'json' ? renderJson(model, agent)
       : spec.format === 'toml' ? renderToml(model, agent)
         : renderMd(spec, model, agent);
@@ -169,14 +197,34 @@ export function writeAgents(target, cwd, tier = readDeveloperTier(cwd)) {
   return written;
 }
 
+export function reconcileAgents(target, cwd, tier, previousNames = [], desiredNames = []) {
+  if (!targetHasAgents(target)) return { written: [], removed: [], collisions: [], names: [] };
+  const previous = new Set(previousNames);
+  const desired = new Set(desiredNames);
+  const removed = removeAgents(target, cwd, [...previous].filter((name) => !desired.has(name)));
+  const written = [];
+  const collisions = [];
+  const names = [];
+  for (const name of desiredNames) {
+    const path = agentPath(target, cwd, name);
+    if (existsSync(path) && !previous.has(name)) {
+      collisions.push(path);
+      continue;
+    }
+    written.push(...writeAgents(target, cwd, tier, [name]));
+    if (existsSync(path)) names.push(name);
+  }
+  return { written, removed, collisions, names };
+}
+
 /**
  * Remove only the agents this catalog ships. An uninstaller that takes an agent the user wrote by hand
  * is worse than one that leaves residue.
  */
-export function removeAgents(target, cwd) {
+export function removeAgents(target, cwd, names = allAgentNames()) {
   const removed = [];
-  for (const agent of AGENTS) {
-    const path = agentPath(target, cwd, agent.name);
+  for (const name of names) {
+    const path = agentPath(target, cwd, name);
     if (path && existsSync(path)) { rmSync(path, { force: true }); removed.push(path); }
   }
   return removed;

package/targets/claude.js

@@ -85,6 +85,9 @@ export function wireHook(paths) {
   // Shared by session-start + userprompt-gate. Hooks are materialized file by file, so a module
   // they import must be copied as their SIBLING — a subdirectory import would break once copied.
   copyFileSync(join(HERE, 'hook-once.mjs'), join(paths.projectRoot, '.rsc', 'hook-once.mjs'));
+  // Same reason: session-start imports the reaper for the landed-worktree sweep, so it travels as a
+  // sibling too. Missing it does not break startup — the sweep is wrapped — it just goes silent.
+  copyFileSync(join(HERE, 'worktree-reaper.mjs'), join(paths.projectRoot, '.rsc', 'worktree-reaper.mjs'));
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
 
   const suggestMd = `${paths.skillDir('suggest')}/SKILL.md`;