pi-gauntlet 5.1.0 → 5.2.1

package/skills/dispatching-parallel-agents/SKILL.md

@@ -112,7 +112,14 @@ Reviewers certify fix concurrency with a `Parallel-safe:` line (see the reviewer
 
 **Precondition:** a clean committed HEAD containing the code under review. When the reviewed change is an unintegrated patch (a wave-mode per-patch spec review), each fix task branches from the wave's base HEAD and carries the prior patch verbatim in its task text — the consuming loop's existing re-dispatch protocol. When the tree is dirty (e.g. post-integration, before the wave commit), the fan-out is unavailable: fix sequentially in place.
 
-**Degradation:** missing, malformed, or ID-less `Parallel-safe:` line, or no `disjoint` group with ≥ 2 IDs → fully sequential fixes. Degradation is silent — it costs parallelism, never correctness.
+Grammar (identical across producers, modulo id prefix — `F` for code/spec reviewers, `G` for conformance-reviewer):
+
+```text
+<group> = <comma-separated id list> " disjoint"
+        | <id> " conflicts " <id> " (" <reason> ")"
+```
+
+**Structural probe:** when the report carries >= 2 actionable finding IDs (Critical/Moderate findings for code-reviewer; PARTIAL/MISSING/scope-creep findings for spec-reviewer; non-DELIVERED gaps for conformance-reviewer), validate the certificate before the fan-out decision: the review must contain **exactly one** line matching `^Parallel-safe: ` whose remainder parses as `<group>[; <group>]*` (grammar above). Zero matching lines, an unparseable remainder, or **any second** `Parallel-safe:` line (identical or not) = malformed -> re-ask the reviewer **once**, quoting the expected grammar, before any disposition or fan-out decision. Still malformed after the re-ask -> fully sequential fixes with an explicit one-line degradation notice in the orchestrator's visible output — never silent. A probe-passing line with no >= 2-ID `disjoint` group is **valid**: sequential fixes, no re-ask, no notice (the certificate says "serial", not a malformation). Fewer than 2 actionable IDs -> skip the probe (nothing to fan out). Reviewer errors (no report at all) are out of scope here — report-shape validation, not report-existence; existing dispatch-failure handling applies.
 
 **After the fix wave:** integrate patches serially per "Review and Integrate" above (mis-partition is self-healing: integrate the successes, re-run the conflicting finding sequentially on integrated HEAD); run the consuming loop's scoped test gate on the integrated tree; then one re-review of the integrated fix delta, per the consuming loop's own rules. The fan-out counts as one fix round against the consuming loop's budget — it grants no extra rounds.
 

package/skills/linear/SKILL.md

@@ -21,8 +21,10 @@ this skill alters re-gates.
 
 ## 1. Setup
 
-Mandatory: `linearis` on PATH and authenticated (`linearis auth status`). Token
-resolution order: `--api-token`, `LINEAR_API_TOKEN`, `~/.linearis/token`.
+Preferred: `linearis` on PATH and authenticated (`linearis auth status`). Token
+resolution order: `--api-token`, `LINEAR_API_TOKEN`, `~/.linearis/token`. This is a
+preference, not a precondition - a missing or unauthenticated CLI degrades Linear
+functionality and is reported, never blocks the run.
 
 > **No `linearis` installed?** If `command -v linearis` fails, fall back to a
 > **Linear MCP server** when the harness has one configured - its tools cover the
@@ -32,7 +34,20 @@ resolution order: `--api-token`, `LINEAR_API_TOKEN`, `~/.linearis/token`.
 > examples below are then guidance for the equivalent MCP call, not literal
 > shell. pi-gauntlet ships no MCP setup; MCP is opportunistic.
 
-No `linearis` and no MCP: report inability, never fabricate.
+No `linearis` and no MCP: report inability, never fabricate. MCP is the fallback for a
+**missing binary only** (`command -v linearis` fails); an installed-but-unauthenticated
+`linearis` re-auths rather than rerouting to MCP.
+
+**Session sweep.** When `linearis` is present and authenticated, run
+`linearis issues usage` once per session, before the first issue operation, and treat
+its output as ground truth for the **issue-domain rows** of the section 3 table (Read,
+Search, List, Create, Update, Discuss, Reply, Edit). Non-issue domains such as labels,
+teams, users, cycles, projects, attachments, files are outside this call's coverage and
+fall to the section 8 backstop, same as any row the sweep didn't run or couldn't reach.
+If the call errors, returns nothing, or the MCP path is in use, note once that the
+issue-domain rows are unverified this session and continue. The sweep lives inside this
+branch only - strictly after the override check above - so
+`tracker: github | none | <unknown>` still means zero probing.
 
 Optional: each `## Issue tracker` override key below, with its degradation.
 
@@ -87,43 +102,50 @@ treated as absent.
 | Create | `linearis issues create "<title>" --team <default team> [--parent-ticket <id>] --status <status>` | Title is positional (no `--title`); `--team` required; `--parent-ticket` for sub-issues; state an explicit `--status` rather than relying on the default. |
 | Update | `linearis issues update <id> --status <status> --assignee <who> --labels <labels> --due-date <date> [relation flags]` | See gotcha (e) for relation flags. |
 | Discuss | `linearis issues discuss <id> --body "<text>"` | Starts a new top-level comment thread. |
-| Reply | `linearis issues reply <id> --body "<text>"` | Root comments only - see gotcha (b). |
-| Edit | `linearis issues comment-edit <id> --body "<text>"` / `linearis issues edit-reply <id> --body "<text>"` | Full rewrite, no history - see gotcha (a). |
+| Reply | `linearis issues reply <thread> --body "<text>"` | `<thread>` is a root discussion thread ID, not an issue ID - see gotcha (b). |
+| Edit | `linearis issues edit <comment> --body "<text>"` / `linearis issues edit-reply <reply> --body "<text>"` | Full rewrite, no history - see gotcha (a). |
 | Labels, teams, users, cycles | `linearis labels list`, `linearis teams list`, `linearis users list`, `linearis cycles list` | Use to resolve names to IDs; see id-cache convention. |
-| Attachments | `linearis attachments create <id> --url <url>` | Link-only, no inline render - see gotcha (d). |
-| Upload | `linearis files upload <path>` | Returns an `assetUrl` for inline embedding - see gotcha (d). |
+| Attachments | `linearis attachments create [<issue>] --url <url>` | Positional is optional (`--issue <issue>` alias); link-only, no inline render - see gotcha (d). |
+| Upload | `linearis files upload <file>` | Returns an `assetUrl` for inline embedding - see gotcha (d). |
 
 Workspace values above (`<default team>`, `<who>`, etc.) are placeholders bound to
 the override keys in section 2 - never a real urlKey, team prefix, or email.
 
+Snapshot verified against `linearis 2026.7.0` (2026-09-01). The installed CLI's
+`usage`/`--help` is ground truth; when they disagree, follow the CLI and tell the user
+this table is stale.
+
 ## 4. Gotchas
 
 a. **Comment edit is a rewrite, no visible history.** To amend rather than replace,
    fetch the old body and pass `OLD + "\n\n" + ADDITION`; surface the overwrite diff
    to the user before pushing.
 
-b. **`reply` targets must be root comments** (`parentId: null`). A non-root target
-   fails with a misleading validation error. To respond in-thread, resolve the
-   thread's root via `discussions`/`--with-comment-threads` and `reply` to that
-   root, or start a new `discuss` thread instead. `edit-reply` is NOT a reply
-   fallback - it rewrites an existing reply. Use it only for an explicitly
-   requested edit of the caller's own reply, behind the rewrite-confirmation rule
-   in (a).
+b. **`reply` targets must be root discussion threads.** `--help`: "`<thread>` must be a
+   root discussion thread ID." A non-root target fails with a misleading validation
+   error. To respond in-thread, resolve the thread's root via
+   `discussions`/`--with-comment-threads` and `reply` to that root, or start a new
+   `discuss` thread instead. `edit-reply` is NOT a reply fallback - it rewrites an
+   existing reply. Use it only for an explicitly requested edit of the caller's own
+   reply, behind the rewrite-confirmation rule in (a).
 
 c. **`@ABC-123` never resolves via the CLI/API.** Use the full issue URL
    `https://linear.app/<workspace urlKey>/issue/<id>`, which unfurls to a native
    badge and records a relation. A literal `@ID` in a body stays literal text.
 
-d. **Images go inline, links don't render.** `linearis files upload <path>` ->
+d. **Images go inline, links don't render.** `linearis files upload <file>` ->
    `![alt](<assetUrl>)` in the body embeds the image. `attachments create` only
    links a URL and renders no image. Asset URLs returned by a `read` are
    short-lived signed JWTs - re-upload for a fresh one, never re-paste an old one.
 
-e. **Relation flags are single-value.** `--blocks`, `--blocked-by`, `--relates-to`,
-   `--duplicate-of` on `create`/`update` keep only the last value if repeated in one
-   call. For multiple relations in one call, use
-   `linearis issues relations add <id>` with its comma-separated flags; otherwise
-   issue separate `update` calls.
+e. **Two different relation flag sets.** On `create`/`update`: `--blocks`,
+   `--blocked-by`, `--relates-to`, `--duplicate-of`, `--similar-to`, plus
+   `--remove-relation` on `update`. These are single-value - repeating one in a single
+   call keeps only the last value (observed behavior, not stated by `--help`). On
+   `linearis issues relations add <issue>` the set is smaller and comma-separated:
+   `--blocks`, `--related`, `--duplicate`, `--similar` - there is **no** `--blocked-by`,
+   so express that direction by inverting the relation or using `update`. For multiple
+   relations in one call use `relations add`; otherwise issue separate `update` calls.
 
 f. **`create`'s title is positional.** There is no `--title` flag.
 
@@ -173,9 +195,16 @@ Safety rules, in addition to the write gate above:
 | Missing `--team` error on create | `--team` is required | Supply `--team <default team>`. |
 | Search returns nothing unexpected | Search is case-sensitive | Retry with matching case. |
 | Cannot edit a comment | Comment belongs to another user | Reply instead of editing. |
-| Reply validation error | Target is not a root comment | See gotcha (b). |
+| Reply validation error | Target is not a root discussion thread | See gotcha (b). |
 | `@ID` shows as literal text | `@ABC-123` mentions don't resolve | Use the full issue URL (gotcha c). |
 | Read is slow | Big ticket with many comments/attachments | Drop `--with-*` flags not needed. |
+| Parser-shape failure on a documented invocation: unknown command/option, unexpected argument | Section 3's snapshot may have drifted from the installed CLI | Re-read that subcommand's `--help`; report the row stale **only if** help actually contradicts it, then follow help |
+
+The last row's trigger is deliberately narrow. Data, auth, status-name, and root-thread
+validation errors have their own rows above and are **not** drift - routing them to "the
+skill is stale" would misdiagnose ordinary failures. This row is the reactive path for
+when the section 1 session sweep didn't run, couldn't run, or doesn't cover the failing
+subcommand (any row outside the `issues` domain).
 
 ## 9. Discovery pointers
 

package/skills/requesting-code-review/SKILL.md

@@ -57,7 +57,7 @@ subagent({ agent: "code-reviewer", task: "... filled template ..." })
 - Note Minor issues for later
 - Push back if reviewer is wrong (with reasoning)
 
-**Fix rounds.** Critical and Moderate findings trigger a fix round; when dispatched from an orchestrating skill, fixes go to `implementer` subagents (per the orchestrator's no-self-coding rule), fanned out per `dispatching-parallel-agents` "Fix fan-out" when the review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings. After integration and the project's test command, re-dispatch the reviewer once on the integrated delta. If Critical or Moderate findings remain, run one more fix round and one more re-review; still failing → escalate to the user. Minor findings never trigger the fan-out.
+**Fix rounds.** Critical and Moderate findings trigger a fix round; when dispatched from an orchestrating skill, fixes go to `implementer` subagents (per the orchestrator's no-self-coding rule), fanned out per `dispatching-parallel-agents` "Fix fan-out" when the review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings. Before fanning out, validate the review's `Parallel-safe:` line with the structural probe in `dispatching-parallel-agents` § Fix fan-out (exactly-one-line grammar check, one re-ask, then explicit sequential fallback). After integration and the project's test command, re-dispatch the reviewer once on the integrated delta. If Critical or Moderate findings remain, run one more fix round and one more re-review; still failing → escalate to the user. Minor findings never trigger the fan-out.
 
 ## Example
 

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

@@ -243,7 +243,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - Skipping the `Implementer Status` parse — treating every response as DONE
 - Starting on main without explicit user consent
 - Dispatching `code-reviewer` before every one of the wave's spec-review verdicts has landed (including fusing SR+CR into one parallel call)
-- Dispatching fixes sequentially on a clean HEAD despite a ≥ 2-ID `disjoint` group in the review's `Parallel-safe:` line
+- Dispatching fixes sequentially on a clean HEAD despite a certified (probe-passing, per dispatching-parallel-agents § Fix fan-out) ≥ 2-ID `disjoint` group in the review's `Parallel-safe:` line
 - Dispatching `code-reviewer` per task inside a wave (CR binds to the integrated wave diff)
 - Dispatching an implementer or code-reviewer without a `SCOPED_TEST_COMMANDS` value (commands or `none`)
 - About to run the full verification entrypoint during the implement phase — task and wave gates run scoped, plan-declared commands only; the full set belongs to verify

package/skills/writing-plans/SKILL.md

@@ -290,19 +290,16 @@ If a decision is genuinely open, put it in an explicit **Open Questions** sectio
 
 ## Self-Review (Before Handoff)
 
-After drafting the plan and before announcing it complete, run these checks yourself. This is a checklist you run yourself — not a subagent dispatch.
+After drafting the plan and before announcing it complete, run the deterministic checker, then the judgment checks yourself — not a subagent dispatch.
 
-- **Table closure (three legs).** Every `## Spec coverage` row's owner is a task-ID list, a spec-authorized `waived: <reason>`, or a mechanical-task row; every `### Task N` heading appears in >=1 row; every requirement row's anchor is contained in the anchor set of each listed owner task's `**Spec:**` line. Zero orphans, zero waived in-scope normative rows, zero row-vs-owner anchor mismatches. Each Documentation impact entry maps to a plan task (or explicit "none").
+- **Deterministic checker.** Run `plan_check({ planPath })` on the saved plan. Assess and fix every finding yourself (no human involvement), then re-run until it passes — a pass writes the execution stamp that implement-start verifies mechanically. If the same finding survives 3 fix rounds, convert it to an explicit Open Question and stop (the pre-existing Open-Questions halt, resolved by the human in-session — not a new gate). The checker covers table closure, quote integrity, anchor resolution, path existence, placeholder scan, wave file-disjointness, solo-line presence, and header-only entrypoint.
 - **Code-vs-anchor sanity.** For each non-waived requirement row, re-read the anchored spec lines and confirm the owner tasks' bodies do what they say - mechanism present, not just the quoted literal. Fix the task, don't annotate.
-- **Quote integrity (spec -> task).** For every non-waived requirement row, extract each backtick-quoted literal inside the row's anchored spec lines (strip the backticks; skip `<placeholder>` template spans) and `grep -F` it against the owning task's body — zero misses. Planner-authored backticks elsewhere in tasks are never scanned; the input set is spec-side literals only.
-- **Anchor resolution.** For every task-level anchor (a `**Spec:**` line carrying `§`; the plan header's path line is exempt), the quoted heading text matches an ATX heading in the spec file and `L<start>-L<end>` is in-bounds, non-empty, and lies within that heading's section — zero unresolved anchors. Verify with `grep -n '^#'` plus a scoped `sed -n`. Ignore `#`-lines inside fenced code blocks when locating headings and section boundaries - a fenced markdown example is not a heading.
-- **Paths exist.** Every `Modify:` path in `Files:` blocks passes `test -f` after stripping any trailing `:line[-line]` suffix; a `Modify:` glob must expand to >=1 match; `Create:` and `Test:` paths are exempt unless the `Test:` path is also listed under `Modify:`. Zero missing.
-- **Placeholder scan.** Grep the doc for `TODO`, `TBD`, `xxx`, `[fill in]`, `<example>`, `etc.`, "probably", "something like". Resolve or convert each into an explicit Open Question.
 - **Type / API consistency.** Function signatures and field names that appear in multiple tasks must match exactly. The plan is its own contract — internal contradictions surface as bugs during execution.
-- **Wave disjointness.** For every multi-task wave, confirm the tasks' `Files:` sets are pairwise disjoint **and** that no two tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path). Either kind of overlap = mis-grouped wave; split or re-order before handoff.
-- **Solo-wave justification.** Every single-task wave carries a `Solo:` line naming its specific blocker. A solo wave without one is mis-grouped or under-justified — merge it or justify it before handoff.
 - **Scoped-test coverage.** Every code-touching wave declares at least one scoped test command; only doc-only waves may have none.
-- **Header-only entrypoint.** The full verification entrypoint appears only in the plan header's `**Verification:**` line. Grep the task body for the header's command string — expect zero hits.
+- **Runtime-resource disjointness.** For every multi-task wave, confirm no two tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path) — `Files:` overlap is checked mechanically, resource contention is not. Contention = mis-grouped wave; split or re-order before handoff.
+- **Solo-reason validity.** Every single-task wave's `Solo:` line (presence is checked mechanically) must name its specific blocker — the blocking task/wave, the contended resource, or `lone remaining task`. Category-only justifications are under-justified; merge or justify before handoff.
+- **Waiver authorization.** Every `waived: <reason>` owner in `## Spec coverage` is authorized by the spec itself marking the item out of scope. A waiver on an in-scope normative requirement is a Self-Review failure — there is no human plan-review gate to catch it downstream.
+- **Documentation-impact mapping.** Each Documentation impact entry maps to a plan task (or explicit "none").
 
 Fix what this review finds before handoff.