@ericrisco/rsc 1.1.3 → 1.1.4

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.3",
+  "version": "1.1.4",
   "counts": {
     "skills": 281
   },

package/package.json

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

package/scripts/lib/spec-gate.js

@@ -34,6 +34,10 @@ const UNCHECKED = [
   'que ninguna sección contenga una suposición sin marcar (no es detectable por máquina; es el juicio que la fase existe para ejercer)',
   'que el contenido de cada sección sea correcto, y no sólo presente',
   'que los criterios de aceptación sean de verdad binarios',
+  // Added with the status check below, for the same reason the three above exist: a green that is
+  // narrower than the rule it appears to enforce is the decorative gate all over again.
+  'si una spec dice "implementada" sin nombrar commit, PR ni versión (no hay nada que ir a mirar)',
+  'si el trabajo de una spec que se declara sin aterrizar llegó por otra vía (git no lo distingue)',
 ];
 
 function fold(s) {
@@ -120,3 +124,97 @@ export function specCompleteness(markdown) {
     unchecked: UNCHECKED,
   };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Does the status still match the repository?
+//
+// The section check above asks whether a spec is COMPLETE. This asks whether it is still TRUE — and
+// nothing asked that before, which is how seven of twenty-five statuses came to contradict the repo:
+// one claiming "sin push ni PR" over work that had been in main for weeks, four sitting in
+// `awaiting-approval` over work already published. Spec: 02-DOCS/wiki/sdd/specs/spec-status-drift.md
+//
+// The vocabulary below was extracted from the 25 real statuses, not imagined. That matters: an
+// invented recognizer reaches for the bare word `implementada`, and the bare word is not checkable —
+// it names nothing to go and look for. Only a commit, a PR or a released version do.
+
+/** The claim shapes this recognizer knows. Anything else is silence, not a finding. */
+export const CLAIM_KINDS = ['sha', 'pr', 'version', 'not-landed'];
+
+// Deliberately absent: the bare words `implementada`, `desplegada`, `descartada`, and the phrase
+// `no aprobada`. The first two name nothing to check. The last two look like landing claims and are
+// not — `descartada` is a spec closed on purpose after being measured, `no aprobada` describes HOW
+// approval happened (in autopilot, not item by item), not whether code shipped. Treating either as a
+// landing claim would invent drift in the two best-closed specs of the set.
+const SHA = /\b[0-9a-f]{7,40}\b/g;
+const PR = /\bPR\s*#(\d+)/gi;
+const VERSION = /\bpublicada en (\d+\.\d+\.\d+)/gi;
+const NOT_LANDED = /\bsin push\b|\bsin PR\b|\bawaiting-approval\b/i;
+
+/**
+ * Pull the checkable claims out of a status string. Pure: no git, no I/O.
+ * @param {string} statusText
+ * @returns {Array<{kind: string, value: string, raw: string}>}
+ */
+export function statusClaims(statusText) {
+  const text = typeof statusText === 'string' ? statusText : '';
+  const claims = [];
+  for (const m of text.matchAll(PR)) claims.push({ kind: 'pr', value: m[1], raw: m[0] });
+  for (const m of text.matchAll(VERSION)) claims.push({ kind: 'version', value: m[1], raw: m[0] });
+  for (const m of text.matchAll(SHA)) claims.push({ kind: 'sha', value: m[0], raw: m[0] });
+  const neg = NOT_LANDED.exec(text);
+  if (neg) claims.push({ kind: 'not-landed', value: neg[0], raw: neg[0] });
+  return claims;
+}
+
+/**
+ * Judge each claim against the repository.
+ *
+ * Four verdicts and none of them collapse into another. `unverifiable` is the one that keeps this
+ * honest — a claim we could not check is not a claim that passed, and it is not drift either.
+ *
+ * `not-landed` is always handed to a human, and that is a deliberate retreat from what the spec
+ * first promised. No query distinguishes "never landed" from "landed by another route": the case
+ * that started this work names a commit that genuinely is not in main, while its deliverable has
+ * been there for weeks. Checking the named commit would bless the misleading status; inferring the
+ * other from anything else would be a heuristic inside a gate. So the deterministic part narrows,
+ * and only what it narrowed goes to judgement — principle 1, and the shape `knowledge-drift` already
+ * uses.
+ *
+ * @param {Array<object>} claims from `statusClaims`
+ * @param {?{hasCommit: Function, isAncestor: Function, hasPr: Function, hasTag: Function}} probe
+ *        null when there is no repository to ask — every claim then reports unverifiable.
+ * @returns {Array<{kind: string, value: string, verdict: string, reason: string}>}
+ */
+export function checkClaims(claims, probe) {
+  return (claims || []).map((c) => {
+    if (c.kind === 'not-landed') {
+      return {
+        ...c,
+        verdict: 'needs-human',
+        reason: 'git cannot tell "never landed" from "landed by another route" — look at whether the deliverable is in main, not at the branch',
+      };
+    }
+    if (!probe) return { ...c, verdict: 'unverifiable', reason: 'no repository to ask' };
+    try {
+      if (c.kind === 'sha') {
+        if (!probe.hasCommit(c.value)) {
+          return { ...c, verdict: 'unverifiable', reason: `commit ${c.value} is not in this repository` };
+        }
+        return probe.isAncestor(c.value)
+          ? { ...c, verdict: 'holds', reason: `${c.value} is in main` }
+          : { ...c, verdict: 'stale', reason: `${c.value} is NOT in main` };
+      }
+      if (c.kind === 'pr') {
+        return probe.hasPr(c.value)
+          ? { ...c, verdict: 'holds', reason: `PR #${c.value} is merged into main` }
+          : { ...c, verdict: 'stale', reason: `no merge of PR #${c.value} in main` };
+      }
+      return probe.hasTag(c.value)
+        ? { ...c, verdict: 'holds', reason: `v${c.value} is tagged` }
+        : { ...c, verdict: 'stale', reason: `no v${c.value} tag in this repository` };
+    } catch (e) {
+      // Could not look. Saying `stale` here would invent a finding out of our own failure.
+      return { ...c, verdict: 'unverifiable', reason: e.message };
+    }
+  });
+}

package/scripts/spec-gate.js

@@ -7,7 +7,8 @@
 import { readFileSync, readdirSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { specCompleteness } from './lib/spec-gate.js';
+import { execFileSync } from 'node:child_process';
+import { specCompleteness, statusClaims, checkClaims } from './lib/spec-gate.js';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const DEFAULT_DIR = join(ROOT, '02-DOCS', 'wiki', 'sdd', 'specs');
@@ -22,6 +23,35 @@ function defaultTargets() {
   }
 }
 
+// The repository, asked instead of assumed. Returns null when there is nothing to ask — a
+// report-only instrument that crashes where it cannot look is worse than one that says so.
+function gitProbe(root) {
+  const git = (args) => execFileSync('git', args, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  let main;
+  try {
+    git(['rev-parse', '--git-dir']);
+    // Prefer the remote tip — a stale local `main` reports merged work as missing. But CI checks out
+    // detached with no `origin/main` and no local `main`, and falling through to "no repository to
+    // ask" there means the check silently stops checking exactly where it runs unattended. HEAD is
+    // the honest last resort: on CI it IS the branch under test.
+    main = ['origin/main', 'main', 'HEAD'].find((ref) => {
+      try { git(['rev-parse', '--verify', ref]); return true; } catch { return false; }
+    });
+    if (!main) throw new Error('no ref to compare against');
+  } catch {
+    return null;
+  }
+  return {
+    hasCommit: (sha) => { try { git(['cat-file', '-e', `${sha}^{commit}`]); return true; } catch { return false; } },
+    isAncestor: (sha) => { try { git(['merge-base', '--is-ancestor', sha, main]); return true; } catch { return false; } },
+    // The squash-merge subject carries `(#N)`; --fixed-strings so the parens are not a regex.
+    hasPr: (n) => { try { return git(['log', main, '--grep', `(#${n})`, '--fixed-strings', '-1', '--format=%H']) !== ''; } catch { return false; } },
+    hasTag: (v) => { try { return git(['tag', '-l', `v${v}`]) !== ''; } catch { return false; } },
+  };
+}
+
+const statusOf = (text) => (/^status:[ \t]*(.*)$/m.exec(text) || [, ''])[1];
+
 function main() {
   const args = process.argv.slice(2);
   const targets = args.length ? args : defaultTargets();
@@ -31,8 +61,21 @@ function main() {
   }
 
   let failed = 0;
+  let drifted = 0;
+  // One probe per repository, not one for the tool's own. A spec's claims are about the history of
+  // the project the spec belongs to — checking them against wherever this script happens to live
+  // gives the right answer only by coincidence, and the wrong one the moment the gate is pointed at
+  // another checkout.
+  const probes = new Map();
+  const probeFor = (path) => {
+    const dir = dirname(path);
+    if (!probes.has(dir)) probes.set(dir, gitProbe(dir));
+    return probes.get(dir);
+  };
+  let anyProbe = false;
   for (const path of targets) {
-    const r = specCompleteness(readFileSync(path, 'utf8'));
+    const text = readFileSync(path, 'utf8');
+    const r = specCompleteness(text);
     const name = basename(path);
     if (r.ok) {
       const typed = r.openPoints.length - r.untyped.length;
@@ -40,17 +83,27 @@ function main() {
       if (r.untyped.length) {
         console.log(`      untyped (treated as open questions): ${r.untyped.length}`);
       }
-    } else {
+    }
+    if (!r.ok) {
       failed += 1;
       console.log(`FAIL  ${name}`);
       if (r.missing.length) console.log(`      missing section(s): ${r.missing.join(', ')}`);
       if (r.empty.length) console.log(`      section(s) with no content: ${r.empty.join(', ')}`);
     }
+    // A status that still matches the repository prints nothing: the report grows only where there
+    // is something to act on (P5).
+    const probe = probeFor(path);
+    anyProbe = anyProbe || Boolean(probe);
+    for (const v of checkClaims(statusClaims(statusOf(text)), probe)) {
+      if (v.verdict === 'holds') continue;
+      if (v.verdict === 'stale') drifted += 1;
+      console.log(`      status ${v.verdict.toUpperCase()}: ${v.raw} — ${v.reason}`);
+    }
   }
 
   // A green here is narrower than the rule it enforces, so it says so every run rather than
   // letting the reader assume the gate covered more than it did.
-  console.log(`\n${targets.length - failed}/${targets.length} pass. Not checked by this gate:`);
+  console.log(`\n${targets.length - failed}/${targets.length} pass, ${drifted} status claim(s) contradicted by the repo${anyProbe ? '' : ' (no repository to ask)'}. Not checked by this gate:`);
   for (const u of specCompleteness('').unchecked) console.log(`  - ${u}`);
   if (failed) process.exit(1);
 }