pi-orchestrator-config 4.23.0 → 4.24.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [4.24.0] - 2026-11-03
+
+- `/pr-review` asks how to decide after the findings table — `Post all`, `Skip all`, or
+  `Decide one by one` — instead of one bulk answer for everything.
+- Deciding one by one gives each finding its own dialog (post, skip, skip with reason, more
+  context, stop), captures the skip reason at decision time, keeps author questions on their
+  Approve / Edit / Skip path, and stores a reason even for a bare skip.
+- Every `ask_user` prompt offers "💬 Discuss with AI first", which returns a sentinel meaning
+  "talk about this decision first" rather than an answer; a caller that passes that row itself
+  gets one row, and `allowDiscuss: false` removes it.
+- Docs: the `ask_user` reference covers `allowDiscuss` and the sentinel; the workflow page
+  documents the mode choice and the real turn cost.
+
 ## [4.23.0] - 2026-11-02
 
 - Minimum pi version raised to 1.5.0 — the extension floor, the sidecar floor, and every manifest move together.

package/extensions/orchestrator/ask-user.ts

@@ -18,6 +18,71 @@ import { createLogger } from "../shared/logger.js";
 
 const log = createLogger("ask-user");
 
+/** Sentinel value returned when the user asks to discuss in plain chat first. */
+export const DISCUSS_VALUE = "__discuss__";
+export const DISCUSS_LABEL = "💬 Discuss with AI first";
+const FREE_INPUT_VALUE = "__free_input__";
+
+/** Emoji/punctuation-free, lowercased form so a caller's plain label still matches. */
+const normalizeOption = (s: string): string =>
+  s.replace(/[^\p{L}\p{N}]+/gu, " ").trim().toLowerCase();
+
+/** A caller option that already is the discuss row: its plain label or the bare sentinel. */
+const isDiscussRow = (option: string): boolean =>
+  option.trim().toLowerCase() === DISCUSS_VALUE ||
+  normalizeOption(option) === normalizeOption(DISCUSS_LABEL);
+
+export function buildAskOptions(
+  options: string[] | undefined,
+  allowDiscuss: boolean,
+): SelectItem[] {
+  // Free-input-only mode: no list, no discuss item.
+  if (!options || options.length === 0) return [];
+
+  let callerSuppliedDiscuss = false;
+  const items: SelectItem[] = [];
+  for (const opt of options) {
+    if (!isDiscussRow(opt)) {
+      items.push({ value: opt, label: opt });
+      continue;
+    }
+    // Opted out: a caller's discuss row must disappear, not merely go unappended.
+    if (!allowDiscuss) continue;
+    // Caller's label stays for display; the sentinel makes selecting it pause.
+    callerSuppliedDiscuss = true;
+    items.push({ value: DISCUSS_VALUE, label: opt, description: "chat first" });
+  }
+  if (!allowDiscuss) {
+    log.debug("ask_user discuss option suppressed", { optionCount: options.length });
+  } else if (callerSuppliedDiscuss) {
+    log.debug("ask_user discuss option deduped", { optionCount: options.length });
+  } else {
+    items.push({ value: DISCUSS_VALUE, label: DISCUSS_LABEL, description: "chat first" });
+    log.debug("ask_user discuss option offered", { optionCount: options.length });
+  }
+  items.push({
+    value: FREE_INPUT_VALUE,
+    label: "✎  Other (type custom answer)",
+    description: "free-text",
+  });
+  return items;
+}
+
+/**
+ * Browser/discord renders options as buttons labelled with the raw string, so the
+ * discuss row travels as its label and comes back mapped to the sentinel. The
+ * free-input row is a TUI control, not an answer — it is never offered remotely.
+ */
+export function browserAskOptions(items: SelectItem[]): string[] {
+  return items
+    .filter((item) => item.value !== FREE_INPUT_VALUE)
+    .map((item) => (item.value === DISCUSS_VALUE ? DISCUSS_LABEL : item.value));
+}
+
+export function answerToValue(answer: string): string {
+  return answer === DISCUSS_LABEL ? DISCUSS_VALUE : answer;
+}
+
 export function registerAskUser(
   pi: ExtensionAPI,
   terminalNotify: (title: string, body: string) => void,
@@ -32,6 +97,7 @@ export function registerAskUser(
       "Use ask_user when you need user input during a workflow (approvals, selections, confirmations).",
       "Do NOT ask users questions via plain text — always use this tool for structured choices.",
       "Provide clear, concise options. Include a 'no' or 'cancel' option when appropriate.",
+      `If ask_user returns exactly "${DISCUSS_VALUE}", the user has NOT answered — they want to talk about this decision first. Open by addressing the decision itself: the trade-offs, the information you are missing, or the alternatives. Never answer with a status report about what you built or verified. Re-call ask_user with the SAME question and options only once the discussion resolves.`,
     ],
     parameters: Type.Object({
       question: Type.String({
@@ -43,6 +109,12 @@ export function registerAskUser(
             "List of selectable options. If omitted, only free-text input is shown.",
         }),
       ),
+      allowDiscuss: Type.Optional(
+        Type.Boolean({
+          description:
+            "Offer a 'Discuss with AI first' option that returns the __discuss__ sentinel without answering (default true).",
+        }),
+      ),
     }),
 
     async execute(_id, params, _signal, _onUpdate, ctx) {
@@ -58,14 +130,16 @@ export function registerAskUser(
 
       terminalNotify("pi", "Action required");
 
+      const assembled = buildAskOptions(params.options, params.allowDiscuss !== false);
+
       // Emit ask request for pidash browser clients
       const askId = `ask-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
       pi.events.emit("pidash:ui-request", {
         id: askId,
         type: "extension_ui_request",
-        method: params.options?.length ? "select" : "input",
+        method: assembled.length ? "select" : "input",
         title: params.question,
-        options: params.options,
+        options: assembled.length ? browserAskOptions(assembled) : undefined,
       });
 
       // Track if resolved (from TUI or browser)
@@ -76,20 +150,21 @@ export function registerAskUser(
         const resp = data as any;
         if (resp.id === askId && externalDone) {
           if (resp.cancelled) externalDone(null);
-          else if (resp.value) externalDone(resp.value);
-          else if (resp.confirmed !== undefined) externalDone(resp.confirmed ? "Yes" : "No");
+          else if (resp.value) {
+            const value = answerToValue(resp.value);
+            log.debug("ask_user browser answer received", { askId, isDiscuss: value === DISCUSS_VALUE });
+            externalDone(value);
+          } else if (resp.confirmed !== undefined) externalDone(resp.confirmed ? "Yes" : "No");
         }
       });
 
-      log.debug("ask_user prompt opened with blocked status", { askId, mode: params.options?.length ? "select" : "input" });
+      log.debug("ask_user prompt opened with blocked status", { askId, mode: assembled.length ? "select" : "input" });
       const result = await ctx.ui.custom<string | null>(
         (tui, theme, _kb, done) => {
           // Allow browser to resolve this dialog
           externalDone = done;
 
-          let mode: "select" | "input" = params.options?.length
-            ? "select"
-            : "input";
+          let mode: "select" | "input" = assembled.length ? "select" : "input";
           let resolved = false;
 
           const resolve = (value: string | null) => {
@@ -141,7 +216,7 @@ export function registerAskUser(
             sl.onSelect = (item: SelectItem) => {
               if (item.value === "__no_match__") {
                 // Ignore — not a real option
-              } else if (item.value === "__free_input__") {
+              } else if (item.value === FREE_INPUT_VALUE) {
                 mode = "input";
                 searchInput.setValue("");
                 tui.requestRender();
@@ -153,18 +228,8 @@ export function registerAskUser(
             return sl;
           };
 
-          if (params.options && params.options.length > 0) {
-            allItems = [
-              ...params.options.map((opt: string) => ({
-                value: opt,
-                label: opt,
-              })),
-              {
-                value: "__free_input__",
-                label: "✎  Other (type custom answer)",
-                description: "free-text",
-              },
-            ];
+          if (assembled.length > 0) {
+            allItems = assembled;
             selectList = makeSelectList(allItems);
           }
 
@@ -176,7 +241,7 @@ export function registerAskUser(
               if (selected) {
                 if (selected.value === "__no_match__") {
                   // Ignore
-                } else if (selected.value === "__free_input__") {
+                } else if (selected.value === FREE_INPUT_VALUE) {
                   mode = "input";
                   searchInput.setValue("");
                 } else {
@@ -288,6 +353,9 @@ export function registerAskUser(
     renderResult(result, _options, theme) {
       const text = result.content[0];
       const value = text?.type === "text" ? text.text : "(no response)";
+      if (value === DISCUSS_VALUE) {
+        return new Text(theme.fg("dim", "💬 Discussion requested"), 0, 0);
+      }
       const icon =
         value === "User cancelled"
           ? theme.fg("warning", "✗")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.23.0",
+  "version": "4.24.0",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"

package/prompts/pr-review.md

@@ -44,6 +44,11 @@ If not found, prompt user: "myk-pi-tools is required. Install with: `uv tool ins
 - `/pr-review 123` - Review PR #123 in current repo
 - `/pr-review https://github.com/owner/repo/pull/123` - Review from URL
 
+Phase 4 asks how you want to decide: `Post all`, `Skip all`, or `Decide one by one`.
+Deciding one by one costs roughly one turn per finding (plus one per discussion round, and one
+more when you skip with a reason or stop early) — choose it when findings need individual
+judgment, not on a 20-finding wall.
+
 ## Task Plan
 
 Before starting any work, create ALL tasks upfront using `TaskCreate`, then set their dependencies
@@ -522,6 +527,72 @@ This avoids ambiguity — user selections for new findings always refer to the `
 - 'none' = Skip posting new findings (previous findings are still auto-posted)
 - Specific numbers = Post only those new findings (numbers refer to the `[NEW]` list)
 
+**One ask decides the mode.** After printing the table, call `ask_user` once with question
+`{N} findings — how do you want to decide?` and options `Post all`, `Skip all`, `Decide one by one`.
+Skip this question entirely when there are ZERO `[NEW]` and ZERO `[AUTHOR-QUESTION]` items —
+go straight to Phase 5 with the auto-posted prior findings (see the zero-item rule below).
+Typed answers (`all`, `none`, `3,7,12`) keep working as free text. `ask_user` appends the
+`💬 Discuss with AI first` row itself — never pass it as one of your own options, or the user
+sees it twice.
+
+- `Post all` → every `[NEW]` finding is selected. Continue to the refine step in bulk mode.
+- `Skip all` → every `[NEW]` finding is skipped. Collect one blanket reason in bulk mode below.
+- `Decide one by one` → run the per-finding loop below.
+- `💬 Discuss with AI first` (`__discuss__`) → not an answer. Talk about the decision itself —
+  trade-offs, what is missing, the alternatives — never a status report on what you just checked —
+  then re-ask the same question with the same options once it resolves.
+
+**Per-finding loop (chosen by `Decide one by one`):**
+
+Everything after this phase — the JSON, the post step, the replies — is unchanged.
+
+1. Print the auto-post header block ONCE: `N prior finding(s) will be re-raised (auto-post).`
+   `[PREV-*]` findings are never part of the loop.
+2. For each `[AUTHOR-QUESTION]` (Q1..) and then each `[NEW]` finding (1..N), in the stable
+   merged order.
+
+   **`[AUTHOR-QUESTION]` items keep their own flow** — never use the finding template or the
+   finding actions for them:
+   - Print the original comment (who asked, where, full text) and the AI-generated suggested
+     answer from Phase 1c.
+   - `ask_user` with question `Question i/N — <one-line summary>` and options `Approve`, `Edit`,
+     `Skip`. No `Show more context` (the question body is the context) and no `Skip + reason`
+     (the stored reason is `Author question — user chose not to respond`).
+   - `Approve` → the suggested answer is posted as-is in Phase 5.
+   - `Edit` → print `Answer for Q{i}:` as plain chat text and STOP the turn; the user's next
+     message is the revised answer, which Phase 5 posts instead of the suggestion.
+   - `Skip` → the question is not answered; it is stored with `skip_reason`
+     `Author question — user chose not to respond`.
+
+   **`[NEW]` findings:**
+   a. Print `Finding i/N — <severity> — <file>:<line>`, the source tag, the full description,
+      the suggestion block, and which reviewer(s) raised it after dedup.
+   b. Call `ask_user` with question `Finding i/N — <one-line summary>` and exactly these options:
+      `Post`, `Skip`, `Skip + reason`, `Show more context`, `Stop here`. Do NOT pass
+      `Discuss with AI first` — `ask_user` appends that row itself.
+   c. Act on the answer:
+      - `Post` → finding is selected for posting.
+      - `Skip` → finding is skipped. Phase 5b still requires a reason, so store the fixed
+        `skip_reason` `Skipped — no reason given`; do not ask the user for one.
+      - `Skip + reason` → re-call `ask_user` with question `Reason for finding i/N:` and no
+        options, so the answer is free text; use it as the reason and continue with the next
+        finding. If the user asks for a multi-line reason, print `Reason for finding i/N:` as
+        plain chat text and STOP the turn instead — their next message is the reason.
+      - `Show more context` → print the surrounding diff hunk and the affected call sites, then
+        re-ask the SAME finding (same index, same options).
+      - `Discuss with AI first` → `ask_user` returns exactly `__discuss__`. That is NOT an answer:
+        the user wants to talk about this finding. Discuss the finding itself — its trade-offs,
+        what you would need to know to judge it, the alternatives — and do not report on your own
+        workflow. Re-ask the SAME finding once the discussion resolves. `__discuss__` is a control
+        value — never post it, never store it, never write it to `.pi/data/review-guidelines.md`.
+      - `Stop here` → every remaining finding is skipped. Ask once for a blanket reason: use
+        `ask_user` with no options when one line is enough, otherwise print the prompt as plain
+        chat text and STOP the turn. If the user gives no reason, store the fixed
+        `skip_reason` `Skipped — no reason given` (Phase 5b rejects an empty one).
+3. The reasons collected here feed the SAME refine → classify → `review-guidelines.md` steps
+   below. Only the timing differs: the reason is captured while the user is looking at that
+   finding instead of in a later bulk round.
+
 If there are ZERO `[NEW]` findings AND zero `[AUTHOR-QUESTION]` findings, skip user
 selection entirely — auto-post the previous findings and proceed directly to Phase 5
 (the auto-post path still generates the comments JSON and posts them — see Phase 5).
@@ -532,10 +603,16 @@ user approval/edit/skip.
 
 🚨 **Skip reason collection (MANDATORY — NEVER SKIP THIS STEP):**
 
-**HARD RULE: If the user skipped ANY finding (said 'no', selected specific numbers
-that exclude some findings, or said 'none'), you MUST ask for skip reasons
-BEFORE proceeding to Phase 5. Do NOT continue the workflow without collecting
-skip reasons. Skipping this step is a HARD VIOLATION.**
+In the per-finding loop the reasons were already captured as you went — go straight to
+step 2 (AI refines each reason) and do not prompt again.
+
+**Bulk mode only (Post all / Skip all / numbers) — HARD RULE: If the user skipped ANY finding
+(said 'no' or 'Skip all', selected specific numbers that exclude some findings), you MUST ask
+for skip reasons BEFORE proceeding to Phase 5.** Do NOT continue the workflow without collecting
+skip reasons. Skipping this step is a HARD VIOLATION.
+
+If the user declines to give any reason, still store one — Phase 5b rejects an empty
+`skip_reason` — using the fixed text `Skipped — no reason given`.
 
 After the user selects which findings to post, compute the skipped set (total `[NEW]`
 findings minus user-selected findings). If the skipped set is non-empty: