filegrc 0.3.3 → 0.4.0

package/src/program-path.js

@@ -1,18 +1,19 @@
 export const RESOURCE_INSTRUCTIONS = {
-  person: "Confirm the policy owner created during setup, then add the actual people who will approve, review, or operate the program.",
-  team: "Review the starter Security and Risk Oversight team, including its members and chair. Add another team only when the organization assigns shared responsibility to it.",
-  system: "Catalog all in-scope systems for the program. Treat anything that operates a control or produces evidence as a System, including software provided by a vendor (like HR software).",
-  vendor: "Catalog the companies that provide in-scope software or services. Link each vendor-provided System to the company that provides it.",
+  person: "Record each person’s actual organizational job title. Keep named program authority, such as CISO, DPO, Policy Owner, or team chair, in dated Appointment records.",
+  appointment: "Record one person’s dated appointment to a named organizational or program responsibility. Scope it to the workspace, a team, or the records governed by that appointment.",
+  team: "Review the starter Security and Risk Oversight team, including its members and chair. Membership and chairs are authoritative on the Team record.",
+  system: "Catalog all in-scope systems for the program. Treat anything that operates a control or produces evidence as a System, including software provided by a vendor (like HR software). Set vendorId on each vendor-provided System; the Vendor’s System list is derived. For every authoritative evidence source, set its source roles, name current access owners, and write repeatable retrieval instructions in Record Markdown before implementing the linked Controls.",
+  vendor: "Catalog the companies that provide in-scope software or services. Link each vendor-provided System with the System’s vendorId.",
   framework: "Confirm the criteria framework and version used for the program.",
   requirement: "Review each criterion, decide whether it applies, and record the reason for that decision.",
-  commitment: "Record supplemental customer promises and service requirements that shape the scope or control design.",
-  policy: "Tailor each policy to match how the organization works. Clear placeholders, assign an owner and separate approver, then record its approval and effective dates.",
+  commitment: "Record supplemental customer promises and service requirements that shape the scope or control design. The Commitment’s systemIds and controlIds are authoritative for what fulfills it.",
+  policy: "Tailor each policy to match how the organization works. Clear placeholders, assign an owner and separate approver, then record its approval and effective dates. Controls link to their governing Policies.",
   document: "Tailor the governed plans and other supporting documents the program needs. Assign owners and approvers, then keep the approved Markdown in Git.",
-  control: "Finish each applicable starter control with the procedure people will follow, its owner, scope, cadence, evidence source, and implementation date.",
+  control: "Finish each applicable starter control with the procedure people will follow, its owner, scope, operation pattern, governing Policy and Requirement mappings, authoritative evidence source Systems, and implementation date. Put calendar and event schedules in Obligations. Confirm that each source is active, has the required evidence role and access owners, and includes repeatable retrieval instructions in Record Markdown.",
   "complementary-control": "Record anything customers or carved-out providers must do for your controls to work as intended.",
-  evidence: "Complete the generated tests for external evidence that has no dedicated Step 5 record. Link each result to its Control and source System, then have another person verify it. When a Step 5 operating record exists, link the artifact’s External Evidence record there instead.",
+  evidence: "Create External Evidence when a real export, report, screenshot, signed file, or approved external reference exists. Select its authoritative source System, link the Controls and operating record it supports, retain the fixed artifact or reference, and have another person verify it before audit use.",
   "risk-assessment": "Complete and approve an assessment of the risks to the in-scope service, systems, vendors, and commitments.",
-  risk: "Record each risk identified by an assessment or operating activity. Assign an owner, rate it, and document the chosen response.",
+  risk: "Record each risk identified by an assessment or operating activity. Assign an owner, rate it, document the chosen response, and link the Controls that treat it from the Risk record.",
   obligation: "Review the recurring work proposed by effective policies. Confirm who owns it, when it is due, and what proof completion requires.",
   "obligation-event": "When a policy-triggering event occurs, record it here and complete the actions filegrc creates for it.",
   "policy-review": "Record scheduled and change-driven reviews of policies and governed documents, including the decision and any follow-up.",
@@ -33,45 +34,30 @@ export const RESOURCE_INSTRUCTIONS = {
   exercise: "Record each incident or continuity exercise, including its objective, participants, result, and follow-up.",
   finding: "Create a Finding only for a confirmed gap that needs separate remediation tracking. Keep the report details in the source record’s Markdown, then assign the Finding, set its due date, and verify closure.",
   "action-item": "Create an Action Item only when follow-up needs its own assignee, deadline, and completion proof. Point it to the record that created the work, then work it from Work Queue.",
-  audit: "Create this record after engaging the CPA firm, then record the agreed scope, criteria, Systems, and report period.",
+  audit: "Create this record after engaging the CPA firm, then record the agreed scope, criteria, Systems, and report period. Control Tests and External Evidence link back with auditId or auditIds.",
   "audit-request": "Record each request from the audit team, assign an owner and due date, and link the approved response and evidence.",
   "data-request": "Record privacy or contractual requests when they apply to the audit scope or the organization’s commitments.",
   "control-test": "Record how an in-scope control was tested, what was sampled, the result, and any exceptions.",
   "audit-population": "Record each complete Type 2 population with its source System, fixed export, query, count, and reconciliation."
 };
 
-export const POLICY_EVENT_NAMES = {
-  "person-started": "New Worker",
-  "person-ended": "Worker Departure",
-  "high-risk-person-ended": "High-Risk Departure",
-  "person-role-changed": "Role Change",
-  "personal-device-access-planned": "Personal Device Access",
-  "vendor-access-planned": "Vendor Access",
-  "vendor-reassessment-needed": "Vendor Reassessment",
-  "system-material-change": "Material System Change",
-  "material-incident": "Material Incident"
-};
-
-export function policyEventName(eventType) {
-  return POLICY_EVENT_NAMES[eventType] || humanize(eventType);
-}
-
 export const PROGRAM_PATH = [
   {
     id: "scope",
     number: 1,
     title: "Define Scope",
     description: "Ownership, criteria, and service boundary",
-    summary: "Confirm the people and teams responsible for the program, set the management goal, review the criteria and customer commitments in scope, then define the customer-facing service, supporting systems, and supplier dependencies.",
+    summary: "Confirm the people, dated appointments, and teams responsible for the program, set the management goal, review the criteria and customer commitments in scope, then define the customer-facing service, supporting systems, and supplier dependencies.",
     sections: [
-      { id: "ownership", title: "Program Ownership", description: "Confirm the people and teams that own, approve, review, and operate the program.", steps: ["Confirm the policy owner created during setup, then add the organization’s actual reviewers and operators.", "Review the starter Security and Risk Oversight team, its members, and its chair.", "Add other teams only when the organization assigns shared responsibility to them."], types: ["person", "team"], defaultOpen: true },
+      { id: "ownership", title: "Program Ownership", description: "Confirm the people, appointments, and teams that own, approve, review, and operate the program.", steps: ["Confirm the initial program lead’s actual job title and the separate Policy Owner Appointment.", "Add the organization’s real appointments, reviewers, and operators.", "Review the starter Security and Risk Oversight team, its members, and its chair.", "Add other teams only when the organization assigns shared responsibility to them."], types: ["person", "appointment", "team"], defaultOpen: true },
       { id: "criteria", title: "Criteria", description: "Confirm the criteria used for the program, resolve whether each requirement applies, and record customer commitments that shape the service or control design.", steps: ["Review the included Security criteria references.", "Mark each requirement applicable or not applicable with a rationale.", "Record customer commitments and keep optional criteria out until management deliberately adds them."], types: ["framework", "requirement", "commitment"], defaultOpen: true },
-      { id: "boundary", title: "Service Boundary", description: "Record the service and its supporting technology and providers. An application or platform is a System because it operates controls or produces evidence; the company providing it is a Vendor because contracts, due diligence, and supplier risk belong to that relationship.", steps: ["Create a Vendor record for each material provider.", "Create System records for the customer-facing service and each supporting application, platform, or internal system that is in scope or produces evidence, then connect vendor-provided Systems to their providers.", "Assign owners, classification, dependencies, and a clear in-scope decision to each System, and keep supplier reviews with the Vendor."], types: ["vendor", "system"], defaultOpen: false }
+      { id: "boundary", title: "Service Boundary", description: "Record the service and its supporting technology and providers. An application or platform is a System because it operates controls or produces evidence; the company providing it is a Vendor because contracts, due diligence, and supplier risk belong to that relationship.", steps: ["Create a Vendor record for each material provider.", "Create System records for the customer-facing service and each supporting application, platform, or internal system that is in scope or produces evidence, then connect vendor-provided Systems to their providers.", "Assign owners, classification, and dependencies, then select the program-scope Systems on the Workspace.", "For Systems that produce control evidence, add their evidence source roles and access owners, then write the exact retrieval procedure in Record Markdown before implementing the linked Controls."], types: ["vendor", "system"], defaultOpen: false }
     ],
-    resourceTypes: ["person", "team", "framework", "requirement", "commitment", "vendor", "system"],
+    resourceTypes: ["person", "appointment", "team", "framework", "requirement", "commitment", "vendor", "system"],
     commands: [
       "filegrc setup",
       "filegrc guide person --json",
+      "filegrc guide appointment --json",
       "filegrc guide system --json",
       "filegrc list system --json"
     ]
@@ -81,9 +67,9 @@ export const PROGRAM_PATH = [
     number: 2,
     title: "Approve Policies",
     description: "Tailor, review, approve, and adopt",
-    summary: "Turn every applicable policy and governed plan into the organization’s actual rules, remove placeholders, link governed controls, and establish approval and effective dates before scheduled work begins. The reviewer must be separate from the owner, is usually internal, and may be external.",
+    summary: "Turn every applicable policy and governed plan into the organization’s actual rules, remove placeholders, confirm that Controls link to their governing Policies, and establish approval and effective dates before scheduled work begins. The reviewer must be separate from the owner, is usually internal, and may be external.",
     sections: [
-      { id: "library", title: "Policy Library", description: "Review, approve, and activate policies and governed plans without treating starter text as adopted practice.", steps: ["Review policy Markdown and replace every organization placeholder.", "Confirm the owner, separate approver, audience, linked controls, and review cadence.", "Record approval and effective dates before changing the status to active."], types: ["policy", "document"], defaultOpen: true }
+      { id: "library", title: "Policy Library", description: "Review, approve, and activate policies and governed plans without treating starter text as adopted practice.", steps: ["Review policy Markdown and replace every organization placeholder.", "Confirm the owner, separate approver, audience, review Obligation, and Controls that point to the Policy.", "Record approval and effective dates before changing the status to active."], types: ["policy", "document"], defaultOpen: true }
     ],
     resourceTypes: ["policy", "document"],
     commands: [
@@ -96,44 +82,30 @@ export const PROGRAM_PATH = [
     id: "controls",
     number: 3,
     title: "Implement Controls",
-    description: "Tailor and finish the starter control set",
-    summary: "Review the starter catalog against the scoped service, then give every applicable internal control an actual procedure, owner, system scope, cadence, policy and criteria mappings, authoritative evidence source, and implementation date. Mark it implemented only after the procedure is operating, then record any controls that customers or carved-out providers must perform.",
+    description: "Finish controls and their evidence sources",
+    summary: "Review the starter catalog against the scoped service, then give every applicable internal control an actual procedure, owner, system scope, operation pattern, policy and criteria mappings, and implementation date. Put calendar and event schedules in Obligations. Connect the Control to the exact authoritative Systems that produce its evidence, and complete each source’s role, access ownership, and retrieval instructions before marking the Control implemented. Then record any controls that customers or carved-out providers must perform.",
     sections: [
-      { id: "catalog", title: "Control Catalog", description: "Finish the starter controls, record applicable complementary controls, and see whether filegrc tracks operation through Work Queue or evidence records.", steps: ["Open every planned control and confirm its mappings and suggested frequency.", "Write the real procedure in Record Markdown and add system scope and evidence sources.", "Record any required customer or carved-out provider controls as Complementary Controls."], types: ["control", "complementary-control"], defaultOpen: true }
+      { id: "catalog", title: "Control Catalog", description: "Finish the starter controls and their authoritative evidence sources, record applicable complementary controls, and see whether filegrc tracks operation through Work Queue or evidence records.", steps: ["Open every planned Control and confirm its mappings and operation pattern.", "Write the real procedure in Record Markdown, add system scope, and map the exact authoritative evidence source Systems.", "Create or confirm every calendar and event schedule as an Obligation.", "Confirm each source System is active, has the required evidence role and current access owners, and includes repeatable retrieval instructions in Record Markdown.", "Resolve every incomplete evidence-family check before marking the Controls implemented.", "Record any required customer or carved-out provider controls as Complementary Controls."], types: ["control", "complementary-control"], defaultOpen: true }
     ],
     resourceTypes: ["control", "complementary-control"],
     commands: [
       "filegrc guide control --json",
       "filegrc list control --json",
-      "filegrc get CONTROL_ID --mutation"
-    ]
-  },
-  {
-    id: "evidence",
-    number: 4,
-    title: "Test Evidence Collection",
-    description: "Verify sources before the period starts",
-    summary: "Before starting the candidate period, test external evidence collection only where no dedicated Step 5 operating record exists. When Step 5 already records the work, attach or reference the external artifact there instead of creating a separate test.",
-    sections: [
-      { id: "collection", title: "Collection Test", description: "Test external evidence collection only where no dedicated Step 5 operating record exists.", steps: ["Confirm that each externally evidenced control names an authoritative source System.", "Complete each generated test export or capture.", "When a Step 5 operating record exists, link the artifact’s External Evidence record there instead."], relatedLinks: [{ label: "Source Systems", href: "#/resources/system" }, { label: "Controls", href: "#/resources/control" }], types: ["evidence"], defaultOpen: true }
-    ],
-    resourceTypes: ["evidence"],
-    commands: [
-      "filegrc evidence-test-drafts --preview --json",
-      "filegrc guide evidence --json",
-      "filegrc list evidence --json",
+      "filegrc get CONTROL_ID --mutation",
+      "filegrc evidence-map --json",
       "filegrc program-readiness --json"
     ]
   },
   {
     id: "run",
-    number: 5,
+    number: 4,
     title: "Operate the Program",
     description: "Run the work and retain dated proof",
     summary: "Record the management candidate start date when reliable evidence collection begins. Maintain current risk assessments and risks, updating the control set when needed. Complete recurring and event-driven work, run continuous and per-transaction controls, and keep dated evidence current throughout the period.",
     sections: [
       { id: "risk", title: "Risk", description: "Maintain the program’s risk assessments and risk register as the service, threats, suppliers, and control needs change.", steps: ["Complete and approve risk assessments on schedule and after material changes.", "Record risks that need treatment, acceptance, or ongoing tracking.", "Add or update controls when the assessment identifies a new or changed response."], types: ["risk-assessment", "risk"], defaultOpen: true },
       { id: "queue", title: "Work Queue", description: "Complete recurring work, Policy Event tasks, and assigned follow-up within their required windows.", steps: ["Review proposed work while policies are drafts.", "Complete due work within its allowed window and link dated proof.", "Start Policy Events when hiring, departures, incidents, or material changes occur; every other open Action Item appears here automatically."], types: ["obligation", "obligation-event", "data-request"], utility: "obligation-board", defaultOpen: true },
+      { id: "evidence", title: "External Evidence", description: "Create records only for real exports, reports, screenshots, signed files, or approved external references collected during operation.", steps: ["Create External Evidence when the artifact exists or an operating record needs fixed supporting proof.", "Select the authoritative source System, link the Controls and source operating record, and retain the fixed attachment or approved reference.", "Record the collector and classification, then have another person verify the evidence before audit use."], types: ["evidence"], defaultOpen: true },
       { id: "governance", title: "Governance", description: "Record formal reviews, oversight meetings, and approved policy or control exceptions.", steps: ["Complete scheduled policy reviews and oversight meetings.", "Record decisions, attendees, follow-up work, and evidence.", "Approve time-bound exceptions before the departure begins."], types: ["policy-review", "meeting", "exception"], defaultOpen: false },
       { id: "inventories", title: "Assets and Vendors", description: "Maintain the asset inventory and recurring reviews of supplier relationships during operation.", steps: ["Keep ownership, custody, status, and lifecycle current for important assets.", "Perform vendor reviews on schedule and after material supplier changes.", "Link fixed reports and review evidence to the operating records."], types: ["asset", "vendor-review"], defaultOpen: false },
       { id: "access-training", title: "Access and Training", description: "Inventory service accounts before recording access decisions, periodic reviews, assignments, and acknowledgements.", steps: ["Catalog service accounts that need separate tracking.", "Preserve access approvals and removals as they occur, then complete periodic access reviews and resolve exceptions.", "Assign training and retain acknowledgement evidence for the exact content revision."], types: ["service-account", "access-grant", "access-review", "training", "attestation"], defaultOpen: false },
@@ -147,6 +119,7 @@ export const PROGRAM_PATH = [
       "obligation",
       "obligation-event",
       "data-request",
+      "evidence",
       "policy-review",
       "meeting",
       "exception",
@@ -181,21 +154,21 @@ export const PROGRAM_PATH = [
         instructions: "Complete recurring work, Policy Event tasks, and assigned Action Items within their allowed windows, link the requested dated proof, and resolve overdue items.",
         use: "See proposed, upcoming, due, and overdue policy work together with every open Action Item. Continuous and per-transaction controls still operate in their source Systems and need dated operating records or evidence.",
         policyBasis: "Effective policies and implemented linked controls activate reusable obligations. Policy Events and source records create owned Action Items. Each occurrence or task retains its own deadline, completion record, and evidence.",
-        commands: ["filegrc obligations --json", "filegrc complete OBLIGATION_ID completion-mutation.json --json"]
+        commands: ["filegrc obligations --json", "filegrc complete OBLIGATION_ID completion-mutation.json --expected-revision REVISION --json"]
       }
     ],
     commands: [
       "filegrc obligations --json",
       "filegrc trigger EVENT_TYPE (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) --subject RESOURCE_ID --json",
-      "filegrc complete OBLIGATION_ID completion-mutation.json --json",
-      "filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-on YYYY-MM-DD --json",
-      "filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD --json",
+      "filegrc complete OBLIGATION_ID completion-mutation.json --expected-revision REVISION --json",
+      "filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-on YYYY-MM-DD --expected-revision REVISION --json",
+      "filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD --expected-revision REVISION --json",
       "filegrc program-readiness --json"
     ]
   },
   {
     id: "audit",
-    number: 6,
+    number: 5,
     title: "Audit",
     description: "Firm, formal period, fieldwork, and report",
     summary: "After the program is collecting reliable evidence, create an Audit record for the real CPA engagement, keep the firm-agreed report period separate from management’s candidate dates, complete management documents, populations, requests, evidence delivery, and fieldwork, then preserve the findings, responses, opinion, and final report.",