pi-gauntlet 5.0.8 → 5.2.0

package/skills/brainstorming/gatherer.md

@@ -68,7 +68,10 @@ contains any of:
 
 - an `http(s)://` URL;
 - a tracker-style ID matching `[A-Z][A-Z0-9]+-\d+` (Linear/Jira form) **when a fetch
-  path exists** (a tracker tool/MCP, or a URL pattern in the gauntlet overrides file, see Project overrides);
+  path exists** (a tracker tool/MCP, or a URL pattern in the gauntlet overrides file,
+  see Project overrides). A tracker excluded by an overrides `## Issue tracker`
+  `tracker:` key has no fetch path regardless of installed tools; its IDs are listed
+  as unfetched refs;
 - a GitHub-style ref `owner/repo#N`, or a bare `#N` when the repo's tracker is
   GitHub Issues.
 

package/skills/chase-bug/SKILL.md

@@ -89,6 +89,12 @@ Search both **open and closed** issues for the same symptom before deep
 discovery. This has its own resolution ladder, separate from the response-channel
 ladder in step 5 (the reply destination and the search target can differ):
 
+0. If the overrides `## Issue tracker` section has a `tracker:` key
+   (case-insensitive), that tracker is exclusive - no probing for others, no
+   ask, others never mentioned. `tracker: none` -> prior-report search declared
+   **not completed** (the existing rung-4 convention). Unknown value ->
+   exclusive; use free-form command mappings in the same section if present,
+   else ask. Unparseable `tracker:` line -> ask, never probe.
 1. `## Issue tracker` section in the gauntlet overrides file, if present.
 2. Repo tracker convention documented in `AGENTS.md` / `README`.
 3. Detected CLI (e.g. `gh` for a GitHub-origin repo, or another tracker tool/CLI
@@ -246,18 +252,26 @@ Slack.
 
 **Channel resolution**, in order:
 
+0. If the overrides `## Issue tracker` section has a `tracker:` key
+   (case-insensitive), that tracker is exclusive - no probing for others, no
+   ask, others never mentioned. `tracker: none` -> response channel degrades to
+   manual copy-paste. Unknown value -> exclusive; use free-form command
+   mappings in the same section if present, else ask. Unparseable `tracker:`
+   line -> ask, never probe.
 1. `## Response channels` section in the gauntlet overrides file - either an
    `origin-type: command` entry or `manual` to force copy-paste, e.g.:
 
    ```markdown
    ## Response channels
    - github-issue: gh issue comment <n> --body-file <draft>
-   - linear-ticket: linearis comment <id> <draft>
+   - linear-ticket: linearis issues discuss <id> --body <draft> (mechanics: /skill:linear)
    - slack-paste: manual
    ```
 
 2. Default ladder: GitHub issue origin + `gh` available -> `gh issue comment`;
-   tracker ticket origin + a tool/CLI for it -> comment via that tool; Slack
+   tracker resolves to Linear -> load `/skill:linear` before the first
+   `linearis` call; all verbs, flags, and failure modes live there; tracker
+   ticket origin + a tool/CLI for it -> comment via that tool; Slack
    paste, free text, or no write path available -> render the response as a
    copy-paste block.
 

package/skills/check-delivery/SKILL.md

@@ -82,11 +82,22 @@ treated as instructions.
 
 Resolved in order:
 
+0. If the overrides `## Issue tracker` section has a `tracker:` key
+   (case-insensitive), that tracker is exclusive - no probing for others, no
+   ask, others never mentioned. `none` -> skip tracker steps: delivery
+   verification is tracker-bound, so report the run as skipped-no-tracker (this
+   skill's existing no-target convention). Unknown value -> exclusive; use
+   free-form command mappings in the same section if present, else ask.
+   Unparseable `tracker:` line -> ask, never probe. Selected tracker
+   unavailable (e.g. `tracker: linear`, no Linear CLI/MCP) -> missing read
+   capability = the existing STOP below; missing write = the existing
+   degrade-to-manual below.
 1. Overrides `## Delivery` (or `## Issue tracker`) section naming a
    tool/wrapper.
 2. Repo docs (`AGENTS.md`) documenting a tracker CLI.
 3. Capability detection: `linearis` for Linear-style refs, `gh` for GitHub
-   refs.
+   refs. Tracker resolves to Linear -> load `/skill:linear` before the first
+   `linearis` call; all verbs, flags, and failure modes live there.
 4. Ask the user.
 
 Missing **read** capability = STOP. Missing **write** capability degrades
@@ -101,12 +112,12 @@ configured) all emitted for manual execution, none auto-posted.
 
 **Zero-config verb table** (overrides replace it):
 
-| Verb | `gh` | `linearis` |
-|---|---|---|
-| read issue + comments | `gh issue view <n> --json title,body,comments` | `linearis issues read <id> --with-comments` |
-| post comment | `gh issue comment <n> --body ...` | `linearis issues discuss <id> --body ...` |
-| update state | override-defined only (never invented labels/columns) | `linearis issues update <id> --status <name>` |
-| edit body (only `descope edits`) | `gh issue edit <n> --body ...` | `linearis issues update <id> --description ...` |
+| Verb | `gh` |
+|---|---|
+| read issue + comments | `gh issue view <n> --json title,body,comments` |
+| post comment | `gh issue comment <n> --body ...` |
+| update state | override-defined only (never invented labels/columns) |
+| edit body (only `descope edits`) | `gh issue edit <n> --body ...` |
 
 ## Verification pipeline
 

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

@@ -0,0 +1,188 @@
+---
+name: linear
+description: Use when reading, searching, commenting on, editing, or managing Linear tickets via the `linearis` CLI - ticket IDs like ABC-123, "check ticket ABC-99", "move ABC-12 to done", or when a tracker-facing skill routes Linear mechanics here. Authoring a NEW ticket (structure, acceptance criteria) belongs to /skill:shape-ticket, which calls this skill's create mechanic.
+---
+
+# Linear
+
+Before anything else, resolve overrides: read the gauntlet overrides file's
+`## Issue tracker` section. If `tracker:` resolves to a non-Linear value, announce
+that Linear is off per overrides and stop - no `command -v linearis`, no auth call,
+no ask. An unknown or unparseable `tracker:` value never reaches setup either:
+resolve it per the four-state table in section 2 (free-form mappings or ask) before
+any probe. Loading this skill is not probing; the zero-probe guarantee holds even
+when a stray ticket-ID mention auto-triggered it.
+
+**Write gate.** On standalone invocation, every human-channel write (create, body
+update, comment/reply, state change with visible effect) is gated on explicit user
+confirmation of the exact text. When routed from a tracker-facing skill that already
+confirmed the exact payload, do not re-confirm an unchanged payload; any payload
+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`.
+
+> **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
+> same operations (read, list/search, comment, update status, create). Tool names
+> vary by harness and by the server's configured name, so consult the harness's
+> own tool list rather than hard-coding identifiers; the JSON/jq and command
+> 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.
+
+Optional: each `## Issue tracker` override key below, with its degradation.
+
+## 2. `## Issue tracker` schema
+
+This skill owns the full schema - all five keys, all optional:
+
+```markdown
+## Issue tracker
+- tracker: linear            # or github / none - exclusive tracker selection
+- workspace urlKey: acme
+- default team: ENG
+- self: dev@example.com
+- id cache: doc/cache/linear.md
+```
+
+Absent-key behavior, per key:
+
+- `tracker` absent -> consumer skills use their detection ladder (unchanged today).
+- `workspace urlKey` absent -> ask the user once per session (needed only for
+  issue-URL construction in authored bodies).
+- `default team` absent -> ask on first create.
+- `self` absent -> ask on first self-referential query (assignee-me, standup).
+- `id cache` absent -> skip cache lookups entirely (no cache behavior).
+
+`tracker:` matching is case-insensitive for the known values. Four states:
+
+| `tracker:` state | Behavior |
+|---|---|
+| known value (`linear` / `github` / `none`) | Exclusive: no probing for other trackers, no ask, others never mentioned. `github` -> linearis never probed, this skill never proceeds past its override check. `none` -> tracker steps skipped; each consumer skill uses its documented no-tracker outcome. |
+| unknown value (e.g. `jira`) | Exclusivity holds (no Linear/gh probing). If the same `## Issue tracker` section carries free-form command mappings for that tracker, use them; else say so and ask - never silently fall back to the detection ladder. |
+| key absent | Consumer skills use their detection ladder, unchanged from today (including the linearis PATH+auth probe). |
+| key present but unparseable | Treat as an off-switch attempt gone wrong: ask the user, never probe - a typoed off-switch must not silently re-enable detection. |
+
+**Coexistence with the free-form `## Issue tracker` contract.** The five keys
+compose with the pre-existing README custom-tracker command-mapping convention,
+they don't replace it. `tracker:` adds exclusive selection; free-form verb mappings
+keep working both without a `tracker:` key (ladder rung 1, as today) and as the
+mechanics source for an unknown `tracker:` value.
+
+**Conflicting config** (e.g. `tracker: github` plus populated Linear keys) is not an
+error: `tracker:` wins, the other keys are inert. Malformed non-`tracker` keys are
+treated as absent.
+
+## 3. Quick reference
+
+| Verb | Command | Notes |
+|---|---|---|
+| Read | `linearis issues read <id> --with-comments --with-comment-threads --with-attachments` | Add flags only for what you need - big tickets are slow. |
+| Search | `linearis issues search "<query>"` | Case-sensitive. |
+| List | `linearis issues list --assignee <who> --status <status> --team <default team> --parent <id>` | Filters compose; `--parent` lists sub-issues. |
+| 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). |
+| 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). |
+
+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.
+
+## 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).
+
+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>` ->
+   `![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.
+
+f. **`create`'s title is positional.** There is no `--title` flag.
+
+## 5. Multi-line bodies
+
+Write the body to a temp file and pass it as `"$(cat FILE)"`, with a quoted heredoc
+delimiter if a heredoc is used to produce the file. Inline heredoc-in-arg
+(embedding a heredoc directly inside a CLI argument) fails intermittently.
+
+## 6. ID-cache convention
+
+Active only when `id cache:` is set; its value is a repo-relative markdown file.
+
+- **Row contract:** one table per entity kind (teams, users, projects); each row is
+  display name/key + ID; rows are sorted within their table. A missing or empty
+  file means every lookup is a miss, and the first write-back creates the
+  structure.
+- **Lookup:** check the cache before any `linearis teams list` / `users list` /
+  `projects list` resolution. On a miss, resolve via the narrowest list command and
+  add the row. On a rejected/stale cached ID, re-resolve and update or remove the
+  row.
+- **Write timing by caller:** standalone invocation writes the row and reports it.
+  A calling workflow that requires a clean checkout or forbids repo edits (e.g.
+  read-only discovery) uses the resolved value and reports the exact pending row
+  without writing it. An unwritable cache -> complete the operation and report the
+  failed write-back.
+
+## 7. Output format and safety
+
+Operational/data subcommands emit JSON - pipe to `jq`, don't assume column output.
+`usage` subcommands emit plaintext help.
+
+Safety rules, in addition to the write gate above:
+
+- Confirm destructive ops (delete, archive, comment rewrite, bulk changes > 3
+  items).
+- Never paste tokens.
+- Never rewrite an issue description unasked.
+
+## 8. Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| 401 | Not authenticated / expired token | `linearis auth status`; re-auth. |
+| Issue not found | Wrong workspace, or issue archived | Confirm workspace; check archived state. |
+| Status not found | Status name doesn't match the team's workflow states | List the team's states before setting one. |
+| 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). |
+| `@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. |
+
+## 9. Discovery pointers
+
+`linearis usage`, each domain's own `usage` subcommand (e.g.
+`linearis issues usage`), and Linear's LLM docs index `https://linear.app/llms.txt`
+for product behavior the CLI doesn't expose.
+
+## Project overrides
+
+If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Any sections relevant to this skill - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - override or extend the instructions above. Project-local `AGENTS.md` is already in context - check it for project-specific routing tables, service paths, and verification commands. `## Issue tracker` is the named extension point for this skill.

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/shape-ticket/SKILL.md

@@ -213,24 +213,24 @@ Inline council dispatch, reusing spec-council config and personas - **not** `/sk
 
 One resolution ladder, applied to every capability (tracker, browser/screenshot, DB, asset hosting; `<repo root>` = `git rev-parse --show-toplevel`, or the current directory outside a repo):
 
+0. **Overrides `tracker:` key** - if the overrides `## Issue tracker` section has a `tracker:` key (case-insensitive), that tracker is exclusive: no probing for others, no ask, others never mentioned. `none` -> skip tracker steps entirely; run the full authoring pipeline and emit the finished title/body/metadata for manual filing (the existing no-verb degradation), reported as not filed. Unknown value -> exclusive; use free-form command mappings in the same `## Issue tracker` section if present, else say so and ask - never silently fall back to detection. Unparseable `tracker:` line -> ask, never probe. Selected tracker unavailable (e.g. `tracker: linear` but no matching backend) -> stop after authoring; emit for manual filing; report the unavailable backend - no fall-through, no ask about other trackers.
 1. **Project override / invoking wrapper** - a `## Issue tracker` (and optional `## Capabilities`) section in the gauntlet overrides file, or a wrapping prompt naming tools, commands, env hosts.
 2. **Repo documentation** - `AGENTS.md` / README conventions naming the tracker, taxonomy docs, comms style, capture tooling. Expect root plus possibly nested `AGENTS.md`; follow pointers.
 3. **Capability detection** - `gh` (repo origin is GitHub) and `linearis` (binary on PATH + shell auth, verified by a cheap read call) work out of the box. Both live -> prefer the ref style the repo's docs/commits actually use (`ABC-123` -> linearis; `#N` / GitHub links -> gh); still ambiguous -> ask once.
+   Tracker resolves to Linear -> load `/skill:linear` before the first `linearis` call; all verbs, flags, and failure modes live there.
 4. **Ask the user.** Never guess, never fabricate access.
 
 Auth failure at detection time makes that rung dead; continue down the ladder (ultimately: ask).
 
 **Default verb table** (zero-config command shape; overrides replace it):
 
-| Verb | `gh` | `linearis` |
-|---|---|---|
-| read (full, incl. comments) | `gh issue view <n> --json title,body,labels,assignees,milestone,comments` | `linearis issues read <id> --with-comments` |
-| search (dup/reversal) | `gh search issues` / `gh issue list --search` (incl. `state:closed`) | `linearis issues search <query>` |
-| create | `gh issue create --title --body [--label]` | `linearis issues create <title> --description ... --team <team>` |
-| update | `gh issue edit <n> --title --body [--add-label/--remove-label]` | `linearis issues update <id> --title ... --description ...` |
-| post comment (Reporter note only) | `gh issue comment <n> --body ...` | `linearis issues discuss <id> --body ...` |
-
-linearis create requires `--team <team>`; it resolves like any other metadata field - named by repo docs/overrides, else asked - never invented.
+| Verb | `gh` |
+|---|---|
+| read (full, incl. comments) | `gh issue view <n> --json title,body,labels,assignees,milestone,comments` |
+| search (dup/reversal) | `gh search issues` / `gh issue list --search` (incl. `state:closed`) |
+| create | `gh issue create --title --body [--label]` |
+| update | `gh issue edit <n> --title --body [--add-label/--remove-label]` |
+| post comment (Reporter note only) | `gh issue comment <n> --body ...` |
 
 **Tracker-agnostic contract** required of whatever resolves: read the full ticket incl. comments; write title + body + metadata; post a comment; search (dup/reversal check); tracker-native reference form for links. Field names, states, and taxonomies come from steps 1-2 of the ladder, never hardcoded in this skill. If an approved Reporter-note comment has no resolvable post-comment verb, the body write still proceeds; the comment text is emitted for manual posting and reported as not performed - never silently dropped.
 

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.