filegrc 0.16.4 → 0.16.6

package/package.json

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

package/src/action-context.js

@@ -0,0 +1,70 @@
+// Keep a short, source-backed inventory beside a derived next action. A link
+// means a record exists; it never proves that the recorded process operated.
+export function buildActionContext(loaded, item) {
+  const records = loaded.resources;
+  const byId = new Map(records.map((record) => [record.id, record]));
+  const subjectId = item.subject?.id || item.resourceId;
+  const subject = subjectId ? byId.get(subjectId) : null;
+  const found = new Map();
+  const add = (id, relationship) => {
+    const record = byId.get(id);
+    if (!record || found.has(id)) return;
+    found.set(id, {
+      type: record.type,
+      id: record.id,
+      title: record.title,
+      status: record.status ?? null,
+      relationship
+    });
+  };
+  if (subject) add(subject.id, "subject");
+  if (item.source?.id) add(item.source.id, "source");
+  for (const id of item.sourceResourceIds || []) add(id, "source");
+  for (const dependency of item.dependencies || []) if (dependency.id) add(dependency.id, "prerequisite");
+  const matchingType = item.createResourceType || (!subject && (item.subject?.type || item.resourceType));
+  const sameType = matchingType
+    ? records.filter((record) => record.type === matchingType)
+    : [];
+  if (subject) {
+    const fields = { ...loaded.model.commonFields, ...loaded.model.resources[subject.type]?.fields };
+    for (const [name, definition] of Object.entries(fields)) {
+      if (!definition?.relation) continue;
+      const ids = Array.isArray(subject[name]) ? subject[name] : [subject[name]];
+      for (const id of ids) if (typeof id === "string") add(id, name);
+    }
+    for (const record of records) {
+      if (record.id === subject.id) continue;
+      const incomingFields = { ...loaded.model.commonFields, ...loaded.model.resources[record.type]?.fields };
+      for (const [name, definition] of Object.entries(incomingFields)) {
+        if (!definition?.relation) continue;
+        const ids = Array.isArray(record[name]) ? record[name] : [record[name]];
+        if (ids.includes(subject.id)) add(record.id, name);
+      }
+    }
+  }
+  for (const record of sameType) add(record.id, "same-type-candidate");
+  const existing = [...found.values()];
+  const unmetChecks = item.unmetChecks || Object.entries(item.checks || {})
+    .filter(([, passed]) => passed === false)
+    .map(([name]) => name);
+  return {
+    workPhase: actionPhase(item),
+    operation: item.createResourceType
+      ? sameType.length ? "inspect-before-create" : "check-before-create"
+      : subject ? "inspect-existing" : sameType.length ? "inspect-before-create" : "check-before-create",
+    unmetChecks,
+    existing: existing.slice(0, 20),
+    existingCount: existing.length,
+    existingTruncated: existing.length > 20,
+    ...(matchingType ? { sameTypeCount: sameType.length } : {}),
+    operationProof: "not-inferred-from-links",
+    reminder: "Related records show current design or recorded work. Verify actual operation before claiming it occurred."
+  };
+}
+
+function actionPhase(item) {
+  if (item.assessment === "period-health" || ["run", "operation"].includes(item.stage)) return "operation";
+  if (["audit-readiness", "delivery-readiness", "audit-closure"].includes(item.assessment) || item.stage === "audit") return "audit";
+  if (item.assessment === "program-configuration" || ["scope", "policies", "controls"].includes(item.stage)) return "setup";
+  return "record";
+}

package/src/agent.js

@@ -74,6 +74,9 @@ export function buildAgentGuide(loaded, type, options = {}) {
   const location = definition.singleton
     ? `data/${definition.singleton}`
     : `data/${definition.collection}/${(definition.recordPath ?? "{id}.json").replaceAll("{id}", options.id || "{id}")}`;
+  const existingRecords = loaded.resources
+    .filter((item) => item.type === type)
+    .sort((left, right) => `${left.title}:${left.id}`.localeCompare(`${right.title}:${right.id}`));
 
   return {
     type,
@@ -104,6 +107,13 @@ export function buildAgentGuide(loaded, type, options = {}) {
         : null
     },
     location,
+    existingRecordCount: existingRecords.length,
+    existingRecords: existingRecords.slice(0, 25).map(({ id, title, status }) => ({
+      id,
+      title,
+      status: status ?? null
+    })),
+    existingRecordsTruncated: existingRecords.length > 25,
     singleton: Boolean(definition.singleton),
     requiredAtCreation,
     conditionalRequirements,
@@ -113,8 +123,8 @@ export function buildAgentGuide(loaded, type, options = {}) {
     workflow: [
       "Inspect existing records and relation candidates before writing.",
       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.",
+        ? "Open the existing singleton record and update only gaps supported by facts from an authoritative source."
+        : "Reuse and update a suitable existing record. Create a scaffold only when no record covers the work, 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.",

package/src/cli.js

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { ACTIVE_MODEL_VERSION, loadModel, SUPPORTED_MODEL_VERSIONS } from "../model/index.js";
 import { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldResourceMutation } from "./agent.js";
+import { buildActionContext } from "./action-context.js";
 import { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 import { saveAuditPopulation, scaffoldAuditPopulationCorrection } from "./audit-populations.js";
 import { createNextAuditCycle, planNextAuditCycle } from "./audit-transition.js";
@@ -295,7 +296,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       programId
     });
     const result = buildProgramPathResult(loaded.model, readiness, auditReadiness);
-    const output = selectProgramPathOutput(result, flags);
+    const output = selectProgramPathOutput(result, flags, loaded);
     if (flags.json) console.log(JSON.stringify(output, null, 2));
     else printProgramPathOutput(output, flags);
     return output;
@@ -935,7 +936,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     const output = flags.workflow
       ? {
           record,
-          workflow: workflowForResource(await assessWorkflow(loaded), record.type, record.id)
+          workflow: workflowForResource(await assessWorkflow(loaded), record.type, record.id, loaded)
         }
       : record;
     console.log(JSON.stringify(output, null, 2));
@@ -1773,6 +1774,9 @@ function printAgentGuide(result) {
   console.log(`Policy basis: ${result.policyBasis}`);
   console.log(`Timing: ${result.cadence}`);
   console.log(`JSON: ${result.location}`);
+  console.log(`Existing ${result.pluralTitle}: ${result.existingRecordCount}`);
+  for (const record of result.existingRecords) console.log(`- ${record.id}\t${record.title}\t${record.status || ""}`);
+  if (result.existingRecordsTruncated) console.log("- More records exist. Run filegrc list for the complete set.");
   if (result.reviewRequirements.collectionReview) {
     const review = result.reviewRequirements.collectionReview;
     console.log(`\nCollection review: ${review.title} (${review.status}, ${review.recordCount} ${review.recordCount === 1 ? "record" : "records"})`);
@@ -1830,7 +1834,7 @@ function buildProgramPathResult(model, readiness, auditReadiness) {
   const readinessById = new Map(readiness.stages.map((stage) => [stage.id, stage]));
   const stages = buildAgentProgramPath(model).map((stage) => {
     if (stage.id === "audit") {
-      const auditAction = auditReadiness?.status === "not-started"
+      const auditAction = !auditReadiness || auditReadiness.status === "not-started"
         ? {
             id: "create-audit",
             status: "action",
@@ -1924,11 +1928,11 @@ function printProgramPath(result) {
   }
 }
 
-function selectProgramPathOutput(result, flags) {
+function selectProgramPathOutput(result, flags, loaded) {
   const modes = ["summary", "next", "current"].filter((name) => flags[name]);
   if (modes.length > 1) throw new Error("Use only one of --summary, --next, or --current.");
   if (flags.summary) return summarizeProgramPath(result);
-  if (flags.next) return nextProgramPath(result);
+  if (flags.next) return nextProgramPath(result, loaded);
   if (flags.current) {
     const stage = result.stages.find(({ id }) => id === result.currentStep.id);
     return { ...result, stages: stage ? [stage] : [] };
@@ -1957,7 +1961,7 @@ function summarizeProgramPath(result) {
   };
 }
 
-function nextProgramPath(result) {
+function nextProgramPath(result, loaded) {
   const stage = result.stages.find(({ id }) => id === result.currentStep.id);
   const nextAction = stage?.nextActions[0];
   return {
@@ -1975,7 +1979,9 @@ function nextProgramPath(result) {
       title: stage.title,
       status: stage.status,
       summary: stage.summary,
-      nextAction: summarizePathAction(nextAction),
+      nextAction: nextAction
+        ? { ...summarizePathAction(nextAction), context: buildActionContext(loaded, { ...nextAction, stage: stage.id }) }
+        : null,
       commands: nextActionCommands(stage, nextAction)
     } : null
   };
@@ -2001,11 +2007,11 @@ function nextActionCommands(stage, action) {
   const commands = [`npx filegrc guide ${resourceType} --json`];
   if (action.resourceId) {
     const resourceId = shellArgument(action.resourceId);
-    commands.push(`npx filegrc get ${resourceId} --mutation`);
+    commands.push(`npx filegrc get ${resourceId} --mutation > MUTATION.json`);
     commands.push(`npx filegrc update ${resourceType} ${resourceId} MUTATION.json --json`);
   } else {
     commands.push(`npx filegrc list ${resourceType} --json`);
-    commands.push(`npx filegrc scaffold ${resourceType} --title "NAME"`);
+    commands.push(`npx filegrc scaffold ${resourceType} --title "NAME" > MUTATION.json`);
     commands.push("npx filegrc create MUTATION.json --json");
   }
   return commands;

package/src/program-path.js

@@ -17,7 +17,7 @@ export const RESOURCE_INSTRUCTIONS = {
   "reporting-route-set": "Replace the reporting-route placeholders with real normal and fallback channels, name the responsible role, and commit the proposal.",
   policy: "Replace Policy placeholders with actual commitments, then have a separate approver approve the exact Markdown revision.",
   document: "Complete the Document Markdown and intended values, assign an owner, and have a separate approver approve the exact revision.",
-  control: "Open this Control’s current next steps. Set up the activity, record how it works, and mark it Implemented when it works.",
+  control: "Open this Control’s next steps and inspect linked Policy, Obligations, Components, and operating records. Reuse existing workflows; fill only the implementation gap, and mark it Implemented when it works. Record actual operation separately.",
   "complementary-control": "Record each real customer or carved-out provider dependency, or confirm that the current scope has none.",
   evidence: "Record a real artifact or approved reference, link its source and supported work, then have another person verify it.",
   "risk-assessment": "Assess the in-scope service, record conclusions, and obtain an independent review.",
@@ -118,7 +118,7 @@ export const RESOURCE_PAGE_SUMMARIES = {
   "retention-schedule-item": "Review each structured retention rule.",
   policy: "Tailor the starter Policy and have someone other than its owner approve it.",
   document: "Adapt and approve plans.",
-  control: "Put each Control in place and record how it works.",
+  control: "Check existing Policy, obligations, and records, then fill each Control’s implementation gap.",
   "complementary-control": "Record customer or provider responsibilities, or confirm there are none.",
   audit: "Record the CPA engagement and scope.",
   "audit-request": "Track fieldwork requests and responses.",

package/src/program-readiness.js

@@ -470,7 +470,7 @@ function scopeStage(workspace, scope, records, byId, model, collectionReviews =
     )));
     items.push(item(
       "commitments",
-      scope.systems.length && uncoveredSystems.length === 0 && unscopedCommitments.length === 0 ? "complete" : "action",
+      !scope.systems.length ? "later" : uncoveredSystems.length === 0 && unscopedCommitments.length === 0 ? "complete" : "action",
       "Record service commitments and system requirements",
       scope.systems.length
         ? `${completeCommitments.length} complete active ${completeCommitments.length === 1 ? "commitment covers" : "commitments cover"} ${scope.systems.length - uncoveredSystems.length} of ${scope.systems.length} in-scope systems.${unscopedCommitments.length ? ` ${unscopedCommitments.length} Commitment${unscopedCommitments.length === 1 ? " has" : "s have"} no System scope and must be reviewed explicitly.` : ""}`
@@ -711,14 +711,23 @@ function reportingRouteItem(records, byId, asOf, timezone = "UTC") {
 }
 
 export function collectionReviewReadinessItem(assessment) {
+  const firstIncomplete = assessment.incompleteRecordProposals?.[0]
+    || assessment.recordProposals?.find(({ complete }) => !complete);
+  const needsFirstRecord = assessment.recordCount === 0
+    && !(assessment.configuration.decisions || []).some((decision) => ["zero-population", "externally-managed"].includes(decision));
+  const proposalAction = !assessment.complete && firstIncomplete;
+  const pendingRetentionRow = assessment.resourceType === "retention-schedule-item"
+    ? assessment.records?.find(({ status }) => status === "planned")
+    : null;
+  const approvalAction = !proposalAction && !pendingRetentionRow
+    ? collectionApprovalIssueAction(assessment)
+    : null;
   const proposalUnits = (assessment.recordProposals || []).map((proposal) => ({
     id: `${assessment.resourceType}-proposal-${proposal.resourceId}`,
     status: proposal.complete ? "complete" : "action",
     title: `${proposal.title} proposal`
   }));
   const proposalBatchComplete = proposalUnits.every(({ status }) => status === "complete");
-  const scheduleApprovalBlocked = assessment.resourceType === "retention-schedule-item"
-    && proposalUnits.some(({ status }) => status !== "complete");
   const batchProgressUnits = assessment.resourceType !== "retention-schedule-item" && proposalUnits.length
     ? [
         {
@@ -737,24 +746,100 @@ export function collectionReviewReadinessItem(assessment) {
     : null;
   return item(
     `collection-review-${assessment.resourceType}`,
-    assessment.complete ? "complete" : scheduleApprovalBlocked ? "blocked" : "action",
-    assessment.status === "stale"
-      ? `Review ${assessment.configuration.title.toLowerCase()} again`
-      : `Review ${assessment.configuration.title.toLowerCase()}`,
-    assessment.message,
-    assessment.review || { type: assessment.resourceType },
+    assessment.complete ? "complete" : pendingRetentionRow && !proposalAction ? "blocked" : "action",
+    proposalAction
+      ? `Complete ${firstIncomplete.title} proposal`
+      : needsFirstRecord
+        ? `Add a record for ${assessment.configuration.title.toLowerCase()}`
+        : approvalAction
+          ? approvalAction.title
+        : assessment.status === "stale"
+          ? `Review ${assessment.configuration.title.toLowerCase()} again`
+          : `Review ${assessment.configuration.title.toLowerCase()}`,
+    proposalAction
+      ? `Complete ${firstIncomplete.title} before reviewing ${assessment.configuration.title.toLowerCase()}.`
+      : assessment.message,
+    proposalAction
+      ? { id: firstIncomplete.resourceId, type: assessment.resourceType }
+      : needsFirstRecord ? { type: assessment.resourceType }
+        : approvalAction ? { type: approvalAction.resourceType, ...(approvalAction.resourceId ? { id: approvalAction.resourceId } : {}) }
+          : assessment.review || { type: assessment.resourceType },
     {
-      resourceType: assessment.resourceType,
+      resourceType: approvalAction?.resourceType || assessment.resourceType,
       reviewPoints: assessment.configuration.reviewPoints,
+      ...(approvalAction?.createResource ? { createResource: true } : {}),
+      ...(pendingRetentionRow && !proposalAction ? { unresolvedAssignments: [{
+        resourceType: "retention-schedule-item",
+        resourceId: pendingRetentionRow.id,
+        reasons: ["Complete or retire the planned retention row before approving the schedule."]
+      }] } : {}),
       ...(batchProgressUnits ? { progressUnits: batchProgressUnits } : {}),
-      commands: [
-        `npx filegrc review-collection ${assessment.resourceType} --scaffold`,
-        `npx filegrc review-collection ${assessment.resourceType} REVIEW.json --preview --json`
-      ]
+      commands: proposalAction
+        ? [
+            `npx filegrc guide ${assessment.resourceType} --json`,
+            `npx filegrc get ${shellArgument(firstIncomplete.resourceId)} --mutation > MUTATION.json`,
+            `npx filegrc update ${assessment.resourceType} ${shellArgument(firstIncomplete.resourceId)} MUTATION.json --json`
+          ]
+        : needsFirstRecord
+          ? [
+              `npx filegrc guide ${assessment.resourceType} --json`,
+              `npx filegrc scaffold ${assessment.resourceType} --title "NAME" > MUTATION.json`,
+              "npx filegrc create MUTATION.json --json"
+            ]
+          : approvalAction
+            ? approvalAction.commands
+            : [
+              `npx filegrc review-collection ${assessment.resourceType} --scaffold > REVIEW.json`,
+              `npx filegrc review-collection ${assessment.resourceType} REVIEW.json --preview --json`,
+              `npx filegrc review-collection ${assessment.resourceType} REVIEW.json --yes --json`
+            ]
     }
   );
 }
 
+function collectionApprovalIssueAction(assessment) {
+  const issue = assessment.approvalIssues?.[0];
+  if (!issue || issue.code === "invalid-retention-schedule-approval-binding") return null;
+  const rows = assessment.records || [];
+  const documentId = issue.resourceId || rows.find(({ scheduleDocumentId }) => scheduleDocumentId)?.scheduleDocumentId;
+  if (issue.code.includes("retention-schedule-document")) {
+    const resourceId = issue.code === "missing-retention-schedule-document" || issue.code === "multiple-retention-schedule-documents"
+      ? null : documentId;
+    return {
+      title: issue.code === "missing-retention-schedule-document" ? "Add the Data Retention Schedule document"
+        : issue.code === "multiple-retention-schedule-documents" ? "Resolve duplicate Data Retention Schedule documents"
+          : "Complete the Data Retention Schedule document",
+      resourceType: "document",
+      resourceId,
+      createResource: issue.code === "missing-retention-schedule-document",
+      commands: resourceId
+        ? ["npx filegrc guide document --json", `npx filegrc get ${shellArgument(resourceId)} --mutation > MUTATION.json`, `npx filegrc update document ${shellArgument(resourceId)} MUTATION.json --json`]
+        : issue.code === "missing-retention-schedule-document"
+          ? ["npx filegrc guide document --json", 'npx filegrc scaffold document --title "Data Retention Schedule" > MUTATION.json', "npx filegrc create MUTATION.json --json"]
+          : ["npx filegrc guide document --json", "npx filegrc list document --workflow --json"]
+    };
+  }
+  if (["retention-row-wrong-schedule-document", "incomplete-retention-schedule-row"].includes(issue.code)) {
+    const row = rows.find(({ id }) => id === issue.resourceId);
+    if (row) return {
+      title: `Complete ${row.title}`,
+      resourceType: "retention-schedule-item",
+      resourceId: row.id,
+      commands: ["npx filegrc guide retention-schedule-item --json", `npx filegrc get ${shellArgument(row.id)} --mutation > MUTATION.json`, `npx filegrc update retention-schedule-item ${shellArgument(row.id)} MUTATION.json --json`]
+    };
+  }
+  if (issue.code === "unreviewed-similar-information-types") return {
+    title: "Review similar Information Types",
+    resourceType: "information-type",
+    commands: ["npx filegrc list information-type --workflow --json", "npx filegrc review-collection information-type --scaffold > REVIEW.json", "npx filegrc review-collection information-type REVIEW.json --preview --json", "npx filegrc review-collection information-type REVIEW.json --yes --json"]
+  };
+  return {
+    title: "Complete retention schedule coverage",
+    resourceType: "retention-schedule-item",
+    commands: ["npx filegrc guide retention-schedule-item --json", "npx filegrc list retention-schedule-item --workflow --json", 'npx filegrc scaffold retention-schedule-item --title "RETENTION RULE" > MUTATION.json', "npx filegrc create MUTATION.json --json"]
+  };
+}
+
 function requiredAppointmentsItem(records, model) {
   const assessments = assessRequiredAppointments(records, model);
   const incomplete = assessments.filter(({ requiredness, state }) => (
@@ -1953,41 +2038,41 @@ function controlCheckLabel(name) {
   })[name] || name;
 }
 
-const starterControlSetup = {
-  "control-security-governance": "Name a reviewer outside day-to-day security ownership and set up a quarterly security review.",
-  "control-policy-management": "Assign someone to maintain the Control list and a separate approver for policies and plans. Set up their review path.",
-  "control-security-communication": "Set up how the approved reporting routes, policy changes, and security notices reach staff and outside parties.",
-  "control-workforce-expectations": "Set up the checks, agreements, and policy acknowledgements required before someone receives sensitive access.",
-  "control-security-training": "Choose how new and existing workers receive security training, acknowledge the current material, and get reminders.",
-  "control-risk-assessment": "Use the Program's risk method to assess the scoped service and record the results in FileGRC Risk Assessments and Risks.",
-  "control-monitoring-remediation": "Define how Control problems are reported, reviewed, and verified closed. Use FileGRC Findings for gaps that need separate follow-up.",
-  "control-access-authorization": "Configure unique, least-privilege accounts in the identity system. Restrict account changes to authorized admins.",
-  "control-strong-authentication": "Turn on required MFA and secure sign-in settings for the in-scope Systems. Identify any gap that needs an approved Exception.",
-  "control-access-review-offboarding": "Confirm the identity system can produce a complete access list and admins can promptly remove or change permissions.",
-  "control-physical-workspace-security": "Decide how visitors, work areas, devices, and paper records are protected in the places your team actually works.",
-  "control-data-classification-inventory": "Apply the approved Classifications to important data in the in-scope Systems and record its location in the inventory.",
-  "control-encryption-transmission": "Configure encryption for in-scope data and devices, and assign who manages keys and approved transfer methods.",
-  "control-data-retention-disposal": "Apply the approved retention schedule to live, backup, and vendor-held data. Define how each class is deleted or destroyed.",
-  "control-inventory-configuration": "List important assets and owners, choose their secure settings, and decide how unsupported assets are handled.",
-  "control-endpoint-protection": "Apply the required device settings, updates, encryption, screen lock, and malware protection to devices that access company Systems.",
-  "control-network-security": "Restrict production network paths and remote access, and document the rules that allow traffic between environments.",
-  "control-change-management": "Set up a change path with risk review, testing, approval, deployment, and rollback for software and infrastructure changes.",
-  "control-vulnerability-management": "Choose what will be scanned, how often, who handles findings, and the target times for fixing them.",
-  "control-penetration-testing": "Decide whether independent testing is needed for this service. If it is, set its scope, cadence, and owner.",
-  "control-logging-monitoring": "Enable useful security logs and alerts for important Systems, protect them, and choose who responds to alerts.",
-  "control-incident-response": "Set up a way to report, assign, escalate, contain, and close security incidents using the approved response plan.",
-  "control-incident-exercise": "Choose a realistic incident scenario and an alert path to test, and assign the people who will run the exercise.",
-  "control-backup-restoration": "Choose what needs backup or another recovery path, configure it, and decide how restores will be tested.",
-  "control-continuity-exercise": "Set recovery priorities, contacts, and responsibilities, and choose how the continuity plan will be exercised.",
-  "control-vendor-due-diligence": "Set a security review and contract check before a new Vendor gets sensitive data or becomes a material dependency.",
-  "control-vendor-monitoring": "Choose which Vendors need ongoing review, who reviews them, and what information the review uses.",
-  "control-security-exceptions": "Document how an Exception is reviewed and approved before a departure from policy begins. Record actual decisions in FileGRC Exceptions."
+const starterControlChecks = {
+  "control-security-governance": "Open the security review calendar and attendee roles. Check a reviewer separate from owners and operators examines risks, incidents, findings, and overdue work on the approved schedule.",
+  "control-policy-management": "Open the Control inventory and a recently revised Policy. Check owners are named, the approver is separate, and the change went through review before approval.",
+  "control-security-communication": "Trace how a security notice or Policy change reaches staff and affected outside parties. Check that the approved reporting routes can be used.",
+  "control-workforce-expectations": "Review onboarding for roles with sensitive access. Check that required screening, agreements, and Policy acknowledgements happen before access.",
+  "control-security-training": "Compare the worker roster with training assignments. Check starters and role changes get training on time, with repeats tied to current content and the approved schedule.",
+  "control-risk-assessment": "Open the risk assessment against in-scope Systems and Vendors. Check threats, fraud, dependencies, and changes have owners and high risks get the required review.",
+  "control-monitoring-remediation": "Open the latest Control review, or schedule the first. Check incidents, test results, Exceptions, and overdue work, with owners and verified closure for gaps.",
+  "control-access-authorization": "Open access lists for in-scope Systems and Vendor tools. Check that accounts use unique identities and only needed permissions, and new grants require a business reason and approval.",
+  "control-strong-authentication": "Open the System and Vendor lists. For each tool used for production, source code, email, identity, or sensitive data, check MFA, unique accounts, default credentials, and admin roles.",
+  "control-access-review-offboarding": "Export access lists from key Systems and Vendor tools. Check privileged and other access reviews meet their approved schedules, and departures lose access within the required window.",
+  "control-physical-workspace-security": "Walk through actual work areas and visitor access. Check who can enter nonpublic spaces and how devices, papers, screens, and conversations are protected.",
+  "control-data-classification-inventory": "List important data stores in Systems and Vendor tools. Check each has an owner, classification, approved purpose, and recorded location.",
+  "control-encryption-transmission": "For Systems, Vendor tools, and devices holding Confidential or Restricted data, check encryption at rest and in transit and who can manage the keys.",
+  "control-data-retention-disposal": "Take each class in the retention schedule and locate its live, backup, and vendor-held copies. Check deletion methods and timing against the approved rule.",
+  "control-inventory-configuration": "Compare actual services, devices, software, service accounts, Vendors, and data stores with the inventory. Check owners, secure settings, and unsupported assets.",
+  "control-endpoint-protection": "Review devices allowed into company Systems. Check encryption, screen lock, updates, and malware protection against the approved settings.",
+  "control-network-security": "Open production network and remote-access rules. Check each path has a business reason, approved authentication, and separation; identify rules due for review.",
+  "control-change-management": "Follow a software or infrastructure change from request to deployment. Check the path includes risk review, testing, approval, and a way to recover.",
+  "control-vulnerability-management": "List internet-facing and important Systems. Check each has vulnerability scan coverage or another approved check, and findings have owners and target dates.",
+  "control-penetration-testing": "Review the service's exposure, major changes, and customer commitments. Decide whether independent testing is needed and, if so, set its scope and cadence.",
+  "control-logging-monitoring": "For each important System, open security logs, alert rules, and service-health checks where needed. Check retention and whether test alerts reach an owner.",
+  "control-incident-response": "Walk through how a worker reports an incident. Check who triages, escalates, contains, communicates, and closes it using the approved plan.",
+  "control-incident-exercise": "Send a test alert through a representative incident path. Check acknowledgement, escalation, and fallback, then record participants, failures, and follow-up.",
+  "control-backup-restoration": "For each important System, inspect backup or alternate recovery settings and failure alerts. Run or review a restore test against its recovery needs.",
+  "control-continuity-exercise": "Review recovery priorities, contacts, and owners. Check the plan covers loss of an important System or provider and has an exercise date.",
+  "control-vendor-due-diligence": "Open the Vendor list. For each with sensitive data or a material service role, check its security review and contract terms; review older Vendors already in use.",
+  "control-vendor-monitoring": "Open critical and high-risk Vendors. Check each has a current review, an owner for open issues, and timely reassessment after a material change or incident.",
+  "control-security-exceptions": "Review departures from security rules. Check each has a reason, owner, risk assessment, compensating measure, approval, and expiry or review date."
 };
 
 export function controlImplementationSteps(control, checks, options = {}) {
   const steps = [];
-  if (!checks.implemented) steps.push(starterControlSetup[control.id]
-    || `Set up this Control: ${control.activity || control.statement}`);
+  if (!checks.implemented) steps.push(starterControlChecks[control.id]
+    || "Inspect the systems, people, vendors, or work this Control covers. Compare current practice with its statement and fix any gaps.");
   const record = [];
   if (!checks.owner) record.push("choose an owner");
   if (!checks.scope) record.push("select the Systems this covers");
@@ -2007,7 +2092,7 @@ export function controlImplementationSteps(control, checks, options = {}) {
     ? `Cover the missing evidence families: ${sourceTargets.length ? sourceTargets.join(" and ") : "this Control"}. For each, link an active Component with the matching kind, evidence owners, and report retrieval instructions.`
     : null;
   const queueStep = checks.workQueue === false
-    ? "Enable a linked Obligation with the owner and schedule for this Control's recurring or event work."
+    ? "Check the linked Obligations. Enable one with the owner and schedule for this Control's recurring or event work, or add one if none covers it."
     : null;
   if (!checks.implemented) {
     if (sourceStep || queueStep) steps.push([sourceStep, queueStep].filter(Boolean).join(" "));

package/src/reconciliation.js

@@ -769,6 +769,7 @@ function validateMergeIdentities(index, model) {
     const identities = new Map();
     for (const parent of parents) {
       const state = recordStateAtCommit(index, model, parent);
+      if (!state) continue;
       let snapshot = snapshots.get(state);
       if (!snapshot) {
         snapshot = state.snapshot || snapshotRecordState(state);

package/src/retention-schedule-approval.js

@@ -43,7 +43,7 @@ export function retentionScheduleApprovalIssues(loaded, program, rows, options =
     || !substantiveMarkdown(scheduleContent)
     || openPlaceholderCount(scheduleContent) > 0)
   ) {
-    issues.push(issue("incomplete-retention-schedule-document", "Complete the Data Retention Schedule document, its owner, linked Control, and Markdown before requesting approval of the complete schedule."));
+    issues.push(issue("incomplete-retention-schedule-document", "Complete the Data Retention Schedule document, its owner, linked Control, and Markdown before requesting approval of the complete schedule.", schedule.id));
   }
   if (
     schedule
@@ -60,7 +60,7 @@ export function retentionScheduleApprovalIssues(loaded, program, rows, options =
     ? activeRows.filter(({ scheduleDocumentId }) => scheduleDocumentId !== schedule.id)
     : [];
   if (mismatched.length) {
-    issues.push(issue("retention-row-wrong-schedule-document", `Link every active retention row to the current Data Retention Schedule document before approval: ${mismatched[0].title}.`));
+    issues.push(issue("retention-row-wrong-schedule-document", `Link every active retention row to the current Data Retention Schedule document before approval: ${mismatched[0].title}.`, mismatched[0].id));
   }
   const revisions = resourceReviewRevisionsSync(
     loaded,
@@ -68,7 +68,7 @@ export function retentionScheduleApprovalIssues(loaded, program, rows, options =
   );
   const incomplete = activeRows.filter((row) => !retentionRuleIsCurrent(row, revisions, byId, loaded));
   if (incomplete.length) {
-    issues.push(issue("incomplete-retention-schedule-row", `Complete the retention decisions before approving the schedule revision: ${incomplete[0].title}.`));
+    issues.push(issue("incomplete-retention-schedule-row", `Complete the retention decisions before approving the schedule revision: ${incomplete[0].title}.`, incomplete[0].id));
   }
   const proposedRows = rows.filter(rowProposesCoverage);
   const scopedPrograms = program.programIds
@@ -96,8 +96,8 @@ function sameIds(left = [], right = []) {
   return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
 }
 
-function issue(code, message) {
-  return { code, message };
+function issue(code, message, resourceId) {
+  return { code, message, ...(resourceId ? { resourceId } : {}) };
 }
 
 function primaryMarkdown(loaded, record) {

package/src/server.js

@@ -670,8 +670,9 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
             : await createResourceDetail(input, type, id, { includeHistory: url.searchParams.get("history") !== "false" });
           if (!entry) return json(response, 404, { error: "Resource not found." });
           if (includeWorkflow && !session) {
-            const workflow = await assessWorkflow(input, { programId: requestOptions.programId });
-            entry.workflow = workflowForResource(workflow, type, id);
+            const loaded = await loadWorkspace(input);
+            const workflow = await assessWorkflow(loaded, { programId: requestOptions.programId });
+            entry.workflow = workflowForResource(workflow, type, id, loaded);
           }
           return json(response, 200, entry);
         }
@@ -1008,7 +1009,7 @@ async function loadStateSessionResource(session, token, type, id, serverOptions,
         historyDeadlineAt: deadlineAt,
         strictHistory: repository?.git?.available === true
       }));
-      detail.workflow = workflowForResource(workflow, type, id);
+      detail.workflow = workflowForResource(workflow, type, id, session.loaded);
     }
     await verifyStateSessionSnapshot(session, performance.now(), deadlineAt);
     assertCurrentStateSession(session);

package/src/web.js

@@ -578,8 +578,8 @@ function readinessOverview() {
     const stage = READINESS_STAGES.find((candidate) => candidate.id === id);
     const current = stageProgress(stage);
     const remaining = current.total - current.complete;
-    const status = !remaining ? "Ready" : current.complete ? remaining + " pages need work" : "Needs work";
-    return [stage.title, stage.summary, href, status, !remaining ? "good" : current.complete ? "warn" : "neutral"];
+    const status = current.status === "In progress" ? remaining + " pages need work" : current.status;
+    return [stage.title, stage.summary, href, status, current.tone];
   };
   const stages = [
     programStage("scope", "#/stage/scope"),
@@ -787,6 +787,7 @@ function wireRetentionScheduleTable(total, initialPage = 1) {
 function renderRetentionScheduleIssues() {
   const actions = retentionSchedulePageItems().filter((item) => (
     item.id !== "collection-review-retention-schedule-item"
+      || !item.commands?.some((command) => command.includes(" review-collection retention-schedule-item"))
   ));
   if (!actions.length) return "";
   return '<section class="retention-issues"><div class="section-head"><div><p class="kicker">Before approval</p><h2>Items to resolve</h2></div></div><div class="retention-issue-list">' + actions.map((item) => {
@@ -1719,7 +1720,7 @@ function retentionSchedulePageItems() {
         key: item.id,
         state: "ready",
         href: item.id === "collection-review-retention-schedule-item"
-          ? "#/retention-schedule"
+          ? retentionCollectionActionHref(item)
           : item.id?.startsWith("retention-use-")
             ? retentionScheduleItemHref(item)
             : item.resourceId && item.resourceType
@@ -1732,6 +1733,19 @@ function retentionSchedulePageItems() {
   ]);
 }
 
+function retentionCollectionActionHref(item) {
+  if (item.resourceType === "document") return item.resourceId
+    ? '#/resource/document/' + encodeURIComponent(item.resourceId) + '?stage=policies'
+    : item.createResource
+      ? '#/resources/document?new=1&documentScope=program&documentKind=schedule&programRole=required&title=Data%20Retention%20Schedule'
+      : '#/resources/document';
+  if (item.resourceType === "information-type") return '#/resources/information-type?review-collection=1';
+  if (item.resourceType === "retention-schedule-item" && item.resourceId && item.resourceId !== item.id) {
+    return '#/resource/retention-schedule-item/' + encodeURIComponent(item.resourceId) + '?stage=policies';
+  }
+  return "#/retention-schedule";
+}
+
 function distinctPageActionItems(items) {
   const distinct = new Map();
   for (const item of items) {
@@ -1842,14 +1856,14 @@ function derivedStagePageState(stage, destination) {
       .filter(({ id }) => id.startsWith("source-family-")) || [];
     const incomplete = evidenceItems.filter(({ status }) => status !== "complete").length;
     return incomplete
-      ? { complete: false, label: incomplete + " " + pluralize("source", incomplete) + " need work" }
+      ? { complete: false, label: incomplete + " " + pluralize("source", incomplete) + (incomplete === 1 ? " needs work" : " need work") }
       : { complete: evidenceItems.length > 0, label: evidenceItems.length ? "Ready" : "Not configured", countsTowardProgress: evidenceItems.length > 0 };
   }
   if (destination.utility === "retention-schedule") {
     const incomplete = retentionSchedulePageItems().length;
     return !incomplete
       ? { complete: true, label: "Approved" }
-      : { complete: false, label: incomplete ? incomplete + " " + pluralize("item", incomplete) + " need work" : "Approval needed" };
+      : { complete: false, label: incomplete ? incomplete + " " + pluralize("item", incomplete) + (incomplete === 1 ? " needs work" : " need work") : "Approval needed" };
   }
   const items = stagePageItems(stage, destination);
   const deferredStates = new Set(["later", "scheduled", "upcoming", "waiting-external"]);
@@ -3223,6 +3237,7 @@ function renderList(main, type, params = new URLSearchParams()) {
       ...(params.get("title") ? { title: params.get("title") } : {}),
       ...(params.get("documentKind") ? { documentKind: params.get("documentKind") } : {}),
       ...(documentScope ? { workflowScope: documentScope } : {}),
+      ...(params.get("programRole") ? { programRole: params.get("programRole") } : {}),
       ...relationshipSeed
     } : {
       ...(params.get("title") ? { title: params.get("title") } : {}),

package/src/workflow.js

@@ -2,6 +2,7 @@ import { cp, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { modelSupports } from "../model/index.js";
+import { buildActionContext } from "./action-context.js";
 import { applicabilityReviewIsCurrent, applicabilityScopeRevision } from "./applicability-scope.js";
 import { retentionScheduleIsAuthoritative } from "./collection-review.js";
 import { assessRequiredAppointments } from "./appointments.js";
@@ -194,7 +195,7 @@ async function assessWorkflowUnmeasured(input, options = {}) {
     findings: findings.sort(compareFindings),
     workItems: workItems.sort(compareWorkItems),
     recommended: recommended
-      ? { ...recommended, rankingReason: rankingReason(recommended) }
+      ? { ...recommended, rankingReason: rankingReason(recommended), context: buildActionContext(loaded, recommended) }
       : null,
     counts: {
       findings: countBy(findings, "state"),
@@ -219,7 +220,7 @@ export function buildWorkflowDelta(before, after) {
   };
 }
 
-export function workflowForResource(workflow, type, id) {
+export function workflowForResource(workflow, type, id, loaded = null) {
   if (!workflow) return {
     findings: [],
     workItems: [],
@@ -246,12 +247,16 @@ export function workflowForResource(workflow, type, id) {
     related: {
       findings: relatedFindings,
       workItems: relatedWorkItems,
-      recommended: [...relatedFindings, ...relatedWorkItems].sort(compareRecommended)[0] || null
+      recommended: contextualAction([...relatedFindings, ...relatedWorkItems].sort(compareRecommended)[0], loaded)
     },
-    recommended: [...findings, ...workItems].sort(compareRecommended)[0] || null
+    recommended: contextualAction([...findings, ...workItems].sort(compareRecommended)[0], loaded)
   };
 }
 
+function contextualAction(item, loaded) {
+  return item && loaded ? { ...item, context: buildActionContext(loaded, item) } : item || null;
+}
+
 export async function previewWorkflowMutation(input, mutation) {
   const loaded = await loadWorkspace(input);
   const previewRoot = await mkdtemp(join(tmpdir(), "filegrc-workflow-preview-"));
@@ -1129,6 +1134,9 @@ function normalizeFinding(code, item, context) {
     title: item.title,
     message: item.message,
     ...(item.nextSteps?.length ? { nextSteps: item.nextSteps } : {}),
+    ...(item.checks ? { unmetChecks: Object.entries(item.checks)
+      .filter(([, passed]) => passed === false)
+      .map(([name]) => name) } : {}),
     ...(item.resourceId ? { resourceId: item.resourceId } : {}),
     ...(item.createResourceType ? { createResourceType: item.createResourceType } : {}),
     ...(item.sourceResourceIds ? { sourceResourceIds: item.sourceResourceIds } : {}),