filegrc 0.4.0 → 0.5.1

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "filegrc",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Sunpeak-AI/filegrc.git"
+    "url": "git+https://github.com/Alignbase/filegrc.git"
   },
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "src"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test --test-concurrency=1"
   },
   "engines": {
     "node": ">=20"

package/src/agent.js

@@ -1,6 +1,7 @@
 import { createResourceId } from "./id.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { RESOURCE_INSTRUCTIONS, resourceProgramContext } from "./program-path.js";
+import { assessCollectionReview } from "./collection-review.js";
 
 const STARTING_STATUS_ORDER = [
   "draft",
@@ -28,6 +29,7 @@ export function listResourceTypes(model) {
 export function buildAgentGuide(loaded, type, options = {}) {
   const definition = loaded.model.resources[type];
   if (!definition) throw new Error(`Unknown resource type "${type}".`);
+  const collectionReview = assessCollectionReview(loaded, type);
   const fields = { ...loaded.model.commonFields, ...definition.fields };
   const required = new Set([
     ...Object.entries(loaded.model.commonFields)
@@ -81,8 +83,23 @@ export function buildAgentGuide(loaded, type, options = {}) {
     programStep: resourceProgramContext(type),
     policyBasis: definition.guidance.policyBasis,
     cadence: definition.guidance.cadence,
+    emptyState: definition.guidance.emptyState ?? null,
     policySourceIds: definition.guidance.sourceResourceIds ?? [],
     obligationActivityTypes: definition.guidance.obligationActivityTypes ?? [],
+    reviewRequirements: {
+      recordReviewPoints: definition.guidance.reviewPoints ?? [],
+      collectionReview: collectionReview
+        ? {
+            title: collectionReview.configuration.title,
+            description: collectionReview.configuration.description,
+            reviewPoints: collectionReview.configuration.reviewPoints,
+            allowedDecisions: collectionReview.configuration.decisions,
+            status: collectionReview.status,
+            recordCount: collectionReview.recordCount,
+            command: `npx filegrc review-collection ${type} --scaffold`
+          }
+        : null
+    },
     location,
     singleton: Boolean(definition.singleton),
     requiredAtCreation,
@@ -155,6 +172,7 @@ export function scaffoldResourceMutation(loaded, type, title, options = {}) {
       record[name] = scaffoldValue(name, field, loaded.model);
     }
   }
+  applyModelScaffoldDefaults(record, loaded);
 
   const slots = markdownEntries(loaded.model, record).filter((slot) => (
     slot.required
@@ -171,6 +189,41 @@ export function scaffoldResourceMutation(loaded, type, title, options = {}) {
   };
 }
 
+function applyModelScaffoldDefaults(record, loaded) {
+  if (record.type === "appointment") {
+    const normalizedTitle = record.title.toLowerCase();
+    const match = Object.entries(loaded.model.appointmentTemplates || {}).find(([kind, template]) => (
+      template.title.toLowerCase() === normalizedTitle
+      || kind === normalizedTitle.replace(/[^a-z0-9]+/g, "-")
+    ));
+    record.appointmentKind = match?.[0] || normalizedTitle.replace(/[^a-z0-9]+/g, "-");
+    if (!record.scopeResourceIds?.length && loaded.workspace?.id) {
+      record.scopeResourceIds = [loaded.workspace.id];
+    }
+    return;
+  }
+  if (record.type === "audit") {
+    const kind = {
+      "soc-2-type-1": "soc-2-type-1",
+      "soc-2-type-2": "soc-2-type-2"
+    }[loaded.workspace?.assuranceGoal];
+    if (kind) record.auditKind = kind;
+    for (const field of ["frameworkIds", "systemIds", "requirementIds", "controlIds"]) {
+      if (loaded.workspace?.[field]?.length) record[field] = [...loaded.workspace[field]];
+    }
+    const programOwner = loaded.resources.find((candidate) => (
+      candidate.type === "appointment"
+      && candidate.appointmentKind === "program-lead"
+      && candidate.status === "active"
+    )) || loaded.resources.find((candidate) => (
+      candidate.type === "appointment"
+      && candidate.appointmentKind === "policy-owner"
+      && candidate.status === "active"
+    ));
+    if (programOwner) record.ownerIds = [programOwner.id];
+  }
+}
+
 export function findResourceReferences(loaded, id) {
   const target = loaded.resources.find((record) => record.id === id);
   if (!target) throw new Error(`Resource "${id}" was not found.`);

package/src/appointments.js

@@ -0,0 +1,19 @@
+export function assessRequiredAppointments(records, model) {
+  const templates = model.appointmentTemplates || {};
+  return Object.entries(templates).map(([kind, template]) => {
+    const appointments = records.filter((record) => (
+      record.type === "appointment"
+      && record.appointmentKind === kind
+      && record.status !== "ended"
+    ));
+    const active = appointments.find(({ status }) => status === "active");
+    const planned = appointments.find(({ status }) => status === "planned");
+    return {
+      kind,
+      template,
+      requiredness: template.requiredness,
+      record: active || planned || null,
+      state: active ? "complete" : "ready"
+    };
+  });
+}

package/src/audit-preparation.js

@@ -10,7 +10,7 @@ import {
 } from "./coverage.js";
 import { createResource, createResources, deleteResource, updateResource } from "./files.js";
 import { createResourceId } from "./id.js";
-import { partiesIndependent } from "./parties.js";
+import { currentPartyPeople, partiesIndependent } from "./parties.js";
 import { resolveDataPath } from "./paths.js";
 import { assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
@@ -433,7 +433,10 @@ function engagementStage(audit, byId, programReadiness) {
   }
   const auditor = audit.auditorVendorId ? byId.get(audit.auditorVendorId) : null;
   const named = Boolean(auditor);
-  return stage("engagement", "Engage the Auditor", "Record the independent CPA firm and engagement contacts before treating the audit as active.", [
+  const currentOwners = [...currentPartyPeople(audit.ownerIds, byId)]
+    .map((id) => byId.get(id))
+    .filter(Boolean);
+  return stage("engagement", "Engage the Auditor", "Record the independent CPA firm and the current management owner who authorizes and coordinates the engagement.", [
     item(
       "engagement-record",
       "complete",
@@ -449,6 +452,21 @@ function engagementStage(audit, byId, programReadiness) {
         ? `${auditor.title} is recorded for the engagement.`
         : "Select the CPA firm and record it here. The independent management policy reviewer is a different role.",
       audit
+    ),
+    item(
+      "engagement-owner",
+      currentOwners.length ? "complete" : "action",
+      "Confirm the management engagement owner",
+      currentOwners.length
+        ? `${currentOwners.map(({ title }) => title).join(" and ")} currently owns management coordination for the engagement.`
+        : "Assign the audit to a current Person, Team, or Appointment. The audit owner may coordinate management and evidence work without a separate audit-specific title.",
+      audit,
+      {
+        commands: [
+          `npx filegrc get ${audit.id} --mutation`,
+          "npx filegrc audit-readiness AUDIT_ID --json"
+        ]
+      }
     )
   ]);
 }
@@ -556,12 +574,21 @@ function evidenceStage(audit, records, byId, model) {
     && controlIdsForRecord(record, byId).size
     && recordRelevantToAuditDate(record, audit, model)
   ));
+  const reconciledZeroPopulationControlIds = new Set(records
+    .filter((record) => (
+      record.type === "audit-population"
+      && record.auditId === audit.id
+      && record.status === "reconciled"
+      && record.conclusion === "complete"
+      && byId.get(record.sourceEvidenceId)?.populationCount === 0
+    ))
+    .flatMap((record) => record.controlIds || []));
   const managedControls = controls.filter((control) => managedFamilies.some((family) => (
     (family.controlCodes || []).includes(control.code)
   )));
   const controlsWithFilegrcRecords = managedControls.filter((control) => filegrcRecords.some((record) => (
     controlIdsForRecord(record, byId).has(control.id)
-  )));
+  )) || reconciledZeroPopulationControlIds.has(control.id));
   const externalControls = controls.filter((control) => externalFamilies.some((family) => (
     (family.controlCodes || []).includes(control.code)
   )) || !evidenceFamiliesFor(control).length);
@@ -574,7 +601,7 @@ function evidenceStage(audit, records, byId, model) {
       managedControls.length && controlsWithFilegrcRecords.length === managedControls.length ? "complete" : managedControls.length ? "action" : "info",
       "Review filegrc Evidence",
       managedControls.length
-        ? `${controlsWithFilegrcRecords.length} of ${managedControls.length} selected controls that use filegrc workflows have a dated operating record for the formal period. Complete each Step 4 record, link it to the control, and add results in its structured fields or Markdown.`
+        ? `${controlsWithFilegrcRecords.length} of ${managedControls.length} selected controls that use filegrc workflows have a dated operating record or reconciled zero-event population for the formal period. Complete each Step 4 record, link it to the control, and add results in its structured fields or Markdown.`
         : "No selected controls use a dedicated filegrc operating record.",
       filegrcRecords[0] || { type: managedFamilies[0]?.operationRecordTypes?.[0] || "control" }
     ),
@@ -606,13 +633,16 @@ function evidenceStage(audit, records, byId, model) {
       ));
       const coveredControls = relevantControls.filter((control) => sourceRecords.some((record) => (
         controlIdsForRecord(record, byId).has(control.id)
-      )));
+      )) || reconciledZeroPopulationControlIds.has(control.id));
+      const zeroPopulationControls = relevantControls.filter((control) => (
+        reconciledZeroPopulationControlIds.has(control.id)
+      ));
       items.push(item(
         `filegrc-${source.id}`,
         coveredControls.length === relevantControls.length ? "complete" : "action",
         source.title,
         coveredControls.length === relevantControls.length
-          ? `${sourceRecords.length} dated filegrc ${sourceRecords.length === 1 ? "record" : "records"} cover ${relevantControls.length} mapped controls. External artifacts needed to support those results are linked from the operating records.`
+          ? `${sourceRecords.length} dated filegrc ${sourceRecords.length === 1 ? "record" : "records"} and ${zeroPopulationControls.length} reconciled zero-population ${zeroPopulationControls.length === 1 ? "conclusion cover" : "conclusions cover"} ${relevantControls.length} mapped controls. Supporting artifacts are linked from the operating records or population export.`
           : `${coveredControls.length} of ${relevantControls.length} mapped controls have a dated ${source.operationRecordTypes.map(displayValue).join(" or ")} record for the formal period. Complete the Step 4 work and attach or reference any supporting external artifact on that record.`,
         sourceRecords[0] || { type: source.operationRecordTypes[0] }
       ));
@@ -846,6 +876,17 @@ function controlIdsForRecord(record, byId, seen = new Set()) {
   if (record.obligationId) {
     for (const id of byId.get(record.obligationId)?.controlIds || []) ids.add(id);
   }
+  for (const candidate of byId.values()) {
+    if (
+      candidate.type === "obligation"
+      && (candidate.completionResourceIds || []).includes(record.id)
+    ) {
+      for (const id of candidate.controlIds || []) ids.add(id);
+    }
+  }
+  for (const subjectId of record.subjectResourceIds || []) {
+    for (const id of controlIdsForRecord(byId.get(subjectId), byId, seen)) ids.add(id);
+  }
   for (const sourceId of record.sourceResourceIds || []) {
     for (const id of controlIdsForRecord(byId.get(sourceId), byId, seen)) ids.add(id);
   }

package/src/audit-transition.js

@@ -0,0 +1,96 @@
+import { createResource } from "./files.js";
+import { createResourceId } from "./id.js";
+import { loadWorkspace } from "./workspace.js";
+
+export async function planNextAuditCycle(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  if (String(loaded.model.modelVersion) !== "3") {
+    throw new Error("Audit-cycle carry-forward requires a model v3 workspace.");
+  }
+  const prior = loaded.resources.find((record) => (
+    record.type === "audit" && record.id === options.priorAuditId
+  ));
+  if (!prior) throw new Error("A prior Audit record is required.");
+  const startsOn = required(options.startsOn, "Next period start");
+  const endsOn = required(options.endsOn, "Next period end");
+  if (startsOn > endsOn) throw new Error("The next period end must be on or after its start.");
+  const priorEnd = prior.coverage?.endsOn || prior.coverage?.on;
+  if (prior.auditKind === "soc-2-type-1" && priorEnd && startsOn <= priorEnd) {
+    throw new Error(`A Type 2 operating period must start after the Type 1 as-of date ${priorEnd}.`);
+  }
+  const title = String(options.title || nextTitle(prior, startsOn, endsOn)).trim();
+  const audit = {
+    id: options.id || createResourceId("audit", title, loaded.resources.map(({ id }) => id)),
+    type: "audit",
+    title,
+    status: "planned",
+    auditKind: "soc-2-type-2",
+    priorAuditId: prior.id,
+    coverage: { kind: "range", startsOn, endsOn },
+    frameworkIds: [...(prior.frameworkIds || [])],
+    systemIds: [...(prior.systemIds || [])],
+    requirementIds: [...(prior.requirementIds || [])],
+    controlIds: [...(prior.controlIds || [])],
+    complementaryControlIds: [...(prior.complementaryControlIds || [])],
+    subserviceVendorIds: [...(prior.subserviceVendorIds || [])],
+    ...(prior.subserviceMethod ? { subserviceMethod: prior.subserviceMethod } : {}),
+    ...(prior.complementaryControlsConclusion
+      ? { complementaryControlsConclusion: prior.complementaryControlsConclusion }
+      : {}),
+    ...(prior.auditorVendorId ? { auditorVendorId: prior.auditorVendorId } : {}),
+    contactIds: [...(prior.contactIds || [])],
+    ownerIds: [...(prior.ownerIds || [])],
+    signatoryAppointmentIds: [...(prior.signatoryAppointmentIds || [])],
+    scope: String(options.scope || prior.scope || "").trim(),
+    ...(String(options.scopeRevision || "").trim()
+      ? { scopeRevision: String(options.scopeRevision).trim() }
+      : {})
+  };
+  return {
+    operation: prior.auditKind === "soc-2-type-1" ? "type-1-to-type-2" : "next-audit-cycle",
+    priorAuditId: prior.id,
+    audit,
+    carriedForward: [
+      "frameworkIds",
+      "systemIds",
+      "requirementIds",
+      "controlIds",
+      "complementaryControlIds",
+      "subserviceVendorIds",
+      "subserviceMethod",
+      "auditorVendorId",
+      "contactIds",
+      "ownerIds",
+      "signatoryAppointmentIds",
+      "scope"
+    ],
+    reviewRequired: [
+      "coverage",
+      "scopeRevision",
+      "criteria and control changes since the prior audit",
+      "source and policy continuity",
+      "subservice assurance coverage",
+      "new or changed commitments"
+    ]
+  };
+}
+
+export async function createNextAuditCycle(input = process.cwd(), options = {}) {
+  if (options.confirmed !== true) {
+    throw new Error("Preview the next audit cycle and confirm the write.");
+  }
+  const plan = await planNextAuditCycle(input, options);
+  const result = await createResource(input, plan.audit);
+  return { ...plan, result };
+}
+
+function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required.`);
+  return normalized;
+}
+
+function nextTitle(prior, startsOn, endsOn) {
+  const year = endsOn.slice(0, 4) || startsOn.slice(0, 4);
+  return `${year} SOC 2 Type 2 audit after ${prior.title}`;
+}

package/src/batch-review.js

@@ -0,0 +1,109 @@
+import { applyResourceBatch } from "./files.js";
+import { getGitSummary } from "./git.js";
+import { loadWorkspace } from "./workspace.js";
+
+const REVIEWABLE_TYPES = new Set([
+  "requirement",
+  "control",
+  "commitment",
+  "complementary-control"
+]);
+
+export async function scaffoldApplicabilityReview(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  if (String(loaded.model.modelVersion) !== "3") {
+    throw new Error("Batch applicability review requires a model v3 workspace.");
+  }
+  const requestedType = options.type ? String(options.type) : null;
+  if (requestedType && !REVIEWABLE_TYPES.has(requestedType)) {
+    throw new Error(`Applicability review type must be one of ${[...REVIEWABLE_TYPES].join(", ")}.`);
+  }
+  const records = loaded.resources.filter((record) => (
+    REVIEWABLE_TYPES.has(record.type)
+    && (!requestedType || record.type === requestedType)
+    && !record.applicabilityReview
+    && !["retired", "superseded"].includes(record.status)
+  ));
+  return {
+    reviewedByIds: [],
+    reviewedOn: null,
+    decisions: records
+      .sort((left, right) => `${left.type}:${left.title}:${left.id}`.localeCompare(`${right.type}:${right.title}:${right.id}`))
+      .map((record) => ({
+        id: record.id,
+        decision: null,
+        rationale: null
+      }))
+  };
+}
+
+export async function planApplicabilityReview(input = process.cwd(), options = {}) {
+  const loaded = await loadWorkspace(input);
+  if (String(loaded.model.modelVersion) !== "3") {
+    throw new Error("Batch applicability review requires a model v3 workspace.");
+  }
+  if (!Array.isArray(options.decisions) || !options.decisions.length) {
+    throw new Error("Applicability review needs at least one decision.");
+  }
+  const byId = new Map(loaded.resources.map((record) => [record.id, record]));
+  const update = options.decisions.map((decision) => {
+    const record = byId.get(decision.id);
+    if (!record || !REVIEWABLE_TYPES.has(record.type)) {
+      throw new Error(`Resource "${decision.id}" is not an applicability-review record.`);
+    }
+    const reviewedByIds = [...new Set((decision.reviewedByIds || options.reviewedByIds || []).map(String))];
+    const reviewedOn = String(decision.reviewedOn || options.reviewedOn || "").trim();
+    const scopeRevision = String(
+      decision.scopeRevision
+      || options.scopeRevision
+      || getGitSummary(loaded.root).commit
+      || "uncommitted"
+    ).trim();
+    const rationale = String(decision.rationale || "").trim();
+    const result = String(decision.decision || "").trim();
+    if (!["applicable", "not-applicable", "externally-managed", "zero-population"].includes(result)) {
+      throw new Error(`Decision for "${record.id}" must be applicable, not-applicable, externally-managed, or zero-population.`);
+    }
+    if (!reviewedByIds.length || !reviewedOn || !rationale) {
+      throw new Error(`Decision for "${record.id}" needs a reviewer, review date, and rationale.`);
+    }
+    const next = {
+      ...record,
+      applicabilityReview: {
+        decision: result,
+        rationale,
+        reviewedByIds,
+        reviewedOn,
+        scopeRevision
+      }
+    };
+    if (record.type === "requirement") {
+      if (!["applicable", "not-applicable"].includes(result)) {
+        throw new Error(`Requirement "${record.id}" must be applicable or not-applicable.`);
+      }
+      next.applicability = result;
+      next.applicabilityRationale = rationale;
+    }
+    if (record.type === "control" && result === "not-applicable") next.status = "not-applicable";
+    if (record.type === "control" && result === "applicable" && record.status === "not-applicable") next.status = "planned";
+    return next;
+  });
+  return {
+    operation: "applicability-review",
+    reviewedIds: update.map(({ id }) => id),
+    changes: {
+      update,
+      expectedRevisions: options.expectedRevisions || {},
+      validateWholeWorkspace: true
+    }
+  };
+}
+
+export async function applyApplicabilityReview(input = process.cwd(), options = {}) {
+  if (options.confirmed !== true) {
+    throw new Error("Preview the applicability decisions and confirm the write.");
+  }
+  const plan = await planApplicabilityReview(input, options);
+  const result = await applyResourceBatch(input, plan.changes);
+  return { ...plan, result };
+}