@ericrisco/rsc 1.0.4 → 1.0.6

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.4",
+  "version": "1.0.6",
   "counts": {
     "skills": 258
   },
@@ -4348,7 +4348,7 @@
     },
     {
       "id": "skill-scout",
-      "description": "Use when a specialized skill probably exists but is not loaded, when a task feels harder than it should because generic reasoning is doing a domain skill's job, or when auditing a workspace's skill coverage for holes. Names the absent skill and emits an install command, or routes onward when none exists. NOT routing among skills you already have (that is `suggest`), NOT writing the skill when none exists (that is `author-skill`).",
+      "description": "Use when a specialized skill probably exists but is not loaded, when a task feels harder than it should because generic reasoning is doing a domain skill's job, when the work just delivered was a repeatable procedure worth turning into a skill or an agent, or when auditing coverage for holes. Resolves against what already exists — installed skills, catalog skills and agent files — then names the gap and emits the install command. NOT routing among skills you already have (that is `suggest`), NOT writing the artifact when none exists (that is `author-skill` for skills, `building-agents` for agents).",
       "tags": [
         "skill-discovery",
         "capability-gap",

package/package.json

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

package/scripts/doctor.js

@@ -7,6 +7,7 @@ import { loadManifest } from './lib/manifest.js';
 import { listBackups } from './lib/backups.js';
 import { SDD_GATE_TEXT } from '../targets/hook-once.mjs';
 import { isEnabled, checkSello, readSello, countFindings, readEffectiveConfig, validateRiskConfig } from '../targets/sello.mjs';
+import { countGaps } from './lib/capabilities.js';
 
 // The sello's health, surfaced where the user already looks (spec: non-blocking
 // findings live in the project and are SUMMARIZED here, never nagged about).
@@ -56,6 +57,8 @@ export function doctor({ target, home, cwd }) {
     },
     contextBudget: contextBudget({ target, home, cwd }),
     sello: selloStatus(root),
+    // Counted, never interpreted — by spec, the gap log's reader is the user.
+    automationGaps: countGaps(root),
   };
   for (const [id, e] of Object.entries(state.skills)) {
     for (const f of e.files) if (!existsSync(f)) report.missing.push(`${id}:${f}`);

package/scripts/eval-lint.sh

@@ -7,6 +7,16 @@ set -euo pipefail
 #   >= 5 should_trigger entries
 #   >= 4 should_not_trigger entries
 #   >= 1 capability scenario
+#   every should_not_trigger route_to resolves (see below)
+#
+# route_to is the one that used to be decorative: the rubric listed "route_to names a
+# real skill" as a deterministic gate and nothing checked it, so evals accumulated
+# routes to skills that were never authored. Each value must now be one of:
+#   - a real catalog skill id (a directory under skills/ with a SKILL.md)
+#   - "none" — deliberately nothing to route to
+#   - "external:<name>" — a skill outside this catalog, on purpose. Some skills
+#     legitimately defer to tools that ship elsewhere; the prefix makes that a
+#     visible, greppable claim instead of a typo indistinguishable from drift.
 #
 # Uses python3 for real YAML parsing when available. If python3 is missing,
 # falls back to a basic structural grep check and SKIPs the deep validation
@@ -36,7 +46,7 @@ warned_skip=0
 validate_py() {
   cy="$1"
   CASES_YAML="$cy" MIN_TRIGGER="$MIN_TRIGGER" MIN_NOT_TRIGGER="$MIN_NOT_TRIGGER" \
-  MIN_CAPABILITY="$MIN_CAPABILITY" python3 - <<'PYEOF'
+  MIN_CAPABILITY="$MIN_CAPABILITY" VALID_IDS="$VALID_IDS" python3 - <<'PYEOF'
 import os, sys
 try:
     import yaml
@@ -72,7 +82,39 @@ st = count("should_trigger")
 sn = count("should_not_trigger")
 cap = count("capability")
 
+# --- route_to resolution -------------------------------------------------------
+# Accepts a real catalog id, "none", or "external:<name>". A value may be a list,
+# or a string holding several targets separated by comma / | / " or ".
+valid = set(filter(None, os.environ.get("VALID_IDS", "").split(",")))
+NOTHING = {"none", "n/a", "-", ""}
+bad_routes = []
+
+def targets(value):
+    items = value if isinstance(value, list) else [value]
+    out = []
+    for item in items:
+        for part in str(item).replace("|", ",").replace(" or ", ",").split(","):
+            out.append(part.strip().strip("`"))
+    return out
+
+for case in (data.get("should_not_trigger") or []):
+    if not isinstance(case, dict) or case.get("route_to") is None:
+        continue
+    for t in targets(case["route_to"]):
+        low = t.lower()
+        if low in NOTHING:
+            continue
+        if low.startswith("external:"):
+            if not low[len("external:"):].strip():
+                bad_routes.append('"external:" with no name')
+            continue
+        if valid and t not in valid:
+            bad_routes.append(t)
+
 reasons = []
+if bad_routes:
+    uniq = sorted(set(bad_routes))
+    reasons.append("route_to does not resolve: %s (use a real skill id, \"none\", or \"external:<name>\")" % ", ".join(uniq))
 if st < 0:
     reasons.append("should_trigger is not a list")
 elif st < mt:
@@ -112,8 +154,17 @@ validate_grep() {
 
 echo "eval-lint: scanning $SKILLS_DIR"
 echo "minimums: should_trigger>=$MIN_TRIGGER should_not_trigger>=$MIN_NOT_TRIGGER capability>=$MIN_CAPABILITY"
+echo "route_to must resolve: a catalog skill id, \"none\", or \"external:<name>\""
 echo
 
+# The set of real skill ids, built once from disk — the same surface the router sees.
+VALID_IDS=""
+for sp in "$SKILLS_DIR"/*; do
+  [ -f "$sp/SKILL.md" ] || continue
+  VALID_IDS="$VALID_IDS,$(basename "$sp")"
+done
+VALID_IDS="${VALID_IDS#,}"
+
 # Iterate skills deterministically; bash 3.2-safe (no mapfile).
 for skill_path in "$SKILLS_DIR"/*; do
   [ -d "$skill_path" ] || continue

package/scripts/install-apply.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { rmSync, existsSync, cpSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { rmSync, existsSync, cpSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { planInstall } from './install-plan.js';
@@ -112,9 +112,35 @@ export async function applyInstall({ skillIds, target, home, cwd = process.cwd()
   writeState(paths.stateFile, state);
   mkdirSync(dirname(versionFile(cwd)), { recursive: true });
   writeFileSync(versionFile(cwd), CLI_VERSION + '\n');
+  ignoreLocalState(cwd);
   return { ...state, backup };
 }
 
+// `.rsc/` holds local machine state — hook scripts, install markers, the sello's
+// seals, the automation-gap log. None of it belongs in a user's repository, and the
+// gap log in particular is prose about what happened in their project: a routine
+// `git add -A` would publish it. Nothing used to keep that out, so add the entry.
+//
+// Additive and idempotent by construction: append one line to an existing
+// .gitignore, never rewrite or reorder it, and never create the file in a directory
+// that is not a git repository.
+export function ignoreLocalState(cwd = process.cwd()) {
+  if (!existsSync(join(cwd, '.git'))) return null;
+  const gi = join(cwd, '.gitignore');
+  let text = '';
+  try { text = existsSync(gi) ? readFileSync(gi, 'utf8') : ''; } catch { return null; }
+  const already = text.split('\n').some((l) => {
+    const s = l.trim().replace(/\/$/, '');
+    return s === '.rsc' || s === '/.rsc';
+  });
+  if (already) return null;
+  const prefix = text === '' ? '' : (text.endsWith('\n') ? '' : '\n');
+  try {
+    appendFileSync(gi, `${prefix}\n# rsc local state (hooks, seals, logs) — machine-local, never committed\n.rsc/\n`);
+    return gi;
+  } catch { return null; }
+}
+
 export function listInstalled({ target, home, cwd = process.cwd() }) {
   const paths = targetPaths(target, home, cwd);
   return Object.keys(readState(paths.stateFile).skills);

package/scripts/lib/capabilities.js

@@ -0,0 +1,189 @@
+// capabilities.js — "what do I already have that solves this?", answered by a
+// command instead of by the model's memory.
+//
+// The automation-gap rule says: never propose BUILDING a skill or an agent before
+// checking whether one already exists. A rule like that is only real if something
+// enumerates the existing set — otherwise it is a decorative gate, the defect class
+// this repo has paid for repeatedly. This file is that something.
+//
+// Three sources, one shape:
+//   installed  — skill artifacts ON DISK, project and user scope, each tagged
+//   available  — catalog skills not installed anywhere (ids; --full adds descriptions)
+//   agents     — agent files on disk, project and user scope, each tagged
+//
+// Both skills and agents are read from DISK, never from the install state file: a
+// state entry whose files were deleted would otherwise answer "covered — use it"
+// for something that is not there, and that answer has no recovery path.
+//
+// 8 of 17 targets have file-based agents; on the other 9 the agent is advisory and
+// there is nothing to enumerate. That is `agentsSupported: false`, never an error —
+// the caller drops the agent branch instead of failing.
+
+import { existsSync, readdirSync, statSync, appendFileSync, readFileSync, mkdirSync } from 'node:fs';
+import { join, dirname, basename, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { loadManifest } from './manifest.js';
+import { targetPaths } from '../../targets/index.js';
+import { developerAgentPath, targetHasAgents } from '../../targets/agents.js';
+
+// AGENT_TARGETS is not exported, so derive dir + extension from the one path helper
+// that owns it — duplicating that table is how two copies drift apart. The extension
+// is taken as everything after the agent's name, because `extname()` cannot recover a
+// COMPOUND extension: copilot writes `developer.agent.md`, where extname says '.md',
+// which both mis-names the agent and degrades the filter to every markdown file.
+const AGENT_NAME = 'developer';
+function agentSpecFor(target, root) {
+  const p = developerAgentPath(target, root);
+  if (!p) return null;
+  const base = basename(p);
+  const i = base.indexOf(AGENT_NAME);
+  const ext = i === 0 ? base.slice(AGENT_NAME.length) : base.slice(base.indexOf('.'));
+  return { dir: dirname(p), ext };
+}
+
+// Real files only. Directories (a dir named `foo.md` is not an agent), dangling
+// symlinks and dotfiles are not capabilities.
+function entriesWithExt(dir, ext) {
+  if (!dir || !existsSync(dir)) return [];
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((e) => !e.name.startsWith('.') && e.name.endsWith(ext) && e.name.length > ext.length)
+      .filter((e) => {
+        if (e.isFile()) return true;
+        if (!e.isSymbolicLink()) return false;
+        try { return statSync(join(dir, e.name)).isFile(); } catch { return false; } // dangling
+      })
+      .map((e) => e.name)
+      .sort();
+  } catch { return []; }
+}
+
+// Project scope first, then user scope — unless they are the same directory (a
+// project that IS the home dir, plausible for the non-code harnesses), where one
+// artifact must not be reported twice.
+function bothScopes(cwd, home, forRoot) {
+  const project = forRoot(cwd);
+  const user = forRoot(home);
+  const same = project?.dir && user?.dir && resolve(project.dir) === resolve(user.dir);
+  return same ? [[project, 'project']] : [[project, 'project'], [user, 'user']];
+}
+
+export function listAgents({ target, home, cwd = process.cwd() } = {}) {
+  if (!targetHasAgents(target)) return { supported: false, agents: [] };
+  const agents = [];
+  for (const [spec, scope] of bothScopes(cwd, home || homedir(), (r) => agentSpecFor(target, r))) {
+    if (!spec) continue;
+    for (const name of entriesWithExt(spec.dir, spec.ext)) {
+      agents.push({ id: name.slice(0, -spec.ext.length), scope, path: join(spec.dir, name) });
+    }
+  }
+  return { supported: true, agents };
+}
+
+// Installed skills, read from disk in both scopes. `skillExt` targets (cursor) store
+// each skill as a single file; the rest use a directory per skill.
+export function listSkills({ target, home, cwd = process.cwd() } = {}) {
+  const out = [];
+  for (const [paths, scope] of bothScopes(cwd, home || homedir(), (r) => {
+    try { const p = targetPaths(target, r, r); return { dir: p.root, probe: p.skillDir('__probe__') }; }
+    catch { return null; }
+  })) {
+    if (!paths?.dir || !existsSync(paths.dir)) continue;
+    const ext = basename(paths.probe).replace('__probe__', ''); // '' for dir-per-skill targets
+    try {
+      for (const e of readdirSync(paths.dir, { withFileTypes: true })) {
+        if (e.name.startsWith('.')) continue;
+        if (ext) { if (e.isFile() && e.name.endsWith(ext)) out.push({ id: e.name.slice(0, -ext.length), scope }); }
+        else if (e.isDirectory() && existsSync(join(paths.dir, e.name, 'SKILL.md'))) out.push({ id: e.name, scope });
+      }
+    } catch { /* unreadable scope → contributes nothing */ }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id) || a.scope.localeCompare(b.scope));
+}
+
+// Keep the discriminator: a description's value is its `NOT x (that is y)` boundary,
+// so never cut it off. Trim the middle instead when the whole thing is long.
+export function shortDesc(d, limit = 220) {
+  const s = String(d || '').replace(/\s+/g, ' ').trim();
+  if (s.length <= limit) return s;
+  const not = s.search(/\bNOT\b/);
+  if (not > 0) {
+    const tail = s.slice(not);
+    const head = s.slice(0, Math.max(0, limit - tail.length - 2));
+    if (head) return `${head.trim()}… ${tail}`;
+  }
+  return `${s.slice(0, limit - 1)}…`;
+}
+
+// `full: true` adds catalog descriptions. Off by default because the catalog's
+// descriptions are ~40 KB and `rsc catalog --available` already serves meaning-based
+// matching — paying for the same bytes twice is the cost this harness keeps cutting.
+export function capabilities({ target, home, cwd = process.cwd(), full = false } = {}) {
+  const manifest = loadManifest();
+  const byId = new Map(manifest.skills.map((s) => [s.id, s]));
+  const skills = listSkills({ target, home, cwd });
+  const installedIds = new Set(skills.map((s) => s.id));
+  const { supported, agents } = listAgents({ target, home, cwd });
+  return {
+    target,
+    agentsSupported: supported,
+    installed: skills.map((s) => ({ ...s, description: shortDesc(byId.get(s.id)?.description) })),
+    available: manifest.skills
+      .filter((s) => !installedIds.has(s.id))
+      .map((s) => (full ? { id: s.id, description: shortDesc(s.description) } : { id: s.id }))
+      .sort((a, b) => a.id.localeCompare(b.id)),
+    agents,
+  };
+}
+
+// --- the gap log ---------------------------------------------------------------
+//
+// Written through this function, never by a skill composing markdown by hand — a
+// free-form writer drifts in format within a few sessions and then nothing can read
+// it back. Nothing DOES read it back (by spec): its reader is the user, and doctor
+// only counts entries.
+//
+// PRIVACY: `procedure` is the assistant's own description of what it observed doing.
+// The user's literal request must never be passed here. This function enforces SHAPE
+// ONLY — it cannot tell a description from a paraphrase, and it does not pretend to.
+// The rule lives in skills/skill-scout/SKILL.md, where it is held by whoever writes.
+
+export const GAP_VERDICTS = [
+  'covered-installed', 'covered-catalog', 'covered-agent',
+  'proposed-accepted', 'proposed-declined',
+];
+
+export function gapLogPath(cwd = process.cwd()) {
+  return join(cwd, '.rsc', 'automation-gaps.md');
+}
+
+// Any whitespace run collapses, not just \n: a lone \r is a CommonMark line ending,
+// so it would render as an extra (forged, dated) entry while `cat` hid it.
+const oneLine = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+
+export function appendGap({ procedure, verdict, cwd = process.cwd(), now }) {
+  const text = oneLine(procedure);
+  if (!text) throw new Error('gap-log: a procedure description is required. Recover: pass --procedure "<what you observed doing>" — your own description of the work, never the user\'s words.');
+  if (!GAP_VERDICTS.includes(verdict)) {
+    throw new Error(`gap-log: verdict must be one of ${GAP_VERDICTS.join(', ')}. Recover: re-run with a valid --verdict.`);
+  }
+  const p = gapLogPath(cwd);
+  mkdirSync(dirname(p), { recursive: true });
+  let needsHeader = true;
+  try { needsHeader = statSync(p).size === 0; } catch { needsHeader = true; }
+  const header = needsHeader
+    ? '# Huecos de automatización\n\nProcedimientos que el asistente observó y qué pasó con ellos. Lo escribe `rsc capabilities gap-log`.\nDebe contener solo la descripción que el asistente hizo de su propio trabajo, no peticiones del usuario — es una regla que sostiene quien escribe, no algo que el código pueda comprobar. Fichero local: no lo commitees.\n\n'
+    : '';
+  const d = now || new Date();
+  const day = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+  appendFileSync(p, `${header}- ${day} · ${text} · **${verdict}**\n`);
+  return p;
+}
+
+export function countGaps(cwd = process.cwd()) {
+  try {
+    const p = gapLogPath(cwd);
+    if (!existsSync(p)) return 0;
+    return readFileSync(p, 'utf8').split('\n').filter((l) => /^- \d{4}-\d{2}-\d{2} · /.test(l)).length;
+  } catch { return 0; } // a malformed log must never take down `doctor`
+}

package/scripts/rsc.js

@@ -327,6 +327,49 @@ async function main() {
       say('Use: npx @ericrisco/rsc registry refresh | registry status');
       return;
     }
+    case 'capabilities': {
+      // "What do I already have that solves this?" — the deterministic step the
+      // automation-gap rule requires BEFORE anyone proposes creating a skill or an
+      // agent. Without this command that rule would rest on the model's memory.
+      const { capabilities, appendGap, countGaps } = await import('./lib/capabilities.js');
+      const { resolveRoot } = await import('../targets/sello.mjs');
+      // A string flag must not swallow the next FLAG as its value (`flag()` returns
+      // the following token blindly), or `--procedure --verdict x` records "--verdict".
+      const str = (name) => {
+        const v = flag(name);
+        return typeof v === 'string' && !v.startsWith('--') ? v : undefined;
+      };
+      // Subcommand by presence, not by position: `capabilities --target claude gap-log`
+      // used to fall through and silently record nothing.
+      if (argv.includes('gap-log')) {
+        // The writer and doctor must agree on the root, or a run from a subdirectory
+        // writes a log nothing counts.
+        const root = resolveRoot(process.cwd());
+        try {
+          const p = appendGap({ procedure: str('procedure'), verdict: str('verdict'), cwd: root });
+          say(`📝 recorded (${countGaps(root)} total): ${p}`);
+        } catch (e) { say(e.message); process.exitCode = 1; }
+        return;
+      }
+      const full = argv.includes('--full');
+      const reports = targets.map((t) => capabilities({ target: t, full }));
+      if (argv.includes('--json')) {
+        return void say(JSON.stringify(reports.length === 1 ? reports[0] : reports, null, 2));
+      }
+      for (const caps of reports) {
+        if (reports.length > 1) say(`# target: ${caps.target}`);
+        for (const s of caps.installed) say(`skill\t${s.id}\tinstalled-${s.scope}\t${s.description}`);
+        for (const s of caps.available) say(`skill\t${s.id}\tavailable${s.description ? `\t${s.description}` : ''}`);
+        if (caps.agentsSupported) {
+          for (const a of caps.agents) say(`agent\t${a.id}\t${a.scope}\t${a.path}`);
+          if (!caps.agents.length) say('# no agent files found (this target supports them)');
+        } else {
+          say(`# ${caps.target} has no file-based agents — the agent option does not apply here`);
+        }
+      }
+      if (!full) say('# catalog shown as ids; add --full for descriptions, or use `catalog --available` to match by meaning');
+      return;
+    }
     case 'sello': {
       // Deterministic transitions of the sello (review receipt). The `review` skill
       // orchestrates the lenses; every state change and every check runs HERE, token-free.
@@ -508,7 +551,8 @@ 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 | audit | registry refresh | doctor | sync | sello <on|off|status|…> | backups | restore <id|latest> | upgrade | 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 | sello <on|off|status|…> | backups | restore <id|latest> | upgrade | uninstall <id> | purge');
+      process.exitCode = 1;
   }
 }
 

package/scripts/skill-rubric.md

@@ -16,7 +16,7 @@ dishonest 9.
 | 3 | **Body craft & progressive disclosure** | 0.15 | **The smallest body that routes correctly** — ≤400 lines is a ceiling, not a target, and there is no minimum: a skill that does its job in 60 lines scores higher than the same skill padded to 200. Every `references/` file is pointed to inline from this body (an unlinked reference is never loaded, so it is dead weight). rsc voice, every fence language-tagged, a checklist/decision table only where the flow branches, an anti-patterns table present. |
 | 4 | **Correctness, grounding & freshness** | **0.25** | Every load-bearing claim is accurate and **current (2025–2026)**: real library/API versions, no hallucinated flags/endpoints. The spec cites **authoritative sources with dates**; nothing rests on stale or invented facts. This is the heaviest dimension by design. |
 | 5 | **Actionability** | 0.15 | Concrete and runnable: real numbers, paths, commands, decision rules — not adjectives. A practitioner could act from it without leaving the skill. |
-| 6 | **Evals quality** | 0.10 | ≥5 `should_trigger` (incl. non-obvious), ≥4 `should_not_trigger` each with a `route_to` that names a **real** sibling, ≥1 `capability` with a meaningful `must_include` rubric. The cases are genuine, not filler. |
+| 6 | **Evals quality** | 0.10 | ≥5 `should_trigger` (incl. non-obvious), ≥4 `should_not_trigger` each with a `route_to` that resolves — a **real** catalog id, `none`, or `external:<name>` (enforced by `eval-lint`), ≥1 `capability` with a meaningful `must_include` rubric. The cases are genuine, not filler. |
 | 7 | **Originality & safety** | 0.10 | rsc voice, not a clone of any external catalog (no borrowed urgency blocks / rationalization tables / `*-reviewer-prompt.md` conventions / verbatim flowcharts). `verify.sh` present iff there is a checkable artifact. No destructive or unsafe advice presented without guardrails. |
 
 **Weighted score** = Σ(subscore × weight), rounded to 1 decimal. **Ship gate: ≥ 8.5.**

package/skills/author-skill/references/eval-authoring.md

@@ -17,7 +17,7 @@ Everything lives in `evals/cases.yaml` (the cases) and `evals/README.md` (how to
 
 `scripts/eval-lint.sh` parses every `cases.yaml` and fails the build only on the **structural minimums**: that `evals/cases.yaml` exists, that `should_trigger`, `should_not_trigger`, and `capability` are present as lists, and that their item counts meet **≥ 5 / ≥ 4 / ≥ 1**. (Without python3+PyYAML it degrades to a presence-only key check.) Run it before shipping to catch a missing or undersized section.
 
-It does **not** read inside the entries. Whether each `should_not_trigger` carries a `route_to`, whether that `route_to` names a sibling that actually exists in this repo, whether your `should_trigger` set includes a genuinely non-obvious or non-English phrasing, and whether each `capability` scenario has a real `must_include` rubric of gradeable points — none of that is enforced by the linter. Those are **author and review responsibilities**: verify them by hand (and in the self-audit / code-review pass) before shipping. A green eval-lint means the shape is right, not that the cases are good.
+It also resolves every `route_to`: each value must be a real catalog skill id, `none`, or `external:<name>` for a skill that deliberately lives outside this catalog — a stale route now fails the build. What it still does **not** read: whether each `should_not_trigger` actually carries a `route_to`, whether your `should_trigger` set includes a genuinely non-obvious or non-English phrasing, and whether each `capability` scenario has a real `must_include` rubric of gradeable points. Those are **author and review responsibilities**: verify them by hand (and in the self-audit / code-review pass) before shipping. A green eval-lint means the shape is right, not that the cases are good.
 
 ## cases.yaml structure
 
@@ -33,7 +33,7 @@ should_trigger:
 
 should_not_trigger:
   - prompt: "A near-miss that looks close but belongs elsewhere."
-    route_to: "sibling-id"   # a skill that ACTUALLY exists in this repo, or "none"
+    route_to: "sibling-id"   # a real catalog id, "none", or "external:<name>" — checked by eval-lint
     why: "Why it is NOT this skill and why the sibling owns it."
   # … ≥ 4 total
 
@@ -53,7 +53,7 @@ capability:
 
 ## Writing good `should_not_trigger` cases
 
-These are where descriptions get sharpened. Each near-miss should be genuinely tempting — adjacent in topic but owned by a sibling. The `route_to` must name a skill that **exists in this repo**; a `route_to` pointing at a non-existent skill is a defect. Pick the siblings most likely to be confused with this one and write a case that disambiguates each.
+These are where descriptions get sharpened. Each near-miss should be genuinely tempting — adjacent in topic but owned by a sibling. The `route_to` must name a skill that **exists in this repo** — `eval-lint` fails the build otherwise. If the right owner genuinely ships outside this catalog, say so with `external:<name>` rather than inventing an id: the prefix makes the claim visible instead of indistinguishable from drift. Pick the siblings most likely to be confused with this one and write a case that disambiguates each.
 
 For `author-skill`, the natural confusables are `specify`/`plan` (building a feature, not a skill), `building-agents` (agent loops), `harness` (generic docs/wiki), and `init` (bootstrapping). Route each near-miss to whichever it truly belongs to.
 

package/skills/building-agents/evals/cases.yaml

@@ -24,7 +24,7 @@ should_not_trigger:
     route_to: "none"
     why: "One-shot throwaway prompt with no tools/eval/production path — the skill says just call the SDK directly."
   - prompt: "Tune Anthropic prompt caching and extended thinking in our anthropic-only client.py to cut latency on a file that only imports the anthropic SDK."
-    route_to: "claude-api"
+    route_to: "external:claude-api"
     why: "Single-vendor Anthropic-SDK internals tuning in a file that only imports anthropic defers to the dedicated Anthropic skill; this skill stays multi-provider."
   - prompt: "Write the pgvector schema and an HNSW-indexed nearest-neighbour SQL query, plus tuning advice — just the database side, no LLM calls."
     route_to: "postgresdb"

package/skills/course-storytelling/evals/cases.yaml

@@ -22,14 +22,14 @@ should_not_trigger:
     route_to: "marketing"
     why: "Sales/landing copy for the course is marketing's domain. The skill teaches; it never bolts a pitch on, and explicitly defers selling words to marketing."
   - prompt: "Audit module 14 of my course for gaps, redundancy, anachronisms, and outdated stack references, and give me a written report."
-    route_to: "review-content"
+    route_to: "external:review-content"
     why: "Diagnostic content-audit pass with a written report. The skill says run review-content first and bring findings here; it rebuilds, it does not audit."
   - prompt: "Design a color system, typography scale, and diagram style for my course slides."
     route_to: "design"
     why: "Pure visual system / pixels. The skill defers the visual layer to design; it owns narrative, not aesthetics."
   - prompt: "Fact-check whether the historical claims in my lesson about the origins of TCP are actually accurate, with sources."
-    route_to: "deep-research"
-    why: "Pure fact-checking/research of subject matter, not reframing teaching. The skill forbids inventing proof and defers verification to deep-research."
+    route_to: "research-ops"
+    why: "Pure fact-checking/research of subject matter, not reframing teaching. The skill forbids inventing proof and defers verification to a research pass — `research-ops` in this catalog, a deep-research tool where the environment provides one."
 
 capability:
   - scenario: "A learner profile already exists and is complete in 02-DOCS/wiki/teaching/. The user gives a flat, definition-only lesson on 'idempotency' for a mid-level backend course and asks to make it land."

package/skills/skill-scout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-scout
-description: "Use when a specialized skill probably exists but is not loaded, when a task feels harder than it should because generic reasoning is doing a domain skill's job, or when auditing a workspace's skill coverage for holes. Names the absent skill and emits an install command, or routes onward when none exists. NOT routing among skills you already have (that is `suggest`), NOT writing the skill when none exists (that is `author-skill`)."
+description: "Use when a specialized skill probably exists but is not loaded, when a task feels harder than it should because generic reasoning is doing a domain skill's job, when the work just delivered was a repeatable procedure worth turning into a skill or an agent, or when auditing coverage for holes. Resolves against what already exists — installed skills, catalog skills and agent files — then names the gap and emits the install command. NOT routing among skills you already have (that is `suggest`), NOT writing the artifact when none exists (that is `author-skill` for skills, `building-agents` for agents)."
 tags: [skill-discovery, capability-gap, meta, recommendations, coverage-audit]
 recommends: [suggest, author-skill, context-budget, continuous-learning, knowledge-ops]
 origin: risco
@@ -8,9 +8,9 @@ origin: risco
 
 # skill-scout — find the skill you don't have
 
-You are the **gap detector** for the skills catalog. Before a task starts — or in the middle of one that is dragging — you answer exactly one question: *is there a skill that should be handling this, and is it loaded?* You do **not** do the work. You name what to load, then get out of the way.
+You are the **gap detector** for the skills catalog. Before a task starts, in the middle of one that is dragging, or right after delivering work that turned out to be a procedure — you answer exactly one question: *is there a skill that should be handling this, and is it loaded?* You do **not** do the work. You name what to load, then get out of the way.
 
-Every run ends in one of three verdicts:
+Every run ends in one of the verdicts in the table below:
 
 - **INSTALLED-elsewhere** — the skill exists in the catalog and on disk somewhere (user scope, another project, a plugin) but is not active *here*. → emit a scope-fix / install command.
 - **MISSING** — the skill exists in the catalog but is not installed at all. → emit an install command and a one-line why.
@@ -26,11 +26,46 @@ Why this matters: skills load by **progressive disclosure**. At session start Cl
 | Clear match, exists at user scope but not in this project (or vice versa) | INSTALLED-elsewhere | Emit the scope-fix (copy to the missing scope) + why. |
 | 2–3 plausible candidates, none dominant | AMBIGUOUS | Name the top 2 with a one-line distinction; ask which fits. Do not guess. |
 | Present skill already covers this task | NO GAP | Say so and hand to `../suggest/SKILL.md` (routing among present skills) — that is its job, not yours. |
+| An installed **agent** already does this work | AGENT-COVERS | Name it, use it (delegate), propose nothing. Agents are listed by `npx @ericrisco/rsc capabilities`; they are invisible to the catalog, so a scan that skips them proposes duplicates. |
 | Catalog match present but its description is too vague to ever fire | WEAK-DESCRIPTION | Treat as a gap; route to `../author-skill/SKILL.md` to fix the frontmatter. |
 | No catalog id fits at all | NONEXISTENT | Route to `../author-skill/SKILL.md`. Do not fabricate an id. |
 
 The branch you must never collapse: **MISSING vs NONEXISTENT.** Confusing them either sends the user to write a skill that already exists, or has them wait for an install command for a skill that was never authored.
 
+## The automation gap — the trigger that fires *after* the work
+
+Everything above is preventive: you scan *before* generic reasoning does a specialist's job. There is a second moment, and it is the opposite one — **the work is already done and delivered**, and only then you notice its shape:
+
+> The last thing you did by hand was a **procedure**: several mostly-deterministic steps, a recognizable result, repeatable by someone else from a description, and plausibly needed again.
+
+Then, in this order and never skipping ahead:
+
+1. **Deliver first.** This never delays, conditions or replaces the work asked for. Raising it beforehand turns a simple request into a conversation about harness architecture.
+2. **Enumerate what exists** — `npx @ericrisco/rsc capabilities` lists installed skills (with their scope), **agent files** and the catalog ids in one pass. Read it; do not recall it. Add `--full` for catalog descriptions, or use `catalog --available` when you need to match by meaning — the default stays cheap on purpose. If the command cannot run, **propose nothing** and say the check did not happen: never propose building on a check that did not occur.
+3. **Something covers it** → use it (install with the usual one-word confirm if it is catalog-only), and **propose nothing**. Proposing to build what already exists is the worst outcome available here — it costs attention and it spends the credibility of every later suggestion.
+4. **Nothing covers it** → one sentence at the end of the work: the procedure you saw, and whether it fits as a skill or an agent. Then stop; the user decides. Their "no" ends it for this procedure for the rest of the session.
+5. **Record it either way** — `npx @ericrisco/rsc capabilities gap-log --procedure "<what YOU observed doing>" --verdict <covered-installed|covered-catalog|covered-agent|proposed-accepted|proposed-declined>`.
+
+**Scale the sentence to the dial**, never whether it appears. Read the accompaniment level in `02-DOCS/wiki/harness/user-profile.md`: at L0/L1 it is one dry line ("this looked like a procedure — worth a skill?"); at L2/L3 add why it qualified and what the skill-vs-agent difference means for them. A profile that asked for brevity still gets the observation, just not the essay.
+
+**The privacy boundary is yours to hold**, not the command's — it validates shape and nothing else, and it cannot tell your description from a paraphrase of the request. `--procedure` carries *your* account of the work you did. Never the user's words. The test: if the line could be reconstructed from what they typed, it does not belong in the log.
+
+**Which log:** this one (`.rsc/automation-gaps.md`, verdicts `covered-*`/`proposed-*`) is for the after-the-work automation gap. The coverage-audit log below (`skill-gaps.jsonl`, verdicts `MISSING`/`NONEXISTENT`) is for a deliberate catalog audit. One event, one log — never both.
+
+**Silence is a correct and common outcome.** A one-off, an exploration, a one-liner, or work that failed is not a procedure — a procedure is extracted from something that worked. There is no switch to turn this off, which is exactly why the bar is high: propose on everything and the feature becomes noise a user cannot escape.
+
+### Skill or agent
+
+Decided by the nature of the work, never its size:
+
+| | Fits a **skill** | Fits an **agent** |
+| --- | --- | --- |
+| Shape | Knowledge + procedure that must **fire at the right moment**, in the conversation, user present | Work you want to **delegate**: its own context, possibly in parallel, possibly another model |
+| Tell | "Whenever X comes up, do it this way" | "Go do X and come back with the result" |
+| Build with | `../author-skill/SKILL.md` | `../building-agents/SKILL.md` |
+
+When both fit, name the cheaper one to try and say the other is possible. When it is genuinely ambiguous, ask instead of choosing. On a target with no file-based agents (`capabilities` says so), the agent option does not exist — do not offer it.
+
 ## Symptoms that the task should have a skill
 
 Watch for these. Any one is enough to run a scan:
@@ -129,5 +164,6 @@ One JSON object per line, append-only. `recommended_id` must be a real catalog i
 
 - `../suggest/SKILL.md` — routing among the skills you already have. suggest is routing; you are procurement. If the right skill is already present, it's suggest's job, not yours.
 - `../author-skill/SKILL.md` — building a new skill when none exists. You own the *exists / missing / nonexistent* decision; the moment the verdict is NONEXISTENT (or WEAK-DESCRIPTION), hand off here.
+- `../building-agents/SKILL.md` — designing the agent when the gap is delegated work rather than in-conversation procedure (see *Skill or agent* above).
 - `context-budget` — when the loaded set is too heavy for the window. That is token budgeting of what *is* loaded; orthogonal to finding what is *absent*. (Not yet on disk; do not link until it ships.)
 - `continuous-learning` / `knowledge-ops` — when the pattern is a recurring *learning* to capture, not a missing skill to install. (Not yet on disk.)

package/skills/suggest/SKILL.md

@@ -71,6 +71,12 @@ and never to interrupt a flow with a nice-to-have. Never recommend something alr
 nothing for natural-language or non-English intent. Never let it decide, and never read its silence
 as "no skill exists" — the catalog plus your judgment is the source of truth.
 
+### Automation gap — after the work
+
+Delivered work a repeatable **procedure**? Before proposing to *build* anything, run
+`npx @ericrisco/rsc capabilities`: covered by a skill or agent → use it, say nothing.
+Not covered → one line, skill or agent. Rules: `skill-scout`.
+
 ---
 
 ## 3. First contact

package/targets/sello.mjs

@@ -35,8 +35,14 @@ import { spawnSync } from 'node:child_process';
 // sello would mutate the change being sealed, so `freeze` → `approve` could never
 // converge (a permanent, unrecoverable delivery lockout). Excluded whether the
 // project tracks .rsc/ or not.
+// Every tool-written journal under .rsc/ belongs here, not just the sello's own:
+// `.rsc/` is a non-lowerable tier-2 risk class, so ANY file the harness writes
+// automatically would escalate risk and invalidate an approved seal on every write.
+// The automation-gap log is exactly that — it is appended after every piece of work,
+// with no switch to stop it, so leaving it out made the lockout permanent.
 export const SELLO_STATE_PATHS = [
   '.rsc/sello.json', '.rsc/sello-config.json', '.rsc/sello-findings.md', '.rsc/sello-log.jsonl',
+  '.rsc/automation-gaps.md',
 ];
 
 export function selloPaths(root) {