pi-gauntlet 4.8.0 → 4.8.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v4.8.2 - 2026-08-14
+
+Tracker-neutral skill wording - Linear is an example, not the canonical vocabulary.
+
+- `brainstorming`: `## Linear Ticket Handling` renamed to `## Ticket Handling` (consumer overrides matching by name/topic keep working - the substring survives); filename convention now `With ticket: YYYY-MM-DD-<ticket-id>-<topic>.md` with `<ticket-id>` defined as a filename-safe slug of the tracker reference (Linear keys verbatim, e.g. `gh-123` for GitHub issue `#123`); plan headers and commit messages use the tracker's native reference form.
+- `writing-plans`: plan header field `**Linear:** E-XXXX` -> `**Ticket:** <ticket-id>`; "same Linear ID" -> "same ticket ID"; commit example `(ref E-XXXX)` -> `(ref <ticket-id>)`.
+- `finishing-a-development-branch`: squash-commit example `(ref E-XXXX)` -> `(ref <ticket-id>)`.
+- AGENTS core: no-new-machinery rule added to the shared Code & Documentation Discipline section.
+
+## v4.8.1 - 2026-08-12
+
+Fix-loop escalation now tracks convergence, not just round count (#7).
+
+- `subagent-driven-development`: new `## Fix-Loop Rounds` section - the reviewer, not the orchestrator, judges fix-loop trajectory. On every re-review the prior report is passed verbatim under a fixed marker and the reviewer ends with `TRAJECTORY: CONVERGING | DIVERGING | STAGNANT`; the orchestrator pattern-matches that line only. One extra fix round is granted at review 3 iff the verdict is `CONVERGING` with no Critical remaining (spec loop: `CONVERGING` alone); `STAGNANT` escalates immediately, even before the ordinary budget is spent; a missing/malformed line never grants. Escalation reports name reviews run, the final verdict, and whether the convergence exception fired. Applies uniformly to the spec-compliance and code-quality loops in sequential and wave modes; `When a Subagent Fails` and the conformance fix loop are unchanged.
+- Both SDD reviewer prompt templates gain a `## Re-review: trajectory verdict` block with pick-first verdict precedence (STAGNANT > DIVERGING > CONVERGING) - any new finding makes the round DIVERGING even when the count fell.
+- Validated on a small model (RED: old prose reproduced the rubber-stamp escalation and continued past stagnation; GREEN: 6/6 scenarios correct against the new section).
+
 ## v4.8.0 - 2026-08-12
 
 - `writing-plans`: mandatory plan-time recon (fixed one-variable scout template writing a draft to the plan path); plan header `**Verification:**` command set (tests + style + format, header-only); per-task format-and-lint step; scoped-test and header-only-entrypoint Self-Review checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.8.0",
+  "version": "4.8.2",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/SKILL.md

@@ -180,7 +180,7 @@ Cover at minimum:
 
 Be ready to go back and clarify when something doesn't make sense.
 
-## Linear Ticket Handling
+## Ticket Handling
 
 When a ticket ID is given, fetch the ticket and treat it as **guidance, not the sole source of truth**. Propose changes to scope, approach, or acceptance criteria when they don't align with the codebase. Surface deviations in the spec doc.
 
@@ -213,8 +213,8 @@ If the change truly is mechanical and contained (rename, formatter run, dependen
 
 Spec lives in the project's `doc/specs/` (see [Project Routing](#project-routing)) with one of:
 
-- With Linear ticket: `YYYY-MM-DD-E-12345-<topic>.md`
-- Without Linear ticket: `YYYY-MM-DD-<topic>.md`
+- With ticket: `YYYY-MM-DD-<ticket-id>-<topic>.md` — `<ticket-id>` is a filename-safe slug of the tracker reference (e.g. `E-12345` for Linear, used verbatim; `gh-123` for GitHub issue `#123`). Plan headers and commit messages use the tracker's native reference form, not the filename slug.
+- Without ticket: `YYYY-MM-DD-<topic>.md`
 
 `<topic>` is a short kebab-case slug (3–6 words). Do **not** append `-design` or any other suffix.
 

package/skills/finishing-a-development-branch/SKILL.md

@@ -178,7 +178,7 @@ git merge --squash <feature-branch>
 git rm doc/plans/<plan-file>.md   # or <service>/doc/plans/<plan-file>.md
 
 # Single commit covering spec + code + review fixes.
-git commit -m "<imperative summary> (ref E-XXXX)"
+git commit -m "<imperative summary> (ref <ticket-id>)"
 
 # Verify tests on merged result
 <Step 1 command for the service(s) touched>

package/skills/subagent-driven-development/SKILL.md

@@ -28,7 +28,7 @@ You are the **orchestrator**. You read the plan, dispatch, review the review, de
 **Do not pause to check in with the user between tasks.** The plan is already approved. Pause only when:
 
 - A subagent returns `NEEDS_CONTEXT` or `BLOCKED` (see [Implementer Status](#implementer-status))
-- A reviewer finds issues the implementer cannot resolve in two attempts
+- A fix loop escalates per [Fix-Loop Rounds](#fix-loop-rounds) (stagnation, or budget exhausted without convergence)
 - A ⚠️ workflow warning fires
 
 Reaching the end of the plan is not a pause: continue through verification and invoke `/skill:finishing-a-development-branch` as defined in [After All Tasks](#after-all-tasks-complete).
@@ -56,13 +56,36 @@ For each task in `plan_tracker`:
 1. **Dispatch implementer.** Pass the full task text + scene-setting context. Don't make the subagent re-read the plan.
 2. **Handle implementer status** (see below).
 3. **Dispatch spec reviewer.** Verify the diff matches the spec — nothing missing, nothing extra.
-4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅.
+4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves.
-6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅.
+6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 7. Mark task complete in `plan_tracker`.
 
 After all tasks: run the whole-diff code review (`requesting-code-review`). Then [After All Tasks](#after-all-tasks-complete).
 
+## Fix-Loop Rounds
+
+One rule governs both review loops - spec-compliance and code-quality - in sequential and parallel-wave modes alike.
+
+**Re-review dispatch rule:** every re-review task includes the complete prior review report verbatim under the marker `## Previous review report (re-review trigger)`, plus the trajectory block from the reviewer's prompt template. The marker's presence is what obligates the reviewer to emit the `TRAJECTORY:` line. You never select, summarize, or diff findings yourself - pattern-match the sentinel line only.
+
+**The sequence.** Each review that finds issues is a decision point: read the `TRAJECTORY:` line before dispatching anything (review 1 has no line - on issues, dispatch fix 1). Any clean review ends the loop.
+
+1. **Review 1** (first review - no sentinel). Issues -> dispatch fix 1.
+2. **Review 2** (re-review). Issues -> if `STAGNANT`, escalate now - no fix 2. Otherwise dispatch fix 2.
+3. **Review 3** (re-review). Issues -> if the line reads `CONVERGING` and does not contain `max severity Critical` (spec reviews: `CONVERGING` alone), run the convergence exception: dispatch fix 3, then review 4. Any other outcome - `STAGNANT`, `DIVERGING`, a missing or malformed line, `max severity Critical` - escalate. Do not re-dispatch just to obtain the line.
+4. **Review 4** (re-review, only after the exception). Issues -> escalate, whatever the verdict. The exception fires at most once per loop; verdicts never chain into a second grant.
+
+Every dispatched fix is verified by a re-review before escalation or task progression - the loop only ever exits on a clean review or an escalation.
+
+**Escalation report:** report reviews run per loop and the final `TRAJECTORY` verdict - report `TRAJECTORY: MISSING` if the line was absent, or quote the raw line if malformed. If the exception ran, say so explicitly: `fix 3 was the convergence exception (CONVERGING, no Critical)`.
+
+**Worked examples:**
+
+- Review-2 verdict `TRAJECTORY: STAGNANT (repeat of: unchecked error path in parser)` -> escalate now, before fix 2 - earlier than the ordinary budget.
+- Review-3 verdict `TRAJECTORY: CONVERGING (3 -> 1, max severity Moderate)` -> dispatch fix 3; if review 4 still finds issues, escalate with the exception named in the report.
+- Review-3 verdict `TRAJECTORY: CONVERGING (3 -> 2, max severity Critical)` or `TRAJECTORY: DIVERGING` or no `TRAJECTORY:` line -> escalate.
+
 ## Implementer Status
 
 Every implementer dispatch returns one of:
@@ -142,10 +165,10 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
 2. **Fan out.** One parallel dispatch (shape below): `implementer` per task, `context: "fresh"`, `worktree: true`. Each returns a status + a patch.
-3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is not the reviewer's job here (the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅.
+3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is not the reviewer's job here (the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
 4. **Integrate.** `git apply` each task's patch sequentially onto HEAD. Apply fails = textual conflict → drop that task, finish the rest, re-run the dropped task sequentially on the updated HEAD.
 5. **Test gate.** Run the union of the wave's tasks' declared test commands on the integrated tree — the full verification set is the verify phase's job, run once. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
-6. **Quality review.** Code-quality review on the integrated wave diff; loop fixes to ✅. Skip for doc-only waves (SR-only per the commit precondition below).
+6. **Quality review.** Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
 7. **Commit the wave.** Leaves a clean tree; the next wave's children branch from this commit and so see the integrated work.
 
 **Two-stage review is preserved:** spec review per task (pre-integration, dispatched `spec-reviewer` — not inline), quality review per wave (post-integration). A wave commit requires one spec-review verdict per accepted task, plus one code-review verdict on the integrated diff for waves that touch code. A doc-only wave (every task's `Files:` block documentation-only, per `writing-plans`' Wave Grouping) is SR-only — the CR gate does not apply.
@@ -204,6 +227,8 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - Making a subagent read the plan instead of passing task text
 - Starting code-quality review before spec compliance is ✅
 - Moving to next task with either review still showing issues
+- Dispatching fix 3 without a reviewer-emitted qualifying `CONVERGING` verdict at review 3
+- Continuing past a `STAGNANT` verdict instead of escalating
 - Letting implementer self-review replace external review (both needed)
 - Spec-reviewing wave patches inline instead of dispatching `spec-reviewer` per patch — sequential mode's step 3 dispatches it; wave mode must too
 - Pausing to "check in" between tasks (continuous execution rule)

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -23,3 +23,35 @@ Dispatch a subagent with the code-reviewer template:
 - Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
 
 **Code reviewer returns:** Strengths, Issues (Critical/Moderate/Minor), Assessment
+
+## Re-review: trajectory verdict
+
+Include the following in the reviewer's task text on every re-review, after
+the prior review report pasted verbatim under a
+`## Previous review report (re-review trigger)` heading:
+
+If your task contains a "Previous review report (re-review trigger)" section
+and you found issues, end your report with exactly one line:
+
+TRAJECTORY: CONVERGING (<n_prev> -> <n_now>, max severity <X>)
+TRAJECTORY: DIVERGING
+TRAJECTORY: STAGNANT (repeat of: <finding>)
+
+Pick the first label that applies, in this order:
+
+1. STAGNANT: a previous finding survives materially unchanged - name it.
+   (e.g. the same unchecked error path flagged last round is still unchecked)
+2. DIVERGING: <n_now> >= <n_prev>, or the fix introduced any new finding.
+   (e.g. 3 findings fixed but the fix broke an import: DIVERGING, not CONVERGING)
+3. CONVERGING: otherwise - the count fell, nothing new appeared, and every
+   surviving finding was materially improved.
+
+<n_prev>/<n_now> are finding counts; <X> is the highest remaining severity.
+For this line the severity set is exactly Critical/Moderate/Minor, regardless
+of the vocabulary used elsewhere in your report.
+
+The orchestrator dispatches one extra fix only when this line says CONVERGING
+without "max severity Critical" - be accurate, not generous.
+
+If you found no issues, report success as usual and omit this line.
+First reviews (no previous-report section) omit this line.

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -62,6 +62,32 @@ Dispatch a subagent with this prompt:
 
     **Verify by reading code, not by trusting report.**
 
+    ## Re-review: trajectory verdict
+
+    If your task contains a "Previous review report (re-review trigger)" section
+    and you found issues, end your report with exactly one line:
+
+    TRAJECTORY: CONVERGING (<n_prev> -> <n_now>)
+    TRAJECTORY: DIVERGING
+    TRAJECTORY: STAGNANT (repeat of: <finding>)
+
+    Pick the first label that applies, in this order:
+
+    1. STAGNANT: a previous finding survives materially unchanged - name it.
+       (e.g. the same missing requirement flagged last round is still missing)
+    2. DIVERGING: <n_now> >= <n_prev>, or the fix introduced any new finding.
+       (e.g. 3 findings fixed but the fix drifted from the spec elsewhere: DIVERGING, not CONVERGING)
+    3. CONVERGING: otherwise - the count fell, nothing new appeared, and every
+       surviving finding was materially improved.
+
+    <n_prev>/<n_now> are finding counts.
+
+    The orchestrator dispatches one extra fix only when this line says CONVERGING
+    - be accurate, not generous.
+
+    If you found no issues, report success as usual and omit this line.
+    First reviews (no previous-report section) omit this line.
+
     Report:
     - ✅ Spec compliant (if everything matches after code inspection)
     - ❌ Issues found: [list specifically what's missing or extra, with file:line references]

package/skills/writing-plans/SKILL.md

@@ -19,7 +19,7 @@ Before drafting the plan, call `phase_tracker({ action: "start", phase: "plan" }
 
 **Input:** an approved spec in `<project>/doc/specs/<filename>.md` — produced by `/skill:brainstorming` in this session, or handed off from another session (see "Resuming with a spec in hand").
 
-**Save plans to:** the sibling `doc/plans/` directory next to the spec. The plan filename matches the spec filename exactly — same date, same Linear ID (if any), same topic slug, no `-design` suffix.
+**Save plans to:** the sibling `doc/plans/` directory next to the spec. The plan filename matches the spec filename exactly — same date, same ticket ID (if any), same topic slug, no `-design` suffix.
 
 | Spec path | Plan path |
 |---|---|
@@ -185,7 +185,7 @@ Each step is **one action, 2-5 minutes**:
 
 **Verification:** `<full verification command set — tests + style + format; a single bundling entrypoint, or the listed individual commands; from the recon report / project overrides>`
 
-**Linear:** `E-XXXX` (omit if no ticket)
+**Ticket:** `<ticket-id>` (omit if none)
 
 ---
 ```
@@ -240,7 +240,7 @@ Each task uses `- [ ]` checkbox steps so execution tools (and humans) can track
 
   ```bash
   git add tests/path/test.py src/path/file.py
-  git commit -m "<imperative subject> (ref E-XXXX)"
+  git commit -m "<imperative subject> (ref <ticket-id>)"
   ```
 ```