@ericrisco/rsc 1.1.5 → 1.2.0

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/commands.js

@@ -0,0 +1,212 @@
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { agentByName, allAgentNames } from './agents.js';
+
+const COMMAND_TARGETS = Object.freeze({
+  claude: { dir: '.claude/commands', ext: '.md', format: 'claude', skillsAreCommands: true },
+  cursor: { dir: '.cursor/commands', ext: '.md', format: 'plain' },
+  gemini: { dir: '.gemini/commands', ext: '.toml', format: 'gemini' },
+  opencode: { dir: '.opencode/commands', ext: '.md', format: 'opencode' },
+  copilot: { dir: '.github/prompts', ext: '.prompt.md', format: 'copilot' },
+  windsurf: { dir: '.windsurf/workflows', ext: '.md', format: 'windsurf' },
+  cline: { dir: '.clinerules/workflows', ext: '.md', format: 'plain', invocationSuffix: '.md' },
+  roo: { dir: '.roo/commands', ext: '.md', format: 'roo' },
+});
+
+export const COMMAND_TARGET_IDS = Object.freeze(Object.keys(COMMAND_TARGETS));
+export const targetHasCommands = (target) => Boolean(COMMAND_TARGETS[target]);
+
+const delegate = (kind, backing) => `Delegate this request to the ${backing} ${kind}. Pass the invocation arguments unchanged: {{ARGS}}\nDo not reproduce that ${kind}'s method here; load it and follow its own stopping and verification rules.`;
+
+const skillCommand = (name, backing = name) => ({
+  name,
+  kind: 'skill',
+  backing,
+  description: `Run the ${backing} skill through a short, non-duplicating entry point.`,
+  body: delegate('skill', backing),
+});
+
+const FIXED_COMMANDS = Object.freeze([
+  ...['specify', 'clarify', 'plan', 'tasks', 'analyze', 'implement', 'verify', 'review', 'ship', 'debug'].map((name) => skillCommand(name)),
+  {
+    name: 'build-fix', kind: 'resolver-selector', backing: 'build-resolver',
+    description: 'Route a build failure to the installed stack resolver without guessing.',
+    body: `Use an installed build-resolver for this failure: {{ARGS}}\nChoose from diagnostic text and affected paths. If more than one remains plausible, list the candidates and ask the user; never dispatch at random.`,
+  },
+  skillCommand('refactor-clean', 'simplify-code'),
+  {
+    name: 'test-coverage', kind: 'testing-skill', backing: 'testing-*',
+    description: 'Delegate coverage work to the installed stack testing skill.',
+    body: delegate('skill', 'testing-*'),
+  },
+  skillCommand('update-docs', 'knowledge-ops'),
+  {
+    name: 'checkpoint', kind: 'capability', backing: 'sello',
+    description: 'Freeze the current candidate for review and seal it only after the required lenses approve.',
+    body: `Use the sello backing for this checkpoint: {{ARGS}}\nRun \`npx @ericrisco/rsc sello freeze\`, complete the required review, then run \`sello approve\` only with the observed lenses. Do not treat freeze as approval.`,
+  },
+  skillCommand('harness-audit', 'harness'),
+  skillCommand('security-scan', 'security-scan'),
+  {
+    name: 'learn', kind: 'memory', backing: 'memory:learn',
+    description: 'Propose one local lesson; saving still requires individual explicit approval.',
+    body: `Invoke memory:learn for exactly one proposed lesson: {{ARGS}}\nAfter individual explicit approval, run \`npx @ericrisco/rsc memory learn\` with its text, evidence, scope, confidence and \`--approve\`. Without that approval, write nothing.`,
+  },
+  {
+    name: 'save-session', kind: 'memory', backing: 'memory:save',
+    description: 'Force a local deterministic session checkpoint.',
+    body: `Invoke memory:save with the current local session identifiers: {{ARGS}}\nRun \`npx @ericrisco/rsc memory save --session <id>\`. Persist only allowed git and SDD ledger metadata; never include conversation or file content.`,
+  },
+  {
+    name: 'resume-session', kind: 'memory', backing: 'memory:resume',
+    description: 'Read the bounded local continuation record for this branch and worktree.',
+    body: `Invoke memory:resume for the current branch and worktree: {{ARGS}}\nRun \`npx @ericrisco/rsc memory resume\`. Label a nearby branch result as nearby; never merge it silently into the exact continuation.`,
+  },
+]);
+
+export const fixedCommands = () => FIXED_COMMANDS.map((command) => ({ ...command }));
+export const fixedCommandNames = () => FIXED_COMMANDS.map((command) => command.name);
+
+function withBacking(command, backing, body) {
+  return { ...command, backing, body: body || command.body.replace(command.backing, backing) };
+}
+
+function fixedFor({ target, skills, agents, memoryMode }) {
+  const spec = COMMAND_TARGETS[target];
+  if (!spec) return [];
+  const skillSet = new Set(skills);
+  const resolverIds = agents.filter((id) => agentByName(id)?.role === 'build-resolver');
+  const testing = skills.filter((id) => id.startsWith('testing-')).sort();
+  const out = [];
+  for (const command of FIXED_COMMANDS) {
+    if (command.kind === 'skill') {
+      if (!skillSet.has(command.backing) || spec.skillsAreCommands) continue;
+      out.push({ ...command });
+    } else if (command.kind === 'testing-skill') {
+      if (!testing.length || spec.skillsAreCommands) continue;
+      out.push(withBacking(command, testing[0]));
+    } else if (command.kind === 'resolver-selector') {
+      if (!resolverIds.length) continue;
+      const backing = resolverIds.length === 1 ? resolverIds[0] : 'build-resolver';
+      const candidates = resolverIds.join(', ');
+      out.push(withBacking(command, backing,
+        `Choose the matching installed build-resolver from: ${candidates}. Pass the failure and invocation arguments unchanged: {{ARGS}}\nUse diagnostics and affected paths. If the choice is ambiguous, list candidates and ask; never dispatch at random.`));
+    } else if (command.kind === 'memory') {
+      if (!['full', 'assisted'].includes(memoryMode)) continue;
+      out.push({ ...command });
+    } else {
+      out.push({ ...command });
+    }
+  }
+  return out;
+}
+
+function stackAliases({ skills, agents }) {
+  const skillSet = new Set(skills);
+  const out = [];
+  for (const id of agents) {
+    const agent = agentByName(id);
+    if (!agent || !['reviewer', 'build-resolver'].includes(agent.role) || !agent.skills?.length) continue;
+    const installedAliases = agent.skills.filter((skill) => skillSet.has(skill));
+    const aliases = installedAliases.length ? installedAliases : [agent.skills[0]];
+    const suffix = agent.role === 'reviewer' ? 'review' : 'build';
+    for (const skill of aliases) {
+      out.push({
+        name: `${skill}-${suffix}`,
+        kind: 'agent',
+        backing: id,
+        description: `Delegate ${skill} ${suffix} work to the installed ${id} agent.`,
+        body: delegate('agent', id),
+      });
+    }
+  }
+  return out;
+}
+
+export function resolveCommands({ target, skills = [], agents = [], memoryMode = 'unsupported' }) {
+  if (!targetHasCommands(target)) return [];
+  const byName = new Map();
+  for (const command of [...fixedFor({ target, skills, agents, memoryMode }), ...stackAliases({ skills, agents })]) {
+    byName.set(command.name, command);
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function validateCommandCatalog(definitions = FIXED_COMMANDS) {
+  const errors = [];
+  const seen = new Set();
+  for (const command of definitions) {
+    const prefix = command?.name || '<unnamed>';
+    if (!command?.name || seen.has(command.name)) errors.push(`${prefix}: unique name required`);
+    seen.add(command?.name);
+    if (!command?.backing || !command?.body?.includes(command.backing)) errors.push(`${prefix}: body must name its exact backing`);
+    if ((command?.body || '').split('\n').length > 40) errors.push(`${prefix}: body exceeds 40 lines`);
+    if (/everything[- ]claude|affaan|worldflow/iu.test(`${command?.description || ''}\n${command?.body || ''}`)) errors.push(`${prefix}: foreign project vocabulary`);
+  }
+  return errors;
+}
+
+export function commandPath(target, cwd, name) {
+  const spec = COMMAND_TARGETS[target];
+  return spec ? join(cwd, ...spec.dir.split('/'), `${name}${spec.ext}`) : null;
+}
+
+function renderArgs(target, body) {
+  const placeholder = target === 'claude' || target === 'opencode' ? '$ARGUMENTS'
+    : target === 'gemini' ? '{{args}}'
+      : 'any text following the slash command';
+  return body.replaceAll('{{ARGS}}', placeholder);
+}
+
+function markdown(command, target) {
+  const body = renderArgs(target, command.body);
+  if (target === 'cursor' || target === 'cline') return `# /${command.name}\n\n${command.description}\n\n${body}\n`;
+  if (target === 'windsurf') return `# /${command.name}\n\n${command.description}\n\n1. ${body.replaceAll('\n', '\n2. ')}\n`;
+  const fm = ['---', `description: "${command.description.replaceAll('"', '\\"')}"`, 'argument-hint: "[arguments]"'];
+  if (target === 'copilot') fm.push('mode: agent');
+  if (target === 'opencode' && command.kind === 'agent') fm.push(`agent: ${command.backing}`);
+  fm.push('---', '');
+  return `${fm.join('\n')}${body}\n`;
+}
+
+function render(command, target) {
+  if (target !== 'gemini') return markdown(command, target);
+  const body = renderArgs(target, command.body);
+  return `description = ${JSON.stringify(command.description)}\nprompt = ${JSON.stringify(body)}\n`;
+}
+
+export function reconcileCommands(target, cwd, previousNames = [], desiredCommands = []) {
+  if (!targetHasCommands(target)) return { written: [], removed: [], collisions: [], names: [] };
+  const previous = new Set(previousNames);
+  const desiredNames = new Set(desiredCommands.map((command) => command.name));
+  const removed = [];
+  for (const name of previous) {
+    if (desiredNames.has(name)) continue;
+    const path = commandPath(target, cwd, name);
+    if (path && existsSync(path)) { rmSync(path, { force: true }); removed.push(path); }
+  }
+  const written = [];
+  const collisions = [];
+  const names = [];
+  for (const command of desiredCommands) {
+    const path = commandPath(target, cwd, command.name);
+    if (existsSync(path) && !previous.has(command.name)) {
+      collisions.push(path);
+      continue;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, render(command, target));
+    written.push(path);
+    names.push(command.name);
+  }
+  return { written, removed, collisions, names };
+}
+
+export function allPotentialCommandNames() {
+  const names = new Set(fixedCommandNames());
+  // Every stack alias follows directly from catalog metadata; no second mapping.
+  const agents = allAgentNames();
+  const skills = [...new Set(agents.flatMap((id) => agentByName(id)?.skills || []))];
+  for (const command of stackAliases({ skills, agents })) names.add(command.name);
+  return [...names];
+}