create-filegrc 0.6.4 → 0.7.0

package/template/README.md

@@ -40,12 +40,16 @@ Detached and feature-branch checkouts are read-only in the browser by default. D
 ![filegrc SOC 2 program overview](docs/filegrc-home.png)
 
 1. **Define scope.** Set program ownership, choose the criteria, and define the service, Systems, and providers in scope.
-2. **Approve policies.** Turn the starter policy set into approved rules that match how the organization works.
-3. **Implement controls.** Define how each control works, where its evidence comes from, and whether customers or providers have responsibilities.
+2. **Approve policies.** Tailor the Policy, then have someone other than its owner approve the exact content. Approval does not mean the linked Controls are implemented.
+3. **Implement controls.** Define how each Control works, where its Evidence comes from, enable its schedules, and complete governed plans. Then review the approved Policies together and activate the selected cutover set.
 4. **Operate the program.** Run scheduled and event-driven work, maintain risk, and retain dated evidence.
 5. **Audit.** Set up the CPA engagement, support fieldwork, and prepare the evidence packet.
 
-Control implementation includes evidence-source readiness. Use `npx filegrc program-readiness --json` to find incomplete Control or Component records. `npx filegrc evidence-map --json` remains available as a focused diagnostic. Create an Evidence Artifact during Step 4 only when a real export, report, screenshot, signed file, or approved external reference exists.
+A Policy says what the company commits to do by the date it takes effect. Approval means the company accepts those commitments. It does not prove the work is done. Controls and operating records describe how the company meets them and provide the proof.
+
+FileGRC does not infer technical implementation from Policy prose. Configuration facts belong in Controls, Components, Systems, governed schedules, and Evidence. A Control may be implemented while its governing Policy is approved but inactive. Enabled Obligations remain dormant until the Policy is active and effective.
+
+Control implementation includes evidence-source and schedule readiness. Use `npx filegrc program-readiness --json` to review incomplete Control or Component records and each per-Policy activation assessment. At the end of Step 3, use the Controls-page review or `npx filegrc activate-policies --scaffold` to choose which approved Policies take effect. You can activate with a documented gap or approved Exception, but Evidence Readiness still requires active Policies, implemented Controls, configured evidence sources, and enabled schedules before the candidate period can begin. `npx filegrc evidence-map --json` remains available as a focused diagnostic. Create an Evidence Artifact during Step 4 only when a real export, report, screenshot, signed file, or approved external reference exists.
 
 The Program Overview shows what is done, what is blocked, and what to do next.
 
@@ -53,14 +57,14 @@ The Program Overview shows what is done, what is blocked, and what to do next.
 
 - **Work Queue** turns policy schedules and follow-up into upcoming, blocked, due, and overdue work, with named blockers when a task cannot proceed.
 - **Policy Events** create the right tasks for hiring, departures, incidents, vendor changes, and other events.
-- **Program Readiness** checks whether management can begin a reliable evidence period.
+- **Program Readiness** checks whether you can begin a reliable evidence period.
 - **Period Health** checks role, policy, control, source, obligation, and Git-history continuity across candidate and formal Type 2 dates.
 - **Audit Readiness** checks the engagement, period, documents, evidence, and Type 2 populations.
 - **Evidence packets** collect the scoped records, attachments, history, indexes, and checksums for delivery.
 
 ![filegrc audit readiness](docs/filegrc-audit.png)
 
-Starter records connect policies, controls, owners, systems, evidence, and schedules. They are proposals, so review them against how your company actually works before approval.
+The Security starter is intentionally small: one Information Security Policy, one Security Incident and Recovery Plan, one focused Data Retention Schedule, one Security Awareness Training record, and the Controls and Obligations needed for the Security common criteria. They are proposals, so review them against how your company actually works. Suggested retention periods and schedule cadences are starting points, not adopted requirements. Add Privacy, Confidentiality, Availability, Processing Integrity, employment, anti-bribery, or other broader GRC material only when the company chooses to expand the scope.
 
 ## Built for engineers and agents
 

package/template/data/AGENTS.md

@@ -116,6 +116,8 @@ Status is an assertion. Before moving a record to a completed, approved, impleme
 
 Do not mark a control implemented because a policy says it should exist. Do not mark evidence verified because it was merely collected. Do not mark a task done without the completion record type requested by its obligation.
 
+Policy approval accepts the reviewed requirements. It does not prove implementation or start governed work. A Control may be implemented while its governing Policy is approved but inactive. Enable its schedules during implementation. At the end of Step 3, run `activate-policies --scaffold`, review the approved Policies together, select the cutover set, and record the real effective date. FileGRC does not infer technical implementation from Policy prose, so put configuration facts in Controls, Components, Systems, governed schedules, and Evidence.
+
 ## Delete and replace
 
 Before deletion:
@@ -169,14 +171,15 @@ Finish each applicable Control and its authoritative source Components together.
 npx filegrc program-readiness --json
 ```
 
-The Control stage reports both Control implementation items and evidence-family source checks. Resolve them through the source records:
+The Control stage reports Control implementation items, evidence-family source checks, governed-plan blockers, and per-Policy activation assessments. Resolve them through the source records:
 
 1. Choose an existing System or scaffold the System that is authoritative for the family.
 2. Set the System to `active`, add the matching `evidenceSourceKinds`, and name current `evidenceOwnerIds`.
 3. Put the exact report, filters, date range, timezone, export format, and reconciliation steps in the System’s Record Markdown.
 4. Add the Component ID to `evidenceSourceComponentIds` on every Control in the family that it supports.
 5. Finish the Control’s owner, procedure, scope, operation pattern, mappings, and implementation date. Put every calendar or event schedule in an Obligation.
-6. Run `program-readiness --json` again and resolve every failed Control or source check before marking the Controls implemented or starting the candidate period.
+6. Enable each required Obligation. It stays dormant while a governing Policy is inactive.
+7. Run `program-readiness --json`, then use `activate-policies --scaffold` to review and atomically activate the selected approved Policies at implementation cutover. A documented gap or approved Exception may support activation, but the candidate period cannot start until Policies are active and Controls are fully implemented and evidence-ready.
 
 Use `get RESOURCE_ID --mutation` and `update` so JSON and Markdown change together. `evidence-map --json` remains available when you want only the evidence-family checks. Do not create an Evidence Artifact while designing or implementing a Control. Create one during Step 4 only when the real export, report, screenshot, signed file, or approved external reference exists.
 
@@ -203,7 +206,7 @@ npx filegrc audit-readiness AUDIT_ID --json
 npx filegrc evidence-packet --audit AUDIT_ID --preview --json
 ```
 
-Run Program Readiness before creating the normal audit engagement. It checks scope, effective policies, implemented controls, and evidence mapping without an audit ID. Fix readiness errors in the Control and System records. Do not edit packet output under `.filegrc/`. A delivery-ready filegrc packet means the management checks passed; the engagement team still judges evidence and performs the examination.
+Run Program Readiness before creating the normal audit engagement. Step 2 checks independent Policy approval without requiring activation. Evidence Readiness separately checks active Policies, implemented Controls, enabled schedules, and evidence mapping without an audit ID. Fix readiness errors in Policy, Control, Component, System, governed schedule, and Evidence records. Do not edit packet output under `.filegrc/`. A delivery-ready filegrc packet means the management checks passed; the engagement team still judges evidence and performs the examination.
 
 ## Finish every change
 

package/template/data/appointments/appointment-policy-owner.json

@@ -7,5 +7,5 @@
   "holderId": "person-program-lead",
   "scopeResourceIds": ["workspace"],
   "startsOn": "{{effective_date}}",
-  "responsibilities": "Own the information security program and the starter policies, controls, documents, training, and scheduled work until management assigns more specific accountable parties."
+  "responsibilities": "Own the information security program, its Policy, Controls, governed documents, training, and scheduled work until management assigns more specific accountable parties."
 }

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

@@ -19,5 +19,5 @@
   ],
   "classificationId": "internal",
   "proposedEffectiveOn": "{{effective_date}}",
-  "programRole": "conditional"
+  "programRole": "required"
 }

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

@@ -10,15 +10,13 @@ Retention periods may come from law, contract, tax, audit, security, or a docume
 
 | Record class | System or location | Owner | Trigger | Retention | End-of-period action | Authority or reason |
 | --- | --- | --- | --- | --- | --- | --- |
-| Security logs for important systems | Complete before approval | Complete before approval | Log event | At least 12 months | Delete through the approved system lifecycle | Information Security Policy |
-| Important production backups | Complete before approval | Complete before approval | Backup creation | At least 30 days | Expire through the protected backup cycle | Information Security Policy |
-| SOC 2 policies, control records, and audit evidence | Git repository and approved evidence locations | Policy owner | End of the relevant audit period | Complete before approval based on audit, contract, and legal needs | Archive or securely delete | Audit and business requirements |
-| Customer and service records | Complete before approval | Complete before approval | Complete before approval | Complete before approval | Delete or anonymize | Contract, law, and business need |
-| Workforce and contractor records | Approved people or payroll system | Complete before approval | End of employment or services | Complete before approval | Securely delete | Employment, tax, and legal requirements |
-| Vendor and contract records | Complete before approval | Complete before approval | End of relationship or contract | Complete before approval | Securely delete | Contract, audit, and legal requirements |
-| Incident and investigation records | Approved incident and evidence systems | Incident owner | Incident closure | Complete before approval | Archive or securely delete | Legal, insurance, contract, and security needs |
-
-Add rows for each important data class in the system and vendor inventories. A row is incomplete until it names the source system, owner, trigger, period, disposal action, and authority.
+| Security logs for important Systems | [Complete before approval: Systems or Components] | [Complete before approval: owner] | Log event | [Confirm or replace proposed default before approval: 12 months, adjusted for investigation, contract, legal, audit, and risk needs] | [Complete before approval: disposal action] | [Complete before approval: authority or reason] |
+| Production backups or alternate recovery copies | [Complete before approval: Systems or Components] | [Complete before approval: owner] | Backup or recovery-copy creation | [Confirm or replace proposed default before approval: 30 days, adjusted to approved System recovery objectives] | [Complete before approval: expiration or disposal action] | [Complete before approval: continuity objective or risk decision] |
+| SOC 2 Policies, Control records, and audit Evidence | Git repository and approved Evidence locations | Policy owner | End of the relevant audit period | [Complete before approval based on audit, contract, and legal needs] | Archive or securely delete | Audit and business requirements |
+| Customer and service records | [Complete before approval: Systems or Components] | [Complete before approval: owner] | [Complete before approval: trigger] | [Complete before approval: retention] | Delete or anonymize | Contract, law, and business need |
+| Incident and investigation records | Approved incident and Evidence Systems | Incident owner | Incident closure | [Complete before approval: retention] | Archive or securely delete | Legal, insurance, contract, and security needs |
+
+Add rows for each important data class in the System and Vendor inventories. A row is incomplete until it names the source System or Component, owner, trigger, period, disposal action, and authority. FileGRC detects the bracketed prompts as approval blockers. Remove each prompt only after replacing it with a reviewed fact.
 
 ## Holds and exceptions
 

package/template/data/documents/{document-incident-response-plan.json → document-security-incident-recovery-plan.json}

@@ -1,7 +1,7 @@
 {
-  "id": "document-incident-response-plan",
+  "id": "document-security-incident-recovery-plan",
   "type": "document",
-  "title": "Incident Response Plan",
+  "title": "Security Incident and Recovery Plan",
   "status": "draft",
   "documentKind": "plan",
   "ownerIds": [
@@ -17,10 +17,9 @@
     "control-security-communication",
     "control-logging-monitoring",
     "control-incident-response",
-    "control-incident-exercise"
-  ],
-  "relatedDocumentIds": [
-    "document-business-continuity-disaster-recovery"
+    "control-incident-exercise",
+    "control-backup-restoration",
+    "control-continuity-exercise"
   ],
   "evidenceIds": [],
   "classificationId": "internal",

package/template/data/documents/document-security-incident-recovery-plan.md

@@ -0,0 +1,79 @@
+# Security Incident and Recovery Plan
+
+## Purpose
+
+This plan coordinates reporting, response, recovery, and continuity when a security event or disruption affects {{company_name}} or an in-scope service. Controls, Components, Systems, Obligations, and Evidence hold the actual technical configuration and proof of operation.
+
+## Reporting routes
+
+The primary reporting route is {{security_contact_email}}.
+
+[Complete before activation: Name a usable alternate reporting route, its owner, protected location, and how workers can find it when the primary email, identity, or collaboration System is unavailable, compromised, or involved in the concern. Do not put secrets in this plan.]
+
+Reports may describe suspected unauthorized access, malware, data loss, credential exposure, security-Control failure, service disruption, fraud affecting the service, or another policy violation. The recipient records the report, protects confidentiality, preserves relevant information, and assigns an initial owner.
+
+## Roles and authority
+
+The Policy Owner maintains this plan and ensures that the organization assigns these duties before activation:
+
+- Incident lead with authority to declare, coordinate, escalate, and close an incident
+- Technical recovery lead for containment, restoration, validation, and rollback
+- System owners for impact assessment, dependencies, and recovery priorities
+- Executive decision-maker for major business, customer, insurance, or legal decisions
+- Communication owner for workforce, customer, Vendor, and public messages
+
+If an incident raises a legal, privacy, or insurance question, the incident lead gets suitable advice at that time. FileGRC does not require pre-arranged counsel, in-house counsel, or a standing legal retainer.
+
+[Complete before activation: Record the emergency contact arrangement, its owner, alternate communication channel, protected storage location, and review schedule.]
+
+## Assessment and declaration
+
+The incident lead records the affected service, Systems, Components, data, customers, Vendors, known timeline, current impact, likely impact, and available Evidence. Severity and declaration use the approved criteria in the Incident Response Control.
+
+A material incident includes one that causes or is likely to cause significant failure of a service commitment or System requirement, material unauthorized access or disclosure, sustained loss of an important service, or a notification duty requiring leadership review.
+
+## Response
+
+The incident team:
+
+1. Records and assesses the report.
+2. Contains the event while preserving Evidence.
+3. Removes or isolates the cause.
+4. Restores affected service through approved recovery procedures.
+5. Validates security and service behavior before normal operation resumes.
+6. Coordinates any legal, contractual, privacy, insurance, customer, or regulatory review the incident actually requires.
+7. Communicates through authorized primary or alternate channels.
+8. Records decisions, Exceptions, remaining risk, lessons, and follow-up work.
+
+The team does not destroy Evidence, promise external notification, or make public statements without the assigned authority. The notification decision records the triggering law, contract, Policy, commitment, or management decision and the facts used.
+
+## Recovery priorities and procedures
+
+[Complete before activation: Link every important System and record its approved recovery time objective, recovery point objective, maximum tolerable downtime, dependencies, owner, and critical customer commitments in the System record.]
+
+For each important System, the applicable Control, Component, System, and Obligation records must identify:
+
+- The backup or alternate recovery approach
+- Scope, frequency, retention, monitoring, and failure response
+- Recovery and restoration procedure
+- People who can access the procedure and required Systems
+- Restore-validation method and governed schedule
+- Dependencies, fallback paths, and validation steps
+
+[Confirm or replace before activation: The starter proposal for important production data is a daily backup, 30-day retention period, and annual restore validation. Record the approved choice for every important System in its Control, Component, System, Retention Schedule, and Obligation records.]
+
+If no approved objective or procedure exists during an event, the incident lead records an interim decision based on customer impact, data risk, and dependencies, then assigns the missing permanent decision as follow-up work.
+
+## Alternate plan access
+
+[Complete before activation: Record the protected alternate location and access method responders will use when the primary identity, source-control, or collaboration Systems are unavailable. Confirm that authorized responders can retrieve the plan without exposing secrets.]
+
+## Closure and follow-up
+
+The incident lead closes the incident only after affected Systems are stable, security validation is complete, Evidence is preserved, required communication decisions are recorded, and remaining work has owners and deadlines. Material incidents receive a retrospective within the approved event window.
+
+## Exercises and maintenance
+
+Management tests a representative security alert from generation through receipt, acknowledgement, escalation, and fallback on the approved governed schedule. It also exercises incident coordination, alternate plan access, emergency contacts, and recovery of selected important Systems on their approved schedules.
+
+Each exercise records scope, participants, objectives, result, Evidence, Exceptions, findings, and follow-up. The owner reviews this plan after a material incident, failed exercise, important System change, or reporting-path change and on the approved Policy-review schedule.

package/template/data/obligations/AGENTS.md

@@ -5,7 +5,8 @@ An obligation is a reusable policy schedule or event template. It is not the rec
 - Calendar obligations need a valid recurrence anchor, owners, expected completion types, and policy or control links.
 - Event obligations need a stable lowercase `eventType`, a prompt, owners, expected completion types, and an explicit deadline window.
 - Keep completed occurrences in `completionResourceIds`. Do not replace prior links when a new period starts.
-- Keep starter obligations as proposals until every governing policy is active and effective and, when the obligation names controls, at least one linked control is implemented.
+- Configure and enable Obligations during Step 3. An enabled Obligation remains dormant until every governing Policy is active and effective and, when it names Controls, at least one linked Control is implemented.
+- Calendar Obligations generated with `status: proposed` contain suggested starting cadences. Review the scope and risk, edit the cadence when needed, and change the Obligation to `active` only when management accepts that schedule. A proposed Obligation never counts as a configured schedule.
 - 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.
 

package/template/data/policies/AGENTS.md

@@ -1,17 +1,27 @@
 # Policy Instructions
 
-Policies state required behavior. Controls, obligations, training, attestations, and evidence show how the organization applies that behavior.
+A Policy says what the company commits to do by the date it takes effect. Approval means the company accepts those commitments. It does not prove the work is done. Controls and operating records describe how the company meets them and provide the proof.
+
+FileGRC does not infer technical implementation from Policy prose. Put configuration facts in Controls, Components, Systems, governed schedules, and Evidence.
+
+Keep durable mandatory outcomes in Policy prose. Put adjustable values such as retention periods, scan cadence, recovery frequency, and review windows in the linked Control, System, Document schedule, or Obligation. Starter values are proposals: management must confirm or replace each value before it counts as configured.
 
 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 Obligation, and acknowledgement requirement match actual practice. When activating it:
+Keep a Policy `draft` until its text, owner, scope, related Requirements and Controls, review Obligation, and acknowledgement requirement are ready for independent review. Move it to `approved` when management accepts the exact content revision. Approval does not require every linked Control to be implemented and does not make the Policy effective.
+
+The Security starter contains one Information Security Policy. Add another Policy only when management expands the program scope or has a distinct approval audience, owner, or legal requirement.
+
+During Step 3, implement Controls while the governing Policy is approved but inactive. Configure and enable its schedules, which remain dormant. Use the Controls-page cutover or `activate-policies --scaffold` to review the approved Policy. Before selecting it for activation:
+
+1. Review the per-Policy activation assessment.
+2. Review linked Controls that are planned or partial, missing Components or evidence sources, missing schedules, and unresolved Exceptions.
+3. Complete required governed plans and assign Training or Attestations.
+4. Set the real effective date and change the approved Policy to `active` at implementation cutover.
+5. If management activates with a known gap, document the decision, follow-up, and any time-bound Exception. Activation does not mark a Control implemented, and Evidence Readiness still requires active and operating Policies.
 
-1. Record the real approver and approval date.
-2. Set the effective date.
-3. Link the controls and requirements it supports.
-4. Update or create its recurring and event obligations.
-5. Assign training or attestations when the policy requires them.
+The independent Policy approver is a management reviewer, not the CPA auditor. Appoint the reviewer during Policy approval. Enabled recurring and event Obligations remain dormant until every governing Policy is active and effective and, when they name Controls, at least one linked Control is implemented.
 
-The independent policy approver is a management reviewer, not the CPA auditor. Appoint the reviewer during policy adoption. Recurring and event obligations linked to the policy remain proposals until the policy is active and effective and, when they name controls, at least one linked control is implemented.
+If a proposed effective date has passed, choose a current or future activation date. Never backdate adoption.
 
 For a material revision, preserve Git history, obtain a new approval, and require a new acknowledgement when the audience’s responsibilities changed. Do not reuse the audit firm as a management approver without confirming independence.

package/template/data/policies/policy-information-security.json

@@ -14,14 +14,8 @@
     "vendors"
   ],
   "acknowledgementRequired": true,
-  "relatedPolicyIds": [
-    "policy-clear-desk-screen",
-    "policy-data-protection-handling",
-    "policy-mobile-computing-communications"
-  ],
   "relatedDocumentIds": [
-    "document-business-continuity-disaster-recovery",
-    "document-incident-response-plan",
+    "document-security-incident-recovery-plan",
     "document-data-retention-schedule"
   ],
   "proposedEffectiveOn": "{{effective_date}}",