filegrc 0.7.1 → 0.8.0

package/src/model-migration.js

@@ -1,5 +1,5 @@
 import { createResourceId } from "./id.js";
-import { applyResourceBatch, contentRevision } from "./files.js";
+import { applyModelMigrationBatch, applyResourceBatch, contentRevision } from "./files.js";
 import { loadWorkspace } from "./workspace.js";
 import { ACTIVE_MODEL_VERSION, loadModel } from "../model/index.js";
 import { legacyCoverage } from "./coverage.js";
@@ -882,7 +882,7 @@ async function migrateV1ToV2(input = process.cwd(), options = {}) {
       + "and resolve every missing value, conflict, and manual action."
     );
   }
-  const result = await applyResourceBatch(input, plan.changes);
+  const result = await applyModelMigrationBatch(input, plan.changes);
   return { ...plan, applied: true, result };
 }
 
@@ -891,7 +891,7 @@ export async function planModelMigration(input = process.cwd(), options = {}) {
   const sourceVersion = String(loaded.workspace?.dataModelVersion || "");
   const requestedTarget = options.targetModelVersion
     ? String(options.targetModelVersion)
-    : sourceVersion === "1" ? V1_TARGET_MODEL_VERSION : sourceVersion === "2" ? "3" : ACTIVE_MODEL_VERSION;
+    : sourceVersion === "1" ? V1_TARGET_MODEL_VERSION : sourceVersion === "2" ? "3" : sourceVersion === "3" ? "4" : ACTIVE_MODEL_VERSION;
   if (sourceVersion === requestedTarget) return emptyPlan(sourceVersion, requestedTarget);
   if (sourceVersion === "1" && requestedTarget === "2") {
     return planV1ToV2Migration(input, options);
@@ -899,13 +899,16 @@ export async function planModelMigration(input = process.cwd(), options = {}) {
   if (sourceVersion === "2" && requestedTarget === "3") {
     return planV2ToV3Migration(loaded);
   }
-  if (sourceVersion === "3" && requestedTarget === ACTIVE_MODEL_VERSION) {
+  if (sourceVersion === "3" && requestedTarget === "4") {
     return planV3ToV4Migration(loaded, options);
   }
+  if (sourceVersion === "4" && requestedTarget === ACTIVE_MODEL_VERSION) {
+    return planV4ToV5Migration(loaded, options);
+  }
   if (sourceVersion === "1" && requestedTarget === ACTIVE_MODEL_VERSION) {
     throw new Error(
       "Model v1 workspaces must migrate to model v2 first. "
-      + "Preview and apply `npx filegrc migrate --to-model 2`, then migrate to model v3 and v4."
+      + "Preview and apply `npx filegrc migrate --to-model 2`, then migrate one version at a time through model v5."
     );
   }
   throw new Error(`Model migration does not support v${sourceVersion} to v${requestedTarget}.`);
@@ -925,7 +928,7 @@ export async function migrateModel(input = process.cwd(), options = {}) {
   if (plan.sourceModelVersion === "1" && plan.targetModelVersion === "2") {
     return migrateV1ToV2(input, options);
   }
-  const result = await applyResourceBatch(input, plan.changes);
+  const result = await applyModelMigrationBatch(input, plan.changes);
   return {
     ...plan,
     applied: true,
@@ -1498,6 +1501,214 @@ async function planV3ToV4Migration(loaded, options = {}) {
   };
 }
 
+async function planV4ToV5Migration(loaded, options = {}) {
+  if (!loaded.workspace?.id) throw new Error("Model migration requires a valid Workspace record.");
+  const targetModel = loadModel("5");
+  const revisions = new Map(loaded.entries.map((entry) => [entry.record.id, contentRevision(entry.source)]));
+  const automatic = [];
+  const reviewRequired = [];
+  const unsupported = [];
+  const missing = [];
+  const manualActions = [];
+  const updates = [];
+  const documentScopeDecisions = options.documentScopes && typeof options.documentScopes === "object"
+    ? options.documentScopes
+    : {};
+  const auditDocumentFields = [
+    "engagementTermsDocumentId",
+    ...(targetModel.auditReadiness?.managementDocuments || []).map(({ field }) => field)
+  ];
+  const auditsByDocumentId = new Map();
+  const allAuditsByDocumentId = new Map();
+  const addAuditReference = (map, documentId, audit) => {
+    if (!documentId) return;
+    if (!map.has(documentId)) map.set(documentId, new Map());
+    map.get(documentId).set(audit.id, audit);
+  };
+  for (const audit of loaded.resources.filter(({ type }) => type === "audit")) {
+    for (const field of auditDocumentFields) {
+      const documentId = audit[field];
+      if (!documentId) continue;
+      addAuditReference(auditsByDocumentId, documentId, audit);
+      addAuditReference(allAuditsByDocumentId, documentId, audit);
+    }
+    for (const documentId of audit.supplementalDocumentIds || []) {
+      addAuditReference(allAuditsByDocumentId, documentId, audit);
+    }
+  }
+  const programDocumentIds = new Set([
+    ...loaded.resources.filter(({ type }) => type === "policy").flatMap(({ relatedDocumentIds }) => relatedDocumentIds || []),
+    ...loaded.resources.filter(({ type }) => type === "obligation").flatMap((record) => [
+      ...(record.scopeResourceIds || []),
+      ...(record.templateResourceId ? [record.templateResourceId] : [])
+    ])
+  ]);
+  const auditDocumentKinds = new Set([
+    ...(targetModel.auditReadiness?.managementDocuments || []).map(({ kind }) => kind),
+    "soc2-engagement-terms"
+  ]);
+  const resetDocumentIds = [];
+  const legacyDocumentIds = [];
+  const documentIds = new Set(loaded.resources.filter(({ type }) => type === "document").map(({ id }) => id));
+
+  for (const documentId of Object.keys(documentScopeDecisions)) {
+    if (!documentIds.has(documentId)) {
+      unsupported.push(classifiedChange(
+        "unsupported",
+        documentId,
+        "workflowScope",
+        `Document scope decision "${documentId}" does not match a Document in this workspace.`
+      ));
+    }
+  }
+
+  for (const original of loaded.resources) {
+    if (original.type === "workspace") {
+      updates.push({ ...original, dataModelVersion: "5" });
+      automatic.push(classifiedChange(
+        "automatic",
+        original.id,
+        "dataModelVersion",
+        "Select model v5 and enable the separate governed Document approval and activation lifecycle."
+      ));
+      continue;
+    }
+    if (original.type !== "document") continue;
+    const governedAuditReferences = [...(auditsByDocumentId.get(original.id)?.values() || [])];
+    const auditReferences = [...(allAuditsByDocumentId.get(original.id)?.values() || [])];
+    const explicitScope = normalizeDocumentScopeDecision(documentScopeDecisions[original.id]);
+    if (Object.hasOwn(documentScopeDecisions, original.id) && !explicitScope) {
+      unsupported.push(classifiedChange(
+        "unsupported",
+        original.id,
+        "workflowScope",
+        `Document scope decision for "${original.id}" must be "program" or "engagement".`
+      ));
+    }
+    const engagementSignal = governedAuditReferences.length > 0 || auditDocumentKinds.has(original.documentKind);
+    const programSignal = programDocumentIds.has(original.id);
+    if (!explicitScope && engagementSignal && programSignal) {
+      unsupported.push(classifiedChange(
+        "unsupported",
+        original.id,
+        "workflowScope",
+        `Document "${original.title}" is linked to both program governance and an Audit. Choose program or engagement in documentScopes.${original.id}.`
+      ));
+    }
+    const workflowScope = explicitScope || (engagementSignal && !programSignal ? "engagement" : "program");
+    const record = { ...original, workflowScope };
+    if (workflowScope === "engagement") delete record.programRole;
+    automatic.push(classifiedChange(
+      "automatic",
+      original.id,
+      "workflowScope",
+      explicitScope
+        ? `Use the reviewed ${workflowScope} workflow scope.`
+        : `Classify this Document as ${workflowScope} from its model kind and authoritative relationships.`
+    ));
+    const historicalEngagement = workflowScope === "engagement" && auditReferences.some(({ status }) => (
+      ["issued", "delivered", "complete"].includes(status)
+    ));
+    if (["superseded", "retired"].includes(record.status)) {
+      if (historicalEngagement) {
+        record.activationBasis = "legacy-v4";
+        legacyDocumentIds.push(record.id);
+      } else delete record.activationBasis;
+      delete record.activatedOn;
+      delete record.activatedByIds;
+      delete record.activatedContentRevisions;
+    } else if (record.status === "active" && historicalEngagement) {
+      record.activationBasis = "legacy-v4";
+      delete record.activatedOn;
+      delete record.activatedByIds;
+      delete record.activatedContentRevisions;
+      legacyDocumentIds.push(record.id);
+      reviewRequired.push(classifiedChange(
+        "review-required",
+        record.id,
+        "activationBasis",
+        "Preserve this historical engagement Document as active with a visible legacy-v4 basis. Model v4 recorded one combined approval and activation state, so the migration does not invent an activation date, actor, or second revision."
+      ));
+    } else if (record.status === "active") {
+      record.status = "approved";
+      if (record.effectiveOn) record.proposedEffectiveOn = record.effectiveOn;
+      delete record.effectiveOn;
+      delete record.activationBasis;
+      delete record.activatedOn;
+      delete record.activatedByIds;
+      delete record.activatedContentRevisions;
+      resetDocumentIds.push(record.id);
+      reviewRequired.push(classifiedChange(
+        "review-required",
+        record.id,
+        "status",
+        workflowScope === "engagement"
+          ? "Model v4 recorded one combined approval and activation state. Preserve the approval and approved revision, then record a separate Step 5 activation after confirming the current engagement facts."
+          : "Model v4 recorded one combined approval and activation state. Preserve the approval and approved revision, confirm the linked requirements, then record a separate Step 3 activation."
+      ));
+    }
+    updates.push(record);
+  }
+
+  const updatedById = new Map(updates.map((record) => [record.id, record]));
+  const migratedRecords = loaded.resources.map((record) => updatedById.get(record.id) || record);
+  await collectTargetValidationActions(loaded, migratedRecords, targetModel, missing, manualActions);
+  for (const item of [...missing, ...manualActions]) {
+    unsupported.push(classifiedChange(
+      "unsupported",
+      item.resourceId,
+      item.field,
+      item.message || `Resolve ${item.field} before applying the model v5 migration.`
+    ));
+  }
+  const ready = unsupported.length === 0;
+  return {
+    schemaVersion: 2,
+    sourceModelVersion: "4",
+    targetModelVersion: "5",
+    ready,
+    missing,
+    conflicts: [],
+    manualActions,
+    classifications: { automatic, reviewRequired, unsupported },
+    notes: reviewRequired,
+    migrationReport: {
+      resetDocumentIds,
+      legacyDocumentIds
+    },
+    summary: {
+      create: 0,
+      update: updates.length,
+      automatic: automatic.length,
+      reviewRequired: reviewRequired.length,
+      unsupported: unsupported.length
+    },
+    fileDiff: {
+      create: [],
+      update: updates.map((record) => ({
+        type: record.type,
+        id: record.id,
+        before: loaded.resources.find(({ id }) => id === record.id),
+        after: record
+      }))
+    },
+    changes: {
+      create: [],
+      update: updates,
+      expectedRevisions: Object.fromEntries(updates.map(({ id }) => [id, revisions.get(id)])),
+      validateWholeWorkspace: true,
+      targetModelVersion: "5"
+    }
+  };
+}
+
+function normalizeDocumentScopeDecision(value) {
+  const candidate = typeof value === "object" && value
+    ? value.workflowScope || value.scope
+    : value;
+  return ["program", "engagement"].includes(candidate) ? candidate : null;
+}
+
 async function collectTargetValidationActions(loaded, records, model, missing, manualActions) {
   const { validateWorkspace } = await import("./validate.js");
   const existingById = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
@@ -2003,7 +2214,7 @@ function migrateInverseArrays(resources, byId, editable, conflicts, mapping) {
 }
 
 function emptyPlan(version, targetVersion = V1_TARGET_MODEL_VERSION) {
-  const classifiedPlan = ["3", "4"].includes(String(targetVersion));
+  const classifiedPlan = Number(targetVersion) >= 3;
   const includesPathMoves = String(targetVersion) === "4";
   return {
     schemaVersion: classifiedPlan ? 2 : 1,

package/src/obligations.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { scaffoldResourceMutation } from "./agent.js";
 import { createResourceId } from "./id.js";
 import { createResourceAndLink, createResources, updateResource } from "./files.js";
-import { loadModel } from "../model/index.js";
+import { loadModel, modelSupports } from "../model/index.js";
 import { coverageEnd } from "./coverage.js";
 import {
   addCalendarDays,
@@ -14,7 +14,7 @@ import {
 } from "./recurrence.js";
 import { currentCalendarDate, isRfc3339Timestamp } from "./time.js";
 import { loadWorkspace } from "./workspace.js";
-import { obligationProgramStatus } from "./program-lifecycle.js";
+import { obligationGovernedDocuments, obligationProgramStatus } from "./program-lifecycle.js";
 import { resolveProgram } from "./program.js";
 
 const COMPLETION_DATE_FIELDS = [
@@ -75,7 +75,7 @@ export function planObligations(resources, options = {}) {
   for (const obligation of obligations) {
     const activity = obligationActivity(model, obligation.activityType);
     const expectedCompletionTypes = activity.completionResourceTypes;
-    const programStatus = obligationProgramStatus(obligation, byId, asOf);
+    const programStatus = obligationProgramStatus(obligation, byId, asOf, model);
     if (obligation.recurrence?.mode === "event" && obligation.recurrence.eventType) {
       const eventType = obligation.recurrence.eventType;
       const group = triggerGroups.get(eventType) ?? {
@@ -111,7 +111,7 @@ export function planObligations(resources, options = {}) {
     }
 
     const configuredAnchor = obligation.recurrence?.anchorDate || obligation.startsOn;
-    const activationDate = obligationActivationDate(obligation, byId);
+    const activationDate = obligationActivationDate(obligation, byId, model);
     const recurrence = {
       ...(obligation.recurrence || {}),
       anchorDate: configuredAnchor && activationDate
@@ -258,8 +258,8 @@ export async function createObligationEvent(input, options) {
     )
   ));
   if (!eventType || templates.length === 0) throw new Error(`No active obligations use event type "${eventType}".`);
-  if (templates.some((record) => obligationProgramStatus(record, byId, occurredOn) === "proposed")) {
-    throw new Error(`Event type "${eventType}" still has starter proposals. Make every governing policy effective and implement at least one linked control before starting this workflow.`);
+  if (templates.some((record) => obligationProgramStatus(record, byId, occurredOn, loaded.model) === "proposed")) {
+    throw new Error(`Event type "${eventType}" still has starter proposals. Make every governing Policy and required governed Document active and effective, then implement at least one linked Control before starting this workflow.`);
   }
   if (templates.some((record) => normalizedEventWindow(record.window).precision === "timestamp") && !occurredAt) {
     throw new Error(`Event type "${eventType}" has hour-based deadlines and requires an RFC 3339 occurredAt timestamp.`);
@@ -720,7 +720,7 @@ function completionTeam(resources, ownerIds) {
 }
 
 function defaultClassificationId(loaded) {
-  if (String(loaded.model.modelVersion) === "4") {
+  if (modelSupports(loaded.model, "program-scope")) {
     return loaded.resources.find(({ type, id, status }) => type === "classification" && id === "internal" && status === "active")?.id
       || loaded.resources.find(({ type, status }) => type === "classification" && status === "active")?.id
       || "";
@@ -792,7 +792,7 @@ function planEventRun(event, actionItems, byId, asOf, now, model) {
       const completionProfile = obligation?.type === "obligation"
         ? obligationActivity(model, obligation.activityType).completionProfile || null
         : null;
-      const completionIds = ["3", "4"].includes(String(model.modelVersion))
+      const completionIds = modelSupports(model, "guided-workflow")
         ? record.completionResourceIds || []
         : [...(record.completionResourceIds || []), ...(record.evidenceIds || [])];
       const linkedCompletionIds = [...new Set(completionIds)];
@@ -991,13 +991,16 @@ function occurrenceStatus(window, asOf, complete) {
   return "upcoming";
 }
 
-function obligationActivationDate(obligation, byId) {
-  const dates = (obligation.policyIds || [])
+function obligationActivationDate(obligation, byId, model) {
+  const policyDates = (obligation.policyIds || [])
     .map((id) => byId.get(id))
     .filter((policy) => policy?.type === "policy")
     .map((policy) => policy.effectiveOn)
     .filter(Boolean);
-  return dates.sort().at(-1) || null;
+  const documentDates = obligationGovernedDocuments(obligation, byId, model)
+    .map((document) => document.effectiveOn)
+    .filter(Boolean);
+  return [...policyDates, ...documentDates].sort().at(-1) || null;
 }
 
 function relativeTiming(window, asOf) {

package/src/policy-library.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import { modelSupports } from "../model/index.js";
 import { applyResourceBatch, contentRevision } from "./files.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
 import { resolveDataPath } from "./paths.js";
@@ -658,7 +659,7 @@ async function buildPolicyLibraryPlan(loaded) {
     });
   }
 
-  for (const addition of String(loaded.model.modelVersion) === "4" ? OBLIGATION_ADDITIONS : []) {
+  for (const addition of modelSupports(loaded.model, "program-scope") ? OBLIGATION_ADDITIONS : []) {
     if (byId.has(addition.id)) {
       skipped.push(skippedItem(addition.id, "present", "An Obligation with this ID already exists, so FileGRC will not replace it."));
       continue;

package/src/program-lifecycle.js

@@ -1,6 +1,93 @@
 import { currentPartyPeople } from "./parties.js";
+import { modelSupports } from "../model/index.js";
 
-export function obligationProgramStatus(obligation, byId, asOf) {
+const requiredDocumentsByControlCache = new WeakMap();
+
+export function auditSpecificDocumentKinds(model) {
+  return new Set([
+    ...(model?.auditReadiness?.managementDocuments || []).map(({ kind }) => kind),
+    "soc2-engagement-terms"
+  ]);
+}
+
+export function documentIsAuditSpecific(document, model) {
+  if (document?.type !== "document") return false;
+  if (modelSupports(model, "document-workflow-scope")) {
+    return document.workflowScope === "engagement";
+  }
+  return auditSpecificDocumentKinds(model).has(document.documentKind);
+}
+
+export function governedDocumentIsOperating(document, asOf, model) {
+  if (document?.type !== "document" || document.status !== "active") return false;
+  if (!document.effectiveOn || document.effectiveOn > asOf) return false;
+  if (!modelSupports(model, "governed-document-activation")) return true;
+  if (document.activationBasis === "legacy-v4") {
+    return document.workflowScope === "engagement"
+      && Boolean(document.approvedOn && document.approvedContentRevisions);
+  }
+  return Boolean(
+    document.activationBasis === "recorded"
+    && document.approvedOn
+    && document.approvedContentRevisions
+    && document.activatedOn
+    && document.activatedOn <= asOf
+    && (document.activatedByIds || []).length
+    && document.activatedContentRevisions
+    && contentRevisionBindingsMatch(document.approvedContentRevisions, document.activatedContentRevisions)
+  );
+}
+
+export function contentRevisionBindingsMatch(left, right) {
+  if (!left || !right || Array.isArray(left) || Array.isArray(right)) return false;
+  const normalize = (value) => Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+  return JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
+}
+
+export function obligationGovernedDocuments(obligation, byId, model) {
+  if (!modelSupports(model, "governed-document-activation")) return [];
+  const policyDocumentIds = (obligation.policyIds || []).flatMap((id) => {
+    const policy = byId.get(id);
+    return policy?.type === "policy" ? policy.relatedDocumentIds || [] : [];
+  });
+  const directDocumentIds = [
+    ...(obligation.scopeResourceIds || []),
+    ...(obligation.templateResourceId ? [obligation.templateResourceId] : [])
+  ];
+  const requiredDocumentsByControl = indexRequiredDocumentsByControl(byId, model);
+  const controlDocumentIds = (obligation.controlIds || [])
+    .flatMap((id) => requiredDocumentsByControl.get(id) || []);
+  return [...new Set([...policyDocumentIds, ...directDocumentIds, ...controlDocumentIds])]
+    .map((id) => byId.get(id))
+    .filter((record) => (
+      record?.type === "document"
+      && !["superseded", "retired"].includes(record.status)
+      && !documentIsAuditSpecific(record, model)
+    ));
+}
+
+function indexRequiredDocumentsByControl(byId, model) {
+  const modelVersion = String(model?.modelVersion || "");
+  const cached = requiredDocumentsByControlCache.get(byId);
+  if (cached?.modelVersion === modelVersion) return cached.index;
+  const index = new Map();
+  for (const record of byId.values()) {
+    if (
+      record.type !== "document"
+      || record.programRole !== "required"
+      || ["superseded", "retired"].includes(record.status)
+      || documentIsAuditSpecific(record, model)
+    ) continue;
+    for (const controlId of record.controlIds || []) {
+      if (!index.has(controlId)) index.set(controlId, []);
+      index.get(controlId).push(record.id);
+    }
+  }
+  requiredDocumentsByControlCache.set(byId, { modelVersion, index });
+  return index;
+}
+
+export function obligationProgramStatus(obligation, byId, asOf, model) {
   if (obligation.status !== "active") return "proposed";
   if (currentPartyPeople(obligation.ownerIds || [], byId).size === 0) return "proposed";
   const policyIds = obligation.policyIds || [];
@@ -12,6 +99,9 @@ export function obligationProgramStatus(obligation, byId, asOf) {
       && policy.effectiveOn <= asOf;
   });
   if (!policiesReady) return "proposed";
+  const governedDocumentsReady = obligationGovernedDocuments(obligation, byId, model)
+    .every((document) => governedDocumentIsOperating(document, asOf, model));
+  if (!governedDocumentsReady) return "proposed";
   const controlIds = obligation.controlIds || [];
   if (!controlIds.length) return "accepted";
   return controlIds.some((id) => byId.get(id)?.type === "control" && byId.get(id).status === "implemented")
@@ -19,10 +109,10 @@ export function obligationProgramStatus(obligation, byId, asOf) {
     : "proposed";
 }
 
-export function obligationIsRunning(obligation, byId, asOf) {
+export function obligationIsRunning(obligation, byId, asOf, model) {
   return obligation?.type === "obligation"
     && obligation.status === "active"
-    && obligationProgramStatus(obligation, byId, asOf) === "accepted";
+    && obligationProgramStatus(obligation, byId, asOf, model) === "accepted";
 }
 
 export function obligationIsEnabled(obligation) {

package/src/program-path.js

@@ -12,7 +12,7 @@ export const RESOURCE_INSTRUCTIONS = {
   requirement: "Keep the published criterion as catalog content. Record management applicability and rationale on the selected Program.",
   commitment: "Record supplemental customer promises and service requirements that shape the scope or control design. The Commitment’s systemIds and controlIds are authoritative for what fulfills it.",
   policy: "Tailor each Policy to match what the company is committing to. Clear placeholders, assign an owner and separate approver, then bind approval to the reviewed content. Approval does not prove implementation. Activate the Policy during the Step 3 cutover after reviewing its implementation gaps.",
-  document: "Tailor the governed plans and other supporting documents the program needs. Assign owners and approvers, then keep the approved Markdown in Git.",
+  document: "Complete required governed plans and schedules in Step 2, assign an owner and separate approver, and bind approval to the intended values and exact Markdown. Implement the linked requirements and activate that approved revision in Step 3. Prepare audit-specific Documents in Step 5.",
   control: "Finish each applicable starter Control with the procedure people follow, its owner, bounded System scope, operating Components, authoritative evidence-source Components, governing Policy and Requirement mappings, and implementation date. Put calendar and event schedules in Obligations.",
   "complementary-control": "Review whether any in-scope Control depends on a customer or carved-out provider action. Record each real dependency, or confirm that the current scope has none.",
   evidence: "Create an Evidence Artifact when a real export, report, screenshot, signed file, or approved external reference exists. Select its authoritative source Component, link the Controls and operating records it supports, retain the fixed artifact or reference, and have another person verify it before audit use.",
@@ -98,16 +98,20 @@ export const PROGRAM_PATH = [
   {
     id: "policies",
     number: 2,
-    title: "Approve Policies",
-    description: "Tailor, review, and approve",
-    summary: "Adapt and approve the starter policies.",
+    title: "Approve Policies and Plans",
+    description: "Tailor requirements, intended values, and approvals",
+    summary: "Adapt and independently approve Policies and required governed Documents.",
     sections: [
-      { id: "library", title: "Policy Library", description: "Review and approve Policy requirements without treating approval as proof of technical implementation.", steps: ["Review Policy Markdown and replace every organization placeholder.", "Confirm the owner, separate approver, audience, review Obligation, and Controls that point to the Policy.", "Record approval against the exact reviewed content. Leave the Policy approved and inactive until the Step 3 implementation cutover."], types: ["policy"], defaultOpen: true }
+      { id: "library", title: "Policy Library", description: "Review and approve Policy requirements without treating approval as proof of technical implementation.", steps: ["Review Policy Markdown and replace every organization placeholder.", "Confirm the owner, separate approver, audience, review Obligation, and Controls that point to the Policy.", "Record approval against the exact reviewed content. Leave the Policy approved and inactive until the Step 3 implementation cutover."], types: ["policy"], defaultOpen: true },
+      { id: "governed-documents", title: "Governed Plans and Schedules", description: "Complete the intended values in each required program plan or schedule and obtain independent approval of the exact revision before implementation.", steps: ["Review each required plan or schedule and replace every organization placeholder with the intended owner, timing, threshold, scope, or response value.", "Confirm the Document owner, separate approver, linked Controls, and review schedule.", "Record approval and its date against the exact Markdown revision. Leave the Document approved until its linked requirements are implemented in Step 3."], types: [], relatedLinks: [{ type: "document", label: "Governed plans and schedules", href: "#/resources/document?stage=policies&documentScope=program" }], defaultOpen: true }
     ],
     resourceTypes: ["policy"],
+    supportingResourceTypes: ["document"],
     commands: [
       "filegrc guide policy --json",
+      "filegrc guide document --json",
       "filegrc list policy --json",
+      "filegrc list document --json",
       "filegrc get POLICY_ID --mutation"
     ]
   },
@@ -118,14 +122,15 @@ export const PROGRAM_PATH = [
     description: "Finish controls and their evidence sources",
     summary: "Describe each Control and connect its evidence source.",
     sections: [
-      { id: "catalog", title: "Control Catalog", description: "Finish the starter Controls, governed plans, schedules, and authoritative evidence sources, then review the approved Policies together at implementation cutover.", steps: ["Open every planned Control and confirm its mappings and operation pattern.", "Write the real procedure in Record Markdown, add bounded System scope, and map the operating and authoritative evidence-source Components.", "Create or enable every calendar and event schedule as an Obligation. Enabled work remains dormant until its governing Policy is active.", "Confirm each source Component is active, has an evidence-source role and rationale in the Control's System scope, has current access owners, and includes repeatable retrieval instructions in Record Markdown.", "Complete required governed plans, then use Review policy activation on the Controls page to inspect each Policy’s planned or partial Controls, missing Components or sources, missing schedules, and unresolved Exceptions.", "Choose the approved Policies that should take effect, set the real effective date, and confirm the Step 3 cutover. You can activate with a documented gap or approved Exception, but Evidence Readiness still requires active and operating Policies."], types: ["control", "complementary-control", "document"], defaultOpen: true }
+      { id: "catalog", title: "Control Catalog", description: "Implement the approved requirements, activate required governed Documents, finish the authoritative evidence sources, then review the approved Policies together at implementation cutover.", steps: ["Open every planned Control and confirm its mappings and operation pattern.", "Write the real procedure in Record Markdown, add bounded System scope, and map the operating and authoritative evidence-source Components.", "Create or enable every calendar and event schedule as an Obligation. Enabled work remains dormant until its governing Policy is active.", "Confirm each source Component is active, has an evidence-source role and rationale in the Control's System scope, has current access owners, and includes repeatable retrieval instructions in Record Markdown.", "Implement every requirement linked from an approved governed plan or schedule, then activate the unchanged approved Document with a separate activation date and revision.", "Use Review policy activation on the Controls page to inspect each Policy’s planned or partial Controls, inactive governed Documents, missing Components or sources, missing schedules, and unresolved Exceptions.", "Choose the approved Policies that should take effect, set the real effective date, and confirm the Step 3 cutover. You can activate with a documented gap or approved Exception, but Evidence Readiness still requires active and operating Policies and Documents."], types: ["control", "complementary-control"], relatedLinks: [{ type: "document", label: "Activate governed plans and schedules", href: "#/resources/document?stage=controls&documentScope=program" }], defaultOpen: true }
     ],
-    resourceTypes: ["control", "complementary-control", "document"],
+    resourceTypes: ["control", "complementary-control"],
     commands: [
       "filegrc guide control --json",
       "filegrc list control --json",
       "filegrc get CONTROL_ID --mutation",
       "filegrc review-collection complementary-control --scaffold",
+      "filegrc activate-documents --scaffold",
       "filegrc activate-policies --scaffold",
       "filegrc evidence-map --json",
       "filegrc program-readiness --json"
@@ -217,7 +222,7 @@ export const PROGRAM_PATH = [
     summary: "Track the CPA engagement, fieldwork, and evidence packet.",
     sections: [
       { id: "engagement", title: "Engagement", description: "Record the actual CPA engagement, formal scope and dates, requests, and management responses.", steps: ["Create the Audit after the CPA firm is engaged.", "Record the firm-agreed type, scope, systems, criteria, and dates.", "Track incoming requests and approved response material."], types: ["audit", "audit-request"], defaultOpen: true },
-      { id: "fieldwork", title: "Fieldwork", description: "Prepare management documents, reconcile Type 2 populations, review both evidence paths, support testing, and build the indexed packet.", steps: ["Initialize engagement-specific management documents and populations.", "Review dated FileGRC operating records and verified Evidence Artifacts for the formal period.", "Reconcile complete populations, link samples, and resolve fieldwork requests and Findings.", "Build the packet from a clean Git revision; it includes FileGRC records, Markdown, Evidence Artifacts, attachments, indexes, history, and checksums."], types: ["audit-population", "control-test"], utility: "audit-packet", defaultOpen: true }
+      { id: "fieldwork", title: "Fieldwork", description: "Prepare audit-specific Documents, reconcile Type 2 populations, review both evidence paths, support testing, and build the indexed packet.", steps: ["Initialize and complete engagement-specific management Documents and populations.", "Approve and activate each audit-specific Document only when its engagement facts and timing are final.", "Review dated FileGRC operating records and verified Evidence Artifacts for the formal period.", "Reconcile complete populations, link samples, and resolve fieldwork requests and Findings.", "Build the packet from a clean Git revision; it includes FileGRC records, Markdown, Evidence Artifacts, attachments, indexes, history, and checksums."], types: ["audit-population", "control-test"], relatedLinks: [{ type: "document", label: "Audit-specific Documents", href: "#/resources/document?stage=audit&documentScope=audit" }], utility: "audit-packet", defaultOpen: true }
     ],
     resourceTypes: ["audit", "audit-request", "audit-population", "control-test"],
     utilities: [