filegrc 0.3.4 → 0.4.0

package/src/cli.js

@@ -6,7 +6,6 @@ import { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldRes
 import { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 import { buildWorkspace } from "./build.js";
 import { generateEvidencePacket, prepareEvidencePacket } from "./evidence-packet.js";
-import { ensureEvidenceTestDrafts, planEvidenceTestDrafts } from "./evidence-tests.js";
 import {
   addEvidenceAttachment,
   createResource,
@@ -15,6 +14,8 @@ import {
   updateResource
 } from "./files.js";
 import { generateModelDocumentation } from "./model-docs.js";
+import { migrateModel, planModelMigration } from "./model-migration.js";
+import { normalizeResourceMutation } from "./mutation.js";
 import {
   completeObligationAction,
   completeObligationEvent,
@@ -23,9 +24,10 @@ import {
   planObligations
 } from "./obligations.js";
 import { relativeToWorkspace, resolveDataPath } from "./paths.js";
-import { buildAgentProgramPath, policyEventName } from "./program-path.js";
-import { assessProgramReadiness } from "./program-readiness.js";
+import { buildAgentProgramPath } from "./program-path.js";
+import { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
+import { effectiveResourceStatus } from "./resource-status.js";
 import { searchResources } from "./search.js";
 import { serveWorkspace } from "./server.js";
 import { planWorkspaceSetup, setupWorkspace, summarizeSetupResult } from "./setup.js";
@@ -89,7 +91,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       ...(flags.boundary !== undefined ? { boundary: flags.boundary } : {}),
       ...(flags.owner !== undefined ? { ownerId: flags.owner } : {}),
       ...(flags.criticality !== undefined ? { criticality: flags.criticality } : {}),
-      ...(flags.classification !== undefined ? { dataClassification: flags.classification } : {}),
+      ...(flags.classification !== undefined ? { classificationId: flags.classification } : {}),
       ...(flags["internet-exposed"] !== undefined ? { internetExposed: flags["internet-exposed"] } : {}),
       ...(flags["program-goal"] !== undefined ? { programGoal: flags["program-goal"] } : {}),
       ...(flags.draft ? { draft: true } : {})
@@ -101,7 +103,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (flags.json) console.log(JSON.stringify(output, null, 2));
     else if (flags.preview) {
       console.log(`Setup preview: ${result.changes.system} system ${result.system.id}; update workspace target to ${result.target.assuranceGoal}.`);
-      console.log("No controls will be linked and no evidence drafts will be created.");
+      console.log("No controls will be linked and no evidence records will be created.");
     }
     else {
       console.log(`${result.draft ? "Saved draft scope" : "Completed initial setup"} for ${result.system.title}.`);
@@ -144,6 +146,35 @@ export async function runCli(argv = process.argv.slice(2)) {
     else console.log(source);
     return;
   }
+  if (command === "migrate") {
+    const targetModel = String(flags["to-model"] || "");
+    if (targetModel !== "2") throw new Error("Pass --to-model 2.");
+    const options = {
+      jobTitle: flags["job-title"],
+      startsOn: flags["starts-on"]
+    };
+    const plan = await planModelMigration(root, options);
+    if (!flags.preview && plan.sourceModelVersion !== plan.targetModelVersion && !flags.yes) {
+      throw new Error("Review migrate --to-model 2 --preview --json, then pass --yes to apply the migration.");
+    }
+    const result = flags.preview
+      ? plan
+      : plan.sourceModelVersion !== plan.targetModelVersion
+        ? await migrateModel(root, options)
+        : { ...plan, applied: false };
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else if (result.sourceModelVersion === result.targetModelVersion) {
+      console.log(`Workspace already uses model v${result.targetModelVersion}.`);
+    } else if (flags.preview) {
+      console.log(`Model migration preview: create ${result.summary.create}; update ${result.summary.update}.`);
+      console.log(result.ready
+        ? "Ready to apply. Rerun with --yes."
+        : `Needs review: ${result.missing.length} missing values, ${result.conflicts.length} conflicts, ${result.manualActions.length} manual actions.`);
+    } else {
+      console.log(`Migrated workspace from model v${result.sourceModelVersion} to v${result.targetModelVersion}.`);
+    }
+    return result;
+  }
   if (command === "describe") {
     const loaded = await loadWorkspace(root);
     const type = positionals[0];
@@ -195,11 +226,18 @@ export async function runCli(argv = process.argv.slice(2)) {
     const loaded = await loadWorkspace(root);
     const type = positionals[0];
     if (type && !loaded.model.resources[type]) throw new Error(`Unknown resource type "${type}".`);
+    const asOf = currentCalendarDate(loaded.workspace.timezone);
     const records = loaded.resources
       .filter((record) => !type || record.type === type)
-      .sort((left, right) => `${left.type}:${left.title}:${left.id}`.localeCompare(`${right.type}:${right.title}:${right.id}`));
+      .sort((left, right) => `${left.type}:${left.title}:${left.id}`.localeCompare(`${right.type}:${right.title}:${right.id}`))
+      .map((record) => {
+        const effectiveStatus = effectiveResourceStatus(record, asOf);
+        return effectiveStatus && effectiveStatus !== record.status
+          ? { ...record, effectiveStatus }
+          : record;
+      });
     if (flags.json) console.log(JSON.stringify(records, null, 2));
-    else for (const record of records) console.log(`${record.id}\t${record.type}\t${record.status ?? ""}\t${record.title}`);
+    else for (const record of records) console.log(`${record.id}\t${record.type}\t${record.effectiveStatus ?? record.status ?? ""}\t${record.title}`);
     return records;
   }
   if (command === "search") {
@@ -217,7 +255,8 @@ export async function runCli(argv = process.argv.slice(2)) {
       from: flags.from,
       through: flags.through,
       now: flags.now,
-      includeComplete: Boolean(flags.complete)
+      includeComplete: Boolean(flags.complete),
+      model: loaded.model
     });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else {
@@ -236,7 +275,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       if (result.triggers.length) {
         console.log("\nPolicy Events:");
         for (const trigger of result.triggers) {
-          console.log(`${trigger.programStatus.toUpperCase()}\t${policyEventName(trigger.eventType)} (${trigger.eventType})\t${trigger.steps.length} Work Queue ${trigger.steps.length === 1 ? "task" : "tasks"}`);
+          console.log(`${trigger.programStatus.toUpperCase()}\t${trigger.title} (${trigger.eventType})\t${trigger.steps.length} Work Queue ${trigger.steps.length === 1 ? "task" : "tasks"}`);
           for (const step of trigger.steps) {
             const owners = step.ownerIds.length ? step.ownerIds.join(",") : "unassigned";
             const proof = step.completionResourceTypes.length ? step.completionResourceTypes.join("|") : "not specified";
@@ -262,7 +301,14 @@ export async function runCli(argv = process.argv.slice(2)) {
     }
     else {
       console.log(`${result.status.toUpperCase()}: ${result.progress.complete} of ${result.progress.total} program items complete`);
-      console.log(`${result.target.label}${result.target.candidatePeriodStart ? `, candidate period starts ${result.target.candidatePeriodStart}` : ""}`);
+      console.log(
+        `${result.target.label}`
+        + (result.target.candidateCoverage?.kind === "range"
+          ? `, candidate period starts ${result.target.candidateCoverage.startsOn}`
+          : result.target.candidateCoverage?.kind === "as-of"
+            ? `, candidate as-of date ${result.target.candidateCoverage.on}`
+            : "")
+      );
       for (const stage of result.stages) {
         console.log(`\n${stage.title}`);
         for (const item of stage.items) console.log(`${item.status.toUpperCase()}\t${item.title}\t${item.message}`);
@@ -274,33 +320,25 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (flags["require-ready"] && !result.evidenceReady) process.exitCode = 2;
     return output;
   }
-  if (command === "evidence-test-drafts") {
-    if (flags.preview) {
-      const loaded = await loadWorkspace(root);
-      const plan = planEvidenceTestDrafts(loaded);
-      const result = {
-        schemaVersion: 1,
-        preview: true,
-        total: plan.length,
-        create: plan.filter(({ existing }) => !existing).map((item) => ({
-          familyId: item.familyId,
-          title: item.title,
-          testEvidenceKind: item.testEvidenceKind,
-          controlIds: item.controlIds
-        })),
-        existing: plan.filter(({ existing }) => existing).map(({ existing }) => ({
-          id: existing.id,
-          title: existing.title,
-          status: existing.status
-        }))
-      };
-      if (flags.json) console.log(JSON.stringify(result, null, 2));
-      else console.log(`Evidence draft preview: create ${result.create.length}; preserve ${result.existing.length}.`);
-      return result;
-    }
-    const result = await ensureEvidenceTestDrafts(root);
+  if (command === "evidence-map") {
+    const loaded = await loadWorkspace(root);
+    const result = await assessEvidenceMap(loaded, { asOf: flags["as-of"] });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
-    else console.log(`Created ${result.created.length} External Evidence test ${result.created.length === 1 ? "draft" : "drafts"}; ${result.total} required families are represented.`);
+    else {
+      console.log(`${result.status.toUpperCase()}: ${result.counts.complete} mapped, ${result.counts.action} need action`);
+      for (const item of result.items) {
+        console.log(`${item.status.toUpperCase()}\t${item.title}\t${item.message}`);
+        if (item.status !== "action") continue;
+        if (item.sourceKinds?.length) console.log(`  Source role: ${item.sourceKinds.join(" or ")}`);
+        for (const source of item.sourceSystemChecks || []) {
+          const missing = Object.entries(source.checks)
+            .filter(([, passed]) => !passed)
+            .map(([name]) => evidenceSourceCheckName(name));
+          if (missing.length) console.log(`  ${source.sourceSystemId}: ${missing.join(", ")}`);
+        }
+        if (item.commands?.length) console.log(`  Next: ${item.commands[0]}`);
+      }
+    }
     return result;
   }
   if (command === "audit-readiness") {
@@ -339,7 +377,10 @@ export async function runCli(argv = process.argv.slice(2)) {
     else {
       console.log(`Work added to the Work Queue: ${result.actions.length} ${result.actions.length === 1 ? "task" : "tasks"} created for ${result.event.title}.`);
       console.log(`Event: obligation-event/${result.event.id}`);
-      for (const action of result.actions) console.log(`Task: action-item/${action.id}\t${action.title}\t${action.dueWindowEndAt || action.dueWindowEnd || action.overdueAt || action.overdueOn}`);
+      for (const action of result.actions) {
+        const deadline = action.completionWindow?.dueAt || action.completionWindow?.dueOn;
+        console.log(`Task: action-item/${action.id}\t${action.title}\t${deadline}`);
+      }
     }
     return result;
   }
@@ -420,7 +461,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       obligationId,
       record: mutation.record,
       content: mutation.content,
-      expectedRevision: flags["expected-revision"]
+      expectedRevision: requireExpectedRevision(flags, `obligation/${obligationId}`)
     });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else console.log(`Created ${result.created.type}/${result.created.id} and linked it to obligation/${obligationId}`);
@@ -434,7 +475,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       completedOn: flags["completed-on"],
       record: mutation.record,
       content: mutation.content,
-      expectedRevision: flags["expected-revision"]
+      expectedRevision: requireExpectedRevision(flags, `action-item/${actionItemId}`)
     });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else console.log(`Created ${result.created.type}/${result.created.id}, linked it to action-item/${actionItemId}, and marked the action done.`);
@@ -446,7 +487,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     const result = await completeObligationEvent(root, {
       eventId,
       completedOn: flags["completed-on"],
-      expectedRevision: flags["expected-revision"]
+      expectedRevision: requireExpectedRevision(flags, `obligation-event/${eventId}`)
     });
     if (flags.json) console.log(JSON.stringify({ record: result.record }, null, 2));
     else console.log(`Marked obligation-event/${eventId} complete.`);
@@ -454,11 +495,12 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "update") {
     const [type, id, file] = positionals;
-    const mutation = await readMutation(file);
+    const mutation = await readMutation(file, { requireRevision: true });
     const result = await updateResource(root, type, id, mutation.record, {
       content: mutation.content,
       expectedRevision: mutation.revision,
-      expectedContentRevisions: mutation.contentRevisions
+      expectedContentRevisions: mutation.contentRevisions,
+      requireExpectedContentRevisions: true
     });
     if (flags.json) console.log(JSON.stringify({ record: result.record }, null, 2));
     else console.log(`Updated ${result.record.type}/${result.record.id}`);
@@ -509,7 +551,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (!evidenceId || !sourcePath) throw new Error("An evidence ID and source file are required.");
     const result = await addEvidenceAttachment(root, evidenceId, sourcePath, {
       name: flags.name,
-      expectedRevision: flags["expected-revision"]
+      expectedRevision: requireExpectedRevision(flags, `evidence/${evidenceId}`)
     });
     const output = {
       evidenceId,
@@ -525,7 +567,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (!evidenceId || !attachment) throw new Error("An evidence ID and attachment name are required.");
     if (!flags.yes) throw new Error("Pass --yes to confirm attachment removal.");
     const result = await removeEvidenceAttachment(root, evidenceId, attachment, {
-      expectedRevision: flags["expected-revision"]
+      expectedRevision: requireExpectedRevision(flags, `evidence/${evidenceId}`)
     });
     const output = {
       evidenceId,
@@ -539,7 +581,9 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (command === "delete") {
     const [type, id] = positionals;
     if (!flags.yes) throw new Error("Pass --yes to confirm deletion. Preserve historical records unless this is a mistake or uncommitted draft.");
-    await deleteResource(root, type, id, { expectedRevision: flags["expected-revision"] });
+    await deleteResource(root, type, id, {
+      expectedRevision: requireExpectedRevision(flags, `${type}/${id}`)
+    });
     console.log(`Deleted ${type}/${id}`);
     return;
   }
@@ -567,37 +611,18 @@ function parseArgs(args) {
   return { positionals, flags };
 }
 
-async function readMutation(path) {
+async function readMutation(path, options = {}) {
   if (!path) throw new Error("A JSON file path or - is required.");
   const source = path === "-" ? await readStdin() : await readFile(resolve(path), "utf8");
-  const parsed = JSON.parse(source);
-  if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
-    throw new Error("A resource record or { record, content } mutation object is required.");
-  }
-  if (!Object.hasOwn(parsed, "record")) {
-    return { record: parsed, content: undefined, revision: undefined, contentRevisions: undefined };
-  }
-  if (!parsed.record || Array.isArray(parsed.record) || typeof parsed.record !== "object") {
-    throw new Error("Mutation record must be a JSON object.");
-  }
-  if (parsed.content !== undefined && (Array.isArray(parsed.content) || typeof parsed.content !== "object" || parsed.content === null)) {
-    throw new Error("Mutation content must be an object keyed by Markdown slot.");
-  }
-  if (parsed.revision !== undefined && typeof parsed.revision !== "string") {
-    throw new Error("Mutation revision must be a string.");
-  }
-  if (
-    parsed.contentRevisions !== undefined
-    && (Array.isArray(parsed.contentRevisions) || typeof parsed.contentRevisions !== "object" || parsed.contentRevisions === null)
-  ) {
-    throw new Error("Mutation contentRevisions must be an object keyed by data-relative Markdown path.");
+  return normalizeResourceMutation(JSON.parse(source), options);
+}
+
+function requireExpectedRevision(flags, target) {
+  const revision = flags["expected-revision"];
+  if (typeof revision !== "string" || revision.length === 0) {
+    throw new Error(`--expected-revision is required when changing ${target}. Reload the resource and try again.`);
   }
-  return {
-    record: parsed.record,
-    content: parsed.content,
-    revision: parsed.revision,
-    contentRevisions: parsed.contentRevisions
-  };
+  return revision;
 }
 
 async function readSetupPayload(path) {
@@ -643,11 +668,11 @@ async function completeInteractiveSetup(root, payload) {
       activePeople[0].id
     );
     result.criticality ||= await askChoice("Criticality", ["low", "medium", "high", "critical"], "high");
-    result.dataClassification ||= classifications.length
+    result.classificationId ||= classifications.length
       ? await askChoice(
         "Data classification",
         classifications,
-        classifications.includes("Confidential") ? "Confidential" : classifications[0]
+        classifications.includes("confidential") ? "confidential" : classifications[0]
       )
       : await askRequired("Data classification");
     if (result.internetExposed === undefined) {
@@ -690,6 +715,7 @@ Usage:
   filegrc build [root] [--output .filegrc/site]
   filegrc validate [root] [--json]
   filegrc model [--json|--write-docs|--check-docs]
+  filegrc migrate --to-model 2 [--preview] [--job-title text] [--starts-on YYYY-MM-DD] [--yes] [--json]
   filegrc describe <resource-type>
   filegrc types [--json]
   filegrc guide [resource-type] [--id resource-id] [--json]
@@ -699,22 +725,22 @@ Usage:
   filegrc search <query> [--type resource-type] [--json]
   filegrc obligations [--as-of YYYY-MM-DD] [--from YYYY-MM-DD] [--through YYYY-MM-DD] [--now RFC3339] [--complete] [--json]
   filegrc program-readiness [--as-of YYYY-MM-DD] [--require-ready] [--summary] [--json]
-  filegrc evidence-test-drafts [--preview] [--json]
+  filegrc evidence-map [--as-of YYYY-MM-DD] [--json]
   filegrc audit-readiness [audit-id] [--require-ready] [--json]
   filegrc prepare-audit <audit-id> [--json]
   filegrc trigger <event-type> (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) [--subject resource-id[,resource-id]] [--title text] [--json]
   filegrc evidence-packet [--audit audit-id] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--output .filegrc/path] [--preview] [--require-ready] [--json]
   filegrc get [resource-type] <id> [--mutation]
   filegrc references <id> [--json]
-  filegrc create <record-or-mutation.json|-> [--json]
-  filegrc complete <obligation-id> <completion-record.json|-> [--expected-revision hash] [--json]
-  filegrc complete-action <action-item-id> <completion-record.json|-> --completed-on YYYY-MM-DD [--expected-revision hash] [--json]
-  filegrc complete-event <obligation-event-id> --completed-on YYYY-MM-DD [--expected-revision hash] [--json]
-  filegrc update <resource-type> <id> <record-or-mutation.json|-> [--json]
+  filegrc create <mutation.json|-> [--json]
+  filegrc complete <obligation-id> <completion-record.json|-> --expected-revision hash [--json]
+  filegrc complete-action <action-item-id> <completion-record.json|-> --completed-on YYYY-MM-DD --expected-revision hash [--json]
+  filegrc complete-event <obligation-event-id> --completed-on YYYY-MM-DD --expected-revision hash [--json]
+  filegrc update <resource-type> <id> <mutation.json|-> [--json]
   filegrc content <resource-type> <id> [slot] [--write markdown-file|-] [--expected-revision hash] [--json]
-  filegrc attach <evidence-id> <source-file> [--name file-name] [--expected-revision hash] [--json]
-  filegrc detach <evidence-id> <attachment-name> --yes [--expected-revision hash] [--json]
-  filegrc delete <resource-type> <id> --yes [--expected-revision hash]
+  filegrc attach <evidence-id> <source-file> --expected-revision hash [--name file-name] [--json]
+  filegrc detach <evidence-id> <attachment-name> --yes --expected-revision hash [--json]
+  filegrc delete <resource-type> <id> --yes --expected-revision hash
 
 All commands accept --root <workspace>. Writes never create Git commits.`);
 }
@@ -751,7 +777,7 @@ Options:
   --boundary <description>    boundary
   --owner <person-id>         ownerId
   --criticality <level>       low, medium, high, or critical
-  --classification <name>     dataClassification
+  --classification <id>       classificationId
   --internet-exposed <bool>   true or false
   --program-goal <goal>       none, readiness, type-1, or type-2
   --draft                     Save the service boundary as planned
@@ -762,14 +788,37 @@ Options:
   --help                      Show this help`);
     return;
   }
+  if (command === "migrate") {
+    console.log(`Usage:
+  filegrc migrate --to-model 2 [options]
+
+Upgrade a model v1 workspace to model v2. The migration moves reverse
+relationships to their authoritative records, converts the former Policy Owner
+seed role into a dated Appointment, makes repository behavior explicit, rewrites
+the moved program-page ID, removes obsolete collection-test fields and per-record
+schemaVersion keys, and changes dataModelVersion last. It writes no Git commit.
+
+Options:
+  --to-model <version>  Required target model; currently 2
+  --preview             Show the complete atomic record plan without writing
+  --job-title <title>   Actual job title for the former Policy Owner seed person
+  --starts-on <date>    Effective date of a new Policy Owner Appointment
+  --yes                 Apply the reviewed migration
+  --json                Print the plan or result as JSON
+  --root <path>         Workspace path
+  --help                Show this help
+
+Start with:
+  npx filegrc migrate --to-model 2 --preview --json`);
+    return;
+  }
   if (command === "program-readiness") {
     console.log(`Usage:
   filegrc program-readiness [options]
 
 Report whether management has defined scope, activated policies, implemented
-controls, configured authoritative evidence sources, and verified test collection
-for external evidence without a dedicated Step 5 record. No audit ID or CPA firm
-is required.
+controls, and mapped every selected control to a configured authoritative evidence
+source. No audit ID or CPA firm is required.
 
 Options:
   --as-of <date>     Evaluate effective dates and obligations on YYYY-MM-DD
@@ -784,14 +833,14 @@ Options:
     console.log(`Usage:
   filegrc program-path [audit-id] [options]
 
-Show the same six-step SOC 2 lifecycle used by the renderer. Each step includes
+Show the same five-step SOC 2 lifecycle used by the renderer. Each step includes
 its exact page instructions, Use and Policy Basis context, resource commands,
-and current readiness state. Pass an audit ID to include Step 6 status.
+and current readiness state. Pass an audit ID to include Step 5 status.
 
 Options:
-  --audit <id>       Audit record to use for Step 6
+  --audit <id>       Audit record to use for Step 5
   --as-of <date>     Evaluate readiness on YYYY-MM-DD
-  --summary          Print compact status and the first action for all six steps
+  --summary          Print compact status and the first action for all five steps
   --next             Print only the current step and its first action
   --current          Print the full guide for the current step only
   --json             Print the selected path view as JSON
@@ -799,18 +848,18 @@ Options:
   --help             Show this help`);
     return;
   }
-  if (command === "evidence-test-drafts") {
+  if (command === "evidence-map") {
     console.log(`Usage:
-  filegrc evidence-test-drafts [options]
+  filegrc evidence-map [options]
 
-Preview or create missing draft External Evidence records for collection that
-does not already have a dedicated Step 5 operating record. Existing tests are
-preserved. Run after confirming applicable controls and source systems.
+Inspect the evidence-source checks included in Control implementation. Each item
+reports the required source roles, linked Controls, authoritative source Systems,
+per-record checks, and exact edit commands. This diagnostic is read-only.
 
 Options:
-  --preview      Report proposed drafts without creating them
-  --json         Print created and existing records as JSON
-  --root <path>  Workspace path
+  --as-of <date>  Evaluate the map on YYYY-MM-DD
+  --json          Print the map as JSON
+  --root <path>   Workspace path
   --help         Show this help`);
     return;
   }
@@ -826,6 +875,7 @@ function agentOverview(model) {
     build: "filegrc build [root]",
     validate: "filegrc validate [root] --json",
     model: "filegrc model --json",
+    migrate: "filegrc migrate --to-model 2 --preview --json",
     describe: "filegrc describe <resource-type>",
     types: "filegrc types --json",
     guide: "filegrc guide [resource-type] --json",
@@ -835,18 +885,18 @@ function agentOverview(model) {
     search: "filegrc search <query> --json",
     obligations: "filegrc obligations --json",
     programReadiness: "filegrc program-readiness --json",
-    evidenceTestDrafts: "filegrc evidence-test-drafts --preview --json",
+    evidenceMap: "filegrc evidence-map --json",
     auditReadiness: "filegrc audit-readiness <audit-id> --json",
     prepareAudit: "filegrc prepare-audit <audit-id>",
     trigger: "filegrc trigger <event-type> <date-or-time-and-subject-flags>",
     evidencePacket: "filegrc evidence-packet --audit <audit-id> --preview --json",
     get: "filegrc get <resource-id> [--mutation]",
     references: "filegrc references <resource-id> --json",
-    create: "filegrc create <record-or-mutation.json>",
+    create: "filegrc create <mutation.json>",
     complete: "filegrc complete <obligation-id> <completion-mutation.json>",
     completeAction: "filegrc complete-action <action-item-id> <completion-mutation.json> --completed-on <date>",
     completeEvent: "filegrc complete-event <obligation-event-id> --completed-on <date>",
-    update: "filegrc update <resource-type> <id> <record-or-mutation.json>",
+    update: "filegrc update <resource-type> <id> <mutation.json>",
     content: "filegrc content <resource-type> <id> [slot] [--write <markdown-file|->]",
     attach: "filegrc attach <evidence-id> <source-file> [--name <file-name>]",
     detach: "filegrc detach <evidence-id> <attachment-name> --yes",
@@ -922,6 +972,8 @@ function printAgentGuide(result) {
   }
   console.log("\nWorkflow:");
   result.workflow.forEach((step, index) => console.log(`${index + 1}. ${step}`));
+  console.log("\nCompletion checks:");
+  result.completionChecks.forEach((check) => console.log(`- ${check}`));
 }
 
 function buildProgramPathResult(model, readiness, auditReadiness) {
@@ -1069,6 +1121,15 @@ function shellArgument(value) {
     : `'${text.replaceAll("'", "'\\''")}'`;
 }
 
+function evidenceSourceCheckName(name) {
+  return ({
+    active: "activate source",
+    sourceRole: "add source role",
+    accessOwners: "add access owner",
+    retrievalInstructions: "add retrieval instructions"
+  })[name] || name;
+}
+
 function printProgramPathOutput(result, flags) {
   if (flags.summary) {
     console.log(`Current: Step ${result.currentStep.number}, ${result.currentStep.title}`);
@@ -1138,13 +1199,10 @@ function summarizeProgramReadiness(result) {
 }
 
 function eventWindowText(window) {
-  if (Number.isInteger(window?.endOffsetHours)) {
-    return window.endOffsetHours === 0 ? "due at event time" : `due within ${window.endOffsetHours} hours`;
-  }
-  if (Number.isInteger(window?.endOffsetDays)) {
-    return window.endOffsetDays === 0 ? "due on event date" : `due within ${window.endOffsetDays} days`;
-  }
-  return "due within 30 days";
+  if (!Number.isInteger(window?.dueAfter)) return "deadline not configured";
+  const unit = window.precision === "timestamp" ? "hour" : "day";
+  if (window.dueAfter === 0) return window.precision === "timestamp" ? "due at event time" : "due on event date";
+  return `due within ${window.dueAfter} ${unit}${window.dueAfter === 1 ? "" : "s"}`;
 }
 
 function formatGuideField(field) {

package/src/coverage.js

@@ -0,0 +1,50 @@
+export function coverageBounds(coverage) {
+  if (coverage?.kind === "as-of" && typeof coverage.on === "string") {
+    return { start: coverage.on, end: coverage.on };
+  }
+  if (
+    coverage?.kind === "range"
+    && typeof coverage.startsOn === "string"
+    && typeof coverage.endsOn === "string"
+  ) {
+    return { start: coverage.startsOn, end: coverage.endsOn };
+  }
+  return { start: null, end: null };
+}
+
+export function coverageStart(coverage) {
+  return coverageBounds(coverage).start;
+}
+
+export function coverageEnd(coverage) {
+  return coverageBounds(coverage).end;
+}
+
+export function coverageMatches(coverage, start, end = start) {
+  const bounds = coverageBounds(coverage);
+  return bounds.start === start && bounds.end === end;
+}
+
+export function coverageOverlaps(coverage, start, end = start) {
+  const bounds = coverageBounds(coverage);
+  return Boolean(bounds.start && bounds.end && bounds.start <= end && bounds.end >= start);
+}
+
+export function coverageContains(coverage, date) {
+  return coverageOverlaps(coverage, date, date);
+}
+
+export function coverageLabel(coverage) {
+  const bounds = coverageBounds(coverage);
+  if (!bounds.start || !bounds.end) return "";
+  return bounds.start === bounds.end ? bounds.start : `${bounds.start} through ${bounds.end}`;
+}
+
+export function legacyCoverage(record, options = {}) {
+  const asOf = options.asOfFields?.map((field) => record[field]).find(Boolean);
+  if (asOf) return { kind: "as-of", on: asOf };
+  const start = options.startFields?.map((field) => record[field]).find(Boolean);
+  const end = options.endFields?.map((field) => record[field]).find(Boolean);
+  if (start && end) return { kind: "range", startsOn: start, endsOn: end };
+  return null;
+}