filegrc 0.6.5 → 0.7.1

package/src/audit-transition.js

@@ -37,6 +37,8 @@ export async function planNextAuditCycle(input = process.cwd(), options = {}) {
       subserviceVendorIds: [...(prior.subserviceVendorIds || [])],
       ...(prior.subserviceMethod ? { subserviceMethod: prior.subserviceMethod } : {})
     }),
+    ...(prior.subserviceConclusion ? { subserviceConclusion: prior.subserviceConclusion } : {}),
+    ...(prior.subserviceConclusionRationale ? { subserviceConclusionRationale: prior.subserviceConclusionRationale } : {}),
     ...(prior.complementaryControlsConclusion
       ? { complementaryControlsConclusion: prior.complementaryControlsConclusion }
       : {}),
@@ -59,6 +61,9 @@ export async function planNextAuditCycle(input = process.cwd(), options = {}) {
       "requirementIds",
       "controlIds",
       "complementaryControlIds",
+      "subserviceConclusion",
+      "subserviceConclusionRationale",
+      "subserviceTreatments",
       "subserviceVendorIds",
       "subserviceMethod",
       "auditorVendorId",

package/src/batch-review.js

@@ -6,6 +6,7 @@ import { serializeWorkspaceMutation } from "./mutation.js";
 import { resolveDataPath } from "./paths.js";
 import { resolveProgram } from "./program.js";
 import { markdownEntries } from "./resource-markdown.js";
+import { soc2RequirementApplicabilityConstraint } from "./soc2.js";
 import { assessWorkflow, buildWorkflowDelta } from "./workflow.js";
 import { loadWorkspace } from "./workspace.js";
 
@@ -44,11 +45,15 @@ export async function scaffoldApplicabilityReview(input = process.cwd(), options
     reviewedOn: null,
     decisions: records
       .sort((left, right) => `${left.type}:${left.title}:${left.id}`.localeCompare(`${right.type}:${right.title}:${right.id}`))
-      .map((record) => ({
-        id: record.id,
-        decision: null,
-        rationale: null
-      }))
+      .map((record) => {
+        const constraint = soc2RequirementApplicabilityConstraint(record, program, loaded.model.modelVersion);
+        return {
+          id: record.id,
+          decision: constraint?.requiredDecision || null,
+          rationale: constraint?.defaultRationale || null,
+          ...(constraint ? { constraint } : {})
+        };
+      })
   };
 }
 
@@ -89,6 +94,10 @@ function planApplicabilityReviewWithContext(context, options) {
     if (!reviewedByIds.length || !reviewedOn || !rationale) {
       throw new Error(`Decision for "${record.id}" needs a reviewer, review date, and rationale.`);
     }
+    const constraint = soc2RequirementApplicabilityConstraint(record, program, loaded.model.modelVersion);
+    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.`);
+    }
     const next = {
       ...record,
       applicabilityReview: {

package/src/cli.js

@@ -41,6 +41,8 @@ import {
   setupExternalReviewerGovernance
 } from "./external-reviewer.js";
 import { relativeToWorkspace, resolveDataPath } from "./paths.js";
+import { activatePolicies, planPolicyActivation, scaffoldPolicyActivation } from "./policy-activation.js";
+import { applyPolicyLibraryUpgrade, assessPolicyLibraryUpgrades } from "./policy-library.js";
 import { buildAgentProgramPath } from "./program-path.js";
 import { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
 import { resolveProgram } from "./program.js";
@@ -432,6 +434,12 @@ export async function runCli(argv = process.argv.slice(2)) {
         console.log(`\n${stage.title}`);
         for (const item of stage.items) console.log(`${item.status.toUpperCase()}\t${item.title}\t${item.message}`);
       }
+      if (result.policyActivations.length) {
+        console.log("\nPolicy activation assessments");
+        for (const policy of result.policyActivations) {
+          console.log(`${policy.label.toUpperCase()}\t${policy.title}\t${policy.gapCount} implementation gaps`);
+        }
+      }
       if (result.canStartCandidatePeriod && !result.operating) {
         console.log(`\nEvidence Ready: management can start the candidate Type 2 period on or after ${result.suggestedCandidatePeriodStart || result.asOf}.`);
       }
@@ -588,6 +596,50 @@ export async function runCli(argv = process.argv.slice(2)) {
     else console.log(`Confirmed ${result.assessment.configuration.title}.`);
     return result;
   }
+  if (command === "activate-policies") {
+    if (flags.scaffold) {
+      const result = await scaffoldPolicyActivation(root, { programId: flags.program });
+      console.log(JSON.stringify(result, null, 2));
+      return result;
+    }
+    const payload = await readSetupPayload(positionals[0]);
+    const options = {
+      ...payload,
+      policyIds: flags.policy ? String(flags.policy).split(",").filter(Boolean) : payload.policyIds,
+      effectiveOn: flags["effective-on"] || payload.effectiveOn,
+      confirmed: flags.yes === true
+    };
+    const result = flags.preview
+      ? await planPolicyActivation(root, options)
+      : await withWorkflowDelta(root, () => activatePolicies(root, options));
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else if (flags.preview) console.log(`Policy activation preview: ${result.policyIds.length} Policies effective ${result.effectiveOn}.`);
+    else console.log(`Activated ${result.policyIds.length} Policies effective ${result.effectiveOn}.`);
+    return result;
+  }
+  if (command === "policy-library") {
+    if (flags.yes && !flags.accept) {
+      throw new Error("Pass --accept <proposal-id> with --yes after reviewing the policy-library diff.");
+    }
+    const result = flags.accept
+      ? await withWorkflowDelta(root, () => applyPolicyLibraryUpgrade(root, String(flags.accept), {
+          confirmed: flags.yes === true,
+          proposalRevision: flags["proposal-revision"] ? String(flags["proposal-revision"]) : null
+        }))
+      : await assessPolicyLibraryUpgrades(root);
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else if (flags.accept) console.log(`Accepted policy-library proposal ${flags.accept}.`);
+    else if (!result.proposals.length) console.log("No starter policy-library update applies. Existing content is unchanged.");
+    else {
+      for (const proposal of result.proposals) {
+        console.log(`${proposal.title} (${proposal.id})`);
+        console.log(proposal.message);
+        for (const change of proposal.changes) console.log(`\n${change.diff}`);
+        console.log(`\nAccept with: filegrc policy-library --accept ${proposal.id} --proposal-revision ${proposal.revision} --yes`);
+      }
+    }
+    return result;
+  }
   if (command === "trigger") {
     const result = await withWorkflowDelta(root, () => createObligationEvent(root, {
       eventType: positionals[0],
@@ -1025,6 +1077,8 @@ Usage:
   filegrc next-audit-cycle <prior-audit-id> [cycle.json|-] --start YYYY-MM-DD --end YYYY-MM-DD [--preview|--yes] [--json]
   filegrc review-applicability [--scaffold --type requirement|control|commitment|complementary-control] [decisions.json|-] [--preview|--yes] [--json]
   filegrc review-collection <resource-type> [--scaffold | review.json|-] [--preview|--yes] [--json]
+  filegrc activate-policies [--scaffold | activation.json|-] [--effective-on YYYY-MM-DD] [--preview|--yes] [--json]
+  filegrc policy-library [--json | --accept proposal-id --proposal-revision revision --yes]
   filegrc trigger <event-type> (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) [--risk-level normal|high] [--subject resource-id[,resource-id]] [--title text] [--json]
   filegrc evidence-packet [--audit audit-id] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--output .filegrc/path] [--preview] [--require-ready] [--json]
   filegrc get [resource-type] <id> [--mutation]
@@ -1174,6 +1228,44 @@ Options:
   --help             Show this help`);
     return;
   }
+  if (command === "activate-policies") {
+    console.log(`Usage:
+  filegrc activate-policies --scaffold [--program id]
+  filegrc activate-policies <activation.json|-> [--effective-on YYYY-MM-DD] [--preview|--yes] [--json]
+
+Review and atomically activate selected approved Policies at the end of Step 3.
+The scaffold includes every required, approved, inactive Policy and its current
+revision. A past effective date is rejected.
+
+Options:
+  --scaffold             Print a cutover payload without writing
+  --program <id>         Program to assess when more than one active Program exists
+  --effective-on <date>  Shared effective date for the selected Policies
+  --preview              Validate and show the atomic updates without writing
+  --yes                  Confirm and apply the reviewed cutover
+  --json                 Print the result as JSON
+  --root <path>          Workspace path
+  --help                 Show this help`);
+    return;
+  }
+  if (command === "policy-library") {
+    console.log(`Usage:
+  filegrc policy-library [--json]
+  filegrc policy-library --accept <proposal-id> --proposal-revision <revision> --yes [--json]
+
+Review optional starter-library updates for unchanged default Policy and Control
+content. The review prints exact diffs. FileGRC skips customized or adopted Policy
+content and writes nothing until you accept one named proposal revision with --yes.
+
+Options:
+  --accept <id>  Accept one proposal after reviewing its diff
+  --proposal-revision <hash>  Confirm the exact reviewed proposal revision
+  --yes          Confirm the named proposal write
+  --json         Print the versioned proposal or acceptance result
+  --root <path>  Workspace path
+  --help         Show this help`);
+    return;
+  }
   if (command === "evidence-map") {
     console.log(`Usage:
   filegrc evidence-map [options]
@@ -1220,6 +1312,7 @@ function agentOverview(model) {
     prepareAudit: "filegrc prepare-audit <audit-id>",
     reconcile: "filegrc reconcile --preview --json",
     externalReviewerSetup: "filegrc external-reviewer-setup [--scaffold | <reviewer.json|-> --preview] --json",
+    policyActivation: "filegrc activate-policies [--scaffold | <activation.json|-> --preview] --json",
     nextAuditCycle: "filegrc next-audit-cycle <prior-audit-id> --start <date> --end <date> --preview --json",
     reviewApplicability: "filegrc review-applicability <decisions.json|-> --preview --json",
     reviewCollection: "filegrc review-collection <resource-type> [--scaffold | <review.json|-> --preview] --json",
@@ -1371,6 +1464,8 @@ function buildProgramPathResult(model, readiness, auditReadiness) {
     currentStep: { id: currentStep.id, number: currentStep.number, title: currentStep.title },
     evidenceReady: readiness.evidenceReady,
     operating: readiness.operating,
+    policyActivations: readiness.policyActivations,
+    policyLibraryProposals: readiness.policyLibraryProposals,
     stages
   };
 }
@@ -1418,6 +1513,8 @@ function summarizeProgramPath(result) {
     currentStep: result.currentStep,
     evidenceReady: result.evidenceReady,
     operating: result.operating,
+    policyActivations: result.policyActivations,
+    policyLibraryProposals: result.policyLibraryProposals,
     stages: result.stages.map((stage) => ({
       id: stage.id,
       number: stage.number,
@@ -1439,6 +1536,8 @@ function nextProgramPath(result) {
     currentStep: result.currentStep,
     evidenceReady: result.evidenceReady,
     operating: result.operating,
+    policyActivations: result.policyActivations,
+    policyLibraryProposals: result.policyLibraryProposals,
     step: stage ? {
       id: stage.id,
       number: stage.number,
@@ -1562,6 +1661,14 @@ function summarizeProgramReadiness(result) {
     scopeCounts: Object.fromEntries(
       Object.entries(result.scope).map(([name, ids]) => [name.replace(/Ids$/, ""), ids.length])
     ),
+    policyActivations: result.policyActivations.map(({ policyId, title, state, label, gapCount }) => ({
+      policyId,
+      title,
+      state,
+      label,
+      gapCount
+    })),
+    policyLibraryProposals: result.policyLibraryProposals,
     unresolvedOwnership: {
       count: unresolvedOwnership.length,
       byReason: ownershipReasons,

package/src/content-readiness.js

@@ -0,0 +1,11 @@
+export function openPlaceholderCount(source) {
+  if (!source) return 0;
+  const matches = source.match(
+    /\{\{[^}\n]+\}\}|\b(?:TODO|TBD)\b|\[(?:complete|confirm|describe|insert|name|replace|select|specify|todo|tbd)[^\]\n]*\]/giu
+  );
+  return matches?.length || 0;
+}
+
+export function substantiveMarkdown(source) {
+  return (source.match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu) || []).length >= 10;
+}

package/src/evidence-packet.js

@@ -16,6 +16,16 @@ import { isWithin, resolveDataPath, resolveWorkspacePath } from "./paths.js";
 import { parseCalendarDate } from "./recurrence.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
+import {
+  auditorWasEngaged,
+  missingSoc2References,
+  recordWasInUseDuringAudit,
+  REQUIRED_SOC2_DESCRIPTION_REFERENCES,
+  REQUIRED_SOC2_SECURITY_REFERENCES,
+  signatoryAppointmentIssue,
+  soc2ReportEvidenceIssue,
+  subsequentEventsReviewIssue
+} from "./soc2.js";
 import { validateWorkspace } from "./validate.js";
 
 const NON_EVIDENCE_RECORD_TYPES = new Set([
@@ -42,7 +52,6 @@ const NON_EVIDENCE_RECORD_TYPES = new Set([
   "vendor",
   "workspace"
 ]);
-
 export async function prepareEvidencePacket(input, options = {}) {
   const validation = await validateWorkspace(input);
   if (!validation.ok) throw new Error(`The workspace has ${validation.counts.errors} validation ${validation.counts.errors === 1 ? "error" : "errors"}. Fix them before generating evidence.`);
@@ -99,7 +108,8 @@ export async function prepareEvidencePacket(input, options = {}) {
       ...(audit.controlIds || []),
       ...(audit.contactIds || []),
       ...(audit.complementaryControlIds || []),
-      ...(audit.subserviceVendorIds || []),
+      ...auditSubserviceVendorIds(audit),
+      ...auditSubserviceComponentIds(audit),
       audit.systemDescriptionDocumentId,
       audit.managementAssertionDocumentId,
       audit.managementRepresentationDocumentId,
@@ -235,7 +245,12 @@ export async function prepareEvidencePacket(input, options = {}) {
     ...markdownEntries(loaded.model, entry.record).map((markdown) => `data/${markdown.path}`)
   ]);
   const historyRevision = getGitSummary(loaded.root);
-  const histories = getWorkspaceHistories(loaded.root, selectedPaths, Number.MAX_SAFE_INTEGER);
+  const histories = getWorkspaceHistories(
+    loaded.root,
+    selectedPaths,
+    Number.MAX_SAFE_INTEGER,
+    { strict: Boolean(historyRevision.commit) }
+  );
   const packetRecords = [...selectedIds]
     .map((id) => byId.get(id))
     .filter(Boolean)
@@ -327,7 +342,9 @@ export async function prepareEvidencePacket(input, options = {}) {
       systemIds: audit.systemIds || [],
       requirementIds: audit.requirementIds || [],
       controlIds: audit.controlIds || [],
-      subserviceMethod: audit.subserviceMethod || null
+      subserviceMethod: auditSubserviceLabel(audit),
+      subserviceConclusion: audit.subserviceConclusion || null,
+      subserviceTreatments: audit.subserviceTreatments || []
     } : null,
     workspace: {
       title: loaded.workspace.title,
@@ -403,7 +420,8 @@ function recordRelevantToAudit(record, audit, byId, seen = new Set()) {
     ...(audit.controlIds || []),
     ...(audit.contactIds || []),
     ...(audit.complementaryControlIds || []),
-    ...(audit.subserviceVendorIds || []),
+    ...auditSubserviceVendorIds(audit),
+    ...auditSubserviceComponentIds(audit),
     audit.systemDescriptionDocumentId,
     audit.managementAssertionDocumentId,
     audit.managementRepresentationDocumentId,
@@ -993,7 +1011,7 @@ function packetGaps({
   if (!audit) {
     gaps.push(gap("error", "missing-audit-scope", "Select an audit record before treating this packet as an auditor delivery."));
   } else {
-    auditGaps(gaps, audit, byId, records, start, end);
+    auditGaps(gaps, audit, byId, records, start, end, model);
   }
   for (const stage of managementPreparation?.stages || []) {
     for (const item of stage.items.filter((entry) => ["action", "later"].includes(entry.status))) {
@@ -1089,7 +1107,7 @@ function packetGaps({
 
   for (const requirementId of requirementIds) {
     const requirement = byId.get(requirementId);
-    if (!requirement || requirement.applicability !== "applicable" || isDescriptionRequirement(requirement)) continue;
+    if (!requirement || !requirementIsApplicable(requirement, audit, byId, model) || isDescriptionRequirement(requirement)) continue;
     const mapped = controlCoverage.some((coverage) => coverage.requirementIds.includes(requirementId));
     if (!mapped) gaps.push(gap("error", "requirement-missing-control", `${requirement.reference || requirement.title} has no control in the packet.`, requirementId));
   }
@@ -1120,11 +1138,11 @@ function packetGaps({
     if (!recentAssessment) {
       gaps.push(gap("error", "missing-risk-assessment", `No completed in-scope risk assessment was found in the year ending ${end}.`, audit.id));
     }
-    for (const vendorId of audit.subserviceVendorIds || []) {
+    for (const vendorId of auditSubserviceVendorIds(audit)) {
       const vendor = byId.get(vendorId);
       if (!vendor) continue;
-      if (vendor.status !== "active") {
-        gaps.push(gap("error", "inactive-subservice-organization", `${vendor.title} is in audit scope but is ${vendor.status}.`, vendor.id));
+      if (!recordWasInUseDuringAudit(vendor, start, end)) {
+        gaps.push(gap("error", "inactive-subservice-organization", `${vendor.title} was not in use during the engagement period.`, vendor.id));
       }
       const reviews = records.filter((record) => (
         record.type === "vendor-review"
@@ -1302,7 +1320,11 @@ function controlNeedsExternalEvidence(control, model) {
   return !families.length || families.some((family) => family.filegrcManaged !== true);
 }
 
-function auditGaps(gaps, audit, byId, records, start, end) {
+function auditGaps(gaps, audit, byId, records, start, end, model) {
+  const program = byId.get(audit.programId);
+  if (String(model.modelVersion) === "4" && program?.assuranceGoal !== audit.auditKind) {
+    gaps.push(gap("error", "audit-program-goal-mismatch", `${audit.title} is ${audit.auditKind}, but its Program goal is ${program?.assuranceGoal || "missing"}. Align the management objective with the formal engagement before delivery.`, audit.id));
+  }
   if (!["soc-2-type-1", "soc-2-type-2"].includes(audit.auditKind)) {
     gaps.push(gap("error", "not-soc2-examination", `${audit.title} is ${audit.auditKind}; a delivery packet requires a SOC 2 Type 1 or Type 2 engagement.`, audit.id));
   } else if (audit.auditKind === "soc-2-type-1") {
@@ -1321,34 +1343,118 @@ function auditGaps(gaps, audit, byId, records, start, end) {
   if (!(audit.requirementIds || []).length) gaps.push(gap("error", "audit-requirements-missing", `${audit.title} has no selected criteria.`, audit.id));
   if (!(audit.controlIds || []).length) gaps.push(gap("error", "audit-controls-missing", `${audit.title} has no selected controls.`, audit.id));
   const selectedRequirements = (audit.requirementIds || []).map((id) => byId.get(id)).filter(Boolean);
-  if (!selectedRequirements.some(isDescriptionRequirement)) {
+  const frameworkRequirements = records.filter((record) => (
+    record.type === "requirement" && (audit.frameworkIds || []).includes(record.frameworkId)
+  ));
+  const descriptionRequirements = frameworkRequirements.filter(isDescriptionRequirement);
+  const missingDescriptionRequirements = descriptionRequirements.filter((requirement) => (
+    !(audit.requirementIds || []).includes(requirement.id)
+  ));
+  const missingRequiredDescriptionReferences = String(model.modelVersion) === "4"
+    ? missingSoc2References(descriptionRequirements, REQUIRED_SOC2_DESCRIPTION_REFERENCES)
+    : [];
+  const securityRequirements = frameworkRequirements.filter(isSecurityRequirement);
+  const missingRequiredSecurityReferences = String(model.modelVersion) === "4"
+    ? missingSoc2References(securityRequirements, REQUIRED_SOC2_SECURITY_REFERENCES)
+    : [];
+  const missingSelectedSecurityReferences = String(model.modelVersion) === "4"
+    ? missingSoc2References(selectedRequirements.filter(isSecurityRequirement), REQUIRED_SOC2_SECURITY_REFERENCES)
+    : [];
+  if (!descriptionRequirements.length) {
     gaps.push(gap("error", "audit-description-criteria-missing", `${audit.title} does not include the SOC 2 description criteria.`, audit.id));
+  } else if (missingDescriptionRequirements.length) {
+    gaps.push(gap("error", "audit-description-criteria-incomplete", `${audit.title} omits ${missingDescriptionRequirements.length} ${missingDescriptionRequirements.length === 1 ? "criterion" : "criteria"} from the selected SOC 2 Description Criteria framework.`, audit.id));
+  } else if (missingRequiredDescriptionReferences.length) {
+    gaps.push(gap("error", "audit-description-criteria-incomplete", `${audit.title} omits ${missingRequiredDescriptionReferences.join(", ")} from the required DC1 through DC9 Description Criteria set.`, audit.id));
+  }
+  if (missingRequiredSecurityReferences.length) {
+    gaps.push(gap("error", "audit-security-criteria-incomplete", `${audit.title}'s selected framework omits ${missingRequiredSecurityReferences.join(", ")} from the required CC1.1 through CC9.2 Security Common Criteria set.`, audit.id));
+  }
+  if (missingSelectedSecurityReferences.length) {
+    gaps.push(gap("error", "audit-security-criteria-incomplete", `${audit.title} omits ${missingSelectedSecurityReferences.join(", ")} from the mandatory Security Common Criteria selected for the engagement.`, audit.id));
   }
   for (const requirement of selectedRequirements) {
-    if (!(audit.frameworkIds || []).includes(requirement.frameworkId) || requirement.applicability !== "applicable") {
+    if (!(audit.frameworkIds || []).includes(requirement.frameworkId) || !requirementIsApplicable(requirement, audit, byId, model)) {
       gaps.push(gap("error", "audit-criteria-scope-conflict", `${requirement.reference || requirement.title} is selected but is not an applicable member of the selected frameworks.`, requirement.id));
     }
   }
-  if (!audit.auditorVendorId) gaps.push(gap("error", "auditor-missing", `${audit.title} does not identify the independent CPA firm.`, audit.id));
-  if (!audit.subserviceMethod) gaps.push(gap("error", "subservice-method-missing", `${audit.title} does not state whether subservice organizations use the carve-out or inclusive method, or are not applicable.`, audit.id));
-  if ((audit.subserviceVendorIds || []).length && audit.subserviceMethod === "not-applicable") {
-    gaps.push(gap("error", "subservice-scope-conflict", `${audit.title} names subservice organizations but marks their treatment not applicable.`, audit.id));
+  const auditor = audit.auditorVendorId ? byId.get(audit.auditorVendorId) : null;
+  if (!auditor) {
+    gaps.push(gap("error", "auditor-missing", `${audit.title} does not identify the independent CPA firm.`, audit.id));
+  } else if (!auditorWasEngaged(auditor, audit)) {
+    gaps.push(gap("error", "auditor-outside-engagement-period", `${auditor.title} was not active during the recorded fieldwork or report period.`, auditor.id));
   }
-  const expectedSubserviceVendorIds = new Set((audit.systemIds || []).flatMap((id) => byId.get(id)?.subserviceVendorIds || []));
-  for (const vendorId of expectedSubserviceVendorIds) {
-    if (!(audit.subserviceVendorIds || []).includes(vendorId)) {
-      gaps.push(gap("error", "subservice-organization-omitted", `${byId.get(vendorId)?.title || vendorId} is identified by an in-scope system but omitted from the engagement's subservice organizations.`, vendorId));
-    }
+  if (String(model.modelVersion) === "4" && !audit.scopeRevision) {
+    gaps.push(gap("error", "audit-scope-revision-missing", `${audit.title} does not bind management's reviewed engagement scope to a Git revision.`, audit.id));
   }
-  if (audit.subserviceMethod === "inclusive") {
-    const subserviceSystemIds = records
-      .filter((record) => record.type === "system" && (audit.subserviceVendorIds || []).includes(record.vendorId))
-      .map((record) => record.id);
-    const includedControls = (audit.controlIds || [])
-      .map((id) => byId.get(id))
-      .filter((control) => (control?.systemIds || []).some((id) => subserviceSystemIds.includes(id)));
-    if (!subserviceSystemIds.length || !includedControls.length) {
-      gaps.push(gap("error", "inclusive-subservice-controls-missing", `${audit.title} uses the inclusive method but does not include cataloged subservice systems and their controls.`, audit.id));
+  if (String(model.modelVersion) === "4") {
+    const treatments = audit.subserviceTreatments || [];
+    const treatmentComponentCounts = new Map();
+    for (const treatment of treatments) {
+      for (const componentId of treatment.componentIds || []) {
+        treatmentComponentCounts.set(componentId, (treatmentComponentCounts.get(componentId) || 0) + 1);
+      }
+    }
+    if (!audit.subserviceConclusion) {
+      gaps.push(gap("error", "subservice-conclusion-missing", `${audit.title} does not state whether subservice organizations are identified.`, audit.id));
+    }
+    if (!audit.subserviceConclusionRationale) {
+      gaps.push(gap("error", "subservice-rationale-missing", `${audit.title} does not explain its subservice conclusion.`, audit.id));
+    }
+    if (audit.subserviceConclusion === "identified" && !treatments.length) {
+      gaps.push(gap("error", "subservice-treatments-missing", `${audit.title} identifies subservice organizations but records no Vendor and Component treatments.`, audit.id));
+    }
+    if (audit.subserviceConclusion === "not-applicable" && treatments.length) {
+      gaps.push(gap("error", "subservice-scope-conflict", `${audit.title} records subservice treatments but marks subservice organizations not applicable.`, audit.id));
+    }
+    for (const treatment of treatments) {
+      const vendor = byId.get(treatment.vendorId);
+      const invalidComponents = (treatment.componentIds || []).filter((componentId) => {
+        const component = byId.get(componentId);
+        return component?.type !== "component"
+          || !recordWasInUseDuringAudit(component, start, end)
+          || component.vendorId !== treatment.vendorId
+          || (treatmentComponentCounts.get(componentId) || 0) > 1
+          || !(component.systemUses || []).some(({ systemId }) => (audit.systemIds || []).includes(systemId));
+      });
+      if (vendor?.type !== "vendor" || !recordWasInUseDuringAudit(vendor, start, end) || !(treatment.componentIds || []).length || invalidComponents.length) {
+        gaps.push(gap(
+          "error",
+          "invalid-subservice-treatment",
+          `${vendor?.title || treatment.vendorId} has a subservice treatment that does not identify that Vendor's supplied Components in use within the selected System boundary during the engagement, or repeats a Component across treatments.`,
+          audit.id
+        ));
+      }
+    }
+    for (const treatment of treatments.filter(({ method }) => method === "inclusive")) {
+      const includedControls = (audit.controlIds || [])
+        .map((id) => byId.get(id))
+        .filter((control) => (control?.componentIds || []).some((id) => (treatment.componentIds || []).includes(id)));
+      if (!includedControls.length) {
+        gaps.push(gap("error", "inclusive-subservice-controls-missing", `${byId.get(treatment.vendorId)?.title || treatment.vendorId} uses the inclusive method but no selected Controls are linked to its included Components.`, audit.id));
+      }
+    }
+  } else {
+    if (!audit.subserviceMethod) gaps.push(gap("error", "subservice-method-missing", `${audit.title} does not state whether subservice organizations use the carve-out or inclusive method, or are not applicable.`, audit.id));
+    if ((audit.subserviceVendorIds || []).length && audit.subserviceMethod === "not-applicable") {
+      gaps.push(gap("error", "subservice-scope-conflict", `${audit.title} names subservice organizations but marks their treatment not applicable.`, audit.id));
+    }
+    const expectedSubserviceVendorIds = new Set((audit.systemIds || []).flatMap((id) => byId.get(id)?.subserviceVendorIds || []));
+    for (const vendorId of expectedSubserviceVendorIds) {
+      if (!(audit.subserviceVendorIds || []).includes(vendorId)) {
+        gaps.push(gap("error", "subservice-organization-omitted", `${byId.get(vendorId)?.title || vendorId} is identified by an in-scope system but omitted from the engagement's subservice organizations.`, vendorId));
+      }
+    }
+    if (audit.subserviceMethod === "inclusive") {
+      const subserviceSystemIds = records
+        .filter((record) => record.type === "system" && (audit.subserviceVendorIds || []).includes(record.vendorId))
+        .map((record) => record.id);
+      const includedControls = (audit.controlIds || [])
+        .map((id) => byId.get(id))
+        .filter((control) => (control?.systemIds || []).some((id) => subserviceSystemIds.includes(id)));
+      if (!subserviceSystemIds.length || !includedControls.length) {
+        gaps.push(gap("error", "inclusive-subservice-controls-missing", `${audit.title} uses the inclusive method but does not include cataloged subservice systems and their controls.`, audit.id));
+      }
     }
   }
   if (!audit.complementaryControlsConclusion) {
@@ -1385,15 +1491,42 @@ function auditGaps(gaps, audit, byId, records, start, end) {
       gaps.push(gap("error", `unapproved-${field}`, `${document.title} is not active with approval and effective dates.`, document.id));
     }
   }
-  if (audit.status === "complete") {
-    const representation = byId.get(audit.managementRepresentationDocumentId);
-    if (!(representation?.evidenceIds || []).length) {
-      gaps.push(gap("error", "unsigned-management-representation", `${representation?.title || audit.title} does not link the signed representation letter evidence.`, representation?.id || audit.id));
+  if (["issued", "delivered", "complete"].includes(audit.status)) {
+    const reportEvidence = audit.reportEvidenceId ? byId.get(audit.reportEvidenceId) : null;
+    if (!reportEvidence) {
+      gaps.push(gap("error", "missing-audit-report", `${audit.title} does not link the final service auditor report.`, audit.id));
+    } else {
+      const reportIssue = soc2ReportEvidenceIssue(reportEvidence, audit, model.modelVersion);
+      if (reportIssue) gaps.push(gap("error", reportIssue.code, reportIssue.message, reportEvidence.id));
     }
-    if (!audit.reportEvidenceId) gaps.push(gap("error", "missing-audit-report", `${audit.title} does not link the final service auditor report.`, audit.id));
     if (!audit.opinion || audit.opinion === "not-issued" || !audit.opinionDate) {
       gaps.push(gap("error", "missing-audit-opinion", `${audit.title} does not record the issued opinion and opinion date.`, audit.id));
     }
+  }
+  if (String(model.modelVersion) === "4" && ["report-draft", "issued", "delivered", "complete"].includes(audit.status)) {
+    const subsequentEventsIssue = subsequentEventsReviewIssue(audit);
+    if (subsequentEventsIssue) {
+      gaps.push(gap("error", subsequentEventsIssue.code, subsequentEventsIssue.message, audit.id));
+    }
+    const signatoryIssue = signatoryAppointmentIssue(audit, byId);
+    if (signatoryIssue) {
+      gaps.push(gap("error", signatoryIssue.code, signatoryIssue.message, audit.id));
+    }
+  }
+  if (audit.status === "complete") {
+    const representation = byId.get(audit.managementRepresentationDocumentId);
+    const signedRepresentation = (representation?.evidenceIds || [])
+      .map((id) => byId.get(id))
+      .find((record) => (
+        record?.type === "evidence"
+        && record.status === "verified"
+        && record.artifactKind === "signed-record"
+        && record.artifactSubtype === "signed-management-representation"
+        && (record.filePaths || []).length
+      ));
+    if (!signedRepresentation) {
+      gaps.push(gap("error", "unsigned-management-representation", `${representation?.title || audit.title} does not link the signed representation letter evidence.`, representation?.id || audit.id));
+    }
     for (const request of records.filter((record) => record.type === "audit-request" && record.auditId === audit.id)) {
       if (!["accepted", "closed"].includes(request.status)) {
         gaps.push(gap("error", "open-final-audit-request", `${request.title} is ${request.status} after the audit was marked complete.`, request.id));
@@ -1418,6 +1551,39 @@ function isDescriptionRequirement(requirement) {
   return (requirement.tags || []).includes("description-criteria") || /^DC\d+/i.test(requirement.reference || "");
 }
 
+function isSecurityRequirement(requirement) {
+  const tags = requirement?.tags || [];
+  return tags.includes("security") || tags.includes("common-criteria") || /^CC\d+(?:\.|$)/i.test(requirement?.reference || "");
+}
+
+function requirementIsApplicable(requirement, audit, byId, model) {
+  if (String(model.modelVersion) !== "4") return requirement.applicability === "applicable";
+  const program = audit?.programId ? byId.get(audit.programId) : null;
+  return (program?.requirementApplicability || []).some((decision) => (
+    decision.requirementId === requirement.id && decision.decision === "applicable"
+  ));
+}
+
+function auditSubserviceVendorIds(audit) {
+  return [...new Set([
+    ...(audit?.subserviceVendorIds || []),
+    ...(audit?.subserviceTreatments || []).map(({ vendorId }) => vendorId)
+  ].filter(Boolean))];
+}
+
+function auditSubserviceComponentIds(audit) {
+  return [...new Set((audit?.subserviceTreatments || []).flatMap(({ componentIds }) => componentIds || []))];
+}
+
+function auditSubserviceLabel(audit) {
+  if (audit?.subserviceConclusion === "not-applicable") return "Not applicable";
+  if (audit?.subserviceConclusion === "identified") {
+    const methods = [...new Set((audit.subserviceTreatments || []).map(({ method }) => method))];
+    return methods.length ? methods.join(" and ") : "Identified, treatments incomplete";
+  }
+  return audit?.subserviceMethod || null;
+}
+
 function shiftYear(value, offset) {
   const date = new Date(`${value}T00:00:00Z`);
   date.setUTCFullYear(date.getUTCFullYear() + offset);