pi-orchestrator-config 4.23.0 → 4.24.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [4.24.1] - 2026-11-03
+
+- Dreaming no longer stores re-derivable changelog: `[done]` takes non-derivable outcomes only (conclusions, measurements, root causes) and reorganizing prunes PR/version/ticket
+  history, so `completions` shrinks instead of rotating changelog for changelog. A live run took this project's topic from 18 entries to 2, keeping the cost baseline and the
+  self-reload finding.
+- Learned memory now survives maintenance: anything a dream deletes that is pinned, enforced, or review-distilled is restored when it finishes, and a topic file it deleted is
+  rebuilt. A deliberate removal is respected because removals are recorded as tombstones rather than inferred from score state — the inference inverted whenever the scheduled
+  rebuild ran mid-dream.
+- `completions` is capped at 6,000 characters through per-topic caps, applied by both write paths. The cap is never satisfied by deleting memory: an over-cap topic is reported and
+  left intact.
+
+## [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/extensions/orchestrator/dreaming.ts

@@ -23,15 +23,248 @@ import { getSetting } from "./project-settings.js";
 import { discoverAgents } from "./agents.js";
 import { ICON_DREAM } from "./icons.js";
 import { setSlot } from "./status-bar.js";
+import { distilledLessonTextList } from "./review-learning.js";
+import { invalidateTopicFileCache, removalsSince, topicCharCap } from "./memory-tree.js";
+import { entryHash } from "./memory-scoring.js";
+
+/** Topic files memory maintenance rewrites. */
+const MEMORY_TOPIC_FILES = ["lessons", "preferences", "patterns", "decisions", "completions", "mistakes"];
+
+/** Line text without its `- [category] ` prefix, lock markers, or `{#id}` suffix. */
+function topicLineText(line: string): string {
+  return line
+    .replace(/^- \[[a-z]+\] /, "")
+    .replace(/\s*\*\((?:pinned|enforced)\)\*/g, "")
+    .replace(/\s*\{#[0-9a-f]+\}\s*$/, "")
+    .trim();
+}
+
+/**
+ * Entries memory maintenance must never delete, whatever the prompt says:
+ * pinned/enforced entries (user-locked, or keyed by text hash for enforcement) and
+ * lessons distilled from reviews — their source is the reviews DB, but nothing
+ * re-materializes the topic line once a dream removes it (issue #1010).
+ */
+export function isProtectedTopicLine(line: string, reviewLessons: readonly string[]): boolean {
+  if (!line.startsWith("- [")) return false;
+  if (line.includes("*(pinned)*") || line.includes("*(enforced)*")) return true;
+  const text = topicLineText(line);
+  return reviewLessons.some((lesson) => {
+    const candidate = lesson.trim();
+    return candidate.length > 0 && text === candidate;
+  });
+}
+
+/** Snapshot every memory topic file's lines, so a dream's deletions can be audited. */
+export function snapshotTopicLines(topicsDir: string): Record<string, string[]> {
+  const before: Record<string, string[]> = {};
+  for (const name of MEMORY_TOPIC_FILES) {
+    try {
+      before[`${name}.md`] = fs.readFileSync(path.join(topicsDir, `${name}.md`), "utf-8").split("\n");
+    } catch {
+      // Topic absent — nothing to protect.
+    }
+  }
+  return before;
+}
+
+/**
+ * Restore protected entries a dream removed, at their original index. Returns how
+ * many lines were put back; zero means the dream stayed inside its mandate.
+ * Any failure is the caller's to log — this never throws.
+ */
+/** Canonical `- [category] text` form used as the memory score key. */
+export function topicLineCanonical(line: string): string {
+  const category = /^- \[([a-z]+)\] /.exec(line)?.[1] ?? "";
+  return `- [${category}] ${topicLineText(line)}`;
+}
+
+export type TopicRestoreReport = {
+  restored: number;
+  failed: number;
+  /** Topics still over their cap after reconcile. Never trimmed here: see below. */
+  overCapTopics: string[];
+};
+
+/**
+ * Restore protected entries a dream removed, at their original index, then keep the
+ * file inside its per-topic cap by dropping unprotected additions — never protected
+ * ones. Recreates a topic the dream deleted outright. Returns what it did; logging is
+ * the caller's, this never throws.
+ */
+export function restoreProtectedTopicLines(
+  topicsDir: string,
+  before: Record<string, string[]>,
+  reviewLessons: readonly string[],
+  removedByUser: (line: string) => boolean = () => false,
+): TopicRestoreReport {
+  const report: TopicRestoreReport = { restored: 0, failed: 0, overCapTopics: [] };
+  for (const [file, beforeLines] of Object.entries(before)) {
+    const filePath = path.join(topicsDir, file);
+    let current: string[] | null = null;
+    try {
+      current = fs.readFileSync(filePath, "utf-8").split("\n");
+    } catch {
+      current = null; // Deleted outright — rebuilt below from the snapshot.
+    }
+    const base = current ?? beforeLines.filter((line) => !line.startsWith("- ["));
+    // A dream that *rewrites* a protected entry keeps it: compare canonical text, not the
+    // raw line, or the original returns beside the rewrite as a duplicate.
+    const surviving = new Set((current ?? []).map(topicLineCanonical));
+    const beforeEntries = new Set(
+      beforeLines.filter((line) => line.startsWith("- [")).map(topicLineCanonical),
+    );
+    const missing = beforeLines
+      .map((line, index) => ({ line, index }))
+      .filter(({ line }) => {
+        if (!line.startsWith("- [") || !isProtectedTopicLine(line, reviewLessons)) return false;
+        if (surviving.has(topicLineCanonical(line))) return false;
+        // Only an explicit tombstone proves a removal. Score absence does not: the
+        // scheduled rebuild prunes scores for lines a dream deleted, which would look
+        // exactly like a user removal and strand the entry (issue #1010).
+        return !removedByUser(line);
+      });
+    if (missing.length === 0 && current !== null) continue;
+
+    const merged = [...base];
+    for (const { line, index } of missing) {
+      merged.splice(Math.min(index, merged.length), 0, line);
+      report.restored += 1;
+    }
+
+    const cap = topicCharCap(file.replace(/\.md$/, ""));
+    // Never trim here. Text cannot distinguish a dream's addition from its rewrite of an
+    // existing memory, and deleting the wrong one loses knowledge that the score rebuild
+    // cannot recover. The write paths still enforce the cap for normal additions; an
+    // over-cap file is reported so the next prune can shrink it with judgment.
+    if (merged.join("\n").length > cap) report.overCapTopics.push(file);
+
+    try {
+      fs.writeFileSync(filePath, merged.join("\n"), "utf-8");
+      invalidateTopicFileCache(filePath);
+    } catch {
+      report.failed += 1;
+      report.restored -= missing.length;
+    }
+  }
+  return report;
+}
+
 import { rebuildAndOrganize } from "./situation-report.js";
 import { runPromotionPass } from "./memory-promotion.js";
 import { mergeProvenancePending } from "./memory-provenance.js";
-import { getProjectTmpDir, getProjectMemoryDir, shouldSkipOneshotShutdownDream } from "./utils.js";
+import { getProjectTmpDir, getProjectMemoryDir, getProjectDataDir, shouldSkipOneshotShutdownDream } from "./utils.js";
 import { fileLog } from "../shared/file-logger.js";
 
 // Scoring rebuild runs every 30 minutes (cheap, no LLM — just rescores and reorganizes)
 const REBUILD_INTERVAL_MS = 30 * 60 * 1000;
 
+export function buildDreamPrompt(
+  lastSessionFile: string | undefined,
+  topicsDir: string,
+): string {
+  return (
+    `Memory dreaming — analyze session and maintain topic files.\n` +
+    `Session file: ${lastSessionFile || "none"}\n` +
+    `Topics directory: ${topicsDir}\n\n` +
+    `Topic files are the source of truth for project memory. Each file holds entries for one category.\n\n` +
+    `Steps:\n` +
+    `1. Read all existing topic files in ${topicsDir}/ (lessons.md, preferences.md, patterns.md, decisions.md, completions.md, mistakes.md).\n` +
+    `   If the directory doesn't exist, create it.\n` +
+    `2. QUALITY GATE: Before extracting from any session, assess its quality:\n` +
+    `   - Score depth (substantive exchanges > 100 chars? decisions made? corrections?)\n` +
+    `   - Skip sessions that are only greetings, trivial Q&A, or < 3 exchanges\n` +
+    `   - Only extract from sessions with real decisions, corrections, or completed work\n` +
+    `3. If a session file is provided, read it and extract things worth remembering:\n` +
+    `   - User corrections → [lesson] → lessons.md\n` +
+    `   - User preferences → [preference] → preferences.md\n` +
+    `   - Mistakes or repeated fix attempts → [mistake] → mistakes.md\n` +
+    `   - Completed work → [done] → completions.md — ONLY non-derivable outcome knowledge:\n` +
+    `     a conclusion, a measurement, a root cause, "X was fixed by Y because Z".\n` +
+    `     NEVER store a PR/issue number list, merge or release history, version changelogs,\n` +
+    `     or closed-ticket roundups — git log, gh, and the tracker already hold them, and a\n` +
+    `     stored "Open: #772" answers "is it fixed?" wrongly once it ships.\n` +
+    `   - Patterns or conventions → [pattern] → patterns.md\n` +
+    `   - Architectural/design decisions → [decision] → decisions.md\n` +
+    `   QUALITY GATE for extraction: one-off permissions granted in a single session\n` +
+    `   ("you can merge this PR", "skip tests just this once") AND task-scoped instructions\n` +
+    `   ("when done, I want an html report", "when bumping to 1.4.0, drop the vendor dir",\n` +
+    `   config-change notes like "every 30min (changed from 1h)") are session/task\n` +
+    `   instructions, NOT memories — never extract them. Apply the standing test: would\n` +
+    `   this apply to a future, unrelated task? No → discard. Only standing, repeated\n` +
+    `   rules are durable.\n` +
+    `   Do NOT add duplicates of existing entries.\n` +
+    `3b. Review the preference candidate queue: if ${topicsDir}/../preference-candidates.jsonl\n` +
+    `   exists and has entries, each holds a VERBATIM sentence the regex extractor queued\n` +
+    `   from user input (issue #961). For each candidate:\n` +
+    `   - Durable standing preference → DISTILL it into a clean one-line [preference]\n` +
+    `     (≤100 chars, actionable, no verbatim chatter) and add to preferences.md\n` +
+    `   - Task-scoped instruction, one-off ask, question, or already covered → discard\n` +
+    `   After processing: RE-READ preference-candidates.jsonl and rewrite it keeping ONLY\n` +
+    `   the entries that appeared after your first read — the extractor appends\n` +
+    `   concurrently, so do NOT truncate the whole file (an entry queued between your\n` +
+    `   read and your rewrite would be erased before any dream cycle reviewed it).\n` +
+    `   Keep the file bounded: if it exceeds 200 lines, also drop the oldest entries\n` +
+    `   beyond that cap.\n` +
+    `4. Scan past session files for unprocessed knowledge. Check if ${topicsDir}/../.dream-watermark exists.\n` +
+    `   If it does, read the timestamp — only process sessions newer than that.\n` +
+    `   Session directory: find .jsonl files under the pi sessions directory.\n` +
+    `   For each unprocessed session, extract durable knowledge (same categories as step 3).\n` +
+    `   Limit: process at most 5 sessions per dream cycle to avoid overload.\n` +
+    `5. Reorganize each topic file:\n` +
+    `   - Remove duplicate or near-duplicate entries\n` +
+    `   - Remove stale/useless entries\n` +
+    `   - Remove session-scoped or expired entries — they are transient by design\n` +
+    `   - Remove task-scoped instruction entries (issue #961): verbatim user utterances\n` +
+    `     (colloquial chat captured raw), mid-sentence cutoffs, one-off deliverable asks\n` +
+    `     ("when done I want a report"), version-pinned migration checklists, config-change\n` +
+    `     notes — these are task/session artifacts, not durable rules. NEVER remove\n` +
+    `     pinned or enforced entries even when they match these shapes.\n` +
+    `   - Remove entries that restate git/GitHub/Jira history — merged-PR lists, release and\n` +
+    `     version notes, closed-ticket roundups. Recoverable by query, therefore not memory.\n` +
+    `     When an entry mixes history with a non-derivable finding, keep only the finding.\n` +
+    `   - Keep each file at a reasonable size (aim for under 20 entries per topic)\n` +
+    `   - NEVER remove or modify entries marked with *(pinned)*\n` +
+    `   - NEVER remove or modify entries marked with *(enforced)* — these have code-enforced triggers/actions that are keyed by text hash. ANY text change destroys the enforcement binding.\n` +
+    `6. Write each updated topic file with this format:\n` +
+    `   # TopicName\n` +
+    `   \n` +
+    `   - [category] summary *(pinned)*              (if pinned)\n` +
+    `   - [category] summary *(enforced)*            (if enforced)\n` +
+    `   - [category] summary *(pinned)* *(enforced)* (if both)\n` +
+    `   - [category] summary                         (if neither)\n` +
+    `7. Auto-generate skills: if you notice a multi-step workflow pattern across entries,\n` +
+    `   create a skill file at .pi/skills/<name>/SKILL.md (project-level, NOT global ~/.agents/).\n` +
+    `   The SKILL.md MUST start with YAML frontmatter:\n` +
+    `   ---\n` +
+    `   name: <name>\n` +
+    `   description: "What this skill does and when to use it"\n` +
+    `   ---\n` +
+    `   Only create skills for workflows with 3+ steps that are likely to recur.\n` +
+    `8. Write the current timestamp to ${topicsDir}/../.dream-watermark to track progress.\n` +
+    `9. Memory rules: one line per entry, max ~100 chars, specific and actionable, no fluff.\n` +
+    `10. Promotion destinations: append candidates to ${topicsDir}/../promotions.md using this block format:\n` +
+    `   ### <12-char-id>\n` +
+    `   - destination: memory|skill|enforcement|project_rule|discard\n` +
+    `   - status: proposed\n` +
+    `   - category: <category>\n` +
+    `   - text: <exact topic entry text>\n` +
+    `   - reason: <why this should graduate>\n` +
+    `   - created: <ISO timestamp>\n` +
+    `   Optional fields: evidence_count, trigger, action, verifier, skill_name, skill_created.\n` +
+    `   Rules:\n` +
+    `   - skill: create .pi/skills/ when confident; set skill_created: true\n` +
+    `   - enforcement: propose trigger/action when mechanical (never/always + command); do NOT invent run_after\n` +
+    `   - project_rule: propose only — NEVER write rules/ or .pi/rules/\n` +
+    `   - discard: stale or superseded noise\n` +
+    `   - Do not reopen entries already marked applied or rejected in promotions.md\n` +
+    `11. Provenance sidecar (optional): for newly extracted entries, write\n` +
+    `   ${topicsDir}/../provenance-pending.jsonl as a single line of JSON (preferred):\n` +
+    `   {"entries":[{"category":"lesson","text":"<exact topic text>","sourceSession":"<session basename>","derivedFrom":"<optional>","informs":["optional"]}]}\n` +
+    `   Do NOT edit memory-scores.jsonl yourself — onComplete merges the sidecar.`
+  );
+}
+
 export function registerDreaming(
   pi: ExtensionAPI,
   spawnAsyncAgent: (
@@ -102,99 +335,13 @@ export function registerDreaming(
     currentDreamId = "";  // Reset until we get the ID from spawnAsyncAgent
     const { agents } = discoverAgents(cwd, "user");
     const topicsDir = path.join(getProjectMemoryDir(cwd), "topics");
+    // Snapshot before the dream touches anything: whatever it removes that is learned
+    // knowledge rather than re-derivable history is put back below (issue #1010).
+    const topicsBeforeDream = snapshotTopicLines(topicsDir);
+    const dreamStartedAt = Date.now();
     const { id } = spawnAsyncAgent(
       "worker",
-      `Memory dreaming — analyze session and maintain topic files.\n` +
-      `Session file: ${lastSessionFile || "none"}\n` +
-      `Topics directory: ${topicsDir}\n\n` +
-      `Topic files are the source of truth for project memory. Each file holds entries for one category.\n\n` +
-      `Steps:\n` +
-      `1. Read all existing topic files in ${topicsDir}/ (lessons.md, preferences.md, patterns.md, decisions.md, completions.md, mistakes.md).\n` +
-      `   If the directory doesn't exist, create it.\n` +
-      `2. QUALITY GATE: Before extracting from any session, assess its quality:\n` +
-      `   - Score depth (substantive exchanges > 100 chars? decisions made? corrections?)\n` +
-      `   - Skip sessions that are only greetings, trivial Q&A, or < 3 exchanges\n` +
-      `   - Only extract from sessions with real decisions, corrections, or completed work\n` +
-      `3. If a session file is provided, read it and extract things worth remembering:\n` +
-      `   - User corrections → [lesson] → lessons.md\n` +
-      `   - User preferences → [preference] → preferences.md\n` +
-      `   - Mistakes or repeated fix attempts → [mistake] → mistakes.md\n` +
-      `   - Completed features/PRs merged → [done] → completions.md\n` +
-      `   - Patterns or conventions → [pattern] → patterns.md\n` +
-      `   - Architectural/design decisions → [decision] → decisions.md\n` +
-      `   QUALITY GATE for extraction: one-off permissions granted in a single session\n` +
-      `   ("you can merge this PR", "skip tests just this once") AND task-scoped instructions\n` +
-      `   ("when done, I want an html report", "when bumping to 1.4.0, drop the vendor dir",\n` +
-      `   config-change notes like "every 30min (changed from 1h)") are session/task\n` +
-      `   instructions, NOT memories — never extract them. Apply the standing test: would\n` +
-      `   this apply to a future, unrelated task? No → discard. Only standing, repeated\n` +
-      `   rules are durable.\n` +
-      `   Do NOT add duplicates of existing entries.\n` +
-      `3b. Review the preference candidate queue: if ${topicsDir}/../preference-candidates.jsonl\n` +
-      `   exists and has entries, each holds a VERBATIM sentence the regex extractor queued\n` +
-      `   from user input (issue #961). For each candidate:\n` +
-      `   - Durable standing preference → DISTILL it into a clean one-line [preference]\n` +
-      `     (≤100 chars, actionable, no verbatim chatter) and add to preferences.md\n` +
-      `   - Task-scoped instruction, one-off ask, question, or already covered → discard\n` +
-      `   After processing: RE-READ preference-candidates.jsonl and rewrite it keeping ONLY\n` +
-      `   the entries that appeared after your first read — the extractor appends\n` +
-      `   concurrently, so do NOT truncate the whole file (an entry queued between your\n` +
-      `   read and your rewrite would be erased before any dream cycle reviewed it).\n` +
-      `   Keep the file bounded: if it exceeds 200 lines, also drop the oldest entries\n` +
-      `   beyond that cap.\n` +
-      `4. Scan past session files for unprocessed knowledge. Check if ${topicsDir}/../.dream-watermark exists.\n` +
-      `   If it does, read the timestamp — only process sessions newer than that.\n` +
-      `   Session directory: find .jsonl files under the pi sessions directory.\n` +
-      `   For each unprocessed session, extract durable knowledge (same categories as step 3).\n` +
-      `   Limit: process at most 5 sessions per dream cycle to avoid overload.\n` +
-      `5. Reorganize each topic file:\n` +
-      `   - Remove duplicate or near-duplicate entries\n` +
-      `   - Remove stale/useless entries\n` +
-      `   - Remove session-scoped or expired entries — they are transient by design\n` +
-      `   - Remove task-scoped instruction entries (issue #961): verbatim user utterances\n` +
-      `     (colloquial chat captured raw), mid-sentence cutoffs, one-off deliverable asks\n` +
-      `     ("when done I want a report"), version-pinned migration checklists, config-change\n` +
-      `     notes — these are task/session artifacts, not durable rules. NEVER remove\n` +
-      `     pinned or enforced entries even when they match these shapes.\n` +
-      `   - Keep each file at a reasonable size (aim for under 20 entries per topic)\n` +
-      `   - NEVER remove or modify entries marked with *(pinned)*\n` +
-      `   - NEVER remove or modify entries marked with *(enforced)* — these have code-enforced triggers/actions that are keyed by text hash. ANY text change destroys the enforcement binding.\n` +
-      `6. Write each updated topic file with this format:\n` +
-      `   # TopicName\n` +
-      `   \n` +
-      `   - [category] summary *(pinned)*              (if pinned)\n` +
-      `   - [category] summary *(enforced)*            (if enforced)\n` +
-      `   - [category] summary *(pinned)* *(enforced)* (if both)\n` +
-      `   - [category] summary                         (if neither)\n` +
-      `7. Auto-generate skills: if you notice a multi-step workflow pattern across entries,\n` +
-      `   create a skill file at .pi/skills/<name>/SKILL.md (project-level, NOT global ~/.agents/).\n` +
-      `   The SKILL.md MUST start with YAML frontmatter:\n` +
-      `   ---\n` +
-      `   name: <name>\n` +
-      `   description: "What this skill does and when to use it"\n` +
-      `   ---\n` +
-      `   Only create skills for workflows with 3+ steps that are likely to recur.\n` +
-      `8. Write the current timestamp to ${topicsDir}/../.dream-watermark to track progress.\n` +
-      `9. Memory rules: one line per entry, max ~100 chars, specific and actionable, no fluff.\n` +
-      `10. Promotion destinations: append candidates to ${topicsDir}/../promotions.md using this block format:\n` +
-      `   ### <12-char-id>\n` +
-      `   - destination: memory|skill|enforcement|project_rule|discard\n` +
-      `   - status: proposed\n` +
-      `   - category: <category>\n` +
-      `   - text: <exact topic entry text>\n` +
-      `   - reason: <why this should graduate>\n` +
-      `   - created: <ISO timestamp>\n` +
-      `   Optional fields: evidence_count, trigger, action, verifier, skill_name, skill_created.\n` +
-      `   Rules:\n` +
-      `   - skill: create .pi/skills/ when confident; set skill_created: true\n` +
-      `   - enforcement: propose trigger/action when mechanical (never/always + command); do NOT invent run_after\n` +
-      `   - project_rule: propose only — NEVER write rules/ or .pi/rules/\n` +
-      `   - discard: stale or superseded noise\n` +
-      `   - Do not reopen entries already marked applied or rejected in promotions.md\n` +
-      `11. Provenance sidecar (optional): for newly extracted entries, write\n` +
-      `   ${topicsDir}/../provenance-pending.jsonl as a single line of JSON (preferred):\n` +
-      `   {"entries":[{"category":"lesson","text":"<exact topic text>","sourceSession":"<session basename>","derivedFrom":"<optional>","informs":["optional"]}]}\n` +
-      `   Do NOT edit memory-scores.jsonl yourself — onComplete merges the sidecar.`,
+      buildDreamPrompt(lastSessionFile, topicsDir),
       cwd,
       agents,
       {
@@ -206,6 +353,34 @@ export function registerDreaming(
           dreamInFlight = false;
           log.info("dream complete", cwd);
           updateDreamStatus();
+          // Undo any deletion of learned knowledge before anything reads the topics.
+          try {
+            const reviewLessons = distilledLessonTextList(getProjectDataDir(cwd));
+            const removed = removalsSince(cwd, dreamStartedAt);
+            const report = restoreProtectedTopicLines(topicsDir, topicsBeforeDream, reviewLessons, (line) =>
+              removed.has(entryHash(topicLineCanonical(line))),
+            );
+            if (report.restored > 0) {
+              log.warn("dream_restored_protected_entries", { restored: report.restored });
+            }
+            if (report.overCapTopics.length > 0) {
+              log.warn("dream_restore_left_topic_over_cap", { topics: report.overCapTopics });
+            }
+            if (report.failed > 0) {
+              log.error("dream_restore_write_failed", { failedTopics: report.failed });
+            }
+            if (report.restored > 0 || report.failed > 0 || report.overCapTopics.length > 0) {
+              fileLog(
+                "dreaming",
+                report.failed > 0 ? "error" : "warn",
+                "dreaming",
+                `protected-memory reconcile: restored=${report.restored} over_cap=${report.overCapTopics.join(",") || "-"} failed=${report.failed}`,
+              );
+            }
+          } catch (err) {
+            log.error("dream_restore_failed", { reason: String((err as Error)?.message ?? err).slice(0, 200) });
+            fileLog("dreaming", "error", "dreaming", "protected-memory restore failed", err);
+          }
           // File log only — console.* leaks into the chat text box.
           try {
             rebuildAndOrganize(cwd);

package/extensions/orchestrator/memory-tools.ts

@@ -31,9 +31,10 @@ import {
   listTopics,
   readAllTopicEntries,
   CATEGORY_TO_TOPIC,
-  MAX_TOPIC_CHARS,
+  topicCharCap,
   findTopicLine,
   invalidateTopicFileCache,
+  recordRemoval,
   type TopicInfo,
 } from "./memory-tree.js";
 import { embedEntry, removeEmbedding, vectorSearch, embedMissing } from "./memory-embeddings.js";
@@ -406,6 +407,9 @@ function registerMemoryRemove(pi: ExtensionAPI): void {
         }
       });
 
+      // Tombstone the removal: the dream guard must be able to tell this from its own damage.
+      recordRemoval(cwd, canonicalLine);
+
       log.info("memory_remove", category, text.slice(0, 60));
       return {
         content: [{ type: "text", text: `Removed: [${category}] ${text}` }],
@@ -551,8 +555,10 @@ function registerMemoryEdit(pi: ExtensionAPI): void {
         const markers = `${wasPinned ? " *(pinned)*" : ""}${wasEnforced ? " *(enforced)*" : ""}${wasId ? ` {#${wasId}}` : ""}`;
         const replacement = `- [${category}] ${newText}${markers}`;
         const newContent = content.replace(lines[matchIndex]!, replacement);
-        if (newContent.length > MAX_TOPIC_CHARS) {
-          return { content: [{ type: "text", text: `Update would exceed topic size limit (${newContent.length}/${MAX_TOPIC_CHARS} chars).` }], details: undefined };
+        const cap = topicCharCap(topicName);
+        if (newContent.length > cap) {
+          log.warn("memory_edit_topic_cap_rejected", { topic: topicName, chars: newContent.length, cap });
+          return { content: [{ type: "text", text: `Update would exceed topic size limit (${newContent.length}/${cap} chars).` }], details: undefined };
         }
         // Replace the line
         lines[matchIndex] = replacement;

package/extensions/orchestrator/memory-tree.ts

@@ -12,8 +12,8 @@
 
 import { createLogger } from "../shared/logger.js";
 import { getProjectMemoryDir } from "./utils.js";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import {
   type MemoryCategory,
   loadScores,
@@ -27,6 +27,65 @@ const log = createLogger("memory");
 /** Max chars per topic file (~3000 tokens × 4 chars/token) */
 export const MAX_TOPIC_CHARS = 12000;
 
+/** Per-topic override of MAX_TOPIC_CHARS. `completions` accretes by default, so it gets
+ *  a tighter budget: completed-work entries crowd out the knowledge worth keeping. */
+export const TOPIC_CHAR_CAP: Record<string, number> = { completions: 6000 };
+
+/** Char cap for a topic file name (without `.md`), falling back to MAX_TOPIC_CHARS. */
+export function topicCharCap(topic: string): number {
+  const cap = TOPIC_CHAR_CAP[topic] ?? MAX_TOPIC_CHARS;
+  log.debug("topic_char_cap_resolved", { topic, cap, overridden: topic in TOPIC_CHAR_CAP });
+  return cap;
+}
+
+/** Append-only log of deliberate entry removals, so background maintenance can tell a
+ *  user removal from its own damage. Score absence cannot: the scheduled rebuild prunes
+ *  scores for lines missing from topic files (issue #1010). */
+const REMOVALS_FILE = "removals.jsonl";
+const MAX_REMOVAL_ROWS = 5000;
+
+/** Record that an entry was removed on purpose. Fail-soft: a lost tombstone can only
+ *  make the dream guard restore a line the user deleted, never delete one. */
+export function recordRemoval(cwd: string, canonicalLine: string): void {
+  try {
+    const file = join(getProjectMemoryDir(cwd), REMOVALS_FILE);
+    const row = `${JSON.stringify({ hash: entryHash(canonicalLine), at: new Date().toISOString() })}\n`;
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, row, "utf-8");
+    log.debug("memory_removal_recorded", { hash: entryHash(canonicalLine) });
+    const rows = readFileSync(file, "utf-8").split("\n").filter(Boolean);
+    if (rows.length > MAX_REMOVAL_ROWS) {
+      writeFileSync(file, `${rows.slice(-MAX_REMOVAL_ROWS).join("\n")}\n`, "utf-8");
+    }
+  } catch (error) {
+    log.warn("memory_removal_record_failed", { reason: String((error as Error)?.message ?? error).slice(0, 120) });
+  }
+}
+
+/** Hashes removed at or after `sinceMs` — the only trustworthy signal that a line
+ *  missing after a background dream was the user's decision, not the dream's damage. */
+export function removalsSince(cwd: string, sinceMs: number): Set<string> {
+  const hashes = new Set<string>();
+  try {
+    const file = join(getProjectMemoryDir(cwd), REMOVALS_FILE);
+    if (!existsSync(file)) return hashes;
+    for (const row of readFileSync(file, "utf-8").split("\n")) {
+      if (!row.trim()) continue;
+      try {
+        const parsed = JSON.parse(row) as { hash?: unknown; at?: unknown };
+        if (typeof parsed.hash !== "string" || typeof parsed.at !== "string") continue;
+        if (Date.parse(parsed.at) >= sinceMs) hashes.add(parsed.hash);
+      } catch {
+        // Skip a malformed row rather than losing the whole log.
+      }
+    }
+    log.debug("memory_removals_since", { sinceMs, count: hashes.size });
+  } catch (error) {
+    log.warn("memory_removals_read_failed", { reason: String((error as Error)?.message ?? error).slice(0, 120) });
+  }
+  return hashes;
+}
+
 /** Topic mapping: which categories go into which topic files */
 export const CATEGORY_TO_TOPIC: Record<MemoryCategory, string> = {
   preference: "preferences",

package/extensions/orchestrator/memory-write.ts

@@ -39,7 +39,7 @@ import {
   isTaskScopedText,
   hasDurabilityMarker,
 } from "./memory-scoring.js";
-import { CATEGORY_TO_TOPIC, MAX_TOPIC_CHARS, readAllTopicEntries, formatTopicLine, findTopicLine, invalidateTopicFileCache } from "./memory-tree.js";
+import { CATEGORY_TO_TOPIC, topicCharCap, readAllTopicEntries, formatTopicLine, findTopicLine, invalidateTopicFileCache, recordRemoval } from "./memory-tree.js";
 import { embedEntry, removeEmbedding, vectorSearch } from "./memory-embeddings.js";
 import { getSetting } from "./project-settings.js";
 
@@ -2165,6 +2165,8 @@ function supersedeEntry(cwd: string, category: string, text: string): void {
     removeEmbedding(cwd, text, category);
 
     const canonicalLine = `- [${category}] ${text}`;
+    // The old text is gone on purpose: tombstone it so the dream guard does not undo an edit.
+    recordRemoval(cwd, canonicalLine);
     const removedId = match.id;
     mutateScores(cwd, (scores) => {
       delete scores.entries[entryHash(canonicalLine)];
@@ -2197,11 +2199,13 @@ function topicCapRejection(cwd: string, category: string, entryLine: string): Ad
     content = `# ${title}\n`;
   }
   const newContent = content.trimEnd() + "\n" + entryLine + "\n";
-  if (newContent.length > MAX_TOPIC_CHARS) {
+  const cap = topicCharCap(topicName);
+  if (newContent.length > cap) {
+    log.warn("memory_topic_cap_rejected", { topic: topicName, chars: newContent.length, cap });
     return {
       status: "rejected",
       message:
-        `Topic "${topicName}" would exceed size limit (${newContent.length}/${MAX_TOPIC_CHARS} chars). ` +
+        `Topic "${topicName}" would exceed size limit (${newContent.length}/${cap} chars). ` +
         `Consolidate or remove entries first using memory_remove.`,
     };
   }

package/extensions/orchestrator/review-learning.ts

@@ -87,6 +87,8 @@ const MAX_LESSON_CHARS = 100;
 const STATE_FILE_NAME = "review-learning-state.json";
 /** Cap on tracked review ids — old reviews never re-distill in practice. */
 const MAX_TRACKED_REVIEWS = 200;
+/** Cap on the long-lived protection list that outlives MAX_TRACKED_REVIEWS. */
+const MAX_PROTECTED_LESSON_TEXTS = 5000;
 
 // ── Command matching ───────────────────────────────────────────────────────
 
@@ -350,17 +352,58 @@ export function loadReviewLessons(dataDir: string): Map<number, Set<string>> {
   return byReview;
 }
 
+/** Every distilled review-lesson text recorded in the state file, flattened.
+ *  Memory maintenance must treat these as learned knowledge, not history: the source
+ *  (the reviews DB) keeps the finding, but nothing re-materializes the topic line
+ *  once it is gone, so a dream that deletes one loses it for good (issue #1010).
+ *  Unions the bounded per-review map with the long-lived protection list so lessons
+ *  from reviews older than the tracking window stay protected. */
+export function distilledLessonTextList(dataDir: string): string[] {
+  const texts = new Set<string>();
+  for (const lessons of loadReviewLessons(dataDir).values()) {
+    for (const lesson of lessons) if (lesson.trim()) texts.add(lesson.trim());
+  }
+  for (const lesson of loadProtectedLessonTexts(dataDir)) if (lesson.trim()) texts.add(lesson.trim());
+  log.debug("distilled_lesson_texts_loaded", { count: texts.size });
+  return [...texts];
+}
+
 function writeStateFile(dataDir: string, distilledReviews: number[], reviewLessons: Map<number, Set<string>>): void {
   const lessons: Record<string, string[]> = {};
   const ids = [...reviewLessons.keys()];
   for (const id of ids.slice(-MAX_TRACKED_REVIEWS)) lessons[String(id)] = [...reviewLessons.get(id)!];
+  // Protection set for older reviews: `lessons` is bounded by MAX_TRACKED_REVIEWS, so
+  // without this union a lesson from review #1 stops being recognizable as reviewed
+  // knowledge once 200 newer reviews land, and memory maintenance may delete it (#1010).
+  const protectedTexts = new Set(loadProtectedLessonTexts(dataDir));
+  for (const set of reviewLessons.values()) for (const text of set) if (text.trim()) protectedTexts.add(text.trim());
   mkdirSync(dataDir, { recursive: true });
   writeFileSync(
     stateFilePath(dataDir),
-    `${JSON.stringify({ distilledReviews: distilledReviews.slice(-MAX_TRACKED_REVIEWS), reviewLessons: lessons }, null, 2)}\n`,
+    `${JSON.stringify(
+      {
+        distilledReviews: distilledReviews.slice(-MAX_TRACKED_REVIEWS),
+        reviewLessons: lessons,
+        protectedLessonTexts: [...protectedTexts].slice(-MAX_PROTECTED_LESSON_TEXTS),
+      },
+      null,
+      2,
+    )}\n`,
   );
 }
 
+/** Lesson texts that must stay recognizable as reviewed knowledge, independent of
+ *  the bounded per-review map. Empty on a fresh or unreadable state file. */
+export function loadProtectedLessonTexts(dataDir: string): string[] {
+  try {
+    const raw = JSON.parse(readFileSync(stateFilePath(dataDir), "utf-8"));
+    const texts = Array.isArray(raw?.protectedLessonTexts) ? raw.protectedLessonTexts : [];
+    return texts.filter((text: unknown): text is string => typeof text === "string" && text.trim().length > 0);
+  } catch {
+    return [];
+  }
+}
+
 /** Record a review id as distilled (bounded — oldest entries drop off). Fail-soft. */
 export function markReviewDistilled(dataDir: string, reviewId: number): void {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.23.0",
+  "version": "4.24.1",
   "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: