@mgiles/perk 2.1.0 → 2.3.0

package/extension/factories/planReview.ts

@@ -19,7 +19,12 @@
 // `plan_draft` redirect). An APPROVED outcome (either backend) wires into the shared
 // `approvalSave` seam (planSave.ts): auto-save → D1a gate exit → terminating result,
 // node link recovered from the `objective_node_claim` carrier inside `savePlan`. A DENY returns
-// feedback and directs a `plan_draft` rewrite + re-review. Strict on deny, FAIL-OPEN everywhere
+// feedback and directs a `plan_draft` rewrite + re-review. Plannotator's browser "Direct Edits"
+// (a `# Direct Edits` unified diff opening the feedback) are handled asymmetrically per arm: the
+// PLAN arm mechanically applies an approved diff (strict apply → draft write-back → save the
+// edited bytes; any failure falls open to the verbatim save + a loud warning); the OBJECTIVE arm
+// cannot fold rendered-markdown edits into the structured draft, so an approve-with-edits SKIPS
+// the save and returns one model-mediated revise round; DENY stays model-mediated on both arms. Strict on deny, FAIL-OPEN everywhere
 // else: headless / dismissed (Esc anywhere = skip, mirroring ask_user_question's dismissal — deny
 // is always explicit) / backend-unavailable all soft-skip so plan authoring never wedges — those
 // arms keep the present-the-plan + human-`/plan-save` discipline (the manual failsafe).
@@ -40,6 +45,12 @@
 // exit → a TERMINATING result; a failed save is non-terminating, leaves the gate read-only, and
 // directs the human `/objective-save` failsafe.
 //
+// THE GIST ARM: a gist-author session (read-only, stage `gist-author`) routes through
+// `executeGistReview` the same way — the reviewed bytes are the RENDERED gist draft
+// (`readGistDraft` + `renderGistDraft`, gistDraft.ts), first-party VIEW-ONLY, implement-here
+// never offered, APPROVED → the `gistApprovalSave` seam (gistSave.ts), no draft soft-skips with
+// `reason: "no_gist_draft"`.
+//
 // INVARIANTS HELD: never calls `setActiveTools`, never registers a `tool_call` handler, never
 // restamps `cache.plan-ref.provider`. The door composes the gate AND the save EXCLUSIVELY
 // through the `approvalSave` seam (Invariant 1: composes, never owns).
@@ -48,12 +59,18 @@ import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   createPlannotatorBridge,
+  extractDirectEdits,
+  hasDirectEditsHeading,
   isPlannotatorPlanSelected,
 } from "../adapters/planAdapterPlannotator.ts";
 import type { Result } from "../substrate/result.ts";
 import type { ToolGating } from "../substrate/toolGating.ts";
 import { paramsOf, stringParam } from "../substrate/toolParams.ts";
+import { applyUnifiedDiff } from "../substrate/unifiedDiff.ts";
 import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { GIST_AUTHOR_STAGE } from "./gistAuthor.ts";
+import { readGistDraft, renderGistDraft } from "./gistDraft.ts";
+import { type GistApprovalSaveOutcome, gistApprovalSave } from "./gistSave.ts";
 import { implementHereExit, implementHereGuidance } from "./implementHere.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
 import { readObjectiveDraft, renderObjectiveDraft } from "./objectiveDraft.ts";
@@ -131,6 +148,17 @@ const OBJECTIVE_SUBJECT: ReviewSubject = {
   noSourceError: "no objective draft resolved",
 };
 
+const GIST_SUBJECT: ReviewSubject = {
+  noun: "gist",
+  present: "the complete gist to the user",
+  presentUnavailable: "the complete gist to the user",
+  implementHereWhere: "on the gist path",
+  draftTool: "gist_draft",
+  failsafeCmd: "/gist-save",
+  detailsExtra: { subject: "gist" },
+  noSourceError: "no gist draft resolved",
+};
+
 const SKIP_TEXT =
   "no interactive review surface available — present the complete plan to the user in your next message.";
 
@@ -244,16 +272,19 @@ type SubjectSaveOutcome =
  * (propagating the seam's `terminate: true` intent); a failed save is non-terminating, leaves
  * the gate read-only, and directs the human manual failsafe. Reviewer feedback is surfaced
  * loudly as implementation guidance — the approved bytes were saved verbatim, never post-edited.
- * The `paramMismatch`/`edited` opts are plan-arm-only (their literals name "plan"/"draft"): the
- * objective delegator never passes opts, so the suffixes render empty and `edited` never reaches
- * its details. The `no-source` arm is defensively unreachable (the reviewed source is always
+ * The `paramMismatch`/`edited`/`directEditsFailed` opts are plan-arm-only (their literals name
+ * "plan"/"draft"): the objective delegator never passes opts, so the suffixes render empty and
+ * `edited` never reaches its details. `directEditsFailed` (plannotator-only) flags that a Direct
+ * Edits section was seen but could not be honored — the saved arm gains a loud warning that the
+ * plan was saved WITHOUT the reviewer's edits, and details carry `direct_edits_applied: false`.
+ * The `no-source` arm is defensively unreachable (the reviewed source is always
  * non-blank) but maps to the save-failed shape rather than throwing.
  */
 function approvedSubjectSaveResult(
   subject: ReviewSubject,
   outcome: Extract<ReviewOutcome, { status: "completed" }>,
   save: SubjectSaveOutcome,
-  opts?: { paramMismatch?: boolean; edited?: boolean },
+  opts?: { paramMismatch?: boolean; edited?: boolean; directEditsFailed?: boolean },
 ): ToolResult {
   const feedback = outcome.feedback
     ? `\n\nReviewer feedback (implementation guidance — the approved ${subject.noun} was saved ` +
@@ -266,6 +297,7 @@ function approvedSubjectSaveResult(
     feedback: outcome.feedback ?? null,
     ...subject.detailsExtra,
     ...(opts?.edited === true ? { edited: true } : {}),
+    ...(opts?.directEditsFailed === true ? { direct_edits_applied: false } : {}),
   };
   if (save.status === "saved") {
     const saveText = save.result.content[0]?.text ?? "";
@@ -275,11 +307,17 @@ function approvedSubjectSaveResult(
       opts?.paramMismatch === true
         ? "\n\n⚠ differing plan param ignored — the validated draft was reviewed and saved."
         : "";
+    const editsWarning =
+      opts?.directEditsFailed === true
+        ? "\n\n⚠ WARNING: the reviewer's Direct Edits could NOT be auto-applied — the plan was " +
+          "saved WITHOUT them. The diff remains in the reviewer feedback above; apply it to the " +
+          "plan issue manually or via a follow-up."
+        : "";
     return {
       content: [
         {
           type: "text",
-          text: `${subject.noun} APPROVED by reviewer.${feedback}\n\n${saveText}${edited}${mismatch}`,
+          text: `${subject.noun} APPROVED by reviewer.${feedback}\n\n${saveText}${edited}${mismatch}${editsWarning}`,
         },
       ],
       // `ok` sits per-branch, NOT in `base` — `base` is spread into the fail branch too.
@@ -323,13 +361,15 @@ function approvedSubjectSaveResult(
 /**
  * Map an APPROVED review outcome + the `approvalSave` outcome into the model-facing tool result
  * (exported for the offline tests) — the plan flavor of `approvedSubjectSaveResult`. `edited`
- * (first-party only) flags that human edits were written back to the draft pre-verdict, so the
- * saved bytes carry them.
+ * flags that human edits were written back to the draft pre-verdict (the first-party editor, or
+ * the plannotator Direct Edits auto-apply), so the saved bytes carry them. `directEditsFailed`
+ * (plannotator-only, optional — absent keeps every existing call site byte-stable) flags a
+ * Direct Edits section that could not be honored: the plan saved verbatim, a loud warning added.
  */
 export function approvedSaveResult(
   outcome: Extract<ReviewOutcome, { status: "completed" }>,
   save: ApprovalSaveOutcome,
-  opts: { paramMismatch: boolean; edited?: boolean },
+  opts: { paramMismatch: boolean; edited?: boolean; directEditsFailed?: boolean },
 ): ToolResult {
   return approvedSubjectSaveResult(
     PLAN_SUBJECT,
@@ -535,7 +575,12 @@ export function approvedObjectiveSaveResult(
  * the transcript). First-party reviews run VIEW-ONLY (edits are never written back;
  * deny+feedback is the change channel). An APPROVED outcome wires into the
  * `objectiveApprovalSave` seam (re-read the STRUCTURED artifact → `saveObjective` → D1a gate
- * exit → terminating); every other outcome maps via `objectiveReviewOutcomeResult`.
+ * exit → terminating); every other outcome maps via `objectiveReviewOutcomeResult`. ONE
+ * carve-out (plannotator only): an approval whose feedback opens a Direct Edits section SKIPS
+ * the save — rendered-markdown edits cannot be folded back into the structured draft
+ * mechanically — and returns a NON-terminating revise round with the gate untouched (fold the
+ * diff in via `objective_draft`, re-review to confirm); perk never saves an objective the
+ * reviewer explicitly edited away from.
  */
 export async function executeObjectiveReview(
   pi: ExtensionAPI,
@@ -576,6 +621,42 @@ export async function executeObjectiveReview(
   let outcome: ReviewOutcome;
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     outcome = await bridge.review(rendered, sig);
+    // APPROVE + Direct Edits (browser edits of the RENDERED markdown), checked BEFORE the
+    // approved-save routing (the approved-first discipline): the save seam re-reads the
+    // STRUCTURED artifact, so rendered-markdown edits — roadmap-table rows included — cannot be
+    // folded back without model judgment. Skip the save, keep the gate read-only, and route ONE
+    // revise round: the model folds the diff into `objective_draft`, then re-reviews to confirm.
+    // The heading check suffices (extraction success is irrelevant here — the diff goes to the
+    // model verbatim either way).
+    if (
+      outcome.status === "completed" &&
+      outcome.approved &&
+      outcome.feedback !== undefined &&
+      hasDirectEditsHeading(outcome.feedback)
+    ) {
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "objective APPROVED with direct browser edits — these cannot be auto-applied to " +
+              "the structured draft, so nothing was saved. Fold the Direct Edits diff below into " +
+              "the working draft with objective_draft (prose hunks → the prose; roadmap-table " +
+              "hunks → the matching node fields), then call plan_review again to confirm.\n\n" +
+              `Reviewer feedback:\n${outcome.feedback}`,
+          },
+        ],
+        details: {
+          ok: true,
+          status: "revise",
+          reason: "direct_edits",
+          approved: true,
+          feedback: outcome.feedback,
+          reviewId: outcome.reviewId,
+          subject: "objective",
+        },
+      };
+    }
   } else {
     const fp = await runFirstPartyReview({
       ui: ctx.ui,
@@ -599,6 +680,111 @@ export async function executeObjectiveReview(
   return objectiveReviewOutcomeResult(outcome);
 }
 
+// ------------------------------------------------------------------------ the gist review arm
+
+const GIST_REVIEW_EDITOR_TITLE =
+  "Gist review (view only — edits are not saved) — Enter: continue to verdict · Esc: skip · " +
+  "Ctrl+G: $EDITOR";
+
+/**
+ * Map a non-approved gist review outcome into the model-facing tool result (exported for the
+ * offline tests) — the gist-flavored sibling of `objectiveReviewOutcomeResult`, delegating to
+ * `subjectReviewOutcomeResult` with `GIST_SUBJECT`. Every arm carries `details.subject: "gist"`;
+ * the texts redirect to `gist_draft` / `/gist-save`. The execute path routes approved outcomes
+ * to `approvedGistSaveResult` first, so `completed` renders DENIED here.
+ */
+export function gistReviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
+  return subjectReviewOutcomeResult(GIST_SUBJECT, outcome);
+}
+
+/**
+ * Map an APPROVED gist review outcome + the `gistApprovalSave` outcome into the model-facing
+ * tool result (exported for the offline tests) — the gist sibling of
+ * `approvedObjectiveSaveResult`, delegating to `approvedSubjectSaveResult` with `GIST_SUBJECT`
+ * and no opts (the gist path reviews only the rendered draft, view-only — no
+ * `paramMismatch`/`edited`).
+ */
+export function approvedGistSaveResult(
+  outcome: Extract<ReviewOutcome, { status: "completed" }>,
+  save: GistApprovalSaveOutcome,
+): ToolResult {
+  return approvedSubjectSaveResult(
+    GIST_SUBJECT,
+    outcome,
+    save.status === "no-draft" ? { status: "no-source" } : save,
+  );
+}
+
+/**
+ * The gist review arm, mirroring `executeObjectiveReview`'s shape with the rendered gist draft
+ * as the SOLE review source (never the `plan` param, never the transcript). First-party reviews
+ * run VIEW-ONLY (edits are never written back; deny+feedback is the change channel); the
+ * implement-here verdict is never offered (a gist is not implementable — it has no strategy).
+ * An APPROVED outcome wires into the `gistApprovalSave` seam (re-read the artifact → `saveGist`
+ * → D1a gate exit → terminating); every other outcome maps via `gistReviewOutcomeResult`.
+ */
+export async function executeGistReview(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  bridge: { review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome> },
+  signal?: AbortSignal,
+): Promise<ToolResult> {
+  // 1. Headless → soft skip (fail-open; never wedges CI/supervisor runs on an interactive UI).
+  if (!ctx.hasUI) return skipResult();
+  // 2. The draft artifact is the sole review source — no draft → soft skip with the gist_draft
+  //    redirect.
+  const draft = readGistDraft(ctx);
+  if (draft === null) {
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            "no gist draft to review — write the working gist with gist_draft (the " +
+            "statement-of-intent prose), then call plan_review again.",
+        },
+      ],
+      details: {
+        ok: false,
+        error: "no gist draft to review — write it with gist_draft first",
+        error_type: "no_gist_draft",
+        status: "skipped",
+        reason: "no_gist_draft",
+      },
+    };
+  }
+  // 3. The reviewed bytes are the RENDERED markdown (title + scope + prose) — never raw JSON.
+  const rendered = renderGistDraft(draft);
+  // 4. Backend dispatch (mirrors the objective path): plannotator-selected → the bridge; ANY
+  //    other selection → the first-party editor, view-only.
+  const sig = signal ?? ctx.signal;
+  let outcome: ReviewOutcome;
+  if (isPlannotatorPlanSelected(ctx.cwd)) {
+    outcome = await bridge.review(rendered, sig);
+  } else {
+    const fp = await runFirstPartyReview({
+      ui: ctx.ui,
+      plan: rendered,
+      writeDraft: () => true, // unreachable under viewOnly — the branch is skipped
+      signal: sig,
+      editorTitle: GIST_REVIEW_EDITOR_TITLE,
+      verdicts: verdictsFor(GIST_SUBJECT),
+      viewOnly: true,
+    });
+    outcome = fp.outcome;
+  }
+  // 5. An APPROVED decision (either backend) wires into the gistApprovalSave seam (the artifact
+  //    is re-read at save time — never the rendered bytes; auto-save → D1a gate exit →
+  //    terminating result); everything else maps via gistReviewOutcomeResult. Approved-first
+  //    routing: gistReviewOutcomeResult's completed case renders DENIED.
+  if (outcome.status === "completed" && outcome.approved) {
+    const save = await gistApprovalSave(pi, ctx, gating);
+    return approvedGistSaveResult(outcome, save);
+  }
+  return gistReviewOutcomeResult(outcome);
+}
+
 // ------------------------------------------------------------------------- the execute core
 
 /**
@@ -641,9 +827,14 @@ export async function executePlanReview(
   }
   // 1. Objective-author session → the objective review arm: the rendered
   //    objective draft is the sole review source; a well-typed `plan` param is ignored here.
-  if (rebuildWorkflowState(branchOf(ctx)).stage === OBJECTIVE_AUTHOR_STAGE) {
+  //    A gist-author session likewise routes to the gist arm (the rendered gist draft).
+  const launchedStage = rebuildWorkflowState(branchOf(ctx)).stage;
+  if (launchedStage === OBJECTIVE_AUTHOR_STAGE) {
     return executeObjectiveReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
   }
+  if (launchedStage === GIST_AUTHOR_STAGE) {
+    return executeGistReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
+  }
   // 2. Headless → soft skip (fail-open; never wedges CI/supervisor runs on an interactive UI).
   if (!ctx.hasUI) return skipResult();
   // 3. File-first resolution: artifact → param, NEVER transcript — an approval
@@ -674,8 +865,34 @@ export async function executePlanReview(
   let outcome: ReviewOutcome;
   let reviewedPlan = src.plan;
   let edited = false;
+  let directEditsFailed = false;
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     outcome = await bridge.review(src.plan, sig);
+    // APPROVE + Direct Edits (browser plan edits, contracts.md §8.23): mechanically apply the
+    // reviewer's diff to the exact bytes reviewed, write it back to the draft (reviewed bytes ==
+    // artifact bytes == saved bytes — the first-party pre-verdict write-back, replayed here
+    // post-verdict because the bridge only reports the diff), and save the EDITED bytes. Every
+    // rung fails open to the verbatim path: no section → untouched; a heading that cannot be
+    // parsed / applied / written back → verbatim save + a loud warning (never save bytes the
+    // artifact doesn't carry). DENY stays model-mediated — the feedback (diff included) passes
+    // through for the plan_draft rewrite.
+    if (outcome.status === "completed" && outcome.approved && outcome.feedback !== undefined) {
+      const section = extractDirectEdits(outcome.feedback);
+      if (section !== null) {
+        const patched = applyUnifiedDiff(src.plan, section.diff);
+        if (patched !== null && writePlanDraft(pi, ctx, patched).details.ok) {
+          reviewedPlan = patched;
+          edited = true;
+          // The applied diff must NOT survive into the result as "apply these exact changes"
+          // guidance — only the annotation remainder (when any) stays reviewer feedback.
+          outcome = { ...outcome, feedback: section.remainder };
+        } else {
+          directEditsFailed = true;
+        }
+      } else if (hasDirectEditsHeading(outcome.feedback)) {
+        directEditsFailed = true;
+      }
+    }
   } else {
     // The 4th verdict (implement-here, the no-save exit) is offered UNLESS this is an
     // objective-node planning session — a node-linked plan must save (the node advance and
@@ -705,7 +922,11 @@ export async function executePlanReview(
   //    gate exit → terminating result); everything else maps via reviewOutcomeResult.
   if (outcome.status === "completed" && outcome.approved) {
     const save = await approvalSave(pi, ctx, gating, { reviewedPlan });
-    return approvedSaveResult(outcome, save, { paramMismatch: src.paramMismatch, edited });
+    return approvedSaveResult(outcome, save, {
+      paramMismatch: src.paramMismatch,
+      edited,
+      directEditsFailed,
+    });
   }
   return reviewOutcomeResult(outcome);
 }

package/extension/index.ts

@@ -14,17 +14,22 @@ import { registerCheckpoints } from "./checkpoints/checkpoints.ts";
 import { registerAddress } from "./doors/address.ts";
 import { registerAskUser } from "./doors/askUser.ts";
 import { registerCiExecutor } from "./doors/ciExecutor.ts";
+import { registerCommitAndCompact } from "./doors/commitCompact.ts";
 import { registerLand } from "./doors/land.ts";
 import { registerLearn } from "./doors/learn.ts";
 import { CODE_DOOR, DOCS_DOOR, registerLearnFactoryDoor } from "./doors/learnFactory.ts";
 import { registerLifecycleGates } from "./doors/lifecycleGates.ts";
 import { registerPrReview } from "./doors/prReview.ts";
 import { registerPrReviewBrowser } from "./doors/prReviewBrowser.ts";
+import { registerPrReviewDynamic } from "./doors/prReviewDynamic.ts";
 import { registerPrReviewTerminal } from "./doors/prReviewTerminal.ts";
 import { registerReady } from "./doors/ready.ts";
 import { registerSelfcheck } from "./doors/selfcheck.ts";
 import { registerSubmit } from "./doors/submit.ts";
 import { registerSubmitPrReview } from "./doors/submitPrReview.ts";
+import { registerGistAuthor } from "./factories/gistAuthor.ts";
+import { registerGistDraft } from "./factories/gistDraft.ts";
+import { registerGistSave } from "./factories/gistSave.ts";
 import { registerImplementHere } from "./factories/implementHere.ts";
 import { registerObjective } from "./factories/objective.ts";
 import { registerObjectiveAuthor } from "./factories/objectiveAuthor.ts";
@@ -151,6 +156,10 @@ export default function (pi: ExtensionAPI) {
   // Objective-author context injection (the objective mirror of plan mode's authoring
   // half). Keyed off (read-only gate AND stage === objective-author); planMode defers to it.
   registerObjectiveAuthor(pi, gating);
+
+  // Gist-author context injection (the gist mirror). Keyed off (read-only gate AND
+  // stage === gist-author); planMode defers to it too.
+  registerGistAuthor(pi, gating);
   let sharedOk = false;
   try {
     sharedDir();
@@ -457,6 +466,9 @@ export default function (pi: ExtensionAPI) {
   // The `objective_draft` working-objective file tool (the plan_draft twin).
   registerObjectiveDraft(pi);
 
+  // The `gist_draft` working-gist file tool (the third draft carve-out).
+  registerGistDraft(pi);
+
   // The universal `ask_user_question` tool: lets a model interactively ask the human a
   // clarifying question (free-text or multiple-choice). Registered in the factory so it exists
   // before the gate snapshots tools; its name is in READ_ONLY_TOOLS so it survives plan mode.
@@ -484,6 +496,12 @@ export default function (pi: ExtensionAPI) {
   // POSTS its review to the PR (the deliberate departure from /address's read-only-child rule).
   registerPrReview(pi);
 
+  // The EXPERIMENTAL warm `/pr-review-dynamic` door: the selector-driven sibling — angle
+  // selection delegated to a fresh perk.review-angle-selector lane, normalized in
+  // module-rendered code; posting shares /pr-review's post_pr_review + clean guard. The
+  // baseline /pr-review stays canonical; promotion/retire is a later dogfood's call.
+  registerPrReviewDynamic(pi);
+
   // The warm `submit_pr_review` tool: the human-gated curated-posting surface both review
   // doors ride (contracts §8.4) — neither door registers tools of its own.
   registerSubmitPrReview(pi);
@@ -522,10 +540,18 @@ export default function (pi: ExtensionAPI) {
   // (The deterministic objective mechanics live in the Python plane: `perk objective …`.)
   registerObjective(pi, perkStatus);
 
+  // The warm `/commit-and-compact` utility door: drive a commit of the work so far, then
+  // compact the session once HEAD has actually advanced (clean/read-only trees compact
+  // immediately; no commit → compaction skipped, loudly). Human-only — no tool twin.
+  registerCommitAndCompact(pi, gating);
+
   // The warm `objective_save` door: the `objective_save` tool + `/objective-save` command
   // (the objective mirror of plan-save). Takes `gating` for the read-only → read-write boundary.
   registerObjectiveSave(pi, gating);
 
+  // The warm `gist_save` door: the `gist_save` tool + `/gist-save` command (the gist mirror).
+  registerGistSave(pi, gating);
+
   // The objective plan factory's warm transition surface: the `objective_node` bounded
   // tool (delegates to the Python cold door; `status:"done"` requires a completion audit) + the
   // `/objective-plan` command (select the next node and author a bounded plan). The command now

package/extension/substrate/config.ts

@@ -48,14 +48,16 @@ export interface PerkConfig {
   /**
    * The agent-keyed `[models.subagents]` table: a per-agent model override for each perk-owned
    * project agent (`pr-reviewer`, `review-classifier`, `objective-explorer`, `conflict-resolver`,
-   * `learn-analyst`, `adversarial-reviewer`). Each configured
-   * value is injected as a per-call inline `model` override on that agent's `subagent` spawn; when
+   * `learn-analyst`, `adversarial-reviewer`, `review-angle-selector`). Each configured
+   * value is injected as the top-level workflow-level `model` on that agent's one `subagent`
+   * workflowScript call — a default flowing onto every lane, single-child runs included (as
+   * /pr-review does); when
    * a key is absent the agent's frontmatter `model` (in `.pi/agents/<name>.md`) is the default.
    * (`subagents.agentOverrides` does NOT reach project agents — `pi-subagents`'
-   * `applyBuiltinOverrides` applies only to builtins — so this inline override is the mechanism.)
+   * `applyBuiltinOverrides` applies only to builtins — so this inline injection is the mechanism.)
    * A value may carry a `:thinking` suffix (`"anthropic/claude-sonnet-4-5:high"`) or be the
    * `"inherit"` sentinel (child inherits the parent session's model) — both resolved by
-   * pi-subagents on the inline override (the last-colon segment counts as thinking only when it
+   * pi-subagents on the injected value (the last-colon segment counts as thinking only when it
    * is a pi level, so ollama-style tags stay part of the model id).
    * Always-present object; absent keys omitted (mirror of `providers`).
    */
@@ -66,6 +68,7 @@ export interface PerkConfig {
     "conflict-resolver"?: string;
     "learn-analyst"?: string;
     "adversarial-reviewer"?: string;
+    "review-angle-selector"?: string;
   };
   /**
    * Optional `[compaction] objective_threshold` — the context-usage fraction (0,1] that triggers
@@ -294,6 +297,7 @@ const SUBAGENT_KEYS = [
   "conflict-resolver",
   "learn-analyst",
   "adversarial-reviewer",
+  "review-angle-selector",
 ] as const;
 
 /**

package/extension/substrate/git.ts

@@ -75,3 +75,41 @@ export function sinceBaseSha(cwd: string, base: string | null | undefined): stri
   git(cwd, ["fetch", "origin", branch], FETCH_TIMEOUT_MS);
   return git(cwd, ["merge-base", "HEAD", `origin/${branch}`]);
 }
+
+/**
+ * The current HEAD sha. **Fail-open**: null on any failure — not a repo, git missing, or an
+ * unborn HEAD (no commits yet), which callers treat as "no before-point to diff from".
+ */
+export function headSha(cwd: string): string | null {
+  return git(cwd, ["rev-parse", "HEAD"]);
+}
+
+/**
+ * Whether the working tree has anything uncommitted (`git status --porcelain`). Untracked files
+ * count as dirty — deliberate: the model decides whether they belong in a commit. **Fail-open to
+ * null** on any failure (not a repo, git missing) — callers must NOT conflate null with clean.
+ * Own `execFileSync` rather than the `git()` helper: `git()` conflates empty output (a clean
+ * tree — meaningful here) with failure.
+ */
+export function worktreeDirty(cwd: string): boolean | null {
+  try {
+    const out = execFileSync("git", ["status", "--porcelain"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.trim() !== "";
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `git log --oneline <fromSha>..HEAD` listing of commits made since `fromSha` — or every
+ * commit (`git log --oneline HEAD`) when `fromSha` is null (HEAD was unborn at capture time).
+ * **Fail-open**: null on failure or when the range is empty.
+ */
+export function commitsSince(cwd: string, fromSha: string | null): string | null {
+  const range = fromSha === null ? "HEAD" : `${fromSha}..HEAD`;
+  return git(cwd, ["log", "--oneline", range]);
+}

package/extension/substrate/terminalLaunch.ts

@@ -51,7 +51,7 @@ function interactiveShellWrap(
   command: string,
 ): string {
   const shell =
-    env.SHELL !== undefined && env.SHELL.startsWith("/")
+    env.SHELL?.startsWith("/") === true
       ? env.SHELL
       : platform === "darwin"
         ? "/bin/zsh"

package/extension/substrate/toolGating.ts

@@ -99,6 +99,22 @@ export const SUBAGENT_TOOLS: readonly string[] = [
   "intercom",
 ];
 
+/**
+ * @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
@@ -118,12 +134,15 @@ export const SUBAGENT_TOOLS: readonly string[] = [
  *  - 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).
+ *  - @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,
+  ...FFF_SEARCH_TOOLS,
   "todo", // @juicesharp/rpiv-todo (the juicesharp-todo provider) — load-time
   // @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.
@@ -152,6 +171,10 @@ export const READ_ONLY_TOOLS = [
   // working-objective artifact in the session data dir (fixed artifact name, seam-derived
   // path); the gate's edit/write/bash blocking is unchanged.
   "objective_draft",
+  // The gist_draft third of the draft carve-out family: gist_draft writes only the one
+  // working-gist artifact in the session data dir (fixed artifact name, seam-derived path);
+  // the gate's edit/write/bash blocking is unchanged.
+  "gist_draft",
   // The objective_node carve-out: it never touches the worktree — it delegates a bounded,
   // workflow-owned node transition to the canonical Python plane (`perk objective node`). Both
   // objective-plan factory paths run gated (the cold door hands off `mode: read-only`; the warm
@@ -163,6 +186,9 @@ export const READ_ONLY_TOOLS = [
   // The borrowed research families (extracted to family constants; set + order byte-identical).
   ...WEB_RESEARCH_TOOLS,
   ...LINEAR_READ_TOOLS,
+  // 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: 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
@@ -192,22 +218,32 @@ export const PERK_TOOLS: readonly string[] = [
   "reconcile_objective",
   "add_objective_node",
   "objective_draft",
+  "gist_draft",
+  "gist_save",
   "learn",
+  "run_learn_wave",
   "ask_user_question",
   "land",
   "post_pr_review",
   "ready",
   "resolve_review_threads",
+  "run_pr_review_wave",
+  "run_pr_review_dynamic_wave",
   "submit_pr_review",
   "run_ci",
   "submit",
 ];
 
 /**
- * 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) —
@@ -229,8 +265,11 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
   "run_ci",
   "land",
   "learn",
+  "run_learn_wave",
   "resolve_review_threads",
   "post_pr_review",
+  "run_pr_review_wave",
+  "run_pr_review_dynamic_wave",
   "submit_pr_review",
   // The reconcile trio: `/land` auto-drives the objective-reconcile pass inside the CURRENT
   // worktree session (driveReconcileAfterLand), and the manual `/objective-reconcile` gesture is
@@ -259,6 +298,8 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
  *    gesture — its guidance names all three).
  */
 export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
+  "gist-author": ["ask_user_question", "gist_draft", "gist_save", ...RESEARCH_TOOLS],
+  "gist-save": ["ask_user_question", "gist_draft", "gist_save", ...RESEARCH_TOOLS],
   "objective-author": [
     "ask_user_question",
     "objective_draft",