filegrc 0.16.14 → 0.16.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filegrc",
-  "version": "0.16.14",
+  "version": "0.16.16",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {

package/src/agent.js

@@ -102,6 +102,7 @@ export function buildAgentGuide(loaded, type, options = {}) {
             allowedDecisions: collectionReview.configuration.decisions,
             status: collectionReview.status,
             recordCount: collectionReview.recordCount,
+            ...(collectionReview.changesSinceReview ? { changesSinceReview: collectionReview.changesSinceReview } : {}),
             command: `npx filegrc review-collection ${type} --scaffold`
           }
         : null

package/src/collection-changes.js

@@ -0,0 +1,158 @@
+import { readFileSync } from "node:fs";
+import { modelSupports } from "../model/index.js";
+import { authoritativeSourceRevisionValue, collectionRevisionInputs, collectionScopeRevisionFacts, scopedCollectionRecords } from "./collection-scope.js";
+import { collectionRevisionMatches } from "./collection-revision.js";
+import { getFileAtRevision } from "./git.js";
+import { reviewHistoricalWorkspace, reviewHistoryContext } from "./historical-workspace.js";
+import { markdownEntries } from "./resource-markdown.js";
+import { resolveProgram } from "./program.js";
+import { resolveDataPath } from "./paths.js";
+import { canonicalCalculatedRevision } from "./revisions.js";
+
+export function collectionChangesSinceReview(loaded, resourceType, review, programId) {
+  if (!/^[a-f0-9]{40,64}$/i.test(review?.scopeRevision || "") || !loaded.root) return unavailable("The reviewed Git snapshot is unavailable. Compare the current records with the prior review.");
+  const before = reviewHistoricalWorkspace(reviewHistoryContext(loaded.root, loaded), review.scopeRevision);
+  if (!before) return unavailable("The reviewed Git snapshot is unavailable. Compare the current records with the prior review.");
+  const workspaceWide = resourceType === "retention-schedule-item"
+    && modelSupports(loaded.model, "retention-schedule-approval");
+  let priorProgram = null;
+  let currentProgram = null;
+  try {
+    if (!workspaceWide) {
+      priorProgram = resolveProgram(before, programId);
+      currentProgram = resolveProgram(loaded, programId);
+    }
+  } catch {
+    return unavailable("The reviewed Program could not be reconstructed. Compare the current scope with the prior review.");
+  }
+  if (!collectionRevisionMatches(before, resourceType, review.collectionRevision, {
+    programId,
+    historicalCommit: review.scopeRevision,
+    authoritativeSourceId: review.authoritativeComponentId || review.authoritativeSystemId
+  })) {
+    return unavailable("The stored revision does not match the reviewed Git snapshot. Compare the current records with the prior review.");
+  }
+  const priorInputs = new Map(collectionRevisionInputs(before, resourceType, priorProgram)
+    .map((input) => [input.record.id, input]));
+  const currentInputs = new Map(collectionRevisionInputs(loaded, resourceType, currentProgram)
+    .map((input) => [input.record.id, input]));
+  const authoritativeSourceId = review.authoritativeComponentId || review.authoritativeSystemId;
+  for (const [source, inputs] of [[before, priorInputs], [loaded, currentInputs]]) {
+    const record = source.resources.find(({ id }) => id === authoritativeSourceId);
+    if (record) inputs.set(record.id, {
+      record,
+      value: authoritativeSourceRevisionValue(record),
+      includeContent: true
+    });
+  }
+  const priorMembers = new Set(scopedCollectionRecords(before, resourceType, priorProgram).map(({ id }) => id));
+  const currentMembers = new Set(scopedCollectionRecords(loaded, resourceType, currentProgram).map(({ id }) => id));
+  const changes = [];
+  for (const id of new Set([...priorInputs.keys(), ...currentInputs.keys()])) {
+    const prior = priorInputs.get(id);
+    const current = currentInputs.get(id);
+    const record = current?.record || prior?.record;
+    const fields = prior && current ? changedFields(prior.value, current.value, loaded.model, record.type) : [];
+    const contentChanged = prior && current && (prior.includeContent || current.includeContent)
+      ? changedContent(before, loaded, review.scopeRevision, prior.record, current.record)
+      : false;
+    const membershipChanged = priorMembers.has(id) !== currentMembers.has(id);
+    if (!prior || !current || fields.length || contentChanged || membershipChanged) {
+      changes.push({
+        id,
+        type: record.type,
+        title: record.title || id,
+        kind: !prior ? "added" : !current ? "removed" : "changed",
+        fields,
+        ...(contentChanged ? { contentChanged: true } : {}),
+        ...(membershipChanged ? { membershipChanged: true } : {})
+      });
+    }
+  }
+  const scopeFields = changedFields(
+    collectionScopeRevisionFacts(before, resourceType, priorProgram),
+    collectionScopeRevisionFacts(loaded, resourceType, currentProgram),
+    loaded.model,
+    "program"
+  );
+  if (!changes.length && !scopeFields.length) {
+    return unavailable("The stored revision does not match the reviewed Git snapshot. Compare the current records with the prior review.");
+  }
+  changes.sort((left, right) => left.type.localeCompare(right.type) || left.title.localeCompare(right.title) || left.id.localeCompare(right.id));
+  const overview = [
+    ...changes.slice(0, 3).map(describeChange),
+    ...(changes.length > 3 ? [`${changes.length - 3} more changed records`] : []),
+    ...(scopeFields.length ? [`Program scope (${scopeFields.join(", ")})`] : [])
+  ].join("; ");
+  const headlineParts = [
+    ...changes.slice(0, 2).map(describeShortChange),
+    ...(changes.length > 2 ? [`${changes.length - 2} more changed records`] : []),
+    ...(scopeFields.length ? [`Program scope: ${scopeFields.slice(0, 2).join(", ")}${scopeFields.length > 2 ? ", more" : ""}`] : [])
+  ];
+  return {
+    status: "available",
+    summary: `Changed since the last review: ${overview}.`,
+    headline: `${headlineParts.join("; ")}. Open the review for details.`,
+    changes,
+    scopeFields
+  };
+}
+
+function unavailable(summary) {
+  return { status: "unavailable", summary, headline: "Changes could not be reconstructed. Open the review for details.", changes: [], scopeFields: [] };
+}
+
+function describeChange(change) {
+  const name = `${change.title} (${change.type})`;
+  if (change.kind !== "changed") return `${name} ${change.kind === "added" ? "entered review scope" : "left review scope"}`;
+  const details = [...change.fields, ...(change.contentChanged ? ["Markdown"] : []), ...(change.membershipChanged ? ["collection membership"] : [])];
+  return `${name}: ${details.join(", ")}`;
+}
+
+function describeShortChange(change) {
+  const name = change.title.length > 44 ? `${change.title.slice(0, 43)}…` : change.title;
+  if (change.kind !== "changed") return `${name} ${change.kind === "added" ? "entered scope" : "left scope"}`;
+  const details = [...change.fields, ...(change.contentChanged ? ["Markdown"] : []), ...(change.membershipChanged ? ["membership"] : [])];
+  return `${name}: ${details.slice(0, 2).join(", ")}${details.length > 2 ? ", more" : ""}`;
+}
+
+function changedFields(before, after, model, type) {
+  const definitions = { ...model.commonFields, ...model.resources[type]?.fields };
+  return [...new Set([...Object.keys(before || {}), ...Object.keys(after || {})])]
+    .filter((field) => !sameValue(before?.[field], after?.[field]))
+    .map((field) => definitions[field]?.label || field.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/\bIds\b/g, "IDs").replace(/^./, (letter) => letter.toUpperCase()));
+}
+
+function sameValue(left, right) {
+  if (typeof left === "string" && typeof right === "string") {
+    return canonicalCalculatedRevision(left) === canonicalCalculatedRevision(right);
+  }
+  if (Array.isArray(left) && Array.isArray(right)) {
+    if (left.every((value) => typeof value === "string") && right.every((value) => typeof value === "string")) {
+      return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
+    }
+    return left.length === right.length && left.every((value, index) => sameValue(value, right[index]));
+  }
+  if (left && right && typeof left === "object" && typeof right === "object") {
+    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+    return [...keys].every((key) => sameValue(left[key], right[key]));
+  }
+  return left === right;
+}
+
+function changedContent(before, current, commit, priorRecord, currentRecord) {
+  const priorPaths = markdownEntries(before.model, priorRecord).map(({ path }) => path);
+  const currentPaths = markdownEntries(current.model, currentRecord).map(({ path }) => path);
+  for (const path of new Set([...priorPaths, ...currentPaths])) {
+    const priorSource = priorPaths.includes(path)
+      ? before.historicalFiles?.get(`data/${path}`) ?? getFileAtRevision(before.root, commit, `data/${path}`)
+      : null;
+    let currentSource = null;
+    if (currentPaths.includes(path)) {
+      try { currentSource = readFileSync(resolveDataPath(current.root, path), "utf8"); }
+      catch (error) { if (error.code !== "ENOENT") throw error; }
+    }
+    if (priorSource !== currentSource) return true;
+  }
+  return false;
+}

package/src/collection-review.js

@@ -16,8 +16,9 @@ import { currentPartyPeople } from "./parties.js";
 import { retentionScheduleApprovalIssues } from "./retention-schedule-approval.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { resolveDataPath } from "./paths.js";
-import { calculateRevision, calculatedRevisionDiagnostic, revisionsMatch } from "./revisions.js";
+import { calculateRevision, calculatedRevisionDiagnostic, displayRevision, revisionsMatch } from "./revisions.js";
 import { personWasActiveOn } from "./soc2.js";
+import { collectionChangesSinceReview } from "./collection-changes.js";
 
 export { collectionRevision };
 
@@ -123,6 +124,9 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
     && review.collectionRevision
     && (!revisionMatches || !reviewScopeMatches)
   );
+  const changesSinceReview = stale
+    ? collectionChangesSinceReview(loaded, resourceType, review, program.id)
+    : null;
   return {
     resourceType,
     configuration,
@@ -134,6 +138,7 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
       : null,
     reviewEntries,
     collectionRevision: currentRevision,
+    changesSinceReview,
     revisionDiagnostic: calculatedRevisionDiagnostic("collection", review?.collectionRevision, currentRevision),
     status: complete ? "current" : stale ? "stale" : "review-required",
     complete,
@@ -143,7 +148,7 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
     message: complete
       ? `${configuration.title} were reviewed on ${review.reviewedOn}.`
       : approvalIssues.length
-        ? approvalIssues[0].message
+        ? `${approvalIssues[0].message}${changesSinceReview ? ` ${changesSinceReview.summary}` : ""}`
       : incompleteRecordProposals.length
         ? `Complete ${incompleteRecordProposals.length} ${configuration.title.toLowerCase()} ${incompleteRecordProposals.length === 1 ? "record proposal" : "record proposals"} before the collection review.`
       : revisionMatches && review?.status === "active" && !reviewersEligible
@@ -151,7 +156,7 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
           ? "Review the Data Retention Schedule again with a reviewer who does not own its governing document or an included schedule row."
           : "Review the Control collection again with a reviewer who does not own an included Control or its enabled Obligation."
       : stale
-        ? `${configuration.title} changed after the last confirmation. Stored revision: ${review.collectionRevision}. Current revision: ${currentRevision}. Review the current records again.`
+        ? `${configuration.title} changed after the last confirmation. ${changesSinceReview.summary} Stored revision: ${displayRevision(review.collectionRevision)}. Current revision: ${displayRevision(currentRevision)}. Review the current records again.`
         : !records.length && !allowsEmptyCollection
           ? `Add at least one ${loaded.model.resources[resourceType].title.toLowerCase()} before confirming this collection.`
         : `Review ${configuration.title.toLowerCase()} before this page can be ready.`
@@ -190,6 +195,7 @@ export async function scaffoldCollectionReview(input = process.cwd(), options =
     : null;
   return {
     resourceType,
+    ...(assessment.changesSinceReview ? { changesSinceReview: assessment.changesSinceReview } : {}),
     decision: priorDecisionStillValid ? priorReview.decision : (assessment.records.length
       ? "complete"
       : allowedDecisions.includes("zero-population") ? "zero-population" : null),

package/src/collection-scope.js

@@ -167,7 +167,9 @@ function scopedProgramPeople(loaded, program = {}) {
   const systemIds = new Set(program.systemIds || []);
   const controlIds = new Set(program.controlIds || []);
   const policyIds = new Set(loaded.resources
-    .filter(({ type, status, programRole }) => type === "policy" && status !== "retired" && programRole !== "reference")
+    .filter(({ type, status, programRole }) => (
+      type === "policy" && !["superseded", "retired"].includes(status) && programRole !== "reference"
+    ))
     .map(({ id }) => id));
   const components = programComponents(loaded, program);
   const componentIds = new Set(components.map(({ id }) => id));
@@ -177,13 +179,13 @@ function scopedProgramPeople(loaded, program = {}) {
   ]);
   const sources = loaded.resources.filter((record) => (
     ["workspace", "program", "appointment", "team"].includes(record.type)
-    || record.type === "system" && systemIds.has(record.id)
+    || record.type === "system" && systemIds.has(record.id) && record.status !== "retired"
     || record.type === "component" && componentIds.has(record.id)
-    || record.type === "vendor" && vendorIds.has(record.id)
-    || record.type === "control" && controlIds.has(record.id)
+    || record.type === "vendor" && vendorIds.has(record.id) && !["deprecated", "terminated"].includes(record.status)
+    || record.type === "control" && controlIds.has(record.id) && record.status !== "retired"
     || record.type === "policy" && policyIds.has(record.id)
-    || record.type === "document" && record.workflowScope !== "engagement"
-    || record.type === "obligation" && (
+    || record.type === "document" && record.workflowScope !== "engagement" && !["superseded", "retired"].includes(record.status)
+    || record.type === "obligation" && record.status !== "retired" && (
       (record.controlIds || []).some((id) => controlIds.has(id))
       || (record.policyIds || []).some((id) => policyIds.has(id))
     )

package/src/files.js

@@ -12,7 +12,7 @@ import { measureTiming } from "./timing.js";
 import { currentCalendarDate, timestampFromLocalDateTime } from "./time.js";
 import { loadWorkspace } from "./workspace.js";
 import { validateWorkspace } from "./validate.js";
-import { calculateRevision, revisionsMatch } from "./revisions.js";
+import { calculateRevision, displayRevision, revisionsMatch } from "./revisions.js";
 
 export const INTERNAL_WORKFLOW_CAPABILITIES = Object.freeze({
   auditManagementReconciliation: Symbol("audit-management-reconciliation"),
@@ -1165,7 +1165,7 @@ async function prepareContentWrites(loaded, record, content, options = {}) {
 function assertRevision(source, expected, label) {
   const current = contentRevision(source);
   if (expected && !revisionsMatch("content", expected, current)) {
-    throw new Error(`${label} changed after you opened it. Stored revision: ${expected}. Current revision: ${current}. Reload the workspace and apply your change again.`);
+    throw new Error(`${label} changed after you opened it. Stored revision: ${displayRevision(expected)}. Current revision: ${displayRevision(current)}. Reload the workspace and apply your change again.`);
   }
 }
 

package/src/program-readiness.js

@@ -794,7 +794,9 @@ export function collectionReviewReadinessItem(assessment) {
           : `Review ${assessment.configuration.title.toLowerCase()}`,
     proposalAction
       ? `Complete ${firstIncomplete.title} before reviewing ${assessment.configuration.title.toLowerCase()}.`
-      : assessment.message,
+      : assessment.approvalIssues?.length || pendingRetentionRow || needsFirstRecord
+        ? assessment.message
+        : assessment.changesSinceReview?.headline || assessment.message,
     proposalAction
       ? { id: firstIncomplete.resourceId, type: assessment.resourceType }
       : needsFirstRecord ? { type: assessment.resourceType }
@@ -1239,7 +1241,7 @@ function requiredGovernedDocuments(scope, records, byId, model) {
   const selectedControlIds = new Set(scope.controls.map(({ id }) => id));
   const linkedDocumentIds = new Set(requiredPolicies(scope, byId).flatMap((policy) => policy.relatedDocumentIds || []));
   const obligationDocumentIds = new Set(records
-    .filter((record) => record.type === "obligation")
+    .filter((record) => record.type === "obligation" && record.status !== "retired")
     .flatMap((record) => [
       ...(record.scopeResourceIds || []),
       ...(record.templateResourceId ? [record.templateResourceId] : [])

package/src/revisions.js

@@ -42,6 +42,12 @@ export function revisionDigest(kind, value) {
   return null;
 }
 
+export function displayRevision(value) {
+  const text = String(value || "");
+  const match = /^(?:filegrc:[a-z-]+:v\d+:sha256:|scope:)?([a-f0-9]{64})$/.exec(text);
+  return match ? match[1].slice(0, 12) : text;
+}
+
 export function revisionsMatch(kind, stored, current) {
   const storedDigest = revisionDigest(kind, stored);
   const currentDigest = revisionDigest(kind, current);

package/src/state.js

@@ -344,7 +344,10 @@ async function createAppStateUnlocked(input, options) {
 function assessApplicabilityReviewStatuses(loaded, program) {
   const decisions = new Map((program.requirementApplicability || []).map((review) => [review.requirementId, review]));
   return Object.fromEntries(loaded.resources
-    .filter(({ type }) => ["requirement", "control", "commitment", "complementary-control"].includes(type))
+    .filter(({ type, status }) => (
+      ["requirement", "control", "commitment", "complementary-control"].includes(type)
+      && !["retired", "superseded"].includes(status)
+    ))
     .map((record) => {
       const review = record.type === "requirement" && modelSupports(loaded.model, "program-scope")
         ? decisions.get(record.id)
@@ -367,6 +370,7 @@ function serializeCollectionReviewAssessment(assessment) {
     status: assessment.status,
     complete: assessment.complete,
     message: assessment.message,
+    ...(assessment.changesSinceReview ? { changesSinceReview: assessment.changesSinceReview } : {}),
     ...(assessment.recordProposals ? { recordProposals: assessment.recordProposals } : {}),
     ...(assessment.incompleteRecordProposals ? { incompleteRecordProposals: assessment.incompleteRecordProposals } : {}),
     ...(assessment.eligibleReviewerIds ? { eligibleReviewerIds: assessment.eligibleReviewerIds } : {}),

package/src/validate.js

@@ -46,7 +46,7 @@ import {
 } from "./reporting-route-integrity.js";
 import { validateWorkflowHistoryIntegrity } from "./workflow-history-integrity.js";
 import { occurrenceMemberExceptionIsValid } from "./obligation-members.js";
-import { calculateRevision, revisionDigest, revisionsMatch } from "./revisions.js";
+import { calculateRevision, displayRevision, revisionDigest, revisionsMatch } from "./revisions.js";
 
 let fingerprintFileReadObserver = null;
 
@@ -2028,7 +2028,7 @@ function validateRequirementMapping(record, loaded, currentReviewRevisions, path
 
 function revisionMismatchDetails(ids, stored, current) {
   return ids.map((id) => (
-    `${id} (stored: ${stored[id] || "missing"}; current: ${current.get(id) || "missing"})`
+    `${id} (stored: ${displayRevision(stored[id]) || "missing"}; current: ${displayRevision(current.get(id)) || "missing"})`
   )).join(", ");
 }
 

package/src/web.js

@@ -1251,7 +1251,7 @@ function collectionReviewPanel(type, force = false) {
     : "";
   const reviewSummary = current && !reviewBlocker
     ? '<p class="collection-review-result"><strong>' + esc(properCase(assessment.review.decision)) + '</strong><span>Reviewed ' + esc(formatCalendarDate(assessment.review.reviewedOn)) + (reviewerNames.length ? " by " + esc(reviewerNames.join(", ")) : "") + "." + reviewNote + '</span></p>'
-    : '<p class="collection-review-result"><strong>' + (scheduleBlocker ? "Complete schedule first" : proposalBlocker ? "Complete proposals first" : needsFirstRecord ? "Records required" : assessment.status === "stale" ? "Review again" : "Review required") + '</strong><span>' + esc(reviewBlocker || assessment.message) + '</span></p>';
+    : '<p class="collection-review-result"><strong>' + (scheduleBlocker ? "Complete schedule first" : proposalBlocker ? "Complete proposals first" : needsFirstRecord ? "Records required" : assessment.status === "stale" ? "Review again" : "Review required") + '</strong><span>' + esc(reviewBlocker || (assessment.status === "stale" && assessment.changesSinceReview ? "Check what changed since the last review, then confirm the current records." : assessment.message)) + '</span></p>';
   const compactReviewSummary = current && !reviewBlocker
     ? '<p class="collection-review-result"><strong>' + esc(properCase(assessment.review.decision)) + '</strong><span>Reviewed ' + esc(formatCalendarDate(assessment.review.reviewedOn)) + (reviewerNames.length ? " by " + esc(reviewerNames.join(", ")) : "") + ".</span></p>"
     : reviewSummary;
@@ -1270,8 +1270,11 @@ function collectionReviewPanel(type, force = false) {
   const summary = current
     ? '<div class="collection-review-current-row"><div class="collection-review-complete-summary"><span class="kicker">' + (scheduleReview ? "Approved schedule" : "Scope confirmation") + '</span>' + compactReviewSummary + '</div>' + details + action + '</div>'
     : details;
+  const changes = !current && assessment.status === "stale" && !reviewBlocker
+    ? collectionReviewChangesHtml(assessment.changesSinceReview)
+    : "";
   return '<section class="collection-review-panel panel ' + (current ? "current" : "required") + '">' + summary +
-    (current ? "" : '<div class="collection-review-foot">' + reviewSummary + action + '</div>') + '</section>';
+    changes + (current ? "" : '<div class="collection-review-foot">' + reviewSummary + action + '</div>') + '</section>';
 }
 
 function retentionScheduleApprovalBlocker() {
@@ -1452,9 +1455,10 @@ function openCollectionReviewDialog(type) {
   const saveDescription = scheduleReview
     ? 'Approve the governing document and ' + assessment.recordCount + ' current ' + pluralize("schedule row", assessment.recordCount) + ' as one revision. A later document, row, or material scope change requires another approval.'
     : 'Confirm ' + assessment.recordCount + ' current ' + pluralize("record", assessment.recordCount) + '. If the collection or material scope changes, FileGRC will ask for another review.';
+  const changes = collectionReviewChangesHtml(assessment.changesSinceReview);
   const confirmSubmit = '<button type="submit" class="button primary">Confirm and save</button>';
   const submit = scheduleReview ? '<button type="submit" class="button primary">Approve schedule</button>' : confirmSubmit;
-  dialog.innerHTML = '<form><div class="dialog-head"><div><p class="kicker">' + dialogKicker + '</p><h2 id="collection-review-dialog-title">' + esc(dialogTitle) + '</h2></div><button type="button" class="icon-button" aria-label="Close">×</button></div><p>' + esc(configuration.description) + '</p><section class="event-dialog-steps collection-review-checks"><strong>' + checklistLabel + '</strong><ul>' + configuration.reviewPoints.map((point) => '<li>' + esc(point) + '</li>').join("") + '</ul></section>' + reviewerHelp + '<div class="form-grid"><label><span>Conclusion</span><select name="decision" required>' + decisions + '</select></label><label><span>Reviewer</span><select name="reviewerId" required><option value="">Select</option>' + people.map(({ record }) => '<option value="' + esc(record.id) + '" ' + ((assessment.review?.reviewedByIds || []).includes(record.id) ? "selected" : "") + '>' + esc(record.title) + '</option>').join("") + '</select></label><label><span>Reviewed on</span><input name="reviewedOn" type="date" required value="' + esc(currentDate()) + '"></label><label data-authoritative-system><span>Authoritative ' + (v4 ? "Component" : "System") + '</span><select name="authoritativeSourceId"><option value="">Select</option>' + systems.map(({ record }) => '<option value="' + esc(record.id) + '" ' + (preservedAuthoritativeSourceId === record.id ? "selected" : "") + '>' + esc(record.title) + '</option>').join("") + '</select></label><label class="full"><span>Review notes</span><textarea name="rationale" rows="3" required placeholder="Note what you confirmed and any scope decision that needs context.">' + esc(assessment.review?.rationale || "") + '</textarea></label></div><div class="workflow-preview"><strong>What this saves</strong><p>' + esc(saveDescription) + '</p></div><div class="dialog-error" role="alert"></div><div class="dialog-actions"><span class="save-status review-save-status" role="status" aria-live="polite"></span><button type="button" class="button" data-event="cancel">Cancel</button>' + submit + '</div></form>';
+  dialog.innerHTML = '<form><div class="dialog-head"><div><p class="kicker">' + dialogKicker + '</p><h2 id="collection-review-dialog-title">' + esc(dialogTitle) + '</h2></div><button type="button" class="icon-button" aria-label="Close">×</button></div><p>' + esc(configuration.description) + '</p>' + changes + '<section class="event-dialog-steps collection-review-checks"><strong>' + checklistLabel + '</strong><ul>' + configuration.reviewPoints.map((point) => '<li>' + esc(point) + '</li>').join("") + '</ul></section>' + reviewerHelp + '<div class="form-grid"><label><span>Conclusion</span><select name="decision" required>' + decisions + '</select></label><label><span>Reviewer</span><select name="reviewerId" required><option value="">Select</option>' + people.map(({ record }) => '<option value="' + esc(record.id) + '" ' + ((assessment.review?.reviewedByIds || []).includes(record.id) ? "selected" : "") + '>' + esc(record.title) + '</option>').join("") + '</select></label><label><span>Reviewed on</span><input name="reviewedOn" type="date" required value="' + esc(currentDate()) + '"></label><label data-authoritative-system><span>Authoritative ' + (v4 ? "Component" : "System") + '</span><select name="authoritativeSourceId"><option value="">Select</option>' + systems.map(({ record }) => '<option value="' + esc(record.id) + '" ' + (preservedAuthoritativeSourceId === record.id ? "selected" : "") + '>' + esc(record.title) + '</option>').join("") + '</select></label><label class="full"><span>Review notes</span><textarea name="rationale" rows="3" required placeholder="Note what you confirmed and any scope decision that needs context.">' + esc(assessment.review?.rationale || "") + '</textarea></label></div><div class="workflow-preview"><strong>What this saves</strong><p>' + esc(saveDescription) + '</p></div><div class="dialog-error" role="alert"></div><div class="dialog-actions"><span class="save-status review-save-status" role="status" aria-live="polite"></span><button type="button" class="button" data-event="cancel">Cancel</button>' + submit + '</div></form>';
   document.body.append(dialog);
   dialog.showModal();
   const form = dialog.querySelector("form");
@@ -1516,6 +1520,23 @@ function openCollectionReviewDialog(type) {
   });
 }
 
+function collectionReviewChangesHtml(changes) {
+  if (!changes) return "";
+  if (changes.status !== "available") {
+    return '<section class="collection-review-change-list"><strong>What changed since the last review</strong><p>' + esc(changes.summary) + '</p></section>';
+  }
+  const rows = changes.changes.map((change) => {
+    const details = change.kind !== "changed" ? change.kind === "added" ? "entered review scope" : "left review scope" : [
+      ...change.fields,
+      ...(change.contentChanged ? ["Markdown"] : []),
+      ...(change.membershipChanged ? ["collection membership"] : [])
+    ].join(", ");
+    return '<li><strong>' + esc(change.title) + '</strong> <span>(' + esc(change.type) + ')</span>: ' + esc(details) + '</li>';
+  });
+  if (changes.scopeFields?.length) rows.push('<li><strong>Program scope</strong>: ' + esc(changes.scopeFields.join(", ")) + '</li>');
+  return '<section class="collection-review-change-list"><strong>What changed since the last review</strong><p>Check these changes before recording a new conclusion.</p><ul>' + rows.join("") + '</ul></section>';
+}
+
 function workflowItemHref(item) {
   const destinationOptions = {
     retentionScheduleApproval: modelSupports("retention-schedule-approval"),
@@ -1897,11 +1918,13 @@ function derivedStagePageState(stage, destination) {
       : { complete: false, label: "Review scope" };
   }
   if (stage.id === "audit" && destination.type === "document" && destination.href.includes("documentScope=audit")) {
-    if (!resourcesOfType("document").some(({ record }) => auditSpecificDocument(record))) {
+    if (!resourcesOfType("document").some(({ record }) => (
+      auditSpecificDocument(record) && !["retired", "superseded"].includes(record.status)
+    ))) {
       return { complete: false, countsTowardProgress: false, label: "Only if needed" };
     }
   }
-  if (destination.type && resourcesOfType(destination.type).length === 0) {
+  if (destination.type && !resourcesOfType(destination.type).some(({ record }) => !["retired", "superseded"].includes(record.status))) {
     return { complete: false, countsTowardProgress: false, label: "Only if needed" };
   }
   return { complete: true, label: "Ready" };
@@ -2792,6 +2815,7 @@ function openNextAuditCycleDialog(prior) {
 }
 
 function controlApplicabilityPending(record) {
+  if (["retired", "superseded"].includes(record.status)) return false;
   if (state.applicabilityReviewStatuses?.[record.id]) {
     return state.applicabilityReviewStatuses[record.id] !== "current";
   }
@@ -2802,6 +2826,7 @@ function controlApplicabilityPending(record) {
 }
 
 function applicabilityPending(record) {
+  if (["retired", "superseded"].includes(record.status)) return false;
   if (state.applicabilityReviewStatuses?.[record.id]) {
     return state.applicabilityReviewStatuses[record.id] !== "current";
   }
@@ -6580,6 +6605,7 @@ html,body{height:100%;overflow:hidden}.shell{grid-template-columns:248px minmax(
 .stage-page-card-actions{display:flex;align-items:center;gap:10px}.stage-page-card-actions .stage-page-open{white-space:nowrap}.stage-page-open::after{content:"";position:absolute;inset:0;z-index:1;border-radius:10px}.stage-page-open:focus-visible::after{outline:2px solid var(--focus);outline-offset:2px}.stage-page-open>span{position:relative;z-index:2}
 .workflow-findings>a:hover{border-color:var(--accent-light);box-shadow:0 3px 9px rgba(21,40,33,.05)}.workflow-findings>a:focus-visible{outline:2px solid var(--focus);outline-offset:2px}.stage-page-card-head{align-items:flex-start}.stage-page-completion-state{flex:0 0 auto;max-width:150px;padding:5px 8px;border-radius:99px;background:#f7e9cf;color:#855717;font-size:9.6px;font-weight:750;line-height:1.25;text-align:right}.stage-page-completion-state.complete{background:#ddefe5;color:#176143}.obligation-card.workflow-target{outline:2px solid var(--focus);outline-offset:3px}.obligation-card-foot{flex-wrap:wrap}.obligation-card-foot .obligation-links{flex:1 1 120px}
 .collection-review-panel.current details{margin-top:8px}.collection-review-detail-content{margin-top:10px}.collection-review-complete-summary{display:flex;align-items:baseline;gap:10px}.collection-review-complete-summary>.kicker{margin:0;white-space:nowrap}.collection-review-panel.current .collection-review-foot{justify-content:flex-end;margin-top:8px}
+.collection-review-change-list{margin:14px 0;padding:12px 14px;border:1px solid var(--line);border-radius:7px;background:var(--surface-soft)}.collection-review-change-list>strong{font-size:11px}.collection-review-change-list p{margin:7px 0 0;color:var(--muted);font-size:11px;line-height:1.5}.collection-review-change-list ul{max-height:180px;overflow:auto;margin:9px 0 0;padding-left:20px;font-size:11px;line-height:1.55}.collection-review-change-list li+li{margin-top:5px}.collection-review-change-list li span{color:var(--muted)}
 .collection-review-current-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.collection-review-panel.current .collection-review-details{flex:0 0 auto;margin:0;padding:0;border:0;background:transparent}.collection-review-panel.current .collection-review-details>summary{color:var(--accent);white-space:nowrap}.collection-review-panel.current .collection-review-details[open]{flex-basis:100%;order:3;padding:10px 12px;border:1px solid var(--line);border-radius:7px;background:var(--surface-soft)}.collection-review-panel.current .collection-review-details[open]>summary{margin-bottom:10px}.collection-review-panel.current .collection-review-details[open] .collection-review-detail-content{margin-top:0}.collection-review-panel.current .button{margin-left:auto}
 @media(max-width:520px){.collection-review-complete-summary{flex:1 1 180px;min-width:0;flex-wrap:wrap}.collection-review-complete-summary .collection-review-result{min-width:0;flex-wrap:wrap}.collection-review-complete-summary .collection-review-result span{overflow-wrap:anywhere}.collection-review-panel.current .button{margin-left:0}}
 @media(max-width:520px){.stage-page-card-head{align-items:stretch;flex-direction:column;gap:10px}.stage-page-card-actions{justify-content:space-between}}

package/src/workflow.js

@@ -26,6 +26,7 @@ import { assessAuditPreparation } from "./audit-preparation.js";
 import { assessProgramReadiness } from "./program-readiness.js";
 import { resolveProgram } from "./program.js";
 import { resourceReviewRevisions, retentionReviewResourceIds, retentionRuleIsCurrent } from "./retention.js";
+import { displayRevision } from "./revisions.js";
 import { signatoryAppointmentIssue, soc2ReportEvidenceIssue, subsequentEventsReviewIssue } from "./soc2.js";
 import { planReconciliation } from "./reconciliation.js";
 import { documentIsAuditSpecific } from "./program-lifecycle.js";
@@ -393,6 +394,7 @@ function recordFinalizationFindings(loaded, program) {
   const findings = [];
   for (const record of loaded.resources) {
     if (["workspace", "renderer-settings"].includes(record.type)) continue;
+    if (["retired", "superseded"].includes(record.status)) continue;
     const incomplete = recordIncompleteReason(record, loaded, program);
     if (incomplete) {
       findings.push(finalizationFinding(record, incomplete, loaded.model));
@@ -543,8 +545,8 @@ function finalizationFields(record, model, resources, program, root) {
       field: "applicabilityReview",
       requiredness: "required",
       message: record.applicabilityReview?.scopeRevision
-        ? `Review applicability against the current service scope. Stored revision: ${record.applicabilityReview.scopeRevision}. Current revision: ${currentRevision}. Then record the decision, rationale, reviewer, and date.`
-        : `Review applicability against the current service scope. Current revision: ${currentRevision}. Then record the decision, rationale, reviewer, and date.`
+        ? `Review applicability against the current service scope. Stored revision: ${displayRevision(record.applicabilityReview.scopeRevision)}. Current revision: ${displayRevision(currentRevision)}. Then record the decision, rationale, reviewer, and date.`
+        : `Review applicability against the current service scope. Current revision: ${displayRevision(currentRevision)}. Then record the decision, rationale, reviewer, and date.`
     });
   }
   if (record.type === "policy" && model.resources.policy?.fields?.programRole && !record.programRole) {
@@ -815,6 +817,9 @@ async function assessPeriodHealth(loaded, options) {
     .map(({ id }) => id));
   for (const record of loaded.resources) {
     if (record.type === "policy" && ["required", "alternative"].includes(record.programRole)) {
+      const historical = ["retired", "superseded"].includes(record.status);
+      const changedOn = record.statusTransition?.changedOn;
+      if (historical && changedOn && changedOn <= coverage.start) continue;
       if (record.status !== "active" || !record.effectiveOn || record.effectiveOn > coverage.start) {
         findings.push(periodGap(record, "policy", record.effectiveOn, coverage));
       }