filegrc 0.9.2 → 0.11.0

package/package.json

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

package/src/applicability-scope.js

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+
+const excludedResourceFields = new Set([
+  "applicabilityReview",
+  "applicability",
+  "status",
+  "statusTransition",
+  "effectiveOn",
+  "procedureEffectiveOn",
+  "procedureRevision",
+  "implementationReviewedByIds",
+  "implementationReviewedOn"
+]);
+
+const unorderedStringArrayFields = new Set([
+  "audience",
+  "roles",
+  "servicesProvided",
+  "exclusions",
+  "evidenceSourceKinds",
+  "tags"
+]);
+
+export function applicabilityScopeRevision(record, program, resources, model) {
+  const selectedSystemIds = new Set(program?.systemIds || []);
+  const selectedFrameworkIds = new Set(program?.frameworkIds || []);
+  const selectedControlIds = new Set(program?.controlIds || []);
+  const selectedComponents = resources.filter(({ type, status, systemUses }) => (
+    type === "component"
+    && status !== "retired"
+    && (systemUses || []).some(({ systemId }) => selectedSystemIds.has(systemId))
+  ));
+  const selectedVendorIds = new Set(selectedComponents.map(({ vendorId }) => vendorId).filter(Boolean));
+  const selectedPolicyIds = new Set(resources
+    .filter(({ type, id }) => type === "control" && selectedControlIds.has(id))
+    .flatMap(({ policyIds }) => policyIds || []));
+  for (const policyId of record.policyIds || []) selectedPolicyIds.add(policyId);
+  const facts = {
+    modelVersion: model.modelVersion,
+    program: {
+      ...pick(program || {}, [
+        "id",
+        "assuranceGoal",
+        "systemIds",
+        "frameworkIds",
+        "requirementIds",
+        "controlIds",
+        "riskMethodology"
+      ], model),
+      ...(record.type === "requirement" ? {} : {
+        requirementApplicability: (program?.requirementApplicability || [])
+          .map((review) => pick(review, ["requirementId", "decision"], model, "program-applicability"))
+          .sort((left, right) => left.requirementId.localeCompare(right.requirementId))
+      })
+    },
+    resource: canonicalObject(model, record.type, Object.fromEntries(Object.entries(record)
+      .filter(([field]) => !excludedResourceFields.has(field)))),
+    systems: resources
+      .filter(({ type, id }) => type === "system" && selectedSystemIds.has(id))
+      .sort(compareRecordIds)
+      .map((system) => pick(system, [
+        "id",
+        "purpose",
+        "servicesProvided",
+        "boundary",
+        "exclusions",
+        "criticality",
+        "informationTypeIds",
+        "classificationId",
+        "internetExposed"
+      ], model)),
+    frameworks: resources
+      .filter(({ type, id }) => type === "framework" && selectedFrameworkIds.has(id))
+      .sort(compareRecordIds)
+      .map((framework) => pick(framework, [
+        "id",
+        "status",
+        "title",
+        "version",
+        "publisher",
+        "description",
+        "sourceReference",
+        "effectiveOn"
+      ], model)),
+    components: selectedComponents
+      .sort(compareRecordIds)
+      .map((component) => pick(component, [
+        "id",
+        "status",
+        "componentKind",
+        "description",
+        "criticality",
+        "environment",
+        "vendorId",
+        "systemUses",
+        "informationUses",
+        "internetExposed",
+        "classificationId",
+        "continuityObjectives"
+      ], model)),
+    vendors: resources
+      .filter(({ type, id }) => type === "vendor" && selectedVendorIds.has(id))
+      .sort(compareRecordIds)
+      .map((vendor) => pick(vendor, [
+        "id",
+        "status",
+        "category",
+        "criticality",
+        "description",
+        "standardAgreement",
+        "agreementDocumentId",
+        "startDate",
+        "endDate",
+        "informationTypeIds",
+        "classificationId"
+      ], model)),
+    policies: resources
+      .filter(({ type, id }) => type === "policy" && selectedPolicyIds.has(id))
+      .sort(compareRecordIds)
+      .map((policy) => pick(policy, [
+        "id",
+        "status",
+        "policyKind",
+        "version",
+        "programRole",
+        "effectiveOn",
+        "requirementIds",
+        "audience",
+        "acknowledgementRequired",
+        "relatedDocumentIds",
+        "approvedContentRevisions"
+      ], model)),
+    requirements: resources
+      .filter(({ type, frameworkId }) => type === "requirement" && selectedFrameworkIds.has(frameworkId))
+      .sort(compareRecordIds)
+      .map((requirement) => pick(requirement, ["id", "frameworkId", "reference", "description", "parentRequirementId"], model)),
+    commitments: resources
+      .filter(({ type, status, systemIds }) => (
+        type === "commitment"
+        && !["retired", "superseded"].includes(status)
+        && (systemIds || []).some((id) => selectedSystemIds.has(id))
+      ))
+      .sort(compareRecordIds)
+      .map((commitment) => pick(commitment, [
+        "id",
+        "commitmentKind",
+        "statement",
+        "systemIds",
+        "requirementIds",
+        "controlIds",
+        "customerFacing"
+      ], model))
+  };
+  return `scope:${createHash("sha256").update(stableJson(facts)).digest("hex")}`;
+}
+
+function compareRecordIds(left, right) {
+  return left.id.localeCompare(right.id);
+}
+
+export function applicabilityReviewIsCurrent(review, record, program, resources, model) {
+  if (
+    review?.scopeRevision
+    && !review.scopeRevision.startsWith("scope:")
+    && Number(model?.modelVersion || 0) < 7
+  ) return true;
+  return Boolean(
+    review?.scopeRevision
+    && review.scopeRevision === applicabilityScopeRevision(record, program, resources, model)
+  );
+}
+
+function pick(record, fields, model, objectType = null) {
+  return canonicalObject(model, objectType || record.type, Object.fromEntries(fields
+    .filter((field) => record?.[field] !== undefined)
+    .map((field) => [field, record[field]])));
+}
+
+function canonicalObject(model, type, value) {
+  const fields = model.resources?.[type]
+    ? { ...model.commonFields, ...model.resources[type].fields }
+    : model.objectTypes?.[type]?.properties || {};
+  return Object.fromEntries(Object.keys(value).sort().map((name) => [
+    name,
+    canonicalFieldValue(model, value[name], fields[name], name)
+  ]));
+}
+
+function canonicalFieldValue(model, value, field, name) {
+  if (Array.isArray(value)) {
+    const items = value.map((item) => field?.itemObjectType && item && typeof item === "object"
+      ? canonicalObject(model, field.itemObjectType, item)
+      : item);
+    if (field?.relation || field?.items === "id" || field?.itemObjectType || unorderedStringArrayFields.has(name)) {
+      items.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    }
+    return items;
+  }
+  if (value && typeof value === "object") {
+    return field?.objectType ? canonicalObject(model, field.objectType, value) : value;
+  }
+  return value;
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/audit-preparation.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { modelSupports } from "../model/index.js";
+import { applicabilityReviewIsCurrent } from "./applicability-scope.js";
 import { openPlaceholderCount, substantiveMarkdown } from "./content-readiness.js";
 import {
   coverageContains,
@@ -13,6 +14,7 @@ import {
 import { createResource, createResources, deleteResource, updateResource } from "./files.js";
 import { getChangedDataPathsSinceRevision, getFileAtRevision, hasGitRevision } from "./git.js";
 import { createResourceId } from "./id.js";
+import { planObligations } from "./obligations.js";
 import { currentPartyPeople, partiesIndependent } from "./parties.js";
 import { resolveDataPath } from "./paths.js";
 import { assessProgramReadiness } from "./program-readiness.js";
@@ -68,27 +70,31 @@ export async function assessAuditPreparation(input, options = {}) {
       : audits.find((record) => !["complete", "closed", "canceled"].includes(record.status)) || audits[0];
   if (options.auditId && !audit) throw new Error(`Audit "${options.auditId}" was not found.`);
 
+  const calendarAsOf = options.asOf || currentCalendarDate(loaded.workspace?.timezone || "UTC");
+  const formalPeriodEnd = audit?.auditKind === "soc-2-type-2" ? coverageEnd(audit.coverage) : null;
+  const readinessAsOf = formalPeriodEnd && formalPeriodEnd < calendarAsOf ? formalPeriodEnd : calendarAsOf;
   const programReadiness = options.programReadiness || await assessProgramReadiness(loaded, {
-    asOf: options.asOf,
+    asOf: readinessAsOf,
     generatedAt: options.generatedAt,
     programId: audit?.programId
   });
   const documentActivations = audit && modelSupports(loaded.model, "governed-document-activation")
-    ? await auditDocumentActivationAssessments(loaded, audit, byId, programReadiness.asOf)
+    ? await auditDocumentActivationAssessments(loaded, audit, byId, calendarAsOf)
     : [];
   const stages = [
-    programFoundationStage(programReadiness, loaded.workspace),
+    programFoundationStage(programReadiness, loaded.workspace, audit),
     engagementStage(audit, byId, programReadiness),
     scopeStage(loaded, audit, records, byId, programReadiness)
   ];
   const fieldworkSections = audit
     ? [
-        await documentsStage(loaded, audit, byId, programReadiness.asOf),
+        await documentsStage(loaded, audit, byId, calendarAsOf),
         evidenceStage(audit, records, byId, loaded.model),
-        populationsStage(audit, records, byId, loaded.model)
+        populationsStage(audit, records, byId, loaded.model),
+        occurrenceContinuityStage(audit, records, loaded.model, programReadiness.asOf)
       ]
     : [];
-  stages.push(fieldworkStage(audit, fieldworkSections));
+  stages.push(fieldworkStage(audit, fieldworkSections, programReadiness));
   stages.push(auditorStage(audit, byId, loaded.model.modelVersion));
 
   for (const stage of stages) {
@@ -191,7 +197,9 @@ export async function prepareAuditWorkspace(input, options = {}) {
     .filter(Boolean);
   const v4 = modelSupports(loaded.model, "program-scope");
   const sourceSystems = loaded.resources.filter((record) => record.type === (v4 ? "component" : "system"));
-  const populations = (audit.auditKind === "soc-2-type-2" ? model.populationTemplates || [] : [])
+  const populations = (audit.auditKind === "soc-2-type-2"
+    ? applicablePopulationTemplates(audit, loaded.resources, model.populationTemplates || [])
+    : [])
     .filter((template) => !existingKinds.has(template.kind))
     .map((template) => {
       const id = createResourceId(
@@ -348,7 +356,15 @@ function scopeStage(loaded, audit, records, byId, programReadiness) {
     .filter((record) => record.type === "requirement" && (audit.frameworkIds || []).includes(record.frameworkId))
     .map((record) => record.id);
   const program = audit.programId ? byId.get(audit.programId) : null;
-  const v4Decisions = new Map((program?.requirementApplicability || []).map((decision) => [decision.requirementId, decision]));
+  const requirementById = new Map(records
+    .filter(({ type }) => type === "requirement")
+    .map((record) => [record.id, record]));
+  const v4Decisions = new Map((program?.requirementApplicability || [])
+    .filter((decision) => (
+      requirementById.has(decision.requirementId)
+      && applicabilityReviewIsCurrent(decision, requirementById.get(decision.requirementId), program, records, loaded.model)
+    ))
+    .map((decision) => [decision.requirementId, decision]));
   const unresolvedRequirements = frameworkRequirementIds
     .map((id) => byId.get(id))
     .filter((requirement) => {
@@ -727,16 +743,21 @@ function canonicalScopeValue(value) {
   return value;
 }
 
-function programFoundationStage(programReadiness, workspace) {
-  const ready = programReadiness.evidenceReady;
+function programFoundationStage(programReadiness, workspace, audit) {
+  const needsOperatingPeriod = audit?.auditKind === "soc-2-type-2";
+  const ready = needsOperatingPeriod ? programReadiness.operating : programReadiness.evidenceReady;
   return stage("program", "Program Readiness", "The management program can be prepared and operated without an audit record or CPA firm.", [
     item(
       "evidence-ready",
       ready ? "complete" : "action",
       "Reach the Evidence Ready gate",
       ready
-        ? `${programReadiness.target.label} is evidence-ready. ${programReadiness.operating ? "Evidence collection is running." : "Management can begin the candidate period."}`
-        : `${programReadiness.counts.action} program-readiness actions remain across scope, policies, controls, and evidence preparation.`,
+        ? needsOperatingPeriod
+          ? `${programReadiness.target.label} is operating for the selected engagement.`
+          : `${programReadiness.target.label} is evidence-ready.`
+        : needsOperatingPeriod && programReadiness.evidenceReady
+          ? "Start the candidate period and finish the current operating-readiness work before treating a Type 2 engagement as management-ready."
+          : `${programReadiness.counts.action} program-readiness actions remain across scope, policies, controls, and evidence preparation.`,
       workspace || { type: "workspace" }
     )
   ]);
@@ -858,14 +879,23 @@ function engagementStage(audit, byId, programReadiness) {
   return stage("engagement", "Engage the Auditor", "Record the independent CPA firm and the current management owner who authorizes and coordinates the engagement.", items);
 }
 
-function fieldworkStage(audit, sections) {
+function fieldworkStage(audit, sections, programReadiness) {
   if (!audit) {
     return stage("fieldwork", "Prepare Fieldwork", "Build engagement-specific documents, exact-period evidence, and Type 2 populations after the firm and period are recorded.", [
       item("fieldwork-later", "later", "Prepare engagement-specific fieldwork", "This work starts after the CPA engagement and formal period exist.", { type: "audit" })
     ]);
   }
+  const formalPeriodReady = Boolean(coverageStart(audit.coverage) && coverageEnd(audit.coverage));
+  const programReady = audit.auditKind === "soc-2-type-2"
+    ? programReadiness.operating
+    : programReadiness.evidenceReady;
+  const available = formalPeriodReady && programReady;
   const items = sections.flatMap((section) => section.items.map((current) => ({
     ...current,
+    ...(available || ["complete", "info", "external"].includes(current.status) ? {} : {
+      status: "later",
+      message: `${current.message} Finish ${formalPeriodReady ? "Program Readiness" : "the formal period and Program Readiness"} before starting this fieldwork item.`
+    }),
     id: `${section.id}-${current.id}`,
     section: section.title
   })));
@@ -877,6 +907,89 @@ function fieldworkStage(audit, sections) {
   );
 }
 
+function occurrenceContinuityStage(audit, records, model, asOf) {
+  if (audit.auditKind !== "soc-2-type-2") {
+    return stage(
+      "occurrences",
+      "Operating Occurrences",
+      "Occurrence continuity applies to Type 2 operating-effectiveness periods.",
+      [item("type-2-only", "info", "No Type 2 occurrence check required", "A Type 1 report evaluates design and implementation as of one date.")]
+    );
+  }
+  const periodStart = coverageStart(audit.coverage);
+  const periodEnd = coverageEnd(audit.coverage);
+  if (!periodStart || !periodEnd) {
+    return stage(
+      "occurrences",
+      "Operating Occurrences",
+      "Check every expected scheduled occurrence across the exact Type 2 period.",
+      [item("period-required", "later", "Select the formal Type 2 period", "The formal period is required before FileGRC can calculate expected occurrences.", audit)]
+    );
+  }
+  const selectedControlIds = new Set(audit.controlIds || []);
+  const periodThrough = [periodEnd, asOf].filter(Boolean).sort()[0] || periodEnd;
+  if (periodThrough < periodStart) {
+    return stage(
+      "occurrences",
+      "Operating Occurrences",
+      "Check every expected scheduled occurrence across the exact Type 2 period.",
+      [item("period-not-started", "later", "Wait for the formal period to begin", `The formal Type 2 period starts on ${periodStart}. No operating occurrences are expected yet.`, audit)]
+    );
+  }
+  const periodResources = records.filter((record) => (
+    record.type !== "obligation"
+    || !(record.controlIds || []).length
+    || record.controlIds.some((id) => selectedControlIds.has(id))
+  ));
+  const plan = planObligations(periodResources, {
+    from: periodStart,
+    asOf: periodThrough,
+    through: periodThrough,
+    now: `${periodThrough}T23:59:59.999Z`,
+    includeComplete: true,
+    model
+  });
+  const gapStatuses = new Set(["overdue", "blocked", "due", "proposed"]);
+  const calendarGaps = plan.calendarItems.filter(({ status }) => gapStatuses.has(status));
+  const eventGaps = plan.eventRuns
+    .filter((run) => run.occurredOn >= periodStart && run.occurredOn <= periodThrough)
+    .flatMap((run) => run.actions)
+    .filter((action) => (
+      (gapStatuses.has(action.status) || action.lateCompletion)
+      && action.controlIds.some((id) => selectedControlIds.has(id))
+    ));
+  const gaps = [...calendarGaps, ...eventGaps];
+  const lateGaps = eventGaps.filter(({ lateCompletion }) => lateCompletion);
+  const firstGap = gaps[0];
+  return stage(
+    "occurrences",
+    "Operating Occurrences",
+    "Check every expected scheduled occurrence across the exact Type 2 period.",
+    [item(
+      "period-occurrences",
+      gaps.length ? "action" : "complete",
+      "Cover every expected operating occurrence",
+      gaps.length
+        ? lateGaps.length
+          ? `${gaps.length} expected ${gaps.length === 1 ? "occurrence needs" : "occurrences need"} review, including ${lateGaps.length} completed after the allowed window. Open the affected Action Item, record a Finding or Exception with management's conclusion, and retain the late completion as historical evidence.`
+          : `${gaps.length} expected ${gaps.length === 1 ? "occurrence is" : "occurrences are"} incomplete, blocked, or still proposed within the formal period. Resolve each Work Queue item before treating management fieldwork as ready.`
+        : `Every expected occurrence through ${periodThrough} has an accepted completion.`,
+      firstGap?.actionItemId
+        ? { type: "action-item", id: firstGap.actionItemId }
+        : firstGap?.obligationId ? { type: "obligation", id: firstGap.obligationId } : audit,
+      {
+        affectedActionItemIds: eventGaps.map(({ actionItemId }) => actionItemId).filter(Boolean),
+        affectedEventIds: [...new Set(eventGaps.map(({ eventId }) => eventId).filter(Boolean))],
+        lateCount: lateGaps.length,
+        commands: firstGap?.actionItemId ? [
+          `npx filegrc get ${firstGap.actionItemId} --json`,
+          `npx filegrc scaffold finding --title "Late operating occurrence review"`
+        ] : []
+      }
+    )]
+  );
+}
+
 async function auditDocumentActivationAssessments(loaded, audit, byId, asOf) {
   const links = new Map();
   const addLink = (documentId, role, definition = null) => {
@@ -914,14 +1027,14 @@ async function auditDocumentActivationAssessments(loaded, audit, byId, asOf) {
       ["approved", "active"].includes(document.status)
       && document.approvedOn
       && document.approvedContentRevisions
-      && (document.activationBasis === "legacy-v4"
+      && (["legacy-v4", "historical"].includes(document.activationBasis)
         ? (document.ownerIds || []).length
         : currentPartyPeople(document.ownerIds || [], byId).size)
       && (document.approverIds || []).length
       && partiesIndependent(document.ownerIds, document.approverIds, byId)
     );
     if (!approvalComplete) issues.push("Complete the independent approval and bind the approved Markdown revision first.");
-    if (document.status === "active" && document.activationBasis !== "legacy-v4") {
+    if (document.status === "active" && !["legacy-v4", "historical"].includes(document.activationBasis)) {
       if (document.activationBasis !== "recorded") issues.push("Record the Step 5 activation basis.");
       if (!document.activatedOn) issues.push("Record the separate Step 5 activation date.");
       else if (document.activatedOn > asOf) issues.push(`The activation date ${document.activatedOn} is after ${asOf}.`);
@@ -1045,8 +1158,8 @@ async function documentsStage(loaded, audit, byId, asOf) {
       complete ? "complete" : representationLater ? "later" : "action",
       definition.title,
       complete
-        ? document.activationBasis === "legacy-v4"
-          ? "Linked Markdown is complete and effective. Its active state is preserved from model v4, which did not record approval and activation as separate events."
+        ? ["legacy-v4", "historical"].includes(document.activationBasis)
+          ? "Linked Markdown is complete and effective. Its historical lifecycle basis does not claim a separate activation event that was never recorded."
           : modelSupports(loaded.model, "governed-document-activation")
             ? "Linked Markdown is complete, independently approved, separately activated by a named Person, revision-bound at both events, and effective."
           : "Linked Markdown is complete, active, approved, and effective."
@@ -1209,7 +1322,12 @@ function populationsStage(audit, records, byId, model) {
   const populations = audit
     ? records.filter((record) => record.type === "audit-population" && record.auditId === audit.id)
     : [];
-  const templates = model.auditReadiness?.populationTemplates || [];
+  const templates = applicablePopulationTemplates(
+    audit,
+    records,
+    model.auditReadiness?.populationTemplates || [],
+    populations
+  );
   const items = templates.map((template) => {
     const population = populations.find((record) => record.populationKind === template.kind);
     const result = populationResult(population, audit, byId);
@@ -1368,11 +1486,26 @@ function initializationNeeded(audit, records, model) {
   const populationKinds = new Set(records
     .filter((record) => record.type === "audit-population" && record.auditId === audit.id)
     .map((record) => record.populationKind));
-  const needsPopulation = audit.auditKind === "soc-2-type-2" && (readiness.populationTemplates || [])
+  const needsPopulation = audit.auditKind === "soc-2-type-2"
+    && applicablePopulationTemplates(audit, records, readiness.populationTemplates || [])
     .some((template) => !populationKinds.has(template.kind));
   return needsDocumentLink || needsPopulation;
 }
 
+function applicablePopulationTemplates(audit, records, templates, existingPopulations = []) {
+  const selectedControls = (audit?.controlIds || [])
+    .map((id) => records.find((record) => record.type === "control" && record.id === id))
+    .filter(Boolean);
+  const selectedCodes = new Set(selectedControls.map(({ code }) => code).filter(Boolean));
+  const existingKinds = new Set(existingPopulations.map(({ populationKind }) => populationKind));
+  const recognizedCodes = new Set(templates.flatMap(({ controlCodes }) => controlCodes || []));
+  if (selectedControls.some(({ code }) => !code || !recognizedCodes.has(code))) return templates;
+  return templates.filter((template) => (
+    existingKinds.has(template.kind)
+    || (template.controlCodes || []).some((code) => selectedCodes.has(code))
+  ));
+}
+
 function applicableManagementDocuments(audit, readiness) {
   return (readiness.managementDocuments || []).filter((definition) => (
     !audit || !definition.engagementKinds?.length || definition.engagementKinds.includes(audit.auditKind)
@@ -1571,7 +1704,10 @@ function item(id, status, title, message, resource = {}, options = {}) {
     message,
     ...(resource.type ? { resourceType: resource.type } : {}),
     ...(resource.id ? { resourceId: resource.id } : {}),
-    ...(options.commands?.length ? { commands: options.commands } : {})
+    ...(options.commands?.length ? { commands: options.commands } : {}),
+    ...(options.affectedActionItemIds?.length ? { affectedActionItemIds: options.affectedActionItemIds } : {}),
+    ...(options.affectedEventIds?.length ? { affectedEventIds: options.affectedEventIds } : {}),
+    ...(options.lateCount ? { lateCount: options.lateCount } : {})
   };
 }
 

package/src/batch-review.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { modelSupports } from "../model/index.js";
+import { applicabilityReviewIsCurrent, applicabilityScopeRevision } from "./applicability-scope.js";
 import { applyResourceBatch } from "./files.js";
 import { getWorkspaceRevisionSnapshot } from "./git.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
@@ -29,15 +30,22 @@ export async function scaffoldApplicabilityReview(input = process.cwd(), options
     throw new Error(`Applicability review type must be one of ${[...REVIEWABLE_TYPES].join(", ")}.`);
   }
   const program = resolveProgram(loaded, options.programId);
+  const requirementById = new Map(loaded.resources
+    .filter(({ type }) => type === "requirement")
+    .map((record) => [record.id, record]));
   const reviewedRequirementIds = new Set((program.requirementApplicability || [])
-    .filter(({ decision }) => ["applicable", "not-applicable"].includes(decision))
+    .filter((review) => (
+      ["applicable", "not-applicable"].includes(review.decision)
+      && requirementById.has(review.requirementId)
+      && applicabilityReviewIsCurrent(review, requirementById.get(review.requirementId), program, loaded.resources, loaded.model)
+    ))
     .map(({ requirementId }) => requirementId));
   const records = loaded.resources.filter((record) => (
     REVIEWABLE_TYPES.has(record.type)
     && (!requestedType || record.type === requestedType)
     && (record.type === "requirement" && modelSupports(loaded.model, "program-scope")
       ? !reviewedRequirementIds.has(record.id)
-      : !record.applicabilityReview)
+      : !applicabilityReviewIsCurrent(record.applicabilityReview, record, program, loaded.resources, loaded.model))
     && !["retired", "superseded"].includes(record.status)
   ));
   return {
@@ -79,8 +87,7 @@ function planApplicabilityReviewWithContext(context, options) {
     throw new Error("Batch expected revisions must be keyed by resource ID.");
   }
   const program = resolveProgram(loaded, options.programId);
-  const v4RequirementDecisions = [];
-  const update = options.decisions.flatMap((decision) => {
+  const reviewedDecisions = options.decisions.map((decision) => {
     const record = byId.get(decision.id);
     if (!record || !REVIEWABLE_TYPES.has(record.type)) {
       throw new Error(`Resource "${decision.id}" is not an applicability-review record.`);
@@ -99,6 +106,33 @@ function planApplicabilityReviewWithContext(context, options) {
     if (constraint && !constraint.allowedDecisions.includes(result)) {
       throw new Error(`${record.reference || record.title} must be applicable because it is required for the selected SOC 2 Security program.`);
     }
+    if (record.type === "requirement" && !["applicable", "not-applicable"].includes(result)) {
+      throw new Error(`Requirement "${record.id}" must be applicable or not-applicable.`);
+    }
+    return { record, result, rationale, reviewedByIds, reviewedOn };
+  });
+  const v4RequirementDecisions = reviewedDecisions
+    .filter(({ record }) => record.type === "requirement" && modelSupports(loaded.model, "program-scope"))
+    .map(({ record, result, rationale, reviewedByIds, reviewedOn }) => ({
+      requirementId: record.id,
+      decision: result,
+      rationale,
+      reviewedByIds,
+      reviewedOn,
+      scopeRevision: applicabilityScopeRevision(record, program, loaded.resources, loaded.model)
+    }));
+  const replacedRequirementIds = new Set(v4RequirementDecisions.map(({ requirementId }) => requirementId));
+  const reviewedProgram = v4RequirementDecisions.length
+    ? {
+        ...program,
+        requirementApplicability: [
+          ...(program.requirementApplicability || []).filter(({ requirementId }) => !replacedRequirementIds.has(requirementId)),
+          ...v4RequirementDecisions
+        ]
+      }
+    : program;
+  const update = reviewedDecisions.flatMap(({ record, result, rationale, reviewedByIds, reviewedOn }) => {
+    const scopeRevision = applicabilityScopeRevision(record, reviewedProgram, loaded.resources, loaded.model);
     const next = {
       ...record,
       applicabilityReview: {
@@ -106,22 +140,11 @@ function planApplicabilityReviewWithContext(context, options) {
         rationale,
         reviewedByIds,
         reviewedOn,
-        scopeRevision: basis.scopeRevision
+        scopeRevision
       }
     };
     if (record.type === "requirement") {
-      if (!["applicable", "not-applicable"].includes(result)) {
-        throw new Error(`Requirement "${record.id}" must be applicable or not-applicable.`);
-      }
       if (modelSupports(loaded.model, "program-scope")) {
-        v4RequirementDecisions.push({
-          requirementId: record.id,
-          decision: result,
-          rationale,
-          reviewedByIds,
-          reviewedOn,
-          scopeRevision: basis.scopeRevision
-        });
         return [];
       }
       next.applicability = result;
@@ -132,14 +155,7 @@ function planApplicabilityReviewWithContext(context, options) {
     return [next];
   });
   if (v4RequirementDecisions.length) {
-    const replaced = new Set(v4RequirementDecisions.map(({ requirementId }) => requirementId));
-    update.push({
-      ...program,
-      requirementApplicability: [
-        ...(program.requirementApplicability || []).filter(({ requirementId }) => !replaced.has(requirementId)),
-        ...v4RequirementDecisions
-      ]
-    });
+    update.push(reviewedProgram);
   }
   return {
     operation: "applicability-review",