filegrc 0.16.1 → 0.16.3

package/README.md

@@ -4,7 +4,7 @@ filegrc is a zero-dependency Node.js engine for Git-native GRC workspaces. It va
 
 Program Readiness checks management-owned scope, policy adoption, control implementation, and authoritative evidence mapping without requiring an audit record. Audit Readiness starts after CPA engagement and checks the firm-agreed date or period, engagement-specific management documents, operating evidence, and Type 2 population completeness.
 
-Controls linked to filegrc Obligations show whether their scheduled work is waiting for policy approval, ready for implementation, running, paused, or mixed. Marking a fully configured Control implemented starts its enabled work when the governing content is effective.
+The Controls list focuses on implementation and its next action. The Obligations list shows schedule state separately, including proposals, approved schedules, and Policies awaiting activation or their effective date. Enabled work starts when its governing content is effective and a linked Control is implemented.
 
 Most users should create a complete workspace:
 

package/package.json

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

package/src/cli.js

@@ -1846,7 +1846,11 @@ function buildProgramPathResult(model, readiness, auditReadiness) {
       nextActions: (current?.items || []).filter((item) => item.status === "action")
     };
   });
-  const currentStep = stages.find((stage) => !["complete", "operating", "management-ready"].includes(stage.status)) || stages.at(-1);
+  const recommendedStage = readiness.stages.find((stage) => stage.items.includes(readiness.firstAction));
+  const recommendedId = recommendedStage?.id === "operation" ? "run" : recommendedStage?.id;
+  const currentStep = stages.find(({ id }) => id === recommendedId)
+    || stages.find((stage) => !["complete", "operating", "management-ready"].includes(stage.status))
+    || stages.at(-1);
   return {
     schemaVersion: 1,
     dataModelVersion: String(model.modelVersion),

package/src/collection-scope.js

@@ -65,6 +65,24 @@ export function scopedCollectionRecords(loaded, resourceType, program) {
   ));
 }
 
+// These records can change which members enter a collection even when they
+// are not part of its current revision inputs yet.
+const COLLECTION_MEMBERSHIP_SOURCES = {
+  person: ["workspace", "program", "appointment", "team", "system", "component", "vendor", "control", "policy", "document", "obligation"],
+  vendor: ["program", "system", "component", "audit"],
+  component: ["program", "system", "control"],
+  "complementary-control": ["program", "system", "component", "control"],
+  "information-type": ["program", "system", "component", "vendor"],
+  "retention-schedule-item": ["program", "system", "component", "vendor", "control", "information-type", "source-coverage"],
+  framework: ["program"],
+  system: ["program"],
+  control: ["program"]
+};
+
+export function collectionMembershipSourceTypes(resourceType) {
+  return COLLECTION_MEMBERSHIP_SOURCES[resourceType] || [];
+}
+
 export function retentionScheduleReviewScope(loaded) {
   const programs = loaded.resources.filter((record) => (
     record.type === "program" && record.status !== "retired"

package/src/obligations.js

@@ -101,6 +101,9 @@ export function planObligations(resources, options = {}) {
     && ["active", "proposed"].includes(record.status)
     && obligationBelongsToProgram(record, obligationProgram, model)
   ));
+  const programStatusByObligationId = new Map(obligations.map((obligation) => [
+    obligation.id, obligationProgramStatus(obligation, byId, asOf, model)
+  ]));
   const obligationIds = new Set(obligations.map(({ id }) => id));
   if (obligations.length > MAX_PLANNED_ITEMS) {
     throw new Error(`The obligation query must be narrowed; it includes more than ${MAX_PLANNED_ITEMS.toLocaleString("en-US")} active obligations.`);
@@ -123,7 +126,7 @@ export function planObligations(resources, options = {}) {
     const schedule = rule || obligation;
     const activity = obligationActivity(model, obligation);
     const expectedCompletionTypes = activity.completionResourceTypes;
-    const programStatus = obligationProgramStatus(obligation, byId, asOf, model);
+    const programStatus = programStatusByObligationId.get(obligation.id);
     const programBlocker = programStatus === "proposed" ? obligationProgramBlocker(obligation, byId, asOf) : null;
     if (schedule.recurrence?.mode === "event" && schedule.recurrence.eventType) {
       const eventType = schedule.recurrence.eventType;
@@ -294,7 +297,7 @@ export function planObligations(resources, options = {}) {
     if (!dueWindowStart || !dueWindowEnd || dueWindowStart > through) continue;
     const overdueOn = addCalendarDays(dueWindowEnd, 1);
     const window = { dueWindowStart, dueWindowEnd, overdueOn };
-    const programStatus = obligationProgramStatus(obligation, byId, asOf, model);
+    const programStatus = programStatusByObligationId.get(obligation.id);
     const programBlocker = programStatus === "proposed" ? obligationProgramBlocker(obligation, byId, asOf) : null;
     const activity = obligationActivity(model, obligation);
     const completedMemberIds = (occurrence.members || [])
@@ -402,6 +405,7 @@ export function planObligations(resources, options = {}) {
     asOf,
     through,
     from: requestedFrom,
+    programStatuses: Object.fromEntries(programStatusByObligationId),
     counts,
     items,
     calendarItems,

package/src/program-readiness.js

@@ -3,6 +3,7 @@ import { modelSupports } from "../model/index.js";
 import { applicabilityReviewIsCurrent } from "./applicability-scope.js";
 import { assessRequiredAppointments } from "./appointments.js";
 import { assessCollectionReviews } from "./collection-review.js";
+import { collectionMembershipSourceTypes, collectionRevisionInputs, collectionScopeRevisionFacts } from "./collection-scope.js";
 import { openPlaceholderCount, substantiveMarkdown } from "./content-readiness.js";
 import { coverageEnd, coverageStart } from "./coverage.js";
 import { planObligations } from "./obligations.js";
@@ -233,6 +234,7 @@ export async function assessProgramReadiness(input, options = {}) {
     policyStage,
     controlStage
   ];
+  const prioritizedSetupItems = prioritizeReviewDependencies(evidenceGateStages, loaded, program);
   for (const current of evidenceGateStages) finalizeStage(current);
   const evidenceReady = evidenceGateStages.every((current) => current.counts.action === 0);
   const stages = [
@@ -260,7 +262,8 @@ export async function assessProgramReadiness(input, options = {}) {
   const items = stages.flatMap((current) => current.items);
   const managedItems = items.filter((current) => !["info", "later"].includes(current.status));
   const complete = managedItems.filter((current) => current.status === "complete").length;
-  const firstAction = items.find((current) => current.status === "action") || null;
+  const firstAction = [...prioritizedSetupItems, ...stages.at(-1).items]
+    .find((current) => current.status === "action") || null;
   const target = {
     programId: program?.id || null,
     goal: program?.assuranceGoal || "none",
@@ -1966,6 +1969,50 @@ function finalizeStage(current) {
   current.status = current.counts.action ? "action" : current.counts.later ? "later" : "complete";
 }
 
+// A collection confirmation can be performed early, but an unfinished input
+// would make it stale again. Derive the ordering from the same revision inputs
+// used to decide whether that confirmation is current.
+export function prioritizeReviewDependencies(stages, loaded, program) {
+  const items = stages.flatMap(({ items }) => items);
+  const edges = new Map(items.map((_, index) => [index, new Set()]));
+  const indegree = items.map(() => 0);
+  for (const [reviewIndex, review] of items.entries()) {
+    if (review.status !== "action" || !review.id.startsWith("collection-review-")) continue;
+    const resourceType = review.id.slice("collection-review-".length);
+    if (!loaded.model.collectionReviews?.[resourceType]) continue;
+    const inputTypes = new Set(collectionRevisionInputs(loaded, resourceType, program)
+      .map(({ record }) => record.type));
+    for (const type of collectionMembershipSourceTypes(resourceType)) inputTypes.add(type);
+    const scopeFacts = collectionScopeRevisionFacts(loaded, resourceType, program);
+    if (Object.keys(scopeFacts).some((key) => key !== "programId")) inputTypes.add("program");
+    for (const key of Object.keys(scopeFacts)) {
+      if (!key.endsWith("Ids")) continue;
+      const type = key.slice(0, -3).replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+      if (loaded.model.resources?.[type]) inputTypes.add(type);
+    }
+    for (const [sourceIndex, source] of items.entries()) {
+      if (sourceIndex === reviewIndex || source.status !== "action"
+        || source.id.startsWith("collection-review-")
+        || !inputTypes.has(source.resourceType)) continue;
+      edges.get(sourceIndex).add(reviewIndex);
+      indegree[reviewIndex]++;
+    }
+  }
+  const remaining = new Set(items.map((_, index) => index));
+  const ordered = [];
+  while (remaining.size) {
+    const next = [...remaining].find((index) => indegree[index] === 0);
+    if (next === undefined) break;
+    remaining.delete(next);
+    ordered.push(items[next]);
+    for (const dependent of edges.get(next)) indegree[dependent]--;
+  }
+  if (ordered.length !== items.length) return items;
+  const rank = new Map(ordered.map((item, index) => [item, index]));
+  for (const stage of stages) stage.items.sort((left, right) => rank.get(left) - rank.get(right));
+  return ordered;
+}
+
 function item(id, status, title, message, resource = {}, details = {}) {
   return {
     id,

package/src/web.js

@@ -246,6 +246,7 @@ function normalizeAppState(next) {
 function blockingStateSections(route) {
   if (route.name === "home") return ["program", "obligations", "workflow"];
   if (route.name === "repository") return ["repository"];
+  if (route.name === "list" && route.type === "obligation") return ["obligations"];
   if (route.name === "obligations" || route.name === "stage" && route.stageId === "run") return ["program", "obligations"];
   if (route.name === "audit-packet") return ["repository", "program", "obligations", "audits"];
   if (route.name === "evidence-sources") return ["program", "workflow"];
@@ -589,6 +590,13 @@ function readinessOverview() {
 }
 
 function nextProgramStageHref() {
+  const firstAction = state.programReadiness?.firstAction;
+  const recommendedStage = state.programReadiness?.stages?.find((stage) => stage.items.some((item) => (
+    item.id === firstAction?.id && item.resourceId === firstAction?.resourceId
+  )));
+  if (recommendedStage) {
+    return "#/stage/" + encodeURIComponent(recommendedStage.id === "operation" ? "run" : recommendedStage.id);
+  }
   const nextStage = READINESS_STAGES.find((stage) => {
     const progress = stageProgress(stage);
     return progress.complete < progress.total;
@@ -3081,7 +3089,6 @@ function renderList(main, type, params = new URLSearchParams()) {
   const fields = [...new Set([
     "title",
     ...(definition.listFields || []),
-    ...(type === "control" ? ["$operationTracking"] : []),
     ...(type === "obligation" ? ["$workQueueStatus"] : [])
   ])].filter((name) => name !== "title");
   const modelFields = { ...state.model.commonFields, ...definition.fields };
@@ -3124,7 +3131,7 @@ function renderList(main, type, params = new URLSearchParams()) {
     const start = (pageNumber - 1) * LIST_PAGE_SIZE;
     const visible = filtered.slice(start, start + LIST_PAGE_SIZE);
     main.querySelector("#result-count").textContent = filtered.length + (filtered.length === 1 ? " record" : " records");
-    main.querySelector("#record-rows").innerHTML = filtered.length ? visible.map((entry) => '<tr><td data-label="' + esc(fieldLabel(type, "title")) + '" data-primary-field><a class="record-title" href="#/resource/' + encodeURIComponent(type) + '/' + encodeURIComponent(entry.record.id) + detailContext + '">' + esc(entry.record.title) + '</a></td>' + fields.map((name) => '<td data-label="' + esc(fieldLabel(type, name)) + '">' + (name === "$operationTracking" ? controlOperationTracking(entry.record) : name === "$workQueueStatus" ? obligationWorkQueueStatus(entry.record) : formatValue(name === "status" ? displayStatus(entry.record) : entry.record[name], name, type, true)) + '</td>').join("") + '<td data-label="Next action">' + recordWorkflowCell(type, entry) + '</td><td data-label="Git file"><code>' + esc(entry.relativePath.replace(/^data\//, "")) + '</code></td></tr>').join("") : '<tr><td colspan="' + (fields.length + 3) + '">' + empty(entries.length ? "No records match this filter." : collectionEmptyState(type, definition)) + '</td></tr>';
+    main.querySelector("#record-rows").innerHTML = filtered.length ? visible.map((entry) => '<tr><td data-label="' + esc(fieldLabel(type, "title")) + '" data-primary-field><a class="record-title" href="#/resource/' + encodeURIComponent(type) + '/' + encodeURIComponent(entry.record.id) + detailContext + '">' + esc(entry.record.title) + '</a></td>' + fields.map((name) => '<td data-label="' + esc(fieldLabel(type, name)) + '">' + (name === "$workQueueStatus" ? obligationWorkQueueStatus(entry.record) : formatValue(name === "status" ? displayStatus(entry.record) : entry.record[name], name, type, true)) + '</td>').join("") + '<td data-label="Next action">' + recordWorkflowCell(type, entry) + '</td><td data-label="Git file"><code>' + esc(entry.relativePath.replace(/^data\//, "")) + '</code></td></tr>').join("") : '<tr><td colspan="' + (fields.length + 3) + '">' + empty(entries.length ? "No records match this filter." : collectionEmptyState(type, definition)) + '</td></tr>';
     pagination.hidden = totalPages === 1;
     previous.disabled = pageNumber === 1;
     next.disabled = pageNumber === totalPages;
@@ -5965,7 +5972,6 @@ function setNavigationGroupOpen(group, open) {
 function groupTitle(id) { return state.model.groups.find((group) => group.id === id)?.title || "Program"; }
 function fieldDefinition(type, name) { return state.model.resources[type]?.fields?.[name] || state.model.commonFields[name]; }
 function fieldLabel(type, name) {
-  if (name === "$operationTracking") return "Operation tracking";
   if (name === "$workQueueStatus") return "Work Queue";
   if (type === "obligation" && name === "status") return "Configuration";
   if (name === "title") return state.model.resources[type]?.titleLabel || state.model.commonFields.title.label;
@@ -6076,58 +6082,49 @@ function formatObjectArray(items, objectType, compact = false) {
     return '<div class="object-value"><span class="object-value-facts">' + facts.join("") + '</span>' + (!compact && notes.length ? '<small>' + esc(notes.join(" ")) + '</small>' : "") + '</div>';
   }).join("") + '</div>';
 }
-function controlOperationTracking(control) {
-  const obligations = resourcesOfType("obligation")
-    .map(({ record }) => record)
-    .filter((record) => record.status !== "retired" && (record.controlIds || []).includes(control.id));
-  if (!obligations.length) {
-    return '<span class="operation-tracking evidence"><strong>Not scheduled in Work Queue</strong><small>Show operation with evidence records</small></span>';
-  }
-  const counts = obligations.reduce((result, obligation) => {
-    const status = workQueueScheduleStatus(obligation, control);
-    result[status] = (result[status] || 0) + 1;
-    return result;
-  }, {});
-  const scheduleCount = obligations.length + " " + pluralize("schedule", obligations.length);
-  if (counts.running === obligations.length) {
-    return '<a class="operation-tracking running" href="#/stage/run"><strong>Running in Work Queue</strong><small>' + esc(scheduleCount) + '</small></a>';
-  }
-  if (counts["waiting-policy"] === obligations.length) {
-    return '<a class="operation-tracking waiting" href="#/stage/run"><strong>Waiting for policy approval</strong><small>' + esc(scheduleCount) + ' enabled</small></a>';
-  }
-  if (counts["waiting-control"] === obligations.length) {
-    return '<a class="operation-tracking waiting" href="#/stage/run"><strong>Ready when implemented</strong><small>' + esc(scheduleCount) + ' enabled</small></a>';
-  }
-  if (counts.paused === obligations.length) {
-    return '<a class="operation-tracking paused" href="#/stage/run"><strong>Work Queue paused</strong><small>' + esc(scheduleCount) + '</small></a>';
-  }
-  const summary = [
-    counts.running ? counts.running + " running" : "",
-    counts["waiting-policy"] ? counts["waiting-policy"] + " waiting for policy" : "",
-    counts["waiting-control"] ? counts["waiting-control"] + " waiting for implementation" : "",
-    counts.paused ? counts.paused + " paused" : ""
-  ].filter(Boolean).join(" · ");
-  return '<a class="operation-tracking mixed" href="#/stage/run"><strong>Work Queue needs attention</strong><small>' + esc(summary) + '</small></a>';
-}
-function workQueueScheduleStatus(obligation, control = null) {
+function workQueueScheduleStatus(obligation) {
+  if (obligation.status === "proposed") {
+    const pendingRules = resourcesOfType("obligation-rule")
+      .map(({ record }) => record)
+      .filter((record) => record.obligationId === obligation.id && ["proposed", "approved"].includes(record.status));
+    return pendingRules.length === 1 && pendingRules[0].status === "approved" ? "approved" : "proposed";
+  }
   if (obligation.status === "paused") return "paused";
   if (obligation.status !== "active") return obligation.status;
+  const programStatus = state.obligations?.programStatuses?.[obligation.id];
+  if (!programStatus) return "not-evaluated";
+  const rule = state.resources.find(({ record }) => record.id === obligation.activeRuleId)?.record;
+  if (obligation.scheduleMode === "rule" && rule?.status !== "active") {
+    return "proposed";
+  }
+  if (rule?.effectiveAt && new Date(rule.effectiveAt) > new Date()) {
+    const prior = state.resources.find(({ record }) => record.id === rule.supersedesId)?.record;
+    if (prior?.obligationId !== obligation.id || !["active", "retired"].includes(prior.status)) {
+      return "waiting-schedule-effective";
+    }
+  }
   const asOf = state.obligations?.asOf || new Date().toISOString().slice(0, 10);
   const policies = (obligation.policyIds || []).map((id) => state.resources.find(({ record }) => record.id === id)?.record);
-  if (!policies.every((policy) => policy?.type === "policy" && policy.status === "active" && policy.effectiveOn && policy.effectiveOn <= asOf)) {
-    return "waiting-policy";
-  }
+  if (policies.some((policy) => policy?.type !== "policy" || !["approved", "active"].includes(policy.status))) return "waiting-policy-approval";
+  if (policies.some((policy) => policy.status !== "active")) return "waiting-policy-activation";
+  if (policies.some((policy) => !policy.effectiveOn || policy.effectiveOn > asOf)) return "waiting-policy-effective";
   const linkedControls = (obligation.controlIds || []).map((id) => state.resources.find(({ record }) => record.id === id)?.record);
-  const implemented = control
-    ? control.status === "implemented"
-    : !linkedControls.length || linkedControls.some((record) => record?.type === "control" && record.status === "implemented");
-  return implemented ? "running" : "waiting-control";
+  const implemented = !linkedControls.length || linkedControls.some((record) => record?.type === "control" && record.status === "implemented");
+  if (!implemented) return "waiting-control";
+  return programStatus === "accepted" ? "running" : "waiting-prerequisites";
 }
 function obligationWorkQueueStatus(obligation) {
   const status = workQueueScheduleStatus(obligation);
+  if (status === "proposed") return '<span class="operation-tracking"><strong>Proposed</strong><small>Review schedule before activation</small></span>';
+  if (status === "approved") return '<span class="operation-tracking"><strong>Approved</strong><small>Activate schedule before operation</small></span>';
   if (status === "running") return '<span class="operation-tracking running"><strong>Running</strong><small>Enabled and policy effective</small></span>';
-  if (status === "waiting-policy") return '<span class="operation-tracking waiting"><strong>Waiting for policy</strong><small>Schedule enabled</small></span>';
+  if (status === "waiting-policy-approval") return '<span class="operation-tracking waiting"><strong>Waiting for policy approval</strong><small>Schedule enabled</small></span>';
+  if (status === "waiting-policy-activation") return '<span class="operation-tracking waiting"><strong>Waiting for policy activation</strong><small>Policy approved</small></span>';
+  if (status === "waiting-policy-effective") return '<span class="operation-tracking waiting"><strong>Waiting for effective date</strong><small>Policy active</small></span>';
+  if (status === "waiting-schedule-effective") return '<span class="operation-tracking waiting"><strong>Waiting for schedule start</strong><small>Approved rule activates at its effective time</small></span>';
   if (status === "waiting-control") return '<span class="operation-tracking waiting"><strong>Waiting for control</strong><small>Implement a linked control</small></span>';
+  if (status === "waiting-prerequisites") return '<span class="operation-tracking waiting"><strong>Waiting for prerequisites</strong><small>Check owner and governed content</small></span>';
+  if (status === "not-evaluated") return '<span class="operation-tracking"><strong>Not assessed here</strong><small>Outside the selected program</small></span>';
   if (status === "paused") return '<span class="operation-tracking paused"><strong>Paused</strong><small>Schedule disabled</small></span>';
   return '<span class="operation-tracking"><strong>' + esc(properCase(status)) + '</strong></span>';
 }