filegrc 0.1.0 → 0.3.0

package/src/evidence-packet.js

@@ -11,6 +11,30 @@ import { markdownEntries } from "./resource-markdown.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
 import { validateWorkspace } from "./validate.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 prepareEvidencePacket(input, options = {}) {
   const validation = await validateWorkspace(input);
   if (!validation.ok) throw new Error(`The workspace has ${validation.counts.errors} validation ${validation.counts.errors === 1 ? "error" : "errors"}. Fix them before generating evidence.`);
@@ -66,7 +90,6 @@ export async function prepareEvidencePacket(input, options = {}) {
       ...(audit.controlIds || []),
       ...(audit.controlTestIds || []),
       ...(audit.evidenceIds || []),
-      ...(audit.findingIds || []),
       ...(audit.contactIds || []),
       ...(audit.complementaryControlIds || []),
       ...(audit.subserviceVendorIds || []),
@@ -81,6 +104,9 @@ export async function prepareEvidencePacket(input, options = {}) {
     for (const request of records.filter((record) => record.type === "audit-request" && record.auditId === audit.id)) {
       selectedIds.add(request.id);
     }
+    for (const record of records.filter((candidate) => ["finding", "action-item"].includes(candidate.type))) {
+      if (recordRelevantToAudit(record, audit, byId)) selectedIds.add(record.id);
+    }
   }
   for (const item of obligations) {
     selectedIds.add(item.obligationId);
@@ -132,9 +158,13 @@ export async function prepareEvidencePacket(input, options = {}) {
     const control = byId.get(controlId);
     addIds(selectedIds, control?.systemIds);
     addIds(selectedIds, control?.commitmentIds);
-    addIds(selectedIds, control?.complementaryControlIds);
     addIds(selectedIds, control?.riskIds);
   }
+  for (const complementaryControl of records.filter((record) => record.type === "complementary-control")) {
+    if ((complementaryControl.relatedControlIds || []).some((id) => controlIds.has(id))) {
+      selectedIds.add(complementaryControl.id);
+    }
+  }
   for (const systemId of audit?.systemIds || []) {
     const system = byId.get(systemId);
     addIds(selectedIds, system?.commitmentIds);
@@ -215,6 +245,10 @@ export async function prepareEvidencePacket(input, options = {}) {
     end,
     timezone: loaded.workspace.timezone
   });
+  const filegrcRecords = datedRecords.filter((record) => (
+    !NON_EVIDENCE_RECORD_TYPES.has(record.type)
+    && controlIdsForRecord(byId.get(record.id), byId).size
+  ));
   const populations = (typeOne ? [] : records)
     .filter((record) => record.type === "audit-population" && (!audit || record.auditId === audit.id))
     .map((record) => populationSummary(record, byId))
@@ -285,6 +319,7 @@ export async function prepareEvidencePacket(input, options = {}) {
     },
     summary: {
       datedRecords: datedRecords.length,
+      filegrcRecords: filegrcRecords.length,
       records: packetRecords.length,
       policies: policyIds.size,
       controls: controlIds.size,
@@ -300,6 +335,7 @@ export async function prepareEvidencePacket(input, options = {}) {
       warnings: warningCount
     },
     datedRecords: datedRecords.sort((a, b) => a.primaryDate.localeCompare(b.primaryDate) || byTitle(a, b)),
+    filegrcRecords: filegrcRecords.sort((a, b) => a.primaryDate.localeCompare(b.primaryDate) || byTitle(a, b)),
     policies: [...policyIds].map((id) => recordSummary(byId.get(id))).filter(Boolean).sort(byTitle),
     controls: [...controlIds].map((id) => recordSummary(byId.get(id))).filter(Boolean).sort(byTitle),
     obligations,
@@ -337,7 +373,6 @@ function recordRelevantToAudit(record, audit, byId, seen = new Set()) {
     ...(audit.controlIds || []),
     ...(audit.controlTestIds || []),
     ...(audit.evidenceIds || []),
-    ...(audit.findingIds || []),
     ...(audit.contactIds || []),
     ...(audit.complementaryControlIds || []),
     ...(audit.subserviceVendorIds || []),
@@ -373,6 +408,12 @@ function recordRelevantToAudit(record, audit, byId, seen = new Set()) {
 
 function expandEvidenceWorkflowContext(selectedIds, byId) {
   const queue = [...selectedIds];
+  const childrenBySource = new Map();
+  for (const record of byId.values()) {
+    if (!["finding", "action-item"].includes(record.type) || !record.sourceResourceId) continue;
+    if (!childrenBySource.has(record.sourceResourceId)) childrenBySource.set(record.sourceResourceId, []);
+    childrenBySource.get(record.sourceResourceId).push(record.id);
+  }
   const enqueue = (ids = []) => {
     for (const id of ids) {
       if (!id || selectedIds.has(id)) continue;
@@ -382,6 +423,7 @@ function expandEvidenceWorkflowContext(selectedIds, byId) {
   };
   for (let index = 0; index < queue.length; index += 1) {
     const record = byId.get(queue[index]);
+    enqueue(childrenBySource.get(record?.id));
     if (record?.type === "evidence") enqueue([...(record.sourceResourceIds || []), record.sourceSystemId]);
     if (record?.type === "audit-population") enqueue([record.sourceEvidenceId, ...(record.controlIds || [])]);
     if (record?.type === "control-test") enqueue([record.populationId, ...(record.sampleEvidenceIds || [])]);
@@ -393,7 +435,7 @@ function expandEvidenceWorkflowContext(selectedIds, byId) {
         ...(record.evidenceIds || [])
       ]);
     }
-    if (record?.type === "obligation-event") enqueue([...(record.obligationIds || []), ...(record.actionItemIds || [])]);
+    if (record?.type === "obligation-event") enqueue(record.obligationIds || []);
   }
 }
 
@@ -515,7 +557,7 @@ async function writeChecksums(output, files) {
 
 function controlMatrixCsv(packet) {
   return csv([
-    ["Control ID", "Code", "Control", "Control Statement", "Operating Activity", "Status", "Effective On", "Frequency", "Operation Mode", "System IDs", "Requirement IDs", "Policy IDs", "Risk IDs", "Operating Record IDs", "Evidence IDs", "Control Test IDs", "Test Outcomes", "Population IDs", "Population Counts", "Sample Sizes", "Exception Counts", "Population Evidence IDs", "Sample Evidence IDs"],
+    ["Control ID", "Code", "Control", "Control Statement", "Operating Activity", "Status", "Effective On", "Frequency", "Operation Mode", "System IDs", "Requirement IDs", "Policy IDs", "Risk IDs", "filegrc Evidence IDs", "External Evidence IDs", "Control Test IDs", "Test Outcomes", "Population IDs", "Population Counts", "Sample Sizes", "Exception Counts", "Population Evidence IDs", "Sample Evidence IDs"],
     ...packet.controlCoverage.map((control) => [
       control.id,
       control.code,
@@ -550,15 +592,15 @@ function packetHandlingMarkdown(packet) {
     "",
     `Evidence classifications: ${packet.handling.classifications.join(", ") || "none recorded"}`,
     `External references present: ${packet.handling.containsExternalReferences ? "yes" : "no"}`,
-    "Encrypted by FileGRC: no",
+    "Encrypted by filegrc: no",
     "",
     "Review every included record and attachment for secrets, unnecessary personal data, customer data, and material outside the audit scope before transfer.",
     "",
-    "Review `external-evidence-index.csv` before delivery. It identifies references that FileGRC did not copy. Reconcile those items to the auditor portal or other approved system so the engagement team can confirm it received the same evidence indexed here.",
+    "Review `external-evidence-index.csv` before delivery. It identifies references that filegrc did not copy. Reconcile those items to the auditor portal or other approved system so the engagement team can confirm it received the same evidence indexed here.",
     "",
     "Transfer this directory through the auditor's approved encrypted channel. Do not email an unencrypted packet. Give access only to the engagement team and retain or remove exported copies under the organization's evidence-retention rules.",
     "",
-    "After transfer, enter the packet directory and run `shasum -a 256 -c SHA256SUMS` or `sha256sum -c SHA256SUMS`. FileGRC does not sign or encrypt the packet because those operations require organization-controlled keys and transfer-system choices.",
+    "After transfer, enter the packet directory and run `shasum -a 256 -c SHA256SUMS` or `sha256sum -c SHA256SUMS`. filegrc does not sign or encrypt the packet because those operations require organization-controlled keys and transfer-system choices.",
     ""
   ].join("\n");
 }
@@ -810,7 +852,7 @@ function buildControlCoverage({ audit, byId, controlIds, evidenceIds, model, rec
         || (!record.auditId && record.asOfDate >= start && record.asOfDate <= end)
       ));
     const operatingRecords = records.filter((record) => (
-      record.type !== "control"
+      !NON_EVIDENCE_RECORD_TYPES.has(record.type)
       && controlIdsForRecord(record, byId).has(controlId)
       && packetRecord(record, model, start, end, timezone)
     ));
@@ -859,6 +901,7 @@ function controlIdsForRecord(record, byId, seen = new Set()) {
   seen.add(record.id);
   if (record.type === "control") ids.add(record.id);
   addIds(ids, record.controlIds);
+  if (record.type === "complementary-control") addIds(ids, record.relatedControlIds);
   if (record.controlId) ids.add(record.controlId);
   for (const sourceId of record.sourceResourceIds || []) addIds(ids, controlIdsForRecord(byId.get(sourceId), byId, seen));
   if (record.sourceResourceId) addIds(ids, controlIdsForRecord(byId.get(record.sourceResourceId), byId, seen));
@@ -926,8 +969,10 @@ function packetGaps({
         }
       }
     }
-    if (!coverage.evidenceIds.length) {
-      gaps.push(gap("error", "control-missing-evidence", `${coverage.code || coverage.title} has no linked evidence in the packet.`, coverage.id));
+    if (controlNeedsExternalEvidence(control, model) && !coverage.evidenceIds.length) {
+      gaps.push(gap("error", "control-missing-external-evidence", `${coverage.code || coverage.title} relies on an external system but has no linked External Evidence in the packet.`, coverage.id));
+    } else if (!controlNeedsExternalEvidence(control, model) && !coverage.operatingRecordIds.length) {
+      gaps.push(gap("error", "control-missing-filegrc-evidence", `${coverage.code || coverage.title} has no dated filegrc operating record in the packet.`, coverage.id));
     }
     if (audit?.auditKind !== "soc-2-type-1" && coverage.status === "implemented" && !coverage.operatingRecordIds.length && coverage.operationMode !== "automated") {
       gaps.push(gap("warning", "control-missing-operating-record", `${coverage.code || coverage.title} has no dated operating record in the packet period.`, coverage.id));
@@ -953,7 +998,8 @@ function packetGaps({
       if (Number.isInteger(testRecord?.exceptionCount) && testRecord.exceptionCount < 0) {
         gaps.push(gap("error", "control-test-exception-count-invalid", `${coverage.code || coverage.title} records a negative exception count.`, test.id));
       }
-      if ((testRecord?.exceptionCount > 0 || ["failed", "passed-with-exceptions"].includes(test.outcome)) && !(testRecord?.findingIds || []).length) {
+      const testFindings = records.filter((record) => record.type === "finding" && record.sourceResourceId === test.id);
+      if ((testRecord?.exceptionCount > 0 || ["failed", "passed-with-exceptions"].includes(test.outcome)) && !testFindings.length) {
         gaps.push(gap("error", "control-test-finding-missing", `${coverage.code || coverage.title} records exceptions or failure without a linked finding.`, test.id));
       }
       const samplingTest = Number.isInteger(test.sampleSize) && test.sampleSize > 0;
@@ -1167,6 +1213,13 @@ function packetGaps({
   return deduplicateGaps(gaps);
 }
 
+function controlNeedsExternalEvidence(control, model) {
+  const families = (model.evidenceSourceFamilies || []).filter((family) => (
+    (family.controlCodes || []).includes(control?.code)
+  ));
+  return !families.length || families.some((family) => family.collectionTestRequired !== false);
+}
+
 function auditGaps(gaps, audit, byId, records, start, end) {
   if (!["soc-2-type-1", "soc-2-type-2"].includes(audit.auditKind)) {
     gaps.push(gap("error", "not-soc2-examination", `${audit.title} is ${audit.auditKind}; a delivery packet requires a SOC 2 Type 1 or Type 2 engagement.`, audit.id));
@@ -1470,7 +1523,7 @@ function recordSummary(record) {
 
 function packetMarkdown(packet) {
   const readiness = packet.readiness.status === "delivery-ready"
-    ? "FileGRC management checks passed. The engagement team still determines whether the evidence is sufficient and appropriate."
+    ? "filegrc management checks passed. The engagement team still determines whether the evidence is sufficient and appropriate."
     : `${packet.readiness.errors} errors and ${packet.readiness.warnings} warnings require review. This is a draft packet.`;
   const periodLabel = packet.period.basis === "as-of"
     ? `as of ${packet.period.start}`
@@ -1490,10 +1543,10 @@ function packetMarkdown(packet) {
     "",
     "## Coverage",
     "",
-    `- ${packet.summary.datedRecords} dated records`,
+    `- ${packet.summary.filegrcRecords} filegrc Evidence records`,
     `- ${packet.summary.obligationOccurrences} recurring obligation occurrences`,
     `- ${packet.summary.eventRuns} event runs`,
-    `- ${packet.summary.evidence} evidence records`,
+    `- ${packet.summary.evidence} External Evidence records`,
     `- ${packet.summary.populations} reconciled or planned populations`,
     `- ${packet.summary.policies} policies`,
     `- ${packet.summary.controls} controls`,
@@ -1501,7 +1554,7 @@ function packetMarkdown(packet) {
     `- ${packet.summary.systems} in-scope systems`,
     `- ${packet.summary.sourceSystems} cataloged source systems`,
     "",
-    "Open `index.html` for the auditor-oriented index. `control-matrix.csv` cross-references criteria, controls, operating records, tests, and evidence. `source-system-index.csv` identifies the systems of record used to produce evidence. `external-evidence-index.csv` lists material that must be delivered or accessed outside this packet. For Type 2, `population-index.csv` records management's population reconciliation and fixed source exports. Raw source records, governed Markdown, fixed attachments, and committed historical versions are included in their respective directories.",
+    "Open `index.html` for the auditor-oriented index. `control-matrix.csv` cross-references criteria, controls, filegrc Evidence, External Evidence, and tests. `source-system-index.csv` identifies the systems of record used to produce External Evidence. `external-evidence-index.csv` lists material that must be delivered or accessed outside this packet. For Type 2, `population-index.csv` records management's population reconciliation and fixed source exports. filegrc records, governed Markdown, fixed attachments, and committed historical versions are included in their respective directories.",
     "",
     "After transfer, enter the packet directory and run `shasum -a 256 -c SHA256SUMS` or `sha256sum -c SHA256SUMS`. The checksum file covers every other packet file.",
     ""
@@ -1516,7 +1569,7 @@ function packetHtml(packet) {
     : "<p>None.</p>";
   const gaps = packet.gaps.length
     ? `<ul>${packet.gaps.map((item) => `<li class="${item.severity}"><strong>${escapeHtml(item.severity)}</strong> ${escapeHtml(item.message)}</li>`).join("")}</ul>`
-    : "<p>FileGRC management checks passed. The engagement team still evaluates sufficiency and appropriateness.</p>";
+    : "<p>filegrc management checks passed. The engagement team still evaluates sufficiency and appropriateness.</p>";
   const engagementDate = packet.period.basis === "as-of"
     ? `As of ${escapeHtml(packet.period.start)}`
     : `${escapeHtml(packet.period.start)} through ${escapeHtml(packet.period.end)}`;
@@ -1527,8 +1580,8 @@ function packetHtml(packet) {
     ? `<table><thead><tr><th>Obligation</th><th>Allowed window</th><th>Status</th></tr></thead><tbody>${packet.obligations.map((item) => `<tr><td>${escapeHtml(item.title)}</td><td>${item.dueWindowStart} through ${item.dueWindowEnd}<br><small>Overdue ${item.overdueOn}</small></td><td>${escapeHtml(item.status)}</td></tr>`).join("")}</tbody></table>`
     : "<p>No recurring occurrences intersect this period.</p>";
   const evidence = packet.evidence.length
-    ? `<table><thead><tr><th>Evidence</th><th>Source and period</th><th>Controls</th><th>Files</th></tr></thead><tbody>${packet.evidence.map((item) => `<tr><td><a href="records/evidence/${encodeURIComponent(item.id)}.json">${escapeHtml(item.title)}</a><small>${escapeHtml(item.status)} · ${escapeHtml(item.evidenceKind)}</small></td><td>${escapeHtml(item.source)}<small>${escapeHtml(item.periodStart || item.collectedOn)}${item.periodEnd ? ` through ${escapeHtml(item.periodEnd)}` : ""}</small></td><td>${item.controlIds.map(escapeHtml).join("<br>") || "None"}</td><td>${item.filePaths.map((path) => `<a class="attachment" href="attachments/${path.split("/").map(encodeURIComponent).join("/")}">${escapeHtml(basename(path))}</a>`).join("") || "No fixed attachment"}</td></tr>`).join("")}</tbody></table>`
-    : "<p>No evidence records were selected.</p>";
+    ? `<table><thead><tr><th>External Evidence</th><th>Source and period</th><th>Controls</th><th>Files</th></tr></thead><tbody>${packet.evidence.map((item) => `<tr><td><a href="records/evidence/${encodeURIComponent(item.id)}.json">${escapeHtml(item.title)}</a><small>${escapeHtml(item.status)} · ${escapeHtml(item.evidenceKind)}</small></td><td>${escapeHtml(item.source)}<small>${escapeHtml(item.periodStart || item.collectedOn)}${item.periodEnd ? ` through ${escapeHtml(item.periodEnd)}` : ""}</small></td><td>${item.controlIds.map(escapeHtml).join("<br>") || "None"}</td><td>${item.filePaths.map((path) => `<a class="attachment" href="attachments/${path.split("/").map(encodeURIComponent).join("/")}">${escapeHtml(basename(path))}</a>`).join("") || "No fixed attachment"}</td></tr>`).join("")}</tbody></table>`
+    : "<p>No External Evidence records were selected.</p>";
   const sourceSystems = packet.sourceSystems.length
     ? `<p><a href="source-system-index.csv">Download source system index CSV</a></p><table><thead><tr><th>System of record</th><th>Evidence roles</th><th>Audit relationship</th><th>Evidence</th></tr></thead><tbody>${packet.sourceSystems.map((item) => `<tr><td><a href="records/system/${encodeURIComponent(item.id)}.json">${escapeHtml(item.title)}</a><small>${escapeHtml(item.status)}</small></td><td>${item.evidenceSourceKinds.map(escapeHtml).join("<br>") || "No evidence role recorded"}</td><td>${item.inAuditScope ? "In-scope system" : "Evidence source"}</td><td>${item.evidenceIds.length}</td></tr>`).join("")}</tbody></table><p><a href="external-evidence-index.csv">Download external evidence delivery index CSV</a></p>`
     : "<p>No source systems were cataloged.</p>";
@@ -1539,25 +1592,25 @@ function packetHtml(packet) {
     ? packet.eventRuns.map((run) => `<article><h3><a href="records/obligation-event/${encodeURIComponent(run.id)}.json">${escapeHtml(run.title)}</a></h3><p>${escapeHtml(run.occurredAt || run.occurredOn)} · ${escapeHtml(run.status)} · ${run.completeCount} of ${run.actions.length} complete</p><table><thead><tr><th>Required action</th><th>Policy cutoff</th><th>Status</th></tr></thead><tbody>${run.actions.map((action) => `<tr><td><a href="records/action-item/${encodeURIComponent(action.actionItemId)}.json">${escapeHtml(action.title)}</a></td><td>${escapeHtml(action.dueWindowEndAt || action.dueWindowEnd)}</td><td>${escapeHtml(action.status)}</td></tr>`).join("")}</tbody></table></article>`).join("")
     : "<p>No event workflows intersect this period.</p>";
   const recordsById = new Map(packet.records.map((record) => [record.id, record]));
-  const datedRecords = packet.datedRecords.length
-    ? `<table><thead><tr><th>Date</th><th>Operating record</th><th>Latest committed change</th></tr></thead><tbody>${packet.datedRecords.map((item) => {
+  const filegrcRecords = packet.filegrcRecords.length
+    ? `<table><thead><tr><th>Date</th><th>filegrc record</th><th>Latest committed change</th></tr></thead><tbody>${packet.filegrcRecords.map((item) => {
       const history = recordsById.get(item.id)?.history?.[0];
       const source = history
         ? `${history.timestamp} · ${history.author} · ${history.subject}`
         : "No committed file history";
       return `<tr><td>${escapeHtml(item.primaryDate)}</td><td><a href="records/${encodeURIComponent(item.type)}/${encodeURIComponent(item.id)}.json">${escapeHtml(item.title)}</a><br><small>${escapeHtml(item.type)}</small></td><td>${escapeHtml(source)}</td></tr>`;
     }).join("")}</tbody></table>`
-    : "<p>No dated operating records matched this period.</p>";
+    : "<p>No filegrc Evidence records matched this period.</p>";
   const controlCoverage = packet.controlCoverage.length
-    ? `<p><a href="control-matrix.csv">Download control matrix CSV</a></p><table><thead><tr><th>Control</th><th>Status and scope</th><th>Criteria</th><th>Operating records</th><th>Evidence</th><th>Tests</th></tr></thead><tbody>${packet.controlCoverage.map((control) => `<tr><td><a href="records/control/${encodeURIComponent(control.id)}.json">${escapeHtml(control.code || control.id)}</a><small>${escapeHtml(control.title)}</small></td><td>${escapeHtml(control.status)}<small>${control.systemIds.map(escapeHtml).join(", ") || "No system scope"}</small></td><td>${control.requirementIds.map(escapeHtml).join("<br>") || "None"}</td><td>${control.operatingRecordIds.length}</td><td>${control.evidenceIds.length}</td><td>${control.tests.length}</td></tr>`).join("")}</tbody></table>`
+    ? `<p><a href="control-matrix.csv">Download control matrix CSV</a></p><table><thead><tr><th>Control</th><th>Status and scope</th><th>Criteria</th><th>filegrc Evidence</th><th>External Evidence</th><th>Tests</th></tr></thead><tbody>${packet.controlCoverage.map((control) => `<tr><td><a href="records/control/${encodeURIComponent(control.id)}.json">${escapeHtml(control.code || control.id)}</a><small>${escapeHtml(control.title)}</small></td><td>${escapeHtml(control.status)}<small>${control.systemIds.map(escapeHtml).join(", ") || "No system scope"}</small></td><td>${control.requirementIds.map(escapeHtml).join("<br>") || "None"}</td><td>${control.operatingRecordIds.length}</td><td>${control.evidenceIds.length}</td><td>${control.tests.length}</td></tr>`).join("")}</tbody></table>`
     : "<p>No controls were selected.</p>";
-  const readinessLabel = packet.readiness.status === "delivery-ready" ? "FileGRC management checks passed" : "Draft, do not deliver";
+  const readinessLabel = packet.readiness.status === "delivery-ready" ? "filegrc management checks passed" : "Draft, do not deliver";
   const packetDate = packet.period.basis === "as-of"
     ? `As of ${escapeHtml(packet.period.start)}`
     : `${escapeHtml(packet.period.start)} through ${escapeHtml(packet.period.end)}`;
   return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Evidence packet</title><style>
 body{font:14px/1.5 system-ui,sans-serif;color:#161825;max-width:1120px;margin:auto;padding:40px;background:#f7f8fc}header,section{background:#fff;border:1px solid #dfe3ef;border-radius:10px;padding:24px;margin:14px 0}h1,h2{margin-top:0}h1{font-size:26px}h2{font-size:17px}ul{padding-left:20px}li{margin:8px 0}small{display:block;color:#656c7e}.attachment{margin-right:10px;font-size:12px}.error{color:#8a2f28}.warning{color:#76500d}.readiness{display:inline-block;padding:5px 9px;border-radius:999px;background:#f7e4e2;color:#7a2520;font-weight:700}.readiness.ready{background:#e2f1e8;color:#245d3b}table{width:100%;border-collapse:collapse}th,td{padding:9px;border:1px solid #dfe3ef;text-align:left;vertical-align:top}code{overflow-wrap:anywhere}dl{display:grid;grid-template-columns:max-content 1fr;gap:8px 16px}dt{font-weight:700}dd{margin:0}
-</style></head><body><header><p>SOC 2 evidence packet</p><span class="readiness ${packet.readiness.status === "delivery-ready" ? "ready" : ""}">${escapeHtml(readinessLabel)}</span><h1>${packetDate}</h1><p>${escapeHtml(packet.workspace.organizationName)} · revision <code>${escapeHtml(packet.revision.commit || "uncommitted")}</code></p></header>${section("Engagement scope", engagement)}${section("Review status", gaps)}${section("Control coverage", controlCoverage)}${section("Systems of record", sourceSystems)}${packet.period.basis === "period" ? section("Management population reconciliation", populations) : ""}${packet.period.basis === "period" ? section("Recurring obligation coverage", obligations) : ""}${packet.period.basis === "period" ? section("Event workflow coverage", eventRuns) : ""}${section("Policies", links(packet.policies))}${section("Dated operating records", datedRecords)}${section("Evidence", evidence)}${section("Integrity and history", "<p>Verify all transferred files with <code>SHA256SUMS</code>. Committed prior versions are under <code>history/</code> with an index that records their source paths and Git metadata.</p>")}</body></html>`;
+</style></head><body><header><p>SOC 2 evidence packet</p><span class="readiness ${packet.readiness.status === "delivery-ready" ? "ready" : ""}">${escapeHtml(readinessLabel)}</span><h1>${packetDate}</h1><p>${escapeHtml(packet.workspace.organizationName)} · revision <code>${escapeHtml(packet.revision.commit || "uncommitted")}</code></p></header>${section("Engagement scope", engagement)}${section("Review status", gaps)}${section("Control coverage", controlCoverage)}${section("Systems of record", sourceSystems)}${packet.period.basis === "period" ? section("Management population reconciliation", populations) : ""}${packet.period.basis === "period" ? section("Recurring obligation coverage", obligations) : ""}${packet.period.basis === "period" ? section("Event workflow coverage", eventRuns) : ""}${section("Policies", links(packet.policies))}${section("filegrc Evidence", filegrcRecords)}${section("External Evidence", evidence)}${section("Integrity and history", "<p>Verify all transferred files with <code>SHA256SUMS</code>. Committed prior versions are under <code>history/</code> with an index that records their source paths and Git metadata.</p>")}</body></html>`;
 }
 
 async function writePacketFile(output, relativePath, source, files) {

package/src/evidence-tests.js

@@ -0,0 +1,69 @@
+import { createResources } from "./files.js";
+import { createResourceId } from "./id.js";
+import { selectedControlFamilies } from "./program-readiness.js";
+import { loadWorkspace } from "./workspace.js";
+
+const TEST_EVIDENCE_KINDS = new Set(["test-export", "test-capture"]);
+
+export function planEvidenceTestDrafts(loaded) {
+  const workspace = loaded.workspace;
+  const selectedIds = new Set(workspace.controlIds || []);
+  const controls = loaded.resources.filter((record) => (
+    record.type === "control"
+    && (!selectedIds.size || selectedIds.has(record.id))
+    && !["not-applicable", "retired"].includes(record.status)
+  ));
+  const families = selectedControlFamilies(controls, loaded.model)
+    .filter((family) => family.collectionTestRequired !== false);
+  const evidence = loaded.resources.filter((record) => (
+    record.type === "evidence" && TEST_EVIDENCE_KINDS.has(record.evidenceKind)
+  ));
+  return families.map((family) => {
+    const familyControlIds = new Set(family.controls.map((control) => control.id));
+    const existing = evidence.find((record) => record.collectionTestFamilyId === family.id)
+      || evidence.find((record) => (
+        (record.controlIds || []).some((id) => familyControlIds.has(id))
+      ));
+    return {
+      familyId: family.id,
+      title: family.title,
+      testEvidenceKind: family.testEvidenceKind,
+      testPrompt: family.testPrompt,
+      controlIds: [...familyControlIds],
+      existing
+    };
+  });
+}
+
+export async function ensureEvidenceTestDrafts(input = process.cwd()) {
+  const loaded = await loadWorkspace(input);
+  const plan = planEvidenceTestDrafts(loaded);
+  const created = [];
+  const usedIds = loaded.resources.map((record) => record.id);
+  for (const item of plan.filter(({ existing }) => !existing)) {
+    const id = createResourceId(
+      "evidence",
+      `${item.title} Collection Test`,
+      usedIds
+    );
+    usedIds.push(id);
+    const record = {
+      schemaVersion: 1,
+      id,
+      type: "evidence",
+      title: `${item.title} Evidence Collection Test`,
+      status: "draft",
+      evidenceKind: item.testEvidenceKind,
+      collectionTestFamilyId: item.familyId,
+      collectionTestPrompt: item.testPrompt,
+      controlIds: item.controlIds
+    };
+    created.push(record);
+  }
+  if (created.length) await createResources(loaded.root, created);
+  return {
+    created,
+    existing: plan.filter(({ existing }) => existing).map(({ existing }) => existing),
+    total: plan.length
+  };
+}

package/src/git.js

@@ -131,6 +131,7 @@ async function commitWorkspaceUnlocked(root, message) {
   }
   const before = getGitSummary(root);
   if (!before.available) throw new Error("Git history is unavailable for this workspace.");
+  if (!before.branch) throw new Error("Check out a branch before creating a browser commit.");
   if (before.clean) throw new Error("The workspace has no changes to commit.");
   if (!tryGit(root, ["config", "user.name"]) || !tryGit(root, ["config", "user.email"])) {
     throw new Error("Configure git user.name and user.email before committing.");
@@ -226,7 +227,7 @@ async function pushWorkspaceUnlocked(root) {
 
 function syncReadySummary(root, action) {
   const summary = getGitSummary(root);
-  if (!summary.available) throw new Error(`Git history is unavailable for this workspace, so FileGRC cannot ${action}.`);
+  if (!summary.available) throw new Error(`Git history is unavailable for this workspace, so filegrc cannot ${action}.`);
   if (!summary.branch) throw new Error(`Check out a branch before trying to ${action}.`);
   if (!summary.clean) throw new Error(`Commit or discard workspace changes before trying to ${action}.`);
   return summary;

package/src/index.js

@@ -3,6 +3,7 @@ export { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldRes
 export { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 export { buildWorkspace } from "./build.js";
 export { generateEvidencePacket, prepareEvidencePacket, writeEvidencePacket } from "./evidence-packet.js";
+export { ensureEvidenceTestDrafts, planEvidenceTestDrafts } from "./evidence-tests.js";
 export {
   addEvidenceAttachment,
   createResource,
@@ -32,6 +33,15 @@ export {
   createObligationEvent,
   planObligations
 } from "./obligations.js";
+export { assessProgramReadiness } from "./program-readiness.js";
+export {
+  buildAgentProgramPath,
+  policyEventName,
+  POLICY_EVENT_NAMES,
+  PROGRAM_PATH,
+  RESOURCE_INSTRUCTIONS,
+  resourceProgramContext
+} from "./program-path.js";
 export {
   addCalendarDays,
   calendarDayDifference,
@@ -40,7 +50,8 @@ export {
   nextCalendarOccurrence
 } from "./recurrence.js";
 export { searchResources, searchableValues } from "./search.js";
-export { createFileGRCServer, serveWorkspace } from "./server.js";
+export { createFilegrcServer, serveWorkspace } from "./server.js";
+export { normalizeSetupPayload, setupWorkspace } from "./setup.js";
 export { createAppState } from "./state.js";
 export { currentCalendarDate, formatCalendarDate, formatLocalDateTime } from "./time.js";
 export { validateWorkspace } from "./validate.js";

package/src/model-docs.js

@@ -1,4 +1,7 @@
+import { buildAgentProgramPath, RESOURCE_INSTRUCTIONS } from "./program-path.js";
+
 export function generateModelDocumentation(model) {
+  const programPath = buildAgentProgramPath(model);
   const lines = [
     "# GRC Data Model",
     "",
@@ -10,6 +13,28 @@ export function generateModelDocumentation(model) {
     "",
     "Each structured resource is one UTF-8 JSON file. Long-form work is an implicit Markdown companion beside that JSON file. Git supplies file authors, timestamps, diffs, commit messages, and revisions, so records do not duplicate those fields or file paths.",
     "",
+    "## Program path",
+    "",
+    "The renderer, CLI, generated agent instructions, and this reference use the same six-step lifecycle:",
+    "",
+    ...programPath.flatMap((stage) => [
+      `### Step ${stage.number}. ${stage.title}`,
+      "",
+      stage.summary,
+      "",
+      ...stage.pages.map((page) => `- **${page.title}** (\`${page.type || `utility:${page.utility}`}\`): ${page.instructions}`),
+      "",
+      ...(stage.operatingRecords?.length ? [
+        "Operating record guides:",
+        "",
+        ...stage.operatingRecords.map((page) => `- **${page.title}** (\`${page.type}\`): ${page.instructions}`),
+        ""
+      ] : []),
+      "Headless commands:",
+      "",
+      ...stage.commands.map((command) => `- \`${command}\``),
+      ""
+    ]),
     "## Common fields",
     "",
     "| Field | Type | Required | Meaning |",
@@ -26,9 +51,9 @@ export function generateModelDocumentation(model) {
     "",
     `Record Markdown is shown by default for: ${model.recordContent.defaultResourceTypes.map((type) => `\`${type}\``).join(", ")}. Other resources without dedicated Markdown can add it when structured fields are not enough.`,
     "",
-    "## Audit preparation defaults",
+    "## Program and audit readiness defaults",
     "",
-    "The engine and renderer use these model-owned defaults to prepare Type 1 and Type 2 engagements. Preparation creates engagement-specific management documents from the local starter templates. Management still confirms scope, approves documents, catalogs authoritative source systems, reconciles Type 2 populations, and supplies source evidence.",
+    "Program Readiness checks management scope, policy adoption, control implementation, authoritative source configuration, and verified test captures without requiring an audit record. Audit Readiness starts after a CPA firm is engaged and uses the defaults below to prepare Type 1 and Type 2 fieldwork.",
     "",
     "Management documents:",
     "",
@@ -40,7 +65,11 @@ export function generateModelDocumentation(model) {
     "",
     "Authoritative systems of record:",
     "",
-    ...model.auditReadiness.externalEvidence.map((item) => `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} ${item.timing}`),
+    ...model.evidenceSourceFamilies.map((item) => (
+      item.collectionTestRequired === false
+        ? `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} filegrc operating records: ${item.operationRecordTypes.map((type) => `\`${type}\``).join(", ")}. No separate collection test is required. ${item.timing}`
+        : `- **${item.title}** (${item.sourceKinds.map((kind) => `\`${kind}\``).join(", ")}): ${item.description} Test external collection: ${item.testPrompt} ${item.timing}`
+    )),
     "",
     "## Resource groups",
     ""
@@ -52,6 +81,7 @@ export function generateModelDocumentation(model) {
     lines.push(`### ${group.title}`, "");
     for (const [type, resource] of resources) {
       lines.push(`#### \`${type}\``, "", resource.description, "");
+      lines.push(`Instructions: ${RESOURCE_INSTRUCTIONS[type] || resource.description}`, "");
       lines.push(`Policy basis: ${resource.guidance.policyBasis}`, "");
       lines.push(`Timing: ${resource.guidance.cadence}`, "");
       if (resource.guidance.sourceResourceIds?.length) {
@@ -68,7 +98,12 @@ export function generateModelDocumentation(model) {
         lines.push("Markdown companions:", "");
         for (const [name, markdown] of Object.entries(resource.markdown)) {
           const suffix = markdown.primary ? ".md" : `-${name}.md`;
-          lines.push(`- **${markdown.label}**: \`${suffix}\` beside the JSON record${markdown.required ? " (required)" : " (optional)"}.`);
+          const requirement = markdown.required
+            ? "required"
+            : markdown.requiredWhen
+              ? `required when ${conditionText(markdown.requiredWhen)}`
+              : "optional";
+          lines.push(`- **${markdown.label}**: \`${suffix}\` beside the JSON record (${requirement}).`);
         }
         lines.push("");
       }
@@ -78,8 +113,10 @@ export function generateModelDocumentation(model) {
         const requiredLabel = required.has(name) || field.required ? "Yes" : field.requiredWhen ? "Conditional" : "No";
         lines.push(`| \`${name}\` | ${fieldType(field)} | ${requiredLabel} | ${escapeCell(fieldNotes(field))} |`);
       }
-      for (const choices of resource.oneOf ?? []) {
-        lines.push("", `At least one of ${choices.map(choiceLabel).join(", ")} is required.`);
+      for (const group of resource.oneOf ?? []) {
+        const choices = Array.isArray(group) ? group : group.fields || [];
+        const condition = Array.isArray(group) ? "" : ` when ${conditionText(group.when)}`;
+        lines.push("", `At least one of ${choices.map(choiceLabel).join(", ")} is required${condition}.`);
       }
       lines.push("");
     }
@@ -87,6 +124,14 @@ export function generateModelDocumentation(model) {
   return lines.join("\n");
 }
 
+function conditionText(condition) {
+  return Object.entries(condition).map(([name, value]) => (
+    Array.isArray(value)
+      ? `\`${name}\` is one of ${value.map((item) => `\`${item}\``).join(", ")}`
+      : `\`${name}\` is \`${value}\``
+  )).join(" and ");
+}
+
 function recordContentMode(model, type, resource) {
   if (!model.recordContent?.slot || resource.markdown) return null;
   return model.recordContent.defaultResourceTypes.includes(type) ? "default" : "optional";