filegrc 0.16.17 → 0.16.18

package/package.json

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

package/src/agent.js

@@ -122,13 +122,15 @@ export function buildAgentGuide(loaded, type, options = {}) {
     oneOf: definition.oneOf ?? [],
     markdown,
     workflow: [
-      "Inspect existing records and relation candidates before writing.",
+      "Inspect the recommended action, existing records, relationships, source Markdown, and available evidence. Do the research, drafting, record edits, and validation you can do yourself.",
       definition.singleton
         ? "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.",
+      "If a material fact, external action, approval, or management decision is still missing, ask the user one specific question. State what you inspected, the exact missing input, and what it unlocks. Do not hand off FileGRC commands, routine record entry, or a vague request to confirm. Continue the workflow after the answer without asking for another handoff.",
+      ...(type === "control" ? ["Separate implementation from operation: document the working configuration, scope, owner, procedure, source, and enabled rules when its operation pattern needs them before marking Implemented. Record dated operating work and evidence only after a real cycle or event occurs; a ready schedule is not proof of operation."] : []),
       ...(type === "program" && modelSupports(loaded.model, "program-scope")
         ? ["Review Requirement applicability with npx filegrc review-applicability --type requirement --scaffold, then preview and apply the reviewed decisions as one validated batch."]
         : []),

package/src/cli.js

@@ -1743,7 +1743,7 @@ function agentOverview(model) {
     commit: "git diff --check && git diff && git add <reviewed-paths> && git commit -m <reason>"
   };
   return {
-    rule: "Treat data/ as the source of truth. Run guide before creating an unfamiliar type, validate after every write, review the Git diff, then commit a focused change.",
+    rule: "Treat data/ as the source of truth. Inspect existing records and sources, then do the research, edits, and validation you can do. Ask the user only for a specific material fact, external action, approval, or decision you cannot establish; explain what it unlocks and continue after the answer. Run guide before creating an unfamiliar type, validate every write, review the Git diff, and commit a focused change.",
     programPath: buildAgentProgramPath(model),
     actions: Object.fromEntries(Object.entries(commands).map(([name, command]) => [
       name,

package/src/program-path.js

@@ -4,11 +4,11 @@ export const RESOURCE_INSTRUCTIONS = {
   program: "Set the Program goal, owners, Systems, Frameworks, criteria decisions, and risk method.",
   person: "Record the person’s actual job title and current status.",
   appointment: "Assign a named authority to one Person with its start date and scope.",
-  team: "Confirm the Team’s members and chair.",
+  team: "Use the current Person and Appointment records to set the Team’s members and chair; ask who holds a role only when those sources cannot establish it.",
   system: "Define the service boundary, exclusions, owners, and information it handles.",
   component: "Record a material service or evidence source and its role in each linked System.",
   vendor: "Record each material external provider and the Components it supplies.",
-  classification: "Confirm the handling categories and apply them to information and evidence.",
+  classification: "Use current Policy content and recorded information needs to propose handling categories, then apply the management decision to information and evidence. Ask about any category those sources do not settle.",
   "information-type": "Name a stable category of information, set its default Classification, and link its uses.",
   framework: "Select the criteria Framework and version used by the Program.",
   requirement: "Review whether this criterion applies to the Program and record the decision and rationale.",
@@ -22,7 +22,7 @@ export const RESOURCE_INSTRUCTIONS = {
   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.",
   risk: "Name the threat and impact, assign an owner, rate the risk, and record its response.",
-  obligation: "Confirm the owner, cadence or trigger, deadline, and proof, then enable the rule when its Control is ready.",
+  obligation: "Read the linked Policy and Control, fill the owner, cadence or trigger, deadline, and proof from those sources, then enable the rule when its Control is ready. Ask only for an unresolved management choice.",
   "retention-schedule-item": "Set the Information Types, scope, cutoff, period, disposition, and sources for one retention rule.",
   "obligation-event": "Record the actual event date and subject, then complete its linked Work Queue actions.",
   "policy-review": "Record the review date, reviewer, decision, and any required follow-up.",
@@ -101,11 +101,11 @@ export const RESOURCE_OUTPUTS = {
 };
 
 export const RESOURCE_PAGE_SUMMARIES = {
-  person: "Confirm who works on the program.",
+  person: "Use current people already recorded; ask for a missing person's identity or role only when needed.",
   appointment: "Assign named authority.",
-  team: "Confirm shared owners and members.",
+  team: "Set shared owners and members from current People and Appointments.",
   program: "Choose the goal, scope, criteria, controls, owners, and risk method.",
-  framework: "Confirm the SOC 2 framework.",
+  framework: "Select the applicable SOC 2 framework and version from the installed catalog.",
   requirement: "Decide which SOC 2 criteria apply.",
   commitment: "Record customer promises that affect scope.",
   "requirement-mapping": "Review how supplemental promises relate to Requirements and Controls.",
@@ -134,8 +134,8 @@ export const PROGRAM_PATH = [
     description: "Ownership, criteria, and service boundary",
     summary: "A reviewed Program scope with owners, criteria, Systems, and material providers.",
     sections: [
-      { id: "ownership", title: "Program Ownership", description: "Confirm who owns the program, plus the normal security reporting channel and its fallback.", steps: ["Confirm the program lead, policy owner, independent reviewer, and oversight team.", "Replace the reporting-channel placeholders with real normal and fallback routes, then commit the proposal."], types: ["person", "appointment", "team", "reporting-route-set"], defaultOpen: true },
-      { id: "criteria", title: "Program and Criteria", description: "Define the Program, confirm its Frameworks, record Program-scoped Requirement applicability, and connect customer commitments that shape the System or Control design.", steps: ["Set the Program goal, owners, risk method, and tentative timing.", "Review each selected criterion for this service and record its applicability decision.", "Replace the starter Commitment prompt with the real promise; add only needed supplemental mappings."], types: ["program", "framework", "requirement", "commitment", "requirement-mapping"], defaultOpen: true },
+      { id: "ownership", title: "Program Ownership", description: "Assign program owners and set the normal security reporting channel and its fallback.", steps: ["Inspect current People and Appointments, then assign the program lead, policy owner, independent reviewer, and oversight team. Ask only for missing assignments.", "Use the actual normal and fallback routes to replace reporting-channel placeholders, then commit the proposal."], types: ["person", "appointment", "team", "reporting-route-set"], defaultOpen: true },
+      { id: "criteria", title: "Program and Criteria", description: "Define the Program, select its Frameworks, record Program-scoped Requirement applicability, and connect customer commitments that shape the System or Control design.", steps: ["Set the Program goal, owners, risk method, and tentative timing from current records; ask for unresolved management choices.", "Compare each selected criterion with the service scope and record its applicability decision.", "Replace the starter Commitment prompt with the actual promise; add only needed supplemental mappings."], types: ["program", "framework", "requirement", "commitment", "requirement-mapping"], defaultOpen: true },
       { id: "boundary", title: "System Boundary", description: "Start with the bounded System. Add Components that materially deliver the service, support Controls, produce authoritative Evidence, or support relevant operations. Keep Vendor relationships and specific Assets separate.", steps: ["Define the service and exclusions in a bounded System selected by the Program.", "Add material Components and Vendors with their actual System relationships.", "Record the Information Types and Classifications the service uses."], types: ["system", "component", "vendor", "classification", "information-type"], defaultOpen: false }
     ],
     resourceTypes: ["person", "appointment", "team", "reporting-route-set", "program", "framework", "requirement", "commitment", "requirement-mapping", "system", "component", "vendor", "classification", "information-type"],
@@ -160,7 +160,7 @@ export const PROGRAM_PATH = [
     description: "Approve governed content and retention decisions",
     summary: "Approved Policies, program Documents, Training content, and retention decisions.",
     sections: [
-      { id: "policy-content", title: "Policies", description: "Approve the program's governing content.", instructions: "Open each Policy, program Document, and Training record. Replace placeholders, confirm the owner and intended values, then have a separate person approve the exact Markdown revision.", output: "Approved content bound to the reviewed revisions.", steps: ["Replace placeholders with the company's real rules, plans, and training material.", "Confirm the owner, separate approver, linked Controls, audience, and intended values.", "Record the independent approval and date against each exact Markdown revision."], types: [], relatedLinks: [{ type: "policy", label: "Policies", href: "#/policies" }], defaultOpen: true },
+      { id: "policy-content", title: "Policies", description: "Approve the program's governing content.", instructions: "Open each Policy, program Document, and Training record. Draft from current approved decisions, replace placeholders, and resolve only material choices with management. A separate person then approves the exact Markdown revision.", output: "Approved content bound to the reviewed revisions.", steps: ["Draft the company's real rules, plans, and training material from current scope and approved decisions.", "Resolve missing owner, separate approver, Control links, audience, or intended values from authoritative records; ask only when a material decision remains.", "Have the independent approver review the exact Markdown revision and record their actual decision and date."], types: [], relatedLinks: [{ type: "policy", label: "Policies", href: "#/policies" }], defaultOpen: true },
       { id: "retention", title: "Data Retention Schedule", description: "Approve the schedule document and its completed rows together.", steps: ["Review the governing schedule and any legal hold or exception rules.", "Complete a row for each distinct information use, cutoff, retention period, and disposition.", "Have a separate reviewer approve the complete document and row set."], types: [], utility: "retention-schedule", defaultOpen: true }
     ],
     resourceTypes: [],
@@ -184,7 +184,7 @@ export const PROGRAM_PATH = [
     description: "Implement and prepare to operate",
     summary: "Implemented Controls with ready evidence sources and enabled work schedules.",
     sections: [
-      { id: "controls", title: "Controls", description: "Put each selected Control into use and record what is actually in place.", steps: ["Open each Control for its specific setup action and current missing checks.", "Configure the activity and record its procedure, Systems, owner, and evidence sources.", "Mark it Implemented with its real start date after its sources and schedules are ready."], types: ["control"], defaultOpen: true },
+      { id: "controls", title: "Controls", description: "Put each selected Control into use and record its working design. Dated operating proof follows when work occurs.", steps: ["Open each Control, linked records, and current missing checks; do the setup that can be established from those sources.", "Configure the activity and record its procedure, Systems, owner, evidence sources, and any work rules its operation pattern requires.", "Mark it Implemented with its real start date when it works. Record later cycles and events separately with dated proof."], types: ["control"], defaultOpen: true },
       { id: "complementary-controls", title: "Complementary Controls", description: "Record customer or provider responsibilities that form part of the implementation boundary, or confirm there are none.", steps: ["Identify any customer or carved-out provider action an in-scope Control depends on.", "Record each dependency, or confirm that the current scope has none."], types: ["complementary-control"], defaultOpen: true },
       { id: "evidence-sources", title: "Evidence Sources", description: "Check that every Control points to an authoritative source that can produce its expected evidence.", steps: ["For each Control family, link an active Component with the required source kind, access owners, and retrieval instructions."], types: [], utility: "evidence-sources", defaultOpen: true },
       { id: "obligations", title: "Obligations", description: "Configure the calendar and event schedules that operate the Controls.", steps: ["Check the owner, trigger or cadence, due window, and required proof for each Obligation.", "Enable the rules that will run the implemented Controls."], types: ["obligation"], defaultOpen: true }

package/src/program-readiness.js

@@ -217,7 +217,7 @@ export async function assessProgramReadiness(input, options = {}) {
       ? item
       : { ...item, status: "blocked", message: `Complete the Control collection review before activation. ${item.message}` };
   }));
-  controlStage.description = `Each implemented Control needs an owner, actual procedure, scope, operation pattern, mappings, an implementation date, enabled Obligations, and complete authoritative source ${modelSupports(loaded.model, "component-sources") ? "Components" : "Systems"}. When implementation is ready, perform one review of the implemented Control collection. Management then activates the unchanged approved program content as the Step 3 cutover.`;
+  controlStage.description = `Each implemented Control needs an owner, actual procedure, scope, operation pattern, mappings, an implementation date, enabled Obligations for scheduled or event work, and complete authoritative source ${modelSupports(loaded.model, "component-sources") ? "Components" : "Systems"}. When implementation is ready, perform one review of the implemented Control collection. Management then activates the unchanged approved program content as the Step 3 cutover.`;
   const scopeReadinessStage = scopeStage(
       program,
       scope,
@@ -596,7 +596,7 @@ function scopeStage(workspace, scope, records, byId, model, collectionReviews =
   items.push(item(
     "criteria",
     criteriaComplete ? "complete" : "action",
-    "Confirm Trust Services criteria, Description Criteria, and Controls",
+    "Resolve criteria decisions and Control coverage",
     criteriaComplete
       ? `${selectedTrustServicesRequirements.length} applicable Trust Services criteria, ${selectedDescriptionRequirements.length} SOC 2 Description Criteria, and ${scope.controls.length} Controls are in scope. Every applicable Trust Services criterion has at least one selected Control; Description Criteria govern the system description and do not map to Controls.`
       : missingRequiredSecurityReferences.length || missingRequiredDescriptionReferences.length
@@ -992,7 +992,7 @@ function programOwnershipItem(records, byId) {
   return item(
     "program-ownership",
     complete ? "complete" : "action",
-    "Confirm program owners and oversight",
+    "Assign program owners and oversight",
     complete
       ? `${currentOwners.size} current ${currentOwners.size === 1 ? "person owns" : "people own"} the program records.${oversight ? " Security and Risk Oversight has a separate current chair." : ""}`
       : detail.join(" "),
@@ -1619,7 +1619,7 @@ function policyActivationItem(assessment) {
     [assessment.unresolvedExceptionIds.length, "unresolved Exceptions"]
   ].filter(([count]) => count).map(([count, label]) => `${count} ${label}`);
   const message = assessment.state === "active-and-operating"
-    ? `Active and effective ${assessment.effectiveOn}; all ${assessment.linkedControlIds.length} linked Controls are implemented with Components, evidence sources, and enabled Obligations.`
+    ? `Active and effective ${assessment.effectiveOn}; all ${assessment.linkedControlIds.length} linked Controls are implemented with Components, evidence sources, and enabled Obligations where scheduled or event work requires them.`
     : assessment.state === "ready-to-activate"
       ? "Implementation checks are complete. Include this approved Policy in the Step 3 cutover when you are ready for it to take effect."
       : `${assessment.label}: ${counts.join(", ") || assessment.timingWarnings.join(" ")}. ${assessment.activationWarning || ""}`.trim();
@@ -2128,7 +2128,7 @@ const starterControlChecks = {
   "control-monitoring-remediation": "Schedule the first Control review. Name who will inspect incidents, tests, Exceptions, overdue work, and follow-up closure when those records exist.",
   "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": "Confirm access lists can be exported from key Systems and Vendor tools. Assign the first access review and the owner who will remove access when a departure occurs.",
+  "control-access-review-offboarding": "Check whether key Systems and Vendor tools can export access lists. Set the first access review and name who removes access after a departure.",
   "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.",
@@ -2154,16 +2154,16 @@ export function controlImplementationSteps(control, checks, options = {}) {
   if (!checks.implemented) steps.push(control.id === "control-strong-authentication" && options.targets?.length
     ? `Ensure MFA and unique accounts are enabled for ${options.targets.join(", ")}; check default credentials and admin roles.`
     : starterControlChecks[control.id]
-    || "Inspect the systems, people, vendors, or work this Control covers. Compare current practice with its statement and fix any gaps.");
+    || `Inspect the Systems, people, Vendors, and work linked to ${control.title || control.id}. Compare the actual configuration with this Control's statement and fix the specific gaps.`);
   const record = [];
-  if (!checks.owner) record.push("choose an owner");
-  if (!checks.scope) record.push("select the Systems this covers");
-  if (!checks.operationPattern) record.push("set when it runs");
-  if (!checks.procedure) record.push("write who does what and when in Procedure");
-  if (!checks.evidenceSource) record.push("link the tool or system that can show it happened");
+  if (!checks.owner) record.push("assign the actual owner from existing People or Appointments");
+  if (!checks.scope) record.push("link the in-scope Systems already in the Program");
+  if (!checks.operationPattern) record.push("record whether it runs continuously, per transaction, on a schedule, or after an event");
+  if (!checks.procedure) record.push("write the current actors, configuration, and procedure in Record Markdown");
+  if (!checks.evidenceSource) record.push("link the authoritative Component that can produce proof");
   if (!checks.policyMapping && checks.policyMapping !== undefined) record.push("link the Policy it implements");
   if (!checks.criteriaMapping && checks.criteriaMapping !== undefined) record.push("link the criteria it covers");
-  if (!checks.implementationDate) record.push("record the actual date it starts working when marking Implemented");
+  if (!checks.implementationDate) record.push("record the date the working implementation took effect when marking Implemented");
   if (checks.procedureRevision === false || checks.procedureEffective === false) {
     record.push("record the Procedure revision and effective date");
   }
@@ -2174,16 +2174,16 @@ 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
-    ? "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."
+    ? "Inspect linked Obligations and their Policy basis. Enable a suitable existing rule with its owner and deadline, or add a rule only if no existing one covers this work. A scheduled rule does not prove a cycle occurred."
     : null;
   if (!checks.implemented) {
     if (sourceStep || queueStep) steps.push([sourceStep, queueStep].filter(Boolean).join(" "));
-    else if (checks.applicability === false) steps.push("Confirm this Control applies to the current Program scope with `review-applicability --scaffold --type control`.");
-    else steps.push("When these launch conditions hold, mark the Control Implemented. This asserts the practice works now; record proof from future cycles and events as they occur.");
+    else if (checks.applicability === false) steps.push("Compare this Control with the current Program scope and record its applicability decision with `review-applicability --scaffold --type control`; ask management only if the decision cannot be established from the scope and commitments.");
+    else steps.push("When these launch conditions hold, mark the Control Implemented with its real effective date. Record dated proof later, when a cycle or event actually occurs.");
   } else {
     if (sourceStep) steps.push(sourceStep);
     if (queueStep) steps.push(queueStep);
-    if (checks.applicability === false) steps.push("Confirm this Control applies to the current Program scope with `review-applicability --scaffold --type control`.");
+    if (checks.applicability === false) steps.push("Compare this Control with the current Program scope and record its applicability decision with `review-applicability --scaffold --type control`; ask management only if the decision cannot be established from the scope and commitments.");
   }
   return steps;
 }

package/src/web.js

@@ -1231,7 +1231,7 @@ function controlLaunchLabel(state) {
   return ({
     planned: "Planned: launch conditions remain",
     partial: "Partially implemented: launch conditions remain",
-    "ready-to-implement": "Launch checks ready: confirm it works, then record the start date",
+    "ready-to-implement": "Launch checks ready: check the live configuration, then record its start date",
     "implemented-with-gaps": "Implemented with gaps: fix the launch checks",
     implemented: "Implemented"
   })[state] || "Control launch";

package/src/workflow.js

@@ -466,13 +466,17 @@ function recordIncompleteReason(record, loaded, program) {
     return {
       state: "ready",
       requiredness: appointmentRequiredness(record, loaded.model),
-      message: "Assign a holder, confirm the authority and independence needed, then activate this Appointment on its actual start date."
+      message: "Check current People and scoped Appointments, assign a qualified holder, and record the actual authority and start date. Ask management only if the holder or independence decision is unresolved."
     };
   }
   const messages = {
     draft: "Add the required details, relationships, and Markdown before review.",
     planned: "Check this planned record against how your program works, then add the missing details.",
-    proposed: "Confirm the work, owner, schedule, and completion requirements before activation.",
+    proposed: ["obligation", "obligation-rule"].includes(record.type)
+      ? "Read the linked Policy and Control, fill the actual owner, schedule, deadline, and proof requirement, then activate the rule. Ask management only for a choice those sources do not settle."
+      : record.type === "reporting-route-set"
+        ? "Fill the normal and fallback reporting routes from approved contact details, commit the proposal, and obtain the required separate approval before it takes effect. Ask only for missing route or authority decisions."
+        : "Inspect the source facts and type guide, complete the proposal, and obtain the required review or approval before activation.",
     "in-review": "Have an independent reviewer approve the exact content revision.",
     open: "Complete this work with the required proof, or formally close it without completion.",
     "in-progress": "Finish the work, record the result, and link the completion proof.",
@@ -724,7 +728,7 @@ function reconciliationFindings(reconciliation) {
     state: "ready",
     severity: "warning",
     requiredness: "conditional",
-    title: `Confirm ${fieldLabel(candidate.eventType)}`,
+    title: `Resolve ${fieldLabel(candidate.eventType)} transition`,
     message: candidate.message,
     subject: candidate.subject,
     fieldPath: candidate.sourcePath,
@@ -1630,12 +1634,12 @@ function periodFinding(key, title, message, state, subject, actions, dependencie
 function auditClosureNextStep(status) {
   const steps = {
     planned: {
-      title: "Confirm the engagement and start audit preparation",
-      message: "Link the agreed engagement terms, confirm scope and management acknowledgement, then move the audit to in progress."
+      title: "Record the agreed engagement and start audit preparation",
+      message: "Read the signed engagement terms, link them, record the agreed scope and management acknowledgement, then move the audit to in progress. Ask for missing terms or acknowledgement only if unavailable."
     },
     "in-progress": {
       title: "Begin fieldwork",
-      message: "Finish management preparation, confirm the fieldwork dates, and move the audit to fieldwork when the CPA firm begins testing."
+      message: "Finish management preparation, record the fieldwork dates agreed with the CPA firm, and move the audit to fieldwork when testing begins. Ask for the dates only if they are not in the engagement correspondence."
     },
     fieldwork: {
       title: "Finish fieldwork and prepare the report",
@@ -1647,7 +1651,7 @@ function auditClosureNextStep(status) {
     },
     issued: {
       title: "Record final report delivery",
-      message: "Confirm the issued report evidence, opinion, report date, authorized recipient, and delivery receipt, then move the audit to delivered."
+      message: "Read the issued report and delivery record, enter the opinion, report date, authorized recipient, and receipt, then move the audit to delivered. Ask only for missing delivery facts."
     },
     delivered: {
       title: "Close the audit",