filegrc 0.3.4 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 filegrc is a zero-dependency Node.js engine for Git-native GRC workspaces. It validates structured JSON records and their Markdown companions, renders a local web app, provides safe CRUD operations, and builds a read-only audit view.
 
-Program Readiness checks management-owned scope, policy adoption, control implementation, authoritative source configuration, and verified test captures without requiring an audit record. Audit Readiness starts after CPA engagement and checks the firm-agreed date or period, engagement-specific management documents, operating evidence, and Type 2 population completeness.
+Program Readiness checks management-owned scope, policy adoption, control implementation, and authoritative evidence mapping without requiring an audit record. Audit Readiness starts after CPA engagement and checks the firm-agreed date or period, engagement-specific management documents, operating evidence, and Type 2 population completeness.
 
 Controls linked to filegrc obligations show whether their Work Queue schedules are waiting for policy approval, ready for implementation, running, paused, or mixed. Marking a fully configured control implemented starts its enabled schedules when their governing policies are effective.
 
@@ -26,7 +26,7 @@ npx filegrc list risk --json
 npx filegrc references risk-example --json
 npx filegrc describe risk
 npx filegrc search "access review"
-npx filegrc evidence-test-drafts --preview --json
+npx filegrc evidence-map --json
 npx filegrc program-readiness --summary --json
 npx filegrc program-readiness --require-ready
 npx filegrc audit-readiness audit-id
@@ -34,27 +34,45 @@ npx filegrc prepare-audit audit-id
 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 v3. Start a model v2 upgrade with a read-only preview:
+
+```sh
+npx filegrc migrate --to-model 3 --preview --json
+```
+
+Review every automatic, review-required, and unsupported item. Resolve unsupported items before applying the same migration with `--yes`. 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/Sunpeak-AI/filegrc/blob/main/docs/upgrading-to-model-v3.md) explains every migration class and the review that follows.
+
+A model v1 workspace must migrate to v2 first:
+
+```sh
+npx filegrc migrate --to-model 2 --preview --json
+```
+
+Follow the [model v2 upgrade guide](https://github.com/Sunpeak-AI/filegrc/blob/main/docs/upgrading-to-model-v2.md), then run the model v3 preview.
+
 `filegrc serve --help` prints bind, port, environment, and safety options without starting the server. The editable server defaults to `127.0.0.1:8787`; 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.
 
 `filegrc setup` provides the headless equivalent of browser onboarding. Run it without arguments for guided terminal setup, or pass all initial service-boundary fields and a management program goal as flags or a JSON payload. Add `--preview` to validate and inspect the planned service and workspace writes without saving. Add `--summary --json` for compact agent output. Selecting Type 1 or Type 2 updates the workspace goal and selected systems. Setup does not select framework records, link controls, create evidence, or create an audit record.
 
-`filegrc program-path --next --json` gives an agent the current step and first action without loading the full lifecycle. Use `--summary` for compact status across all six steps, `--current` for the full current-step guide, or no compact flag for every step. `filegrc guide <type>` repeats the matching page guidance and adds fields, relationship candidates, Markdown slots, and timing for that record type.
+`filegrc program-path --next --json` gives an agent the current step and first action without loading the full lifecycle. Use `--summary` for compact status across all five steps, `--current` for the full current-step guide, or no compact flag for every step. `filegrc guide <type>` repeats the matching page guidance and adds fields, relationship candidates, Markdown slots, and timing for that record type.
 
 `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. The command does not require an audit ID or CPA firm.
 
-`filegrc evidence-test-drafts --preview --json` reports the missing draft tests for external evidence without writing them. Run `filegrc evidence-test-drafts` after confirming applicable controls and authoritative source Systems. When a Step 5 operating record exists, put the fixed artifact in an External Evidence record and link it from that operating record.
+Control implementation includes each selected Control family’s expected evidence, authoritative source Systems, and source-readiness checks. `filegrc evidence-map --json` provides a focused read-only diagnostic for those checks. Fix gaps in the Control and System records. During Step 4, create External Evidence only when a real artifact exists, then link it to the supporting operating record when applicable.
 
 `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.
 
 Long-form Markdown lives beside its JSON record. filegrc derives the Markdown path, so records do not store it.
 
-Headless creates and updates accept either a record or `{ "record": {...}, "content": {...} }`, the same mutation shape used by the web app. Run `filegrc get <id> --mutation` before an update to include JSON and Markdown revision hashes; stale writes are rejected. Use `filegrc content <type> <id>` to read a companion and `--write <file|->` to replace it. `filegrc guide --json` is the compact action and resource index for agents.
+Headless creates and updates require the `{ "record": {...}, "content": {...}, "revision": "...", "contentRevisions": {...} }` mutation envelope used by the web app. Run `filegrc scaffold` for a new mutation or `filegrc get <id> --mutation` before an update; stale record and Markdown writes are rejected. Use `filegrc content <type> <id>` to read a companion and `--write <file|->` to replace it. `filegrc guide --json` is the compact action and resource index for agents.
 
 Use `filegrc attach <evidence-id> <source-file>` to copy a fixed evidence file under its record and update `filePaths` without overwriting an existing attachment.
 
 Use `filegrc detach <evidence-id> <attachment-name> --yes` for explicit removal. Evidence records with linked local attachments cannot be deleted.
 
-The package requires Node.js 20 or newer. It uses Git for authors, commit timestamps, messages, diffs, and revisions. New workspaces use trunk mode, which fetches and fast-forwards before each browser mutation, validates and commits the saved change, then pushes. Existing settings without `repositoryMode` keep manual browser Git behavior. Agents and terminal users use Git directly; the filegrc CLI does not wrap pull, commit, or push.
+The package requires Node.js 20 or newer. It uses Git for authors, commit timestamps, messages, diffs, and revisions. New workspaces use trunk mode, which fetches and fast-forwards before each browser mutation, validates and commits the saved change, then pushes. Agents and terminal users use Git directly; the filegrc CLI does not wrap pull, commit, or push.
 
 The editable server has no authentication and binds to loopback by default. Put it behind trusted authentication before exposing it on a network, or publish the read-only static build.
 

package/model/index.js

@@ -1,9 +1,47 @@
 import { readFileSync } from "node:fs";
 
-export function loadModel(version = "1") {
+export const ACTIVE_MODEL_VERSION = "3";
+export const SUPPORTED_MODEL_VERSIONS = Object.freeze(["2", ACTIVE_MODEL_VERSION]);
+
+export function loadModel(version = ACTIVE_MODEL_VERSION) {
   const requested = String(version);
-  if (requested !== "1") throw new Error(`Unsupported data model version "${requested}". Available version: 1`);
-  return JSON.parse(readFileSync(new URL("./v1.json", import.meta.url), "utf8"));
+  if (!SUPPORTED_MODEL_VERSIONS.includes(requested)) {
+    const migrationTarget = requested === "1" ? "2" : "3";
+    throw new Error(
+      `Unsupported data model version "${requested}". This filegrc release supports models v2 and v3. `
+      + `Run \`npx filegrc migrate --to-model ${migrationTarget} --preview --json\` from the workspace root.`
+    );
+  }
+  const model = JSON.parse(readFileSync(new URL(`./v${requested}.json`, import.meta.url), "utf8"));
+  for (const [type, definition] of Object.entries(model.resources)) {
+    for (const [name, field] of Object.entries({ ...model.commonFields, ...definition.fields })) {
+      expandRegistryReference(model, field, `${type}.${name}`);
+      if (field.relationGroup) {
+        const relation = model.relationGroups?.[field.relationGroup];
+        if (!Array.isArray(relation) || relation.length === 0) {
+          throw new Error(`Model field ${type}.${name} uses unknown relation group "${field.relationGroup}".`);
+        }
+        field.relation = [...relation];
+      }
+    }
+  }
+  for (const [objectType, schema] of Object.entries(model.objectTypes || {})) {
+    for (const [name, field] of Object.entries(schema.properties || {})) {
+      expandRegistryReference(model, field, `${objectType}.${name}`);
+    }
+  }
+  return model;
+}
+
+function expandRegistryReference(model, field, path) {
+  if (!field.registry) return;
+  const registry = model[field.registry];
+  if (!registry || Array.isArray(registry) || typeof registry !== "object") {
+    throw new Error(`Model field ${path} uses unknown registry "${field.registry}".`);
+  }
+  const values = Object.keys(registry);
+  if (!values.length) throw new Error(`Model registry "${field.registry}" cannot be empty.`);
+  field.values = values;
 }
 
 export function getResourceDefinition(model, type) {

package/model/v1.json

@@ -28,27 +28,27 @@
     ]
   },
   "evidenceSourceFamilies": [
-      {"id":"workforce","title":"Workforce System","sourceKinds":["workforce"],"controlCodes":["HR-01","HR-03","IAM-03"],"testEvidenceKind":"test-export","testPrompt":"Export a workforce-change report from the HR or workforce system containing starters, role changes, and departures.","description":"Catalog the HR or workforce system that is authoritative for starts, role changes, and departures. Bring the complete workforce-change population and source reports used to reconcile access and responsibilities.","timing":"Identify the source during scoping. Preserve event records as changes occur and export the complete Type 2 population after the period closes."},
-      {"id":"training-acknowledgement","title":"Training and Acknowledgements","sourceKinds":["training-acknowledgement"],"controlCodes":["GOV-03","HR-01","HR-02"],"testEvidenceKind":"test-export","testPrompt":"Export assignments and completions tied to a specific training or policy revision.","collectionTestRequired":false,"operationRecordTypes":["training","attestation"],"description":"filegrc records training assignments, content revisions, completions, acknowledgements, exceptions, and overdue follow-up during Step 5.","timing":"Set up training and acknowledgement records before assignments begin. Preserve completion proof as work occurs, then reconcile the complete Type 2 population to the workforce population after close."},
-      {"id":"identity-access","title":"Identity and Access Systems","sourceKinds":["identity-access"],"controlCodes":["IAM-01","IAM-02","IAM-03"],"testEvidenceKind":"test-export","testPrompt":"Export users, roles, privileged access, or authentication settings from the identity provider or an in-scope application.","description":"Catalog the identity provider and each important application that enforces access. Bring identity, role, privileged-access, authentication-setting, review, and removal exports.","timing":"Identify sources during scoping. Capture configuration near the Type 1 date or at the start and end of a Type 2 period; export complete change and review populations after the Type 2 period closes."},
-      {"id":"production-change","title":"Production Change Systems","sourceKinds":["production-change"],"controlCodes":["CHG-01"],"testEvidenceKind":"test-capture","testPrompt":"Capture a change from the source control or deployment system showing review, testing, approval, deployment, and rollback information.","description":"Catalog source control, deployment, and infrastructure-change systems. Bring protection settings, reviews, test and approval records, deployments, emergency changes, and rollback evidence.","timing":"Identify sources before the audit period. Preserve per-change evidence as changes occur and export the complete period population after a Type 2 period closes."},
-      {"id":"security-monitoring","title":"Security Monitoring Systems","sourceKinds":["security-monitoring"],"controlCodes":["LOG-01","IR-01","IR-02"],"testEvidenceKind":"test-capture","testPrompt":"Capture logging or alert configuration and a delivered test alert from the monitoring system.","description":"Catalog logging and alerting systems. Bring configuration, coverage, alert delivery tests, alerts, investigations, and zero-event proof. filegrc records qualifying incidents and their response during Step 5.","timing":"Capture configuration and coverage at the Type 1 date or across the Type 2 period. Preserve cases as they occur and export complete alert and incident populations after close."},
-      {"id":"vulnerability-management","title":"Vulnerability Management","sourceKinds":["vulnerability-management"],"controlCodes":["VUL-01","PEN-01"],"testEvidenceKind":"test-export","testPrompt":"Export a result from the vulnerability or dependency scanner showing scope, coverage, findings, and severity.","collectionTestRequired":false,"operationRecordTypes":["vulnerability-scan","penetration-test"],"description":"filegrc records vulnerability scans and penetration tests during Step 5. Put the scanner output or independent report in an External Evidence record and link it from the operating record rather than creating a separate collection test.","timing":"Confirm coverage before the audit period. Preserve scan and remediation evidence when generated and export the complete Type 2 population after close."},
-      {"id":"endpoint-asset","title":"Endpoint Management Systems","sourceKinds":["endpoint-asset"],"controlCodes":["PHY-01","OPS-01","OPS-02","DATA-01"],"testEvidenceKind":"test-export","testPrompt":"Export devices, security configuration, and compliance status from the endpoint-management system.","description":"Catalog device-management and endpoint-compliance systems. Bring the complete device population, security configuration, compliance status, and exceptions. filegrc records asset ownership, custody, loss, return, and disposal during Step 5.","timing":"Identify sources before devices receive access. Capture configuration near the Type 1 date or across the Type 2 period and export the complete Type 2 population after close."},
-      {"id":"backup-recovery","title":"Backup and Recovery","sourceKinds":["backup-recovery"],"controlCodes":["BCP-01","BCP-02"],"testEvidenceKind":"test-export","testPrompt":"Export job history from the backup system showing scheduled runs, successes, failures, and follow-up.","collectionTestRequired":false,"operationRecordTypes":["backup-test","exercise"],"description":"filegrc records restoration tests and continuity exercises during Step 5. Put backup-system output in an External Evidence record and link it from the operating record rather than creating a separate collection test.","timing":"Capture configuration at the Type 1 date or across the Type 2 period. Preserve restoration and exercise results when performed and export complete job and failure history after period close."},
-      {"id":"vendor-management","title":"Vendors","sourceKinds":["vendor-management"],"controlCodes":["VEN-01","VEN-02"],"testEvidenceKind":"test-capture","testPrompt":"Capture a completed vendor review with its contract, assurance report, risk decision, and follow-up.","collectionTestRequired":false,"operationRecordTypes":["vendor-review"],"description":"filegrc records vendor reviews, risk decisions, supporting reports, exceptions, and follow-up during Step 5.","timing":"Identify relevant subservice organizations during scoping. Complete reviews during operation, obtain current assurance reports before fieldwork, and document bridge coverage when a report ends before the report period."},
-      {"id":"exception-finding","title":"Exceptions and Findings","sourceKinds":["exception-finding"],"controlCodes":["MON-01","EXC-01"],"testEvidenceKind":"test-export","testPrompt":"Export open and closed exceptions or findings with owners, status, dates, and remediation verification.","collectionTestRequired":false,"operationRecordTypes":["exception","finding","action-item"],"description":"filegrc records control exceptions, findings, risk acceptance, remediation, verification, and overdue work during Step 5.","timing":"Record items as they arise. Keep their status and follow-up current, then include the complete period population in fieldwork."},
-      {"id":"data-handling","title":"Data Protection Configuration","sourceKinds":["data-handling"],"controlCodes":["DATA-02","DATA-03"],"testEvidenceKind":"test-capture","testPrompt":"Capture encryption and retention settings from an in-scope System.","description":"Catalog the systems authoritative for encryption settings and retention rules. Bring current configuration and approved schedules. Preserve completed disposal actions, exceptions, and verification during Step 5.","timing":"Confirm configuration and retention rules before the audit period. Preserve disposal evidence when work occurs and capture configuration near the Type 1 date or across the Type 2 period."},
-      {"id":"network-security","title":"Network Security Systems","sourceKinds":["network-security"],"controlCodes":["NET-01"],"testEvidenceKind":"test-capture","testPrompt":"Capture current firewall or network-access rules from the network system and confirm that remote and production access paths appear.","description":"Catalog the systems authoritative for network boundaries, firewall rules, and remote access. Bring current configuration, rule reviews, approvals, changes, and exceptions.","timing":"Confirm boundary and remote-access configuration before the audit period. Preserve rule changes as they occur and capture current configuration near the Type 1 date or across the Type 2 period."},
-      {"id":"governance","title":"Governance","sourceKinds":["governance"],"controlCodes":["GOV-01","GOV-02"],"testEvidenceKind":"test-capture","testPrompt":"Capture one completed oversight review or policy approval with the participants, decisions, dates, and follow-up work.","collectionTestRequired":false,"operationRecordTypes":["policy-review","meeting"],"description":"filegrc records policy approvals, oversight reviews, meetings, decisions, assigned actions, and completion proof in Steps 2 and 5.","timing":"Approve policies before they take effect. Preserve oversight records and decisions when the work occurs."},
-      {"id":"risk-management","title":"Risk Management","sourceKinds":["risk-management"],"controlCodes":["RSK-01"],"testEvidenceKind":"test-export","testPrompt":"Export the risk register with owners, ratings, treatment decisions, review dates, and open actions.","collectionTestRequired":false,"operationRecordTypes":["risk-assessment","risk"],"description":"filegrc records risk assessments, risks, treatment decisions, reviews, and follow-up during Step 5.","timing":"Complete the initial assessment while operating the program. Preserve risk changes and reviews as they occur, then include the current register in fieldwork."}
+      {"id":"workforce","title":"Workforce System","sourceKinds":["workforce"],"controlCodes":["HR-01","HR-03","IAM-03"],"evidenceKind":"export","evidencePrompt":"Export a workforce-change report from the HR or workforce system containing starters, role changes, and departures.","description":"Catalog the HR or workforce system that is authoritative for starts, role changes, and departures. Bring the complete workforce-change population and source reports used to reconcile access and responsibilities.","timing":"Identify the source during scoping. Preserve event records as changes occur and export the complete Type 2 population after the period closes."},
+      {"id":"training-acknowledgement","title":"Training and Acknowledgements","sourceKinds":["training-acknowledgement"],"controlCodes":["GOV-03","HR-01","HR-02"],"evidenceKind":"export","evidencePrompt":"Export assignments and completions tied to a specific training or policy revision.","filegrcManaged":true,"operationRecordTypes":["training","attestation"],"description":"filegrc records training assignments, content revisions, completions, acknowledgements, exceptions, and overdue follow-up during Step 4.","timing":"Set up training and acknowledgement records before assignments begin. Preserve completion proof as work occurs, then reconcile the complete Type 2 population to the workforce population after close."},
+      {"id":"identity-access","title":"Identity and Access Systems","sourceKinds":["identity-access"],"controlCodes":["IAM-01","IAM-02","IAM-03"],"evidenceKind":"export","evidencePrompt":"Export users, roles, privileged access, or authentication settings from the identity provider or an in-scope application.","description":"Catalog the identity provider and each important application that enforces access. Bring identity, role, privileged-access, authentication-setting, review, and removal exports.","timing":"Identify sources during scoping. Capture configuration near the Type 1 date or at the start and end of a Type 2 period; export complete change and review populations after the Type 2 period closes."},
+      {"id":"production-change","title":"Production Change Systems","sourceKinds":["production-change"],"controlCodes":["CHG-01"],"evidenceKind":"capture","evidencePrompt":"Capture a change from the source control or deployment system showing review, testing, approval, deployment, and rollback information.","description":"Catalog source control, deployment, and infrastructure-change systems. Bring protection settings, reviews, test and approval records, deployments, emergency changes, and rollback evidence.","timing":"Identify sources before the audit period. Preserve per-change evidence as changes occur and export the complete period population after a Type 2 period closes."},
+      {"id":"security-monitoring","title":"Security Monitoring Systems","sourceKinds":["security-monitoring"],"controlCodes":["LOG-01","IR-01","IR-02"],"evidenceKind":"capture","evidencePrompt":"Capture logging or alert configuration and a delivered test alert from the monitoring system.","description":"Catalog logging and alerting systems. Bring configuration, coverage, alert delivery tests, alerts, investigations, and zero-event proof. filegrc records qualifying incidents and their response during Step 4.","timing":"Capture configuration and coverage at the Type 1 date or across the Type 2 period. Preserve cases as they occur and export complete alert and incident populations after close."},
+      {"id":"vulnerability-management","title":"Vulnerability Management","sourceKinds":["vulnerability-management"],"controlCodes":["VUL-01","PEN-01"],"evidenceKind":"export","evidencePrompt":"Export a result from the vulnerability or dependency scanner showing scope, coverage, findings, and severity.","filegrcManaged":true,"operationRecordTypes":["vulnerability-scan","penetration-test"],"description":"filegrc records vulnerability scans and penetration tests during Step 4. Put the scanner output or independent report in an External Evidence record and link it from the operating record when fixed supporting proof is needed.","timing":"Confirm coverage before the audit period. Preserve scan and remediation evidence when generated and export the complete Type 2 population after close."},
+      {"id":"endpoint-asset","title":"Endpoint Management Systems","sourceKinds":["endpoint-asset"],"controlCodes":["PHY-01","OPS-01","OPS-02","DATA-01"],"evidenceKind":"export","evidencePrompt":"Export devices, security configuration, and compliance status from the endpoint-management system.","description":"Catalog device-management and endpoint-compliance systems. Bring the complete device population, security configuration, compliance status, and exceptions. filegrc records asset ownership, custody, loss, return, and disposal during Step 4.","timing":"Identify sources before devices receive access. Capture configuration near the Type 1 date or across the Type 2 period and export the complete Type 2 population after close."},
+      {"id":"backup-recovery","title":"Backup and Recovery","sourceKinds":["backup-recovery"],"controlCodes":["BCP-01","BCP-02"],"evidenceKind":"export","evidencePrompt":"Export job history from the backup system showing scheduled runs, successes, failures, and follow-up.","filegrcManaged":true,"operationRecordTypes":["backup-test","exercise"],"description":"filegrc records restoration tests and continuity exercises during Step 4. Put backup-system output in an External Evidence record and link it from the operating record when fixed supporting proof is needed.","timing":"Capture configuration at the Type 1 date or across the Type 2 period. Preserve restoration and exercise results when performed and export complete job and failure history after period close."},
+      {"id":"vendor-management","title":"Vendors","sourceKinds":["vendor-management"],"controlCodes":["VEN-01","VEN-02"],"evidenceKind":"capture","evidencePrompt":"Capture a completed vendor review with its contract, assurance report, risk decision, and follow-up.","filegrcManaged":true,"operationRecordTypes":["vendor-review"],"description":"filegrc records vendor reviews, risk decisions, supporting reports, exceptions, and follow-up during Step 4.","timing":"Identify relevant subservice organizations during scoping. Complete reviews during operation, obtain current assurance reports before fieldwork, and document bridge coverage when a report ends before the report period."},
+      {"id":"exception-finding","title":"Exceptions and Findings","sourceKinds":["exception-finding"],"controlCodes":["MON-01","EXC-01"],"evidenceKind":"export","evidencePrompt":"Export open and closed exceptions or findings with owners, status, dates, and remediation verification.","filegrcManaged":true,"operationRecordTypes":["exception","finding","action-item"],"description":"filegrc records control exceptions, findings, risk acceptance, remediation, verification, and overdue work during Step 4.","timing":"Record items as they arise. Keep their status and follow-up current, then include the complete period population in fieldwork."},
+      {"id":"data-handling","title":"Data Protection Configuration","sourceKinds":["data-handling"],"controlCodes":["DATA-02","DATA-03"],"evidenceKind":"capture","evidencePrompt":"Capture encryption and retention settings from an in-scope System.","description":"Catalog the systems authoritative for encryption settings and retention rules. Bring current configuration and approved schedules. Preserve completed disposal actions, exceptions, and verification during Step 4.","timing":"Confirm configuration and retention rules before the audit period. Preserve disposal evidence when work occurs and capture configuration near the Type 1 date or across the Type 2 period."},
+      {"id":"network-security","title":"Network Security Systems","sourceKinds":["network-security"],"controlCodes":["NET-01"],"evidenceKind":"capture","evidencePrompt":"Capture current firewall or network-access rules from the network system and confirm that remote and production access paths appear.","description":"Catalog the systems authoritative for network boundaries, firewall rules, and remote access. Bring current configuration, rule reviews, approvals, changes, and exceptions.","timing":"Confirm boundary and remote-access configuration before the audit period. Preserve rule changes as they occur and capture current configuration near the Type 1 date or across the Type 2 period."},
+      {"id":"governance","title":"Governance","sourceKinds":["governance"],"controlCodes":["GOV-01","GOV-02"],"evidenceKind":"capture","evidencePrompt":"Capture one completed oversight review or policy approval with the participants, decisions, dates, and follow-up work.","filegrcManaged":true,"operationRecordTypes":["policy-review","meeting"],"description":"filegrc records policy approvals, oversight reviews, meetings, decisions, assigned actions, and completion proof in Steps 2 and 4.","timing":"Approve policies before they take effect. Preserve oversight records and decisions when the work occurs."},
+      {"id":"risk-management","title":"Risk Management","sourceKinds":["risk-management"],"controlCodes":["RSK-01"],"evidenceKind":"export","evidencePrompt":"Export the risk register with owners, ratings, treatment decisions, review dates, and open actions.","filegrcManaged":true,"operationRecordTypes":["risk-assessment","risk"],"description":"filegrc records risk assessments, risks, treatment decisions, reviews, and follow-up during Step 4.","timing":"Complete the initial assessment while operating the program. Preserve risk changes and reviews as they occur, then include the current register in fieldwork."}
   ],
   "commonFields": {
     "schemaVersion": {"type":"integer","required":true,"const":1,"label":"Schema version"},
     "id": {"type":"string","format":"id","required":true,"label":"ID"},
     "type": {"type":"string","required":true,"label":"Type"},
     "title": {"type":"string","required":true,"label":"Title","search":true},
-    "ownerIds": {"type":"array","items":"id","relation":["person","team"],"label":"Owners","filter":true},
+    "ownerIds": {"type":"array","items":"id","relation":["person","team","appointment"],"label":"Owners","filter":true},
     "tags": {"type":"array","items":"string","label":"Tags","filter":true,"search":true},
     "relatedResourceIds": {"type":"array","items":"id","relation":["*"],"label":"Related resources"},
     "extensions": {"type":"object","label":"Extensions"}
@@ -125,10 +125,10 @@
       "pluralTitle": "People",
       "group": "people-access",
       "collection": "people",
-      "description": "People who own, approve, review, or perform program work, or receive access and training. Keep detailed personnel records in the HR system.",
+      "description": "People who own, approve, review, or perform program work, or receive access and training. Record each person’s actual organization job title here and keep named program authority in dated Appointments. Keep detailed personnel records in the HR system.",
       "guidance": {
         "policyBasis": "The information security policy and employee handbook assign work to named people and require onboarding, training, role-change, and offboarding records.",
-        "cadence": "Create before assigning work or access, update after role changes, and mark inactive at departure. Training is due within 30 days of starting and annually.",
+        "cadence": "Create before assigning work or access, update the job title after organizational changes, review Appointments separately, and mark inactive only after active Appointments are ended or transferred. Training is due within 30 days of starting and annually.",
         "sourceResourceIds": ["policy-information-security","policy-employee-handbook"],
         "obligationActivityTypes": ["training","performance-review"]
       },
@@ -136,15 +136,42 @@
       "fields": {
         "status": {"type":"enum","values":["active","inactive","external"],"filter":true},
         "email": {"type":"string","format":"email","search":true},
-        "role": {"type":"string","search":true},
+        "jobTitle": {"type":"string","label":"Organization job title","search":true},
+        "role": {"type":"string","label":"Legacy role","search":true,"legacy":true,"authoritativeFields":["person.jobTitle","appointment.appointmentKind"]},
         "department": {"type":"string","filter":true},
         "managerId": {"type":"id","relation":["person"]},
         "startDate": {"type":"date"},
         "endDate": {"type":"date"},
         "employmentType": {"type":"string","filter":true},
-        "teamIds": {"type":"array","items":"id","relation":["team"]}
+        "organization": {"type":"string","search":true},
+        "teamIds": {"type":"array","items":"id","relation":["team"],"label":"Legacy teams","legacy":true,"authoritativeFields":["team.memberIds","team.chairIds"]}
       },
-      "listFields": ["title","status","role","department"]
+      "listFields": ["title","status","jobTitle","department"]
+    },
+    "appointment": {
+      "title": "Appointment",
+      "pluralTitle": "Appointments",
+      "group": "governance",
+      "collection": "appointments",
+      "description": "One person’s dated appointment to a named organizational or program responsibility, such as CISO, DPO, Policy Owner, or team chair. Use the Person job title for the person’s ordinary organizational position.",
+      "guidance": {
+        "policyBasis": "The information security policy assigns named authority and accountability, while workforce procedures require responsibility changes and departures to be reviewed and transferred.",
+        "cadence": "Create when management assigns a named responsibility. End the Appointment and create a new one when the holder changes. Reassign every linked responsibility before a holder departs.",
+        "sourceResourceIds": ["policy-information-security","policy-employee-handbook"]
+      },
+      "required": ["status","appointmentKind","holderId","scopeResourceIds"],
+      "fields": {
+        "status": {"type":"enum","values":["planned","active","ended"],"filter":true},
+        "appointmentKind": {"type":"string","format":"id","label":"Appointment kind","filter":true,"search":true},
+        "holderId": {"type":"id","relation":["person"],"label":"Holder"},
+        "scopeResourceIds": {"type":"array","items":"id","relation":["*"],"label":"Scope"},
+        "startsOn": {"type":"date","requiredWhen":{"status":["active","ended"]}},
+        "endsOn": {"type":"date","requiredWhen":{"status":"ended"}},
+        "appointedByIds": {"type":"array","items":"id","relation":["person","team"],"label":"Appointed by"},
+        "responsibilities": {"type":"string","search":true},
+        "evidenceIds": {"type":"array","items":"id","relation":["evidence"]}
+      },
+      "listFields": ["title","status","appointmentKind","holderId","startsOn","endsOn"]
     },
     "service-account": {
       "title": "Service account",
@@ -190,11 +217,12 @@
         "status": {"type":"enum","values":["active","inactive"],"filter":true},
         "purpose": {"type":"string","search":true},
         "memberIds": {"type":"array","items":"id","relation":["person"]},
-        "chairIds": {"type":"array","items":"id","relation":["person"]},
+        "chairIds": {"type":"array","items":"id","relation":["person","appointment"]},
         "charterDocumentId": {"type":"id","relation":["document"]},
         "meetingCadence": {"type":"object"}
       },
-      "listFields": ["title","status","purpose"]
+      "listFields": ["title","status","purpose"],
+      "formFields": ["chairIds"]
     },
     "system": {
       "title": "System",
@@ -202,10 +230,10 @@
       "pluralTitle": "Systems",
       "group": "systems-vendors",
       "collection": "systems",
-      "description": "Applications, services, and platforms that support the scoped service, operate controls, or produce evidence. Record vendor-provided software as a System and link it to its Vendor.",
+      "description": "Applications, services, and platforms that support the scoped service, operate controls, or produce evidence. Record vendor-provided software as a System and link it to its Vendor. Before implementing a Control that relies on a System for evidence, add the System’s evidence source roles and access owners and document repeatable retrieval instructions in Record Markdown.",
       "guidance": {
         "policyBasis": "The information security, data handling, and continuity policies require management to know which Systems are in scope, who owns them, what data they handle, how critical they are, and where evidence comes from.",
-        "cadence": "Complete the in-scope inventory before policy approval and control implementation. Review it at least annually and after material architecture, data, vendor, service, recovery, or evidence-source changes. Test report access and extraction before the candidate period begins.",
+        "cadence": "Complete the in-scope inventory before policy approval and control implementation. For each authoritative evidence source, assign its source roles and current access owners, document the exact report, filters, date range, timezone, export format, and reconciliation steps in Record Markdown, and test retrieval before implementing the linked Controls. Review the inventory at least annually and after material architecture, data, vendor, service, recovery, or evidence-source changes.",
         "sourceResourceIds": ["policy-information-security","policy-data-protection-handling","document-business-continuity-disaster-recovery"],
         "obligationActivityTypes": ["inventory-review"]
       },
@@ -222,13 +250,14 @@
         "internetExposed": {"type":"boolean","filter":true},
         "inScope": {"type":"boolean","filter":true},
         "parentSystemId": {"type":"id","relation":["system"]},
-        "commitmentIds": {"type":"array","items":"id","relation":["commitment"]},
+        "commitmentIds": {"type":"array","items":"id","relation":["commitment"],"label":"Legacy commitments","legacy":true,"authoritativeFields":["commitment.systemIds"]},
         "subserviceVendorIds": {"type":"array","items":"id","relation":["vendor"]},
         "evidenceSourceKinds": {"type":"array","items":"string","label":"Evidence source roles","filter":true,"search":true},
-        "evidenceOwnerIds": {"type":"array","items":"id","relation":["person","team"],"label":"Evidence access owners"},
+        "evidenceOwnerIds": {"type":"array","items":"id","relation":["person","team","appointment"],"label":"Evidence access owners"},
         "continuityObjectives": {"type":"object"}
       },
-      "listFields": ["title","status","criticality","environment","inScope"]
+      "listFields": ["title","status","criticality","environment","inScope","evidenceSourceKinds","evidenceOwnerIds"],
+      "formFields": ["vendorId","evidenceSourceKinds","evidenceOwnerIds"]
     },
     "asset": {
       "title": "Asset",
@@ -248,7 +277,7 @@
         "status": {"type":"enum","values":["active","lost","retired","disposed"],"filter":true},
         "assetKind": {"type":"string","filter":true},
         "criticality": {"type":"enum","values":["low","medium","high","critical"],"filter":true},
-        "custodianIds": {"type":"array","items":"id","relation":["person","team"]},
+        "custodianIds": {"type":"array","items":"id","relation":["person","team","appointment"]},
         "businessPurpose": {"type":"string","search":true},
         "serialOrAssetTag": {"type":"string","search":true},
         "systemIds": {"type":"array","items":"id","relation":["system"]},
@@ -302,10 +331,10 @@
       "group": "evidence",
       "collection": "evidence",
       "recordPath": "{id}/evidence.json",
-      "description": "External Evidence holds exports, reports, screenshots, signed files, and approved external references collected from other Systems. Step 5 records created in filegrc do not need a separate record here. Step 6 reviews and packages both evidence paths for the CPA firm.",
+      "description": "External Evidence holds exports, reports, screenshots, signed files, and approved external references collected from other Systems. Step 4 records created in filegrc do not need a separate record here. Step 5 reviews and packages both evidence paths for the CPA firm.",
       "guidance": {
         "policyBasis": "The information security and data handling policies require retained proof from authoritative Systems when filegrc's own operating records do not contain the full result.",
-        "cadence": "Before the candidate period begins, test each selected control family that relies on evidence from outside filegrc. Once operation starts, collect external evidence whenever the control runs, keep filegrc operating records current, verify evidence before audit use, cover the stated period, and retain it according to classification and record rules.",
+        "cadence": "Create External Evidence only when a real export, report, screenshot, signed file, or approved external reference exists. Select its authoritative source System, link the Controls and operating record it supports, record collection facts, verify it before audit use, cover the stated date or period, and retain it according to classification and record rules.",
         "sourceResourceIds": ["policy-information-security","policy-data-protection-handling"]
       },
       "required": ["status","evidenceKind"],
@@ -315,8 +344,8 @@
       "fields": {
         "status": {"type":"enum","values":["draft","collected","verified","expired","withdrawn"],"filter":true},
         "evidenceKind": {"type":"string","filter":true},
-        "collectionTestFamilyId": {"type":"string","label":"Collection test family","filter":true},
-        "collectionTestPrompt": {"type":"string","label":"What to collect","search":true},
+        "collectionTestFamilyId": {"type":"string","label":"Legacy collection family","filter":true},
+        "collectionTestPrompt": {"type":"string","label":"Legacy collection prompt","search":true},
         "source": {"type":"string","search":true,"requiredWhen":{"status":["collected","verified","expired","withdrawn"]}},
         "collectedOn": {"type":"date","requiredWhen":{"status":["collected","verified","expired","withdrawn"]}},
         "classification": {"type":"string","filter":true,"requiredWhen":{"status":["collected","verified","expired","withdrawn"]}},
@@ -330,7 +359,7 @@
         "populationCount": {"type":"integer","minimum":0,"label":"Population count","requiredWhen":{"evidenceKind":"population-export"}},
         "completenessValidation": {"type":"string","label":"Completeness validation","search":true,"requiredWhen":{"evidenceKind":"population-export"}},
         "accuracyValidation": {"type":"string","label":"Accuracy validation","search":true,"requiredWhen":{"evidenceKind":"population-export"}},
-        "sourceSystemId": {"type":"id","relation":["system"],"label":"Source system","requiredWhen":{"evidenceKind":["population-export","test-export","test-capture"],"status":["collected","verified","expired","withdrawn"]}},
+        "sourceSystemId": {"type":"id","relation":["system"],"label":"Source system","showWhenInactive":true,"requiredWhen":{"evidenceKind":["population-export","test-export","test-capture"],"status":["collected","verified","expired","withdrawn"]}},
         "systemIds": {"type":"array","items":"id","relation":["system"]},
         "controlIds": {"type":"array","items":"id","relation":["control"]},
         "auditIds": {"type":"array","items":"id","relation":["audit"]},
@@ -343,6 +372,7 @@
         "capture": {"type":"object"}
       },
       "listFields": ["title","status","evidenceKind","collectedOn","classification"],
+      "formFields": ["auditIds"],
       "markdown": {
         "content": {"label":"Evidence","primary":true,"required":false}
       }
@@ -442,7 +472,7 @@
         "description": {"type":"string","search":true},
         "parentRequirementId": {"type":"id","relation":["requirement"]},
         "applicabilityRationale": {"type":"string"},
-        "controlIds": {"type":"array","items":"id","relation":["control"]}
+        "controlIds": {"type":"array","items":"id","relation":["control"],"label":"Legacy controls","legacy":true,"authoritativeFields":["control.requirementIds"]}
       },
       "listFields": ["description","applicability","frameworkId"]
     },
@@ -470,7 +500,8 @@
         "effectiveOn": {"type":"date","requiredWhen":{"status":"active"}},
         "supersedesId": {"type":"id","relation":["commitment"]}
       },
-      "listFields": ["title","status","commitmentKind","customerFacing"]
+      "listFields": ["title","status","commitmentKind","customerFacing"],
+      "formFields": ["systemIds","controlIds"]
     },
     "complementary-control": {
       "title": "Complementary control",
@@ -503,10 +534,10 @@
       "pluralTitle": "Controls",
       "group": "program",
       "collection": "controls",
-      "description": "Management’s actual safeguards and procedures, mapped to Policies, Requirements, Systems, and evidence sources. The Work Queue schedules recurring operation where configured; Evidence shows that operation occurred.",
+      "description": "Management’s actual safeguards and procedures, mapped to Policies, Requirements, Systems, and authoritative evidence sources. The Work Queue schedules recurring operation where configured; Evidence shows that operation occurred. A Control is ready for implementation only when each source System is active, has the required evidence role and current access owners, and includes repeatable retrieval instructions.",
       "guidance": {
         "policyBasis": "Controls translate approved Policies and applicable Requirements into owned procedures that management can operate and prove. Policy text alone does not show implementation.",
-        "cadence": "Before marking a control implemented, record its owner, actual procedure in Record Markdown, system scope, cadence, authoritative evidence sources, and implementation date. filegrc-managed controls also require enabled schedules with effective governing policies. Marking the control implemented starts eligible schedules.",
+        "cadence": "Before marking a Control implemented, record its owner, actual procedure in Record Markdown, system scope, cadence, authoritative evidence source Systems, and implementation date. Confirm each source System is active, has the evidence role required by the Control family and current access owners, and includes repeatable retrieval instructions in Record Markdown. filegrc-managed Controls also require enabled schedules with effective governing policies. Marking the Control implemented starts eligible schedules.",
         "sourceResourceIds": ["policy-information-security","policy-data-protection-handling"],
         "obligationActivityTypes": ["risk-assessment","policy-review"]
       },
@@ -525,13 +556,14 @@
         "frequency": {"type":"string","filter":true},
         "systemIds": {"type":"array","items":"id","relation":["system"],"requiredWhen":{"status":"implemented"}},
         "evidenceSourceIds": {"type":"array","items":"id","relation":["system"],"label":"Authoritative evidence sources","requiredWhen":{"status":"implemented"}},
-        "commitmentIds": {"type":"array","items":"id","relation":["commitment"]},
+        "commitmentIds": {"type":"array","items":"id","relation":["commitment"],"label":"Legacy commitments","legacy":true,"authoritativeFields":["commitment.controlIds"]},
         "policyIds": {"type":"array","items":"id","relation":["policy"]},
-        "riskIds": {"type":"array","items":"id","relation":["risk"]},
+        "riskIds": {"type":"array","items":"id","relation":["risk"],"label":"Legacy risks","legacy":true,"authoritativeFields":["risk.controlIds"]},
         "effectiveOn": {"type":"date","requiredWhen":{"status":"implemented"}},
         "retiredOn": {"type":"date"}
       },
-      "listFields": ["code","title","status","controlType","operationMode","frequency"]
+      "listFields": ["code","title","status","controlType","operationMode","frequency","evidenceSourceIds"],
+      "formFields": ["policyIds"]
     },
     "control-test": {
       "title": "Control test",
@@ -575,7 +607,8 @@
           "requiredWhen": {"status":"not-performed"}
         }
       },
-      "listFields": ["title","status","controlId","performedBy","outcome","completedOn"]
+      "listFields": ["title","status","controlId","performedBy","outcome","completedOn"],
+      "formFields": ["auditId"]
     },
     "finding": {
       "title": "Finding",
@@ -647,7 +680,7 @@
       "required": ["status","assigneeIds","sourceResourceId"],
       "fields": {
         "status": {"type":"enum","values":["open","in-progress","blocked","done","canceled"],"filter":true},
-        "assigneeIds": {"type":"array","items":"id","relation":["person","team"]},
+        "assigneeIds": {"type":"array","items":"id","relation":["person","team","appointment"]},
         "sourceResourceId": {"type":"id","relation":["*"]},
         "description": {"type":"string","search":true},
         "priority": {"type":"rating","filter":true},
@@ -696,7 +729,7 @@
         "parentPolicyId": {"type":"id","relation":["policy"]},
         "relatedPolicyIds": {"type":"array","items":"id","relation":["policy"]},
         "relatedDocumentIds": {"type":"array","items":"id","relation":["document"]},
-        "controlIds": {"type":"array","items":"id","relation":["control"]},
+        "controlIds": {"type":"array","items":"id","relation":["control"],"label":"Legacy controls","legacy":true,"authoritativeFields":["control.policyIds"]},
         "requirementIds": {"type":"array","items":"id","relation":["requirement"]},
         "audience": {"type":"array","items":"string","filter":true},
         "acknowledgementRequired": {"type":"boolean","filter":true}
@@ -865,7 +898,8 @@
         "requirementIds": {"type":"array","items":"id","relation":["requirement"]},
         "reviewCadence": {"type":"object"}
       },
-      "listFields": ["title","status","response","inherentRating","residualRating"]
+      "listFields": ["title","status","response","inherentRating","residualRating"],
+      "formFields": ["controlIds"]
     },
     "risk-assessment": {
       "title": "Risk assessment",
@@ -923,7 +957,7 @@
         "criticality": {"type":"enum","values":["low","medium","high","critical"],"filter":true},
         "description": {"type":"string","search":true},
         "service": {"type":"string","search":true},
-        "systemIds": {"type":"array","items":"id","relation":["system"]},
+        "systemIds": {"type":"array","items":"id","relation":["system"],"label":"Legacy systems","legacy":true,"authoritativeFields":["system.vendorId"]},
         "dataClassification": {"type":"string","filter":true},
         "dataTypes": {"type":"array","items":"string","search":true},
         "subprocessor": {"type":"boolean","filter":true},
@@ -1300,10 +1334,10 @@
         "complementaryControlsConclusion": {"type":"enum","values":["identified","not-applicable"],"label":"Complementary controls conclusion"},
         "subserviceVendorIds": {"type":"array","items":"id","relation":["vendor"]},
         "subserviceMethod": {"type":"enum","values":["carve-out","inclusive","not-applicable"]},
-        "controlTestIds": {"type":"array","items":"id","relation":["control-test"]},
+        "controlTestIds": {"type":"array","items":"id","relation":["control-test"],"label":"Legacy control tests","legacy":true,"authoritativeFields":["control-test.auditId"]},
         "opinion": {"type":"enum","values":["unmodified","qualified","adverse","disclaimer","not-issued"],"filter":true},
         "opinionDate": {"type":"date"},
-        "evidenceIds": {"type":"array","items":"id","relation":["evidence"]},
+        "evidenceIds": {"type":"array","items":"id","relation":["evidence"],"label":"Legacy evidence","legacy":true,"authoritativeFields":["evidence.auditIds"]},
         "reportEvidenceId": {"type":"id","relation":["evidence"]},
         "managementResponseDocumentId": {"type":"id","relation":["document"]},
         "supplementalDocumentIds": {"type":"array","items":"id","relation":["document"]}