frontend-project-context 1.3.1 → 1.7.0

package/src/project-context/ai-entry.mjs

@@ -0,0 +1,320 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { canonicalJson, digestJson, sha256 } from "./canonical-json.mjs";
+import { sourceStatus, validateContract, validateProjectionLock } from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { atomicWriteFile, atomicWriteJson, readJsonFile } from "./io.mjs";
+import { normalizeRelativePath, resolveWritableInside } from "./path-policy.mjs";
+
+export const AI_ENTRY_RENDERER_VERSION = 3;
+export const AI_ENTRY_REGION_ID = "project-context-ai-entry";
+export const AI_ENTRY_START = "<!-- project-context:ai-entry:start -->";
+export const AI_ENTRY_END = "<!-- project-context:ai-entry:end -->";
+
+const ENTRY_LINES = [
+  AI_ENTRY_START,
+  "<!-- project-context:ai-entry; schema-version: 1; renderer-version: 3 -->",
+  "## Project Context 启动流程",
+  "",
+  "开始项目工作前，使用项目本地安装的 `frontend-project-context` CLI，不要临时下载其他版本。",
+  "",
+  "1. 运行 `npm exec --offline -- project-context status --project . --json`；如果本地依赖不存在，停止并报告，不要临时下载同名包。",
+  "2. 如果状态为 `partial` 或 `invalid`，停止写入并报告准确的恢复证据。",
+  "3. 如果尚未初始化，先预览 `setup`；如果已初始化但需要处理，使用 `sync` 工作单元；如果为 `clean`，继续遵守本文件其余仓库规则，并执行已获授权的用户任务。",
+  "4. 任何 plan、bundle、receipt、review 或 AI 建议都不代表人工批准。",
+  "5. 声明完成前，将 Project Context 恢复为 `clean`，否则报告准确的阻断项。",
+  AI_ENTRY_END,
+];
+
+function entryOutput(output) {
+  let normalized;
+  try {
+    normalized = normalizeRelativePath(output, { label: "AI Entry output" });
+  } catch (error) {
+    fail("ai-entry-output-invalid", "AI Entry output must stay inside the project", {
+      exitCode: 2,
+      cause: error,
+      details: { path: output },
+    });
+  }
+  if (path.posix.basename(normalized) !== "AGENTS.md") {
+    fail("ai-entry-output-invalid", "AI Entry output must be an AGENTS.md file", {
+      exitCode: 2,
+      details: { path: normalized },
+    });
+  }
+  return normalized;
+}
+
+async function resolveEntryOutput(root, output, write) {
+  const normalized = entryOutput(output);
+  try {
+    return await resolveWritableInside(root, normalized, { createParent: write });
+  } catch (error) {
+    fail("ai-entry-output-invalid", "AI Entry output is not safely writable inside the project", {
+      exitCode: 2,
+      cause: error,
+      details: { path: normalized, reason: error.code ?? "invalid-output" },
+    });
+  }
+}
+
+async function readIfPresent(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function count(content, needle) {
+  return content.split(needle).length - 1;
+}
+
+export function renderAiEntry(newline = "\n") {
+  return ENTRY_LINES.join(newline);
+}
+
+export function parseAiEntryRegion(content) {
+  if (typeof content !== "string") return { state: "absent", region: null };
+  const starts = count(content, AI_ENTRY_START);
+  const ends = count(content, AI_ENTRY_END);
+  if (starts === 0 && ends === 0) return { state: "absent", region: null };
+  if (starts !== 1 || ends !== 1) return { state: "conflict", reason: "marker-count", region: null };
+  const start = content.indexOf(AI_ENTRY_START);
+  const endStart = content.indexOf(AI_ENTRY_END);
+  if (endStart <= start) return { state: "conflict", reason: "marker-order", region: null };
+  const end = endStart + AI_ENTRY_END.length;
+  const between = content.slice(start + AI_ENTRY_START.length, endStart);
+  if (between.includes(AI_ENTRY_START) || between.includes(AI_ENTRY_END)) {
+    return { state: "conflict", reason: "nested-marker", region: null };
+  }
+  return { state: "present", start, end, region: content.slice(start, end) };
+}
+
+function newlineFor(content) {
+  return content?.includes("\r\n") ? "\r\n" : "\n";
+}
+
+function appendRegion(content, region, newline) {
+  if (content === null || content.length === 0) return region;
+  const trailingNewline = content.endsWith("\r\n") || content.endsWith("\n");
+  return `${content}${trailingNewline ? newline : `${newline}${newline}`}${region}`;
+}
+
+function schema2FileEntry(entry) {
+  return entry.ownership ? structuredClone(entry) : { ...structuredClone(entry), ownership: "file" };
+}
+
+function sourceImpact(project, output, afterDigest) {
+  const sources = project.contract.sources
+    .filter((source) => sourceStatus(source) === "active" && ["file", "path", "json-pointer"].includes(source.kind) && source.path === output)
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const sourceIds = sources.map((source) => source.id);
+  const selected = new Set(sourceIds);
+  const itemIds = project.contract.items
+    .filter((item) => item.sources.some((id) => selected.has(id)) || selected.has(item.verification?.source))
+    .map((item) => item.id)
+    .sort((left, right) => left.localeCompare(right));
+  return { sourceIds, itemIds, afterDigest: sourceIds.length > 0 ? afterDigest : null };
+}
+
+function ownershipConflict(pathname, reason) {
+  fail("ai-entry-ownership-conflict", `AI Entry ownership is not trustworthy: ${pathname}`, {
+    exitCode: 3,
+    details: { path: pathname, reason },
+  });
+}
+
+function entryLock(project, output) {
+  return project.projectionsLock.projections.find((entry) => entry.path === output) ?? null;
+}
+
+function assertEntryOwnership(output, content, lockEntry, parsed) {
+  if (lockEntry && lockEntry.ownership !== "region") {
+    fail("ai-entry-path-conflict", `AI Entry conflicts with a whole-file projection: ${output}`, {
+      exitCode: 3,
+      details: { path: output },
+    });
+  }
+  if (parsed.state === "conflict") ownershipConflict(output, parsed.reason);
+  if (parsed.state === "present" && !lockEntry) ownershipConflict(output, "marker-without-lock");
+  if (parsed.state === "absent" && lockEntry) ownershipConflict(output, "lock-without-marker");
+  if (lockEntry && sha256(parsed.region) !== lockEntry.regionDigest) ownershipConflict(output, "region-digest-mismatch");
+}
+
+function nextProjectionLock(project, output, nextEntry) {
+  return validateProjectionLock({
+    schemaVersion: 2,
+    projections: [
+      ...project.projectionsLock.projections
+        .filter((entry) => entry.path !== output)
+        .map(schema2FileEntry),
+      ...(nextEntry ? [nextEntry] : []),
+    ].sort((left, right) => left.path.localeCompare(right.path)),
+  });
+}
+
+async function commitEntry(project, resolved, existing, nextContent, nextLock, dependencies) {
+  const readJson = dependencies.readJson ?? readJsonFile;
+  const readContent = dependencies.readFile ?? readIfPresent;
+  const writeJson = dependencies.writeJson ?? atomicWriteJson;
+  const writeFile = dependencies.writeFile ?? atomicWriteFile;
+  if (dependencies.beforeCommit) await dependencies.beforeCommit();
+  const currentContract = validateContract(await readJson(project.files.contract, "contract.json"));
+  const currentLock = validateProjectionLock(await readJson(project.files.projectionsLock, "projections.lock.json"));
+  if (digestJson(currentContract) !== project.contractDigest) {
+    fail("ai-entry-state-changed", "contract changed while the AI Entry was being prepared", { exitCode: 1 });
+  }
+  if (digestJson(currentLock) !== project.projectionsLockDigest) {
+    fail("ai-entry-state-changed", "projection lock changed while the AI Entry was being prepared", { exitCode: 1 });
+  }
+  if (await readContent(resolved.absolute) !== existing) {
+    fail("ai-entry-state-changed", "AGENTS.md changed while the AI Entry was being prepared", {
+      exitCode: 1,
+      details: { path: resolved.normalized },
+    });
+  }
+  await writeJson(project.files.projectionsLock, nextLock);
+  try {
+    await writeFile(resolved.absolute, nextContent);
+  } catch (error) {
+    try {
+      const recoveryCurrent = validateProjectionLock(await readJson(project.files.projectionsLock, "projections.lock.json"));
+      if (canonicalJson(recoveryCurrent) === canonicalJson(nextLock)) {
+        await writeJson(project.files.projectionsLock, project.projectionsLock);
+      } else if (error && typeof error === "object") {
+        error.details = { ...(error.details ?? {}), recovery: "projection-lock-restore-skipped-concurrent-change" };
+      }
+    } catch (recoveryError) {
+      if (error && typeof error === "object") {
+        error.details = { ...(error.details ?? {}), recovery: "projection-lock-restore-failed", recoveryMessage: recoveryError.message };
+      }
+    }
+    throw error;
+  }
+}
+
+export async function inspectAiEntry(root, project, output = "AGENTS.md") {
+  const resolved = await resolveEntryOutput(root, output, false);
+  const content = await readIfPresent(resolved.absolute);
+  const parsed = parseAiEntryRegion(content);
+  const lockEntry = entryLock(project, resolved.normalized);
+  if (lockEntry && lockEntry.ownership !== "region") {
+    return { state: "absent", path: null, rendererVersion: null };
+  }
+  if (content === null && lockEntry?.ownership === "region") {
+    return { state: "absent", path: resolved.normalized, rendererVersion: lockEntry.rendererVersion };
+  }
+  try {
+    assertEntryOwnership(resolved.normalized, content, lockEntry, parsed);
+  } catch (error) {
+    if (error?.code === "ai-entry-ownership-conflict" || error?.code === "ai-entry-path-conflict") {
+      return { state: "conflict", path: resolved.normalized, rendererVersion: lockEntry?.rendererVersion ?? null, reason: error.details?.reason ?? error.code };
+    }
+    throw error;
+  }
+  if (!lockEntry) return { state: "absent", path: null, rendererVersion: null };
+  return {
+    state: lockEntry.rendererVersion === AI_ENTRY_RENDERER_VERSION ? "current" : "stale",
+    path: resolved.normalized,
+    rendererVersion: lockEntry.rendererVersion,
+  };
+}
+
+export async function publishAiEntry(root, project, options, dependencies = {}) {
+  const write = Boolean(options.write);
+  const resolved = await resolveEntryOutput(root, options.output, write);
+  const readContent = dependencies.readFile ?? readIfPresent;
+  const existing = await readContent(resolved.absolute);
+  const parsed = parseAiEntryRegion(existing);
+  const currentEntry = entryLock(project, resolved.normalized);
+  assertEntryOwnership(resolved.normalized, existing, currentEntry, parsed);
+  const newline = newlineFor(existing);
+  const region = renderAiEntry(newline);
+  const nextContent = parsed.state === "present"
+    ? `${existing.slice(0, parsed.start)}${region}${existing.slice(parsed.end)}`
+    : appendRegion(existing, region, newline);
+  const nextEntry = {
+    path: resolved.normalized,
+    target: "ai-entry",
+    ownership: "region",
+    regionId: AI_ENTRY_REGION_ID,
+    regionDigest: sha256(region),
+    rendererVersion: AI_ENTRY_RENDERER_VERSION,
+    createdFile: existing === null || currentEntry?.createdFile === true,
+  };
+  const nextLock = nextProjectionLock(project, resolved.normalized, nextEntry);
+  const action = currentEntry && existing === nextContent && canonicalJson(currentEntry) === canonicalJson(nextEntry) ? "unchanged" : currentEntry ? "update" : "create";
+  const impact = sourceImpact(project, resolved.normalized, sha256(nextContent));
+  const result = {
+    action,
+    current: {
+      entry: currentEntry ? structuredClone(currentEntry) : null,
+      contentDigest: existing === null ? null : sha256(existing),
+      region: parsed.region,
+    },
+    proposed: {
+      entry: nextEntry,
+      contentDigest: sha256(nextContent),
+      region,
+    },
+    baselines: {
+      contract: project.contractDigest,
+      projectionsLock: project.projectionsLockDigest,
+      content: existing === null ? null : sha256(existing),
+    },
+    migration: {
+      required: project.projectionsLock.schemaVersion === 1,
+      from: project.projectionsLock.schemaVersion,
+      to: 2,
+      trigger: "publish-entry",
+    },
+    impact: { itemIds: impact.itemIds, sourceIds: impact.sourceIds, paths: [resolved.normalized], projectionPaths: [resolved.normalized], afterSourceDigest: impact.afterDigest },
+    written: false,
+  };
+  if (write && action !== "unchanged") {
+    await commitEntry(project, resolved, existing, nextContent, nextLock, dependencies);
+    result.written = true;
+  }
+  return result;
+}
+
+export async function removeAiEntry(root, project, options, dependencies = {}) {
+  const write = Boolean(options.write);
+  const resolved = await resolveEntryOutput(root, options.output, false);
+  const readContent = dependencies.readFile ?? readIfPresent;
+  const existing = await readContent(resolved.absolute);
+  const parsed = parseAiEntryRegion(existing);
+  const currentEntry = entryLock(project, resolved.normalized);
+  assertEntryOwnership(resolved.normalized, existing, currentEntry, parsed);
+  if (!currentEntry) {
+    return {
+      action: "unchanged",
+      current: { entry: null, contentDigest: existing === null ? null : sha256(existing), region: null },
+      proposed: { entry: null, contentDigest: existing === null ? null : sha256(existing), region: null },
+      baselines: { contract: project.contractDigest, projectionsLock: project.projectionsLockDigest, content: existing === null ? null : sha256(existing) },
+      migration: { required: false, from: project.projectionsLock.schemaVersion, to: project.projectionsLock.schemaVersion, trigger: null },
+      impact: { itemIds: [], sourceIds: [], paths: [resolved.normalized], projectionPaths: [resolved.normalized], afterSourceDigest: null },
+      written: false,
+    };
+  }
+  const nextContent = `${existing.slice(0, parsed.start)}${existing.slice(parsed.end)}`;
+  const nextLock = nextProjectionLock(project, resolved.normalized, null);
+  const impact = sourceImpact(project, resolved.normalized, sha256(nextContent));
+  const result = {
+    action: "remove",
+    current: { entry: structuredClone(currentEntry), contentDigest: sha256(existing), region: parsed.region },
+    proposed: { entry: null, contentDigest: sha256(nextContent), region: null },
+    baselines: { contract: project.contractDigest, projectionsLock: project.projectionsLockDigest, content: sha256(existing) },
+    migration: { required: false, from: project.projectionsLock.schemaVersion, to: 2, trigger: null },
+    impact: { itemIds: impact.itemIds, sourceIds: impact.sourceIds, paths: [resolved.normalized], projectionPaths: [resolved.normalized], afterSourceDigest: impact.afterDigest },
+    written: false,
+  };
+  if (write) {
+    await commitEntry(project, resolved, existing, nextContent, nextLock, dependencies);
+    result.written = true;
+  }
+  return result;
+}

package/src/project-context/assist.mjs

@@ -5,6 +5,7 @@ import { fail } from "./errors.mjs";
 import { reviewSource } from "./maintenance.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 import { effectiveItems, scopeApplies } from "./scope-compiler.mjs";
+import { createSourceReadContext } from "./source-reader.mjs";
 
 const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
 const LARGE_IMPACT_THRESHOLD = 100;
@@ -347,11 +348,12 @@ function syncWorkUnits(problemReviews, signals, findings, pendingItems) {
 }
 
 export async function buildSyncAssistBundle(root, project, changedPaths = []) {
+  const sourceReadContext = createSourceReadContext();
   const reviewResults = await Promise.all(project.contract.sources.map(async (source) => {
     if (sourceStatus(source) === "deprecated" || !LOCAL_SOURCE_KINDS.has(source.kind)) {
       return { source, nonLocal: nonLocalSourceChange(source) };
     }
-    return { source, review: await reviewSource(root, project, source.id) };
+    return { source, review: await reviewSource(root, project, source.id, { sourceReadContext }) };
   }));
   const reviews = reviewResults.filter((entry) => entry.review).map((entry) => entry.review);
   const problemReviews = reviews.filter((review) => ["changed", "missing", "unreadable"].includes(review.status));
@@ -368,7 +370,7 @@ export async function buildSyncAssistBundle(root, project, changedPaths = []) {
     .map((id) => affectedItem(itemById.get(id), sourceImpacts.get(id), largeImpactIds.has(id)))
     .sort((left, right) => left.id.localeCompare(right.id));
   const signals = pathSignals(project.contract, changedPaths);
-  const findings = stableFindings(await checkProject(root, project));
+  const findings = stableFindings(await checkProject(root, project, { sourceReadContext }));
   const pending = project.contract.items
     .filter((item) => item.status === "proposed")
     .map(pendingItem)

package/src/project-context/capabilities.mjs

@@ -11,6 +11,9 @@ import {
 } from "./exchange-schema.mjs";
 import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
 import { RENDERER_VERSION } from "./renderer.mjs";
+import { AI_ENTRY_RENDERER_VERSION } from "./ai-entry.mjs";
+import { PROJECT_STATUS_SCHEMA_VERSION } from "./project-status.mjs";
+import { EVIDENCE_BUNDLE_SCHEMA_VERSION, EVIDENCE_INPUT_SCHEMA_VERSION } from "./evidence-schema.mjs";
 import {
   CONTEXT_BUDGET_UNIT,
   INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
@@ -18,57 +21,99 @@ import {
   STAGE_RECEIPT_SCHEMA_VERSION,
   TASK_CONTEXT_PLAN_SCHEMA_VERSION,
 } from "./task-context-schema.mjs";
+import {
+  MIGRATION_PLAN_SCHEMA_VERSION,
+  UPGRADE_ASSESSMENT_SCHEMA_VERSION,
+  UPGRADE_RESULT_BUNDLE_SCHEMA_VERSION,
+} from "./upgrade-schema.mjs";
+import {
+  ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+  CONTEXT_QUERY_SCHEMA_VERSION,
+  COVERAGE_AUDIT_SCHEMA_VERSION,
+  ROUTING_INDEX_SCHEMA_VERSION,
+} from "./adaptive-context-schema.mjs";
+import {
+  HOST_PROMOTION_EVIDENCE_SCHEMA_VERSION,
+  TRUTH_RECONCILIATION_INPUT_SCHEMA_VERSION,
+  TRUTH_RECONCILIATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+} from "./truth-reconciliation-schema.mjs";
 
-function schemas() {
+function schemas(projectionLockWritten = 1) {
   return {
     actionPlan: ACTION_PLAN_SCHEMA_VERSION,
+    adaptiveContextBundle: ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION,
     assistBundle: ASSIST_BUNDLE_SCHEMA_VERSION,
     capabilities: CAPABILITIES_SCHEMA_VERSION,
     contract: 2,
+    contextQuery: CONTEXT_QUERY_SCHEMA_VERSION,
+    coverageAudit: COVERAGE_AUDIT_SCHEMA_VERSION,
     dashboardViewModel: DASHBOARD_SCHEMA_VERSION,
+    evidenceBundle: EVIDENCE_BUNDLE_SCHEMA_VERSION,
+    evidenceInput: EVIDENCE_INPUT_SCHEMA_VERSION,
     integrationReviewBundle: INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
-    projectionLock: 1,
+    hostPromotionEvidence: HOST_PROMOTION_EVIDENCE_SCHEMA_VERSION,
+    projectionLock: 2,
+    projectionLockReadable: [1, 2],
+    projectionLockWritten,
     projectionRenderer: RENDERER_VERSION,
     proposal: 1,
+    projectStatus: PROJECT_STATUS_SCHEMA_VERSION,
+    aiEntryRenderer: AI_ENTRY_RENDERER_VERSION,
+    migrationManifest: 2,
+    migrationPlan: MIGRATION_PLAN_SCHEMA_VERSION,
     reviewBundle: REVIEW_BUNDLE_SCHEMA_VERSION,
+    routingIndex: ROUTING_INDEX_SCHEMA_VERSION,
     sourceLock: 1,
     stageContextBundle: STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
     stageReceipt: STAGE_RECEIPT_SCHEMA_VERSION,
     taskContextPlan: TASK_CONTEXT_PLAN_SCHEMA_VERSION,
+    truthReconciliationInput: TRUTH_RECONCILIATION_INPUT_SCHEMA_VERSION,
+    truthReconciliationReviewBundle: TRUTH_RECONCILIATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+    upgradeAssessment: UPGRADE_ASSESSMENT_SCHEMA_VERSION,
+    upgradeResultBundle: UPGRADE_RESULT_BUNDLE_SCHEMA_VERSION,
   };
 }
 
+export const PERMANENT_BOUNDARIES = Object.freeze({
+  provider: false,
+  agentRuntime: false,
+  git: false,
+  network: false,
+  dependencyInstallation: false,
+  automaticApproval: false,
+  businessCodeWrites: false,
+  taskExecution: false,
+  stagePathBodyReads: false,
+  applyPlan: false,
+  scheduler: false,
+  daemon: false,
+  telemetry: false,
+  selfUpdate: false,
+  automaticEvidenceUpload: false,
+  packageManager: false,
+  automaticUpgrade: false,
+});
+
 export async function buildCapabilities(root) {
   const initialization = await inspectProjectInitialization(root);
   let project = null;
+  let projectionLockWritten = 1;
   if (initialization.status === "initialized") {
     const loaded = await loadProject(root);
     project = { id: loaded.contract.project.id, name: loaded.contract.project.name };
+    projectionLockWritten = loaded.projectionsLock.schemaVersion;
   }
   return {
     schemaVersion: CAPABILITIES_SCHEMA_VERSION,
     package: { name: "frontend-project-context", version: PACKAGE_VERSION },
     exchangeProtocolVersion: EXCHANGE_PROTOCOL_VERSION,
-    schemas: schemas(),
+    schemas: schemas(projectionLockWritten),
     commands: [...COMMANDS],
     actionKinds: [...ACTION_KINDS],
     contextBudget: { unit: CONTEXT_BUDGET_UNIT, modelTokens: false, callerMustProvideLimit: true },
     initialization: initialization.status,
     initialized: initialization.status === "initialized",
     project,
-    boundaries: {
-      provider: false,
-      agentRuntime: false,
-      git: false,
-      network: false,
-      dependencyInstallation: false,
-      automaticApproval: false,
-      businessCodeWrites: false,
-      taskExecution: false,
-      stagePathBodyReads: false,
-      applyPlan: false,
-      scheduler: false,
-      daemon: false,
-    },
+    boundaries: { ...PERMANENT_BOUNDARIES },
   };
 }

package/src/project-context/checker.mjs

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { AI_ENTRY_RENDERER_VERSION, parseAiEntryRegion } from "./ai-entry.mjs";
 import { sha256 } from "./canonical-json.mjs";
 import { sourceStatus } from "./contract-schema.mjs";
 import { readSourceDigest, verifyItem } from "./source-reader.mjs";
@@ -7,7 +8,8 @@ import { findConflicts, validateOverrides } from "./scope-compiler.mjs";
 import { parseProjectionMarker, RENDERER_VERSION, renderProjection } from "./renderer.mjs";
 import { resolveWritableInside } from "./path-policy.mjs";
 
-export async function checkProject(root, project) {
+export async function checkProject(root, project, options = {}) {
+  const sourceReadContext = options.sourceReadContext;
   const findings = [];
   const contractSourceIds = new Set(project.contract.sources.map((source) => source.id));
   const sourceLock = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
@@ -24,7 +26,7 @@ export async function checkProject(root, project) {
       continue;
     }
     try {
-      const actual = await readSourceDigest(root, source);
+      const actual = await readSourceDigest(root, source, sourceReadContext);
       if (actual !== locked) findings.push({ code: "source-changed", source: source.id, path: source.path, expected: locked, actual });
     } catch (error) {
       const code = error.code === "source-missing"
@@ -50,7 +52,7 @@ export async function checkProject(root, project) {
   const sourceMap = new Map(project.contract.sources.map((source) => [source.id, source]));
   for (const item of project.contract.items.filter((candidate) => candidate.status === "approved")) {
     try {
-      const verification = await verifyItem(root, item, sourceMap);
+      const verification = await verifyItem(root, item, sourceMap, sourceReadContext);
       if (verification) findings.push(verification);
     } catch (error) {
       findings.push({
@@ -74,7 +76,23 @@ export async function checkProject(root, project) {
     try {
       content = await readFile(resolved.absolute, "utf8");
     } catch (error) {
-      findings.push({ code: error?.code === "ENOENT" ? "projection-missing" : "projection-unreadable", path: entry.path });
+      findings.push({
+        code: entry.ownership === "region"
+          ? error?.code === "ENOENT" ? "ai-entry-missing" : "projection-unreadable"
+          : error?.code === "ENOENT" ? "projection-missing" : "projection-unreadable",
+        path: entry.path,
+      });
+      continue;
+    }
+    if (entry.ownership === "region") {
+      const parsed = parseAiEntryRegion(content);
+      if (parsed.state !== "present" || sha256(parsed.region) !== entry.regionDigest) {
+        findings.push({ code: "ai-entry-ownership-conflict", path: entry.path });
+        continue;
+      }
+      if (entry.rendererVersion !== AI_ENTRY_RENDERER_VERSION) {
+        findings.push({ code: "ai-entry-renderer-stale", path: entry.path, expected: AI_ENTRY_RENDERER_VERSION, actual: entry.rendererVersion });
+      }
       continue;
     }
     const marker = parseProjectionMarker(content);
@@ -113,7 +131,7 @@ export async function checkProject(root, project) {
 }
 
 export function checkExitCode(findings) {
-  return findings.some((finding) => finding.code === "projection-ownership-conflict") ? 3 : findings.length > 0 ? 1 : 0;
+  return findings.some((finding) => ["projection-ownership-conflict", "ai-entry-ownership-conflict", "ai-entry-path-conflict"].includes(finding.code)) ? 3 : findings.length > 0 ? 1 : 0;
 }
 
 export function blockingContextFindings(findings) {
@@ -127,6 +145,6 @@ export function blockingContextFindings(findings) {
 }
 
 export function findingSeverity(finding) {
-  if (finding.code === "projection-ownership-conflict") return "conflict";
+  if (["projection-ownership-conflict", "ai-entry-ownership-conflict", "ai-entry-path-conflict"].includes(finding.code)) return "conflict";
   return blockingContextFindings([finding]).length > 0 ? "blocked" : "attention";
 }