@mgiles/perk 2.2.0 → 3.0.0

package/extension/substrate/toolGating.ts

@@ -89,8 +89,9 @@ export const LINEAR_MUTATING_TOOLS: readonly string[] = [
  * (≈830 schema chars — accepted, documented, test-pinned). A later `session_tree` re-apply
  * filters over the original snapshot (which lacks the late names), so a tree navigation drops
  * them — the pre-existing snapshot behavior, unchanged. Child-side tools (`contact_supervisor`,
- * `structured_output`) are out of scope: spawned children are unscoped by design (§8.40
- * adopt-never-impersonates).
+ * `structured_output`) are out of scope for the STAGE census — spawned children stay
+ * stage-unscoped by design (§8.40 adopt-never-impersonates) — but they DO ride READ_ONLY_TOOLS,
+ * because the read-only gate IS inherited by adopted children (see SUBAGENT_CHILD_TOOLS).
  */
 export const SUBAGENT_TOOLS: readonly string[] = [
   "subagent",
@@ -99,6 +100,47 @@ export const SUBAGENT_TOOLS: readonly string[] = [
   "intercom",
 ];
 
+/**
+ * pi-subagents' CHILD-side engine tools. `structured_output` and `contact_supervisor` register
+ * only inside spawned child sessions (the env-keyed prompt-runtime registration — never in
+ * parents, so those names are inert in every gated parent session; `setActiveTools` ignores
+ * unknown names). `subagent_wait` is ALSO registered by the top-level parent extension
+ * (pi-subagents 0.45.1's `registerWaitTool`) — the accepted widening: a wait-only,
+ * non-repo-mutating tool active in gated parents. A gated ADOPTED child (mode inherited via the
+ * `adopt` arm, contracts.md §8.3) must keep them active:
+ *  - `structured_output` is the engine-REQUIRED completion call when the launch carries an
+ *    `outputSchema` — stripping it makes the child physically unable to finish and fails the
+ *    run with `structuredOutputFailed`;
+ *  - `contact_supervisor` is the child→parent intercom door;
+ *  - `subagent_wait` is the fanout-child wait door.
+ * None mutates the repo (`structured_output` writes only the engine's capture file under
+ * `.pi-subagents/` scratch). Census decision, recorded: these names deliberately join NEITHER
+ * PERK_TOOLS nor BORROWED_TOOLS — the stage-filter universe never sees them because children
+ * are stage-unscoped by design (adopt never impersonates a stage), so gate membership is their
+ * only governance surface.
+ */
+export const SUBAGENT_CHILD_TOOLS: readonly string[] = [
+  "structured_output",
+  "contact_supervisor",
+  "subagent_wait",
+];
+
+/**
+ * @ff-labs/pi-fff's search tools. BOTH mode name-sets are enumerated (static names, inert
+ * when absent — the code_search version-tolerance precedent): warm sessions run pi-fff's
+ * default tools-and-ui mode (fffind/ffgrep [+ fff-multi-grep when enabled upstream]);
+ * perk cold launches inject PI_FFF_MODE=override, where FFF registers under the builtin
+ * names find/grep (already allowlisted/pass-through) plus multi_grep. All register at
+ * load time. Frecency/history state lives under ~/.pi/agent/fff/ — outside the worktree
+ * (the fetch_content cache-write precedent), so the read-only bar holds.
+ */
+export const FFF_SEARCH_TOOLS: readonly string[] = [
+  "fffind",
+  "ffgrep",
+  "fff-multi-grep",
+  "multi_grep",
+];
+
 /**
  * The enumerated borrowed-package tool census (contracts.md §8.40): every foreign tool name perk
  * wires — via `BORROWED_PACKAGES`, a provider package, or the linear issue backend — joins the
@@ -115,16 +157,27 @@ export const SUBAGENT_TOOLS: readonly string[] = [
  *    stage set over a foreign restriction. Pre-existing interplay, recorded, not re-engineered.
  *  - Zero-tool packages: @tombell/pi-diff (commands only), the footer providers, and the hunk
  *    review CLI (not a Pi package) register nothing — nothing to enumerate.
- *  - Single-governance rule: `ask_user_question` must stay OUT of this census — the
- *    @juicesharp/rpiv-ask-user-question provider registers the IDENTICAL name perk does, so the
- *    name-keyed PERK_TOOLS entry already governs both registrations (hygiene-tested).
+ *  - Single-governance rule: a name is governed ONCE — it lives in exactly one census. perk
+ *    registers no same-named `ask_user_question` anymore (the first-party tool is deleted), so
+ *    the name lives HERE, in the borrowed census, not in PERK_TOOLS (hygiene-tested).
+ *    Registration timing nuance: @juicesharp/rpiv-ask-user-question registers the tool at load
+ *    time, then a `hasUI`-keyed reconcile strips/restores it — headless sessions carry no
+ *    `ask_user_question` schema at all.
+ *  - @ff-labs/pi-fff (FFF_SEARCH_TOOLS): registration timing load-time (both modes); no
+ *    `setFooter` (only a keyed optional-chained `setStatus`); zero bundled skills.
  */
 export const BORROWED_TOOLS: readonly string[] = [
   ...WEB_RESEARCH_TOOLS,
   ...LINEAR_READ_TOOLS,
   ...LINEAR_MUTATING_TOOLS,
   ...SUBAGENT_TOOLS,
-  "todo", // @juicesharp/rpiv-todo (the juicesharp-todo provider) — load-time
+  ...FFF_SEARCH_TOOLS,
+  // @juicesharp/rpiv-todo (required borrow) — registers at load; its checklist overlay is
+  // `hasUI`-gated (headless-safe).
+  "todo",
+  // @juicesharp/rpiv-ask-user-question (required borrow) — registers at load; strips itself
+  // headlessly (!hasUI reconcile).
+  "ask_user_question",
   // @plannotator/pi-extension: perk never drives its plan phases (the adapter bridges
   // `plan_review` to its event API), so the submit tool is dead weight in stage sessions.
   "plannotator_submit_plan",
@@ -167,23 +220,55 @@ export const READ_ONLY_TOOLS = [
   // The borrowed research families (extracted to family constants; set + order byte-identical).
   ...WEB_RESEARCH_TOOLS,
   ...LINEAR_READ_TOOLS,
-  // The delegation carve-in: the gated objective-plan seed/guidance names the
-  // `perk.objective-explorer` spawn, so `subagent`/`wait` (+ the parent supervisor pair, which
-  // already leaks active into cold-door gated sessions via late registration — keeping
-  // warm-entered gates consistent, and letting the parent answer child `contact_supervisor`
-  // asks) must be reachable while gated. ACCEPTED LENIENCY, deliberately documented: spawned
-  // children are unscoped by design (§8.40 adopt-never-impersonates). The explorer's agent def
-  // is structurally write-blocked (`tools: read, grep, find, ls, bash` frontmatter in
-  // agents/objective-explorer.md), but the `subagent` tool itself can spawn ad-hoc read-write
+  // FFF local search belongs in read-only exploration (the override names find/grep are
+  // already present above; these are the additive tools-and-ui names + multi_grep).
+  ...FFF_SEARCH_TOOLS,
+  // The delegation carve-in: `subagent`/`wait` (+ the parent supervisor pair, which already
+  // leaks active into cold-door gated sessions via late registration — keeping warm-entered
+  // gates consistent, and letting the parent answer child `contact_supervisor` asks) stay
+  // reachable while gated for the other delegation flows (the gated objective-plan guidance now
+  // names the `explore_objective_node` tool below, not a direct spawn). ACCEPTED LENIENCY,
+  // deliberately documented: spawned children are unscoped by design (§8.40
+  // adopt-never-impersonates), and the `subagent` tool itself can spawn ad-hoc read-write
   // children — a posture choice with NO agent-allowlist backstop, consistent with the arg-blind
   // `curl`/`agent-browser` precedents (contracts.md §8.3).
   ...SUBAGENT_TOOLS,
+  // The explorer-wave carve-in: the gated objective-plan session's OPTIONAL explore step is the
+  // `explore_objective_node` tool — it spawns the read-only `perk.objective-explorer` child over
+  // the already-carved-in SUBAGENT tools (the draft-review-wave precedent) and writes nothing to
+  // the worktree.
+  "explore_objective_node",
+  // The child-side carve-in: gated adopt-children must keep the engine's injected tools — see
+  // SUBAGENT_CHILD_TOOLS.
+  ...SUBAGENT_CHILD_TOOLS,
+  // The draft-review-door carve-in: plan-authoring sessions run GATED, so the
+  // /plan-review-browser companions must be reachable while read-only. `push_annotations` only
+  // POSTs findings to the door-primed local plannotator server (no worktree writes — the
+  // fetch_content cache-write precedent class); the wave pair spawns the read-only
+  // `perk.draft-reviewer` over the already-carved-in SUBAGENT_TOOLS/SUBAGENT_CHILD_TOOLS.
+  "push_annotations",
+  "start_draft_review_wave",
+  "collect_draft_review_wave",
+  // The audit-wave carve-in: the seeded `perk-dev audit judge` session runs GATED (the `audit`
+  // stage is read-only), so `run_audit_wave` must be reachable while read-only. Its one write
+  // (`<bundle>/verdicts.json`) is structurally bound to the cold door's workflow-state
+  // `audit_bundle_dir` — the tool takes NO parameters, so no caller-supplied path exists and a
+  // gated session cannot aim the writer anywhere (contracts.md §8.50).
+  "run_audit_wave",
+  // The harvest-wave carve-in: the seeded learn-harvest session runs GATED (the read-only
+  // objective-author borrow), so `run_harvest_wave` must be reachable while read-only. Its
+  // manifest read is structurally bound to the session's claimed run-scoped scratch path (the
+  // `manifest_path` param is verified against it and any other path refused — the
+  // `run_audit_wave` no-aimable-writer posture, read-side), it spawns the read-only
+  // `perk.harvest-analyst` over the already-carved-in SUBAGENT_TOOLS/SUBAGENT_CHILD_TOOLS, and
+  // it writes nothing to the worktree (contracts.md §8.48).
+  "run_harvest_wave",
 ];
 
 /**
  * Every tool perk itself registers (contracts.md §8.40). Name-keyed: `setActiveTools` ignores
- * unknown names, so a vacated registration (e.g. `ask_user_question` under a foreign
- * `[providers] askuser` selection registers the IDENTICAL name) or an absent tool is inert.
+ * unknown names, so an absent tool is inert (e.g. a borrowed census name whose package stripped
+ * or never registered it — `ask_user_question` in a headless session — has nothing to enable).
  * Stage scoping filters the scoped universe `PERK_TOOLS ∪ BORROWED_TOOLS` — builtins and
  * un-enumerated foreign names pass through untouched (fail-open).
  */
@@ -199,21 +284,46 @@ export const PERK_TOOLS: readonly string[] = [
   "gist_draft",
   "gist_save",
   "learn",
-  "ask_user_question",
+  "run_learn_wave",
+  "run_audit_wave",
+  "run_harvest_wave",
   "land",
   "post_pr_review",
   "ready",
-  "resolve_review_threads",
+  "classify_review_feedback",
+  "finalize_address",
+  "explore_objective_node",
+  "run_pr_review_wave",
+  "run_pr_review_dynamic_wave",
   "submit_pr_review",
+  "start_review_wave",
+  "collect_review_wave",
+  "push_annotations",
+  "start_draft_review_wave",
+  "collect_draft_review_wave",
   "run_ci",
   "submit",
+  // The stacked-delivery warm surface (contracts.md §8.51/§8.56): read + control tools over
+  // the cold `objective stack` workers. Never in READ_ONLY_TOOLS — sync/adopt/recover/land
+  // mutate published branches and PRs; the gated posture is the driving commands' soft
+  // refusal.
+  "objective_stack_status",
+  "objective_stack_sync",
+  "objective_stack_adopt",
+  "objective_stack_recover",
+  "objective_stack_land",
 ];
 
 /**
- * The research bundle EVERY stage list carries: web research + Linear reads are useful in every
- * stage session (authoring and worktree alike) and mutate nothing.
+ * The universal non-mutating bundle EVERY stage list carries: web research + Linear reads +
+ * FFF local search are useful in every stage session (authoring and worktree alike) and
+ * mutate nothing (FFF's frecency state lives under ~/.pi/agent/fff/, outside the worktree).
  */
-const RESEARCH_TOOLS: readonly string[] = [...WEB_RESEARCH_TOOLS, ...LINEAR_READ_TOOLS];
+const RESEARCH_TOOLS: readonly string[] = [
+  ...WEB_RESEARCH_TOOLS,
+  ...LINEAR_READ_TOOLS,
+  ...FFF_SEARCH_TOOLS,
+];
 
 /**
  * The PR-loop family shared by ALL FIVE worktree stages (implement/submit/address/land/learn) —
@@ -223,7 +333,7 @@ const RESEARCH_TOOLS: readonly string[] = [...WEB_RESEARCH_TOOLS, ...LINEAR_READ
  * the post-land reconcile drive — `/land` auto-drives `/objective-reconcile` in-session, whose
  * guidance names the reconcile trio, so the trio must be active in every worktree stage). The
  * headless worker also REQUIRES the model-invoked `submit` (implement) /
- * `resolve_review_threads` (address) to reach its completion bar. Borrowed additions: delegation
+ * `finalize_address` (address) to reach its completion bar. Borrowed additions: delegation
  * (SUBAGENT_TOOLS — the `/pr-review`/`/address`/`/submit`-conflict/`/learn` orchestration flows)
  * and `todo` (the foreign checklist overlay the implement-progress discipline rides) are
  * worktree-family only.
@@ -235,15 +345,35 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
   "run_ci",
   "land",
   "learn",
-  "resolve_review_threads",
+  "run_learn_wave",
+  "classify_review_feedback",
+  "finalize_address",
   "post_pr_review",
+  "run_pr_review_wave",
+  "run_pr_review_dynamic_wave",
   "submit_pr_review",
+  // The human review doors' companion tools (/pr-review-terminal, /pr-review-browser): the
+  // review-wave pair + the door-primed annotation push. The plan-stage widening landed via the
+  // draft-review door (/plan-review-browser): the plan-family stage lists carry the draft-wave
+  // pair + push_annotations.
+  "start_review_wave",
+  "collect_review_wave",
+  "push_annotations",
   // The reconcile trio: `/land` auto-drives the objective-reconcile pass inside the CURRENT
   // worktree session (driveReconcileAfterLand), and the manual `/objective-reconcile` gesture is
   // registered globally — both inject guidance naming these three tools.
   "reconcile_objective",
   "add_objective_node",
   "objective_node",
+  // The stacked-delivery quintet: `/objective-sync`/`/objective-recover`/`/objective-land`
+  // drive worktree sessions (post-amend sync from implement/address; recovery and the atomic
+  // landing from anywhere in the PR loop), so their guidance-named tools must be active
+  // across the whole family.
+  "objective_stack_status",
+  "objective_stack_sync",
+  "objective_stack_adopt",
+  "objective_stack_recover",
+  "objective_stack_land",
   ...RESEARCH_TOOLS,
   ...SUBAGENT_TOOLS,
   "todo",
@@ -253,7 +383,8 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
  * Per-stage active perk tools for gate-OFF sessions (contracts.md §8.40). Keys = the registry
  * stage ids; an unknown/absent stage id is fail-open (no filtering — version-skew safety).
  * Rationale pins:
- *  - `ask_user_question` is universal (every stage list carries it).
+ *  - `ask_user_question` is universal (every stage list carries it); the name is BORROWED now
+ *    (the @juicesharp questionnaire, via BORROWED_TOOLS — headless sessions carry no schema).
  *  - `plan`/`save` cover the plan-family stage borrowers (`plan from`/`plan replan`/
  *    `learn docs`/`learn code` borrow `plan`; `skills create/refine` borrow `save`).
  *  - `objective-author`/`objective-save` cover `objective replan` + `objective author --from`.
@@ -263,6 +394,12 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
  *    three objective stages (the post-save `/objective-reconcile` gesture) AND the worktree
  *    family (the post-land `driveReconcileAfterLand` drive + the manual `/objective-reconcile`
  *    gesture — its guidance names all three).
+ *  - the draft-review companions (`start_draft_review_wave`/`collect_draft_review_wave`/
+ *    `push_annotations`) also ride the two objective stages (§8.23's
+ *    `/objective-review-browser` — gate-OFF coverage: after `objectiveApprovalSave` exits the
+ *    gate mid-flow, late collects/pushes must not dead-end), and `plan_review` rides them
+ *    because the door guidance names it (in both objective stages it routes to the objective
+ *    review arm; the drive-coverage guard forces both the moment the guidance names them).
  */
 export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
   "gist-author": ["ask_user_question", "gist_draft", "gist_save", ...RESEARCH_TOOLS],
@@ -274,6 +411,13 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "reconcile_objective",
     "add_objective_node",
     "objective_node",
+    // The /objective-review-browser companions (gate-OFF coverage: after objectiveApprovalSave
+    // exits the gate mid-flow, late collects/pushes must not dead-end) + plan_review (the door
+    // guidance names it; it routes to the objective review arm here).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
+    "plan_review",
     ...RESEARCH_TOOLS,
   ],
   "objective-save": [
@@ -283,6 +427,11 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "reconcile_objective",
     "add_objective_node",
     "objective_node",
+    // The /objective-review-browser companions + plan_review (see the objective-author note).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
+    "plan_review",
     ...RESEARCH_TOOLS,
   ],
   "objective-plan": [
@@ -291,17 +440,48 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "plan_review",
     "plan_save",
     "objective_node",
+    "explore_objective_node",
     "reconcile_objective",
     "add_objective_node",
+    // The /plan-review-browser companions (gate-OFF coverage: after approvalSave exits the gate
+    // mid-flow, late collects/pushes must not dead-end — the drive-coverage guard forces this
+    // the moment the guidance names them).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
+    ...RESEARCH_TOOLS,
+  ],
+  plan: [
+    "ask_user_question",
+    "plan_draft",
+    "plan_review",
+    "plan_save",
+    // The /plan-review-browser companions (see the objective-plan note).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
+    ...RESEARCH_TOOLS,
+  ],
+  save: [
+    "ask_user_question",
+    "plan_draft",
+    "plan_review",
+    "plan_save",
+    // The /plan-review-browser companions (see the objective-plan note).
+    "start_draft_review_wave",
+    "collect_draft_review_wave",
+    "push_annotations",
     ...RESEARCH_TOOLS,
   ],
-  plan: ["ask_user_question", "plan_draft", "plan_review", "plan_save", ...RESEARCH_TOOLS],
-  save: ["ask_user_question", "plan_draft", "plan_review", "plan_save", ...RESEARCH_TOOLS],
   implement: WORKTREE_STAGE_TOOLS,
   submit: WORKTREE_STAGE_TOOLS,
   address: WORKTREE_STAGE_TOOLS,
   land: WORKTREE_STAGE_TOOLS,
   learn: WORKTREE_STAGE_TOOLS,
+  // The dev-only session-audit orchestrator (`perk-dev audit judge`). The session runs GATED
+  // (read-only mode), where this list is inert; it exists for the keys≡registry pin and the
+  // defensive gate-off arm.
+  audit: ["ask_user_question", "run_audit_wave", ...RESEARCH_TOOLS],
 };
 
 /** The read-only marker / custom-message type injected into context while active. */

package/extension/substrate/workflowState.ts

@@ -33,6 +33,12 @@ export interface WorkflowState {
   mode?: string;
   /** The registry stage id this run is acting on (recorded at cold claim from the handoff). */
   stage?: string;
+  /**
+   * The running @mgiles/perk version stamped when run identity is established (§8.3) —
+   * claim/fork/adopt/mint in session_start. The session-audit vintage layer's exact basis;
+   * omitted when only the perkVersion() failure sentinel is available. Best-effort tier.
+   */
+  perk_version?: string;
   predecessor?: string;
   active_plan_ref?: PlanRef | null;
   active_objective?: string | null;

package/extension/surfaces/footerProvider.ts

@@ -1,16 +1,16 @@
-// The footer provider seam (INSTALL-SITE / runtime vacating). The footer is the SECOND interface
-// seam (no durable artifact to bridge), mirroring askuser but with a different vacating mechanism:
+// The footer provider seam (INSTALL-SITE / runtime vacating). The footer is an interface
+// seam (no durable artifact to bridge) with a runtime vacating mechanism:
 // perk installs its own footer (`installPerkFooter`) inside `index.ts`'s `session_start` event
 // handler, so under a foreign `[providers] footer` selection perk simply does NOT call
 // `installPerkFooter` — a runtime guard at that single install site, keyed off `ctx.cwd`. That
 // leaves the foreign footer (`pi-powerline-footer` or `pi-bar`) as the sole footer surface;
-// perk's objective/checkpoints progress still reaches it automatically via the already-publishing
-// composed `perk` `setStatus` slot (both foreign footers render extension statuses), so the
+// perk's objective progress still reaches it automatically via the already-publishing
+// single-value `perk` `setStatus` slot (both foreign footers render extension statuses), so the
 // adapter is vacate-only (`adapter: null`, no shim, no injected context).
 //
 // This module reads config (via `resolveProviders`/`loadPerkConfig`) so it does NOT belong in the
 // dependency-free `surfaces.ts`; it contains no rich-UI calls, so `surfacesGuard.test.ts` passes
-// it cleanly. Mirror of `askUser.ts`'s `resolvedAskUserProviderId` / `isPerkAskUserReferenceSelected`.
+// it cleanly. Mirror of `planMode.ts`'s `resolvedPlanProviderId` / `isPerkPlanReferenceSelected`.
 
 import { loadPerkConfig } from "../substrate/config.ts";
 import {
@@ -22,7 +22,7 @@ import {
 /**
  * The resolved `[providers] footer` selection id for `cwd`. Fail-safe to the perk-footer
  * reference: any load/resolution failure returns the reference id so perk keeps installing its
- * own footer — the default path is the hard guarantee. Mirror of `resolvedAskUserProviderId`: the
+ * own footer — the default path is the hard guarantee. Mirror of `resolvedPlanProviderId`: the
  * catch narrows to genuine file-read/parse failures (the resolver is per-seam fail-open) and is
  * logged, never silent.
  */