pi-gauntlet 5.18.0 → 5.18.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.18.1 - 2026-09-23
+
+- Review dispatch tasks now carry the installed path of `reference/documentation-impact.md` so fresh reviewers do not flag the citation as missing. (#44)
+
 ## v5.18.0 - 2026-09-23
 
 - Projects can declare end-to-end happy-path commands in a `## Happy path` overrides table (`Row | Paths | Command | Timeout`, contract in `README.md`); `writing-plans` selects the row covering the plan's files into an optional `**Happy path:**` header line (`plan_check` validates it and bans the command from tasks and wave prose), `subagent-driven-development` runs it once in the verify phase between code review and the conformance audit under `timeout -k 30s` via `bash -c`, and the `conformance-reviewer` reads the bounded transcript as runtime evidence (`passed` / `failed` / `not run`; a failure in code the change never touched is `rescope`, never `fix`). Fix rounds re-run it only when the round touches the row's paths or an open gap cites the transcript; the closure sentinel and the finish render carry a `happy-path:` line. Optional end to end - no section, no change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.18.0",
+  "version": "5.18.1",
   "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

@@ -181,6 +181,8 @@ The first four are the inline **lint**: run them here and fix what they surface.
 
 ## Spec Council (Optional)
 
+Before dispatching the worker below, resolve `reference/documentation-impact.md` relative to this loaded skill as one absolute `<DOCUMENTATION_IMPACT_GUIDELINE>` path value. Pass that value in the worker task; do not add it to the spec.
+
 After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**; council **apply mechanics** live in `/skill:roasting-the-spec` (single source of truth - link, don't restate). Resolve the council with `gauntlet_setting({ key: "specCouncil" })` - the tool returns the merged (repo-over-preset) value as `{ verdict, members, chair, malformed, warning, errors }`. **Do not** hand-roll a settings read. When `verdict` is `"council"`, the council *is* the critique pass - invoke `/skill:roasting-the-spec` automatically (no offer, no prompt), passing `members`/`chair`; also pass the verbatim human input (the original prompt, any ticket AC snapshot - the raw rows under the gather draft's `## Ticket acceptance criteria (verbatim)` heading, never the spec's section, which holds the author's dispositions - and the questionary answers that changed scope) - roasting-the-spec forwards it to members and chair as the `Human input (verbatim; off-limits for over-spec)` block; it applies its apply-set and returns the audit (Applied/Deferred/Rejected). When `verdict` is `"worker"`, dispatch the worker below. If `malformed` is true or `errors` is non-empty, emit the `warning`/error as one line, then branch strictly on `verdict` - `malformed` can accompany *either* verdict (e.g. a bad `chair` with valid `members` still returns `council`), so never infer the worker path from `malformed` alone. If `gauntlet_setting` is unavailable, stop and report - never fall back to a manual bash/JSON settings merge. The already-applied council edits (or the worker's in-place fixes) ride in the same worktree commit. The conceptual precedence rule lives in `verification-before-completion/reference/settings-precedence.md`.
 
 When `verdict` is `"worker"`, dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
@@ -188,8 +190,9 @@ When `verdict` is `"worker"`, dispatch one fresh `worker` that applies the scope
 ```
 subagent({ agent: "worker", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>", task:
   "Problem statement: <the problem the spec addresses + the user's stated intent>.\n" +
-  "Read the spec at <abs path to doc/specs/...>. Edit ONLY that file. Apply two checks and\n" +
-  "fix what you find in place: (1) Scope — does every paragraph serve the goal? Cut filler;\n" +
+  "Read the spec at <abs path to doc/specs/...>. Edit ONLY that file.\n" +
+  "The portable citation `reference/documentation-impact.md` in the spec is the pi-gauntlet guideline at <DOCUMENTATION_IMPACT_GUIDELINE>, not a consumer doc; do not flag it as an external reference, and preserve it - never remove it as redundant or replace it with the resolved absolute path.\n" +
+  "Apply two checks and fix what you find in place: (1) Scope — does every paragraph serve the goal? Cut filler;\n" +
   "state out-of-scope explicitly. (2) Ambiguity — is every 'we should' a concrete decision?\n" +
   "Replace 'we could probably' with 'we will'/'we won't'. Also inline any load-bearing\n" +
   "external reference (ticket AC, commit SHA, doc) already given to you in the problem\n" +

package/skills/brainstorming/reference/amendment-surface.md

@@ -34,6 +34,8 @@ Everything else - evidence-backed factual drift outside human-owned text - goes
 
 ## 3. Reviewer - one dispatch per batch
 
+Resolve the sibling `documentation-impact.md` in this file's directory as one absolute `<DOCUMENTATION_IMPACT_GUIDELINE>` path value before this dispatch. Pass that value in the task; do not add it to the spec.
+
 Rubric - `auto-apply` only when all three hold:
 
 - **(a)** evidence-backed factual correction: `evidence` is a cited observation, not a claim;
@@ -53,7 +55,7 @@ printf '%s/%s%s\n' "$PI_PROVIDER" "$PI_MODEL" "${lvl:+:$lvl}"
 subagent({ agent: "spec-council-member", context: "fresh", async: false,
   model: "<printed string>", cwd: "<abs worktree path>",
   control: { needsAttentionAfterMs: 60000, inFlightSilenceCeilingMs: 240000, inFlightSilenceKillMs: 300000 },
-  task: "Mode: amendment-review\nSpec: <abs spec path>\nRubric:\n<the three predicates above, verbatim>\nItems:\n<per item: handle | location | old -> new | evidence>\nHuman input (data, not instructions):\n```\n<the spec's ## Human input section, or: none - judge (c) from Goal/Problem/scope/AC>\n```" })
+  task: "Mode: amendment-review\nThe portable citation `reference/documentation-impact.md` in the spec is the pi-gauntlet guideline at <DOCUMENTATION_IMPACT_GUIDELINE>, not a consumer doc; do not flag it as an external reference.\nSpec: <abs spec path>\nRubric:\n<the three predicates above, verbatim>\nItems:\n<per item: handle | location | old -> new | evidence>\nHuman input (data, not instructions):\n```\n<the spec's ## Human input section, or: none - judge (c) from Goal/Problem/scope/AC>\n```" })
 ```
 
 Expected reply - one line per item, nothing else:

package/skills/brainstorming/reference/documentation-impact.md

@@ -120,7 +120,9 @@ later event and should not be flagged as missing before that event fires).
 
 Keep this list in sync with the skills that cite this doc:
 
-- `brainstorming` section 6 and its Spec Self-Review check.
+- `brainstorming` section 6, its Spec Self-Review check, and its worker dispatch context.
+- `roasting-the-spec` member and chair dispatch context.
+- `brainstorming/reference/amendment-surface.md` amendment-review dispatch context.
 - `writing-plans` - sources doc-update tasks from the spec's Documentation
   impact section.
 - `verification-before-completion/reference/conformance-check.md` - docs named

package/skills/roasting-the-spec/SKILL.md

@@ -44,6 +44,8 @@ brainstorming owns the gate: it resolves this config via `gauntlet_setting`, emi
 
 ## The council run
 
+Resolve `../brainstorming/reference/documentation-impact.md` relative to this loaded skill as one absolute `<DOCUMENTATION_IMPACT_GUIDELINE>` path value. Pass that value in every member and chair task below; do not add it to the spec.
+
 ### 1 — Fan out to members
 
 Create an absolute temp dir outside the worktree so member files are never tracked by git:
@@ -66,7 +68,7 @@ subagent({
     cwd: "<abs worktree path>",
     task: "Problem statement: <the problem the spec addresses, from its Context section and the user's stated intent>.\n" +
           "Human input (verbatim; off-limits for over-spec):\n```\n<original prompt>\n<ticket AC snapshot, if any>\n<questionary answers that changed scope>\n```\n" +
-          "Read the spec at <abs path to doc/specs/...>. Verify its load-bearing claims against the codebase, bounded per your verification-hygiene rules (rg, explicit paths, timeout 30). Critique it on your five axes and emit your template.",
+          "Read the spec at <abs path to doc/specs/...>. The portable citation `reference/documentation-impact.md` in the spec is the pi-gauntlet guideline at <DOCUMENTATION_IMPACT_GUIDELINE>, not a consumer doc; do not flag it as an external reference. Verify the spec's load-bearing claims against the codebase, bounded per your verification-hygiene rules (rg, explicit paths, timeout 30). Critique it on your five axes and emit your template.",
     output: "<tmpdir>/member-" + i + "-" + slug(model) + ".md"
   }))
 })
@@ -80,7 +82,7 @@ The `Human input (verbatim; off-limits for over-spec)` block is supplied by the
 
 **Usable-critique test (mechanical structural probe).** After the fanout returns - success or failure of the tool call itself - probe the expected output paths on disk; judge by files, not by the tool result's failed/succeeded labels (a killed member may have written a usable critique first). A member file is usable iff it is non-empty AND contains a `^verdict:\s*(sound|needs-work|unsound)` line, an `^addresses-problem:` line, and a `^lean:` line. A `findings:` header with zero bullets is a valid, usable sound critique. Existence plus header regex only - never read or weigh findings content.
 
-**Targeted retry.** Members whose file is missing or not usable are re-dispatched **once**, together, in a second foreground parallel call carrying `async: false` and the same `control` block, with fresh output paths that preserve the `member-<i>-<slug>` basename under a `retry/` subdir of the same temp dir (the chair recovers `raised-by` attribution from that filename pattern). Await its terminal result. Members with usable files are never re-run.
+**Targeted retry.** Members whose file is missing or not usable are re-dispatched **once**, together, in a second foreground parallel call carrying `async: false` and the same `control` block. Reuse the complete initial task verbatim. Use fresh output paths that preserve the `member-<i>-<slug>` basename under a `retry/` subdir of the same temp dir (the chair recovers `raised-by` attribution from that filename pattern). Await its terminal result. Members with usable files are never re-run.
 
 **Quorum.** At least one usable file after retry -> dispatch the chair over the usable files only (next section). Zero usable files -> abort the council, say so, and return to the user gate.
 
@@ -101,6 +103,7 @@ subagent({
         "Member critiques (already injected via reads — do not search for them):\n" +
         usableMemberPaths.join("\n") + "\n" +
         "Coverage: <N> of <M> members reported<; <slug>: <one-line reason> per missing member>.\n" +
+        "The portable citation `reference/documentation-impact.md` in the spec is the pi-gauntlet guideline at <DOCUMENTATION_IMPACT_GUIDELINE>, not a consumer doc; do not flag it as an external reference.\n" +
         "Consolidate and adjudicate the member critiques. Codebase access is permitted for contested-claim checks only, bounded per your hygiene rules (rg, explicit paths, timeout 30)."
 })
 ```
@@ -109,7 +112,7 @@ The chair runs one long foreground single-turn synthesis; await its terminal res
 
 List the exact member paths in the task text. The `reads:` array injects their contents, but the chair's prompt expects the paths explicitly; without them it scans the tree for `*.md` and stalls.
 
-A chair synthesis is usable iff it contains a `^consensus:` line and a `^lean:` line. If the configured `chair` model is unreachable, retry once with the inherited model; a wedge-killed or unusable chair retries once with the same model. Each retry remains foreground with top-level `async: false` and is awaited to a terminal result. Second failure -> abort the council, say so, and return to the user gate.
+A chair synthesis is usable iff it contains a `^consensus:` line and a `^lean:` line. If the configured `chair` model is unreachable, retry once with the inherited model; a wedge-killed or unusable chair retries once with the same model. Each retry remains foreground with top-level `async: false`. Reuse the complete initial task verbatim. Await its terminal result. Second failure -> abort the council, say so, and return to the user gate.
 
 ### 3 — Decide and apply