@ericrisco/rsc 1.0.20 → 1.0.22

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/ericrisco/rsc-harness/main/site/og.png" alt="rsc — the plain-language wizard installing 5 of 264 skills into Claude Code and Codex CLI, leaving the other 259 out of your context window" width="960">
+<img src="https://raw.githubusercontent.com/ericrisco/rsc-harness/main/site/og.png" alt="rsc — your agent needs a memory (02-DOCS/, or it invents what it cannot remember), arms (01-TOOLS/, or it never touches your database), a trade (264 skills, or it guesses how the job is done), and reflexes (deterministic hooks, or it forgets the rule mid-session). One meta-harness for 17 coding assistants." width="960">
 
 # `rsc` — 264 agent skills, one CLI, zero bloat
 
@@ -26,12 +26,12 @@ npx @ericrisco/rsc            # plain-language wizard — no jargon, installs wh
 
 <br>
 
-<img src="https://raw.githubusercontent.com/ericrisco/rsc-harness/main/site/meta-harness.png" alt="rsc is a meta-harness above your coding agents: TOOLS (01-TOOLS/, one folder per provider — Postgres, MongoDB, Stripe, Redis, Supabase, Firebase, Cloudflare, Hetzner, plus any API via api-connector-builder), 02-DOCS (the company brain — a knowledge graph turning raw/ into wiki/, OKF v0.1), and SKILLS (264, installed one at a time). All three feed Claude Code, Codex CLI and opencode, which work on your repo — and the results feed back into the brain." width="960">
+<img src="https://raw.githubusercontent.com/ericrisco/rsc-harness/main/site/meta-harness.png" alt="rsc — the model (Claude, GPT, Gemini) is the brain your coding agent rents, and you already have that. Claude Code, Codex and opencode sit in the middle. Below them the rsc meta-harness adds everything the model lacks: memory (02-DOCS/) so it stops inventing, arms (01-TOOLS/) so it can execute, a trade (264 skills) so it stops guessing, and reflexes (deterministic hooks) so it cannot forget the rule mid-session." width="960">
 
-**One harness above every agent.** `rsc` wires three layers into whichever assistant you
-already use — the **tools** that connect your providers, the **02-DOCS brain** that turns your
-own results into knowledge, and the **skills** that teach the agent the job — then keeps all
-three in sync as you work.
+**The model is the only part your agent already has.** `rsc` is the meta-harness that adds
+the rest: a **memory** so it stops inventing, **arms** so it can execute, a **trade** so it stops
+guessing, and **reflexes** so it cannot forget the rule mid-session — into whichever assistant
+you already use, and kept in sync as you work.
 
 </div>
 

package/manifest.json

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

package/package.json

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

package/scripts/lib/capabilities.js

@@ -148,20 +148,39 @@ export function capabilities({ target, home, cwd = process.cwd(), full = false }
 // 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.
 
+// `proposed-capability` added 2026-08-18: none of the original five could express "this needs an
+// executable capability, not a skill", which is the majority of what the repetition detector actually
+// finds. Without it the honest case had to be recorded as one of the other five, and all five would
+// have been false. Additive — the existing five keep validating unchanged.
 export const GAP_VERDICTS = [
   'covered-installed', 'covered-catalog', 'covered-agent',
-  'proposed-accepted', 'proposed-declined',
+  'proposed-accepted', 'proposed-declined', 'proposed-capability',
 ];
 
 export function gapLogPath(cwd = process.cwd()) {
   return join(cwd, '.rsc', 'automation-gaps.md');
 }
 
+/**
+ * The user-level log. A procedure repeated across three projects is STRONGER evidence that it should
+ * stop being manual, not weaker — and the per-repo log makes that pattern invisible by construction
+ * (clarify 2026-08-18). Nothing "wins" when the two disagree: they are summed, de-duplicated by
+ * date+procedure+verdict, so double-writing cannot double-count.
+ */
+export function globalGapLogPath(home = homedir()) {
+  return join(home, '.rsc', 'automation-gaps.md');
+}
+
+/** Repo name as it appears in a log line, so the offer can say WHERE it repeated. */
+export function repoNameOf(cwd = process.cwd()) {
+  return basename(resolve(cwd));
+}
+
 // 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 }) {
+export function appendGap({ procedure, verdict, cwd = process.cwd(), now, home = homedir() }) {
   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)) {
@@ -177,6 +196,19 @@ export function appendGap({ procedure, verdict, cwd = process.cwd(), now }) {
   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`);
+
+  // Also record globally, tagged with the repo. Wrapped: a home directory that cannot be written must
+  // never take down the local record, which is the one the current repo depends on.
+  try {
+    const g = globalGapLogPath(home);
+    mkdirSync(dirname(g), { recursive: true });
+    let gHeader = true;
+    try { gHeader = statSync(g).size === 0; } catch { gHeader = true; }
+    const gh = gHeader
+      ? '# Huecos de automatización (global)\n\nAcumulado de todos los repos, para que un procedimiento repetido en varios proyectos sea visible.\nLo escribe `rsc capabilities gap-log`. Cada línea lleva `[repo:<nombre>]`. Fichero local: no lo commitees.\n\n'
+      : '';
+    appendFileSync(g, `${gh}- ${day} · ${text} · [repo:${repoNameOf(cwd)}] · **${verdict}**\n`);
+  } catch { /* the local log is what matters; a global failure is not fatal */ }
   return p;
 }
 

package/scripts/lib/repetition-report.js

@@ -0,0 +1,47 @@
+// repetition-report.js — the I/O half of the repetition detector.
+//
+// Kept apart from repetition.js on purpose: the deciding is pure and heavily tested, the reading of two
+// files is not. Mixing them would make the interesting logic need fixtures on disk.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { gapLogPath, globalGapLogPath, capabilities } from './capabilities.js';
+import { parseGapLog, groupProcedures, decideOffer, mergeLogs, THRESHOLD } from './repetition.js';
+
+/**
+ * Read local + global logs, group, decide. FAILS CLOSED: an unreadable log yields `blocked`, never an
+ * invented count. countGaps() already sets the precedent of not taking `doctor` down over a malformed
+ * log; the difference here is that the degradation is announced instead of swallowed.
+ */
+export function repetitionReport({ cwd = process.cwd(), home = homedir(), target = 'claude' } = {}) {
+  const read = (p, label) => {
+    if (!existsSync(p)) return { entries: [], missing: true };
+    try { return { entries: parseGapLog(readFileSync(p, 'utf8')), missing: false }; }
+    catch (e) { return { error: `no se pudo leer el registro ${label} (${p}): ${e.message}` }; }
+  };
+  const local = read(gapLogPath(cwd), 'local');
+  const global = read(globalGapLogPath(home), 'global');
+  if (local.error || global.error) {
+    return { blocked: true, reason: local.error || global.error, offer: null, uncertain: [], entries: 0 };
+  }
+  const merged = mergeLogs(local.entries, global.entries);
+  if (!merged.length) {
+    return { blocked: false, offer: null, reason: 'no hay entradas registradas todavía', uncertain: [], entries: 0 };
+  }
+  const { groups, uncertain } = groupProcedures(merged);
+
+  // "Already covered" is answered by the command that reads the disk, never by memory — the decision
+  // capabilities.js already made and for the right reason.
+  let covered = false;
+  try {
+    const caps = capabilities({ target, cwd });
+    const top = [...groups].sort((a, b) => b.entries.length - a.entries.length)[0];
+    if (top) {
+      const words = top.key.toLowerCase();
+      covered = caps.installed.some((s) => words.includes(s.id)) || (caps.agents || []).some((a) => words.includes(a.id));
+    }
+  } catch { /* enumeration failing must not fabricate "covered" — leave it false */ }
+
+  const { offer, reason } = decideOffer({ groups, threshold: THRESHOLD, covered });
+  return { blocked: false, offer, reason, uncertain, entries: merged.length, groups: groups.length };
+}

package/scripts/lib/repetition.js

@@ -0,0 +1,186 @@
+// repetition.js — has this procedure been done before, and does it deserve to stop being manual?
+//
+// The always-on rule already asks "did you just deliver a repeatable PROCEDURE?" — a judgment about ONE
+// episode, made by the same agent that just performed it, at the moment it is most convinced its work
+// was special. Grepping the always-on layer for repeat|repetit|twice|recurr returns nothing: nothing
+// looks backwards.
+//
+// The registry that would allow it already exists. `rsc capabilities gap-log` writes one line per
+// observed procedure, and the only thing that consumes it is countGaps(), which returns a TOTAL for
+// `doctor` to display. The ledger is written and nobody interrogates it — the passive form of the same
+// P2 defect.
+//
+// The evidence is the session that wrote this: four manual mutation runs (8, 17, 12, 6 mutants) and
+// five identical score-then-rescore passes, none of which ever triggered the rule, because each episode
+// looked like one-off work on its own.
+//
+// Two decisions from clarify (2026-08-18): the count is GLOBAL with a per-repo breakdown (a procedure
+// repeated across projects is stronger signal, not weaker), and the threshold is THREE — a reasoned
+// bet, not a measurement, and it says so.
+
+import { tokenize } from './text-rank.js';
+
+export const THRESHOLD = 3;
+
+// Numerals and structural filler carry no information about WHICH procedure this is — "eight mutants"
+// and "twelve mutants" are the same work. Dropping them is what made the margin measurable at all.
+const FILLER = /^(uno|dos|tres|cuatro|cinco|seis|siete|ocho|nueve|diez|once|doce|trece|catorce|quince|dieciseis|diecisiet|dieciocho|diecinuev|veint|cada|por|sobr|un|una|one|two|three|four|five|six|seven|eight|nine|ten|each)$/;
+
+// CALIBRATED, NOT GUESSED. Three metrics were measured on real descriptions from the session that
+// motivated this (3 same-procedure pairs, 12 different-procedure pairs):
+//
+//   metric    same            different   margin
+//   jaccard   0.17–0.30       ≤0.09       0.08
+//   overlap   0.29–0.50       ≤0.20       0.09
+//   dice      0.29–0.46       ≤0.17       0.12   ← widest, so this is the one
+//
+// The first version used Jaccard at 0.6 and grouped nothing: the real case came out as four groups of
+// one. Guessing a threshold for a similarity metric is how you ship a detector that never fires.
+//
+// HONEST LIMIT: n=15 pairs from one session. This is calibration, not validation. If it groups wrongly
+// in practice the number moves, and the measurement above is the record of how it was chosen.
+export const GROUP_AT = 0.25;
+// The band where the answer is "maybe": it does NOT group, and it records what it refused to assume.
+// Grouping wrongly inflates the count and fires an offer about something that never repeated — the more
+// expensive of the two mistakes (P7: a system that nags in the harmless 80% gets switched off).
+export const UNCERTAIN_AT = 0.17;
+
+const LOG_LINE = /^- (\d{4}-\d{2}-\d{2}) · (.+?) · \*\*([a-z-]+)\*\*\s*$/;
+const REPO_TAG = /\s*·?\s*\[repo:([^\]]+)\]\s*$/;
+
+/** Parse a gap log. Malformed lines are skipped, not guessed at; the caller decides what silence means. */
+export function parseGapLog(text) {
+  const out = [];
+  const lines = String(text || '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = LOG_LINE.exec(lines[i]);
+    if (!m) continue;
+    let procedure = m[2];
+    let repo = null;
+    const tag = REPO_TAG.exec(procedure);
+    if (tag) { repo = tag[1]; procedure = procedure.slice(0, tag.index).trim(); }
+    out.push({ date: m[1], procedure, verdict: m[3], repo, line: i + 1 });
+  }
+  return out;
+}
+
+/** Significant tokens: text-rank's (accent-folded, stopworded, stemmed) minus numerals and filler. */
+export function terms(text) {
+  return new Set(tokenize(String(text || '')).filter((tk) => !FILLER.test(tk)));
+}
+
+/**
+ * Dice coefficient over significant tokens: 2|A∩B| / (|A|+|B|). Not cosine — that weights by IDF over a
+ * corpus and here there are just two sentences. Not Jaccard — measured narrower on real data (see the
+ * table above).
+ */
+export function similarity(a, b) {
+  const A = terms(a);
+  const B = terms(b);
+  if (!A.size || !B.size) return 0;
+  let inter = 0;
+  for (const tk of A) if (B.has(tk)) inter++;
+  return (2 * inter) / (A.size + B.size);
+}
+
+/**
+ * Group entries describing the same procedure. Deterministic: first entry of a group is its key, and a
+ * candidate joins only if it clears GROUP_AT against that key. Anything in the uncertain band is left
+ * ungrouped and recorded, so a human can see what the detector refused to assume.
+ */
+export function groupProcedures(entries, threshold = GROUP_AT) {
+  const groups = [];
+  const uncertain = [];
+  for (const e of entries) {
+    let best = null;
+    let bestScore = 0;
+    for (const g of groups) {
+      const s = similarity(e.procedure, g.key);
+      if (s > bestScore) { bestScore = s; best = g; }
+    }
+    if (best && bestScore >= threshold) {
+      best.entries.push(e);
+      if (e.repo) best.repos.set(e.repo, (best.repos.get(e.repo) || 0) + 1);
+      continue;
+    }
+    if (best && bestScore >= UNCERTAIN_AT) {
+      uncertain.push({ procedure: e.procedure, nearest: best.key, score: Number(bestScore.toFixed(2)) });
+    }
+    groups.push({
+      key: e.procedure,
+      entries: [e],
+      repos: new Map(e.repo ? [[e.repo, 1]] : []),
+    });
+  }
+  return { groups, uncertain };
+}
+
+const CAPABILITY_VERBS = /\b(plantar|plant|correr|ejecutar|run|contar|count|restaurar|restore|medir|measure|extraer|extract|puntuar|score|comparar|compare|generar|generate)\b/i;
+const AGENT_VERBS = /\b(revisar|review|refutar|refute|auditar|audit|verificar|verify|juzgar|judge|a ciegas|blind)\b/i;
+
+/**
+ * Which shape does this procedure want? Order matters: the first match wins, and capability comes
+ * first because it is the majority case observed and the one with no verdict until now. Writing a
+ * paragraph for something that needs a script is the failure the generalization gate already named.
+ */
+export function recommendKind(procedure) {
+  const p = String(procedure || '');
+  if (CAPABILITY_VERBS.test(p)) {
+    return {
+      kind: 'capability',
+      why: 'describe algo que hay que ejecutar y comparar; una skill escribiría un párrafo donde hace falta un script o un hook',
+    };
+  }
+  if (AGENT_VERBS.test(p)) {
+    return {
+      kind: 'agent',
+      why: 'describe mirar o juzgar sin arrastrar el contexto de quien lo pide, que es para lo que sirve un contexto fresco',
+    };
+  }
+  return { kind: 'skill', why: 'describe guía y disciplina sobre lo que ya se está haciendo en la conversación' };
+}
+
+const DECLINED = 'proposed-declined';
+
+/**
+ * Should anything be said? Silence is the default and the common case.
+ *
+ * Never offers when: below threshold, already covered, or previously declined. A "no" that has to be
+ * repeated every week is what makes someone switch the whole harness off.
+ */
+export function decideOffer({ groups, threshold = THRESHOLD, covered = false }) {
+  if (covered) return { offer: null, reason: 'ya cubierto por una skill o agente instalado' };
+  const ranked = [...groups].sort((a, b) => b.entries.length - a.entries.length);
+  for (const g of ranked) {
+    if (g.entries.length < threshold) continue;
+    // A decline anywhere in the group retires it permanently.
+    if (g.entries.some((e) => e.verdict === DECLINED)) continue;
+    const rec = recommendKind(g.key);
+    return {
+      offer: {
+        procedure: g.key,
+        seen: g.entries.length,
+        dates: g.entries.map((e) => e.date),
+        repos: [...g.repos.entries()].map(([repo, n]) => ({ repo, n })),
+        kind: rec.kind,
+        why: rec.why,
+        threshold,
+      },
+      reason: null,
+    };
+  }
+  return { offer: null, reason: `ningún procedimiento alcanza el umbral de ${threshold}` };
+}
+
+/** Merge local + global entries, de-duplicated by date+procedure+verdict, so double-writing cannot double-count. */
+export function mergeLogs(localEntries, globalEntries) {
+  const seen = new Set();
+  const out = [];
+  for (const e of [...localEntries, ...globalEntries]) {
+    const k = `${e.date}|${e.procedure}|${e.verdict}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(e);
+  }
+  return out;
+}

package/scripts/rsc.js

@@ -352,6 +352,26 @@ async function main() {
         } catch (e) { say(e.message); process.exitCode = 1; }
         return;
       }
+      // `capabilities repetition` — read the ledger nobody was interrogating. It lives here and not in
+      // a new command because the enumeration and the writing already live here, and splitting them
+      // across two places is the parallel bookkeeping P3 forbids.
+      if (argv.includes('repetition')) {
+        const root = resolveRoot(process.cwd());
+        const { repetitionReport } = await import('./lib/repetition-report.js');
+        const rep = repetitionReport({ cwd: root });
+        if (argv.includes('--json')) return void say(JSON.stringify(rep, null, 2));
+        if (rep.blocked) { say(`⚠️  ${rep.reason}`); process.exitCode = 1; return; }
+        if (!rep.offer) { say(`# nada que ofrecer — ${rep.reason} (${rep.entries} entradas leídas)`); return; }
+        const o = rep.offer;
+        const where = o.repos.length ? ` · ${o.repos.map((r) => `${r.repo}×${r.n}`).join(', ')}` : '';
+        say(`🔁 «${o.procedure}» visto ${o.seen} veces (${o.dates.join(', ')})${where}`);
+        say(`   → ${o.kind}: ${o.why}`);
+        say(`   registra la decisión con: rsc capabilities gap-log --procedure "..." --verdict proposed-${o.kind === 'capability' ? 'capability' : 'accepted'}|proposed-declined`);
+        if (rep.uncertain.length) {
+          say(`   (${rep.uncertain.length} parecido(s) que NO se agruparon por debajo del umbral — deliberado)`);
+        }
+        return;
+      }
       const full = argv.includes('--full');
       const reports = targets.map((t) => capabilities({ target: t, full }));
       if (argv.includes('--json')) {