filegrc 0.16.5 → 0.16.6

package/package.json

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