@ericrisco/rsc 1.0.12 → 1.0.13

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.12",
+  "version": "1.0.13",
   "counts": {
     "skills": 264
   },

package/package.json

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

package/skills/fastapi/scripts/verify.sh

@@ -9,9 +9,20 @@
 # Auto-detects each tool. If a tool is missing it prints a yellow SKIP and continues
 # (it never FAILs on a missing tool). Prefers `uv run <tool>` when `uv` is present,
 # else the bare tool on PATH. Exits non-zero only if a tool actually ran and reported
-# a failure. The coverage threshold is read from the project's pyproject.toml
-# (--cov-fail-under); this script does not hardcode a second threshold. Idempotent:
-# re-running yields the same result (read-only beyond whatever the project's pytest does).
+# a failure. Idempotent: re-running yields the same result (read-only beyond whatever
+# the project's pytest does).
+#
+# COVERAGE IS ONLY A GATE IF YOUR PROJECT MAKES IT ONE. The threshold is deliberately
+# delegated to the project (--cov-fail-under in pyproject.toml / setup.cfg / .coveragerc)
+# rather than hardcoded here. But when the project sets none, `pytest --cov` prints a
+# percentage and exits 0 however far coverage falls — and a layer that prints a number and
+# exits 0 is a report, not a gate. That case is reported as [gap] instead of PASS, because
+# the two are indistinguishable on screen and the broken one can only ever produce green:
+# no failing run will ever surface it.
+#
+# A [gap] does NOT change the exit code — breaking every repo that passes today is not this
+# script's call. This script reports; the `verify` skill judges, and there a gap counts as
+# an unverified criterion, which fails the verdict.
 #
 # Compatible with stock macOS bash 3.2: no `mapfile`, no associative arrays, and every
 # array access is guarded so `set -u` never trips on an "unbound" empty array.
@@ -30,7 +41,28 @@ warn() { printf '%s%s%s\n' "$YELLOW" "$*" "$RESET"; }
 ok()   { printf '%s%s%s\n' "$GREEN" "$*" "$RESET"; }
 fail() { printf '%s%s%s\n' "$RED" "$*" "$RESET"; }
 
-PASSED=0; SKIPPED=0; FAILED=0
+PASSED=0; SKIPPED=0; FAILED=0; GAPS=0
+
+# gap <reason> — the layer ran and had nothing to fail with. Counted and printed, but it
+# deliberately does NOT touch FAILED: see the header note on why the exit code is unchanged.
+gap() { printf '%sGAP: %s%s\n' "$YELLOW" "$*" "$RESET"; GAPS=$((GAPS + 1)); }
+
+# coverage_threshold_configured — does the project actually gate on coverage?
+# Looks for pytest's --cov-fail-under (addopts or a bare flag) and coverage.py's fail_under.
+# Grep rc: 0 = found, 1 = not found, >=2 = the scan itself broke. Treat "broke" as NOT
+# configured so the answer errs toward reporting a gap; a broken scan must never buy a pass.
+coverage_threshold_configured() {
+  local f rc
+  for f in "$TARGET/pyproject.toml" "$TARGET/setup.cfg" "$TARGET/tox.ini" "$TARGET/.coveragerc" "$TARGET/pytest.ini"; do
+    [ -f "$f" ] || continue
+    grep -qE 'cov-fail-under|fail_under' "$f" && return 0
+    rc=$?
+    if [ "$rc" -ge 2 ]; then
+      warn "NOTE: could not read '${f}' while checking for a coverage threshold; treating it as absent"
+    fi
+  done
+  return 1
+}
 
 have() { command -v "$1" >/dev/null 2>&1; }
 
@@ -105,12 +137,21 @@ run_step "ruff check"        ruff check "$TARGET"
 run_step "ruff format check" ruff format --check "$TARGET"
 run_step "mypy"              mypy "$TARGET"
 run_step "pytest + coverage" pytest --cov --cov-report=term-missing
+# Only meaningful if pytest actually ran; a SKIP already says nothing was measured.
+if tool_available pytest && ! coverage_threshold_configured; then
+  gap "coverage ran without a threshold (no --cov-fail-under / fail_under found) — this layer cannot fail. Add --cov-fail-under=<n> to pyproject.toml addopts to make it a gate."
+fi
 run_step "pip-audit"         pip-audit
 
-printf '\n%d passed, %d skipped, %d failed\n' "$PASSED" "$SKIPPED" "$FAILED"
+printf '\n%d passed, %d skipped, %d failed, %d gap(s)\n' "$PASSED" "$SKIPPED" "$FAILED" "$GAPS"
+if [ "$GAPS" -gt 0 ]; then
+  warn "A GAP is neither a pass nor a failure: the layer ran and could not have failed. Report it as unverified."
+fi
 if [ "$FAILED" -gt 0 ]; then
   fail "verify.sh: failures detected"
   exit 1
 fi
-ok "verify.sh: ok"
+# "every check that could fail, passed" rather than a bare ok: with a GAP present, the
+# stronger claim would be false in exactly the way this script now exists to prevent.
+ok "verify.sh: ok (every check that could fail, passed)"
 exit 0

package/skills/go/scripts/verify.sh

@@ -11,6 +11,17 @@
 # Real problems (unformatted code, vet/test/vuln failures) exit non-zero.
 # Read-only: never mutates your source.
 #
+# ONE LAYER HERE IS A REPORT, NOT A GATE. `go test -cover` takes no threshold flag, so
+# coverage can print any number — 4%, 0% — and still exit 0. It is therefore reported as
+# [gap]: the layer ran and had nothing to fail with. Said out loud because a layer that
+# prints a number and exits 0 looks exactly like a layer that passed, and that shape can
+# only ever produce green — no failing run will ever tell you about it. Want a real
+# coverage gate in Go? Parse `go tool cover -func` and compare, or use a CI action; this
+# script does not pretend to be one.
+#
+# A [gap] does NOT change the exit code: this script reports, the `verify` skill judges,
+# and there it counts as an unverified criterion, which fails the verdict.
+#
 # Portability: runs on stock macOS bash 3.2 (no mapfile, no associative arrays,
 # no unguarded array expansions under `set -u`).
 
@@ -24,12 +35,16 @@ else
 fi
 
 failed=0
+gaps=0
 
 have()  { command -v "$1" >/dev/null 2>&1; }
 warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
 fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
 ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
 info()  { printf -- '----- %s\n' "$*"; }
+# A layer that ran but had nothing to fail with. Deliberately does NOT set `failed`:
+# breaking every repo that passes today is not this script's call to make.
+gap()   { printf '%s[gap ]%s %s\n' "$YELLOW" "$RESET" "$*"; gaps=$((gaps + 1)); }
 
 # Must run from a module root.
 if [ ! -f go.mod ]; then
@@ -89,6 +104,10 @@ if have go; then
     warn "cgo disabled or C compiler '$cgo_cc' not found; running plain go test -cover"
     if go test -cover ./...; then ok "tests pass (no race)"; else fail "tests failed"; fi
   fi
+  # The tests above are a gate; the coverage number printed alongside them is not.
+  # `go test -cover` has no threshold flag, so coverage cannot fail this script no matter
+  # how far it falls. Reported so nobody reads the percentage as a checked constraint.
+  gap "coverage: reported, not gated — 'go test -cover' takes no threshold, so this layer cannot fail"
 else
   warn "go not found - skipping tests"
 fi
@@ -102,8 +121,14 @@ else
 fi
 
 echo
+if [ "$gaps" -ne 0 ]; then
+  printf '%s%d layer(s) ran without being able to fail (see [gap] above).%s\n' "$YELLOW" "$gaps" "$RESET"
+  printf 'Not a pass and not a failure: report them as unverified rather than green.\n'
+fi
 if [ "$failed" -ne 0 ]; then
   printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
   exit 1
 fi
-printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"
+# Deliberately "checks that could fail, passed" and not "all checks passed": with a [gap]
+# present the second sentence would be false in the way this whole change exists to stop.
+printf '%sPASS:%s every check that could fail, passed.\n' "$GREEN" "$RESET"

package/skills/implement/SKILL.md

@@ -76,6 +76,24 @@ code tells you nothing about whether it can fail. **Refactor only on green** kee
 reversible against a passing bar. **Checkpoint after each task** is what makes this resumable and
 reviewable instead of a 2000-line surprise diff.
 
+### Four things you may never do to reach green
+
+The loop only means anything if green cannot be manufactured. These are absolute, and each one is a
+way people reach green without fixing anything:
+
+1. **Never weaken a test to make it pass.** Not broadening an assertion, not adding a skip, not
+   raising a tolerance, not deleting it. A test that looks wrong is a **spec conversation** — surface
+   it, don't bury it.
+2. **Never edit a test and the implementation in the same step to reach green.** Change one, run,
+   then the other. Simultaneous edits let you redefine correctness to match your bug without
+   noticing you did it.
+3. **Never mock the unit under test**, or mock so much that the test only exercises the mocks. Mock
+   boundaries you don't own — network, clock, filesystem, third-party SDK — never the logic you are
+   being paid to verify.
+4. **Never chase the coverage number.** Coverage detects untested code; it is not a target. A test
+   added to touch lines, with no meaningful assertion, is gaming — and mutation testing exists
+   precisely to catch it (`../testing-py/SKILL.md`, `../testing-web/SKILL.md`, `../testing-go/SKILL.md`).
+
 ### The done-check is the contract
 
 Each task carries a done-check from the `tasks` phase ("returns 409 on duplicate email", "list

package/skills/review/SKILL.md

@@ -128,9 +128,41 @@ gap deliberately with `--accept-partial-lenses` (it is recorded). Every approval
 
 **Lenses by risk tier** — tier 0 never reaches you (the gate passes docs/copy silently);
 tier 1 → run the single most relevant pass from the table above yourself; tier 2 → dispatch
-**three parallel fresh-context subagents** (correctness · security · tests-as-evidence), each
-given only the diff and told to *refute* readiness, not confirm it. Fresh context is the point:
-a reviewer who inherits the implementer's context inherits its blind spots.
+**three parallel fresh-context subagents** (correctness · security · tests-as-evidence), each told
+to *refute* readiness, not confirm it. Fresh context is the point: a reviewer who inherits the
+implementer's context inherits its blind spots.
+
+**Give each refuter exactly four inputs — no more, no less.** The diff alone is not enough, and
+that is not a detail: with only the diff, the one failure class no test suite can structurally
+catch — *the change is correct and is not what the approved spec asked for* — is invisible to the
+whole panel.
+
+1. **The task contract** — the original request **plus every scope change a human explicitly
+   approved since.** Not just the first message: without the approved changes a legitimate scope
+   revision reads as a spec gap and you get a confident false positive.
+2. **The approved spec** (`02-DOCS/wiki/sdd/specs/<slug>.md`).
+3. **The exact source state** — commit SHA, or a tree hash when git is absent. A verdict belongs to
+   the state that was reviewed, not to the project.
+4. **The entry point** — the one command that reruns the checks.
+
+**And say what they do not get:** your conversation, your reasoning, your defences, and your draft
+verdict. If a claim needs your justification to stand, it is not proven.
+
+**Blind first, compare second.** Each refuter records what it attacked and what it found *before*
+being shown your conclusions. Only then may it compare and add findings — the blind record is
+append-only after that, never rewritten. Skip this and the fresh context is spent confirming your
+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 — the same rule that governs a dismissal.
+
+Two extra finding classes the four inputs unlock, neither reachable from a diff:
+
+- **Contract vs spec** — what would a caller reasonably expect, given the stated deployment, that
+  no clause covers? An exclusion the spec deliberately approved is **not** a finding; an exclusion
+  the spec describes *inaccurately* is.
+- **Mapping, both directions** — an acceptance criterion with no test that can be made to fail, and
+  a test pinning behaviour no criterion asked for.
 
 **A finding blocks only if it survives all three filters** — no exceptions, and eagerness to
 find something is not evidence:

package/skills/specify/evals/cases.yaml

@@ -78,3 +78,5 @@ capability:
       - "Captures observable behaviour (what the user sees/can do) and explicit non-goals / out-of-scope rather than implementation (no file format library, storage, or job-queue detail)."
       - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to Points to clarify instead of fabricating decisions."
       - "Notes that the spec is complete-enough-to-plan with open points remaining, and hands off to clarify — not to plan or implementation."
+      - "After the user answers a question, folds the answer in, states what changed, shows the revised spec, and asks for approval AGAIN — it does not treat the answer as approval of the spec, including when the user picked the recommended option."
+      - "If told to run the whole chain up front, records the approval as autopilot rather than item-by-item, and says the spec is the artifact to review after the fact."

package/skills/testing-go/evals/cases.yaml

@@ -42,3 +42,5 @@ capability:
       - A hand-written interface fake or net/http/httptest server for the HTTP dependency, not a mock framework by default
       - Runs with -race for the concurrent path and shows a go test -coverprofile / cross-package coverage command
       - A benchmark using for b.Loop() with b.ReportAllocs() rather than a b.N loop
+      - "Does not present the coverage percentage as proof the suite detects bugs: states Go has no mature mutation tool, gives the manual procedure, and distinguishes mutation (tests that would not notice a bug) from fuzzing (inputs the code mishandles)."
+      - "Requires a hand-rolled mutant runner to prove it executed each mutant, and says why — a kill reported without running can only inflate the score, so no failing run would ever reveal it."

package/skills/testing-py/evals/cases.yaml

@@ -42,3 +42,5 @@ capability:
       - "asserts on the return value / observable behavior, not on mock private internals like _mock_calls"
       - "mentions a strict posture: --strict-markers and/or --strict-config (or the pytest 9 strict_* aliases)"
       - "at least one negative/error-path test (e.g. raises on non-200), not only the happy path"
+      - "Does not present branch coverage as proof the suite detects bugs: names mutation testing (mutmut) as the layer that catches assertion-free tests, and scopes it to the changed module rather than the whole tree."
+      - "Calibrates mutation by risk rather than prescribing it as a default toll, and says a surviving mutant may be semantically equivalent — to be classified with a reason, never killed with an assertion about non-behaviour."

package/skills/testing-web/evals/cases.yaml

@@ -50,3 +50,5 @@ capability:
       - Tests an error path (500 -> visible error / role=alert) in a separate case
       - No bare act() misuse in the component test; no assertions on state/props/className
       - At least one real expect(...) assertion per test
+      - "Does not present coverage as proof the suite detects bugs: names Stryker as the layer that catches assertion-free tests, and scopes `mutate` to the changed files because a whole-project run does not finish."
+      - "Calibrates mutation by risk rather than prescribing it always, and treats a surviving mutant as possibly equivalent (classified with a reason) instead of adding an assertion about non-behaviour."

package/skills/verify/SKILL.md

@@ -80,6 +80,7 @@ If `config.yaml` provides `testing.commands.verify`, run those commands first or
 Rules for RUN:
 
 - The stack `verify.sh` **skips missing tools** (yellow SKIP) rather than failing on them — so a SKIP is not a pass. Note every SKIP; a skipped test suite means that criterion is **unverified**, which is not the same as verified-passing.
+- A `GAP` is the third thing, and it is the one that looks most like a pass: **the layer ran and had nothing to fail with.** The fastapi gate reports it when coverage runs with no `--cov-fail-under` configured; the Go gate reports it always, because `go test -cover` takes no threshold. The script deliberately does not fail on a GAP — that judgement is yours. **Treat a GAP as an unverified criterion, which fails the verdict**, and record it (see the mapping below). A gate that reports and a gate that checks are indistinguishable on screen, and only the broken one is guaranteed to stay green.
 - A non-zero exit from a tool that actually ran is a hard FAIL. Record the failing tool and its output.
 - Run from the directory the stack skill documents (Go runs from the module root; others from the subproject root). Don't guess paths.
 - If no `scripts/verify.sh` exists for a touched stack, that's a gap — say the gate is incomplete and recommend the user add the stack skill, rather than hand-rolling a one-off check that drifts from the real gate.
@@ -157,6 +158,15 @@ source_state: 3f9a1c2 (clean)
 
 `SUSTITUIDA` is the dangerous one. "Ran the suite twice" is not *suite health: stable* — it is a substitute that cannot see whole-suite order dependence, and a reader who can't tell the two apart reads "found nothing" where the truth is "did not look with that instrument".
 
+**Where a `GAP` goes — and do not invent a fourth label.** A layer that ran without being able to fail is not `NO-APLICA` (the surface exists) and not `HERRAMIENTA-AUSENTE` (the tool ran). It is `SUSTITUIDA`: what ran was **a report in place of a gate**, and what it cannot detect is **coverage falling**. Write it that way:
+
+```text
+- **SUSTITUIDA** — coverage: ran without a threshold (GAP). A report, not a gate;
+  cannot detect coverage regressing. Fix: --cov-fail-under=<n> in pyproject addopts.
+```
+
+**And while you are there: the global percentage is the wrong number.** A project-wide floor barely moves when your change lands untested — 200 new uncovered lines in a 20k-line codebase is a rounding error against an 85% floor, so the gate passes and the change is untested. What matters is whether **the lines you touched** are exercised: `diff-cover coverage.xml --fail-under=100` gates exactly those. This is guidance, not something the generated `verify.sh` scripts do — recommend it, don't assume it ran.
+
 **A dismissed finding carries evidence, one line each.** A fix is self-evidencing — the test now passes. A dismissal is not: "not a real problem" is indistinguishable from "did not check". Name the command, the `file:line`, or the test that disproves it, or write "ninguno".
 
 Append-only spirit: don't overwrite a prior run's record; a new run is a new dated file. The record is the receipt the `review` and `ship` phases trust.

package/skills/verify/evals/cases.yaml

@@ -72,3 +72,8 @@ capability:
       - "RECORDS a dated verification file under 02-DOCS/wiki/sdd/verifications/ and indexes it in the root CLAUDE.md Knowledge map."
       - "Returns a VERDICT that is PASS only if EVERY item has passing evidence; a single unverified acceptance criterion makes the whole verdict FAIL — and refuses to call it 'done' otherwise."
       - "On PASS, points to the review phase; on FAIL, routes failing checks to debug and missing coverage back to implement."
+      - "Treats a coverage GAP (the layer ran with no threshold configured, so it could not have failed) as an unverified criterion that fails the verdict — not as a pass — and records it as SUSTITUIDA: a report in place of a gate, unable to detect coverage regressing."
+      - "Before trusting any home-grown gate that reports green, asks for it to be watched failing on a known-bad input, and states the limit: one negative control proves one bad case reaches the failure path, not that the gate covers the rule it claims to enforce."
+      - "Splits layers that did not run into NO-APLICA / HERRAMIENTA-AUSENTE / SUSTITUIDA rather than one undifferentiated SKIP list, and never writes SUSTITUIDA as a pass."
+      - "Binds the record to a source state (short commit SHA plus clean/dirty) and takes every number from one fresh run made after the last edit, refusing to reuse mid-task figures."
+      - "Gives any dismissed finding its own evidence line (command, file:line, or the test that disproves it) rather than asserting it was not a real problem."