create-filegrc 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-filegrc",
-  "version": "0.7.1",
+  "version": "0.8.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.8.0",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.7.1",
+        version: "0.8.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 5 --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 v5 migration adds explicit program or engagement scope, preserves known Document approval facts, and creates no activation event, actor, revision, or date. It keeps historical Documents from issued or completed Audits active with a visible `legacy-v4` activation basis.
 
-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 v5 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v5.md) explains the separate Document approval and activation 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. Policy content and required program plans and schedules 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 Work Queue schedule enabled. Required governed Documents 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 plans and schedules active and effective, with no unresolved activation blockers. Audit-specific 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 or required program Document. Enabled Obligations remain dormant until the Policy and required program Documents are 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` and `policyActivations` in Program Readiness before cutover. Complete and approve intended Document values in Step 2. After the linked Controls are implemented, use `npx filegrc activate-documents --scaffold` to record the active Person who performs the cutover plus the actual Step 3 activation and effective dates against the unchanged approved revision. Then 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 Document and Policy is active and operating. Operate and collect Evidence in Step 4. Keep engagement terms, management assertions, representation letters, and other audit-specific Documents in Step 5. Approve and activate each audit-specific 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 v4 workspaces must run `npx filegrc migrate --to-model 5 --preview --json` after installing a model v5 package. The migration assigns each Document to the program or engagement workflow, preserves each known approval, moves active Documents that still need a distinct activation back to approved, and keeps the old effective date as proposed. It preserves management Documents from issued and completed Audits with a visible legacy basis instead of rewriting history. Review the result, implement or confirm the linked requirements, then activate the exact approved revisions in Step 3. Older workspaces migrate one model version at a time. See the [model v5 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v5.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 and plans.** Tailor each Policy and complete the intended values in required governed plans and schedules. 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 enable its schedules. Activate each unchanged approved plan or schedule 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, governed schedules, and Evidence. A Control may be implemented while its governing Policy or required program Document is approved but inactive. Enabled Obligations remain dormant until the Policy and required program Documents are 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, schedule, and governed-Document readiness. Use `npx filegrc program-readiness --json` to review incomplete Control or Component records plus `documentActivations` and `policyActivations`. Activate ready plans and schedules with `npx filegrc activate-documents --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 and required program Documents, implemented Controls, configured evidence sources, and enabled schedules 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-specific Documents in Step 5, link each to one Audit, approve it, then activate it with `npx filegrc activate-documents --audit AUDIT_ID --scaffold`. Evidence packets include the separate approval and activation facts and exact content revisions in `document-lifecycle-index.csv`.
 
 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 and governed-Document 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 plan or schedule has `workflowScope: program` and stays `approved` until its linked Controls are implemented. In Step 3, run `activate-documents --scaffold` and record the active Person who performs the cutover, actual activation date, and effective date; FileGRC binds the activation to the unchanged content as a separate revision event. 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-specific 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 Policy and required governed-Document approval without requiring activation. Step 3 separately checks active Documents, their activation dates and bound revisions, active Policies, implemented Controls, enabled schedules, and evidence mapping without an audit ID. Fix readiness errors in Policy, Document, Control, Component, System, 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.
 
 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

@@ -18,7 +18,7 @@ During Step 3, implement Controls while the governing Policy is approved but ina
 
 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 governed plans and schedules have independent Step 2 approval, implement their linked requirements, 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/workspace.json

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

package/template/package.json

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