filegrc 0.15.0 → 0.15.2

package/src/collection-review.js

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { modelSupports } from "../model/index.js";
 import {
   collectionRevision,
   collectionRevisionMatches
 } from "./collection-revision.js";
-import { scopedCollectionRecords } from "./collection-scope.js";
-import { applyResourceBatch, INTERNAL_WORKFLOW_CAPABILITIES } from "./files.js";
+import { collectionRecordProposals, retentionScheduleReviewScope, scopedCollectionRecords } from "./collection-scope.js";
+import { applyResourceBatch, applyRetentionScheduleReviewBatch, contentRevision, INTERNAL_WORKFLOW_CAPABILITIES } from "./files.js";
 import { getGitSummary } from "./git.js";
 import { createResourceId } from "./id.js";
 import { loadWorkspace } from "./workspace.js";
@@ -13,6 +14,8 @@ import { resolveProgram } from "./program.js";
 import { currentCalendarDate } from "./time.js";
 import { currentPartyPeople } from "./parties.js";
 import { retentionScheduleApprovalIssues } from "./retention-schedule-approval.js";
+import { markdownEntries } from "./resource-markdown.js";
+import { resolveDataPath } from "./paths.js";
 
 export { collectionRevision };
 
@@ -29,13 +32,21 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
   const configuration = loaded.model.collectionReviews?.[resourceType];
   if (!configuration) return null;
   const program = resolveProgram(loaded, options.programId);
+  const workspaceWideRetentionReview = resourceType === "retention-schedule-item"
+    && modelSupports(loaded.model, "retention-schedule-approval");
+  const retentionScope = workspaceWideRetentionReview ? retentionScheduleReviewScope(loaded) : null;
   const records = scopedCollectionRecords(loaded, resourceType, program);
-  const reviewEntry = loaded.entries.find(({ record }) => (
+  const reviewEntries = loaded.entries.filter(({ record }) => (
     record.type === "collection-review"
     && record.resourceType === resourceType
     && record.status !== "retired"
-    && (!modelSupports(loaded.model, "program-scope") || (record.scopeResourceIds || []).includes(program.id))
+    && (workspaceWideRetentionReview
+      || !modelSupports(loaded.model, "program-scope")
+      || (record.scopeResourceIds || []).includes(program.id))
   ));
+  const reviewEntry = workspaceWideRetentionReview
+    ? reviewEntries.find(({ record }) => sameIds(record.scopeResourceIds, retentionScope.programIds)) || reviewEntries[0]
+    : reviewEntries[0];
   const review = reviewEntry?.record || null;
   const authoritativeSourceId = review?.decision === "externally-managed"
     ? review.authoritativeComponentId || review.authoritativeSystemId
@@ -71,26 +82,35 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
       ? assessRetentionScheduleReviewers(loaded, records)
       : null;
   const approvalIssues = resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")
-    ? retentionScheduleApprovalIssues(loaded, program, records, {
-        informationTypesReviewed: assessCollectionReview(loaded, "information-type", options).complete
+    ? retentionScheduleApprovalIssues(loaded, retentionScope, records, {
+        informationTypesReviewed: retentionScope.programIds.every((id) => (
+          assessCollectionReview(loaded, "information-type", { programId: id }).complete
+        )),
+        approvalReview: review?.status === "active" ? review : null
       })
     : [];
+  const recordProposals = collectionRecordProposals(loaded, resourceType, records, program);
+  const incompleteRecordProposals = recordProposals.filter(({ complete: ready }) => !ready);
   const reviewersEligible = !reviewerEligibility || Boolean(
     review?.reviewedByIds?.length
     && review.reviewedByIds.every((id) => reviewerEligibility.eligibleReviewerIds.includes(id))
   );
+  const reviewScopeMatches = !workspaceWideRetentionReview
+    || sameIds(review?.scopeResourceIds, retentionScope.programIds);
   const complete = Boolean(
     review?.status === "active"
     && allowedDecisions.includes(review.decision)
     && revisionMatches
     && temporalReview
+    && reviewScopeMatches
     && reviewersEligible
+    && !incompleteRecordProposals.length
     && !approvalIssues.length
   );
   const stale = Boolean(
     review?.status === "active"
     && review.collectionRevision
-    && !revisionMatches
+    && (!revisionMatches || !reviewScopeMatches)
   );
   return {
     resourceType,
@@ -101,15 +121,19 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
     reviewRevision: reviewEntry
       ? createHash("sha256").update(reviewEntry.source).digest("hex")
       : null,
+    reviewEntries,
     collectionRevision: currentRevision,
     status: complete ? "current" : stale ? "stale" : "review-required",
     complete,
     ...(reviewerEligibility || {}),
+    ...(recordProposals.length ? { recordProposals, incompleteRecordProposals } : {}),
     ...(approvalIssues.length ? { approvalIssues } : {}),
     message: complete
       ? `${configuration.title} were reviewed on ${review.reviewedOn}.`
       : approvalIssues.length
         ? approvalIssues[0].message
+      : incompleteRecordProposals.length
+        ? `Complete ${incompleteRecordProposals.length} ${configuration.title.toLowerCase()} ${incompleteRecordProposals.length === 1 ? "record proposal" : "record proposals"} before the collection review.`
       : revisionMatches && review?.status === "active" && !reviewersEligible
         ? resourceType === "retention-schedule-item"
           ? "Review the Data Retention Schedule again with a reviewer who does not own its governing document or an included schedule row."
@@ -122,6 +146,11 @@ export function assessCollectionReview(loaded, resourceType, options = {}) {
   };
 }
 
+export function retentionScheduleIsAuthoritative(loaded, program) {
+  return !modelSupports(loaded.model, "retention-schedule-approval")
+    || assessCollectionReview(loaded, "retention-schedule-item", { programId: program?.id }).complete;
+}
+
 export async function scaffoldCollectionReview(input = process.cwd(), options = {}) {
   const loaded = await loadWorkspace(input);
   const program = resolveProgram(loaded, options.programId);
@@ -170,6 +199,9 @@ export async function planCollectionReview(input = process.cwd(), options = {})
   const loaded = await loadWorkspace(input);
   const program = resolveProgram(loaded, options.programId);
   const resourceType = requiredType(loaded, options.resourceType);
+  const workspaceWideRetentionReview = resourceType === "retention-schedule-item"
+    && modelSupports(loaded.model, "retention-schedule-approval");
+  const retentionScope = workspaceWideRetentionReview ? retentionScheduleReviewScope(loaded) : null;
   const assessment = assessCollectionReview(loaded, resourceType, { programId: program.id });
   if (options.expectedCollectionRevision && options.expectedCollectionRevision !== assessment.collectionRevision) {
     throw new Error(`${assessment.configuration.title} changed after it was displayed. Reload and review the current revision before approving it.`);
@@ -178,7 +210,8 @@ export async function planCollectionReview(input = process.cwd(), options = {})
     throw new Error("Data Retention Schedule approval requires the displayed collection revision. Reload or scaffold the current review before approving it.");
   }
   await requireControlReviewReady(loaded, resourceType, program.id);
-  await requireRetentionScheduleReady(loaded, resourceType, program);
+  await requireRetentionScheduleReady(loaded, resourceType, program, retentionScope);
+  requireCollectionRecordProposalsReady(assessment);
   const configuration = assessment.configuration;
   const decision = String(options.decision || "").trim();
   const rationale = String(options.rationale || "").trim();
@@ -251,6 +284,9 @@ export async function planCollectionReview(input = process.cwd(), options = {})
     authoritativeSourceId: decision === "externally-managed" ? authoritativeSourceId : null
   });
   const existing = assessment.review;
+  const existingEntries = workspaceWideRetentionReview
+    ? assessment.reviewEntries
+    : assessment.reviewEntries.filter(({ record }) => record.id === existing?.id);
   const preservesReviewHistory = temporalReviews;
   const record = {
     ...(!existing ? {
@@ -264,7 +300,7 @@ export async function planCollectionReview(input = process.cwd(), options = {})
       type: "collection-review",
       title: `${configuration.title} review`,
       resourceType,
-      scopeResourceIds: [program.id]
+      scopeResourceIds: workspaceWideRetentionReview ? retentionScope.programIds : [program.id]
     } : preservesReviewHistory ? {
       ...existing,
       id: createResourceId(
@@ -281,6 +317,7 @@ export async function planCollectionReview(input = process.cwd(), options = {})
     reviewedOn,
     collectionRevision: currentRevision,
     scopeRevision,
+    ...(workspaceWideRetentionReview ? { scopeResourceIds: retentionScope.programIds } : {}),
     ...(temporalReviews ? {
       coverage: { kind: "as-of", on: reviewedOn },
       knowledgeCutoffAt: now.toISOString(),
@@ -294,34 +331,86 @@ export async function planCollectionReview(input = process.cwd(), options = {})
     delete record.authoritativeSystemId;
     delete record.authoritativeComponentId;
   }
+  const creates = !existing || preservesReviewHistory ? [record] : [];
+  const updates = !existing || preservesReviewHistory ? [] : [record];
+  const expectedRevisions = Object.fromEntries(existingEntries.map((entry) => [
+    entry.record.id,
+    entry.record.id === existing?.id && options.expectedRevision
+      ? options.expectedRevision
+      : createHash("sha256").update(entry.source).digest("hex")
+  ]));
+  if (existingEntries.length && preservesReviewHistory) {
+    for (const entry of existingEntries) {
+      updates.push({
+        ...entry.record,
+        status: "retired",
+        statusTransition: {
+          changedByIds: reviewedByIds,
+          changedOn: reviewedOn,
+          reason: `Superseded by ${record.id}.`
+        }
+      });
+    }
+  }
+  if (resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")) {
+    const scheduleEntry = loaded.entries.find(({ record: candidate }) => (
+      candidate.type === "document"
+      && candidate.documentKind === "schedule"
+      && candidate.workflowScope === "program"
+      && !["superseded", "retired"].includes(candidate.status)
+    ));
+    if (scheduleEntry && ["draft", "approved", "active"].includes(scheduleEntry.record.status)) {
+      const currentContentRevisions = await contentRevisions(loaded, scheduleEntry.record);
+      const approvedSchedule = {
+        ...scheduleEntry.record,
+        status: "approved",
+        approverIds: reviewedByIds,
+        approvedOn: reviewedOn,
+        approvedContentRevisions: currentContentRevisions
+      };
+      for (const field of [
+        "activationBasis",
+        "activatedByIds",
+        "activatedOn",
+        "activatedContentRevisions",
+        "effectiveOn",
+        "statusTransition"
+      ]) delete approvedSchedule[field];
+      updates.push(approvedSchedule);
+      expectedRevisions[scheduleEntry.record.id] = scheduleEntry.revision;
+    }
+  }
   return {
     operation: "collection-review",
     resourceType,
     assessment,
     changes: {
-      ...(!existing || preservesReviewHistory ? { create: [record] } : { update: [record] }),
-      ...(existing && preservesReviewHistory ? {
-        update: [{
-          ...existing,
-          status: "retired",
-          statusTransition: {
-            changedByIds: reviewedByIds,
-            changedOn: reviewedOn,
-            reason: `Superseded by ${record.id}.`
-          }
-        }]
-      } : {}),
-      ...(existing ? {
-        expectedRevisions: {
-          [existing.id]: options.expectedRevision || assessment.reviewRevision
-        }
-      } : {}),
+      ...(creates.length ? { create: creates } : {}),
+      ...(updates.length ? { update: updates } : {}),
+      ...(Object.keys(expectedRevisions).length ? { expectedRevisions } : {}),
       validateWholeWorkspace: true,
       workflowCapability: INTERNAL_WORKFLOW_CAPABILITIES.collectionReviewReassessment
     }
   };
 }
 
+function requireCollectionRecordProposalsReady(assessment) {
+  const incomplete = assessment.incompleteRecordProposals || [];
+  if (!incomplete.length) return;
+  throw new Error(
+    `Complete every ${assessment.configuration.title.toLowerCase()} record proposal before the collection review. Remaining: ${incomplete.map(({ title }) => title).join(", ")}.`
+  );
+}
+
+async function contentRevisions(loaded, record) {
+  const revisions = {};
+  for (const markdown of markdownEntries(loaded.model, record)) {
+    const source = await readFile(resolveDataPath(loaded.root, markdown.path), "utf8");
+    revisions[markdown.path] = contentRevision(source);
+  }
+  return revisions;
+}
+
 async function requireControlReviewReady(loaded, resourceType, programId) {
   if (resourceType !== "control") return;
   const { assessProgramReadiness } = await import("./program-readiness.js");
@@ -339,11 +428,13 @@ async function requireControlReviewReady(loaded, resourceType, programId) {
   }
 }
 
-async function requireRetentionScheduleReady(loaded, resourceType, program) {
+async function requireRetentionScheduleReady(loaded, resourceType, program, retentionScope) {
   if (resourceType !== "retention-schedule-item" || !modelSupports(loaded.model, "retention-schedule-approval")) return;
   const rows = scopedCollectionRecords(loaded, resourceType, program);
-  const approvalIssues = retentionScheduleApprovalIssues(loaded, program, rows, {
-    informationTypesReviewed: assessCollectionReview(loaded, "information-type", { programId: program.id }).complete
+  const approvalIssues = retentionScheduleApprovalIssues(loaded, retentionScope || program, rows, {
+    informationTypesReviewed: (retentionScope?.programIds || [program.id]).every((id) => (
+      assessCollectionReview(loaded, "information-type", { programId: id }).complete
+    ))
   });
   if (approvalIssues.length) throw new Error(approvalIssues[0].message);
 }
@@ -388,7 +479,7 @@ function assessRetentionScheduleReviewers(loaded, rows) {
   };
 }
 
-function sameIds(left, right) {
+function sameIds(left = [], right = []) {
   return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
 }
 
@@ -397,7 +488,9 @@ export async function applyCollectionReview(input = process.cwd(), options = {})
     throw new Error("Preview the collection review and confirm the write.");
   }
   const plan = await planCollectionReview(input, options);
-  const result = await applyResourceBatch(input, plan.changes);
+  const result = plan.resourceType === "retention-schedule-item"
+    ? await applyRetentionScheduleReviewBatch(input, plan.changes)
+    : await applyResourceBatch(input, plan.changes);
   const loaded = await loadWorkspace(input);
   return {
     ...plan,

package/src/collection-revision.js

@@ -30,7 +30,12 @@ export function collectionRevisionMatches(loaded, resourceType, storedRevision,
 }
 
 function calculateCollectionRevision(loaded, resourceType, options, legacy) {
-  const program = Object.hasOwn(options, "program")
+  const workspaceWideRetentionReview = resourceType === "retention-schedule-item"
+    && modelSupports(loaded.model, "retention-schedule-approval")
+    && !legacy;
+  const program = workspaceWideRetentionReview
+    ? null
+    : Object.hasOwn(options, "program")
     ? options.program
     : resolveProgram(loaded, options.programId);
   const inputs = new Map(collectionRevisionInputs(loaded, resourceType, program, { legacy })

package/src/collection-scope.js

@@ -65,6 +65,77 @@ export function scopedCollectionRecords(loaded, resourceType, program) {
   ));
 }
 
+export function retentionScheduleReviewScope(loaded) {
+  const programs = loaded.resources.filter((record) => (
+    record.type === "program" && record.status !== "retired"
+  ));
+  return {
+    id: "workspace",
+    programIds: programs.map(({ id }) => id).sort(),
+    systemIds: [...new Set(programs.flatMap((record) => record.systemIds || []))],
+    controlIds: [...new Set(programs.flatMap((record) => record.controlIds || []))],
+    frameworkIds: [...new Set(programs.flatMap((record) => record.frameworkIds || []))]
+  };
+}
+
+const RECORD_PROPOSAL_COLLECTIONS = new Set([
+  "component",
+  "vendor",
+  "complementary-control",
+  "information-type"
+]);
+
+export function collectionRecordProposals(loaded, resourceType, records, program) {
+  if (!RECORD_PROPOSAL_COLLECTIONS.has(resourceType)) return [];
+  const currentRecords = records.filter((record) => collectionRecordIsCurrent(record));
+  const scopedIds = new Set(currentRecords.map(({ id }) => id));
+  const candidates = new Map(currentRecords.map((record) => [record.id, record]));
+  const activePrograms = loaded.resources.filter((record) => record.type === "program" && record.status !== "retired");
+  if (activePrograms.length === 1 && activePrograms[0].id === program?.id && ["component", "complementary-control"].includes(resourceType)) {
+    for (const record of loaded.resources) {
+      if (
+        record.type !== resourceType
+        || ["retired", "superseded"].includes(record.status)
+        || collectionRecordProposalComplete(record, loaded)
+      ) continue;
+      candidates.set(record.id, record);
+    }
+  }
+  return [...candidates.values()].map((record) => ({
+    resourceId: record.id,
+    title: record.title,
+    complete: scopedIds.has(record.id) && collectionRecordProposalComplete(record, loaded)
+  }));
+}
+
+function collectionRecordIsCurrent(record) {
+  if (record.type === "vendor") return !["deprecated", "terminated"].includes(record.status);
+  if (record.type === "information-type") return !["superseded", "retired"].includes(record.status);
+  if (record.type === "complementary-control") return !["superseded", "retired"].includes(record.status);
+  return record.status !== "retired";
+}
+
+function collectionRecordProposalComplete(record, loaded) {
+  if (record.type === "vendor") return record.status !== "evaluating";
+  if (record.type === "component") {
+    if (record.status === "planned") return false;
+    if (record.status === "retired") return true;
+    return record.status === "active"
+      && Boolean(String(record.description || "").trim())
+      && (record.ownerIds || []).length > 0
+      && (record.systemUses || []).length > 0
+      && (record.systemUses || []).every(({ roles, rationale }) => (
+        (roles || []).length > 0 && Boolean(String(rationale || "").trim())
+      ));
+  }
+  if (record.type === "information-type") {
+    if (record.status === "retired") return true;
+    const classification = loaded.resources.find(({ id, type }) => type === "classification" && id === record.classificationId);
+    return record.status === "active" && classification?.status === "active";
+  }
+  return record.status !== "planned";
+}
+
 export function selectScopedCollectionRecords(loaded, selector, program) {
   if (!selector?.resourceType) return [];
   return scopedCollectionRecords(loaded, selector.resourceType, program).filter((record) => (
@@ -231,7 +302,10 @@ export function collectionRevisionInputs(loaded, resourceType, program, options
       .map(({ id }) => id));
   }
   if (resourceType === "retention-schedule-item" && !legacy && modelSupports(loaded.model, "retention-schedule-approval")) {
-    const uses = retentionUses(loaded, program || {});
+    const programs = program
+      ? [program]
+      : loaded.resources.filter((record) => record.type === "program" && record.status !== "retired");
+    const uses = programs.flatMap((candidate) => retentionUses(loaded, candidate));
     addIds(uses.map(({ resource }) => resource.id));
     addIds(uses.map(({ informationTypeId }) => informationTypeId));
     const schedules = loaded.resources
@@ -243,14 +317,14 @@ export function collectionRevisionInputs(loaded, resourceType, program, options
       ))
     addIds(schedules.map(({ id }) => id));
     for (const schedule of schedules) {
-      addPartyIds([...(schedule.ownerIds || []), ...(schedule.approverIds || [])]);
+      addPartyIds(schedule.ownerIds || []);
     }
     for (const record of reviewed) {
       addIds([record.scheduleDocumentId]);
       addIds(record.informationTypeIds);
       addIds(record.scopeResourceIds);
       addIds(record.sourceResourceIds);
-      addPartyIds([...(record.ownerIds || []), ...(record.approvedByIds || [])]);
+      addPartyIds(record.ownerIds || []);
     }
   }
   if (resourceType === "complementary-control") {
@@ -267,14 +341,43 @@ export function collectionRevisionInputs(loaded, resourceType, program, options
   return [...records.values()].map((record) => ({
     record,
     value: reviewedIds.has(record.id)
-      ? record
-      : dependencyRevisionValue(resourceType, record, legacy),
+      ? resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")
+        ? retentionScheduleRowProposalValue(record)
+        : record
+      : resourceType === "retention-schedule-item"
+        && modelSupports(loaded.model, "retention-schedule-approval")
+        && record.type === "document"
+          ? retentionScheduleDocumentProposalValue(record)
+          : dependencyRevisionValue(resourceType, record, legacy),
     includeContent: legacy
       || reviewedIds.has(record.id)
       || dependencyContentAffectsRevision(resourceType, record.type)
   }));
 }
 
+function retentionScheduleRowProposalValue(record) {
+  return Object.fromEntries(Object.entries(record).filter(([field]) => ![
+    "approvedByIds",
+    "approvedOn"
+  ].includes(field)));
+}
+
+function retentionScheduleDocumentProposalValue(record) {
+  return Object.fromEntries(Object.entries(record).filter(([field]) => ![
+    "status",
+    "approverIds",
+    "approvedOn",
+    "approvedContentRevisions",
+    "activationBasis",
+    "activatedByIds",
+    "activatedOn",
+    "activatedContentRevisions",
+    "effectiveOn",
+    "proposedEffectiveOn",
+    "statusTransition"
+  ].includes(field)));
+}
+
 export function collectionScopeRevisionFacts(loaded, resourceType, program) {
   if (!modelSupports(loaded.model, "program-scope")) {
     const common = { programId: program?.id ?? null };
@@ -296,6 +399,19 @@ export function collectionScopeRevisionFacts(loaded, resourceType, program) {
     }
     return common;
   }
+  if (resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")) {
+    const programs = loaded.resources
+      .filter((record) => record.type === "program" && record.status !== "retired")
+      .sort((left, right) => left.id.localeCompare(right.id));
+    return {
+      programIds: programs.map(({ id }) => id),
+      programs: programs.map((record) => ({
+        id: record.id,
+        systemIds: sorted(record.systemIds),
+        controlIds: sorted(record.controlIds)
+      }))
+    };
+  }
   const common = { programId: program?.id ?? null };
   if (resourceType === "framework") {
     return {

package/src/files.js

@@ -234,6 +234,12 @@ export async function applyGovernedContentActivationBatch(input, changes) {
   ));
 }
 
+export async function applyRetentionScheduleReviewBatch(input, changes) {
+  return serializeWorkspaceMutation(input, (root) => (
+    applyResourceBatchUnlocked(root, changes, "retention-schedule-approval")
+  ));
+}
+
 export async function applyModelMigrationBatch(input, changes) {
   return serializeWorkspaceMutation(input, (root) => (
     applyResourceBatchUnlocked(root, changes, "model-migration")
@@ -1231,7 +1237,13 @@ function assertGovernedContentLifecycleMutation(previousRecord, nextRecord, mode
   const title = getResourceDefinition(model, nextRecord.type).title;
   const approvedStatuses = new Set(["approved", "active", "superseded", "retired"]);
   const activatedStatuses = new Set(["active", "superseded", "retired"]);
-  if (approvedStatuses.has(previousRecord.status) && approvedStatuses.has(nextRecord.status)) {
+  const retentionScheduleReapproval = lifecycleOperation === "retention-schedule-approval"
+    && previousRecord.type === "document"
+    && previousRecord.documentKind === "schedule"
+    && previousRecord.workflowScope === "program"
+    && nextRecord.documentKind === "schedule"
+    && nextRecord.workflowScope === "program";
+  if (approvedStatuses.has(previousRecord.status) && approvedStatuses.has(nextRecord.status) && !retentionScheduleReapproval) {
     assertLifecycleFieldsUnchanged(previousRecord, nextRecord, [
       "approverIds",
       "approvedOn",

package/src/git.js

@@ -1774,6 +1774,92 @@ export async function prefetchBrowserRemote(
   return prefetch;
 }
 
+export async function synchronizeBrowserStartup(
+  input = process.cwd(),
+  options = {},
+) {
+  return serializeWorkspaceMutation(input, async (root) => {
+    const config = await getRepositoryConfig(root);
+    if (config.mode !== "trunk" || options.allowNonAuthoritativeWrites === true) {
+      return { status: "not-needed", updated: false };
+    }
+
+    const before = await requireTrunkPreconditionsAsync(root, config, {
+      allowAhead: true,
+    });
+    await fetchConfiguredRemote(root, config);
+    const synchronized = inspectTrunkRepository(
+      root,
+      config,
+      await getRepositorySnapshot(root, { fresh: true }),
+    );
+    if (synchronized.ahead > 0 || synchronized.behind === 0) {
+      return {
+        status: synchronized.ahead > 0 ? "blocked" : "current",
+        updated: false,
+        ahead: synchronized.ahead,
+        behind: synchronized.behind,
+        commit: synchronized.currentCommit,
+      };
+    }
+
+    const target = synchronized.upstreamCommit;
+    const incomingCommits = lines(
+      git(root, [
+        "rev-list",
+        "--reverse",
+        `${synchronized.currentCommit}..${target}`,
+      ]),
+    );
+    assertCommitsInsideWorkspace(root, incomingCommits);
+    for (const commit of incomingCommits) assertNoCommitWorkspaceContentFilters(root, commit);
+    assertExpectedCheckout(
+      root,
+      `refs/heads/${config.authoritativeBranch}`,
+      before.currentCommit,
+    );
+    await gitForWriteAsync(
+      root,
+      [
+        "-c",
+        "core.hooksPath=/dev/null",
+        "merge",
+        "--ff-only",
+        "--no-edit",
+        "--no-stat",
+        target,
+      ],
+      `fast-forward ${config.authoritativeBranch} at server startup`,
+      {
+        expectedCheckout: {
+          expectedRef: `refs/heads/${config.authoritativeBranch}`,
+          expectedCommit: before.currentCommit,
+        },
+        expectedNoOperation: true,
+      },
+    );
+    const after = inspectTrunkRepository(
+      root,
+      config,
+      await getRepositorySnapshot(root, { fresh: true }),
+    );
+    if (after.ahead !== 0 || after.behind !== 0 || after.currentCommit !== target) {
+      throw new Error(
+        "The authoritative branch changed while FileGRC fast-forwarded it. Reconcile the repository with Git, then restart FileGRC.",
+      );
+    }
+    const synchronizedAt = new Date().toISOString();
+    lastSuccessfulSynchronizations.set(root, synchronizedAt);
+    return {
+      status: "updated",
+      updated: true,
+      commit: after.currentCommit,
+      shortCommit: after.currentCommit.slice(0, 8),
+      synchronizedAt,
+    };
+  });
+}
+
 async function prefetchBrowserRemoteCoalesced(root, options) {
   const prepared = await serializeWorkspaceMutation(root, async () => {
     const config = await getRepositoryConfig(root);

package/src/index.js

@@ -49,7 +49,8 @@ export {
   pullWorkspace,
   pushWorkspace,
   retryBrowserSync,
-  runBrowserMutation
+  runBrowserMutation,
+  synchronizeBrowserStartup
 } from "./git.js";
 export { generateModelDocumentation } from "./model-docs.js";
 export { renderMarkdown } from "./markdown.js";
@@ -86,7 +87,7 @@ export {
   scaffoldExternalReviewerGovernance,
   setupExternalReviewerGovernance
 } from "./external-reviewer.js";
-export { assessEvidenceMap, assessProgramReadiness } from "./program-readiness.js";
+export { assessEvidenceMap, assessProgramReadiness, calculateProgramProgress } from "./program-readiness.js";
 export {
   approveReportingRouteSet,
   assessReportingRoutePeriod,

package/src/program-path.js

@@ -111,7 +111,7 @@ export const PROGRAM_PATH = [
     summary: "Review and independently approve Policies, program Documents, Training content, and the Data Retention Schedule.",
     sections: [
       { id: "policy-content", title: "Policies", description: "Review every program Policy, Document, and Training record in one table, then bind independent approval to each exact revision.", steps: ["Review each governed Markdown artifact and replace every organization placeholder.", "Confirm the owner, separate approver, linked Controls, audience, and intended values that apply to each artifact.", "Record approval and its date against the exact revision. Leave approved content inactive until its Step 3 implementation cutover."], types: [], relatedLinks: [{ type: "policy", label: "Policies", href: "#/policies" }], defaultOpen: true },
-      { id: "retention", title: "Data Retention Schedule", description: "Approve the schedule document and its structured rows as one governed schedule.", steps: ["Review the schedule policy, legal holds, exceptions, and disposal requirements.", "Define rows only for Information Types and operational sources the organization actually uses.", "Confirm the complete document-and-row revision with one schedule review."], types: [], utility: "retention-schedule", defaultOpen: true }
+      { id: "retention", title: "Data Retention Schedule", description: "Complete each row proposal, then approve the document and all proposed rows once.", steps: ["Review the schedule policy, legal holds, exceptions, and disposal requirements.", "Have the owner finish each row for the Information Types and operational sources the organization actually uses.", "Trigger one independent approval only after the document and every row proposal are complete."], types: [], utility: "retention-schedule", defaultOpen: true }
     ],
     resourceTypes: [],
     supportingResourceTypes: ["policy", "document", "training", "retention-schedule-item"],