pi-gauntlet 5.2.1 → 5.2.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v5.2.3 - 2026-09-01
+
+- Isolated `subagent` dispatch examples now mint an OS-temp report directory and use absolute `output:` paths, preventing reports from being captured in and deleted with throwaway worktrees. The parallel-dispatch Output capture guidance now distinguishes that isolated failure mode from non-isolated shared-working-tree commit/overwrite risk. Fixes #23. Spec: `doc/specs/2026-09-01-gh-23-absolute-report-paths.md`.
+
+## v5.2.2 - 2026-09-01
+
+- `linear` skill: the once-per-session `linearis issues usage` sweep no longer requires authentication. `usage` prints local help and makes no API call, so gating it on `auth status` skipped the cheap staleness check exactly when the agent was already degraded; it now runs whenever the binary is present. Also drops a dead "or the MCP path is in use" skip clause - the sweep sits inside the present-binary branch, and MCP is the fallback only when the binary is missing. Prose only, no code or config surface. Follow-up to #22; spec `doc/specs/2026-09-01-gh-22-linear-cli-verification.md` amended to match.
+
 ## v5.2.1 - 2026-09-01
 
 - `linear` skill: seven `linearis` invocations corrected against the installed CLI (2026.7.0) - the nonexistent `issues comment-edit` becomes `issues edit <comment>`, `reply` takes a root discussion thread ID, `edit-reply` takes `<reply>`, `files upload` takes `<file>` (two occurrences), `attachments create`'s issue positional is optional, and gotcha (e) now documents two distinct relation flag sets (`relations add` has no `--blocked-by`). Setup is **preferred, not required**: a missing or unauthenticated `linearis` degrades and reports instead of blocking the run (MCP stays the fallback for a missing binary only). Drift resistance added in place - a once-per-session `linearis issues usage` consult for the issue-domain rows, a visible verified-against stamp under the quick-reference table, and one narrow parser-shape row in the failure table. Fixes #22. Spec: `doc/specs/2026-09-01-gh-22-linear-cli-verification.md`.

package/package.json

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

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

@@ -183,7 +183,11 @@ Parallel dispatch rides on the `subagent` tool (the pi-cohort package). Mechanic
 - **Filesystem isolation** — `worktree: true` runs each task in its own git worktree so concurrent edits can't collide. Requires clean git state; each task's diff returns separately for you to integrate. Omit it for read-only investigations.
 - **Worktree base / `cwd`** — under `worktree: true` the base commit is `HEAD` resolved from the **top-level `cwd`**, which defaults to the orchestrator's process cwd. When you orchestrate from inside a git worktree, pass that worktree's absolute path as the top-level `cwd`, or children branch from the wrong checkout. Don't set per-task `cwd` with `worktree: true` — it must equal the shared cwd or the run errors.
 - **Agent choice** — `worker` is the pi-cohort builtin generalist. Use a persona (`implementer`, `code-reviewer`) when you want its system prompt and tool profile. Persona frontmatter (tools, thinking, context) is fixed; only `model`, `task`, `output`, `reads`, `progress`, `skill` are callable per task.
-- **Output capture** — `output: "<file>"` writes a task's summary to a file instead of inline; add `outputMode: "file-only"` for large results.
+- **Output capture** - `output: "<file>"` writes a task's summary to a file instead of inline; add `outputMode: "file-only"` for large results. When a batch uses `worktree: true`, each `output:` path must be absolute and outside every isolated checkout; a relative report is captured as helper work and then deleted with the checkout. In a non-isolated batch, a relative report lands in the shared working tree and risks being committed or overwritten by a later task.
+
+```bash
+REPORT_DIR=$(mktemp -d)
+```
 
 ```ts
 subagent({
@@ -191,9 +195,9 @@ subagent({
   worktree: true,        // isolate edits; omit for read-only investigations
   concurrency: 3,
   tasks: [
-    { agent: "worker", task: "Fix + explain failures in src/a.test.ts", output: "a.md" },
-    { agent: "worker", task: "Fix + explain failures in src/b.test.ts", output: "b.md" },
-    { agent: "worker", task: "Fix + explain failures in src/c.test.ts", output: "c.md" },
+    { agent: "worker", task: "Fix + explain failures in src/a.test.ts", output: "<REPORT_DIR>/a.md" },
+    { agent: "worker", task: "Fix + explain failures in src/b.test.ts", output: "<REPORT_DIR>/b.md" },
+    { agent: "worker", task: "Fix + explain failures in src/c.test.ts", output: "<REPORT_DIR>/c.md" },
   ],
 })
 ```

package/skills/linear/SKILL.md

@@ -38,15 +38,16 @@ No `linearis` and no MCP: report inability, never fabricate. MCP is the fallback
 **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
+**Session sweep.** When `linearis` is present, 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. Authentication is not required -
+`usage` prints local help and makes no API call, so the sweep still runs on an
+installed-but-unauthenticated CLI. If the call errors or returns nothing, note once that
+the issue-domain rows are unverified this session and continue. The sweep lives inside
+the present-binary 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.

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

@@ -185,6 +185,10 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 **Set `cwd` to your worktree — resilience-critical.** This whole workflow runs *inside* a worktree, but the `subagent` tool resolves the worktree base from the **top-level `cwd`**, which defaults to the orchestrator's process cwd — the *primary* checkout (usually `main`), not the worktree. Omit `cwd` and `worktree: true` branches every child from the primary checkout's HEAD: the children never see your spec, plan, or prior-wave commits, and integration runs against the wrong baseline. Pass the worktree's absolute path as the top-level `cwd`. Do **not** set per-task `cwd` under `worktree: true` — pi-cohort requires it to equal the shared cwd and errors otherwise. (Clean-tree is enforced here too — `resolveRepoState` rejects a dirty tree — which is why each wave commits before the next.)
 
+```bash
+REPORT_DIR=$(mktemp -d)
+```
+
 ```ts
 subagent({
   context: "fresh",
@@ -193,8 +197,8 @@ subagent({
   concurrency: 4,        // default; cap = wave size
   tasks: [
     // do NOT set per-task cwd under worktree:true — it must equal the top-level cwd or the run errors
-    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "wave1-task1.md" },
-    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "wave1-task2.md" },
+    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "<REPORT_DIR>/wave1-task1.md" },
+    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "<REPORT_DIR>/wave1-task2.md" },
   ],
 })
 ```