filegrc 0.7.0 → 0.8.0

package/src/evidence-packet.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { copyFile, mkdir, readFile, readdir, readlink, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { modelSupports } from "../model/index.js";
 import { assessAuditPreparation } from "./audit-preparation.js";
 import {
   coverageContains,
@@ -10,13 +11,26 @@ import {
   coverageOverlaps,
   coverageStart
 } from "./coverage.js";
-import { getFileAtRevision, getGitSummary, getWorkspaceHistories, hasGitRevision } from "./git.js";
+import { getFilesAtRevisions, getGitSummary, getWorkspaceHistories, getWorkspaceRevisionSnapshot, hasGitRevision } from "./git.js";
 import { planObligations } from "./obligations.js";
-import { isWithin, resolveDataPath, resolveWorkspacePath } from "./paths.js";
+import { isWithin, resolveDataPath, resolveWorkspacePath, resolveWorkspaceRoot } 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";
+import { measureTiming } from "./timing.js";
+
+const preparedPacketValidations = new WeakMap();
 
 const NON_EVIDENCE_RECORD_TYPES = new Set([
   "appointment",
@@ -42,7 +56,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 +112,9 @@ export async function prepareEvidencePacket(input, options = {}) {
       ...(audit.controlIds || []),
       ...(audit.contactIds || []),
       ...(audit.complementaryControlIds || []),
-      ...(audit.subserviceVendorIds || []),
+      ...auditSubserviceVendorIds(audit),
+      ...auditSubserviceComponentIds(audit),
+      audit.engagementTermsDocumentId,
       audit.systemDescriptionDocumentId,
       audit.managementAssertionDocumentId,
       audit.managementRepresentationDocumentId,
@@ -218,7 +233,7 @@ export async function prepareEvidencePacket(input, options = {}) {
     return sourceRevisionValidity.get(revision);
   };
   const evidence = [...evidenceIds].map((id) => evidenceSummary(byId.get(id), byId, revisionIsValid)).filter(Boolean).sort(byTitle);
-  const v4 = String(loaded.model.modelVersion) === "4";
+  const v4 = modelSupports(loaded.model, "component-sources");
   const sourceSystemIds = new Set([
     ...(v4
       ? [...controlIds].flatMap((id) => byId.get(id)?.evidenceSourceComponentIds || [])
@@ -234,8 +249,13 @@ export async function prepareEvidencePacket(input, options = {}) {
     `data/${entry.relativePath}`,
     ...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 historyRevision = await getWorkspaceRevisionSnapshot(loaded.root);
+  const histories = getWorkspaceHistories(
+    loaded.root,
+    selectedPaths,
+    Number.MAX_SAFE_INTEGER,
+    { strict: Boolean(historyRevision.commit) }
+  );
   const packetRecords = [...selectedIds]
     .map((id) => byId.get(id))
     .filter(Boolean)
@@ -290,6 +310,7 @@ export async function prepareEvidencePacket(input, options = {}) {
     generatedAt,
     selectDefault: false
   });
+  const documentLifecycles = auditDocumentLifecycleSummaries(audit, loaded.model, byId);
   const gaps = packetGaps({
     audit,
     byId,
@@ -308,7 +329,7 @@ export async function prepareEvidencePacket(input, options = {}) {
   });
   const errorCount = gaps.filter(({ severity }) => severity === "error").length;
   const warningCount = gaps.filter(({ severity }) => severity === "warning").length;
-  return {
+  const packet = {
     schemaVersion: 1,
     generatedAt,
     period: { start, end, basis },
@@ -327,7 +348,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,
@@ -359,6 +382,7 @@ export async function prepareEvidencePacket(input, options = {}) {
       eventRuns: eventRuns.length,
       evidence: evidence.length,
       populations: populations.length,
+      ...(modelSupports(loaded.model, "governed-document-activation") ? { documents: documentLifecycles.length } : {}),
       gaps: gaps.length,
       errors: errorCount,
       warnings: warningCount
@@ -373,11 +397,64 @@ export async function prepareEvidencePacket(input, options = {}) {
     [v4 ? "sourceComponents" : "sourceSystems"]: sourceSystems,
     dataModelVersion: String(loaded.model.modelVersion),
     populations,
+    ...(modelSupports(loaded.model, "governed-document-activation") ? { documentLifecycles } : {}),
     managementPreparation,
     controlCoverage,
     gaps,
     records: packetRecords
   };
+  preparedPacketValidations.set(packet, {
+    validation,
+    revision: {
+      commit: packet.revision.commit,
+      branch: packet.revision.branch,
+      dataDigest: packet.revision.dataDigest
+    }
+  });
+  return packet;
+}
+
+function auditDocumentLifecycleSummaries(audit, model, byId) {
+  if (!audit || !modelSupports(model, "governed-document-activation")) return [];
+  const rolesById = new Map();
+  const add = (id, role) => {
+    if (!id) return;
+    const roles = rolesById.get(id) || [];
+    roles.push(role);
+    rolesById.set(id, roles);
+  };
+  add(audit.engagementTermsDocumentId, "Engagement Terms");
+  for (const definition of model.auditReadiness?.managementDocuments || []) {
+    if (!(definition.engagementKinds || []).includes(audit.auditKind)) continue;
+    add(audit[definition.field], definition.title || definition.field);
+  }
+  for (const id of audit.supplementalDocumentIds || []) add(id, "Supplemental");
+  return [...rolesById]
+    .map(([id, roles]) => {
+      const document = byId.get(id);
+      if (document?.type !== "document") return null;
+      const personLabels = (ids = []) => ids.map((personId) => byId.get(personId)?.title || personId);
+      return {
+        id: document.id,
+        title: document.title,
+        workflowScope: document.workflowScope || null,
+        roles: [...new Set(roles)],
+        status: document.status,
+        ownerIds: document.ownerIds || [],
+        approverIds: document.approverIds || [],
+        approvers: personLabels(document.approverIds),
+        approvedOn: document.approvedOn || null,
+        approvedContentRevisions: document.approvedContentRevisions || null,
+        activationBasis: document.activationBasis || null,
+        activatedByIds: document.activatedByIds || [],
+        activators: personLabels(document.activatedByIds),
+        activatedOn: document.activatedOn || null,
+        activatedContentRevisions: document.activatedContentRevisions || null,
+        effectiveOn: document.effectiveOn || null
+      };
+    })
+    .filter(Boolean)
+    .sort(byTitle);
 }
 
 function expandSupersededPolicyIds(policyIds, byId) {
@@ -403,7 +480,9 @@ function recordRelevantToAudit(record, audit, byId, seen = new Set()) {
     ...(audit.controlIds || []),
     ...(audit.contactIds || []),
     ...(audit.complementaryControlIds || []),
-    ...(audit.subserviceVendorIds || []),
+    ...auditSubserviceVendorIds(audit),
+    ...auditSubserviceComponentIds(audit),
+    audit.engagementTermsDocumentId,
     audit.systemDescriptionDocumentId,
     audit.managementAssertionDocumentId,
     audit.managementRepresentationDocumentId,
@@ -483,7 +562,17 @@ export async function writeEvidencePacket(input, packet, options = {}) {
   let outputOption = options.output || `.filegrc/evidence-packets/${baseName}`;
   requireDerivedOutputPath(outputOption);
   let output = resolveWorkspacePath(input, outputOption);
-  const validation = await validateWorkspace(input);
+  const prepared = preparedPacketValidations.get(packet);
+  const preparedValidation = prepared
+    && prepared.validation.loaded.root === resolveWorkspaceRoot(input)
+    && prepared.revision.commit === packet.revision?.commit
+    && prepared.revision.branch === packet.revision?.branch
+    && prepared.revision.dataDigest === packet.revision?.dataDigest
+    ? prepared.validation
+    : null;
+  const validation = preparedValidation
+    ? preparedValidation
+    : 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 writing evidence.`);
   await assertPacketSourceState(packet, validation.loaded);
   const entriesById = new Map(validation.loaded.entries.map((entry) => [entry.record.id, entry]));
@@ -513,9 +602,12 @@ export async function writeEvidencePacket(input, packet, options = {}) {
     await writePacketFile(output, "README.md", packetMarkdown(packet), files);
     await writePacketFile(output, "index.html", packetHtml(packet), files);
     await writePacketFile(output, "control-matrix.csv", controlMatrixCsv(packet), files);
+    if (modelSupports(packet.dataModelVersion, "governed-document-activation")) {
+      await writePacketFile(output, "document-lifecycle-index.csv", documentLifecycleIndexCsv(packet), files);
+    }
     await writePacketFile(output, "evidence-index.csv", evidenceIndexCsv(packet), files);
-    await writePacketFile(output, packet.dataModelVersion === "4" ? "source-component-index.csv" : "source-system-index.csv", sourceSystemIndexCsv(packet), files);
-    await writePacketFile(output, packet.dataModelVersion === "4" ? "evidence-artifact-index.csv" : "external-evidence-index.csv", externalEvidenceIndexCsv(packet), files);
+    await writePacketFile(output, modelSupports(packet.dataModelVersion, "component-sources") ? "source-component-index.csv" : "source-system-index.csv", sourceSystemIndexCsv(packet), files);
+    await writePacketFile(output, modelSupports(packet.dataModelVersion, "evidence-artifacts") ? "evidence-artifact-index.csv" : "external-evidence-index.csv", externalEvidenceIndexCsv(packet), files);
     await writePacketFile(output, "population-index.csv", populationIndexCsv(packet), files);
     await writePacketFile(output, "HANDLING.md", packetHandlingMarkdown(packet), files);
     for (const item of packet.records) {
@@ -542,12 +634,28 @@ export async function writeEvidencePacket(input, packet, options = {}) {
       }
     }
     const historyIndex = [];
+    const historicalFiles = [];
     for (const item of packet.records) {
-      await exportCommittedVersions(validation.loaded.root, output, item, item.path, item.history, historyIndex, files);
+      collectCommittedVersions(historicalFiles, item, item.path, item.history);
       for (const content of item.contentPaths || []) {
-        await exportCommittedVersions(validation.loaded.root, output, item, content.path, content.history, historyIndex, files);
+        collectCommittedVersions(historicalFiles, item, content.path, content.history);
       }
     }
+    const historicalSources = getFilesAtRevisions(validation.loaded.root, historicalFiles);
+    for (let index = 0; index < historicalFiles.length; index += 1) {
+      const source = historicalSources[index];
+      if (source === null) continue;
+      const { item, sourcePath, history } = historicalFiles[index];
+      const exportedPath = join("history", item.type, item.id, history.commit, basename(sourcePath));
+      await writePacketFile(output, exportedPath, source, files);
+      historyIndex.push({
+        resourceId: item.id,
+        resourceType: item.type,
+        sourcePath,
+        exportedPath: exportedPath.split("\\").join("/"),
+        ...history
+      });
+    }
     await writePacketFile(output, "history/index.json", `${JSON.stringify(historyIndex, null, 2)}\n`, files);
     await assertPacketSourceState(packet, validation.loaded);
     await writeChecksums(output, files);
@@ -568,35 +676,34 @@ export function generateEvidencePacket(input, options = {}) {
   });
 }
 
-async function exportCommittedVersions(root, output, item, sourcePath, history, historyIndex, files) {
+function collectCommittedVersions(target, item, sourcePath, history) {
   for (const revision of history || []) {
-    const source = getFileAtRevision(root, revision.commit, sourcePath);
-    if (source === null) continue;
-    const exportedPath = join("history", item.type, item.id, revision.commit, basename(sourcePath));
-    await writePacketFile(output, exportedPath, source, files);
-    historyIndex.push({
-      resourceId: item.id,
-      resourceType: item.type,
-      sourcePath,
-      exportedPath: exportedPath.split("\\").join("/"),
-      ...revision
-    });
+    target.push({ item, sourcePath, relativePath: sourcePath, revision: revision.commit, history: revision });
   }
 }
 
 async function writeChecksums(output, files) {
-  const lines = [];
-  for (const relativePath of [...files].sort()) {
-    const hash = createHash("sha256");
-    for await (const chunk of createReadStream(resolvePacketOutputPath(output, relativePath))) hash.update(chunk);
-    lines.push(`${hash.digest("hex")}  ${relativePath}`);
-  }
-  await writeFile(resolvePacketOutputPath(output, "SHA256SUMS"), `${lines.join("\n")}\n`, { encoding: "utf8", flag: "wx" });
+  await measureTiming("packet-output-hash", async () => {
+    const paths = [...files].sort();
+    const lines = new Array(paths.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(4, paths.length) }, async () => {
+      while (next < paths.length) {
+        const index = next++;
+        const relativePath = paths[index];
+        const hash = createHash("sha256");
+        for await (const chunk of createReadStream(resolvePacketOutputPath(output, relativePath))) hash.update(chunk);
+        lines[index] = `${hash.digest("hex")}  ${relativePath}`;
+      }
+    });
+    await Promise.all(workers);
+    await writeFile(resolvePacketOutputPath(output, "SHA256SUMS"), `${lines.join("\n")}\n`, { encoding: "utf8", flag: "wx" });
+  });
 }
 
 function controlMatrixCsv(packet) {
   return csv([
-    ["Control ID", "Code", "Control", "Control Statement", "Operating Activity", "Status", "Effective On", "Operation Pattern", "Operation Mode", "System IDs", "Requirement IDs", "Policy IDs", "Risk IDs", "filegrc Evidence IDs", packet.dataModelVersion === "4" ? "Evidence Artifact IDs" : "External Evidence IDs", "Control Test IDs", "Test Outcomes", "Population IDs", "Population Counts", "Sample Sizes", "Exception Counts", "Population Evidence IDs", "Sample Evidence IDs"],
+    ["Control ID", "Code", "Control", "Control Statement", "Operating Activity", "Status", "Effective On", "Operation Pattern", "Operation Mode", "System IDs", "Requirement IDs", "Policy IDs", "Risk IDs", "filegrc Evidence IDs", modelSupports(packet.dataModelVersion, "evidence-artifacts") ? "Evidence Artifact IDs" : "External Evidence IDs", "Control Test IDs", "Test Outcomes", "Population IDs", "Population Counts", "Sample Sizes", "Exception Counts", "Population Evidence IDs", "Sample Evidence IDs"],
     ...packet.controlCoverage.map((control) => [
       control.id,
       control.code,
@@ -625,6 +732,30 @@ function controlMatrixCsv(packet) {
   ]);
 }
 
+function documentLifecycleIndexCsv(packet) {
+  return csv([
+    ["Document ID", "Document", "Workflow Scope", "Audit Roles", "Status", "Owner IDs", "Approver IDs", "Approvers", "Approved On", "Approved Content Revisions", "Activation Basis", "Activator IDs", "Activators", "Activated On", "Activation Content Revisions", "Effective On"],
+    ...packet.documentLifecycles.map((document) => [
+      document.id,
+      document.title,
+      document.workflowScope,
+      document.roles.join("\n"),
+      document.status,
+      document.ownerIds.join("\n"),
+      document.approverIds.join("\n"),
+      document.approvers.join("\n"),
+      document.approvedOn,
+      document.approvedContentRevisions ? JSON.stringify(document.approvedContentRevisions) : "",
+      document.activationBasis,
+      document.activatedByIds.join("\n"),
+      document.activators.join("\n"),
+      document.activatedOn,
+      document.activatedContentRevisions ? JSON.stringify(document.activatedContentRevisions) : "",
+      document.effectiveOn
+    ])
+  ]);
+}
+
 function packetHandlingMarkdown(packet) {
   return [
     "# Packet Handling",
@@ -645,7 +776,7 @@ function packetHandlingMarkdown(packet) {
 }
 
 function evidenceIndexCsv(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   return csv([
     ["Evidence ID", v4 ? "Evidence Artifact" : "Evidence", "Status", "Kind", "Source", v4 ? "Source Component ID" : "Source System ID", v4 ? "Source Component" : "Source System", "Collected On", "Collector IDs", "Verified On", "Verifier IDs", "Period Start", "Period End", "Generated At", "Timezone", "Query or Report Parameters", "Population Count", "Completeness Validation", "Accuracy Validation", "Control IDs", "Source Resource IDs", "Source Commit", "File Paths", "External Reference"],
     ...packet.evidence.map((item) => [
@@ -678,7 +809,7 @@ function evidenceIndexCsv(packet) {
 }
 
 function sourceSystemIndexCsv(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   return csv([
     [v4 ? "Component ID" : "System ID", v4 ? "Component" : "System", "Status", "Evidence Source Roles", "Evidence Access Owner IDs", "Vendor ID", v4 ? "Supports Audit System" : "In Audit Scope", "Evidence IDs"],
     ...(packet.sourceComponents || packet.sourceSystems || []).map((item) => [
@@ -695,7 +826,7 @@ function sourceSystemIndexCsv(packet) {
 }
 
 function externalEvidenceIndexCsv(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   return csv([
     ["Evidence ID", v4 ? "Evidence Artifact" : "Evidence", v4 ? "Source Component ID" : "Source System ID", v4 ? "Source Component" : "Source System", "Control IDs", "External Reference", "Fixed Attachment Included", "Delivery Note"],
     ...packet.evidence
@@ -716,7 +847,7 @@ function externalEvidenceIndexCsv(packet) {
 }
 
 function populationIndexCsv(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   return csv([
     ["Population ID", "Population", "Kind", "Status", "Period Start", "Period End", v4 ? "Source Component ID" : "Source System ID", v4 ? "Source Component" : "Source System", "Authoritative Source", "Query or Report Parameters", "Timezone", "Generated At", "Record Count", "Completeness Validation", "Accuracy Validation", "Reconciled By", "Reconciled On", "Conclusion", "Control IDs", "Evidence ID", "Not Applicable Reason"],
     ...packet.populations.map((item) => [
@@ -769,7 +900,7 @@ function requireDerivedOutputPath(value) {
 async function assertPacketSourceState(packet, loaded) {
   await assertLoadedEntriesCurrent(loaded);
   const dataDigest = await dataTreeDigest(loaded.root);
-  const git = getGitSummary(loaded.root);
+  const git = await getWorkspaceRevisionSnapshot(loaded.root);
   if (
     packet.revision?.dataDigest !== dataDigest
     || packet.revision?.commit !== git.commit
@@ -789,36 +920,38 @@ async function assertLoadedEntriesCurrent(loaded) {
 }
 
 async function dataTreeDigest(root) {
-  const hash = createHash("sha256");
-  updateDigestField(hash, "filegrc-data-tree-v1");
-  const visit = async (directory, prefix = "") => {
-    const entries = await readdir(directory, { withFileTypes: true });
-    entries.sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
-      const path = join(directory, entry.name);
-      if (entry.isDirectory()) {
-        updateDigestField(hash, "directory");
-        updateDigestField(hash, relativePath);
-        await visit(path, relativePath);
-      } else if (entry.isFile()) {
-        const fileHash = createHash("sha256");
-        for await (const chunk of createReadStream(path)) fileHash.update(chunk);
-        updateDigestField(hash, "file");
-        updateDigestField(hash, relativePath);
-        updateDigestField(hash, fileHash.digest("hex"));
-      } else if (entry.isSymbolicLink()) {
-        updateDigestField(hash, "symlink");
-        updateDigestField(hash, relativePath);
-        updateDigestField(hash, await readlink(path));
-      } else {
-        updateDigestField(hash, "other");
-        updateDigestField(hash, relativePath);
+  return measureTiming("packet-data-hash", async () => {
+    const hash = createHash("sha256");
+    updateDigestField(hash, "filegrc-data-tree-v1");
+    const visit = async (directory, prefix = "") => {
+      const entries = await readdir(directory, { withFileTypes: true });
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const entry of entries) {
+        const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+          updateDigestField(hash, "directory");
+          updateDigestField(hash, relativePath);
+          await visit(path, relativePath);
+        } else if (entry.isFile()) {
+          const fileHash = createHash("sha256");
+          for await (const chunk of createReadStream(path)) fileHash.update(chunk);
+          updateDigestField(hash, "file");
+          updateDigestField(hash, relativePath);
+          updateDigestField(hash, fileHash.digest("hex"));
+        } else if (entry.isSymbolicLink()) {
+          updateDigestField(hash, "symlink");
+          updateDigestField(hash, relativePath);
+          updateDigestField(hash, await readlink(path));
+        } else {
+          updateDigestField(hash, "other");
+          updateDigestField(hash, relativePath);
+        }
       }
-    }
-  };
-  await visit(resolveDataPath(root, "."));
-  return `sha256:${hash.digest("hex")}`;
+    };
+    await visit(resolveDataPath(root, "."));
+    return `sha256:${hash.digest("hex")}`;
+  });
 }
 
 function updateDigestField(hash, value) {
@@ -993,7 +1126,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))) {
@@ -1031,7 +1164,7 @@ function packetGaps({
       }
     }
     if (controlNeedsExternalEvidence(control, model) && !coverage.evidenceIds.length) {
-      gaps.push(gap("error", "control-missing-external-evidence", `${coverage.code || coverage.title} relies on an external source but has no linked ${String(model.modelVersion) === "4" ? "Evidence Artifact" : "External Evidence"} in the packet.`, coverage.id));
+      gaps.push(gap("error", "control-missing-external-evidence", `${coverage.code || coverage.title} relies on an external source but has no linked ${modelSupports(model, "evidence-artifacts") ? "Evidence Artifact" : "External Evidence"} in the packet.`, coverage.id));
     } else if (!controlNeedsExternalEvidence(control, model) && !coverage.operatingRecordIds.length) {
       gaps.push(gap("error", "control-missing-filegrc-evidence", `${coverage.code || coverage.title} has no dated filegrc operating record in the packet.`, coverage.id));
     }
@@ -1089,7 +1222,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 +1253,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"
@@ -1247,7 +1380,7 @@ function packetGaps({
         }
       }
     } else if (["population-export", "system-export", "configuration-export"].includes(item.artifactKind)) {
-      gaps.push(gap("error", "evidence-source-system-unrecorded", `${item.title} is a source export but does not link the cataloged ${String(model.modelVersion) === "4" ? "source Component" : "system of record"}.`, item.id));
+      gaps.push(gap("error", "evidence-source-system-unrecorded", `${item.title} is a source export but does not link the cataloged ${modelSupports(model, "component-sources") ? "source Component" : "system of record"}.`, item.id));
     }
     if (item.externalReference && !item.filePaths.length) {
       gaps.push(gap("warning", "external-only-evidence", `${item.title} relies on an external reference and is not self-contained in the packet.`, item.id));
@@ -1302,7 +1435,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 (modelSupports(model, "program-scope") && 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 +1458,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 = modelSupports(model, "program-scope")
+    ? missingSoc2References(descriptionRequirements, REQUIRED_SOC2_DESCRIPTION_REFERENCES)
+    : [];
+  const securityRequirements = frameworkRequirements.filter(isSecurityRequirement);
+  const missingRequiredSecurityReferences = modelSupports(model, "program-scope")
+    ? missingSoc2References(securityRequirements, REQUIRED_SOC2_SECURITY_REFERENCES)
+    : [];
+  const missingSelectedSecurityReferences = modelSupports(model, "program-scope")
+    ? 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 (modelSupports(model, "program-scope") && !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 (modelSupports(model, "program-scope")) {
+    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 +1606,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 (modelSupports(model, "program-scope") && ["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 +1666,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 (!modelSupports(model, "program-scope")) 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);
@@ -1619,7 +1900,7 @@ function recordSummary(record) {
 }
 
 function packetMarkdown(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   const readiness = packet.readiness.status === "delivery-ready"
     ? "filegrc management checks passed. The engagement team still determines whether the evidence is sufficient and appropriate."
     : `${packet.readiness.errors} errors and ${packet.readiness.warnings} warnings require review. This is a draft packet.`;
@@ -1646,6 +1927,9 @@ function packetMarkdown(packet) {
     `- ${packet.summary.eventRuns} event runs`,
     `- ${packet.summary.evidence} ${v4 ? "Evidence Artifact" : "External Evidence"} records`,
     `- ${packet.summary.populations} reconciled or planned populations`,
+    ...(modelSupports(packet.dataModelVersion, "governed-document-activation")
+      ? [`- ${packet.summary.documents} governed engagement Documents with approval and activation history`]
+      : []),
     `- ${packet.summary.policies} policies`,
     `- ${packet.summary.controls} controls`,
     `- ${packet.summary.requirements} criteria`,
@@ -1653,7 +1937,7 @@ function packetMarkdown(packet) {
     `- ${v4 ? packet.summary.sourceComponents : packet.summary.sourceSystems} cataloged source ${v4 ? "Components" : "Systems"}`,
     "",
     v4
-      ? "Open `index.html` for the auditor-oriented index. `control-matrix.csv` cross-references criteria, Controls, filegrc Evidence, Evidence Artifacts, and tests. `source-component-index.csv` identifies the Components used to produce Evidence. `evidence-artifact-index.csv` lists material that must be delivered or accessed outside this packet. For Type 2, `population-index.csv` records management's population reconciliation and fixed source exports. FileGRC records, governed Markdown, fixed attachments, and committed historical versions are included in their respective directories."
+      ? `Open \`index.html\` for the auditor-oriented index. \`control-matrix.csv\` cross-references criteria, Controls, filegrc Evidence, Evidence Artifacts, and tests.${modelSupports(packet.dataModelVersion, "governed-document-activation") ? " `document-lifecycle-index.csv` lists each engagement Document's approval and activation facts and exact Markdown revisions." : ""} \`source-component-index.csv\` identifies the Components used to produce Evidence. \`evidence-artifact-index.csv\` lists material that must be delivered or accessed outside this packet. For Type 2, \`population-index.csv\` records management's population reconciliation and fixed source exports. FileGRC records, governed Markdown, fixed attachments, and committed historical versions are included in their respective directories.`
       : "Open `index.html` for the auditor-oriented index. `control-matrix.csv` cross-references criteria, controls, filegrc Evidence, External Evidence, and tests. `source-system-index.csv` identifies the systems of record used to produce External Evidence. `external-evidence-index.csv` lists material that must be delivered or accessed outside this packet. For Type 2, `population-index.csv` records management's population reconciliation and fixed source exports. filegrc records, governed Markdown, fixed attachments, and committed historical versions are included in their respective directories.",
     "",
     "After transfer, enter the packet directory and run `shasum -a 256 -c SHA256SUMS` or `sha256sum -c SHA256SUMS`. The checksum file covers every other packet file.",
@@ -1663,7 +1947,7 @@ function packetMarkdown(packet) {
 }
 
 function packetHtml(packet) {
-  const v4 = packet.dataModelVersion === "4";
+  const v4 = modelSupports(packet.dataModelVersion, "component-sources");
   const artifactLabel = v4 ? "Evidence Artifact" : "External Evidence";
   const section = (title, body) => `<section><h2>${escapeHtml(title)}</h2>${body}</section>`;
   const links = (items) => items.length
@@ -1709,13 +1993,16 @@ function packetHtml(packet) {
   const controlCoverage = packet.controlCoverage.length
     ? `<p><a href="control-matrix.csv">Download control matrix CSV</a></p><table><thead><tr><th>Control</th><th>Status and scope</th><th>Criteria</th><th>filegrc Evidence</th><th>${artifactLabel}</th><th>Tests</th></tr></thead><tbody>${packet.controlCoverage.map((control) => `<tr><td><a href="records/control/${encodeURIComponent(control.id)}.json">${escapeHtml(control.code || control.id)}</a><small>${escapeHtml(control.title)}</small></td><td>${escapeHtml(control.status)}<small>${control.systemIds.map(escapeHtml).join(", ") || "No system scope"}</small></td><td>${control.requirementIds.map(escapeHtml).join("<br>") || "None"}</td><td>${control.operatingRecordIds.length}</td><td>${control.evidenceIds.length}</td><td>${control.tests.length}</td></tr>`).join("")}</tbody></table>`
     : "<p>No controls were selected.</p>";
+  const documentLifecycles = packet.documentLifecycles?.length
+    ? `<p><a href="document-lifecycle-index.csv">Download Document lifecycle index CSV</a></p><table><thead><tr><th>Document</th><th>Audit role</th><th>Approval</th><th>Activation</th></tr></thead><tbody>${packet.documentLifecycles.map((document) => `<tr><td><a href="records/document/${encodeURIComponent(document.id)}.json">${escapeHtml(document.title)}</a><small>${escapeHtml(document.status)} · ${escapeHtml(document.workflowScope || "scope not recorded")}</small></td><td>${document.roles.map(escapeHtml).join("<br>")}</td><td>${escapeHtml(document.approvedOn || "Not approved")}<small>${document.approvers.map(escapeHtml).join(", ") || "No approver recorded"}</small></td><td>${escapeHtml(document.activatedOn || "Not activated")}<small>${document.activators.map(escapeHtml).join(", ") || "No activator recorded"}${document.effectiveOn ? ` · effective ${escapeHtml(document.effectiveOn)}` : ""}</small></td></tr>`).join("")}</tbody></table>`
+    : "<p>No governed engagement Documents were linked to this audit.</p>";
   const readinessLabel = packet.readiness.status === "delivery-ready" ? "filegrc management checks passed" : "Draft, do not deliver";
   const packetDate = packet.period.basis === "as-of"
     ? `As of ${escapeHtml(packet.period.start)}`
     : `${escapeHtml(packet.period.start)} through ${escapeHtml(packet.period.end)}`;
   return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Evidence packet</title><style>
 body{font:14px/1.5 system-ui,sans-serif;color:#161825;max-width:1120px;margin:auto;padding:40px;background:#f7f8fc}header,section{background:#fff;border:1px solid #dfe3ef;border-radius:10px;padding:24px;margin:14px 0}h1,h2{margin-top:0}h1{font-size:26px}h2{font-size:17px}ul{padding-left:20px}li{margin:8px 0}small{display:block;color:#656c7e}.attachment{margin-right:10px;font-size:12px}.error{color:#8a2f28}.warning{color:#76500d}.readiness{display:inline-block;padding:5px 9px;border-radius:999px;background:#f7e4e2;color:#7a2520;font-weight:700}.readiness.ready{background:#e2f1e8;color:#245d3b}table{width:100%;border-collapse:collapse}th,td{padding:9px;border:1px solid #dfe3ef;text-align:left;vertical-align:top}code{overflow-wrap:anywhere}dl{display:grid;grid-template-columns:max-content 1fr;gap:8px 16px}dt{font-weight:700}dd{margin:0}
-</style></head><body><header><p>SOC 2 evidence packet</p><span class="readiness ${packet.readiness.status === "delivery-ready" ? "ready" : ""}">${escapeHtml(readinessLabel)}</span><h1>${packetDate}</h1><p>${escapeHtml(packet.workspace.organizationName)} · revision <code>${escapeHtml(packet.revision.commit || "uncommitted")}</code></p></header>${section("Engagement scope", engagement)}${section("Review status", gaps)}${section("Control coverage", controlCoverage)}${section(v4 ? "Source Components" : "Systems of record", sourceSystems)}${packet.period.basis === "period" ? section("Management population reconciliation", populations) : ""}${packet.period.basis === "period" ? section("Recurring obligation coverage", obligations) : ""}${packet.period.basis === "period" ? section("Event workflow coverage", eventRuns) : ""}${section("Policies", links(packet.policies))}${section("filegrc Evidence", filegrcRecords)}${section(v4 ? "Evidence Artifacts" : "External Evidence", evidence)}${section("Integrity and history", "<p>Verify all transferred files with <code>SHA256SUMS</code>. Committed prior versions are under <code>history/</code> with an index that records their source paths and Git metadata.</p>")}</body></html>`;
+</style></head><body><header><p>SOC 2 evidence packet</p><span class="readiness ${packet.readiness.status === "delivery-ready" ? "ready" : ""}">${escapeHtml(readinessLabel)}</span><h1>${packetDate}</h1><p>${escapeHtml(packet.workspace.organizationName)} · revision <code>${escapeHtml(packet.revision.commit || "uncommitted")}</code></p></header>${section("Engagement scope", engagement)}${section("Review status", gaps)}${modelSupports(packet.dataModelVersion, "governed-document-activation") ? section("Document lifecycle", documentLifecycles) : ""}${section("Control coverage", controlCoverage)}${section(v4 ? "Source Components" : "Systems of record", sourceSystems)}${packet.period.basis === "period" ? section("Management population reconciliation", populations) : ""}${packet.period.basis === "period" ? section("Recurring obligation coverage", obligations) : ""}${packet.period.basis === "period" ? section("Event workflow coverage", eventRuns) : ""}${section("Policies", links(packet.policies))}${section("filegrc Evidence", filegrcRecords)}${section(v4 ? "Evidence Artifacts" : "External Evidence", evidence)}${section("Integrity and history", "<p>Verify all transferred files with <code>SHA256SUMS</code>. Committed prior versions are under <code>history/</code> with an index that records their source paths and Git metadata.</p>")}</body></html>`;
 }
 
 async function writePacketFile(output, relativePath, source, files) {