@jesdi/skills 0.0.20 → 0.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/crap-gate/SKILL.md

@@ -71,8 +71,12 @@ TypeScript targets still need `node` and the project's own `typescript` package.
 Coverage commands still need the project's test dependencies; configure them
 with its normal runner (for example, `cd backend && pipenv run pytest ...`).
 The launcher preserves PATH and the caller's environment for these commands;
-its private Python is only for the gate engine. It does not install project
-dependencies or edit project environments.
+its private Python is only for the gate engine. One exception: when no
+virtualenv is active and the repo root has `.venv/bin`, that directory goes
+first on PATH, so a bare `python -m coverage` reaches the project's
+interpreter. It does not install project dependencies or edit project
+environments. When a command writes no report, the error ends with the last
+lines of its log.
 
 By default the engine runs each target's coverage command only when that
 target has changed files, so a backend-only change never runs the frontend

package/skills/crap-gate/crap.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import subprocess
 import sys
 import tempfile
@@ -109,6 +110,18 @@ def _score_target(
 
 # ── coverage commands ───────────────────────────────────────────────────────
 
+def _coverage_env(root: Path) -> dict[str, str]:
+    """The caller's environment, plus the repo's `.venv/bin` first on PATH when
+    no virtualenv is active, so a bare `python -m coverage` finds the project's
+    interpreter instead of one without its test dependencies."""
+    env = dict(os.environ)
+    venv = root / ".venv"
+    if not env.get("VIRTUAL_ENV") and (venv / "bin").is_dir():
+        env["VIRTUAL_ENV"] = str(venv)
+        env["PATH"] = f"{venv / 'bin'}{os.pathsep}{env.get('PATH', '')}"
+    return env
+
+
 def _maybe_run_coverage(target: Target, root: Path, run_mode: str, needed: bool) -> TargetRun:
     report = root / target.coverage_report
     should_run = run_mode == "run" or (run_mode == "auto" and needed)
@@ -126,13 +139,17 @@ def _maybe_run_coverage(target: Target, root: Path, run_mode: str, needed: bool)
     # config (same trust model as a Makefile or no-mistakes' commands.*), never
     # user input — it needs `cd … && …`, env assignments and pipes.
     with log.open("w") as fh:
-        proc = subprocess.run(target.coverage_command, shell=True, cwd=root, stdout=fh, stderr=subprocess.STDOUT)
+        proc = subprocess.run(
+            target.coverage_command, shell=True, cwd=root, env=_coverage_env(root),
+            stdout=fh, stderr=subprocess.STDOUT,
+        )
     seconds = time.monotonic() - started
     fresh = report.exists() and (before is None or report.stat().st_mtime_ns > before)
     if not fresh:
         raise ToolError(
             f"{target.name}: coverage command exited {proc.returncode} and wrote no report "
-            f"({target.coverage_report}); see {log.relative_to(root)}"
+            f"({target.coverage_report}); see {log.relative_to(root)}. Last lines:\n"
+            + "\n".join(log.read_text(errors="replace").splitlines()[-10:])
         )
     if proc.returncode != 0:
         print(

package/skills/crap-gate/run.sh

@@ -69,7 +69,8 @@ if [ ! -x "$uv" ]; then
 fi
 
 # Limit uv settings to this subprocess. Do not activate a venv or change PATH:
-# coverage commands must inherit the caller's project environment unchanged.
+# coverage commands inherit the caller's project environment (the engine adds
+# only the repo's own .venv/bin, when no virtualenv is active).
 managed_uv() (
     unset UV_NO_MANAGED_PYTHON UV_PYTHON UV_PYTHON_DOWNLOADS UV_PYTHON_BIN_DIR
     export UV_PYTHON_INSTALL_DIR="$cache/python"

package/skills/crap-gate/test_cli.py

@@ -150,3 +150,27 @@ def test_config_not_at_git_toplevel_is_a_tool_error(tmp_path, monkeypatch, capsy
     monkeypatch.chdir(sub)
     assert crap.main([]) == 2
     assert "git repository root" in capsys.readouterr().err
+
+
+def test_coverage_command_prefers_the_repo_venv(repo, monkeypatch, capsys):
+    # A bare `python` in the command must reach the repo's .venv, not whatever
+    # interpreter the caller's PATH has (which may lack coverage).
+    monkeypatch.delenv("VIRTUAL_ENV", raising=False)
+    venv_bin = repo / ".venv" / "bin"
+    venv_bin.mkdir(parents=True)
+    (venv_bin / "venvpy").write_text('#!/bin/sh\nexec python3 "$@"\n')
+    (venv_bin / "venvpy").chmod(0o755)
+    cfg = json.loads((repo / ".crap-gate.json").read_text())
+    cfg["targets"][0]["coverage"]["command"] = "venvpy fake_cov.py"
+    (repo / ".crap-gate.json").write_text(json.dumps(cfg))
+    (repo / "pkg" / "m.py").write_text(BASE_SRC + "\n\ndef k():\n    return 1\n")
+    assert crap.main([]) == 0
+
+
+def test_coverage_command_without_report_shows_the_log_tail(repo, capsys):
+    cfg = json.loads((repo / ".crap-gate.json").read_text())
+    cfg["targets"][0]["coverage"]["command"] = "echo 'No module named coverage' && exit 1"
+    (repo / ".crap-gate.json").write_text(json.dumps(cfg))
+    (repo / "pkg" / "m.py").write_text(BASE_SRC + "\n\ndef k():\n    return 1\n")
+    assert crap.main([]) == 2
+    assert "No module named coverage" in capsys.readouterr().err

package/skills/implement-spec/SKILL.md

@@ -11,7 +11,10 @@ Changes: a model tier per subagent; a context-isolated test-writer commits
 locked acceptance tests at the ticket's Seam, the implementer turns them green
 with /tdd and reports to a contract; per-ticket review before merge, fix loop
 capped at 4 rounds with escalation; a ruling ledger and four stop conditions;
-a per-ticket gate (check command + crap-gate) before DONE, re-run by the reviewer; check command after each merge; final /review-diff on the most capable model, one
+a per-ticket gate (check command + crap-gate) before DONE, re-run by the reviewer;
+already-green locked tests need a demonstrated mutation; a Codex correctness
+pass per risky ticket; tickets touching the same functions run in sequence;
+check command after each merge; final /review-diff on the most capable model, one
 fixer; closes tickets only if they are issues. Review loop and ledger adapt
 superpowers' subagent-driven-development (obra/superpowers, MIT).
 -->
@@ -26,6 +29,8 @@ Communication to and from subagents should be sparse. Communicate primarily thro
 
 Run ticket subagents in the background where possible for **maximum concurrency**.
 
+**Every dispatch prompt says: never `git stash`, reset or check out other branches; worktrees share one stash and one ref store.**
+
 **Name the model on every dispatch.** Omitted, it inherits yours. Exploration, test-writer, reviewer: mid tier (reviewer higher for risky diffs). Implementer: mid tier; cheapest when the ticket carries the complete code; most capable for design judgment or broad codebase work. Merger: cheapest. Escalations: one tier above the agent that got stuck. Final reviewer: most capable.
 
 **Rule, don't stall.** Keep a **ledger** file in the notes directory: every decision as `Ruling: <what> — <why> — <cost if wrong>`, and each ticket's state, so you can resume after compaction. Don't check in between tickets. Stop and ask only for: an irreversible or destructive operation, a security-sensitive action, a side effect outside the worktrees (a push to a shared branch, a publish), or a spec so broken that every path forward is a guess.
@@ -38,15 +43,19 @@ Run ticket subagents in the background where possible for **maximum concurrency*
 
 3. Create a branch, and a draft PR. If the spec and tickets are issues, mark the PR as 'closing' them.
 
-4. Each ticket gets its own worktree and branch. For a ticket with behavioral criteria, a **test-writer subagent** goes first. It sees ONLY the spec, the ticket, CONTEXT.md/ADRs and the public interface of the ticket's **Seam** line (pointers, not summaries), never the implementer's plan or code. It writes one black-box acceptance test per criterion through that interface (defining the interface if it doesn't exist yet), confirms each fails for the right reason (missing behavior, not an import or syntax error), commits them red, and reports the SHA and files. Those files are now **locked**. A ticket with no behavioral criteria (Seam: `none — refactor`) skips this: its existing tests are the contract, unmodified.
+4. Each ticket gets its own worktree and branch. For a ticket with behavioral criteria, a **test-writer subagent** goes first. It sees ONLY the spec, the ticket, CONTEXT.md/ADRs and the public interface of the ticket's **Seam** line (pointers, not summaries), never the implementer's plan or code. It writes one black-box acceptance test per criterion through that interface (defining the interface if it doesn't exist yet), confirms each fails for the right reason (missing behavior, not an import or syntax error), commits them red, and reports the SHA and files. A test that is already green before any implementation is vacuous until proven otherwise (an earlier guard or early return often satisfies it for an unrelated reason): the test-writer rewrites it to fail, or, when the criterion truly holds already, reports the production-code mutation that turns it red and the red output. Those files are now **locked**. A ticket with no behavioral criteria (Seam: `none — refactor`) skips this: its existing tests are the contract, unmodified.
 
 5. An **implementer subagent** starts from that commit and makes the locked tests green, using /tdd vertical slices for anything internal. It never edits locked files and never dispatches subagents. Before reporting DONE it runs the **gate** in its worktree: the repo's check command (lint, typecheck, full test suite: `make check`, or what AGENTS.md documents) and, when the repo has `.crap-gate.json`, crap-gate scoped to the ticket (`run.sh --base <PR branch>`, or the repo's `make crap-gate` wrapper). DONE means both are green; a gate it can't turn green is BLOCKED, with the output. It reports: status (DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT or BLOCKED), commits, red→green evidence for locked tests and its own slices, the gate's final lines, files touched, concerns. If a locked test contradicts the spec or ticket, it reports BLOCKED with evidence; you rule, and either send the test-writer a correction or overrule the implementer. Handle any BLOCKED by changing something: more context, a stronger model, a split ticket, or a ruling. Never retry unchanged.
 
-6. On DONE, a **reviewer subagent** re-runs the gate first (a red gate is a Critical finding; don't trust the report), then checks the diff against the ticket and spec, then for quality. It also checks that `git diff <test-writer-sha>..HEAD -- <locked files>` is empty and that every criterion has a locked test. Critical or Important findings start a fix loop of at most 4 rounds, each a fix plus a re-review scoped to that fix: rounds 1-2 resume the implementer; rounds 3-4 go to a fresh implementer one tier up. After round 4, rule on each open finding in the ledger and move on. Minor findings go to the ledger for the final review.
+6. On DONE, a **reviewer subagent** re-runs the gate first (a red gate is a Critical finding; don't trust the report), then checks the diff against the ticket and spec, then for quality. It also checks that `git diff <test-writer-sha>..HEAD -- <locked files>` is empty and that every criterion has a locked test. For each locked test, it breaks the production line the test exists to protect (a temporary edit, reverted after) and confirms that test goes red; a test that stays green is Critical. It re-runs every mutation the test-writer reported. Name your specific suspicions in the reviewer prompt (a sibling caller, a key built from the old identity, a guard another ticket added): named suspicions find regressions a generic review misses.
+
+   A **risky** ticket touches shared state, persistence keys or identities, concurrency, money or auth. For those, run the correctness pass from /review-diff yourself, in parallel with the reviewer: `codex exec` with that skill's `correctness.md` on range `<PR branch>...<ticket branch>` (three dots: from the merge-base, so tickets merged meanwhile don't show up), in quick mode (the command is in the review-diff skill). Its findings join the reviewer's, with the same severities.
+
+   Critical or Important findings start a fix loop of at most 4 rounds, each a fix plus a re-review scoped to that fix: rounds 1-2 resume the implementer; rounds 3-4 go to a fresh implementer one tier up. After round 4, rule on each open finding in the ledger and move on. Minor findings go to the ledger for the final review.
 
 7. Once a ticket passes review, a **merger subagent** merges it to the PR branch and runs the repo's check command (lint, typecheck, full suite). If it fails, an implementer fixes the PR branch before the next merge.
 
-8. If this changes the **frontier** of available tickets, start the next tickets. This allows for maximum concurrency.
+8. If this changes the **frontier** of available tickets, start the next tickets. This allows for maximum concurrency. Exception: two ready tickets that change the same function never run at once. Compare their **Touches** lines (or ask the exploration subagent where each will land); on overlap, start one and hold the other until the first merges, then branch it from the updated PR branch. Record the hold as a ruling.
 
 9. Once all tickets are complete, a reviewer on the most capable model runs /review-diff on the PR branch, given the ledger's minor findings and rulings. One **implementer subagent** fixes every finding, then re-review that fix once. Rule on anything left.
 

package/skills/red-team-data-model/SKILL.md

@@ -40,11 +40,30 @@ Given the tables/fields (from `design.md` or a sketch), produce:
 4. **Permissions** — who can see or mutate what; staff vs. customer vs. owner
    boundaries; what an authenticated-but-wrong-role request can still reach.
 
+## Identity inventory (when the change widens a key)
+
+When the change widens an identity or key space (`issue` becomes
+`target#issue`, `user` becomes `tenant+user`), the top 5 is not enough: one
+missed identity is a cross-tenant bug. After the top 5, grep the code for every
+identity built from the old key and list each one as **covered** (the design
+rekeys it) or **out of scope** (with the reason). Look for:
+
+- file and directory names (`task-{N}.json`, `messages/{issue}.jsonl`),
+  including legacy files a save or migration retires;
+- hashes, fingerprints and dedupe keys;
+- cache keys, lock names, markers, dict and set keys;
+- command and URL arguments that take the bare key (`/attach N`);
+- log and event fields other code reads back.
+
+This list is exhaustive, not ranked. It is not a fix: say what is keyed by
+the old identity, not how to rekey it.
+
 ## What NOT to do
 
 - Don't suggest schema changes, indexes, or constraints — that's the design
   session's job, after this list exists.
 - Don't hedge with "it depends" — pick the worst plausible interpretation and
   state its consequence.
-- Don't produce more than 5. Rank and cut; the top failure matters more than
-  a complete list.
+- Don't produce more than 5 failure scenarios. Rank and cut; the top failure
+  matters more than a complete list. (The identity inventory is the one
+  exhaustive list.)

package/skills/to-openspec/SKILL.md

@@ -43,12 +43,15 @@ the spec before the design is written. Don't write code.
 Run only when asked (for example "/to-openspec <slug> stage 2"), after the human has reviewed
 stage 1. Re-read `proposal.md` and `spec.md` first; the human may have edited them.
 
-1. Run the `red-team-data-model` skill against the data model. Print the top 5; don't write them
-   to a file.
+1. Run the `red-team-data-model` skill against the data model. Print the top 5, and its identity
+   inventory when the change widens a key; don't write them to a file.
 2. Write `specs/<slug>/design.md`:
    - **Decisions**: one line each with its tradeoff. Include the ones the red-team findings force.
    - **Data model**: every invariant a DB constraint can enforce (`CHECK`, `UNIQUE`, `NOT NULL`,
      FK, conditional `UPDATE ... WHERE`) goes in the table, not only in app code.
+   - **Identities**: when the change widens a key, every item of the red-team's identity
+     inventory, marked covered (task IDs filled in step 3) or out of scope (why). Otherwise "None." Add the
+     heading when the repo's template lacks it.
    - **Seams**: the endpoint, function, or command the tests drive through, marked existing or
      new. Prefer one high seam.
 3. Write `specs/<slug>/tasks.md`: vertical slices, each small enough for one commit and one green
@@ -58,6 +61,8 @@ stage 1. Re-read `proposal.md` and `spec.md` first; the human may have edited th
      makes the list a task graph `implement-spec` can run directly.
    - A slice adds only the tables and columns its own scenarios need, not the whole model up front.
    - No standalone "run the checks" task: every task already ends with the check command green.
+   - Then fill the task IDs into `design.md`'s **Identities**: every identity marked covered names
+     the task that rekeys it. A covered identity with no task is a missing task; add it.
 
 Print the task list, then **Open questions**: every red-team finding the design leaves
 unresolved, and every input the design assumes but the sources don't provide. Then stop. Don't

package/skills/to-openspec/templates/design.md

@@ -14,6 +14,14 @@ Tables/fields touched or added, and the invariants that go in DB constraints (no
 |---|---|---|---|
 | | | | |
 
+## Identities
+
+When this change widens a key, each identity built from the old key (file names, hashes,
+dedupe keys, command args, dict keys): covered by which task, or out of scope and why. Otherwise
+"None."
+
+- `<identity>` — covered by <task> | out of scope: <why>.
+
 ## Seams
 
 Where tests drive through: module, function, command, or endpoint. Mark each existing or new.

package/skills/to-tickets/SKILL.md

@@ -9,8 +9,9 @@ Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebb
 Changes: tickets always go to `.agent/tickets/<NN>-<slug>.md` (no tracker path);
 numbering is contiguous from 01 in dependency order; acceptance criteria must state
 observable behavior; every ticket names its **Seam** (the public interface its
-acceptance tests hit); the approval quiz is skipped when unattended; model
-invocation is allowed.
+acceptance tests hit) and what it **Touches** (files and functions, for
+scheduling); the approval quiz is skipped when unattended; model invocation is
+allowed.
 -->
 
 # To Tickets
@@ -53,6 +54,7 @@ When a human is in the loop, present the proposed breakdown as a numbered list.
 - **Title**: short descriptive name
 - **Blocked by**: which other tickets (if any) must complete first
 - **Seam**: the public interface its acceptance tests hit
+- **Touches**: the files and functions it expects to change
 - **What it delivers**: the end-to-end behaviour this ticket makes work
 
 Ask the user:
@@ -85,6 +87,8 @@ Do NOT close or modify any parent issue.
 
 **Seam:** the public interface the acceptance tests hit (a function, an HTTP route, a CLI command, a config loader…), or `none — refactor`.
 
+**Touches:** the files, and the functions within them, this ticket expects to change.
+
 - [ ] Acceptance criterion 1
 - [ ] Acceptance criterion 2
 
@@ -102,4 +106,10 @@ Every ticket carries a **Seam** line: the one public interface through which its
 
 </seam-rule>
 
-Avoid specific file paths or code snippets: they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.
+<touches-rule>
+
+The **Touches** line is a best guess, for scheduling: `implement-spec` never runs two tickets at once that change the same function, because parallel restructures of one function turn into rebase churn and broken locked tests. Name functions, not only files, when a file is shared (`dispatcher/main.py: _run_pass, _resume_woken`). Two tickets restructuring the same function is also a hint to add a blocking edge between them, or to merge them.
+
+</touches-rule>
+
+Outside the **Touches** line, avoid specific file paths or code snippets: they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-24T15:47:23.496Z",
+  "generatedAt": "2026-09-24T19:16:41.414Z",
   "skills": [
     {
       "name": "backlog",
@@ -22,8 +22,8 @@
     },
     {
       "name": "crap-gate",
-      "version": "0.1.3",
-      "hash": "sha256-39041927a985061599a39bb287232b83655ecbac61b7de52486f485991a99d30",
+      "version": "0.1.4",
+      "hash": "sha256-a3fe7bcb7ad6566aa25c44b0bc7823c625b536b4f3eb5cdfe73e6628ad04ee05",
       "description": "Score every function a branch changed with CRAP (cyclomatic complexity × untested fraction), fail on existing functions above 15 and new functions above 9, and drive a fixer + independent reviewer loop until the gate passes. Use when implementation is done and before pushing, when the user says \"run the crap gate\", \"check CRAP\", \"is this change tested enough\", or when a push gate reports CRAP violations."
     },
     {
@@ -46,8 +46,8 @@
     },
     {
       "name": "implement-spec",
-      "version": "0.1.1",
-      "hash": "sha256-678f3481bce18448d0d27ef33c096d4b64faf8dd7254dd8d0bc73f8c134a7f58",
+      "version": "0.1.2",
+      "hash": "sha256-ae8c88981b359c9b19ba285bacc38264ba11dca163be7b1fde4ff73ac278465b",
       "description": "Implement a specification in code."
     },
     {
@@ -64,8 +64,8 @@
     },
     {
       "name": "red-team-data-model",
-      "version": "0.1.0",
-      "hash": "sha256-3c7a00bbb05190a431ea101db79b6e27bbfc6c8b24b14b0fe560a82a201afdb9",
+      "version": "0.1.1",
+      "hash": "sha256-37737ab44c3c2f4812ceedbf2a14cdb259ceca0c8d8b9bb9ac9af92b23742808",
       "description": "Attack a proposed or existing data model for the ways it breaks under real conditions — concurrency, time windows, money, permissions — without proposing a redesign. Use right after sketching a data model, before writing the spec, so the top failure scenarios shape the spec's requirements and tests instead of getting discovered mid-build. Trigger on \"red-team my data model\", \"what breaks in this schema\", or \"/red-team\"."
     },
     {
@@ -76,8 +76,8 @@
     },
     {
       "name": "to-openspec",
-      "version": "0.1.0",
-      "hash": "sha256-c3c66a08fe27afa1f530989b77c7b4fd2d6a379cc844a9ca5f55072bede9b64a",
+      "version": "0.1.1",
+      "hash": "sha256-223f00ac309e5365e77708e8f3fc22c36a02e52f4c071af54ea25ea4d9461965",
       "description": "Turn settled discovery notes and a sketched data model into a spec folder in openspec shape (proposal, spec, design, tasks) under specs/<slug>/. Runs in two stages with a human review between them. No interview, just synthesis of decisions already made. Trigger on \"write the spec\", \"to-openspec\", or \"/to-openspec <slug> [stage 2]\"."
     },
     {
@@ -88,8 +88,8 @@
     },
     {
       "name": "to-tickets",
-      "version": "0.1.1",
-      "hash": "sha256-4c838fa240c742353f77b3a3c1246a0948140587e81c9bc587f84c648e552bba",
+      "version": "0.1.2",
+      "hash": "sha256-13e639c6412c6d875d285e452fd0f8c64597c4653cedbbe0e7aa0c19cd717ec1",
       "description": "Break a spec, plan, or the current conversation into numbered tracer-bullet ticket files under .agent/tickets/, each declaring its blocking edges and acceptance criteria phrased as observable behavior. Use after a spec is approved and before implementation starts."
     },
     {