create-filegrc 0.3.4 → 0.5.0

package/template/data/audits/AGENTS.md

@@ -17,7 +17,7 @@ Preparation creates engagement-specific management documents and, for Type 2, po
 
 Review both evidence paths for the exact formal date or period:
 
-1. filegrc Evidence consists of dated Step 5 operating records. Complete the record, link it to the applicable Controls, record the result in its fields or Markdown, and link any external artifact needed to support that result.
+1. filegrc Evidence consists of dated Step 4 operating records. Complete the record, link it to the applicable Controls, record the result in its fields or Markdown, and link any external artifact needed to support that result.
 2. External Evidence consists of verified `evidence` records from other Systems. Confirm the source System, date or period, Control links, collector, verifier, and fixed attachment or approved external reference.
 
 The packet compiles both paths. It includes filegrc records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.

package/template/data/collection-reviews/collection-review-complementary-control.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-complementary-control",
+  "type": "collection-review",
+  "title": "Customer and provider responsibilities review",
+  "status": "planned",
+  "resourceType": "complementary-control",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/collection-reviews/collection-review-framework.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-framework",
+  "type": "collection-review",
+  "title": "Framework and criteria sources review",
+  "status": "planned",
+  "resourceType": "framework",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/collection-reviews/collection-review-person.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-person",
+  "type": "collection-review",
+  "title": "Program participants review",
+  "status": "planned",
+  "resourceType": "person",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/collection-reviews/collection-review-system.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-system",
+  "type": "collection-review",
+  "title": "Service and system boundary review",
+  "status": "planned",
+  "resourceType": "system",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/collection-reviews/collection-review-vendor.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-vendor",
+  "type": "collection-review",
+  "title": "Vendor and subservice scope review",
+  "status": "planned",
+  "resourceType": "vendor",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/documents/document-business-continuity-disaster-recovery.json

@@ -1,21 +1,17 @@
 {
-  "schemaVersion": 1,
   "id": "document-business-continuity-disaster-recovery",
   "type": "document",
   "title": "Business Continuity and Disaster Recovery Plan",
   "status": "draft",
   "documentKind": "plan",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["employees", "contractors"],
+  "audience": [
+    "employees",
+    "contractors"
+  ],
   "acknowledgementRequired": true,
   "controlIds": [
     "control-policy-management",
@@ -23,6 +19,11 @@
     "control-backup-restoration",
     "control-continuity-exercise"
   ],
-  "relatedDocumentIds": ["document-incident-response-plan"],
-  "evidenceIds": []
+  "relatedDocumentIds": [
+    "document-incident-response-plan"
+  ],
+  "evidenceIds": [],
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "required"
 }

package/template/data/documents/document-business-continuity-disaster-recovery.md

@@ -31,9 +31,11 @@ During a disruption, {{company_name}} will:
 
 ## Roles
 
+These names describe recovery functions, not required job titles or separate Appointments. The current Policy Owner performs them by default and management delegates a function only when that matches how the organization actually recovers its services.
+
 ### Policy owner
 
-{{policy_owner_name}} owns this plan and keeps it current. The policy owner may delegate response duties but remains accountable for the plan.
+The current Policy Owner owns this plan and keeps it current. The Policy Owner may delegate response duties but remains accountable for the plan.
 
 ### Security and risk oversight
 

package/template/data/documents/document-contractor-policy-acknowledgement.json

@@ -1,20 +1,20 @@
 {
-  "schemaVersion": 1,
   "id": "document-contractor-policy-acknowledgement",
   "type": "document",
   "title": "Contractor Policy Acknowledgement",
   "status": "draft",
   "documentKind": "attestation-template",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["contractors"],
-  "controlIds": ["control-workforce-expectations"]
+  "audience": [
+    "contractors"
+  ],
+  "controlIds": [
+    "control-workforce-expectations"
+  ],
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

package/template/data/documents/document-contractor-training-acknowledgement.json

@@ -1,21 +1,23 @@
 {
-  "schemaVersion": 1,
   "id": "document-contractor-training-acknowledgement",
   "type": "document",
   "title": "Contractor Training Acknowledgement",
   "status": "draft",
   "documentKind": "attestation-template",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["contractors"],
-  "controlIds": ["control-security-training"],
-  "relatedResourceIds": ["training-security-awareness"]
+  "audience": [
+    "contractors"
+  ],
+  "controlIds": [
+    "control-security-training"
+  ],
+  "trainingIds": [
+    "training-security-awareness"
+  ],
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

package/template/data/documents/document-data-retention-schedule.json

@@ -1,24 +1,23 @@
 {
-  "schemaVersion": 1,
   "id": "document-data-retention-schedule",
   "type": "document",
   "title": "Data Retention Schedule",
   "status": "draft",
   "documentKind": "schedule",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["data-owners", "system-owners"],
+  "audience": [
+    "data-owners",
+    "system-owners"
+  ],
   "acknowledgementRequired": false,
   "controlIds": [
     "control-data-classification-inventory",
     "control-data-retention-disposal"
-  ]
+  ],
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

package/template/data/documents/document-employee-handbook-acknowledgement.json

@@ -1,20 +1,20 @@
 {
-  "schemaVersion": 1,
   "id": "document-employee-handbook-acknowledgement",
   "type": "document",
   "title": "Employee Handbook Acknowledgement",
   "status": "draft",
   "documentKind": "attestation-template",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["employees"],
-  "controlIds": ["control-workforce-expectations"]
+  "audience": [
+    "employees"
+  ],
+  "controlIds": [
+    "control-workforce-expectations"
+  ],
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

package/template/data/documents/document-employee-policy-acknowledgement.json

@@ -1,20 +1,20 @@
 {
-  "schemaVersion": 1,
   "id": "document-employee-policy-acknowledgement",
   "type": "document",
   "title": "Employee Policy Acknowledgement",
   "status": "draft",
   "documentKind": "attestation-template",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["employees"],
-  "controlIds": ["control-workforce-expectations"]
+  "audience": [
+    "employees"
+  ],
+  "controlIds": [
+    "control-workforce-expectations"
+  ],
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

package/template/data/documents/document-employee-training-acknowledgement.json

@@ -1,21 +1,23 @@
 {
-  "schemaVersion": 1,
   "id": "document-employee-training-acknowledgement",
   "type": "document",
   "title": "Employee Training Acknowledgement",
   "status": "draft",
   "documentKind": "attestation-template",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["employees"],
-  "controlIds": ["control-security-training"],
-  "relatedResourceIds": ["training-security-awareness"]
+  "audience": [
+    "employees"
+  ],
+  "controlIds": [
+    "control-security-training"
+  ],
+  "trainingIds": [
+    "training-security-awareness"
+  ],
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

package/template/data/documents/document-incident-response-plan.json

@@ -1,21 +1,17 @@
 {
-  "schemaVersion": 1,
   "id": "document-incident-response-plan",
   "type": "document",
   "title": "Incident Response Plan",
   "status": "draft",
   "documentKind": "plan",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["employees", "contractors"],
+  "audience": [
+    "employees",
+    "contractors"
+  ],
   "acknowledgementRequired": false,
   "controlIds": [
     "control-security-communication",
@@ -23,6 +19,11 @@
     "control-incident-response",
     "control-incident-exercise"
   ],
-  "relatedDocumentIds": ["document-business-continuity-disaster-recovery"],
-  "evidenceIds": []
+  "relatedDocumentIds": [
+    "document-business-continuity-disaster-recovery"
+  ],
+  "evidenceIds": [],
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "required"
 }

package/template/data/documents/document-incident-response-plan.md

@@ -8,7 +8,7 @@ This plan defines how {{company_name}} identifies, declares, contains, investiga
 
 This plan applies to suspected or confirmed events affecting company or customer systems, data, identities, devices, facilities, vendors, or business operations. Availability disruptions may also activate the Business Continuity and Disaster Recovery Plan.
 
-Questions and incident reports should be sent immediately to {{security_contact_email}}. If that route is unavailable or may be compromised, contact {{policy_owner_name}} through a known alternate channel.
+Questions and incident reports should be sent immediately to {{security_contact_email}}. If that route is unavailable or may be compromised, contact the current Policy Owner through a known alternate channel.
 
 ## Definitions
 
@@ -41,13 +41,15 @@ Severity considers affected data, systems, customers, privileges, duration, spre
 
 ## Roles and authority
 
+These names describe response functions, not required job titles or separate Appointments. The current Policy Owner performs them by default and management delegates a function only when that matches how the organization actually responds.
+
 ### Reporter
 
 Anyone may report a suspected incident. Reporters preserve available evidence, stop unsafe activity when they can do so safely, and follow response instructions. They do not need proof before reporting.
 
 ### Incident lead
 
-The incident lead declares the incident, assigns severity, coordinates work, maintains the incident record, approves status changes, and decides when the incident is contained and closed. {{policy_owner_name}} acts as incident lead until another qualified person is assigned.
+The incident lead declares the incident, assigns severity, coordinates work, maintains the incident record, approves status changes, and decides when the incident is contained and closed. The current Policy Owner acts as incident lead until another qualified person is assigned.
 
 ### Technical responders
 

package/template/data/documents/document-soc2-management-assertion.json

@@ -1,5 +1,4 @@
 {
-  "schemaVersion": 1,
   "id": "document-soc2-management-assertion",
   "type": "document",
   "title": "SOC 2 Management Assertion",
@@ -7,8 +6,9 @@
   "documentKind": "soc2-management-assertion",
   "template": true,
   "ownerIds": [
-    "person-policy-owner"
+    "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classification": "Confidential"
+  "classificationId": "confidential",
+  "programRole": "required"
 }

package/template/data/documents/document-soc2-management-representation.json

@@ -1,5 +1,4 @@
 {
-  "schemaVersion": 1,
   "id": "document-soc2-management-representation",
   "type": "document",
   "title": "SOC 2 Management Representation Letter",
@@ -7,8 +6,9 @@
   "documentKind": "soc2-management-representation",
   "template": true,
   "ownerIds": [
-    "person-policy-owner"
+    "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classification": "Confidential"
+  "classificationId": "confidential",
+  "programRole": "required"
 }

package/template/data/documents/document-soc2-period-completeness.json

@@ -1,5 +1,4 @@
 {
-  "schemaVersion": 1,
   "id": "document-soc2-period-completeness",
   "type": "document",
   "title": "SOC 2 Period Completeness Statement",
@@ -7,8 +6,9 @@
   "documentKind": "soc2-period-completeness",
   "template": true,
   "ownerIds": [
-    "person-policy-owner"
+    "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classification": "Confidential"
+  "classificationId": "confidential",
+  "programRole": "conditional"
 }

package/template/data/documents/document-soc2-system-description.json

@@ -1,5 +1,4 @@
 {
-  "schemaVersion": 1,
   "id": "document-soc2-system-description",
   "type": "document",
   "title": "SOC 2 System Description",
@@ -7,8 +6,9 @@
   "documentKind": "soc2-system-description",
   "template": true,
   "ownerIds": [
-    "person-policy-owner"
+    "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classification": "Internal"
+  "classificationId": "internal",
+  "programRole": "required"
 }

package/template/data/evidence/AGENTS.md

@@ -2,7 +2,7 @@
 
 An evidence record explains what a proof item is, where it came from, what period it supports, who collected it, and which records or controls it supports. The attachment alone is not enough.
 
-Onboarding does not create collection tests. After confirming applicable controls and authoritative source Systems, preview proposed tests with `npx filegrc evidence-test-drafts --preview --json`, then explicitly create the missing drafts. Risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings do not need a separate test. When one of those operating records needs a fixed external artifact, create or update an External Evidence record for the artifact and link its ID from the operating record. Keep a created collection test as `draft` until the artifact has actually been captured. Set it to `collected` only after selecting the source System, attaching or referencing the result, and recording the source, date, classification, and collector. Set it to `verified` only after another named person checks it.
+Do not create placeholder or collection-test Evidence. Control implementation maps Controls to complete authoritative Systems; `npx filegrc evidence-map --json` remains available as a focused diagnostic. Create External Evidence during Step 4 only when a real export, report, screenshot, signed file, or approved external reference exists. When an operating record needs fixed supporting proof, create or update an External Evidence record and link its ID from that record. Keep new evidence as `draft` until the artifact exists. Set it to `collected` only after selecting the source System, attaching or referencing the result, and recording the source, date, classification, and collector. Set it to `verified` only after another named person checks it.
 
 ## Create evidence
 
@@ -16,12 +16,12 @@ Onboarding does not create collection tests. After confirming applicable control
 Copy a local fixed file and update the record atomically:
 
 ```sh
-npx filegrc attach EVIDENCE_ID /path/to/source-file --name auditor-facing-name.csv
+npx filegrc attach EVIDENCE_ID /path/to/source-file --name auditor-facing-name.csv --expected-revision REVISION
 ```
 
 The command never overwrites an existing attachment.
 
-Use `npx filegrc detach EVIDENCE_ID FILE_NAME --yes` when removing a mistaken attachment. filegrc will not delete an evidence record while local attachments remain.
+Read `REVISION` from `npx filegrc get EVIDENCE_ID --mutation`. Use `npx filegrc detach EVIDENCE_ID FILE_NAME --yes --expected-revision REVISION` when removing a mistaken attachment. filegrc will not delete an evidence record while local attachments remain.
 
 For a rendered page capture, record the route, filters, audit period, exact Git commit, capture time and method, source resource IDs, and screenshot. A current screenshot cannot prove an earlier state unless it is rendered from or bound to that revision.
 

package/template/data/obligation-events/AGENTS.md

@@ -12,7 +12,7 @@ The obligations output lists every task the trigger will add, with its owner, de
 Complete each action with the requested resource type and proof. Then close the workflow:
 
 ```sh
-npx filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD
+npx filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD --expected-revision REVISION
 ```
 
-filegrc refuses to close an event with unfinished or unproved actions. Cancel an event only when the triggering event itself was entered in error or did not occur; explain the reason in related records or the commit message.
+Read `REVISION` from `npx filegrc get OBLIGATION_EVENT_ID --mutation`. filegrc refuses to close an event with unfinished or unproved actions. Cancel an event only when the triggering event itself was entered in error or did not occur; explain the reason in related records or the commit message.

package/template/data/obligations/AGENTS.md

@@ -9,4 +9,4 @@ An obligation is a reusable policy schedule or event template. It is not the rec
 - When an approved cadence changes, update the policy, control, and obligation together.
 - Pause or retire a template only when the underlying policy work no longer applies. Do not delete historical templates that explain prior periods.
 
-Use `npx filegrc obligations --json` to inspect calculated recurring work and preview every Policy Event task, owner, deadline, and requested proof. Use `npx filegrc complete OBLIGATION_ID completion-mutation.json` to create and link a dated occurrence in one validated write. Use `npx filegrc trigger EVENT_TYPE ...` only after the matching event occurs; it adds all configured Action Items to the Work Queue atomically.
+Use `npx filegrc obligations --json` to inspect calculated recurring work and preview every Policy Event task, owner, deadline, and requested proof. Run `npx filegrc complete OBLIGATION_ID --scaffold --window-start YYYY-MM-DD --completed-on YYYY-MM-DD > completion-mutation.json`, fill the actual work and proof, then pass that file to `npx filegrc complete OBLIGATION_ID completion-mutation.json`. The scaffold includes the current Obligation revision, and the final command creates and links the dated occurrence in one validated write. Use `npx filegrc trigger EVENT_TYPE ...` only after the matching event occurs; it adds all configured Action Items to the Work Queue atomically.

package/template/data/people/person-program-lead.json

@@ -0,0 +1,9 @@
+{
+  "id": "person-program-lead",
+  "type": "person",
+  "title": "{{policy_owner_name}}",
+  "status": "active",
+  "email": "{{policy_owner_email}}",
+  "jobTitle": "{{policy_owner_job_title}}",
+  "affiliation": "internal"
+}

package/template/data/policies/AGENTS.md

@@ -4,7 +4,7 @@ Policies state required behavior. Controls, obligations, training, attestations,
 
 Use the `content` Markdown slot for the policy text. Keep ownership and approval metadata in JSON. The approver must be separate from the owner, including through team membership. The reviewer will usually be another leader or manager in the organization, but may be external.
 
-Keep a policy `draft` until its text, owner, scope, related requirements and controls, approval, effective date, review cadence, and acknowledgement requirement match actual practice. When activating it:
+Keep a policy `draft` until its text, owner, scope, related requirements and controls, approval, effective date, review Obligation, and acknowledgement requirement match actual practice. When activating it:
 
 1. Record the real approver and approval date.
 2. Set the effective date.

package/template/data/policies/policy-anti-bribery-corruption.json

@@ -1,24 +1,19 @@
 {
-  "schemaVersion": 1,
   "id": "policy-anti-bribery-corruption",
   "type": "policy",
   "title": "Anti-Bribery and Corruption Policy",
   "status": "draft",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "policyKind": "corporate-conduct",
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "audience": ["employees", "contractors", "agents"],
+  "audience": [
+    "employees",
+    "contractors",
+    "agents"
+  ],
   "acknowledgementRequired": true,
-  "controlIds": [
-    "control-security-governance",
-    "control-policy-management",
-    "control-workforce-expectations"
-  ]
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

package/template/data/policies/policy-anti-bribery-corruption.md

@@ -70,7 +70,7 @@ Transactions must be recorded promptly, accurately, and with enough detail to ex
 
 ## Reporting
 
-Report questions, suspected violations, requests for improper payments, or inaccurate records to {{policy_owner_name}} at {{security_contact_email}}. Reports may be made without first notifying a manager.
+Report questions, suspected violations, requests for improper payments, or inaccurate records to the current Policy Owner at {{security_contact_email}}. Reports may be made without first notifying a manager.
 
 {{company_name}} prohibits retaliation against anyone who reports a concern or participates in an investigation in good faith.
 

package/template/data/policies/policy-clear-desk-screen.json

@@ -1,23 +1,18 @@
 {
-  "schemaVersion": 1,
   "id": "policy-clear-desk-screen",
   "type": "policy",
   "title": "Clear Desk and Clear Screen Policy",
   "status": "draft",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "policyKind": "information-security",
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "audience": ["employees", "contractors"],
+  "audience": [
+    "employees",
+    "contractors"
+  ],
   "acknowledgementRequired": true,
-  "controlIds": [
-    "control-policy-management",
-    "control-physical-workspace-security"
-  ]
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "alternative"
 }