feat(triage): how_to lane staleness governance + notifications FAQ (PP-4831)

A how_to answer names UI ("go to Settings → Libraries") and has no fix version to
expire against, so it goes stale silently when the app's navigation moves — exactly
the Palace-icon → Settings reroute we just did. This adds the governance to catch that.

- KBEntry gains `ui_surface` (the screen a how_to depends on) + `reviewed_at` (when
  the answer was last verified). Both nil for known_issue entries.
- All four how_to entries are now anchored + dated; HT-003 switch-library and the
  add-library answers point at `settings-libraries`.
- HowToGovernanceTests adds a UI-surface CHANGE LOG (surface → last-changed date) and
  a staleness lint: any how_to whose `reviewed_at` predates its surface's last-changed
  date fails — the screen moved and nobody re-checked the directions. `settings-libraries`
  is dated 2026-07-20 (today's reroute); the answers were re-reviewed the same day, so
  they pass — had they not been, the lint would have caught it. Teeth proven on the real
  catalog: rolling a review date back to before the change fails with the drift message.
- New FAQ entry HT-2026-004-notifications (hold-ready + due-soon reminders — enable
  notifications; from HelpSpot 18103), with a benchmark case.

Note on FAQ growth: several "common questions" (loan period, borrow limit, hold window)
have LIBRARY-SPECIFIC answers (they vary per library's config), so they're poor canned
FAQs — better routed to the library than answered with a hardcoded number. v1 adds the
universal one (notifications); the rest want product input before authoring.

TriageBotCore suite 248/248 green via `swift test`.

**Scope:** TriageBotCore local package only — KBEntry anchor/date fields, catalog
metadata + one new how_to entry, governance tests. No classifier/reducer/escalation
change (that's PP-4832). No app/DRM/sign-in code.

**Not done:** branched off the unmerged PP-4825 branch; re-stack after #1305 + PP-4825
land. Applying the UI anchor to known_issue text (which can also drift) is deferred.
Holding PR until tomorrow per request — pushed for backup only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: t

.forgeos/intent/pp-4831-howto-governance.md

@@ -0,0 +1,47 @@
+---
+name: pp-4831-howto-governance
+created: 2026-07-20
+author: claude-opus-4-8
+---
+
+**ADR refs:** none — ForgeOS governance is off in this environment.
+
+**Ticket:** PP-4831 (offshoot of PP-4825). Branched off
+`feat/pp-4825-triage-corpus-generalhelp` (independent of PP-4832). Re-stack after
+#1305 + PP-4825 land.
+
+**Why:** a how_to answer references UI ("go to Settings → Libraries") and has no fix
+version to expire against, so it goes stale silently when the UI moves — exactly what
+happened with the Palace-icon → Settings library-switch reroute. This adds the
+governance the how_to lane needs to stay trustworthy, plus one new FAQ entry.
+
+## Claims
+
+- adds field `uiSurface` to `KBEntry` (the UI screen a how_to answer depends on)
+- adds field `reviewedAt` to `KBEntry` (the date the answer was last verified)
+- adds `ui_surface` + `reviewed_at` to the three existing how_to entries in
+  `catalog.json` (HT-001 renewals, HT-002 return-early, HT-003 switch-library)
+- adds a how_to entry `HT-2026-004-notifications` to `catalog.json` (hold-ready +
+  due-soon reminders — enable notifications; from HelpSpot 18103)
+- adds a benchmark shouldMatch case for HT-004 to `ResponseQualityTests`
+- adds `HowToGovernanceTests` — a UI-surface change-log registry + a staleness lint
+  that fails any how_to whose `reviewed_at` predates its surface's last-changed date,
+  requires every how_to to carry a known `ui_surface` + `reviewed_at`, and proves the
+  lint has teeth on a synthetic drifted entry
+
+## Anti-claims
+
+- does NOT change the classifier, scorer, normalization, version gate, or reducer
+- does NOT change escalation behavior (that is PP-4832)
+- does NOT alter the existing how_to keywords or answer text (only adds anchor/date
+  metadata) — except adding the new HT-004 entry
+- does NOT apply the ui_surface anchor to known_issue entries (how_to only for v1;
+  KI text-drift is a separate concern)
+- does NOT touch sign-in, borrow, download, DRM, or audiobook production code
+
+## Files in scope
+
+- Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Models/KBEntry.swift
+- Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Resources/catalog.json
+- Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/ResponseQualityTests.swift
+- Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/HowToGovernanceTests.swift

Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Models/KBEntry.swift

@@ -95,6 +95,14 @@ public struct KBEntry: Codable, Equatable, Identifiable, Sendable {
     public let helpspotTag: String?
     public let trustLevel: KBTrustLevel
     public let visibility: KBVisibility
+    /// The UI screen a `how_to` answer depends on (e.g. "settings-libraries").
+    /// A how_to answer references the app's navigation and has no fix version to
+    /// expire against, so it goes stale silently when the UI moves. This anchor
+    /// lets a governance lint flag entries whose screen changed after they were
+    /// last reviewed. Nil for known_issue entries (PP-4831).
+    public let uiSurface: String?
+    /// The date (YYYY-MM-DD) a how_to answer was last verified against the UI.
+    public let reviewedAt: String?
 
     /// `kind` with its default applied — `.knownIssue` when the JSON omitted it.
     public var resolvedKind: KBKind { kind ?? .knownIssue }
@@ -118,6 +126,8 @@ public struct KBEntry: Codable, Equatable, Identifiable, Sendable {
         case helpspotTag = "helpspot_tag"
         case trustLevel = "trust_level"
         case visibility = "visibility"
+        case uiSurface = "ui_surface"
+        case reviewedAt = "reviewed_at"
     }
 
     public init(
@@ -138,7 +148,9 @@ public struct KBEntry: Codable, Equatable, Identifiable, Sendable {
         escalateAnyway: Bool = false,
         helpspotTag: String? = nil,
         trustLevel: KBTrustLevel = .authoritative,
-        visibility: KBVisibility = .userFacing
+        visibility: KBVisibility = .userFacing,
+        uiSurface: String? = nil,
+        reviewedAt: String? = nil
     ) {
         self.id = id
         self.category = category
@@ -158,6 +170,8 @@ public struct KBEntry: Codable, Equatable, Identifiable, Sendable {
         self.helpspotTag = helpspotTag
         self.trustLevel = trustLevel
         self.visibility = visibility
+        self.uiSurface = uiSurface
+        self.reviewedAt = reviewedAt
     }
 }
 

Palace/Packages/PalaceTriageBot/Sources/TriageBotCore/Resources/catalog.json

@@ -754,7 +754,9 @@
       "escalate_anyway": false,
       "helpspot_tag": "how-to-renewals",
       "trust_level": "authoritative",
-      "visibility": "user_facing"
+      "visibility": "user_facing",
+      "ui_surface": "catalog",
+      "reviewed_at": "2026-07-20"
     },
     {
       "id": "HT-2026-002-return-early",
@@ -783,7 +785,9 @@
       "escalate_anyway": false,
       "helpspot_tag": "how-to-return-early",
       "trust_level": "authoritative",
-      "visibility": "user_facing"
+      "visibility": "user_facing",
+      "ui_surface": "my-books",
+      "reviewed_at": "2026-07-20"
     },
     {
       "id": "HT-2026-003-switch-library",
@@ -810,7 +814,38 @@
       "escalate_anyway": false,
       "helpspot_tag": "how-to-switch-library",
       "trust_level": "authoritative",
-      "visibility": "user_facing"
+      "visibility": "user_facing",
+      "ui_surface": "settings-libraries",
+      "reviewed_at": "2026-07-20"
+    },
+    {
+      "id": "HT-2026-004-notifications",
+      "category": "other",
+      "kind": "how_to",
+      "symptom_keywords": [
+        "get notified",
+        "notify me when",
+        "hold ready notification",
+        "remind me when",
+        "due date reminder",
+        "reminder when",
+        "turn on notifications",
+        "enable notifications",
+        "when my book is due"
+      ],
+      "user_facing_workaround": "Turn on notifications and Palace will alert you when a hold you placed is ready to borrow, and again when a loan is about to expire. You can enable them when you first install the app, or later in your phone's Settings under Palace.",
+      "internal_reference": {
+        "helpspot": [
+          18103
+        ]
+      },
+      "confidence_threshold": 0.1,
+      "escalate_anyway": false,
+      "helpspot_tag": "how-to-notifications",
+      "trust_level": "authoritative",
+      "visibility": "user_facing",
+      "ui_surface": "notifications-settings",
+      "reviewed_at": "2026-07-20"
     }
   ]
 }

Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/HowToGovernanceTests.swift

@@ -0,0 +1,96 @@
+import XCTest
+@testable import TriageBotCore
+
+/// PP-4831 — governance for the general-help (how_to) lane. A how_to answer names
+/// UI ("go to Settings → Libraries") and has no fix version to expire against, so
+/// it goes stale silently when the app's navigation moves. This pins that every
+/// how_to entry is anchored to a UI surface + carries a review date, and flags any
+/// answer that was last reviewed BEFORE its surface changed — i.e. the screen moved
+/// and nobody re-checked the directions.
+final class HowToGovernanceTests: XCTestCase {
+
+    /// The UI-surface change log. Bump a surface's date whenever its screen/nav
+    /// changes; any how_to reviewed before that date then fails the staleness check
+    /// until a human re-verifies the answer and bumps its `reviewed_at`.
+    ///
+    /// `settings-libraries` last changed 2026-07-20 — the Palace-icon library
+    /// switcher moved into Settings (PP-4825). The switch/add-library answers were
+    /// re-reviewed the same day, so they pass; had they not been, this would fail.
+    static let uiSurfaceChangeLog: [String: String] = [
+        "settings-libraries": "2026-07-20",
+        "my-books": "2026-05-01",
+        "catalog": "2026-05-01",
+        "notifications-settings": "2026-07-20",
+    ]
+
+    private func loadEntries() throws -> [KBEntry] {
+        try BundledCatalogSource.loadCatalogSync().entries
+    }
+
+    /// Entries whose answer was last reviewed before their anchored surface changed.
+    /// ISO dates compare correctly as strings. Shared by the catalog test and the
+    /// teeth test so both exercise the same logic.
+    static func staleHowToEntries(_ entries: [KBEntry], changeLog: [String: String]) -> [String] {
+        var stale: [String] = []
+        for entry in entries where entry.resolvedKind == .howTo {
+            guard let surface = entry.uiSurface,
+                  let reviewed = entry.reviewedAt,
+                  let changed = changeLog[surface] else { continue }
+            if reviewed < changed {
+                stale.append("\(entry.id): reviewed \(reviewed) < surface '\(surface)' changed \(changed)")
+            }
+        }
+        return stale
+    }
+
+    // MARK: - Structure: every how_to is anchored + dated + known
+
+    func testEveryHowTo_isAnchoredAndDated() throws {
+        for entry in try loadEntries() where entry.resolvedKind == .howTo {
+            XCTAssertNotNil(entry.uiSurface, "\(entry.id): how_to must declare a ui_surface it depends on")
+            XCTAssertNotNil(entry.reviewedAt, "\(entry.id): how_to must carry a reviewed_at date")
+        }
+    }
+
+    func testEveryHowToSurface_isInTheChangeLog() throws {
+        for entry in try loadEntries() where entry.resolvedKind == .howTo {
+            guard let surface = entry.uiSurface else { continue }
+            XCTAssertNotNil(Self.uiSurfaceChangeLog[surface],
+                            "\(entry.id): ui_surface '\(surface)' is not a known UI surface. Add it to the change log (and remove a surface that no longer exists).")
+        }
+    }
+
+    // MARK: - Drift: no how_to reviewed before its surface changed
+
+    func testNoHowTo_wasReviewedBeforeItsSurfaceChanged() throws {
+        let stale = Self.staleHowToEntries(try loadEntries(), changeLog: Self.uiSurfaceChangeLog)
+        XCTAssertTrue(stale.isEmpty,
+                      "how_to answers whose screen changed after they were last reviewed — re-verify the directions and bump reviewed_at:\n  \(stale.joined(separator: "\n  "))")
+    }
+
+    // MARK: - The lint has teeth
+
+    func testStalenessLint_catchesADriftedEntry() {
+        // A how_to reviewed in January, anchored to a surface that changed in July,
+        // MUST be flagged — proof the check would fire when the UI moves under an
+        // un-re-reviewed answer.
+        let drifted = KBEntry(
+            id: "HT-STALE", category: .library, kind: .howTo,
+            symptomKeywords: ["switch library"],
+            userFacingWorkaround: "Tap the (now-removed) top-left logo to switch libraries.",
+            confidenceThreshold: 0.1, uiSurface: "settings-libraries", reviewedAt: "2026-01-01"
+        )
+        let stale = Self.staleHowToEntries([drifted], changeLog: Self.uiSurfaceChangeLog)
+        XCTAssertEqual(stale.count, 1, "a Jan-reviewed answer on a July-changed surface must be flagged")
+    }
+
+    func testFreshlyReviewedEntry_isNotFlagged() {
+        let fresh = KBEntry(
+            id: "HT-FRESH", category: .library, kind: .howTo,
+            symptomKeywords: ["switch library"],
+            userFacingWorkaround: "Go to Settings → Libraries and tap the one you want.",
+            confidenceThreshold: 0.1, uiSurface: "settings-libraries", reviewedAt: "2026-07-20"
+        )
+        XCTAssertTrue(Self.staleHowToEntries([fresh], changeLog: Self.uiSurfaceChangeLog).isEmpty)
+    }
+}

Palace/Packages/PalaceTriageBot/Tests/TriageBotCoreTests/ResponseQualityTests.swift

@@ -413,6 +413,12 @@ final class ResponseQualityTests: XCTestCase {
              expect: .shouldMatch(entryId: "HT-2026-003-switch-library"),
              source: "common patron question — multiple libraries in one app"),
 
+        // === HT-2026-004 notifications / reminders (how_to) ===
+        Case(userText: "how do I get notified when my hold is ready",
+             category: .other, context: nil,
+             expect: .shouldMatch(entryId: "HT-2026-004-notifications"),
+             source: "HelpSpot 18103 — hold-ready + due-soon reminders; enable notifications"),
+
         // how_to negative — no FAQ answer exists; must still escalate, not
         // grab a loosely-related how_to.
         Case(userText: "how do I delete my account permanently",