filegrc 0.7.0 → 0.8.0

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
@@ -37,6 +38,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 +62,9 @@ export async function planNextAuditCycle(input = process.cwd(), options = {}) {
       "requirementIds",
       "controlIds",
       "complementaryControlIds",
+      "subserviceConclusion",
+      "subserviceConclusionRationale",
+      "subserviceTreatments",
       "subserviceVendorIds",
       "subserviceMethod",
       "auditorVendorId",

package/src/batch-review.js

@@ -1,11 +1,13 @@
 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";
 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";
 
@@ -19,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)) {
@@ -33,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)
@@ -44,11 +46,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 } : {})
+        };
+      })
   };
 }
 
@@ -59,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.");
@@ -89,6 +95,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: {
@@ -103,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,
@@ -42,6 +43,7 @@ import {
 } 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";
@@ -182,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) {
@@ -616,6 +619,54 @@ 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.");
+    }
+    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],
@@ -1031,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]
@@ -1054,6 +1105,8 @@ 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]
   filegrc get [resource-type] <id> [--mutation]
@@ -1120,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
@@ -1142,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") {
@@ -1223,6 +1277,48 @@ 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]
+  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]
@@ -1251,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",
@@ -1270,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",
@@ -1422,6 +1519,7 @@ function buildProgramPathResult(model, readiness, auditReadiness) {
     evidenceReady: readiness.evidenceReady,
     operating: readiness.operating,
     policyActivations: readiness.policyActivations,
+    documentActivations: readiness.documentActivations,
     policyLibraryProposals: readiness.policyLibraryProposals,
     stages
   };
@@ -1625,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,

package/src/collection-review.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { modelSupports } from "../model/index.js";
 import { collectionRevision } from "./collection-revision.js";
 import { scopedCollectionRecords } from "./collection-scope.js";
 import { applyResourceBatch } from "./files.js";
@@ -26,7 +27,7 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
     record.type === "collection-review"
     && record.resourceType === resourceType
     && record.status !== "retired"
-    && (String(loaded.model.modelVersion) !== "4" || (record.scopeResourceIds || []).includes(program.id))
+    && (!modelSupports(loaded.model, "program-scope") || (record.scopeResourceIds || []).includes(program.id))
   ));
   const review = reviewEntry?.record || null;
   const authoritativeSourceId = review?.decision === "externally-managed"
@@ -86,7 +87,7 @@ export async function scaffoldCollectionReview(input = process.cwd(), options =
     rationale: null,
     reviewedByIds: [],
     reviewedOn: null,
-    ...(String(loaded.model.modelVersion) === "4"
+    ...(modelSupports(loaded.model, "program-scope")
       ? { authoritativeComponentId: null }
       : { authoritativeSystemId: null })
   };
@@ -103,7 +104,7 @@ export async function planCollectionReview(input = process.cwd(), options = {})
   const reviewedByIds = [...new Set((options.reviewedByIds || []).map(String).filter(Boolean))];
   const reviewedOn = String(options.reviewedOn || "").trim();
   const scopeRevision = String(options.scopeRevision || getGitSummary(loaded.root).commit || "uncommitted").trim();
-  const v4 = String(loaded.model.modelVersion) === "4";
+  const v4 = modelSupports(loaded.model, "program-scope");
   const authoritativeSourceId = String(v4 ? options.authoritativeComponentId : options.authoritativeSystemId || "").trim();
   if (!(configuration.decisions || ["complete"]).includes(decision)) {
     throw new Error(

package/src/collection-scope.js

@@ -1,7 +1,8 @@
+import { modelSupports } from "../model/index.js";
 import { programComponents, selectedRequirementIds } from "./program.js";
 
 export function scopedCollectionRecords(loaded, resourceType, program) {
-  if (String(loaded.model.modelVersion) !== "4") {
+  if (!modelSupports(loaded.model, "program-scope")) {
     return loaded.resources.filter((record) => record.type === resourceType);
   }
   if (resourceType === "vendor") {
@@ -37,7 +38,7 @@ export function scopedCollectionRecords(loaded, resourceType, program) {
 
 export function collectionRevisionInputs(loaded, resourceType, program) {
   const reviewed = scopedCollectionRecords(loaded, resourceType, program);
-  if (String(loaded.model.modelVersion) !== "4") {
+  if (!modelSupports(loaded.model, "program-scope")) {
     return reviewed.map((record) => ({ record, value: record }));
   }
   const byId = new Map(loaded.resources.map((record) => [record.id, record]));
@@ -94,7 +95,7 @@ export function collectionRevisionInputs(loaded, resourceType, program) {
 }
 
 export function collectionScopeRevisionFacts(loaded, resourceType, program) {
-  if (String(loaded.model.modelVersion) !== "4") {
+  if (!modelSupports(loaded.model, "program-scope")) {
     const common = { programId: program?.id ?? null };
     if (resourceType === "framework") {
       return {

package/src/document-activation.js

@@ -0,0 +1,145 @@
+import { applyDocumentActivationBatch, contentRevision } from "./files.js";
+import { serializeWorkspaceMutation } from "./mutation.js";
+import { modelSupports } from "../model/index.js";
+import { assessAuditDocumentActivations } from "./audit-preparation.js";
+import { assessProgramReadiness } from "./program-readiness.js";
+import { personWasActiveOn } from "./soc2.js";
+import { currentCalendarDate } from "./time.js";
+import { loadWorkspace } from "./workspace.js";
+
+export async function scaffoldDocumentActivation(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  requireDocumentLifecycle(loaded);
+  const candidates = await activationCandidates(loaded, options);
+  const revisionById = new Map(loaded.entries.map((entry) => [entry.record.id, contentRevision(entry.source)]));
+  const today = currentCalendarDate(loaded.workspace.timezone);
+  return {
+    documentIds: candidates.map(({ documentId }) => documentId),
+    ...(options.auditId ? { auditId: options.auditId, workflowScope: "engagement" } : { workflowScope: "program" }),
+    activatedByIds: [],
+    activatedOn: today,
+    effectiveOn: today,
+    expectedRevisions: Object.fromEntries(candidates.map(({ documentId }) => [documentId, revisionById.get(documentId)])),
+    confirmed: false
+  };
+}
+
+export async function planDocumentActivation(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  requireDocumentLifecycle(loaded);
+  const documentIds = [...new Set((options.documentIds || []).map(String))];
+  if (!documentIds.length) throw new Error("Document activation needs at least one approved governed Document.");
+  const activatedByIds = [...new Set((options.activatedByIds || []).map(String))];
+  if (!activatedByIds.length) throw new Error("Document activation needs the Person who performed the activation.");
+  const activatedOn = String(options.activatedOn || "").trim();
+  const effectiveOn = String(options.effectiveOn || "").trim();
+  if (!isCalendarDate(activatedOn)) throw new Error("Document activation needs the actual activation date in YYYY-MM-DD format.");
+  if (!isCalendarDate(effectiveOn)) throw new Error("Document activation needs a real effective date in YYYY-MM-DD format.");
+  const today = currentCalendarDate(loaded.workspace.timezone);
+  if (activatedOn !== today) {
+    throw new Error(`The activation date records today's lifecycle event and must be ${today}. Keep a future date in proposedEffectiveOn until activation occurs.`);
+  }
+  if (effectiveOn < activatedOn) {
+    throw new Error("The effective date cannot be before the separate activation date; do not backdate adoption.");
+  }
+  const expectedRevisions = options.expectedRevisions || {};
+  if (Array.isArray(expectedRevisions) || !expectedRevisions || typeof expectedRevisions !== "object") {
+    throw new Error("Document activation expected revisions must be keyed by Document ID.");
+  }
+  const workflowScope = options.auditId ? "engagement" : "program";
+  const candidates = await activationCandidates(loaded, options);
+  const assessmentById = new Map(candidates.map((item) => [item.documentId, item]));
+  const entryById = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
+  const invalidActivatorIds = activatedByIds.filter((id) => {
+    const person = entryById.get(id)?.record;
+    return !personWasActiveOn(person, activatedOn);
+  });
+  if (invalidActivatorIds.length) {
+    throw new Error(`Document activation needs active People as activators: ${invalidActivatorIds.join(", ")}.`);
+  }
+  const update = documentIds.map((documentId) => {
+    const entry = entryById.get(documentId);
+    if (!entry || entry.record.type !== "document") throw new Error(`Document "${documentId}" was not found.`);
+    if (entry.record.status !== "approved") {
+      throw new Error(`Document "${documentId}" must be independently approved before its separate ${workflowScope === "engagement" ? "Step 5" : "Step 3"} activation.`);
+    }
+    if (entry.record.workflowScope !== workflowScope) {
+      throw new Error(`Document "${documentId}" belongs to the ${entry.record.workflowScope} workflow, not ${workflowScope}.`);
+    }
+    const assessment = assessmentById.get(documentId);
+    if (assessment?.state !== "ready-to-activate") {
+      const missing = assessment?.missingImplementationControlIds || [];
+      throw new Error(
+        missing.length
+          ? `Document "${documentId}" cannot be activated until linked Controls are implemented: ${missing.join(", ")}.`
+          : `Document "${documentId}" is not ready for ${workflowScope === "engagement" ? "Step 5" : "Step 3"} activation.`
+      );
+    }
+    if (!/^[a-f0-9]{64}$/.test(expectedRevisions[documentId] || "")) {
+      throw new Error(`Document activation needs the current record revision for "${documentId}". Regenerate the activation review and try again.`);
+    }
+    const record = {
+      ...entry.record,
+      status: "active",
+      activationBasis: "recorded",
+      activatedByIds,
+      activatedOn,
+      effectiveOn,
+      activatedContentRevisions: structuredClone(entry.record.approvedContentRevisions)
+    };
+    delete record.proposedEffectiveOn;
+    return record;
+  });
+  return {
+    operation: "document-activation",
+    workflowScope,
+    ...(options.auditId ? { auditId: options.auditId } : {}),
+    documentIds,
+    activatedByIds,
+    activatedOn,
+    effectiveOn,
+    changes: {
+      update,
+      expectedRevisions: Object.fromEntries(documentIds.map((documentId) => [documentId, expectedRevisions[documentId]])),
+      validateWholeWorkspace: true
+    }
+  };
+}
+
+async function activationCandidates(loaded, options) {
+  if (options.auditId) {
+    return (await assessAuditDocumentActivations(loaded, {
+      auditId: options.auditId,
+      asOf: currentCalendarDate(loaded.workspace.timezone)
+    })).filter(({ state }) => state === "ready-to-activate");
+  }
+  const readiness = await assessProgramReadiness(loaded, { programId: options.programId });
+  return readiness.documentActivations.filter(({ state }) => state === "ready-to-activate");
+}
+
+export async function activateDocuments(input = process.cwd(), options = {}) {
+  if (options.confirmed !== true) throw new Error("Review the governed Document activation and confirm the write.");
+  return serializeWorkspaceMutation(input, async (root) => {
+    const plan = await planDocumentActivation(root, options);
+    const result = await applyDocumentActivationBatch(root, plan.changes);
+    return { ...plan, result };
+  });
+}
+
+function requireDocumentLifecycle(loaded) {
+  if (!modelSupports(loaded.model, "governed-document-activation")) {
+    throw new Error("Separate governed Document approval and activation requires a model v5 workspace.");
+  }
+}
+
+function isCalendarDate(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+  const [, year, month, day] = match.map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  date.setUTCHours(0, 0, 0, 0);
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}