fix(memory-wiki): honor durable: true frontmatter in stale pages report

chenweicong736 · claude · chenweicong736 · commit 6d640a655605 · 2026-06-18T16:23:49.000+08:00
The Stale Pages report previously flagged every non-report page whose updatedAt was older than 30 days, including intentionally durable references such as concept and synthesis pages. Bridge-mode vaults typically have many such pages, drowning out real staleness signal. This change adds a strict boolean `durable` frontmatter marker. Pages with `durable: true` are excluded from the stale-pages filter at compile time. The marker is strict (asBoolean only accepts real booleans, not string literals), is opt-in, and does not touch updatedAt, so other freshness signals remain accurate. Lint and agent-digest callers are unaffected; the change is scoped to the dashboard report filter. Fixes #93485 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
diff --git a/docs/plugins/memory-wiki.md b/docs/plugins/memory-wiki.md
@@ -311,6 +311,24 @@ These reports track things like:
 - evidence class coverage
 - non-public privacy tiers that need review before use
 
+### Opting pages out of the Stale Pages report
+
+Concept, synthesis, and other intentionally durable reference pages should
+not be flagged by the 30-day / 90-day freshness thresholds in
+`reports/stale-pages.md`. Mark any such page with a strict boolean frontmatter
+field:
+
+```yaml
+---
+durable: true
+---
+```
+
+`memory-wiki` excludes pages where `durable: true` is set from the Stale Pages
+report. Use this for concepts, syntheses, and other reference material whose
+value comes from durability rather than recency. The marker does not change
+`updatedAt`, so other freshness signals remain accurate.
+
 ## Search and retrieval
 
 `memory-wiki` supports two search backends:
diff --git a/extensions/memory-wiki/src/compile.test.ts b/extensions/memory-wiki/src/compile.test.ts
@@ -559,6 +559,67 @@ describe("compileMemoryWikiVault", () => {
     );
   });
 
+  it("excludes durable pages from the Stale Pages report", async () => {
+    const { rootDir, config } = await createVault({
+      rootDir: nextCaseRoot(),
+      initialize: true,
+    });
+
+    const oldTimestamp = "2024-01-01T00:00:00.000Z";
+
+    await fs.writeFile(
+      path.join(rootDir, "concepts", "alpha-concept.md"),
+      renderWikiMarkdown({
+        frontmatter: {
+          pageType: "concept",
+          id: "concept.alpha",
+          title: "Alpha Concept",
+          updatedAt: oldTimestamp,
+          durable: true,
+        },
+        body: "# Alpha Concept\n",
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      path.join(rootDir, "syntheses", "alpha-synthesis.md"),
+      renderWikiMarkdown({
+        frontmatter: {
+          pageType: "synthesis",
+          id: "synthesis.alpha",
+          title: "Alpha Synthesis",
+          updatedAt: oldTimestamp,
+          durable: true,
+        },
+        body: "# Alpha Synthesis\n",
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      path.join(rootDir, "concepts", "beta-concept.md"),
+      renderWikiMarkdown({
+        frontmatter: {
+          pageType: "concept",
+          id: "concept.beta",
+          title: "Beta Concept",
+          updatedAt: oldTimestamp,
+        },
+        body: "# Beta Concept\n",
+      }),
+      "utf8",
+    );
+
+    await compileMemoryWikiVault(config);
+
+    const stalePages = await fs.readFile(
+      path.join(rootDir, "reports", "stale-pages.md"),
+      "utf8",
+    );
+    expect(stalePages).not.toContain("Alpha Concept");
+    expect(stalePages).not.toContain("Alpha Synthesis");
+    expect(stalePages).toContain("Beta Concept");
+  });
+
   it("skips dashboard report pages when createDashboards is disabled", async () => {
     const { rootDir, config } = await createVault({
       rootDir: nextCaseRoot(),
diff --git a/extensions/memory-wiki/src/compile.ts b/extensions/memory-wiki/src/compile.ts
@@ -214,6 +214,7 @@ const DASHBOARD_PAGES: DashboardPageDefinition[] = [
         .filter(
           (page) =>
             page.kind !== "report" &&
+            page.durable !== true &&
             !(
               isUnmanagedRawSourceSummary(page) &&
               !managedImportedSourcePagePaths.has(page.relativePath)
diff --git a/extensions/memory-wiki/src/markdown.test.ts b/extensions/memory-wiki/src/markdown.test.ts
@@ -325,6 +325,74 @@ describe("toWikiPageSummary", () => {
     expect(crlfStructuredSource?.pageType).toBe("source");
   });
 
+  it("parses the durable opt-in flag from frontmatter strictly", () => {
+    const trueDurable = toWikiPageSummary({
+      absolutePath: "/tmp/wiki/concepts/concept-durable-true.md",
+      relativePath: "concepts/concept-durable-true.md",
+      raw: renderWikiMarkdown({
+        frontmatter: {
+          pageType: "concept",
+          title: "Concept Durable True",
+          updatedAt: "2024-01-01T00:00:00.000Z",
+          durable: true,
+        },
+        body: "# Concept Durable True\n\ndurable reference",
+      }),
+    });
+    expect(trueDurable?.durable).toBe(true);
+
+    const falseDurable = toWikiPageSummary({
+      absolutePath: "/tmp/wiki/concepts/concept-durable-false.md",
+      relativePath: "concepts/concept-durable-false.md",
+      raw: renderWikiMarkdown({
+        frontmatter: {
+          pageType: "concept",
+          title: "Concept Durable False",
+          updatedAt: "2024-01-01T00:00:00.000Z",
+          durable: false,
+        },
+        body: "# Concept Durable False\n\ndurable opt-out",
+      }),
+    });
+    expect(falseDurable?.durable).toBe(false);
+
+    const stringDurable = toWikiPageSummary({
+      absolutePath: "/tmp/wiki/concepts/concept-durable-string.md",
+      relativePath: "concepts/concept-durable-string.md",
+      raw: renderWikiMarkdown({
+        frontmatter: {
+          pageType: "concept",
+          title: "Concept Durable String",
+          updatedAt: "2024-01-01T00:00:00.000Z",
+          durable: "true",
+        },
+        body: "# Concept Durable String\n\ndurable opt-in via string is not honored",
+      }),
+    });
+    expect(stringDurable?.durable).toBeUndefined();
+
+    const missingDurable = toWikiPageSummary({
+      absolutePath: "/tmp/wiki/concepts/concept-durable-missing.md",
+      relativePath: "concepts/concept-durable-missing.md",
+      raw: renderWikiMarkdown({
+        frontmatter: {
+          pageType: "concept",
+          title: "Concept Durable Missing",
+          updatedAt: "2024-01-01T00:00:00.000Z",
+        },
+        body: "# Concept Durable Missing\n\ndurable opt-in missing",
+      }),
+    });
+    expect(missingDurable?.durable).toBeUndefined();
+
+    const noFrontmatterDurable = toWikiPageSummary({
+      absolutePath: "/tmp/wiki/concepts/concept-durable-no-frontmatter.md",
+      relativePath: "concepts/concept-durable-no-frontmatter.md",
+      raw: "# Concept Durable No Frontmatter\n\nno frontmatter block",
+    });
+    expect(noFrontmatterDurable?.durable).toBeUndefined();
+  });
+
   it("normalizes agent-facing people wiki metadata", () => {
     const raw = renderWikiMarkdown({
       frontmatter: {
diff --git a/extensions/memory-wiki/src/markdown.ts b/extensions/memory-wiki/src/markdown.ts
@@ -2,6 +2,7 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
 import {
+  asBoolean,
   asFiniteNumber,
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
@@ -107,6 +108,7 @@ export type WikiPageSummary = {
   unsafeLocalRelativePath?: string;
   lastRefreshedAt?: string;
   updatedAt?: string;
+  durable?: boolean;
 };
 
 const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
@@ -626,5 +628,6 @@ export function toWikiPageSummary(params: {
     unsafeLocalRelativePath: normalizeOptionalString(parsed.frontmatter.unsafeLocalRelativePath),
     lastRefreshedAt: normalizeOptionalString(parsed.frontmatter.lastRefreshedAt),
     updatedAt: normalizeOptionalString(parsed.frontmatter.updatedAt),
+    durable: asBoolean(parsed.frontmatter.durable),
   };
 }
