filegrc 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filegrc",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {

package/src/agent.js

@@ -217,6 +217,9 @@ function applyModelScaffoldDefaults(record, loaded, options = {}) {
       "soc-2-type-2": "soc-2-type-2"
     }[program?.assuranceGoal];
     if (kind) record.auditKind = kind;
+    if (modelSupports(loaded.model, "reporting-route-sets") && loaded.workspace?.timezone) {
+      record.timezone = loaded.workspace.timezone;
+    }
     for (const field of ["frameworkIds", "systemIds", "requirementIds", "controlIds"]) {
       if (field === "requirementIds" && modelSupports(loaded.model, "program-scope")) {
         record[field] = (program.requirementApplicability || []).filter(({ decision }) => decision === "applicable").map(({ requirementId }) => requirementId);

package/src/audit-populations.js

@@ -0,0 +1,88 @@
+import {
+  applyResourceBatch,
+  contentRevision,
+  createResource,
+  INTERNAL_WORKFLOW_CAPABILITIES,
+  updateResource
+} from "./files.js";
+import { modelSupports } from "../model/index.js";
+import { currentCalendarDate } from "./time.js";
+import { loadWorkspace } from "./workspace.js";
+
+export async function scaffoldAuditPopulationCorrection(input, options = {}) {
+  const loaded = await loadWorkspace(input);
+  if (!modelSupports(loaded.model, "rolled-up-obligations")) {
+    throw new Error("Audit population correction requires data model v9.");
+  }
+  const entry = loaded.entries.find(({ record }) => (
+    record.type === "audit-population" && record.id === options.populationId
+  ));
+  if (!entry) throw new Error(`Audit population "${options.populationId || ""}" was not found.`);
+  if (!["reconciled", "not-applicable"].includes(entry.record.status)) {
+    throw new Error(`Audit population "${entry.record.id}" must be finalized before it can be corrected.`);
+  }
+  const correctionDate = options.asOf || currentCalendarDate(loaded.workspace.timezone);
+  const affectedControlTests = loaded.resources
+    .filter((record) => record.type === "control-test" && record.populationId === entry.record.id)
+    .map(({ id, title, status, controlId }) => ({ id, title, status, controlId }));
+  const record = {
+    ...entry.record,
+    id: `${entry.record.id}-correction-${correctionDate}`,
+    title: `${entry.record.title} correction`,
+    status: "planned",
+    supersedesId: entry.record.id
+  };
+  delete record.reconciledByIds;
+  delete record.reconciledOn;
+  delete record.conclusion;
+  return {
+    operation: "supersede",
+    record,
+    revision: contentRevision(entry.source),
+    affectedControlTests,
+    instructions: affectedControlTests.length
+      ? "Correct the population facts and link the fixed replacement export. Saving preserves the original and marks tests based on it as stale until replacement tests use this correction."
+      : "Correct the population facts, link the fixed replacement export, and record a new reconciliation. Saving preserves the original as superseded."
+  };
+}
+
+export async function saveAuditPopulation(input, options = {}) {
+  const record = options.record;
+  if (record?.type !== "audit-population") throw new Error("An Audit population record is required.");
+  const loaded = await loadWorkspace(input);
+  const existing = loaded.entries.find(({ record: current }) => current.id === record.id);
+  if (record.supersedesId) {
+    requireMutationRevision(options.expectedRevision, `Audit population "${record.supersedesId}"`);
+    if (existing) throw new Error(`Superseding Audit population "${record.id}" already exists.`);
+    const predecessor = loaded.entries.find(({ record: current }) => (
+      current.type === "audit-population" && current.id === record.supersedesId
+    ));
+    if (!predecessor) throw new Error(`Superseded Audit population "${record.supersedesId}" was not found.`);
+    if (!["reconciled", "not-applicable"].includes(predecessor.record.status)) {
+      throw new Error(`Audit population "${predecessor.record.id}" must be finalized before it can be superseded.`);
+    }
+    if (
+      predecessor.record.auditId !== record.auditId
+      || predecessor.record.populationKind !== record.populationKind
+    ) {
+      throw new Error("A correction must keep the same Audit and population kind as its predecessor.");
+    }
+    return applyResourceBatch(input, {
+      workflowCapability: INTERNAL_WORKFLOW_CAPABILITIES.auditPopulationSupersession,
+      create: [record],
+      update: [{ ...predecessor.record, status: "superseded" }],
+      contentUpdates: { [record.id]: options.content || {} },
+      expectedRevisions: { [predecessor.record.id]: options.expectedRevision }
+    });
+  }
+  if (existing) requireMutationRevision(options.expectedRevision, `Audit population "${record.id}"`);
+  return existing
+    ? updateResource(input, "audit-population", record.id, record, { expectedRevision: options.expectedRevision, content: options.content })
+    : createResource(input, record, { content: options.content });
+}
+
+function requireMutationRevision(revision, target) {
+  if (typeof revision !== "string" || revision.length === 0) {
+    throw new Error(`A revision is required when changing ${target}. Reload the resource and try again.`);
+  }
+}

package/src/audit-preparation.js

@@ -76,7 +76,7 @@ export async function assessAuditPreparation(input, options = {}) {
   const programReadiness = options.programReadiness || await assessProgramReadiness(loaded, {
     asOf: readinessAsOf,
     generatedAt: options.generatedAt,
-    programId: audit?.programId
+    programId: audit?.programId || options.programId
   });
   const documentActivations = audit && modelSupports(loaded.model, "governed-document-activation")
     ? await auditDocumentActivationAssessments(loaded, audit, byId, calendarAsOf)
@@ -942,6 +942,7 @@ function occurrenceContinuityStage(audit, records, model, asOf) {
     || record.controlIds.some((id) => selectedControlIds.has(id))
   ));
   const plan = planObligations(periodResources, {
+    programId: audit.programId,
     from: periodStart,
     asOf: periodThrough,
     through: periodThrough,
@@ -1320,7 +1321,11 @@ function populationsStage(audit, records, byId, model) {
     );
   }
   const populations = audit
-    ? records.filter((record) => record.type === "audit-population" && record.auditId === audit.id)
+    ? records.filter((record) => (
+        record.type === "audit-population"
+        && record.auditId === audit.id
+        && record.status !== "superseded"
+      ))
     : [];
   const templates = applicablePopulationTemplates(
     audit,

package/src/cli.js

@@ -4,6 +4,7 @@ import { createInterface } from "node:readline/promises";
 import { ACTIVE_MODEL_VERSION, loadModel, SUPPORTED_MODEL_VERSIONS } from "../model/index.js";
 import { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldResourceMutation } from "./agent.js";
 import { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
+import { saveAuditPopulation, scaffoldAuditPopulationCorrection } from "./audit-populations.js";
 import { createNextAuditCycle, planNextAuditCycle } from "./audit-transition.js";
 import {
   applyApplicabilityReviewWithContext,
@@ -36,12 +37,16 @@ import { generateModelDocumentation } from "./model-docs.js";
 import { migrateModel, planModelMigration } from "./model-migration.js";
 import { normalizeResourceMutation } from "./mutation.js";
 import {
+  activateObligationRule,
   completeObligationAction,
   completeObligationEvent,
   completeObligationOccurrence,
   createObligationEvent,
   planObligations,
-  scaffoldObligationCompletion
+  saveObligationOccurrence,
+  scaffoldObligationCompletion,
+  scaffoldObligationOccurrence,
+  scaffoldObligationRuleActivation
 } from "./obligations.js";
 import {
   planExternalReviewerGovernance,
@@ -53,6 +58,13 @@ import { activatePolicies, planPolicyActivation, scaffoldPolicyActivation } from
 import { applyPolicyLibraryUpgrade, assessPolicyLibraryUpgrades } from "./policy-library.js";
 import { buildAgentProgramPath } from "./program-path.js";
 import { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
+import {
+  approveReportingRouteSet,
+  assessReportingRouteSets,
+  cancelReportingRouteSet,
+  proposeReportingRouteSet,
+  scaffoldReportingRouteSet
+} from "./reporting-route-sets.js";
 import { planProgramAmendment } from "./program-amendment.js";
 import { resolveProgram } from "./program.js";
 import { resourceReviewRevisions, retentionReviewResourceIds } from "./retention.js";
@@ -79,6 +91,7 @@ const BOOLEAN_FLAGS = new Set([
   "apply",
   "check-docs",
   "complete",
+  "correct-finalized",
   "current",
   "draft",
   "help",
@@ -384,6 +397,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (command === "obligations") {
     const loaded = await loadWorkspace(root);
     const result = planObligations(loaded.resources, {
+      programId: flags.program,
       asOf: flags["as-of"] ?? currentCalendarDate(loaded.workspace.timezone),
       from: flags.from,
       through: flags.through,
@@ -406,8 +420,12 @@ export async function runCli(argv = process.argv.slice(2)) {
           item.actionItemId
             ? item.status === "blocked"
               ? `filegrc get ${item.actionItemId} --mutation`
-              : `filegrc complete-action ${item.actionItemId} --scaffold --completed-on YYYY-MM-DD`
-            : `filegrc complete ${item.obligationId} --scaffold --window-start ${item.dueWindowStart} --completed-on YYYY-MM-DD`
+              : `filegrc complete-action ${item.actionItemId} --scaffold${flags.program ? ` --program ${flags.program}` : ""} --completed-on YYYY-MM-DD`
+            : item.ruleId && ["proposed", "approved"].includes(item.ruleStatus)
+              ? `filegrc activate-obligation-rule ${item.ruleId} --scaffold`
+              : item.ruleId
+                ? `filegrc reconcile-obligation ${item.obligationId} --scaffold --window-start ${item.dueWindowStart}${flags.program ? ` --program ${flags.program}` : ""}${item.reconciliationStatus === "reconciled" ? " --correct-finalized" : ""}`
+                : `filegrc complete ${item.obligationId} --scaffold --window-start ${item.dueWindowStart}${flags.program ? ` --program ${flags.program}` : ""} --completed-on YYYY-MM-DD`
         ].join("\t"));
       }
       if (result.triggers.length) {
@@ -464,6 +482,52 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (flags["require-ready"] && !result.evidenceReady) process.exitCode = 2;
     return output;
   }
+  if (command === "reporting-route-sets") {
+    const result = await assessReportingRouteSets(root, {
+      programId: flags.program,
+      at: flags.at
+    });
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else if (!result.supported) console.log("Reporting Channel Sets are not supported by this workspace model.");
+    else console.log(result.issues.length
+      ? `${result.issues.length} Reporting Channel Set action${result.issues.length === 1 ? "" : "s"} remain.`
+      : "Reporting Channel Set requirements are covered.");
+    return result;
+  }
+  if (command === "reporting-route-set") {
+    const [action, value] = positionals;
+    if (flags.scaffold || action === "scaffold") {
+      const scaffoldAction = flags.action || (action === "scaffold" && value) || "approve";
+      const result = scaffoldReportingRouteSet({
+        action: scaffoldAction,
+        routeSetId: flags.id,
+        timezone: flags.timezone,
+        effectiveAt: flags["effective-at"],
+        proposalCommit: flags["proposal-commit"],
+        expectedRevision: flags.revision,
+        predecessorExpectedRevision: flags["predecessor-revision"]
+      });
+      console.log(JSON.stringify(result, null, 2));
+      return result;
+    }
+    if (action === "propose") {
+      const result = await withWorkflowDelta(root, () => proposeReportingRouteSet(root, { routeSetId: value, expectedRevision: flags.revision }));
+      if (flags.json) console.log(JSON.stringify(result, null, 2));
+      else console.log(`Proposed ${result.record.id}. Commit the proposal before approval.`);
+      return result;
+    }
+    if (["approve", "cancel"].includes(action)) {
+      if (!value) throw new Error(`Pass a JSON payload path for reporting-route-set ${action}.`);
+      const payload = JSON.parse(await readFile(resolve(value), "utf8"));
+      const result = action === "approve"
+        ? await withWorkflowDelta(root, () => approveReportingRouteSet(root, payload))
+        : await withWorkflowDelta(root, () => cancelReportingRouteSet(root, payload));
+      if (flags.json) console.log(JSON.stringify(result, null, 2));
+      else console.log(`${action === "approve" ? "Approved" : "Canceled"} ${result.record.id}. Commit this managed event before relying on it.`);
+      return result;
+    }
+    throw new Error("Use reporting-route-set scaffold [approve|cancel|successor], propose ROUTE_SET_ID, approve PAYLOAD.json, or cancel PAYLOAD.json.");
+  }
   if (command === "program-amendment") {
     const sourceResourceId = flags.source || positionals[0];
     if (!sourceResourceId) throw new Error("Pass a source resource ID or --source resource-id.");
@@ -557,6 +621,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       ? await withWorkflowDelta(root, () => applyReconciliation(root, {
         candidateId: flags.candidate,
         transitionFingerprint: flags.candidate,
+        programId: flags.program,
         occurredOn: flags["occurred-on"],
         occurredAt: flags["occurred-at"],
         riskLevel: flags["risk-level"],
@@ -621,12 +686,16 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "review-applicability") {
     if (flags.scaffold) {
-      const result = await scaffoldApplicabilityReview(root, { type: flags.type });
+      const result = await scaffoldApplicabilityReview(root, { type: flags.type, programId: flags.program });
       console.log(JSON.stringify(result, null, 2));
       return result;
     }
     const payload = await readSetupPayload(positionals[0]);
-    const options = { ...payload, confirmed: flags.yes === true };
+    const options = {
+      ...payload,
+      programId: flags.program || payload.programId,
+      confirmed: flags.yes === true
+    };
     const result = flags.preview
       ? await planApplicabilityReview(root, options)
       : await applyApplicabilityReviewWithContext(root, options, { includeWorkflowDelta: true });
@@ -638,7 +707,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (command === "review-collection") {
     const resourceType = positionals[0] || flags.type;
     if (flags.scaffold) {
-      const result = await scaffoldCollectionReview(root, { resourceType });
+      const result = await scaffoldCollectionReview(root, { resourceType, programId: flags.program });
       console.log(JSON.stringify(result, null, 2));
       return result;
     }
@@ -646,6 +715,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     const options = {
       ...payload,
       resourceType: resourceType || payload.resourceType,
+      programId: flags.program || payload.programId,
       confirmed: flags.yes === true
     };
     const result = flags.preview
@@ -751,6 +821,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "trigger") {
     const result = await withWorkflowDelta(root, () => createObligationEvent(root, {
+      programId: flags.program,
       eventType: positionals[0],
       occurredOn: flags["occurred-on"],
       occurredAt: flags["occurred-at"],
@@ -774,6 +845,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       start: flags.start,
       end: flags.end,
       auditId: flags.audit,
+      programId: flags.program,
       output: flags.output
     };
     const generated = flags.preview
@@ -862,6 +934,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (flags.scaffold) {
       const result = await scaffoldObligationCompletion(root, {
         obligationId,
+        programId: flags.program,
         windowStart: flags["window-start"],
         completedOn: flags["completed-on"]
       });
@@ -879,11 +952,81 @@ export async function runCli(argv = process.argv.slice(2)) {
     else console.log(`Created ${result.created.type}/${result.created.id} and linked it to obligation/${obligationId}`);
     return result;
   }
+  if (command === "activate-obligation-rule") {
+    const [ruleId, file] = positionals;
+    if (!ruleId) throw new Error("An Obligation Rule ID is required.");
+    if (flags.scaffold) {
+      const result = await scaffoldObligationRuleActivation(root, { ruleId });
+      console.log(JSON.stringify(result, null, 2));
+      return result;
+    }
+    if (!file) throw new Error("A scaffolded Obligation Rule activation payload file is required.");
+    const source = await readSetupPayload(file);
+    const payload = source.payload || source;
+    const result = await withWorkflowDelta(root, () => activateObligationRule(root, { ...payload, ruleId }));
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`Activated obligation-rule/${ruleId}`);
+    return result;
+  }
+  if (command === "reconcile-obligation") {
+    const [obligationId, file] = positionals;
+    if (!obligationId) throw new Error("An Obligation ID is required.");
+    if (flags.scaffold) {
+      const result = await scaffoldObligationOccurrence(root, {
+        obligationId,
+        programId: flags.program,
+        windowStart: flags["window-start"],
+        asOf: flags["as-of"],
+        correctFinalized: flags["correct-finalized"] === true
+      });
+      console.log(JSON.stringify(result, null, 2));
+      return result;
+    }
+    if (!file) throw new Error("A scaffolded Obligation occurrence mutation file is required.");
+    const mutation = await readMutation(file);
+    if (mutation.record?.type !== "obligation-occurrence" || mutation.record.obligationId !== obligationId) {
+      throw new Error("The mutation must contain an Obligation occurrence for the requested Obligation.");
+    }
+    const loaded = await loadWorkspace(root);
+    const existing = loaded.resources.some(({ id, type }) => id === mutation.record.id && type === "obligation-occurrence");
+    const result = await withWorkflowDelta(root, () => saveObligationOccurrence(root, {
+      record: mutation.record,
+      programId: flags.program || mutation.record.programId,
+      content: mutation.content,
+      expectedRevision: expectedRevision(flags, mutation, `obligation-occurrence/${mutation.record.supersedesId || mutation.record.id}`)
+    }));
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`${existing ? "Updated" : "Created"} obligation-occurrence/${mutation.record.id}`);
+    return result;
+  }
+  if (command === "correct-audit-population") {
+    const [populationId, file] = positionals;
+    if (!populationId) throw new Error("An Audit Population ID is required.");
+    if (flags.scaffold) {
+      const result = await scaffoldAuditPopulationCorrection(root, { populationId, asOf: flags["as-of"] });
+      console.log(JSON.stringify(result, null, 2));
+      return result;
+    }
+    if (!file) throw new Error("A scaffolded Audit Population correction payload file is required.");
+    const mutation = await readMutation(file);
+    if (mutation.record?.type !== "audit-population" || mutation.record.supersedesId !== populationId) {
+      throw new Error("The mutation must contain an Audit Population correction for the requested population.");
+    }
+    const result = await withWorkflowDelta(root, () => saveAuditPopulation(root, {
+      record: mutation.record,
+      content: mutation.content,
+      expectedRevision: expectedRevision(flags, mutation, `audit-population/${populationId}`)
+    }));
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`Created audit-population/${mutation.record.id} and superseded audit-population/${populationId}.`);
+    return result;
+  }
   if (command === "complete-action") {
     const [actionItemId, file] = positionals;
     if (flags.scaffold) {
       const result = await scaffoldObligationCompletion(root, {
         actionItemId,
+        programId: flags.program,
         completedOn: flags["completed-on"]
       });
       console.log(JSON.stringify(result, null, 2));
@@ -906,6 +1049,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (!eventId) throw new Error("A Policy Event ID is required.");
     const result = await withWorkflowDelta(root, () => completeObligationEvent(root, {
       eventId,
+      programId: flags.program,
       completedOn: flags["completed-on"],
       expectedRevision: requireExpectedRevision(flags, `obligation-event/${eventId}`)
     }));
@@ -1172,17 +1316,19 @@ Usage:
   filegrc workflow [audit-id] [--as-of YYYY-MM-DD] [--through YYYY-MM-DD] [--complete] [--require-ready] [--json]
   filegrc period-health [audit-id] [--start YYYY-MM-DD --end YYYY-MM-DD] [--as-of YYYY-MM-DD] [--require-healthy] [--json]
   filegrc milestone-check [--as-of YYYY-MM-DD] [--json]
+  filegrc reporting-route-sets [--program program-id] [--at RFC3339] [--json]
+  filegrc reporting-route-set scaffold <approve|cancel|successor> [--id route-set-id] | propose ROUTE_SET_ID | approve PAYLOAD.json | cancel PAYLOAD.json
   filegrc scaffold <resource-type> --title text [--id resource-id] [--program program-id]
   filegrc list [resource-type] [--workflow] [--json]
   filegrc search <query> [--type resource-type] [--json]
-  filegrc obligations [--as-of YYYY-MM-DD] [--from YYYY-MM-DD] [--through YYYY-MM-DD] [--now RFC3339] [--complete] [--json]
+  filegrc obligations [--program program-id] [--as-of YYYY-MM-DD] [--from YYYY-MM-DD] [--through YYYY-MM-DD] [--now RFC3339] [--complete] [--json]
   filegrc program-readiness [--as-of YYYY-MM-DD] [--require-ready] [--summary] [--json]
   filegrc program-amendment <source-resource-id> [--json]
   filegrc review-bindings <retention-or-mapping-id> [--json]
   filegrc evidence-map [--as-of YYYY-MM-DD] [--json]
   filegrc audit-readiness [audit-id] [--as-of YYYY-MM-DD] [--require-ready] [--json]
   filegrc prepare-audit <audit-id> [--json]
-  filegrc reconcile [--preview|--apply --candidate fingerprint (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) --yes] [--risk-level normal|high] [--json]
+  filegrc reconcile [--preview|--apply --candidate fingerprint (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) --yes] [--program program-id] [--risk-level normal|high] [--json]
   filegrc external-reviewer-setup --scaffold
   filegrc external-reviewer-setup <reviewer.json|-> [--preview|--yes] [--json]
   filegrc next-audit-cycle <prior-audit-id> [cycle.json|-] --start YYYY-MM-DD --end YYYY-MM-DD [--preview|--yes] [--json]
@@ -1192,17 +1338,22 @@ Usage:
   filegrc activate-content [--scaffold | activation.json|-] [--program id] [--activated-by person-id] [--activated-on YYYY-MM-DD] [--effective-on YYYY-MM-DD] [--preview|--yes] [--json]
   filegrc activate-documents [--scaffold | activation.json|-] [--program id | --audit id] [--activated-by person-id] [--activated-on YYYY-MM-DD] [--effective-on YYYY-MM-DD] [--preview|--yes] [--json]
   filegrc policy-library [--json | --accept proposal-id --proposal-revision revision --yes]
-  filegrc trigger <event-type> (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) [--risk-level normal|high] [--subject resource-id[,resource-id]] [--title text] [--json]
-  filegrc evidence-packet [--audit audit-id] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--output .filegrc/path] [--preview] [--require-ready] [--json]
+  filegrc trigger <event-type> (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) [--program program-id] [--risk-level normal|high] [--subject resource-id[,resource-id]] [--title text] [--json]
+  filegrc evidence-packet [--audit audit-id | --program program-id] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--output .filegrc/path] [--preview] [--require-ready] [--json]
   filegrc get [resource-type] <id> [--mutation]
   filegrc references <id> [--json]
   filegrc preview-mutation <preview.json|-> [--json]
   filegrc create <mutation.json|-> [--json]
-  filegrc complete <obligation-id> --scaffold --window-start YYYY-MM-DD [--completed-on YYYY-MM-DD]
+  filegrc complete <obligation-id> --scaffold --window-start YYYY-MM-DD [--program program-id] [--completed-on YYYY-MM-DD]
   filegrc complete <obligation-id> <completion-record.json|-> [--expected-revision hash] [--json]
-  filegrc complete-action <action-item-id> --scaffold [--completed-on YYYY-MM-DD]
+  filegrc activate-obligation-rule <rule-id> [payload.json] [--scaffold] [--json]
+  filegrc reconcile-obligation <obligation-id> --scaffold --window-start YYYY-MM-DD [--program program-id] [--as-of YYYY-MM-DD] [--correct-finalized]
+  filegrc reconcile-obligation <obligation-id> <occurrence.json|-> [--program program-id] [--expected-revision hash] [--json]
+  filegrc correct-audit-population <population-id> --scaffold [--as-of YYYY-MM-DD]
+  filegrc correct-audit-population <population-id> <correction.json|-> [--expected-revision hash] [--json]
+  filegrc complete-action <action-item-id> --scaffold [--program program-id] [--completed-on YYYY-MM-DD]
   filegrc complete-action <action-item-id> <completion-record.json|-> --completed-on YYYY-MM-DD [--expected-revision hash] [--json]
-  filegrc complete-event <obligation-event-id> --completed-on YYYY-MM-DD --expected-revision hash [--json]
+  filegrc complete-event <obligation-event-id> --program program-id --completed-on YYYY-MM-DD --expected-revision hash [--json]
   filegrc update <resource-type> <id> <mutation.json|-> [--json]
   filegrc content <resource-type> <id> [slot] [--write markdown-file|-] [--expected-revision hash] [--json]
   filegrc attach <evidence-id> <source-file> --expected-revision hash [--name file-name] [--json]
@@ -1288,6 +1439,27 @@ Start with:
   # Use the next model version shown by the guide.`);
     return;
   }
+  if (["reporting-route-set", "reporting-route-sets"].includes(command)) {
+    console.log(`Usage:
+  filegrc reporting-route-sets [--program program-id] [--at RFC3339] [--json]
+  filegrc reporting-route-set scaffold approve [--id route-set-id] [--timezone IANA] [--effective-at RFC3339] [--proposal-commit commit] [--revision revision]
+  filegrc reporting-route-set scaffold cancel [--id route-set-id] [--timezone IANA] [--revision revision]
+  filegrc reporting-route-set scaffold successor [--id route-set-id] [--timezone IANA] [--effective-at RFC3339] [--proposal-commit commit] [--revision revision] [--predecessor-revision revision]
+  filegrc reporting-route-set propose ROUTE_SET_ID [--revision revision] [--json]
+  filegrc reporting-route-set approve PAYLOAD.json [--json]
+  filegrc reporting-route-set cancel PAYLOAD.json [--json]
+
+Reporting channels are the email addresses, phone numbers, web forms, in-person
+contacts, or other destinations people use to raise a concern. A set keeps the
+normal channel and its fallback together for one purpose. Inspect the rules that
+require them or advance a set through proposal, approval, and cancellation. CLI writes never create Git commits.
+Commit the proposal before approval, then commit the approval before its effective
+time. The action-specific payload scaffolds name the actual event time, IANA
+timezone, authority Appointment, Evidence, and current revisions. Approval and
+successor scaffolds also require the full proposal commit. A successor records
+its approval and the predecessor cancellation together.`);
+    return;
+  }
   if (command === "program-readiness") {
     console.log(`Usage:
   filegrc program-readiness [options]
@@ -1515,6 +1687,7 @@ function agentOverview(model) {
     previewMutation: "filegrc preview-mutation <preview.json> --json",
     create: "filegrc create <mutation.json>",
     complete: "filegrc complete <obligation-id> <completion-mutation.json>",
+    reconcileObligation: "filegrc reconcile-obligation <obligation-id> --scaffold --window-start <date>",
     completeAction: "filegrc complete-action <action-item-id> <completion-mutation.json> --completed-on <date>",
     completeEvent: "filegrc complete-event <obligation-event-id> --completed-on <date>",
     update: "filegrc update <resource-type> <id> <mutation.json>",

package/src/collection-review-integrity.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { loadModel } from "../model/index.js";
+import { collectionRevision } from "./collection-revision.js";
+import { scopedCollectionRecords } from "./collection-scope.js";
+import { getDataFilesAtRevision, getFileAtRevision, getRecordIdentityHistory, hasGitRevision } from "./git.js";
+import { currentCalendarDate, isRfc3339Timestamp } from "./time.js";
+
+export function collectionReviewRevision(record) {
+  const reviewedFacts = {
+    id: record.id,
+    type: record.type,
+    title: record.title,
+    resourceType: record.resourceType,
+    decision: record.decision,
+    rationale: record.rationale,
+    reviewedByIds: record.reviewedByIds,
+    reviewedOn: record.reviewedOn,
+    collectionRevision: record.collectionRevision,
+    scopeRevision: record.scopeRevision,
+    coverage: record.coverage,
+    knowledgeCutoffAt: record.knowledgeCutoffAt,
+    populationResourceIds: record.populationResourceIds,
+    scopeResourceIds: record.scopeResourceIds,
+    authoritativeComponentId: record.authoritativeComponentId,
+    supersedesId: record.supersedesId
+  };
+  return createHash("sha256").update(JSON.stringify(reviewedFacts)).digest("hex");
+}
+
+export function historicalCollectionReviewSnapshot(root, record, model, timezone, resourceType, cutoff, selector = null, relativePath = null, expectedCommit = null) {
+  if (!historicalCollectionReviewIsUsable(record, model, timezone, resourceType, cutoff)) return null;
+  const reviewCommit = committedCollectionReviewMatch(root, record, relativePath, expectedCommit, timezone, cutoff);
+  if (!reviewCommit) return null;
+  const paths = getDataFilesAtRevision(root, record.scopeRevision);
+  if (!paths.length || !hasGitRevision(root, record.scopeRevision)) return null;
+  const entries = [];
+  for (const path of paths) {
+    const source = getFileAtRevision(root, record.scopeRevision, path);
+    if (source === null) return null;
+    try {
+      entries.push({ record: JSON.parse(source), source, relativePath: path.slice("data/".length) });
+    } catch {
+      return null;
+    }
+  }
+  const workspace = entries.find(({ relativePath, record: candidate }) => (
+    relativePath === "workspace.json" && candidate?.type === "workspace"
+  ))?.record;
+  if (!workspace) return null;
+  const resources = entries.map(({ record: candidate }) => candidate);
+  const programId = (record.scopeResourceIds || []).find((id) => resources.some((candidate) => (
+    candidate.type === "program" && candidate.id === id
+  )));
+  const program = resources.find((candidate) => candidate.type === "program" && candidate.id === programId);
+  if (!program) return null;
+  const snapshot = { root, entries, resources, workspace, model: loadModel(workspace.dataModelVersion) };
+  const collectionIds = scopedCollectionRecords(snapshot, resourceType, program).map(({ id }) => id).sort();
+  const currentRevision = collectionRevision(snapshot, resourceType, {
+    program,
+    authoritativeSourceId: record.authoritativeComponentId
+  });
+  if (
+    record.collectionRevision !== currentRevision
+    || JSON.stringify([...(record.populationResourceIds || [])].sort()) !== JSON.stringify(collectionIds)
+  ) return null;
+  const selectedIds = selector
+    ? resources.filter((candidate) => (
+        candidate.type === selector.resourceType
+        && collectionIds.includes(candidate.id)
+        && (!selector.statuses?.length || selector.statuses.includes(candidate.status))
+        && (!selector.criticalities?.length || selector.criticalities.includes(candidate.criticality))
+      )).map(({ id }) => id).sort()
+    : collectionIds;
+  return { collectionIds, selectedIds, reviewCommit: reviewCommit.commit };
+}
+
+function committedCollectionReviewMatch(root, record, relativePath, expectedCommit, timezone, cutoff) {
+  const identityHistory = getRecordIdentityHistory(root, record.id);
+  const history = expectedCommit
+    ? identityHistory.filter(({ commit }) => commit === expectedCommit)
+    : [...identityHistory].reverse();
+  const expected = collectionReviewRevision(record);
+  return history.find(({ commit, path }) => {
+    if (expectedCommit && commit !== expectedCommit) return false;
+    const source = getFileAtRevision(root, commit, path);
+    if (!source) return false;
+    try {
+      const historical = JSON.parse(source);
+      return historical.type === "collection-review"
+        && historical.id === record.id
+        && ["active", "retired"].includes(historical.status)
+        && collectionReviewRevision(historical) === expected;
+    } catch {
+      return false;
+    }
+  }) || null;
+}
+
+function historicalCollectionReviewIsUsable(record, model, timezone, resourceType, cutoff) {
+  if (
+    record?.type !== "collection-review"
+    || !["active", "retired"].includes(record.status)
+    || record.resourceType !== resourceType
+    || record.coverage?.kind !== "as-of"
+    || record.coverage.on !== cutoff
+    || !Array.isArray(record.populationResourceIds)
+    || !record.collectionRevision
+    || !record.scopeRevision
+    || record.reviewedOn !== cutoff
+    || !isRfc3339Timestamp(record.knowledgeCutoffAt)
+    || currentCalendarDate(timezone, new Date(record.knowledgeCutoffAt)) !== cutoff
+  ) return false;
+  const allowed = model.collectionReviews?.[resourceType]?.decisions || ["complete"];
+  if (!allowed.includes(record.decision)) return false;
+  return record.decision === "zero-population"
+    ? record.populationResourceIds.length === 0
+    : record.populationResourceIds.length > 0;
+}