@henryqw/pi-subagent 10.0.0 → 10.1.0

package/CONTEXT.md

@@ -29,7 +29,7 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation. Explicit Role/caller tool names verify against the final filtered child registry after explicit provider `session_start` handlers, and unavailable names fail before the first turn.
 - Main policy populates direct `model` and `thinking` only for explicit user overrides; otherwise it selects only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This has no provenance tracking or runtime enforcement. An omitted class uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration (default `fast`); library callers select a Role plus their own Model Task declaration.
 - The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. A missing local JSON config uses defaults quietly. Missing shared task-model config warns once per session because delegation needs a route. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.
-- User Role Markdown files and Subagent JSON config (`config/pi-subagent/config.json`) live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models/config.json`. Package-shipped built-in Roles (`implementer`, `reviewer`) resolve from the package's own `examples/roles/` Markdown through the same parser; a same-named user file explicitly overrides a built-in for `delegate_task` and `delegate_flow`.
+- User Role Markdown files and Subagent JSON config (`config/pi-subagent/config.json`) live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models/config.json`. Package-shipped built-in Roles (`implementer`, `reviewer`, `scout`) resolve from the package's own `examples/roles/` Markdown through the same parser; same-named user files override built-ins for `delegate_task`, while same-named `implementer` and `reviewer` files override Flow defaults. The `synthesizer` Markdown remains the only optional inert sample.
 - `delegate_flow` accepts 1–8 independent units with direct validation commands, optional `modelClass`, and optional non-empty `review` judgment text. Omitted classes use pi-subagent's local `pi-subagent/delegateTask` declaration (default `fast`); each unit's current class resolves through its shared profile route for its Implementer and, when `review` exists, Reviewer. At Flow start it always resolves/freezes the effective Implementer and resolves/freezes a Reviewer only when at least one requested unit has `review`. One active Flow creates every Unit Worktree before launching Implementers in parallel, then processes settled units in declared order. For each unit Flow rebases in place when earlier units advanced Main, inspects committed Git state, and runs declared validation. Validation is authoritative for objective verification: units without `review` fast-forward their exact validated tip; units with `review` send the exact Review Packet to the Reviewer in the same worktree and require exact `PASS` before the same guarded `git merge --ff-only` path.
 - Flow is memory-only. Only a post-rebase commit drop produces a no-op (`base === tip`); it validates, skips Reviewer and merge, then cleans up ordinarily. Initial zero-commit implementations block. Implementer, validation, or reviewer blocks allow one `delegate_flow_continue({ guidance, modelClass? })` repair in the same worktree; omission retains the Unit's current class and presence replaces it for that repair. A second block is terminal. Rebase and evidence/Reviewer/infrastructure failures retain worktrees. A reported fast-forward failure retains its worktree unless Main is clean at the exact integrated tip, which completes with the merge diagnostic as a warning. Cleanup uses non-forced worktree removal and branch deletion; cleanup refusal is a completion warning.
 - Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge validation. It never changes generic `delegate_task` Role resolution, isolation, non-Git fallback, or ordinary direct plan/file review.

package/README.md

@@ -135,7 +135,7 @@ Rebase and infrastructure failures are terminal. A reported fast-forward failure
 
 Otherwise it is terminal and retains the affected worktree. Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge gate.
 
-`delegate_task` keeps its generic isolation behavior. Flow uses the package-shipped Implementer by default and the package-shipped Reviewer only when a unit requests review. Same-named user Roles remain supported overrides.
+`delegate_task` keeps its generic isolation behavior. Flow uses the package-shipped Implementer by default and the package-shipped Reviewer only when a unit requests review; the built-in Scout is not part of Flow. Same-named user Roles remain supported overrides.
 
 ### Delegate UI summary
 
@@ -200,28 +200,28 @@ An unreadable or invalid Role file fails role loading fast. Duplicate role names
 
 ## Roles
 
-The package ships two working built-in Roles. They are always available without configuration.
+The package ships three working built-in Roles. They are always available without configuration.
 
 - `implementer`: focused edits requesting worktree isolation; commits completed scoped changes locally and never pushes or opens PRs without authorization
 - `reviewer`: read-only correctness review of supplied plans or files, or—only when a Flow unit declares `review`—of Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits
+- `scout`: read-only code and evidence mapping for one bounded task; never changes files
 
-A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default.
+A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default. The built-in `scout` is available to generic `delegate_task`; `delegate_flow` remains limited to its fixed Implementer/Reviewer protocol.
 
-The repository also includes optional inert samples:
+The repository also includes one optional inert sample:
 
-- [`scout`](./examples/roles/scout.md): read-only discovery
 - [`synthesizer`](./examples/roles/synthesizer.md): reconcile supplied reports
 
-Copy them manually from your installed `@henryqw/pi-subagent` package if you want a starting point. npm installs ship the `examples/roles/` directory.
+Copy it manually from your installed `@henryqw/pi-subagent` package if you want a starting point. npm installs ship the `examples/roles/` directory.
 
 ```bash
 mkdir -p ~/.pi/agent/config/pi-subagent
-cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
+cp <package-install-dir>/examples/roles/synthesizer.md ~/.pi/agent/config/pi-subagent/
 ```
 
 Locate the install directory with `npm root` inside your project, or through Pi's package installation path.
 
-The package never installs or writes Role configuration. Sample names are not built-ins. After copying, edit or replace them as your own Roles.
+The package never installs or writes Role configuration. After copying, edit or replace `synthesizer.md` as your own Role.
 
 ## Skill
 

package/dist/index.d.ts

@@ -45,14 +45,13 @@ export interface ResolvedRoleSkills {
     paths: string[];
     missing: string[];
 }
-declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer"];
+declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer", "scout"];
 export type BuiltinRoleName = (typeof BUILTIN_ROLE_NAMES)[number];
 export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
 /**
- * Validated built-in implementer/reviewer Roles plus valid user roles from
- * `config/pi-subagent`. A user role with a built-in name overrides the default;
- * duplicate names among user files are an error. Missing user directory returns
- * the built-ins.
+ * Validated package-shipped Roles plus valid user roles from `config/pi-subagent`.
+ * A user role with a built-in name overrides the default; duplicate names among
+ * user files are an error. Missing user directory returns the built-ins.
  */
 export declare function loadRoles(agentDir?: string): Role[];
 export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string, thinking?: ThinkingLevel): ResolvedTaskRoute;

package/dist/index.js

@@ -46,9 +46,8 @@ function validateExtension(extension, source) {
 function extensionList(value, source) {
     return stringList(value, "extensions", source).map((extension) => validateExtension(extension, source));
 }
-// Built-in Roles required by the bundled pi-subagent-delegated-development Skill;
-// resolved from the package-shipped Markdown relative to this module.
-const BUILTIN_ROLE_NAMES = ["implementer", "reviewer"];
+// Built-in Roles resolved from the package-shipped Markdown relative to this module.
+const BUILTIN_ROLE_NAMES = ["implementer", "reviewer", "scout"];
 /** Single-file Role parser shared by built-in and user roles. */
 function parseRoleFile(file, raw) {
     let parsed;
@@ -89,10 +88,9 @@ function builtinRoles() {
     return BUILTIN_ROLE_NAMES.map(loadBuiltinRole);
 }
 /**
- * Validated built-in implementer/reviewer Roles plus valid user roles from
- * `config/pi-subagent`. A user role with a built-in name overrides the default;
- * duplicate names among user files are an error. Missing user directory returns
- * the built-ins.
+ * Validated package-shipped Roles plus valid user roles from `config/pi-subagent`.
+ * A user role with a built-in name overrides the default; duplicate names among
+ * user files are an error. Missing user directory returns the built-ins.
  */
 export function loadRoles(agentDir = getAgentDir()) {
     const byName = new Map(builtinRoles().map((role) => [role.name, role]));

package/docs/adr/001-composable-ephemeral-execution.md

@@ -12,7 +12,7 @@ Resource Policy is split at launch preparation:
 - Caller may add explicit tools, extensions, and environment through `createRoleLaunch`.
 - The executor receives the resulting Pi Launch and does not discover resources.
 
-Built-in `implementer` and `reviewer` Roles ship as Markdown in `examples/roles/` and use the same parser as user Roles. For generic delegation, a same-named user Role explicitly overrides a built-in. The package does not install, copy, or write user configuration.
+Built-in `implementer`, `reviewer`, and `scout` Roles ship as Markdown in `examples/roles/` and use the same parser as user Roles. For generic delegation, a same-named user Role explicitly overrides a built-in. The package does not install, copy, or write user configuration.
 
 Main populates direct `model` and `thinking` only for explicit user overrides; otherwise it chooses only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This is tool policy, not executor provenance tracking or runtime enforcement.
 

package/docs/orchestration.md

@@ -66,7 +66,7 @@ Single mode puts one delegation's fields at the top level.
 
 | Field | Required | Contract |
 | --- | --- | --- |
-| `role` | yes | Name of a Role in the user's effective `config/pi-subagent` directory or a package-shipped built-in (`implementer`, `reviewer`); a same-named user file overrides the built-in. |
+| `role` | yes | Name of a Role in the user's effective `config/pi-subagent` directory or a package-shipped built-in (`implementer`, `reviewer`, `scout`); a same-named user file overrides the built-in. |
 | `name` | yes | Main-supplied short task name: about five words and fewer than 30 characters; C0/C1 control characters are rejected. |
 | `task` | yes | Non-empty bounded task packet. |
 | `model` | no | Designated `provider/modelId`; takes precedence over `modelClass`, and Main supplies it only for an explicit user override. |
@@ -108,7 +108,7 @@ If rebase drops all unit commits, `base === tip` is a no-op: Flow validates curr
 
 Flow has no dependency graph, saved state, automatic retry, aggregate review, or post-merge validation. Use it only for commuting changes; combine or sequence units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.
 
-`delegate_task` remains generic: its optional worktree isolation, non-Git behavior, and direct plan/file review are unchanged. Flow uses package-shipped Roles as defaults while retaining same-named user Role overrides; the Reviewer is needed only for a requested review criterion.
+`delegate_task` remains generic: its optional worktree isolation, non-Git behavior, and direct plan/file review are unchanged. The built-in `scout` is available only through generic `delegate_task`; Flow uses package-shipped Implementer and conditional Reviewer Roles as defaults while retaining same-named user Role overrides.
 
 ## Per-delegation resources and isolation
 
@@ -391,30 +391,30 @@ The verdict schema, parser, round state, shared workspace, and terminal decision
 
 ## Built-in Roles and samples
 
-The package ships two working built-in Roles, validated by the same parser as user roles and always present even with no `config/pi-subagent` directory:
+The package ships three working built-in Roles, validated by the same parser as user roles and always present even with no `config/pi-subagent` directory:
 
 | Built-in | Behavior |
 | --- | --- |
 | `implementer` | Focused implementation requesting `isolation: worktree`; commits scoped changes locally, never pushes or opens PRs without authorization. Non-Git or unborn-`HEAD` contexts may use Main's cwd. |
 | `reviewer` | Read-only correctness review of supplied plans/files, or—when a Flow unit declares `review`—Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits. |
+| `scout` | Read-only code and evidence mapping for one bounded task; never changes files. |
 
 A same-named Markdown file in `config/pi-subagent/` explicitly overrides the built-in default.
 
-Additional repository samples are inert starting points, not installed configuration:
+The repository includes one optional inert sample, not installed configuration:
 
 | Sample | Intended starting point |
 | --- | --- |
-| [`scout`](../examples/roles/scout.md) | Read-only code/evidence mapping. |
 | [`synthesizer`](../examples/roles/synthesizer.md) | Reconcile supplied reports without broad discovery. |
 
-Copy the package-shipped samples from your installed `@henryqw/pi-subagent` package (npm installs include `examples/roles/`) if you want them:
+Copy the package-shipped sample from your installed `@henryqw/pi-subagent` package (npm installs include `examples/roles/`) if you want it:
 
 ```bash
 mkdir -p ~/.pi/agent/config/pi-subagent
-cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
+cp <package-install-dir>/examples/roles/synthesizer.md ~/.pi/agent/config/pi-subagent/
 ```
 
-The package never creates, copies, updates, or removes files in `~/.pi/agent/config/pi-subagent/`. Once copied, the files and their names are entirely user-owned.
+The package never creates, copies, updates, or removes files in `~/.pi/agent/config/pi-subagent/`. Once copied, the file and its name are entirely user-owned.
 
 The bundled [`pi-subagent-delegated-development`](../skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side planner/orchestrator policy only. `delegate_flow` owns its fixed Git mechanics and objective validation authority; the Skill defines no runtime code or configuration. `delegate_task` remains the generic flat single/parallel/chain mechanism.
 

package/examples/roles/implementer.md

@@ -14,12 +14,12 @@ skills: []
 isolation: worktree
 ---
 
-Implement one bounded task.
+Implement the bounded outcome, not a preassigned file list. Work in the assigned cwd. Read applicable repository instructions and domain context first; inspect the relevant flow, callers, and tests before editing. Preserve unrelated work. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies. Do not add speculative work. Stop when the outcome is complete or blocked.
 
-Read applicable repository instructions and domain context first. Inspect the existing flow and its callers before editing. Work only in the assigned cwd and explicitly assigned files; preserve unrelated changes. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies.
+For ordinary delegation, run focused validation needed to establish correctness. For Flow, the declared validation gate is authoritative: run only narrow development checks while implementing and do not duplicate that final gate.
 
-For ordinary delegation, run the focused validation needed to establish that the change is correct. When a Flow packet declares an authoritative validation gate, treat that gate as the final validation: run only narrow development checks needed while implementing, and do not duplicate the declared gate. Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs; deterministic developer tools remain allowed.
+Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-Commit completed scoped changes locally unless the task forbids it. Never create or manage another worktree. Never push or open pull requests without explicit authorization.
+Commit completed scoped changes locally unless the task says otherwise. Do not create or manage another worktree. Never push or open a pull request without explicit authorization. For Flow, leave the assigned worktree and branch intact.
 
-For ordinary delegation, report the completed change, validation, and remaining risks. For Flow, return the retained assigned cwd, branch, base commit, tip commit, changed files from the base-to-tip committed diff, clean `git status --porcelain=v1 --untracked-files=all` result, and validation results. Do not remove the retained worktree or task branch; Main cleans them only after successful integration and validation.
+Report briefly: outcome, commit, checks run, and remaining risks. Do not repeat Flow's Git-derived evidence.

package/examples/roles/reviewer.md

@@ -10,15 +10,11 @@ extensions: []
 skills: []
 ---
 
-Perform a read-only correctness review of one bounded change.
+Review read-only in exactly two modes:
 
-Support exactly two review modes:
+1. Ordinary delegation: use supplied requirements and named files/evidence only. Do not prepare Git, require a commit/Review Packet, or broaden discovery. If evidence is insufficient, say so and stop.
+2. Flow exact review: only with an explicit judgment criterion, use the same assigned Unit Worktree and exact Review Packet `{base, tip, patchPath}`. Treat the exact patch at `patchPath` as authoritative; read only referenced files/context. Declared validation is authoritative for objective verification. Judge only the explicit criterion; never infer a diff from another branch/worktree.
 
-1. For ordinary delegation, review the supplied plan and explicitly named files directly. Do not prepare Git, require commits, or require a patch packet.
-2. For Flow exact review, only when the task supplies an explicit judgment criterion, require a Review Packet `{base, tip, patchPath}` and the same assigned Unit Worktree context. Declared validation is authoritative for objective verification; judge only that criterion. Read the exact patch as authoritative, then read only the files it references and relevant criterion context. Do not infer a diff from a branch or another worktree.
+Report only actionable correctness risks introduced by the change—not style preferences, speculative hypotheticals, or unrelated pre-existing issues. Use only `read`, `grep`, `find`, and `ls`; run no commands/tests and never edit, write, commit, push, or manage Git/worktrees. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-In either mode, review only the supplied requirements and explicitly referenced context. Use only `read`, `grep`, `find`, or `ls` for that review. For ordinary delegation, check correctness, regressions, trust-boundary validation, error handling, and missing high-value tests. Do not run commands or tests. Never manage Main, Git, or tests; never edit or write files, commit, push, or otherwise modify state.
-
-Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
-
-Emit exactly `PASS` when there are zero findings. Any finding must block approval: return findings first, ordered by severity, with file and line evidence, impact, and the smallest valid fix. Do not emit `PASS` alongside findings.
+Output exactly `PASS` when there are no findings. Otherwise output findings only, ordered by severity, with file:line evidence, impact, and smallest valid fix; any finding blocks approval. Never combine `PASS` with findings. Stop when supplied evidence is covered; in Flow, stop after its criterion.

package/examples/roles/scout.md

@@ -1,19 +1,23 @@
 ---
 name: scout
 description: Maps relevant code and evidence for one bounded task without changing files
-tools: [read, grep, find, ls]
+tools:
+  - read
+  - grep
+  - find
+  - ls
 extensions: []
 skills: []
 ---
 
-Perform read-only discovery for one bounded task.
+Answer only the bounded discovery questions.
 
-Stay within the paths and questions named in the task. Read applicable repository instructions and domain context before tracing the concrete execution or data flow far enough to identify affected files, callers, tests, and constraints. Do not design or implement changes.
+Read applicable repository instructions and domain context first. Trace the relevant execution/data flow, callers, tests, and constraints only far enough to answer. Separate observed facts, supported inferences, and unknowns. Stop when answered; if blocked, state what is missing.
 
-Do not edit files or run shell commands. Return:
+Do not design, recommend, implement, edit, or run shell commands.
 
-- a concise map of relevant files and symbols and how they connect;
-- evidence with file paths and line numbers;
-- uncertainties or missing context.
+Return concisely:
 
-Stop when the task's questions are answered.
+- a map of relevant files and symbols and how they connect;
+- path:line evidence;
+- uncertainties or missing context.

package/examples/roles/synthesizer.md

@@ -1,7 +1,8 @@
 ---
 name: synthesizer
 description: Reconciles bounded worker reports into one evidence-based result
-tools: [read]
+tools:
+  - read
 extensions: []
 skills: []
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",