frontend-project-context 1.8.0 → 1.9.1

package/src/project-context/contract-schema.mjs

@@ -10,6 +10,7 @@ const STATUSES = new Set(["proposed", "approved", "deprecated"]);
 const SCOPE_KINDS = new Set(["project", "path-prefix", "file"]);
 const VERIFICATION_KINDS = new Set(["none", "file-exists", "json-value", "path-digest"]);
 const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const DIGEST_MODES = new Set(["full-file", "outside-owned-ai-entry"]);
 
 function object(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -64,7 +65,14 @@ export function sourceStatus(source) {
 }
 
 export function sourceForContract(source, schemaVersion) {
-  return schemaVersion === 2 ? { ...structuredClone(source), status: "active" } : structuredClone(source);
+  return schemaVersion >= 2 ? { ...structuredClone(source), status: "active" } : structuredClone(source);
+}
+
+export function promoteContractToSchema3(contract) {
+  if (contract.schemaVersion === 3) return contract;
+  contract.schemaVersion = 3;
+  contract.sources = contract.sources.map((source) => source.status === undefined ? { ...source, status: "active" } : source);
+  return contract;
 }
 
 export function sourceRegistrationShape(source) {
@@ -76,12 +84,14 @@ export function sourceRegistrationShape(source) {
 
 export function validateSource(source, label = "source", options = {}) {
   const contractSchemaVersion = options.contractSchemaVersion ?? 1;
+  const governedStatus = contractSchemaVersion >= 2 && options.proposal !== true;
   object(source, label);
   const allowed = new Set(["id", "kind", "path", "pointer", "reference", "digest"]);
-  if (contractSchemaVersion === 2) {
+  if (governedStatus) {
     allowed.add("status");
     allowed.add("deprecation");
   }
+  if (contractSchemaVersion >= 3) allowed.add("digestMode");
   exactKeys(source, allowed, label);
   stableId(source.id, `${label}.id`);
   if (!SOURCE_KINDS.has(source.kind)) fail("schema-invalid-enum", `${label}.kind is invalid`);
@@ -97,6 +107,10 @@ export function validateSource(source, label = "source", options = {}) {
     } else if (source.pointer !== undefined) {
       fail("schema-invalid", `${label}.pointer is only valid for json-pointer sources`);
     }
+    if (source.digestMode !== undefined) {
+      if (source.kind !== "file") fail("schema-invalid", `${label}.digestMode is only valid for file sources`);
+      if (!DIGEST_MODES.has(source.digestMode)) fail("schema-invalid-enum", `${label}.digestMode is invalid`);
+    }
     if (source.reference !== undefined) fail("schema-invalid", `${label}.reference is not valid for local sources`);
   } else {
     string(source.reference, `${label}.reference`);
@@ -107,7 +121,7 @@ export function validateSource(source, label = "source", options = {}) {
       fail("schema-invalid", `${label}.digest must be null or omitted for unverifiable sources`);
     }
   }
-  if (contractSchemaVersion === 2) {
+  if (governedStatus) {
     if (!SOURCE_STATUSES.has(source.status)) fail("schema-invalid-enum", `${label}.status is invalid`);
     if (source.status === "active" && source.deprecation !== undefined) {
       fail("schema-invalid", `${label}.deprecation is not allowed for active sources`);
@@ -123,6 +137,23 @@ export function validateSource(source, label = "source", options = {}) {
   return source;
 }
 
+function validateConsumption(consumption, item, label) {
+  object(consumption, label);
+  exactKeys(consumption, new Set(["requiredSources", "conditionalSources"]), label);
+  uniqueStrings(consumption.requiredSources, `${label}.requiredSources`, { empty: true });
+  uniqueStrings(consumption.conditionalSources, `${label}.conditionalSources`, { empty: true });
+  for (const [name, values] of Object.entries(consumption)) {
+    const sorted = [...values].sort((left, right) => left.localeCompare(right));
+    if (JSON.stringify(values) !== JSON.stringify(sorted)) fail("schema-invalid", `${label}.${name} must be stably sorted`);
+    for (const source of values) {
+      stableId(source, `${label}.${name} entry`);
+      if (!item.sources.includes(source)) fail("source-reference-missing", `${label}.${name} must reference item sources: ${source}`);
+    }
+  }
+  const overlap = consumption.requiredSources.find((source) => consumption.conditionalSources.includes(source));
+  if (overlap) fail("schema-invalid", `${label} source roles must be mutually exclusive: ${overlap}`);
+}
+
 function validateApproval(approval, label) {
   object(approval, label);
   exactKeys(approval, new Set(["by", "at", "rationale"]), label);
@@ -164,9 +195,12 @@ function validateVerification(verification, label) {
 
 export function validateItem(item, label = "item", options = {}) {
   object(item, label);
+  const contractSchemaVersion = options.contractSchemaVersion ?? 1;
+  const allowed = new Set(["id", "kind", "subject", "value", "statement", "scope", "status", "sources", "overrides", "approval", "verification"]);
+  if (contractSchemaVersion >= 3) allowed.add("consumption");
   exactKeys(
     item,
-    new Set(["id", "kind", "subject", "value", "statement", "scope", "status", "sources", "overrides", "approval", "verification"]),
+    allowed,
     label,
   );
   stableId(item.id, `${label}.id`);
@@ -193,6 +227,7 @@ export function validateItem(item, label = "item", options = {}) {
   }
   if (item.approval !== undefined && item.status !== "proposed") validateApproval(item.approval, `${label}.approval`);
   if (item.verification != null) validateVerification(item.verification, `${label}.verification`);
+  if (item.consumption !== undefined) validateConsumption(item.consumption, item, `${label}.consumption`);
   if (options.proposal && item.status !== "proposed") {
     fail("proposal-not-proposed", `${label} must remain proposed`);
   }
@@ -210,7 +245,7 @@ function assertUnique(records, label) {
 export function validateContract(contract) {
   object(contract, "contract");
   exactKeys(contract, new Set(["schemaVersion", "project", "sources", "items"]), "contract");
-  if (![1, 2].includes(contract.schemaVersion)) fail("schema-version-unsupported", "contract.schemaVersion must be 1 or 2");
+  if (![1, 2, 3].includes(contract.schemaVersion)) fail("schema-version-unsupported", "contract.schemaVersion must be 1, 2, or 3");
   object(contract.project, "contract.project");
   exactKeys(contract.project, new Set(["id", "name", "root"]), "contract.project");
   stableId(contract.project.id, "contract.project.id");
@@ -222,7 +257,7 @@ export function validateContract(contract) {
   contract.sources.forEach((source, index) => validateSource(source, `contract.sources[${index}]`, {
     contractSchemaVersion: contract.schemaVersion,
   }));
-  contract.items.forEach((item, index) => validateItem(item, `contract.items[${index}]`));
+  contract.items.forEach((item, index) => validateItem(item, `contract.items[${index}]`, { contractSchemaVersion: contract.schemaVersion }));
   assertUnique(contract.sources, "contract.sources");
   assertUnique(contract.items, "contract.items");
   const sourcesById = new Map(contract.sources.map((source) => [source.id, source]));
@@ -234,6 +269,15 @@ export function validateContract(contract) {
         fail("source-reference-deprecated", `item ${item.id} references deprecated source ${source}`);
       }
     }
+    for (const sourceId of [
+      ...(item.consumption?.requiredSources ?? []),
+      ...(item.consumption?.conditionalSources ?? []),
+    ]) {
+      const referenced = sourcesById.get(sourceId);
+      if (!referenced || !["file", "path", "json-pointer"].includes(referenced.kind)) {
+        fail("schema-invalid", `item ${item.id} consumption source must be a local source: ${sourceId}`);
+      }
+    }
     if (item.verification?.kind !== "none" && item.verification?.source) {
       const referenced = sourcesById.get(item.verification.source);
       if (!referenced) {
@@ -255,8 +299,8 @@ export function validateProposal(proposal) {
   if (!Array.isArray(proposal.sources) || !Array.isArray(proposal.items)) {
     fail("schema-invalid", "proposal.sources and proposal.items must be arrays");
   }
-  proposal.sources.forEach((source, index) => validateSource(source, `proposal.sources[${index}]`));
-  proposal.items.forEach((item, index) => validateItem(item, `proposal.items[${index}]`, { proposal: true }));
+  proposal.sources.forEach((source, index) => validateSource(source, `proposal.sources[${index}]`, { contractSchemaVersion: 3, proposal: true }));
+  proposal.items.forEach((item, index) => validateItem(item, `proposal.items[${index}]`, { proposal: true, contractSchemaVersion: 3 }));
   assertUnique(proposal.sources, "proposal.sources");
   assertUnique(proposal.items, "proposal.items");
   const sourceIds = new Set(proposal.sources.map((source) => source.id));
@@ -264,6 +308,15 @@ export function validateProposal(proposal) {
     for (const source of item.sources) {
       if (!sourceIds.has(source)) fail("source-reference-missing", `proposal item ${item.id} references unknown source ${source}`);
     }
+    for (const sourceId of [
+      ...(item.consumption?.requiredSources ?? []),
+      ...(item.consumption?.conditionalSources ?? []),
+    ]) {
+      const source = proposal.sources.find((entry) => entry.id === sourceId);
+      if (!source || !["file", "path", "json-pointer"].includes(source.kind)) {
+        fail("schema-invalid", `proposal item ${item.id} consumption source must be local: ${sourceId}`);
+      }
+    }
   }
   return proposal;
 }
@@ -308,7 +361,7 @@ export function validateProjectionLock(lock) {
       if (entry.regionId !== "project-context-ai-entry") fail("schema-invalid-enum", "AI Entry regionId is invalid");
       string(entry.regionDigest, `${label}.regionDigest`);
       if (!SHA256.test(entry.regionDigest)) fail("schema-invalid", "AI Entry regionDigest must be sha256");
-      if (![1, 2, 3, 4].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, 3, or 4");
+      if (![1, 2, 3, 4, 5].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, 3, 4, or 5");
       if (typeof entry.createdFile !== "boolean") fail("schema-invalid", `${label}.createdFile must be boolean`);
     } else {
       if (entry.target !== "agents" && entry.target !== "ruler") fail("schema-invalid-enum", "projection target is invalid");

package/src/project-context/coverage-profile.mjs

@@ -0,0 +1,127 @@
+import { canonicalJson, digestJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+import { scopeApplies } from "./scope-compiler.mjs";
+
+const COVERAGE_SUBJECT = "project.registration-coverage";
+const DISPOSITIONS = new Set(["contract-covered", "dynamic-investigation", "excluded-approved", "unresolved"]);
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail("coverage-profile-invalid", `${label} must be an object`);
+}
+
+function exactKeys(value, required, optional, label) {
+  object(value, label);
+  const allowed = new Set([...required, ...optional]);
+  for (const key of Object.keys(value)) if (!allowed.has(key)) fail("coverage-profile-invalid", `${label} contains unknown field: ${key}`);
+  for (const key of required) if (!Object.hasOwn(value, key)) fail("coverage-profile-invalid", `${label}.${key} is required`);
+}
+
+function strings(values, label) {
+  if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) fail("coverage-profile-invalid", `${label} must be a string array`);
+  return values;
+}
+
+function normalizePath(value, label) {
+  if (typeof value !== "string") fail("coverage-profile-invalid", `${label} must be a string`);
+  try {
+    return normalizeRelativePath(value, { allowRoot: true, label });
+  } catch {
+    fail("coverage-profile-invalid", `${label} must be a valid project-relative path`);
+  }
+}
+
+function normalizedPaths(values, label) {
+  const normalized = strings(values, label).map((value) => normalizePath(value, `${label} entry`));
+  return uniqueSorted(normalized);
+}
+
+export function coverageProfile(contract) {
+  const candidates = contract.items.filter((item) => item.status === "approved" && item.kind === "policy" && item.subject === COVERAGE_SUBJECT);
+  if (candidates.length === 0) return null;
+  if (candidates.length > 1) fail("coverage-profile-conflict", `multiple approved ${COVERAGE_SUBJECT} items are active`);
+  const item = candidates[0];
+  const value = item.value;
+  object(value, `${item.id} coverage value`);
+  if (value.version === 2) {
+    exactKeys(value, ["version", "domains"], [], `${item.id} coverage v2 value`);
+    if (!Array.isArray(value.domains)) fail("coverage-profile-invalid", `${item.id} coverage v2 domains must be an array`);
+    const approved = new Map(contract.items.filter((entry) => entry.status === "approved").map((entry) => [entry.id, entry]));
+    const ids = new Set();
+    const paths = new Set();
+    const domains = value.domains.map((domain, index) => {
+      const label = `${item.id} domains[${index}]`;
+      exactKeys(domain, ["id", "path", "disposition", "itemIds"], ["rationale"], label);
+      if (typeof domain.id !== "string" || domain.id.length === 0 || ids.has(domain.id)) fail("coverage-profile-invalid", `${label}.id must be unique`);
+      ids.add(domain.id);
+      const normalizedPath = normalizePath(domain.path, `${label}.path`);
+      if (normalizedPath !== domain.path || paths.has(normalizedPath)) fail("coverage-profile-invalid", `${label}.path must be normalized and unique`);
+      paths.add(normalizedPath);
+      if (!DISPOSITIONS.has(domain.disposition)) fail("coverage-profile-invalid", `${label}.disposition is invalid`);
+      const itemIds = uniqueSorted(strings(domain.itemIds, `${label}.itemIds`));
+      if (canonicalJson(itemIds) !== canonicalJson(domain.itemIds)) fail("coverage-profile-invalid", `${label}.itemIds must be sorted and unique`);
+      if (domain.disposition === "contract-covered") {
+        if (itemIds.length === 0) fail("coverage-profile-invalid", `${label} contract-covered domain requires itemIds`);
+        for (const itemId of itemIds) {
+          const covered = approved.get(itemId);
+          if (!covered || !scopeApplies(covered.scope, normalizedPath)) fail("coverage-profile-invalid", `${label} references an item that is not effective for its path: ${itemId}`);
+        }
+      }
+      if (domain.disposition === "excluded-approved" && (typeof domain.rationale !== "string" || domain.rationale.length === 0)) {
+        fail("coverage-profile-invalid", `${label} excluded-approved domain requires rationale`);
+      }
+      if (domain.rationale !== undefined && typeof domain.rationale !== "string") fail("coverage-profile-invalid", `${label}.rationale must be a string`);
+      return {
+        id: domain.id,
+        path: normalizedPath,
+        disposition: domain.disposition,
+        itemIds,
+        ...(domain.rationale !== undefined ? { rationale: domain.rationale } : {}),
+      };
+    }).sort((left, right) => left.id.localeCompare(right.id));
+    if (canonicalJson(domains) !== canonicalJson(value.domains)) fail("coverage-profile-invalid", `${item.id} domains must be stably sorted by id`);
+    return { itemId: item.id, itemDigest: digestJson(item), sourceIds: [...item.sources].sort(), version: 2, domains };
+  }
+  exactKeys(value, ["roots", "excludedPaths"], [], `${item.id} coverage value`);
+  return {
+    itemId: item.id,
+    itemDigest: digestJson(item),
+    sourceIds: [...item.sources].sort(),
+    version: 1,
+    roots: normalizedPaths(value.roots, "coverage roots"),
+    excludedPaths: normalizedPaths(value.excludedPaths, "coverage excluded paths"),
+  };
+}
+
+function pathWithin(target, parent) {
+  return parent === "." || target === parent || target.startsWith(`${parent}/`);
+}
+
+export function coverageDomainForPath(profile, candidatePath) {
+  if (!profile || profile.version !== 2) return null;
+  return profile.domains
+    .filter((entry) => pathWithin(candidatePath, entry.path))
+    .sort((left, right) => right.path.length - left.path.length || left.id.localeCompare(right.id))[0] ?? null;
+}
+
+export function coverageClass(profile, registeredPaths, candidatePath) {
+  if (registeredPaths.has(candidatePath)) return "registered";
+  if (!profile) return "outside-declared-coverage";
+  if (profile.version === 2) {
+    const domain = coverageDomainForPath(profile, candidatePath);
+    if (!domain) return "outside-declared-coverage";
+    return {
+      "contract-covered": "registered",
+      "dynamic-investigation": "dynamic-investigation",
+      "excluded-approved": "excluded-approved",
+      unresolved: "unresolved",
+    }[domain.disposition];
+  }
+  if (profile.excludedPaths.some((entry) => pathWithin(candidatePath, entry))) return "excluded-approved";
+  if (profile.roots.some((entry) => pathWithin(candidatePath, entry))) return "review-required";
+  return "outside-declared-coverage";
+}

package/src/project-context/exchange-schema.mjs

@@ -2,11 +2,11 @@ import { canonicalValue, digestJson, validateJsonValue } from "./canonical-json.
 import { fail } from "./errors.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 
-export const PACKAGE_VERSION = "1.8.0";
-export const EXCHANGE_PROTOCOL_VERSION = 8;
+export const PACKAGE_VERSION = "1.9.1";
+export const EXCHANGE_PROTOCOL_VERSION = 9;
 export const ACTION_PLAN_SCHEMA_VERSION = 2;
 export const REVIEW_BUNDLE_SCHEMA_VERSION = 2;
-export const CAPABILITIES_SCHEMA_VERSION = 8;
+export const CAPABILITIES_SCHEMA_VERSION = 9;
 
 export const ACTION_KINDS = Object.freeze([
   "accept-source-change",
@@ -143,7 +143,7 @@ function normalizeScope(value, label) {
 function normalizeItemInput(input, label, extra = []) {
   object(input, label);
   exactKeys(input, new Set([
-    "id", "kind", "subject", "value", "statement", "sources", "scope", "overrides", "verification", ...extra,
+    "id", "kind", "subject", "value", "statement", "sources", "scope", "overrides", "verification", "consumption", ...extra,
   ]), label);
   stableId(input.id, `${label}.id`);
   if (!ITEM_KINDS.has(input.kind)) invalid(`${label}.kind is invalid`);
@@ -159,6 +159,16 @@ function normalizeItemInput(input, label, extra = []) {
   sources.forEach((entry) => stableId(entry, `${label}.sources entry`));
   const overrides = uniqueStrings(input.overrides ?? [], `${label}.overrides`, { empty: true });
   overrides.forEach((entry) => stableId(entry, `${label}.overrides entry`));
+  let consumption;
+  if (input.consumption !== undefined) {
+    object(input.consumption, `${label}.consumption`);
+    exactKeys(input.consumption, new Set(["requiredSources", "conditionalSources"]), `${label}.consumption`);
+    const requiredSources = uniqueStrings(input.consumption.requiredSources, `${label}.consumption.requiredSources`, { empty: true });
+    const conditionalSources = uniqueStrings(input.consumption.conditionalSources, `${label}.consumption.conditionalSources`, { empty: true });
+    for (const source of [...requiredSources, ...conditionalSources]) if (!sources.includes(source)) invalid(`${label}.consumption source must be included in sources: ${source}`);
+    if (requiredSources.some((source) => conditionalSources.includes(source))) invalid(`${label}.consumption roles must be mutually exclusive`);
+    consumption = { requiredSources, conditionalSources };
+  }
   return {
     id: input.id,
     kind: input.kind,
@@ -168,18 +178,23 @@ function normalizeItemInput(input, label, extra = []) {
     sources,
     scope: normalizeScope(input.scope, `${label}.scope`),
     overrides,
+    ...(consumption ? { consumption } : {}),
     ...(input.verification !== undefined ? { verification: normalizeVerification(input.verification, `${label}.verification`) } : {}),
   };
 }
 
 function normalizeSourceInput(input, label) {
   object(input, label);
-  exactKeys(input, new Set(["id", "kind", "path", "pointer", "reference"]), label);
+  exactKeys(input, new Set(["id", "kind", "path", "pointer", "reference", "digestMode"]), label);
   stableId(input.id, `${label}.id`);
   if (!SOURCE_KINDS.has(input.kind)) invalid(`${label}.kind is invalid`);
   if (["file", "path", "json-pointer"].includes(input.kind)) {
     if (input.reference !== undefined) invalid(`${label}.reference is not allowed for local sources`);
     const normalized = { id: input.id, kind: input.kind, path: projectPath(input.path, `${label}.path`) };
+    if (input.digestMode !== undefined) {
+      if (input.kind !== "file" || !["full-file", "outside-owned-ai-entry"].includes(input.digestMode)) invalid(`${label}.digestMode is invalid`);
+      normalized.digestMode = input.digestMode;
+    }
     if (input.kind === "json-pointer") {
       string(input.pointer, `${label}.pointer`, { empty: true });
       if (input.pointer !== "" && !input.pointer.startsWith("/")) invalid(`${label}.pointer must use RFC 6901 syntax`);
@@ -187,7 +202,7 @@ function normalizeSourceInput(input, label) {
     } else if (input.pointer !== undefined) invalid(`${label}.pointer is only allowed for json-pointer`);
     return normalized;
   }
-  if (input.path !== undefined || input.pointer !== undefined) invalid(`${label} cannot contain a local path`);
+  if (input.path !== undefined || input.pointer !== undefined || input.digestMode !== undefined) invalid(`${label} cannot contain a local path or digest mode`);
   string(input.reference, `${label}.reference`);
   return { id: input.id, kind: input.kind, reference: input.reference };
 }
@@ -531,6 +546,8 @@ export function itemPrimitiveInput(input) {
     scope: input.scope.kind,
     scopePath: input.scope.path,
     overrides: [...input.overrides],
+    requiredSources: [...(input.consumption?.requiredSources ?? [])],
+    conditionalSources: [...(input.consumption?.conditionalSources ?? [])],
     verification: input.verification?.kind,
     verificationSource: input.verification?.source,
     verificationExpectedPresent: Boolean(input.verification && Object.hasOwn(input.verification, "expected")),

package/src/project-context/exchange.mjs

@@ -71,6 +71,8 @@ function itemArgs(input, options = {}) {
     "--scope", input.scope.kind,
     ...(input.scope.path ? ["--scope-path", input.scope.path] : []),
     ...(input.overrides.length > 0 ? ["--overrides", ...input.overrides] : []),
+    ...(input.consumption?.requiredSources?.length > 0 ? ["--required-source", ...input.consumption.requiredSources] : []),
+    ...(input.consumption?.conditionalSources?.length > 0 ? ["--conditional-source", ...input.consumption.conditionalSources] : []),
   ];
   if (input.verification) {
     args.push("--verification", input.verification.kind);
@@ -89,6 +91,7 @@ function sourceArgs(input) {
     ...(input.path ? ["--path", input.path] : []),
     ...(input.pointer !== undefined ? ["--pointer", input.pointer] : []),
     ...(input.reference ? ["--reference", input.reference] : []),
+    ...(input.digestMode ? ["--digest-mode", input.digestMode] : []),
   ];
 }
 

package/src/project-context/initialization-instruction.mjs

@@ -1,11 +1,12 @@
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import path from "node:path";
 import { sha256 } from "./canonical-json.mjs";
 import { PACKAGE_VERSION } from "./exchange-schema.mjs";
 
-export const INITIALIZATION_INSTRUCTION_SCHEMA_VERSION = 1;
+export const INITIALIZATION_INSTRUCTION_SCHEMA_VERSION = 2;
 export const INITIALIZATION_INSTRUCTION_ID = "ai-project-initialization";
-export const INITIALIZATION_INSTRUCTION_VERSION = 1;
+export const INITIALIZATION_INSTRUCTION_VERSION = 2;
 export const INITIALIZATION_INSTRUCTION_PACKAGE_PATH = "docs/AI-PROJECT-INITIALIZATION.md";
 export const INITIALIZATION_INSTRUCTION_COMMAND = "project-context instructions --project PATH [--json | --prompt]";
 
@@ -23,12 +24,29 @@ export async function readInitializationInstruction() {
 }
 
 export async function buildInitializationInstruction(targetRoot, boundaries) {
+  let entryContent = null;
+  try {
+    entryContent = await readFile(path.join(targetRoot, "AGENTS.md"), "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
   return {
     schemaVersion: INITIALIZATION_INSTRUCTION_SCHEMA_VERSION,
     package: { name: "frontend-project-context", version: PACKAGE_VERSION },
     instruction: await readInitializationInstruction(),
     targetRoot,
     boundaries: { ...boundaries },
+    entryRuleReview: {
+      path: "AGENTS.md",
+      present: entryContent !== null,
+      allowedDispositions: ["migrated-to-contract", "kept-in-entry-intentionally", "excluded-as-stale", "unresolved-blocker"],
+      records: entryContent === null || entryContent.trim().length === 0 ? [] : [{
+        id: "human-entry-content",
+        disposition: "unresolved-blocker",
+        rationale: "Classify every duplicated or legacy human entry rule in the concentrated initialization review before completion.",
+      }],
+      automaticDeletion: false,
+    },
   };
 }
 

package/src/project-context/maintenance.mjs

@@ -1,6 +1,6 @@
 import { digestJson } from "./canonical-json.mjs";
 import { buildItemProposal } from "./authoring.mjs";
-import { sourceStatus, validateContract, validateSourceLock } from "./contract-schema.mjs";
+import { promoteContractToSchema3, sourceStatus, validateContract, validateSourceLock } from "./contract-schema.mjs";
 import { fail } from "./errors.mjs";
 import { writeProjectState } from "./project-store.mjs";
 import { readSourceDigest } from "./source-reader.mjs";
@@ -104,7 +104,7 @@ export async function reviewSource(root, project, sourceId, options = {}) {
   let status;
   let reason;
   try {
-    currentDigest = await readSourceDigest(root, source, options.sourceReadContext);
+    currentDigest = await readSourceDigest(root, source, options.sourceReadContext, { projectionsLock: project.projectionsLock });
     if (lockedDigest === null || lockedDigest !== source.digest) {
       status = "unreadable";
       reason = lockedDigest === null ? "source-lock-missing" : "source-lock-mismatch";
@@ -179,7 +179,7 @@ export async function acceptSourceChange(root, project, input, options = {}) {
   if (options.write) {
     let actual;
     try {
-      actual = await readSourceDigest(root, source);
+      actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
     } catch (error) {
       fail("source-accept-digest-mismatch", "source became unavailable while acceptance was being prepared", {
         exitCode: 1,
@@ -266,7 +266,7 @@ export async function deprecateSource(project, input, options = {}) {
 
   const timestamp = input.at ?? new Date().toISOString();
   const nextContract = structuredClone(project.contract);
-  nextContract.schemaVersion = 2;
+  if (nextContract.schemaVersion < 2) nextContract.schemaVersion = 2;
   nextContract.sources = nextContract.sources.map((source) => {
     const active = source.status === undefined ? { ...source, status: "active" } : source;
     if (source.id !== input.id) return active;
@@ -326,6 +326,7 @@ export async function reviseItem(root, project, input, options = {}) {
     });
   }
   const nextContract = structuredClone(project.contract);
+  if (replacement.consumption !== undefined) promoteContractToSchema3(nextContract);
   nextContract.items[nextContract.items.findIndex((item) => item.id === input.id)] = replacement;
   validateContract(nextContract);
   if (options.write) await writeProjectState(project, nextContract, project.sourcesLock, options.storeOptions);

package/src/project-context/migration-manifest.mjs

@@ -22,7 +22,7 @@ const MIGRATION_KINDS = new Set([
 ]);
 const ROLLBACK_CLASSES = new Set(["package-only", "reversible-data", "forward-only"]);
 const CONSUMER_CHANGE_KEYS = new Set([
-  "actionPlan", "adaptiveContextBundle", "capabilities", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
+  "actionPlan", "adaptiveContextBundle", "capabilities", "contextBundle", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
   "hostPromotionEvidence", "integrationReviewBundle", "reviewBundle", "routingIndex", "stageContextBundle", "stageReceipt", "taskContextPlan",
   "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
 ]);
@@ -103,7 +103,7 @@ export function validateMigrationManifest(input) {
   ]), "migration manifest");
   if (manifest.schemaVersion !== MIGRATION_MANIFEST_SCHEMA_VERSION) invalid("migration manifest schemaVersion must be 2");
   exactKeys(manifest.package, new Set(["name", "version"]), "migration manifest package");
-  if (manifest.package.name !== "frontend-project-context" || manifest.package.version !== "1.8.0") invalid("migration manifest package does not match this runtime");
+  if (manifest.package.name !== "frontend-project-context" || manifest.package.version !== "1.9.1") invalid("migration manifest package does not match this runtime");
   versions(manifest.upgradeFrom, "upgradeFrom");
   if (manifest.upgradeFrom.length === 0) invalid("upgradeFrom must not be empty");
   exactKeys(manifest.stores, new Set(["contract", "projectionLock", "proposal", "sourceLock"]), "stores");
@@ -111,7 +111,7 @@ export function validateMigrationManifest(input) {
   exactKeys(manifest.renderers, new Set(["aiEntry", "projection"]), "renderers");
   for (const name of Object.keys(manifest.renderers)) versionMatrix(manifest.renderers[name], `renderers.${name}`);
   exactKeys(manifest.protocols, new Set([
-    "exchange", "actionPlan", "adaptiveContextBundle", "contextQuery", "coverageAudit", "reviewBundle", "evidenceInput", "evidenceBundle", "taskContextPlan",
+    "exchange", "actionPlan", "adaptiveContextBundle", "contextBundle", "contextQuery", "coverageAudit", "reviewBundle", "evidenceInput", "evidenceBundle", "taskContextPlan",
     "routingIndex", "stageReceipt", "stageContextBundle", "integrationReviewBundle", "hostPromotionEvidence",
     "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
   ]), "protocols");

package/src/project-context/renderer.mjs

@@ -64,7 +64,7 @@ function groupedSections(sections) {
   return groups;
 }
 
-function renderCollectedBundle(bundle, sources, task, options = {}) {
+export function renderCollectedContextBundle(bundle, sources, task, options = {}) {
   const locale = options.locale ?? "zh-CN";
   const lines = [
     "# Project Context Bundle",
@@ -100,11 +100,18 @@ function renderCollectedBundle(bundle, sources, task, options = {}) {
       lines.push(`- \`${id}\` — ${source?.kind ?? "unknown"}: \`${location}\``);
     }
   }
+  if ((options.gaps ?? []).length > 0) {
+    lines.push("", "## Context gaps", "");
+    for (const gap of options.gaps) lines.push(`- \`${gap.code}\`${gap.path ? ` — \`${gap.path}\`` : ""}`);
+  }
+  if ((options.nextActions ?? []).length > 0) {
+    lines.push("", "## Next actions", "", ...options.nextActions.map((action) => `- \`${action}\``));
+  }
   return `${lines.join("\n")}\n`;
 }
 
 export function renderContextBundle(contract, paths, task, options = {}) {
-  return renderCollectedBundle(collectBundle(contract, paths), contract.sources, task, options);
+  return renderCollectedContextBundle(collectBundle(contract, paths), contract.sources, task, options);
 }
 
 export function renderSelectedContextBundle(contract, paths, itemIds, task, options = {}) {
@@ -122,7 +129,7 @@ export function renderSelectedContextBundle(contract, paths, itemIds, task, opti
     sections,
     itemIds: [...selected].sort(),
   };
-  return renderCollectedBundle(bundle, contract.sources, task, options);
+  return renderCollectedContextBundle(bundle, contract.sources, task, options);
 }
 
 // Task delivery deliberately has its own renderer. Managed AGENTS/Ruler projections
@@ -183,7 +190,7 @@ export function renderTaskContextBundle(contract, paths, itemIds, task, options
 
 export function renderProjection(contract, paths, target) {
   const bundle = collectBundle(contract, paths);
-  const body = renderCollectedBundle(bundle, contract.sources);
+  const body = renderCollectedContextBundle(bundle, contract.sources);
   const bundleDigest = sha256(body);
   const marker = `<!-- managed-by: project-context; renderer-version: ${RENDERER_VERSION}; target: ${target}; contract-digest: ${bundle.contractDigest}; bundle-digest: ${bundleDigest} -->`;
   return {

package/src/project-context/source-reader.mjs

@@ -1,6 +1,7 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { canonicalJson, sha256 } from "./canonical-json.mjs";
+import { canonicalJson, digestJson, sha256 } from "./canonical-json.mjs";
+import { AI_ENTRY_REGION_ID, parseAiEntryRegion } from "./ai-entry.mjs";
 import { sourceStatus } from "./contract-schema.mjs";
 import { fail } from "./errors.mjs";
 import { resolveExistingInside } from "./path-policy.mjs";
@@ -97,10 +98,34 @@ export async function digestPathIdentity(projectRoot, relativePath, context) {
   });
 }
 
-export async function readSourceDigest(projectRoot, source, context) {
+async function digestOutsideOwnedAiEntry(projectRoot, source, context, projectionsLock) {
+  const lock = projectionsLock?.projections?.find((entry) => entry.path === source.path);
+  if (!lock || lock.ownership !== "region" || lock.target !== "ai-entry" || lock.regionId !== AI_ENTRY_REGION_ID) {
+    fail("source-digest-ownership-invalid", `outside-owned-ai-entry requires a trusted AI Entry lock: ${source.path}`);
+  }
+  const { absolute } = await resolveExistingInside(projectRoot, source.path);
+  const content = await cached(context, `body:${absolute}`, async () => {
+    if (context?.metrics) context.metrics.sourceBodyReads += 1;
+    return readFile(absolute, "utf8");
+  });
+  const parsed = parseAiEntryRegion(content);
+  if (parsed.state !== "present") fail("source-digest-marker-invalid", `AI Entry markers are not valid: ${source.path}`);
+  if (sha256(parsed.region) !== lock.regionDigest) fail("source-digest-ownership-invalid", `AI Entry region digest does not match its lock: ${source.path}`);
+  const renderer = /project-context:ai-entry; schema-version: 1; renderer-version: (\d+)/u.exec(parsed.region)?.[1];
+  if (renderer === undefined || Number(renderer) !== lock.rendererVersion) {
+    fail("source-digest-ownership-invalid", `AI Entry renderer does not match its lock: ${source.path}`);
+  }
+  return digestJson({ before: content.slice(0, parsed.start), after: content.slice(parsed.end) });
+}
+
+export async function readSourceDigest(projectRoot, source, context, options = {}) {
   if (sourceStatus(source) === "deprecated") return null;
   if (source.kind === "human-decision" || source.kind === "external-reference") return null;
   if (source.kind === "path") return digestPathIdentity(projectRoot, source.path, context);
+  if (source.kind === "file" && source.digestMode === "outside-owned-ai-entry") {
+    return cached(context, `digest:outside-owned-ai-entry:${source.path}`, () =>
+      digestOutsideOwnedAiEntry(projectRoot, source, context, options.projectionsLock));
+  }
   if (source.kind === "file") return digestPath(projectRoot, source.path, context);
   return sha256(canonicalJson(await readJsonSourceValue(projectRoot, source, context)));
 }

package/src/project-context/upgrade-schema.mjs

@@ -121,7 +121,7 @@ export function validateUpgradeAssessment(input) {
     stores: new Set(["contract", "projectionLock", "proposal", "sourceLock"]),
     renderers: new Set(["aiEntry", "projection"]),
     protocols: new Set([
-      "actionPlan", "adaptiveContextBundle", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
+      "actionPlan", "adaptiveContextBundle", "contextBundle", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
       "hostPromotionEvidence", "integrationReviewBundle", "reviewBundle", "routingIndex", "stageContextBundle", "stageReceipt",
       "taskContextPlan", "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
     ]),