filegrc 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 FileGRC contributors
+Copyright (c) 2026 filegrc contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
-# FileGRC
+# filegrc
 
-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.
+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.
 
-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.
+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.
 
 Most users should create a complete workspace:
 
@@ -27,6 +27,7 @@ npx filegrc references risk-example --json
 npx filegrc describe risk
 npx filegrc search "access review"
 npx filegrc evidence-test-drafts
+npx filegrc program-readiness --summary --json
 npx filegrc program-readiness --require-ready
 npx filegrc audit-readiness audit-id
 npx filegrc prepare-audit audit-id
@@ -35,17 +36,17 @@ npx filegrc evidence-packet --start 2026-01-01 --end 2026-06-30 --audit audit-id
 
 `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.
 
-`filegrc setup` provides the headless equivalent of browser onboarding. It accepts all initial service-boundary fields and a management program goal as flags or a JSON payload. Selecting Type 1 or Type 2 updates the workspace goal and program scope. It does not create an audit record.
+`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. Selecting Type 1 or Type 2 updates the workspace goal and program scope. It does not create an audit record.
 
 `filegrc program-path` gives agents the renderer’s six-step order, exact page Instructions, Use, Policy Basis, commands, current state, and next actions. `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. Use `--require-ready` in automation. The command does not require an audit ID or CPA firm.
+`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` creates missing draft tests for external evidence that does not already have a dedicated Step 5 record. When a Step 5 operating record exists, put the fixed artifact in an External Evidence record and link it from that operating record. Completing browser or CLI onboarding runs the same operation automatically.
 
 `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.
+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.
 
@@ -53,7 +54,7 @@ Use `filegrc attach <evidence-id> <source-file>` to copy a fixed evidence file u
 
 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. Browser commits are explicit. Without a remote they remain local; with a remote the browser commits and pushes together. Browser pulls use rebase. 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. Browser commits are explicit. Without a remote they remain local; with a remote the browser commits and pushes together. Browser pulls use rebase. 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/v1.json

@@ -1,6 +1,6 @@
 {
   "modelVersion": "1",
-  "title": "FileGRC data model",
+  "title": "filegrc data model",
   "description": "Stable, query-worthy GRC metadata. Long-form work is stored as implicit Markdown companion files beside each structured JSON record.",
   "recordContent": {
     "slot": "record",
@@ -29,19 +29,19 @@
   },
   "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":"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":"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":"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."}
   ],
   "commonFields": {
     "schemaVersion": {"type":"integer","required":true,"const":1,"label":"Schema version"},
@@ -106,7 +106,7 @@
       "singleton": "renderer.json",
       "description": "Optional local interface settings, including onboarding visibility and manually completed Step pages. Renderer settings are not required for SOC 2 and do not change compliance records.",
       "guidance": {
-        "policyBasis": "Renderer settings are a FileGRC convenience, not a SOC 2 requirement, control, audit record, or substitute for evidence.",
+        "policyBasis": "Renderer settings are a filegrc convenience, not a SOC 2 requirement, control, audit record, or substitute for evidence.",
         "cadence": "Change it when the team wants to rerun or suppress an optional renderer workflow, then review and commit the resulting diff."
       },
       "required": ["showOnboarding"],
@@ -262,7 +262,7 @@
       "pluralTitle": "Documents",
       "group": "governance",
       "collection": "documents",
-      "description": "Governed plans, charters, procedures, standards, reports, and templates that are not Policies or another FileGRC record type. A general document catalog is not required for SOC 2.",
+      "description": "Governed plans, charters, procedures, standards, reports, and templates that are not Policies or another filegrc record type. A general document catalog is not required for SOC 2.",
       "guidance": {
         "policyBasis": "Policies rely on governed documents for detailed plans, procedures, charters, and reports. Git preserves the approved text and its revision history.",
         "cadence": "Follow each record's review cadence. Starter governed documents are reviewed at least annually and after material changes or use, with an approver who is separate from the owner.",
@@ -274,7 +274,7 @@
         "status": {"type":"enum","values":["draft","active","superseded","retired"],"filter":true},
         "documentKind": {"type":"string","filter":true},
         "template": {"type":"boolean","filter":true},
-        "approverIds": {"type":"array","items":"id","relation":["person","team"],"disjointFrom":"ownerIds"},
+        "approverIds": {"type":"array","items":"id","relation":["person","team"],"disjointFrom":"ownerIds","requiredWhen":{"status":"active"}},
         "version": {"type":"string"},
         "effectiveOn": {"type":"date","requiredWhen":{"status":"active"}},
         "approvedOn": {"type":"date","requiredWhen":{"status":"active"}},
@@ -299,10 +299,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 5 records created in filegrc do not need a separate record here. Step 6 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.",
+        "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.",
         "sourceResourceIds": ["policy-information-security","policy-data-protection-handling"]
       },
       "required": ["status","evidenceKind"],
@@ -351,7 +351,7 @@
       "collection": "obligations",
       "description": "Reusable schedules for recurring or event-driven work. Obligations feed the Work Queue; completion records and linked Evidence prove that the work occurred. Obligations are not required for SOC 2.",
       "guidance": {
-        "policyBasis": "FileGRC uses Obligations to turn policy and control cadence into owned, dated work linked to its scope and required proof.",
+        "policyBasis": "filegrc uses Obligations to turn policy and control cadence into owned, dated work linked to its scope and required proof.",
         "cadence": "Treat starter work as proposed until every governing policy is active and effective and, when the obligation names controls, at least one linked control is implemented. Then use the recurrence and activation date, and create a separate completion record for every period.",
         "sourceResourceIds": ["policy-information-security","policy-data-protection-handling","document-business-continuity-disaster-recovery"]
       },
@@ -406,7 +406,7 @@
       "collection": "frameworks",
       "description": "Published criteria sets and versions used to define the program and audit scope.",
       "guidance": {
-        "policyBasis": "The CPA examination uses the selected Framework. FileGRC’s starter references provide orientation but do not replace the publisher’s official criteria.",
+        "policyBasis": "The CPA examination uses the selected Framework. filegrc’s starter references provide orientation but do not replace the publisher’s official criteria.",
         "cadence": "Add or retire a version only through a deliberate scope decision. Reconfirm the selected version when planning each audit."
       },
       "required": ["status","version"],
@@ -503,7 +503,7 @@
       "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.",
       "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 sources, and implementation date. 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"]
       },
@@ -678,10 +678,10 @@
         "sourceResourceIds": ["policy-information-security"],
         "obligationActivityTypes": ["policy-review"]
       },
-      "required": ["status","ownerIds","approverIds"],
+      "required": ["status","ownerIds"],
       "fields": {
         "status": {"type":"enum","values":["draft","in-review","approved","active","superseded","retired"],"filter":true},
-        "approverIds": {"type":"array","items":"id","relation":["person","team"],"disjointFrom":"ownerIds"},
+        "approverIds": {"type":"array","items":"id","relation":["person","team"],"disjointFrom":"ownerIds","requiredWhen":{"status":["in-review","approved","active"]}},
         "policyNumber": {"type":"string","search":true},
         "policyKind": {"type":"string","filter":true},
         "version": {"type":"string"},

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "filegrc",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Sunpeak-AI/FileGRC.git"
+    "url": "git+https://github.com/Sunpeak-AI/filegrc.git"
   },
   "type": "module",
   "bin": {

package/src/audit-preparation.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { createResource, createResources, deleteResource, updateResource } from "./files.js";
 import { createResourceId } from "./id.js";
+import { partiesIndependent } from "./parties.js";
 import { resolveDataPath } from "./paths.js";
 import { assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
@@ -550,7 +551,7 @@ function evidenceStage(audit, records, byId, model) {
   const evidenceFamiliesFor = (control) => (model.evidenceSourceFamilies || []).filter((family) => (
     (family.controlCodes || []).includes(control.code)
   ));
-  const fileGRCRecords = records.filter((record) => (
+  const filegrcRecords = records.filter((record) => (
     !NON_EVIDENCE_RECORD_TYPES.has(record.type)
     && controlIdsForRecord(record, byId).size
     && recordRelevantToAuditDate(record, audit, model)
@@ -558,7 +559,7 @@ function evidenceStage(audit, records, byId, model) {
   const managedControls = controls.filter((control) => managedFamilies.some((family) => (
     (family.controlCodes || []).includes(control.code)
   )));
-  const controlsWithFileGRCRecords = managedControls.filter((control) => fileGRCRecords.some((record) => (
+  const controlsWithFilegrcRecords = managedControls.filter((control) => filegrcRecords.some((record) => (
     controlIdsForRecord(record, byId).has(control.id)
   )));
   const externalControls = controls.filter((control) => externalFamilies.some((family) => (
@@ -570,12 +571,12 @@ function evidenceStage(audit, records, byId, model) {
   const items = [
     item(
       "filegrc-evidence",
-      managedControls.length && controlsWithFileGRCRecords.length === managedControls.length ? "complete" : managedControls.length ? "action" : "info",
-      "Review FileGRC Evidence",
+      managedControls.length && controlsWithFilegrcRecords.length === managedControls.length ? "complete" : managedControls.length ? "action" : "info",
+      "Review filegrc Evidence",
       managedControls.length
-        ? `${controlsWithFileGRCRecords.length} of ${managedControls.length} selected controls that use FileGRC workflows have a dated operating record for the formal period. Complete each Step 5 record, link it to the control, and add results in its structured fields or Markdown.`
-        : "No selected controls use a dedicated FileGRC operating record.",
-      fileGRCRecords[0] || { type: managedFamilies[0]?.operationRecordTypes?.[0] || "control" }
+        ? `${controlsWithFilegrcRecords.length} of ${managedControls.length} selected controls that use filegrc workflows have a dated operating record for the formal period. Complete each Step 5 record, link it to the control, and add results in its structured fields or Markdown.`
+        : "No selected controls use a dedicated filegrc operating record.",
+      filegrcRecords[0] || { type: managedFamilies[0]?.operationRecordTypes?.[0] || "control" }
     ),
     item(
       "external-evidence",
@@ -600,7 +601,7 @@ function evidenceStage(audit, records, byId, model) {
       continue;
     }
     if (source.collectionTestRequired === false) {
-      const sourceRecords = fileGRCRecords.filter((record) => (
+      const sourceRecords = filegrcRecords.filter((record) => (
         relevantControls.some((control) => controlIdsForRecord(record, byId).has(control.id))
       ));
       const coveredControls = relevantControls.filter((control) => sourceRecords.some((record) => (
@@ -611,7 +612,7 @@ function evidenceStage(audit, records, byId, model) {
         coveredControls.length === relevantControls.length ? "complete" : "action",
         source.title,
         coveredControls.length === relevantControls.length
-          ? `${sourceRecords.length} dated FileGRC ${sourceRecords.length === 1 ? "record" : "records"} cover ${relevantControls.length} mapped controls. External artifacts needed to support those results are linked from the operating records.`
+          ? `${sourceRecords.length} dated filegrc ${sourceRecords.length === 1 ? "record" : "records"} cover ${relevantControls.length} mapped controls. External artifacts needed to support those results are linked from the operating records.`
           : `${coveredControls.length} of ${relevantControls.length} mapped controls have a dated ${source.operationRecordTypes.map(displayValue).join(" or ")} record for the formal period. Complete the Step 5 work and attach or reference any supporting external artifact on that record.`,
         sourceRecords[0] || { type: source.operationRecordTypes[0] }
       ));
@@ -640,7 +641,7 @@ function evidenceStage(audit, records, byId, model) {
         || { type: "system" }
     ));
   }
-  return stage("evidence", "Audit Evidence", "Review both evidence paths: dated FileGRC operating records and verified External Evidence from authoritative systems. FileGRC includes both in the audit packet.", items);
+  return stage("evidence", "Audit Evidence", "Review both evidence paths: dated filegrc operating records and verified External Evidence from authoritative systems. filegrc includes both in the audit packet.", items);
 }
 
 function populationsStage(audit, records, byId, model) {
@@ -676,11 +677,11 @@ function populationsStage(audit, records, byId, model) {
 }
 
 function auditorStage() {
-  return stage("auditor", "Fieldwork and Report", "FileGRC prepares the record set but does not make the CPA firm's independent judgments.", [
+  return stage("auditor", "Fieldwork and Report", "filegrc prepares the record set but does not make the CPA firm's independent judgments.", [
     item("firm-eligibility", "external", "Firm eligibility and independence", "Confirm directly with the engagement partner that the firm and signing practitioner meet applicable licensing, peer-review, ethics, and independence requirements. Keep the signed engagement terms with the audit record if management needs a copy."),
     item("sampling", "external", "Sample selection and independent testing", "The auditor chooses samples, performs tests, evaluates exceptions, and decides whether more work is needed."),
     item("report", "external", "Report and opinion", "Management reviews and signs its representations. The auditor issues the final report and opinion."),
-    item("criteria", "external", "Authoritative criteria and examination guidance", "FileGRC stores reference IDs and orientation text. Use the publisher's current official criteria and the engagement team's examination guidance for scope, evaluation, and reporting.")
+    item("criteria", "external", "Authoritative criteria and examination guidance", "filegrc stores reference IDs and orientation text. Use the publisher's current official criteria and the engagement team's examination guidance for scope, evaluation, and reporting.")
   ]);
 }
 
@@ -946,30 +947,6 @@ function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-function partiesIndependent(ownerIds, approverIds, byId) {
-  const owners = partyPeople(ownerIds, byId);
-  const approvers = partyPeople(approverIds, byId);
-  return owners.size > 0
-    && approvers.size > 0
-    && ![...owners].some((id) => approvers.has(id));
-}
-
-function partyPeople(ids = [], byId, seen = new Set()) {
-  const people = new Set();
-  for (const id of ids) {
-    if (seen.has(id)) continue;
-    seen.add(id);
-    const record = byId.get(id);
-    if (record?.type === "person") people.add(id);
-    if (record?.type === "team") {
-      for (const personId of partyPeople([...(record.memberIds || []), ...(record.chairIds || [])], byId, seen)) {
-        people.add(personId);
-      }
-    }
-  }
-  return people;
-}
-
 function auditSummary(audit) {
   return {
     id: audit.id,

package/src/cli.js

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { loadModel } from "../model/index.js";
 import { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldResourceMutation } from "./agent.js";
 import { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
@@ -42,6 +43,7 @@ const BOOLEAN_FLAGS = new Set([
   "mutation",
   "preview",
   "require-ready",
+  "summary",
   "write-docs",
   "yes"
 ]);
@@ -60,7 +62,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       host: flags.host ?? process.env.FILEGRC_HOST,
       port: flags.port ?? process.env.FILEGRC_PORT
     });
-    console.log(`FileGRC workspace: ${result.url}`);
+    console.log(`filegrc workspace: ${result.url}`);
     console.log(`Data: ${result.root}/data`);
     return await new Promise((resolvePromise) => {
       const stop = () => result.server.close(resolvePromise);
@@ -70,7 +72,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "setup") {
     const payload = positionals[0] ? await readSetupPayload(positionals[0]) : {};
-    const result = await setupWorkspace(root, {
+    const setupInput = await completeInteractiveSetup(root, {
       ...payload,
       ...(flags["service-name"] !== undefined ? { serviceName: flags["service-name"] } : {}),
       ...(flags.boundary !== undefined ? { boundary: flags.boundary } : {}),
@@ -81,6 +83,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       ...(flags["program-goal"] !== undefined ? { programGoal: flags["program-goal"] } : {}),
       ...(flags.draft ? { draft: true } : {})
     });
+    const result = await setupWorkspace(root, setupInput);
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else {
       console.log(`${result.draft ? "Saved draft scope" : "Completed initial setup"} for ${result.system.title}.`);
@@ -226,7 +229,15 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (command === "program-readiness") {
     const loaded = await loadWorkspace(root);
     const result = await assessProgramReadiness(loaded, { asOf: flags["as-of"] });
-    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    const output = flags.summary ? summarizeProgramReadiness(result) : result;
+    if (flags.json) console.log(JSON.stringify(output, null, 2));
+    else if (flags.summary) {
+      console.log(`${result.status.toUpperCase()}: ${result.progress.complete} of ${result.progress.total} program items complete`);
+      for (const stage of output.stages) {
+        console.log(`${stage.status.toUpperCase()}\t${stage.title}\t${stage.counts.action} actions`);
+      }
+      if (output.firstAction) console.log(`Next: ${output.firstAction.title}\t${output.firstAction.message}`);
+    }
     else {
       console.log(`${result.status.toUpperCase()}: ${result.progress.complete} of ${result.progress.total} program items complete`);
       console.log(`${result.target.label}${result.target.candidatePeriodStart ? `, candidate period starts ${result.target.candidatePeriodStart}` : ""}`);
@@ -239,7 +250,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       }
     }
     if (flags["require-ready"] && !result.evidenceReady) process.exitCode = 2;
-    return result;
+    return output;
   }
   if (command === "evidence-test-drafts") {
     const result = await ensureEvidenceTestDrafts(root);
@@ -554,6 +565,56 @@ async function readSetupPayload(path) {
   return parsed;
 }
 
+async function completeInteractiveSetup(root, payload) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return payload;
+  const loaded = await loadWorkspace(root);
+  const activePeople = loaded.resources.filter(({ type, status }) => type === "person" && status === "active");
+  if (!activePeople.length) throw new Error("Setup requires at least one active person who can own the service.");
+  const classifications = Object.keys(loaded.workspace.classificationDefinitions || {});
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  const result = { ...payload };
+  const askRequired = async (label, defaultValue = "") => {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    let value = "";
+    while (!value) value = (await prompt.question(`${label}${suffix}: `)).trim() || defaultValue;
+    return value;
+  };
+  const askChoice = async (label, choices, defaultValue = "") => {
+    let value = "";
+    while (!choices.includes(value)) {
+      value = await askRequired(`${label} (${choices.join("/")})`, defaultValue);
+    }
+    return value;
+  };
+  try {
+    result.serviceName ||= await askRequired(
+      "Service name",
+      loaded.workspace.organizationName ? `${loaded.workspace.organizationName} service` : ""
+    );
+    result.boundary ||= await askRequired("Service boundary");
+    result.ownerId ||= await askChoice(
+      "Service owner ID",
+      activePeople.map(({ id }) => id),
+      activePeople[0].id
+    );
+    result.criticality ||= await askChoice("Criticality", ["low", "medium", "high", "critical"], "high");
+    result.dataClassification ||= classifications.length
+      ? await askChoice(
+        "Data classification",
+        classifications,
+        classifications.includes("Confidential") ? "Confidential" : classifications[0]
+      )
+      : await askRequired("Data classification");
+    if (result.internetExposed === undefined) {
+      result.internetExposed = (await askChoice("Internet exposed", ["yes", "no"])) === "yes";
+    }
+    result.programGoal ||= await askChoice("Program goal", ["none", "readiness", "type-1", "type-2"]);
+  } finally {
+    prompt.close();
+  }
+  return result;
+}
+
 async function readTextInput(path) {
   if (path === true || !path) throw new Error("Pass --write <markdown-file|->.");
   return path === "-" ? readStdin() : readFile(resolve(String(path)), "utf8");
@@ -576,7 +637,7 @@ async function printVersion() {
 }
 
 function printHelp() {
-  console.log(`FileGRC - Git-native GRC workspace
+  console.log(`filegrc - Git-native GRC workspace
 
 Usage:
   filegrc serve [root] [--host 127.0.0.1] [--port 8787]
@@ -592,7 +653,7 @@ Usage:
   filegrc list [resource-type] [--json]
   filegrc search <query> [--type resource-type] [--json]
   filegrc obligations [--as-of YYYY-MM-DD] [--from YYYY-MM-DD] [--through YYYY-MM-DD] [--now RFC3339] [--complete] [--json]
-  filegrc program-readiness [--as-of YYYY-MM-DD] [--require-ready] [--json]
+  filegrc program-readiness [--as-of YYYY-MM-DD] [--require-ready] [--summary] [--json]
   filegrc evidence-test-drafts [--json]
   filegrc audit-readiness [audit-id] [--require-ready] [--json]
   filegrc prepare-audit <audit-id> [--json]
@@ -634,7 +695,8 @@ Safety:
   filegrc setup [setup.json|-] [options]
 
 Create or update the initial service boundary through the same validated operation
-used by browser onboarding. JSON keys use the camelCase forms shown below.
+used by browser onboarding. Run without input in an interactive terminal for guided
+setup. JSON keys use the camelCase forms shown below.
 
 Options:
   --service-name <name>       serviceName
@@ -662,6 +724,7 @@ is required.
 Options:
   --as-of <date>     Evaluate effective dates and obligations on YYYY-MM-DD
   --require-ready    Exit with code 2 unless the Evidence Ready gate passes
+  --summary          Omit item details and print stage counts and next actions
   --json             Print the result as JSON
   --root <path>      Workspace path
   --help             Show this help`);
@@ -860,6 +923,41 @@ function printProgramPath(result) {
   }
 }
 
+function summarizeProgramReadiness(result) {
+  const summarizeItem = (item) => item ? {
+    id: item.id,
+    status: item.status,
+    title: item.title,
+    message: item.message,
+    ...(item.resourceType ? { resourceType: item.resourceType } : {}),
+    ...(item.resourceId ? { resourceId: item.resourceId } : {})
+  } : null;
+  return {
+    schemaVersion: result.schemaVersion,
+    generatedAt: result.generatedAt,
+    asOf: result.asOf,
+    status: result.status,
+    evidenceReady: result.evidenceReady,
+    operating: result.operating,
+    canStartCandidatePeriod: result.canStartCandidatePeriod,
+    suggestedCandidatePeriodStart: result.suggestedCandidatePeriodStart,
+    target: result.target,
+    progress: result.progress,
+    counts: result.counts,
+    scopeCounts: Object.fromEntries(
+      Object.entries(result.scope).map(([name, ids]) => [name.replace(/Ids$/, ""), ids.length])
+    ),
+    firstAction: summarizeItem(result.firstAction),
+    stages: result.stages.map((stage) => ({
+      id: stage.id,
+      title: stage.title,
+      status: stage.status,
+      counts: stage.counts,
+      firstAction: summarizeItem(stage.items.find(({ status }) => status === "action"))
+    }))
+  };
+}
+
 function eventWindowText(window) {
   if (Number.isInteger(window?.endOffsetHours)) {
     return window.endOffsetHours === 0 ? "due at event time" : `due within ${window.endOffsetHours} hours`;