filegrc 0.15.0 → 0.15.2

package/model/v11.json

@@ -567,7 +567,7 @@
     },
     "vendor": {
       "title": "Vendor inventory",
-      "description": "Confirm material external provider relationships separately from Program System and Component scope.",
+      "description": "Finish each material external provider record, then confirm the Vendor inventory once as a complete collection separate from Program System and Component scope.",
       "reviewPoints": [
         "Add Vendors for material external commercial or service relationships.",
         "Confirm contracts, due diligence, criticality, information access, and monitoring.",
@@ -593,7 +593,7 @@
     },
     "complementary-control": {
       "title": "Customer and provider responsibilities",
-      "description": "Confirm whether any in-scope Control depends on a customer or carved-out provider action, including when no such dependency exists.",
+      "description": "Finish each customer or carved-out provider responsibility record, then confirm the collection once, including when no such dependency exists.",
       "reviewPoints": [
         "Think through the customer and carved-out provider actions that in-scope Controls depend on, and add any missing Complementary Control.",
         "Confirm each statement names a specific action, responsible party, affected System, and dependent Control.",
@@ -606,7 +606,7 @@
     },
     "component": {
       "title": "Scoped Components",
-      "description": "Confirm the Components that materially participate in the selected Program Systems.",
+      "description": "Finish each Component proposal, then confirm once that the collection materially participating in the selected Program Systems is complete.",
       "reviewPoints": [
         "Start with each bounded System and include only Components that deliver its service, support Controls, produce authoritative Evidence, or support relevant operations.",
         "Confirm every System use has the right role and a specific rationale.",
@@ -631,7 +631,7 @@
     },
     "information-type": {
       "title": "Information Type inventory",
-      "description": "Confirm that Information Types are complete, distinct, and linked to the Systems, Components, and Vendors that use or access them.",
+      "description": "Finish each Information Type proposal, then confirm once that the collection is complete, distinct, and linked to the Systems, Components, and Vendors that use or access it.",
       "reviewPoints": [
         "Review near-duplicate names and choose one canonical Information Type only after confirming they mean the same thing.",
         "Retire superseded records through a reviewed migration that rewrites every relationship.",
@@ -644,11 +644,11 @@
     },
     "retention-schedule-item": {
       "title": "Data Retention Schedule",
-      "description": "Approve the schedule document and its structured rows as one governed schedule. Include only actual information uses and keep undecided organization values planned.",
+      "description": "Complete each structured row proposal, then approve the schedule document and all proposed rows in one independent review. Include only actual information uses and keep undecided organization values planned.",
       "reviewPoints": [
-        "Review the Data Retention Schedule document, its Markdown, and every included structured row as one revision.",
+        "Confirm the owner completed every row proposal, then review the Data Retention Schedule document, its Markdown, and every proposed row as one revision.",
         "Confirm schedule coverage across the Systems, Components, Vendors, source families, logs, backups, audit records, and FileGRC records the organization actually uses.",
-        "Confirm every active item has an approved cutoff, retention period, disposition action, owner, approver, and exact reviewed source revisions; keep undecided behavior planned."
+        "Confirm every proposed item has a reviewed cutoff, retention period, disposition action, owner, and exact source revisions; keep undecided behavior planned."
       ],
       "decisions": [
         "complete",
@@ -7699,14 +7699,14 @@
       "pluralTitle": "Retention Schedule",
       "group": "governance",
       "collection": "retention-schedule-items",
-      "description": "One reviewed schedule item that states which Information Types and operational scope it covers, when retention starts, how long information is kept, and its approved disposition.",
+      "description": "One owner-completed proposal that states which Information Types and operational scope it covers, when retention starts, how long information is kept, and its proposed disposition. It becomes authoritative through the single whole-schedule approval.",
       "guidance": {
         "policyBasis": "Management must translate legal, contractual, privacy, security, and business needs into explicit retention and disposition instructions without treating starter periods as organization facts.",
-        "cadence": "Review before activation and after a source Policy, Requirement, Commitment, information use, System, Component, Vendor, or legal-hold process changes.",
+        "cadence": "Complete the proposal before whole-schedule approval and revisit it after a source Policy, Requirement, Commitment, information use, System, Component, Vendor, or legal-hold process changes.",
         "reviewPoints": [
           "Confirm the Information Types and operational scope covered by this item.",
-          "Confirm the cutoff, retention period, and disposition action from approved management sources.",
-          "Keep the item planned until management approves every organization-specific value."
+          "Confirm the cutoff, retention period, and disposition action from management sources.",
+          "Keep the item planned until the owner completes every organization-specific value and binds the current source revisions."
         ],
         "sourceResourceIds": [
           "policy-information-security",
@@ -7828,16 +7828,11 @@
           "relation": [
             "person"
           ],
-          "requiredWhen": {
-            "status": "active"
-          },
-          "label": "Approved by"
+          "label": "Legacy row reviewer"
         },
         "approvedOn": {
           "type": "date",
-          "requiredWhen": {
-            "status": "active"
-          }
+          "label": "Legacy row review date"
         },
         "reviewedSourceRevisions": {
           "type": "object",
@@ -7891,8 +7886,6 @@
         "retentionPeriod",
         "dispositionAction",
         "dispositionInstructions",
-        "approvedByIds",
-        "approvedOn",
         "reviewedSourceRevisions",
         "supersedesId",
         "statusTransition"

package/package.json

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

package/src/audit-preparation.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { modelSupports } from "../model/index.js";
 import { applicabilityReviewIsCurrent } from "./applicability-scope.js";
+import { selectDefaultAudit } from "./audit-selection.js";
 import { openPlaceholderCount, substantiveMarkdown } from "./content-readiness.js";
 import {
   coverageContains,
@@ -63,20 +64,21 @@ export async function assessAuditPreparation(input, options = {}) {
   const records = loaded.resources;
   const byId = new Map(records.map((record) => [record.id, record]));
   const audits = records.filter((record) => record.type === "audit");
+  const calendarAsOf = options.asOf || currentCalendarDate(loaded.workspace?.timezone || "UTC");
   const audit = options.auditId
     ? audits.find((record) => record.id === options.auditId)
     : options.selectDefault === false
       ? null
-      : audits.find((record) => !["complete", "closed", "canceled"].includes(record.status)) || audits[0];
+      : selectDefaultAudit(audits, calendarAsOf);
   if (options.auditId && !audit) throw new Error(`Audit "${options.auditId}" was not found.`);
 
-  const calendarAsOf = options.asOf || currentCalendarDate(loaded.workspace?.timezone || "UTC");
   const formalPeriodEnd = audit?.auditKind === "soc-2-type-2" ? coverageEnd(audit.coverage) : null;
   const readinessAsOf = formalPeriodEnd && formalPeriodEnd < calendarAsOf ? formalPeriodEnd : calendarAsOf;
   const programReadiness = options.programReadiness || await assessProgramReadiness(loaded, {
     asOf: readinessAsOf,
     generatedAt: options.generatedAt,
-    programId: audit?.programId || options.programId
+    programId: audit?.programId || options.programId,
+    auditId: audit?.id
   });
   const documentActivations = audit && modelSupports(loaded.model, "governed-document-activation")
     ? await auditDocumentActivationAssessments(loaded, audit, byId, calendarAsOf)
@@ -103,17 +105,21 @@ export async function assessAuditPreparation(input, options = {}) {
   }
   const items = stages.flatMap((stage) => stage.items);
   const counts = countStatuses(items);
-  const managedItems = items.filter((item) => !["external", "info", "later"].includes(item.status));
-  const completedManagedItems = managedItems.filter((item) => item.status === "complete");
+  const progressUnits = items.flatMap((current) => (
+    current.progressUnit === false || ["external", "info", "later"].includes(current.status)
+      ? []
+      : current.progressUnits?.length ? current.progressUnits : [current]
+  )).filter((current) => !["external", "info", "later"].includes(current.status));
+  const completedProgressUnits = progressUnits.filter((current) => current.status === "complete");
   return {
     schemaVersion: 1,
     generatedAt: options.generatedAt || new Date().toISOString(),
     audit: audit ? auditSummary(audit) : null,
     status: !audit ? "not-started" : counts.action ? "needs-work" : "management-ready",
     progress: {
-      complete: completedManagedItems.length,
-      total: managedItems.length,
-      percent: managedItems.length ? Math.round((completedManagedItems.length / managedItems.length) * 100) : 0
+      complete: completedProgressUnits.length,
+      total: progressUnits.length,
+      percent: progressUnits.length ? Math.round((completedProgressUnits.length / progressUnits.length) * 100) : 0
     },
     counts,
     canInitialize: Boolean(audit
@@ -746,6 +752,12 @@ function canonicalScopeValue(value) {
 function programFoundationStage(programReadiness, workspace, audit) {
   const needsOperatingPeriod = audit?.auditKind === "soc-2-type-2";
   const ready = needsOperatingPeriod ? programReadiness.operating : programReadiness.evidenceReady;
+  const setupRemaining = programReadiness.setupProgress?.remaining
+    ?? (programReadiness.progress?.mode === "setup-progress" ? programReadiness.progress.remaining : 0);
+  const activeWindow = programReadiness.progress?.mode === "operating-window";
+  const activeWindowLabel = programReadiness.progress?.source === "audit"
+    ? "audit window"
+    : "candidate operating period";
   return stage("program", "Program Readiness", "The management program can be prepared and operated without an audit record or CPA firm.", [
     item(
       "evidence-ready",
@@ -755,9 +767,13 @@ function programFoundationStage(programReadiness, workspace, audit) {
         ? needsOperatingPeriod
           ? `${programReadiness.target.label} is operating for the selected engagement.`
           : `${programReadiness.target.label} is evidence-ready.`
+        : needsOperatingPeriod && activeWindow
+          ? setupRemaining
+            ? `The ${activeWindowLabel} is active, but ${setupRemaining} required setup ${setupRemaining === 1 ? "action remains" : "actions remain"} across scope, policies, controls, and evidence preparation.`
+            : `The ${activeWindowLabel} is active, but current operating work needs attention before treating the engagement as management-ready.`
         : needsOperatingPeriod && programReadiness.evidenceReady
           ? "Start the candidate period and finish the current operating-readiness work before treating a Type 2 engagement as management-ready."
-          : `${programReadiness.counts.action} program-readiness actions remain across scope, policies, controls, and evidence preparation.`,
+          : `${setupRemaining} required setup ${setupRemaining === 1 ? "action remains" : "actions remain"} across scope, policies, controls, and evidence preparation.`,
       workspace || { type: "workspace" }
     )
   ]);
@@ -953,7 +969,7 @@ function occurrenceContinuityStage(audit, records, model, asOf) {
   const gapStatuses = new Set(["overdue", "blocked", "due", "proposed"]);
   const calendarGaps = plan.calendarItems.filter(({ status }) => gapStatuses.has(status));
   const eventGaps = plan.eventRuns
-    .filter((run) => run.occurredOn >= periodStart && run.occurredOn <= periodThrough)
+    .filter((run) => run.status !== "canceled" && run.occurredOn >= periodStart && run.occurredOn <= periodThrough)
     .flatMap((run) => run.actions)
     .filter((action) => (
       (gapStatuses.has(action.status) || action.lateCompletion)
@@ -962,6 +978,57 @@ function occurrenceContinuityStage(audit, records, model, asOf) {
   const gaps = [...calendarGaps, ...eventGaps];
   const lateGaps = eventGaps.filter(({ lateCompletion }) => lateCompletion);
   const firstGap = gaps[0];
+  const progressUnits = occurrenceProgressUnits(plan, {
+    selectedControlIds,
+    periodStart,
+    periodThrough
+  });
+  return occurrenceContinuityStageResult({
+    audit,
+    gaps,
+    lateGaps,
+    firstGap,
+    eventGaps,
+    periodThrough,
+    progressUnits
+  });
+}
+
+export function occurrenceProgressUnits(plan, { selectedControlIds, periodStart, periodThrough }) {
+  return [
+    ...plan.calendarItems.flatMap((occurrence) => {
+      const completedMemberIds = new Set(occurrence.completedMemberIds || []);
+      const conclusionComplete = occurrence.reconciliationStatus === "reconciled"
+        && ["complete", "complete-with-exceptions", "zero-population"].includes(occurrence.operatingResult);
+      const occurrenceComplete = conclusionComplete || occurrence.legacySchedule && occurrence.status === "complete";
+      const memberUnits = (occurrence.expectedMemberIds || []).map((resourceId) => ({
+        id: `occurrence-${occurrence.occurrenceKey}-member-${resourceId}`,
+        status: occurrenceComplete || completedMemberIds.has(resourceId) ? "complete" : "action",
+        title: `${occurrence.title} member ${resourceId}`
+      }));
+      const membersComplete = memberUnits.every(({ status }) => status === "complete");
+      return [
+        ...memberUnits,
+        {
+          id: `occurrence-${occurrence.occurrenceKey}-reconciliation`,
+          status: occurrenceComplete ? "complete" : membersComplete && occurrence.membershipFinal ? "action" : "blocked",
+          title: `${occurrence.title} reconciliation`
+        }
+      ];
+    }),
+    ...plan.eventRuns
+      .filter((run) => run.status !== "canceled" && run.occurredOn >= periodStart && run.occurredOn <= periodThrough)
+      .flatMap((run) => run.actions)
+      .filter((action) => action.controlIds.some((id) => selectedControlIds.has(id)))
+      .map((action) => ({
+        id: `event-action-${action.actionItemId || action.key}`,
+        status: action.status === "complete" && !action.lateCompletion ? "complete" : "action",
+        title: action.title
+      }))
+  ];
+}
+
+function occurrenceContinuityStageResult({ audit, gaps, lateGaps, firstGap, eventGaps, periodThrough, progressUnits }) {
   return stage(
     "occurrences",
     "Operating Occurrences",
@@ -985,7 +1052,8 @@ function occurrenceContinuityStage(audit, records, model, asOf) {
         commands: firstGap?.actionItemId ? [
           `npx filegrc get ${firstGap.actionItemId} --json`,
           `npx filegrc scaffold finding --title "Late operating occurrence review"`
-        ] : []
+        ] : [],
+        progressUnits
       }
     )]
   );
@@ -1336,12 +1404,33 @@ function populationsStage(audit, records, byId, model) {
   const items = templates.map((template) => {
     const population = populations.find((record) => record.populationKind === template.kind);
     const result = populationResult(population, audit, byId);
+    const preparationComplete = populationPreparationComplete(population, audit);
     return item(
       `population-${template.kind}`,
       result.status,
       template.title,
       result.message || `Use ${template.sourcePrompt} as the starting point, then record the exact authoritative source.`,
-      population || { type: "audit-population" }
+      population || { type: "audit-population" },
+      {
+        progressUnits: population?.status === "not-applicable" ? [
+          {
+            id: `population-${template.kind}-applicability`,
+            status: result.status,
+            title: `${template.title} applicability decision`
+          }
+        ] : [
+          {
+            id: `population-${template.kind}-preparation`,
+            status: preparationComplete ? "complete" : "action",
+            title: `${template.title} preparation`
+          },
+          {
+            id: `population-${template.kind}-conclusion`,
+            status: result.status === "complete" ? "complete" : preparationComplete ? "action" : "blocked",
+            title: `${template.title} reconciliation conclusion`
+          }
+        ]
+      }
     );
   });
   return stage(
@@ -1388,7 +1477,7 @@ function auditorStage(audit, byId, modelVersion) {
   ]);
 }
 
-function populationResult(population, audit, byId) {
+export function populationResult(population, audit, byId) {
   if (!population) return { status: "action", message: "Initialize this population for the engagement." };
   if (!coverageMatches(
     population.coverage,
@@ -1421,6 +1510,7 @@ function populationResult(population, audit, byId) {
     && evidence.type === "evidence"
     && evidence.artifactKind === "population-export"
     && evidence.status === "verified"
+    && (population.ownerIds || []).length > 0
     && (population.sourceComponentId || population.sourceSystemId)
     && (evidence.sourceComponentId || evidence.sourceSystemId) === (population.sourceComponentId || population.sourceSystemId)
     && coverageMatches(
@@ -1447,6 +1537,21 @@ function populationResult(population, audit, byId) {
   };
 }
 
+function populationPreparationComplete(population, audit) {
+  if (!population || !coverageMatches(
+    population.coverage,
+    coverageStart(audit?.coverage),
+    coverageEnd(audit?.coverage)
+  )) return false;
+  if (population.status === "not-applicable") {
+    return !(population.controlIds || []).length && Boolean(String(population.notApplicableReason || "").trim());
+  }
+  return Boolean(
+    (population.ownerIds || []).length
+    && (population.sourceComponentId || population.sourceSystemId)
+  );
+}
+
 function timestampDate(value, timezone) {
   if (!value || !timezone) return null;
   const instant = new Date(value);
@@ -1718,7 +1823,9 @@ function item(id, status, title, message, resource = {}, options = {}) {
     ...(options.commands?.length ? { commands: options.commands } : {}),
     ...(options.affectedActionItemIds?.length ? { affectedActionItemIds: options.affectedActionItemIds } : {}),
     ...(options.affectedEventIds?.length ? { affectedEventIds: options.affectedEventIds } : {}),
-    ...(options.lateCount ? { lateCount: options.lateCount } : {})
+    ...(options.lateCount ? { lateCount: options.lateCount } : {}),
+    ...(options.progressUnits?.length ? { progressUnits: options.progressUnits } : {}),
+    ...(options.progressUnit === false ? { progressUnit: false } : {})
   };
 }
 

package/src/audit-selection.js

@@ -0,0 +1,33 @@
+export function selectDefaultAudit(audits = [], asOf = "") {
+  const terminal = new Set(["complete", "closed", "canceled", "delivered"]);
+  const coverageStart = (audit) => audit?.coverage?.startsOn
+    || audit?.coverage?.periodStart
+    || audit?.coverage?.on
+    || "";
+  const statusOrder = new Map([
+    ["planned", 0],
+    ["in-progress", 1],
+    ["fieldwork", 2],
+    ["report-draft", 3],
+    ["issued", 4],
+    ["delivered", 5],
+    ["complete", 6]
+  ]);
+  const open = audits.filter((audit) => !terminal.has(audit.status));
+  const candidates = [...(open.length ? open : audits)];
+  candidates.sort((left, right) => {
+    const leftStart = coverageStart(left);
+    const rightStart = coverageStart(right);
+    const leftStarted = Boolean(leftStart && (!asOf || leftStart <= asOf));
+    const rightStarted = Boolean(rightStart && (!asOf || rightStart <= asOf));
+    return Number(rightStarted) - Number(leftStarted)
+      || (leftStarted && rightStarted
+        ? rightStart.localeCompare(leftStart)
+        : leftStart && rightStart
+          ? leftStart.localeCompare(rightStart)
+          : Number(Boolean(rightStart)) - Number(Boolean(leftStart)))
+      || (statusOrder.get(right.status) ?? -1) - (statusOrder.get(left.status) ?? -1)
+      || String(left.id || "").localeCompare(String(right.id || ""));
+  });
+  return candidates[0] || null;
+}

package/src/cli.js

@@ -136,6 +136,13 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (result.usedFallbackPort) {
       console.log(`Port ${result.requestedPort} is already in use. Using ${result.address.port} instead.`);
     }
+    if (result.startupSynchronization?.status === "updated") {
+      console.log(`Updated the authoritative branch to ${result.startupSynchronization.shortCommit} before serving.`);
+    } else if (result.startupSynchronization?.status === "blocked") {
+      console.warn(`Remote startup sync is blocked because local and remote history diverged (${result.startupSynchronization.ahead} ahead, ${result.startupSynchronization.behind} behind). Reconcile the branch before relying on this server.`);
+    } else if (result.startupSynchronization?.status === "failed") {
+      console.warn(`Remote startup sync did not complete: ${result.startupSynchronization.message}`);
+    }
     console.log(`filegrc workspace: ${result.url}`);
     console.log(`Data: ${result.root}/data`);
     printGithubStarMessage();
@@ -447,16 +454,17 @@ export async function runCli(argv = process.argv.slice(2)) {
     const loaded = await loadWorkspace(root);
     const result = await assessProgramReadiness(loaded, { asOf: flags["as-of"], programId: flags.program });
     const output = flags.summary ? summarizeProgramReadiness(result) : result;
+    const headlineStatus = result.progress.status || result.status;
     if (flags.json) console.log(JSON.stringify(output, null, 2));
     else if (flags.summary) {
-      console.log(`${result.status.toUpperCase()}: ${result.progress.complete} of ${result.progress.total} program items complete`);
+      console.log(`${headlineStatus.toUpperCase()}: ${result.progress.label} ${result.progress.percent}%. ${result.progress.detail}`);
       for (const stage of output.stages) {
-        console.log(`${stage.status.toUpperCase()}\t${stage.title}\t${stage.counts.action} actions`);
+        console.log(`${stage.status.toUpperCase()}\t${stage.title}\t${stage.counts.action} checks need action`);
       }
       if (output.firstAction) console.log(`Next: ${output.firstAction.title}\t${output.firstAction.message}`);
     }
     else {
-      console.log(`${result.status.toUpperCase()}: ${result.progress.complete} of ${result.progress.total} program items complete`);
+      console.log(`${headlineStatus.toUpperCase()}: ${result.progress.label} ${result.progress.percent}%. ${result.progress.detail}`);
       console.log(
         `${result.target.label}`
         + (result.target.candidateCoverage?.kind === "range"
@@ -2036,6 +2044,8 @@ function summarizeProgramReadiness(result) {
     suggestedCandidatePeriodStart: result.suggestedCandidatePeriodStart,
     target: result.target,
     progress: result.progress,
+    setupProgress: result.setupProgress,
+    checkProgress: result.checkProgress,
     counts: result.counts,
     scopeCounts: Object.fromEntries(
       Object.entries(result.scope).map(([name, ids]) => [name.replace(/Ids$/, ""), ids.length])