chore(ledger): reconcile the clinical sign-off closure and two new findings

docs/outstanding-issues-inbox/7dc2d09a-b05c-4d10-b198-263af3c0f45e.json

@@ -0,0 +1,11 @@
+{
+  "version": 2,
+  "id": "7dc2d09a-b05c-4d10-b198-263af3c0f45e",
+  "createdOn": "2026-08-22",
+  "action": "update",
+  "payload": {
+    "id": "#RSD9EJ",
+    "source": "PR #2298 push attempts 2026-08-22/23 (squash-merged as f3d1a3cce2c943ad3083425ed9c7c46dbef23087; the feature branch and its commits 90b5de61f/7703188ef/55f3a47fa are NOT reachable from any ref -- view them on the PR page, not via git); scripts/guard-push.mjs; scripts/check-ledger-write-discipline.mjs; commit 9a382a050 (#2294) is the reconcile whose applied/ records triggered the false positive and IS on main. REPRODUCTION without those commits: branch from main, let a reconcile PR land on main, merge origin/main into the branch, then push -- guard-push refuses with 'applied/<uuid>.json was introduced without moving the identical pending request from the base' while 'node scripts/check-ledger-write-discipline.mjs --base origin/main --head HEAD' passes on the same tree. The divergence between those two results is the bug.",
+    "baseRowFingerprint": "b687cb212853e6b4c4df866ea79d625556cad416a0c3e406a2044f82691a4d4b"
+  }
+}

scripts/check-docs-links.mjs

@@ -20,11 +20,17 @@
  * Blocking for maintained docs: runs in verify:cheap and CI. Historical
  * directories and dated point-in-time records stay excluded unless --all is
  * requested, so preserved history cannot block unrelated PRs.
+ *
+ * Outstanding-issues inbox citations are special: an immutable request is
+ * queued at `docs/outstanding-issues-inbox/<uuid>.json` and, after reconcile,
+ * lives at `docs/outstanding-issues-inbox/applied/<uuid>.json`. Ledger rows
+ * (and the request's own source/detail) keep citing the pending path because
+ * the JSON is immutable. Treat the applied sibling as the same file.
  */
 
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { applyRequestBatch, validateRequest } from "./ledger-inbox.mjs";
 
@@ -66,10 +72,28 @@ const VERBATIM_DIRS = new Set(["codex-cloud-review"]);
 const APP_ROUTE_GROUPS = ["(search-app)"];
 const OUTSTANDING_ISSUES = "docs/outstanding-issues.md";
 const OUTSTANDING_ISSUES_INBOX = "docs/outstanding-issues-inbox";
+const INBOX_REQUEST_NAME = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$/i;
+
+/**
+ * Pending inbox UUID paths keep being cited after reconcile moves the file
+ * into `applied/`. Return that applied sibling, or null when the path is not
+ * a pending inbox request citation.
+ */
+export function appliedInboxFallbackPath(repoRelative) {
+  const cleaned = repoRelative.replace(/\/$/, "");
+  const prefix = `${OUTSTANDING_ISSUES_INBOX}/`;
+  const appliedPrefix = `${OUTSTANDING_ISSUES_INBOX}/applied/`;
+  if (!cleaned.startsWith(prefix) || cleaned.startsWith(appliedPrefix)) return null;
+  const name = cleaned.slice(prefix.length);
+  if (name.includes("/") || !INBOX_REQUEST_NAME.test(name)) return null;
+  return `${appliedPrefix}${name}`;
+}
 
 function repoPathExists(repoRelative) {
   const cleaned = repoRelative.replace(/\/$/, "");
   if (existsSync(path.join(repoRoot, cleaned))) return true;
+  const applied = appliedInboxFallbackPath(cleaned);
+  if (applied && existsSync(path.join(repoRoot, applied))) return true;
 
   if (!cleaned.startsWith("src/app/") || cleaned.includes("src/app/(")) return false;
   const appRelative = cleaned.slice("src/app/".length);
@@ -176,68 +200,73 @@ function isExternalLink(value) {
   return /^([a-z][a-z0-9+.-]*:|\/\/)/i.test(value) || value.startsWith("#");
 }
 
-let missing = 0;
-let checked = 0;
-
-for (const target of defaultTargets()) {
-  const absoluteTarget = path.join(repoRoot, target);
-  if (!existsSync(absoluteTarget)) continue;
-  const markdown = markdownForTarget(target, absoluteTarget);
-  const targetDir = path.posix.dirname(target);
-  const failures = [];
-
-  const check = (repoRelative, label) => {
-    if (ALLOWLIST.has(repoRelative)) return;
-    checked += 1;
-    if (!repoPathExists(repoRelative)) failures.push(label);
-  };
-
-  // Inline code spans: repo-root-relative repo paths.
-  for (const rawCandidate of codeSpanCandidates(markdown)) {
-    const value = stripSuffixes(rawCandidate);
-    const base = ROOT_PREFIXES.some((prefix) => value.startsWith(prefix)) ? globBaseDir(value) : null;
-    if (base !== null) {
-      if (ALLOWLIST.has(value)) continue;
+function main() {
+  let missing = 0;
+  let checked = 0;
+
+  for (const target of defaultTargets()) {
+    const absoluteTarget = path.join(repoRoot, target);
+    if (!existsSync(absoluteTarget)) continue;
+    const markdown = markdownForTarget(target, absoluteTarget);
+    const targetDir = path.posix.dirname(target);
+    const failures = [];
+
+    const check = (repoRelative, label) => {
+      if (ALLOWLIST.has(repoRelative)) return;
       checked += 1;
-      if (!existsSync(path.join(repoRoot, base))) failures.push(`${value} (glob base '${base}' missing)`);
-      continue;
+      if (!repoPathExists(repoRelative)) failures.push(label);
+    };
+
+    // Inline code spans: repo-root-relative repo paths.
+    for (const rawCandidate of codeSpanCandidates(markdown)) {
+      const value = stripSuffixes(rawCandidate);
+      const base = ROOT_PREFIXES.some((prefix) => value.startsWith(prefix)) ? globBaseDir(value) : null;
+      if (base !== null) {
+        if (ALLOWLIST.has(value)) continue;
+        checked += 1;
+        if (!existsSync(path.join(repoRoot, base))) failures.push(`${value} (glob base '${base}' missing)`);
+        continue;
+      }
+      if (!looksLikeRootPath(value)) continue;
+      check(value, value);
     }
-    if (!looksLikeRootPath(value)) continue;
-    check(value, value);
-  }
 
-  // Markdown link targets: repo docs use both repo-root-relative targets
-  // (`src/lib/env.ts`) and file-relative targets (`codebase-index.md`,
-  // `../AGENTS.md`). Accept whichever resolves, confined to the repository.
-  for (const rawCandidate of linkCandidates(markdown)) {
-    if (isExternalLink(rawCandidate)) continue;
-    const value = stripSuffixes(rawCandidate);
-    if (value === "" || value.includes("*") || /[<>{}$\\]/.test(value) || /\s/.test(value)) continue;
-    const relative = path.posix.normalize(path.posix.join(targetDir === "." ? "" : targetDir, value));
-    if (relative.startsWith("..")) {
+    // Markdown link targets: repo docs use both repo-root-relative targets
+    // (`src/lib/env.ts`) and file-relative targets (`codebase-index.md`,
+    // `../AGENTS.md`). Accept whichever resolves, confined to the repository.
+    for (const rawCandidate of linkCandidates(markdown)) {
+      if (isExternalLink(rawCandidate)) continue;
+      const value = stripSuffixes(rawCandidate);
+      if (value === "" || value.includes("*") || /[<>{}$\\]/.test(value) || /\s/.test(value)) continue;
+      const relative = path.posix.normalize(path.posix.join(targetDir === "." ? "" : targetDir, value));
+      if (relative.startsWith("..")) {
+        checked += 1;
+        failures.push(`${rawCandidate} (escapes repository root)`);
+        continue;
+      }
+      const rootStyle = path.posix.normalize(value);
+      const candidates = rootStyle === relative || rootStyle.startsWith("..") ? [relative] : [rootStyle, relative];
+      if (candidates.some((candidate) => ALLOWLIST.has(candidate))) continue;
       checked += 1;
-      failures.push(`${rawCandidate} (escapes repository root)`);
-      continue;
+      const found = candidates.some((candidate) => repoPathExists(candidate));
+      if (!found)
+        failures.push(rawCandidate === relative ? relative : `${rawCandidate} (tried ${candidates.join(", ")})`);
+    }
+
+    if (failures.length > 0) {
+      missing += failures.length;
+      console.error(`\n${target}:`);
+      for (const failure of failures) console.error(`  MISSING ${failure}`);
     }
-    const rootStyle = path.posix.normalize(value);
-    const candidates = rootStyle === relative || rootStyle.startsWith("..") ? [relative] : [rootStyle, relative];
-    if (candidates.some((candidate) => ALLOWLIST.has(candidate))) continue;
-    checked += 1;
-    const found = candidates.some((candidate) => repoPathExists(candidate));
-    if (!found)
-      failures.push(rawCandidate === relative ? relative : `${rawCandidate} (tried ${candidates.join(", ")})`);
   }
 
-  if (failures.length > 0) {
-    missing += failures.length;
-    console.error(`\n${target}:`);
-    for (const failure of failures) console.error(`  MISSING ${failure}`);
+  if (missing > 0) {
+    console.error(`\ndocs link check FAILED: ${missing} missing path(s) across ${checked} checked references.`);
+    process.exit(1);
   }
-}
 
-if (missing > 0) {
-  console.error(`\ndocs link check FAILED: ${missing} missing path(s) across ${checked} checked references.`);
-  process.exit(1);
+  console.log(`docs link check passed: ${checked} repo path references resolve.`);
 }
 
-console.log(`docs link check passed: ${checked} repo path references resolve.`);
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();

scripts/ci-change-scope.mjs

@@ -270,6 +270,15 @@ const perfExclusionPatterns = [
   "src/instrumentation.ts",
   "src/sentry.server.config.ts",
   "src/sentry.edge.config.ts",
+  // Developer-hub payload only. `src/lib/developer-area/ledger-snapshot.ts`
+  // imports this JSON, and the only route importers are under
+  // `src/app/mockups/development/` (already excluded; 404 in production). A
+  // ledger reconcile that closes the last P1 must not pay a 7-minute
+  // Lighthouse budget run, and must not fail merge on TBT noise from
+  // `/documents/search`. Measured on PR #2302: this file alone flipped
+  // perf_changed and the job failed mobile TBT +32.7% against a baseline
+  // the same change cannot move.
+  "data/outstanding-issues-snapshot.json",
 ];
 
 function isPerfChangedPath(filePath) {
@@ -983,6 +992,12 @@ function selfTest() {
     ["public/therapy-compass-data/therapies-home.json", "data/medications-snapshot.json"],
     { perf_changed: true },
   );
+  // Mockup-only ledger snapshot: same `data/` root as medications, but it
+  // cannot reach a budgeted route. Closing the last P1 on PR #2302 otherwise
+  // forced Lighthouse onto a docs/ledger reconcile.
+  assertScope("perf-off-for-outstanding-issues-snapshot", ["data/outstanding-issues-snapshot.json"], {
+    perf_changed: false,
+  });
   assertScope("perf-on-for-build-config", ["next.config.ts", "postcss.config.mjs", "tsconfig.json"], {
     perf_changed: true,
   });

tests/check-docs-links.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { appliedInboxFallbackPath } from "../scripts/check-docs-links.mjs";
+
+describe("appliedInboxFallbackPath", () => {
+  it("maps a pending inbox UUID citation to the applied sibling", () => {
+    expect(appliedInboxFallbackPath("docs/outstanding-issues-inbox/edebb730-91d9-42f5-bd93-ca2abb9678bc.json")).toBe(
+      "docs/outstanding-issues-inbox/applied/edebb730-91d9-42f5-bd93-ca2abb9678bc.json",
+    );
+  });
+
+  it("does not wrap an already-applied path or a nested inbox file", () => {
+    expect(
+      appliedInboxFallbackPath("docs/outstanding-issues-inbox/applied/edebb730-91d9-42f5-bd93-ca2abb9678bc.json"),
+    ).toBeNull();
+    expect(appliedInboxFallbackPath("docs/outstanding-issues-inbox/README.md")).toBeNull();
+    expect(appliedInboxFallbackPath("docs/outstanding-issues.md")).toBeNull();
+    expect(appliedInboxFallbackPath("docs/outstanding-issues-inbox/not-a-uuid.json")).toBeNull();
+  });
+});

tests/developer-hub-page.dom.test.tsx

@@ -34,8 +34,8 @@ vi.mock("@/components/account-data-provider", () => ({
  * snapshot — so the band is exercised against the shape the route actually
  * loads rather than a hand-built fixture that could drift from it. `null` means
  * "do not override", which is also how the assertions below read the true
- * count. The committed snapshot has `p1 === 2`, so without this the singular
- * and zero branches are never reached at all.
+ * count. The committed snapshot can have `p1 === 0` (no open P1s), so the
+ * override is what reaches the singular and non-zero branches.
  */
 const p1 = vi.hoisted(() => ({ value: null as number | null }));
 
@@ -109,12 +109,17 @@ describe("developer hub page — synthetic-data warning", () => {
 describe("developer hub page — needs-you-now band", () => {
   it("reports the snapshot's own P1 count", () => {
     // No override, so this is the real committed snapshot: the band must agree
-    // with the data the route actually loads, not merely with itself.
+    // with the data the route actually loads, not merely with itself. When the
+    // snapshot has no P1s the page must omit the band rather than render a
+    // settled-looking "0 blocking items" line — that is the same contract as
+    // the explicit zero-override case below.
     const { counts } = loadLedgerSnapshot();
-    expect(counts.p1).toBeGreaterThan(0);
-
     render(<DeveloperHubPage />);
-    expect(screen.getByTestId("developer-hub-needs-you-now")).toHaveTextContent(String(counts.p1));
+    if (counts.p1 > 0) {
+      expect(screen.getByTestId("developer-hub-needs-you-now")).toHaveTextContent(String(counts.p1));
+    } else {
+      expect(screen.queryByTestId("developer-hub-needs-you-now")).toBeNull();
+    }
   });
 
   it("carries no text beyond the computed count", () => {
@@ -144,9 +149,9 @@ describe("developer hub page — needs-you-now band", () => {
   });
 
   it("renders nothing rather than a reassuring all-clear when there are no blockers", () => {
-    // The committed snapshot has p1 = 2, so this branch is otherwise never
-    // exercised. A band reading "0 blocking items" would be a settled-looking
-    // statement about work the page cannot see.
+    // A band reading "0 blocking items" would be a settled-looking statement
+    // about work the page cannot see. The override keeps this branch explicit
+    // even on days the committed snapshot already has no P1s.
     p1.value = 0;
     render(<DeveloperHubPage />);