@ericrisco/rsc 1.0.11 → 1.0.12

package/manifest.json

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

package/package.json

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

package/skills/specify/SKILL.md

@@ -130,6 +130,35 @@ irreversible, or large scope), dispatch a **fresh-context subagent** to read the
 **Skip it** for L0/L1 on a small, low-risk spec — the self-review scan is enough there; don't spin up
 a subagent to vet a two-paragraph spec. Like the rest of the chain, ceremony scales to the stakes.
 
+### Approval is its own exchange (step 9)
+
+**An answer to a question is not an approval.** If you asked the user to decide something, they
+answered *that question* and nothing else. Their answer is an **input** to the spec — and it
+*changes* the spec, which means any approval you were holding before the question is the approval
+of a document that no longer exists.
+
+Questions and approval are two exchanges, in that order:
+
+```text
+ask → user answers → fold it in → say what changed → show the revised spec → ask for approval
+```
+
+- **The recommended-option shape is where this fails most easily.** When the user picks the option
+  you recommended, the spec *looks* unchanged and consent *looks* implied. Neither is true — you
+  proposed, they chose, the spec moved.
+- **None of these are approval:** an answer to your question; a "go ahead" about some other step;
+  silence; the request that started the task. If you cannot quote the words that approved **this**
+  spec, you do not have approval.
+- **Autopilot is still valid** — an up-front "run it all yourself" authorizes the whole run, and
+  that is a real answer to a real question. What changes is the bookkeeping: record it as
+  **approved in autopilot, not item by item**, in the spec's `status:`. The spec then becomes the
+  artifact the user reviews *after the fact*, and the work claims correspondingly less certainty
+  about having captured their intent. Writing "aprobada" flat, when what happened was a blanket
+  go-ahead, is the record telling a small lie about the strongest gate in the chain.
+- **Rejection is information — keep it.** If the user turns the spec down, revise it in place and
+  append the reason to `## Revisions`. Never delete and start clean: what they rejected, and why,
+  is the most useful thing in the file.
+
 ## Worked shape (abridged)
 
 ```markdown
@@ -206,6 +235,8 @@ The proposal is allowed to mention options and tradeoffs; the spec that follows
 | Skip the whole loop because "this is too simple to design" | That's the rationalization that wastes the most work. Every feature gets the loop; only a literal one-line, zero-risk change skips. |
 | Present one approach as the answer | Offer 2-3 distinct directions with trade-offs and a recommendation; let the user choose before you write the spec. |
 | Hand to `plan`/`implement` before the user approved the written spec | The approval at step 9 is the gate. No design approved → nothing gets built. |
+| Treat the answer to your question as the approval of the spec | They answered the question, and the answer *changed* the spec. Fold it in, say what changed, show it, ask again. |
+| Write `status: aprobada` after a blanket "just run it" | That is autopilot. Record it as such — the record must not overstate the strongest gate in the chain. |
 | Skip non-goals because "it's obvious" | Unsaid scope becomes assumed scope. State what you are *not* doing. |
 | Resolve every ambiguity yourself to look finished | Inventing answers is worse than naming gaps. List them in Points to clarify. |
 | Start designing the solution because it's clearer | Stay on WHAT/WHY. The plan is a later, separate phase. |

package/skills/testing-go/SKILL.md

@@ -169,6 +169,23 @@ go build -cover -o ./bin/app .                         # coverage for integratio
 
 A coverage **percentage is a smoke alarm, not a goal.** 100% line coverage with no assertions on the values is worthless; 70% on the branches that actually carry logic is fine. Use `-coverpkg=./...` when your tests live in a separate package and exercise code across the module, or the number undercounts. Profiles, integration-binary coverage, and reading the HTML report are in `references/coverage-and-benchmarks.md`.
 
+## Mutation: does the suite actually notice?
+
+Coverage tells you which code ran; it cannot tell you whether any test would have **noticed** if that code were wrong. A table-driven test whose cases all assert `err == nil` and nothing else raises coverage without detecting anything. Mutation testing plants bugs on purpose — flip a `<` to `<=`, drop an early return, replace a returned value with the zero value — and a mutant the suite still passes is a test that asserts nothing.
+
+This is **not** fuzzing. Fuzzing hunts inputs your code mishandles; mutation hunts tests that would not catch a bug you already know about. They find different things and neither substitutes for the other.
+
+Go has **no mature mutation tool** — `go-mutesting` and `gremlins` exist but neither is a dependable default — so this is the manual procedure, and that makes the discipline stricter here, not looser:
+
+1. Pick the changed logic. Script the run and **commit the script** (e.g. `tools/mutants.go` or a shell driver); do not hand-edit N times, because you will need to rerun it and a restore mistake is silent.
+2. One mutant at a time: flip a comparison, off-by-one a bound or slice index, delete one branch, swap `&&`/`||`, return the zero value. `go test ./...` must fail for every one.
+3. Restore, confirm with `git diff` that nothing else moved, and rerun the suite green.
+4. Report as `N/N killed`, naming the mutants.
+
+**The runner must prove it executed each mutant.** A hand-rolled driver that can report a kill it never ran only ever *inflates* the score — so that defect can never surface as a red run, and no failing test will ever tell you about it. Assert the mutated file changed on disk (compare hashes before and after) and that the test command actually exited non-zero for the reason you expect, rather than trusting the loop.
+
+**A survivor is not automatically a failure.** Some mutants are semantically equivalent and cannot be killed; classify those with the reason instead of writing a test that asserts non-behaviour. Scale the whole layer to risk (P7): reach for it where a bug is expensive — money, auth, data loss, concurrency, a public API — not on every change.
+
 ## Benchmarks
 
 Use `for b.Loop()` (Go 1.24+), not the legacy `for i := 0; i < b.N; i++`. `b.Loop` manages the timer itself (setup before the loop and teardown after are excluded automatically), runs the body the right number of times, and the compiler is taught **not** to dead-code-eliminate calls inside it.

package/skills/testing-py/SKILL.md

@@ -139,6 +139,24 @@ pytest --cov=mypkg --cov-branch --cov-report=term-missing --cov-fail-under=85
 
 Line coverage lies because executing a line is not the same as testing its outcomes. A function with `if x: a() else: b()` reaches 100% line coverage from a single test that only takes the `if` arm — the `else` ships untested. `--cov-branch` (or `branch = true`) forces both arms to be exercised, which is exactly where happy-path-only suites leak bugs. `term-missing` prints the unhit line and branch numbers so you know what to write next. Exclude only code that is correctly never run by tests (`if TYPE_CHECKING:`, `raise NotImplementedError`, `__repr__`) — never exclude a branch just to make the number go up.
 
+## Mutation: does the suite actually notice?
+
+Branch coverage tells you which code ran. It cannot tell you whether any test would have **noticed** if that code were wrong — and a test with no assertion, or an assertion that cannot fail, raises coverage without detecting anything. Mutation testing closes that gap by planting bugs on purpose: if the suite still passes, the mutant *survived* and you have found a test that asserts nothing.
+
+```bash
+# pyproject.toml → [tool.mutmut]  source_paths = ["src/"]
+mutmut run                    # whole source tree
+mutmut run "mypkg.core*"      # scope it — this is the normal case
+mutmut results                # what survived
+```
+
+Reach for the real tool, not a hand-written mutant list: mutmut generates mutants from the syntax tree, so it cannot apply one to code that moved and cannot report one it never ran.
+
+- **Scale it to risk.** This is not a default toll — it is minutes-to-hours on a real tree. Run it where a bug is expensive (money, auth, data loss, concurrency, a public API) or where a green suite keeps shipping bugs anyway. Always scope to the code you changed.
+- **A survivor is not automatically a failure.** Some mutants are semantically equivalent to the original and cannot be killed. Classify those with the reason ("equivalent: both branches return the same value for every reachable input"). Never add a test that asserts non-behaviour just to kill one — that is the same gaming that coverage-chasing is.
+- **A survivor that is a real bug gets a test, not an excuse.** Write the assertion that kills it, then rerun.
+- **If you hand-roll a runner, prove it executed every mutant.** Clear `__pycache__` and set `PYTHONDONTWRITEBYTECODE` per mutant: two same-size mutants written in the same second can share a bytecode cache, and the runner then reports a kill for code it never ran. That defect can only ever *inflate* the score, so it will never show up as a red run — which is why the proof has to be built in rather than assumed.
+
 ## Property testing
 
 Reach for Hypothesis when a fixed example matrix can't cover the input space: parsers, serializers, encoders, math, anything with an invariant. You assert a *property* that must hold for all inputs and let Hypothesis hunt counterexamples.

package/skills/testing-web/SKILL.md

@@ -194,6 +194,26 @@ didn't change, and a giant DOM snapshot gets blindly `--updated` the first time
 small, stable, serializable output (a formatted currency string, a normalized config object). Never
 snapshot a full component tree as your primary assertion.
 
+## Mutation: does the suite actually notice?
+
+Coverage tells you which code ran. It cannot tell you whether any test would have **noticed** if that code were wrong — and a `render()` with no assertion, or a snapshot nobody reads, raises coverage while detecting nothing. Mutation testing plants bugs on purpose: if the suite still passes, the mutant *survived* and you have found a test that asserts nothing.
+
+```jsonc
+// stryker.config.json — scope is not optional here
+{ "testRunner": "vitest", "mutate": ["src/cart/total.ts", "src/cart/discount.ts"] }
+```
+
+```bash
+npx stryker run
+```
+
+Reach for the real tool over a hand-written mutant list: Stryker generates mutants from the syntax tree, so it cannot apply one to code that moved and cannot report one it never ran.
+
+- **Always scope `mutate` to the files you changed.** A whole-project Stryker run on a real front-end does not finish in a useful amount of time; that is the main reason teams try it once and abandon it.
+- **Scale it to risk.** Not a default toll. Run it on the logic where a bug is expensive — pricing, totals, permissions, anything money- or auth-shaped — not on presentational components, where a surviving mutant usually just means the DOM detail genuinely does not matter.
+- **A survivor is not automatically a failure.** Some mutants are semantically equivalent to the original and cannot be killed; classify those with the reason. Never add an assertion about non-behaviour just to kill one — that is coverage-chasing wearing a different hat.
+- **A survivor that is a real bug gets an assertion, not an excuse.** Write it, then rerun.
+
 ## Anti-patterns
 
 | Anti-pattern | Why it's wrong | Do instead |

package/skills/verify/SKILL.md

@@ -84,6 +84,15 @@ Rules for RUN:
 - 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.
 
+#### A home-grown gate must prove it can fail
+
+The dangerous way a checker breaks is not a crash — it is **fail-open**: nothing errors, the layer prints pass, and it prints pass forever. That failure can only ever produce green, so no failing run will ever surface it. The rule follows: **before you trust a home-grown gate's pass, watch it fail** on a known-bad input. It is the RED principle applied to the checker.
+
+- **Third-party tools are exempt.** pytest, mypy, tsc, eslint, ruff, `go vet` have earned their failure behavior. This rule is for what we wrote: grep gates, one-off scripts, custom guards, anything whose exit codes nobody has tested.
+- **A must-find-nothing grep has three outcomes, not two.** No matches = pass. A match = fail. **The scan itself breaking** (unreadable input, bad pattern) = fail too. Left unhandled, an unreadable file becomes a silent pass. No `|| true`, no `2>/dev/null`, no bare fallthrough.
+- **State the limit where you state the pass.** Watching a gate fail once proves that *one* known-bad case reaches its failure path. It does **not** prove the gate recognizes every violation of the rule it claims to enforce — a gate can fail closed perfectly and still guard a spelling rather than a behavior. Record the control, and record what it does not buy.
+- **Our own known fail-open:** the stack `verify.sh` scripts SKIP a missing tool instead of failing. That is a documented gap, not a pass — so it goes in the record's *Capas no ejecutadas* under `HERRAMIENTA-AUSENTE`, never left implied.
+
 ### 3 — WALK the done-checks and acceptance criteria
 
 The stack gate proves the code is *clean and tested*. It does **not** prove the feature does what the spec asked. Walk both lists explicitly:
@@ -106,6 +115,7 @@ tags: [sdd, verification]
 timestamp: YYYY-MM-DDTHH:MM:SSZ
 topic: sdd
 slug: <slug>
+source_state: 3f9a1c2 (clean)
 ---
 
 # Verification — <slug> — YYYY-MM-DD
@@ -122,9 +132,33 @@ slug: <slug>
 - [x] AC1 user can place an order — evidence: e2e test green
 - [ ] AC3 duplicate submit is a no-op — UNVERIFIED: no observable proof
 
+## Capas no ejecutadas
+- **NO-APLICA** — mutation: no logic module changed, only templates.
+- **HERRAMIENTA-AUSENTE** — mypy: not installed in this environment; verify.sh printed SKIP and **nothing ran in its place**.
+- **SUSTITUIDA** — suite health: ran the suite twice in a fixed order instead of randomized. Cannot detect whole-suite order dependence.
+
+## Hallazgos descartados
+- "the retry loop can spin forever" — dismissed: `client.py:88` caps it at 3 attempts; test_client.py::test_retry_cap covers it.
+
 ## Verdict: FAIL — 2 open items (T4 done-check, AC3). Not ready for review.
 ```
 
+**`source_state:` is not decoration.** A verdict belongs to the commit it was measured against, not to the project: without it, nobody can tell whether the record describes the code that shipped. Record the short SHA plus `clean` or `dirty` — a dirty tree means the record describes bytes that exist on no commit, which is worth knowing when someone reads it three weeks later.
+
+**All numbers come from one fresh run made after the last edit.** A figure from mid-task is stale and does not go in the record, however true it was when you saw it.
+
+**Split "didn't run" three ways**, because one `SKIP` list collapses three different confidence claims and they read identically:
+
+| Label | Means | Reader should conclude |
+|---|---|---|
+| `NO-APLICA` | the project has no such surface | nothing missing; this describes the project |
+| `HERRAMIENTA-AUSENTE` | the surface exists, the tool was missing, **nothing ran** | that failure class was not looked for at all |
+| `SUSTITUIDA` | something else ran instead | say what the substitute **cannot** detect; never write this as a pass |
+
+`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".
+
+**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.
 
 ### 5 — VERDICT
@@ -146,6 +180,9 @@ Append-only spirit: don't overwrite a prior run's record; a new run is a new dat
 | "A test is failing — let me just fix it real quick." | That's `debug`, a different discipline. `verify` reports the failure and hands off; it does not patch mid-gate. |
 | "I'll write the verdict, then run the checks to confirm." | Backwards. RUN and WALK first; the verdict is the *consequence* of output you already read. |
 | "The gate is mostly green, I'll call it done." | If you cannot point at the line of command output that proves a claim, you have no claim. Go run it. |
+| "I looked at that finding; it's not a real problem." | A dismissal with no evidence is indistinguishable from a check you never made. Name the command, `file:line`, or test that disproves it — or fix it. |
+| "The record is dated, that's enough to trace it." | A date does not identify code. Without `source_state`, nobody can tell whether the record describes what shipped. |
+| "My grep gate passed, so the tree is clean." | Did you ever watch it fail? An unhandled broken scan exits like a pass. Prove it can fail before you trust its green. |
 
 ## Result envelope