filegrc 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filegrc",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,9 @@
     "src"
   ],
   "scripts": {
-    "test": "node --test --test-concurrency=4"
+    "test": "node ../../scripts/run-filegrc-tests.mjs",
+    "test:fast": "node ../../scripts/run-filegrc-tests.mjs --fast",
+    "test:full": "npm test"
   },
   "engines": {
     "node": ">=20"

package/src/agent.js

@@ -1,3 +1,4 @@
+import { modelSupports } from "../model/index.js";
 import { createResourceId } from "./id.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { RESOURCE_INSTRUCTIONS, resourceProgramContext } from "./program-path.js";
@@ -116,7 +117,7 @@ export function buildAgentGuide(loaded, type, options = {}) {
       recommendedMarkdown.length
         ? "Keep model fields in JSON and use the recommended Markdown companion for the detailed work, decisions, results, exceptions, and follow-up that apply to this record."
         : "Keep the current facts and lifecycle state in JSON. Add optional Record Markdown only when the model fields cannot explain the record clearly.",
-      ...(type === "program" && String(loaded.model.modelVersion) === "4"
+      ...(type === "program" && modelSupports(loaded.model, "program-scope")
         ? ["Review Requirement applicability with npx filegrc review-applicability --type requirement --scaffold, then preview and apply the reviewed decisions as one validated batch."]
         : []),
       "Run npx filegrc validate, review the full Git diff, and commit the JSON, Markdown, and attachments together with a message that explains why the record changed."
@@ -125,7 +126,7 @@ export function buildAgentGuide(loaded, type, options = {}) {
       "Required and status-dependent fields are complete, and the lifecycle status matches the facts.",
       "Every relationship resolves to the intended existing record.",
       "Dates describe the business event in the workspace time zone, not the file edit time.",
-      ...(type === "program" && String(loaded.model.modelVersion) === "4"
+      ...(type === "program" && modelSupports(loaded.model, "program-scope")
         ? ["Every selected Requirement has an applicable or not-applicable decision reviewed against the current Program scope."]
         : []),
       ...(recommendedMarkdown.length
@@ -217,7 +218,7 @@ function applyModelScaffoldDefaults(record, loaded, options = {}) {
     }[program?.assuranceGoal];
     if (kind) record.auditKind = kind;
     for (const field of ["frameworkIds", "systemIds", "requirementIds", "controlIds"]) {
-      if (field === "requirementIds" && String(loaded.model.modelVersion) === "4") {
+      if (field === "requirementIds" && modelSupports(loaded.model, "program-scope")) {
         record[field] = (program.requirementApplicability || []).filter(({ decision }) => decision === "applicable").map(({ requirementId }) => requirementId);
       } else if (program?.[field]?.length) record[field] = [...program[field]];
     }

package/src/audit-preparation.js

@@ -1,5 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import { modelSupports } from "../model/index.js";
+import { openPlaceholderCount, substantiveMarkdown } from "./content-readiness.js";
 import {
   coverageContains,
   coverageEnd,
@@ -15,6 +17,7 @@ import { currentPartyPeople, partiesIndependent } from "./parties.js";
 import { resolveDataPath } from "./paths.js";
 import { assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
+import { contentRevisionBindingsMatch, governedDocumentIsOperating } from "./program-lifecycle.js";
 import {
   auditorWasEngaged,
   missingSoc2References,
@@ -25,6 +28,7 @@ import {
   signatoryAppointmentIssue,
   subsequentEventsReviewIssue
 } from "./soc2.js";
+import { currentCalendarDate } from "./time.js";
 import { loadWorkspace } from "./workspace.js";
 
 const NON_EVIDENCE_RECORD_TYPES = new Set([
@@ -65,9 +69,13 @@ export async function assessAuditPreparation(input, options = {}) {
   if (options.auditId && !audit) throw new Error(`Audit "${options.auditId}" was not found.`);
 
   const programReadiness = options.programReadiness || await assessProgramReadiness(loaded, {
+    asOf: options.asOf,
     generatedAt: options.generatedAt,
     programId: audit?.programId
   });
+  const documentActivations = audit && modelSupports(loaded.model, "governed-document-activation")
+    ? await auditDocumentActivationAssessments(loaded, audit, byId, programReadiness.asOf)
+    : [];
   const stages = [
     programFoundationStage(programReadiness, loaded.workspace),
     engagementStage(audit, byId, programReadiness),
@@ -75,7 +83,7 @@ export async function assessAuditPreparation(input, options = {}) {
   ];
   const fieldworkSections = audit
     ? [
-        await documentsStage(loaded, audit, byId),
+        await documentsStage(loaded, audit, byId, programReadiness.asOf),
         evidenceStage(audit, records, byId, loaded.model),
         populationsStage(audit, records, byId, loaded.model)
       ]
@@ -107,10 +115,23 @@ export async function assessAuditPreparation(input, options = {}) {
       && coverageStart(audit.coverage)
       && coverageEnd(audit.coverage)
       && initializationNeeded(audit, records, loaded.model)),
+    documentActivations,
     stages
   };
 }
 
+export async function assessAuditDocumentActivations(input = process.cwd(), options = {}) {
+  const loaded = input?.resources && input?.model && input?.entries
+    ? input
+    : await loadWorkspace(input);
+  if (!modelSupports(loaded.model, "governed-document-activation")) return [];
+  const audit = loaded.resources.find((record) => record.type === "audit" && record.id === options.auditId);
+  if (!audit) throw new Error(`Audit "${options.auditId || ""}" was not found.`);
+  const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+  const asOf = options.asOf || currentCalendarDate(loaded.workspace.timezone);
+  return auditDocumentActivationAssessments(loaded, audit, byId, asOf);
+}
+
 export async function prepareAuditWorkspace(input, options = {}) {
   const loaded = await loadWorkspace(input);
   const audit = loaded.resources.find((record) => record.type === "audit" && record.id === options.auditId);
@@ -168,7 +189,7 @@ export async function prepareAuditWorkspace(input, options = {}) {
   const selectedControls = (audit.controlIds || [])
     .map((id) => loaded.resources.find((record) => record.id === id))
     .filter(Boolean);
-  const v4 = String(loaded.model.modelVersion) === "4";
+  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 || [] : [])
     .filter((template) => !existingKinds.has(template.kind))
@@ -269,7 +290,7 @@ function scopeStage(loaded, audit, records, byId, programReadiness) {
     ));
   }
 
-  const v4 = String(programReadiness.dataModelVersion) === "4";
+  const v4 = modelSupports(programReadiness.dataModelVersion, "program-scope");
   const engagementStart = coverageStart(audit.coverage);
   const engagementEnd = coverageEnd(audit.coverage);
   const scopeRevision = assessScopeRevision(loaded, audit, v4);
@@ -744,9 +765,12 @@ function engagementStage(audit, byId, programReadiness) {
   const engagementTermsComplete = Boolean(
     engagementTerms?.type === "document"
     && engagementTerms.documentKind === "soc2-engagement-terms"
-    && engagementTerms.status === "active"
+    && governedDocumentIsOperating(
+      engagementTerms,
+      programReadiness.asOf,
+      { modelVersion: programReadiness.dataModelVersion }
+    )
     && engagementTerms.approvedOn
-    && engagementTerms.effectiveOn
   );
   const acknowledgementPeople = (audit.managementAcknowledgedByIds || [])
     .map((id) => byId.get(id))
@@ -805,7 +829,7 @@ function engagementStage(audit, byId, programReadiness) {
       }
     )
   ];
-  if (["3", "4"].includes(String(programReadiness.dataModelVersion))) {
+  if (modelSupports(programReadiness.dataModelVersion, "guided-workflow")) {
     items.push(
       item(
         "engagement-terms",
@@ -853,51 +877,160 @@ function fieldworkStage(audit, sections) {
   );
 }
 
-async function documentsStage(loaded, audit, byId) {
-  const definitions = applicableManagementDocuments(audit, loaded.model.auditReadiness || {});
-  const items = [];
-  for (const definition of definitions) {
-    const document = audit?.[definition.field] ? byId.get(audit[definition.field]) : null;
-    const source = document ? await primaryMarkdown(loaded, document) : "";
-    const contentIssues = managementDocumentContentIssues(source, definition, audit);
-    const engagementEnd = coverageEnd(audit?.coverage);
-    if (document?.approvedOn && engagementEnd && document.approvedOn < engagementEnd) {
-      contentIssues.push(`Approve the final document on or after the engagement ${audit.auditKind === "soc-2-type-1" ? "date" : "period end"}.`);
+async function auditDocumentActivationAssessments(loaded, audit, byId, asOf) {
+  const links = new Map();
+  const addLink = (documentId, role, definition = null) => {
+    if (!documentId) return;
+    const current = links.get(documentId) || { documentId, roles: [], definitions: [] };
+    current.roles.push(role);
+    if (definition) current.definitions.push(definition);
+    links.set(documentId, current);
+  };
+  addLink(audit.engagementTermsDocumentId, "engagement-terms");
+  for (const definition of applicableManagementDocuments(audit, loaded.model.auditReadiness || {})) {
+    addLink(audit[definition.field], definition.field, definition);
+  }
+  for (const documentId of audit.supplementalDocumentIds || []) addLink(documentId, "supplemental");
+
+  const assessments = [];
+  for (const link of links.values()) {
+    const document = byId.get(link.documentId);
+    if (document?.type !== "document") continue;
+    if (link.roles.every((role) => role === "supplemental") && document.workflowScope !== "engagement") continue;
+    const source = await primaryMarkdown(loaded, document);
+    const issues = [];
+    if (document.workflowScope !== "engagement") issues.push("Set workflowScope to engagement.");
+    if (document.template === true) issues.push("Replace the starter template with the completed engagement Document.");
+    if (!substantiveMarkdown(source)) issues.push("Complete the Document Markdown.");
+    const placeholders = openPlaceholderCount(source);
+    if (placeholders) issues.push(`Resolve ${placeholders} open ${placeholders === 1 ? "placeholder" : "placeholders"}.`);
+    if (link.roles.includes("engagement-terms") && document.documentKind !== "soc2-engagement-terms") {
+      issues.push("Use documentKind soc2-engagement-terms for the accepted engagement terms.");
     }
-    if (definition.kind === "soc2-period-completeness" && document?.approvedOn && audit) {
-      const latestReconciliation = loaded.resources
-        .filter((record) => record.type === "audit-population" && record.auditId === audit.id)
-        .map((record) => record.reconciledOn)
-        .filter(Boolean)
-        .sort()
-        .at(-1);
-      if (latestReconciliation && document.approvedOn < latestReconciliation) {
-        contentIssues.push("Approve the period completeness statement after the last population reconciliation.");
-      }
+    for (const definition of link.definitions) {
+      issues.push(...await managementDocumentLifecycleIssues(loaded, audit, definition, document, source, asOf, byId));
     }
-    if (definition.kind === "soc2-management-representation" && document) {
-      const signedEvidence = (document.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 (!signedEvidence) contentIssues.push("Link verified signed-record Evidence with subtype signed-management-representation and a fixed-format copy of the signed letter.");
+    const approvalComplete = Boolean(
+      ["approved", "active"].includes(document.status)
+      && document.approvedOn
+      && document.approvedContentRevisions
+      && (document.activationBasis === "legacy-v4"
+        ? (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.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}.`);
+      if (!(document.activatedByIds || []).length) issues.push("Name the active Person who performed activation.");
       else {
-        const dateIssue = signedRepresentationDateIssue(signedEvidence, audit, loaded.model.modelVersion);
-        if (dateIssue) contentIssues.push(dateIssue);
+        const invalidActorIds = document.activatedByIds.filter((id) => !personWasActiveOn(byId.get(id), document.activatedOn));
+        if (invalidActorIds.length) issues.push(`Activation actors were not active on ${document.activatedOn}: ${invalidActorIds.join(", ")}.`);
       }
+      if (!document.activatedContentRevisions) issues.push("Bind activation to the exact Document Markdown revision.");
+      else if (!contentRevisionBindingsMatch(document.approvedContentRevisions, document.activatedContentRevisions)) {
+        issues.push("The activated revision must match the unchanged approved revision.");
+      }
+      if (!document.effectiveOn) issues.push("Record the effective date.");
+      else if (document.effectiveOn > asOf) issues.push(`The Document does not become effective until ${document.effectiveOn}.`);
+    }
+    const operating = governedDocumentIsOperating(document, asOf, loaded.model) && issues.length === 0;
+    const state = operating
+      ? "active-and-operating"
+      : document.status === "active"
+        ? "active-with-gaps"
+        : document.status === "approved" && issues.length === 0
+          ? "ready-to-activate"
+          : document.status === "approved"
+            ? "approved-not-ready"
+            : "approval-pending";
+    assessments.push({
+      auditId: audit.id,
+      documentId: document.id,
+      title: document.title,
+      roles: [...new Set(link.roles)],
+      state,
+      label: auditDocumentActivationLabel(state),
+      issues: [...new Set(issues)],
+      approvedOn: document.approvedOn || null,
+      activatedOn: document.activatedOn || null,
+      activatedByIds: document.activatedByIds || [],
+      effectiveOn: document.effectiveOn || null,
+      approvalRevisionBound: Boolean(document.approvedContentRevisions),
+      activationRevisionBound: Boolean(document.activatedContentRevisions),
+      gapCount: [...new Set(issues)].length
+    });
+  }
+  return assessments.sort((left, right) => left.title.localeCompare(right.title));
+}
+
+function auditDocumentActivationLabel(state) {
+  return ({
+    "approval-pending": "Approval pending in Step 5",
+    "approved-not-ready": "Approved, engagement facts incomplete",
+    "ready-to-activate": "Ready to activate in Step 5",
+    "active-with-gaps": "Active with lifecycle or engagement gaps",
+    "active-and-operating": "Active and ready for the engagement"
+  })[state] || state;
+}
+
+async function managementDocumentLifecycleIssues(loaded, audit, definition, document, source, asOf, byId) {
+  const issues = managementDocumentContentIssues(source, definition, audit);
+  if (document.documentKind !== definition.kind) {
+    issues.push(`Use documentKind ${definition.kind} for this Audit field.`);
+  }
+  const engagementEnd = coverageEnd(audit?.coverage);
+  if (document.approvedOn && engagementEnd && document.approvedOn < engagementEnd) {
+    issues.push(`Approve the final document on or after the engagement ${audit.auditKind === "soc-2-type-1" ? "date" : "period end"}.`);
+  }
+  if (definition.kind === "soc2-period-completeness" && document.approvedOn) {
+    const latestReconciliation = loaded.resources
+      .filter((record) => record.type === "audit-population" && record.auditId === audit.id)
+      .map((record) => record.reconciledOn)
+      .filter(Boolean)
+      .sort()
+      .at(-1);
+    if (latestReconciliation && document.approvedOn < latestReconciliation) {
+      issues.push("Approve the period completeness statement after the last population reconciliation.");
     }
+  }
+  if (definition.kind === "soc2-management-representation") {
+    const signedEvidence = (document.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 (!signedEvidence) issues.push("Link verified signed-record Evidence with subtype signed-management-representation and a fixed-format copy of the signed letter.");
+    else {
+      const dateIssue = signedRepresentationDateIssue(signedEvidence, audit, loaded.model.modelVersion);
+      if (dateIssue) issues.push(dateIssue);
+    }
+  }
+  return issues;
+}
+
+async function documentsStage(loaded, audit, byId, asOf) {
+  const definitions = applicableManagementDocuments(audit, loaded.model.auditReadiness || {});
+  const items = [];
+  for (const definition of definitions) {
+    const document = audit?.[definition.field] ? byId.get(audit[definition.field]) : null;
+    const source = document ? await primaryMarkdown(loaded, document) : "";
+    const contentIssues = document
+      ? await managementDocumentLifecycleIssues(loaded, audit, definition, document, source, asOf, byId)
+      : [];
     const complete = Boolean(
       document
       && document.type === "document"
       && document.template !== true
-      && document.status === "active"
+      && governedDocumentIsOperating(document, asOf, loaded.model)
       && document.approvedOn
-      && document.effectiveOn
       && (document.ownerIds || []).length
       && (document.approverIds || []).length
       && partiesIndependent(document.ownerIds, document.approverIds, byId)
@@ -912,7 +1045,11 @@ async function documentsStage(loaded, audit, byId) {
       complete ? "complete" : representationLater ? "later" : "action",
       definition.title,
       complete
-        ? "Linked Markdown is complete, active, approved, and effective."
+        ? 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."
+          : 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."
         : document
           ? `${definition.timing} ${contentIssues[0] || "Complete and approve the engagement-specific document."}`
           : `Link the starter ${definition.title.toLowerCase()} to this audit. ${definition.timing}`,
@@ -925,7 +1062,7 @@ async function documentsStage(loaded, audit, byId) {
 export function signedRepresentationDateIssue(evidence, audit, modelVersion) {
   const engagementEnd = coverageEnd(audit?.coverage);
   const timingMessage = `The signed representation must be dated on or after the engagement ${audit?.auditKind === "soc-2-type-1" ? "date" : "period end"}.`;
-  if (String(modelVersion) !== "4") {
+  if (!modelSupports(modelVersion, "program-scope")) {
     return !evidence?.collectedOn || (engagementEnd && evidence.collectedOn < engagementEnd)
       ? timingMessage
       : null;
@@ -999,7 +1136,7 @@ function evidenceStage(audit, records, byId, model) {
       externalEvidence[0] || { type: "evidence" }
     )
   ];
-  const v4 = String(model.modelVersion) === "4";
+  const v4 = modelSupports(model, "program-scope");
   const systems = records.filter((record) => record.type === (v4 ? "component" : "system") && record.status === "active");
   const sourceId = (record) => v4 ? record.sourceComponentId : record.sourceSystemId;
   for (const source of model.evidenceSourceFamilies || []) {
@@ -1103,7 +1240,7 @@ function auditorStage(audit, byId, modelVersion) {
   const signatoryStatus = !audit || ["planned", "in-progress", "fieldwork"].includes(audit.status)
     ? "later"
     : signatoryIssue ? "action" : "complete";
-  const managementItems = String(modelVersion) === "4" ? [
+  const managementItems = modelSupports(modelVersion, "program-scope") ? [
     item(
       "subsequent-events",
       subsequentEventsStatus,

package/src/audit-transition.js

@@ -1,11 +1,12 @@
+import { modelSupports } from "../model/index.js";
 import { createResource } from "./files.js";
 import { createResourceId } from "./id.js";
 import { loadWorkspace } from "./workspace.js";
 
 export async function planNextAuditCycle(input = process.cwd(), options = {}) {
   const loaded = await loadWorkspace(input);
-  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
-    throw new Error("Audit-cycle carry-forward requires a model v3 or v4 workspace.");
+  if (!modelSupports(loaded.model, "guided-workflow")) {
+    throw new Error("Audit-cycle carry-forward requires a model v3 or newer workspace.");
   }
   const prior = loaded.resources.find((record) => (
     record.type === "audit" && record.id === options.priorAuditId

package/src/batch-review.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import { modelSupports } from "../model/index.js";
 import { applyResourceBatch } from "./files.js";
 import { getWorkspaceRevisionSnapshot } from "./git.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
@@ -20,8 +21,8 @@ const REVIEWABLE_TYPES = new Set([
 export async function scaffoldApplicabilityReview(input = process.cwd(), options = {}) {
   const context = await applicabilityReviewContext(input);
   const { loaded } = context;
-  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
-    throw new Error("Batch applicability review requires a model v3 or v4 workspace.");
+  if (!modelSupports(loaded.model, "guided-workflow")) {
+    throw new Error("Batch applicability review requires a model v3 or newer workspace.");
   }
   const requestedType = options.type ? String(options.type) : null;
   if (requestedType && !REVIEWABLE_TYPES.has(requestedType)) {
@@ -34,7 +35,7 @@ export async function scaffoldApplicabilityReview(input = process.cwd(), options
   const records = loaded.resources.filter((record) => (
     REVIEWABLE_TYPES.has(record.type)
     && (!requestedType || record.type === requestedType)
-    && (record.type === "requirement" && String(loaded.model.modelVersion) === "4"
+    && (record.type === "requirement" && modelSupports(loaded.model, "program-scope")
       ? !reviewedRequirementIds.has(record.id)
       : !record.applicabilityReview)
     && !["retired", "superseded"].includes(record.status)
@@ -64,8 +65,8 @@ export async function planApplicabilityReview(input = process.cwd(), options = {
 
 function planApplicabilityReviewWithContext(context, options) {
   const { basis, loaded } = context;
-  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
-    throw new Error("Batch applicability review requires a model v3 or v4 workspace.");
+  if (!modelSupports(loaded.model, "guided-workflow")) {
+    throw new Error("Batch applicability review requires a model v3 or newer workspace.");
   }
   if (!Array.isArray(options.decisions) || !options.decisions.length) {
     throw new Error("Applicability review needs at least one decision.");
@@ -112,7 +113,7 @@ function planApplicabilityReviewWithContext(context, options) {
       if (!["applicable", "not-applicable"].includes(result)) {
         throw new Error(`Requirement "${record.id}" must be applicable or not-applicable.`);
       }
-      if (String(loaded.model.modelVersion) === "4") {
+      if (modelSupports(loaded.model, "program-scope")) {
         v4RequirementDecisions.push({
           requirementId: record.id,
           decision: result,

package/src/cli.js

@@ -1,7 +1,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { loadModel } from "../model/index.js";
+import { ACTIVE_MODEL_VERSION, loadModel, SUPPORTED_MODEL_VERSIONS } from "../model/index.js";
 import { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldResourceMutation } from "./agent.js";
 import { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 import { createNextAuditCycle, planNextAuditCycle } from "./audit-transition.js";
@@ -16,6 +16,7 @@ import {
   scaffoldCollectionReview
 } from "./collection-review.js";
 import { buildWorkspace } from "./build.js";
+import { activateDocuments, planDocumentActivation, scaffoldDocumentActivation } from "./document-activation.js";
 import { generateEvidencePacket, prepareEvidencePacket } from "./evidence-packet.js";
 import {
   addEvidenceAttachment,
@@ -183,15 +184,16 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "migrate") {
     const targetModel = String(flags["to-model"] || "");
-    if (!["2", "3", "4"].includes(targetModel)) throw new Error("Pass --to-model 2, --to-model 3, or --to-model 4.");
-    const systemDecisions = flags.decisions
+    if (!["2", "3", "4", "5"].includes(targetModel)) throw new Error("Pass --to-model 2, --to-model 3, --to-model 4, or --to-model 5.");
+    const migrationDecisions = flags.decisions
       ? JSON.parse(await readFile(resolve(String(flags.decisions)), "utf8"))
       : undefined;
     const options = {
       jobTitle: flags["job-title"],
       startsOn: flags["starts-on"],
       targetModelVersion: targetModel,
-      systemDecisions: systemDecisions?.systemDecisions || systemDecisions
+      systemDecisions: migrationDecisions?.systemDecisions || (targetModel === "4" ? migrationDecisions : undefined),
+      documentScopes: migrationDecisions?.documentScopes || (targetModel === "5" ? migrationDecisions : undefined)
     };
     const plan = await planModelMigration(root, options);
     if (!flags.preview && plan.sourceModelVersion !== plan.targetModelVersion && !flags.yes) {
@@ -617,6 +619,31 @@ export async function runCli(argv = process.argv.slice(2)) {
     else console.log(`Activated ${result.policyIds.length} Policies effective ${result.effectiveOn}.`);
     return result;
   }
+  if (command === "activate-documents") {
+    if (flags.scaffold) {
+      const result = await scaffoldDocumentActivation(root, { programId: flags.program, auditId: flags.audit });
+      console.log(JSON.stringify(result, null, 2));
+      return result;
+    }
+    const payload = await readSetupPayload(positionals[0]);
+    const options = {
+      ...payload,
+      documentIds: flags.document ? String(flags.document).split(",").filter(Boolean) : payload.documentIds,
+      activatedByIds: flags["activated-by"] ? String(flags["activated-by"]).split(",").filter(Boolean) : payload.activatedByIds,
+      activatedOn: flags["activated-on"] || payload.activatedOn,
+      effectiveOn: flags["effective-on"] || payload.effectiveOn,
+      programId: flags.program || payload.programId,
+      auditId: flags.audit || payload.auditId,
+      confirmed: flags.yes === true
+    };
+    const result = flags.preview
+      ? await planDocumentActivation(root, options)
+      : await withWorkflowDelta(root, () => activateDocuments(root, options));
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else if (flags.preview) console.log(`Document activation preview: ${result.documentIds.length} governed Documents effective ${result.effectiveOn}.`);
+    else console.log(`Activated ${result.documentIds.length} governed Documents 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.");
@@ -1055,7 +1082,7 @@ Usage:
   filegrc build [root] [--output .filegrc/site]
   filegrc validate [root] [--json]
   filegrc model [--json|--write-docs|--check-docs]
-  filegrc migrate --to-model <2|3|4> [--preview] [--decisions path] [--job-title text] [--starts-on YYYY-MM-DD] [--yes] [--json]
+  filegrc migrate --to-model <2|3|4|5> [--preview] [--decisions path] [--job-title text] [--starts-on YYYY-MM-DD] [--yes] [--json]
   filegrc describe <resource-type>
   filegrc types [--json]
   filegrc guide [resource-type] [--id resource-id] [--program program-id] [--json]
@@ -1078,6 +1105,7 @@ Usage:
   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 activate-documents [--scaffold | activation.json|-] [--program id | --audit id] [--activated-by person-id] [--activated-on YYYY-MM-DD] [--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]
@@ -1145,19 +1173,20 @@ Options:
   }
   if (command === "migrate") {
     console.log(`Usage:
-  filegrc migrate --to-model <2|3|4> [options]
+  filegrc migrate --to-model <${SUPPORTED_MODEL_VERSIONS.join("|")}> [options]
 
 Upgrade a workspace through an explicit, reviewable model boundary. Model v1
-workspaces migrate to v2 first. Model v2 workspaces migrate to v3, then v4. v4 separates
+workspaces migrate to v2 first. Continue one version at a time through v${ACTIVE_MODEL_VERSION}. v4 separates
 the repository Workspace, management Program, bounded Systems, operational Components,
-specific Assets, Vendors, normalized information, and Evidence Artifacts. v3 migration
+specific Assets, Vendors, normalized information, and Evidence Artifacts. Model v5 separates
+Document approval from activation and records program-versus-engagement scope. v3 migration
 previews may require a decisions JSON file for ambiguous old Systems. v3 still creates planned
 core Appointments, removal of obsolete manual page state, classified review work,
 and dataModelVersion changed last. The command writes no Git commit.
 
 Options:
-  --to-model <version>  Required target model; migrations must run in order through 2, 3, and 4
-  --decisions <path>    v4 JSON object keyed by old System ID with system/component decisions
+  --to-model <version>  Required target model; migrations must run in order through ${SUPPORTED_MODEL_VERSIONS.join(", ")}
+  --decisions <path>    JSON systemDecisions for v4 or documentScopes for ambiguous v5 Documents
   --preview             Show the complete atomic record plan without writing
   --job-title <title>   Actual job title for the former Policy Owner seed person
   --starts-on <date>    Effective date of a new Policy Owner Appointment
@@ -1167,7 +1196,7 @@ Options:
   --help                Show this help
 
 Start with:
-  npx filegrc migrate --to-model 4 --preview --json`);
+  npx filegrc migrate --to-model ${ACTIVE_MODEL_VERSION} --preview --json`);
     return;
   }
   if (command === "program-readiness") {
@@ -1248,6 +1277,30 @@ Options:
   --help                 Show this help`);
     return;
   }
+  if (command === "activate-documents") {
+    console.log(`Usage:
+  filegrc activate-documents --scaffold [--program id | --audit id]
+  filegrc activate-documents <activation.json|-> [--audit id] [--activated-by person-id] [--activated-on YYYY-MM-DD] [--effective-on YYYY-MM-DD] [--preview|--yes] [--json]
+
+Activate required governed plans and schedules in Step 3 after their linked
+Controls are implemented, or activate engagement Documents in Step 5 after
+their audit-specific facts are complete. Approval, activation, and effective
+dates remain separate, and activation binds its own exact Markdown revision.
+
+Options:
+  --scaffold             Print the ready activation payload without writing
+  --program <id>         Program to assess when more than one active Program exists
+  --audit <id>           Audit whose engagement Documents should be activated in Step 5
+  --activated-by <id>    Active Person who performs the activation
+  --activated-on <date>  Actual activation date, which must be today
+  --effective-on <date>  Effective date on or after activation
+  --preview              Validate and show the atomic updates without writing
+  --yes                  Confirm and apply the reviewed activation
+  --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]
@@ -1294,7 +1347,7 @@ function agentOverview(model) {
     build: "filegrc build [root]",
     validate: "filegrc validate [root] --json",
     model: "filegrc model --json",
-    migrate: "filegrc migrate --to-model 4 --preview --json",
+    migrate: "filegrc migrate --to-model 5 --preview --json",
     describe: "filegrc describe <resource-type>",
     types: "filegrc types --json",
     guide: "filegrc guide [resource-type] --json",
@@ -1313,6 +1366,7 @@ function agentOverview(model) {
     reconcile: "filegrc reconcile --preview --json",
     externalReviewerSetup: "filegrc external-reviewer-setup [--scaffold | <reviewer.json|-> --preview] --json",
     policyActivation: "filegrc activate-policies [--scaffold | <activation.json|-> --preview] --json",
+    documentActivation: "filegrc activate-documents [--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",
@@ -1465,6 +1519,7 @@ function buildProgramPathResult(model, readiness, auditReadiness) {
     evidenceReady: readiness.evidenceReady,
     operating: readiness.operating,
     policyActivations: readiness.policyActivations,
+    documentActivations: readiness.documentActivations,
     policyLibraryProposals: readiness.policyLibraryProposals,
     stages
   };
@@ -1668,6 +1723,13 @@ function summarizeProgramReadiness(result) {
       label,
       gapCount
     })),
+    documentActivations: result.documentActivations.map(({ documentId, title, state, label, gapCount }) => ({
+      documentId,
+      title,
+      state,
+      label,
+      gapCount
+    })),
     policyLibraryProposals: result.policyLibraryProposals,
     unresolvedOwnership: {
       count: unresolvedOwnership.length,