frontend-project-context 1.7.0 → 1.9.1

package/schemas/upgrade-assessment.schema.json

@@ -9,8 +9,8 @@
     "schemaVersion": {"const": 1},
     "kind": {"const": "upgrade-assessment"},
     "product": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"const": "frontend-project-context"}}},
-    "fromVersion": {"enum": ["1.3.1", "1.4.0", "1.5.0", "1.6.0"]},
-    "targetVersion": {"const": "1.7.0"},
+    "fromVersion": {"enum": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]},
+    "targetVersion": {"const": "1.9.1"},
     "fromVersionEvidence": {"const": "host-asserted"},
     "manifestSchemaVersion": {"const": 2},
     "manifestDigest": {"$ref": "#/$defs/digest"},

package/schemas/upgrade-result-bundle.schema.json

@@ -10,7 +10,7 @@
     "kind": {"const": "upgrade-result-bundle"},
     "product": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"const": "frontend-project-context"}}},
     "fromVersion": {"type": "string"},
-    "targetVersion": {"const": "1.7.0"},
+    "targetVersion": {"const": "1.9.1"},
     "manifestDigest": {"$ref": "#/$defs/digest"},
     "planDigest": {"$ref": "#/$defs/digest"},
     "mode": {"enum": ["preview", "write"]},

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

@@ -5,7 +5,7 @@ import { normalizeRelativePath } from "./path-policy.mjs";
 export const CONTEXT_QUERY_SCHEMA_VERSION = 2;
 export const ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION = 2;
 export const ROUTING_INDEX_SCHEMA_VERSION = 2;
-export const COVERAGE_AUDIT_SCHEMA_VERSION = 1;
+export const COVERAGE_AUDIT_SCHEMA_VERSION = 2;
 export const ADAPTIVE_SELECTOR_VERSION = 2;
 export const ROUTING_INDEX_PATH = ".project-context/derived/routing-index.json";
 

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

@@ -3,6 +3,7 @@ import path from "node:path";
 import { canonicalJson, digestJson, prettyCanonicalJson, sha256 } from "./canonical-json.mjs";
 import { blockingContextFindings, checkProject } from "./checker.mjs";
 import { sourceStatus } from "./contract-schema.mjs";
+import { coverageClass, coverageProfile } from "./coverage-profile.mjs";
 import { discoverProject } from "./discovery.mjs";
 import { ProjectContextError, fail } from "./errors.mjs";
 import { atomicWriteFile, readJsonFile } from "./io.mjs";
@@ -26,7 +27,6 @@ import {
 const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
 const MANDATORY_KINDS = new Set(["policy", "validation-description"]);
 const ROUTED_KINDS = new Set(["fact", "reference"]);
-const COVERAGE_SUBJECT = "project.registration-coverage";
 const RETRIEVAL_SUBJECT = "project.context-retrieval";
 const EXCLUDED_BODIES = Object.freeze(["chat-history", "git-diffs", "source-bodies", "task-path-bodies", "verification-logs"]);
 const ROUTING_STOP_TERMS = new Set(["a", "an", "and", "apply", "change", "for", "in", "of", "on", "project", "rule", "the", "to", "update", "use"]);
@@ -145,24 +145,7 @@ export async function indexContext(root, project, options = {}) {
   return index;
 }
 
-function pathWithin(target, parent) { return parent === "." || target === parent || target.startsWith(`${parent}/`); }
-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;
-  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["excludedPaths", "roots"].includes(key)) || !Array.isArray(value.roots) || !Array.isArray(value.excludedPaths)) fail("coverage-profile-invalid", `${item.id} coverage value is invalid`);
-  const normalize = (values, label) => uniqueSorted(values.map((entry) => normalizeRelativePath(entry, { allowRoot: true, label })));
-  return { itemId: item.id, itemDigest: digestJson(item), sourceIds: [...item.sources].sort(), roots: normalize(value.roots, "coverage root"), excludedPaths: normalize(value.excludedPaths, "coverage excluded path") };
-}
-function coverageClass(profile, registeredPaths, candidatePath) {
-  if (registeredPaths.has(candidatePath)) return "registered";
-  if (!profile) return "outside-declared-coverage";
-  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";
-}
+export { coverageClass, coverageProfile } from "./coverage-profile.mjs";
 export async function buildCoverageAudit(root, project, changedPaths = []) {
   const profile = coverageProfile(project.contract);
   const proposal = await discoverProject(root, project.contract);
@@ -175,10 +158,16 @@ export async function buildCoverageAudit(root, project, changedPaths = []) {
     if (!byPath.has(normalized)) byPath.set(normalized, { path: normalized, origin: "host-changed-path-signal" });
   }
   for (const registeredPath of registered) if (!byPath.has(registeredPath)) byPath.set(registeredPath, { path: registeredPath, origin: "registered-source" });
-  const categories = { registered: [], "excluded-approved": [], "review-required": [], "outside-declared-coverage": [] };
+  const categories = { registered: [], "dynamic-investigation": [], "excluded-approved": [], "review-required": [], unresolved: [], "outside-declared-coverage": [] };
   for (const candidate of [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path))) categories[coverageClass(profile, registeredPaths, candidate.path)].push(candidate);
-  const registrationCoverage = !profile ? "not-declared" : categories["review-required"].length === 0 ? "closed-for-declared-scope" : "review-required";
-  return sealArtifact({ schemaVersion: 1, kind: "coverage-audit", project: { id: project.contract.project.id, name: project.contract.project.name }, snapshots: snapshots(project), profile, registrationCoverage, categories, guarantee: "declared-scope-only-never-all-project-truth" }, "auditDigest");
+  const registrationCoverage = !profile
+    ? "not-declared"
+    : categories.unresolved.length > 0
+      ? "unresolved"
+      : categories["review-required"].length === 0
+        ? "closed-for-declared-scope"
+        : "review-required";
+  return sealArtifact({ schemaVersion: 2, kind: "coverage-audit", project: { id: project.contract.project.id, name: project.contract.project.name }, snapshots: snapshots(project), profile, registrationCoverage, categories, guarantee: "declared-scope-only-never-all-project-truth" }, "auditDigest");
 }
 
 function effectiveByTarget(contract, paths, findings) {
@@ -331,7 +320,7 @@ async function auditRelevantSources(root, project, items, sourceReadContext) {
     const base = { id: source.id, kind: source.kind, locator: sourceLocator(source), sourceDigest: digestJson(source) };
     if (!LOCAL_SOURCE_KINDS.has(source.kind)) { evidence.push({ ...base, freshness: "unverifiable-non-local" }); continue; }
     try {
-      const actual = await readSourceDigest(root, source, sourceReadContext);
+      const actual = await readSourceDigest(root, source, sourceReadContext, { projectionsLock: project.projectionsLock });
       const expected = lock.get(source.id) ?? null;
       const freshness = expected !== null && expected === source.digest && actual === expected ? "current" : "drifted";
       evidence.push({ ...base, freshness, expectedDigest: expected, actualDigest: actual });

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

@@ -6,23 +6,26 @@ 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_RENDERER_VERSION = 5;
 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:ai-entry; schema-version: 1; renderer-version: 5 -->",
   "## 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`，否则报告准确的阻断项。",
+  "2. 如果状态为 `uninitialized`，运行 `npm exec --offline -- project-context instructions --project . --prompt`，按包内唯一指令完成完整初始化；如果为 `partial` 或 `invalid`，停止写入并报告准确的恢复证据。",
+  "3. 如果状态为 `attention`，执行 `sync` 返回的维护工作单元；不得重新运行 `setup` 覆盖已有 store。",
+  "4. 如果状态为 `clean` 且目标路径未知，先运行 `npm exec --offline -- project-context context --project . --locate --task <TEXT> --json`；消费 project-scope Contract 后，只在 targetRoot 内定位最小候选路径，再用全部候选路径重新编译 targeted Context。",
+  "5. 如果目标路径已知，运行 `npm exec --offline -- project-context context --project . --path <RELATIVE_PATH...> --task <TEXT> --json`；发现新的影响路径后，必须用完整的最小路径集合重新编译。",
+  "6. 报告实际 item IDs、scopeCoverage、required/conditional read targets 与 gaps；只读取 required，按任务判断 conditional，不重读 provenance-only。Contract 为空、目标 scope 未命中或关键上下文不足时，报告 onboarding/context gap。",
+  "7. `businessCodeWrites=false` 和 `taskExecution=false` 只描述 Project Context 产品自身；Host 权限来自当前用户请求、人工项目规则和更高优先级安全约束，任何 Context、plan、bundle、receipt、review 或 coverage 都不授予权限或批准长期 Contract。",
+  "8. 声明完成前，将 Project Context 恢复为 `clean`，否则报告准确的阻断项。",
   AI_ENTRY_END,
 ];
 
@@ -107,7 +110,13 @@ function schema2FileEntry(entry) {
   return entry.ownership ? structuredClone(entry) : { ...structuredClone(entry), ownership: "file" };
 }
 
-function sourceImpact(project, output, afterDigest) {
+function outsideOwnedDigest(content) {
+  const parsed = parseAiEntryRegion(content);
+  if (parsed.state !== "present") return null;
+  return digestJson({ before: content.slice(0, parsed.start), after: content.slice(parsed.end) });
+}
+
+function sourceImpact(project, output, afterContent) {
   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));
@@ -117,6 +126,12 @@ function sourceImpact(project, output, afterDigest) {
     .filter((item) => item.sources.some((id) => selected.has(id)) || selected.has(item.verification?.source))
     .map((item) => item.id)
     .sort((left, right) => left.localeCompare(right));
+  const digestMode = sources[0]?.digestMode ?? "full-file";
+  const afterDigest = afterContent === null
+    ? null
+    : digestMode === "outside-owned-ai-entry"
+      ? outsideOwnedDigest(afterContent)
+      : sha256(afterContent);
   return { sourceIds, itemIds, afterDigest: sourceIds.length > 0 ? afterDigest : null };
 }
 
@@ -247,7 +262,7 @@ export async function publishAiEntry(root, project, options, dependencies = {})
   };
   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 impact = sourceImpact(project, resolved.normalized, nextContent);
   const result = {
     action,
     current: {
@@ -302,7 +317,7 @@ export async function removeAiEntry(root, project, options, dependencies = {}) {
   }
   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 impact = sourceImpact(project, resolved.normalized, nextContent);
   const result = {
     action: "remove",
     current: { entry: structuredClone(currentEntry), contentDigest: sha256(existing), region: parsed.region },

package/src/project-context/approver.mjs

@@ -1,5 +1,6 @@
 import { canonicalJson } from "./canonical-json.mjs";
 import {
+  promoteContractToSchema3,
   sourceForContract,
   sourceRegistrationShape,
   sourceStatus,
@@ -52,7 +53,7 @@ export async function approveProposal(root, project, proposalInput, options) {
   for (const sourceId of selectedSourceIds) {
     const source = proposalSources.get(sourceId);
     if (!source) fail("proposal-source-missing", `proposal source is missing: ${sourceId}`);
-    const actual = await readSourceDigest(root, source);
+    const actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
     if (actual !== null && actual !== source.digest) {
       fail("proposal-source-changed", `source changed after discovery: ${sourceId}`, {
         exitCode: 1,
@@ -61,6 +62,9 @@ export async function approveProposal(root, project, proposalInput, options) {
     }
   }
   const nextContract = structuredClone(project.contract);
+  if (selected.some((item) => item.consumption !== undefined) || [...selectedSourceIds].some((id) => proposalSources.get(id)?.digestMode !== undefined)) {
+    promoteContractToSchema3(nextContract);
+  }
   for (const sourceId of selectedSourceIds) {
     const source = proposalSources.get(sourceId);
     const existing = nextContract.sources.find((entry) => entry.id === sourceId);
@@ -141,7 +145,7 @@ export async function approvePendingItems(root, project, options) {
     }
     let actual;
     try {
-      actual = await readSourceDigest(root, source);
+      actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
     } catch (error) {
       fail("pending-source-changed", `pending item source is unavailable: ${sourceId}`, {
         exitCode: 1,

package/src/project-context/authoring.mjs

@@ -1,5 +1,6 @@
 import { canonicalJson } from "./canonical-json.mjs";
 import {
+  promoteContractToSchema3,
   sourceForContract,
   sourceRegistrationShape,
   sourceStatus,
@@ -32,8 +33,8 @@ function sourceLocator(source) {
   });
 }
 
-export async function buildRegisteredSource(root, input) {
-  const { id, kind, path: sourcePath, pointer, reference } = input;
+export async function buildRegisteredSource(root, input, options = {}) {
+  const { id, kind, path: sourcePath, pointer, reference, digestMode } = input;
   let source;
   if (LOCAL_SOURCE_KINDS.has(kind)) {
     if (!has(sourcePath) || has(reference) || (kind === "json-pointer" ? !has(pointer) : has(pointer))) {
@@ -44,21 +45,23 @@ export async function buildRegisteredSource(root, input) {
       kind,
       path: normalizeRelativePath(sourcePath, { label: "source path" }),
       ...(kind === "json-pointer" ? { pointer } : {}),
+      ...(digestMode !== undefined ? { digestMode } : {}),
     };
-    source.digest = await readSourceDigest(root, source);
+    if (digestMode !== undefined && kind !== "file") fail("argument-conflict", "--digest-mode is only valid for file sources");
+    source.digest = await readSourceDigest(root, source, undefined, { projectionsLock: options.projectionsLock });
   } else if (REFERENCE_SOURCE_KINDS.has(kind)) {
-    if (!has(reference) || has(sourcePath) || has(pointer)) {
+    if (!has(reference) || has(sourcePath) || has(pointer) || has(digestMode)) {
       fail("argument-conflict", `${kind} source requires only --reference`, { details: { source: id } });
     }
     source = { id, kind, reference };
   } else {
     fail("schema-invalid-enum", `source kind is invalid: ${kind}`, { details: { source: id } });
   }
-  return validateSource(source);
+  return validateSource(source, "source", { contractSchemaVersion: digestMode === undefined ? 1 : 3, proposal: true });
 }
 
 export async function registerSource(root, project, input, options = {}) {
-  const source = await buildRegisteredSource(root, input);
+  const source = await buildRegisteredSource(root, input, { projectionsLock: project.projectionsLock });
   const existingById = project.contract.sources.find((entry) => entry.id === source.id);
   if (existingById) {
     if (sourceStatus(existingById) === "deprecated" || canonicalJson(sourceRegistrationShape(existingById)) !== canonicalJson(source)) {
@@ -77,6 +80,7 @@ export async function registerSource(root, project, input, options = {}) {
   }
 
   const nextContract = structuredClone(project.contract);
+  if (source.digestMode !== undefined) promoteContractToSchema3(nextContract);
   const storedSource = sourceForContract(source, nextContract.schemaVersion);
   nextContract.sources.push(storedSource);
   nextContract.sources.sort((left, right) => left.id.localeCompare(right.id));
@@ -91,7 +95,7 @@ export async function registerSource(root, project, input, options = {}) {
 
   if (options.write) {
     if (LOCAL_SOURCE_KINDS.has(source.kind)) {
-      const actual = await readSourceDigest(root, source);
+      const actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
       if (actual !== source.digest) {
         fail("source-changed-during-register", `source changed while registration was being prepared: ${source.id}`, {
           exitCode: 1,
@@ -157,6 +161,21 @@ export function buildItemProposal(project, input) {
       details: { item: input.id, source: verification.source },
     });
   }
+  const requiredSources = input.requiredSources ?? [];
+  const conditionalSources = input.conditionalSources ?? [];
+  if (new Set(requiredSources).size !== requiredSources.length) fail("schema-duplicate", "--required-source contains duplicate IDs");
+  if (new Set(conditionalSources).size !== conditionalSources.length) fail("schema-duplicate", "--conditional-source contains duplicate IDs");
+  const roleSources = [...requiredSources, ...conditionalSources];
+  const overlap = requiredSources.find((source) => conditionalSources.includes(source));
+  if (overlap) fail("argument-conflict", `source cannot be both required and conditional: ${overlap}`);
+  for (const sourceId of roleSources) {
+    if (!sourceIds.includes(sourceId)) fail("source-reference-missing", `consumption source must be included in --sources: ${sourceId}`);
+    if (!LOCAL_SOURCE_KINDS.has(sourceMap.get(sourceId)?.kind)) fail("argument-conflict", `consumption source must be local: ${sourceId}`);
+  }
+  const consumption = roleSources.length > 0 ? {
+    requiredSources: [...requiredSources].sort((left, right) => left.localeCompare(right)),
+    conditionalSources: [...conditionalSources].sort((left, right) => left.localeCompare(right)),
+  } : undefined;
   const item = {
     id: input.id,
     kind: input.kind,
@@ -167,9 +186,10 @@ export function buildItemProposal(project, input) {
     status: "proposed",
     sources: sourceIds,
     overrides: input.overrides ?? [],
+    ...(consumption ? { consumption } : {}),
     ...(verification ? { verification } : {}),
   };
-  validateItem(item, "proposal item", { proposal: true });
+  validateItem(item, "proposal item", { proposal: true, contractSchemaVersion: 3 });
 
   if (item.overrides.length > 0) {
     const hypothetical = { ...structuredClone(item), status: "approved", approval: { by: "proposal-preflight", at: "1970-01-01T00:00:00.000Z" } };

package/src/project-context/capabilities.mjs

@@ -13,6 +13,7 @@ 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 { CONTEXT_BUNDLE_SCHEMA_VERSION } from "./context-bundle.mjs";
 import { EVIDENCE_BUNDLE_SCHEMA_VERSION, EVIDENCE_INPUT_SCHEMA_VERSION } from "./evidence-schema.mjs";
 import {
   CONTEXT_BUDGET_UNIT,
@@ -37,6 +38,11 @@ import {
   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 {
@@ -44,13 +50,16 @@ function schemas(projectionLockWritten = 1) {
     adaptiveContextBundle: ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION,
     assistBundle: ASSIST_BUNDLE_SCHEMA_VERSION,
     capabilities: CAPABILITIES_SCHEMA_VERSION,
-    contract: 2,
+    contract: 3,
+    contractReadable: [1, 2, 3],
+    contextBundle: CONTEXT_BUNDLE_SCHEMA_VERSION,
     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],
@@ -96,6 +105,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") {
@@ -111,6 +121,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

@@ -26,7 +26,7 @@ export async function checkProject(root, project, options = {}) {
       continue;
     }
     try {
-      const actual = await readSourceDigest(root, source, sourceReadContext);
+      const actual = await readSourceDigest(root, source, sourceReadContext, { projectionsLock: project.projectionsLock });
       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"

package/src/project-context/cli.mjs

@@ -5,6 +5,7 @@ import { buildItemProposal, registerSource } from "./authoring.mjs";
 import { blockingContextFindings, checkExitCode, checkProject } from "./checker.mjs";
 import { digestJson, prettyCanonicalJson } from "./canonical-json.mjs";
 import { validateProposal } from "./contract-schema.mjs";
+import { buildContextBundle } from "./context-bundle.mjs";
 import { buildDashboardModel } from "./dashboard-model.mjs";
 import { renderDashboardHtml } from "./dashboard-renderer.mjs";
 import { discoverProject } from "./discovery.mjs";
@@ -20,32 +21,33 @@ import { initializeProject, inspectProjectInitialization, loadProject } from "./
 import { publishProjection } from "./projection-store.mjs";
 import { publishAiEntry, removeAiEntry } from "./ai-entry.mjs";
 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]
   project-context upgrade-plan --project PATH --assessment FILE [--json]
   project-context upgrade-apply --project PATH --plan FILE [--write] [--json]
   project-context setup --project PATH --id ID --name NAME [--output FILE] [--write] [--json]
-  project-context register --project PATH --id SOURCE_ID --kind KIND [--path PATH] [--pointer POINTER] [--reference TEXT] [--write] [--json]
-  project-context propose --project PATH --id ITEM_ID --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--output FILE --write] [--json]
+  project-context register --project PATH --id SOURCE_ID --kind KIND [--path PATH] [--pointer POINTER] [--reference TEXT] [--digest-mode full-file|outside-owned-ai-entry] [--write] [--json]
+  project-context propose --project PATH --id ITEM_ID --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--required-source SOURCE_ID...] [--conditional-source SOURCE_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--output FILE --write] [--json]
   project-context review-source --project PATH --id SOURCE_ID [--json]
   project-context accept-source-change --project PATH --id SOURCE_ID --expected-digest SHA256 [--affected-items ITEM_ID...] [--write] [--json]
-  project-context revise --project PATH --id ITEM_ID [--expected-item-digest SHA256] --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--write] [--json]
+  project-context revise --project PATH --id ITEM_ID [--expected-item-digest SHA256] --kind KIND --subject SUBJECT (--value TEXT | --value-json JSON) --statement TEXT --sources SOURCE_ID... --scope SCOPE [--scope-path PATH] [--overrides ITEM_ID...] [--required-source SOURCE_ID...] [--conditional-source SOURCE_ID...] [--verification KIND] [--verification-source SOURCE_ID] [--verification-expected-json JSON] [--write] [--json]
   project-context deprecate --project PATH --id ITEM_ID [--expected-item-digest SHA256] --by NAME --rationale TEXT [--write] [--json]
   project-context deprecate-source --project PATH --id SOURCE_ID [--expected-source-digest SHA256] --by NAME --rationale TEXT [--write] [--json]
   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 --project PATH (--locate --task TEXT | --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]
@@ -65,26 +67,27 @@ All commands are read-only unless their own --write flag is present.
 const VALUE_FLAGS = new Set([
   "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",
+  "verification", "verification-source", "verification-expected-json", "digest-mode",
   "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage", "from-version", "assessment", "previous", "previous-review",
 ]);
 const LIST_FLAGS = new Set([
-  "ids", "path", "input", "changed-path", "sources", "overrides", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
+  "ids", "path", "input", "changed-path", "sources", "overrides", "required-source", "conditional-source", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
 ]);
-const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending", "prompt"]);
+const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending", "prompt", "locate"]);
 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"])],
   ["upgrade-plan", new Set(["project", "assessment", "json", "help"])],
   ["upgrade-apply", new Set(["project", "plan", "write", "json", "help"])],
   ["setup", new Set(["project", "id", "name", "output", "write", "json", "help"])],
-  ["register", new Set(["project", "id", "kind", "path", "pointer", "reference", "write", "json", "help"])],
+  ["register", new Set(["project", "id", "kind", "path", "pointer", "reference", "digest-mode", "write", "json", "help"])],
   ["propose", new Set([
     "project", "id", "kind", "subject", "value", "value-json", "statement", "sources", "scope", "scope-path",
-    "overrides", "verification", "verification-source", "verification-expected-json", "output", "write", "json", "help",
+    "overrides", "required-source", "conditional-source", "verification", "verification-source", "verification-expected-json", "output", "write", "json", "help",
   ])],
   ["review-source", new Set(["project", "id", "json", "help"])],
   ["accept-source-change", new Set([
@@ -92,7 +95,7 @@ const COMMAND_OPTIONS = new Map([
   ])],
   ["revise", new Set([
     "project", "id", "expected-item-digest", "kind", "subject", "value", "value-json", "statement", "sources",
-    "scope", "scope-path", "overrides", "verification", "verification-source", "verification-expected-json",
+    "scope", "scope-path", "overrides", "required-source", "conditional-source", "verification", "verification-source", "verification-expected-json",
     "write", "json", "help",
   ])],
   ["deprecate", new Set([
@@ -103,7 +106,7 @@ 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", new Set(["project", "path", "locate", "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"])],
@@ -230,6 +233,8 @@ function itemInput(options) {
     scope: required(options, "scope"),
     scopePath: options["scope-path"],
     overrides: options.overrides ?? [],
+    requiredSources: options["required-source"] ?? [],
+    conditionalSources: options["conditional-source"] ?? [],
     verification: options.verification,
     verificationSource: options["verification-source"],
     verificationExpectedPresent: hasExpected,
@@ -342,6 +347,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 = [
@@ -434,7 +451,7 @@ async function runCommand(command, options) {
   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: "" };
+    return { exitCode: ["review-required", "unresolved"].includes(audit.registrationCoverage) ? 1 : 0, stdout: jsonOrText(options, audit, summary), stderr: "" };
   }
   if (command === "index-context") {
     const index = await indexContextFiles(root, { write: options.write });
@@ -464,6 +481,7 @@ async function runCommand(command, options) {
       path: optionalOneListValue(options, "path"),
       pointer: options.pointer,
       reference: options.reference,
+      digestMode: options["digest-mode"],
     }, { write: options.write });
     const summary = result.action === "unchanged"
       ? `Source unchanged: ${result.source.id}.\n`
@@ -622,9 +640,19 @@ async function runCommand(command, options) {
   if (command === "context") {
     const findings = blockingContextFindings(await checkProject(root, project));
     if (findings.length > 0) fail("context-blocked", "context generation is blocked by contract or source findings", { exitCode: 1, details: { findings } });
-    const paths = required(options, "path");
-    const content = renderContextBundle(project.contract, paths, options.task, { locale: contextLocale(options) });
-    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson({ content }) : content, stderr: "" };
+    const hasLocate = options.locate === true;
+    const hasPaths = options.path !== undefined;
+    if (hasLocate === hasPaths) fail("argument-conflict", "context requires exactly one of --locate or --path");
+    if (hasLocate && (typeof options.task !== "string" || options.task.trim().length === 0)) {
+      fail("argument-missing", "--locate requires a non-empty --task");
+    }
+    const bundle = await buildContextBundle(root, project, {
+      mode: hasLocate ? "locate" : "targeted",
+      paths: options.path ?? [],
+      task: options.task,
+      locale: contextLocale(options),
+    });
+    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson(bundle) : bundle.content, stderr: "" };
   }
   if (command === "publish") {
     const findings = blockingContextFindings(await checkProject(root, project));