filegrc 0.9.2 → 0.11.0

package/src/program-amendment.js

@@ -0,0 +1,222 @@
+import { findResourceReferences } from "./agent.js";
+import { resourceReviewRevision, resourceReviewRevisions, retentionReviewResourceIds } from "./retention.js";
+import { loadWorkspace } from "./workspace.js";
+
+const SOURCE_TYPES = new Set(["policy", "document", "framework", "requirement", "commitment"]);
+const DIRECT_DEPENDENT_TYPES = new Set(["requirement", "commitment", "control", "requirement-mapping", "retention-schedule-item", "obligation"]);
+
+export async function planProgramAmendment(input, options = {}) {
+  const loaded = input?.resources && input?.model ? input : await loadWorkspace(input);
+  const sourceId = options.sourceResourceId;
+  const source = loaded.resources.find((record) => record.id === sourceId);
+  if (!source) throw new Error(`Source resource "${sourceId}" was not found.`);
+  if (!SOURCE_TYPES.has(source.type)) {
+    throw new Error("A program amendment source must be a Policy, Document, Framework, Requirement, or Commitment.");
+  }
+  const direct = findResourceReferences(loaded, source.id).references.filter((reference) => DIRECT_DEPENDENT_TYPES.has(reference.type));
+  const directById = new Map(direct.map((reference) => [reference.id, reference]));
+  const reviewRevision = loaded.root ? await resourceReviewRevision(loaded, source.id) : null;
+  const relatedIds = new Set([source.id, ...direct.map(({ id }) => id)]);
+  const affectedRequirementIds = new Set([
+    ...(source.type === "requirement" ? [source.id] : []),
+    ...loaded.resources.filter((record) => relatedIds.has(record.id) && record.type === "requirement").map(({ id }) => id)
+  ]);
+  for (const record of loaded.resources) {
+    if (record.type === "commitment" && (record.requirementIds || []).some((id) => affectedRequirementIds.has(id))) relatedIds.add(record.id);
+    if (record.type === "requirement-mapping" && [...(record.sourceResourceIds || []), ...(record.targetResourceIds || [])].some((id) => affectedRequirementIds.has(id))) relatedIds.add(record.id);
+  }
+  const affectedCommitmentIds = new Set([
+    ...(source.type === "commitment" ? [source.id] : []),
+    ...loaded.resources.filter((record) => relatedIds.has(record.id) && record.type === "commitment").map(({ id }) => id)
+  ]);
+  const affectedControlIds = new Set([
+    ...direct.filter(({ type }) => type === "control").map(({ id }) => id),
+    ...(source.controlIds || []).filter((id) => loaded.resources.some((record) => record.id === id && record.type === "control"))
+  ]);
+  for (const id of affectedControlIds) relatedIds.add(id);
+  for (const commitmentId of affectedCommitmentIds) {
+    const commitment = loaded.resources.find(({ id }) => id === commitmentId);
+    for (const id of [...(commitment?.systemIds || []), ...(commitment?.requirementIds || []), ...(commitment?.controlIds || [])]) relatedIds.add(id);
+    for (const id of commitment?.controlIds || []) affectedControlIds.add(id);
+  }
+  for (const record of loaded.resources) {
+    if (record.type === "requirement-mapping" && [...(record.sourceResourceIds || []), ...(record.targetResourceIds || [])].some((id) => affectedCommitmentIds.has(id))) relatedIds.add(record.id);
+    if (record.type === "retention-schedule-item" && (record.sourceResourceIds || []).some((id) => affectedCommitmentIds.has(id))) relatedIds.add(record.id);
+  }
+  const primaryMappings = loaded.resources.filter((record) => record.type === "requirement-mapping" && relatedIds.has(record.id));
+  for (const mapping of primaryMappings) {
+    for (const id of [...(mapping.sourceResourceIds || []), ...(mapping.targetResourceIds || [])]) {
+      relatedIds.add(id);
+      if (loaded.resources.find((record) => record.id === id)?.type === "control") affectedControlIds.add(id);
+    }
+  }
+  for (const record of loaded.resources) {
+    if (record.type === "requirement" && relatedIds.has(record.id)) affectedRequirementIds.add(record.id);
+  }
+  for (const record of loaded.resources) {
+    if (record.type === "control" && (record.requirementIds || []).some((id) => affectedRequirementIds.has(id))) {
+      affectedControlIds.add(record.id);
+      relatedIds.add(record.id);
+    }
+  }
+  for (const record of loaded.resources) {
+    if (record.type === "requirement-mapping" && (record.sourceResourceIds || []).some((id) => affectedControlIds.has(id))) {
+      relatedIds.add(record.id);
+      for (const id of [...(record.sourceResourceIds || []), ...(record.targetResourceIds || [])]) relatedIds.add(id);
+    }
+    if (record.type === "retention-schedule-item" && (record.sourceResourceIds || []).some((id) => affectedControlIds.has(id))) relatedIds.add(record.id);
+    if (record.type === "obligation" && (record.controlIds || []).some((id) => affectedControlIds.has(id))) relatedIds.add(record.id);
+  }
+  const related = loaded.resources.filter((record) => relatedIds.has(record.id) && record.id !== source.id);
+  const affected = related.map((record) => {
+    const relationFields = ["sourceResourceIds", "targetResourceIds", "requirementIds", "systemIds", "controlIds", "policyIds", "scopeResourceIds"].filter((field) => (
+      (record[field] || []).some((id) => relatedIds.has(id))
+    ));
+    const directReference = directById.get(record.id);
+    return {
+      type: record.type,
+      id: record.id,
+      title: record.title,
+      status: record.status,
+      field: relationFields.length === 1 ? relationFields[0] : directReference?.field || "transitive",
+      ...(relationFields.length ? { relationFields } : {})
+    };
+  });
+  const groups = {};
+  for (const record of affected) (groups[record.type] ||= []).push(record);
+  const missing = [];
+  if (["policy", "document", "framework"].includes(source.type) && !(groups.commitment || []).length) {
+    missing.push({
+      resourceType: "commitment",
+      message: "Record each externally or internally stated promise that changes the program scope or operating duties."
+    });
+  }
+  if ((source.type === "commitment" || (groups.commitment || []).length) && !(groups["requirement-mapping"] || []).length) {
+    missing.push({
+      resourceType: "requirement-mapping",
+      message: "Review how the source Commitments relate to existing Requirements and Controls. Do not assume full equivalence."
+    });
+  }
+  const mappingSources = related
+    .filter((record) => record.type === "requirement-mapping")
+    .flatMap((record) => [...(record.sourceResourceIds || []), ...(record.targetResourceIds || [])]);
+  const retentionSources = related
+    .filter((record) => record.type === "retention-schedule-item")
+    .flatMap((record) => retentionReviewResourceIds(record, loaded));
+  const currentReviewRevisions = await resourceReviewRevisions(loaded, [
+    source.id,
+    ...mappingSources,
+    ...retentionSources
+  ]);
+  const staleMappings = related.filter((record) => (
+    record.type === "requirement-mapping"
+    && record.status === "active"
+    && reviewBindingsDiffer(
+      [...new Set([...(record.sourceResourceIds || []), ...(record.targetResourceIds || [])])],
+      record.reviewedSourceRevisions,
+      currentReviewRevisions
+    )
+  ));
+  if (staleMappings.length) {
+    missing.push({
+      resourceType: "requirement-mapping",
+      resourceIds: staleMappings.map(({ id }) => id),
+      message: "Re-review each affected mapping against the current source revision before relying on it."
+    });
+  }
+  const retention = related.filter((record) => (
+    record.type === "retention-schedule-item"
+    && record.status === "active"
+    && reviewBindingsDiffer(retentionReviewResourceIds(record, loaded), record.reviewedSourceRevisions, currentReviewRevisions)
+  ));
+  if (retention.length) {
+    missing.push({
+      resourceType: "retention-schedule-item",
+      resourceIds: retention.map(({ id }) => id),
+      message: "Re-review each affected retention item and bind it to the current source revision before treating it as active."
+    });
+  }
+  return {
+    schemaVersion: 1,
+    source: {
+      type: source.type,
+      id: source.id,
+      title: source.title,
+      status: source.status,
+      reviewRevision
+    },
+    currentReviewRevisions: Object.fromEntries(currentReviewRevisions),
+    affected,
+    byResourceType: Object.fromEntries(Object.entries(groups).map(([type, records]) => [type, records.map(({ id }) => id)])),
+    reviewWork: missing,
+    commands: [
+      `npx filegrc references ${source.id} --json`,
+      "npx filegrc guide commitment --json",
+      "npx filegrc guide requirement-mapping --json",
+      "npx filegrc guide retention-schedule-item --json",
+      "npx filegrc program-readiness --json"
+    ],
+    principle: "The plan identifies affected records but never creates promises, mappings, retention periods, or deletion behavior without management review."
+  };
+}
+
+function reviewBindingsDiffer(expectedIds, reviewed = {}, current) {
+  const expected = new Set(expectedIds);
+  if (Object.keys(reviewed).length !== expected.size) return true;
+  return [...expected].some((id) => !current.get(id) || reviewed[id] !== current.get(id));
+}
+
+export async function assessProgramAmendmentReadiness(loaded) {
+  if (!loaded.model.resources["requirement-mapping"]) return [];
+  const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+  const commitments = loaded.resources.filter((record) => (
+    record.type === "commitment" && !["superseded", "retired"].includes(record.status)
+  ));
+  const sourceIds = new Set(commitments.flatMap((record) => record.sourceResourceIds || []));
+  for (const record of loaded.resources) {
+    if (["policy", "document"].includes(record.type) && record.programRole === "supporting" && !["superseded", "retired"].includes(record.status)) {
+      sourceIds.add(record.id);
+    }
+  }
+  const sourceRecords = [...new Set([...sourceIds, ...commitments.map(({ id }) => id)])]
+    .map((id) => byId.get(id))
+    .filter((record) => record && SOURCE_TYPES.has(record.type));
+  const plans = await Promise.all(sourceRecords.map((record) => (
+    planProgramAmendment(loaded, { sourceResourceId: record.id })
+  )));
+  const items = [];
+  for (const plan of plans) {
+    for (const work of plan.reviewWork.filter((candidate) => (
+      ["commitment", "requirement-mapping"].includes(candidate.resourceType)
+      && !resourceIdsPresent(candidate, loaded)
+    ))) {
+      const id = `program-amendment-${plan.source.id}-${work.resourceType}`;
+      if (items.some((item) => item.id === id)) continue;
+      items.push({
+        id,
+        status: "action",
+        title: work.resourceType === "commitment" ? `Record commitments from ${plan.source.title}` : `Map commitments affected by ${plan.source.title}`,
+        message: work.message,
+        resourceType: plan.source.type,
+        resourceId: plan.source.id,
+        createResourceType: work.resourceType,
+        sourceResourceIds: work.resourceType === "commitment"
+          ? [plan.source.id]
+          : plan.byResourceType.commitment || (plan.source.type === "commitment" ? [plan.source.id] : []),
+        commands: [
+          `npx filegrc scaffold ${work.resourceType} --title ${shellArgument(work.resourceType === "commitment" ? `Commitment from ${plan.source.title}` : `Mapping for ${plan.source.title}`)}`,
+          `npx filegrc program-amendment ${plan.source.id} --json`
+        ]
+      });
+    }
+  }
+  return items;
+}
+
+function shellArgument(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function resourceIdsPresent(work, loaded) {
+  return (work.resourceIds || []).some((id) => loaded.resources.some((record) => record.id === id));
+}

package/src/program-lifecycle.js

@@ -22,7 +22,7 @@ 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") {
+  if (["legacy-v4", "historical"].includes(document.activationBasis)) {
     return document.workflowScope === "engagement"
       && Boolean(document.approvedOn && document.approvedContentRevisions);
   }

package/src/program-path.js

@@ -11,6 +11,7 @@ export const RESOURCE_INSTRUCTIONS = {
   framework: "Confirm the criteria framework and version used for the program.",
   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.",
+  "requirement-mapping": "Record a reviewed relationship among Requirements, Commitments, and Controls. Choose the comparison method and relationship explicitly, explain the rationale, and bind the review to every mapped source revision.",
   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: "Complete required program Documents 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 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.",
@@ -19,6 +20,7 @@ export const RESOURCE_INSTRUCTIONS = {
   "risk-assessment": "Complete and approve an assessment of the risks to the in-scope service, systems, vendors, and commitments.",
   risk: "Record each risk identified by an assessment or operating activity. Assign an owner, rate it, document the chosen response, and link the Controls that treat it from the Risk record.",
   obligation: "Review the recurring work proposed by effective policies. Confirm who owns it, when it is due, and what proof completion requires.",
+  "retention-schedule-item": "Use one structured row for each reviewed retention rule. Name its Information Types, scope, cutoff, period, disposition, sources, owner, and approval. Keep unknown organization values planned for management review.",
   "obligation-event": "When a policy-triggering event occurs, record it here and complete the actions filegrc creates for it.",
   "policy-review": "Record scheduled and change-driven reviews of policies and governed documents, including the decision and any follow-up.",
   meeting: "Record required oversight meetings, including attendees, decisions, minutes, and follow-up work.",
@@ -53,11 +55,13 @@ export const RESOURCE_PAGE_SUMMARIES = {
   framework: "Confirm the SOC 2 framework.",
   requirement: "Decide which SOC 2 criteria apply.",
   commitment: "Record customer promises that affect scope.",
+  "requirement-mapping": "Review how supplemental promises relate to Requirements and Controls.",
   vendor: "List material external providers.",
   system: "Define the service boundary.",
   component: "Connect each material Component to a System.",
   classification: "Define handling levels.",
   "information-type": "Define information categories.",
+  "retention-schedule-item": "Review each structured retention rule.",
   policy: "Tailor the starter Policy and have someone other than its owner approve it.",
   document: "Adapt and approve plans.",
   control: "Describe each Control and its evidence source.",
@@ -77,21 +81,19 @@ export const PROGRAM_PATH = [
     summary: "Name the owners, criteria, service, Systems, and providers in scope.",
     sections: [
       { id: "ownership", title: "Program Ownership", description: "Confirm the people, appointments, and teams that own, approve, review, and operate the program.", steps: ["Confirm the initial program lead’s actual job title and the separate Policy Owner Appointment.", "Add the organization’s real appointments, reviewers, and operators.", "Review the starter Security and Risk Oversight team, its members, and its chair.", "Add other teams only when the organization assigns shared responsibility to them."], types: ["person", "appointment", "team"], defaultOpen: true },
-      { id: "criteria", title: "Program and Criteria", description: "Define the Program, confirm its Frameworks, record Program-scoped Requirement applicability, and connect customer commitments that shape the System or Control design.", steps: ["Confirm the Program goal, owners, risk method, and candidate period.", "Review the included Security criteria references and record each applicability decision on the Program.", "Record customer commitments and keep optional criteria out until the company chooses to add them."], types: ["program", "framework", "requirement", "commitment"], defaultOpen: true },
+      { id: "criteria", title: "Program and Criteria", description: "Define the Program, confirm its Frameworks, record Program-scoped Requirement applicability, and connect customer commitments that shape the System or Control design.", steps: ["Confirm the Program goal, owners, risk method, and candidate period.", "Review the included Security criteria references and record each applicability decision on the Program.", "Record customer commitments and reviewed mappings. Keep optional criteria out until the company chooses to add them."], types: ["program", "framework", "requirement", "commitment", "requirement-mapping"], defaultOpen: true },
       { id: "boundary", title: "System Boundary", description: "Start with the bounded System. Add Components that materially deliver the service, support Controls, produce authoritative Evidence, or support relevant operations. Keep Vendor relationships and specific Assets separate.", steps: ["Create the complete bounded System and select it on the Program.", "Add only relevant Components, with a role and rationale for each System use.", "Create Vendors for material external provider relationships and link supplied Components when factual.", "Normalize Information Types and Classifications used by the System, Components, Vendors, Risks, and Evidence Artifacts."], types: ["system", "component", "vendor", "classification", "information-type"], defaultOpen: false }
     ],
-    resourceTypes: ["person", "appointment", "team", "program", "framework", "requirement", "commitment", "system", "component", "vendor", "classification", "information-type"],
+    resourceTypes: ["person", "appointment", "team", "program", "framework", "requirement", "commitment", "requirement-mapping", "system", "component", "vendor", "classification", "information-type"],
     commands: [
       "filegrc setup",
       "filegrc guide person --json",
       "filegrc guide appointment --json",
       "filegrc guide system --json",
       "filegrc guide component --json",
-      "filegrc review-collection person --scaffold",
-      "filegrc review-collection framework --scaffold",
+      "filegrc guide requirement-mapping --json",
       "filegrc review-collection vendor --scaffold",
-      "filegrc review-collection system --scaffold",
-      "filegrc review-collection component --scaffold",
+      "filegrc review-collection information-type --scaffold",
       "filegrc list system --json"
     ]
   },
@@ -123,15 +125,18 @@ 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: "Implement approved requirements, configure Obligations, activate approved program content, finish authoritative evidence sources, then activate the Policies at 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.", "Review and 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 program Document or Training record, then activate the unchanged approved revisions with separate activation dates and bindings.", "Use the activation review to inspect planned or partial Controls, inactive governed content, 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."], types: ["control", "complementary-control", "obligation"], defaultOpen: true }
+      { id: "catalog", title: "Control Catalog", description: "Implement approved requirements, configure retention and Obligations, activate approved program content, finish authoritative evidence sources, then activate the Policies at 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.", "Review every Retention Schedule Item against current information uses and approved sources. Do not infer periods or disposition behavior.", "Review and 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 program Document or Training record, then activate the unchanged approved revisions with separate activation dates and bindings.", "Use the activation review to inspect planned or partial Controls, inactive governed content, 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."], types: ["control", "complementary-control", "retention-schedule-item", "obligation"], defaultOpen: true }
     ],
-    resourceTypes: ["control", "complementary-control", "obligation"],
+    resourceTypes: ["control", "complementary-control", "retention-schedule-item", "obligation"],
     commands: [
       "filegrc guide control --json",
       "filegrc list control --json",
       "filegrc get CONTROL_ID --mutation",
       "filegrc guide obligation --json",
+      "filegrc guide retention-schedule-item --json",
+      "filegrc review-collection retention-schedule-item --scaffold",
       "filegrc list obligation --json",
+      "filegrc review-collection component --scaffold",
       "filegrc review-collection complementary-control --scaffold",
       "filegrc activate-content --scaffold",
       "filegrc activate-policies --scaffold",

package/src/program-readiness.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { modelSupports } from "../model/index.js";
+import { applicabilityReviewIsCurrent } from "./applicability-scope.js";
 import { assessRequiredAppointments } from "./appointments.js";
 import { assessCollectionReviews } from "./collection-review.js";
 import { openPlaceholderCount, substantiveMarkdown } from "./content-readiness.js";
@@ -15,7 +16,10 @@ import {
 } from "./program-lifecycle.js";
 import { currentPartyPeople, partiesIndependent, partyPeople } from "./parties.js";
 import { assessPolicyLibraryUpgrades } from "./policy-library.js";
+import { assessProgramAmendmentReadiness } from "./program-amendment.js";
 import { programComponents, resolveProgram, selectedRequirementIds } from "./program.js";
+import { assessRequirementMappingReadiness } from "./requirement-mapping.js";
+import { assessRetentionReadiness } from "./retention.js";
 import { markdownEntries } from "./resource-markdown.js";
 import {
   missingSoc2References,
@@ -52,6 +56,12 @@ export async function assessProgramReadiness(input, options = {}) {
     .map(collectionReviewReadinessItem));
   const sourceStage = await evidenceSourcesStage(scope, byId, loaded.model, readMarkdown);
   controlStage.items.push(...sourceStage.items);
+  controlStage.items.push(...await assessRetentionReadiness(loaded, program, {
+    informationTypesReviewed: collectionReviews.find(({ resourceType }) => resourceType === "information-type")?.complete === true
+  }));
+  controlStage.items.push(...collectionReviews
+    .filter(({ resourceType }) => ["component", "retention-schedule-item"].includes(resourceType))
+    .map(collectionReviewReadinessItem));
   const governedContent = await governedContentItems(scope, records, byId, readMarkdown, asOf, loaded.model);
   controlStage.items.push(...governedContent.items);
   const policyActivations = await assessPolicyActivations(
@@ -65,15 +75,18 @@ export async function assessProgramReadiness(input, options = {}) {
   );
   controlStage.items.push(...policyActivations.map(policyActivationItem));
   controlStage.description = `Each implemented Control needs an owner, actual procedure, scope, operation pattern, mappings, an implementation date, enabled Obligations, and complete authoritative source ${modelSupports(loaded.model, "component-sources") ? "Components" : "Systems"}. Activate unchanged approved program Documents and Training after their requirements are implemented, then activate approved Policies at the implementation cutover.`;
-  const evidenceGateStages = [
-    scopeStage(
+  const scopeReadinessStage = scopeStage(
       program,
       scope,
       records,
       byId,
       loaded.model,
-      collectionReviews.filter(({ resourceType }) => resourceType !== "complementary-control")
-    ),
+      collectionReviews.filter(({ resourceType }) => ["person", "framework", "system", "vendor", "information-type"].includes(resourceType))
+    );
+  scopeReadinessStage.items.push(...await assessRequirementMappingReadiness(loaded));
+  scopeReadinessStage.items.push(...await assessProgramAmendmentReadiness(loaded));
+  const evidenceGateStages = [
+    scopeReadinessStage,
     policyStage,
     controlStage
   ];
@@ -81,7 +94,7 @@ export async function assessProgramReadiness(input, options = {}) {
   const evidenceReady = evidenceGateStages.every((current) => current.counts.action === 0);
   const stages = [
     ...evidenceGateStages,
-    operationStage(loaded, program, scope, records, byId, asOf, evidenceReady, loaded.model)
+    await operationStage(loaded, program, scope, records, byId, asOf, evidenceReady, loaded.model)
   ];
   finalizeStage(stages.at(-1));
   const candidateStarted = Boolean(
@@ -103,6 +116,7 @@ export async function assessProgramReadiness(input, options = {}) {
   const firstAction = items.find((current) => current.status === "action") || null;
 
   return {
+    program,
     schemaVersion: 1,
     dataModelVersion: String(loaded.model.modelVersion),
     generatedAt: options.generatedAt || new Date().toISOString(),
@@ -252,16 +266,22 @@ function scopeStage(workspace, scope, records, byId, model, collectionReviews =
   ));
 
   if (modelSupports(model, "guided-workflow")) {
-    const commitments = records.filter((record) => (
+    const allCommitments = records.filter((record) => (
       record.type === "commitment"
       && !["superseded", "retired"].includes(record.status)
-      && (record.systemIds || []).some((id) => scope.systems.some((system) => system.id === id))
     ));
+    const commitments = allCommitments.filter((record) => (
+      (record.systemIds || []).some((id) => scope.systems.some((system) => system.id === id))
+    ));
+    const unscopedCommitments = allCommitments.filter((record) => !(record.systemIds || []).length);
     const completeCommitments = commitments.filter((record) => (
       record.status === "active"
       && record.statement
       && record.effectiveOn
-      && (modelSupports(model, "program-scope") || record.applicabilityReview?.decision === "applicable")
+      && (!model.resources.commitment?.fields?.applicabilityReview || (
+        record.applicabilityReview?.decision === "applicable"
+        && applicabilityReviewIsCurrent(record.applicabilityReview, record, workspace, records, model)
+      ))
       && currentPartyPeople(record.ownerIds, byId).size > 0
       && (record.requirementIds || []).length > 0
       && (record.controlIds || []).length > 0
@@ -271,14 +291,15 @@ function scopeStage(workspace, scope, records, byId, model, collectionReviews =
     )));
     items.push(item(
       "commitments",
-      scope.systems.length && uncoveredSystems.length === 0 ? "complete" : "action",
+      scope.systems.length && uncoveredSystems.length === 0 && unscopedCommitments.length === 0 ? "complete" : "action",
       "Record service commitments and system requirements",
       scope.systems.length
-        ? `${completeCommitments.length} complete active ${completeCommitments.length === 1 ? "commitment covers" : "commitments cover"} ${scope.systems.length - uncoveredSystems.length} of ${scope.systems.length} in-scope systems.`
+        ? `${completeCommitments.length} complete active ${completeCommitments.length === 1 ? "commitment covers" : "commitments cover"} ${scope.systems.length - uncoveredSystems.length} of ${scope.systems.length} in-scope systems.${unscopedCommitments.length ? ` ${unscopedCommitments.length} Commitment${unscopedCommitments.length === 1 ? " has" : "s have"} no System scope and must be reviewed explicitly.` : ""}`
         : "Define the service boundary before recording its customer promises and approved system requirements.",
       commitments[0] || { type: "commitment" },
       {
         uncoveredSystemIds: uncoveredSystems.map(({ id }) => id),
+        unscopedCommitmentIds: unscopedCommitments.map(({ id }) => id),
         commands: [
           "npx filegrc guide commitment --json",
           "npx filegrc list commitment --workflow --json",
@@ -290,7 +311,15 @@ function scopeStage(workspace, scope, records, byId, model, collectionReviews =
   }
 
   const selectedRequirementIds = new Set(scope.requirements.map((record) => record.id));
-  const v4Decisions = new Map((workspace?.requirementApplicability || []).map((decision) => [decision.requirementId, decision.decision]));
+  const requirementById = new Map(records
+    .filter(({ type }) => type === "requirement")
+    .map((record) => [record.id, record]));
+  const v4Decisions = new Map((workspace?.requirementApplicability || [])
+    .filter((decision) => (
+      requirementById.has(decision.requirementId)
+      && applicabilityReviewIsCurrent(decision, requirementById.get(decision.requirementId), workspace, records, model)
+    ))
+    .map((decision) => [decision.requirementId, decision.decision]));
   const applicableRequirements = records.filter((record) => (
     record.type === "requirement"
     && scope.frameworks.some((framework) => framework.id === record.frameworkId)
@@ -1162,6 +1191,7 @@ async function controlsStage(scope, byId, readMarkdown, asOf, model) {
     const checks = {
       ...(model.resources.control?.fields?.applicabilityReview ? {
         applicability: control.applicabilityReview?.decision === "applicable"
+          && applicabilityReviewIsCurrent(control.applicabilityReview, control, scope.program, [...byId.values()], model)
       } : {}),
       implemented: control.status === "implemented",
       owner: (control.ownerIds || []).length > 0,
@@ -1316,7 +1346,7 @@ async function evidenceSourcesStage(scope, byId, model, readMarkdown) {
   return stage("sources", "Control Evidence Sources", `Complete the authoritative ${modelSupports(model, "component-sources") ? "Components" : "Systems"} for every selected control family before marking the Controls implemented.`, items);
 }
 
-function operationStage(loaded, workspace, scope, records, byId, asOf, evidenceReady, model) {
+async function operationStage(loaded, workspace, scope, records, byId, asOf, evidenceReady, model) {
   const goal = workspace?.assuranceGoal || "none";
   if (!evidenceReady) {
     return stage("operation", "Operate the Program", "Run the controls and preserve dated evidence after the Evidence Ready gate passes.", [
@@ -1355,7 +1385,7 @@ function operationStage(loaded, workspace, scope, records, byId, asOf, evidenceR
     ? coverageEnd(workspace.candidateCoverage)
     : null;
   const startStatus = !start ? "action" : start <= asOf ? "complete" : "later";
-  const sourceCoverage = assessSourceCoverageReadiness(loaded, scope.controls.map(({ id }) => id), workspace);
+  const sourceCoverage = await assessSourceCoverageReadiness(loaded, scope.controls.map(({ id }) => id), workspace);
   const incompleteSourceCoverage = sourceCoverage.filter(({ complete }) => !complete);
   return stage("operation", "Operate the Program", "Start the management candidate Type 2 period only after the Evidence Ready gate, then keep collection running.", [
     item(

package/src/reconciliation.js

@@ -11,7 +11,9 @@ const TRANSITIONS = {
   person: [
     {
       eventType: "person-started",
-      applies: (before, after) => after?.status === "active" && before?.status !== "active",
+      applies: (before, after) => after?.status === "active"
+        && after?.affiliation !== "external"
+        && before?.status !== "active",
       message: "Confirm whether activating this Person represents a workforce start that needs policy-event work."
     },
     {
@@ -95,16 +97,26 @@ export async function planReconciliation(input = process.cwd()) {
   const loaded = input?.resources && input?.model && input?.entries
     ? input
     : await loadWorkspace(input);
+  const headRevision = gitRevision(loaded.root);
   if (!modelSupports(loaded.model, "guided-workflow")) {
     return {
       contractVersion: 1,
-      gitRevision: gitRevision(loaded.root),
+      gitRevision: headRevision,
       changedPaths: [],
       candidates: [],
       message: "Direct-file transition reconciliation is available in model v3 and newer workspaces."
     };
   }
   const changedPaths = gitChangedPaths(loaded.root);
+  if (!headRevision) {
+    return {
+      contractVersion: 1,
+      gitRevision: null,
+      changedPaths,
+      candidates: [],
+      message: "Commit the initial workspace before FileGRC checks later direct-file changes for Policy Events."
+    };
+  }
   const currentByPath = new Map(loaded.entries.map((entry) => [
     `data/${entry.relativePath}`,
     entry
@@ -176,7 +188,7 @@ export async function planReconciliation(input = process.cwd()) {
   }
   return {
     contractVersion: 1,
-    gitRevision: gitRevision(loaded.root),
+    gitRevision: headRevision,
     changedPaths,
     candidates: candidates.sort((a, b) => a.id.localeCompare(b.id))
   };

package/src/requirement-mapping.js

@@ -0,0 +1,61 @@
+import { resourceReviewRevisions } from "./retention.js";
+
+export async function assessRequirementMappingReadiness(loaded) {
+  if (!loaded.model.resources["requirement-mapping"]) return [];
+  const mappings = loaded.resources.filter((record) => (
+    record.type === "requirement-mapping" && !["superseded", "retired"].includes(record.status)
+  ));
+  const ids = mappings.flatMap((record) => [
+    ...(record.sourceResourceIds || []),
+    ...(record.targetResourceIds || [])
+  ]);
+  const revisions = await resourceReviewRevisions(loaded, ids);
+  const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+  return mappings.map((mapping) => {
+    const mappedIds = [...new Set([
+      ...(mapping.sourceResourceIds || []),
+      ...(mapping.targetResourceIds || [])
+    ])];
+    const staleIds = mappedIds.filter((id) => (
+      !revisions.get(id) || mapping.reviewedSourceRevisions?.[id] !== revisions.get(id)
+    )).concat(Object.keys(mapping.reviewedSourceRevisions || {}).filter((id) => !mappedIds.includes(id)));
+    const structurallyComplete = mappingStructureIsComplete(mapping);
+    const complete = mapping.status === "active" && structurallyComplete && staleIds.length === 0;
+    return {
+      id: `requirement-mapping-${mapping.id}`,
+      status: complete ? "complete" : "action",
+      title: complete ? `Mapping current: ${mapping.title}` : `Review mapping: ${mapping.title}`,
+      message: mapping.status !== "active"
+        ? "This mapping is still planned. Review both sides, choose the relationship and comparison method, and bind the current revisions before activation."
+        : !structurallyComplete
+          ? "This active mapping is incomplete. Add distinct source and target records, the relationship and method, a rationale, owners, reviewer, review date, and current revision bindings."
+        : `This mapping no longer matches ${staleIds.length} mapped ${staleIds.length === 1 ? "record" : "records"}. Review it before relying on the stated relationship.`,
+      resourceType: "requirement-mapping",
+      resourceId: mapping.id,
+      staleResourceIds: staleIds,
+      commands: [
+        `npx filegrc get ${mapping.id} --mutation`,
+        `npx filegrc review-bindings ${mapping.id} --json`,
+        ...staleIds
+          .filter((id) => ["policy", "document", "framework", "requirement", "commitment"].includes(byId.get(id)?.type))
+          .map((id) => `npx filegrc program-amendment ${id} --json`)
+      ]
+    };
+  });
+}
+
+function mappingStructureIsComplete(mapping) {
+  const sourceIds = [...new Set(mapping.sourceResourceIds || [])];
+  const targetIds = [...new Set(mapping.targetResourceIds || [])];
+  return sourceIds.length > 0
+    && targetIds.length > 0
+    && !sourceIds.some((id) => targetIds.includes(id))
+    && ["equal-to", "equivalent-to", "subset-of", "superset-of", "intersects-with", "no-relationship"].includes(mapping.relationship)
+    && ["syntactic", "semantic", "functional"].includes(mapping.method)
+    && Boolean(String(mapping.rationale || "").trim())
+    && (mapping.ownerIds || []).length > 0
+    && (mapping.reviewedByIds || []).length > 0
+    && Boolean(mapping.reviewedOn)
+    && mapping.reviewedSourceRevisions
+    && typeof mapping.reviewedSourceRevisions === "object";
+}