create-filegrc 0.9.2 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-filegrc",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Create a filegrc workspace for a SOC 2 program",
   "license": "MIT",
   "repository": {

package/src/defaults.js

@@ -9,6 +9,7 @@ const OVERSIGHT_TEAM_ID = "team-security-risk-oversight";
 const INFORMATION_SECURITY_POLICY_ID = "policy-information-security";
 const RETENTION_SCHEDULE_ID = "document-data-retention-schedule";
 const SECURITY_PLAN_ID = "document-security-incident-recovery-plan";
+const FILEGRC_INFORMATION_TYPE_ID = "information-type-grc-records";
 const FILEGRC_SOURCE_FAMILIES = [
   "training-acknowledgement",
   "exception-finding",
@@ -1117,6 +1118,10 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
     classificationId: "confidential",
     internetExposed: false,
     systemUses: [],
+    informationUses: [{
+      informationTypeId: FILEGRC_INFORMATION_TYPE_ID,
+      processingOperations: ["collect", "store", "use", "share", "delete"]
+    }],
     evidenceSourceKinds: FILEGRC_SOURCE_FAMILIES,
     evidenceOwnerIds: [POLICY_OWNER_APPOINTMENT_ID]
   };
@@ -1152,14 +1157,36 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
       ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
       ...(filegrcManaged ? {
         collectionCadence: "Record work when it occurs and export the complete population for the audit period.",
-        retention: "Keep records for the period defined in the approved Data Retention Schedule.",
+        retentionScheduleItemIds: [`retention-schedule-item-source-${sourceFamilyId}`],
         reconciliationMethod: "Export the complete filegrc source-family population, compare it with related in-scope records and Work Queue activity, and investigate omissions or duplicates.",
         validFrom: effectiveDate
       } : {})
     };
   });
 
+  const informationType = {
+    id: FILEGRC_INFORMATION_TYPE_ID,
+    type: "information-type",
+    title: "Governance, risk, compliance, and audit records",
+    status: "active",
+    classificationId: "confidential",
+    description: "Structured program records, approvals, work history, and evidence indexes stored in the FileGRC repository."
+  };
+  const retentionScheduleItems = SOURCE_FAMILIES.map(([sourceFamilyId, title]) => ({
+    id: `retention-schedule-item-source-${sourceFamilyId}`,
+    type: "retention-schedule-item",
+    title: `${title} retention review`,
+    status: "planned",
+    description: "Management must select the covered Information Types, cutoff, retention period, and disposition behavior before activation.",
+    informationTypeIds: FILEGRC_SOURCE_FAMILIES.includes(sourceFamilyId) ? [FILEGRC_INFORMATION_TYPE_ID] : [],
+    scopeResourceIds: [`source-coverage-${sourceFamilyId}`],
+    scheduleDocumentId: RETENTION_SCHEDULE_ID,
+    sourceResourceIds: [INFORMATION_SECURITY_POLICY_ID, RETENTION_SCHEDULE_ID],
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID]
+  }));
+
   const foundation = [
+    recordFile("information-types", informationType),
     recordFile("components", programRepository),
     recordFile("teams", team)
   ];
@@ -1173,6 +1200,7 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
     ...controlRecords.map((record) => recordFile("controls", record)),
     ...foundation,
     ...sourceCoverageRecords.map((record) => recordFile("source-coverage", record)),
+    ...retentionScheduleItems.map((record) => recordFile("retention-schedule-items", record)),
     ...obligationRecords.map((record) => recordFile("obligations", record))
   ];
 }

package/src/index.js

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

package/template/AGENTS.md

@@ -16,6 +16,7 @@ npx filegrc program-path --next --json
 npx filegrc guide risk-assessment --json
 npx filegrc list person --json
 npx filegrc program-readiness --summary --json
+npx filegrc program-amendment SOURCE_RESOURCE_ID --json
 ```
 
 `program-path --next --json` gives agents the current step and first action. Use `--summary` for all five step statuses or `--current` for the current step’s page summaries, detailed guidance fields, commands, and next actions. The general guide lists every supported action and record type. A type guide adds the checks needed for that resource, including timing, required and conditional fields, current relationship candidates, JSON location, and Markdown slots.
@@ -57,7 +58,7 @@ Read `data/AGENTS.md` before changing records. More specific instructions inside
 
 The JSON and Markdown under `data/`, the installed model, policy content, and Git history are the inputs to FileGRC’s shared workflow calculation. Source files hold facts, decisions, relationships, dates, status, and evidence references. They do not each need a copy of the generic audit-readiness instructions or calculated TODO list.
 
-Use `npx filegrc workflow --json` for the complete derived checklist, named readiness assessments, blockers, Work Items, and recommended next action. `guide`, `list --workflow`, `get --workflow`, mutation previews, the HTTP API, and the browser consume the same calculation. Resolve a derived finding by changing its source facts, recording a reviewed applicability decision, accepting an allowed Exception, or completing authoritative assigned work. Never add a separate TODO file or UI-only completion flag for calculated work.
+Start with `npx filegrc program-path --next --json` for the current step and next action. Use `npx filegrc workflow --json` when you need the complete derived checklist, named readiness assessments, blockers, and Work Items. `guide`, `list --workflow`, `get --workflow`, mutation previews, the HTTP API, and the browser consume the same calculation. Resolve a derived finding by changing its source facts, recording a reviewed applicability decision, accepting an allowed Exception, or completing authoritative assigned work. Never add a separate TODO file or UI-only completion flag for calculated work.
 
 FileGRC marks an item `blocked` only when named prerequisite records must be resolved first. A missing record, editable error, or management decision is `ready` when you can act on it now, even when it prevents a readiness assessment from passing.
 
@@ -98,15 +99,23 @@ Do not rewrite or remove committed records that explain prior audit periods. Clo
 
 `data/workspace.json` selects the model through `dataModelVersion`. The installed `filegrc` package owns the authoritative model. Do not copy or invent a local schema.
 
+### Standards alignment
+
+FileGRC uses AICPA SOC 2 terms for the assurance subject matter and borrows useful structure from NIST OSCAL. A FileGRC System is the bounded system being governed or examined. Components are the logical capabilities that implement or support it, Assets are specific inventory items, Controls describe management's implementation, and Control Tests and Findings hold assessment work. Frameworks and Requirements act like catalog content, while the Program's reviewed applicability decisions perform the control-selection role associated with an OSCAL Profile.
+
+This repository is not a native OSCAL document. Keep using the installed FileGRC model, its flat JSON records, human-readable IDs, companion Markdown, and typed relationships. Do not introduce OSCAL document nesting, UUIDs, back matter, or fields that `filegrc guide` does not support. Store an OSCAL identifier in `externalIds` when a real external mapping exists. Do not claim that this workspace or an audit packet is OSCAL-compatible unless an explicit FileGRC exporter validates that output against the supported official OSCAL schema.
+
+Use standards terms only when their meanings match. Do not call a general program change a Profile or tailoring operation unless it selects or modifies control requirements. Do not put every adjustable policy value into a generic parameter object. Keep retention periods in the approved retention schedule, recurring cadences in Obligations, recovery objectives on Systems or Components, and other decisions in their model-defined records. Organization-specific decisions remain authoritative when starter or policy-library content changes.
+
 If the installed CLI reports that this workspace uses an unsupported model, start with:
 
 ```sh
-npx filegrc migrate --to-model 6 --preview --json
+npx filegrc migrate --to-model 8 --preview --json
 ```
 
-Older workspaces migrate one version at a time. Review every preview’s automatic, review-required, and unsupported classifications before applying it with the same options and `--yes`. The v6 migration separates Training approval from activation, preserves existing active Training with a visible `legacy-v5` activation basis, and removes Training schedule fields because Obligations now own assignment timing.
+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 v8 migration preserves legacy retention prose as notes, renames Component processing operations, and creates no retention periods or disposition behavior.
 
-The [model v6 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v6.md) explains the Training lifecycle and Obligation review.
+The [model v8 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v8.md) explains the structured retention and mapping changes.
 
 Run these commands when working with records:
 

package/template/README.md

@@ -19,7 +19,7 @@ npm run serve
 
 Requires Node.js 20 or newer and Git.
 
-Existing model v5 workspaces must run `npx filegrc migrate --to-model 6 --preview --json` after installing a model v6 package. The migration gives Training separate approval and activation facts, preserves active model v5 Training with a visible legacy basis, and removes Training schedule fields because Obligations now own assignment timing. Review the result and confirm or create each Training Obligation in Step 3. Older workspaces migrate one model version at a time. See the [model v6 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v6.md).
+Existing model v7 workspaces must run `npx filegrc migrate --to-model 8 --preview --json` after installing a model v8 package. The migration preserves legacy retention prose as notes and creates no retention periods or disposition behavior. Older workspaces migrate one model version at a time. See the [model v8 upgrade guide](https://github.com/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v8.md).
 
 ## How it works
 
@@ -74,8 +74,8 @@ The browser is helpful, but it is not required. An agent can discover the model,
 
 ```sh
 npx filegrc program-path --next --json
-npx filegrc workflow --json
 npx filegrc reconcile --preview --json
+npx filegrc workflow --json # full checklist when needed
 npx filegrc period-health --require-healthy --json
 npx filegrc review-applicability decisions.json --preview --json
 npx filegrc review-collection person --scaffold

package/template/data/AGENTS.md

@@ -8,16 +8,15 @@ Treat the installed model as the authority. Do not infer a schema from a nearby
 
 ```sh
 npx filegrc guide --json
-npx filegrc workflow --json
-npx filegrc reconcile --preview --json
 npx filegrc program-path --next --json
+npx filegrc reconcile --preview --json
 npx filegrc types --json
 npx filegrc guide RESOURCE_TYPE --json
 npx filegrc list RESOURCE_TYPE --json
 npx filegrc search "TERM" --json
 ```
 
-Use `workflow --json` to get the shared assessments, complete checklist, Work Items, blockers, and recommended next action. Use `program-path --next --json` for the current lifecycle step. Use `guide` before any unfamiliar create or status transition. It reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots, timing, and exact paths. Use `describe` only when you need the raw model definition.
+Use `program-path --next --json` for the current lifecycle step. Use `workflow --json` when you need the full shared assessments, complete checklist, Work Items, and blockers. Use `guide` before any unfamiliar create or status transition. It reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots, timing, and exact paths. Use `describe` only when you need the raw model definition.
 
 After changing a lifecycle fact directly, review `reconcile --preview --json`. A candidate asks whether the change represents a real policy event. Supply the actual event date or timestamp, departure risk when relevant, and explicit confirmation before applying it.
 
@@ -100,6 +99,8 @@ If `guide` marks a Markdown slot recommended, fill it before treating the delive
 
 When `guide` returns a collection review requirement, review the listed type-specific criteria and use `npx filegrc review-collection RESOURCE_TYPE --scaffold`. Fill the management conclusion, rationale, reviewer, and date, then preview and apply the payload. Do not invent `collectionRevision`; FileGRC calculates it from the current records and material Program scope. Any later change makes the confirmation stale and requires another review.
 
+Use Retention Schedule Items as the structured rows of the Data Retention Schedule. Keep a row `planned` until management has approved its Information Types, scope, cutoff, period, disposition action, instructions, sources, approver, date, and reviewed source revisions. Run `npx filegrc program-readiness --json` after changing an information use, source-coverage record, Commitment, Policy, or other source. FileGRC may identify missing or stale decisions, but it must never infer an organization-specific period or deletion behavior.
+
 Store a relationship only on its authoritative record. Control Tests store `auditId`; Evidence Artifacts store `auditIds`; Commitments store `systemIds` and `controlIds`; Controls store `policyIds`, `requirementIds`, `systemIds`, `componentIds`, and `evidenceSourceComponentIds`; Risks store `controlIds`; Components store their `vendorId` and `systemUses`. Use `references` to inspect derived inbound links.
 
 Use explicit business dates. Git records when a file changed, but it does not replace `occurredOn`, `scheduledFor`, `completedOn`, `approvedOn`, or similar fields.

package/template/data/collection-reviews/collection-review-information-type.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-information-type",
+  "type": "collection-review",
+  "title": "Information Type inventory review",
+  "status": "planned",
+  "resourceType": "information-type",
+  "scopeResourceIds": [
+    "program-soc-2"
+  ]
+}

package/template/data/collection-reviews/collection-review-retention-schedule-item.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-retention-schedule-item",
+  "type": "collection-review",
+  "title": "Retention schedule review",
+  "status": "planned",
+  "resourceType": "retention-schedule-item",
+  "scopeResourceIds": [
+    "program-soc-2"
+  ]
+}

package/template/data/documents/AGENTS.md

@@ -10,7 +10,7 @@ Set `workflowScope` to `program` for reusable plans, schedules, charters, proced
 
 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.
+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: historical` is only for an imported historical audit Document whose source did not record approval and activation as separate events. 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.
 

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

@@ -16,7 +16,9 @@
   "acknowledgementRequired": false,
   "controlIds": [
     "control-data-classification-inventory",
-    "control-data-retention-disposal"
+    "control-data-retention-disposal",
+    "control-logging-monitoring",
+    "control-backup-restoration"
   ],
   "classificationId": "internal",
   "proposedEffectiveOn": "{{effective_date}}",

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

@@ -8,15 +8,9 @@ Retention periods may come from law, contract, tax, audit, security, or a docume
 
 ## Schedule
 
-| Record class | System or location | Owner | Trigger | Retention | End-of-period action | Authority or reason |
-| --- | --- | --- | --- | --- | --- | --- |
-| Security logs for important Systems | [Complete before approval: Systems or Components] | [Complete before approval: owner] | Log event | [Confirm or replace proposed default before approval: 12 months, adjusted for investigation, contract, legal, audit, and risk needs] | [Complete before approval: disposal action] | [Complete before approval: authority or reason] |
-| Production backups or alternate recovery copies | [Complete before approval: Systems or Components] | [Complete before approval: owner] | Backup or recovery-copy creation | [Confirm or replace proposed default before approval: 30 days, adjusted to approved System recovery needs] | [Complete before approval: expiration or disposal action] | [Complete before approval: recovery need, commitment, or risk decision] |
-| SOC 2 Policies, Control records, and audit Evidence | Git repository and approved Evidence locations | Policy owner | End of the relevant audit period | [Complete before approval based on audit, contract, and legal needs] | Archive or securely delete | Audit and business requirements |
-| Customer and service records | [Complete before approval: Systems or Components] | [Complete before approval: owner] | [Complete before approval: trigger] | [Complete before approval: retention] | Delete or anonymize | Contract, law, and business need |
-| Incident and investigation records | Approved incident and Evidence Systems | Incident owner | Incident closure | [Complete before approval: retention] | Archive or securely delete | Legal, insurance, contract, and security needs |
-
-Add rows for each important data class in the System and Vendor inventories. A row is incomplete until it names the source System or Component, owner, trigger, period, disposal action, and authority. Remove each bracketed prompt only after replacing it with a reviewed fact.
+The structured Retention Schedule Items linked to this document are its schedule rows. Each approved item must name the covered Information Types and operational scope, owner, cutoff, period, disposition action, instructions, and authority. Planned items are review prompts and are not approved retention behavior.
+
+Management must cover important information used by Systems, Components, and Vendors, including security logs, backups or alternate recovery copies, governance records, audit evidence, customer and service records, and incident records when those classes exist. No starter period or disposition action is an approved organization value.
 
 ## Holds and exceptions
 

package/template/data/workspace.json

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

package/template/package.json

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