pi-cohort 6.1.1 → 7.0.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [7.0.1] - 2026-09-17
+
+### Fixed
+
+- `/handoff` records the run's linked worktree instead of the session cwd: the producer names it, the scout validates it against `git worktree list --porcelain` and snapshots it via `git -C`; a rejected candidate is surfaced under `## Open questions`; the `worktree:` field no longer misreports `yes` from a primary subdirectory. ([#17](https://github.com/jjuraszek/pi-cohort/issues/17))
+
+## [7.0.0] - 2026-09-17
+
+### Removed
+
+- Packaged prompts `/parallel-review`, `/review-loop`, `/parallel-cleanup`, `/gather-context-and-clarify`, `/parallel-context-build`, `/parallel-handoff-plan`. Review and delivery workflows live in pi-gauntlet.
+- Remaining `interview` references left from the pi-intercom removal.
+
+### Added
+
+- `/investigate <request> [--out path]`: parallel read-only recon (`scout`, `reviewer`, `context-builder` on refs), premise check, questions with recommendations, optional verification wave.
+- `/handoff [--out path]`: fixed-template brief for a fresh session; `doc/handoff-template.md` is the contract consumers parse.
+
+### Changed
+
+- `skills/pi-cohort/SKILL.md` covers only what the tool description and schema leave open (fresh vs fork, acceptance levels, per-task overrides, control actions); the prompt bodies, agent roster, and duplicated tool mechanics are gone.
+- `reference/config-fields.md` separates management `skills` from execution-time `skill`.
+
 ## [6.1.1] - 2026-09-17
 
 ### Fixed

package/README.md

@@ -117,6 +117,8 @@ Run parallel reviewers: one for correctness, one for tests, and one for unnecess
 
 That's the whole surface for day-to-day use. More phrasing patterns: [doc/commands.md](doc/commands.md#prompt-cookbook-appendix).
 
+Review and delivery workflows live in pi-gauntlet; pi-cohort ships delegation primitives plus `/investigate` and `/handoff`.
+
 ## Architecture
 
 `subagent()` supports four dispatch shapes, all through the same tool:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "6.1.1",
+  "version": "7.0.1",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/prompts/handoff.md

@@ -0,0 +1,54 @@
+---
+description: "Use when the context window is nearly full and the work must continue in a fresh session."
+---
+
+Write a handoff brief for a fresh session. The template is the contract in `doc/handoff-template.md` of pi-cohort; section names are fixed.
+
+Optional `--out <path>` (relative resolves against cwd):
+
+$@
+
+## Rules
+
+- `DIR=$(mktemp -d)`. The dispatch: `async: false` and `context: "fresh"` at the top level; `reads: false`; absolute `output` under `$DIR`. If it returns an async handle, a `forceTopLevelAsync` setting is active: stop and report it. Do not poll, relaunch, or continue.
+- The child is read-only against the repository; its only write is its `output` file.
+- You write `## Intent`, `## Decisions`, `## Open questions`, and `## Skills loaded` from your own transcript, before the call and after it returns. Do not fork a child for this: forking a near-full transcript is the cost this handoff avoids.
+- Write nothing into the repository; the brief goes to `--out` or `$DIR/handoff.md`.
+
+## Run worktree
+
+Before the snapshot dispatch, determine the run worktree from your own transcript and interpolate it into the scout task as `Run worktree: <abs path>` or `Run worktree: none`:
+
+- A flow-level worktree the run created (any `git worktree add <path>` you ran, or a `Worktree ready at <path>` report from `/skill:using-git-worktrees`) or was told to work in (a resume brief's `worktree: yes <path>`, or a user instruction).
+- Never inferred from the session cwd; a created or assigned worktree still qualifies when it happens to equal the cwd. Never a per-task worktree from `tasks[].worktree: true` or `worktree: true` dispatches - those are ephemeral.
+- Two flow-level worktrees in the transcript: the candidate is the one most recently used by later work (a dispatch `cwd`, a `git -C <path>`, or a `cd <path>`); if that does not distinguish them, the most recent creation or assignment. The other goes into `## Open questions` as `Also seen: <path> - not recorded as the run worktree`.
+- No flow-level worktree created or named: `Run worktree: none`.
+
+After the scout returns, copy any `open-question:` line from `repo.md` into `## Open questions` without the `open-question:` prefix; it never appears in `## Repo state`.
+
+## Repo snapshot
+
+```
+subagent({ async: false, context: "fresh", tasks: [
+  { agent: "scout", cwd: "<cwd>", reads: false, output: "<DIR>/repo.md",
+    task: "Read-only; write only to your output path. Run worktree: <abs path|none>. Steps: (1) linked set: git worktree list --porcelain | awk '/^worktree /{print substr($0,10)}' - the first line is the primary checkout, the rest are the linked worktrees; a relative candidate resolves against the primary toplevel, not cwd. (2) candidate `none` or line absent -> target is cwd, go to (4). Otherwise if the candidate is relative, prefix it with the primary toplevel (first linked-set line) first; C=$(git -C <candidate> rev-parse --show-toplevel); valid when that succeeds and C equals one of the linked lines exactly (a line after the first; equality with the first, primary line is invalid); anything else (failure, not listed, the primary itself, prunable) is invalid -> target is cwd and emit the open-question line in (5). (3) valid -> target is $C and `worktree: yes $C`. (4) target cwd -> T=$(git rev-parse --show-toplevel); `worktree: yes $T` when $T equals one of the linked lines exactly (a line after the first; the first, primary line gives `worktree: no`), else `worktree: no`. (5) report each field on its own line, `unavailable` when a command fails, every git command as `git -C <target>`: toplevel (git -C <target> rev-parse --show-toplevel); the worktree line from (3) or (4); branch (git -C <target> branch --show-current, `detached` when empty); HEAD SHA; base (origin/HEAD short name, else origin/main or origin/master if present, else `base: unknown`); dirty (git -C <target> status --porcelain, or `clean`); diff-stat (git -C <target> diff --stat <base>...HEAD; `diff-stat: unavailable` when base is unknown); test command (<target>/package.json scripts or <target>/AGENTS.md). Invalid candidate: after the fields add the single line `open-question: producer named <candidate as submitted> as the run worktree; it is not a linked worktree of this repo`. cwd not a git repo -> the single line `not a git repo`, plus the same open-question line if a candidate was submitted." }
+]})
+```
+
+## Process state
+
+Include `## Process state` only when both `phase_tracker` and `plan_tracker` tools exist AND `phase_tracker status` shows a phase `in_progress`. Then: `phase_tracker status` and `plan_tracker status` outputs verbatim; `Active task: <task name>` (the task you are working on; `none` when no plan is active or no task is active); the line `Gate history not restored - re-validate before advancing.`. Tools absent, all phases pending, or hotfix flow -> omit the section.
+
+## Brief
+
+```markdown
+# Handoff: <one line>
+## Intent
+## Repo state          (the snapshot fields; `## Repo state: not a git repo` when so)
+## Decisions           (bullets; rejected alternatives marked `rejected:`)
+## Open questions
+## Skills loaded       (frontmatter `name` of every skill whose SKILL.md body is in context - a `<skill>` block or a tool result on a `*/SKILL.md` path; `## Skills loaded: none` when there are none)
+## Process state       (only per the rule above)
+```
+
+Write it, print the path and the brief.

package/prompts/investigate.md

@@ -0,0 +1,60 @@
+---
+description: "Use when a request's premises are unverified, the territory is unknown, or the user asks to look into something before planning or brainstorming."
+---
+
+Investigate the request below with parallel read-only personas, then write a brief the user can paste into a fresh session or hand to brainstorming.
+
+Request (text, or a path to a file holding it; optional trailing `--out <path>`):
+
+$@
+
+## Rules
+
+- Empty request -> stop and ask for it. A path that does not exist is request text.
+- `DIR=$(mktemp -d)`. Every dispatch: `async: false` and `context: "fresh"` at the top level (never inside a task object); `cwd` = `git rev-parse --show-toplevel`; every task `reads: false` and an absolute `output` under `$DIR`. Interpolate shell variables into the call as absolute paths.
+- If a dispatch returns an async handle, a `forceTopLevelAsync` setting is active: stop and report it. Do not poll, relaunch, or continue.
+- Every child is read-only against the repository; its only write is its `output` file. Say so in every task text. `reads: false` is mandatory: persona `defaultReads` name chain files that do not exist here.
+- Write nothing into the repository. The brief goes to `--out` if given (relative resolves against cwd), else `$DIR/brief.md`.
+- A question whose answer is in code, docs, or the tracker is not asked; it is looked up in wave 1 or wave 2.
+- A verification task that would run, build, or validate the proposed change is rejected at brief-writing time. Wave 2 exercises the system as it is today.
+
+## Wave 1
+
+Detect refs in the request: `http(s)://` URLs; `owner/repo#N`; bare `#N` when `git remote get-url origin` is a GitHub URL; `[A-Z][A-Z0-9]+-\d+`.
+
+One call, shape `subagent({ async: false, context: "fresh", tasks: [...] })`:
+
+```
+subagent({ async: false, context: "fresh", tasks: [
+  { agent: "scout", cwd: "<root>", reads: false, output: "<DIR>/scout.md",
+    task: "Read-only recon; write only to your output path. Request: <request>. Map the territory: files with line ranges, patterns and conventions a change must match, test conventions, integration points, and whether the codebase or ecosystem already solves this. Cite paths." },
+  { agent: "reviewer", cwd: "<root>", reads: false, output: "<DIR>/premise.md",
+    task: "Read-only premise critique; do not edit any file, write only to your output path. Request: <request>. For each claim the request makes or assumes, classify: Confirmed (cite code), Contradicted (cite code), or Unverified (asserted, not shown). No design proposals." },
+  // only when refs were detected:
+  { agent: "context-builder", cwd: "<root>", reads: false, output: "<DIR>/external.md",
+    task: "Read-only; write only to your output path, context handoff only (no meta-prompt file). Request: <request>. Refs: <one per line>. For each: acceptance criteria, hard constraints, linked discussion that changes scope, contradictions with the request. A ref you cannot read -> `unreadable: <ref>` and continue." }
+]})
+```
+
+A task that errored or left its output empty -> its section reads `<agent> failed: <reason>`. The brief is still written.
+
+## Brief
+
+Read the outputs and write, section names fixed:
+
+```markdown
+# Investigation: <slug>
+## Request
+## Findings            (cited; `### Verified` appended after wave 2)
+## External context    (only when context-builder ran; unreadable refs listed)
+## Premise check       (Confirmed / Contradicted / Unverified - one line each, cited)
+## Open questions      (numbered; each ends with `Recommendation: <answer> - <why>`)
+## Verification tasks  (numbered; independent; each: one-paragraph read-only subagent task + `Expected:`; current behaviour only)
+## Next steps          (suggestions only; no implementation task decomposition)
+```
+
+Print the path and the brief.
+
+## Wave 2 (ask once)
+
+Ask: "Run the verification tasks?" No -> stop. Yes -> one call `subagent({ async: false, context: "fresh", tasks })`, one task per verification task, `scout` by default or `reviewer` when judgement is needed, each task text containing the phrase "read-only", `reads: false`, absolute `output` under `$DIR`. Fold results into `## Findings` under `### Verified` and rewrite the brief at the same path.