pi-gauntlet 5.5.0 → 5.5.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v5.5.2 - 2026-09-13
+
+- `release.sh <level>` promotes the CHANGELOG `## Unreleased` section to `## vX.Y.Z - <date>` and commits it with `package.json` in the single `Release X.Y.Z` commit, so `patch`/`minor`/`major` now work here (the `current`-only path is gone). New CONFIG field `CHANGELOG_HEADING`.
+- Release skill: a user instruction naming the level is the approval - no proposal step or re-confirmation; bundled follow-ups run after `verify`.
+- AGENTS.md rewritten to always-on essentials plus routing; shared core bumped to v3. Persona frontmatter knobs table and pin rationale moved to `doc/personas.md`. Gold rule scoped to agent-initiated writes; a user instruction naming the write is its confirmation.
+- Added `.pi/gauntlet-overrides.md` (`tracker: github`, release path, write-gate carve-out for user-named writes).
+- `verification-before-completion/reference/conformance-check.md`: the conformance fix round is one parallel `implementer` `tasks` wave (greedy `Gn` selection, `conflicts` partners held) -> `git apply` -> scoped tests -> delta re-audit. Per-gap `spec-reviewer`, per-round `code-reviewer`, and the per-round full test set are gone. New **Convergence** step after every `CONFORMS`: full `Verification` set once, one direct `code-reviewer` over `git diff <r0-head>..HEAD`; repairs re-enter the round as a `conformance fix CR` wave that counts against `maxFixRounds`. Finish grammar, personas, and settings unchanged.
+
+## v5.5.1 - 2026-09-10
+
+- `linear`: copyable, version-scoped recovery for attachment-download 401s resolves the decrypted credential through linearis instead of reading encrypted token storage. Restricts credential delivery to HTTPS Linear uploads, rejects redirects, and checks downloaded bytes; an offline regression executes the documented example.
+
 ## v5.5.0 - 2026-09-10
 
 - `writing-plans`: every task carries a `**Tests:**` block - scoped commands anchored to the task's `Test:` paths, optional `via:` entry point, or `none: <category>`; the plan grammar `plan_check` enforces moves to `skills/writing-plans/reference/plan-contract.md`. (#28)

package/package.json

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

package/skills/linear/SKILL.md

@@ -24,7 +24,9 @@ this skill alters re-gates.
 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.
+functionality and is reported, never blocks the run. The token file is encrypted
+storage: never use its contents as an HTTP credential or infer the credential type
+from its `v1:` storage-format prefix. Resolve it through linearis instead.
 
 > **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
@@ -192,7 +194,7 @@ Safety rules, in addition to the write gate above:
 | Symptom | Cause | Fix |
 |---|---|---|
 | 401 | Not authenticated / expired token | `linearis auth status`; re-auth - unless the download row below applies. |
-| 401 on `files download` while `issues read` works | linearis 2026.7.0 and 2026.8.0 prepend `Bearer ` to personal API keys on file downloads ([linearis-oss/linearis#300](https://github.com/linearis-oss/linearis/issues/300)) | Not an auth problem - do not re-auth. Fetch the URL with the bare key, or use a version without the bug once one ships. |
+| 401 on `files download` while `issues read` works | linearis 2026.7.0 and 2026.8.0 prepend `Bearer ` to personal API keys on file downloads ([linearis-oss/linearis#300](https://github.com/linearis-oss/linearis/issues/300)) | Not an auth problem - do not re-auth. Use the recovery below, or use a version without the bug once one ships. |
 | 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>`. |
@@ -203,6 +205,45 @@ Safety rules, in addition to the write gate above:
 | 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 |
 
+For that download-only 401, this 2026.7.0/2026.8.0 workaround calls linearis's
+version-specific internal `getApiToken` API. Supply the fresh `uploads.linear.app` URL
+from `issues read --with-attachments` and an output path. It rejects other hosts and
+redirects, sends the resolved key without `Bearer`, writes only a non-empty response,
+and never prints or stores the key separately:
+
+<!-- linear-download-recovery:start -->
+```bash
+download_linear_asset() {
+  LINEARIS_BIN="${LINEARIS_BIN:-$(command -v linearis)}" node --input-type=module - "$1" "$2" <<'NODE'
+import { realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [urlText, output] = process.argv.slice(2);
+const url = new URL(urlText);
+if (url.protocol !== "https:" || url.hostname !== "uploads.linear.app")
+  throw new Error("refusing to send a credential outside https://uploads.linear.app");
+const packageRoot = dirname(dirname(realpathSync(process.env.LINEARIS_BIN)));
+const { getApiToken } = await import(pathToFileURL(join(packageRoot, "dist/common/auth.js")));
+const response = await fetch(url, {
+  headers: { Authorization: getApiToken({}) },
+  redirect: "error",
+});
+if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+const bytes = new Uint8Array(await response.arrayBuffer());
+if (bytes.byteLength === 0) throw new Error("download failed: empty response");
+writeFileSync(output, bytes);
+console.log(`downloaded ${bytes.byteLength} bytes to ${output}`);
+NODE
+}
+download_linear_asset 'https://uploads.linear.app/...' '/tmp/attachment'
+```
+<!-- linear-download-recovery:end -->
+
+Do not declare the attachment inaccessible until this recovery used the resolved
+credential; reading `~/.linearis/token` directly does not count. Afterward, confirm the
+reported byte count and inspect the file type before consuming or extracting it.
+
 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

package/skills/verification-before-completion/reference/conformance-check.md

@@ -142,29 +142,24 @@ prerequisites hold.
 Per round:
 
 1. **Synchronize gap tasks** — append only a genuinely new gap that is entering remediation, named `Gn: <gap origin clause verbatim, truncated>`; never `init`. Find existing gaps by their exact `Gn:` prefix and reuse that index even if origin wording changes. Carried-OPEN inventory-only gaps add nothing. Before dispatch, mark every remediated gap's existing index `in_progress`; a re-audit needing more work reopens that same `Gn` index. The lifecycle traces `[T1,T2]`, then `[T1,T2,G1]`, then `[T1,T2,G1,G2]`; no test-retry or review-round wrapper task.
-2. **Fix dispatch** — per `dispatching-parallel-agents` "Fix fan-out": a `disjoint`
-   group of ≥ 2 gaps (per the report's `Parallel-safe:` line) fixes in one parallel
-   foreground dispatch — one `implementer` per gap (fresh context, `async: false`,
-   `worktree: true`, `cwd` = the conformance worktree, task = the gap block verbatim
-   with `touched-files` as the ownership boundary). For an `UNAUTHORIZED` `fix` gap
+2. **Fix wave** — select gaps greedily in `Gn` order: take each `fix` gap unless a gap it `conflicts` with (per the report's `Parallel-safe:` line) is already taken; the certificate's `disjoint` grouping is ignored, and a certificate still malformed after the one re-ask means every gap `conflicts` with every other. Held gaps carry to the next round; the wave is never empty while an eligible `fix` gap exists. Dispatch **one** call - `subagent({ context: "fresh", async: false, tasks: [...] })` - with one `implementer` task per selected gap (`worktree: true`, `cwd` = the conformance worktree, task = the gap block verbatim with `touched-files` as the ownership boundary). A single gap is a one-task `tasks` call; a lone `agent: "implementer"` call never appears in this loop. For an `UNAUTHORIZED` `fix` gap
    whose `evidence` opens with the over-spec provenance (`spec "<section>" - "<clause>" (over-spec)`), the orchestrator adds the spec path to that gap's `touched-files` before dispatch,
    so the implementer deletes the surface **and** the clause/AC line in the same
    fix commit; the re-audit then has no `Rn` for it and no `MISSING` echo. The dispatch adds `SCOPED_TEST_COMMANDS`
-   to the gap block: the gap-relevant plan-declared commands, or `none` (the round's
-   test gate owns execution). `conflicts` pairs serialize. Gaps outside any ≥ 2-ID
-   `disjoint` group run sequentially as before. Then dispatch foreground `spec-reviewer`
-   per gap on the gap-block reference contract below.
+   to the gap block: the gap-relevant plan-declared commands, or `none`; on an ad-hoc no-plan path, the project's canonical test command.
 3. **Integrate** serially via `git apply` onto the worktree HEAD, one gap's
-   patch at a time. Failure handling is inherited verbatim from
+   patch at a time. Commit each per-gap fix with the message **`conformance fix Gn`** (durable,
+   `git log`-readable pre-squash) so the finish gate and any revert can identify
+   auto-applied fixes; a Convergence repair wave commits as one **`conformance fix CR`**.
+   Failure handling is inherited verbatim from
    `dispatching-parallel-agents` "Review and Integrate": textual conflict →
    re-run one agent sequentially with the other's integrated changes as
    context; semantic conflict (applies clean, suite fails) → re-run the
    offending task sequentially on integrated HEAD; a failed agent → integrate
    the successes, then retry the failure with fresh context including the
    integrated changes. A `BLOCKED`/`NEEDS_CONTEXT` return surfaces to the user.
-4. **Test gate** on the integrated tree. In a plan flow, run the full plan-header `Verification` set once here; on an ad-hoc no-plan path, use the project's canonical test command. A failure re-enters the failure-handling rules above.
-5. **Round CR and completion** — run `code-reviewer` once on the round's cumulative fix delta (not per gap), foreground with `async: false` and `SCOPED_TEST_COMMANDS` = the round's gap-relevant commands, or `none` (the round's test gate owns execution). After integration, tests, and this CR accept the work, explicitly mark every remediated gap's same `Gn` index `complete`, before re-audit.
-6. **Re-audit**: foreground re-dispatch `conformance-reviewer` with `async: false` over the fixes **plus** the
+4. **Scoped tests** on the integrated tree: the round's `SCOPED_TEST_COMMANDS` union. A failure re-enters the failure-handling rules above.
+5. **Re-audit**: foreground re-dispatch `conformance-reviewer` with `async: false` over the fixes **plus** the
    regression guard (any prior-`DELIVERED` requirement whose `evidence` file
    the fix diff touched). Pass the full prior conformance report (every row,
    including DELIVERED rows and their `evidence` `file:line`) and the round's
@@ -173,18 +168,23 @@ Per round:
    `model:` when it is `undefined` to inherit the parent's model. Inside a
    brainstorming-entered flow, the phase-tracker closure guard blocks a dispatch
    that omits `model:` when `closureReview.model` is set, and warns (non-blocking)
-   on one whose model differs.
-7. **Converge or continue**: verdict `CONFORMS` → record it, done. Open gaps
+   on one whose model differs. Mark every `Gn` the re-audit reports `DELIVERED`
+   `complete`; open ones stay `in_progress`.
+6. **Converge or continue**: verdict `CONFORMS` → Convergence below. Open gaps
    within the cap → re-partition (per the rule above) and start the next
    round. Cap (`gauntlet_setting({ key: "closureReview" }).maxFixRounds`,
    default `2`, floors negatives at `0`, coerces non-integers to `2`) reached
-   with an open `fix` gap → **escalate to the human** with the per-gap
+   with an open `fix` gap or repair item → **escalate to the human** with the per-gap
    round-by-round verdict trail. Escalation is the sole non-completing
    terminal state — no silent re-loop, no auto-ship.
 
-Commit each per-gap fix with the message **`conformance fix Gn`** (durable,
-`git log`-readable pre-squash) so the finish gate and any revert can identify
-auto-applied fixes.
+**Convergence** — runs after R0 `CONFORMS` and after every `CONFORMS` re-audit. `r0-head` is HEAD when the loop was entered (the R0 dispatch, or the finish-time `fix-now` entry) - the parent of the oldest `conformance fix` commit; `audited-base` stays the last audit's HEAD SHA.
+
+a. Run the full plan-header `Verification` set once (ad-hoc: the project's canonical test command). After R0 `CONFORMS` with no round run, the pre-R0 full run counts.
+b. Dispatch `code-reviewer` directly (foreground, `async: false`, `SCOPED_TEST_COMMANDS: none`) over `git diff <r0-head>..HEAD`; never via `/skill:requesting-code-review`. An empty diff is nothing to review - no dispatch.
+c. Repair items = every failing command from a + every Critical/Moderate finding from b (`Behaviour-change: yes` included; the re-audit is its origin check). None → write the closure block; done. Any at the cap → escalate per step 6 with the test/CR trail. Any under the cap → re-enter step 2 as a one-task `tasks` wave: one `implementer` whose task is every repair item verbatim (ownership boundary = the files in `git diff <r0-head>..HEAD`, the CR findings' `touched-files`, and the files each failing command's output names, `SCOPED_TEST_COMMANDS: none`, no `Gn` tracker task, no gap selection), integrate as one `conformance fix CR`, re-audit, then Convergence again. That wave counts against `maxFixRounds`. Later Convergence CRs keep the same `<r0-head>..HEAD` range.
+
+`conformance fix CR` is not a gap fix: it is absent from the `auto-applied fix commits` index and has no `revert conformance fix Gn` action at the finish gate.
 
 **`maxFixRounds: 0`**: skip this loop entirely; every `recommended: fix` gap is
 carried OPEN to the finish gate per the precondition-unavailable
@@ -194,22 +194,6 @@ auto-fix, so treat `fix` gaps like any other deferred gap — unlike a cap > 0
 that is *exhausted*, which escalates mid-verify because the loop tried and
 could not converge.
 
-### `spec-reviewer` gap-block reference contract
-
-Per-gap `spec-reviewer` in step 2 above is a **pre-integration mechanical
-check**, distinct from the round-level re-audit in step 6 (which still
-references the *origin* — spec + original prompt — unchanged). Frame the
-per-gap dispatch against the **gap block**, not a plan task:
-
-- **Requirement** = the gap's `origin` + `remediation` (what must be true
-  after the fix).
-- **Closure proof** = the patch satisfies that requirement within the gap's
-  `touched-files` — nothing missing, nothing extra.
-- **Output** = `spec-reviewer`'s normal MATCH/DRIFT verdict, referenced to the
-  gap block instead of a plan task.
-
-This is a task-framing contract in the dispatch, not a new persona.
-
 ## Concern decomposition
 
 The main verification orchestrator — **not** `conformance-reviewer` — decomposes
@@ -459,15 +443,15 @@ concerns into one gap-scoped fix contract:
   boundary).
 
 Rescoped, accepted, and followed-up sibling concerns are **excluded** from the
-projection. The `implementer` and the pre-integration `spec-reviewer` receive
-this projected contract in place of the original whole-gap block.
-
-The projected task runs the existing full loop above: it retains the gap-level
-`conformance fix Gn` commit name, reruns the project's tests, runs
-`code-reviewer`, re-audits against the amended spec, and reenters the gate only
-if concerns remain. Gap-level revert stays available through the flat commit
-index. The gate records the final result by concern ID and title before showing
-branch integration options.
+projection. The `implementer` receives this projected contract in place of the
+original whole-gap block.
+
+The projected task runs the round and Convergence above with `r0-head` = HEAD at
+this entry: it retains the gap-level `conformance fix Gn` commit name, re-audits
+against the amended spec, and reenters the gate only if concerns remain.
+Gap-level revert stays available through the flat commit index. The gate records
+the final result by concern ID and title before showing branch integration
+options.
 
 ## Checklist