filegrc 0.9.1 → 0.10.0

package/src/model-migration.js

@@ -3,7 +3,9 @@ import { applyModelMigrationBatch, applyResourceBatch, contentRevision } from ".
 import { loadWorkspace } from "./workspace.js";
 import { ACTIVE_MODEL_VERSION, loadModel } from "../model/index.js";
 import { legacyCoverage } from "./coverage.js";
-import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { resolveDataPath } from "./paths.js";
 import { markdownEntries } from "./resource-markdown.js";
 
@@ -895,7 +897,8 @@ export async function planModelMigration(input = process.cwd(), options = {}) {
       : sourceVersion === "2" ? "3"
         : sourceVersion === "3" ? "4"
           : sourceVersion === "4" ? "5"
-            : ACTIVE_MODEL_VERSION;
+            : sourceVersion === "5" ? "6"
+              : ACTIVE_MODEL_VERSION;
   if (sourceVersion === requestedTarget) return emptyPlan(sourceVersion, requestedTarget);
   if (sourceVersion === "1" && requestedTarget === "2") {
     return planV1ToV2Migration(input, options);
@@ -909,20 +912,24 @@ export async function planModelMigration(input = process.cwd(), options = {}) {
   if (sourceVersion === "4" && requestedTarget === "5") {
     return planV4ToV5Migration(loaded, options);
   }
-  if (sourceVersion === "5" && requestedTarget === ACTIVE_MODEL_VERSION) {
+  if (sourceVersion === "5" && requestedTarget === "6") {
     return planV5ToV6Migration(loaded);
   }
+  if (sourceVersion === "6" && requestedTarget === ACTIVE_MODEL_VERSION) {
+    return planV6ToV7Migration(loaded);
+  }
   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 one version at a time through model v6."
+      + `Preview and apply \`npx filegrc migrate --to-model 2\`, then migrate one version at a time through model v${ACTIVE_MODEL_VERSION}.`
     );
   }
   throw new Error(`Model migration does not support v${sourceVersion} to v${requestedTarget}.`);
 }
 
 export async function migrateModel(input = process.cwd(), options = {}) {
-  const plan = await planModelMigration(input, options);
+  const loaded = await loadWorkspace(input);
+  const plan = await planModelMigration(loaded.root, options);
   if (plan.sourceModelVersion === plan.targetModelVersion) {
     return { ...plan, applied: false };
   }
@@ -932,18 +939,44 @@ export async function migrateModel(input = process.cwd(), options = {}) {
       + "and resolve every missing value, conflict, manual action, and unsupported change."
     );
   }
+  const migrationReportPath = await persistMigrationReport(loaded.root, plan);
   if (plan.sourceModelVersion === "1" && plan.targetModelVersion === "2") {
-    return migrateV1ToV2(input, options);
+    return { ...await migrateV1ToV2(loaded.root, options), migrationReportPath };
   }
-  const result = await applyModelMigrationBatch(input, plan.changes);
+  const result = await applyModelMigrationBatch(loaded.root, plan.changes);
   return {
     ...plan,
     applied: true,
+    migrationReportPath,
     result,
-    postMigrationAssessment: await postMigrationAssessment(input)
+    postMigrationAssessment: await postMigrationAssessment(loaded.root)
   };
 }
 
+async function persistMigrationReport(root, plan) {
+  const relativePath = `.filegrc/migrations/model-v${plan.sourceModelVersion}-to-v${plan.targetModelVersion}.json`;
+  const directory = join(root, ".filegrc", "migrations");
+  const path = join(root, relativePath);
+  const temporaryPath = `${path}.${randomUUID()}.tmp`;
+  await mkdir(directory, { recursive: true });
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify({
+      schemaVersion: 1,
+      sourceModelVersion: plan.sourceModelVersion,
+      targetModelVersion: plan.targetModelVersion,
+      summary: plan.summary,
+      classifications: plan.classifications,
+      migrationReport: plan.migrationReport || null,
+      fileDiff: plan.fileDiff
+    }, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
+  return relativePath;
+}
+
 async function planV2ToV3Migration(loaded) {
   if (!loaded.workspace?.id) {
     throw new Error("Model migration requires a valid Workspace record.");
@@ -1312,7 +1345,7 @@ async function planV3ToV4Migration(loaded, options = {}) {
         ? [{
             systemId: targetIds[0],
             roles: derivedComponentRoles(record, loaded.resources),
-            rationale: `Migrated from v3 System "${record.title}" because it was recorded as part of or support for this bounded System.`
+            rationale: `Supports the bounded System "${byId.get(targetIds[0])?.title || targetIds[0]}".`
           }]
         : [];
     if (!uses.length) {
@@ -1477,6 +1510,7 @@ async function planV3ToV4Migration(loaded, options = {}) {
       componentIds: [...systemKinds].filter(([, kind]) => kind === "component").map(([id]) => id),
       classificationIds: [...classifications.values()],
       informationTypeIds: [...informationTypes.values()],
+      unmappedLegacyFields: collectV4LegacyFields(loaded.resources, systemKinds),
       relationshipUpdates: updates.filter((record) => record.type !== "workspace").map(({ id, type }) => ({ id, type }))
     },
     summary: {
@@ -1847,6 +1881,159 @@ async function planV5ToV6Migration(loaded) {
   };
 }
 
+async function planV6ToV7Migration(loaded) {
+  if (!loaded.workspace?.id) throw new Error("Model migration requires a valid Workspace record.");
+  const targetModel = loadModel("7");
+  const revisions = new Map(loaded.entries.map((entry) => [entry.record.id, contentRevision(entry.source)]));
+  const automatic = [];
+  const unsupported = [];
+  const missing = [];
+  const manualActions = [];
+  const updates = [];
+  const historicalActivationIds = [];
+  const trainingReactivation = [];
+  const preservedTrainingHistoryIds = [];
+  const purifiedNarrativeIds = [];
+  const removedMigrationExtensions = [];
+  const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+
+  for (const original of loaded.resources) {
+    const record = structuredClone(original);
+    let changed = false;
+    if (original.type === "workspace") {
+      record.dataModelVersion = "7";
+      changed = true;
+      automatic.push(classifiedChange("automatic", original.id, "dataModelVersion", "Select model v7 and keep upgrade mechanics out of compliance entities."));
+    }
+    if (original.type === "document" && original.activationBasis === "legacy-v4") {
+      record.activationBasis = "historical";
+      changed = true;
+      historicalActivationIds.push(original.id);
+      automatic.push(classifiedChange(
+        "automatic",
+        original.id,
+        "activationBasis",
+        "Replace the model-version label with the equivalent historical activation basis."
+      ));
+    }
+    if (original.type === "training" && original.activationBasis === "legacy-v5") {
+      delete record.activationBasis;
+      delete record.activatedByIds;
+      delete record.activatedOn;
+      delete record.activatedContentRevisions;
+      if (original.status === "active") {
+        trainingReactivation.push({ resourceId: original.id, priorEffectiveOn: original.effectiveOn || null });
+        record.status = "approved";
+        delete record.effectiveOn;
+      } else {
+        preservedTrainingHistoryIds.push(original.id);
+      }
+      changed = true;
+      automatic.push(classifiedChange(
+        "automatic",
+        original.id,
+        original.status === "active" ? "status" : "activationBasis",
+        original.status === "active"
+          ? "Keep the approved Training content and require management to record its next activation explicitly."
+          : "Keep the closed Training lifecycle facts without a model-version activation label."
+      ));
+    }
+    if (
+      original.type === "information-type"
+      && /^Information category migrated from the v3 dataTypes value ".+"\.$/.test(original.description || "")
+    ) {
+      record.description = `Information handled by in-scope Systems or Components under the "${original.title}" category.`;
+      changed = true;
+      purifiedNarrativeIds.push(original.id);
+      automatic.push(classifiedChange("automatic", original.id, "description", "Replace generated upgrade prose with the underlying information-handling fact."));
+    }
+    if (original.type === "component" && Array.isArray(original.systemUses)) {
+      let systemUsesPurified = false;
+      record.systemUses = original.systemUses.map((use) => {
+        if (!/^Migrated from v3 System ".+" because it was recorded as part of or support for this bounded System\.$/.test(use.rationale || "")) return use;
+        changed = true;
+        systemUsesPurified = true;
+        purifiedNarrativeIds.push(original.id);
+        return { ...use, rationale: `Supports the bounded System "${byId.get(use.systemId)?.title || use.systemId}".` };
+      });
+      if (systemUsesPurified) automatic.push(classifiedChange("automatic", original.id, "systemUses", "Replace generated upgrade prose with the existing Component-to-System fact."));
+    }
+    if (original.type === "audit" && Array.isArray(original.subserviceTreatments)) {
+      let treatmentsPurified = false;
+      record.subserviceTreatments = original.subserviceTreatments.map((treatment) => {
+        if (treatment.rationale !== "Migrated from the explicit v3 Audit subservice scope and method; management must confirm the treatment.") return treatment;
+        changed = true;
+        treatmentsPurified = true;
+        purifiedNarrativeIds.push(original.id);
+        return { ...treatment, rationale: `This Vendor is subject to the ${treatment.method} method for this engagement.` };
+      });
+      if (treatmentsPurified) automatic.push(classifiedChange("automatic", original.id, "subserviceTreatments", "Replace generated upgrade prose with the existing engagement treatment fact."));
+    }
+    if (record.extensions?.["filegrc.migration"] !== undefined) {
+      removedMigrationExtensions.push({ resourceId: original.id, details: record.extensions["filegrc.migration"] });
+      delete record.extensions["filegrc.migration"];
+      if (!Object.keys(record.extensions).length) delete record.extensions;
+      changed = true;
+      automatic.push(classifiedChange("automatic", original.id, "extensions", "Move prior upgrade details out of the compliance record and into this migration report."));
+    }
+    if (changed) 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 v7 migration.`
+    ));
+  }
+  const ready = unsupported.length === 0;
+  return {
+    schemaVersion: 2,
+    sourceModelVersion: "6",
+    targetModelVersion: "7",
+    ready,
+    missing,
+    conflicts: [],
+    manualActions,
+    classifications: { automatic, reviewRequired: [], unsupported },
+    notes: [],
+    migrationReport: {
+      historicalActivationIds,
+      trainingReactivation,
+      preservedTrainingHistoryIds,
+      purifiedNarrativeIds: [...new Set(purifiedNarrativeIds)],
+      removedMigrationExtensions
+    },
+    summary: {
+      create: 0,
+      update: updates.length,
+      automatic: automatic.length,
+      reviewRequired: 0,
+      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: "7"
+    }
+  };
+}
+
 function normalizeDocumentScopeDecision(value) {
   const candidate = typeof value === "object" && value
     ? value.workflowScope || value.scope
@@ -2085,7 +2272,7 @@ function migrateV4InformationTypes(loaded, creates, automatic, reviewRequired, u
       type: "information-type",
       title: value.title,
       status: classificationIds.length === 1 ? "active" : "planned",
-      description: `Information category migrated from the v3 dataTypes value "${value.title}".`,
+      description: `Information handled by in-scope Systems or Components under the "${value.title}" category.`,
       ...(classificationIds.length === 1 ? { classificationId: classificationIds[0] } : {})
     });
     result.set(key, id);
@@ -2113,13 +2300,7 @@ function migrateBoundedSystem(record, informationTypes, classifications) {
     continuityObjectives: record.continuityObjectives,
     statusTransition: record.statusTransition,
     tags: record.tags,
-    extensions: mergeMigrationExtension(record.extensions, {
-      ...(record.environment ? { environment: record.environment } : {}),
-      ...(record.vendorId ? { vendorId: record.vendorId } : {}),
-      ...(record.subserviceVendorIds ? { subserviceVendorIds: record.subserviceVendorIds } : {}),
-      ...(record.evidenceSourceKinds ? { evidenceSourceKinds: record.evidenceSourceKinds } : {}),
-      ...(record.evidenceOwnerIds ? { evidenceOwnerIds: record.evidenceOwnerIds } : {})
-    }),
+    extensions: complianceExtensions(record.extensions),
     externalIds: record.externalIds
   });
 }
@@ -2149,9 +2330,7 @@ function migrateComponent(record, systemUses, informationTypes, classifications)
     continuityObjectives: record.continuityObjectives,
     statusTransition: record.statusTransition,
     tags: record.tags,
-    extensions: mergeMigrationExtension(record.extensions, {
-      ...(record.subserviceVendorIds ? { subserviceVendorIds: record.subserviceVendorIds } : {})
-    }),
+    extensions: complianceExtensions(record.extensions),
     externalIds: record.externalIds
   });
 }
@@ -2165,10 +2344,8 @@ function componentKind(value, vendorId) {
 
 function migrateV4Vendor(record, informationTypes, classifications, reviewRequired) {
   const migrated = { ...record };
-  const legacy = {};
   for (const field of ["service", "subprocessor", "backupVendorId"]) {
     if (!Object.hasOwn(migrated, field)) continue;
-    legacy[field] = migrated[field];
     delete migrated[field];
     reviewRequired.push(classifiedChange(
       "review-required",
@@ -2184,7 +2361,7 @@ function migrateV4Vendor(record, informationTypes, classifications, reviewRequir
   migrated.informationTypeIds = normalizedInformationTypeIds(record.dataTypes, informationTypes);
   delete migrated.dataTypes;
   if (record.classificationId) migrated.classificationId = classifications.get(record.classificationId);
-  migrated.extensions = mergeMigrationExtension(record.extensions, legacy);
+  migrated.extensions = complianceExtensions(record.extensions);
   if (!Object.keys(migrated.extensions || {}).length) delete migrated.extensions;
   return migrated;
 }
@@ -2291,7 +2468,7 @@ function rewriteV4SystemRelationships(record, context) {
           vendorId,
           componentIds,
           method,
-          rationale: "Migrated from the explicit v3 Audit subservice scope and method; management must confirm the treatment."
+          rationale: `This Vendor is subject to the ${method} method for this engagement.`
         });
         context.reviewRequired.push(classifiedChange("review-required", record.id, "subserviceTreatments", "Confirm each migrated audit-time subservice treatment and rationale."));
       } else requireComponentDecision(record, "subserviceVendorIds", context, `Choose the Components and audit-time treatment for Vendor "${vendorId}".`);
@@ -2312,16 +2489,29 @@ function normalizedInformationTypeIds(values, informationTypes) {
   return [...new Set((values || []).map((value) => informationTypes.get(String(value).trim().toLowerCase())).filter(Boolean))];
 }
 
-function mergeMigrationExtension(existing, legacy) {
-  const useful = Object.fromEntries(Object.entries(legacy || {}).filter(([, value]) => value !== undefined));
-  if (!Object.keys(useful).length) return existing;
-  return {
-    ...(existing || {}),
-    "filegrc.migration": {
-      ...(existing?.["filegrc.migration"] || {}),
-      v3: useful
-    }
-  };
+function complianceExtensions(existing) {
+  if (!existing) return undefined;
+  const result = { ...existing };
+  delete result["filegrc.migration"];
+  return Object.keys(result).length ? result : undefined;
+}
+
+function collectV4LegacyFields(resources, systemKinds) {
+  return resources.flatMap((record) => {
+    const fieldNames = record.type === "system"
+      ? systemKinds.get(record.id) === "system"
+        ? ["environment", "vendorId", "subserviceVendorIds", "evidenceSourceKinds", "evidenceOwnerIds"]
+        : ["subserviceVendorIds"]
+      : record.type === "vendor"
+        ? ["service", "subprocessor", "backupVendorId"]
+        : [];
+    const fields = Object.fromEntries(fieldNames
+      .filter((field) => Object.hasOwn(record, field))
+      .map((field) => [field, record[field]]));
+    const priorMigrationDetails = record.extensions?.["filegrc.migration"];
+    if (priorMigrationDetails !== undefined) fields.priorMigrationDetails = priorMigrationDetails;
+    return Object.keys(fields).length ? [{ resourceId: record.id, resourceType: record.type, fields }] : [];
+  });
 }
 
 function cleanUndefined(value) {

package/src/obligations.js

@@ -37,6 +37,11 @@ const COMPLETION_TIMESTAMP_FIELDS = [
   "deprovisionedOn"
 ];
 const MAX_PLANNED_ITEMS = 10_000;
+const SCAFFOLDED_COMPLETION_TYPES = new Set([
+  "access-review", "attestation", "backup-test", "control-activity", "control-test",
+  "evidence", "exercise", "meeting", "penetration-test", "policy-review",
+  "risk-assessment", "vendor-review", "vulnerability-scan"
+]);
 
 export function planObligations(resources, options = {}) {
   const records = resources.map((item) => item?.record ?? item).filter(Boolean);
@@ -101,7 +106,7 @@ export function planObligations(resources, options = {}) {
         eventRiskLevels: obligation.eventRiskLevels || [],
         templateResourceId: obligation.templateResourceId || null,
         completionResourceTypes: expectedCompletionTypes,
-        completionType: activity.completionType,
+        completionType: preferredCompletionType(activity, obligation, byId),
         completionProfile: activity.completionProfile || null,
         programStatus,
         window: normalizedEventWindow(obligation.window)
@@ -155,7 +160,7 @@ export function planObligations(resources, options = {}) {
         controlIds: obligation.controlIds || [],
         scopeResourceIds: obligation.scopeResourceIds || [],
         completionResourceTypes: expectedCompletionTypes,
-        completionType: activity.completionType,
+        completionType: preferredCompletionType(activity, obligation, byId),
         completionProfile: activity.completionProfile || null,
         completionResourceIds: completions.map((record) => record.id),
         status,
@@ -313,6 +318,7 @@ export async function completeObligationOccurrence(input, options) {
   ));
   if (!obligation) throw new Error(`Obligation "${options?.obligationId ?? ""}" was not found.`);
   assertExpectedCompletionType(obligation, options?.record, loaded.model);
+  assertAttestationCompletionScope(obligation, options.record, loaded.resources);
   return createResourceAndLink(loaded.root, options.record, {
     type: "obligation",
     id: obligation.id,
@@ -343,7 +349,10 @@ export async function scaffoldObligationCompletion(input, options = {}) {
     ? plannedActionForScaffold(loaded, action, completedOn)
     : plannedOccurrenceForScaffold(loaded, obligation, options.windowStart, completedOn);
   const activity = obligationActivity(loaded.model, obligation.activityType);
-  const type = activity.completionType;
+  const type = item.completionType || preferredCompletionType(activity, {
+    ...obligation,
+    subjectResourceIds: item.subjectResourceIds || []
+  }, new Map(loaded.resources.map((record) => [record.id, record])));
   if (!type) throw new Error(`Obligation "${obligation.id}" has no configured completion resource type.`);
 
   const mutation = scaffoldResourceMutation(
@@ -369,10 +378,14 @@ export async function scaffoldObligationCompletion(input, options = {}) {
       activityType: obligation.activityType,
       completionResourceType: type,
       completionProfile: activity.completionProfile || null,
+      workItemStatus: item.status,
+      programStatus: item.programStatus || null,
       requiredFacts: loaded.model.completionProfiles?.[activity.completionProfile]?.requiredFacts || [],
       dueWindowStart: item.dueWindowStart || null,
       dueWindowEnd: item.dueWindowEnd || null,
-      instructions: "Replace every null or empty required value with the actual work performed. Keep the actual completion date and time, actors, result, scope, independent review, and supporting evidence. This revision makes the completed write safe against a stale Work Queue item."
+      instructions: item.status === "proposed" || item.programStatus === "proposed"
+        ? "This work is still a proposal. Resolve its governing Policy, Control, owner, and completion profile before recording completion."
+        : "Replace every null or empty required value with the actual work performed. Keep the actual completion date and time, actors, result, scope, independent review, and supporting evidence. This revision makes the completed write safe against a stale Work Queue item."
     }
   };
 }
@@ -394,6 +407,7 @@ export async function completeObligationAction(input, options) {
   assertExpectedCompletionType(obligation, options?.record, loaded.model);
   const completedOn = requireDate(options?.completedOn, "completion date");
   const event = loaded.resources.find((record) => record.type === "obligation-event" && record.id === action.sourceResourceId);
+  assertAttestationCompletionScope(obligation, options.record, loaded.resources, event);
   if (event?.occurredOn && completedOn < event.occurredOn) {
     throw new Error("The action completion date cannot be before its policy event date.");
   }
@@ -456,6 +470,28 @@ function assertExpectedCompletionType(obligation, record, model) {
   }
 }
 
+function assertAttestationCompletionScope(obligation, record, resources, event = null) {
+  if (record?.type !== "attestation") return;
+  const byId = new Map(resources.map((candidate) => [candidate.id, candidate]));
+  const eventPeople = (event?.subjectResourceIds || []).filter((id) => byId.get(id)?.type === "person");
+  const expectedPeople = eventPeople.length
+    ? eventPeople
+    : (obligation.scopeResourceIds || []).filter((id) => byId.get(id)?.type === "person");
+  if (expectedPeople.length && !expectedPeople.includes(record.personId)) {
+    throw new Error(`Attestation personId must name the Person in scope for Obligation "${obligation.id}".`);
+  }
+  const primarySubjects = [obligation.templateResourceId, ...(obligation.scopeResourceIds || [])]
+    .filter((id) => ["policy", "document", "training", "action-item"].includes(byId.get(id)?.type));
+  const allowedSubjects = new Set(primarySubjects.length ? primarySubjects : obligation.policyIds || []);
+  const actualSubjects = new Set(record.subjectResourceIds || []);
+  if (
+    actualSubjects.size !== allowedSubjects.size
+    || [...actualSubjects].some((id) => !allowedSubjects.has(id))
+  ) {
+    throw new Error(`Attestation subjects must name the exact authored content in scope for Obligation "${obligation.id}".`);
+  }
+}
+
 function plannedOccurrenceForScaffold(loaded, obligation, windowStart, completedOn) {
   const start = requireDate(windowStart, "occurrence window start");
   const plan = planObligations(loaded.resources, {
@@ -489,6 +525,7 @@ function plannedActionForScaffold(loaded, action, completedOn) {
 function applyCompletionScaffoldDefaults(record, context) {
   const { loaded, item, obligation, completedOn, activity } = context;
   const program = resolveProgram(loaded);
+  const byId = new Map(loaded.resources.map((candidate) => [candidate.id, candidate]));
   const responsiblePeople = currentPeopleForParties(loaded.resources, item.ownerIds || []);
   if (!responsiblePeople.length) {
     throw new Error(`Obligation "${obligation.id}" needs an active owner whose Appointment or Team resolves to a current Person.`);
@@ -554,19 +591,27 @@ function applyCompletionScaffoldDefaults(record, context) {
       evidenceIds: [],
       approvedOn: completedOn
     }),
-    attestation: () => ({
-      status: "completed",
-      subjectResourceIds: [...new Set([
+    attestation: () => {
+      const personId = (item.subjectResourceIds || []).find((id) => byId.get(id)?.type === "person")
+        || (obligation.scopeResourceIds || []).find((id) => byId.get(id)?.type === "person");
+      const primarySubjectIds = [...new Set([
         obligation.templateResourceId,
         ...(obligation.scopeResourceIds || [])
-      ].filter(Boolean))],
-      personId: responsiblePeople[0],
-      attestationKind: obligation.activityType || "completion",
-      assignedOn: item.dueWindowStart || completedOn,
-      dueOn: item.dueWindowEnd || completedOn,
-      completedOn,
-      attestationMethod: "git-approval"
-    }),
+      ].filter((id) => ["policy", "document", "training", "action-item"].includes(byId.get(id)?.type)))];
+      const subjectResourceIds = primarySubjectIds.length ? primarySubjectIds : [...(obligation.policyIds || [])];
+      if (!personId) throw new Error("An Attestation completion needs the Person who made the acknowledgement or completed the training.");
+      if (!subjectResourceIds.length) throw new Error("An Attestation completion needs the exact Policy, Document, Training, or Action Item content acknowledged.");
+      return {
+        status: "completed",
+        subjectResourceIds,
+        personId,
+        attestationKind: obligation.activityType || "completion",
+        assignedOn: item.dueWindowStart || completedOn,
+        dueOn: item.dueWindowEnd || completedOn,
+        completedOn,
+        attestationMethod: "git-approval"
+      };
+    },
     "access-review": () => {
       if (!systemIds.length) throw new Error("An Access Review completion needs an active in-scope System.");
       return {
@@ -621,22 +666,32 @@ function applyCompletionScaffoldDefaults(record, context) {
       evidenceIds: [],
       coverage
     }),
-    "control-activity": () => ({
-      ...common,
-      profileId: activity.completionProfile || obligation.activityType,
-      obligationId: obligation.id,
-      controlIds: item.controlIds || obligation.controlIds || [],
-      scopeResourceIds: (item.scopeResourceIds || obligation.scopeResourceIds || []).length
-        ? (item.scopeResourceIds || obligation.scopeResourceIds)
-        : [program.id],
-      performerIds: responsiblePeople,
-      completedAt: timestamp,
-      method: "",
-      result: "",
-      reviewerIds,
-      reviewedOn: completedOn,
-      ownerIds: item.ownerIds || obligation.ownerIds || []
-    }),
+    "control-activity": () => {
+      const allowedScopeTypes = new Set(
+        loaded.model.resources["control-activity"].fields.scopeResourceIds.relation || []
+      );
+      const requestedScopeIds = item.subjectResourceIds || item.scopeResourceIds || obligation.scopeResourceIds || [];
+      const validScopeIds = requestedScopeIds.filter((id) => allowedScopeTypes.has(byId.get(id)?.type));
+      const fallbackScopeIds = systemIds.length
+        ? systemIds
+        : (item.controlIds || obligation.controlIds || []).filter((id) => allowedScopeTypes.has(byId.get(id)?.type));
+      return {
+        ...common,
+        profileId: activity.completionProfile || obligation.activityType,
+        obligationId: obligation.id,
+        controlIds: item.controlIds || obligation.controlIds || [],
+        scopeResourceIds: validScopeIds.length
+          ? validScopeIds
+          : fallbackScopeIds.length ? fallbackScopeIds : [loaded.workspace.id],
+        performerIds: responsiblePeople,
+        completedAt: timestamp,
+        method: "",
+        result: "",
+        reviewerIds,
+        reviewedOn: completedOn,
+        ownerIds: item.ownerIds || obligation.ownerIds || []
+      };
+    },
     exercise: () => ({
       ...common,
       exerciseKind: item.title.toLowerCase().includes("continuity") ? "business-continuity" : "incident-response",
@@ -792,6 +847,12 @@ function planEventRun(event, actionItems, byId, asOf, now, model) {
       const completionProfile = obligation?.type === "obligation"
         ? obligationActivity(model, obligation.activityType).completionProfile || null
         : null;
+      const completionType = obligation?.type === "obligation"
+        ? preferredCompletionType(obligationActivity(model, obligation.activityType), {
+            ...obligation,
+            subjectResourceIds: event.subjectResourceIds || []
+          }, byId)
+        : null;
       const completionIds = modelSupports(model, "guided-workflow")
         ? record.completionResourceIds || []
         : [...(record.completionResourceIds || []), ...(record.evidenceIds || [])];
@@ -801,6 +862,7 @@ function planEventRun(event, actionItems, byId, asOf, now, model) {
         || matchingCompletionIds.length > 0;
       const complete = record.status === "done" && completionSatisfied;
       const window = plannedCompletionWindow(record.completionWindow);
+      const lateCompletion = complete && completionWasLate(record, matchingCompletionIds, byId, window);
       const timingStatus = complete
         ? "complete"
         : window.overdueAt && new Date(now) > new Date(window.overdueAt)
@@ -824,14 +886,17 @@ function planEventRun(event, actionItems, byId, asOf, now, model) {
         ownerIds: record.assigneeIds || [],
         policyIds: obligation?.policyIds || [],
         controlIds: obligation?.controlIds || [],
+        subjectResourceIds: event.subjectResourceIds || [],
         scopeResourceIds: obligation?.scopeResourceIds || [],
         templateResourceId: obligation?.templateResourceId || null,
         completionResourceIds: record.completionResourceIds || [],
         evidenceIds: record.evidenceIds || [],
         expectedCompletionTypes,
         completionProfile,
+        completionType,
         matchingCompletionIds,
         missingCompletion: record.status === "done" && !completionSatisfied,
+        lateCompletion,
         canceledAction: record.status === "canceled",
         recordedStatus: record.status,
         completedOn: record.completedOn || null,
@@ -870,6 +935,38 @@ function planEventRun(event, actionItems, byId, asOf, now, model) {
   };
 }
 
+function completionWasLate(action, completionIds, byId, window) {
+  if (window.dueWindowEndAt) {
+    const completedAt = completionIds
+      .map((id) => completionTimestamp(byId.get(id)))
+      .filter(Boolean)
+      .sort()[0];
+    if (completedAt) return new Date(completedAt) > new Date(window.dueWindowEndAt);
+    return !action.completedOn || action.completedOn >= window.dueWindowEndAt.slice(0, 10);
+  }
+  return Boolean(window.dueWindowEnd && action.completedOn && action.completedOn > window.dueWindowEnd);
+}
+
+function completionTimestamp(record) {
+  if (!record) return null;
+  return record.completedAt || record.occurredAt || record.collectedAt || record.verifiedAt || null;
+}
+
+function preferredCompletionType(activity, item, byId) {
+  const primary = activity.completionType;
+  const hasPersonSubject = [...(item.subjectResourceIds || []), ...(item.scopeResourceIds || [])]
+    .some((id) => byId.get(id)?.type === "person");
+  const hasAuthoredSubject = [item.templateResourceId, ...(item.scopeResourceIds || [])]
+    .some((id) => ["policy", "document", "training", "action-item"].includes(byId.get(id)?.type))
+    || (item.policyIds || []).some((id) => byId.get(id)?.type === "policy");
+  if (primary === "attestation" && (!hasPersonSubject || !hasAuthoredSubject) && activity.completionResourceTypes.includes("evidence")) {
+    return "evidence";
+  }
+  if (SCAFFOLDED_COMPLETION_TYPES.has(primary)) return primary;
+  if (activity.completionResourceTypes.includes("evidence")) return "evidence";
+  return primary;
+}
+
 function planStandaloneAction(record, byId, asOf, now) {
   const source = byId.get(record.sourceResourceId);
   const window = plannedCompletionWindow(record.completionWindow);

package/src/policy-activation.js

@@ -12,6 +12,11 @@ export async function scaffoldPolicyActivation(input = process.cwd(), options =
   ));
   const revisionById = new Map(loaded.entries.map((entry) => [entry.record.id, contentRevision(entry.source)]));
   return {
+    available: approved.length > 0,
+    message: approved.length
+      ? `${approved.length} approved ${approved.length === 1 ? "Policy is" : "Policies are"} available for the Step 3 cutover.`
+      : "No Policy is ready for activation. Finish Step 2 approval, then resolve its Step 3 implementation gaps.",
+    nextCommand: approved.length ? null : "npx filegrc program-path --next --json",
     policyIds: approved.map(({ policyId }) => policyId),
     effectiveOn: currentCalendarDate(loaded.workspace.timezone),
     expectedRevisions: Object.fromEntries(approved.map(({ policyId }) => [policyId, revisionById.get(policyId)])),