create-filegrc 0.3.4 → 0.5.0

package/src/index.js

@@ -10,7 +10,7 @@ const execute = promisify(execFile);
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const textExtensions = new Set(["", ".json", ".md", ".txt", ".yml", ".yaml", ".gitignore"]);
 const STARTER_PROFILES = new Set(["foundation", "security"]);
-const SECURITY_TEMPLATE_COLLECTIONS = new Set(["documents", "policies", "training"]);
+const SECURITY_TEMPLATE_COLLECTIONS = new Set(["collection-reviews", "documents", "policies", "training"]);
 
 export async function createFilegrc(options = {}) {
   const parameterConfig = JSON.parse(await readFile(join(packageRoot, "template-parameters.json"), "utf8"));
@@ -29,7 +29,7 @@ export async function createFilegrc(options = {}) {
   const starterText = starterTemplateText(starter, prompted.company_name);
   const values = {
     ...prompted,
-    effective_date: options.effectiveDate ?? new Date().toISOString().slice(0, 10),
+    effective_date: options.effectiveDate ?? calendarDateInTimezone(prompted.timezone),
     project_name: normalizePackageName(basename(target)),
     filegrc_version: engine.version,
     filegrc_version_range: engine.dependency,
@@ -74,6 +74,16 @@ export async function createFilegrc(options = {}) {
   };
 }
 
+function calendarDateInTimezone(timezone, date = new Date()) {
+  const values = Object.fromEntries(new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(date).map(({ type, value }) => [type, value]));
+  return `${values.year}-${values.month}-${values.day}`;
+}
+
 export function normalizeStarterProfile(value = "security") {
   const profile = String(value || "security").trim().toLowerCase();
   const normalized = profile === "empty" ? "foundation" : profile === "soc2-security" ? "security" : profile;
@@ -172,6 +182,7 @@ async function resolvePromptValues(parameters, options) {
   const mapped = {
     company_name: options.companyName,
     policy_owner_name: options.policyOwnerName,
+    policy_owner_job_title: options.policyOwnerJobTitle,
     policy_owner_email: options.policyOwnerEmail,
     security_contact_email: options.securityContactEmail,
     timezone: options.timezone
@@ -179,6 +190,7 @@ async function resolvePromptValues(parameters, options) {
   if (options.yes) {
     mapped.company_name ??= "Example Company";
     mapped.policy_owner_name ??= "Security Owner";
+    mapped.policy_owner_job_title ??= "Chief Executive Officer";
     mapped.security_contact_email ??= "security@example.com";
   }
   for (const key of Object.keys(mapped)) {
@@ -208,7 +220,7 @@ async function resolvePromptValues(parameters, options) {
   if (missing.length) {
     throw new Error(`Missing required values: ${missing.map(({ key }) => key).join(", ")}`);
   }
-  for (const key of ["company_name", "policy_owner_name"]) {
+  for (const key of ["company_name", "policy_owner_name", "policy_owner_job_title"]) {
     if (/[\u0000-\u001f\u007f]/.test(mapped[key])) {
       throw new Error(`${key} must be a single line without control characters.`);
     }
@@ -372,7 +384,7 @@ async function summarizeResources(target) {
   for (const path of await collectFiles(join(target, "data"))) {
     if (extname(path) !== ".json") continue;
     const record = JSON.parse(await readFile(path, "utf8"));
-    if (!record?.id || !record?.type || !record?.schemaVersion) continue;
+    if (!record?.id || !record?.type) continue;
     total += 1;
     counts[record.type] = (counts[record.type] || 0) + 1;
   }
@@ -394,7 +406,7 @@ async function applyStarterScope(target, starter, effectiveDate) {
 }
 
 function starterStages(starter, counts) {
-  const foundationTypes = new Set(["workspace", "renderer-settings", "person", "team", "system"]);
+  const foundationTypes = new Set(["workspace", "renderer-settings", "person", "appointment", "team", "system"]);
   const foundation = Object.entries(counts.byType)
     .filter(([type]) => foundationTypes.has(type))
     .reduce((total, [, count]) => total + count, 0);
@@ -418,11 +430,12 @@ function starterTemplateText(starter, companyName) {
       agent_purpose: `This repository is ${companyName}’s foundation filegrc workspace. Engineers and agents maintain the source records under \`data/\`. The \`filegrc\` package validates, searches, edits, and renders those files. No framework or assurance program has been selected yet.`,
       starter_baseline: `## Foundation baseline
 
-The generated workspace starts with five structural records:
+The generated workspace starts with foundational program records:
 
 - Workspace and renderer settings
 - The initial active owner
-- An inactive security and risk oversight team that still needs an independent chair
+- The two core Appointment records: an active Policy Owner plus a planned Independent Policy Reviewer assignment. Create another Appointment only when management actually delegates a named responsibility.
+- A planned security and risk oversight team that still needs an independent chair
 - The filegrc Git repository as a governance system of record
 - A default 5x5 risk method and Public, Internal, Confidential, and Restricted data classifications
 
@@ -430,7 +443,7 @@ This profile does not include framework requirements, policies, governed documen
       audit_preparation_guidance: "The foundation profile does not include the local SOC 2 management-document templates used by `prepare-audit`. Add reviewed templates and program scope before initializing audit work. Audit preparation must not invent missing policy, control, or evidence facts.",
       starter_setup: `## Start the program
 
-This foundation profile contains the workspace, initial owner, oversight team, renderer settings, and filegrc system of record. It does not select a framework or create proposed policies, controls, obligations, or evidence.
+This foundation profile contains the workspace, initial owner, core Appointments, oversight team, renderer settings, and filegrc system of record. It does not select a framework or create proposed policies, controls, obligations, or evidence.
 
 1. Run \`npx filegrc setup\` for guided service and goal setup, or use browser onboarding.
 2. Use \`npx filegrc guide --json\` before creating framework requirements, policies, controls, obligations, and evidence sources.
@@ -451,6 +464,7 @@ The generated workspace starts with the SOC 2 Security category:
 - The 33 Common Criteria reference IDs from CC1.1 through CC9.2, without the licensed criteria text
 - The nine Description Criteria reference IDs from DC1 through DC9, without the licensed criteria text
 - Planned controls mapped to those references and the included policies
+- The two core Appointment records. Policy Owner starts active; Independent Policy Reviewer remains Ready until assigned. Program coordination, incident, recovery, executive, legal, privacy, insurance, communications, and audit-coordination functions stay with the Policy Owner unless management delegates one through a custom Appointment.
 - A security and risk oversight team chaired by an independent reviewer who may be internal or external
 - Recurring obligations for the reviews, scans, tests, training, and meetings required by the included policies
 - A default 5x5 risk method and Public, Internal, Confidential, and Restricted data classifications
@@ -465,23 +479,22 @@ The starter policies, controls, and obligations are proposals. They do not state
 
 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. Preview External Evidence drafts with \`npx filegrc evidence-test-drafts --preview --json\`. Create them only after confirming applicable controls and authoritative source systems.
-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.
-6. Engage a CPA firm, record the separate firm-agreed period in an audit record, review filegrc Evidence and External Evidence, and prepare fieldwork.`
+3. Review the starter control set and implement each applicable Control with its actual procedure, scope, cadence, and authoritative evidence source Systems. Confirm every source is active, has the required evidence role and current access owners, and includes repeatable retrieval instructions in Record Markdown. Add the implementation date, confirm any linked Work Queue schedules are enabled, then record any complementary customer or subservice controls.
+4. 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.
+5. Engage a CPA firm, record the separate firm-agreed period in an audit record, review filegrc Evidence and External Evidence, and prepare fieldwork.`
   };
 }
 
 function validateCombinedSetup(setup) {
   if (!setup) return;
   if (Array.isArray(setup) || typeof setup !== "object") throw new Error("setup must be a JSON object.");
-  const required = ["serviceName", "boundary", "criticality", "dataClassification", "internetExposed"];
+  const required = ["serviceName", "boundary", "criticality", "classificationId", "internetExposed"];
   const missing = required.filter((name) => setup[name] === undefined || setup[name] === "");
   if (missing.length) throw new Error(`Combined setup is missing: ${missing.join(", ")}.`);
 }
 
 async function runCombinedSetup(target, input) {
-  const setup = { programGoal: "none", ownerId: "person-policy-owner", ...input };
+  const setup = { programGoal: "none", ownerId: "person-program-lead", ...input };
   const args = [
     join(target, "node_modules", "filegrc", "bin", "filegrc.js"),
     "setup",
@@ -489,7 +502,7 @@ async function runCombinedSetup(target, input) {
     "--boundary", String(setup.boundary),
     "--owner", String(setup.ownerId),
     "--criticality", String(setup.criticality),
-    "--classification", String(setup.dataClassification),
+    "--classification", String(setup.classificationId),
     "--internet-exposed", String(setup.internetExposed),
     "--program-goal", String(setup.programGoal),
     "--summary",
@@ -503,13 +516,13 @@ async function runCombinedSetup(target, input) {
 async function writeMinimalLockfile(target, name, versionRange) {
   const lock = {
     name,
-    version: "0.3.4",
+    version: "0.5.0",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.3.4",
+        version: "0.5.0",
         dependencies: { filegrc: versionRange }
       }
     }

package/template/AGENTS.md

@@ -18,7 +18,7 @@ npx filegrc list person --json
 npx filegrc program-readiness --summary --json
 ```
 
-`program-path --next --json` gives agents the current step and first action. Use `--summary` for all six step statuses or `--current` for the current step’s full renderer Instructions, Use, Policy Basis, commands, and next actions. The general guide lists every supported action and record type. A type guide repeats that page guidance and adds timing, required and conditional fields, current relationship candidates, JSON location, and Markdown slots.
+`program-path --next --json` gives agents the current step and first action. Use `--summary` for all five step statuses or `--current` for the current step’s page summaries, detailed guidance fields, commands, and next actions. The general guide lists every supported action and record type. A type guide adds the checks needed for that resource, including timing, required and conditional fields, current relationship candidates, JSON location, and Markdown slots.
 
 For a new record, generate a mutation envelope:
 
@@ -52,11 +52,25 @@ Read `data/AGENTS.md` before changing records. More specific instructions inside
 - Do not store secrets, credentials, session data, or personal data that may need to be erased from Git history.
 - Keep the editable local server on loopback or behind trusted authentication. Use the read-only static build for audit sharing.
 
+## Source truth and derived workflow
+
+The JSON and Markdown under `data/`, the installed model, policy content, and Git history are the inputs to FileGRC’s shared workflow calculation. Source files hold facts, decisions, relationships, dates, status, and evidence references. They do not each need a copy of the generic audit-readiness instructions or calculated TODO list.
+
+Use `npx filegrc workflow --json` for the complete derived checklist, named readiness assessments, blockers, Work Items, and recommended next action. `guide`, `list --workflow`, `get --workflow`, mutation previews, the HTTP API, and the browser consume the same calculation. Resolve a derived finding by changing its source facts, recording a reviewed applicability decision, accepting an allowed Exception, or completing authoritative assigned work. Never add a separate TODO file or UI-only completion flag for calculated work.
+
+FileGRC marks an item `blocked` only when named prerequisite records must be resolved first. A missing record, editable error, or management decision is `ready` when you can act on it now, even when it prevents a readiness assessment from passing.
+
+An Action Item or Audit Request is a source record because it captures a real assignment, owner, deadline, and completion proof. A Collection Review is also a source record because FileGRC cannot infer that management reviewed an apparently complete or empty collection. `npx filegrc guide RESOURCE_TYPE --json` returns the type-specific review criteria and current confirmation state. Use `npx filegrc review-collection RESOURCE_TYPE --scaffold`, fill the conclusion and reviewer facts, preview it, then apply it with `--yes`. FileGRC calculates the collection revision and marks the confirmation stale after a reviewed record or material scope fact changes.
+
+Other prompts and blockers remain derived. After a direct file edit, run `npm run validate`, `npx filegrc reconcile --preview --json`, and `npx filegrc workflow --json`. Reconciliation reports source transitions that may need a dated Policy Event and linked tasks. It never treats a file diff as proof that a real-world event happened. Apply a candidate only after confirming the event facts. The result must match an equivalent browser or CLI edit.
+
+Run `npm run check:milestone` in CI. Before an assurance goal is selected it checks structural validity. It checks Evidence Readiness after a goal is selected, then Period Health after candidate coverage dates exist.
+
 ## Git is the audit trail
 
 Git supplies file authors, commit timestamps, messages, diffs, and revisions. Do not add fields such as `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, or a second change log.
 
-Domain events still need explicit dates. Keep values such as `occurredOn`, `approvedOn`, `reviewedOn`, `completedOn`, and audit-period dates in their records.
+Domain events still need explicit dates. Keep values such as `occurredOn`, `scheduledFor`, `approvedOn`, `completedOn`, and audit-period dates in their records.
 
 Use a dedicated private repository for your FileGRC workspace. The browser commits and pushes each saved program change, so a standalone repository keeps the compliance audit trail separate from application development history.
 
@@ -69,11 +83,11 @@ Use a dedicated private repository for your FileGRC workspace. The browser commi
 
 New workspaces use trunk repository mode with `main` as the authoritative branch and `origin` as the remote. Each browser mutation checks the whole Git worktree, fetches the remote, fast-forwards only, rechecks the edited revision, writes through the normal domain function, validates the workspace, stages only this FileGRC workspace, creates a focused commit, and pushes it. Browser onboarding commits its related workspace, system, and renderer changes together.
 
-The Repository page reports `Synced`, `Syncing`, `Not synced`, `Read-only checkout`, or `Git setup required`. A failed push keeps the local FileGRC commit and offers Retry sync when every ahead commit changes only this workspace. FileGRC never pushes an ahead commit that includes files outside this workspace, and it never merges, rebases, switches branches, resolves conflicts, or changes files outside the workspace.
+The Repository page reports `Synced`, `Syncing`, `Not synced`, `Read-only checkout`, or `Git setup required`. Browser saves return after the validated local commit, then push in the background. Treat `Syncing` as locally durable but not yet durable on the remote, and wait for `Synced` before starting another write. A failed push keeps the local FileGRC commit and offers Retry sync when every ahead commit changes only this workspace. FileGRC never pushes an ahead commit that includes files outside this workspace, and it never merges, rebases, switches branches, resolves conflicts, or changes files outside the workspace.
 
 Record lifecycle fields are the approval source. Draft, proposed, approved, and retired records may all live on the authoritative branch. Do not use Git branches to represent policy approval.
 
-Existing workspaces without `repositoryMode` remain in manual mode. In manual mode, review the workspace diff and use the Repository controls or Git CLI. Agents and terminal users always own their Git synchronization and should pull, commit, and push directly. FileGRC does not replace repository authentication, authorization, branch protection, or review controls.
+Manual mode requires an explicit `repositoryMode` in `data/renderer.json`. In manual mode, review the workspace diff and use the Repository controls or Git CLI. Agents and terminal users always own their Git synchronization and should pull, commit, and push directly. FileGRC does not replace repository authentication, authorization, branch protection, or review controls.
 
 Use `npx filegrc serve --allow-non-authoritative-writes` only for local development in a task worktree. The override is visible in the UI and never commits or pushes.
 
@@ -83,6 +97,16 @@ Do not rewrite or remove committed records that explain prior audit periods. Clo
 
 `data/workspace.json` selects the model through `dataModelVersion`. The installed `filegrc` package owns the authoritative model. Do not copy or invent a local schema.
 
+If the installed CLI reports that this workspace uses an unsupported model, start with:
+
+```sh
+npx filegrc migrate --to-model 3 --preview --json
+```
+
+Model v1 workspaces migrate to v2 first. Review the v3 preview’s automatic, review-required, and unsupported classifications before applying it with the same options and `--yes`. The migration creates no approvals, holders, evidence, or historical dates.
+
+The [model v3 upgrade guide](https://github.com/Sunpeak-AI/filegrc/blob/main/docs/upgrading-to-model-v3.md) explains the classifications, automatic changes, and required post-migration review.
+
 Run these commands when working with records:
 
 ```sh
@@ -108,14 +132,16 @@ Headless agents get the same protection by exporting an edit payload with `fileg
 
 ## Renderer settings and onboarding
 
-`data/renderer.json` stores committed renderer and repository preferences. New workspaces set `showOnboarding` to `true`, `repositoryMode` to `trunk`, `authoritativeBranch` to `main`, and `repositoryRemote` to `origin`. In trunk mode, completing or skipping onboarding commits and pushes the related change. Existing settings without `repositoryMode` keep manual behavior.
+`data/renderer.json` stores committed renderer and repository preferences. New workspaces set `showOnboarding` to `true`, `repositoryMode` to `trunk`, `authoritativeBranch` to `main`, and `repositoryRemote` to `origin`. In trunk mode, completing or skipping onboarding commits the related change and starts its background push.
 
-Onboarding explains the file and Git workflow, the program path, policy obligations, and Policy Events before covering report types and the final audit stage. It then collects the initial service boundary, owner, business criticality, highest data classification, internet exposure, and optional program goal. It creates or updates one `system` record and stores that selected system and the management goal on `workspace`. It does not select framework records, link controls to the service, or create evidence. Selecting Type 1 or Type 2 does not create an audit engagement. Completing onboarding opens the Step 1 overview so the user can add the real reviewers and operators, finish the oversight team, and confirm the criteria, commitments, vendors, and systems before approving policies.
+Onboarding explains the file and Git workflow, the program path, policy obligations, and Policy Events before covering report types and the final audit stage. It then collects the initial service boundary, owner, business criticality, highest data classification, internet exposure, and optional program goal. It creates or updates one `system` record, stores that selected system and the management goal on `workspace`, and creates one planned service-commitment prompt. Replace that prompt with the actual customer promise or approved service requirement before activation. Onboarding does not link controls to the service or create evidence. Selecting Type 1 or Type 2 does not create an audit engagement. Completing onboarding opens the Step 1 overview so the user can add the real reviewers and operators, finish the oversight team, and confirm the criteria, commitments, vendors, and systems before approving policies.
 
 The renderer is optional. Agents may set `showOnboarding` to `false` and maintain all records headlessly. Restart onboarding from Repository when useful. Read-only builds never run it.
 
 {{starter_baseline}}
 
+Review all criteria against the actual service boundary in one explicit batch. Run `npx filegrc review-applicability --scaffold --type requirement > decisions.json`, fill every decision, then preview with `npx filegrc review-applicability decisions.json --preview --json` and apply the same file with `--yes`. Every decision needs a reviewer, date, and rationale. FileGRC records the current scope revision automatically.
+
 ## Work Queue and Policy Events
 
 Run the same obligation planner used by the web app:
@@ -130,12 +156,14 @@ Work Queue includes recurring obligations, Policy Event tasks, and every other o
 A calendar obligation’s recurrence anchor starts its first allowed cycle. Unless `window` narrows that range, completion is allowed from the cycle start through the day before the next cycle, and the item becomes overdue on the next cycle’s first day. Use **Record work** in Work Queue, or create and link a completion atomically with:
 
 ```sh
+npx filegrc complete obligation-id --scaffold --window-start YYYY-MM-DD --completed-on YYYY-MM-DD > completion-record.json
+# Fill the actual work, evidence, review, and any null or empty required values.
 npx filegrc complete obligation-id completion-record.json
 ```
 
-Keep prior completion links because the planner matches each dated record to its own period.
+The scaffold includes the current obligation revision, so the second command rejects a stale Work Queue write. Keep prior completion links because the planner matches each dated record to its own period.
 
-Event obligations are templates. Do not mark a template complete or replace it for each occurrence. Use Trigger Work on Step 5 or run:
+Event obligations are templates. Do not mark a template complete or replace it for each occurrence. Use Trigger Work on Step 4 or run:
 
 ```sh
 npx filegrc trigger person-started --occurred-on 2026-07-25 --subject person-new-worker --json
@@ -147,11 +175,13 @@ Run `npx filegrc obligations` first to preview every task, owner, deadline, and
 Complete an event action and link its new proof in one validated write:
 
 ```sh
+npx filegrc complete-action action-item-id --scaffold --completed-on 2026-07-25 > completion-record.json
+# Fill the actual work, evidence, review, and any null or empty required values.
 npx filegrc complete-action action-item-id completion-record.json --completed-on 2026-07-25
-npx filegrc complete-event obligation-event-id --completed-on 2026-07-25
+npx filegrc complete-event obligation-event-id --completed-on 2026-07-25 --expected-revision REVISION
 ```
 
-filegrc rejects a completion resource whose type does not match the obligation. It will close the event only after every action has its requested proof.
+Completion scaffolds include the target revision. For other updates, read `REVISION` from `npx filegrc get RESOURCE_ID --mutation`. filegrc rejects a completion resource whose type does not match the obligation. It will close the event only after every action has its requested proof.
 
 ## Headless Markdown
 
@@ -177,11 +207,10 @@ The Evidence Ready gate requires:
 
 1. A management goal, selected systems, criteria, and controls.
 2. Active policies with completed text, separate management approval, real approval and effective dates, and linked controls.
-3. Implemented controls with an owner, actual procedure, scope, cadence, evidence source, mappings, implementation date, and every eligible linked Work Queue schedule running.
-4. Active authoritative systems with evidence source roles, access owners, and repeatable extraction instructions in Record Markdown.
-5. A verified `test-export` or `test-capture` evidence record for each selected control family that relies on evidence from outside filegrc.
+3. Implemented Controls with an owner, actual procedure, scope, operation pattern, mappings, implementation date, and every required linked Work Queue schedule running.
+4. Every selected Control mapped to active authoritative Systems with the required evidence source roles, current access owners, and repeatable extraction instructions in Record Markdown.
 
-Onboarding does not create External Evidence records. After confirming the applicable controls and authoritative source Systems, run `npx filegrc evidence-test-drafts --preview --json` and review the proposed collection tests. Then run `npx filegrc evidence-test-drafts` to create the missing drafts. filegrc-managed records, such as risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings, do not need a separate collection test. Put any fixed external artifact in an External Evidence record and link it from the operating record. For each created draft, choose its authoritative source System, attach or reference the real result, record its collector and classification, then have another person verify it.
+Onboarding does not create External Evidence records. Complete authoritative source Systems as part of Control implementation. For every incomplete family in Program Readiness, update the Control with its authoritative evidence source Systems, then give each source the required evidence role, current access owners, and repeatable retrieval instructions in Record Markdown. Use `npx filegrc evidence-map --json` when you want only those source checks. During Step 4, create External Evidence only when a real artifact exists. Select its source System, attach or reference the result, link the Controls and operating record it supports, record its collector and classification, then have another person verify it before audit use.
 
 When the gate passes, set `workspace.candidatePeriodStart` to the date reliable evidence collection begins. Do not backdate it. `candidatePeriodStart` and `candidatePeriodEnd` express management’s target. They do not establish the final report period.
 
@@ -205,7 +234,7 @@ The audit record’s `typeOneAsOf`, `periodStart`, and `periodEnd` are the dates
 
 Review both evidence paths against the exact firm-agreed date or period:
 
-1. filegrc Evidence consists of dated Step 5 operating records. Complete each applicable record, link it to the Controls it supports, record the result in structured fields or Markdown, and link any external artifact needed to support that result.
+1. filegrc Evidence consists of dated Step 4 operating records. Complete each applicable record, link it to the Controls it supports, record the result in structured fields or Markdown, and link any external artifact needed to support that result.
 2. External Evidence consists of verified `evidence` records from authoritative Systems. Confirm the source System, audit date or period, Control links, collector, verifier, and fixed attachment or approved external reference.
 
 Audit Readiness reports coverage for both paths. The packet includes the matching filegrc records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.
@@ -232,9 +261,18 @@ Link a control test to its `audit-population` record when sampling applies. Link
 
 ## Content and approvals
 
-The seed policy owner is {{policy_owner_name}} at {{policy_owner_email}}, and the security reporting address is {{security_contact_email}}. Replace ownership or contacts when responsibilities change.
+The initial program lead is {{policy_owner_name}}, {{policy_owner_job_title}}, at {{policy_owner_email}}. The separate Policy Owner Appointment records this person’s starting program authority, and the security reporting address is {{security_contact_email}}. Update the Person when their organizational position changes. End and replace Appointments when named authority moves to someone else.
 
-Appoint an independent management reviewer during policy review, not as a condition of defining the service boundary. The reviewer must be separate from the policy owner and able to challenge the owner’s decisions. Most organizations assign another internal leader or manager. An external reviewer is also allowed, and a one-person company needs one because no second internal person is available. The reviewer chairs Security and Risk Oversight and approves policies and governed documents.
+Appoint an independent management reviewer during policy review, not as a condition of defining the service boundary. The reviewer must be separate from the policy owner and able to challenge the owner’s decisions. Assign another internal leader or manager when a suitable reviewer is available. Otherwise, appoint a qualified external reviewer. The reviewer chairs Security and Risk Oversight and approves policies and governed documents.
+
+To appoint an internal reviewer, create or update that Person and set the planned Independent Policy Reviewer Appointment’s `holderId`, scope, start date, responsibilities, and independence rationale before making it active. When no suitable internal reviewer is available, include the reviewer’s real organizational job title, organization, start date, and independence rationale in `reviewer.json`, then preview the external-reviewer bundle before applying it:
+
+```sh
+npx filegrc external-reviewer-setup --scaffold > reviewer.json
+# Replace the null values with the reviewer's current facts and independence rationale.
+npx filegrc external-reviewer-setup reviewer.json --preview --json
+npx filegrc external-reviewer-setup reviewer.json --yes --json
+```
 
 The management reviewer and CPA auditor are different roles. Do not assign the CPA firm management or approval work without first confirming the firm's independence requirements.
 

package/template/README.md

@@ -19,6 +19,8 @@ npm run serve
 
 Requires Node.js 20 or newer and Git.
 
+Existing model v2 workspaces must run `npx filegrc migrate --to-model 3 --preview --json` after installing a model v3 package. Review each automatic, review-required, and unsupported item before applying the same migration with `--yes`. Model v1 workspaces migrate to v2 first. See the [model v3 upgrade guide](https://github.com/Sunpeak-AI/filegrc/blob/main/docs/upgrading-to-model-v3.md).
+
 ## How it works
 
 The repository is the program. There is no separate application database.
@@ -29,28 +31,30 @@ The repository is the program. There is no separate application database.
 
 Use the same source through the local web app, a text editor, the CLI, or CI. Browser and CLI actions call the same rules, so engineers and agents see the same validation and readiness results.
 
-New workspaces use `main` as the authoritative browser branch. Browser saves fetch and fast-forward from `origin`, validate the change, create a focused commit, and push it. Draft, proposed, approved, and retired records all live on that branch because record status, not a Git branch, represents approval.
+New workspaces use `main` as the authoritative browser branch. Browser saves fetch and fast-forward from `origin`, validate the change, and create a focused local commit. The UI then unlocks for navigation while Git push continues in the background. Other writes remain locked until the Repository status confirms `Synced`; a failed push keeps the local commit and offers Retry sync. Draft, proposed, approved, and retired records all live on that branch because record status, not a Git branch, represents approval.
 
-Detached and feature-branch checkouts are read-only in the browser by default. Developers can run `npx filegrc serve --allow-non-authoritative-writes` for local task-worktree edits; that override never commits or pushes. Existing workspaces without `repositoryMode` keep manual browser Git behavior. CLI and agent workflows continue to manage Git explicitly.
+Detached and feature-branch checkouts are read-only in the browser by default. Developers can run `npx filegrc serve --allow-non-authoritative-writes` for local task-worktree edits; that override never commits or pushes. CLI and agent workflows continue to manage Git explicitly.
 
 ## One path from setup to audit
 
 ![filegrc SOC 2 program overview](docs/filegrc-home.png)
 
-1. **Define scope.** Confirm owners, criteria, commitments, vendors, and in-scope systems.
-2. **Approve policies.** Tailor the proposals and record separate owners and reviewers.
-3. **Implement controls.** Add the real procedure, scope, cadence, and evidence source.
-4. **Test evidence collection.** Collect and verify evidence from each authoritative system.
-5. **Operate the program.** Work the queue, trigger Policy Events, maintain risks, and preserve dated evidence.
-6. **Audit.** Record the CPA engagement and agreed period, support fieldwork, and build the packet.
+1. **Define scope.** Set program ownership, choose the criteria, and define the service, Systems, and providers in scope.
+2. **Approve policies.** Turn the starter policy set into approved rules that match how the organization works.
+3. **Implement controls.** Define how each control works, where its evidence comes from, and whether customers or providers have responsibilities.
+4. **Operate the program.** Run scheduled and event-driven work, maintain risk, and retain dated evidence.
+5. **Audit.** Set up the CPA engagement, support fieldwork, and prepare the evidence packet.
+
+Control implementation includes evidence-source readiness. Use `npx filegrc program-readiness --json` to find incomplete Control or System records. `npx filegrc evidence-map --json` remains available as a focused diagnostic. Create External Evidence during Step 4 only when a real export, report, screenshot, signed file, or approved external reference exists.
 
 The Program Overview shows what is done, what is blocked, and what to do next.
 
 ## The routine work stays connected
 
-- **Work Queue** turns policy schedules and follow-up into upcoming, due, and overdue work.
+- **Work Queue** turns policy schedules and follow-up into upcoming, blocked, due, and overdue work, with named blockers when a task cannot proceed.
 - **Policy Events** create the right tasks for hiring, departures, incidents, vendor changes, and other events.
 - **Program Readiness** checks whether management can begin a reliable evidence period.
+- **Period Health** checks role, policy, control, source, obligation, and Git-history continuity across candidate and formal Type 2 dates.
 - **Audit Readiness** checks the engagement, period, documents, evidence, and Type 2 populations.
 - **Evidence packets** collect the scoped records, attachments, history, indexes, and checksums for delivery.
 
@@ -64,11 +68,18 @@ The browser is helpful, but it is not required. An agent can discover the model,
 
 ```sh
 npx filegrc program-path --next --json
+npx filegrc workflow --json
+npx filegrc reconcile --preview --json
+npx filegrc period-health --require-healthy --json
+npx filegrc review-applicability decisions.json --preview --json
+npx filegrc review-collection person --scaffold
 npx filegrc guide risk-assessment --json
 npx filegrc obligations --json
+npx filegrc complete OBLIGATION_ID --scaffold --window-start YYYY-MM-DD --completed-on YYYY-MM-DD
 npx filegrc program-readiness --summary --json
 npx filegrc audit-readiness audit-id --json
 npx filegrc evidence-packet --audit audit-id
+npm run check:milestone
 ```
 
 Read `AGENTS.md` and `data/AGENTS.md` inside a generated workspace for the full headless workflow.

package/template/WORKSPACE.md

@@ -27,6 +27,19 @@ npx filegrc validate --json
 
 Read `AGENTS.md` and `data/AGENTS.md` before broad changes.
 
+## Establish the Git baseline
+
+Review the generated proposals and make an initial commit before recording setup decisions. This gives later changes a clear baseline and prevents first-run files from looking like real-world policy events.
+
+If this is a dedicated repository:
+
+```sh
+git add .
+git commit -m "Initialize FileGRC program"
+```
+
+The editable browser uses `main` and pushes saved changes to `origin`. Connect this repository to a dedicated private remote and push `main` before using browser writes. CLI and file-based users can manage Git on their normal review cadence, but should still commit the baseline before changing program facts.
+
 {{starter_setup}}
 
 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

@@ -8,6 +8,8 @@ Treat the installed model as the authority. Do not infer a schema from a nearby
 
 ```sh
 npx filegrc guide --json
+npx filegrc workflow --json
+npx filegrc reconcile --preview --json
 npx filegrc program-path --next --json
 npx filegrc types --json
 npx filegrc guide RESOURCE_TYPE --json
@@ -15,7 +17,9 @@ npx filegrc list RESOURCE_TYPE --json
 npx filegrc search "TERM" --json
 ```
 
-Use `program-path --next --json` to find the current lifecycle step and first action. Use `--summary` for all six step statuses or `--current` for the current step’s full renderer 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.
+Use `workflow --json` to get the shared assessments, complete checklist, Work Items, blockers, and recommended next action. Use `program-path --next --json` for the current lifecycle step. Use `guide` before any unfamiliar create or status transition. It reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots, timing, and exact paths. Use `describe` only when you need the raw model definition.
+
+After changing a lifecycle fact directly, review `reconcile --preview --json`. A candidate asks whether the change represents a real policy event. Supply the actual event date or timestamp, departure risk when relevant, and explicit confirmation before applying it.
 
 ## Choose the right record
 
@@ -24,7 +28,9 @@ Use `program-path --next --json` to find the current lifecycle step and first ac
 - 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`.
-- 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.
+- A Person’s `jobTitle` is their actual position in the organization. A named authority they hold, such as CISO, DPO, Policy Owner, or team chair, belongs in a dated `appointment` scoped to the workspace, team, or governed records.
+- Team membership and chairs are authoritative on `team.memberIds` and `team.chairIds`.
+- A dated Step 4 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`.
 
@@ -43,7 +49,6 @@ The scaffold is a mutation envelope:
 ```json
 {
   "record": {
-    "schemaVersion": 1,
     "id": "resource-type-human-name",
     "type": "resource-type",
     "title": "Human name"
@@ -93,7 +98,11 @@ JSON is for stable metadata used by validation, relationships, filters, schedule
 
 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.
+When `guide` returns a collection review requirement, review the listed type-specific criteria and use `npx filegrc review-collection RESOURCE_TYPE --scaffold`. Fill the management conclusion, rationale, reviewer, and date, then preview and apply the payload. Do not invent `collectionRevision`; FileGRC calculates it from the current records and material Workspace scope. Any later change makes the confirmation stale and requires another review.
+
+Store a relationship only on its authoritative record. Control Tests store `auditId`; External Evidence stores `auditIds`; Commitments store `systemIds` and `controlIds`; Controls store `policyIds` and `requirementIds`; Risks store `controlIds`; Systems store their direct `vendorId`. Use `references` to inspect derived inbound links.
+
+Use explicit business dates. Git records when a file changed, but it does not replace `occurredOn`, `scheduledFor`, `completedOn`, `approvedOn`, or similar fields.
 
 ## Status changes
 
@@ -118,7 +127,7 @@ npx filegrc references RESOURCE_ID --json
 Delete only an uncommitted draft or a mistake:
 
 ```sh
-npx filegrc delete RESOURCE_TYPE RESOURCE_ID --yes
+npx filegrc delete RESOURCE_TYPE RESOURCE_ID --yes --expected-revision REVISION
 ```
 
 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.
@@ -137,7 +146,7 @@ The JSON uses `filePaths: ["evidence/evidence-example/source-export.csv"]`. Comm
 Use the attachment command to copy a fixed file and update `filePaths` in one validated action:
 
 ```sh
-npx filegrc attach EVIDENCE_ID /path/to/source-export.csv
+npx filegrc attach EVIDENCE_ID /path/to/source-export.csv --expected-revision REVISION
 ```
 
 It refuses symlinks, hidden destination names, and existing destination files.
@@ -145,24 +154,45 @@ It refuses symlinks, hidden destination names, and existing destination files.
 Remove a local attachment explicitly before deleting its evidence record:
 
 ```sh
-npx filegrc detach EVIDENCE_ID source-export.csv --yes
+npx filegrc detach EVIDENCE_ID source-export.csv --yes --expected-revision REVISION
 ```
 
 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.
 
+## Implement Controls and Their Evidence Sources
+
+Finish each applicable Control and its authoritative source Systems together. Use Program Readiness as the completion check:
+
+```sh
+npx filegrc program-readiness --json
+```
+
+The Control stage reports both Control implementation items and evidence-family source checks. Resolve them through the source records:
+
+1. Choose an existing System or scaffold the System that is authoritative for the family.
+2. Set the System to `active`, add the matching `evidenceSourceKinds`, and name current `evidenceOwnerIds`.
+3. Put the exact report, filters, date range, timezone, export format, and reconciliation steps in the System’s Record Markdown.
+4. Add the System ID to `evidenceSourceIds` on every Control in the family that it supports.
+5. Finish the Control’s owner, procedure, scope, operation pattern, mappings, and implementation date. Put every calendar or event schedule in an Obligation.
+6. Run `program-readiness --json` again and resolve every failed Control or source check before marking the Controls implemented or starting the candidate period.
+
+Use `get RESOURCE_ID --mutation` and `update` so JSON and Markdown change together. `evidence-map --json` remains available when you want only the evidence-family checks. Do not create an Evidence record while designing or implementing a Control. Create External Evidence during Step 4 only when the real export, report, screenshot, signed file, or approved external reference exists.
+
 ## Scheduled and event work
 
 ```sh
 npx filegrc obligations --json
+npx filegrc complete OBLIGATION_ID --scaffold --window-start YYYY-MM-DD --completed-on YYYY-MM-DD > completion-mutation.json
 npx filegrc complete OBLIGATION_ID completion-mutation.json
 npx filegrc trigger EVENT_TYPE --occurred-on YYYY-MM-DD --subject RESOURCE_ID --json
+npx filegrc complete-action ACTION_ITEM_ID --scaffold --completed-on YYYY-MM-DD > completion-mutation.json
 npx filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-on YYYY-MM-DD
-npx filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD
+npx filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD --expected-revision REVISION
 ```
 
-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.
+Fill the scaffold with the actual work, evidence, review, and every null or empty required value. Completion scaffolds include the target revision. For other updates, read `REVISION` from `npx filegrc get RESOURCE_ID --mutation`. 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
 
@@ -173,7 +203,7 @@ npx filegrc audit-readiness AUDIT_ID --json
 npx filegrc evidence-packet --audit AUDIT_ID --preview --json
 ```
 
-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.
+Run Program Readiness before creating the normal audit engagement. It checks scope, effective policies, implemented controls, and evidence mapping without an audit ID. Fix readiness errors in the Control and System 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
 
@@ -186,4 +216,4 @@ git diff
 
 Review every changed JSON, Markdown, and attachment. Confirm the diff contains no secrets, temporary files, source exports with prohibited data, or derived `.filegrc/` output. Make one focused commit whose message says why the compliance record changed.
 
-These commands are for CLI and agent work, which continues to manage Git explicitly. Browser saves in trunk mode commit and push automatically from the configured authoritative branch. Do not use a feature branch as a record approval state, and never include application changes when this workspace lives in a monorepo.
+These commands are for CLI and agent work, which continues to manage Git explicitly. Browser saves in trunk mode commit automatically from the configured authoritative branch, then push in the background while the UI reports `Syncing`. Do not start another write until it reports `Synced`. Do not use a feature branch as a record approval state, and never include application changes when this workspace lives in a monorepo.

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

@@ -5,7 +5,7 @@ Create an Action Item only when follow-up needs its own assignee, deadline, and
 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:
 
 ```sh
-npx filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-on YYYY-MM-DD
+npx filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-on YYYY-MM-DD --expected-revision REVISION
 ```
 
-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`.
+Read `REVISION` from `npx filegrc get ACTION_ITEM_ID --mutation`. 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/appointments/appointment-independent-policy-reviewer.json

@@ -0,0 +1,11 @@
+{
+  "id": "appointment-independent-policy-reviewer",
+  "type": "appointment",
+  "title": "Independent Policy Reviewer",
+  "status": "planned",
+  "appointmentKind": "independent-policy-reviewer",
+  "scopeResourceIds": [
+    "workspace"
+  ],
+  "responsibilities": "Challenge and approve policies and governed documents independently from their owners. Assign a qualified external reviewer when no suitable internal reviewer is available."
+}

package/template/data/appointments/appointment-policy-owner.json

@@ -0,0 +1,11 @@
+{
+  "id": "appointment-policy-owner",
+  "type": "appointment",
+  "title": "Policy Owner",
+  "status": "active",
+  "appointmentKind": "policy-owner",
+  "holderId": "person-program-lead",
+  "scopeResourceIds": ["workspace"],
+  "startsOn": "{{effective_date}}",
+  "responsibilities": "Own the information security program and the starter policies, controls, documents, training, and scheduled work until management assigns more specific accountable parties."
+}