nebulosity 1.0.0 → 1.1.0

package/lib/index/summarize/prompts.ts

@@ -1,10 +1,22 @@
+import type { SummaryTargetKind } from "../../db/schema";
 import type { Importer, SummaryText } from "../../db/store/summaries";
 import { childToward, lcaFolder } from "../aggregate";
 import { countLines } from "../languages/typescript";
 import { dirOf } from "../paths";
 
-/** Part of every inputHash. Bump it to redo every summary on purpose (a better prompt, new settings). Version 2: ADR-034. */
-export const PROMPT_VERSION = 2;
+/** Version 2, ADR-034. Version 3, plain short paragraphs with a length line (ADR-034, amended 2026-10-29). */
+export const PROMPT_VERSION = 3;
+
+/** The prompt that wrote a row whose prompt_version is null (P3). Version 1 never wrote a stored summary. */
+export const UNRECORDED_PROMPT_VERSION = 2;
+
+/**
+ * Whether a row holds model text an older prompt wrote. A template isn't model text, and a row with no model has no
+ * text yet. A null prompt_version reads as UNRECORDED_PROMPT_VERSION.
+ */
+export function writtenInOlderStyle(row: { model: string | null; promptVersion: number | null }): boolean {
+    return !!row.model && row.model !== "template" && (row.promptVersion ?? UNRECORDED_PROMPT_VERSION) < PROMPT_VERSION;
+}
 
 /**
  * Who writes what by default (ADR-028): Haiku for the many files, Sonnet for the folders and the repo people read first.
@@ -39,31 +51,102 @@ export const MAX_FOLDER_ITEMS = 50;
 /** A file's prompt names this many of the areas its importers sit in (PIVOT_SPEC.md §4.2's groups); the rest fold into a count. */
 export const MAX_IMPORTER_GROUPS = 3;
 
-// Prompt v2 (ADR-034). The taglines' examples are deliberately not from VS Code, so the model can't copy one into a summary.
+// Prompt v3.3 (ADR-034, amended 2026-10-29), v3.2 with a usage example that names a part instead of inviting a count,
+// still PROMPT_VERSION 3 since no release wrote v3.2. The taglines' examples are deliberately not from VS Code, so the model can't copy one into a summary.
+const PLAIN = "Use short sentences, with no semicolons, colons or dashes. When you need a technical term, say what it means the first time, or use a plainer word.";
+
 export const FILE_SYSTEM_PROMPT = [
-    "You write the summary a developer sees for one source file while exploring an unfamiliar codebase.",
-    "Give a tagline and a summary. The tagline is a noun phrase of 3 to 6 plain words, like \"Retry policy with exponential backoff\". The summary is 2 to 4 sentences.",
-    "The summary says what the file is responsible for, names its most important exports, and says how other code uses it. The \"Imported by\" line comes from the repository's import graph; use it to say how widely and where the file is used.",
-    "In the summary, write identifiers (functions, classes, types, variables and file names) in backticks, like `parseConfig`.",
-    "Use real identifiers from the file. Don't narrate the code line by line, and don't guess beyond what you're shown. Don't mention truncation or code you weren't shown.",
+    "You write the summary people see for one source file while they find their way around a codebase that's new to them. Write for a smart reader who doesn't know this project's vocabulary.",
+    "Give a tagline and a summary. The tagline is a noun phrase of 3 to 6 plain words that says what the file is for, like \"Automatic retry for failed requests\". It doesn't count toward the summary's length.",
+    "The summary is short paragraphs with a blank line between them. The last line of the request says about how many words, paragraphs and code names to use. Stay close to it, and use fewer when the file is simple.",
+    "The first paragraph is 1 or 2 sentences on what the file is for and why the project needs it, in everyday words, with no code names.",
+    "Then say what's inside. Name only the most important exports, in backticks like `parseConfig`, and say in plain words what each one does.",
+    "End with one sentence on how widely the file is used and where, from the \"Imported by\" line, which comes from the repository's import graph. Say it in words that match how widely it really is used, like \"Almost every part of the app relies on it.\" or \"The settings screen uses it, and little else does.\" Name the parts that use it, never a number of files.",
+    PLAIN,
+    "Don't narrate the code line by line, don't guess beyond what you're shown, and don't mention truncation or code you weren't shown.",
 ].join("\n");
 
 export const FOLDER_SYSTEM_PROMPT = [
-    "You write the summary a developer sees for one folder while exploring an unfamiliar codebase. You're given the summaries of the files and subfolders inside it.",
-    "Give a tagline and a summary. The tagline is a noun phrase of 3 to 6 plain words, like \"Payment provider integrations\". The summary is 2 to 4 sentences.",
-    "The summary says what the folder is responsible for as a whole, which parts matter most, and how they fit together.",
-    "In the summary, write file, folder, function and class names in backticks, like `retry.ts`.",
-    "Don't list every item, and don't guess beyond the summaries you're given.",
+    "You write the summary people see for one folder while they find their way around a codebase that's new to them. You're given the summaries of the files and subfolders inside it. Write for a smart reader who doesn't know this project's vocabulary.",
+    "Give a tagline and a summary. The tagline is a noun phrase of 3 to 6 plain words that says what the folder is for, like \"Online payment handling\". It doesn't count toward the summary's length.",
+    "The summary is short paragraphs with a blank line between them. The last line of the request says about how many words, paragraphs and code names to use. Stay close to it, and use fewer when the folder is simple.",
+    "The first paragraph is 1 or 2 sentences on what this part of the project does, in everyday words, with no code names.",
+    "Then say which parts matter most and how they fit together. Name only the most important files or subfolders, in backticks like `checkout/`, and say in plain words what each one does.",
+    PLAIN,
+    "Don't list every item, don't give numbers of files, and don't guess beyond the summaries you're given.",
 ].join("\n");
 
 export const REPO_SYSTEM_PROMPT = [
-    "You write the overview a developer sees first when opening an unfamiliar repository. You're given the summaries of its top-level folders and files.",
-    "Give a tagline and a summary. The tagline is a noun phrase of 3 to 6 plain words, like \"Distributed task scheduling service\". The summary is 2 to 4 sentences.",
-    "The summary says what the project is, names its main areas, and says where a newcomer should start reading.",
-    "In the summary, write folder and file names in backticks, like `src/server`.",
-    "Don't guess beyond the summaries you're given.",
+    "You write the overview people see first when they open a repository that's new to them. You're given the summaries of its top-level folders and files. Write for a smart reader who doesn't know this project's vocabulary.",
+    "Give a tagline and a summary. The tagline is a noun phrase of 3 to 6 plain words that says what the project is, like \"Online store server\". It doesn't count toward the summary's length.",
+    "The summary is short paragraphs with a blank line between them. The last line of the request says about how many words, paragraphs and code names to use. Stay close to it.",
+    "The first paragraph is 1 or 2 sentences on what the project is and who it's for, in everyday words, with no code names.",
+    "Then name its main areas, in backticks like `src/server`, each with a few plain words on what it holds, and end by saying where a newcomer should start reading.",
+    PLAIN,
+    "Don't give numbers of files, and don't guess beyond the summaries you're given.",
 ].join("\n");
 
+/** How long a summary is asked to be. Its line ends every request (lengthLine). */
+export type LengthTier = "small" | "medium" | "large";
+
+/*
+ * The tiers' thresholds (ADR-034, amended 2026-10-29). A file is large at LARGE_FILE_LINES lines or more, or at
+ * LARGE_FILE_IMPORTERS importers or more, and small under SMALL_FILE_LINES lines with SMALL_FILE_IMPORTERS importers or
+ * fewer. A folder is large at LARGE_FOLDER_FILES files or more, and small at SMALL_FOLDER_FILES or fewer. Everything
+ * else is medium, and the repo is always large. On VS Code's model-written summaries that makes files 38% small, 48%
+ * medium and 14% large, and folders 69%, 29% and 3%, as measured by evidence/probes/spread.cjs in the plainer
+ * summaries ledger (.superpowers/sdd/2026-10-29-plain-summaries).
+ */
+export const SMALL_FILE_LINES = 120;
+export const SMALL_FILE_IMPORTERS = 3;
+export const LARGE_FILE_LINES = 600;
+export const LARGE_FILE_IMPORTERS = 30;
+export const SMALL_FOLDER_FILES = 5;
+export const LARGE_FOLDER_FILES = 100;
+
+/** A file's tier, from its line count and every file that imports it (tests included), large first. */
+export function fileTier(lineCount: number, importers: number): LengthTier {
+    if (lineCount >= LARGE_FILE_LINES || importers >= LARGE_FILE_IMPORTERS) return "large";
+    if (lineCount < SMALL_FILE_LINES && importers <= SMALL_FILE_IMPORTERS) return "small";
+    return "medium";
+}
+
+/** A folder's tier, from the source files under it. */
+export function folderTier(fileCount: number): LengthTier {
+    if (fileCount >= LARGE_FOLDER_FILES) return "large";
+    if (fileCount <= SMALL_FOLDER_FILES) return "small";
+    return "medium";
+}
+
+/** What a length line counts, per kind of target. */
+const NAMED: Record<SummaryTargetKind, string> = { file: "exports", folder: "files or subfolders", repo: "folders or files" };
+
+/** Each tier's word target (design §4). Folders and the repo are told these, and kept within them in the samples. */
+export const TIER_WORDS: Record<LengthTier, number> = { small: 50, medium: 90, large: 150 };
+
+/**
+ * The words a file is told, below its tier's target for small and medium files. The final sample (Summary Review #6)
+ * measured Haiku writing 1.6 to 1.8 times what it was told on small files and 1.1 to 1.3 times on medium ones, so
+ * these land it near 50 and 90 (the owner, 2026-10-29, as design §4 allowed). Large files kept within 150.
+ */
+export const FILE_TOLD_WORDS: Record<LengthTier, number> = { small: 30, medium: 70, large: 150 };
+
+/** The request's last line, saying about how many words, paragraphs and code names a summary of this tier uses. */
+export function lengthLine(kind: SummaryTargetKind, tier: LengthTier): string {
+    const what = NAMED[kind];
+    const words = (kind === "file" ? FILE_TOLD_WORDS : TIER_WORDS)[tier];
+    switch (tier){
+        case "small": return `Write at most ${words} words, in 2 paragraphs, and name at most 2 ${what}.`;
+        case "medium": return `Write at most ${words} words, in 2 or 3 paragraphs, and name at most 3 ${what}.`;
+        case "large": return `Write at most ${words} words, in up to 5 paragraphs, as many as it needs, and name at most 5 ${what}.`;
+    }
+}
+
+/** A request's body with its length line last, after a blank line, where sample #2 measured it. */
+export function withLengthLine(body: string, kind: SummaryTargetKind, tier: LengthTier): string {
+    return `${body}\n\n${lengthLine(kind, tier)}`;
+}
+
 /** One child of a folder, as its prompt shows it. lineCount is a folder's total, used only for ordering. */
 export type FolderItem = { name: string; kind: "file" | "folder"; fileCount: number; lineCount: number; text: SummaryText | null };
 
@@ -72,6 +155,11 @@ export function plural(n: number, word: string, pluralWord = `${word}s`): string
     return `${n.toLocaleString("en-US")} ${n === 1 ? word : pluralWord}`;
 }
 
+/** A summary on one line, for the readers that show it so: its paragraphs, each trimmed, joined by a space. */
+export function joinParagraphs(summary: string): string {
+    return summary.split(/\n\s*\n/).map((paragraph) => paragraph.trim()).filter((paragraph) => paragraph !== "").join(" ");
+}
+
 /**
  * A file's prompt: the imports/exports listing chunks.ts generates (it opens with
  * "File: <path>"), the line count, who imports the file (the line importerLine renders),
@@ -130,43 +218,52 @@ export function importerLine(filePath: string, importers: readonly Importer[], m
     return line;
 }
 
+/** A folder's prompt, its body only (the length line is added by withLengthLine). oneLine is listItems'. */
 export function renderFolderPrompt(
     folder: { path: string; fileCount: number; directFileCount: number },
     items: readonly FolderItem[],
-    maxItems: number = MAX_FOLDER_ITEMS
+    maxItems: number = MAX_FOLDER_ITEMS,
+    oneLine: boolean = true
 ): string {
     return [
         `Folder: ${folder.path}`,
         `${plural(folder.fileCount, "source file")} in total, ${folder.directFileCount} directly inside.`,
         "",
         "Contents, largest first:",
-        ...listItems(items, maxItems),
+        ...listItems(items, maxItems, oneLine),
     ].join("\n");
 }
 
+/** The repo's prompt, its body only (the length line is added by withLengthLine). oneLine is listItems'. */
 export function renderRepoPrompt(
     repo: { name: string; fileCount: number; folderCount: number },
     items: readonly FolderItem[],
-    maxItems: number = MAX_FOLDER_ITEMS
+    maxItems: number = MAX_FOLDER_ITEMS,
+    oneLine: boolean = true
 ): string {
     return [
         `Repository: ${repo.name}`,
         `${plural(repo.fileCount, "source file")} in ${plural(repo.folderCount, "folder")}.`,
         "",
         "Top-level contents, largest first:",
-        ...listItems(items, maxItems),
+        ...listItems(items, maxItems, oneLine),
     ].join("\n");
 }
 
-/** Largest first (by lines), ties by name; the overflow becomes one "…and N smaller items" line. */
-function listItems(items: readonly FolderItem[], maxItems: number): string[] {
+/**
+ * Largest first (by lines), ties by name; the overflow becomes one "…and N smaller items" line. Each child's summary
+ * is written on one line (joinParagraphs), so one child stays one line. With oneLine false it's written verbatim, as
+ * prompt v2 did, for P2's older check, which renders a folder's body the way the version that wrote it did.
+ */
+function listItems(items: readonly FolderItem[], maxItems: number, oneLine: boolean): string[] {
     const sorted = [...items].sort((a, b) => b.lineCount - a.lineCount || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
     const lines = sorted.slice(0, maxItems).map((item) => {
         const label = item.kind === "folder"
             ? `${item.name}/ (${plural(item.fileCount, "file")})`
             : `${item.name} (${plural(item.lineCount, "line")})`;
-        return `- ${label}: ${item.text ? `${item.text.tagline} — ${item.text.summary}` : "(no summary yet)"}`;
+        if (!item.text) return `- ${label}: (no summary yet)`;
+        return `- ${label}: ${item.text.tagline} — ${oneLine ? joinParagraphs(item.text.summary) : item.text.summary}`;
     });
 
     const hidden = sorted.length - maxItems;

package/lib/index/summarize/run.ts

@@ -16,9 +16,11 @@ import { repoKey } from "../paths";
 import { projectSpend, type ProjectedRequest } from "./budget";
 import { mapLimit } from "./concurrency";
 import { DEFAULT_SUMMARY_MODELS, type ResolvedSummaryModels } from "./models";
-import { foldersAbove, type PlannedTarget, type TargetState } from "./plan";
+import { foldersAbove, type PlannedTarget, type Restyle, type TargetState } from "./plan";
 import { formatUsd } from "./pricing";
-import { FILE_SYSTEM_PROMPT, FOLDER_SYSTEM_PROMPT, importerLine, plural, REPO_SYSTEM_PROMPT, renderFilePrompt } from "./prompts";
+import {
+    FILE_SYSTEM_PROMPT, fileTier, FOLDER_SYSTEM_PROMPT, importerLine, plural, PROMPT_VERSION, REPO_SYSTEM_PROMPT, renderFilePrompt, withLengthLine,
+} from "./prompts";
 import { planSnapshot, type Snapshot } from "./snapshot";
 import { refreshSummaryStatus, stillAtAnthropic, summaryStageStatus } from "./status";
 import { BatchGoneError, ModelUnavailableError, SummarizerAuthError, type Summarizer, type SummaryOutcome, type SummaryRequest } from "./types";
@@ -42,6 +44,16 @@ export type SummaryRunOptions = {
     wait?: boolean;
     /** Redo out-of-date folders now (default). Incremental runs pass false: those wait until someone opens them. */
     refreshStaleFolders?: boolean;
+    /**
+     * true redoes the summaries an older prompt version wrote, as `nebulosity summarize` does after its estimate and yes.
+     * The worker's jobs leave it off.
+     */
+    restyle?: boolean;
+    /**
+     * true leaves an out-of-date folder or the repo an older prompt version wrote to be opened, and lets the folder
+     * above it go without it (PlanOptions.olderFoldersWaitToBeOpened, Q2 B). The sweep passes it. Default: false.
+     */
+    olderFoldersWaitToBeOpened?: boolean;
     pollIntervalMs?: number;
     /** How often a long wave refreshes the stage and the lock. */
     heartbeatMs?: number;
@@ -220,6 +232,11 @@ type RunContext = {
      * writes are part of the rest the spend cap projects (foldersAbove); otherwise they turn lazy, and nothing sends them.
      */
     refreshStaleFolders: boolean;
+    /**
+     * Which summaries an older prompt version wrote every pass redoes (SummaryRunOptions.restyle): "all" when the run was
+     * told to restyle, else "none". Every wave plans the same way, so a later wave restyles what an earlier one left.
+     */
+    restyle: Restyle;
     /**
      * The note of the spend-cap check that failed in this pass; every pass starts with none. While it's set nothing more
      * is sent, but batches at Anthropic are still collected, and the run finishes with it when nothing more can happen.
@@ -235,10 +252,11 @@ type RunContext = {
 
 function newContext(
     db: Db, repoId: number, root: string, models: ResolvedSummaryModels, say: (message: string) => void, budget: Budget | null = null,
-    select: (target: PlannedTarget) => boolean = () => true, sendLeft: number = Infinity, refreshStaleFolders: boolean = true
+    select: (target: PlannedTarget) => boolean = () => true, sendLeft: number = Infinity, refreshStaleFolders: boolean = true,
+    restyle: Restyle = "none"
 ): RunContext {
     return {
-        db, repoId, root, models, say, budget, select, sendLeft, refreshStaleFolders,
+        db, repoId, root, models, say, budget, select, sendLeft, refreshStaleFolders, restyle,
         failedThisRun: new Set(),
         tally: { summarized: 0, templated: 0, failed: 0, batches: 0, waves: 0 },
         missedPasses: 0,
@@ -275,8 +293,9 @@ export async function runSummaries(repoRoot: string, options: SummaryRunOptions)
         repoUsd: options.repoBudgetUsd ?? null,
     };
     const refreshStaleFolders = options.refreshStaleFolders ?? true;
+    const olderFoldersWaitToBeOpened = options.olderFoldersWaitToBeOpened ?? false;
     const ctx = newContext(db, repoId, root, options.models ?? DEFAULT_SUMMARY_MODELS, options.onProgress ?? (() => {}), budget,
-        options.select, options.maxTargets, refreshStaleFolders);
+        options.select, options.maxTargets, refreshStaleFolders, options.restyle ? "all" : "none");
     let last: PlannedTarget[] = [];
 
     // a mistyped id must fail before anything is locked, released or rewritten
@@ -290,7 +309,7 @@ export async function runSummaries(repoRoot: string, options: SummaryRunOptions)
             ctx.say(`released ${batchId}: ${plural(released, "request")} will be sent again`);
         }
         for (;;){
-            const snap = planSnapshot(db, repoId, refreshStaleFolders, ctx.failedThisRun, ctx.models);
+            const snap = planSnapshot(db, repoId, refreshStaleFolders, ctx.failedThisRun, ctx.models, ctx.restyle, olderFoldersWaitToBeOpened);
             last = snap.targets;
             const ids = applyTargetUpdates(db, repoId, snap.targets);
             ctx.tally.templated += snap.targets.filter((t) => t.state === "template").length;
@@ -365,16 +384,19 @@ export async function runSummaries(repoRoot: string, options: SummaryRunOptions)
  * What a full run would send to a model right now (S11): every target still to be written, as the kind and model of its
  * request, planned the way runSummaries' first pass plans (stale folders redone), and then every folder and the repo
  * above them, which their new text puts out of date (foldersAbove, R24), and above what's still at Anthropic. A template
- * is no request. Reads only.
+ * is no request. With restyle (the default, as a full run restyles), every summary an older prompt version wrote is one
+ * too, marked restyle; false plans as `--no-restyle` runs, leaving them as they are. Reads only.
  */
-export function plannedRequests(repoRoot: string, models: ResolvedSummaryModels = DEFAULT_SUMMARY_MODELS): ProjectedRequest[] {
+export function plannedRequests(
+    repoRoot: string, models: ResolvedSummaryModels = DEFAULT_SUMMARY_MODELS, restyle: boolean = true
+): ProjectedRequest[] {
     const db = getDb();
     const repoId = requireRepository(db, repoKey(path.resolve(repoRoot)));
     const toWrite: ReadonlySet<TargetState> = new Set(["ready", "waiting", "lazy", "failed"]);
-    const targets = planSnapshot(db, repoId, true, new Set(), models).targets;
+    const targets = planSnapshot(db, repoId, true, new Set(), models, restyle ? "all" : "none").targets;
     const written = targets.filter((t) => toWrite.has(t.state) && t.model !== "template");
     const above = foldersAbove(targets, [...written, ...targets.filter((t) => t.state === "in-flight")]);
-    return [...written, ...above].map((t) => ({ kind: t.kind, model: t.model }));
+    return [...written, ...above].map((t) => ({ kind: t.kind, model: t.model, ...(t.restyle ? { restyle: true as const } : {}) }));
 }
 
 /**
@@ -386,8 +408,10 @@ const summarizingNow = new Map<string, Promise<StoredSummary>>();
 /**
  * Summarizes one file or folder right now through the regular API, jumping the queue (PIVOT_SPEC.md §5.3: the Map calls
  * this when someone opens a path that has no summary, or an out-of-date one). A current summary comes back as it is,
- * without an API call. A folder whose children aren't all summarized is refused (TargetNotReadyError): its summary would
- * be written over "(no summary yet)" lines. Concurrent calls for one target share one request (ADR-033, amended).
+ * without an API call, unless an older prompt version wrote it: that one target is rewritten in the current style (P8,
+ * Q2 B), and its children are left as they are. A folder whose children aren't all summarized is refused
+ * (TargetNotReadyError): its summary would be written over "(no summary yet)" lines. Concurrent calls for one target
+ * share one request (ADR-033, amended).
  * A model the API no longer serves throws ModelUnavailableError, leaving the row as it was (ADR-066).
  */
 export function summarizeNow(
@@ -407,7 +431,10 @@ async function summarizeOnce(root: string, targetPath: string, summarizer: Summa
     const db = getDb();
     const repoId = requireRepository(db, repoKey(root));
     requireStructureReady(db, repoId);
-    const snap = planSnapshot(db, repoId, true, new Set(), models);
+    // Only the opened target is restyled (P8): children an older prompt wrote count as current, so a folder whose
+    // children are all in the older style is ready at once instead of waiting for them. An out-of-date child folder an
+    // older prompt wrote waits to be opened itself (Q2 B), so it doesn't keep this one waiting either.
+    const snap = planSnapshot(db, repoId, true, new Set(), models, { path: targetPath }, true);
     const target = snap.targets.find((t) => t.path === targetPath);
     if (!target) throw new TargetNotFoundError(targetPath);
     if (target.state === "waiting") throw new TargetNotReadyError(targetPath);
@@ -433,9 +460,9 @@ async function summarizeOnce(root: string, targetPath: string, summarizer: Summa
 }
 
 /**
- * A file's prompt, built from exactly the bytes the index saw. Null when the file changed
- * on disk after indexing, or vanished: a summary of different bytes would contradict the
- * structure the index holds for it.
+ * A file's prompt, built from exactly the bytes the index saw, ending with its tier's length line (P6). Null when the
+ * file changed on disk after indexing, or vanished: a summary of different bytes would contradict the structure the
+ * index holds for it.
  */
 export function buildFilePrompt(db: Db, repoId: number, root: string, file: Pick<FileFacts, "path" | "contentHash" | "lineCount">): string | null {
     let source: string;
@@ -451,7 +478,10 @@ export function buildFilePrompt(db: Db, repoId: number, root: string, file: Pick
     if (listing === null) return null;
 
     // The importers are in the prompt but not in the input hash (path + content only, plan.ts), so a new importer doesn't re-summarize a central file on every pull.
-    return renderFilePrompt(listing, file.lineCount, importerLine(file.path, loadImporters(db, repoId, file.path)), source);
+    // Their count, tests included (the same count as FileFacts.importedBy), also sets the tier, which is likewise left out of the hash.
+    const importers = loadImporters(db, repoId, file.path);
+    const body = renderFilePrompt(listing, file.lineCount, importerLine(file.path, importers), source);
+    return withLengthLine(body, "file", fileTier(file.lineCount, importers.length));
 }
 
 /**
@@ -873,7 +903,7 @@ function ingest(
             id: destination.id,
             batchId: destination.batchId,
             inputHash: destination.inputHash,
-            outcome: outcome.ok ? { ok: true, text: outcome.text, model: outcome.model } : { ok: false, error: outcome.error },
+            outcome: outcome.ok ? { ok: true, text: outcome.text, model: outcome.model, promptVersion: PROMPT_VERSION } : { ok: false, error: outcome.error },
         });
 
         if (outcome.ok){

package/lib/index/summarize/snapshot.ts

@@ -1,7 +1,7 @@
 import type { Db } from "../../db/client";
 import { loadFileFacts, loadFolderFacts, loadSummaries, type FileFacts } from "../../db/store/summaries";
 import type { ResolvedSummaryModels } from "./models";
-import { planSummaries, type PlannedTarget } from "./plan";
+import { planSummaries, type PlannedTarget, type Restyle } from "./plan";
 
 /** One planning pass: the plan, and the file facts it was made from. */
 export type Snapshot = { targets: PlannedTarget[]; files: Map<string, FileFacts> };
@@ -10,9 +10,12 @@ export type Snapshot = { targets: PlannedTarget[]; files: Map<string, FileFacts>
  * Plans every target of a repo from what the database holds right now. Summary runs, summarizeNow and the stage
  * refresh (status.ts) all plan through here, so they can't disagree about a target's state. `models` is the setting
  * as resolved for this job (ADR-066): the model is part of every inputHash, so every planner has to use the same one.
+ * `restyle` is PlanOptions.restyle: which summaries an older prompt wrote this plan redoes (P1).
+ * `olderFoldersWaitToBeOpened` is PlanOptions.olderFoldersWaitToBeOpened (Q2 B).
  */
 export function planSnapshot(
-    db: Db, repoId: number, refreshStaleFolders: boolean, failedThisRun: ReadonlySet<string>, models: ResolvedSummaryModels
+    db: Db, repoId: number, refreshStaleFolders: boolean, failedThisRun: ReadonlySet<string>, models: ResolvedSummaryModels,
+    restyle: Restyle = "none", olderFoldersWaitToBeOpened: boolean = false
 ): Snapshot {
     // One read transaction: a structure run committing meanwhile can't hand us half of its changes.
     // (better-sqlite3 has one connection, so reads through `db` inside the callback belong to it.)
@@ -22,6 +25,8 @@ export function planSnapshot(
             models: models.models,
             refreshStaleFolders,
             failedThisRun,
+            restyle,
+            olderFoldersWaitToBeOpened,
         });
         return { targets, files: new Map(files.map((f) => [f.path, f])) };
     });

package/lib/index/summarize/status.ts

@@ -90,8 +90,9 @@ export function refreshSummaryStatus(
     if (!models.ok && options.summarizerAvailable) return null;
     const db = getDb();
     const repoId = requireRepository(db, repoKey(path.resolve(repoRoot)));
-    // between runs, out-of-date folders are lazy: redone when opened, or by the background worker's sweep
-    const snap = planSnapshot(db, repoId, false, new Set(), models.ok ? models : DEFAULT_SUMMARY_MODELS);
+    // between runs, out-of-date folders are lazy: redone when opened, or by the background worker's sweep. Nothing is
+    // restyled: a summary an older prompt wrote for the same input counts as current, so it isn't waiting (P1).
+    const snap = planSnapshot(db, repoId, false, new Set(), models.ok ? models : DEFAULT_SUMMARY_MODELS, "none");
     if (models.ok) applyTargetUpdates(db, repoId, snap.targets);
     if (isSummaryLockHeld(db)) return null;
 

package/lib/tools/text.ts

@@ -1,5 +1,6 @@
 import type { SummaryStatus } from "../contracts";
 import { freshnessNote } from "../engine/freshness";
+import { joinParagraphs } from "../index/summarize/prompts";
 
 /**
  * Answers stay under this many characters (ADR-047). Claude Code warns past 10,000 tokens and moves a text result of
@@ -18,10 +19,10 @@ export function shownPath(repoPath: string, kind: "folder" | "file"): string {
 /** A count as answers write it: 4231 → "4,231". */
 export const formatCount = (n: number): string => n.toLocaleString("en-US");
 
-/** The line where a summary goes: its text, or what's in its place. */
+/** The line where a summary goes: its text, its paragraphs joined by a space so it stays one line, or what's in its place. */
 export function summaryLine(target: { tagline?: string; summary?: string; summaryStatus: SummaryStatus; summaryError?: string }): string {
     if (target.tagline){
-        const text = target.summary ? `${target.tagline} — ${target.summary}` : target.tagline;
+        const text = target.summary ? `${target.tagline} — ${joinParagraphs(target.summary)}` : target.tagline;
         return target.summaryStatus === "stale" ? `${text} (Out of date: changed since it was summarized.)` : text;
     }
     if (target.summaryStatus === "off") return SUMMARIES_OFF_LINE;

package/mcp/server.ts

@@ -16,7 +16,7 @@ import { setupCall } from "../lib/tools/repo";
 import { deliveryNote, type MapDelivery } from "../lib/tools/text";
 
 /** package.json's version (a test keeps them equal). */
-export const SERVER_VERSION = "1.0.0";
+export const SERVER_VERSION = "1.1.0";
 
 /** Sends one live event to the Map's server on `port`; true when it took it (lib/live/client.ts). */
 export type LivePoster = (event: LiveEvent, port: number) => Promise<boolean>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nebulosity",
-  "version": "1.0.0",
-  "description": "A live map of how a big codebase fits together, for Claude Code and for you: a local import index, an MCP server and the Map.",
+  "version": "1.1.0",
+  "description": "A live map of how a big codebase fits together, for Claude Code and for you, with a local import index, an MCP server and the Map.",
   "keywords": [
     "claude-code",
     "mcp",
@@ -61,6 +61,7 @@
     "!.next/**/*.map",
     "!.next/**/*.nft.json",
     "!**/*.test.ts",
+    "!**/*.test.tsx",
     "LICENSE",
     "README.md"
   ],
@@ -84,6 +85,7 @@
     "bench-calls": "tsx scripts/bench-calls.ts",
     "bench-languages": "tsx scripts/bench-languages.ts",
     "check-layout": "node scripts/check-layout.mjs",
+    "check-routes": "tsx scripts/check-routes.ts",
     "compare-summaries": "tsx scripts/compare-summaries.ts",
     "eval:run": "tsx scripts/eval/run.ts",
     "eval:probe": "tsx scripts/eval/probe.ts",

package/scripts/commands/summarize-command.ts

@@ -1,5 +1,5 @@
 /**
- * nebulosity summarize <path-to-repo> [--direct | --batch] [--no-wait] [--budget <usd>] [--path <repo-relative path>]
+ * nebulosity summarize <path-to-repo> [--direct | --batch] [--no-wait] [--no-restyle] [--budget <usd>] [--path <repo-relative path>]
  *                      [--release-batch <batch id>]... [--yes]
  * (in a checkout: npm run summarize -- <path-to-repo> …)
  *
@@ -8,6 +8,9 @@
  *   --no-wait never sleeps: it collects the batches that have already ended, submits what
  *   that makes ready, and exits. Running the command again (by hand, or from cron) carries
  *   on from there.
+ * - A full run also rewrites, in the current style, the summaries an older Nebulosity wrote (P7), and its estimate says
+ *   how many requests do that. --no-restyle leaves them as they are, so a catch-up sends only what changed: the spend
+ *   cap counts the repo's spend across runs, and a big repo's restyle could take it past the budget before anything else.
  * - --budget caps this repo's recorded summary spend (summary_usage, across runs), in US
  *   dollars (default 15, S2's ceiling); ADR-035 lists the spend it can't see, such as the
  *   checkpoint reviews. Before each batch or regular-API wave the run projects spent + at
@@ -39,6 +42,7 @@ import { summarizerFromEnv } from "../../lib/index/summarize/claude";
 import { estimateSpend } from "../../lib/index/summarize/estimate";
 import { configuredSummaryModels, type ResolvedSummaryModels } from "../../lib/index/summarize/models";
 import { costUsd, formatUsd, type PriceTable } from "../../lib/index/summarize/pricing";
+import { joinParagraphs, plural } from "../../lib/index/summarize/prompts";
 import {
     BATCH_THRESHOLD, BatchesUnreachableError, DEFAULT_BUDGET_USD, plannedRequests, runSummaries, StructureNotReadyError, summarizeNow, TargetNotFoundError,
     TargetNotReadyError, UnknownBatchError, type Transport,
@@ -47,7 +51,7 @@ import { ModelUnavailableError } from "../../lib/index/summarize/types";
 import { keyHint } from "../../lib/hints";
 import { loadLocalEnv } from "../env";
 
-const USAGE = "usage: nebulosity summarize <path-to-repo> [--direct | --batch] [--no-wait] [--budget <usd>] [--path <repo-relative path>] [--release-batch <batch id>]... [--yes]"
+const USAGE = "usage: nebulosity summarize <path-to-repo> [--direct | --batch] [--no-wait] [--no-restyle] [--budget <usd>] [--path <repo-relative path>] [--release-batch <batch id>]... [--yes]"
     + "   (in a checkout: npm run summarize -- <path-to-repo> …)";
 
 /** The arguments as a run uses them, or null when they can't be run as given. */
@@ -56,6 +60,8 @@ type SummarizeOptions = {
     onePath: string | null;
     transport: Transport;
     wait: boolean;
+    /** A full run rewrites the summaries an older version wrote (P7), unless --no-restyle is given. */
+    restyle: boolean;
     budgetUsd: number;
     releaseBatches: string[];
     /** --yes: spend without being asked (the only way without a terminal). */
@@ -65,7 +71,7 @@ type SummarizeOptions = {
 /**
  * Every argument after the repo path must be one this command knows, or it stops here. An argument it ignored would
  * leave the defaults in charge: "--path=src/x.ts" used to start a full summary pass (up to the $15 budget) instead of
- * the one request --path asks for. So, each at most once: the three switches, and the two options whose value is the
+ * the one request --path asks for. So, each at most once: the five switches, and the two options whose value is the
  * next argument, whatever it is ("--path ''" is the repo itself). Anything else, a "--flag=value" spelling or a second
  * repo path included, gets the usage line.
  */
@@ -73,7 +79,7 @@ function parseSummarizeArgs(args: readonly string[]): SummarizeOptions | null {
     const target = args[0];
     if (!target || target.startsWith("--")) return null;
 
-    const SWITCHES = ["--direct", "--batch", "--no-wait", "--yes"];
+    const SWITCHES = ["--direct", "--batch", "--no-wait", "--no-restyle", "--yes"];
     const OPTIONS = ["--budget", "--path"];
     const REPEATABLE = ["--release-batch"];
     const repeated = new Map<string, string[]>();
@@ -108,6 +114,7 @@ function parseSummarizeArgs(args: readonly string[]): SummarizeOptions | null {
         onePath: values.get("--path") ?? null,
         transport: switches.has("--direct") ? "direct" : switches.has("--batch") ? "batch" : "auto",
         wait: !switches.has("--no-wait"),
+        restyle: !switches.has("--no-restyle"),
         budgetUsd,
         releaseBatches,
         yes: switches.has("--yes"),
@@ -168,12 +175,17 @@ async function summarize(options: SummarizeOptions): Promise<number> {
         }
         const row = await summarizeNow(root, onePath, summarizer, models);
         say(`${row.kind} ${row.path || "(repo)"}: ${row.status}${row.error ? ` (${row.error})` : ""}`);
-        if (row.tagline) say(`${row.tagline} — ${row.summary}`);
+        // on one line (P9): a summary's paragraphs, joined by a space
+        if (row.tagline) say(`${row.tagline} — ${joinParagraphs(row.summary ?? "")}`);
     } else{
         if (!summarizer) say(`ANTHROPIC_API_KEY is not set: writing test-file templates only (summaries need a key: ${keyHint()}).`);
         else if (!(await confirmSpend(options, models))) return 1;
         const result = await runSummaries(root, {
-            summarizer, models, transport: options.transport, wait: options.wait, budgetUsd: options.budgetUsd, releaseBatches: options.releaseBatches, onProgress: say,
+            summarizer, models, transport: options.transport, wait: options.wait,
+            // Without a key nothing can be sent, a restyle included, so the run plans as the stage refresh does: what an
+            // older version wrote counts as current (P1), instead of turning the stage "off" over rewrites it can't send.
+            restyle: summarizer !== null && options.restyle,
+            budgetUsd: options.budgetUsd, releaseBatches: options.releaseBatches, onProgress: say,
         });
         say(`up to date ${result.upToDate}/${result.total} · summarized ${result.summarized} · templated ${result.templated}`
             + ` · failed ${result.failed} · lazy ${result.lazy} · at Anthropic ${result.inFlight}`
@@ -195,11 +207,12 @@ async function summarize(options: SummarizeOptions): Promise<number> {
 /**
  * The estimate and the yes (S11): prints what a full run would send and cost, then asks. Without a terminal it needs --yes.
  * A run with nothing to send needs no yes. A yes is recorded for the repo, with the run's budget. Returns false when the
- * run must not start. The requests are planned, and priced, with the summary models setting (ADR-066).
+ * run must not start. The requests are planned, and priced, with the summary models setting (ADR-066), and restyled as the
+ * run restyles (P7).
  */
 async function confirmSpend(options: SummarizeOptions, setting: ResolvedSummaryModels): Promise<boolean> {
     const { root } = options;
-    const requests = plannedRequests(root, setting);
+    const requests = plannedRequests(root, setting, options.restyle);
     const db = getDb();
     const repoId = requireRepository(db, repoKey(root));
 
@@ -223,9 +236,14 @@ async function confirmSpend(options: SummarizeOptions, setting: ResolvedSummaryM
     const folders = requests.filter((r) => r.kind === "folder").length.toLocaleString("en-US");
     // the repo is named apart only when the setting gives it a model of its own
     const above = models.repo === models.folder ? `${folders} folders and the repo to ${models.folder}` : `${folders} folders to ${models.folder} and the repo to ${models.repo}`;
+    // what an older version wrote, which this run rewrites unless it was given --no-restyle (P7)
+    const restyled = requests.filter((r) => r.restyle).length;
+    const restyle = restyled > 0
+        ? ` This includes rewriting ${plural(restyled, "summary", "summaries")} an older version of Nebulosity wrote, in the new plain style. Add --no-restyle to leave them as they are.`
+        : "";
     say(`${path.basename(root)}: about ${estimate.requests.toLocaleString("en-US")} requests (${files.toLocaleString("en-US")} files to ${models.file},`
         + ` ${above}), about ${formatUsd(estimate.usd)} at list prices`
-        + `${batch ? ", by the Batch API" : ""}${noPrice}. Writing summaries sends each file's code to Anthropic.`);
+        + `${batch ? ", by the Batch API" : ""}${noPrice}. Writing summaries sends each file's code to Anthropic.${restyle}`);
 
     if (!options.yes){
         if (!process.stdin.isTTY){

package/.next/server/chunks/ssr/[root-of-the-server]__0ekw8p2ramybv._.js

@@ -1,3 +0,0 @@
-module.exports=[[38872,a=>{let b={src:a.i(26758).default,width:256,height:256};a.s(["default",0,b])},48760,a=>{let b={src:a.i(71385).default,width:680,height:680};a.s(["default",0,b])},66114,a=>{var b=a.i(82509);a.n(b)},11857,(a,b,c)=>{b.exports=a.r(24951).vendored["react-rsc"].ReactServerDOMTurbopackServer},717,(a,b,c)=>{b.exports=a.r(24951).vendored["react-rsc"].React}],54799,(a,b,c)=>{b.exports=a.x("crypto",()=>require("crypto"))},70406,(a,b,c)=>{b.exports=a.x("next/dist/compiled/@opentelemetry/api",()=>require("next/dist/compiled/@opentelemetry/api"))},20635,(a,b,c)=>{b.exports=a.x("next/dist/server/app-render/action-async-storage.external.js",()=>require("next/dist/server/app-render/action-async-storage.external.js"))},24725,(a,b,c)=>{b.exports=a.x("next/dist/server/app-render/after-task-async-storage.external.js",()=>require("next/dist/server/app-render/after-task-async-storage.external.js"))},43285,(a,b,c)=>{b.exports=a.x("next/dist/server/app-render/dynamic-access-async-storage.external.js",()=>require("next/dist/server/app-render/dynamic-access-async-storage.external.js"))},56704,(a,b,c)=>{b.exports=a.x("next/dist/server/app-render/work-async-storage.external.js",()=>require("next/dist/server/app-render/work-async-storage.external.js"))},32319,(a,b,c)=>{b.exports=a.x("next/dist/server/app-render/work-unit-async-storage.external.js",()=>require("next/dist/server/app-render/work-unit-async-storage.external.js"))},59043,(a,b,c)=>{b.exports=a.x("next/dist/server/runtime-reacts.external.js",()=>require("next/dist/server/runtime-reacts.external.js"))},93695,(a,b,c)=>{b.exports=a.x("next/dist/shared/lib/no-fallback-error.external.js",()=>require("next/dist/shared/lib/no-fallback-error.external.js"))},81111,(a,b,c)=>{b.exports=a.x("node:stream",()=>require("node:stream"))},14747,(a,b,c)=>{b.exports=a.x("path",()=>require("path"))},26758,a=>{a.v("/_next/static/media/favicon.2vob68tjqpejf.ico"+(globalThis.NEXT_CLIENT_ASSET_SUFFIX||""))},71385,a=>{a.v("/_next/static/media/icon.0absiuod-8x8n.svg"+(globalThis.NEXT_CLIENT_ASSET_SUFFIX||""))},82509,(a,b,c)=>{let{createClientModuleProxy:d}=a.r(11857);a.n(d("[project]/node_modules/next/dist/client/components/builtin/global-error.js"))},62212,function(a){a.n(a.i(66114))},14465,(a,b,c)=>{(()=>{"use strict";var a={86:a=>{a.exports=function(a,b){return"string"==typeof a?g(a):"number"==typeof a?f(a,b):null},a.exports.format=f,a.exports.parse=g;var b=/\B(?=(\d{3})+(?!\d))/g,c=/(?:\.0*|(\.[^0]+)0+)$/,d={b:1,kb:1024,mb:1048576,gb:0x40000000,tb:0x10000000000,pb:0x4000000000000},e=/^((-|\+)?(\d+(?:\.\d+)?)) *(kb|mb|gb|tb|pb)$/i;function f(a,e){if(!Number.isFinite(a))return null;var f=Math.abs(a),g=e&&e.thousandsSeparator||"",h=e&&e.unitSeparator||"",i=e&&void 0!==e.decimalPlaces?e.decimalPlaces:2,j=!!(e&&e.fixedDecimals),k=e&&e.unit||"";k&&d[k.toLowerCase()]||(k=f>=d.pb?"PB":f>=d.tb?"TB":f>=d.gb?"GB":f>=d.mb?"MB":f>=d.kb?"KB":"B");var l=(a/d[k.toLowerCase()]).toFixed(i);return j||(l=l.replace(c,"$1")),g&&(l=l.split(".").map(function(a,c){return 0===c?a.replace(b,g):a}).join(".")),l+h+k}function g(a){if("number"==typeof a&&!isNaN(a))return a;if("string"!=typeof a)return null;var b,c=e.exec(a),f="b";return c?(b=parseFloat(c[1]),f=c[4].toLowerCase()):(b=parseInt(a,10),f="b"),Math.floor(d[f]*b)}}},c={};function d(b){var e=c[b];if(void 0!==e)return e.exports;var f=c[b]={exports:{}},g=!0;try{a[b](f,f.exports,d),g=!1}finally{g&&delete c[b]}return f.exports}d.ab="/ROOT/node_modules/next/dist/compiled/bytes/",b.exports=d(86)})()}];
-
-//# sourceMappingURL=%5Broot-of-the-server%5D__0ekw8p2ramybv._.js.map