filegrc 0.1.0 → 0.2.0

package/package.json

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

package/src/agent.js

@@ -1,5 +1,6 @@
 import { createResourceId } from "./id.js";
 import { markdownEntries } from "./resource-markdown.js";
+import { RESOURCE_INSTRUCTIONS, resourceProgramContext } from "./program-path.js";
 
 const STARTING_STATUS_ORDER = [
   "draft",
@@ -73,7 +74,10 @@ export function buildAgentGuide(loaded, type, options = {}) {
     type,
     title: definition.title,
     pluralTitle: definition.pluralTitle,
+    instructions: RESOURCE_INSTRUCTIONS[type] || definition.description,
+    use: definition.description,
     purpose: definition.description,
+    programStep: resourceProgramContext(type),
     policyBasis: definition.guidance.policyBasis,
     cadence: definition.guidance.cadence,
     policySourceIds: definition.guidance.sourceResourceIds ?? [],

package/src/audit-preparation.js

@@ -3,9 +3,34 @@ import { readFile } from "node:fs/promises";
 import { createResource, createResources, deleteResource, updateResource } from "./files.js";
 import { createResourceId } from "./id.js";
 import { resolveDataPath } from "./paths.js";
+import { assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { loadWorkspace } from "./workspace.js";
 
+const NON_EVIDENCE_RECORD_TYPES = new Set([
+  "audit",
+  "audit-population",
+  "audit-request",
+  "commitment",
+  "complementary-control",
+  "control",
+  "control-test",
+  "document",
+  "evidence",
+  "framework",
+  "obligation",
+  "organization",
+  "person",
+  "policy",
+  "renderer-settings",
+  "requirement",
+  "system",
+  "team",
+  "training",
+  "vendor",
+  "workspace"
+]);
+
 export async function assessAuditPreparation(input, options = {}) {
   const loaded = input?.resources && input?.model && input?.entries
     ? input
@@ -20,13 +45,23 @@ export async function assessAuditPreparation(input, options = {}) {
       : audits.find((record) => !["complete", "closed", "canceled"].includes(record.status)) || audits[0];
   if (options.auditId && !audit) throw new Error(`Audit "${options.auditId}" was not found.`);
 
-  const stages = [];
-  stages.push(scopeStage(audit, records, byId));
-  stages.push(programStage(audit, records, byId));
-  stages.push(await documentsStage(loaded, audit, byId));
-  stages.push(evidenceStage(audit, records, byId, loaded.model));
-  stages.push(populationsStage(audit, records, byId, loaded.model));
-  stages.push(auditorStage(loaded.model));
+  const programReadiness = options.programReadiness || await assessProgramReadiness(loaded, {
+    generatedAt: options.generatedAt
+  });
+  const stages = [
+    programFoundationStage(programReadiness, loaded.workspace),
+    engagementStage(audit, byId, programReadiness),
+    scopeStage(audit, records, byId, programReadiness)
+  ];
+  const fieldworkSections = audit
+    ? [
+        await documentsStage(loaded, audit, byId),
+        evidenceStage(audit, records, byId, loaded.model),
+        populationsStage(audit, records, byId, loaded.model)
+      ]
+    : [];
+  stages.push(fieldworkStage(audit, fieldworkSections));
+  stages.push(auditorStage());
 
   for (const stage of stages) {
     stage.counts = countStatuses(stage.items);
@@ -40,7 +75,7 @@ export async function assessAuditPreparation(input, options = {}) {
     schemaVersion: 1,
     generatedAt: options.generatedAt || new Date().toISOString(),
     audit: audit ? auditSummary(audit) : null,
-    status: counts.action ? "needs-work" : audit ? "management-ready" : "not-started",
+    status: !audit ? "not-started" : counts.action ? "needs-work" : "management-ready",
     progress: {
       complete: completedManagedItems.length,
       total: managedItems.length,
@@ -169,19 +204,17 @@ export async function prepareAuditWorkspace(input, options = {}) {
   };
 }
 
-function scopeStage(audit, records, byId) {
+function scopeStage(audit, records, byId, programReadiness) {
   const items = [];
-  items.push(item(
-    "engagement",
-    audit ? "complete" : "action",
-    "Create the engagement",
-    audit
-      ? `${audit.title} is the audit record used for scope, dates, the CPA firm, requests, and the final report.`
-      : "Create a SOC 2 Type 2 audit record before collecting period evidence.",
-    audit || { type: "audit" }
-  ));
   if (!audit) {
-    return stage("scope", "Scope and Engagement", "Define the report, service boundary, criteria, dependencies, and CPA firm.", items);
+    items.push(item(
+      "formal-period",
+      "later",
+      "Confirm the formal report scope and period",
+      "Create the engagement after selecting a CPA firm. Keep operating the management program and preserving evidence in the meantime.",
+      { type: "audit" }
+    ));
+    return stage("period", "Confirm the Formal Period", "Record the auditor-agreed report scope and dates without overwriting management's candidate period.", items);
   }
 
   const periodComplete = audit.auditKind === "soc-2-type-2"
@@ -192,11 +225,11 @@ function scopeStage(audit, records, byId) {
   items.push(item(
     "period",
     periodComplete ? "complete" : "action",
-    "Set the report type and date",
+    "Set the auditor-agreed report type and date",
     periodComplete
       ? audit.auditKind === "soc-2-type-2"
-        ? `Type 2 period: ${audit.periodStart} through ${audit.periodEnd}.`
-        : `Type 1 as-of date: ${audit.typeOneAsOf}.`
+        ? `Auditor-agreed Type 2 period: ${audit.periodStart} through ${audit.periodEnd}.`
+        : `Auditor-agreed Type 1 as-of date: ${audit.typeOneAsOf}.`
       : audit.auditKind === "soc-2-type-1"
         ? "Set the Type 1 as-of date."
         : audit.auditKind === "soc-2-type-2"
@@ -204,6 +237,21 @@ function scopeStage(audit, records, byId) {
           : "Change this readiness record to a Type 1 or Type 2 engagement before planning the report.",
     audit
   ));
+  if (audit.auditKind === "soc-2-type-2" && programReadiness.target.candidatePeriodStart) {
+    const candidate = [programReadiness.target.candidatePeriodStart, programReadiness.target.candidatePeriodEnd]
+      .filter(Boolean)
+      .join(" through ");
+    const agreed = [audit.periodStart, audit.periodEnd].filter(Boolean).join(" through ");
+    items.push(item(
+      "candidate-period-comparison",
+      "info",
+      "Compare candidate and auditor-agreed periods",
+      agreed
+        ? `Management candidate: ${candidate}. Auditor agreed: ${agreed}. Preserve both sets of dates when they differ.`
+        : `Management candidate: ${candidate}. The formal period remains unset until the CPA firm agrees to it.`,
+      audit
+    ));
+  }
 
   const systems = (audit.systemIds || []).map((id) => byId.get(id)).filter(Boolean);
   const completeSystems = systems.filter((system) => (
@@ -350,87 +398,79 @@ function scopeStage(audit, records, byId) {
     audit
   ));
 
-  const auditor = audit.auditorVendorId ? byId.get(audit.auditorVendorId) : null;
-  const auditorNamed = Boolean(auditor || hasMeaningfulValue(audit.auditor));
-  items.push(item(
-    "auditor",
-    auditorNamed ? "complete" : "action",
-    "Engage an independent CPA firm",
-    auditorNamed
-      ? `${auditor?.title || "An independent CPA firm"} is recorded for the engagement.`
-      : "Select a CPA firm and agree on scope, timing, subservice treatment, and evidence expectations early.",
-    audit
-  ));
-  return stage("scope", "Scope and Engagement", "Define the report, service boundary, criteria, dependencies, and CPA firm.", items);
-}
-
-function programStage(audit, records, byId) {
-  const selectedControls = audit?.controlIds?.length
-    ? audit.controlIds.map((id) => byId.get(id)).filter(Boolean)
-    : records.filter((record) => record.type === "control" && record.status !== "retired");
-  const policyIds = new Set(selectedControls.flatMap((control) => control.policyIds || []));
-  const policies = (policyIds.size
-    ? [...policyIds].map((id) => byId.get(id)).filter(Boolean)
-    : records.filter((record) => record.type === "policy" && !["superseded", "retired"].includes(record.status)));
-  const approvedPolicies = policies.filter((policy) => (
-    ["approved", "active"].includes(policy.status)
-    && policy.approvedOn
-    && policy.effectiveOn
-    && (policy.ownerIds || []).length
-    && (policy.approverIds || []).length
-    && partiesIndependent(policy.ownerIds, policy.approverIds, byId)
-  ));
-  const implementedControls = selectedControls.filter((control) => (
-    control.status === "implemented"
-    && control.effectiveOn
-    && control.activity
-    && control.operationMode
-    && control.frequency
-    && (control.ownerIds || []).length
-    && (control.requirementIds || []).length
-    && (control.policyIds || []).length
-    && (!audit?.systemIds?.length || (control.systemIds || []).some((id) => audit.systemIds.includes(id)))
-  ));
-  const assessment = records.find((record) => (
-    record.type === "risk-assessment"
-    && record.status === "complete"
-    && record.methodology
-    && record.approvedOn
-    && partiesIndependent(record.assessorIds, record.reviewerIds, byId)
-    && (!audit?.periodEnd || (record.assessmentDate <= audit.periodEnd && record.assessmentDate >= shiftYear(audit.periodEnd, -1)))
-    && (!audit?.systemIds?.length || !(record.systemIds || []).length || record.systemIds.some((id) => audit.systemIds.includes(id)))
-  ));
-  return stage("program", "Adopt and Implement", "Approve the rules, confirm the controls match actual operation, and assess risk.", [
+  return stage("period", "Confirm the Formal Period", "Record the auditor-agreed report type, date or period, scope, criteria, systems, and dependency treatment.", items);
+}
+
+function programFoundationStage(programReadiness, workspace) {
+  const ready = programReadiness.evidenceReady;
+  return stage("program", "Program Readiness", "The management program can be prepared and operated without an audit record or CPA firm.", [
     item(
-      "policies",
-      policies.length && approvedPolicies.length === policies.length ? "complete" : "action",
-      "Approve the applicable policies",
-      policies.length
-        ? `${approvedPolicies.length} of ${policies.length} applicable policies have an owner, separate approver, approval date, and effective date.`
-        : "Link the controls to the policies management will adopt.",
-      approvedPolicies[0] || policies[0] || { type: "policy" }
-    ),
+      "evidence-ready",
+      ready ? "complete" : "action",
+      "Reach the Evidence Ready gate",
+      ready
+        ? `${programReadiness.target.label} is evidence-ready. ${programReadiness.operating ? "Evidence collection is running." : "Management can begin the candidate period."}`
+        : `${programReadiness.counts.action} program-readiness actions remain across scope, policies, controls, and evidence preparation.`,
+      workspace || { type: "workspace" }
+    )
+  ]);
+}
+
+function engagementStage(audit, byId, programReadiness) {
+  if (!audit) {
+    return stage("engagement", "Engage the Auditor", "Select a CPA firm after the program is evidence-ready, or earlier when a customer deadline makes coordination urgent.", [
+      item(
+        "engagement",
+        programReadiness.evidenceReady ? "action" : "later",
+        "Create the CPA engagement",
+        programReadiness.evidenceReady
+          ? "Select the independent CPA firm, sign the engagement, then create the audit record with the firm and contacts."
+          : "Finish the management program first. Early auditor engagement remains available when a customer deadline requires it.",
+        { type: "audit" }
+      )
+    ]);
+  }
+  const auditor = audit.auditorVendorId ? byId.get(audit.auditorVendorId) : null;
+  const named = Boolean(auditor || hasMeaningfulValue(audit.auditor));
+  return stage("engagement", "Engage the Auditor", "Record the independent CPA firm and engagement contacts before treating the audit as active.", [
     item(
-      "controls",
-      selectedControls.length && implementedControls.length === selectedControls.length ? "complete" : "action",
-      "Confirm every control is implemented",
-      selectedControls.length
-        ? `${implementedControls.length} of ${selectedControls.length} selected controls are implemented, effective, owned, mapped, scoped, and define their activity, mode, and frequency.`
-        : "Select the controls for the engagement, then confirm each statement matches current practice.",
-      implementedControls[0] || selectedControls[0] || { type: "control" }
+      "engagement-record",
+      "complete",
+      "Create the engagement record",
+      `${audit.title} tracks the formal scope, dates, requests, fieldwork, and report.`,
+      audit
     ),
     item(
-      "risk-assessment",
-      assessment ? "complete" : "action",
-      "Complete the in-scope risk assessment",
-      assessment
-        ? `${assessment.title} is the most recent completed, approved, and independently reviewed assessment found for the service.`
-        : "Complete an in-scope risk assessment during the year ending with the report date or period, using the approved method and a reviewer separate from the assessor.",
-      assessment || { type: "risk-assessment" }
+      "auditor",
+      named ? "complete" : "action",
+      "Record the independent CPA firm",
+      named
+        ? `${auditor?.title || audit.auditor?.firm || "The independent CPA firm"} is recorded for the engagement.`
+        : "Select the CPA firm and record it here. The independent management policy reviewer is a different role.",
+      audit
     )
   ]);
 }
 
+function fieldworkStage(audit, sections) {
+  if (!audit) {
+    return stage("fieldwork", "Prepare Fieldwork", "Build engagement-specific documents, exact-period evidence, and Type 2 populations after the firm and period are recorded.", [
+      item("fieldwork-later", "later", "Prepare engagement-specific fieldwork", "This work starts after the CPA engagement and formal period exist.", { type: "audit" })
+    ]);
+  }
+  const items = sections.flatMap((section) => section.items.map((current) => ({
+    ...current,
+    id: `${section.id}-${current.id}`,
+    section: section.title
+  })));
+  return stage(
+    "fieldwork",
+    "Prepare Fieldwork",
+    "Complete management documents, exact-period operating evidence, and Type 2 population reconciliations for the engagement.",
+    items
+  );
+}
+
 async function documentsStage(loaded, audit, byId) {
   const definitions = applicableManagementDocuments(audit, loaded.model.auditReadiness || {});
   const items = [];
@@ -500,27 +540,55 @@ async function documentsStage(loaded, audit, byId) {
 function evidenceStage(audit, records, byId, model) {
   const controls = (audit?.controlIds || []).map((id) => byId.get(id)).filter(Boolean);
   const evidence = records.filter((record) => record.type === "evidence");
-  const periodEvidence = evidence.filter((record) => (
+  const externalEvidence = evidence.filter((record) => (
     record.status === "verified"
     && (record.evidenceKind !== "rendered-record" || record.sourceCommit)
     && evidenceRelevantToAuditDate(record, audit)
   ));
-  const controlsWithEvidence = controls.filter((control) => periodEvidence.some((record) => (
+  const managedFamilies = (model.evidenceSourceFamilies || []).filter((family) => family.collectionTestRequired === false);
+  const externalFamilies = (model.evidenceSourceFamilies || []).filter((family) => family.collectionTestRequired !== false);
+  const evidenceFamiliesFor = (control) => (model.evidenceSourceFamilies || []).filter((family) => (
+    (family.controlCodes || []).includes(control.code)
+  ));
+  const fileGRCRecords = records.filter((record) => (
+    !NON_EVIDENCE_RECORD_TYPES.has(record.type)
+    && controlIdsForRecord(record, byId).size
+    && recordRelevantToAuditDate(record, audit, model)
+  ));
+  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)
+  )));
+  const externalControls = controls.filter((control) => externalFamilies.some((family) => (
+    (family.controlCodes || []).includes(control.code)
+  )) || !evidenceFamiliesFor(control).length);
+  const controlsWithExternalEvidence = externalControls.filter((control) => externalEvidence.some((record) => (
     controlIdsForRecord(record, byId).has(control.id)
   )));
   const items = [
     item(
-      "control-evidence",
-      controls.length && controlsWithEvidence.length === controls.length ? "complete" : "action",
-      "Collect operating evidence from authoritative systems",
-      controls.length
-        ? `${controlsWithEvidence.length} of ${controls.length} selected controls have verified evidence for the period.`
-        : "Select the engagement controls before checking their operating evidence.",
-      periodEvidence[0] || { type: "evidence" }
+      "filegrc-evidence",
+      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 5 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" }
+    ),
+    item(
+      "external-evidence",
+      externalControls.length && controlsWithExternalEvidence.length === externalControls.length ? "complete" : externalControls.length ? "action" : "info",
+      "Review External Evidence",
+      externalControls.length
+        ? `${controlsWithExternalEvidence.length} of ${externalControls.length} selected controls that rely on external systems have verified External Evidence for the formal period. Confirm the source System, date or period, control links, collector, verifier, and retained artifact or approved external reference.`
+        : "No selected controls require a separate External Evidence record.",
+      externalEvidence[0] || { type: "evidence" }
     )
   ];
   const systems = records.filter((record) => record.type === "system" && record.status === "active");
-  for (const source of model.auditReadiness?.externalEvidence || []) {
+  for (const source of model.evidenceSourceFamilies || []) {
     const relevantControls = controls.filter((control) => (source.controlCodes || []).includes(control.code));
     if (!relevantControls.length) {
       items.push(item(
@@ -531,10 +599,28 @@ function evidenceStage(audit, records, byId, model) {
       ));
       continue;
     }
+    if (source.collectionTestRequired === false) {
+      const sourceRecords = fileGRCRecords.filter((record) => (
+        relevantControls.some((control) => controlIdsForRecord(record, byId).has(control.id))
+      ));
+      const coveredControls = relevantControls.filter((control) => sourceRecords.some((record) => (
+        controlIdsForRecord(record, byId).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.`
+          : `${coveredControls.length} of ${relevantControls.length} mapped controls have a dated ${source.operationRecordTypes.map(displayValue).join(" or ")} record for the formal period. Complete the Step 5 work and attach or reference any supporting external artifact on that record.`,
+        sourceRecords[0] || { type: source.operationRecordTypes[0] }
+      ));
+      continue;
+    }
     const sourceSystems = systems.filter((system) => (
       (system.evidenceSourceKinds || []).some((kind) => (source.sourceKinds || []).includes(kind))
     ));
-    const coveredControls = relevantControls.filter((control) => periodEvidence.some((record) => (
+    const coveredControls = relevantControls.filter((control) => externalEvidence.some((record) => (
       sourceSystems.some((system) => system.id === record.sourceSystemId)
       && controlIdsForRecord(record, byId).has(control.id)
     )));
@@ -549,12 +635,12 @@ function evidenceStage(audit, records, byId, model) {
       status,
       source.title,
       message,
-      periodEvidence.find((record) => sourceSystems.some((system) => system.id === record.sourceSystemId))
+      externalEvidence.find((record) => sourceSystems.some((system) => system.id === record.sourceSystemId))
         || sourceSystems[0]
         || { type: "system" }
     ));
   }
-  return stage("evidence", "Operating Evidence Sources", "Catalog each authoritative system, record when to extract its evidence, and bind verified exports to the controls. FileGRC packages the proof but does not replace those systems.", items);
+  return stage("evidence", "Audit Evidence", "Review both evidence paths: dated FileGRC operating records and verified External Evidence from authoritative systems. FileGRC includes both in the audit packet.", items);
 }
 
 function populationsStage(audit, records, byId, model) {
@@ -589,8 +675,8 @@ function populationsStage(audit, records, byId, model) {
   );
 }
 
-function auditorStage(model) {
-  return stage("auditor", "Auditor-Owned Work", "FileGRC prepares the record set but does not make the CPA firm's independent judgments.", [
+function auditorStage() {
+  return stage("auditor", "Fieldwork and Report", "FileGRC prepares the record set but does not make the CPA firm's independent judgments.", [
     item("firm-eligibility", "external", "Firm eligibility and independence", "Confirm directly with the engagement partner that the firm and signing practitioner meet applicable licensing, peer-review, ethics, and independence requirements. Keep the signed engagement terms with the audit record if management needs a copy."),
     item("sampling", "external", "Sample selection and independent testing", "The auditor chooses samples, performs tests, evaluates exceptions, and decides whether more work is needed."),
     item("report", "external", "Report and opinion", "Management reviews and signs its representations. The auditor issues the final report and opinion."),
@@ -722,6 +808,27 @@ function evidenceRelevantToAuditDate(record, audit) {
     && evidenceOverlaps(record, audit.periodStart, audit.periodEnd);
 }
 
+function recordRelevantToAuditDate(record, audit, model) {
+  if (!audit) return false;
+  const start = audit.auditKind === "soc-2-type-1" ? audit.typeOneAsOf : audit.periodStart;
+  const end = audit.auditKind === "soc-2-type-1" ? audit.typeOneAsOf : audit.periodEnd;
+  if (!start || !end) return false;
+  if (record.periodStart && record.periodEnd && record.periodStart <= end && record.periodEnd >= start) {
+    return true;
+  }
+  const definition = model.resources[record.type];
+  const fields = { ...model.commonFields, ...(definition?.fields || {}) };
+  return Object.entries(fields).some(([name, field]) => {
+    const value = record[name];
+    if (field.type === "date") return value >= start && value <= end;
+    if (field.type === "timestamp" && typeof value === "string") {
+      const date = value.slice(0, 10);
+      return date >= start && date <= end;
+    }
+    return false;
+  });
+}
+
 function controlIdsForRecord(record, byId, seen = new Set()) {
   const ids = new Set();
   if (!record || seen.has(record.id)) return ids;
@@ -898,9 +1005,3 @@ function countStatuses(items) {
 function displayValue(value) {
   return String(value || "not started").replaceAll("-", " ").replace(/\b\w/g, (character) => character.toUpperCase());
 }
-
-function shiftYear(value, offset) {
-  const date = new Date(`${value}T00:00:00Z`);
-  date.setUTCFullYear(date.getUTCFullYear() + offset);
-  return date.toISOString().slice(0, 10);
-}