create-filegrc 0.4.0 → 0.5.1

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "create-filegrc",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Create a filegrc workspace for a SOC 2 program",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Sunpeak-AI/filegrc.git"
+    "url": "git+https://github.com/Alignbase/filegrc.git"
   },
   "type": "module",
   "bin": {

package/src/cli.js

@@ -68,6 +68,10 @@ export async function runCli(argv = process.argv.slice(2)) {
   console.log("");
   console.log(`  cd ${shellQuote(result.target)}`);
   if (options.install === false) console.log("  npm install");
+  if (result.gitMode !== "existing-worktree") {
+    console.log("  git add .");
+    console.log('  git commit -m "Initialize FileGRC program"');
+  }
   if (!result.setup) console.log("  npx filegrc setup");
   if (result.setup) console.log("  npx filegrc program-path --next --json");
   console.log("  npm run validate");
@@ -84,7 +88,9 @@ export async function runCli(argv = process.argv.slice(2)) {
     ? `  1. Confirm the selected assurance goal with management: ${assuranceGoalLabel(result.setup.target.assuranceGoal)}.`
     : "  1. Select and confirm the assurance goal.");
   console.log("  2. Appoint an independent reviewer who is separate from the policy owner.");
-  console.log("Review the generated records, then commit the approved baseline.");
+  console.log(result.gitMode === "existing-worktree"
+    ? "Review the generated records and commit only this workspace's approved baseline."
+    : "Connect the dedicated private origin and push main before using browser writes.");
 }
 
 function shellQuote(value) {

package/src/defaults.js

@@ -14,6 +14,41 @@ const ROLE_TRAINING_IDS = [
   "training-privileged-sensitive-roles",
   "training-anti-bribery-high-risk-roles"
 ];
+const FILEGRC_SOURCE_FAMILIES = [
+  "training-acknowledgement",
+  "exception-finding",
+  "governance",
+  "risk-management",
+  "vendor-management"
+];
+const FILEGRC_SOURCE_CONTROL_CODES = new Set([
+  "GOV-01",
+  "GOV-02",
+  "GOV-03",
+  "HR-01",
+  "HR-02",
+  "RSK-01",
+  "MON-01",
+  "EXC-01",
+  "VEN-01",
+  "VEN-02"
+]);
+const SOURCE_FAMILIES = [
+  ["workforce", "Workforce System"],
+  ["training-acknowledgement", "Training and Acknowledgements"],
+  ["identity-access", "Identity and Access Systems"],
+  ["production-change", "Production Change Systems"],
+  ["security-monitoring", "Security Monitoring Systems"],
+  ["vulnerability-management", "Vulnerability Management"],
+  ["endpoint-asset", "Endpoint Management Systems"],
+  ["backup-recovery", "Backup and Recovery"],
+  ["vendor-management", "Vendors"],
+  ["exception-finding", "Exceptions and Findings"],
+  ["data-handling", "Data Protection Configuration"],
+  ["network-security", "Network Security Systems"],
+  ["governance", "Governance"],
+  ["risk-management", "Risk Management"]
+];
 
 const commonCriteria = [
   ["CC1.1", "Integrity and ethical values", "Set, communicate, and enforce standards for integrity and ethical conduct."],
@@ -467,7 +502,11 @@ const obligations = [
     ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
     scopeResourceIds: ["training-security-awareness"],
     templateResourceId: "training-security-awareness",
-    controlIds: ["control-security-training"],
+    controlIds: [
+      "control-security-communication",
+      "control-workforce-expectations",
+      "control-security-training"
+    ],
     policyIds: [INFORMATION_SECURITY_POLICY_ID, DATA_POLICY_ID]
   },
   {
@@ -588,7 +627,7 @@ const obligations = [
     activityType: "vendor-review",
     recurrence: calendar("year", 1),
     ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
-    controlIds: ["control-vendor-monitoring"],
+    controlIds: ["control-vendor-due-diligence", "control-vendor-monitoring"],
     policyIds: [INFORMATION_SECURITY_POLICY_ID, DATA_POLICY_ID]
   },
   {
@@ -685,7 +724,8 @@ const obligations = [
     id: "obligation-high-risk-departure-access",
     title: "Revoke access at or before departure notice",
     activityType: "access-removal",
-    recurrence: event("high-risk-person-ended"),
+    recurrence: event("person-ended"),
+    eventRiskLevels: ["high"],
     triggerPrompt: "Involuntary or high-risk departure?",
     window: eventWindowHours(0),
     ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
@@ -857,7 +897,150 @@ const obligations = [
     triggerPrompt: "Material security incident?",
     window: eventWindow(7),
     ownerIds: [OVERSIGHT_TEAM_ID],
-    controlIds: ["control-monitoring-remediation"],
+    controlIds: ["control-monitoring-remediation", "control-security-exceptions"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-vendor-activation-review",
+    title: "Complete vendor activation review",
+    activityType: "vendor-review",
+    recurrence: event("vendor-activated"),
+    triggerPrompt: "Vendor activated?",
+    window: eventWindow(30),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-vendor-due-diligence", "control-vendor-monitoring"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-vendor-termination-closeout",
+    title: "Revoke vendor access and confirm data return or disposal",
+    activityType: "access-removal",
+    recurrence: event("vendor-terminated"),
+    triggerPrompt: "Vendor terminated?",
+    window: eventWindow(7),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-vendor-monitoring", "control-access-review-offboarding"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID, DATA_POLICY_ID]
+  },
+  {
+    id: "obligation-data-use-change-assessment",
+    title: "Assess the changed data use and control impact",
+    activityType: "risk-assessment",
+    recurrence: event("material-data-use-change"),
+    triggerPrompt: "Material data-use change?",
+    window: eventWindow(30),
+    ownerIds: [OVERSIGHT_TEAM_ID],
+    controlIds: ["control-risk-assessment", "control-data-classification-inventory"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID, DATA_POLICY_ID]
+  },
+  {
+    id: "obligation-incident-closure-review",
+    title: "Complete incident closure and lessons-learned review",
+    activityType: "incident-retrospective",
+    recurrence: event("incident-closed"),
+    triggerPrompt: "Incident closed?",
+    window: eventWindow(7),
+    ownerIds: [OVERSIGHT_TEAM_ID],
+    controlIds: ["control-incident-response", "control-monitoring-remediation"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-policy-revision-approval",
+    title: "Review and approve the revised policy",
+    activityType: "policy-review",
+    recurrence: event("policy-revised"),
+    triggerPrompt: "Policy materially revised?",
+    window: eventWindow(30),
+    ownerIds: [OVERSIGHT_TEAM_ID],
+    controlIds: ["control-policy-management"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-emergency-change-review",
+    title: "Complete emergency-change post-review",
+    activityType: "change-review",
+    recurrence: event("emergency-change"),
+    triggerPrompt: "Emergency change completed?",
+    window: eventWindow(2),
+    ownerIds: [OVERSIGHT_TEAM_ID],
+    controlIds: ["control-change-management"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-exception-expiry-review",
+    title: "Review expired exception and compensating controls",
+    activityType: "exception-review",
+    recurrence: event("exception-expired"),
+    triggerPrompt: "Exception expired?",
+    window: eventWindow(1),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-monitoring-remediation", "control-security-exceptions"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-service-account-creation-review",
+    title: "Authorize and review the new service account",
+    activityType: "access-provisioning",
+    recurrence: event("service-account-created"),
+    triggerPrompt: "Service account created?",
+    window: eventWindow(3),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-access-authorization"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-service-account-expiry",
+    title: "Disable or renew the expired service account",
+    activityType: "access-removal",
+    recurrence: event("service-account-expired"),
+    triggerPrompt: "Service account expired?",
+    window: eventWindow(1),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-access-review-offboarding"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-vulnerability-confirmed-remediation",
+    title: "Assign confirmed vulnerability remediation",
+    activityType: "remediation",
+    recurrence: event("vulnerability-confirmed"),
+    triggerPrompt: "Vulnerability confirmed?",
+    window: eventWindow(3),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-vulnerability-management"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-vulnerability-overdue-escalation",
+    title: "Escalate overdue vulnerability remediation",
+    activityType: "remediation",
+    recurrence: event("vulnerability-overdue"),
+    triggerPrompt: "Vulnerability remediation overdue?",
+    window: eventWindow(1),
+    ownerIds: [OVERSIGHT_TEAM_ID],
+    controlIds: ["control-vulnerability-management", "control-monitoring-remediation"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID]
+  },
+  {
+    id: "obligation-asset-disposal-proof",
+    title: "Record asset sanitization and disposal proof",
+    activityType: "asset-recovery",
+    recurrence: event("asset-disposed"),
+    triggerPrompt: "Asset disposed?",
+    window: eventWindow(7),
+    ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+    controlIds: ["control-inventory-configuration", "control-data-retention-disposal"],
+    policyIds: [INFORMATION_SECURITY_POLICY_ID, DATA_POLICY_ID]
+  },
+  {
+    id: "obligation-continuity-activation-review",
+    title: "Review continuity activation, recovery, and follow-up",
+    activityType: "continuity-review",
+    recurrence: event("continuity-activated"),
+    triggerPrompt: "Continuity plan activated?",
+    window: eventWindow(7),
+    ownerIds: [OVERSIGHT_TEAM_ID],
+    controlIds: ["control-continuity-exercise", "control-monitoring-remediation"],
     policyIds: [INFORMATION_SECURITY_POLICY_ID]
   }
 ];
@@ -899,9 +1082,9 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
     title: `${reference}: ${name}`,
     frameworkId: FRAMEWORK_ID,
     reference,
-    applicability: "applicable",
+    applicability: "undetermined",
     description,
-    applicabilityRationale: "Included in the default SOC 2 Security baseline. Confirm applicability and exact interpretation with the selected auditor.",
+    applicabilityRationale: "Confirm applicability against the selected service, scope, and auditor guidance before accepting this starter criterion.",
     tags: ["security", "common-criteria"]
   }));
   const descriptionRequirements = descriptionCriteria.map(([reference, name, description]) => ({
@@ -910,9 +1093,9 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
     title: `${reference}: ${name}`,
     frameworkId: DESCRIPTION_FRAMEWORK_ID,
     reference,
-    applicability: "applicable",
+    applicability: "undetermined",
     description,
-    applicabilityRationale: "Included for preparing the system description. Confirm the official criterion and expected presentation with the selected auditor.",
+    applicabilityRationale: "Confirm applicability against the selected service and auditor guidance before accepting this starter description criterion.",
     tags: ["description-criteria"]
   }));
   const controlRecords = controls.map((control) => ({
@@ -928,7 +1111,10 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
     controlType: control.controlType,
     operationMode: control.operationMode,
     operationPattern: control.operationPattern,
-    policyIds: control.policies
+    policyIds: control.policies,
+    ...(FILEGRC_SOURCE_CONTROL_CODES.has(control.code)
+      ? { evidenceSourceIds: ["system-filegrc-program-repository"] }
+      : {})
   }));
   const team = {
     id: OVERSIGHT_TEAM_ID,
@@ -951,14 +1137,14 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
     environment: "Git repository",
     classificationId: "confidential",
     internetExposed: false,
-    evidenceSourceKinds: ["training-acknowledgement", "exception-finding"],
+    evidenceSourceKinds: FILEGRC_SOURCE_FAMILIES,
     evidenceOwnerIds: [POLICY_OWNER_APPOINTMENT_ID]
   };
   const obligationRecords = obligations.map((obligation) => ({
     id: obligation.id,
     type: "obligation",
     title: obligation.title,
-    status: "active",
+    status: "proposed",
     activityType: obligation.activityType,
     recurrence: obligation.recurrence.mode === "calendar"
       ? { ...obligation.recurrence, anchorDate: effectiveDate }
@@ -966,12 +1152,32 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
     ownerIds: obligation.ownerIds,
     startsOn: effectiveDate,
     ...(obligation.triggerPrompt ? { triggerPrompt: obligation.triggerPrompt } : {}),
+    ...(obligation.eventRiskLevels ? { eventRiskLevels: obligation.eventRiskLevels } : {}),
     ...(obligation.window ? { window: obligation.window } : {}),
     ...(obligation.scopeResourceIds ? { scopeResourceIds: obligation.scopeResourceIds } : {}),
     ...(obligation.templateResourceId ? { templateResourceId: obligation.templateResourceId } : {}),
     controlIds: obligation.controlIds,
     policyIds: obligation.policyIds
   }));
+  const sourceCoverageRecords = SOURCE_FAMILIES.map(([sourceFamilyId, title]) => {
+    const filegrcManaged = FILEGRC_SOURCE_FAMILIES.includes(sourceFamilyId);
+    return {
+      id: `source-coverage-${sourceFamilyId}`,
+      type: "source-coverage",
+      title: `${title} coverage`,
+      status: filegrcManaged ? "active" : "planned",
+      sourceFamilyId,
+      coverageKind: filegrcManaged ? "filegrc" : "external-system",
+      scopeResourceIds: ["workspace"],
+      ownerIds: [POLICY_OWNER_APPOINTMENT_ID],
+      ...(filegrcManaged ? {
+        collectionCadence: "Record work when it occurs and export the complete population for the audit period.",
+        retention: "Keep records for the period defined in the approved Data Retention Schedule.",
+        reconciliationMethod: "Export the complete filegrc source-family population, compare it with related in-scope records and Work Queue activity, and investigate omissions or duplicates.",
+        validFrom: effectiveDate
+      } : {})
+    };
+  });
 
   const foundation = [
     recordFile("systems", programRepository),
@@ -986,6 +1192,7 @@ export function baselineRecordFiles(effectiveDate, starter = "security") {
     ...descriptionRequirements.map((record) => recordFile("requirements", record)),
     ...controlRecords.map((record) => recordFile("controls", record)),
     ...foundation,
+    ...sourceCoverageRecords.map((record) => recordFile("source-coverage", record)),
     ...obligationRecords.map((record) => recordFile("obligations", record))
   ];
 }

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;
@@ -396,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);
@@ -420,10 +430,11 @@ 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
+- 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
@@ -432,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.
@@ -453,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
@@ -504,13 +516,13 @@ async function runCombinedSetup(target, input) {
 async function writeMinimalLockfile(target, name, versionRange) {
   const lock = {
     name,
-    version: "0.4.0",
+    version: "0.5.1",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.4.0",
+        version: "0.5.1",
         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 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.
+`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,6 +52,20 @@ 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.
@@ -86,10 +100,12 @@ Do not rewrite or remove committed records that explain prior audit periods. Clo
 If the installed CLI reports that this workspace uses an unsupported model, start with:
 
 ```sh
-npx filegrc migrate --to-model 2 --preview --json
+npx filegrc migrate --to-model 3 --preview --json
 ```
 
-Resolve every missing value, conflict, and manual action in the preview before applying the migration with the same options and `--yes`.
+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/Alignbase/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:
 
@@ -118,12 +134,14 @@ Headless agents get the same protection by exporting an edit payload with `fileg
 
 `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:
@@ -138,10 +156,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 --expected-revision REVISION
+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 4 or run:
 
@@ -155,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 completion-record.json --completed-on 2026-07-25 --expected-revision REVISION
+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 --expected-revision REVISION
 ```
 
-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.
+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
 
@@ -241,7 +263,16 @@ Link a control test to its `audit-population` record when sampling applies. Link
 
 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,7 +19,7 @@ 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`.
+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/Alignbase/filegrc/blob/main/docs/upgrading-to-model-v3.md).
 
 ## How it works
 
@@ -39,11 +39,11 @@ Detached and feature-branch checkouts are read-only in the browser by default. D
 
 ![filegrc SOC 2 program overview](docs/filegrc-home.png)
 
-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, 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.
+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.
 
@@ -51,9 +51,10 @@ 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.
 
@@ -67,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.
@@ -84,4 +92,4 @@ The independent CPA firm still selects samples, tests controls, evaluates except
 
 Do not put secrets or personal data that may need erasure into Git. The editable local server has no authentication and binds to loopback by default.
 
-Learn more at [filegrc.com](https://filegrc.com) or [view the source on GitHub](https://github.com/Sunpeak-AI/filegrc).
+Learn more at [filegrc.com](https://filegrc.com) or [view the source on GitHub](https://github.com/Alignbase/filegrc).

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 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.
+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
 
@@ -94,6 +98,8 @@ 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.
 
+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.
@@ -178,13 +184,15 @@ Use `get RESOURCE_ID --mutation` and `update` so JSON and Markdown change togeth
 
 ```sh
 npx filegrc obligations --json
-npx filegrc complete OBLIGATION_ID completion-mutation.json --expected-revision REVISION
+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 completion-mutation.json --completed-on YYYY-MM-DD --expected-revision REVISION
+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 --expected-revision REVISION
 ```
 
-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.
+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
 

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/collection-reviews/collection-review-complementary-control.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-complementary-control",
+  "type": "collection-review",
+  "title": "Customer and provider responsibilities review",
+  "status": "planned",
+  "resourceType": "complementary-control",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/collection-reviews/collection-review-framework.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-framework",
+  "type": "collection-review",
+  "title": "Framework and criteria sources review",
+  "status": "planned",
+  "resourceType": "framework",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/collection-reviews/collection-review-person.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-person",
+  "type": "collection-review",
+  "title": "Program participants review",
+  "status": "planned",
+  "resourceType": "person",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/collection-reviews/collection-review-system.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-system",
+  "type": "collection-review",
+  "title": "Service and system boundary review",
+  "status": "planned",
+  "resourceType": "system",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

package/template/data/collection-reviews/collection-review-vendor.json

@@ -0,0 +1,10 @@
+{
+  "id": "collection-review-vendor",
+  "type": "collection-review",
+  "title": "Vendor and subservice scope review",
+  "status": "planned",
+  "resourceType": "vendor",
+  "scopeResourceIds": [
+    "workspace"
+  ]
+}

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

@@ -8,7 +8,6 @@
     "appointment-policy-owner"
   ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees",
     "contractors"
@@ -24,5 +23,7 @@
     "document-incident-response-plan"
   ],
   "evidenceIds": [],
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "required"
 }

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

@@ -31,6 +31,8 @@ During a disruption, {{company_name}} will:
 
 ## Roles
 
+These names describe recovery functions, not required job titles or separate Appointments. The current Policy Owner performs them by default and management delegates a function only when that matches how the organization actually recovers its services.
+
 ### Policy owner
 
 The current Policy Owner owns this plan and keeps it current. The Policy Owner may delegate response duties but remains accountable for the plan.

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

@@ -8,12 +8,13 @@
     "appointment-policy-owner"
   ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "contractors"
   ],
   "controlIds": [
     "control-workforce-expectations"
   ],
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

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

@@ -8,7 +8,6 @@
     "appointment-policy-owner"
   ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "contractors"
   ],
@@ -18,5 +17,7 @@
   "trainingIds": [
     "training-security-awareness"
   ],
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

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

@@ -8,7 +8,6 @@
     "appointment-policy-owner"
   ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "data-owners",
     "system-owners"
@@ -18,5 +17,7 @@
     "control-data-classification-inventory",
     "control-data-retention-disposal"
   ],
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

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

@@ -8,12 +8,13 @@
     "appointment-policy-owner"
   ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees"
   ],
   "controlIds": [
     "control-workforce-expectations"
   ],
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

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

@@ -8,12 +8,13 @@
     "appointment-policy-owner"
   ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees"
   ],
   "controlIds": [
     "control-workforce-expectations"
   ],
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

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

@@ -8,7 +8,6 @@
     "appointment-policy-owner"
   ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees"
   ],
@@ -18,5 +17,7 @@
   "trainingIds": [
     "training-security-awareness"
   ],
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

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

@@ -8,7 +8,6 @@
     "appointment-policy-owner"
   ],
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees",
     "contractors"
@@ -24,5 +23,7 @@
     "document-business-continuity-disaster-recovery"
   ],
   "evidenceIds": [],
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "required"
 }

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

@@ -41,6 +41,8 @@ Severity considers affected data, systems, customers, privileges, duration, spre
 
 ## Roles and authority
 
+These names describe response functions, not required job titles or separate Appointments. The current Policy Owner performs them by default and management delegates a function only when that matches how the organization actually responds.
+
 ### Reporter
 
 Anyone may report a suspected incident. Reporters preserve available evidence, stop unsafe activity when they can do so safely, and follow response instructions. They do not need proof before reporting.

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

@@ -9,5 +9,6 @@
     "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classificationId": "confidential"
+  "classificationId": "confidential",
+  "programRole": "required"
 }

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

@@ -9,5 +9,6 @@
     "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classificationId": "confidential"
+  "classificationId": "confidential",
+  "programRole": "required"
 }

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

@@ -9,5 +9,6 @@
     "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classificationId": "confidential"
+  "classificationId": "confidential",
+  "programRole": "conditional"
 }

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

@@ -9,5 +9,6 @@
     "appointment-policy-owner"
   ],
   "version": "0.1",
-  "classificationId": "internal"
+  "classificationId": "internal",
+  "programRole": "required"
 }

package/template/data/obligations/AGENTS.md

@@ -9,4 +9,4 @@ An obligation is a reusable policy schedule or event template. It is not the rec
 - When an approved cadence changes, update the policy, control, and obligation together.
 - Pause or retire a template only when the underlying policy work no longer applies. Do not delete historical templates that explain prior periods.
 
-Use `npx filegrc obligations --json` to inspect calculated recurring work and preview every Policy Event task, owner, deadline, and requested proof. Read the Obligation revision with `npx filegrc get OBLIGATION_ID --mutation`, then use `npx filegrc complete OBLIGATION_ID completion-mutation.json --expected-revision REVISION` to create and link a dated occurrence in one validated write. Use `npx filegrc trigger EVENT_TYPE ...` only after the matching event occurs; it adds all configured Action Items to the Work Queue atomically.
+Use `npx filegrc obligations --json` to inspect calculated recurring work and preview every Policy Event task, owner, deadline, and requested proof. Run `npx filegrc complete OBLIGATION_ID --scaffold --window-start YYYY-MM-DD --completed-on YYYY-MM-DD > completion-mutation.json`, fill the actual work and proof, then pass that file to `npx filegrc complete OBLIGATION_ID completion-mutation.json`. The scaffold includes the current Obligation revision, and the final command creates and links the dated occurrence in one validated write. Use `npx filegrc trigger EVENT_TYPE ...` only after the matching event occurs; it adds all configured Action Items to the Work Queue atomically.

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

@@ -8,11 +8,12 @@
   ],
   "policyKind": "corporate-conduct",
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees",
     "contractors",
     "agents"
   ],
-  "acknowledgementRequired": true
+  "acknowledgementRequired": true,
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

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

@@ -8,10 +8,11 @@
   ],
   "policyKind": "information-security",
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees",
     "contractors"
   ],
-  "acknowledgementRequired": true
+  "acknowledgementRequired": true,
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "alternative"
 }

package/template/data/policies/policy-data-protection-handling.json

@@ -8,7 +8,6 @@
   ],
   "policyKind": "information-security",
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees",
     "contractors",
@@ -17,5 +16,7 @@
   "acknowledgementRequired": true,
   "relatedDocumentIds": [
     "document-data-retention-schedule"
-  ]
+  ],
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "required"
 }

package/template/data/policies/policy-employee-handbook.json

@@ -8,7 +8,6 @@
   ],
   "policyKind": "workforce-conduct",
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees"
   ],
@@ -16,5 +15,7 @@
   "relatedDocumentIds": [
     "document-employee-handbook-acknowledgement",
     "document-employee-policy-acknowledgement"
-  ]
+  ],
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "conditional"
 }

package/template/data/policies/policy-information-security.json

@@ -8,7 +8,6 @@
   ],
   "policyKind": "information-security",
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees",
     "contractors",
@@ -24,5 +23,7 @@
     "document-business-continuity-disaster-recovery",
     "document-incident-response-plan",
     "document-data-retention-schedule"
-  ]
+  ],
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "required"
 }

package/template/data/policies/policy-information-security.md

@@ -28,7 +28,7 @@ The policy owner:
 
 An independent reviewer chairs the security and risk oversight group. This person must be separate from the policy owner and able to challenge the owner's decisions. The reviewer will usually be another leader or manager in the organization, but may be external. The reviewer approves policies and governed plans, challenges management's assessment of control operation, and records independent decisions.
 
-The security and risk oversight group meets at least quarterly to review the risk register, material incidents, significant findings, vendor and access review results, policy changes, exercises, and overdue work. Each meeting has formal minutes, decisions, and assigned actions. A one-person company must appoint a qualified external person to fill the independent reviewer role because no second internal person is available.
+The security and risk oversight group meets at least quarterly to review the risk register, material incidents, significant findings, vendor and access review results, policy changes, exercises, and overdue work. Each meeting has formal minutes, decisions, and assigned actions. When no suitable internal independent reviewer is available, the organization appoints a qualified external person to fill the role.
 
 System and process owners classify their systems and data, approve access, maintain safeguards, respond to findings, and keep recovery information current.
 

package/template/data/policies/policy-mobile-computing-communications.json

@@ -8,10 +8,11 @@
   ],
   "policyKind": "information-security",
   "version": "1.0",
-  "effectiveOn": "{{effective_date}}",
   "audience": [
     "employees",
     "contractors"
   ],
-  "acknowledgementRequired": true
+  "acknowledgementRequired": true,
+  "proposedEffectiveOn": "{{effective_date}}",
+  "programRole": "supporting"
 }

package/template/data/renderer.json

@@ -5,6 +5,5 @@
   "showOnboarding": true,
   "repositoryMode": "trunk",
   "authoritativeBranch": "main",
-  "repositoryRemote": "origin",
-  "completedStagePageIds": []
+  "repositoryRemote": "origin"
 }

package/template/data/systems/system-filegrc-program-repository.md

@@ -1,9 +1,9 @@
 # filegrc Program Repository
 
-This Git repository is the system of record for filegrc governance records and their revision history. It can supply the training and acknowledgement catalog, exception and finding populations, policy and document approvals, obligation history, Policy Event workflows, and management evidence indexes.
+This Git repository is the system of record for filegrc governance records and their revision history. It can supply the training and acknowledgement catalog, exception and finding populations, policy and document approvals, risk register and assessments, vendor inventory and reviews, oversight records, obligation history, Policy Event workflows, and management evidence indexes.
 
 ## Evidence Extraction
 
 Run filegrc from a clean commit. Use resource dates and audit links to select the exact engagement date or period, save the query or agent instructions with the export, and retain the fixed result behind an evidence record. Record a zero count when the committed source query returns no relevant items.
 
-The repository is authoritative only for records stored here. Identity, workforce, source-control, deployment, monitoring, endpoint, backup, vulnerability, and vendor systems remain authoritative for the activity they perform.
+The repository is authoritative only for records stored here. Identity, workforce, source-control, deployment, monitoring, endpoint, backup, vulnerability, and external vendor-management systems remain authoritative for the activity they perform.

package/template/data/workspace.json

@@ -1,5 +1,5 @@
 {
-  "dataModelVersion": "2",
+  "dataModelVersion": "3",
   "id": "workspace",
   "type": "workspace",
   "title": "{{program_title}}",

package/template/package.json

@@ -1,13 +1,14 @@
 {
   "name": "{{project_name}}",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "private": true,
   "description": "filegrc workspace for a SOC 2 program",
   "type": "module",
   "scripts": {
     "serve": "filegrc serve",
     "build": "filegrc build",
-    "validate": "filegrc validate"
+    "validate": "filegrc validate",
+    "check:milestone": "filegrc milestone-check"
   },
   "dependencies": {
     "filegrc": "{{filegrc_version_range}}"