filegrc 0.5.1 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filegrc",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {

package/src/agent.js

@@ -2,6 +2,7 @@ import { createResourceId } from "./id.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { RESOURCE_INSTRUCTIONS, resourceProgramContext } from "./program-path.js";
 import { assessCollectionReview } from "./collection-review.js";
+import { resolveProgram } from "./program.js";
 
 const STARTING_STATUS_ORDER = [
   "draft",
@@ -29,7 +30,7 @@ export function listResourceTypes(model) {
 export function buildAgentGuide(loaded, type, options = {}) {
   const definition = loaded.model.resources[type];
   if (!definition) throw new Error(`Unknown resource type "${type}".`);
-  const collectionReview = assessCollectionReview(loaded, type);
+  const collectionReview = assessCollectionReview(loaded, type, { programId: options.programId });
   const fields = { ...loaded.model.commonFields, ...definition.fields };
   const required = new Set([
     ...Object.entries(loaded.model.commonFields)
@@ -115,12 +116,18 @@ export function buildAgentGuide(loaded, type, options = {}) {
       recommendedMarkdown.length
         ? "Keep model fields in JSON and use the recommended Markdown companion for the detailed work, decisions, results, exceptions, and follow-up that apply to this record."
         : "Keep the current facts and lifecycle state in JSON. Add optional Record Markdown only when the model fields cannot explain the record clearly.",
+      ...(type === "program" && String(loaded.model.modelVersion) === "4"
+        ? ["Review Requirement applicability with npx filegrc review-applicability --type requirement --scaffold, then preview and apply the reviewed decisions as one validated batch."]
+        : []),
       "Run npx filegrc validate, review the full Git diff, and commit the JSON, Markdown, and attachments together with a message that explains why the record changed."
     ],
     completionChecks: [
       "Required and status-dependent fields are complete, and the lifecycle status matches the facts.",
       "Every relationship resolves to the intended existing record.",
       "Dates describe the business event in the workspace time zone, not the file edit time.",
+      ...(type === "program" && String(loaded.model.modelVersion) === "4"
+        ? ["Every selected Requirement has an applicable or not-applicable decision reviewed against the current Program scope."]
+        : []),
       ...(recommendedMarkdown.length
         ? ["Required or recommended Markdown explains the work, decisions, results, exceptions, and follow-up that apply."]
         : ["The structured fields state the current fact clearly; optional Record Markdown is added only when needed."]),
@@ -172,7 +179,7 @@ export function scaffoldResourceMutation(loaded, type, title, options = {}) {
       record[name] = scaffoldValue(name, field, loaded.model);
     }
   }
-  applyModelScaffoldDefaults(record, loaded);
+  applyModelScaffoldDefaults(record, loaded, options);
 
   const slots = markdownEntries(loaded.model, record).filter((slot) => (
     slot.required
@@ -189,7 +196,7 @@ export function scaffoldResourceMutation(loaded, type, title, options = {}) {
   };
 }
 
-function applyModelScaffoldDefaults(record, loaded) {
+function applyModelScaffoldDefaults(record, loaded, options = {}) {
   if (record.type === "appointment") {
     const normalizedTitle = record.title.toLowerCase();
     const match = Object.entries(loaded.model.appointmentTemplates || {}).find(([kind, template]) => (
@@ -203,14 +210,18 @@ function applyModelScaffoldDefaults(record, loaded) {
     return;
   }
   if (record.type === "audit") {
+    const program = resolveProgram(loaded, options.programId);
     const kind = {
       "soc-2-type-1": "soc-2-type-1",
       "soc-2-type-2": "soc-2-type-2"
-    }[loaded.workspace?.assuranceGoal];
+    }[program?.assuranceGoal];
     if (kind) record.auditKind = kind;
     for (const field of ["frameworkIds", "systemIds", "requirementIds", "controlIds"]) {
-      if (loaded.workspace?.[field]?.length) record[field] = [...loaded.workspace[field]];
+      if (field === "requirementIds" && String(loaded.model.modelVersion) === "4") {
+        record[field] = (program.requirementApplicability || []).filter(({ decision }) => decision === "applicable").map(({ requirementId }) => requirementId);
+      } else if (program?.[field]?.length) record[field] = [...program[field]];
     }
+    if (program.type === "program") record.programId = program.id;
     const programOwner = loaded.resources.find((candidate) => (
       candidate.type === "appointment"
       && candidate.appointmentKind === "program-lead"
@@ -280,6 +291,7 @@ function allowedValues(model, field) {
 
 function scaffoldValue(name, field = {}, model) {
   if (field.const !== undefined) return field.const;
+  if (field.default !== undefined) return structuredClone(field.default);
   if (name === "status" && field.values) {
     return STARTING_STATUS_ORDER.find((value) => field.values.includes(value)) ?? field.values[0] ?? null;
   }

package/src/audit-preparation.js

@@ -55,7 +55,8 @@ export async function assessAuditPreparation(input, options = {}) {
   if (options.auditId && !audit) throw new Error(`Audit "${options.auditId}" was not found.`);
 
   const programReadiness = options.programReadiness || await assessProgramReadiness(loaded, {
-    generatedAt: options.generatedAt
+    generatedAt: options.generatedAt,
+    programId: audit?.programId
   });
   const stages = [
     programFoundationStage(programReadiness, loaded.workspace),
@@ -157,7 +158,8 @@ export async function prepareAuditWorkspace(input, options = {}) {
   const selectedControls = (audit.controlIds || [])
     .map((id) => loaded.resources.find((record) => record.id === id))
     .filter(Boolean);
-  const sourceSystems = loaded.resources.filter((record) => record.type === "system");
+  const v4 = String(loaded.model.modelVersion) === "4";
+  const sourceSystems = loaded.resources.filter((record) => record.type === (v4 ? "component" : "system"));
   const populations = (audit.auditKind === "soc-2-type-2" ? model.populationTemplates || [] : [])
     .filter((template) => !existingKinds.has(template.kind))
     .map((template) => {
@@ -183,7 +185,7 @@ export async function prepareAuditWorkspace(input, options = {}) {
         coverage: structuredClone(audit.coverage),
         ownerIds: [...audit.ownerIds],
         ...(controlIds.length ? { controlIds } : {}),
-        ...(matchingSources.length === 1 ? { sourceSystemId: matchingSources[0].id } : {}),
+        ...(matchingSources.length === 1 ? { [v4 ? "sourceComponentId" : "sourceSystemId"]: matchingSources[0].id } : {}),
         reconciliationSummary: `Authoritative source to confirm: ${template.sourcePrompt}. ${template.timing || ""}`.trim()
       };
     });
@@ -608,14 +610,16 @@ function evidenceStage(audit, records, byId, model) {
     item(
       "external-evidence",
       externalControls.length && controlsWithExternalEvidence.length === externalControls.length ? "complete" : externalControls.length ? "action" : "info",
-      "Review External Evidence",
+      "Review Evidence Artifacts",
       externalControls.length
-        ? `${controlsWithExternalEvidence.length} of ${externalControls.length} selected controls that rely on external systems have verified External Evidence for the formal period. Confirm the source System, date or period, control links, collector, verifier, and retained artifact or approved external reference.`
-        : "No selected controls require a separate External Evidence record.",
+        ? `${controlsWithExternalEvidence.length} of ${externalControls.length} selected controls that rely on external Components have verified Evidence Artifacts for the formal period. Confirm the source Component, date or period, control links, collector, verifier, and retained artifact or approved external reference.`
+        : "No selected controls require a separate Evidence Artifact.",
       externalEvidence[0] || { type: "evidence" }
     )
   ];
-  const systems = records.filter((record) => record.type === "system" && record.status === "active");
+  const v4 = String(model.modelVersion) === "4";
+  const systems = records.filter((record) => record.type === (v4 ? "component" : "system") && record.status === "active");
+  const sourceId = (record) => v4 ? record.sourceComponentId : record.sourceSystemId;
   for (const source of model.evidenceSourceFamilies || []) {
     const relevantControls = controls.filter((control) => (source.controlCodes || []).includes(control.code));
     if (!relevantControls.length) {
@@ -652,7 +656,7 @@ function evidenceStage(audit, records, byId, model) {
       (system.evidenceSourceKinds || []).some((kind) => (source.sourceKinds || []).includes(kind))
     ));
     const coveredControls = relevantControls.filter((control) => externalEvidence.some((record) => (
-      sourceSystems.some((system) => system.id === record.sourceSystemId)
+      sourceSystems.some((system) => system.id === sourceId(record))
       && controlIdsForRecord(record, byId).has(control.id)
     )));
     const status = sourceSystems.length && coveredControls.length === relevantControls.length ? "complete" : "action";
@@ -666,12 +670,12 @@ function evidenceStage(audit, records, byId, model) {
       status,
       source.title,
       message,
-      externalEvidence.find((record) => sourceSystems.some((system) => system.id === record.sourceSystemId))
+      externalEvidence.find((record) => sourceSystems.some((system) => system.id === sourceId(record)))
         || sourceSystems[0]
-        || { type: "system" }
+        || { type: v4 ? "component" : "system" }
     ));
   }
-  return stage("evidence", "Audit Evidence", "Review both evidence paths: dated filegrc operating records and verified External Evidence from authoritative systems. filegrc includes both in the audit packet.", items);
+  return stage("evidence", "Audit Evidence", `Review both evidence paths: dated filegrc operating records and verified ${v4 ? "Evidence Artifacts from authoritative Components" : "External Evidence from authoritative systems"}. filegrc includes both in the audit packet.`, items);
 }
 
 function populationsStage(audit, records, byId, model) {
@@ -748,8 +752,8 @@ function populationResult(population, audit, byId) {
     && evidence.type === "evidence"
     && evidence.artifactKind === "population-export"
     && evidence.status === "verified"
-    && population.sourceSystemId
-    && evidence.sourceSystemId === population.sourceSystemId
+    && (population.sourceComponentId || population.sourceSystemId)
+    && (evidence.sourceComponentId || evidence.sourceSystemId) === (population.sourceComponentId || population.sourceSystemId)
     && coverageMatches(
       evidence.coverage,
       coverageStart(audit.coverage),

package/src/audit-transition.js

@@ -4,8 +4,8 @@ import { loadWorkspace } from "./workspace.js";
 
 export async function planNextAuditCycle(input = process.cwd(), options = {}) {
   const loaded = await loadWorkspace(input);
-  if (String(loaded.model.modelVersion) !== "3") {
-    throw new Error("Audit-cycle carry-forward requires a model v3 workspace.");
+  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
+    throw new Error("Audit-cycle carry-forward requires a model v3 or v4 workspace.");
   }
   const prior = loaded.resources.find((record) => (
     record.type === "audit" && record.id === options.priorAuditId
@@ -32,8 +32,11 @@ export async function planNextAuditCycle(input = process.cwd(), options = {}) {
     requirementIds: [...(prior.requirementIds || [])],
     controlIds: [...(prior.controlIds || [])],
     complementaryControlIds: [...(prior.complementaryControlIds || [])],
-    subserviceVendorIds: [...(prior.subserviceVendorIds || [])],
-    ...(prior.subserviceMethod ? { subserviceMethod: prior.subserviceMethod } : {}),
+    ...(prior.programId ? { programId: prior.programId } : {}),
+    ...(prior.subserviceTreatments ? { subserviceTreatments: structuredClone(prior.subserviceTreatments) } : {
+      subserviceVendorIds: [...(prior.subserviceVendorIds || [])],
+      ...(prior.subserviceMethod ? { subserviceMethod: prior.subserviceMethod } : {})
+    }),
     ...(prior.complementaryControlsConclusion
       ? { complementaryControlsConclusion: prior.complementaryControlsConclusion }
       : {}),

package/src/batch-review.js

@@ -1,6 +1,7 @@
 import { applyResourceBatch } from "./files.js";
 import { getGitSummary } from "./git.js";
 import { loadWorkspace } from "./workspace.js";
+import { resolveProgram } from "./program.js";
 
 const REVIEWABLE_TYPES = new Set([
   "requirement",
@@ -11,17 +12,23 @@ const REVIEWABLE_TYPES = new Set([
 
 export async function scaffoldApplicabilityReview(input = process.cwd(), options = {}) {
   const loaded = await loadWorkspace(input);
-  if (String(loaded.model.modelVersion) !== "3") {
-    throw new Error("Batch applicability review requires a model v3 workspace.");
+  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
+    throw new Error("Batch applicability review requires a model v3 or v4 workspace.");
   }
   const requestedType = options.type ? String(options.type) : null;
   if (requestedType && !REVIEWABLE_TYPES.has(requestedType)) {
     throw new Error(`Applicability review type must be one of ${[...REVIEWABLE_TYPES].join(", ")}.`);
   }
+  const program = resolveProgram(loaded, options.programId);
+  const reviewedRequirementIds = new Set((program.requirementApplicability || [])
+    .filter(({ decision }) => ["applicable", "not-applicable"].includes(decision))
+    .map(({ requirementId }) => requirementId));
   const records = loaded.resources.filter((record) => (
     REVIEWABLE_TYPES.has(record.type)
     && (!requestedType || record.type === requestedType)
-    && !record.applicabilityReview
+    && (record.type === "requirement" && String(loaded.model.modelVersion) === "4"
+      ? !reviewedRequirementIds.has(record.id)
+      : !record.applicabilityReview)
     && !["retired", "superseded"].includes(record.status)
   ));
   return {
@@ -39,14 +46,16 @@ export async function scaffoldApplicabilityReview(input = process.cwd(), options
 
 export async function planApplicabilityReview(input = process.cwd(), options = {}) {
   const loaded = await loadWorkspace(input);
-  if (String(loaded.model.modelVersion) !== "3") {
-    throw new Error("Batch applicability review requires a model v3 workspace.");
+  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
+    throw new Error("Batch applicability review requires a model v3 or v4 workspace.");
   }
   if (!Array.isArray(options.decisions) || !options.decisions.length) {
     throw new Error("Applicability review needs at least one decision.");
   }
   const byId = new Map(loaded.resources.map((record) => [record.id, record]));
-  const update = options.decisions.map((decision) => {
+  const program = resolveProgram(loaded, options.programId);
+  const v4RequirementDecisions = [];
+  const update = options.decisions.flatMap((decision) => {
     const record = byId.get(decision.id);
     if (!record || !REVIEWABLE_TYPES.has(record.type)) {
       throw new Error(`Resource "${decision.id}" is not an applicability-review record.`);
@@ -81,16 +90,30 @@ export async function planApplicabilityReview(input = process.cwd(), options = {
       if (!["applicable", "not-applicable"].includes(result)) {
         throw new Error(`Requirement "${record.id}" must be applicable or not-applicable.`);
       }
+      if (String(loaded.model.modelVersion) === "4") {
+        v4RequirementDecisions.push({ requirementId: record.id, decision: result, rationale, reviewedByIds, reviewedOn, scopeRevision });
+        return [];
+      }
       next.applicability = result;
       next.applicabilityRationale = rationale;
     }
     if (record.type === "control" && result === "not-applicable") next.status = "not-applicable";
     if (record.type === "control" && result === "applicable" && record.status === "not-applicable") next.status = "planned";
-    return next;
+    return [next];
   });
+  if (v4RequirementDecisions.length) {
+    const replaced = new Set(v4RequirementDecisions.map(({ requirementId }) => requirementId));
+    update.push({
+      ...program,
+      requirementApplicability: [
+        ...(program.requirementApplicability || []).filter(({ requirementId }) => !replaced.has(requirementId)),
+        ...v4RequirementDecisions
+      ]
+    });
+  }
   return {
     operation: "applicability-review",
-    reviewedIds: update.map(({ id }) => id),
+    reviewedIds: options.decisions.map(({ id }) => id),
     changes: {
       update,
       expectedRevisions: options.expectedRevisions || {},

package/src/cli.js

@@ -43,6 +43,7 @@ import {
 import { relativeToWorkspace, resolveDataPath } from "./paths.js";
 import { buildAgentProgramPath } from "./program-path.js";
 import { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
+import { resolveProgram } from "./program.js";
 import { applyReconciliation, planReconciliation } from "./reconciliation.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { effectiveResourceStatus } from "./resource-status.js";
@@ -95,6 +96,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     const result = await serveWorkspace(positionals[0] ?? root, {
       host: flags.host ?? process.env.FILEGRC_HOST,
       port: flags.port ?? process.env.FILEGRC_PORT,
+      fallbackToAvailablePort: true,
       allowNonAuthoritativeWrites: flags["allow-non-authoritative-writes"] === true
     });
     const stopped = new Promise((resolvePromise) => {
@@ -106,6 +108,9 @@ export async function runCli(argv = process.argv.slice(2)) {
       process.once("SIGINT", stop);
       process.once("SIGTERM", stop);
     });
+    if (result.usedFallbackPort) {
+      console.log(`Port ${result.requestedPort} is already in use. Using ${result.address.port} instead.`);
+    }
     console.log(`filegrc workspace: ${result.url}`);
     console.log(`Data: ${result.root}/data`);
     printGithubStarMessage();
@@ -130,7 +135,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     const output = flags.summary && !flags.preview ? summarizeSetupResult(result) : result;
     if (flags.json) console.log(JSON.stringify(output, null, 2));
     else if (flags.preview) {
-      console.log(`Setup preview: ${result.changes.system} system ${result.system.id}; update workspace target to ${result.target.assuranceGoal}.`);
+      console.log(`Setup preview: ${result.changes.system} System ${result.system.id}; update the assurance target to ${result.target.assuranceGoal}.`);
       console.log("No controls will be linked and no evidence records will be created.");
     }
     else {
@@ -139,8 +144,8 @@ export async function runCli(argv = process.argv.slice(2)) {
       if (result.draft) {
         console.log("Planned and in scope means selected for scope review, not approved or active.");
       }
-      console.log(`Target: ${result.workspace.assuranceGoal}`);
-      console.log("Next: finish Step 1 by confirming people, criteria, commitments, vendors, and in-scope systems. Run npx filegrc program-path --next --json.");
+      console.log(`Target: ${(result.program || result.workspace).assuranceGoal}`);
+      console.log("Next: finish Step 1 by confirming people, criteria, commitments, bounded Systems, Components, and Vendors. Run npx filegrc program-path --next --json.");
     }
     return output;
   }
@@ -176,11 +181,15 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "migrate") {
     const targetModel = String(flags["to-model"] || "");
-    if (!["2", "3"].includes(targetModel)) throw new Error("Pass --to-model 2 or --to-model 3.");
+    if (!["2", "3", "4"].includes(targetModel)) throw new Error("Pass --to-model 2, --to-model 3, or --to-model 4.");
+    const systemDecisions = flags.decisions
+      ? JSON.parse(await readFile(resolve(String(flags.decisions)), "utf8"))
+      : undefined;
     const options = {
       jobTitle: flags["job-title"],
       startsOn: flags["starts-on"],
-      targetModelVersion: targetModel
+      targetModelVersion: targetModel,
+      systemDecisions: systemDecisions?.systemDecisions || systemDecisions
     };
     const plan = await planModelMigration(root, options);
     if (!flags.preview && plan.sourceModelVersion !== plan.targetModelVersion && !flags.yes) {
@@ -228,15 +237,17 @@ export async function runCli(argv = process.argv.slice(2)) {
       else printAgentOverview(result);
       return result;
     }
-    const result = buildAgentGuide(loaded, type, { id: flags.id });
+    const result = buildAgentGuide(loaded, type, { id: flags.id, programId: flags.program });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else printAgentGuide(result);
     return result;
   }
   if (command === "program-path") {
     const loaded = await loadWorkspace(root);
-    const readiness = await assessProgramReadiness(loaded, { asOf: flags["as-of"] });
     const auditId = positionals[0] || flags.audit;
+    const audit = auditId ? loaded.resources.find(({ id, type }) => id === auditId && type === "audit") : null;
+    const programId = flags.program || audit?.programId;
+    const readiness = await assessProgramReadiness(loaded, { asOf: flags["as-of"], programId });
     const auditReadiness = auditId ? await assessAuditPreparation(loaded, { auditId }) : null;
     const result = buildProgramPathResult(loaded.model, readiness, auditReadiness);
     const output = selectProgramPathOutput(result, flags);
@@ -247,6 +258,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (command === "workflow") {
     const result = await assessWorkflow(root, {
       auditId: positionals[0] || flags.audit,
+      programId: flags.program,
       asOf: flags["as-of"],
       through: flags.through,
       includeComplete: Boolean(flags.complete)
@@ -264,6 +276,7 @@ export async function runCli(argv = process.argv.slice(2)) {
       : undefined;
     const result = await assessWorkflow(root, {
       auditId: positionals[0] || flags.audit,
+      programId: flags.program,
       asOf: flags["as-of"],
       through: flags.end || flags.through,
       coverage
@@ -292,10 +305,11 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "milestone-check") {
     const loaded = await loadWorkspace(root);
-    const result = await assessWorkflow(loaded, { asOf: flags["as-of"] });
-    const target = loaded.workspace?.assuranceGoal === "none"
+    const result = await assessWorkflow(loaded, { asOf: flags["as-of"], programId: flags.program });
+    const program = resolveProgram(loaded, flags.program);
+    const target = program?.assuranceGoal === "none"
       ? "structuralValidity"
-      : loaded.workspace?.candidateCoverage
+      : program?.candidateCoverage
         ? "periodHealth"
         : "evidenceReadiness";
     const output = {
@@ -312,7 +326,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (command === "scaffold") {
     const loaded = await loadWorkspace(root);
     const type = positionals[0];
-    const result = scaffoldResourceMutation(loaded, type, flags.title, { id: flags.id });
+    const result = scaffoldResourceMutation(loaded, type, flags.title, { id: flags.id, programId: flags.program });
     console.log(JSON.stringify(result, null, 2));
     return result;
   }
@@ -333,7 +347,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     const output = flags.workflow
       ? {
           records,
-          workflow: await assessWorkflow(loaded, { asOf })
+          workflow: await assessWorkflow(loaded, { asOf, programId: flags.program })
         }
       : records;
     if (flags.json) console.log(JSON.stringify(output, null, 2));
@@ -394,7 +408,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "program-readiness") {
     const loaded = await loadWorkspace(root);
-    const result = await assessProgramReadiness(loaded, { asOf: flags["as-of"] });
+    const result = await assessProgramReadiness(loaded, { asOf: flags["as-of"], programId: flags.program });
     const output = flags.summary ? summarizeProgramReadiness(result) : result;
     if (flags.json) console.log(JSON.stringify(output, null, 2));
     else if (flags.summary) {
@@ -427,7 +441,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "evidence-map") {
     const loaded = await loadWorkspace(root);
-    const result = await assessEvidenceMap(loaded, { asOf: flags["as-of"] });
+    const result = await assessEvidenceMap(loaded, { asOf: flags["as-of"], programId: flags.program });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else {
       console.log(`${result.status.toUpperCase()}: ${result.counts.complete} mapped, ${result.counts.action} need action`);
@@ -435,11 +449,11 @@ export async function runCli(argv = process.argv.slice(2)) {
         console.log(`${item.status.toUpperCase()}\t${item.title}\t${item.message}`);
         if (item.status !== "action") continue;
         if (item.sourceKinds?.length) console.log(`  Source role: ${item.sourceKinds.join(" or ")}`);
-        for (const source of item.sourceSystemChecks || []) {
+        for (const source of item.sourceComponentChecks || item.sourceSystemChecks || []) {
           const missing = Object.entries(source.checks)
             .filter(([, passed]) => !passed)
             .map(([name]) => evidenceSourceCheckName(name));
-          if (missing.length) console.log(`  ${source.sourceSystemId}: ${missing.join(", ")}`);
+          if (missing.length) console.log(`  ${source.sourceComponentId || source.sourceSystemId}: ${missing.join(", ")}`);
         }
         if (item.commands?.length) console.log(`  Next: ${item.commands[0]}`);
       }
@@ -989,15 +1003,15 @@ Usage:
   filegrc build [root] [--output .filegrc/site]
   filegrc validate [root] [--json]
   filegrc model [--json|--write-docs|--check-docs]
-  filegrc migrate --to-model <2|3> [--preview] [--job-title text] [--starts-on YYYY-MM-DD] [--yes] [--json]
+  filegrc migrate --to-model <2|3|4> [--preview] [--decisions path] [--job-title text] [--starts-on YYYY-MM-DD] [--yes] [--json]
   filegrc describe <resource-type>
   filegrc types [--json]
-  filegrc guide [resource-type] [--id resource-id] [--json]
+  filegrc guide [resource-type] [--id resource-id] [--program program-id] [--json]
   filegrc program-path [audit-id] [--as-of YYYY-MM-DD] [--summary|--next|--current] [--json]
   filegrc workflow [audit-id] [--as-of YYYY-MM-DD] [--through YYYY-MM-DD] [--complete] [--require-ready] [--json]
   filegrc period-health [audit-id] [--start YYYY-MM-DD --end YYYY-MM-DD] [--as-of YYYY-MM-DD] [--require-healthy] [--json]
   filegrc milestone-check [--as-of YYYY-MM-DD] [--json]
-  filegrc scaffold <resource-type> --title text [--id resource-id]
+  filegrc scaffold <resource-type> --title text [--id resource-id] [--program program-id]
   filegrc list [resource-type] [--workflow] [--json]
   filegrc search <query> [--type resource-type] [--json]
   filegrc obligations [--as-of YYYY-MM-DD] [--from YYYY-MM-DD] [--through YYYY-MM-DD] [--now RFC3339] [--complete] [--json]
@@ -1038,7 +1052,8 @@ function printCommandHelp(command) {
 
 Options:
   --host <address>  Bind address. Defaults to FILEGRC_HOST or 127.0.0.1.
-  --port <number>   Port. Defaults to FILEGRC_PORT or 8787. Use 0 for an available port.
+  --port <number>   Preferred port. Defaults to FILEGRC_PORT or 8787. If occupied,
+                    the server uses an available port. Use 0 to choose one directly.
   --root <path>     Workspace path when no positional root is given.
   --allow-non-authoritative-writes
                      Allow local browser writes from a task checkout. This explicit
@@ -1076,15 +1091,19 @@ Options:
   }
   if (command === "migrate") {
     console.log(`Usage:
-  filegrc migrate --to-model <2|3> [options]
+  filegrc migrate --to-model <2|3|4> [options]
 
 Upgrade a workspace through an explicit, reviewable model boundary. Model v1
-workspaces migrate to v2 first. Model v2 workspaces migrate to v3 with planned
+workspaces migrate to v2 first. Model v2 workspaces migrate to v3, then v4. v4 separates
+the repository Workspace, management Program, bounded Systems, operational Components,
+specific Assets, Vendors, normalized information, and Evidence Artifacts. v3 migration
+previews may require a decisions JSON file for ambiguous old Systems. v3 still creates planned
 core Appointments, removal of obsolete manual page state, classified review work,
 and dataModelVersion changed last. The command writes no Git commit.
 
 Options:
-  --to-model <version>  Required target model; 2 for legacy v1 migration, 3 for the active model
+  --to-model <version>  Required target model; migrations must run in order through 2, 3, and 4
+  --decisions <path>    v4 JSON object keyed by old System ID with system/component decisions
   --preview             Show the complete atomic record plan without writing
   --job-title <title>   Actual job title for the former Policy Owner seed person
   --starts-on <date>    Effective date of a new Policy Owner Appointment
@@ -1094,7 +1113,7 @@ Options:
   --help                Show this help
 
 Start with:
-  npx filegrc migrate --to-model 3 --preview --json`);
+  npx filegrc migrate --to-model 4 --preview --json`);
     return;
   }
   if (command === "program-readiness") {
@@ -1106,6 +1125,7 @@ controls, and mapped every selected control to a configured authoritative eviden
 source. No audit ID or CPA firm is required.
 
 Options:
+  --program <id>     Program to assess when more than one active Program exists
   --as-of <date>     Evaluate effective dates and obligations on YYYY-MM-DD
   --require-ready    Exit with code 2 unless the Evidence Ready gate passes
   --summary          Omit item details and print stage counts and next actions
@@ -1124,6 +1144,7 @@ deterministic Work Items, and one recommended next action.
 
 Options:
   --audit <id>       Limit audit assessments to one engagement
+  --program <id>     Program to assess when no Audit supplies the Program
   --as-of <date>     Evaluate on YYYY-MM-DD
   --through <date>   Include scheduled work through YYYY-MM-DD
   --complete         Include completed Work Items
@@ -1143,6 +1164,7 @@ and current readiness state. Pass an audit ID to include Step 5 status.
 
 Options:
   --audit <id>       Audit record to use for Step 5
+  --program <id>     Program to assess when no Audit supplies the Program
   --as-of <date>     Evaluate readiness on YYYY-MM-DD
   --summary          Print compact status and the first action for all five steps
   --next             Print only the current step and its first action
@@ -1157,10 +1179,11 @@ Options:
   filegrc evidence-map [options]
 
 Inspect the evidence-source checks included in Control implementation. Each item
-reports the required source roles, linked Controls, authoritative source Systems,
+reports the required source roles, linked Controls, authoritative source Components,
 per-record checks, and exact edit commands. This diagnostic is read-only.
 
 Options:
+  --program <id>  Program to assess when more than one active Program exists
   --as-of <date>  Evaluate the map on YYYY-MM-DD
   --json          Print the map as JSON
   --root <path>   Workspace path
@@ -1179,7 +1202,7 @@ function agentOverview(model) {
     build: "filegrc build [root]",
     validate: "filegrc validate [root] --json",
     model: "filegrc model --json",
-    migrate: "filegrc migrate --to-model 3 --preview --json",
+    migrate: "filegrc migrate --to-model 4 --preview --json",
     describe: "filegrc describe <resource-type>",
     types: "filegrc types --json",
     guide: "filegrc guide [resource-type] --json",