Merge pull request 'chore: sprint skill + self-review gate in the dev loop' (#48) from chore/sprint-skill into main

.claude/skills/sprint/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sprint
+description: Use when the user says "start sprint N", "groom sprint N", "continue the sprint", or "/sprint" for the digger project — grooms a sprint just-in-time, then runs the per-issue dev loop (worktree → TDD → PR → CI green → self-review → stop for the human to approve+merge), keeping the plan and Forgejo issues reconciled. Encodes digger's working agreement; composes with the superpowers skills rather than replacing them.
+---
+
+# digger sprint runner
+
+A thin orchestrator for delivering one sprint of the digger v1 plan. It does **not** invent rules — it sequences the existing ones and enforces the guardrails so nothing gets skipped across a long, context-heavy sprint. The authorities it points at:
+
+- `CLAUDE.md` — the working agreement (worktrees, TDD, never self-merge).
+- `docs/superpowers/plans/2026-07-01-digger-v1-plan.md` — the **source of truth** for scope.
+- `docs/sprints/README.md` + `docs/sprints/sprint-<n>-*.md` — the grooming convention and each sprint's groom doc.
+- Forgejo (via the Forgejo MCP, repo `forgejo_admin/digger`) — issues + milestones.
+- superpowers skills — `test-driven-development`, `using-git-worktrees`, `requesting-code-review`, `executing-plans` / `subagent-driven-development`, `verification-before-completion`.
+
+## Non-negotiables (never skip)
+
+- **Never self-merge, never mark ready early.** A PR is "ready" only after **CI is green AND a self-review pass is done**. The human approves and merges.
+- **Plan is the source of truth.** Any issue add/change/remove is reflected back into the plan doc in the same breath.
+- **Groom only the sprint about to start**, from plan + current repo state + the previous sprint's retro.
+
+## Phase 1 — Groom
+
+1. Read the sprint's section of the plan, the previous sprint's retro (if any), and the current repo state.
+2. Write or refresh `docs/sprints/sprint-<n>-<slug>.md` from the template in `docs/sprints/README.md` (demoable slice, issues-in-scope + PR sequence, adjustments vs plan, risks, DoD).
+3. If grooming changes scope, flow it back: **groom doc → plan doc → Forgejo issues** (create/edit via MCP).
+4. **Show the groom doc to the human and wait for a go-ahead** before writing any code.
+
+## Phase 2 — Per-issue dev loop
+
+For each issue in the groom's PR sequence (respect `Depends on`; split large issues into multiple PRs):
+
+1. **Pick the issue** (Forgejo MCP); confirm it's unblocked.
+2. **Worktree + branch** off latest `main` — `../digger.worktrees/<issue>-<slug>`, branch `<type>/<issue>-<slug>` (use superpowers:using-git-worktrees).
+3. **TDD** — red → green → refactor (superpowers:test-driven-development). Keep the change scoped to the issue.
+4. **Open the PR** — `Closes #N`, small and self-contained.
+5. **Wait for CI to go green** (Linux unit + integration; Windows unit where relevant). Do not proceed while red.
+6. **Self-review** the diff (`/code-review` or superpowers:requesting-code-review). Fix blocking findings; if you push fixes, **re-confirm CI is green**.
+7. **Only now say it's ready** — present the PR + evidence (green CI, self-review summary) and **stop for the human to approve + merge**. Never self-merge.
+8. **After merge** — remove the worktree + delete the branch; reconcile the plan doc + Forgejo issue/milestone status; tick the issue in the groom doc.
+
+**Keep the groom doc's per-issue Status live** at every transition (`todo → in progress (branch <x>) → PR #N open (CI <state>) → merged`), not only on merge. Commit per TDD step and push the branch early, so the PR + CI reflect the true state. This is what makes a mid-sprint resume deterministic rather than archaeological.
+
+## Resume — session closed mid-sprint
+
+A new session has none of the prior conversation; reconstruct the frontier from durable state, in this order:
+
+1. **Groom doc** (`docs/sprints/sprint-<n>-*.md`) — the per-issue Status column is the first read: what's done, what's in flight.
+2. **Forgejo** (MCP) — issue states, milestone progress, and any **open PR** with its CI + review state.
+3. **Git** — `git worktree list`, branch commits, and whether any worktree has committed-but-unpushed **or uncommitted** work (the only signal not on Forgejo).
+4. **Decide the frontier and resume:**
+   - Open PR awaiting the human's merge → leave it; pick the next unblocked issue.
+   - Branch mid-implementation (worktree exists) → continue its TDD loop from where the commits/tests leave off.
+   - PR open but CI red or self-review not done → finish that gate before touching anything else.
+   - Nothing in flight → start the next unblocked issue in the groom's sequence.
+
+Always re-honor the gates on resume: CI green + self-review before "ready", never self-merge. If the groom doc's Status disagrees with Forgejo/git, trust Forgejo/git and correct the groom doc.
+
+## Phase 3 — Close the sprint
+
+- When every in-scope issue is merged and the demoable slice runs, fill the **Retro** in the groom doc.
+- Reconcile the plan doc + `v1` milestone with what actually shipped.
+- The retro is the primary input to the next sprint's grooming.
+
+## If the user just says "continue" / "next issue"
+
+Resume Phase 2 at the next unblocked issue in the current groom doc. If no groom doc exists for the active sprint, do Phase 1 first.

CLAUDE.md

@@ -19,7 +19,10 @@ Authoritative spec — read before planning or any architectural decision:
   the repo), branched as `<type>/<issue>-<slug>` (feat|fix|chore|docs|refactor|test) off the
   latest main. Never work on main. Remove the worktree and delete the branch after merge.
 - Dev loop: pick a Forgejo issue (via the Forgejo MCP) → worktree + branch → tests-first →
-  PR (Closes #N) → review + green CI → **I approve and merge. Never self-merge.**
+  PR (Closes #N) → **wait for CI to go green → self-review my own diff** (via `/code-review`
+  or superpowers:requesting-code-review; fix blocking findings — if I push fixes, re-confirm
+  CI is green) → **only then say it's ready** → **I approve and merge. Never self-merge.**
+  Never claim a PR is ready before CI is green and the self-review pass is done.
 - Prefer **small, functional PRs.** I review PRs myself, so keep each one small,
   self-contained, and independently green — that makes review much easier. If an
   issue/task is large, **split it into multiple PRs** (one issue may span several);

docs/sprints/README.md

@@ -22,9 +22,11 @@ The [v1 plan](../superpowers/plans/2026-07-01-digger-v1-plan.md) is the stable,
 <The one working end-to-end thing this sprint proves at close.>
 
 ## Issues in scope (PR sequence)
-| # | Title | Depends on | Notes / PR split |
-|---|---|---|---|
-| #NN | … | #NN | … |
+Keep **Status** live at every transition (`todo → in progress → PR #N open (CI <state>) → merged`) so a mid-sprint resume can read the frontier instead of reconstructing it.
+
+| # | Title | Depends on | Status | Notes / PR split |
+|---|---|---|---|---|
+| #NN | … | #NN | todo | … |
 
 ## Adjustments vs the plan
 <What changed during grooming and why. "None" is a valid answer. Each change
@@ -34,6 +36,7 @@ must already be reflected in the plan doc + the Forgejo issue.>
 - …
 
 ## Definition of done
+- Every in-scope issue: PR opened → **CI green → self-review pass done → human approved + merged** (never self-merged, never called ready before CI-green + self-review).
 - All in-scope issues merged; CI green (incl. the relevant tiers); the demoable slice runs.
 - Plan doc + milestone reconciled with what actually shipped.