filegrc 0.16.18 → 0.16.20

package/model/v11.json

@@ -2603,7 +2603,7 @@
         "cadence": "Create before relying on a promise, review during audit scoping, and supersede it when the service or agreement changes.",
         "reviewPoints": [
           "Confirm the statement reflects a real customer promise, service requirement, or approved business objective that applies to the current scope.",
-          "Confirm which parts of the service the promise or objective affects.",
+          "Confirm which parts of the service the promise or objective affects. When a linked Policy or Document has independent sections, name the exact governing Markdown heading in sourceSectionHeadings before reviewing downstream mappings.",
           "Use \"External\", \"Zero Population\", or \"Not Applicable\" only when it is true for the current scope."
         ],
         "sourceResourceIds": [
@@ -2657,6 +2657,12 @@
             "requirement"
           ]
         },
+        "sourceSectionHeadings": {
+          "type": "object",
+          "objectType": "string-map",
+          "label": "Reviewed source sections",
+          "description": "Map a source Policy or Document ID to one exact Markdown heading when the Commitment comes from that section."
+        },
         "requirementIds": {
           "type": "array",
           "items": "id",
@@ -2731,6 +2737,7 @@
       "formFields": [
         "systemIds",
         "sourceResourceIds",
+        "sourceSectionHeadings",
         "requirementIds",
         "controlIds",
         "applicabilityReview",
@@ -7706,6 +7713,7 @@
         "reviewPoints": [
           "Confirm the Information Types and operational scope covered by this item.",
           "Confirm the cutoff, retention period, and disposition action from management sources.",
+          "When a linked Policy or Document has independent sections, set sourceSectionHeadings to the exact governing Markdown heading. Keep a whole-source binding when the entire source governs the row.",
           "Keep the item planned until the owner completes every organization-specific value and binds the current source revisions."
         ],
         "sourceResourceIds": [
@@ -7779,6 +7787,12 @@
           ],
           "label": "Authority and source records"
         },
+        "sourceSectionHeadings": {
+          "type": "object",
+          "objectType": "string-map",
+          "label": "Reviewed source sections",
+          "description": "Map a source Policy or Document ID to one exact Markdown heading when only that section governs this decision. Omit the ID when the complete source governs it."
+        },
         "cutoff": {
           "type": "object",
           "objectType": "retention-cutoff",
@@ -7882,6 +7896,7 @@
         "scopeResourceIds",
         "scheduleDocumentId",
         "sourceResourceIds",
+        "sourceSectionHeadings",
         "cutoff",
         "retentionPeriod",
         "dispositionAction",

package/package.json

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

package/src/cli.js

@@ -586,12 +586,14 @@ export async function runCli(argv = process.argv.slice(2)) {
         ? [...new Set([...(record.sourceResourceIds || []), ...(record.targetResourceIds || [])])]
         : null;
     if (!dependencyIds) throw new Error("Review bindings are available for Retention Schedule records and Requirement Mappings.");
-    const revisions = await resourceReviewRevisions(loaded, dependencyIds);
+    const revisions = await resourceReviewRevisions(loaded, dependencyIds, "legacy", record);
+    const missingSectionIds = dependencyIds.filter((id) => Object.hasOwn(record.sourceSectionHeadings || {}, id) && !revisions.has(id));
     const result = {
       resource: { type: record.type, id: record.id, title: record.title },
       dependencyIds,
       reviewedSourceRevisions: Object.fromEntries(revisions),
-      missingResourceIds: dependencyIds.filter((id) => !revisions.has(id))
+      missingResourceIds: dependencyIds.filter((id) => !revisions.has(id) && !missingSectionIds.includes(id)),
+      ...(missingSectionIds.length ? { missingSectionIds } : {})
     };
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else {

package/src/collection-revision.js

@@ -30,6 +30,10 @@ export function collectionRevisionMatches(loaded, resourceType, storedRevision,
   // Accept both the pre-0.16 scope: input and the digest-only input used by
   // 0.16.0, as well as the older collection basis from 0.9.1.
   if (revisionsMatch("collection", storedRevision, currentRevision)) return true;
+  if (resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")
+    && revisionsMatch("collection", storedRevision, calculateCollectionRevision(
+      loaded, resourceType, { ...options, legacyRetentionSourceBasis: true }, false
+    ))) return true;
   const allowOlderBasis = resourceType !== "retention-schedule-item"
     || !modelSupports(loaded.model, "retention-schedule-approval");
   for (const olderBasis of [false, true]) {
@@ -152,13 +156,17 @@ function historicallyEquivalentCollection(loaded, resourceType, stored, options,
     // Require the complete reviewed basis to be unchanged under the current
     // semantic calculation before accepting an older byte-sensitive digest.
     if (!revisionsMatch("collection", current, collectionRevision(snapshot, resourceType, historicalOptions))) continue;
-    for (const legacy of [false, true]) {
-      for (const scopeHashInput of ["legacy", "digest"]) {
-        for (const scopeFactsInput of ["legacy", "source"]) {
-          if (revisionsMatch("collection", stored, calculateCollectionRevision(
-            snapshot, resourceType, { ...historicalOptions, historicalReviewMetadata: true },
-            legacy, scopeHashInput, scopeFactsInput
-          ))) return true;
+    for (const legacyRetentionSourceBasis of resourceType === "retention-schedule-item" ? [false, true] : [false]) {
+      for (const historicalReviewMetadata of legacyRetentionSourceBasis ? [false] : [true]) {
+        for (const legacy of [false, true]) {
+          for (const scopeHashInput of ["legacy", "digest"]) {
+            for (const scopeFactsInput of ["legacy", "source"]) {
+              if (revisionsMatch("collection", stored, calculateCollectionRevision(
+                snapshot, resourceType, { ...historicalOptions, historicalReviewMetadata, legacyRetentionSourceBasis },
+                legacy, scopeHashInput, scopeFactsInput
+              ))) return true;
+            }
+          }
         }
       }
     }
@@ -175,7 +183,12 @@ function calculateCollectionRevision(loaded, resourceType, options, legacy, scop
     : Object.hasOwn(options, "program")
     ? options.program
     : resolveProgram(loaded, options.programId);
-  const inputs = new Map(collectionRevisionInputs(loaded, resourceType, program, { legacy, historicalReviewMetadata: options.historicalReviewMetadata })
+  const inputs = new Map(collectionRevisionInputs(loaded, resourceType, program, {
+    legacy,
+    historicalReviewMetadata: options.historicalReviewMetadata,
+    historicalCommit: options.historicalCommit,
+    legacyRetentionSourceBasis: options.legacyRetentionSourceBasis
+  })
     .map((input) => [input.record.id, input]));
   const authoritativeSource = loaded.resources.find(({ id }) => id === options.authoritativeSourceId);
   if (authoritativeSource) {

package/src/collection-scope.js

@@ -1,6 +1,6 @@
 import { modelSupports } from "../model/index.js";
 import { programComponents, selectedRequirementIds } from "./program.js";
-import { retentionReviewResourceIds, retentionUses } from "./retention.js";
+import { resourceReviewRevisionsSync, retentionReviewResourceIds, retentionSystemUses, retentionUses } from "./retention.js";
 import { documentIsAuditSpecific } from "./program-lifecycle.js";
 
 export function scopedCollectionRecords(loaded, resourceType, program) {
@@ -210,6 +210,8 @@ export function collectionRevisionInputs(loaded, resourceType, program, options
   const byId = new Map(loaded.resources.map((record) => [record.id, record]));
   const records = new Map(reviewed.map((record) => [record.id, record]));
   const reviewedIds = new Set(records.keys());
+  const scheduleDocumentIds = new Set(resourceType === "retention-schedule-item"
+    ? reviewed.map((record) => record.scheduleDocumentId).filter(Boolean) : []);
   const addIds = (ids) => {
     for (const id of ids || []) {
       const record = byId.get(id);
@@ -363,7 +365,7 @@ export function collectionRevisionInputs(loaded, resourceType, program, options
     record,
     value: reviewedIds.has(record.id)
       ? resourceType === "retention-schedule-item" && modelSupports(loaded.model, "retention-schedule-approval")
-        ? retentionScheduleRowProposalValue(record, options.historicalReviewMetadata)
+        ? retentionScheduleRowProposalValue(record, loaded, options)
         : options.historicalReviewMetadata ? record : substantiveRevisionValue(record)
       : resourceType === "retention-schedule-item"
         && modelSupports(loaded.model, "retention-schedule-approval")
@@ -371,19 +373,25 @@ export function collectionRevisionInputs(loaded, resourceType, program, options
           ? retentionScheduleDocumentProposalValue(record)
           : options.historicalReviewMetadata
             ? dependencyRevisionValue(resourceType, record, legacy, true, currentModel)
-            : substantiveRevisionValue(dependencyRevisionValue(resourceType, record, legacy, false, currentModel)),
+            : substantiveRevisionValue(dependencyRevisionValue(resourceType, record, legacy, false, currentModel, scheduleDocumentIds, options.legacyRetentionSourceBasis)),
     includeContent: legacy
       || reviewedIds.has(record.id)
-      || dependencyContentAffectsRevision(resourceType, record.type, options.historicalReviewMetadata, currentModel)
+      || dependencyContentAffectsRevision(resourceType, record, options.historicalReviewMetadata, currentModel, scheduleDocumentIds, options.legacyRetentionSourceBasis)
   }));
 }
 
-function retentionScheduleRowProposalValue(record, historicalReviewMetadata = false) {
-  return Object.fromEntries(Object.entries(record).filter(([field]) => ![
+function retentionScheduleRowProposalValue(record, loaded, options = {}) {
+  const value = Object.fromEntries(Object.entries(record).filter(([field]) => ![
     "approvedByIds",
     "approvedOn",
-    ...(historicalReviewMetadata ? [] : ["reviewedSourceRevisions", "tags", "statusTransition"])
+    ...(options.historicalReviewMetadata ? [] : ["reviewedSourceRevisions", "tags", "statusTransition"])
   ].includes(field)));
+  if (!options.historicalReviewMetadata && !options.legacyRetentionSourceBasis) {
+    value.sourceDecisionRevisions = Object.fromEntries(resourceReviewRevisionsSync(
+      loaded, record.sourceResourceIds || [], "legacy", false, options.historicalCommit || null, record
+    ));
+  }
+  return value;
 }
 
 function retentionScheduleDocumentProposalValue(record) {
@@ -533,7 +541,7 @@ const dependencyFields = {
     obligation: ["id", "type", "status", "activityType", "scheduleMode", "ownerIds", "activeRuleId", "policyIds", "controlIds", "ruleIds"],
     "source-coverage": ["id", "type", "status", "sourceFamilyId", "coverageKind", "scopeResourceIds", "excludedPopulation", "retrieverIds", "collectionCadence", "retentionScheduleItemIds", "reconciliationMethod", "validFrom", "validThrough", "applicabilityReview", "readinessTestEvidenceIds", "ownerIds", "componentId"],
     evidence: ["id", "type", "status", "artifactKind", "readinessTest", "retrievalResult", "accessConfirmed", "coveredSourceFamilyIds", "sourceComponentId", "componentIds", "systemIds", "collectedOn", "collectorIds", "verifierIds", "verifiedOn"],
-    "retention-schedule-item": ["id", "type", "status", "description", "informationTypeIds", "scopeResourceIds", "scheduleDocumentId", "sourceResourceIds", "ownerIds", "approvedByIds", "approvedOn", "reviewedSourceRevisions", "cutoff", "retentionPeriod", "dispositionAction", "dispositionInstructions"],
+    "retention-schedule-item": ["id", "type", "status", "description", "informationTypeIds", "scopeResourceIds", "scheduleDocumentId", "sourceResourceIds", "sourceSectionHeadings", "ownerIds", "approvedByIds", "approvedOn", "reviewedSourceRevisions", "cutoff", "retentionPeriod", "dispositionAction", "dispositionInstructions"],
     document: ["id", "type", "documentKind", "workflowScope", "ownerIds", "approverIds", "approvedOn", "approvedContentRevisions", "controlIds"],
     policy: ["id", "type", "programRole", "ownerIds", "approverIds", "approvedOn", "approvedContentRevisions", "relatedDocumentIds", "controlIds"],
     training: ["id", "type", "ownerIds", "approverIds", "approvedOn", "approvedContentRevisions", "controlIds"],
@@ -597,7 +605,12 @@ const dependencyContentTypes = {
   "complementary-control": new Set(["system", "document", "component"])
 };
 
-function dependencyRevisionValue(resourceType, record, legacy, historicalReviewMetadata = false, currentModel = false) {
+function dependencyRevisionValue(resourceType, record, legacy, historicalReviewMetadata = false, currentModel = false, scheduleDocumentIds = new Set(), legacyRetentionSourceBasis = false) {
+  if (resourceType === "retention-schedule-item" && currentModel && !historicalReviewMetadata && !legacyRetentionSourceBasis
+    && (["policy", "requirement", "commitment", "control"].includes(record.type)
+      || record.type === "document" && record.documentKind !== "schedule" && !scheduleDocumentIds.has(record.id))) {
+    return { id: record.id, type: record.type };
+  }
   const controlDecision = currentModel && !historicalReviewMetadata && record.type === "control"
     && ["retention-schedule-item", "complementary-control"].includes(resourceType);
   const fields = controlDecision
@@ -612,13 +625,20 @@ function dependencyRevisionValue(resourceType, record, legacy, historicalReviewM
   const value = Object.fromEntries(fields
     .filter((field) => record[field] !== undefined)
     .map((field) => [field, record[field]]));
+  if (resourceType === "retention-schedule-item" && currentModel && !historicalReviewMetadata
+    && !legacyRetentionSourceBasis && record.type === "component") {
+    value.systemUses = retentionSystemUses(value.systemUses);
+  }
   if (controlDecision) value.unavailable = ["not-applicable", "retired", "superseded"].includes(record.status);
   return value;
 }
 
-function dependencyContentAffectsRevision(resourceType, dependencyType, historicalReviewMetadata = false, currentModel = false) {
-  return ((!currentModel || historicalReviewMetadata) && resourceType === "complementary-control" && dependencyType === "control")
-    || dependencyContentTypes[resourceType]?.has(dependencyType) || false;
+function dependencyContentAffectsRevision(resourceType, dependency, historicalReviewMetadata = false, currentModel = false, scheduleDocumentIds = new Set(), legacyRetentionSourceBasis = false) {
+  if (resourceType === "retention-schedule-item" && currentModel && !historicalReviewMetadata && !legacyRetentionSourceBasis
+    && (dependency.type === "policy" || dependency.type === "document"
+      && dependency.documentKind !== "schedule" && !scheduleDocumentIds.has(dependency.id))) return false;
+  return ((!currentModel || historicalReviewMetadata) && resourceType === "complementary-control" && dependency.type === "control")
+    || dependencyContentTypes[resourceType]?.has(dependency.type) || false;
 }
 
 function sorted(values) {

package/src/program-amendment.js

@@ -128,7 +128,7 @@ export async function planProgramAmendment(input, options = {}) {
   const retention = related.filter((record) => (
     record.type === "retention-schedule-item"
     && record.status === "active"
-    && reviewBindingsDiffer(retentionReviewResourceIds(record, loaded), record.reviewedSourceRevisions, currentReviewRevisions, loaded)
+    && reviewBindingsDiffer(retentionReviewResourceIds(record, loaded), record.reviewedSourceRevisions, currentReviewRevisions, loaded, record)
   ));
   if (retention.length) {
     missing.push({
@@ -161,10 +161,10 @@ export async function planProgramAmendment(input, options = {}) {
   };
 }
 
-function reviewBindingsDiffer(expectedIds, reviewed = {}, current, loaded) {
+function reviewBindingsDiffer(expectedIds, reviewed = {}, current, loaded, reviewer = null) {
   const expected = new Set(expectedIds);
   if (Object.keys(reviewed).length !== expected.size) return true;
-  return [...expected].some((id) => !resourceReviewRevisionMatches(loaded, current, id, reviewed[id]));
+  return [...expected].some((id) => !resourceReviewRevisionMatches(loaded, current, id, reviewed[id], reviewer));
 }
 
 export async function assessProgramAmendmentReadiness(loaded) {

package/src/retention.js

@@ -156,92 +156,120 @@ export async function resourceReviewRevision(loaded, resourceId) {
   return (await resourceReviewRevisions(loaded, [resourceId])).get(resourceId) || null;
 }
 
-export async function resourceReviewRevisions(loaded, ids, scopeHashInput = "legacy") {
+export async function resourceReviewRevisions(loaded, ids, scopeHashInput = "legacy", reviewer = null) {
   const wanted = new Set(ids);
   const entries = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
   const revisions = new Map();
   const reviewing = new Set();
-  const review = async (id) => {
-    if (revisions.has(id)) return revisions.get(id);
-    const entry = entries.get(id);
-    if (!entry || reviewing.has(id)) return null;
-    reviewing.add(id);
-    const parts = [reviewSource(loaded, entry, scopeHashInput)];
+  const review = async (id, heading = null) => {
+    const key = `${id}\0${heading || ""}`;
+    if (revisions.has(key)) return revisions.get(key);
+    const entry = effectiveReviewEntry(loaded, entries.get(id));
+    if (!entry || reviewing.has(key)) return null;
+    reviewing.add(key);
+    const parts = [reviewSource(loaded, entry, scopeHashInput, false, heading, reviewer)];
+    let matchedSection = !heading;
     for (const markdown of reviewMarkdownEntries(loaded, entry, false)) {
       try {
-        parts.push(await readFile(resolveDataPath(loaded.root, markdown.path), "utf8"));
+        const source = entry.reviewCommit
+          ? entry.reviewFiles?.get(`data/${markdown.path}`)
+            ?? getFileAtRevision(loaded.root, entry.reviewCommit, `data/${markdown.path}`)
+          : await readFile(resolveDataPath(loaded.root, markdown.path), "utf8");
+        if (source !== null) {
+          const section = reviewedMarkdownSection(source, heading);
+          if (section !== null) { parts.push(section); matchedSection = true; }
+        }
       } catch (error) {
         if (error.code !== "ENOENT") throw error;
       }
     }
+    if (!matchedSection) { reviewing.delete(key); return null; }
+    let missingDependency = false;
     for (const sourceId of [...new Set(entry.record.sourceResourceIds || [])].sort()) {
-      const revision = await review(sourceId);
+      const revision = await review(sourceId, sourceHeading(entry.record, sourceId));
       if (revision) parts.push(`${sourceId}:${revisionDigest("content", revision) || revision}`);
+      else missingDependency = true;
     }
-    reviewing.delete(id);
+    reviewing.delete(key);
+    if (missingDependency) return null;
     const revision = contentRevision(parts.join("\n"));
-    revisions.set(id, revision);
+    revisions.set(key, revision);
     return revision;
   };
+  const selected = new Map();
   for (const id of wanted) {
-    await review(id);
+    selected.set(id, await review(id, sourceHeading(reviewer, id)));
   }
-  return new Map([...revisions].filter(([id]) => wanted.has(id)));
+  return new Map([...selected].filter(([, revision]) => revision));
 }
 
-export function resourceReviewRevisionsSync(loaded, ids, scopeHashInput = "legacy", legacySource = false, historicalCommit = null) {
+export function resourceReviewRevisionsSync(loaded, ids, scopeHashInput = "legacy", legacySource = false, historicalCommit = null, reviewer = null) {
   const wanted = new Set(ids);
   const entries = new Map(loaded.entries.map((entry) => [entry.record.id, entry]));
   const revisions = new Map();
   const reviewing = new Set();
-  const review = (id) => {
-    if (revisions.has(id)) return revisions.get(id);
-    const entry = entries.get(id);
-    if (!entry || reviewing.has(id)) return null;
-    reviewing.add(id);
-    const parts = [reviewSource(loaded, entry, scopeHashInput, legacySource)];
+  const review = (id, heading = null) => {
+    const key = `${id}\0${heading || ""}`;
+    if (revisions.has(key)) return revisions.get(key);
+    const entry = historicalCommit ? entries.get(id) : effectiveReviewEntry(loaded, entries.get(id));
+    if (!entry || reviewing.has(key)) return null;
+    reviewing.add(key);
+    const parts = [reviewSource(loaded, entry, scopeHashInput, legacySource, heading, reviewer)];
+    let matchedSection = !heading;
     for (const markdown of reviewMarkdownEntries(loaded, entry, legacySource)) {
       try {
-        const source = historicalCommit
-          ? loaded.historicalFiles
-            ? loaded.historicalFiles.get(`data/${markdown.path}`) ?? null
-            : getFileAtRevision(loaded.root, historicalCommit, `data/${markdown.path}`)
+        const source = (historicalCommit || entry.reviewCommit)
+          ? loaded.historicalFiles?.get(`data/${markdown.path}`)
+            ?? entry.reviewFiles?.get(`data/${markdown.path}`)
+            ?? getFileAtRevision(loaded.root, historicalCommit || entry.reviewCommit, `data/${markdown.path}`)
           : readFileSync(resolveDataPath(loaded.root, markdown.path), "utf8");
-        if (source !== null) parts.push(source);
+        if (source !== null) {
+          const section = legacySource ? source : reviewedMarkdownSection(source, heading);
+          if (section !== null) { parts.push(section); matchedSection = true; }
+        }
       } catch (error) {
         if (error.code !== "ENOENT") throw error;
       }
     }
+    if (!matchedSection) { reviewing.delete(key); return null; }
+    let missingDependency = false;
     for (const sourceId of [...new Set(entry.record.sourceResourceIds || [])].sort()) {
-      const revision = review(sourceId);
+      const revision = review(sourceId, sourceHeading(entry.record, sourceId));
       if (revision) parts.push(`${sourceId}:${revisionDigest("content", revision) || revision}`);
+      else missingDependency = true;
     }
-    reviewing.delete(id);
+    reviewing.delete(key);
+    if (missingDependency) return null;
     const revision = contentRevision(parts.join("\n"));
-    revisions.set(id, revision);
+    revisions.set(key, revision);
     return revision;
   };
-  for (const id of wanted) review(id);
-  return new Map([...revisions].filter(([id]) => wanted.has(id)));
+  const selected = new Map();
+  for (const id of wanted) selected.set(id, review(id, sourceHeading(reviewer, id)));
+  return new Map([...selected].filter(([, revision]) => revision));
 }
 
-export function resourceReviewRevisionMatches(loaded, revisions, id, stored) {
-  const current = revisions.get(id);
+export function resourceReviewRevisionMatches(loaded, revisions, id, stored, reviewer = null) {
+  const current = (sourceHeading(reviewer, id) || reviewer?.type === "retention-schedule-item")
+    ? resourceReviewRevisionsSync(loaded, [id], "legacy", false, null, reviewer).get(id)
+    : revisions.get(id);
   if (!current || !revisionDigest("content", stored)) return false;
   if (revisionsMatch("content", stored, current)) return true;
-  const legacy = resourceReviewRevisionsSync(loaded, [id], "legacy", true).get(id);
-  if (revisionsMatch("content", stored, legacy)) return true;
-  // Version 0.16.0 used a bare digest as the hash input for scopeRevision.
-  // Read that binding without changing the legacy scope: basis restored here.
-  const compatible = resourceReviewRevisionsSync(loaded, [id], "digest", true).get(id);
-  if (revisionsMatch("content", stored, compatible)) return true;
-  return historicallyEquivalentReviewSource(loaded, id, stored, current);
+  if (!sourceHeading(reviewer, id)) {
+    const legacy = resourceReviewRevisionsSync(loaded, [id], "legacy", true).get(id);
+    if (revisionsMatch("content", stored, legacy)) return true;
+    // Version 0.16.0 used a bare digest as the hash input for scopeRevision.
+    // Read that binding without changing the legacy scope: basis restored here.
+    const compatible = resourceReviewRevisionsSync(loaded, [id], "digest", true).get(id);
+    if (revisionsMatch("content", stored, compatible)) return true;
+  }
+  return historicallyEquivalentReviewSource(loaded, id, stored, current, reviewer);
 }
 
 // Recompute the old byte-sensitive binding at each committed state. The
 // semantic source graph must still equal today's graph, including linked
 // records and Markdown, before the old approval is treated as current.
-function historicallyEquivalentReviewSource(loaded, id, stored, current) {
+function historicallyEquivalentReviewSource(loaded, id, stored, current, reviewer = null) {
   if (!loaded.root) return false;
   const context = reviewHistoryContext(loaded.root, loaded);
   const { index } = context;
@@ -262,8 +290,13 @@ function historicallyEquivalentReviewSource(loaded, id, stored, current) {
     if (relevantPaths && ![...changed.keys()].some((path) => relevantPaths.has(path) || path.endsWith(".md"))) continue;
     const snapshot = reviewHistoricalWorkspace(context, commit);
     if (!snapshot?.entries.some(({ record }) => record.id === id)) continue;
-    const semantic = resourceReviewRevisionsSync(snapshot, [id], "legacy", false, commit).get(id);
+    const semantic = resourceReviewRevisionsSync(snapshot, [id], "legacy", false, commit, reviewer).get(id);
     if (!revisionsMatch("content", semantic, current)) continue;
+    // A row may narrow a source to its retention facts or a named Markdown
+    // section. Accept its old binding only when those facts still match the
+    // committed source that supplied the binding.
+    const original = resourceReviewRevisionsSync(snapshot, [id], "legacy", false, commit).get(id);
+    if (revisionsMatch("content", stored, original)) return true;
     for (const scopeHashInput of ["legacy", "digest"]) {
       const legacy = resourceReviewRevisionsSync(snapshot, [id], scopeHashInput, true, commit).get(id);
       if (revisionsMatch("content", stored, legacy)) return true;
@@ -293,7 +326,20 @@ export function retentionUses(loaded, program) {
   return [...new Map(uses.map((use) => [`${use.resource.id}:${use.informationTypeId}`, use])).values()];
 }
 
-function reviewSource(loaded, entry, scopeHashInput = "legacy", legacySource = false) {
+function reviewSource(loaded, entry, scopeHashInput = "legacy", legacySource = false, heading = null, reviewer = null) {
+  if (heading && !legacySource) {
+    const governingFields = entry.record.type === "policy"
+      ? ["policyKind", "effectiveOn", "supersedesId", "parentPolicyId", "relatedPolicyIds", "relatedDocumentIds", "requirementIds", "audience", "acknowledgementRequired", "programRole", "reportingRouteRequirements"]
+      : ["documentKind", "workflowScope", "effectiveOn", "supersedesId", "systemIds", "controlIds", "relatedDocumentIds", "audience", "acknowledgementRequired", "trainingIds", "classificationId", "programRole", "componentIds", "reportingRouteRequirements"];
+    return JSON.stringify({
+      id: entry.record.id,
+      type: entry.record.type,
+      governingStatus: ["approved", "active"].includes(entry.record.status)
+        ? "approved" : entry.record.status || null,
+      ...Object.fromEntries(["extensions", "externalIds", ...governingFields].filter((field) => entry.record[field] !== undefined)
+        .map((field) => [field, entry.record[field]]))
+    });
+  }
   if (
     modelSupports(loaded.model, "retention-schedule-approval")
     && entry.record.type === "document"
@@ -318,7 +364,7 @@ function reviewSource(loaded, entry, scopeHashInput = "legacy", legacySource = f
   return legacySource
     ? canonicalCalculatedRevisionJson(entry.source, scopeHashInput)
     : canonicalCalculatedRevisionJson(JSON.stringify(substantiveReviewSource(
-      JSON.parse(entry.source), modelSupports(loaded.model, "retention-schedule-approval")
+      JSON.parse(entry.source), modelSupports(loaded.model, "retention-schedule-approval"), reviewer
     )), scopeHashInput);
 }
 
@@ -330,9 +376,93 @@ function reviewMarkdownEntries(loaded, entry, legacySource) {
   return markdownEntries(loaded.model, entry.record);
 }
 
+const approvedReviewEntries = new WeakMap();
+
+function effectiveReviewEntry(loaded, entry) {
+  if (!entry || !loaded.root || !["policy", "document", "training"].includes(entry.record.type)) return entry;
+  if (!["draft", "in-review", "approved", "active"].includes(entry.record.status)) return entry;
+  if (approvedReviewContentMatches(loaded, entry)) return entry;
+  if (["approved", "active"].includes(entry.record.status)) return entry;
+  let cache = approvedReviewEntries.get(loaded.resources);
+  if (!cache) {
+    cache = new Map();
+    approvedReviewEntries.set(loaded.resources, cache);
+  }
+  if (cache.has(entry.record.id)) return cache.get(entry.record.id) || entry;
+  const context = reviewHistoryContext(loaded.root, loaded);
+  for (const commit of [...reviewHistoryCommits(context)].reverse()) {
+    const snapshot = reviewHistoricalWorkspace(context, commit);
+    const historical = snapshot?.entries.find(({ record }) => record.id === entry.record.id);
+    if (!historical || !approvedReviewContentMatches(snapshot, historical, commit)) continue;
+    const approved = { ...historical, reviewCommit: commit, reviewFiles: snapshot.historicalFiles };
+    cache.set(entry.record.id, approved);
+    return approved;
+  }
+  cache.set(entry.record.id, null);
+  return entry;
+}
+
+function approvedReviewContentMatches(loaded, entry, commit = null) {
+  if (!["approved", "active"].includes(entry.record.status)) return false;
+  const bindings = entry.record.approvedContentRevisions || entry.record.effectiveContentRevisions;
+  if (!bindings) return true;
+  for (const markdown of reviewMarkdownEntries(loaded, entry, false)) {
+    const source = commit
+      ? loaded.historicalFiles?.get(`data/${markdown.path}`)
+        ?? getFileAtRevision(loaded.root, commit, `data/${markdown.path}`)
+      : (() => {
+        try { return readFileSync(resolveDataPath(loaded.root, markdown.path), "utf8"); }
+        catch (error) { if (error.code === "ENOENT") return null; throw error; }
+      })();
+    if (!source || !revisionsMatch("content", bindings[markdown.path], contentRevision(source))) return false;
+  }
+  return true;
+}
+
+export function reviewedMarkdownSection(source, heading) {
+  if (!heading) return source;
+  const lines = source.split("\n");
+  const wanted = heading.trim().replace(/^#{1,6}\s+/, "").toLowerCase();
+  const headings = [];
+  const fencedLines = new Set();
+  let fence = null;
+  for (const [index, line] of lines.entries()) {
+    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+    if (fence) {
+      fencedLines.add(index);
+      if (marker?.[0] === fence[0] && marker.length >= fence.length
+        && /^\s*$/.test(line.slice(line.indexOf(marker) + marker.length))) fence = null;
+      continue;
+    }
+    if (marker) { fence = marker; fencedLines.add(index); continue; }
+    const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (match) headings.push({ index, level: match[1].length, title: match[2].trim().toLowerCase() });
+  }
+  const matches = headings.filter(({ title }) => title === wanted);
+  if (matches.length !== 1) return null;
+  const selected = matches[0];
+  const ancestors = [];
+  for (const candidate of headings.filter(({ index }) => index < selected.index)) {
+    while (ancestors.length && ancestors.at(-1).level >= candidate.level) ancestors.pop();
+    ancestors.push(candidate);
+  }
+  const next = headings.find(({ index, level }) => index > selected.index && level <= selected.level);
+  const context = ancestors.map(({ index }) => {
+    const following = headings.find((candidate) => candidate.index > index);
+    return lines.slice(index, following?.index).filter((_, offset) => !fencedLines.has(index + offset)).join("\n").trim();
+  });
+  return [...context, lines.slice(selected.index, next?.index).join("\n").trim()].join("\n\n");
+}
+
+function sourceHeading(record, sourceId) {
+  const headings = record?.sourceSectionHeadings;
+  return headings && Object.hasOwn(headings, sourceId) && typeof headings[sourceId] === "string"
+    ? headings[sourceId] : null;
+}
+
 const reviewDecisionFields = {
   control: ["statement", "requirementIds", "code", "activity", "controlType", "operationMode", "operationPattern", "systemIds", "policyIds", "componentIds", "evidenceSourceComponentIds"],
-  commitment: ["commitmentKind", "statement", "systemIds", "sourceResourceIds", "requirementIds", "controlIds", "customerFacing", "effectiveOn", "reportingRouteRequirements"],
+  commitment: ["commitmentKind", "statement", "systemIds", "sourceResourceIds", "sourceSectionHeadings", "requirementIds", "controlIds", "customerFacing", "effectiveOn", "reportingRouteRequirements"],
   "complementary-control": ["responsibleParty", "statement", "systemIds", "vendorId", "requirementIds", "commitmentIds", "relatedControlIds", "sourceDocumentIds", "componentIds"],
   "source-coverage": ["sourceFamilyId", "coverageKind", "scopeResourceIds", "excludedPopulation", "collectionCadence", "reconciliationMethod", "validFrom", "validThrough", "componentId", "retentionScheduleItemIds"],
   system: ["purpose", "servicesProvided", "boundary", "exclusions", "criticality", "informationTypeIds", "classificationId", "internetExposed", "continuityObjectives"],
@@ -345,7 +475,7 @@ const reviewDecisionFields = {
   document: ["documentKind", "workflowScope", "template", "version", "effectiveOn", "supersedesId", "systemIds", "controlIds", "relatedDocumentIds", "audience", "acknowledgementRequired", "trainingIds", "classificationId", "programRole", "componentIds", "reportingRouteRequirements"]
 };
 
-function substantiveReviewSource(record, currentModel) {
+function substantiveReviewSource(record, currentModel, reviewer = null) {
   if (currentModel && reviewDecisionFields[record.type]) {
     const fields = ["id", "type", "title", "extensions", "externalIds", ...reviewDecisionFields[record.type]];
     const decision = Object.fromEntries(fields.filter((field) => record[field] !== undefined)
@@ -357,6 +487,9 @@ function substantiveReviewSource(record, currentModel) {
     } else {
       decision.status = record.status || null;
     }
+    if (record.type === "component" && reviewer?.type === "retention-schedule-item") {
+      decision.systemUses = retentionSystemUses(decision.systemUses);
+    }
     if (["control", "commitment", "complementary-control"].includes(record.type)) {
       decision.nonApplicableDecision = ["not-applicable", "externally-managed", "zero-population"]
         .includes(record.applicabilityReview?.decision) ? record.applicabilityReview.decision : null;
@@ -387,6 +520,13 @@ function substantiveReviewSource(record, currentModel) {
   return source;
 }
 
+export function retentionSystemUses(uses) {
+  return uses?.map((use) => ({
+    ...use,
+    roles: use.roles?.filter((role) => role !== "evidence-source")
+  }));
+}
+
 export function nearDuplicateInformationTypes(records) {
   const types = records.filter((record) => record.type === "information-type" && !["retired", "superseded"].includes(record.status));
   const pairs = [];
@@ -450,7 +590,7 @@ export function retentionRuleIsCurrent(rule, revisions, byId = new Map(), loaded
   const dependencyIds = retentionReviewResourceIds(rule, loaded);
   if (Object.keys(rule.reviewedSourceRevisions).length !== dependencyIds.length) return false;
   return dependencyIds.every((id) => (
-    resourceReviewRevisionMatches(loaded, revisions, id, rule.reviewedSourceRevisions?.[id])
+    resourceReviewRevisionMatches(loaded, revisions, id, rule.reviewedSourceRevisions?.[id], rule)
   ));
 }
 

package/src/server.js

@@ -627,9 +627,23 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
           return json(response, 400, { error: "Pass one or more safe resource IDs." });
         }
         const loaded = await loadWorkspace(input);
-        const revisions = await resourceReviewRevisions(loaded, ids);
+        const sourceSectionHeadings = Object.create(null);
+        for (const value of url.searchParams.getAll("section")) {
+          const separator = value.indexOf(":");
+          const id = value.slice(0, separator);
+          const heading = value.slice(separator + 1).trim();
+          if (separator < 1 || !ids.includes(id) || !heading || heading.length > 200) {
+            return json(response, 400, { error: "Each reviewed section must name a selected source and a Markdown heading." });
+          }
+          sourceSectionHeadings[id] = heading;
+        }
+        const revisions = await resourceReviewRevisions(loaded, ids, "legacy", { sourceSectionHeadings });
         const missing = ids.filter((id) => !revisions.has(id));
-        if (missing.length) return json(response, 404, { error: `Resources not found: ${missing.join(", ")}.` });
+        if (missing.length) return json(response, 404, {
+          error: missing.some((id) => sourceSectionHeadings[id])
+            ? `A selected source heading is missing or ambiguous: ${missing.filter((id) => sourceSectionHeadings[id]).join(", ")}.`
+            : `Resources not found: ${missing.join(", ")}.`
+        });
         return json(response, 200, { revisions: Object.fromEntries(revisions) });
       }
       if (request.method === "PUT" && url.pathname === "/api/content") {

package/src/validate.js

@@ -219,6 +219,19 @@ async function validateWorkspaceUnmeasured(input) {
       }
       validateNestedRelations(fieldName, value, field, loaded.model, byId, displayPath, diagnostics);
     }
+    if (record.sourceSectionHeadings) {
+      for (const [sourceId, heading] of Object.entries(record.sourceSectionHeadings)) {
+        if (!(record.sourceResourceIds || []).includes(sourceId)
+          || !["policy", "document"].includes(byId.get(sourceId)?.type)
+          || !String(heading || "").trim()) {
+          diagnostics.push(error(
+            "invalid-source-section",
+            displayPath,
+            `sourceSectionHeadings.${sourceId} must name a linked Policy or Document and a Markdown heading.`
+          ));
+        }
+      }
+    }
     validateIndependentApproval(record, byId, displayPath, diagnostics);
     validateCompletedObligationEvent(record, byId, loaded.model, displayPath, diagnostics);
     validateActionObligationRule(record, byId, displayPath, diagnostics);
@@ -1995,7 +2008,7 @@ function validateRetentionScheduleItem(record, loaded, byId, currentReviewRevisi
   const sources = retentionReviewResourceIds(record, loaded);
   const revisions = record.reviewedSourceRevisions || {};
   const missing = sources.filter((id) => (
-    !resourceReviewRevisionMatches(loaded, currentReviewRevisions, id, revisions[id])
+    !resourceReviewRevisionMatches(loaded, currentReviewRevisions, id, revisions[id], record)
   )).concat(Object.keys(revisions).filter((id) => !sources.includes(id)));
   if (missing.length) {
     diagnostics.push(error(

package/src/web.js

@@ -5358,6 +5358,8 @@ function editorField(type, name, field, value, required, editing, oneOfRequired
       control = stringMapEditor(value || {}, name, name === "reviewedSourceRevisions");
       const mapHelp = name === "reviewedSourceRevisions"
         ? "Bind the exact current JSON and Markdown revisions after reviewing every selected record."
+        : name === "sourceSectionHeadings"
+          ? "Use a linked Policy or Document ID and its exact Markdown heading. The selected section governs this decision."
         : "Add one named value per row.";
       return fieldWrap(name, "string-map", label, requiredMark, control, mapHelp, required);
     }
@@ -5558,7 +5560,11 @@ async function bindCurrentReviewRevisions(dialog, button) {
   setButtonBusy(button, true, "Binding…");
   let bound = false;
   try {
-    const query = ids.map((id) => "id=" + encodeURIComponent(id)).join("&");
+    const sections = [...dialog.querySelectorAll('[data-field-group="sourceSectionHeadings"] .string-map-row')]
+      .map((row) => [row.querySelector('[data-map-key]')?.value?.trim(), row.querySelector('[data-map-value]')?.value?.trim()])
+      .filter(([id, heading]) => id && heading);
+    const query = ids.map((id) => "id=" + encodeURIComponent(id))
+      .concat(sections.map(([id, heading]) => "section=" + encodeURIComponent(id + ":" + heading))).join("&");
     const response = await localFetch("/api/review-revisions?" + query);
     if (!response.ok) throw new Error(await responseMessage(response));
     const { revisions } = await response.json();
@@ -6775,6 +6781,7 @@ dialog::backdrop{background:rgba(0,0,24,.62)}
 @media(max-width:760px){.workflow-findings{grid-template-columns:1fr}}
 .choice-tag{overflow-wrap:normal;font-size:10px}.form-field[data-kind="structured-object"],.string-map-property{grid-column:1/-1}.string-map-row .text-button{text-transform:none;letter-spacing:0;color:var(--muted);font-size:11px}
 .form-field[data-kind="string-map"]{grid-column:1/-1}.string-map-actions{display:flex;flex-wrap:wrap;gap:7px}
+.form-field[data-field-group="sourceSectionHeadings"] .string-map-row{grid-template-columns:minmax(0,1fr) minmax(0,2fr) auto}
 @media(max-width:760px){.setup-banner>.button{justify-self:start}.setup-draft-state{justify-content:flex-start;flex-wrap:wrap;gap:12px 22px}.setup-draft-state .button{width:100%}}
 @media(max-width:760px){.string-map-row{grid-template-columns:1fr 1fr}.string-map-row .text-button{grid-column:1/-1;justify-self:start}}