filegrc 0.3.4 → 0.4.0

package/package.json

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

package/src/agent.js

@@ -66,6 +66,7 @@ export function buildAgentGuide(loaded, type, options = {}) {
   const requiredAtCreation = fieldList.filter(({ required: isRequired }) => isRequired);
   const conditionalRequirements = fieldList.filter(({ requiredWhen, required: isRequired }) => requiredWhen && !isRequired);
   const optionalFields = fieldList.filter(({ required, requiredWhen }) => !required && !requiredWhen);
+  const recommendedMarkdown = markdown.filter(({ recommended }) => recommended);
   const location = definition.singleton
     ? `data/${definition.singleton}`
     : `data/${definition.collection}/${(definition.recordPath ?? "{id}.json").replaceAll("{id}", options.id || "{id}")}`;
@@ -91,15 +92,21 @@ export function buildAgentGuide(loaded, type, options = {}) {
     markdown,
     workflow: [
       "Inspect existing records and relation candidates before writing.",
-      "Create a scaffold, then replace every null value and empty required array with facts from an authoritative source.",
-      "Keep stable metadata in JSON and put the work performed, inputs, results, decisions, exceptions, and follow-up in the recommended Markdown companion.",
+      definition.singleton
+        ? "Open the existing singleton record, then replace every null value and empty required array with facts from an authoritative source."
+        : "Create a scaffold, then replace every null value and empty required array with facts from an authoritative source.",
+      recommendedMarkdown.length
+        ? "Keep model fields in JSON and use the recommended Markdown companion for the detailed work, decisions, results, exceptions, and follow-up that apply to this record."
+        : "Keep the current facts and lifecycle state in JSON. Add optional Record Markdown only when the model fields cannot explain the record clearly.",
       "Run npx filegrc validate, review the full Git diff, and commit the JSON, Markdown, and attachments together with a message that explains why the record changed."
     ],
     completionChecks: [
-      "The record describes work that actually occurred; planned work is not marked complete.",
+      "Required and status-dependent fields are complete, and the lifecycle status matches the facts.",
       "Every relationship resolves to the intended existing record.",
       "Dates describe the business event in the workspace time zone, not the file edit time.",
-      "Results, exceptions, decisions, evidence, and follow-up records are linked where applicable.",
+      ...(recommendedMarkdown.length
+        ? ["Required or recommended Markdown explains the work, decisions, results, exceptions, and follow-up that apply."]
+        : ["The structured fields state the current fact clearly; optional Record Markdown is added only when needed."]),
       "No secrets or personal data that may need erasure were added to Git."
     ]
   };
@@ -131,14 +138,22 @@ export function scaffoldResourceMutation(loaded, type, title, options = {}) {
     ...(definition.required ?? [])
   ]);
   const record = {
-    schemaVersion: 1,
     id,
     type,
     title: normalizedTitle
   };
   for (const name of required) {
     if (record[name] !== undefined) continue;
-    record[name] = scaffoldValue(name, fields[name]);
+    record[name] = scaffoldValue(name, fields[name], loaded.model);
+  }
+  for (const [name, field] of Object.entries(fields)) {
+    if (
+      record[name] === undefined
+      && field.requiredWhen
+      && conditionMatches(record, field.requiredWhen)
+    ) {
+      record[name] = scaffoldValue(name, field, loaded.model);
+    }
   }
 
   const slots = markdownEntries(loaded.model, record).filter((slot) => (
@@ -210,17 +225,30 @@ function allowedValues(model, field) {
   return null;
 }
 
-function scaffoldValue(name, field = {}) {
+function scaffoldValue(name, field = {}, model) {
   if (field.const !== undefined) return field.const;
   if (name === "status" && field.values) {
     return STARTING_STATUS_ORDER.find((value) => field.values.includes(value)) ?? field.values[0] ?? null;
   }
   if (field.type === "array") return [];
-  if (field.type === "object") return {};
+  if (field.type === "object") {
+    const schema = model?.objectTypes?.[field.objectType];
+    if (!schema) return {};
+    return Object.fromEntries((schema.required || []).map((propertyName) => [
+      propertyName,
+      scaffoldValue(propertyName, schema.properties?.[propertyName], model)
+    ]));
+  }
   if (field.type === "boolean") return false;
   return null;
 }
 
+function conditionMatches(record, condition) {
+  return Object.entries(condition || {}).every(([name, expected]) => (
+    Array.isArray(expected) ? expected.includes(record[name]) : record[name] === expected
+  ));
+}
+
 function markdownScaffold(title, type, slot) {
   const heading = slot.label === "Record" ? title : `${title}: ${slot.label}`;
   const sections = slot.name === "agenda"

package/src/audit-preparation.js

@@ -1,5 +1,13 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
+import {
+  coverageContains,
+  coverageEnd,
+  coverageLabel,
+  coverageMatches,
+  coverageOverlaps,
+  coverageStart
+} from "./coverage.js";
 import { createResource, createResources, deleteResource, updateResource } from "./files.js";
 import { createResourceId } from "./id.js";
 import { partiesIndependent } from "./parties.js";
@@ -85,9 +93,8 @@ export async function assessAuditPreparation(input, options = {}) {
     counts,
     canInitialize: Boolean(audit
       && ["soc-2-type-1", "soc-2-type-2"].includes(audit.auditKind)
-      && (audit.auditKind === "soc-2-type-1"
-        ? audit.typeOneAsOf
-        : audit.periodStart && audit.periodEnd)
+      && coverageStart(audit.coverage)
+      && coverageEnd(audit.coverage)
       && initializationNeeded(audit, records, loaded.model)),
     stages
   };
@@ -100,10 +107,10 @@ export async function prepareAuditWorkspace(input, options = {}) {
   if (!["soc-2-type-1", "soc-2-type-2"].includes(audit.auditKind)) {
     throw new Error("Audit preparation requires a SOC 2 Type 1 or Type 2 engagement.");
   }
-  if (audit.auditKind === "soc-2-type-2" && (!audit.periodStart || !audit.periodEnd)) {
+  if (audit.auditKind === "soc-2-type-2" && audit.coverage?.kind !== "range") {
     throw new Error("Set the Type 2 audit period before initializing audit preparation.");
   }
-  if (audit.auditKind === "soc-2-type-1" && !audit.typeOneAsOf) {
+  if (audit.auditKind === "soc-2-type-1" && audit.coverage?.kind !== "as-of") {
     throw new Error("Set the Type 1 as-of date before initializing audit preparation.");
   }
 
@@ -167,15 +174,13 @@ export async function prepareAuditWorkspace(input, options = {}) {
         (system.evidenceSourceKinds || []).includes(template.sourceKind)
       ));
       return {
-        schemaVersion: 1,
         id,
         type: "audit-population",
         title: template.title,
         status: "planned",
         auditId: audit.id,
         populationKind: template.kind,
-        periodStart: audit.periodStart,
-        periodEnd: audit.periodEnd,
+        coverage: structuredClone(audit.coverage),
         ownerIds: [...audit.ownerIds],
         ...(controlIds.length ? { controlIds } : {}),
         ...(matchingSources.length === 1 ? { sourceSystemId: matchingSources[0].id } : {}),
@@ -219,9 +224,9 @@ function scopeStage(audit, records, byId, programReadiness) {
   }
 
   const periodComplete = audit.auditKind === "soc-2-type-2"
-    ? audit.periodStart && audit.periodEnd
+    ? audit.coverage?.kind === "range"
     : audit.auditKind === "soc-2-type-1"
-      ? audit.typeOneAsOf
+      ? audit.coverage?.kind === "as-of"
       : false;
   items.push(item(
     "period",
@@ -229,8 +234,8 @@ function scopeStage(audit, records, byId, programReadiness) {
     "Set the auditor-agreed report type and date",
     periodComplete
       ? audit.auditKind === "soc-2-type-2"
-        ? `Auditor-agreed Type 2 period: ${audit.periodStart} through ${audit.periodEnd}.`
-        : `Auditor-agreed Type 1 as-of date: ${audit.typeOneAsOf}.`
+        ? `Auditor-agreed Type 2 period: ${coverageLabel(audit.coverage)}.`
+        : `Auditor-agreed Type 1 as-of date: ${coverageLabel(audit.coverage)}.`
       : audit.auditKind === "soc-2-type-1"
         ? "Set the Type 1 as-of date."
         : audit.auditKind === "soc-2-type-2"
@@ -238,11 +243,9 @@ function scopeStage(audit, records, byId, programReadiness) {
           : "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 ");
+  if (audit.auditKind === "soc-2-type-2" && programReadiness.target.candidateCoverage) {
+    const candidate = coverageLabel(programReadiness.target.candidateCoverage);
+    const agreed = coverageLabel(audit.coverage);
     items.push(item(
       "candidate-period-comparison",
       "info",
@@ -257,9 +260,8 @@ function scopeStage(audit, records, byId, programReadiness) {
   const systems = (audit.systemIds || []).map((id) => byId.get(id)).filter(Boolean);
   const completeSystems = systems.filter((system) => (
     system.status === "active"
-    && system.inScope === true
     && system.description
-    && system.dataClassification
+    && system.classificationId
     && (system.ownerIds || []).length
   ));
   items.push(item(
@@ -272,12 +274,10 @@ function scopeStage(audit, records, byId, programReadiness) {
     systems[0] || { type: "system" }
   ));
 
-  const engagementStart = audit.auditKind === "soc-2-type-1" ? audit.typeOneAsOf : audit.periodStart;
+  const engagementStart = coverageStart(audit.coverage);
   const commitments = records.filter((record) => record.type === "commitment"
     && record.status === "active"
-    && systems.some((system) => (
-      (system.commitmentIds || []).includes(record.id) || (record.systemIds || []).includes(system.id)
-    )));
+    && systems.some((system) => (record.systemIds || []).includes(system.id)));
   const completeCommitments = commitments.filter((commitment) => (
     commitment.statement
     && (commitment.ownerIds || []).length
@@ -287,7 +287,7 @@ function scopeStage(audit, records, byId, programReadiness) {
     && (commitment.controlIds || []).length
   ));
   const systemsWithoutCommitments = systems.filter((system) => !completeCommitments.some((commitment) => (
-    (system.commitmentIds || []).includes(commitment.id) || (commitment.systemIds || []).includes(system.id)
+    (commitment.systemIds || []).includes(system.id)
   )));
   items.push(item(
     "commitments",
@@ -432,7 +432,7 @@ function engagementStage(audit, byId, programReadiness) {
     ]);
   }
   const auditor = audit.auditorVendorId ? byId.get(audit.auditorVendorId) : null;
-  const named = Boolean(auditor || hasMeaningfulValue(audit.auditor));
+  const named = Boolean(auditor);
   return stage("engagement", "Engage the Auditor", "Record the independent CPA firm and engagement contacts before treating the audit as active.", [
     item(
       "engagement-record",
@@ -446,7 +446,7 @@ function engagementStage(audit, byId, programReadiness) {
       named ? "complete" : "action",
       "Record the independent CPA firm",
       named
-        ? `${auditor?.title || audit.auditor?.firm || "The independent CPA firm"} is recorded for the engagement.`
+        ? `${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
     )
@@ -479,7 +479,7 @@ async function documentsStage(loaded, audit, byId) {
     const document = audit?.[definition.field] ? byId.get(audit[definition.field]) : null;
     const source = document ? await primaryMarkdown(loaded, document) : "";
     const contentIssues = managementDocumentContentIssues(source, definition, audit);
-    const engagementEnd = audit?.auditKind === "soc-2-type-1" ? audit.typeOneAsOf : audit?.periodEnd;
+    const engagementEnd = coverageEnd(audit?.coverage);
     if (document?.approvedOn && engagementEnd && document.approvedOn < engagementEnd) {
       contentIssues.push(`Approve the final document on or after the engagement ${audit.auditKind === "soc-2-type-1" ? "date" : "period end"}.`);
     }
@@ -543,11 +543,11 @@ function evidenceStage(audit, records, byId, model) {
   const evidence = records.filter((record) => record.type === "evidence");
   const externalEvidence = evidence.filter((record) => (
     record.status === "verified"
-    && (record.evidenceKind !== "rendered-record" || record.sourceCommit)
+    && (record.artifactKind !== "rendered-page" || record.sourceCommit)
     && evidenceRelevantToAuditDate(record, audit)
   ));
-  const managedFamilies = (model.evidenceSourceFamilies || []).filter((family) => family.collectionTestRequired === false);
-  const externalFamilies = (model.evidenceSourceFamilies || []).filter((family) => family.collectionTestRequired !== false);
+  const managedFamilies = (model.evidenceSourceFamilies || []).filter((family) => family.filegrcManaged === true);
+  const externalFamilies = (model.evidenceSourceFamilies || []).filter((family) => family.filegrcManaged !== true);
   const evidenceFamiliesFor = (control) => (model.evidenceSourceFamilies || []).filter((family) => (
     (family.controlCodes || []).includes(control.code)
   ));
@@ -574,7 +574,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 5 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 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" }
     ),
@@ -600,7 +600,7 @@ function evidenceStage(audit, records, byId, model) {
       ));
       continue;
     }
-    if (source.collectionTestRequired === false) {
+    if (source.filegrcManaged === true) {
       const sourceRecords = filegrcRecords.filter((record) => (
         relevantControls.some((control) => controlIdsForRecord(record, byId).has(control.id))
       ));
@@ -613,7 +613,7 @@ function evidenceStage(audit, records, byId, model) {
         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.`,
+          : `${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] }
       ));
       continue;
@@ -687,7 +687,11 @@ function auditorStage() {
 
 function populationResult(population, audit, byId) {
   if (!population) return { status: "action", message: "Initialize this population for the engagement." };
-  if (population.periodStart !== audit?.periodStart || population.periodEnd !== audit?.periodEnd) {
+  if (!coverageMatches(
+    population.coverage,
+    coverageStart(audit?.coverage),
+    coverageEnd(audit?.coverage)
+  )) {
     return { status: "action", message: "The population period does not match the exact audit period." };
   }
   if (population.status === "not-applicable") {
@@ -712,12 +716,15 @@ function populationResult(population, audit, byId) {
   ];
   const evidenceComplete = evidence
     && evidence.type === "evidence"
-    && evidence.evidenceKind === "population-export"
+    && evidence.artifactKind === "population-export"
     && evidence.status === "verified"
     && population.sourceSystemId
     && evidence.sourceSystemId === population.sourceSystemId
-    && evidence.periodStart === audit.periodStart
-    && evidence.periodEnd === audit.periodEnd
+    && coverageMatches(
+      evidence.coverage,
+      coverageStart(audit.coverage),
+      coverageEnd(audit.coverage)
+    )
     && requiredEvidence.every((field) => evidence[field] !== undefined && evidence[field] !== null && evidence[field] !== "");
   const reconciliationComplete = (population.reconciledByIds || []).length
     && population.reconciledOn
@@ -726,14 +733,14 @@ function populationResult(population, audit, byId) {
   const generatedOn = timestampDate(evidence?.generatedAt, evidence?.timezone);
   const sequenceComplete = Number.isInteger(evidence?.populationCount)
     && evidence.populationCount >= 0
-    && generatedOn > audit.periodEnd
+    && generatedOn > coverageEnd(audit.coverage)
     && population.reconciledOn >= generatedOn;
   if (!evidenceComplete || !reconciliationComplete || !sequenceComplete) {
     return { status: "action", message: "Finish the reconciliation and link a verified population export with its exact query, timezone, count, completeness check, and accuracy check." };
   }
   return {
     status: "complete",
-    message: `${evidence.populationCount} items reconciled from ${evidence.source || "the authoritative source"}${population.conclusion === "complete-with-exceptions" ? " with documented exceptions" : ""}.`
+    message: `${evidence.populationCount} items reconciled from ${evidence.sourceDescription || "the authoritative source"}${population.conclusion === "complete-with-exceptions" ? " with documented exceptions" : ""}.`
   };
 }
 
@@ -792,31 +799,30 @@ function applicableManagementDocuments(audit, readiness) {
 }
 
 function evidenceOverlaps(record, start, end) {
-  return (record.periodStart && record.periodEnd && record.periodStart <= end && record.periodEnd >= start)
+  return coverageOverlaps(record.coverage, start, end)
     || (record.collectedOn && record.collectedOn >= start && record.collectedOn <= end);
 }
 
 function evidenceRelevantToAuditDate(record, audit) {
   if (!audit) return false;
   if (audit.auditKind === "soc-2-type-1") {
-    const date = audit.typeOneAsOf;
+    const date = coverageStart(audit.coverage);
     return Boolean(date) && (
-      (record.periodStart && record.periodEnd && record.periodStart <= date && record.periodEnd >= date)
+      coverageContains(record.coverage, date)
       || record.collectedOn === date
     );
   }
-  return Boolean(audit.periodStart && audit.periodEnd)
-    && evidenceOverlaps(record, audit.periodStart, audit.periodEnd);
+  const start = coverageStart(audit.coverage);
+  const end = coverageEnd(audit.coverage);
+  return Boolean(start && end) && evidenceOverlaps(record, start, end);
 }
 
 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;
+  const start = coverageStart(audit.coverage);
+  const end = coverageEnd(audit.coverage);
   if (!start || !end) return false;
-  if (record.periodStart && record.periodEnd && record.periodStart <= end && record.periodEnd >= start) {
-    return true;
-  }
+  if (coverageOverlaps(record.coverage, start, end)) return true;
   const definition = model.resources[record.type];
   const fields = { ...model.commonFields, ...(definition?.fields || {}) };
   return Object.entries(fields).some(([name, field]) => {
@@ -872,9 +878,7 @@ function managementDocumentContentIssues(source, definition, audit) {
   ));
   if (missingHeadings.length) return [`Add the missing description sections: ${missingHeadings.join(", ")}.`];
   if (definition.dateBinding === "engagement" && audit) {
-    const dates = audit.auditKind === "soc-2-type-1"
-      ? [audit.typeOneAsOf]
-      : [audit.periodStart, audit.periodEnd];
+    const dates = [coverageStart(audit.coverage), coverageEnd(audit.coverage)];
     if (dates.some((date) => date && !source.includes(date))) {
       return ["Name the exact engagement date or period in the document."];
     }
@@ -923,16 +927,16 @@ function materializeManagementMarkdown(source, audit, records) {
     .map(displayValue))]
     .join(", ");
   const period = audit.auditKind === "soc-2-type-1"
-    ? audit.typeOneAsOf || "[as-of date]"
-    : audit.periodStart && audit.periodEnd
-      ? `${audit.periodStart} through ${audit.periodEnd}`
+    ? coverageStart(audit.coverage) || "[as-of date]"
+    : coverageStart(audit.coverage) && coverageEnd(audit.coverage)
+      ? coverageLabel(audit.coverage)
       : "[start date] through [end date]";
   return withoutDiscarded
     .replaceAll(`<!-- ${keep}:start -->`, "")
     .replaceAll(`<!-- ${keep}:end -->`, "")
-    .replaceAll("[as-of date]", audit.typeOneAsOf || "[as-of date]")
-    .replaceAll("[start date]", audit.periodStart || "[start date]")
-    .replaceAll("[end date]", audit.periodEnd || "[end date]")
+    .replaceAll("[as-of date]", coverageStart(audit.coverage) || "[as-of date]")
+    .replaceAll("[start date]", coverageStart(audit.coverage) || "[start date]")
+    .replaceAll("[end date]", coverageEnd(audit.coverage) || "[end date]")
     .replaceAll("[engagement date or period]", period)
     .replaceAll("[engagement scope]", audit.scope || "[engagement scope]")
     .replaceAll("[in-scope systems]", systems || "[in-scope systems]")
@@ -953,8 +957,7 @@ function auditSummary(audit) {
     title: audit.title,
     status: audit.status,
     kind: audit.auditKind,
-    periodStart: audit.periodStart || null,
-    periodEnd: audit.periodEnd || null
+    coverage: audit.coverage || null
   };
 }