@vellumai/assistant 0.8.10-dev.202606100110.1d2c8c4 → 0.8.10-dev.202606100317.c8b43c8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.8.10-dev.202606100110.1d2c8c4",
+  "version": "0.8.10-dev.202606100317.c8b43c8",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/memory/v2/__tests__/consolidation-job.test.ts

@@ -336,6 +336,20 @@ describe("memoryV2ConsolidateJob — non-empty buffer", () => {
     expect(enqueuedJobs.map((j) => j.type)).toEqual(["memory_v2_reembed"]);
   });
 
+  test("includes the core-pages curation section in the prompt only when a v3 flag is on", async () => {
+    // v2-only installs must not be instructed to curate memory/core-pages.md
+    // — the file feeds the v3 core lane and is inert without it.
+    v3FlagOn = false;
+    await memoryV2ConsolidateJob(makeJob(), CONFIG);
+    expect(runnerLastArgs?.prompt as string).not.toContain("core-pages");
+
+    v3FlagOn = true;
+    await memoryV2ConsolidateJob(makeJob(), CONFIG);
+    expect(runnerLastArgs?.prompt as string).toContain(
+      "## 10. Review `memory/core-pages.md`",
+    );
+  });
+
   test("returns run_failed and skips follow-ups when the runner reports failure", async () => {
     runnerImpl = async () => ({
       conversationId: "conv-1",

package/src/memory/v2/__tests__/consolidation-prompt-flag-gating-guard.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Guard: the DEFAULT consolidation prompt must not leak flag-gated feature
+ * content to installs that don't have the feature enabled.
+ *
+ * Why this exists: the consolidation prompt ships to every assistant with no
+ * `memory.v2.consolidation_prompt_path` override, and it is processed without
+ * any flag check at run time — so flag-gated instructions added to the shared
+ * template reach the entire default population at their next consolidation.
+ * That happened once: the memory-v3 `core-pages.md` curation step landed
+ * inline and instructed v2-only installs to curate a file nothing on their
+ * install reads, under premises ("kept in reach every turn", "the hot set")
+ * that are false without the v3 lanes. This is the same leak class
+ * `workspace-release-notes-feature-flag-guard.test.ts` blocks for UPDATES.md,
+ * via a path that guard doesn't cover.
+ *
+ * The rule this enforces: flag-gated content enters the template only via a
+ * `{{...}}` placeholder substituted by `renderConsolidationPrompt` under a
+ * `ConsolidationPromptOptions` gate. When you add a gated section, register
+ * it in GATED_SECTIONS below so the guard covers it.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  CORE_PAGES_CONSOLIDATION_SECTION,
+  renderConsolidationPrompt,
+} from "../prompts/consolidation.js";
+
+type Registry = {
+  flags: Array<{
+    key: string;
+    scope: string;
+    defaultEnabled: boolean;
+  }>;
+};
+
+/**
+ * Every flag-gated section of the consolidation prompt, with a short
+ * distinctive marker that would survive light rewording of the section body.
+ * The guard asserts neither appears in the all-gates-off rendering.
+ */
+const GATED_SECTIONS: Array<{
+  name: string;
+  section: string;
+  marker: string;
+}> = [
+  {
+    name: "memory-v3 core-pages curation (gate: memory-v3-shadow|live)",
+    section: CORE_PAGES_CONSOLIDATION_SECTION,
+    marker: "core-pages",
+  },
+];
+
+/** All `ConsolidationPromptOptions` gates forced off — the v2-only rendering. */
+const ALL_GATES_OFF = { includeCorePagesSection: false };
+
+// Registry helpers mirror workspace-release-notes-feature-flag-guard.test.ts.
+function loadDefaultDisabledAssistantFlagKeys(): string[] {
+  const registryPath = join(
+    process.cwd(),
+    "..",
+    "meta",
+    "feature-flags",
+    "feature-flag-registry.json",
+  );
+  const registry = JSON.parse(readFileSync(registryPath, "utf-8")) as Registry;
+  return registry.flags
+    .filter((flag) => flag.scope === "assistant" && !flag.defaultEnabled)
+    .map((flag) => flag.key)
+    .sort();
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function featureFlagKeyPattern(key: string): RegExp {
+  const escaped = escapeRegExp(key);
+  if (key.includes("-")) {
+    return new RegExp(`(?:^|[^a-z0-9-])${escaped}(?:$|[^a-z0-9-])`, "i");
+  }
+  return new RegExp("[`'\"]" + escaped + "[`'\"]", "i");
+}
+
+describe("default consolidation prompt flag-gating guard", () => {
+  const rendered = renderConsolidationPrompt("Jan 1, 12:00 AM", ALL_GATES_OFF);
+
+  test("leaves no unsubstituted {{...}} placeholders", () => {
+    // A placeholder added to the template but not wired into
+    // renderConsolidationPrompt's substitutions would ship raw braces to
+    // every default-prompt install.
+    const residue = rendered.match(/\{\{[A-Z0-9_]+\}\}/g) ?? [];
+    expect(
+      residue,
+      "Unsubstituted placeholder(s) in the default consolidation prompt — " +
+        "wire them through renderConsolidationPrompt and gate them via " +
+        "ConsolidationPromptOptions.",
+    ).toEqual([]);
+  });
+
+  test("contains no flag-gated section content when all gates are off", () => {
+    const violations: string[] = [];
+    for (const { name, section, marker } of GATED_SECTIONS) {
+      if (rendered.includes(section)) {
+        violations.push(`${name}: full section text present`);
+      }
+      if (rendered.includes(marker)) {
+        violations.push(`${name}: marker "${marker}" present`);
+      }
+    }
+
+    const message = [
+      "The default consolidation prompt reaches every install with no prompt",
+      "override, regardless of feature flags. Flag-gated feature instructions",
+      "must enter via a {{...}} placeholder substituted under a",
+      "ConsolidationPromptOptions gate (see CORE_PAGES_PLACEHOLDER for the",
+      "pattern) — never inline in CONSOLIDATION_PROMPT.",
+      "",
+      "Violations:",
+      ...violations.map((violation) => `  - ${violation}`),
+    ].join("\n");
+    expect(violations, message).toEqual([]);
+  });
+
+  test("references no default-disabled assistant feature flags", () => {
+    const violations: string[] = [];
+    for (const key of loadDefaultDisabledAssistantFlagKeys()) {
+      if (featureFlagKeyPattern(key).test(rendered)) {
+        violations.push(`references default-disabled flag "${key}"`);
+      }
+    }
+    expect(
+      violations,
+      "The default consolidation prompt must not mention default-disabled " +
+        "assistant feature flags by name.\n" +
+        violations.map((violation) => `  - ${violation}`).join("\n"),
+    ).toEqual([]);
+  });
+});

package/src/memory/v2/__tests__/prompts-consolidation.test.ts

@@ -60,13 +60,29 @@ afterAll(() => {
   rmSync(tmpWorkspace, { recursive: true, force: true });
 });
 
-const { CONSOLIDATION_PROMPT, CUTOFF_PLACEHOLDER, resolveConsolidationPrompt } =
-  await import("../prompts/consolidation.js");
+const {
+  CONSOLIDATION_PROMPT,
+  CORE_PAGES_CONSOLIDATION_SECTION,
+  CORE_PAGES_PLACEHOLDER,
+  CUTOFF_PLACEHOLDER,
+  resolveConsolidationPrompt,
+} = await import("../prompts/consolidation.js");
 
 const CUTOFF = "2026-05-01T12:00:00.000Z";
 
-const bundledPrompt = (): string =>
-  (CONSOLIDATION_PROMPT as string).replaceAll(CUTOFF_PLACEHOLDER, CUTOFF);
+/** Options for tests not exercising the v3 core-pages gate. */
+const NO_CORE = { includeCorePagesSection: false };
+const WITH_CORE = { includeCorePagesSection: true };
+
+const bundledPrompt = (includeCorePagesSection = false): string =>
+  (CONSOLIDATION_PROMPT as string)
+    .replaceAll(CUTOFF_PLACEHOLDER, CUTOFF)
+    .replaceAll(
+      CORE_PAGES_PLACEHOLDER,
+      includeCorePagesSection
+        ? (CORE_PAGES_CONSOLIDATION_SECTION as string)
+        : "",
+    );
 
 beforeEach(() => {
   warnCalls.length = 0;
@@ -88,7 +104,7 @@ afterEach(() => {
 
 describe("resolveConsolidationPrompt — no override", () => {
   test("returns the bundled prompt with {{CUTOFF}} substituted when overridePath is null", () => {
-    const result = resolveConsolidationPrompt(null, CUTOFF);
+    const result = resolveConsolidationPrompt(null, CUTOFF, NO_CORE);
     expect(result).toContain("You are running memory consolidation");
     expect(result).toContain(CUTOFF);
     expect(result).not.toContain(CUTOFF_PLACEHOLDER);
@@ -96,12 +112,49 @@ describe("resolveConsolidationPrompt — no override", () => {
   });
 });
 
+describe("resolveConsolidationPrompt — core-pages gate", () => {
+  test("omits the core-pages section (and any placeholder residue) when the v3 gate is off", () => {
+    // v2-only installs must not be told to curate a file nothing reads.
+    const result = resolveConsolidationPrompt(null, CUTOFF, NO_CORE);
+    expect(result).not.toContain("core-pages");
+    expect(result).not.toContain(CORE_PAGES_PLACEHOLDER);
+    // The section's slot collapses cleanly: §9 flows straight into the
+    // separator with no stray blank lines.
+    expect(result).toContain(
+      "never wholesale-clear.\n\n---\n\n# What NOT to do",
+    );
+  });
+
+  test("includes the core-pages section exactly once, in place, when the v3 gate is on", () => {
+    const result = resolveConsolidationPrompt(null, CUTOFF, WITH_CORE);
+    expect(result).toContain("## 10. Review `memory/core-pages.md`");
+    expect(result.split("## 10. Review").length - 1).toBe(1);
+    expect(result).not.toContain(CORE_PAGES_PLACEHOLDER);
+    // Positioned between §9 and the don'ts, as authored.
+    const sectionAt = result.indexOf("## 10. Review");
+    expect(sectionAt).toBeGreaterThan(result.indexOf("## 9. Trim"));
+    expect(sectionAt).toBeLessThan(result.indexOf("# What NOT to do"));
+  });
+
+  test("substitutes the placeholder in override files per the same gate", () => {
+    const path = join(tmpWorkspace, "custom-prompt.md");
+    writeFileSync(path, "Before\n{{CORE_PAGES_SECTION}}After {{CUTOFF}}\n");
+
+    const withCore = resolveConsolidationPrompt(path, CUTOFF, WITH_CORE);
+    expect(withCore).toContain("## 10. Review `memory/core-pages.md`");
+    expect(withCore).not.toContain(CORE_PAGES_PLACEHOLDER);
+
+    const withoutCore = resolveConsolidationPrompt(path, CUTOFF, NO_CORE);
+    expect(withoutCore).toBe(`Before\nAfter ${CUTOFF}\n`);
+  });
+});
+
 describe("resolveConsolidationPrompt — with override", () => {
   test("loads an absolute path verbatim and substitutes {{CUTOFF}}", () => {
     const path = join(tmpWorkspace, "custom-prompt.md");
     writeFileSync(path, "Custom prompt at {{CUTOFF}}\n");
 
-    const result = resolveConsolidationPrompt(path, CUTOFF);
+    const result = resolveConsolidationPrompt(path, CUTOFF, NO_CORE);
 
     expect(result).toBe(`Custom prompt at ${CUTOFF}\n`);
     expect(warnCalls).toHaveLength(0);
@@ -113,7 +166,11 @@ describe("resolveConsolidationPrompt — with override", () => {
       "Workspace-relative {{CUTOFF}}\n",
     );
 
-    const result = resolveConsolidationPrompt("custom-prompt.md", CUTOFF);
+    const result = resolveConsolidationPrompt(
+      "custom-prompt.md",
+      CUTOFF,
+      NO_CORE,
+    );
 
     expect(result).toBe(`Workspace-relative ${CUTOFF}\n`);
     expect(warnCalls).toHaveLength(0);
@@ -124,7 +181,11 @@ describe("resolveConsolidationPrompt — with override", () => {
     const path = join(homedir(), filename);
     writeFileSync(path, "Home dir {{CUTOFF}}\n");
     try {
-      const result = resolveConsolidationPrompt(`~/${filename}`, CUTOFF);
+      const result = resolveConsolidationPrompt(
+        `~/${filename}`,
+        CUTOFF,
+        NO_CORE,
+      );
       expect(result).toBe(`Home dir ${CUTOFF}\n`);
       expect(warnCalls).toHaveLength(0);
     } finally {
@@ -136,7 +197,11 @@ describe("resolveConsolidationPrompt — with override", () => {
     const body = "No placeholder here. Just a plain prompt.\n";
     writeFileSync(join(tmpWorkspace, "no-placeholder.md"), body);
 
-    const result = resolveConsolidationPrompt("no-placeholder.md", CUTOFF);
+    const result = resolveConsolidationPrompt(
+      "no-placeholder.md",
+      CUTOFF,
+      NO_CORE,
+    );
 
     expect(result).toBe(body);
     expect(warnCalls).toHaveLength(0);
@@ -148,7 +213,11 @@ describe("resolveConsolidationPrompt — with override", () => {
       "{{CUTOFF}} ... {{CUTOFF}} ... {{CUTOFF}}",
     );
 
-    const result = resolveConsolidationPrompt("custom-prompt.md", CUTOFF);
+    const result = resolveConsolidationPrompt(
+      "custom-prompt.md",
+      CUTOFF,
+      NO_CORE,
+    );
 
     expect(result).toBe(`${CUTOFF} ... ${CUTOFF} ... ${CUTOFF}`);
     expect(result).not.toContain(CUTOFF_PLACEHOLDER);
@@ -160,6 +229,7 @@ describe("resolveConsolidationPrompt — failure modes", () => {
     const result = resolveConsolidationPrompt(
       "/this/path/does/not/exist.md",
       CUTOFF,
+      NO_CORE,
     );
 
     expect(result).toBe(bundledPrompt());
@@ -173,7 +243,7 @@ describe("resolveConsolidationPrompt — failure modes", () => {
     const path = join(tmpWorkspace, "empty.md");
     writeFileSync(path, "");
 
-    const result = resolveConsolidationPrompt(path, CUTOFF);
+    const result = resolveConsolidationPrompt(path, CUTOFF, NO_CORE);
 
     expect(result).toBe(bundledPrompt());
     expect(warnCalls).toHaveLength(1);
@@ -185,7 +255,7 @@ describe("resolveConsolidationPrompt — failure modes", () => {
     const path = join(tmpWorkspace, "empty.md");
     writeFileSync(path, "   \n\n\t\n");
 
-    const result = resolveConsolidationPrompt(path, CUTOFF);
+    const result = resolveConsolidationPrompt(path, CUTOFF, NO_CORE);
 
     expect(result).toBe(bundledPrompt());
     expect(warnCalls).toHaveLength(1);
@@ -198,7 +268,7 @@ describe("resolveConsolidationPrompt — failure modes", () => {
     // 1 MiB + 1 byte — just over the cap so we don't waste test memory.
     writeFileSync(path, Buffer.alloc(1 * 1024 * 1024 + 1, 0x61));
 
-    const result = resolveConsolidationPrompt(path, CUTOFF);
+    const result = resolveConsolidationPrompt(path, CUTOFF, NO_CORE);
 
     expect(result).toBe(bundledPrompt());
     expect(warnCalls).toHaveLength(1);
@@ -213,7 +283,7 @@ describe("resolveConsolidationPrompt — failure modes", () => {
     const link = join(tmpWorkspace, "link.md");
     symlinkSync(target, link);
 
-    const result = resolveConsolidationPrompt(link, CUTOFF);
+    const result = resolveConsolidationPrompt(link, CUTOFF, NO_CORE);
 
     expect(result).toBe(bundledPrompt());
     expect(warnCalls).toHaveLength(1);
@@ -230,7 +300,7 @@ describe("resolveConsolidationPrompt — failure modes", () => {
       return;
     }
 
-    const result = resolveConsolidationPrompt(fifoPath, CUTOFF);
+    const result = resolveConsolidationPrompt(fifoPath, CUTOFF, NO_CORE);
 
     expect(result).toBe(bundledPrompt());
     expect(warnCalls).toHaveLength(1);

package/src/memory/v2/consolidation-job.ts

@@ -175,10 +175,17 @@ export async function memoryV2ConsolidateJob(
     // the `memory.v2.consolidation_prompt_path` config override but bounds
     // it to a regular file under 1 MiB before substitution so a stray path
     // (or a `/dev/zero`-style pseudo-file) cannot exfiltrate megabytes of
-    // bytes through the wake hint.
+    // bytes through the wake hint. The core-pages curation section rides the
+    // same v3 gate as the maintenance follow-up: the file feeds the v3 core
+    // lane, so on a v2-only install the instruction would curate a file
+    // nothing reads.
+    const memoryV3Active =
+      isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config) ||
+      isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config);
     const prompt = resolveConsolidationPrompt(
       config.memory.v2.consolidation_prompt_path,
       cutoff,
+      { includeCorePagesSection: memoryV3Active },
     );
 
     const runResult = await runBackgroundJob({
@@ -212,10 +219,7 @@ export async function memoryV2ConsolidateJob(
     // is active, so it never fans out on v2-only installs.
     const followUpJobIds: string[] = [];
     const jobTypes: MemoryJobType[] = [...FOLLOW_UP_JOB_TYPES];
-    if (
-      isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config) ||
-      isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config)
-    ) {
+    if (memoryV3Active) {
       jobTypes.push(V3_FOLLOW_UP_JOB_TYPE);
     }
     for (const jobType of jobTypes) {

package/src/memory/v2/prompts/consolidation.ts

@@ -30,6 +30,37 @@ const log = getLogger("memory-v2-consolidate-prompt");
 /** Sentinel substituted with the cutoff timestamp at runtime. */
 export const CUTOFF_PLACEHOLDER = "{{CUTOFF}}";
 
+/**
+ * Sentinel substituted with {@link CORE_PAGES_CONSOLIDATION_SECTION} (or the
+ * empty string) at runtime. The core-pages file only exists for the memory-v3
+ * retrieval lanes, so the section is included only when a v3 flag is enabled
+ * for the assistant — on a v2-only install the instruction would have the
+ * agent curate a file nothing reads, under premises ("kept in reach every
+ * turn", "the hot set") that are false there.
+ *
+ * New flag-gated sections must follow this placeholder pattern and be
+ * registered in consolidation-prompt-flag-gating-guard.test.ts, which blocks
+ * gated content from reaching the default (all-gates-off) rendering.
+ */
+export const CORE_PAGES_PLACEHOLDER = "{{CORE_PAGES_SECTION}}";
+
+/**
+ * The flag-gated `memory/core-pages.md` curation step. Ends with a blank line
+ * so substituting it (or the empty string) ahead of the `---` separator keeps
+ * the surrounding template byte-stable either way.
+ */
+export const CORE_PAGES_CONSOLIDATION_SECTION = `## 10. Review \`memory/core-pages.md\` — the curated core set
+
+\`memory/core-pages.md\` lists the pages retrieval keeps in reach EVERY turn, regardless of topic. It exists for one class of page: associative texture — registers, identity frames, calibration rules — pages with no lexical or semantic match to the message that neither search nor usage frequency can surface on their own. You are the only editor of this file; review it each pass.
+
+- **Format:** one page per list line — \`- [[slug]]\` or \`- slug\`, optionally followed by an inline note: after a wikilink the note is free-form (\`- [[slug]] — why it belongs\`); after a bare slug introduce it with a dash (\`- slug — why it belongs\`). Headings, blank lines, and standalone prose lines are ignored, so annotate freely.
+- **Keep it small** — on the order of a few dozen entries (~30–50). Every entry costs context budget every single turn.
+- **Add** a page only when its content should always be in reach with no topical cue. If a search query would find it, it doesn't belong here.
+- **Remove** entries made redundant by frequent use — recently-used pages stay warm automatically (the hot set), so a page that comes up all the time doesn't need a core slot.
+- **Fix** entries whose page you renamed or deleted this pass (maintenance reports dangling entries, but never edits the file).
+
+`;
+
 /**
  * Upper bound for the override file. Real consolidation prompts are kilobytes;
  * 1 MiB is generous headroom while preventing a `settings.write` principal from
@@ -384,17 +415,7 @@ Scan namespace sizes. If any namespace has crossed ~12-15 articles with visible
 - Rewrite to contain ONLY entries with timestamp ≥ \`${CUTOFF_PLACEHOLDER}\`.
 - Smart removal — never wholesale-clear.
 
-## 10. Review \`memory/core-pages.md\` — the curated core set
-
-\`memory/core-pages.md\` lists the pages retrieval keeps in reach EVERY turn, regardless of topic. It exists for one class of page: associative texture — registers, identity frames, calibration rules — pages with no lexical or semantic match to the message that neither search nor usage frequency can surface on their own. You are the only editor of this file; review it each pass.
-
-- **Format:** one page per list line — \`- [[slug]]\` or \`- slug\`, optionally followed by an inline note: after a wikilink the note is free-form (\`- [[slug]] — why it belongs\`); after a bare slug introduce it with a dash (\`- slug — why it belongs\`). Headings, blank lines, and standalone prose lines are ignored, so annotate freely.
-- **Keep it small** — on the order of a few dozen entries (~30–50). Every entry costs context budget every single turn.
-- **Add** a page only when its content should always be in reach with no topical cue. If a search query would find it, it doesn't belong here.
-- **Remove** entries made redundant by frequent use — recently-used pages stay warm automatically (the hot set), so a page that comes up all the time doesn't need a core slot.
-- **Fix** entries whose page you renamed or deleted this pass (maintenance reports dangling entries, but never edits the file).
-
----
+${CORE_PAGES_PLACEHOLDER}---
 
 # What NOT to do
 
@@ -443,14 +464,31 @@ For each article you touched:
 
 This is the engine that decides who you are tomorrow. Be ORGANIZED. Care, judgment, voice. Your voice. Your wiki.`;
 
+/** Flag-derived options threaded from the consolidation job. */
+export interface ConsolidationPromptOptions {
+  /**
+   * Include the `memory/core-pages.md` curation step. True only when a
+   * memory-v3 flag (shadow or live) is enabled for the assistant — the file
+   * feeds the v3 core lane and is inert on v2-only installs.
+   */
+  includeCorePagesSection: boolean;
+}
+
 /**
- * Resolve `CONSOLIDATION_PROMPT` with `{{CUTOFF}}` substituted. The prompt
- * treats the cutoff as opaque text — callers pass a `Mon D, h:mm AM/PM`
- * timestamp matching the `buffer.md` entry format so the agent compares
+ * Resolve `CONSOLIDATION_PROMPT` with `{{CUTOFF}}` substituted and the
+ * flag-gated core-pages section included or elided. The prompt treats the
+ * cutoff as opaque text — callers pass a `Mon D, h:mm AM/PM` timestamp
+ * matching the `buffer.md` entry format so the agent compares
  * like-with-like.
  */
-export function renderConsolidationPrompt(cutoff: string): string {
-  return CONSOLIDATION_PROMPT.replaceAll(CUTOFF_PLACEHOLDER, cutoff);
+export function renderConsolidationPrompt(
+  cutoff: string,
+  options: ConsolidationPromptOptions,
+): string {
+  return CONSOLIDATION_PROMPT.replaceAll(CUTOFF_PLACEHOLDER, cutoff).replaceAll(
+    CORE_PAGES_PLACEHOLDER,
+    options.includeCorePagesSection ? CORE_PAGES_CONSOLIDATION_SECTION : "",
+  );
 }
 
 /**
@@ -458,6 +496,11 @@ export function renderConsolidationPrompt(cutoff: string): string {
  * referenced by `memory.v2.consolidation_prompt_path`, then substitute
  * `{{CUTOFF}}`. Path-resolution rules are documented on the schema field.
  *
+ * Override files get the same placeholder substitutions as the bundled
+ * template: `{{CUTOFF}}` always, and `{{CORE_PAGES_SECTION}}` per the same
+ * flag gate — so a prompt copied from the bundled source never leaks a raw
+ * placeholder, and a customized prompt can opt into the managed section.
+ *
  * Failure handling is intentionally permissive — missing file, read error, or
  * empty/whitespace-only body all log a warning and fall back to the bundled
  * prompt. Consolidation must never break because of a bad override: the
@@ -466,8 +509,9 @@ export function renderConsolidationPrompt(cutoff: string): string {
 export function resolveConsolidationPrompt(
   overridePath: string | null,
   cutoff: string,
+  options: ConsolidationPromptOptions,
 ): string {
-  if (overridePath === null) return renderConsolidationPrompt(cutoff);
+  if (overridePath === null) return renderConsolidationPrompt(cutoff, options);
 
   const resolvedPath = resolveOverridePath(overridePath);
   let contents: string;
@@ -483,7 +527,7 @@ export function resolveConsolidationPrompt(
         },
         "consolidation prompt override is not a regular file; using bundled prompt",
       );
-      return renderConsolidationPrompt(cutoff);
+      return renderConsolidationPrompt(cutoff, options);
     }
     if (stat.size > MAX_PROMPT_BYTES) {
       log.warn(
@@ -497,7 +541,7 @@ export function resolveConsolidationPrompt(
         },
         "consolidation prompt override exceeds size limit; using bundled prompt",
       );
-      return renderConsolidationPrompt(cutoff);
+      return renderConsolidationPrompt(cutoff, options);
     }
     contents = readFileSync(resolvedPath, "utf-8");
   } catch (err) {
@@ -506,7 +550,7 @@ export function resolveConsolidationPrompt(
       { configuredPath: overridePath, resolvedPath, code, fallback: "bundled" },
       "consolidation prompt override unreadable; using bundled prompt",
     );
-    return renderConsolidationPrompt(cutoff);
+    return renderConsolidationPrompt(cutoff, options);
   }
 
   if (contents.trim().length === 0) {
@@ -519,10 +563,15 @@ export function resolveConsolidationPrompt(
       },
       "consolidation prompt override is empty; using bundled prompt",
     );
-    return renderConsolidationPrompt(cutoff);
+    return renderConsolidationPrompt(cutoff, options);
   }
 
-  return contents.replaceAll(CUTOFF_PLACEHOLDER, cutoff);
+  return contents
+    .replaceAll(CUTOFF_PLACEHOLDER, cutoff)
+    .replaceAll(
+      CORE_PAGES_PLACEHOLDER,
+      options.includeCorePagesSection ? CORE_PAGES_CONSOLIDATION_SECTION : "",
+    );
 }
 
 function resolveOverridePath(overridePath: string): string {