create-filegrc 0.7.0 → 0.8.0

package/README.md

@@ -28,7 +28,7 @@ For one noninteractive run, pass company and service fields together or use `--c
     "serviceName": "Example Service",
     "boundary": "The production service and supporting infrastructure.",
     "criticality": "high",
-    "dataClassification": "Confidential",
+    "classificationId": "confidential",
     "internetExposed": true,
     "programGoal": "type-2"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-filegrc",
-  "version": "0.7.0",
+  "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/defaults.js

@@ -88,7 +88,7 @@ const descriptionCriteria = [
   ["DC5", "Applicable criteria and controls", "Identify the applicable trust services criteria and the controls designed to address them."],
   ["DC6", "Complementary user entity controls", "Describe controls that customers are expected to operate for the service organization's controls to work as intended."],
   ["DC7", "Subservice organizations and controls", "Describe relevant subservice organizations, how their controls are treated, and complementary controls they are expected to operate."],
-  ["DC8", "Criteria not relevant", "Identify any trust services criteria within an included category that are not relevant to the system and explain why."],
+  ["DC8", "Criteria not relevant", "Confirm that every Security Common Criterion applies. Identify any criterion from an included optional Trust Services Category that is not relevant to the system and explain the limited circumstances."],
   ["DC9", "Significant changes", "Describe significant system changes during the reporting period that could affect a report user's understanding of the system."]
 ];
 const commonCriteriaReferences = commonCriteria.map(([reference]) => reference);
@@ -109,10 +109,10 @@ const controls = [
   {
     id: "control-policy-management",
     code: "GOV-02",
-    title: "Policy management",
-    statement: "The policy owner reviews governed policies and plans at least annually and after material changes, obtains approval from a separate independent approver, and retains the approved revisions in Git.",
+    title: "Control and policy management",
+    statement: "Management selects and develops manual and technology Controls from approved objectives, commitments, risks, dependencies, and changes, and records each Control's owner, scope, procedure, operation pattern, evidence source, and implementation status. The policy owner reviews Controls, governed policies, and plans at least annually and after material changes, obtains separate approval for governed content, and retains approved revisions in Git.",
     requirements: ["CC5.1", "CC5.2", "CC5.3"],
-    activity: "Review, approve, communicate, and version policies and plans.",
+    activity: "Review Control design and evidence paths, correct gaps or approve time-bound Exceptions, and review, approve, communicate, and version governed policies and plans.",
     controlType: "preventive",
     operationMode: "manual",
     operationPattern: "mixed",
@@ -121,10 +121,10 @@ const controls = [
   {
     id: "control-security-communication",
     code: "GOV-03",
-    title: "Security communication",
-    statement: "The organization communicates security responsibilities, approved reporting routes, material changes, and relevant control information to its workforce and outside parties.",
+    title: "Security information and communication",
+    statement: "Management obtains or generates, checks, and uses relevant and reliable information from internal and external sources to operate Controls, and communicates security responsibilities, approved reporting routes, material changes, and relevant Control information to its workforce and outside parties in time for action.",
     requirements: ["CC2.1", "CC2.2", "CC2.3"],
-    activity: "Maintain reporting routes and communicate policies, changes, and security information.",
+    activity: "Record material information sources, scope, period, ownership, and known limits; maintain reporting routes; and communicate policies, changes, and security information.",
     controlType: "preventive",
     operationMode: "hybrid",
     operationPattern: "mixed",
@@ -134,12 +134,12 @@ const controls = [
     id: "control-workforce-expectations",
     code: "HR-01",
     title: "Workforce expectations",
-    statement: "Workers agree to applicable conduct, confidentiality, acceptable-use, and security responsibilities before receiving access and are held accountable for violations.",
-    requirements: ["CC1.4"],
-    activity: "Complete screening when appropriate, agreements, policy acknowledgement, and corrective action.",
+    statement: "Workers are screened before sensitive access when lawful and appropriate to role risk, have the competence needed for assigned duties, agree to applicable conduct, confidentiality, acceptable-use, intellectual-property, and security responsibilities before receiving access, and are held accountable for violations.",
+    requirements: ["CC1.4", "CC1.5"],
+    activity: "Record the role-based screening decision, confirm competence and authority, complete agreements and policy acknowledgement, and take corrective action when needed.",
     controlType: "preventive",
     operationMode: "manual",
-    operationPattern: "event-driven",
+    operationPattern: "mixed",
     policies: [INFORMATION_SECURITY_POLICY_ID]
   },
   {
@@ -158,9 +158,9 @@ const controls = [
     id: "control-risk-assessment",
     code: "RSK-01",
     title: "Risk assessment and treatment",
-    statement: "The organization assesses information security risk at least annually and after material changes, assigns owners and responses, and reviews high and critical risks at least quarterly.",
+    statement: "The organization defines security objectives and risk tolerance, assesses information security, fraud, misconduct, dependency, and change risk at least annually and after material changes, assigns owners and responses, and reviews high and critical risks at least quarterly.",
     requirements: ["CC3.1", "CC3.2", "CC3.3", "CC3.4", "CC9.1"],
-    activity: "Identify threats and changes, score risk, select treatment, and track review dates.",
+    activity: "Confirm objectives and risk tolerance, identify internal and external threats, fraud and misconduct scenarios, dependencies, and changes, score risk, select treatment, and track review dates.",
     controlType: "detective",
     operationMode: "manual",
     operationPattern: "mixed",
@@ -170,7 +170,7 @@ const controls = [
     id: "control-monitoring-remediation",
     code: "MON-01",
     title: "Control monitoring and remediation",
-    statement: "Management reviews control operation, incidents, test results, exceptions, and findings, then assigns and tracks corrective work through completion.",
+    statement: "Management reviews Control operation, source information, incidents, test results, Exceptions, and findings at least quarterly and after significant failures, then communicates deficiencies and assigns, tracks, and verifies corrective work through completion.",
     requirements: ["CC4.1", "CC4.2"],
     activity: "Review control evidence and track deficiencies, owners, due dates, and verification.",
     controlType: "detective",
@@ -194,9 +194,9 @@ const controls = [
     id: "control-strong-authentication",
     code: "IAM-02",
     title: "Strong authentication",
-    statement: "Important systems use approved authentication settings, protected unique credentials, and multi-factor authentication for administrative, production, source-control, email, identity, and sensitive-data access when supported.",
+    statement: "Important Systems use approved strong-authentication settings, unique identities, protected credentials, changed or disabled default credentials, and separate administrative identities or roles when technically supported and appropriate to risk. Multi-factor authentication is required for workforce and administrative access to production, source control, email, identity, and Systems that provide access to Confidential or Restricted data. Customer and external-user authentication requirements follow approved Controls, customer commitments, and risk decisions. Where required MFA is unavailable, management approves a time-bound Exception with a risk assessment, compensating Controls, an accountable owner, and a review or expiration date.",
     requirements: ["CC6.1", "CC6.2", "CC6.6"],
-    activity: "Configure and monitor authentication, credential storage, and privileged roles.",
+    activity: "Configure and monitor authentication, credential and recovery-material protection, default credentials, privileged identities or roles, customer requirements, and approved MFA Exceptions.",
     controlType: "preventive",
     operationMode: "hybrid",
     operationPattern: "continuous",
@@ -242,9 +242,9 @@ const controls = [
     id: "control-encryption-transmission",
     code: "DATA-02",
     title: "Encryption and secure transmission",
-    statement: "Confidential and Restricted data is encrypted in transit over untrusted networks and at rest in approved systems and on devices, with protected key access.",
+    statement: "Confidential and Restricted data is encrypted in transit over untrusted networks and at rest in approved Systems and on devices, with named key ownership, protected key access, and risk-based key lifecycle controls.",
     requirements: ["CC6.1", "CC6.7"],
-    activity: "Configure encryption and approved transfer methods based on classification.",
+    activity: "Configure encryption and approved transfer methods based on classification, and control key generation, storage, distribution, rotation, revocation, and recovery as applicable.",
     controlType: "preventive",
     operationMode: "automated",
     operationPattern: "continuous",
@@ -259,16 +259,16 @@ const controls = [
     activity: "Apply approved retention and disposal methods to active, local, backup, and vendor-held copies.",
     controlType: "preventive",
     operationMode: "hybrid",
-    operationPattern: "event-driven",
+    operationPattern: "mixed",
     policies: [INFORMATION_SECURITY_POLICY_ID]
   },
   {
     id: "control-inventory-configuration",
     code: "OPS-01",
     title: "System inventory and secure configuration",
-    statement: "The organization maintains inventories of important systems, company and approved personal devices, service accounts, vendors, and data stores, with owners, lifecycle state, and secure configuration expectations.",
+    statement: "The organization maintains inventories of important Systems, Components, company and approved personal devices, software, service accounts, Vendors, and data stores, with owners, lifecycle state, and secure configuration expectations. Unsupported or unneeded important assets are upgraded, isolated, replaced, or retired according to risk.",
     requirements: ["CC6.1", "CC7.1"],
-    activity: "Maintain inventories, baselines, ownership, classification, and approved deviations.",
+    activity: "Maintain inventories, baselines, ownership, classification, lifecycle decisions, secure retirement, and approved deviations.",
     controlType: "preventive",
     operationMode: "hybrid",
     operationPattern: "mixed",
@@ -279,8 +279,8 @@ const controls = [
     code: "OPS-02",
     title: "Endpoint protection",
     statement: "Devices that access company systems use approved configuration, encryption, screen locking, supported software, security updates, and continuous malware protection when supported.",
-    requirements: ["CC6.6", "CC7.1"],
-    activity: "Use continuous platform protection where supported and verify endpoint configuration, update, and compliance state on the risk-based schedule recorded in an Obligation when periodic work is needed.",
+    requirements: ["CC6.6", "CC6.8", "CC7.1"],
+    activity: "Use continuous platform protection where supported and verify endpoint configuration, update, and compliance state on the approved risk-based schedule when periodic work is needed.",
     controlType: "preventive",
     operationMode: "automated",
     operationPattern: "mixed",
@@ -290,9 +290,9 @@ const controls = [
     id: "control-network-security",
     code: "NET-01",
     title: "Network and remote-access security",
-    statement: "The organization restricts network paths, protects remote access with approved encryption and authentication, and reviews material network access rules at least annually.",
+    statement: "The organization restricts network paths, separates production and nonproduction environments according to data and risk, protects remote access with approved encryption and authentication, and reviews material network access rules at least annually.",
     requirements: ["CC6.6", "CC6.7"],
-    activity: "Manage boundaries, firewall rules, wireless safeguards, and remote production access.",
+    activity: "Manage boundaries, environment connections, firewall rules, wireless safeguards, and remote production access.",
     controlType: "preventive",
     operationMode: "hybrid",
     operationPattern: "mixed",
@@ -302,12 +302,12 @@ const controls = [
     id: "control-change-management",
     code: "CHG-01",
     title: "Change management",
-    statement: "Material software and infrastructure changes are recorded, tested, approved, deployed through an authorized process, and recoverable. Review is independent when practical; a small team records a risk-appropriate compensating or post-deployment review, or an approved Exception, when independent pre-deployment review is not possible.",
+    statement: "Source and deployment paths protect against unauthorized changes and malicious software. Material software and infrastructure changes are recorded, receive a security design or threat analysis suited to their risk, are tested, approved, deployed through an authorized process, and are recoverable. Review is independent when practical; a small team records a risk-appropriate compensating or post-deployment review, or an approved Exception, when independent pre-deployment review is not possible.",
     requirements: ["CC6.8", "CC8.1"],
-    activity: "Record the reason, author, risk, reviewer or compensating review, test result, deployment, and rollback method.",
+    activity: "Record the reason, author, risk, security analysis when applicable, reviewer or compensating review, test result, deployment, communication, and rollback method.",
     controlType: "preventive",
     operationMode: "hybrid",
-    operationPattern: "event-driven",
+    operationPattern: "mixed",
     policies: [INFORMATION_SECURITY_POLICY_ID]
   },
   {
@@ -316,7 +316,7 @@ const controls = [
     title: "Vulnerability management",
     statement: "The organization monitors for vulnerabilities, chooses scan coverage and cadence based on exposure and risk, and assigns each confirmed vulnerability an approved risk-based remediation target or time-bound Exception.",
     requirements: ["CC7.1", "CC7.2", "CC7.3"],
-    activity: "Choose scan coverage and cadence. Review the starter remediation targets of Critical 7 days, High 14 days, Medium 30 days, and Low 90 days, then record the approved targets or time-bound Exceptions.",
+    activity: "Choose scan coverage and cadence, define approved risk-based remediation targets, and document time-bound Exceptions when a target cannot be met.",
     controlType: "detective",
     operationMode: "hybrid",
     operationPattern: "mixed",
@@ -328,7 +328,7 @@ const controls = [
     title: "Penetration testing",
     statement: "Management records whether independent penetration testing is needed for the in-scope service, then documents its scope and cadence from exposure, change, customer commitments, and risk decisions. Findings are tracked to resolution or approved risk treatment.",
     requirements: ["CC7.1", "CC7.2"],
-    activity: "Define scope, perform independent testing, review results, and track findings.",
+    activity: "Review and record applicability and cadence. When testing is required, define its scope and independence, perform the test, review results, and track findings.",
     controlType: "detective",
     operationMode: "manual",
     operationPattern: "scheduled",
@@ -338,9 +338,9 @@ const controls = [
     id: "control-logging-monitoring",
     code: "LOG-01",
     title: "Logging and monitoring",
-    statement: "Important systems record and protect security and operational events, retain them according to the approved Data Retention Schedule, and use risk-based alerting, review, and alert-path testing recorded in the applicable Controls and Obligations.",
+    statement: "Important Systems record and protect security and operational events, retain them according to the approved Data Retention Schedule, and use risk-based alerting, review, and alert-path testing. Systems with availability commitments, recovery objectives, or material operational dependencies also monitor the health, capacity, failure, and service indicators needed to detect degradation.",
     requirements: ["CC7.2", "CC7.3"],
-    activity: "Collect, protect, alert on, test, and review important log output and access.",
+    activity: "Collect, protect, alert on, test, and review important log output, access, and applicable health, capacity, failure, and service indicators.",
     controlType: "detective",
     operationMode: "hybrid",
     operationPattern: "mixed",
@@ -398,9 +398,9 @@ const controls = [
     id: "control-vendor-due-diligence",
     code: "VEN-01",
     title: "Vendor due diligence and contracting",
-    statement: "New Vendors receive risk-based security and privacy review and suitable contractual safeguards before access to Confidential or Restricted data. Vendors that predate Policy adoption receive a documented transition review, deadline, or approved risk acceptance.",
+    statement: "New Vendors receive risk-based security and privacy review and suitable contractual safeguards before access to Confidential or Restricted data or material reliance by an important service. Applicable contracts address permitted use and confidentiality, security responsibilities, incident notice, access and subprocessor restrictions, continuity, data return or deletion, termination, and assurance rights. Vendors that predate Policy adoption receive a documented transition review, deadline, or approved risk acceptance.",
     requirements: ["CC9.2"],
-    activity: "Assess service, data, access, assurance, recovery, incidents, and contract terms before access.",
+    activity: "Assess service, data, access, assurance, recovery, incidents, dependencies, supplied Components, and applicable contract safeguards before access or material reliance.",
     controlType: "preventive",
     operationMode: "manual",
     operationPattern: "event-driven",
@@ -440,7 +440,11 @@ const obligations = [
     recurrence: calendar("month", 3),
     ownerIds: [OVERSIGHT_TEAM_ID],
     scopeResourceIds: [OVERSIGHT_TEAM_ID],
-    controlIds: ["control-security-governance"],
+    controlIds: [
+      "control-security-governance",
+      "control-security-communication",
+      "control-monitoring-remediation"
+    ],
     policyIds: [INFORMATION_SECURITY_POLICY_ID]
   },
   {
@@ -454,7 +458,16 @@ const obligations = [
       SECURITY_PLAN_ID,
       RETENTION_SCHEDULE_ID
     ],
-    controlIds: ["control-policy-management"],
+    controlIds: ["control-policy-management", "control-data-retention-disposal"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-annual-control-design-review",
+    title: "Annual Control design and evidence-path review",
+    activityType: "control-design-review",
+    recurrence: calendar("year", 1),
+    ownerIds: [OVERSIGHT_TEAM_ID],
+    controlIds: ["control-policy-management", "control-monitoring-remediation"],
     policyIds: [INFORMATION_SECURITY_POLICY_ID]
   },
   {
@@ -466,6 +479,15 @@ const obligations = [
     controlIds: ["control-risk-assessment"],
     policyIds: [INFORMATION_SECURITY_POLICY_ID]
   },
+  {
+    id: "obligation-annual-workforce-competence-review",
+    title: "Annual workforce security-role competence review",
+    activityType: "performance-review",
+    recurrence: calendar("year", 1),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-workforce-expectations"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
   {
     id: "obligation-annual-security-training",
     title: "Annual security awareness training",
@@ -537,8 +559,8 @@ const obligations = [
   },
   {
     id: "obligation-annual-penetration-test",
-    title: "Annual independent penetration test",
-    activityType: "penetration-test",
+    title: "Annual penetration-testing applicability and cadence review",
+    activityType: "risk-assessment",
     recurrence: calendar("year", 1),
     ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
     controlIds: ["control-penetration-testing"],
@@ -603,6 +625,17 @@ const obligations = [
     controlIds: ["control-continuity-exercise"],
     policyIds: [INFORMATION_SECURITY_POLICY_ID]
   },
+  {
+    id: "obligation-worker-start-screening",
+    title: "Record the role-based screening and competence decision before sensitive access",
+    activityType: "workforce-review",
+    recurrence: event("person-started"),
+    triggerPrompt: "New employee or contractor?",
+    window: eventWindow(0),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-workforce-expectations"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
   {
     id: "obligation-worker-start-agreements",
     title: "Collect workforce agreements and policy acknowledgements",
@@ -694,6 +727,17 @@ const obligations = [
     controlIds: ["control-access-authorization", "control-access-review-offboarding"],
     policyIds: [INFORMATION_SECURITY_POLICY_ID]
   },
+  {
+    id: "obligation-worker-role-change-training",
+    title: "Assign and complete applicable role-based security training",
+    activityType: "role-training",
+    recurrence: event("person-role-changed"),
+    triggerPrompt: "Worker role changed?",
+    window: eventWindow(30),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-workforce-expectations", "control-security-training"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
   {
     id: "obligation-personal-device-approval",
     title: "Approve personal-device access and security conditions before use",

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.0",
+    version: "0.8.0",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.7.0",
+        version: "0.8.0",
         dependencies: { filegrc: versionRange }
       }
     }

package/template/AGENTS.md

@@ -49,7 +49,7 @@ Read `data/AGENTS.md` before changing records. More specific instructions inside
 - Put policies, plans, charters, procedures, meeting minutes, training, assertions, narratives, templates, and audit responses in Markdown beside their JSON records. filegrc derives the Markdown name, so records do not contain file paths.
 - Put signed forms, screenshots, third-party reports, and immutable exports behind evidence records. These files may be PDF, image, CSV, or another fixed format.
 - Never fetch an external evidence reference automatically.
-- Do not store secrets, credentials, session data, or personal data that may need to be erased from Git history.
+- Do not store plaintext credentials, private keys, tokens, recovery codes, session data, or personal data that may need to be erased from Git history. Source-controlled ciphertext is allowed only under the Information Security Policy's approved encryption, separate-key, access, and rotation conditions.
 - Keep the editable local server on loopback or behind trusted authentication. Use the read-only static build for audit sharing.
 
 ## Source truth and derived workflow
@@ -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.
 
@@ -233,7 +233,11 @@ npx filegrc audit-readiness audit-2026-type-2
 npx filegrc audit-readiness audit-2026-type-2 --require-ready --json
 ```
 
-The audit record’s `typeOneAsOf`, `periodStart`, and `periodEnd` are the dates agreed with the CPA firm. Keep the workspace candidate dates even when the formal period differs.
+The audit record’s `coverage` object stores the dates agreed with the CPA firm. Use `{ "kind": "as-of", "on": "YYYY-MM-DD" }` for Type 1 or `{ "kind": "range", "startsOn": "YYYY-MM-DD", "endsOn": "YYYY-MM-DD" }` for Type 2. Keep the Program candidate coverage even when the formal date or period differs.
+
+After reviewing the engagement's Program, Systems, criteria, Controls, commitments, subservices, complementary controls, and signatories, record the reviewed Git commit in `scopeRevision`. Update that value only after another complete scope review.
+
+Select a framework containing the complete CC1.1 through CC9.2 Security Common Criteria set, all nine SOC 2 Description Criteria, and any optional Trust Services Categories in scope. Treat every Security Common Criterion as applicable and include Controls that cover every applicable selected Trust Services criterion. For an included optional category, keep a criterion in the framework when management judges it not relevant and record the limited circumstances under DC8. Do not omit a Description Criterion. Record whether subservice organizations are identified in `subserviceConclusion` and explain the decision. If they are identified, use `subserviceTreatments` to connect each Vendor to its supplied Components inside a selected System and record the carve-out or inclusive method and rationale. An inclusive treatment also requires selected Controls linked to those Components.
 
 {{audit_preparation_guidance}}
 
@@ -244,7 +248,9 @@ Review both evidence paths against the exact firm-agreed date or period:
 
 Audit Readiness reports coverage for both paths. The packet includes the matching filegrc records and Markdown with Git history, plus Evidence Artifacts, retained attachments, delivery indexes, and checksums.
 
-Near the end of fieldwork, link a verified fixed-format copy of the signed management representation letter to its engagement-specific document. Date it on or after the Type 1 date or Type 2 period end. A representation that is still marked for later blocks packet delivery.
+Near the end of fieldwork, link a verified fixed-format copy of the signed management representation letter to its engagement-specific document. Record the actual signing timestamp in the Evidence `businessEventAt` field. It must be on or after the Type 1 date or Type 2 period end and must match the CPA report date once `reportDate` is known. A representation that is still marked for later blocks packet delivery.
+
+When the CPA firm issues the report, retain it as verified `third-party-report` Evidence with `artifactSubtype: "soc2-report"` and link that exact Evidence record through `reportEvidenceId`. A draft, screenshot, unrelated business record, or unverified file does not establish report issuance.
 
 Catalog each authoritative source as a Component and assign its `evidenceSourceKinds`. A third-party application is a Component when it supports a bounded System, a Control, Evidence, or relevant operations. Create a separate Vendor for its provider and connect the Component through `vendorId`; keep contracts, due diligence, and supplier risk on the Vendor. Name the people who can access reports and keep extraction instructions in the Component's Record Markdown. For each Type 2 population, select one source Component and export the exact audit period. Split a population when different Components or queries produce its items. Link a verified `population-export` Evidence Artifact that names the same source Component and stores the query or report parameters, generation time, timezone, count, completeness check, and accuracy check. A zero count still requires the source export and query. A population linked to an in-scope Control cannot be marked not applicable.
 

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.
 
@@ -64,7 +64,9 @@ The Program Overview shows what is done, what is blocked, and what to do next.
 
 ![filegrc audit readiness](docs/filegrc-audit.png)
 
-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.
+The Security starter uses one consolidated Information Security Policy with familiar policy-family headings, 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. The headings make common customer and Vendor questionnaire topics easy to locate, but they do not prove implementation or create separate policy documents. Confirm the applicable Control status and Evidence before answering a questionnaire.
+
+These records 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
 
@@ -94,6 +96,8 @@ filegrc manages GRC records and audit evidence. Your workforce, identity, source
 
 The independent CPA firm still selects samples, tests controls, evaluates exceptions, decides whether evidence is sufficient, and issues the SOC 2 report.
 
-Do not put secrets or personal data that may need erasure into Git. The editable local server has no authentication and binds to loopback by default.
+For a SOC 2 engagement, scope all 33 Security Common Criteria, all nine Description Criteria, and any optional Trust Services Categories included in the report. The Security Common Criteria remain mandatory. Record any criterion from an optional category judged not relevant under DC8 instead of omitting a Description Criterion.
+
+Do not put plaintext credentials, private keys, tokens, recovery codes, or personal data that may need erasure into Git. Source-controlled ciphertext is allowed only under the Information Security Policy's approved encryption, separate-key, access, and rotation conditions. The editable local server has no authentication and binds to loopback by default.
 
 Learn more at [filegrc.com](https://filegrc.com) or [view the source on GitHub](https://github.com/Alignbase/filegrc).

package/template/WORKSPACE.md

@@ -42,4 +42,6 @@ The editable browser uses `main` and pushes saved changes to `origin`. Connect t
 
 {{starter_setup}}
 
+Do not put plaintext credentials, private keys, authentication tokens, recovery codes, session material, or personal data that may need erasure into Git. Source-controlled ciphertext is allowed only under the Information Security Policy's approved encryption, separate-key, access, and rotation rules.
+
 filegrc manages GRC records and audit evidence. It does not replace infrastructure logging, monitoring, identity, backup, endpoint, or incident-detection systems.

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
 
@@ -173,12 +173,12 @@ npx filegrc program-readiness --json
 
 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.
+1. Choose an existing Component or scaffold the Component that is authoritative for the family.
+2. Set the Component to `active`, connect it to each bounded System through `systemUses` with the `evidence-source` role and a rationale, add the matching `evidenceSourceKinds`, and name current `evidenceOwnerIds`.
+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,9 @@ 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.
 
 ## Finish every change
 
@@ -217,6 +219,6 @@ git status --short
 git diff
 ```
 
-Review every changed JSON, Markdown, and attachment. Confirm the diff contains no secrets, temporary files, source exports with prohibited data, or derived `.filegrc/` output. Make one focused commit whose message says why the compliance record changed.
+Review every changed JSON, Markdown, and attachment. Confirm the diff contains no plaintext credentials, private keys, tokens, recovery codes, improperly controlled ciphertext, temporary files, source exports with prohibited data, or derived `.filegrc/` output. Make one focused commit whose message says why the compliance record changed.
 
 These commands are for CLI and agent work, which continues to manage Git explicitly. Browser saves in trunk mode commit automatically from the configured authoritative branch, then push in the background while the UI reports `Syncing`. Do not start another write until it reports `Synced`. Do not use a feature branch as a record approval state, and never include application changes when this workspace lives in a monorepo.

package/template/data/audits/AGENTS.md

@@ -15,6 +15,10 @@ npx filegrc audit-readiness AUDIT_ID --json
 
 Preparation creates engagement-specific management documents and, for Type 2, population records. It does not approve documents, implement controls, reconcile populations, or create evidence.
 
+Before fieldwork, link the accepted engagement terms as an active approved Document with `documentKind: "soc2-engagement-terms"`. Record the actual acknowledgement date, on or after approval and no later than fieldwork start, and the current management people who acknowledged the terms.
+
+Select a framework containing every CC1.1 through CC9.2 Security Common Criterion, all nine SOC 2 Description Criteria, and any optional Trust Services Categories included in the report. Treat every Security Common Criterion as applicable. For an included optional category, keep a criterion in the framework when management judges it not relevant, record the limited circumstances, and disclose them under DC8. Do not omit any Description Criterion. Bind management's complete scope review to its Git commit in `scopeRevision`. The selected auditor Vendor must represent the CPA firm engaged for the examination and must have been active during the engagement period.
+
 Review both evidence paths for the exact formal date or period:
 
 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.
@@ -30,3 +34,9 @@ npx filegrc evidence-packet --audit AUDIT_ID
 ```
 
 Do not state that an auditor accepted evidence, selected a sample, cleared an exception, or issued a report unless that fact came from the engagement team. filegrc tracks management preparation; the CPA firm owns examination judgments and the report.
+
+The signed representation requires verified `signed-record` Evidence with `artifactSubtype: "signed-management-representation"` and a fixed-format attachment. Record the letter's actual signing timestamp in `businessEventAt`; `collectedOn` only records when FileGRC received it. The signing date must match the CPA report date once `reportDate` is known. Store the issued SOC 2 report as verified `third-party-report` Evidence with `artifactSubtype: "soc2-report"`, record its actual issuance timestamp in `sourceGeneratedAt`, and link it through `reportEvidenceId` before closing the Audit. Reconcile `reportDate` and `opinionDate` to the date on that issued report.
+
+At report draft and again before closure, record the subsequent-events review through the CPA report date. Name the actual reviewers, review on or after the through date, state management's conclusion, and link relevant incidents, findings, and Evidence.
+
+For each packet delivery, name the people who performed the least-disclosure review and approved delivery. Record the redaction decision, recipient, approved delivery System, exact packet Git revision, SHA-256 manifest checksum, chronological review, approval, and delivery dates, and the receipt reference. Final assertion and representation signers must have active authority Appointments linked from the Audit.

package/template/data/documents/AGENTS.md

@@ -0,0 +1,17 @@
+# Governed Document Instructions
+
+The companion Markdown in this collection is the governed document that management reviews, approves, signs, or gives to the service auditor. Write it as a standalone company artifact.
+
+Do not put FileGRC commands, record-entry instructions, readiness states, relationship IDs, or starter-library mechanics in the governed prose. Keep those details in this guide, the record editor, and calculated work guidance. A document may name FileGRC only when FileGRC itself is part of the document's subject, such as an actual system component or evidence source.
+
+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"
   ],