create-filegrc 0.7.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-filegrc",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Create a filegrc workspace for a SOC 2 program",
   "license": "MIT",
   "repository": {
@@ -18,7 +18,8 @@
     "template-parameters.json"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node ../../scripts/run-create-filegrc-tests.mjs",
+    "test:full": "npm test"
   },
   "engines": {
     "node": ">=20"

package/src/index.js

@@ -523,13 +523,13 @@ async function runCombinedSetup(target, input) {
 async function writeMinimalLockfile(target, name, versionRange) {
   const lock = {
     name,
-    version: "0.7.1",
+    version: "0.9.0",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.7.1",
+        version: "0.9.0",
         dependencies: { filegrc: versionRange }
       }
     }

package/template/AGENTS.md

@@ -100,12 +100,12 @@ Do not rewrite or remove committed records that explain prior audit periods. Clo
 If the installed CLI reports that this workspace uses an unsupported model, start with:
 
 ```sh
-npx filegrc migrate --to-model 3 --preview --json
+npx filegrc migrate --to-model 6 --preview --json
 ```
 
-Older workspaces migrate one version at a time. Review the v4 preview’s automatic, review-required, and unsupported classifications before applying it with the same options and `--yes`. The migration creates no approvals, holders, Evidence Artifacts, or historical dates.
+Older workspaces migrate one version at a time. Review every preview’s automatic, review-required, and unsupported classifications before applying it with the same options and `--yes`. The v6 migration separates Training approval from activation, preserves existing active Training with a visible `legacy-v5` activation basis, and removes Training schedule fields because Obligations now own assignment timing.
 
-The [model v4 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v4.md) explains System classification decisions, relationship changes, and required post-migration review.
+The [model v6 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v6.md) explains the Training lifecycle and Obligation review.
 
 Run these commands when working with records:
 
@@ -206,14 +206,14 @@ npx filegrc program-readiness --require-ready --summary --json
 The Evidence Ready gate requires:
 
 1. A management goal, selected systems, criteria, and controls.
-2. Policy content approved by someone other than its owner in Step 2, followed by active Policies with real effective dates at the Step 3 cutover.
-3. Implemented Controls with an owner, actual procedure, scope, operation pattern, mappings, implementation date, and every required linked Work Queue schedule enabled.
+2. Policies, required program Documents, and Training independently approved in Step 2, with approval dates and exact approved content revisions.
+3. Implemented Controls with an owner, actual procedure, scope, operation pattern, mappings, implementation date, and every required linked Obligation enabled. Required program Documents and Training must then be activated in Step 3 with separate activation dates and exact activation revisions.
 4. Every selected Control mapped to active authoritative Components with the required evidence source roles, current access owners, and repeatable extraction instructions in Record Markdown.
-5. Required governed plans complete and active, with no unresolved activation blockers.
+5. Required governed content active and effective, with no unresolved activation blockers. Audit Documents remain in Step 5 and do not satisfy this program gate.
 
-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. A Control may be implemented against an approved inactive Policy, and enabled Obligations remain dormant until that Policy is active and effective.
+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. A Control may be implemented against an approved inactive Policy, required program Document, or Training record. Enabled Obligations remain dormant until all of their governing content is active and effective.
 
-Review `policyActivations` in Program Readiness before cutover. It shows planned or partial Controls, missing Components or evidence sources, missing schedules, unresolved Exceptions, and dates that need attention. 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 remains incomplete until every required Policy is active and operating. FileGRC does not infer technical implementation from Policy prose. Put configuration facts in Controls, Components, Systems, governed schedules, and Evidence.
+Review `documentActivations`, `trainingActivations`, and `policyActivations` in Program Readiness before cutover. Approve Policies, program Documents, and Training in Step 2. Define schedules as Obligations and implement the linked Controls in Step 3, then use `npx filegrc activate-content --scaffold` to record the active Person and actual activation and effective dates against each unchanged approved revision. Use the Controls-page review or `npx filegrc activate-policies --scaffold` to choose which approved Policies take effect. Evidence Readiness remains incomplete until every required program artifact is active and operating. Operate and collect Evidence in Step 4. Keep engagement terms, management assertions, representation letters, and other Audit Documents in Step 5. Approve and activate each Audit Document there as separate writes after its engagement facts are complete.
 
 Onboarding does not create Evidence Artifacts. Complete authoritative source Components as part of Control implementation. For every incomplete family in Program Readiness, update the Control with its authoritative `evidenceSourceComponentIds`, then give each source Component the required evidence role, current access owners, and repeatable retrieval instructions in Record Markdown. Use `npx filegrc evidence-map --json` when you want only those source checks. During Step 4, create an Evidence Artifact only when a real artifact exists. Select its `sourceComponentId`, attach or reference the result, link the Controls and operating record it supports, record its collector and Classification, then have another person verify it before audit use.
 

package/template/README.md

@@ -19,7 +19,7 @@ npm run serve
 
 Requires Node.js 20 or newer and Git.
 
-Existing model v3 workspaces must run `npx filegrc migrate --to-model 4 --preview --json` after installing a model v4 package. Review each automatic, review-required, and unsupported item, supply explicit System classification decisions where needed, then apply the same migration with `--yes`. Older workspaces migrate one model version at a time. See the [model v4 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v4.md).
+Existing model v5 workspaces must run `npx filegrc migrate --to-model 6 --preview --json` after installing a model v6 package. The migration gives Training separate approval and activation facts, preserves active model v5 Training with a visible legacy basis, and removes Training schedule fields because Obligations now own assignment timing. Review the result and confirm or create each Training Obligation in Step 3. Older workspaces migrate one model version at a time. See the [model v6 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v6.md).
 
 ## How it works
 
@@ -40,16 +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.** 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.
+2. **Approve policies.** Review Policies, program Documents, and Training in one table. Have someone other than the owner approve each exact revision. Approval does not mean the linked Controls are implemented.
+3. **Implement controls.** Implement the approved requirements, define how each Control works, connect its Evidence sources, and configure Obligations. Activate each unchanged approved Document or Training record with a separate activation date and revision, then activate the selected Policy 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.
 
 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.
+FileGRC does not infer technical implementation from Policy prose. Configuration facts belong in Controls, Components, Systems, Obligations, and Evidence. A Control may be implemented while its governing Policy, required program Document, or Training is approved but inactive. Enabled Obligations remain dormant until all of their governing content 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.
+Control implementation includes evidence-source, Obligation, and governed-content readiness. Use `npx filegrc program-readiness --json` to review incomplete Control or Component records plus `documentActivations`, `trainingActivations`, and `policyActivations`. Activate ready program Documents and Training with `npx filegrc activate-content --scaffold`; name the active Person who performs activation, and keep approval and activation as separate dates and content-revision bindings. Then use the Controls-page review or `npx filegrc activate-policies --scaffold` to choose which approved Policies take effect. Evidence Readiness requires active Policies, required program Documents, Training, implemented Controls, configured evidence sources, and enabled Obligations before the candidate period can begin. Create Evidence during Step 4 only after operation produces a real record or artifact. Create engagement terms, management assertions, representation letters, and other Audit Documents in Step 5, link each to one Audit, approve it, then activate it with `npx filegrc activate-documents --audit AUDIT_ID --scaffold`.
 
 The Program Overview shows what is done, what is blocked, and what to do next.
 

package/template/data/AGENTS.md

@@ -116,7 +116,7 @@ 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.
+Policy, program Document, and Training approval in Step 2 accepts the reviewed requirements, intended values, and exact content revisions. It does not prove implementation or start governed work. A required program Document has `workflowScope: program`, and Training stays `approved`, until linked Controls and Obligations are ready. In Step 3, run `activate-content --scaffold` and record the active Person who performs the cutover, actual activation date, and effective date; FileGRC binds activation to each unchanged approved revision. Then run `activate-policies --scaffold`, review the approved Policies together, select the cutover set, and record the real effective date. Operate the program and collect Evidence in Step 4. Create Audit Documents with `workflowScope: engagement` only in the Step 5 workflow. After each Audit Document is complete, record approval first, then activate the unchanged approved revision in a separate update with its actor, actual activation date, and effective date.
 
 ## Delete and replace
 
@@ -178,7 +178,7 @@ The Control stage reports Control implementation items, evidence-family source c
 3. Put the exact report, filters, date range, timezone, export format, and reconciliation steps in the Component’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. Enable each required Obligation. It stays dormant while a governing Policy is inactive.
+6. Enable each required Obligation. It stays dormant while a governing Policy or required program Document is inactive. The first operating window starts from the latest applicable effective date, so FileGRC does not create overdue work for a period before cutover.
 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.
@@ -206,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. 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.
+Run Program Readiness before creating the normal audit engagement. Step 2 checks independent approval of Policies, required program Documents, and Training without requiring activation. Step 3 separately checks active Documents and Training, their activation dates and bound revisions, active Policies, implemented Controls, enabled Obligations, and evidence mapping without an audit ID. Fix readiness errors in Policy, Document, Training, Control, Component, System, Obligation, 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.
 
 For a real engagement, select the Program and its bounded Systems, a framework containing the complete CC1.1 through CC9.2 Security Common Criteria set, all nine SOC 2 Description Criteria, any optional Trust Services Categories in scope, and Controls that cover every applicable selected Trust Services criterion. Treat every Security Common Criterion as applicable. For an included optional category, keep a criterion in the framework when management judges it not relevant and record the limited circumstances in the System Description's DC8 disclosure. Do not omit any of the nine Description Criteria. Use `coverage.kind: "as-of"` with `on` for Type 1 or `coverage.kind: "range"` with `startsOn` and `endsOn` for Type 2. Record the Git commit for management's complete scope review in `scopeRevision`. Record `subserviceConclusion` and its rationale. When subservice organizations are identified, each `subserviceTreatments` item must connect one Vendor to its supplied Components within a selected System and choose the carve-out or inclusive method. Inclusive treatments also need the selected Controls that operate on those Components.
 

package/template/data/documents/AGENTS.md

@@ -6,6 +6,12 @@ Do not put FileGRC commands, record-entry instructions, readiness states, relati
 
 Bracketed prompts mark facts management must supply. Replace every prompt with a reviewed fact before approval, activation, signature, or delivery. FileGRC treats unresolved prompts as content blockers where the document lifecycle requires complete content.
 
+Set `workflowScope` to `program` for reusable plans, schedules, charters, procedures, and standards. Set it to `engagement` only for Documents prepared for a named Audit, including engagement terms, management assertions, period-completeness statements, system descriptions, and representation letters.
+
+Required program Documents follow `draft → approved → active`. Step 2 records the independent approver, `approvedOn`, and the exact `approvedContentRevisions`. After the linked requirements are implemented, Step 3 records `activationBasis: recorded`, the active Person in `activatedByIds`, `activatedOn`, `effectiveOn`, and the unchanged `activatedContentRevisions`. Approval and activation are separate writes even when they happen on the same calendar date. Editing bound Markdown requires a new approval and activation.
+
+Engagement Documents use the same separate events inside Step 5. Link each approved or active engagement Document to exactly one Audit, and do not reuse it as a Policy or Obligation document. Activate ready engagement Documents with `npx filegrc activate-documents --audit AUDIT_ID --scaffold`. Approval and activation facts become immutable after their event; return the Document to draft or approved and record a new lifecycle event when the content or decision changes. `activationBasis: legacy-v4` is only for historical audit Documents preserved by the model v4 migration. Do not use it for new work.
+
 Keep resource links in the Document JSON and supporting records. In the Markdown, describe the underlying business fact in ordinary terms. For example, use “management's control matrix,” “authoritative-source export,” or “signed letter reference” instead of a FileGRC record type or ID.
 
 The SOC 2 assertion, representation letter, period-completeness statement, and system description are management deliverables. Reconcile them to the selected Audit, criteria, Controls, populations, events, and Evidence, but do not describe the repository workflow in the final artifact. The service auditor supplies or approves final engagement wording where applicable.

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

@@ -4,6 +4,7 @@
   "title": "Data Retention Schedule",
   "status": "draft",
   "documentKind": "schedule",
+  "workflowScope": "program",
   "ownerIds": [
     "appointment-policy-owner"
   ],

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

@@ -4,6 +4,7 @@
   "title": "Security Incident and Recovery Plan",
   "status": "draft",
   "documentKind": "plan",
+  "workflowScope": "program",
   "ownerIds": [
     "appointment-policy-owner"
   ],

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

@@ -4,11 +4,11 @@
   "title": "SOC 2 Management Assertion",
   "status": "draft",
   "documentKind": "soc2-management-assertion",
+  "workflowScope": "engagement",
   "template": true,
   "ownerIds": [
     "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classificationId": "confidential",
-  "programRole": "required"
+  "classificationId": "confidential"
 }

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

@@ -4,11 +4,11 @@
   "title": "SOC 2 Management Representation Letter",
   "status": "draft",
   "documentKind": "soc2-management-representation",
+  "workflowScope": "engagement",
   "template": true,
   "ownerIds": [
     "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classificationId": "confidential",
-  "programRole": "required"
+  "classificationId": "confidential"
 }

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

@@ -4,11 +4,11 @@
   "title": "SOC 2 Period Completeness Statement",
   "status": "draft",
   "documentKind": "soc2-period-completeness",
+  "workflowScope": "engagement",
   "template": true,
   "ownerIds": [
     "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classificationId": "confidential",
-  "programRole": "conditional"
+  "classificationId": "confidential"
 }

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

@@ -4,11 +4,11 @@
   "title": "SOC 2 System Description",
   "status": "draft",
   "documentKind": "soc2-system-description",
+  "workflowScope": "engagement",
   "template": true,
   "ownerIds": [
     "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classificationId": "internal",
-  "programRole": "required"
+  "classificationId": "internal"
 }

package/template/data/obligations/AGENTS.md

@@ -5,7 +5,7 @@ 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.
-- 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.
+- Configure and enable Obligations during Step 3. An enabled Obligation remains dormant until every governing Policy and required program Document is active and effective and, when it names Controls, at least one linked Control is implemented. FileGRC starts calendar work from the latest Policy or governed Document effective date, so pre-cutover periods do not become overdue work.
 - 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

@@ -2,7 +2,7 @@
 
 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.
+FileGRC does not infer technical implementation from Policy prose. Put configuration facts in Controls, Components, Systems, Obligations, 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.
 
@@ -14,11 +14,11 @@ The Security starter contains one consolidated Information Security Policy. Its
 
 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:
+During Step 3, implement Controls while the governing Policy is approved but inactive. Configure and enable its Obligations, 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.
+3. Confirm required program Documents and Training have independent Step 2 approval, implement their linked requirements and Obligations, and activate their exact approved revisions separately in Step 3.
 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.
 

package/template/data/training/training-security-awareness.json

@@ -10,8 +10,6 @@
     "employees",
     "contractors"
   ],
-  "assignmentTrigger": "onboarding",
-  "completionWindowDays": 30,
   "policyIds": [
     "policy-information-security"
   ],

package/template/data/workspace.json

@@ -1,5 +1,5 @@
 {
-  "dataModelVersion": "4",
+  "dataModelVersion": "6",
   "id": "workspace",
   "type": "workspace",
   "title": "{{program_title}}",

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "{{project_name}}",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "private": true,
   "description": "filegrc workspace for a SOC 2 program",
   "type": "module",