create-filegrc 0.3.3 → 0.4.0

package/src/index.js

@@ -16,6 +16,7 @@ export async function createFilegrc(options = {}) {
   const parameterConfig = JSON.parse(await readFile(join(packageRoot, "template-parameters.json"), "utf8"));
   const target = resolve(options.target ?? "filegrc-program");
   const starter = normalizeStarterProfile(options.starter);
+  const repository = normalizeRepositoryOptions(options);
   if (options.setup && options.install === false) {
     throw new Error("Combined service setup requires installation. Remove --no-install or run filegrc setup after npm install.");
   }
@@ -38,6 +39,7 @@ export async function createFilegrc(options = {}) {
   await mkdir(target, { recursive: true });
   await copyTemplate(target, starter);
   await renderTemplate(target, parameterConfig, values, starter);
+  await writeRendererRepositorySettings(target, repository);
   await writeBaselineRecords(target, values.effective_date, starter);
   await applyStarterScope(target, starter, values.effective_date);
   const initialResourceCounts = await summarizeResources(target);
@@ -49,7 +51,7 @@ export async function createFilegrc(options = {}) {
     await writeMinimalLockfile(target, values.project_name, values.filegrc_version_range);
   }
   const joinedExistingWorktree = await isInsideGitWorktree(target);
-  if (!joinedExistingWorktree) await run("git", ["init"], target);
+  if (!joinedExistingWorktree) await run("git", ["init", `--initial-branch=${repository.authoritativeBranch}`], target);
   const gitHead = await inspectGitHead(target);
   const setup = options.setup ? await runCombinedSetup(target, options.setup) : null;
   const resourceCounts = setup ? await summarizeResources(target) : initialResourceCounts;
@@ -67,7 +69,8 @@ export async function createFilegrc(options = {}) {
     install: installed ? "installed" : "skipped",
     gitMode: joinedExistingWorktree ? "existing-worktree" : "initialized",
     gitBranch: gitHead.branch,
-    gitDetached: gitHead.detached
+    gitDetached: gitHead.detached,
+    repository
   };
 }
 
@@ -80,6 +83,54 @@ export function normalizeStarterProfile(value = "security") {
   return normalized;
 }
 
+function normalizeRepositoryOptions(options) {
+  const mode = String(options.repositoryMode ?? "trunk").trim();
+  if (!["trunk", "manual"].includes(mode)) {
+    throw new Error("Repository mode must be trunk or manual.");
+  }
+  return {
+    mode,
+    authoritativeBranch: normalizeGitSetting(options.authoritativeBranch, "main", "authoritative branch"),
+    remote: normalizeGitSetting(options.repositoryRemote, "origin", "repository remote")
+  };
+}
+
+function normalizeGitSetting(value, fallback, label) {
+  const result = String(value ?? fallback).trim();
+  if (!safeGitName(result)) {
+    throw new Error(`${label} must be a safe Git name.`);
+  }
+  return result;
+}
+
+function safeGitName(value) {
+  const segments = value.split("/");
+  return Boolean(value)
+    && value !== "@"
+    && value !== "HEAD"
+    && !value.startsWith("-")
+    && !value.includes("..")
+    && !value.includes("@{")
+    && !/[\s~^:?*[\]\\\u0000-\u001f\u007f]/.test(value)
+    && segments.every((segment) => (
+      segment
+      && !segment.startsWith(".")
+      && !segment.endsWith(".")
+      && !segment.endsWith(".lock")
+    ));
+}
+
+async function writeRendererRepositorySettings(target, repository) {
+  const path = join(target, "data", "renderer.json");
+  const renderer = JSON.parse(await readFile(path, "utf8"));
+  await writeFile(path, `${JSON.stringify({
+    ...renderer,
+    repositoryMode: repository.mode,
+    authoritativeBranch: repository.authoritativeBranch,
+    repositoryRemote: repository.remote
+  }, null, 2)}\n`, "utf8");
+}
+
 export async function resolveFilegrcVersion(explicitVersion) {
   if (explicitVersion) return cleanVersion(explicitVersion);
   try {
@@ -121,6 +172,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
@@ -128,6 +180,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)) {
@@ -157,7 +210,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.`);
     }
@@ -321,7 +374,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;
   }
@@ -371,7 +424,7 @@ The generated workspace starts with five structural records:
 
 - Workspace and renderer settings
 - The initial active owner
-- An inactive security and risk oversight team that still needs an independent chair
+- 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
 
@@ -414,23 +467,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",
@@ -438,7 +490,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",
@@ -452,13 +504,13 @@ async function runCombinedSetup(target, input) {
 async function writeMinimalLockfile(target, name, versionRange) {
   const lock = {
     name,
-    version: "0.3.3",
+    version: "0.4.0",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.3.3",
+        version: "0.4.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 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.
 
 For a new record, generate a mutation envelope:
 
@@ -56,11 +56,26 @@ Read `data/AGENTS.md` before changing records. More specific instructions inside
 
 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.
 
-Make focused commits with messages that explain the reason for the change. The engine never creates commits automatically. Review the workspace diff, then use the commit action on Repository or the Git CLI. The renderer validates the workspace and requires an explicit message before it creates a commit.
+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.
 
-Pull before starting work when other people or agents may have changed the repository. Without a remote, the browser's Repository page creates a local commit and hides synchronization actions. With a remote, it pulls with rebase, refuses to pull over uncommitted files, and pushes immediately after it creates a commit. Agents and terminal users own Git synchronization and should run `git pull --rebase`, `git commit`, and `git push` directly. Do not create merge commits for routine synchronization.
+- Prefer creating or cloning FileGRC as a standalone private repository.
+- Run the editable browser from the authoritative branch's main checkout.
+- Do not place a new FileGRC workspace inside an application monorepo unless the organization has explicitly chosen that structure.
+- If FileGRC already lives in a monorepo, do not relocate it automatically.
+- In a monorepo, never include application changes in FileGRC-generated commits.
+- Treat detached and feature-branch copies as read-only unless an explicit development override is active.
+
+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`. 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.
+
+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.
 
 Do not rewrite or remove committed records that explain prior audit periods. Close or retire them. Delete only mistakes and uncommitted drafts.
 
@@ -68,6 +83,14 @@ 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 2 --preview --json
+```
+
+Resolve every missing value, conflict, and manual action in the preview before applying the migration with the same options and `--yes`.
+
 Run these commands when working with records:
 
 ```sh
@@ -93,7 +116,7 @@ Headless agents get the same protection by exporting an edit payload with `fileg
 
 ## Renderer settings and onboarding
 
-`data/renderer.json` stores committed renderer preferences. New workspaces set `showOnboarding` to `true`. Completing or skipping onboarding sets it to `false`; the app does not commit that change.
+`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.
 
@@ -115,12 +138,12 @@ 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 completion-record.json
+npx filegrc complete obligation-id completion-record.json --expected-revision REVISION
 ```
 
 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
@@ -132,11 +155,11 @@ 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 completion-record.json --completed-on 2026-07-25
-npx filegrc complete-event obligation-event-id --completed-on 2026-07-25
+npx filegrc complete-action action-item-id completion-record.json --completed-on 2026-07-25 --expected-revision REVISION
+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.
+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
 
@@ -162,11 +185,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.
 
@@ -190,7 +212,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.
@@ -217,7 +239,7 @@ 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.
 

package/template/README.md

@@ -8,6 +8,8 @@ filegrc gives founder-led engineering teams one place to adopt policies, impleme
 
 It is open source, MIT licensed, and runs locally.
 
+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.
+
 ```sh
 npx create-filegrc@latest company-grc
 cd company-grc
@@ -17,6 +19,8 @@ npm run serve
 
 Requires Node.js 20 or newer and Git.
 
+Existing model v1 workspaces must run `npx filegrc migrate --to-model 2 --preview --json` after installing a model v2 package. Resolve every reported item before applying the same migration with `--yes`.
+
 ## How it works
 
 The repository is the program. There is no separate application database.
@@ -27,16 +31,21 @@ 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, 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. 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.
+1. **Define scope.** Confirm people, dated appointments, teams, criteria, commitments, vendors, and in-scope systems. For Systems that produce evidence, add their source roles, access owners, and retrieval instructions.
 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.
+3. **Implement controls.** Add the real procedure, scope, operation pattern, and authoritative evidence Systems. Put calendar and event schedules in Obligations. Confirm every source is active and has the required role, access owners, and repeatable retrieval instructions before marking the Control implemented.
+4. **Operate the program.** Work the queue, trigger Policy Events, maintain risks, and preserve dated evidence.
+5. **Audit.** Record the CPA engagement and agreed period, support fieldwork, and build the 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.
 

package/template/data/AGENTS.md

@@ -15,7 +15,7 @@ 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 `program-path --next --json` to find the current lifecycle step and first action. Use `--summary` for all five 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.
 
 ## Choose the right record
 
@@ -24,7 +24,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 +45,6 @@ The scaffold is a mutation envelope:
 ```json
 {
   "record": {
-    "schemaVersion": 1,
     "id": "resource-type-human-name",
     "type": "resource-type",
     "title": "Human name"
@@ -93,7 +94,9 @@ 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.
+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 +121,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 +140,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 +148,43 @@ 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 completion-mutation.json
+npx filegrc complete OBLIGATION_ID completion-mutation.json --expected-revision REVISION
 npx filegrc trigger EVENT_TYPE --occurred-on YYYY-MM-DD --subject RESOURCE_ID --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-action ACTION_ITEM_ID completion-mutation.json --completed-on YYYY-MM-DD --expected-revision REVISION
+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.
+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 +195,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
 
@@ -185,3 +207,5 @@ 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 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-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."
+}

package/template/data/audits/AGENTS.md

@@ -17,7 +17,7 @@ Preparation creates engagement-specific management documents and, for Type 2, po
 
 Review both evidence paths for the exact formal date or period:
 
-1. filegrc Evidence consists of dated Step 5 operating records. Complete the record, link it to the applicable Controls, record the result in its fields or Markdown, and link any external artifact needed to support that result.
+1. filegrc Evidence consists of dated Step 4 operating records. Complete the record, link it to the applicable Controls, record the result in its fields or Markdown, and link any external artifact needed to support that result.
 2. External Evidence consists of verified `evidence` records from other Systems. Confirm the source System, date or period, Control links, collector, verifier, and fixed attachment or approved external reference.
 
 The packet compiles both paths. It includes filegrc records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.

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

@@ -1,21 +1,18 @@
 {
-  "schemaVersion": 1,
   "id": "document-business-continuity-disaster-recovery",
   "type": "document",
   "title": "Business Continuity and Disaster Recovery Plan",
   "status": "draft",
   "documentKind": "plan",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["employees", "contractors"],
+  "audience": [
+    "employees",
+    "contractors"
+  ],
   "acknowledgementRequired": true,
   "controlIds": [
     "control-policy-management",
@@ -23,6 +20,9 @@
     "control-backup-restoration",
     "control-continuity-exercise"
   ],
-  "relatedDocumentIds": ["document-incident-response-plan"],
-  "evidenceIds": []
+  "relatedDocumentIds": [
+    "document-incident-response-plan"
+  ],
+  "evidenceIds": [],
+  "classificationId": "internal"
 }

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

@@ -33,7 +33,7 @@ During a disruption, {{company_name}} will:
 
 ### Policy owner
 
-{{policy_owner_name}} owns this plan and keeps it current. The policy owner may delegate response duties but remains accountable for the plan.
+The current Policy Owner owns this plan and keeps it current. The Policy Owner may delegate response duties but remains accountable for the plan.
 
 ### Security and risk oversight
 

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

@@ -1,20 +1,19 @@
 {
-  "schemaVersion": 1,
   "id": "document-contractor-policy-acknowledgement",
   "type": "document",
   "title": "Contractor Policy Acknowledgement",
   "status": "draft",
   "documentKind": "attestation-template",
-  "ownerIds": ["person-policy-owner"],
+  "ownerIds": [
+    "appointment-policy-owner"
+  ],
   "version": "1.0",
   "effectiveOn": "{{effective_date}}",
-  "reviewCadence": {
-    "mode": "calendar",
-    "unit": "year",
-    "interval": 1,
-    "anchorDate": "{{effective_date}}"
-  },
-  "classification": "internal",
-  "audience": ["contractors"],
-  "controlIds": ["control-workforce-expectations"]
+  "audience": [
+    "contractors"
+  ],
+  "controlIds": [
+    "control-workforce-expectations"
+  ],
+  "classificationId": "internal"
 }