filegrc 0.16.5 → 0.16.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filegrc",
-  "version": "0.16.5",
+  "version": "0.16.7",
   "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"})`);
@@ -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
   };

package/src/policy-library/information-security-policy-v2.md

@@ -120,6 +120,8 @@ Removable media containing Confidential or Restricted data requires owner approv
 
 The Data Retention Schedule defines the approved period and disposal method for important in-scope record classes. Supporting standards, procedures, and system records document implementation. Disposal must be suitable for the media and classification, with dated proof when the Control requires it.
 
+Owners document and test how approved deletion requests and retention cutoffs apply to primary data, derived copies, local copies, Vendor-held data, and backups. Procedures identify copies that cannot be removed immediately, their access restrictions and expiry, and any legal hold or contractual limit. Owners verify completion against the approved scope before representing data as deleted.
+
 ## Cryptography, Encryption, Key, and Secrets Management Policy
 
 ### Encryption requirements
@@ -164,6 +166,8 @@ Passwords and other authenticators must meet settings approved for the System's
 - **Customer and external-user access:** MFA is required when an approved Control, customer commitment, or risk decision requires it.
 - **Exceptions:** Where required MFA is unavailable, management must approve a time-bound Exception with a risk assessment, compensating Controls, an accountable owner, and a review or expiration date.
 
+Owners document customer authentication and workforce authentication separately for each relevant System. They record whether either path uses single sign-on, where MFA is enforced, and how access is revoked. Remote-access methods are selected and approved for the System and risk; a VPN is required only when an approved Control, commitment, or risk decision calls for one.
+
 ## Endpoint, Mobile Device, BYOD, and Malware Protection Policy
 
 ### Company devices and platform protection
@@ -194,6 +198,8 @@ Owners restrict inbound, outbound, and internal network paths and management int
 
 Production, development, test, and general-user environments must be separated to the extent needed for their data, exposure, privileges, and change risk. Connections between environments require approved paths and safeguards. Wireless and other local networks used for company work require authentication and encryption appropriate to current risk and technical capability.
 
+When a service processes data for multiple customers, owners define and enforce customer-data boundaries appropriate to the architecture. They verify that access paths and material changes preserve those boundaries, and record the test method, result, and follow-up.
+
 ## Configuration Management and System Maintenance Policy
 
 Important Systems and Components use documented secure configuration expectations based on trusted guidance, technical capability, and risk. Owners change or disable unnecessary default accounts, credentials, services, ports, features, and configurations. Deviations require review and, when material, an approved Exception.
@@ -230,6 +236,8 @@ Important Systems record and protect the security and operational events needed
 
 Logs use synchronized time, restrict alteration and access, and avoid unnecessary secrets or personal data. Each System's retention period belongs in the approved Data Retention Schedule. Owners document risk-based alerts, review paths, thresholds, and response ownership in approved standards, procedures, and schedules.
 
+When an incident may require investigation, responders preserve relevant logs and their context under the incident process, with controlled access and a documented retention or hold decision.
+
 ### Monitoring and alert testing
 
 Systems with availability commitments, recovery objectives, or material operational dependencies monitor the health, capacity, failure, and service indicators needed to detect degradation. Representative alert paths are tested from generation through acknowledgement, escalation, and fallback on the approved schedule and after a material path change. This requirement does not prescribe a particular monitoring or log-management product.

package/src/policy-library.js

@@ -146,6 +146,7 @@ const DOCUMENT_CONTENT_UPDATES = [
   }
 ];
 const PRIOR_STARTER_POLICY_REVISIONS = new Set([
+  "b440eb17797624c1b456f778b12a955c871de308349e565b5d69ab6a25703673",
   "b0f9b988a8bd231fe70ce71b6a732970e709b7af7826c1b55f1532f511b6e511",
   "e87961c6a665d73e9d3cce96ab978df87579668e72ea236248680db1f69a5fa1",
   "2b50c75f4f138eebc7154a6b6e0e50b843f016c228632f7c71239ec27c18cbbf",
@@ -157,6 +158,16 @@ const PRIOR_STARTER_POLICY_REVISIONS = new Set([
 ]);
 
 const CONTROL_UPDATES = [
+  {
+    id: "control-access-review-offboarding",
+    prior: [{
+      activity: "Review access populations, record decisions, and remove dormant, expired, or unneeded access."
+    }],
+    next: {
+      activity: "Review complete access populations, including workers and third parties with customer-data access, record decisions, and remove dormant, expired, or unneeded access."
+    },
+    summary: "Prompt a complete customer-data access population without changing the approved review cadence."
+  },
   {
     id: "control-policy-management",
     prior: [{
@@ -283,15 +294,21 @@ const CONTROL_UPDATES = [
   },
   {
     id: "control-network-security",
-    prior: [{
-      statement: "The organization restricts network paths, protects remote access with approved encryption and authentication, and reviews material network access rules at least annually.",
-      activity: "Manage boundaries, firewall rules, wireless safeguards, and remote production access."
-    }],
+    prior: [
+      {
+        statement: "The organization restricts network paths, protects remote access with approved encryption and authentication, and reviews material network access rules at least annually.",
+        activity: "Manage boundaries, firewall rules, wireless safeguards, and remote production access."
+      },
+      {
+        statement: "The organization restricts network paths, separates production and nonproduction environments according to data and risk, protects remote access with approved encryption and authentication, and reviews material network access rules at least annually.",
+        activity: "Manage boundaries, environment connections, firewall rules, wireless safeguards, and remote production access."
+      }
+    ],
     next: {
       statement: "The organization restricts network paths, separates production and nonproduction environments according to data and risk, protects remote access with approved encryption and authentication, and reviews material network access rules at least annually.",
-      activity: "Manage boundaries, environment connections, firewall rules, wireless safeguards, and remote production access."
+      activity: "Document and verify customer and environment boundaries, approved network rules and deviations by source, wireless safeguards, and remote production access."
     },
-    summary: "Add risk-based production and nonproduction environment separation."
+    summary: "Prompt evidence for customer and environment boundaries and network-rule coverage."
   },
   {
     id: "control-change-management",
@@ -340,23 +357,32 @@ const CONTROL_UPDATES = [
       {
         activity: "Use continuous platform protection where supported and verify endpoint configuration, update, and compliance state on the risk-based schedule recorded in an Obligation when periodic work is needed.",
         requirementIds: ["requirement-soc2-cc6-6", "requirement-soc2-cc6-8", "requirement-soc2-cc7-1"]
+      },
+      {
+        activity: "Use continuous platform protection where supported and verify endpoint configuration, update, and compliance state on the approved risk-based schedule when periodic work is needed.",
+        requirementIds: ["requirement-soc2-cc6-6", "requirement-soc2-cc6-8", "requirement-soc2-cc7-1"]
       }
     ],
     next: {
-      activity: "Use continuous platform protection where supported and verify endpoint configuration, update, and compliance state on the approved risk-based schedule when periodic work is needed.",
+      activity: "Document protection coverage and approved deviations by device or platform class. Use continuous platform protection where supported and verify configuration, updates, and compliance on the approved risk-based schedule when periodic work is needed.",
       requirementIds: ["requirement-soc2-cc6-6", "requirement-soc2-cc6-8", "requirement-soc2-cc7-1"]
     },
-    summary: "Map endpoint malware protection to CC6.8 and keep implementation scheduling out of the Control description."
+    summary: "Prompt platform protection coverage, deviations, and verification without mandating one product."
   },
   {
     id: "control-vulnerability-management",
-    prior: [{
-      activity: "Choose scan coverage and cadence. Review the starter remediation targets of Critical 7 days, High 14 days, Medium 30 days, and Low 90 days, then record the approved targets or time-bound Exceptions."
-    }],
+    prior: [
+      {
+        activity: "Choose scan coverage and cadence. Review the starter remediation targets of Critical 7 days, High 14 days, Medium 30 days, and Low 90 days, then record the approved targets or time-bound Exceptions."
+      },
+      {
+        activity: "Choose scan coverage and cadence, define approved risk-based remediation targets, and document time-bound Exceptions when a target cannot be met."
+      }
+    ],
     next: {
-      activity: "Choose scan coverage and cadence, define approved risk-based remediation targets, and document time-bound Exceptions when a target cannot be met."
+      activity: "Define scan scope and cadence, severity criteria, risk-based remediation and patch targets, and time-bound Exceptions when a target cannot be met."
     },
-    summary: "Keep starter-selection instructions and unapproved remediation targets out of the Control description."
+    summary: "Prompt explicit scan scope, severity criteria, and approved remediation and patch targets."
   },
   {
     id: "control-logging-monitoring",
@@ -403,6 +429,16 @@ const CONTROL_UPDATES = [
       activity: "Assess service, data, access, assurance, recovery, incidents, dependencies, supplied Components, and applicable contract safeguards before access or material reliance."
     },
     summary: "Name the contract outcomes considered when a Vendor handles protected data or supports an important service."
+  },
+  {
+    id: "control-vendor-monitoring",
+    prior: [{
+      activity: "Review vendor performance, assurance, recovery, access, incidents, and contract obligations."
+    }],
+    next: {
+      activity: "Set review intervals by Vendor risk and customer-data access. Review performance, assurance, recovery, access, incidents, and contract obligations, and reassess after material change."
+    },
+    summary: "Prompt review intervals for every customer-data Vendor while keeping the interval risk-based."
   }
 ];
 
@@ -439,6 +475,16 @@ const OBLIGATION_UPDATES = [
   }
 ];
 
+const PRIOR_STARTER_RULE_RATIONALE = "Starter proposal derived from the linked Policy. Management must review the cadence, population, completion criteria, and timing before activation.";
+const OBLIGATION_RULE_RATIONALE_UPDATES = [
+  ["obligation-rule-quarterly-privileged-access-review-v1", "Cover privileged and production access. Add other customer-data access only when an approved commitment or risk decision requires quarterly review."],
+  ["obligation-rule-annual-access-review-v1", "Cover other important access, including customer-data paths not assigned to a shorter approved review schedule. Avoid counting the same access twice."],
+  ["obligation-rule-monthly-endpoint-protection-verification-v1", "Confirm device and platform classes, protection coverage, exceptions, evidence, and whether the monthly cadence fits the approved risk decision."],
+  ["obligation-rule-annual-network-access-review-v1", "Confirm the in-scope network and host rule sources, customer and environment boundaries, deviations, and review cadence."],
+  ["obligation-rule-quarterly-vulnerability-scan-v1", "Confirm scan scope, severity method, remediation and patch targets, and whether exposure or a customer commitment requires a shorter cadence, such as monthly."],
+  ["obligation-rule-annual-critical-vendor-review-v1", "Confirm the high and critical Vendor population, and set a separate review interval for other Vendors with customer-data access where needed."]
+].map(([id, guidance]) => ({ id, rationale: `${PRIOR_STARTER_RULE_RATIONALE} ${guidance}` }));
+
 const OBLIGATION_ADDITIONS = [
   {
     id: "obligation-annual-control-design-review",
@@ -760,6 +806,37 @@ async function buildPolicyLibraryPlan(loaded) {
     });
   }
 
+  for (const { id, rationale } of OBLIGATION_RULE_RATIONALE_UPDATES) {
+    const entry = byId.get(id);
+    const obligation = entry ? byId.get(entry.record.obligationId)?.record : null;
+    const displayPath = `data/obligation-rules/${id}.json`;
+    if (!entry || entry.record.type !== "obligation-rule" || !obligation || obligation.type !== "obligation") {
+      skipped.push(skippedItem(id, "missing", `The starter ${id} Obligation Rule is not present.`));
+      continue;
+    }
+    if (entry.record.rationale === rationale) {
+      skipped.push(skippedItem(id, "current", "The Obligation Rule already contains the current starter guidance."));
+      continue;
+    }
+    if (entry.record.status !== "proposed" || obligation.status !== "proposed") {
+      skipped.push(skippedItem(id, "operating", "Only proposed Obligations and Rules are eligible for starter-library guidance updates."));
+      continue;
+    }
+    if (entry.record.rationale !== PRIOR_STARTER_RULE_RATIONALE || !obligation.ruleIds?.includes(id)) {
+      skipped.push(skippedItem(id, "customized", "The Obligation Rule differs from a recognized prior starter, so FileGRC will not rewrite it."));
+      continue;
+    }
+    updates.push({ ...entry.record, rationale });
+    expectedRevisions[id] = entry.revision;
+    proposalChanges.push({
+      resourceType: "obligation-rule",
+      resourceId: id,
+      path: displayPath,
+      summary: "Add scope and cadence checks to the unchanged proposed starter rule.",
+      diff: replacementDiff(displayPath, [["rationale", entry.record.rationale, rationale]])
+    });
+  }
+
   for (const addition of modelSupports(loaded.model, "program-scope") ? OBLIGATION_ADDITIONS : []) {
     if (byId.has(addition.id)) {
       skipped.push(skippedItem(addition.id, "present", "An Obligation with this ID already exists, so FileGRC will not replace it."));

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

@@ -2038,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");
@@ -2092,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/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/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 } : {}),