@jesdi/skills 0.0.27 → 0.0.29

package/README.md

@@ -47,8 +47,25 @@ npx @jesdi/skills-cli update [skill] [--all] [--global]
 npx @jesdi/skills-cli sync
 npx @jesdi/skills-cli list
 npx @jesdi/skills-cli uninstall <skill> [--global]
+npx @jesdi/skills-cli pin <skill> [--global]     # keep the installed version
+npx @jesdi/skills-cli unpin <skill> [--global]
+npx @jesdi/skills-cli hook                 # register the session update hook
 ```
 
+## Automatic updates
+
+A global install registers a session-start hook in Claude Code
+(`~/.claude/settings.json`) and Codex (`~/.codex/hooks.json`), for each one
+that is present. The first session of a day runs
+`skills-cli update --all --global` in the background; the result is in
+`~/.my-skills/.session-update.log`. Project installs do not change: they stay
+at the versions committed in `.my-skills.json`.
+
+To keep a skill at its installed version, pin it: `skills-cli pin <skill>
+--global`. No update touches a pinned skill until `unpin`. To stop all
+automatic updates, remove the hook entry from the two config files; the next
+global install or `skills-cli hook` adds it again.
+
 ## Third-party skills (not vendored)
 
 Skills authored by other people are **not** copied into this repo — they keep

package/package.json

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

package/skills/implement-spec/SKILL.md

@@ -11,13 +11,19 @@ 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;
+a per-ticket gate (check command + crap-gate) before DONE, verified 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; no push and no PR until every
+fixer; ticket-grouped history with fixes folded in before review; closes
+tickets only if they are issues; no push and no PR until every
 ticket is merged and the final review has passed. Review loop and ledger adapt
 superpowers' subagent-driven-development (obra/superpowers, MIT).
+Verification schedule (after a 44-hour run with 65 full gates for six tickets):
+one gate record per candidate, verified by the reviewer instead of re-run;
+mutation proofs once, then only for changed lines; a budget ruling after round 2;
+fixture corrections outside the fix loop; a named fallback when codex exec is refused;
+one report file per agent; plain-sentence ledger.
 -->
 
 You have been provided a spec. This spec should have tickets associated with it, describing how to implement the spec.
@@ -28,19 +34,19 @@ The tickets are not a list of steps. They are a **task graph** with blocking rel
 
 Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers.
 
-Run ticket subagents in the background where possible for **maximum concurrency**.
+Run ticket subagents in the background where possible for **maximum concurrency**. Wait on a running subagent with one long wait, in minutes. Each subagent leaves one report file plus its gate log in the notes directory; mutation evidence is a table in the report, and a tree-hash manifest or a per-mutant log is a sign the agent is building its own procedure.
 
 **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 for a small, fully specified ticket; 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.
+**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. Ledger entries are plain sentences, one line per event, written for a human who was not there. After a compaction, read the ledger and continue from its last state: a recorded green gate, review or merge stays settled. 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.
 
 ## Steps
 
 1. Read the spec and tickets. Read enough to understand the task graph.
 
-2. Create a notes directory outside the repo, readable by all subagents, and start the ledger there. (optional) An **exploration subagent** saves its notes on relevant code and docs there, so implementers focus on implementation.
+2. Create a notes directory outside the repo, readable by all subagents, and start the ledger there. (optional) An **exploration subagent** saves its notes on relevant code and docs there, so implementers focus on implementation. It is the only exploration or preparation agent: a ticket starts with its test-writer, when its frontier turn comes.
 
 3. Create the PR branch locally. Do **not** push it and do **not** open a PR yet: nothing leaves the
    machine until every ticket is merged and the final review has passed (step 10). Intermediate
@@ -49,22 +55,30 @@ Run ticket subagents in the background where possible for **maximum concurrency*
 
 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.
+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. While working it runs targeted tests. Before reporting DONE it runs the **gate** once, on a clean tree at its final commit, as one **gate record**: 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), wrapped so the log in the notes directory carries the start and end time, the commit, and the status:
 
-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.
+   ```sh
+   { date -u; git rev-parse HEAD; git status --short; <gate commands>; echo "gate exit $?"; date -u; } 2>&1 | tee <notes>/<ticket>-gate-$(git rev-parse --short HEAD).log
+   ```
 
-   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.
+   DONE means the record is green; a gate it can't turn green is BLOCKED, with the output. CRAP findings are the implementer's to resolve inside the ticket, within this same gate. It reports: status (DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT or BLOCKED), commits, red→green evidence for locked tests and its own slices, the gate record's path and 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.
 
-   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** verifies the gate record first: the recorded commit is the ticket tip, the status was clean, and the tail is green. A missing, mismatched or red record is a Critical finding, and only then does the reviewer run the gate itself. It 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; that one diff is the whole locked-file check. In the first review, 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. A mutation proof is keyed to its test and production line: a later round repeats it only when that line changed. 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.
 
-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.
+   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. When `codex exec` is refused or unavailable, the reviewer's brief gains `correctness.md` for the ticket's risk; that reviewer is the correctness pass, with no second agent.
+
+   A finding that a locked test encodes a stale path, format, fixture layout or setup detail is a **fixture correction**, outside the fix loop: one test-writer dispatch fixes it, the ledger records the file and reason, and the review continues. A setup or environment failure (a missing dependency link, a cache permission, a leftover process) is fixed at its cause before any gate runs again.
+
+   Critical or Important findings start a fix loop of at most 4 rounds, each a fix plus a re-review scoped to that fix: the implementer uses targeted tests, ends the round with one gate record on its final commit, and the re-review verifies that record and the changed lines. Rounds 1-2 resume the implementer; rounds 3-4 go to a fresh implementer one tier up. After round 2, rule in the ledger before continuing: continue, split the ticket, or redesign it. 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. Record the ticket's commits and any integration fixes in the ledger. After the merge and checks pass, remove that ticket's worktree and delete its branch with `git branch -d` from the PR branch, while its commits are still ancestors of the PR tip. Cleanup is part of completing the ticket, before any rebase.
 
 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. When in doubt, hold: a ticket you suspect builds on another ready or running ticket waits for it, even without a declared edge. 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.
+9. Once all tickets are complete, fetch and rebase the unpublished PR branch onto the latest base, then tidy its history by ticket using [history.md](history.md). A reviewer on the most capable model runs /review-diff on the resulting PR branch, given the ledger's minor findings and rulings. Record its resolved range and reviewed tip in the ledger. One **implementer subagent** fixes every finding as one batch, which may contain several working commits; it records the owning ticket for each fix. Use targeted checks during the fixes. Once the whole batch is complete, tidy it into the ticket commits, then run /review-diff on the full rewritten branch. If history was preserved, a scoped /review-diff on `<last-reviewed-tip>..HEAD` suffices. Its gate runs once for the completed batch. Record the new review's range and tip, marking superseded coverage, or `not needed` if there were no fixes. Rule on anything left.
+
+10. Before pushing, compare `git rev-parse HEAD` with the last reviewed tip and confirm the worktree is clean. Every commit through the branch tip must be covered by the full review plus any scoped re-reviews. Collect any later commits, including orchestrator changes, into one batch and follow step 9's tidy-and-review procedure. A rebase or history rewrite invalidates the recorded coverage: review the full rewritten branch, with one full gate for that completed batch. The push is ready only when the history is grouped by ticket, the clean branch tip equals the last reviewed tip, and every finding has a fix or a ledger ruling. If the review cannot finish, report the blocker and each unreviewed commit with its subject, and keep the branch local.
 
-10. Now, and only now, push the PR branch once and open the PR, ready for review (not draft). If the
-    spec and tickets are issues, mark the PR as 'closing' them. List every ruling from the ledger in
-    your final message.
+    Now push the PR branch once and open the PR, ready for review (not draft), using /pr for the body when installed. If the spec and tickets are issues, mark the PR as 'closing' them. In your final message, list every ruling, the final ticket-to-commit map, and the review coverage: the latest full review's range and tip, any scoped re-review ranges and tips since it (or `not needed`), the current branch tip, and whether it equals the last reviewed tip. Earlier reviews of superseded history stay in the ledger.
 
-11. Clean up all ticket worktrees.
+11. Confirm every ticket worktree and branch was removed in step 7.

package/skills/implement-spec/history.md

@@ -0,0 +1,52 @@
+# History by ticket
+
+Tidy the unpublished integration branch into one coherent commit per ticket,
+ordered so each ticket follows its dependencies. Each commit contains that
+ticket's acceptance tests, implementation, and all review or integration fixes.
+The reviewer's commit list should tell the story of the tickets, with the
+final behavior at each step.
+
+## Before rewriting
+
+- Confirm all ticket worktrees and branches were cleaned up after their merges,
+  and that the integration worktree is clean.
+- Confirm the branch has never been pushed. Once pushed, preserve its history
+  and add reviewed follow-up commits; rewriting a published branch requires
+  explicit user authorization.
+- Record the current tip and `HEAD^{tree}` in the ledger as the recovery point.
+  Use the ticket reports and ledger to map every working commit and every fix
+  to its owning ticket before editing history.
+
+## Group the changes
+
+Use an interactive rebase or reconstruct the commits in an isolated worktree,
+operating only on branch-owned commits after the base. Fold red-test commits,
+implementation commits, and later fixes into their ticket commit. Flatten
+branch-only merge commits while preserving their conflict-resolution changes.
+Keep the test-writer's acceptance files unchanged from their locked versions.
+
+A fix touching several tickets is split by ownership when the resulting
+commits can stand alone in dependency order. If it cannot be split safely,
+combine the affected tickets into one coherent commit, name them in the
+message, and record the reason in the ledger. Every final change has a ticket
+owner; an out-of-scope change needs a ruling before inclusion.
+
+Use a commit subject that names the ticket's delivered behavior and put its
+ticket number or file pointer in the body. Keep a map from the old working
+commits to the final ticket commits in the ledger; ticket reports and locked
+test SHAs still refer to the original history.
+
+## Completion
+
+The rewritten tip's tree must equal the saved tree: history cleanup changes
+the presentation of the work, not its files. A mismatch must be resolved
+before review. Inspect each final commit's diff against its ticket to confirm
+the tests, implementation, and fixes stayed together, dependencies precede
+their consumers, and no temporary red-test or fix-only commits remain.
+
+Use targeted checks where needed to verify a regrouped ticket. Run the full
+gate once at the completed branch tip, through /review-diff. Rewriting changes
+the review endpoints, so the next review covers the full rewritten branch;
+mark the old coverage superseded even if the tip's tree is identical. After a
+review requests fixes, finish the whole fix batch, fold it into these same
+ticket commits, and repeat this completion check before the next review.

package/skills/review-diff/SKILL.md

@@ -37,6 +37,15 @@ on one axis must not hide a failure on another.
 Before anything else, confirm the range resolves and the diff is non-empty. A
 bad ref fails here, not inside three reviewers.
 
+Resolve the diff endpoints to commit SHAs once, before the gate, and use that
+immutable range for every reviewer and the commit list. For a base ref, the
+start is its merge-base with the captured `HEAD`; for an explicit range, keep
+its requested diff semantics. Record the reviewed tip (the right endpoint)
+and the branch tip at the start. Run the gate on that reviewed tip in a clean
+worktree; an explicit range ending at another commit needs a worktree at that
+commit. Local changes must be committed or removed before review so the range
+accounts for everything checked.
+
 ## Step 0 — gate (sequential, a precondition, not a reviewer)
 
 1. Run the repo's check command: `make check` if the Makefile has it,
@@ -70,7 +79,7 @@ paste one reviewer's output into another's prompt.
   ```bash
   out=$(mktemp) && codex exec -s read-only --ephemeral -o "$out" \
     "Read and follow <skill-dir>/correctness.md. Range: <range>. Commits: <list>.<quick>" \
-    >/dev/null 2>&1; cat "$out"
+    < /dev/null >/dev/null 2>&1; cat "$out"
   ```
 
   No Codex → spawn a subagent with the same instruction and note "Correctness:
@@ -88,6 +97,7 @@ fresh context if you can, and say so.
 
 ```
 Gate: `make check` green · crap-gate green
+Coverage: <resolved range> · reviewed tip: <SHA> · current branch tip: <SHA> · tip matches: yes/no
 
 ## Spec
 <report, verbatim or lightly cleaned>
@@ -107,6 +117,15 @@ A skipped step keeps its place with its one-line note (in the gate line, or
 as the section body and summary line). `--quick` has no Structure section and
 no Structure summary line. A clean reviewer's summary line is `0 findings`.
 
+Read the original branch tip again when reporting. Include the coverage line
+in full and quick reviews, and label a failed gate `review not run` rather
+than calling its endpoint reviewed. Name skipped or failed reviewers so the
+coverage line cannot imply they ran. If the branch tip changed, list each
+commit in `<reviewed-tip>..<current-tip>` with its subject. If the reviewed tip
+is no longer an ancestor (for example, after a rebase or history cleanup), state that this review
+does not cover the current history. Report a dirty worktree as unreviewed
+local changes even when the tips match.
+
 Do not merge, dedupe or re-rank findings across reviewers, and do not pick an
 overall winner. A finding two reviewers both raise stays in both reports; that
 is signal.

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-06T10:03:53.513Z",
+  "generatedAt": "2026-10-08T12:46:28.852Z",
   "skills": [
     {
       "name": "backlog",
@@ -46,8 +46,8 @@
     },
     {
       "name": "implement-spec",
-      "version": "0.1.5",
-      "hash": "sha256-43b1b1b97386b96b2cc8124ca906ffc0a5a4b35362413b52ac154c1faaa0b43e",
+      "version": "0.1.7",
+      "hash": "sha256-dfcd2f6a13fd06dd4fb7a45bb0d85ae39228ec804dc94c845310afa72808d3d5",
       "description": "Implement a specification in code."
     },
     {
@@ -70,8 +70,8 @@
     },
     {
       "name": "review-diff",
-      "version": "0.1.1",
-      "hash": "sha256-ac4b526f0436f06acc4e5e2254b83b5318a14065caab3f922f20fa7da9e87c5f",
+      "version": "0.1.2",
+      "hash": "sha256-70beaf1478820d66e1831d45739ce97ced50224b46c5003d887ea62c8438f251",
       "description": "Review a branch before merge: first a gate (the repo's check command plus crap-gate), then three independent reviewers in parallel — spec (did we build what was asked, no more, no less), correctness via Codex (races, idempotency, money, time, authz, indexes, N+1, migrations, error paths, test quality) and structure (deep-quality-review). `--quick` runs only spec and correctness, shortened, for a live interview. Use when the user says \"/review-diff\", \"review this branch\", \"review this slice\", \"review before merge\", or before closing out a spec task."
     },
     {