@ericrisco/rsc 1.0.22 → 1.0.24

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.22",
+  "version": "1.0.24",
   "counts": {
     "skills": 264
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/install-apply.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { rmSync, existsSync, cpSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { planInstall } from './install-plan.js';
 import { targetPaths, writeSkill, wireHook, unwireHook, baseDir, TARGET_IDS } from '../targets/index.js';
-import { targetHasAgents, writeDeveloperAgent, removeDeveloperAgent, developerAgentPath } from '../targets/agents.js';
+import { targetHasAgents, writeAgents, removeAgents, agentPath, agentNames } from '../targets/agents.js';
 import { readState, writeState } from './lib/state.js';
 import { createBackup } from './lib/backups.js';
 
@@ -70,7 +70,7 @@ function managedPathsForInstall({ skillIds, target, home, cwd }) {
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd });
   const out = [paths.stateFile, versionFile(cwd), baseVersionsFile(cwd)];
-  if (targetHasAgents(target)) out.push(developerAgentPath(target, cwd), join(cwd, '.rsc', 'developer.json'));
+  if (targetHasAgents(target)) out.push(...agentNames().map((n) => agentPath(target, cwd, n)), join(cwd, '.rsc', 'developer.json'));
   for (const step of plan) {
     if (step.kind === 'skill') {
       out.push(step.to, baseDir(step.id, cwd));
@@ -103,11 +103,18 @@ export async function applyInstall({ skillIds, target, home, cwd = process.cwd()
     }
   }
   writeBaseVersions(cwd, baseVersions);
-  // Install the `developer` subagent for targets that support file-based agents (Claude
-  // Code, Cursor, OpenCode, Gemini, Copilot, Junie, Kiro, Codex). It runs at the balanced
-  // tier by default (never light/Haiku); the tier lives in .rsc/developer.json, set by
-  // `init` at onboarding and honored on every (re)install/sync.
-  if (targetHasAgents(target)) state.agents = writeDeveloperAgent(target, cwd).length ? ['developer'] : [];
+  // Install the catalog's subagents for targets that support file-based agents (Claude
+  // Code, Cursor, OpenCode, Gemini, Copilot, Junie, Kiro, Codex): `developer` plus the three
+  // adversarial refuter lenses `review` dispatches at tier 2. They run at the balanced tier
+  // by default (never light/Haiku); the tier lives in .rsc/developer.json, set by `init` at
+  // onboarding and honored on every (re)install/sync.
+  //
+  // The recorded names come from what was WRITTEN, not from a hardcoded list: a state entry
+  // naming an agent whose file never landed answers "you have it" for something absent.
+  if (targetHasAgents(target)) {
+    const written = writeAgents(target, cwd);
+    state.agents = written.map((f) => basename(f).split('.')[0]);
+  }
   state.version = CLI_VERSION;
   writeState(paths.stateFile, state);
   mkdirSync(dirname(versionFile(cwd)), { recursive: true });
@@ -214,9 +221,12 @@ export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRu
     }
     // unwireHook mutates files, so only run it for real (dry runs skip it).
     if (!dryRun) removed.push(...unwireHook(target, paths));
-    // Remove the installed developer subagent (agent-capable targets only).
-    const agentFile = developerAgentPath(target, cwd);
-    if (agentFile) drop(agentFile);
+    // Remove the subagents this catalog installed — and only those. An uninstaller that takes
+    // an agent the user wrote by hand is worse than one that leaves residue.
+    for (const n of agentNames()) {
+      const agentFile = agentPath(target, cwd, n);
+      if (agentFile) drop(agentFile);
+    }
   }
   drop(join(cwd, '.rsc'), true);
   if (withDocs) drop(join(cwd, '02-DOCS'), true);

package/scripts/knowledge-doctor.js

@@ -19,9 +19,16 @@ import { diagnose, CLASSES } from './lib/knowledge-doctor.js';
 const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
 const WIKI = join(REPO, '02-DOCS', 'wiki');
 
-const walk = (dir) => readdirSync(dir).flatMap((e) => {
-  const p = join(dir, e);
-  return statSync(p).isDirectory() ? walk(p) : (p.endsWith('.md') ? [p] : []);
+// withFileTypes, NOT statSync — this matches scripts/drift-check.js:167, the precedent the plan cited
+// as exact and then diverged from. statSync FOLLOWS symlinks, so a symlink under the wiki let the walk
+// read outside the declared zone (reporting the logical path, hiding the escape), a dangling symlink
+// crashed the whole report with ENOENT, and a symlink cycle crashed it with ELOOP. dirent.isDirectory()
+// does none of that: a symlink is neither a file nor a directory here, so it is skipped.
+const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+  const p = join(dir, e.name);
+  if (e.isDirectory()) return walk(p);
+  if (e.isFile() && p.endsWith('.md')) return [p];
+  return []; // symlinks, sockets, anything else: not our business, and not a crash
 });
 
 // Injected so the pure library never touches git. Cached: the same ref is asked about repeatedly.
@@ -48,19 +55,49 @@ function main() {
   const indexPath = join(WIKI, 'index.md');
   const indexText = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : null;
 
+  // AC7 says an unreadable document is a candidate with its reason, never a silent skip. The first
+  // version read "unreadable" as "frontmatter unparseable" only, so a chmod-000 file or a dangling
+  // symlink threw out of readFileSync and took the WHOLE report with it — worse than a silent skip.
+  const unreadable = [];
   const docs = files.map((p) => {
     const rel = relative(WIKI, p);
+    let text;
+    try {
+      text = readFileSync(p, 'utf8');
+    } catch (e) {
+      unreadable.push({
+        path: relative(REPO, p), line: 1, cls: 'fuera-de-sitio', uncertain: true,
+        signal: `no se pudo leer el fichero (${e.code || e.message})`,
+        expected: 'un documento legible', found: e.code || 'error de lectura',
+      });
+      return null;
+    }
     return {
       path: relative(REPO, p),
       rel,
       dir: dirname(rel) === '.' ? '' : dirname(rel),
-      text: readFileSync(p, 'utf8'),
+      text,
       // Only artifacts the chain consumes are expected in the Knowledge map; an article is not.
       indexable: rel.startsWith('sdd/specs/') || rel.startsWith('sdd/verifications/'),
     };
-  });
+  }).filter(Boolean);
+
+  // Project artifacts outside the wiki: skill ids and script basenames. The library cannot read the
+  // repo (it is pure by design), so the caller that can, does.
+  const extraSlugs = [];
+  for (const [dir, strip] of [['skills', null], ['scripts', /\.(js|mjs|sh)$/], ['scripts/lib', /\.(js|mjs)$/]]) {
+    try {
+      for (const e of readdirSync(join(REPO, dir), { withFileTypes: true })) {
+        if (strip && e.isFile()) extraSlugs.push(e.name.replace(strip, ''));
+        else if (!strip && e.isDirectory()) extraSlugs.push(e.name);
+      }
+    } catch { /* a missing directory is not an error here */ }
+  }
 
-  const report = diagnose({ docs, indexText, refExists });
+  const report = diagnose({ docs, indexText, refExists, extraSlugs });
+  // Unreadable files are candidates too, and they sort first: a document nobody can open is the one
+  // whose staleness nobody can check.
+  if (unreadable.length) report.candidates = [...unreadable, ...report.candidates];
   if (asJson) { console.log(JSON.stringify(report, null, 2)); process.exit(0); }
 
   const byClass = (c) => report.candidates.filter((x) => x.cls === c);
@@ -69,10 +106,15 @@ function main() {
     console.log('Sin candidatos. Nada que triar.\n');
   } else {
     console.log(`${report.candidates.length} candidato(s), ordenados por coste de equivocarse:\n`);
+    // Filenames are interpolated into markdown, and a filename may contain newlines and backticks. A
+    // crafted name rendered a structurally valid FORGED candidate while the tally below still read 0 —
+    // and the consumer of this report (knowledge-ops) archives and overwrites files. Neutralise the
+    // three characters that can break out of the line.
+    const safe = (s) => String(s).replace(/[\r\n]+/g, '⏎').replace(/`/g, "'");
     for (const c of report.candidates) {
-      console.log(`- **${c.cls}** · \`${c.path}:${c.line}\`${c.uncertain ? ' · _incierto_' : ''}`);
-      console.log(`  - señal: ${c.signal}`);
-      console.log(`  - esperado: ${c.expected} · encontrado: ${c.found}`);
+      console.log(`- **${c.cls}** · \`${safe(c.path)}:${c.line}\`${c.uncertain ? ' · _incierto_' : ''}`);
+      console.log(`  - señal: ${safe(c.signal)}`);
+      console.log(`  - esperado: ${safe(c.expected)} · encontrado: ${safe(c.found)}`);
     }
     console.log('');
     for (const [label, cls] of [['se contradice', CLASSES.CONTRADICTS], ['ya no aplica', CLASSES.STALE], ['fuera de sitio', CLASSES.MISPLACED]]) {

package/scripts/lib/knowledge-doctor.js

@@ -27,7 +27,11 @@ export const CLASSES = { STALE: 'ya-no-aplica', MISPLACED: 'fuera-de-sitio', CON
 
 // Out of scope, named so their absence is not read as cleanliness.
 export const NOT_LOOKED_AT = [
-  'La PRIMERA instancia de una desviación de convención: las convenciones se derivan del wiki en cada corrida, así que un único fichero fuera de sitio define su propia ubicación como válida. Deliberado — hardcodear la tabla sería una segunda copia de la verdad que deriva de ella.',
+  // This entry described the PRE-FIX dead-code behaviour and survived the fix that removed it: a stale
+  // claim inside the tool built to find stale claims. Rewritten to name the mechanism that actually
+  // ships — the 75% dominant-share threshold — and its real blind spot.
+  'Un tipo con pocos documentos: una carpeta solo se reconoce como el hogar de un `type:` cuando concentra el 75% de sus documentos, así que un tipo con 3 o menos ejemplares no tiene hogar y su ubicación nunca se juzga. Deliberado — la alternativa es marcar trabajo correcto (`article` vive legítimamente en tres carpetas).',
+  'Documentos alcanzados por symlink: el recorrido usa `withFileTypes` y salta los enlaces, así que un `.md` enlazado dentro del wiki no se audita. Es el precio de impedir que el recorrido se escape de `02-DOCS/` siguiendo un enlace.',
   'Contradicción general entre documentos (exige comparación semántica; fuera por clarify 18-08).',
   'Obsolescencia semántica de prosa: si un párrafo sobre arquitectura sigue siendo cierto.',
   'La memoria del proyecto: drift-check ya resuelve sus rutas vía memoryDir(); su auditoría semántica queda fuera.',
@@ -58,9 +62,43 @@ export function parseFrontmatter(text) {
 }
 
 /** Does this document declare itself the single source of a fact? Matched on normalized prose. */
+/**
+ * Does this document declare ITSELF the single source of a fact?
+ *
+ * The first version matched `fuente única` / `single source of` anywhere in the file, and an adversarial
+ * review measured what that admits: on a 51-document wiki, **7 documents passed and only 1 actually
+ * declared single-sourcehood**. The other six were meta-documents merely DISCUSSING the concept — this
+ * detector's own spec, its own plan, and three verification records — and five of them had an unrelated
+ * first table sitting there as a denominator. One ordinary edit adding "probado 9 veces" to any of their
+ * descriptions would have fabricated a contradiction against a table with nothing to do with the number.
+ * That is over-firing on correct work, the direction P7 and the v1.0.17 rule both name as the dangerous
+ * one, and the whole narrow scope agreed in clarify rested on this gate being narrow.
+ *
+ * So the phrase must now be SELF-REFERENTIAL: the document has to point at itself ("esta tabla", "this
+ * table", "aquí") as the place the fact lives. Talking about single sources in the abstract no longer
+ * qualifies.
+ */
 export function declaresSingleSource(text) {
   const p = normalizeProse(text);
-  return /en ning[uú]n otro sitio|and nowhere else|fuente [uú]nica|single source of/i.test(p);
+  // A locator ("en esta tabla", "in this table", "aquí") within a short window of the exclusivity
+  // claim. The window keeps it one sentence: a doc that says "esta tabla" in one paragraph and
+  // "fuente única" three pages later is not declaring anything.
+  const claim = /(en esta (tabla|lista)|in this (table|list)|aqu[ií] y en ning|here and nowhere)/i;
+  const exclusive = /(en ning[uú]n otro sitio|and nowhere else|nowhere else|fuente [uú]nica de|single source of truth for)/i;
+  if (!claim.test(p) || !exclusive.test(p)) return false;
+  // And they must be near each other, or two unrelated sentences pass by coincidence.
+  const ci = p.search(claim);
+  const ei = p.search(exclusive);
+  if (Math.abs(ci - ei) > 160) return false;
+  // A QUOTED phrase is a citation, not a declaration. Measured: two documents still passed after the
+  // narrowing above, and both were quoting this repo's own pattern registry — a spec and a verification
+  // record. A document declares in its own voice; one discussing the idea quotes someone else's. Both
+  // are exactly the kind of document whose description naturally gains "probado 9 veces", which is how
+  // the fabricated contradiction would have arrived.
+  const around = p.slice(Math.max(0, ei - 60), ei + 60);
+  const quoted = /["«“][^"»”]{0,120}$/.test(p.slice(Math.max(0, ei - 120), ei))
+    && /^[^"«“]{0,120}["»”]/.test(p.slice(ei));
+  return !quoted || /\*\*/.test(around) === false ? !quoted : false;
 }
 
 const WORD_NUMBERS = {
@@ -72,9 +110,14 @@ const WORD_NUMBERS = {
  * A count asserted in the FRONTMATTER only. Body prose is not a usable signal: the live case's own
  * document contains "7 veces" inside a table cell describing something else entirely.
  */
+export const MAX_REFS_PER_DOC = 32;
+// A frontmatter value longer than this is not a title or a description. Bound before matching: the
+// digit-run pattern is quadratic, measured at 21.5s on an 160k-character value.
+const MAX_FM_VALUE = 2000;
+
 export function statedCountInFrontmatter(fields) {
   for (const key of ['description', 'title']) {
-    const v = String(fields[key] || '');
+    const v = String(fields[key] || '').slice(0, MAX_FM_VALUE);
     const digits = /(\d+)\s+(?:veces|times|apariciones|occurrences)/i.exec(v);
     if (digits) return { value: Number(digits[1]), source: key, literal: digits[0] };
     const words = new RegExp(`\\b(${Object.keys(WORD_NUMBERS).join('|')})\\s+(?:veces|times)`, 'i').exec(v);
@@ -83,9 +126,22 @@ export function statedCountInFrontmatter(fields) {
   return null;
 }
 
-/** Data rows of the first markdown table (header and separator excluded). */
+/**
+ * Blank out fenced code blocks, keeping the line count intact so reported line numbers stay true.
+ * Without this, an illustrative table inside ``` fences counted as the canonical one: a real 3-row
+ * table read as 1 row, and the report printed two wrong numbers as its evidence.
+ */
+export function stripFences(body) {
+  let inFence = false;
+  return String(body || '').split('\n').map((l) => {
+    if (/^\s*(```|~~~)/.test(l)) { inFence = !inFence; return ''; }
+    return inFence ? '' : l;
+  }).join('\n');
+}
+
+/** Data rows of the first markdown table (header and separator excluded), fences excluded. */
 export function firstTableRowCount(body) {
-  const lines = String(body || '').split('\n');
+  const lines = stripFences(body).split('\n');
   let i = lines.findIndex((l) => /^\s*\|.*\|/.test(l) && /\|/.test(l));
   if (i === -1) return null;
   if (!/^\s*\|[\s:|-]+\|/.test(lines[i + 1] || '')) return null; // header must be followed by a separator
@@ -107,9 +163,29 @@ export function findStaleClaims({ path, text, refExists }) {
   if (!status) return [];
   const out = [];
   const refs = new Set();
-  for (const m of status.matchAll(/\b([0-9a-f]{7,8})\b/g)) refs.add(m[1]);
-  for (const m of status.matchAll(/\bv?(\d+\.\d+\.\d+)\b/g)) refs.add(`v${m[1]}`);
-  for (const ref of refs) {
+  // A short hex run is only a commit if it is NOT all digits: `20260818` is a compact date, and the
+  // old pattern reported it as a missing commit. Verified: `status: implementada el 20260818` produced
+  // a candidate for a ref that never existed as a ref.
+  for (const m of status.matchAll(/\b([0-9a-f]{7,8})\b/g)) {
+    if (/^\d+$/.test(m[1])) continue;
+    refs.add(m[1]);
+  }
+  // A version is only a tag claim when the text presents it as one. `requiere node 18.0.0 y ajv 8.18.0`
+  // used to yield two candidates for tags `v18.0.0` and `v8.18.0` — dependency versions read as releases.
+  for (const m of status.matchAll(/\b(?:v|versión |version |publicada en |released in |released as )(\d+\.\d+\.\d+)\b/gi)) {
+    refs.add(`v${m[1]}`);
+  }
+  // Cap the spawns a single document can cause: one status: with 3000 distinct refs spawned 6002 git
+  // processes and took 76s. A document citing more than this is not making a traceable claim.
+  const capped = [...refs].slice(0, MAX_REFS_PER_DOC);
+  if (refs.size > MAX_REFS_PER_DOC) {
+    out.push({
+      path, line: lineOf(text, 'status:'), cls: CLASSES.STALE, uncertain: true,
+      signal: `status: cita ${refs.size} referencias; solo se comprobaron las primeras ${MAX_REFS_PER_DOC}`,
+      expected: `un status: con referencias acotadas`, found: `${refs.size} referencias`,
+    });
+  }
+  for (const ref of capped) {
     if (refExists(ref)) continue;
     out.push({
       path, line: lineOf(text, 'status:'), cls: CLASSES.STALE,
@@ -120,6 +196,21 @@ export function findStaleClaims({ path, text, refExists }) {
   return out;
 }
 
+/**
+ * Is there an actual index ROW for this path — a list item whose markdown link targets it?
+ *
+ * The first version was `indexText.includes(doc.rel)`, a substring test, so a path merely MENTIONED in
+ * prose silenced the check: "Borramos sdd/specs/x.md porque ya no aplica" counted as indexed. That is
+ * verbatim the mistake this repo recorded as having shipped twice in one day — "the path appears in the
+ * string" is not "the row exists" — and it fails in the under-firing direction, which is the quiet one.
+ */
+export function hasIndexRow(indexText, rel) {
+  if (!rel) return false;
+  const escaped = rel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const row = new RegExp(`^\\s*[-*]\\s.*\\]\\([^)]*${escaped}\\)`, 'm');
+  return row.test(String(indexText || ''));
+}
+
 /**
  * Class 2 — out of place. Conventions are DERIVED from the wiki on every run, never hardcoded:
  * a hardcoded table is a second copy of the truth and drifts from it.
@@ -214,7 +305,7 @@ export function findMisplaced({ doc, conventions, indexText }) {
       });
     }
   }
-  if (indexText != null && doc.indexable && !indexText.includes(doc.rel)) {
+  if (indexText != null && doc.indexable && !hasIndexRow(indexText, doc.rel)) {
     out.push({
       path: doc.path, line: 1, cls: CLASSES.MISPLACED,
       signal: 'artefacto sin fila en el Knowledge map',
@@ -224,6 +315,44 @@ export function findMisplaced({ doc, conventions, indexText }) {
   return out;
 }
 
+/**
+ * Class 2b — an entry in a canonical log that does not describe what that log says it contains.
+ *
+ * AC2 of the spec, and it was NOT implemented in the shipped version — found by two independent
+ * refuter lenses. It is not a nice-to-have: one of the three incidents that motivated the whole spec
+ * was four entries written into `decisions.md` by eval agents, about features nobody was building.
+ * Worse than absent, the disclosure list did not name it, so the report presented the canonical log as
+ * scanned and clean — affirming a check nobody performed.
+ *
+ * The signal has to be narrow or this becomes the noisiest detector in the tool. A canonical log
+ * declares its own subject in its opening prose ("Procedimientos que el asistente observó",
+ * "decisiones de alcance"). An entry is a candidate when its heading names a SLUG that exists nowhere
+ * in the project — because a decision about `magic-link-login` when no such spec, plan or artifact
+ * exists is either about someone else's work or about work nobody is doing.
+ */
+export function findLogIntruders({ path, text, knownSlugs }) {
+  if (!/decisions\.md$|automation-gaps\.md$/.test(path)) return [];
+  const out = [];
+  const lines = String(text || '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const h = /^##\s+\d{4}-\d{2}-\d{2}\s*[—·-]\s*(.+)$/.exec(lines[i]);
+    if (!h) continue;
+    // A slug-shaped token in the heading: lowercase words joined by hyphens, at least two parts.
+    const slugs = (h[1].match(/`?\b([a-z][a-z0-9]+(?:-[a-z0-9]+)+)\b`?/g) || [])
+      .map((s) => s.replace(/`/g, ''));
+    const orphans = slugs.filter((s) => !knownSlugs.has(s));
+    // Only flag when EVERY slug in the heading is unknown: a heading mixing known and unknown terms is
+    // ordinary prose, not an entry about work that does not exist.
+    if (!slugs.length || orphans.length !== slugs.length) continue;
+    out.push({
+      path, line: i + 1, cls: CLASSES.MISPLACED, uncertain: true,
+      signal: `entrada cuyo asunto (${orphans.map((s) => `\`${s}\``).join(', ')}) no corresponde a ningún artefacto del proyecto`,
+      expected: 'una entrada sobre trabajo que existe', found: 'asunto sin artefacto',
+    });
+  }
+  return out;
+}
+
 /** Class 3 — a frontmatter count contradicting the table the document declares its single source. */
 export function findContradictions({ path, text }) {
   if (!declaresSingleSource(text)) return [];
@@ -253,13 +382,26 @@ export function rank(candidates) {
 }
 
 /** The whole pass, over already-read documents. Pure: no fs, no git — both are injected. */
-export function diagnose({ docs, indexText, refExists }) {
+export function diagnose({ docs, indexText, refExists, extraSlugs = [] }) {
   const cands = [];
   const conventions = deriveConventions(docs);
+  // Slugs the project actually has, derived from the documents themselves (P3: the content is the
+  // ledger). A log entry whose subject is not in here is about work that does not exist.
+  // extraSlugs comes from the CLI, which knows the repo: skill ids and script basenames are project
+  // artifacts too. Deriving only from wiki filenames flagged `drift-check` — a real script — as work
+  // that does not exist.
+  const knownSlugs = new Set(extraSlugs);
+  for (const doc of docs) {
+    const base = (doc.rel || doc.path).split('/').pop().replace(/\.md$/, '').replace(/\.plan$/, '');
+    knownSlugs.add(base);
+    const fmSlug = parseFrontmatter(doc.text).fields.slug;
+    if (fmSlug) knownSlugs.add(fmSlug);
+  }
   for (const doc of docs) {
     cands.push(...findStaleClaims({ path: doc.path, text: doc.text, refExists }));
     cands.push(...findMisplaced({ doc, conventions, indexText }));
     cands.push(...findContradictions({ path: doc.path, text: doc.text }));
+    cands.push(...findLogIntruders({ path: doc.path, text: doc.text, knownSlugs }));
   }
   return { candidates: rank(cands), scanned: docs.length, notLookedAt: NOT_LOOKED_AT };
 }

package/targets/agents.js

@@ -1,5 +1,10 @@
-// rsc developer agent — installed with the harness for every target that supports
-// file-based subagents with a per-agent model. The agent runs at the `balanced` tier
+// rsc agent registry — the agents installed with the harness for every target that supports
+// file-based subagents with a per-agent model.
+//
+// This file shipped ONE agent with its name, description and body as module constants. Adding a
+// second was therefore not "copy a block": it was turning the file into a registry without breaking
+// the `developer` installs already deployed to users. The registry is the work; the refuters are its
+// first client. See 02-DOCS/wiki/sdd/specs/refuter-agent.md. The agent runs at the `balanced` tier
 // (never `light`/Haiku): Sonnet for Anthropic-backed tools, the provider's mid model
 // elsewhere. The chosen tier (balanced default, or heavy) lives in `.rsc/developer.json`,
 // written by `init` at onboarding and read here so re-syncs honor it.
@@ -33,9 +38,31 @@ const AGENT_TARGETS = {
 export const AGENT_TARGET_IDS = Object.keys(AGENT_TARGETS);
 export function targetHasAgents(target) { return Boolean(AGENT_TARGETS[target]); }
 
-const NAME = 'developer';
-const DESC = 'Implementation worker: turns an approved spec+plan into working, tested code under strict TDD (red->green->refactor), one task at a time. The rsc SDD fan-out/implementation hand.';
-const BODY = `You are the **developer** subagent for this project — the hands of the rsc SDD chain. You execute a planned, approved task into working, tested code. You do NOT design features.
+// The contract every refuter shares, in ONE place. Three lens files each carry the lens inside them
+// (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:**
+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.
+
+**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.
+
+**Blind first, compare second.** Record what you attacked and what you found BEFORE you are shown the builder's conclusions. Only then may you compare and add findings; the blind record is append-only after that, never rewritten. Skip this and your fresh context is spent confirming their framing, which is the one thing it was bought to avoid.
+
+**The attack list is the deliverable, not just the findings.** "Nothing found" without saying where you looked is indistinguishable from not having looked.
+
+**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 = [
+  {
+    name: 'developer',
+    desc: 'Implementation worker: turns an approved spec+plan into working, tested code under strict TDD (red->green->refactor), one task at a time. The rsc SDD fan-out/implementation hand.',
+    body: `You are the **developer** subagent for this project — the hands of the rsc SDD chain. You execute a planned, approved task into working, tested code. You do NOT design features.
 
 - Work **test-first**: smallest failing test (RED), least code to pass it (GREEN), then refactor on green. A test that never failed proves nothing.
 - One task at a time; keep the diff to that task's scope — no "while I'm here".
@@ -43,7 +70,54 @@ const BODY = `You are the **developer** subagent for this project — the hands
 - If there is no approved spec + plan for non-trivial feature work, STOP and route to \`specify\` — do not write feature code.
 - Log non-obvious decisions to \`02-DOCS/wiki/sdd/decisions.md\`. Report your diff + test output at the end.
 
-Full discipline lives in the \`implement\` skill.`;
+Full discipline lives in the \`implement\` skill.`,
+  },
+  {
+    name: 'refuter-correctness',
+    desc: 'Adversarial reviewer, correctness lens: attacks a green diff for boundary and error-path defects, and demands that any home-grown gate prove it can both fail and pass. Fresh context, mandate to refute.',
+    body: `You are the **correctness** refuter for this project — one of three adversarial lenses ${'`review`'} dispatches at tier 2. What matters is not the number of lenses but their **diversity**: the worst defect this panel ever found was found by the privacy lens, which was not looking for it.
+
+${REFUTER_CONTRACT}
+
+**Your lens — correctness on the boundaries, not the happy path:** off-by-one, null/empty/zero, error paths swallowed, races, the wrong operator, a value that is correct in one function and unchecked in its twin.
+
+**And the lens this panel was missing:** when the change adds or touches a **gate, checker or guard**, ask it in BOTH directions.
+- Can it fail? Feed it a known-bad input and watch it fail. A gate nobody has seen fail is not a gate.
+- **Can it pass?** Feed it a known-good input and watch it pass. Over-blocking is not the safe side — a gate that fires on correct work gets muted, worked around, or wedges the pipeline that depends on it, and it is *harder* to notice because it arrives dressed as diligence.
+- Watch for a check that matches **text** where it should match **structure**: "the path appears in the string" is not "the write targets that location". That exact mistake shipped twice in one day here.`,
+  },
+  {
+    name: 'refuter-security',
+    desc: 'Adversarial reviewer, security and privacy lens: hunts untrusted input reaching a sink, authz gaps, leaked secrets and data escaping where it should not. Fresh context, mandate to refute.',
+    body: `You are the **security and privacy** refuter for this project — one of three adversarial lenses ${'`review`'} dispatches at tier 2. Your value is that you are not looking where the others look: the worst defect this panel ever found was found by this lens, chasing something else entirely.
+
+${REFUTER_CONTRACT}
+
+**Your lens:** untrusted input reaching a sink (injection, SSRF, path traversal), authorization gaps (authenticated is not authorized), secrets in the diff or in config, and **data leaving where it should not** — a log line, an error message, a file written outside its zone, a payload sent to a third party.
+
+**Follow the trail rather than the checklist.** When something looks merely untidy — a file in an odd place, a path that repeats — ask who else cares about that location before dismissing it. That is how this lens found the worst one.`,
+  },
+  {
+    name: 'refuter-tests',
+    desc: 'Adversarial reviewer, tests-as-evidence lens: tries to make the suite pass wrongly, invents mutants the builder did not choose, and checks the spec-to-test mapping in both directions. Fresh context, mandate to refute.',
+    body: `You are the **tests-as-evidence** refuter for this project — one of three adversarial lenses ${'`review`'} dispatches at tier 2.
+
+${REFUTER_CONTRACT}
+
+**Your lens — try to make the suite pass wrongly:** implementation keyed to test inputs, mocks swallowing the logic under test, assertions that cannot fail, coverage that touches lines without asserting anything.
+
+**Invent mutants the builder did not choose.** Their mutant list encodes their blind spots. Watch for tests that pin less than they claim — a boundary pinned in one function and not in its twin, a magnitude left free while its boundary is fixed, an assertion satisfied by a caller that never arrived. **Before reporting a surviving mutant, prove it diverges:** construct a concrete input where mutant and original disagree. A survivor you cannot make disagree is an equivalent mutant, and reporting it sends someone to write a test that asserts non-behaviour.
+
+**Check the mapping both ways:** every acceptance criterion needs a falsification procedure that can be made to fail, and every test should trace to something someone asked for.`,
+  },
+];
+
+// 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);
+export const agentNames = () => AGENTS.map((a) => a.name);
 
 // `.rsc/developer.json` — the chosen tier (balanced default; never light). `init` writes
 // it on the onboarding answer; the installer reads it so every (re)install/sync matches.
@@ -60,39 +134,57 @@ export function writeDeveloperTier(cwd, tier) {
   return t;
 }
 
-function renderMd(spec, model) {
-  const fm = ['---', `name: ${NAME}`, `description: "${DESC}"`, `model: ${model}`];
+function renderMd(spec, model, agent) {
+  const fm = ['---', `name: ${agent.name}`, `description: "${agent.desc}"`, `model: ${model}`];
   if (spec.mode) fm.push(`mode: ${spec.mode}`);
   fm.push('---', '');
-  return `${fm.join('\n')}${BODY}\n`;
+  return `${fm.join('\n')}${agent.body}\n`;
 }
-const renderJson = (model) => `${JSON.stringify({ name: NAME, description: DESC, model, prompt: BODY }, null, 2)}\n`;
-function renderToml(model) {
+const renderJson = (model, agent) => `${JSON.stringify({ name: agent.name, description: agent.desc, model, 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 = "${NAME}"\ndescription = "${esc(DESC)}"\nmodel = "${model}"\ndeveloper_instructions = '''\n${BODY}\n'''\n`;
+  return `name = "${agent.name}"\ndescription = "${esc(agent.desc)}"\nmodel = "${model}"\ndeveloper_instructions = '''\n${agent.body}\n'''\n`;
 }
 
-export function developerAgentPath(target, cwd) {
+export function agentPath(target, cwd, name = 'developer') {
   const spec = AGENT_TARGETS[target];
-  return spec ? join(cwd, ...spec.dir.split('/'), `${NAME}${spec.ext}`) : null;
+  return spec ? join(cwd, ...spec.dir.split('/'), `${name}${spec.ext}`) : null;
 }
 
-export function writeDeveloperAgent(target, cwd, tier = readDeveloperTier(cwd)) {
+export function writeAgents(target, cwd, tier = readDeveloperTier(cwd)) {
   const spec = AGENT_TARGETS[target];
   if (!spec) return [];
   const model = spec.model(tier);
-  const content = spec.format === 'json' ? renderJson(model)
-    : spec.format === 'toml' ? renderToml(model)
-      : renderMd(spec, model);
-  const path = developerAgentPath(target, cwd);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, content);
-  return [path];
+  const written = [];
+  for (const agent of AGENTS) {
+    const content = spec.format === 'json' ? renderJson(model, agent)
+      : spec.format === 'toml' ? renderToml(model, agent)
+        : renderMd(spec, model, agent);
+    const path = agentPath(target, cwd, agent.name);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    written.push(path);
+  }
+  return written;
 }
 
-export function removeDeveloperAgent(target, cwd) {
-  const path = developerAgentPath(target, cwd);
-  if (path && existsSync(path)) { rmSync(path, { force: true }); return [path]; }
-  return [];
+/**
+ * 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) {
+  const removed = [];
+  for (const agent of AGENTS) {
+    const path = agentPath(target, cwd, agent.name);
+    if (path && existsSync(path)) { rmSync(path, { force: true }); removed.push(path); }
+  }
+  return removed;
 }
+
+// ── back-compat aliases. Kept because `developer` is already installed in user repos and in
+// capabilities.js's spec derivation; renaming their imports is not worth breaking a deployed install.
+export const developerAgentPath = (target, cwd) => agentPath(target, cwd, 'developer');
+export const writeDeveloperAgent = (target, cwd, tier = readDeveloperTier(cwd)) => writeAgents(target, cwd, tier);
+export const removeDeveloperAgent = (target, cwd) => removeAgents(target, cwd);
+export { byName as agentByName };