Add outstanding-issues row-staleness fingerprint checks

docs/branch-review-records/09f7a6223d2cc9cf801d28f42c84347fb6e8fe8167098620126ddf8a61a1994e.record.md

@@ -0,0 +1 @@
+| 2026-08-17 | 2018 | a4338471f29c12c4f98b5abf4910aaf6f461d992 | merge-conflict resolution + review fixes for PR #2009 (docs/filter-contract.md, scripts/check-outstanding-issues.mjs, scripts/ledger-inbox.mjs, src/components/clinical-dashboard/account-setup-dialog.tsx, tests/ui-smoke.spec.ts, tests/ui-tools.spec.ts) | reviewed and fixed: resolved 6-file merge conflict against main, fixed 2 CodeRabbit findings (fingerprint case-sensitivity, URL regex boundary), left 2 findings unaddressed (fingerprint-mandatory migration risk, design-token nitpick) | check-outstanding-issues self-test, ledger-inbox self-test, check:outstanding-issues, check-ledger-write-discipline, focused vitest (outstanding-issues-writer, repo-hygiene, ledger-inbox-cancellation, favourites-auth-gate), prettier --check, typecheck, eslint |

scripts/check-outstanding-issues.mjs

@@ -31,6 +31,7 @@
 
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 
 import { canonicalLegacyIssueId, issueIdCitations, parseIssueIdCell } from "./issue-id.mjs";
 
@@ -41,6 +42,7 @@ const ARCHIVE_HEADING = "## Resolved / archive";
 const QUEUE_HEADING = "## Recommended execution queue";
 const MARKER = /<!--\s*issues:next-id=(\d+)\s*-->/;
 const PRETTIER_IGNORE = "<!-- prettier-ignore -->";
+const ISSUE_ROW_FINGERPRINT = /^[0-9a-f]{64}$/i;
 /**
  * A table's separator row, e.g. `| ---- | --- |`, which declares its width.
  * The inner pipes must be in the class: without them this only ever matched a
@@ -248,6 +250,26 @@ export function parseIssues(markdown) {
  };
 }
 
+export function issueRowFingerprint(markdown, issueId) {
+ const match = String(issueId)
+ .trim()
+ .match(/^#(\d+)$/);
+ if (!match) return null;
+ const number = Number(match[1]);
+ if (!Number.isFinite(number)) return null;
+
+ const row = parseIssues(markdown).rows.find(
+ (entry) => entry.number === number && entry.table === "open" && entry.valid && entry.raw,
+ );
+ if (!row) return null;
+ const normalized = `| ${cells(row.raw).join(" | ")} |`;
+ return createHash("sha256").update(normalized).digest("hex");
+}
+
+export function isValidIssueRowFingerprint(value) {
+ return ISSUE_ROW_FINGERPRINT.test(String(value ?? ""));
+}
+
 export function checkIssues(markdown, { prettierIgnored = false } = {}) {
  const problems = [];
  const { openStart, archiveStart, markerCount, rows, orphans, bodyCount, queueCitations } = parseIssues(markdown);

scripts/ledger-inbox.mjs

@@ -13,7 +13,12 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { addIssue, resolveIssue, updateIssue } from "./outstanding-issues.mjs";
-import { ISSUES_PATH, checkIssues } from "./check-outstanding-issues.mjs";
+import {
+ ISSUES_PATH,
+ checkIssues,
+ issueRowFingerprint,
+ isValidIssueRowFingerprint,
+} from "./check-outstanding-issues.mjs";
 import { isIssueDisplayId, isIssueUlid, issueUlid, issueUlidFromRequest } from "./issue-id.mjs";
 
 const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -39,6 +44,10 @@ function requestPath(id) {
  return path.posix.join(INBOX_DIR, `${id}.json`);
 }
 
+function readOutstandingIssues() {
+ return readFileSync(path.join(ROOT, ISSUES_PATH), "utf8");
+}
+
 export function validateRequest(request) {
  const problems = [];
  if (!request || typeof request !== "object") return ["request must be an object"];
@@ -60,6 +69,11 @@ export function validateRequest(request) {
  if (request.action === "done") {
  if (!isIssueDisplayId(request.payload?.id)) problems.push("done requires a canonical issue display id");
  if (!request.payload?.outcome) problems.push("done requires outcome");
+ if (
+ request.payload?.baseRowFingerprint !== undefined &&
+ !isValidIssueRowFingerprint(request.payload.baseRowFingerprint)
+ )
+ problems.push("done requires a valid baseRowFingerprint");
  }
  if (request.action === "update") {
  if (!isIssueDisplayId(request.payload?.id)) problems.push("update requires a canonical issue display id");
@@ -69,6 +83,11 @@ export function validateRequest(request) {
  if (!["pri", "summary", "detail", "source"].some((field) => request.payload?.[field] !== undefined)) {
  problems.push("update requires pri, summary, detail, or source");
  }
+ if (
+ request.payload?.baseRowFingerprint !== undefined &&
+ !isValidIssueRowFingerprint(request.payload.baseRowFingerprint)
+ )
+ problems.push("update requires a valid baseRowFingerprint");
  if (request.payload?.pri !== undefined && !["P1", "P2", "P3"].includes(String(request.payload.pri))) {
  problems.push("update pri must be P1, P2, or P3");
  }
@@ -89,6 +108,18 @@ export function applyRequest(markdown, request) {
  throw new Error("cancel requests must be applied through batch reconciliation");
  }
  const options = { date: request.createdOn };
+ if ((request.action === "done" || request.action === "update") && request.payload?.baseRowFingerprint) {
+ const id = request.payload.id;
+ const fingerprint = issueRowFingerprint(markdown, id);
+ if (!fingerprint) {
+ throw new Error(`${id} is no longer open; reread and reissue this request from the latest ledger`);
+ }
+ if (fingerprint !== String(request.payload.baseRowFingerprint).toLowerCase()) {
+ throw new Error(
+ `${id} is stale: the ledger row changed after this request was queued; reread and reissue from the latest ledger`,
+ );
+ }
+ }
  if (request.action === "add") {
  const durableId = request.payload.issueUlid ?? issueUlidFromRequest(request.createdOn, request.id);
  return addIssue(markdown, request.payload, { ...options, issueUlid: durableId });
@@ -403,6 +434,13 @@ function createRequest(action, argv) {
  detail: argValue(argv, "detail"),
  source: argValue(argv, "source"),
  };
+ if (["done", "update"].includes(action) && typeof payload.id === "string") {
+ const currentFingerprint = issueRowFingerprint(readOutstandingIssues(), payload.id);
+ if (currentFingerprint === null) {
+ throw new Error(`ledger request rejected: ${payload.id} is not in Open items`);
+ }
+ payload.baseRowFingerprint = currentFingerprint;
+ }
  const request = { version: 2, id: randomUUID(), createdOn: date(), action, payload };
  const problems = validateRequest(request);
  if (problems.length > 0) throw new Error(problems.join("; "));
@@ -557,14 +595,14 @@ function selfTest() {
  id: "22222222-2222-4222-8222-222222222222",
  createdOn: "2026-08-13",
  action: "done",
- payload: { id: "#001", outcome: "done" },
+ payload: { id: "#001", outcome: "done", baseRowFingerprint: issueRowFingerprint(base, "#001") },
  };
  const update = {
  version: 1,
  id: "33333333-3333-4333-8333-333333333333",
  createdOn: "2026-08-13",
  action: "update",
- payload: { id: "#001", summary: "updated" },
+ payload: { id: "#001", summary: "updated", baseRowFingerprint: issueRowFingerprint(base, "#001") },
  };
  const cancel = {
  version: 1,
@@ -581,7 +619,7 @@ function selfTest() {
  id: "55555555-5555-4555-8555-555555555555",
  createdOn: "2026-08-13",
  action: "update",
- payload: { id: "#001", pri: "P3" },
+ payload: { id: "#001", pri: "P3", baseRowFingerprint: issueRowFingerprint(base, "#001") },
  };
  if (validateRequest(reprioritise).length > 0) {
  throw new Error("self-test failed: a pri-only update request must validate");
@@ -617,6 +655,22 @@ function selfTest() {
  if (validateRequest({ ...add, payload: {} }).length === 0)
  throw new Error("self-test failed: invalid request accepted");
 
+ const staleBase = base.replace("one", "stale");
+ let staleRejected = false;
+ try {
+ applyRequest(staleBase, done);
+ } catch (error) {
+ staleRejected = /stale/.test(String(error));
+ }
+ if (!staleRejected) throw new Error("self-test failed: stale done request was not rejected");
+ let staleUpdateRejected = false;
+ try {
+ applyRequest(staleBase, update);
+ } catch (error) {
+ staleUpdateRejected = /stale/.test(String(error));
+ }
+ if (!staleUpdateRejected) throw new Error("self-test failed: stale update request was not rejected");
+
  let conflictRejected = false;
  try {
  applyRequestBatch(base, [done, update]);

tests/repo-hygiene.test.ts

@@ -36,7 +36,7 @@ import {
  sanitizeCell,
 } from "../scripts/branch-review-ledger.mjs";
 import { validateLedger } from "../scripts/check-branch-review-ledger.mjs";
-import { mergeAttributeProblem } from "../scripts/check-outstanding-issues.mjs";
+import { issueRowFingerprint, mergeAttributeProblem } from "../scripts/check-outstanding-issues.mjs";
 import { applyRequest, validateRequest } from "../scripts/ledger-inbox.mjs";
 
 describe("check-env-parity name parsing", () => {
@@ -683,4 +683,57 @@ describe("outstanding-issues inbox", () => {
  expect(applied).toContain("| #ABCDEF <!-- issue-ulid:0000000000ABCDEF0000000000 --> | P2 | issue | queued |");
  expect(applied).toContain("<!-- issues:next-id=2 -->");
  });
+
+ it("rejects stale done/update requests when the row hash changed after queueing", () => {
+ const ledger = [
+ "<!-- issues:next-id=2 -->",
+ "",
+ "## Recommended execution queue",
+ "",
+ "<!-- prettier-ignore -->",
+ "",
+ "| Order | ID(s) |",
+ "| --- | --- |",
+ "| 1 | `#001` |",
+ "",
+ "## Open items",
+ "",
+ "<!-- prettier-ignore -->",
+ "",
+ "| ID | Pri | Type | Summary | Detail / next action | Source | Added |",
+ "| --- | --- | --- | --- | --- | --- | --- |",
+ "| #001 | P2 | issue | original summary | original detail | source | 2026-01-01 |",
+ "",
+ "## Resolved / archive",
+ "",
+ "<!-- prettier-ignore -->",
+ "",
+ "| ID | Type | Summary | Outcome | Resolved |",
+ "| ---- | ---- | ---- | ---- | ---- |",
+ "| #000 | issue | old | done | 2026-01-01 |",
+ "",
+ ].join("\n");
+ const baseFingerprint = issueRowFingerprint(ledger, "#001");
+ expect(baseFingerprint).not.toBeNull();
+
+ const done = {
+ version: 1,
+ id: "77777777-7777-4777-8777-777777777777",
+ createdOn: "2026-08-13",
+ action: "done",
+ payload: { id: "#001", outcome: "done", baseRowFingerprint: baseFingerprint },
+ };
+ const update = {
+ version: 1,
+ id: "88888888-8888-4888-8888-888888888888",
+ createdOn: "2026-08-13",
+ action: "update",
+ payload: { id: "#001", summary: "new summary", baseRowFingerprint: baseFingerprint },
+ };
+
+ const stale = ledger.replace("original summary", "mutated summary");
+ expect(() => applyRequest(ledger, done)).not.toThrow();
+ expect(() => applyRequest(stale, done)).toThrow(/stale|no longer open/);
+ expect(() => applyRequest(stale, update)).toThrow(/stale|no longer open/);
+ });
 });

tests/ui-tools.spec.ts

@@ -1454,7 +1454,7 @@ test.describe("Clinical KB tools directory and legacy launcher", () => {
  await expect(page).toHaveURL(/group=urgent/);
  await expect(page.getByRole("button", { name: "Remove Crisis & urgent filter" })).toBeVisible();
  await filterPanel.getByTestId("service-filter-panel-clear").click();
- await expect(page).toHaveURL(/q=13YARN/);
+ await expect(page).toHaveURL(/[?&]q=13YARN(?:&|#|$)/);
  await expect(page).not.toHaveURL(/group=/);
  await expect(page.getByTestId("service-search-result-13yarn")).toBeVisible();
  await filterPanel.getByRole("button", { name: "Close", exact: true }).click();