frontend-project-context 1.6.0 → 1.8.0

package/src/project-context/capabilities.mjs

@@ -26,17 +26,38 @@ import {
   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";
+import {
+  INITIALIZATION_INSTRUCTION_COMMAND,
+  INITIALIZATION_INSTRUCTION_SCHEMA_VERSION,
+  readInitializationInstruction,
+} from "./initialization-instruction.mjs";
 
 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,
+    initializationInstruction: INITIALIZATION_INSTRUCTION_SCHEMA_VERSION,
+    hostPromotionEvidence: HOST_PROMOTION_EVIDENCE_SCHEMA_VERSION,
     projectionLock: 2,
     projectionLockReadable: [1, 2],
     projectionLockWritten,
@@ -47,10 +68,13 @@ function schemas(projectionLockWritten = 1) {
     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,
   };
@@ -78,6 +102,7 @@ export const PERMANENT_BOUNDARIES = Object.freeze({
 
 export async function buildCapabilities(root) {
   const initialization = await inspectProjectInitialization(root);
+  const instruction = await readInitializationInstruction();
   let project = null;
   let projectionLockWritten = 1;
   if (initialization.status === "initialized") {
@@ -93,6 +118,13 @@ export async function buildCapabilities(root) {
     commands: [...COMMANDS],
     actionKinds: [...ACTION_KINDS],
     contextBudget: { unit: CONTEXT_BUDGET_UNIT, modelTokens: false, callerMustProvideLimit: true },
+    initializationInstruction: {
+      id: instruction.id,
+      version: instruction.version,
+      packagePath: instruction.packagePath,
+      digest: instruction.digest,
+      command: INITIALIZATION_INSTRUCTION_COMMAND,
+    },
     initialization: initialization.status,
     initialized: initialization.status === "initialized",
     project,

package/src/project-context/checker.mjs

@@ -8,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]));
@@ -25,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"
@@ -51,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({

package/src/project-context/cli.mjs

@@ -1,4 +1,5 @@
 import { buildSetupAssistBundle, buildSyncAssistBundle } from "./assist.mjs";
+import { buildAdaptiveContextBundleFiles, buildAdaptiveContextDeliveryFiles, buildCoverageAuditFiles, indexContextFiles } from "./adaptive-context.mjs";
 import { approvePendingItems, approveProposal } from "./approver.mjs";
 import { buildItemProposal, registerSource } from "./authoring.mjs";
 import { blockingContextFindings, checkExitCode, checkProject } from "./checker.mjs";
@@ -22,12 +23,15 @@ import { buildProjectStatus } from "./project-status.mjs";
 import { renderContextBundle } from "./renderer.mjs";
 import { buildIntegrationReviewBundleFiles, buildStageContextBundleFiles } from "./task-context.mjs";
 import { applyMigrationPlanFile, buildMigrationPlanFile, buildUpgradeAssessment } from "./upgrade.mjs";
+import { buildTruthReconciliationReviewFiles } from "./truth-reconciliation.mjs";
+import { buildInitializationInstruction, renderInitializationPrompt } from "./initialization-instruction.mjs";
 
 const HELP = `project-context — model-neutral project contract compiler
 
 Usage:
   project-context init --project PATH --id ID --name NAME [--write] [--json]
   project-context capabilities --project PATH [--json]
+  project-context instructions --project PATH [--json | --prompt]
   project-context status --project PATH [--json]
   project-context evidence --project PATH --input FILE [--json]
   project-context upgrade-check --project PATH --from-version VERSION [--json]
@@ -44,6 +48,9 @@ Usage:
   project-context discover --project PATH [--output FILE --write] [--json]
   project-context approve --project PATH (--proposal FILE | --pending) --ids ID... --by NAME [--rationale TEXT] [--write] [--json | --full-json]
   project-context context --project PATH --path RELATIVE_PATH... [--task TEXT] [--locale zh-CN|en|all] [--json]
+  project-context context-query --project PATH --input FILE [--previous FILE] [--json | --prompt]
+  project-context coverage-audit --project PATH [--changed-path RELATIVE_PATH...] [--json]
+  project-context index-context --project PATH [--write] [--json]
   project-context publish --project PATH --target agents|ruler --output FILE [--path RELATIVE_PATH...] [--write] [--json]
   project-context publish-entry --project PATH --output AGENTS.md [--write] [--json]
   project-context remove-entry --project PATH --output AGENTS.md [--write] [--json]
@@ -53,22 +60,24 @@ Usage:
   project-context preflight --project PATH --plan FILE [--json]
   project-context stage-context --project PATH --plan FILE --stage STAGE_ID [--receipt FILE...] [--receipt-bundle FILE...] [--changed-path RELATIVE_PATH...] [--json]
   project-context integration-review --project PATH --plan FILE [--receipt FILE...] [--receipt-bundle FILE...] [--main-changed-path RELATIVE_PATH...] [--branch-changed-path RELATIVE_PATH...] [--json]
+  project-context reconcile-truth --project PATH --input FILE... [--previous-review FILE] [--json]
 
 All commands are read-only unless their own --write flag is present.
 `;
 const VALUE_FLAGS = new Set([
-  "project", "id", "name", "input", "output", "proposal", "by", "task", "target", "rationale",
+  "project", "id", "name", "output", "proposal", "by", "task", "target", "rationale",
   "kind", "pointer", "reference", "subject", "value", "value-json", "statement", "scope", "scope-path",
   "verification", "verification-source", "verification-expected-json",
-  "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage", "from-version", "assessment",
+  "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage", "from-version", "assessment", "previous", "previous-review",
 ]);
 const LIST_FLAGS = new Set([
-  "ids", "path", "changed-path", "sources", "overrides", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
+  "ids", "path", "input", "changed-path", "sources", "overrides", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
 ]);
-const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending"]);
+const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending", "prompt"]);
 const COMMAND_OPTIONS = new Map([
   ["init", new Set(["project", "id", "name", "write", "json", "help"])],
   ["capabilities", new Set(["project", "json", "help"])],
+  ["instructions", new Set(["project", "json", "prompt", "help"])],
   ["status", new Set(["project", "json", "help"])],
   ["evidence", new Set(["project", "input", "json", "help"])],
   ["upgrade-check", new Set(["project", "from-version", "json", "help"])],
@@ -98,6 +107,9 @@ const COMMAND_OPTIONS = new Map([
   ["discover", new Set(["project", "output", "write", "json", "help"])],
   ["approve", new Set(["project", "proposal", "pending", "ids", "by", "rationale", "write", "json", "full-json", "help"])],
   ["context", new Set(["project", "path", "task", "locale", "json", "help"])],
+  ["context-query", new Set(["project", "input", "previous", "json", "prompt", "help"])],
+  ["coverage-audit", new Set(["project", "changed-path", "json", "help"])],
+  ["index-context", new Set(["project", "write", "json", "help"])],
   ["publish", new Set(["project", "target", "output", "path", "write", "json", "help"])],
   ["publish-entry", new Set(["project", "output", "write", "json", "help"])],
   ["remove-entry", new Set(["project", "output", "write", "json", "help"])],
@@ -107,6 +119,7 @@ const COMMAND_OPTIONS = new Map([
   ["preflight", new Set(["project", "plan", "json", "help"])],
   ["stage-context", new Set(["project", "plan", "stage", "receipt", "receipt-bundle", "changed-path", "json", "help"])],
   ["integration-review", new Set(["project", "plan", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path", "json", "help"])],
+  ["reconcile-truth", new Set(["project", "input", "previous-review", "json", "help"])],
 ]);
 
 export function parseArgs(argv) {
@@ -332,6 +345,18 @@ async function runCommand(command, options) {
   if (!COMMAND_OPTIONS.has(command)) fail("command-unknown", `unknown command: ${command}`);
   rejectUnsupportedOptions(command, options, COMMAND_OPTIONS.get(command));
   const root = await resolveProjectRoot(required(options, "project"));
+  if (command === "instructions") {
+    if (options.json && options.prompt) fail("argument-conflict", "instructions accepts only one of --json or --prompt");
+    const instruction = await buildInitializationInstruction(root, PERMANENT_BOUNDARIES);
+    if (options.prompt) return { exitCode: 0, stdout: renderInitializationPrompt(instruction), stderr: "" };
+    const summary = [
+      `Initialization instruction ${instruction.instruction.id} v${instruction.instruction.version}.`,
+      `Package: ${instruction.package.name}@${instruction.package.version}.`,
+      `Target root: ${instruction.targetRoot}.`,
+      `Instruction: ${instruction.instruction.packagePath}; ${instruction.instruction.digest}.`,
+    ].join("\n") + "\n";
+    return { exitCode: 0, stdout: jsonOrText(options, instruction, summary), stderr: "" };
+  }
   if (command === "capabilities") {
     const capabilities = await buildCapabilities(root);
     const summary = [
@@ -348,7 +373,7 @@ async function runCommand(command, options) {
     return { exitCode: result.exitCode, stdout: jsonOrText(options, result.status, summary), stderr: "" };
   }
   if (command === "evidence") {
-    const bundle = await buildEvidenceBundleFile(root, required(options, "input"));
+    const bundle = await buildEvidenceBundleFile(root, oneListValue(options, "input"));
     const summary = [
       `Evidence ${bundle.result}; project health ${bundle.projectContext.health}.`,
       `Finding codes: ${bundle.projectContext.findingCodes.join(", ") || "none"}.`,
@@ -411,6 +436,26 @@ async function runCommand(command, options) {
     const summary = `Stage context ${bundle.status}: ${bundle.stage.id}; ${bundle.contractItems.length} contract item(s), ${bundle.readTargets.length} read target(s), ${bundle.budget.usedUtf8Bytes}/${bundle.budget.maxUtf8Bytes} UTF-8 bytes.\n`;
     return { exitCode: bundle.status === "ready" ? 0 : 1, stdout: jsonOrText(options, bundle, summary), stderr: "" };
   }
+  if (command === "context-query") {
+    if (options.json && options.prompt) fail("argument-conflict", "context-query accepts only one of --json or --prompt");
+    if (options.prompt) {
+      const result = await buildAdaptiveContextDeliveryFiles(root, oneListValue(options, "input"), { previousPath: options.previous });
+      return { exitCode: result.bundle.taskHealth === "ready" ? 0 : 1, stdout: result.content, stderr: "" };
+    }
+    const bundle = await buildAdaptiveContextBundleFiles(root, oneListValue(options, "input"), { previousPath: options.previous });
+    const summary = `Adaptive context ${bundle.taskHealth}: ${bundle.hydratedItems.length} hydrated, ${bundle.retainedItemIds.length} retained, ${bundle.deferredItems.length} deferred item(s); audit ${bundle.budget.audit.usedUtf8Bytes}/${bundle.budget.audit.maxUtf8Bytes}, delivery ${bundle.budget.delivery.usedUtf8Bytes}/${bundle.budget.delivery.maxUtf8Bytes} UTF-8 bytes.\n`;
+    return { exitCode: bundle.taskHealth === "ready" ? 0 : 1, stdout: jsonOrText(options, bundle, summary), stderr: "" };
+  }
+  if (command === "coverage-audit") {
+    const audit = await buildCoverageAuditFiles(root, options["changed-path"] ?? []);
+    const summary = `Registration coverage ${audit.registrationCoverage}: ${audit.categories["review-required"].length} review-required candidate(s).\n`;
+    return { exitCode: audit.registrationCoverage === "review-required" ? 1 : 0, stdout: jsonOrText(options, audit, summary), stderr: "" };
+  }
+  if (command === "index-context") {
+    const index = await indexContextFiles(root, { write: options.write });
+    const summary = `Routing index ${options.write ? "written" : "preview"}: ${index.items.length} item(s), ${index.sources.length} source(s); ${index.indexDigest}.\n`;
+    return { exitCode: 0, stdout: jsonOrText(options, index, summary), stderr: "" };
+  }
   if (command === "integration-review") {
     const bundle = await buildIntegrationReviewBundleFiles(root, required(options, "plan"), {
       receiptPaths: options.receipt ?? [],
@@ -421,6 +466,11 @@ async function runCommand(command, options) {
     const summary = `Integration review ${bundle.status}: ${bundle.findings.length} finding(s), ${bundle.contractOverlapItemIds.length} contract overlap(s), ${bundle.decisionCandidates.length} decision candidate(s).\n`;
     return { exitCode: bundle.status === "reviewable" ? 0 : 1, stdout: jsonOrText(options, bundle, summary), stderr: "" };
   }
+  if (command === "reconcile-truth") {
+    const bundle = await buildTruthReconciliationReviewFiles(root, required(options, "input"), { previousReviewPath: options["previous-review"] });
+    const summary = `Truth reconciliation ${bundle.summary.taskHealth}: ${bundle.summary.collisionGroups} collision group(s), ${bundle.summary.findings} finding(s); existing delivery ${bundle.summary.existingDelivery}.\n`;
+    return { exitCode: bundle.summary.taskHealth === "ready" ? 0 : 1, stdout: jsonOrText(options, bundle, summary), stderr: "" };
+  }
   const project = await loadProject(root);
   if (command === "register") {
     const result = await registerSource(root, project, {

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

@@ -308,7 +308,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 (entry.rendererVersion !== 1) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1");
+      if (![1, 2, 3, 4].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, 3, or 4");
       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/discovery.mjs

@@ -145,7 +145,7 @@ export async function discoverProject(root, contract) {
           id: "fact-package-manager",
           subject: "project.package-manager",
           value: packageJson.packageManager,
-          statement: `The project declares package manager ${packageJson.packageManager}.`,
+          statement: `项目声明使用包管理器 ${packageJson.packageManager}。`,
           source,
         }));
       }
@@ -155,7 +155,7 @@ export async function discoverProject(root, contract) {
           id: `fact-${scriptId}`,
           subject: `project.${scriptId.replaceAll("-", ".")}`,
           value: packageJson.scripts[name],
-          statement: `The project declares the ${name} script.`,
+          statement: `项目声明了 ${name} 脚本。`,
           source,
         }));
       }
@@ -167,7 +167,7 @@ export async function discoverProject(root, contract) {
           id: `fact-${dependencyId}`,
           subject: `project.${dependencyId.replaceAll("-", ".")}`,
           value: dependencies[name],
-          statement: `The project declares ${name} as a dependency.`,
+          statement: `项目声明 ${name} 为依赖。`,
           source,
         }));
       }
@@ -181,7 +181,7 @@ export async function discoverProject(root, contract) {
       id: `fact-${configId}`,
       subject: `project.${configId.replaceAll("-", ".")}`,
       value: true,
-      statement: `The project contains ${relative}.`,
+      statement: `项目包含 ${relative}。`,
       source,
     }));
   }
@@ -191,7 +191,7 @@ export async function discoverProject(root, contract) {
       id: `fact-${generatedId("top-level-directory", relative)}`,
       subject: "project.structure.top-level-directory",
       value: relative,
-      statement: `The project contains the top-level directory ${relative}.`,
+      statement: `项目包含顶层目录 ${relative}。`,
       source,
       scope: { kind: "path-prefix", path: relative },
     }));
@@ -221,7 +221,7 @@ export async function discoverProject(root, contract) {
       kind: "reference",
       subject: `agent-rules.${slug(relative)}`,
       value: relative,
-      statement: `Review the existing Agent instruction source at ${relative}.`,
+      statement: `阅读现有 AI Agent 指令源 ${relative}。`,
       source,
       scope: relative.includes("/") && !relative.startsWith(".")
         ? { kind: "path-prefix", path: path.posix.dirname(relative) }
@@ -243,7 +243,7 @@ export async function discoverProject(root, contract) {
         kind: "reference",
         subject: `registered-source.${source.id.replaceAll("-", ".")}`,
         value: source.path ?? source.reference,
-        statement: `Review the explicitly registered project source ${source.id}.`,
+        statement: `阅读显式登记的项目源 ${source.id}。`,
         source: source.id,
       }));
     } catch {

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.6.0";
-export const EXCHANGE_PROTOCOL_VERSION = 4;
+export const PACKAGE_VERSION = "1.8.0";
+export const EXCHANGE_PROTOCOL_VERSION = 8;
 export const ACTION_PLAN_SCHEMA_VERSION = 2;
 export const REVIEW_BUNDLE_SCHEMA_VERSION = 2;
-export const CAPABILITIES_SCHEMA_VERSION = 4;
+export const CAPABILITIES_SCHEMA_VERSION = 8;
 
 export const ACTION_KINDS = Object.freeze([
   "accept-source-change",
@@ -22,10 +22,11 @@ export const ACTION_KINDS = Object.freeze([
 ]);
 
 export const COMMANDS = Object.freeze([
-  "accept-source-change", "approve", "capabilities", "check", "context", "dashboard", "deprecate",
+  "accept-source-change", "approve", "capabilities", "check", "context", "context-query", "coverage-audit", "dashboard", "deprecate",
   "deprecate-source", "discover", "evidence", "init", "integration-review", "preflight", "propose", "publish", "register",
-  "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",
 ]);
 
 const ACTION_KIND_SET = new Set(ACTION_KINDS);

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

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { sha256 } from "./canonical-json.mjs";
+import { PACKAGE_VERSION } from "./exchange-schema.mjs";
+
+export const INITIALIZATION_INSTRUCTION_SCHEMA_VERSION = 1;
+export const INITIALIZATION_INSTRUCTION_ID = "ai-project-initialization";
+export const INITIALIZATION_INSTRUCTION_VERSION = 1;
+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) {
+  return {
+    schemaVersion: INITIALIZATION_INSTRUCTION_SCHEMA_VERSION,
+    package: { name: "frontend-project-context", version: PACKAGE_VERSION },
+    instruction: await readInitializationInstruction(),
+    targetRoot,
+    boundaries: { ...boundaries },
+  };
+}
+
+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

@@ -79,7 +79,7 @@ export function sourceImpact(project, sourceId) {
   return { ...relations, directProjectionPaths, staleProjectionPaths };
 }
 
-export async function reviewSource(root, project, sourceId) {
+export async function reviewSource(root, project, sourceId, options = {}) {
   const source = project.contract.sources.find((entry) => entry.id === sourceId);
   if (!source) fail("source-not-found", `source is not registered: ${sourceId}`, { details: { source: sourceId } });
   const sourceObjectDigest = digestJson(source);
@@ -104,7 +104,7 @@ export async function reviewSource(root, project, sourceId) {
   let status;
   let reason;
   try {
-    currentDigest = await readSourceDigest(root, source);
+    currentDigest = await readSourceDigest(root, source, options.sourceReadContext);
     if (lockedDigest === null || lockedDigest !== source.digest) {
       status = "unreadable";
       reason = lockedDigest === null ? "source-lock-missing" : "source-lock-mismatch";

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

@@ -22,8 +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", "capabilities", "evidenceBundle", "evidenceInput", "exchange",
-  "integrationReviewBundle", "reviewBundle", "stageContextBundle", "stageReceipt", "taskContextPlan",
+  "actionPlan", "adaptiveContextBundle", "capabilities", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
+  "hostPromotionEvidence", "integrationReviewBundle", "reviewBundle", "routingIndex", "stageContextBundle", "stageReceipt", "taskContextPlan",
+  "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
 ]);
 
 function invalid(message, details) {
@@ -102,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.6.0") invalid("migration manifest package does not match this runtime");
+  if (manifest.package.name !== "frontend-project-context" || manifest.package.version !== "1.8.0") 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");
@@ -110,8 +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", "reviewBundle", "evidenceInput", "evidenceBundle", "taskContextPlan",
-    "stageReceipt", "stageContextBundle", "integrationReviewBundle",
+    "exchange", "actionPlan", "adaptiveContextBundle", "contextQuery", "coverageAudit", "reviewBundle", "evidenceInput", "evidenceBundle", "taskContextPlan",
+    "routingIndex", "stageReceipt", "stageContextBundle", "integrationReviewBundle", "hostPromotionEvidence",
+    "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 });