filegrc 0.7.0 → 0.8.0

package/README.md

@@ -36,13 +36,21 @@ npx filegrc evidence-packet --start 2026-01-01 --end 2026-06-30 --audit audit-id
 
 ## Upgrade an existing workspace
 
-The normal runtime uses data model v4. Start a model v3 upgrade with a read-only preview:
+Package updates may include optional starter Policy and Control revisions. Review them without writing:
 
 ```sh
-npx filegrc migrate --to-model 4 --preview --json
+npx filegrc policy-library
 ```
 
-Review every automatic, review-required, and unsupported item. A v3 System may represent either a bounded System or a Component, so ambiguous records need an explicit decisions file. Resolve unsupported items before applying the same migration with `--yes`. The [model v4 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v4.md) documents the decisions shape and migration result.
+The command shows an exact diff only when the current text still matches the prior starter default. It skips customized, approved, active, superseded, and retired Policy content. Accept one named proposal revision only with the command printed by the review, which includes `--accept`, `--proposal-revision`, and `--yes`. Acceptance fails if the proposal changed after review. It changes only the listed defaults and does not approve a Policy, activate it, or mark a Control implemented.
+
+The normal runtime uses data model v5. Start a model v4 upgrade with a read-only preview:
+
+```sh
+npx filegrc migrate --to-model 5 --preview --json
+```
+
+Review every automatic, review-required, and unsupported item. Model v4 combined Document approval and activation, so the migration preserves approval facts, assigns program or engagement scope, and moves active Documents that still need a distinct cutover to approved without inventing an activation actor, date, or revision. It preserves historical management Documents from issued or completed Audits with a visible legacy basis. Resolve unsupported items before applying the same migration with `--yes`. The [model v5 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v5.md) documents the migration and required Step 3 review.
 
 A model v2 workspace must migrate to v3 first:
 
@@ -50,7 +58,7 @@ A model v2 workspace must migrate to v3 first:
 npx filegrc migrate --to-model 3 --preview --json
 ```
 
-The migration writes one atomic batch, validates model v3, changes no Git history, and is safe to rerun. The [model v3 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v3.md) explains every migration class and the review that follows. Apply it before previewing model v4.
+The migration writes one atomic batch, validates model v3, changes no Git history, and is safe to rerun. The [model v3 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v3.md) explains every migration class and the review that follows. Apply it before previewing model v4, then model v5.
 
 A model v1 workspace must migrate to v2 first:
 
@@ -58,7 +66,7 @@ A model v1 workspace must migrate to v2 first:
 npx filegrc migrate --to-model 2 --preview --json
 ```
 
-Follow the [model v2 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v2.md), then run the model v3 and v4 previews in order.
+Follow the [model v2 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v2.md), then run the model v3, v4, and v5 previews in order.
 
 `filegrc serve --help` prints bind, port, environment, and safety options without starting the server. The editable server prefers `127.0.0.1:8787` and chooses another available port when that port is occupied. Set `FILEGRC_HOST`, `FILEGRC_PORT`, or the matching flags when needed. In trunk mode, browser saves synchronize, commit, and push from the authoritative branch. Use `--allow-non-authoritative-writes` for local development in a task checkout; the override never commits or pushes.
 
@@ -68,7 +76,7 @@ Follow the [model v2 upgrade guide](https://github.com/Alignbase/filegrc/blob/ma
 
 `filegrc program-readiness` reports whether management can start a candidate Type 2 period. Add `--summary --json` for compact stage counts and next actions, or omit `--summary` for every readiness item. Use `--require-ready` in automation. Pass `--program PROGRAM_ID` when more than one active Program exists. The command does not require an Audit ID or CPA firm.
 
-Control implementation includes each selected Control family’s expected evidence, authoritative source Components, and source-readiness checks. `filegrc evidence-map --json` provides a focused read-only diagnostic for those checks. Fix gaps in the Control and Component records. During Step 4, create an Evidence Artifact only when a real export, report, screenshot, signed file, or approved external reference exists, then link it to the supporting operating record when applicable.
+Step 2 completes and independently approves the intended values and exact revisions of required program plans and schedules. Step 3 implements their linked requirements and uses `filegrc activate-documents --scaffold` to record the active Person, separate activation date, and revision. Control implementation also checks expected evidence, authoritative source Components, and source readiness. During Step 4, create Evidence only when operation produces a real record or artifact. Keep engagement-scoped terms, management assertions, representation letters, and other audit-specific Documents in Step 5. Link each one to one Audit and use `filegrc activate-documents --audit AUDIT_ID --scaffold` after approval. Model v5 evidence packets export both lifecycle events and their exact revisions in `document-lifecycle-index.csv`.
 
 `filegrc obligations` shows recurring work and a task-level preview for each Policy Event, including owners, deadlines, and requested proof. `filegrc trigger` adds the event and all of its Action Items to the Work Queue atomically, then prints the created task IDs and deadlines.
 

package/model/index.js

@@ -1,14 +1,31 @@
 import { readFileSync } from "node:fs";
 
-export const ACTIVE_MODEL_VERSION = "4";
-export const SUPPORTED_MODEL_VERSIONS = Object.freeze(["2", "3", ACTIVE_MODEL_VERSION]);
+export const ACTIVE_MODEL_VERSION = "5";
+export const SUPPORTED_MODEL_VERSIONS = Object.freeze(["2", "3", "4", ACTIVE_MODEL_VERSION]);
+export const MODEL_CAPABILITY_VERSIONS = Object.freeze({
+  "guided-workflow": 3,
+  "program-scope": 4,
+  "component-sources": 4,
+  "evidence-artifacts": 4,
+  "governed-document-activation": 5,
+  "document-workflow-scope": 5
+});
+
+export function modelSupports(modelOrVersion, capability) {
+  const introduced = MODEL_CAPABILITY_VERSIONS[capability];
+  if (!introduced) throw new Error(`Unknown model capability "${capability}".`);
+  const version = typeof modelOrVersion === "object"
+    ? modelOrVersion?.modelVersion
+    : modelOrVersion;
+  return Number(version || 0) >= introduced;
+}
 
 export function loadModel(version = ACTIVE_MODEL_VERSION) {
   const requested = String(version);
   if (!SUPPORTED_MODEL_VERSIONS.includes(requested)) {
-    const migrationTarget = requested === "1" ? "2" : requested === "2" ? "3" : "4";
+    const migrationTarget = requested === "1" ? "2" : requested === "2" ? "3" : requested === "3" ? "4" : "5";
     throw new Error(
-      `Unsupported data model version "${requested}". This filegrc release supports models v2, v3, and v4. `
+      `Unsupported data model version "${requested}". This filegrc release supports models v2, v3, v4, and v5. `
       + `Run \`npx filegrc migrate --to-model ${migrationTarget} --preview --json\` from the workspace root.`
     );
   }

package/model/v4.json

@@ -723,7 +723,9 @@
         ],
         "obligationActivityTypes": [
           "training",
-          "performance-review"
+          "performance-review",
+          "workforce-review",
+          "role-training"
         ]
       },
       "required": [
@@ -1393,6 +1395,11 @@
       "guidance": {
         "policyBasis": "Policies rely on governed documents for detailed plans, procedures, charters, and reports. Git preserves the approved text and its revision history.",
         "cadence": "Follow the linked review Obligation. Starter governed documents are reviewed at least annually and after material changes or use, with an approver who is separate from the owner.",
+        "reviewPoints": [
+          "Write companion Markdown as a standalone company artifact. Keep FileGRC commands, record-entry instructions, readiness states, relationship IDs, and starter-library mechanics in guides and calculated work unless FileGRC itself is the document's subject.",
+          "Replace every bracketed prompt with a reviewed fact before approval, activation, signature, or delivery.",
+          "Describe the business fact in ordinary terms and keep resource relationships in the Document record and supporting records."
+        ],
         "sourceResourceIds": [
           "policy-information-security",
           "document-security-incident-recovery-plan"
@@ -1636,6 +1643,11 @@
         "policyBasis": "The information security policy requires retained proof from authoritative Components when FileGRC operating records do not contain the full result.",
         "cadence": "Create an Evidence Artifact only for a real retained artifact or approved reference. Identify its source Component or source records, Controls, collection and verification facts, coverage, revision, and classification.",
         "emptyState": "No Evidence Artifacts have been collected. Add one only when a real retained artifact or approved external reference exists.",
+        "reviewPoints": [
+          "Use artifactKind signed-record and artifactSubtype signed-management-representation for the fixed signed management representation letter.",
+          "For a signed management representation, record the actual signing timestamp in businessEventAt; collectedOn records when FileGRC received the artifact, not when management signed it.",
+          "Use artifactKind third-party-report and artifactSubtype soc2-report for the final report issued by the CPA firm, and record the report's actual issuance timestamp in sourceGeneratedAt."
+        ],
         "sourceResourceIds": [
           "policy-information-security"
         ]
@@ -2656,7 +2668,7 @@
         "cadence": "A Control may be implemented while its governing Policy is approved but inactive. Before marking it implemented, record its owner, actual procedure in Record Markdown, bounded System scope, operation pattern, authoritative evidence-source Components, implementation date, and enabled calendar or event schedules. Confirm each source Component is active, has the evidence role required by the Control family and current access owners, and includes repeatable retrieval instructions in Record Markdown. Enabled schedules remain dormant until their governing Policies are active and effective.",
         "reviewPoints": [
           "Confirm the Control is needed for the applicable Requirements, customer Commitments, and current service boundary.",
-          "Confirm the procedure describes what people actually do.",
+          "Confirm the procedure describes what people actually do, and keep starter-selection and FileGRC record-entry instructions out of the Control statement and activity. A Control may name FileGRC when FileGRC is an actual operating Component or evidence source.",
           "Use a not-applicable, external, or zero-population conclusion only when it is factually true for the current scope."
         ],
         "sourceResourceIds": [
@@ -2664,7 +2676,8 @@
         ],
         "obligationActivityTypes": [
           "risk-assessment",
-          "policy-review"
+          "policy-review",
+          "control-design-review"
         ]
       },
       "required": [
@@ -4108,6 +4121,11 @@
       "guidance": {
         "policyBasis": "The information security policy requires security training and added role-specific instruction when a person’s responsibilities or data access warrant it.",
         "cadence": "Assign security training at onboarding, complete it within 30 days, repeat at least annually, and reassign after relevant material changes or incidents.",
+        "reviewPoints": [
+          "Write workforce-facing material as standalone company training. Keep FileGRC commands, record-entry instructions, and data-model terms in guides and assignment records.",
+          "State required behavior without implying that every user needs a paid product or that customer MFA applies without an approved requirement.",
+          "Tie each completion to the exact training revision the person reviewed."
+        ],
         "sourceResourceIds": [
           "policy-information-security"
         ],
@@ -6030,10 +6048,10 @@
       "collection": "penetration-tests",
       "description": "One internal or external penetration test, including provider, scope, period, method, result, affected Systems, Evidence, Vulnerabilities, Findings, and review.",
       "guidance": {
-        "policyBasis": "The information security policy requires independent testing of the in-scope service’s external attack surface and tracked resolution of confirmed results.",
-        "cadence": "Perform at least annually and reconsider scope after material attack-surface or architecture changes.",
+        "policyBasis": "The information security policy requires management to decide whether penetration testing is needed from exposure, material changes, customer commitments, technical capability, and risk, then track confirmed findings when testing is performed.",
+        "cadence": "Use the cadence approved in the applicable Control, customer commitment, or risk decision. Review applicability at least annually and after material attack-surface or architecture changes; the review may conclude that no penetration test is required.",
         "reviewPoints": [
-          "Confirm the tester was independent and the scope covered the current attack surface.",
+          "Confirm the testing decision, tester independence when required, scope, method, and cadence match the approved reason for testing.",
           "Confirm the report supports the recorded result.",
           "Confirm every issue has remediation, an accepted exception, or verified closure."
         ],
@@ -6696,6 +6714,18 @@
           "items": "object",
           "itemObjectType": "audit-subservice-treatment",
           "label": "Subservice treatments"
+        },
+        "subserviceConclusion": {
+          "type": "enum",
+          "values": [
+            "not-applicable",
+            "identified"
+          ],
+          "label": "Subservice conclusion"
+        },
+        "subserviceConclusionRationale": {
+          "type": "string",
+          "label": "Subservice conclusion rationale"
         }
       },
       "listFields": [
@@ -6707,6 +6737,8 @@
       ],
       "formFields": [
         "coverage",
+        "subserviceConclusion",
+        "subserviceConclusionRationale",
         "subserviceTreatments"
       ]
     },
@@ -7376,7 +7408,9 @@
             "log-review",
             "network-review",
             "continuity-review",
+            "control-design-review",
             "performance-review",
+            "workforce-review",
             "personal-device-approval",
             "security-scan"
           ],
@@ -9220,6 +9254,24 @@
         "component"
       ]
     },
+    "control-design-review": {
+      "title": "Control design and evidence-path review",
+      "completionType": "control-activity",
+      "completionResourceTypes": [
+        "control-activity"
+      ],
+      "recurrenceModes": [
+        "calendar",
+        "event"
+      ],
+      "scopeResourceTypes": [
+        "control",
+        "program",
+        "system",
+        "component"
+      ],
+      "completionProfile": "control-design-review"
+    },
     "continuity-review": {
       "title": "Continuity review",
       "completionType": "control-activity",
@@ -9425,6 +9477,21 @@
       ],
       "completionProfile": "performance-review"
     },
+    "workforce-review": {
+      "title": "Workforce screening and competence review",
+      "completionType": "control-activity",
+      "completionResourceTypes": [
+        "control-activity"
+      ],
+      "recurrenceModes": [
+        "calendar",
+        "event"
+      ],
+      "scopeResourceTypes": [
+        "person"
+      ],
+      "completionProfile": "workforce-review"
+    },
     "personal-device-approval": {
       "title": "Personal device approval",
       "completionType": "control-activity",
@@ -10022,6 +10089,18 @@
         "completedAt"
       ]
     },
+    "control-design-review": {
+      "title": "Control design and evidence-path review",
+      "resourceType": "control-activity",
+      "requiredFacts": [
+        "performerIds",
+        "scopeResourceIds",
+        "method",
+        "result",
+        "reviewerIds",
+        "completedAt"
+      ]
+    },
     "performance-review": {
       "title": "Performance review",
       "resourceType": "control-activity",
@@ -10034,6 +10113,18 @@
         "completedAt"
       ]
     },
+    "workforce-review": {
+      "title": "Workforce screening and competence review",
+      "resourceType": "control-activity",
+      "requiredFacts": [
+        "performerIds",
+        "scopeResourceIds",
+        "method",
+        "result",
+        "reviewerIds",
+        "completedAt"
+      ]
+    },
     "personal-device-approval": {
       "title": "Personal-device approval",
       "resourceType": "control-activity",