frontend-project-context 1.7.0 → 1.9.1

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.7.0";
-export const EXCHANGE_PROTOCOL_VERSION = 7;
+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 = 7;
+export const CAPABILITIES_SCHEMA_VERSION = 9;
 
 export const ACTION_KINDS = Object.freeze([
   "accept-source-change",
@@ -24,7 +24,7 @@ export const ACTION_KINDS = Object.freeze([
 export const COMMANDS = Object.freeze([
   "accept-source-change", "approve", "capabilities", "check", "context", "context-query", "coverage-audit", "dashboard", "deprecate",
   "deprecate-source", "discover", "evidence", "init", "integration-review", "preflight", "propose", "publish", "register",
-  "index-context", "publish-entry", "remove-entry", "review-source", "revise", "setup", "stage-context", "status", "sync",
+  "index-context", "instructions", "publish-entry", "remove-entry", "review-source", "revise", "setup", "stage-context", "status", "sync",
   "upgrade-apply", "upgrade-check", "upgrade-plan",
   "reconcile-truth",
 ]);
@@ -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

@@ -0,0 +1,60 @@
+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 = 2;
+export const INITIALIZATION_INSTRUCTION_ID = "ai-project-initialization";
+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]";
+
+const INSTRUCTION_FILE = fileURLToPath(new URL(`../../${INITIALIZATION_INSTRUCTION_PACKAGE_PATH}`, import.meta.url));
+
+export async function readInitializationInstruction() {
+  const content = await readFile(INSTRUCTION_FILE, "utf8");
+  return {
+    id: INITIALIZATION_INSTRUCTION_ID,
+    version: INITIALIZATION_INSTRUCTION_VERSION,
+    packagePath: INITIALIZATION_INSTRUCTION_PACKAGE_PATH,
+    digest: sha256(content),
+    content,
+  };
+}
+
+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,
+    },
+  };
+}
+
+export function renderInitializationPrompt(result) {
+  return [
+    `<!-- frontend-project-context initialization instruction ${result.instruction.version}; ${result.instruction.digest} -->`,
+    `<!-- resolved-target-root: ${result.targetRoot} -->`,
+    result.instruction.content.trimEnd(),
+    "",
+  ].join("\n");
+}

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,9 +22,9 @@ 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",
+  "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
 ]);
 
 function invalid(message, details) {
@@ -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.7.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,9 +111,9 @@ 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",
+    "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
   ]), "protocols");
   for (const name of Object.keys(manifest.protocols)) versionMatrix(manifest.protocols[name], `protocols.${name}`);
   if (!Array.isArray(manifest.builtInMigrations)) invalid("builtInMigrations must be an array");

package/src/project-context/project-status.mjs

@@ -4,8 +4,9 @@ import { checkExitCode, checkProject } from "./checker.mjs";
 import { ProjectContextError } from "./errors.mjs";
 import { PACKAGE_VERSION } from "./exchange-schema.mjs";
 import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
 
-export const PROJECT_STATUS_SCHEMA_VERSION = 1;
+export const PROJECT_STATUS_SCHEMA_VERSION = 2;
 
 function uniqueSorted(values) {
   return [...new Set(values.filter((value) => value !== undefined && value !== null))]
@@ -46,6 +47,7 @@ function base(initialization, health, nextActions) {
     snapshots: null,
     health,
     entry: { state: "absent", path: null, rendererVersion: null },
+    contractReadiness: initialization === "uninitialized" ? "not-initialized" : "contract-incomplete",
     summary: emptySummary(),
     findingCodes: [],
     sourceIds: [],
@@ -65,7 +67,7 @@ function statusBoundaries(boundaries) {
 export async function buildProjectStatus(root, boundaries) {
   const initialization = await inspectProjectInitialization(root);
   if (initialization.status !== "initialized") {
-    const result = base(initialization.status, initialization.status, initialization.status === "uninitialized" ? ["run-setup-preview"] : ["resolve-conflict"]);
+    const result = base(initialization.status, initialization.status, initialization.status === "uninitialized" ? ["read-initialization-instructions"] : ["resolve-conflict"]);
     result.initialization.present = [...initialization.present];
     result.initialization.missing = [...initialization.missing];
     if (initialization.status === "partial") result.findingCodes = ["project-state-partial"];
@@ -112,7 +114,11 @@ export async function buildProjectStatus(root, boundaries) {
     if (sync.summary.affectedProjections > 0) nextActions.push("review-projection");
     if (entry.state !== "current") nextActions.push("publish-ai-entry");
     if (findings.length > 0 && nextActions.length === 0) nextActions.push("run-sync");
-    if (health === "clean") nextActions.push("ready-for-task");
+    if (health === "clean") {
+      const hasActiveSource = project.contract.sources.some((source) => sourceStatus(source) === "active");
+      const hasApprovedItem = project.contract.items.some((item) => item.status === "approved");
+      nextActions.push(hasActiveSource && hasApprovedItem && entry.state === "current" ? "compile-task-context" : "complete-onboarding");
+    }
   }
   const sourceIds = uniqueSorted([
     ...findings.flatMap((finding) => finding.source ? [finding.source] : []),
@@ -138,6 +144,11 @@ export async function buildProjectStatus(root, boundaries) {
     },
     health,
     entry,
+    contractReadiness: health === "clean" && entry.state === "current" &&
+      project.contract.sources.some((source) => sourceStatus(source) === "active") &&
+      project.contract.items.some((item) => item.status === "approved")
+      ? "contract-ready"
+      : "contract-incomplete",
     summary: {
       findings: findings.length,
       changedSources: sync.summary.changedSources,

package/src/project-context/project-store.mjs

@@ -1,4 +1,4 @@
-import { access, mkdir, rename, rm } from "node:fs/promises";
+import { access, lstat, mkdir, readdir, rename, rm, rmdir } from "node:fs/promises";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { canonicalJson, digestJson } from "./canonical-json.mjs";
@@ -43,8 +43,20 @@ async function exists(filePath) {
   }
 }
 
+async function isEmptyDirectory(filePath) {
+  try {
+    const stats = await lstat(filePath);
+    if (!stats.isDirectory()) return false;
+    return (await readdir(filePath)).length === 0;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 export async function inspectProjectInitialization(root) {
   const files = projectFiles(root);
+  const emptyContainer = await isEmptyDirectory(files.directory);
   const entries = [
     [CONTEXT_DIRECTORY, files.directory],
     [`${CONTEXT_DIRECTORY}/${CONTRACT_FILE}`, files.contract],
@@ -53,6 +65,7 @@ export async function inspectProjectInitialization(root) {
   ];
   const present = [];
   for (const [relative, absolute] of entries) {
+    if (relative === CONTEXT_DIRECTORY && emptyContainer) continue;
     if (await exists(absolute)) present.push(relative);
   }
   const storePaths = entries.slice(1).map(([relative]) => relative);
@@ -71,8 +84,9 @@ export async function initializeProject(root, id, name, write) {
   validateContract(initial.contract);
   validateSourceLock(initial.sourcesLock);
   validateProjectionLock(initial.projectionsLock);
+  const emptyContainer = await isEmptyDirectory(files.directory);
   const existing = [];
-  if (await exists(files.directory)) existing.push(CONTEXT_DIRECTORY);
+  if ((await exists(files.directory)) && !emptyContainer) existing.push(CONTEXT_DIRECTORY);
   for (const filePath of [files.contract, files.sourcesLock, files.projectionsLock]) {
     if (await exists(filePath)) existing.push(path.relative(root, filePath));
   }
@@ -80,6 +94,17 @@ export async function initializeProject(root, id, name, write) {
     fail("project-already-initialized", "project context files already exist", { details: { paths: existing } });
   }
   if (write) {
+    if (emptyContainer) {
+      try {
+        await rmdir(files.directory);
+      } catch (error) {
+        if (error?.code !== "ENOENT") {
+          fail("project-already-initialized", "project context directory changed before initialization", {
+            details: { paths: [CONTEXT_DIRECTORY] },
+          });
+        }
+      }
+    }
     const temporaryDirectory = `${files.directory}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
     try {
       await mkdir(temporaryDirectory, { recursive: false });

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,9 +121,9 @@ 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",
+      "taskContextPlan", "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
     ]),
   };
   for (const [name, group] of Object.entries(value.compatibility)) {