filegrc 0.4.0 → 0.5.0

package/src/collection-review.js

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto";
+import { applyResourceBatch } from "./files.js";
+import { getGitSummary } from "./git.js";
+import { loadWorkspace } from "./workspace.js";
+
+export function collectionRevision(loaded, resourceType) {
+  const records = loaded.entries
+    .filter(({ record }) => record.type === resourceType)
+    .map(({ record, source }) => ({
+      id: record.id,
+      revision: createHash("sha256").update(source).digest("hex")
+    }))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const workspaceScope = {
+    assuranceGoal: loaded.workspace?.assuranceGoal ?? null,
+    candidateCoverage: loaded.workspace?.candidateCoverage ?? null,
+    systemIds: [...(loaded.workspace?.systemIds || [])].sort(),
+    frameworkIds: [...(loaded.workspace?.frameworkIds || [])].sort(),
+    requirementIds: [...(loaded.workspace?.requirementIds || [])].sort(),
+    controlIds: [...(loaded.workspace?.controlIds || [])].sort()
+  };
+  return createHash("sha256")
+    .update(JSON.stringify({ resourceType, records, workspaceScope }))
+    .digest("hex");
+}
+
+export function assessCollectionReviews(input) {
+  const loaded = input?.resources && input?.model && input?.entries
+    ? input
+    : null;
+  if (!loaded) throw new Error("Collection review assessment requires a loaded workspace.");
+  return Object.keys(loaded.model.collectionReviews || {})
+    .map((resourceType) => assessCollectionReview(loaded, resourceType));
+}
+
+export function assessCollectionReview(loaded, resourceType) {
+  const configuration = loaded.model.collectionReviews?.[resourceType];
+  if (!configuration) return null;
+  const records = loaded.resources.filter((record) => record.type === resourceType);
+  const reviewEntry = loaded.entries.find(({ record }) => (
+    record.type === "collection-review"
+    && record.resourceType === resourceType
+    && record.status !== "retired"
+  ));
+  const review = reviewEntry?.record || null;
+  const currentRevision = collectionRevision(loaded, resourceType);
+  const allowedDecisions = configuration.decisions || ["complete"];
+  const complete = Boolean(
+    review?.status === "active"
+    && allowedDecisions.includes(review.decision)
+    && review.collectionRevision === currentRevision
+  );
+  const stale = Boolean(
+    review?.status === "active"
+    && review.collectionRevision
+    && review.collectionRevision !== currentRevision
+  );
+  return {
+    resourceType,
+    configuration,
+    records,
+    recordCount: records.length,
+    review,
+    reviewRevision: reviewEntry
+      ? createHash("sha256").update(reviewEntry.source).digest("hex")
+      : null,
+    collectionRevision: currentRevision,
+    status: complete ? "current" : stale ? "stale" : "review-required",
+    complete,
+    message: complete
+      ? `${configuration.title} were reviewed on ${review.reviewedOn}.`
+      : stale
+        ? `${configuration.title} changed after the last confirmation. Review the current records again.`
+        : `Review ${configuration.title.toLowerCase()} before this page can be ready.`
+  };
+}
+
+export async function scaffoldCollectionReview(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  const resourceType = requiredType(loaded, options.resourceType);
+  const assessment = assessCollectionReview(loaded, resourceType);
+  const allowedDecisions = assessment.configuration.decisions || ["complete"];
+  return {
+    resourceType,
+    decision: assessment.records.length
+      ? "complete"
+      : allowedDecisions.includes("zero-population") ? "zero-population" : null,
+    rationale: null,
+    reviewedByIds: [],
+    reviewedOn: null,
+    authoritativeSystemId: null
+  };
+}
+
+export async function planCollectionReview(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  const resourceType = requiredType(loaded, options.resourceType);
+  const assessment = assessCollectionReview(loaded, resourceType);
+  const configuration = assessment.configuration;
+  const decision = String(options.decision || "").trim();
+  const rationale = String(options.rationale || "").trim();
+  const reviewedByIds = [...new Set((options.reviewedByIds || []).map(String).filter(Boolean))];
+  const reviewedOn = String(options.reviewedOn || "").trim();
+  const scopeRevision = String(options.scopeRevision || getGitSummary(loaded.root).commit || "uncommitted").trim();
+  const authoritativeSystemId = String(options.authoritativeSystemId || "").trim();
+  if (!(configuration.decisions || ["complete"]).includes(decision)) {
+    throw new Error(
+      `${configuration.title} review must use one of: ${(configuration.decisions || ["complete"]).join(", ")}.`
+    );
+  }
+  if (!assessment.records.length && decision === "complete") {
+    throw new Error(`${configuration.title} has no records. Use zero-population or another allowed conclusion.`);
+  }
+  if (assessment.records.length && decision === "zero-population") {
+    throw new Error(`${configuration.title} has ${assessment.records.length} records and cannot be confirmed as a zero population.`);
+  }
+  if (!rationale || !reviewedByIds.length || !reviewedOn) {
+    throw new Error(`${configuration.title} review needs review notes, a reviewer, and a review date.`);
+  }
+  if (decision === "externally-managed") {
+    const system = loaded.resources.find((record) => (
+      record.type === "system"
+      && record.id === authoritativeSystemId
+      && record.status === "active"
+    ));
+    if (!system) throw new Error(`${configuration.title} review needs an active authoritative System.`);
+  }
+  const existing = assessment.review;
+  const record = {
+    ...(existing || {
+      id: `collection-review-${resourceType}`,
+      type: "collection-review",
+      title: `${configuration.title} review`,
+      resourceType,
+      scopeResourceIds: [loaded.workspace.id]
+    }),
+    status: "active",
+    decision,
+    rationale,
+    reviewedByIds,
+    reviewedOn,
+    collectionRevision: assessment.collectionRevision,
+    scopeRevision,
+    ...(decision === "externally-managed" ? { authoritativeSystemId } : {})
+  };
+  if (decision !== "externally-managed") delete record.authoritativeSystemId;
+  return {
+    operation: "collection-review",
+    resourceType,
+    assessment,
+    changes: {
+      ...(existing ? { update: [record] } : { create: [record] }),
+      ...(existing ? {
+        expectedRevisions: {
+          [existing.id]: options.expectedRevision || assessment.reviewRevision
+        }
+      } : {}),
+      validateWholeWorkspace: true
+    }
+  };
+}
+
+export async function applyCollectionReview(input = process.cwd(), options = {}) {
+  if (options.confirmed !== true) {
+    throw new Error("Preview the collection review and confirm the write.");
+  }
+  const plan = await planCollectionReview(input, options);
+  const result = await applyResourceBatch(input, plan.changes);
+  const loaded = await loadWorkspace(input);
+  return {
+    ...plan,
+    result,
+    assessment: assessCollectionReview(loaded, plan.resourceType)
+  };
+}
+
+function requiredType(loaded, value) {
+  const resourceType = String(value || "").trim();
+  if (!loaded.model.collectionReviews?.[resourceType]) {
+    throw new Error(
+      `Collection review type must be one of: ${Object.keys(loaded.model.collectionReviews || {}).join(", ")}.`
+    );
+  }
+  return resourceType;
+}

package/src/evidence-packet.js

@@ -884,6 +884,14 @@ function buildControlCoverage({ audit, byId, controlIds, evidenceIds, model, rec
       && controlIdsForRecord(record, byId).has(controlId)
       && packetRecord(record, model, start, end, timezone)
     ));
+    const zeroPopulationRecords = records.filter((record) => (
+      record.type === "audit-population"
+      && record.auditId === audit?.id
+      && record.status === "reconciled"
+      && record.conclusion === "complete"
+      && (record.controlIds || []).includes(controlId)
+      && byId.get(record.sourceEvidenceId)?.populationCount === 0
+    ));
     const linkedEvidenceIds = new Set(evidenceByControl.get(controlId) || []);
     for (const test of tests) {
       addIds(linkedEvidenceIds, test.evidenceIds);
@@ -909,7 +917,7 @@ function buildControlCoverage({ audit, byId, controlIds, evidenceIds, model, rec
         .map(({ id }) => id)
         .sort(),
       evidenceIds: [...linkedEvidenceIds].sort(),
-      operatingRecordIds: operatingRecords.map(({ id }) => id).sort(),
+      operatingRecordIds: [...operatingRecords, ...zeroPopulationRecords].map(({ id }) => id).sort(),
       tests: tests.map((test) => ({
         ...testPopulationSummary(test, byId),
         id: test.id,
@@ -935,6 +943,17 @@ function controlIdsForRecord(record, byId, seen = new Set()) {
   for (const sourceId of record.sourceResourceIds || []) addIds(ids, controlIdsForRecord(byId.get(sourceId), byId, seen));
   if (record.sourceResourceId) addIds(ids, controlIdsForRecord(byId.get(record.sourceResourceId), byId, seen));
   if (record.obligationId) addIds(ids, byId.get(record.obligationId)?.controlIds);
+  for (const candidate of byId.values()) {
+    if (
+      candidate.type === "obligation"
+      && (candidate.completionResourceIds || []).includes(record.id)
+    ) {
+      addIds(ids, candidate.controlIds);
+    }
+  }
+  for (const subjectId of record.subjectResourceIds || []) {
+    addIds(ids, controlIdsForRecord(byId.get(subjectId), byId, seen));
+  }
   return ids;
 }
 
@@ -1003,7 +1022,13 @@ function packetGaps({
     } else if (!controlNeedsExternalEvidence(control, model) && !coverage.operatingRecordIds.length) {
       gaps.push(gap("error", "control-missing-filegrc-evidence", `${coverage.code || coverage.title} has no dated filegrc operating record in the packet.`, coverage.id));
     }
-    if (audit?.auditKind !== "soc-2-type-1" && coverage.status === "implemented" && !coverage.operatingRecordIds.length && coverage.operationMode !== "automated") {
+    if (
+      audit?.auditKind !== "soc-2-type-1"
+      && coverage.status === "implemented"
+      && !coverage.operatingRecordIds.length
+      && !coverage.evidenceIds.length
+      && coverage.operationMode !== "automated"
+    ) {
       gaps.push(gap("warning", "control-missing-operating-record", `${coverage.code || coverage.title} has no dated operating record in the packet period.`, coverage.id));
     }
     for (const test of coverage.tests) {
@@ -1151,6 +1176,13 @@ function packetGaps({
           `${run.title}: ${action.title} was canceled. Complete the requirement or cancel the event with a documented reason.`,
           action.actionItemId
         ));
+      } else if (action.status === "blocked") {
+        gaps.push(gap(
+          "error",
+          "blocked-event-action",
+          `${run.title}: ${action.title} is blocked. ${action.blockingReason || "Open the Action Item and resolve its named blockers."}`,
+          action.actionItemId
+        ));
       } else if (action.missingCompletion) {
         gaps.push(gap(
           "error",

package/src/external-reviewer.js

@@ -0,0 +1,165 @@
+import { applyResourceBatch } from "./files.js";
+import { createResourceId } from "./id.js";
+import { currentCalendarDate } from "./time.js";
+import { loadWorkspace } from "./workspace.js";
+
+export async function scaffoldExternalReviewerGovernance(input = process.cwd()) {
+  const loaded = await loadWorkspace(input);
+  if (String(loaded.model.modelVersion) !== "3") {
+    throw new Error("External reviewer setup requires a model v3 workspace.");
+  }
+  return {
+    reviewerName: null,
+    jobTitle: null,
+    email: null,
+    organization: null,
+    startsOn: currentCalendarDate(loaded.workspace.timezone),
+    independenceRationale: null,
+    appointedByIds: [],
+    instructions: "Replace every null required value with current facts. The reviewer must be independent from policy ownership and operating work. Preview the completed file before applying it."
+  };
+}
+
+export async function planExternalReviewerGovernance(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  if (String(loaded.model.modelVersion) !== "3") {
+    throw new Error("External reviewer setup requires a model v3 workspace.");
+  }
+  const name = required(options.reviewerName, "External reviewer name");
+  const startsOn = required(options.startsOn, "Appointment start date");
+  const existingPerson = loaded.resources.find((record) => (
+    record.type === "person"
+    && record.affiliation === "external"
+    && (
+      record.id === options.reviewerId
+      || record.email && options.email && record.email.toLowerCase() === String(options.email).toLowerCase()
+    )
+  ));
+  const jobTitle = required(
+    options.jobTitle || existingPerson?.jobTitle,
+    "External reviewer organizational job title"
+  );
+  const person = {
+    ...(existingPerson || {
+      id: options.reviewerId || createResourceId("person", name, loaded.resources.map(({ id }) => id)),
+      type: "person"
+    }),
+    title: name,
+    status: "active",
+    affiliation: "external",
+    jobTitle,
+    ...(options.email ? { email: String(options.email) } : {}),
+    ...(options.organization ? { organization: String(options.organization) } : {})
+  };
+  const workspaceId = loaded.workspace.id;
+  const creates = existingPerson ? [] : [person];
+  const updates = existingPerson ? [person] : [];
+  const appointmentIds = [];
+  const appointmentSpecs = [
+    {
+      kind: "independent-policy-reviewer",
+      title: "Independent Policy Reviewer",
+      responsibilities: "Review and approve policies and governed documents independently from the owner, chair security and risk oversight, and challenge management decisions."
+    }
+  ];
+  for (const spec of appointmentSpecs) {
+    const existing = loaded.resources.find((record) => (
+      record.type === "appointment"
+      && record.appointmentKind === spec.kind
+      && record.status !== "ended"
+    ));
+    const appointment = {
+      ...(existing || {
+        id: createResourceId("appointment", spec.title, [
+          ...loaded.resources.map(({ id }) => id),
+          ...creates.map(({ id }) => id)
+        ]),
+        type: "appointment",
+        title: spec.title
+      }),
+      status: "active",
+      appointmentKind: spec.kind,
+      holderId: person.id,
+      scopeResourceIds: [workspaceId],
+      startsOn,
+      responsibilities: existing?.responsibilities || spec.responsibilities,
+      independenceRationale: required(
+        options.independenceRationale,
+        "Independence rationale"
+      ),
+      ...(options.appointedByIds?.length
+        ? { appointedByIds: [...new Set(options.appointedByIds.map(String))] }
+        : {})
+    };
+    appointmentIds.push(appointment.id);
+    if (existing) updates.push(appointment);
+    else creates.push(appointment);
+  }
+
+  const team = loaded.resources.find((record) => (
+    record.type === "team" && record.id === "team-security-risk-oversight"
+  )) || loaded.resources.find((record) => record.type === "team" && /oversight/i.test(record.title));
+  if (team) {
+    updates.push({
+      ...team,
+      status: "active",
+      memberIds: [...new Set([...(team.memberIds || []), person.id])],
+      chairIds: [...new Set([...(team.chairIds || []), appointmentIds[0]])]
+    });
+  } else {
+    creates.push({
+      id: createResourceId("team", "Security and Risk Oversight", [
+        ...loaded.resources.map(({ id }) => id),
+        ...creates.map(({ id }) => id)
+      ]),
+      type: "team",
+      title: "Security and Risk Oversight",
+      status: "active",
+      purpose: "Provide independent review of security, risk, policies, incidents, findings, and overdue work.",
+      memberIds: [person.id],
+      chairIds: [appointmentIds[0]]
+    });
+  }
+
+  for (const policy of loaded.resources.filter((record) => (
+    record.type === "policy"
+    && ["draft", "in-review"].includes(record.status)
+    && !(record.approverIds || []).includes(person.id)
+  ))) {
+    updates.push({
+      ...policy,
+      approverIds: [...new Set([...(policy.approverIds || []), person.id])]
+    });
+  }
+  return {
+    operation: "external-reviewer-governance",
+    reviewerId: person.id,
+    appointmentIds,
+    changes: {
+      create: creates,
+      update: deduplicateUpdates(updates),
+      validateWholeWorkspace: true
+    }
+  };
+}
+
+export async function setupExternalReviewerGovernance(input = process.cwd(), options = {}) {
+  if (options.confirmed !== true) {
+    throw new Error("Preview the external reviewer governance bundle and confirm the write.");
+  }
+  const plan = await planExternalReviewerGovernance(input, options);
+  const result = await applyResourceBatch(input, plan.changes);
+  return { ...plan, result };
+}
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required.`);
+  return normalized;
+}
+
+function deduplicateUpdates(records) {
+  const byId = new Map();
+  for (const record of records) byId.set(record.id, record);
+  return [...byId.values()];
+}

package/src/files.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants, link, lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { getResourceDefinition } from "../model/index.js";
+import { getResourceDefinition, loadModel } from "../model/index.js";
 import { serializeWorkspaceMutation, workspaceValidationDeferred } from "./mutation.js";
 import { isCanonicalDataPath, resolveDataPath, resolveWorkspaceRoot } from "./paths.js";
 import { markdownEntries } from "./resource-markdown.js";
@@ -214,6 +214,31 @@ async function applyResourceBatchUnlocked(input, changes = {}) {
     throw new Error("Batch expected revisions must be keyed by resource ID.");
   }
   const loaded = await loadWorkspace(input);
+  const workspaceUpdate = updates.find((record) => (
+    record.type === "workspace" && record.id === loaded.workspace?.id
+  ));
+  const changesModelVersion = workspaceUpdate
+    && String(workspaceUpdate.dataModelVersion || "") !== String(loaded.workspace?.dataModelVersion || "");
+  const targetModelVersion = changes.targetModelVersion
+    ? String(changes.targetModelVersion)
+    : null;
+  if (changesModelVersion && !targetModelVersion) {
+    throw new Error(
+      "A resource batch that changes dataModelVersion must declare targetModelVersion."
+    );
+  }
+  if (
+    targetModelVersion
+    && (
+      changes.validateWholeWorkspace !== true
+      || String(workspaceUpdate?.dataModelVersion || "") !== targetModelVersion
+    )
+  ) {
+    throw new Error(
+      "A cross-model resource batch must validate the whole workspace and update its dataModelVersion to the target model."
+    );
+  }
+  const writeModel = targetModelVersion ? loadModel(targetModelVersion) : loaded.model;
   const deferValidation = workspaceValidationDeferred();
   const before = deferValidation || changes.validateWholeWorkspace
     ? null
@@ -224,7 +249,7 @@ async function applyResourceBatchUnlocked(input, changes = {}) {
   for (const record of creates) {
     validateBatchRecord(record, ids);
     if (existingById.has(record.id)) throw new Error(`Resource "${record.id}" already exists.`);
-    const path = resourcePath(loaded.root, loaded.model, record);
+    const path = resourcePath(loaded.root, writeModel, record);
     writes.push({ operation: "create", path, record, previous: null, fileMode: 0o666 });
   }
   for (const record of updates) {
@@ -234,7 +259,7 @@ async function applyResourceBatchUnlocked(input, changes = {}) {
     if (existing.record.type !== record.type) {
       throw new Error(`Resource "${record.id}" cannot change type.`);
     }
-    const path = resourcePath(loaded.root, loaded.model, record);
+    const path = resourcePath(loaded.root, writeModel, record);
     const previous = await readFile(path, "utf8");
     const mode = (await stat(path)).mode & 0o777;
     assertRevision(
@@ -643,14 +668,15 @@ async function prepareApprovalBinding(loaded, record, contentWrites, previousRec
   if (record.type === "attestation") {
     return prepareAttestationBinding(loaded, record, previousRecord);
   }
-  if (!["policy", "document"].includes(record.type)) return record;
+  const bindingField = approvalBindingField(record, loaded.model);
+  if (!bindingField) return record;
   const nextRecord = structuredClone(record);
   if (!approvalBound(record)) {
-    delete nextRecord.approvedContentRevisions;
+    delete nextRecord[bindingField];
     return nextRecord;
   }
-  if (approvalBound(previousRecord) && previousRecord.approvedContentRevisions) {
-    nextRecord.approvedContentRevisions = structuredClone(previousRecord.approvedContentRevisions);
+  if (approvalBound(previousRecord) && previousRecord[bindingField]) {
+    nextRecord[bindingField] = structuredClone(previousRecord[bindingField]);
     return nextRecord;
   }
   const proposed = new Map(contentWrites.map((item) => [item.dataRelativePath, item.source]));
@@ -667,7 +693,7 @@ async function prepareApprovalBinding(loaded, record, contentWrites, previousRec
     }
     revisions[item.path] = contentRevision(source);
   }
-  nextRecord.approvedContentRevisions = revisions;
+  nextRecord[bindingField] = revisions;
   return nextRecord;
 }
 
@@ -704,13 +730,23 @@ async function prepareAttestationBinding(loaded, record, previousRecord = null)
 }
 
 function approvalBound(record) {
-  if (!record || !["policy", "document"].includes(record.type)) return false;
+  if (!record || !["policy", "document", "training"].includes(record.type)) return false;
   const statuses = record.type === "policy"
     ? ["approved", "active", "superseded", "retired"]
-    : ["active", "superseded", "retired"];
+    : record.type === "document"
+      ? ["active", "superseded", "retired"]
+      : ["active", "retired"];
   return statuses.includes(record.status);
 }
 
+function approvalBindingField(record, model) {
+  if (["policy", "document"].includes(record?.type)) return "approvedContentRevisions";
+  if (record?.type === "training" && model.resources.training?.fields?.effectiveContentRevisions) {
+    return "effectiveContentRevisions";
+  }
+  return null;
+}
+
 async function exclusiveContentFiles(loaded, record) {
   const candidates = markdownEntries(loaded.model, record).map(({ path }) => path);
   const files = [];

package/src/index.js

@@ -1,6 +1,25 @@
-export { getResourceDefinition, loadModel } from "../model/index.js";
+export {
+  ACTIVE_MODEL_VERSION,
+  getResourceDefinition,
+  loadModel,
+  SUPPORTED_MODEL_VERSIONS
+} from "../model/index.js";
 export { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldResourceMutation } from "./agent.js";
 export { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
+export { createNextAuditCycle, planNextAuditCycle } from "./audit-transition.js";
+export {
+  applyApplicabilityReview,
+  planApplicabilityReview,
+  scaffoldApplicabilityReview
+} from "./batch-review.js";
+export {
+  applyCollectionReview,
+  assessCollectionReview,
+  assessCollectionReviews,
+  collectionRevision,
+  planCollectionReview,
+  scaffoldCollectionReview
+} from "./collection-review.js";
 export { buildWorkspace } from "./build.js";
 export { generateEvidencePacket, prepareEvidencePacket, writeEvidencePacket } from "./evidence-packet.js";
 export {
@@ -35,13 +54,20 @@ export {
   completeObligationEvent,
   completeObligationOccurrence,
   createObligationEvent,
-  planObligations
+  planObligations,
+  scaffoldObligationCompletion
 } from "./obligations.js";
+export {
+  planExternalReviewerGovernance,
+  scaffoldExternalReviewerGovernance,
+  setupExternalReviewerGovernance
+} from "./external-reviewer.js";
 export { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
 export {
   buildAgentProgramPath,
   PROGRAM_PATH,
   RESOURCE_INSTRUCTIONS,
+  RESOURCE_PAGE_SUMMARIES,
   resourceProgramContext
 } from "./program-path.js";
 export {
@@ -53,9 +79,17 @@ export {
 } from "./recurrence.js";
 export { searchResources, searchableValues } from "./search.js";
 export { effectiveResourceStatus } from "./resource-status.js";
+export { applyReconciliation, planReconciliation } from "./reconciliation.js";
 export { createFilegrcServer, serveWorkspace } from "./server.js";
 export { normalizeSetupPayload, planWorkspaceSetup, setupWorkspace, summarizeSetupResult } from "./setup.js";
 export { createAppState, createResourceDetail } from "./state.js";
 export { currentCalendarDate, formatCalendarDate, formatLocalDateTime } from "./time.js";
 export { validateWorkspace } from "./validate.js";
+export {
+  assessWorkflow,
+  buildWorkflowDelta,
+  previewWorkflowMutation,
+  workflowForResource,
+  WORKFLOW_CONTRACT_VERSION
+} from "./workflow.js";
 export { indexResources, loadWorkspace } from "./workspace.js";

package/src/model-docs.js

@@ -45,6 +45,16 @@ export function generateModelDocumentation(model) {
       `| \`${name}\` | ${types.map((type) => `\`${type}\``).join(", ")} |`
     )),
     "",
+    "## Collection review confirmations",
+    "",
+    "FileGRC derives record issues, but it cannot infer that management reviewed an apparently complete or empty collection. Each configured collection review records the conclusion, reviewer, date, current scope revision, and exact collection revision. A record or material scope change makes the confirmation stale.",
+    "",
+    "| Resource type | Review | Allowed conclusions | What to review |",
+    "| --- | --- | --- | --- |",
+    ...Object.entries(model.collectionReviews || {}).map(([type, review]) => (
+      `| \`${type}\` | ${escapeCell(review.title)} | ${review.decisions.map((decision) => `\`${decision}\``).join(", ")} | ${escapeCell(review.reviewPoints.join(" "))} |`
+    )),
+    "",
     "## Relationship constraints",
     "",
     "Relationship constraints prevent cycles and duplicate active authority or access records.",
@@ -130,6 +140,11 @@ export function generateModelDocumentation(model) {
       lines.push(`Instructions: ${RESOURCE_INSTRUCTIONS[type] || resource.description}`, "");
       lines.push(`Policy basis: ${resource.guidance.policyBasis}`, "");
       lines.push(`Timing: ${resource.guidance.cadence}`, "");
+      if (resource.guidance.reviewPoints?.length) {
+        lines.push("When reviewing:", "");
+        for (const point of resource.guidance.reviewPoints) lines.push(`- ${point}`);
+        lines.push("");
+      }
       if (resource.guidance.sourceResourceIds?.length) {
         lines.push(`Default sources: ${resource.guidance.sourceResourceIds.map((id) => `\`${id}\``).join(", ")}`, "");
       }