create-filegrc 0.1.0 → 0.3.0

package/template/README.md

@@ -1,23 +1,24 @@
-# FileGRC
+# filegrc
+
+![filegrc, run a SOC 2 program as files in Git](docs/filegrc-social-preview.png)
 
 Run a SOC 2 program as files in Git.
 
-FileGRC gives a founder-led engineering team one place to adopt policies, track recurring compliance work, respond to company events, and prepare an audit. JSON holds structured records, Markdown holds long-form work, and Git supplies the change history.
+filegrc gives a founder-led engineering team one place to adopt policies, implement controls, test External Evidence collection, run recurring compliance work, and prepare an audit. JSON holds structured records, Markdown holds long-form work, and Git supplies the change history.
 
 There is no separate application database. The repository is the program, so engineers and agents can use the same data through the web app, a text editor, or the CLI.
 
-![FileGRC SOC 2 program overview](docs/filegrc-home.png)
-
 ## Why it exists
 
 SOC 2 work tends to scatter across documents, calendars, tickets, screenshots, and the auditor’s request list. That makes it hard to answer basic questions: What is due? Which policy requires it? What changed during the audit period? Is the evidence complete?
 
-FileGRC keeps that work connected:
+filegrc keeps that work connected:
 
 - A starter Security program links criteria references, policies, planned controls, owners, and schedules.
-- The obligation board turns policy timing into upcoming, due, and overdue work.
-- Event checklists cover hiring, departures, vendor changes, incidents, and other policy triggers.
-- Audit Readiness says what management work, source-system exports, and evidence are still missing.
+- Work Queue turns policy timing into upcoming, due, and overdue work.
+- Policy Events add the required hiring, departure, vendor, incident, and change tasks to the Work Queue.
+- Program Readiness says whether management can begin a candidate Type 2 evidence period without an audit record.
+- Audit Readiness starts later with the CPA engagement, formal period, fieldwork documents, populations, and evidence delivery.
 - The packet builder produces a scoped, indexed delivery with source files, attachments, history, and checksums.
 
 The starter content is a proposal, not a claim of compliance. Review every policy and planned control against how your company actually operates before approving it.
@@ -33,35 +34,44 @@ npm run validate
 npm run serve
 ```
 
-Setup asks for the company name, the initial policy owner, and a security contact email. It initializes Git when needed. The first local run then helps define the service boundary, an independent approver, and an optional audit goal.
+Setup asks for the legal organization name, the initial policy owner and their email, a security reporting address, and the program timezone. It initializes Git when needed. The first local run then defines the initial service boundary and an optional program goal. A Type 2 choice records management intent, not an audit engagement. Completing onboarding opens Step 1 so you can add the real reviewers and operators, finish the oversight team, and confirm the criteria, commitments, vendors, and systems before moving on.
 
 Open the printed local URL. You can commit locally from Repository without configuring a remote. Add a remote when the team is ready to share the workspace, then the browser can pull with rebase and push reviewed commits.
 
+The creation summary reports the resolved engine version, program timezone, starter record counts, install result, and whether the target joined an existing Git worktree. Generated workspaces receive an organization-specific README with their engine version, validation commands, and remaining setup work.
+
 ## How it works
 
-1. Add or edit compliance artifacts under `data/`.
-2. FileGRC validates relationships, renders the current program, and calculates policy work.
-3. Commit focused changes with a message that explains why the records changed.
-4. Git preserves the author, time, message, diff, and prior version.
-5. For an audit, define the Type 1 date or Type 2 period and generate an evidence packet from the selected revision.
+1. Confirm the program’s people and oversight team, applicable criteria, commitments, material vendors, and in-scope systems.
+2. Review and activate the policies with a separate management reviewer, who is usually internal and may be external.
+3. Tailor the starter controls, add each owner, actual procedure, scope, cadence, evidence source, and implementation date, and confirm any linked Work Queue schedules are enabled. Marking a control implemented starts eligible schedules. Then record any complementary customer or subservice controls.
+4. Open each generated External Evidence draft, choose its authoritative source System, collect the named artifact, and have another person verify it.
+5. Start the management candidate period, maintain risk assessments and risks, update controls when needed, work the filegrc queue, and preserve dated evidence.
+6. Engage a CPA firm, record the separate firm-agreed period, review filegrc Evidence and External Evidence, prepare fieldwork, and generate the evidence packet.
 
 Long-form policies, procedures, plans, minutes, training, assertions, and audit responses are Markdown companions beside their JSON records. Screenshots, signed acknowledgements, reports, and fixed exports are attachments linked through evidence records.
 
+Third-party software is usually both a System and a Vendor. The application is the System because it operates controls and produces evidence. The provider is the Vendor because contracts, due diligence, and supplier risk belong to that relationship. Link the System to the Vendor with `vendorId`, and link exported evidence to the System.
+
 ## Run the program
 
-Use Overview to follow the audit chain: scope, criteria, policies, controls, operation, and audit. The sidebar follows the same order.
+Use Overview to follow one six-step path: define scope, approve policies, implement controls, test External Evidence, operate the program, then complete the audit. Steps 1 through 4 and Step 6 open an overview with instructions, record links, progress, and completion status. Step 5 opens Policy Events and the Work Queue because operation is ongoing rather than a one-time checklist. The progress tracker opens the first incomplete step.
 
-Use Obligation Board for recurring work and event checklists. Each item shows its allowed completion window and overdue cutoff, based on the policy that created it. Link a dated completion record and evidence to close the occurrence.
+![filegrc SOC 2 program overview](docs/filegrc-home.png)
 
-Use the resource pages to maintain systems, people, vendors, risks, controls, tests, incidents, training, meetings, and evidence. The question-mark guide on each list explains what the record type is for, which policies call for it, and when to update it.
+Use Work Queue for recurring work, Policy Event tasks, and other assigned follow-up. Trigger a Policy Event when the underlying change occurs, and filegrc adds its required actions to the queue with their owners and deadlines. Create a separate Action Item only when follow-up needs its own assignee, deadline, and completion proof. Each queue item shows its due window or deadline. Link dated proof to close the work.
+
+Use the resource pages to maintain systems, people, vendors, risks, controls, tests, incidents, training, meetings, and External Evidence. The question-mark guide on each list explains what the record type is for, which policies call for it, and when to update it.
 
 Agents use the same logic headlessly:
 
 ```sh
 npx filegrc guide risk-assessment --json
+npx filegrc program-path --json
 npx filegrc scaffold risk-assessment --title "2026 Annual Risk Assessment"
 npx filegrc list risk --json
 npx filegrc obligations --json
+npx filegrc program-readiness --summary --json
 npx filegrc complete obligation-id completion-record.json
 npx filegrc trigger person-started --occurred-on 2026-07-25 --subject person-id
 npx filegrc complete-action action-item-id completion-record.json --completed-on 2026-07-25
@@ -69,15 +79,28 @@ npx filegrc complete-event obligation-event-id --completed-on 2026-07-25
 npx filegrc search "access review"
 ```
 
-`guide` reports the policy context, timing, required fields, valid values, relationship candidates, and Markdown locations for every resource type. `scaffold` produces the same JSON and Markdown mutation shape used by the browser. Read `AGENTS.md` and `data/AGENTS.md` for the full headless workflow.
+`program-path` reports the same six steps, current status, page order, exact Instructions, Use, Policy Basis, and next actions shown in the renderer. `program-readiness --summary --json` reports compact stage counts and next actions; omit `--summary` when you need every readiness item. `guide` reports that same page guidance for one resource, plus timing, required fields, valid values, relationship candidates, and Markdown locations. `scaffold` produces the same JSON and Markdown mutation shape used by the browser. Read `AGENTS.md` and `data/AGENTS.md` for the full headless workflow.
+
+## Start the evidence period
+
+Program Readiness works without an audit ID or CPA firm:
+
+```sh
+npx filegrc program-readiness --json
+npx filegrc program-readiness --require-ready
+```
+
+The Evidence Ready gate requires defined scope, effective policies, implemented controls, configured authoritative systems, and verified collection for external evidence that does not already have a dedicated Step 5 record. Put scan reports, backup output, and other fixed artifacts in External Evidence records, then link them from the applicable Step 5 operating records. Starter obligations remain enabled proposals until their governing policies are effective and at least one linked control is implemented. A filegrc-managed control cannot be implemented while one of its linked Work Queue schedules is paused or waiting for policy approval.
+
+When the gate passes, record `candidatePeriodStart` on the workspace on the date reliable collection begins. This is management’s candidate Type 2 period. Do not backdate it. The later audit record keeps the separate period agreed with the CPA firm.
 
 ## Prepare the audit
 
-Record the audit firm, scope, and exact date or period. Audit Readiness then checks management-owned preparation, including the system description, assertion, policy and control state, source systems, evidence, and Type 2 populations.
+After engaging a CPA firm, create the audit record with the firm, scope, and exact agreed date or period. Audit Readiness checks the program foundation, engagement, formal scope and dates, management documents, filegrc Evidence, External Evidence, and Type 2 populations.
 
-![FileGRC audit readiness](docs/filegrc-audit.png)
+![filegrc audit readiness](docs/filegrc-audit.png)
 
-For a Type 2 audit, reconcile each complete period population to its authoritative system after the period closes. A zero-item population still needs its source export and query. FileGRC packages the selected records, Markdown, fixed attachments, historical versions, indexes, and SHA-256 checksums.
+For a Type 2 audit, reconcile each complete period population to its authoritative system after the period closes. A zero-item population still needs its source export and query. filegrc Evidence consists of dated operating records and their Markdown and Git history. External Evidence consists of verified exports, reports, screenshots, signed files, and approved external references. The packet compiles both paths with the selected records, attachments, indexes, historical versions, and SHA-256 checksums.
 
 ```sh
 npx filegrc prepare-audit audit-id
@@ -85,13 +108,15 @@ npx filegrc audit-readiness audit-id --json
 npx filegrc evidence-packet --audit audit-id
 ```
 
-FileGRC checks management preparation and packet integrity. The independent CPA firm still selects samples, tests controls, evaluates exceptions, decides whether evidence is sufficient, and issues the SOC 2 report.
+filegrc checks management preparation and packet integrity. The independent CPA firm still selects samples, tests controls, evaluates exceptions, decides whether evidence is sufficient, and issues the SOC 2 report.
+
+Early CPA engagement remains available when a customer deadline, unusual scope, or other timing risk needs input before the program reaches Evidence Ready. It is optional, not the default first action.
 
 ## What belongs elsewhere
 
-FileGRC does not replace workforce, identity, source-control, deployment, infrastructure, monitoring, endpoint, backup, vulnerability, training, signature, procurement, contract, or vendor-risk systems.
+filegrc does not replace workforce, identity, source-control, deployment, infrastructure, monitoring, endpoint, backup, vulnerability, training, signature, procurement, contract, or vendor-risk systems.
 
-Catalog each authoritative system in FileGRC, record how to export from it, and attach or reference the fixed evidence when Audit Readiness asks for it. The generated external-delivery index identifies files that still need to be supplied through an auditor portal or another approved channel.
+Catalog each authoritative system in filegrc, record how to export from it, and attach or reference the fixed evidence when Audit Readiness asks for it. The generated external-delivery index identifies files that still need to be supplied through an auditor portal or another approved channel.
 
 The starter uses the SOC 2 Security category and does not include licensed criteria text. Add Availability, Processing Integrity, Confidentiality, or Privacy only when they are in scope.
 

package/template/WORKSPACE.md

@@ -0,0 +1,41 @@
+# {{company_name}} SOC 2 Program
+
+This private workspace holds {{company_name}}'s SOC 2 program records and audit evidence. JSON under `data/` stores structured records, Markdown stores long-form work, and Git records reviewed changes.
+
+The workspace uses filegrc {{filegrc_version}} through the dependency range `{{filegrc_version_range}}`.
+
+## Work locally
+
+You need Node.js 20 or newer and Git.
+
+```sh
+npm install
+npm run validate
+npm run serve
+```
+
+The editable server binds to loopback by default and has no authentication. Do not expose it to an untrusted network.
+
+Agents and terminal users can inspect the workspace without the browser:
+
+```sh
+npx filegrc guide --json
+npx filegrc program-path --json
+npx filegrc obligations --json
+npx filegrc validate --json
+```
+
+Read `AGENTS.md` and `data/AGENTS.md` before broad changes.
+
+## Finish initial setup
+
+The starter policies, controls, and obligations are proposals. They do not state that {{company_name}} operates the described controls.
+
+1. Run `npx filegrc setup` for guided service and goal setup, or use browser onboarding. Then finish Step 1 by adding the real reviewers and operators, finishing the oversight team, and confirming applicable criteria, commitments, material vendors, and in-scope systems.
+2. Review the starter policies, appoint a reviewer who is separate from the policy owner, and activate only the policies that match current practice. The reviewer will usually be another person in the organization, but may be external.
+3. Review the starter control set, implement each applicable control with its actual procedure, scope, cadence, evidence sources, and implementation date, and confirm any linked Work Queue schedules are enabled. Marking a control implemented starts eligible schedules. Then record any complementary customer or subservice controls.
+4. Open each generated External Evidence draft, choose its authoritative source System, collect the named artifact, and have another person verify it.
+5. Run `npx filegrc program-readiness --require-ready`, record the management candidate period start when reliable evidence collection begins, maintain risk assessments and risks, update controls when needed, use Work Queue for scheduled work, and trigger Policy Events when changes create required actions. `npx filegrc obligations` previews every event task, owner, deadline, and requested proof before the trigger creates anything.
+6. Engage a CPA firm, record the separate firm-agreed period in an audit record, review filegrc Evidence and External Evidence, and prepare fieldwork.
+
+filegrc manages GRC records and audit evidence. It does not replace infrastructure logging, monitoring, identity, backup, endpoint, or incident-detection systems.

package/template/data/AGENTS.md

@@ -1,4 +1,4 @@
-# FileGRC Data Instructions
+# filegrc Data Instructions
 
 These instructions apply to every file under `data/`. The root `AGENTS.md` explains the program and Git workflow. A collection-level `AGENTS.md`, when present, adds rules for that resource.
 
@@ -8,13 +8,14 @@ Treat the installed model as the authority. Do not infer a schema from a nearby
 
 ```sh
 npx filegrc guide --json
+npx filegrc program-path --json
 npx filegrc types --json
 npx filegrc guide RESOURCE_TYPE --json
 npx filegrc list RESOURCE_TYPE --json
 npx filegrc search "TERM" --json
 ```
 
-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, policy context, timing, and exact paths. Use `describe` only when you need the raw model definition.
+Use `program-path` to find the current lifecycle step and see the renderer’s exact page Instructions, Use, Policy Basis, commands, and next actions. Use `guide` before any unfamiliar create or status transition. It repeats the page guidance and 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.
 
 ## Choose the right record
 
@@ -23,7 +24,7 @@ Use `guide` before any unfamiliar create or status transition. It reports requir
 - Work required on a schedule or event belongs in `obligation`.
 - A dated instance of work belongs in its activity type, such as `meeting`, `risk-assessment`, `access-review`, `vulnerability-scan`, `backup-test`, or `exercise`.
 - A fact that may change over time belongs in an inventory record, such as `person`, `system`, `asset`, `vendor`, or `access-grant`.
-- Proof belongs in `evidence`, not in an unexplained attachment.
+- A dated Step 5 operating record proves that filegrc-managed work occurred. Put each fixed external artifact in an `evidence` record and link it from the operating record; never add an unexplained attachment.
 - Follow-up work belongs in `action-item`. A gap belongs in `finding`, a known threat belongs in `risk`, and an approved temporary departure belongs in `exception`.
 - An auditor request belongs in `audit-request`; the engagement itself belongs in `audit`.
 
@@ -60,7 +61,7 @@ npx filegrc create /tmp/filegrc-mutation.json
 npx filegrc validate --json
 ```
 
-Creation is atomic. If JSON, Markdown, relationships, or validation fail, FileGRC rolls back the write. IDs are globally unique and immutable after commit.
+Creation is atomic. If JSON, Markdown, relationships, or validation fail, filegrc rolls back the write. IDs are globally unique and immutable after commit.
 
 ## Read and update
 
@@ -76,7 +77,7 @@ Edit the exported mutation, then run:
 npx filegrc update RESOURCE_TYPE RESOURCE_ID /tmp/filegrc-mutation.json
 ```
 
-The mutation includes the complete record, current Markdown, and revision hashes. FileGRC rejects the update if another person or agent changed either source after export. Reload and reapply the intended change instead of overwriting it.
+The mutation includes the complete record, current Markdown, and revision hashes. filegrc rejects the update if another person or agent changed either source after export. Reload and reapply the intended change instead of overwriting it.
 
 To update JSON and Markdown together, pass `{ "record": {...}, "content": {...}, "revision": "...", "contentRevisions": {...} }`. To change one Markdown slot:
 
@@ -90,7 +91,7 @@ Never replace a complete record with a partial JSON object. Never change `id` or
 
 JSON is for stable metadata used by validation, relationships, filters, schedules, and audit checks. Markdown is for the actual work: inputs, method, observations, results, rationale, decisions, exceptions, and follow-up.
 
-If `guide` marks a Markdown slot recommended, fill it before treating the deliverable as complete. Link evidence and resulting risks, findings, exceptions, or action items in JSON. Do not put a report’s entire variable structure into new JSON fields.
+If `guide` marks a Markdown slot recommended, fill it before treating the deliverable as complete. Keep observations and report details in the source record’s Markdown. Create a Finding only for a confirmed gap that needs its own remediation lifecycle. Create an Action Item only when follow-up needs a separate assignee, deadline, and completion proof. Set each child record’s `sourceResourceId` to the record that produced it; do not maintain reverse Finding or Action Item arrays on the source. Do not put a report’s entire variable structure into new JSON fields.
 
 Use explicit business dates. Git records when a file changed, but it does not replace `occurredOn`, `assessmentDate`, `reviewedOn`, `completedOn`, or similar fields.
 
@@ -120,7 +121,7 @@ Delete only an uncommitted draft or a mistake:
 npx filegrc delete RESOURCE_TYPE RESOURCE_ID --yes
 ```
 
-FileGRC rejects deletion that breaks references and removes owned Markdown with the JSON. Retire, close, cancel, supersede, or replace committed records that explain historical operation.
+filegrc rejects deletion that breaks references and removes owned Markdown with the JSON. Retire, close, cancel, supersede, or replace committed records that explain historical operation.
 
 ## Evidence and attachments
 
@@ -147,7 +148,7 @@ Remove a local attachment explicitly before deleting its evidence record:
 npx filegrc detach EVIDENCE_ID source-export.csv --yes
 ```
 
-FileGRC will not delete an evidence record that still has local attachments.
+filegrc will not delete an evidence record that still has local attachments.
 
 Never invent evidence, dates, approvals, results, people, or source-system details. If a required fact is unavailable, leave the record in a non-final state and report the missing input.
 
@@ -161,17 +162,18 @@ npx filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-
 npx filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD
 ```
 
-`complete` and `complete-action` validate the expected completion type and link the new record atomically. `complete-event` refuses to close the workflow until every action has its requested proof. For hour-based deadlines use `--occurred-at` with an RFC 3339 timestamp and timezone.
+Run `obligations` before `trigger` to preview every Policy Event task, owner, deadline, and requested proof. Triggering creates the event and adds all linked Action Items to the Work Queue atomically. `complete` and `complete-action` validate the expected completion type and link the new record atomically. `complete-event` refuses to close the workflow until every action has its requested proof. For hour-based deadlines use `--occurred-at` with an RFC 3339 timestamp and timezone.
 
 ## Audit work
 
 ```sh
+npx filegrc program-readiness --summary --json
 npx filegrc prepare-audit AUDIT_ID
 npx filegrc audit-readiness AUDIT_ID --json
 npx filegrc evidence-packet --audit AUDIT_ID --preview --json
 ```
 
-Fix readiness errors in source records. Do not edit packet output under `.filegrc/`. A delivery-ready FileGRC packet means the management checks passed; the engagement team still judges evidence and performs the examination.
+Run Program Readiness before creating the normal audit engagement. It checks scope, effective policies, implemented controls, evidence sources, and test captures without an audit ID. Fix readiness errors in source records. Do not edit packet output under `.filegrc/`. A delivery-ready filegrc packet means the management checks passed; the engagement team still judges evidence and performs the examination.
 
 ## Finish every change
 

package/template/data/action-items/AGENTS.md

@@ -1,6 +1,6 @@
 # Action Item Instructions
 
-An action item must point to the record that created the work. Keep the assignee, due date or policy window, blockers, completion records, and evidence explicit.
+Create an Action Item only when follow-up needs its own assignee, deadline, and completion proof. Keep simpler remediation on the Finding or other source record. Set `sourceResourceId` to the record that created the work; filegrc derives the backlink and adds every open Action Item to Work Queue. Keep the assignee, due date or policy window, blockers, completion records, and evidence explicit.
 
 For an event-generated action, do not weaken or extend its policy deadline by hand. Create the requested completion resource and close the action atomically:
 
@@ -8,4 +8,4 @@ For an event-generated action, do not weaken or extend its policy deadline by ha
 npx filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-on YYYY-MM-DD
 ```
 
-FileGRC rejects the wrong completion type. Mark ordinary action items `done` only after the work occurred and the completion record or evidence is linked. Use `blocked` while a named dependency prevents work, and link that dependency with `blockingResourceIds`.
+filegrc rejects the wrong completion type. Mark ordinary Action Items `done` only after the work occurred, set `completedOn`, and link the completion record or evidence. Use `blocked` while a named dependency prevents work, and link that dependency with `blockingResourceIds`.

package/template/data/audits/AGENTS.md

@@ -1,6 +1,10 @@
 # Audit Instructions
 
-Create one `audit` record for one engagement. Define the audit kind, framework, exact Type 1 date or Type 2 period, scope, owners, auditor, and report status from facts supplied by management or the engagement team.
+Create one `audit` record for one real CPA engagement. Define the audit kind, framework, exact firm-agreed Type 1 date or Type 2 period, scope, owners, auditor, and report status from facts supplied by management or the engagement team.
+
+Keep management’s candidate Type 2 dates on `workspace`. Do not copy them into the audit record until the CPA firm agrees to those dates. Preserve both sets when the formal period differs.
+
+The normal path is to pass `npx filegrc program-readiness --require-ready` and start reliable evidence collection before engaging the firm. Early engagement is allowed when a customer deadline or unusual scope needs CPA input.
 
 After the audit record has its dates:
 
@@ -11,6 +15,13 @@ npx filegrc audit-readiness AUDIT_ID --json
 
 Preparation creates engagement-specific management documents and, for Type 2, population records. It does not approve documents, implement controls, reconcile populations, or create evidence.
 
+Review both evidence paths for the exact formal date or period:
+
+1. filegrc Evidence consists of dated Step 5 operating records. Complete the record, link it to the applicable Controls, record the result in its fields or Markdown, and link any external artifact needed to support that result.
+2. External Evidence consists of verified `evidence` records from other Systems. Confirm the source System, date or period, Control links, collector, verifier, and fixed attachment or approved external reference.
+
+The packet compiles both paths. It includes filegrc records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.
+
 Run readiness repeatedly and fix source records. Preview the packet before writing it:
 
 ```sh
@@ -18,4 +29,4 @@ npx filegrc evidence-packet --audit AUDIT_ID --preview --json
 npx filegrc evidence-packet --audit AUDIT_ID
 ```
 
-Do not state that an auditor accepted evidence, selected a sample, cleared an exception, or issued a report unless that fact came from the engagement team. FileGRC tracks management preparation; the CPA firm owns examination judgments and the report.
+Do not state that an auditor accepted evidence, selected a sample, cleared an exception, or issued a report unless that fact came from the engagement team. filegrc tracks management preparation; the CPA firm owns examination judgments and the report.

package/template/data/documents/document-business-continuity-disaster-recovery.json

@@ -6,7 +6,6 @@
   "status": "draft",
   "documentKind": "plan",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
   "reviewCadence": {

package/template/data/documents/document-contractor-policy-acknowledgement.json

@@ -6,7 +6,6 @@
   "status": "draft",
   "documentKind": "attestation-template",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
   "reviewCadence": {

package/template/data/documents/document-contractor-training-acknowledgement.json

@@ -6,7 +6,6 @@
   "status": "draft",
   "documentKind": "attestation-template",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
   "reviewCadence": {

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

@@ -6,7 +6,6 @@
   "status": "draft",
   "documentKind": "schedule",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
   "reviewCadence": {

package/template/data/documents/document-employee-handbook-acknowledgement.json

@@ -6,7 +6,6 @@
   "status": "draft",
   "documentKind": "attestation-template",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
   "reviewCadence": {

package/template/data/documents/document-employee-policy-acknowledgement.json

@@ -6,7 +6,6 @@
   "status": "draft",
   "documentKind": "attestation-template",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
   "reviewCadence": {

package/template/data/documents/document-employee-training-acknowledgement.json

@@ -6,7 +6,6 @@
   "status": "draft",
   "documentKind": "attestation-template",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
   "reviewCadence": {

package/template/data/documents/document-incident-response-plan.json

@@ -6,7 +6,6 @@
   "status": "draft",
   "documentKind": "plan",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
   "reviewCadence": {

package/template/data/documents/document-soc2-management-assertion.json

@@ -9,9 +9,6 @@
   "ownerIds": [
     "person-policy-owner"
   ],
-  "approverIds": [
-    "person-independent-approver"
-  ],
   "version": "0.1",
   "classification": "Confidential"
 }

package/template/data/documents/document-soc2-management-representation.json

@@ -9,9 +9,6 @@
   "ownerIds": [
     "person-policy-owner"
   ],
-  "approverIds": [
-    "person-independent-approver"
-  ],
   "version": "0.1",
   "classification": "Confidential"
 }

package/template/data/documents/document-soc2-period-completeness.json

@@ -9,9 +9,6 @@
   "ownerIds": [
     "person-policy-owner"
   ],
-  "approverIds": [
-    "person-independent-approver"
-  ],
   "version": "0.1",
   "classification": "Confidential"
 }

package/template/data/documents/document-soc2-period-completeness.md

@@ -6,7 +6,7 @@ Reporting period: [start date] through [end date]
 
 Management reconciled every audit-population record linked to this engagement to its authoritative source and included every item relevant to the in-scope system and controls. The generated `population-index.csv` is incorporated into this statement by reference and records each population ID, source system, query, timezone, count, validation, reviewer, conclusion, and fixed export.
 
-| Population | FileGRC population ID | Result or exception |
+| Population | filegrc population ID | Result or exception |
 | --- | --- | --- |
 | Workforce starts, role changes, and departures | [Population ID] | [Result] |
 | Access grants, changes, reviews, and removals | [Population ID] | [Result] |
@@ -27,6 +27,6 @@ For a population with zero items, retain the source-system export or report that
 
 ## Management Confirmation
 
-To the best of management's knowledge after the reconciliations above, FileGRC and the linked evidence contain the complete populations and reportable events relevant to the engagement period.
+To the best of management's knowledge after the reconciliations above, filegrc and the linked evidence contain the complete populations and reportable events relevant to the engagement period.
 
 [Identify the responsible signer, title, signature or approval method, and date.]

package/template/data/documents/document-soc2-system-description.json

@@ -9,9 +9,6 @@
   "ownerIds": [
     "person-policy-owner"
   ],
-  "approverIds": [
-    "person-independent-approver"
-  ],
   "version": "0.1",
   "classification": "Internal"
 }

package/template/data/documents/document-soc2-system-description.md

@@ -1,6 +1,6 @@
 # {{company_name}} SOC 2 System Description
 
-> Draft preparation document. Complete every bracketed item, reconcile it to the FileGRC records, and have the service auditor review the final presentation.
+> Draft preparation document. Complete every bracketed item, reconcile it to the filegrc records, and have the service auditor review the final presentation.
 
 ## Reporting Period and Scope
 
@@ -16,7 +16,7 @@
 
 ## DC2: Service Commitments and System Requirements
 
-[Summarize customer commitments, contractual security promises, internal objectives, and the system requirements needed to meet them. Link the FileGRC commitment records.]
+[Summarize customer commitments, contractual security promises, internal objectives, and the system requirements needed to meet them. Link the filegrc commitment records.]
 
 ## DC3: System Components
 
@@ -46,7 +46,7 @@
 
 ## DC5: Applicable Criteria and Controls
 
-[Reference the selected criteria and control matrix generated by FileGRC.]
+[Reference the selected criteria and control matrix generated by filegrc.]
 
 ## DC6: Complementary User Entity Controls
 

package/template/data/evidence/AGENTS.md

@@ -1,13 +1,15 @@
-# Evidence Instructions
+# External Evidence Instructions
 
 An evidence record explains what a proof item is, where it came from, what period it supports, who collected it, and which records or controls it supports. The attachment alone is not enough.
 
+Completing onboarding creates draft collection tests only for evidence that must come from systems outside filegrc and does not already have a dedicated Step 5 record. Risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings do not need a separate test. When one of those operating records needs a fixed external artifact, create or update an External Evidence record for the artifact and link its ID from the operating record. Keep a generated collection test as `draft` until the artifact has actually been captured. Set it to `collected` only after selecting the source System, attaching or referencing the result, and recording the source, date, classification, and collector. Set it to `verified` only after another named person checks it.
+
 ## Create evidence
 
 1. Run `npx filegrc guide evidence --json`.
 2. Use one evidence record for one coherent proof item or fixed export.
 3. Put local attachments under `data/evidence/EVIDENCE_ID/` and list their data-relative paths in `filePaths`.
-4. Use `externalReference` only when the file must remain in an approved external system. FileGRC never fetches it.
+4. Use `externalReference` only when the file must remain in an approved external system. filegrc never fetches it.
 5. Link `sourceResourceIds`, `controlIds`, and `auditIds` as applicable. Use `sourceCommit` when the evidence represents repository state.
 6. Name the actual collector. A `verified` record also needs the actual verifier and verification date.
 
@@ -19,7 +21,7 @@ npx filegrc attach EVIDENCE_ID /path/to/source-file --name auditor-facing-name.c
 
 The command never overwrites an existing attachment.
 
-Use `npx filegrc detach EVIDENCE_ID FILE_NAME --yes` when removing a mistaken attachment. FileGRC will not delete an evidence record while local attachments remain.
+Use `npx filegrc detach EVIDENCE_ID FILE_NAME --yes` when removing a mistaken attachment. filegrc will not delete an evidence record while local attachments remain.
 
 For a rendered page capture, record the route, filters, audit period, exact Git commit, capture time and method, source resource IDs, and screenshot. A current screenshot cannot prove an earlier state unless it is rendered from or bound to that revision.
 

package/template/data/obligation-events/AGENTS.md

@@ -1,13 +1,13 @@
 # Policy Event Instructions
 
-Do not create an `obligation-event` or its action items by hand. Start the configured checklist:
+Do not create an `obligation-event` or its Action Items by hand. Preview the configured Policy Event, then trigger its work:
 
 ```sh
 npx filegrc obligations --json
 npx filegrc trigger EVENT_TYPE --occurred-on YYYY-MM-DD --subject RESOURCE_ID --json
 ```
 
-Use `--occurred-at` with an RFC 3339 timestamp when any action has an hour-based deadline. The command creates the event and full action checklist atomically.
+The obligations output lists every task the trigger will add, with its owner, deadline, and requested proof. Use `--occurred-at` with an RFC 3339 timestamp when any action has an hour-based deadline. The trigger creates the event and adds all Action Items to the Work Queue atomically, then reports the event, task count, task IDs, and deadlines.
 
 Complete each action with the requested resource type and proof. Then close the workflow:
 
@@ -15,4 +15,4 @@ Complete each action with the requested resource type and proof. Then close the
 npx filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD
 ```
 
-FileGRC refuses to close an event with unfinished or unproved actions. Cancel an event only when the triggering event itself was entered in error or did not occur; explain the reason in related records or the commit message.
+filegrc refuses to close an event with unfinished or unproved actions. Cancel an event only when the triggering event itself was entered in error or did not occur; explain the reason in related records or the commit message.

package/template/data/obligations/AGENTS.md

@@ -5,7 +5,8 @@ An obligation is a reusable policy schedule or event template. It is not the rec
 - Calendar obligations need a valid recurrence anchor, owners, expected completion types, and policy or control links.
 - Event obligations need a stable lowercase `eventType`, a prompt, owners, expected completion types, and an explicit deadline window.
 - Keep completed occurrences in `completionResourceIds`. Do not replace prior links when a new period starts.
+- Keep starter obligations as proposals until every governing policy is active and effective and, when the obligation names controls, at least one linked control is implemented.
 - When an approved cadence changes, update the policy, control, and obligation together.
 - Pause or retire a template only when the underlying policy work no longer applies. Do not delete historical templates that explain prior periods.
 
-Use `npx filegrc obligations --json` to inspect calculated work. Use `npx filegrc complete OBLIGATION_ID completion-mutation.json` to create and link a dated occurrence in one validated write.
+Use `npx filegrc obligations --json` to inspect calculated recurring work and preview every Policy Event task, owner, deadline, and requested proof. Use `npx filegrc complete OBLIGATION_ID completion-mutation.json` to create and link a dated occurrence in one validated write. Use `npx filegrc trigger EVENT_TYPE ...` only after the matching event occurs; it adds all configured Action Items to the Work Queue atomically.

package/template/data/people/person-policy-owner.json

@@ -4,7 +4,7 @@
   "type": "person",
   "title": "{{policy_owner_name}}",
   "status": "active",
-  "email": "{{security_contact_email}}",
+  "email": "{{policy_owner_email}}",
   "role": "Policy Owner",
   "teamIds": ["team-security-risk-oversight"]
 }

package/template/data/policies/AGENTS.md

@@ -2,7 +2,7 @@
 
 Policies state required behavior. Controls, obligations, training, attestations, and evidence show how the organization applies that behavior.
 
-Use the `content` Markdown slot for the policy text. Keep ownership and approval metadata in JSON. The approver must be separate from the owner, including through team membership, and must not operate the controls they review.
+Use the `content` Markdown slot for the policy text. Keep ownership and approval metadata in JSON. The approver must be separate from the owner, including through team membership. The reviewer will usually be another leader or manager in the organization, but may be external.
 
 Keep a policy `draft` until its text, owner, scope, related requirements and controls, approval, effective date, review cadence, and acknowledgement requirement match actual practice. When activating it:
 
@@ -12,4 +12,6 @@ Keep a policy `draft` until its text, owner, scope, related requirements and con
 4. Update or create its recurring and event obligations.
 5. Assign training or attestations when the policy requires them.
 
+The independent policy approver is a management reviewer, not the CPA auditor. Appoint the reviewer during policy adoption. Recurring and event obligations linked to the policy remain proposals until the policy is active and effective and, when they name controls, at least one linked control is implemented.
+
 For a material revision, preserve Git history, obtain a new approval, and require a new acknowledgement when the audience’s responsibilities changed. Do not reuse the audit firm as a management approver without confirming independence.

package/template/data/policies/policy-anti-bribery-corruption.json

@@ -5,7 +5,6 @@
   "title": "Anti-Bribery and Corruption Policy",
   "status": "draft",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "policyKind": "corporate-conduct",
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",

package/template/data/policies/policy-clear-desk-screen.json

@@ -5,7 +5,6 @@
   "title": "Clear Desk and Clear Screen Policy",
   "status": "draft",
   "ownerIds": ["person-policy-owner"],
-  "approverIds": ["person-independent-approver"],
   "policyKind": "information-security",
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",