frontend-project-context 1.3.1 → 1.7.0

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";
@@ -8,21 +9,32 @@ import { buildDashboardModel } from "./dashboard-model.mjs";
 import { renderDashboardHtml } from "./dashboard-renderer.mjs";
 import { discoverProject } from "./discovery.mjs";
 import { ProjectContextError, fail } from "./errors.mjs";
+import { buildEvidenceBundleFile } from "./evidence.mjs";
 import { buildCapabilities, preflightActionPlanFile } from "./exchange.mjs";
+import { PERMANENT_BOUNDARIES } from "./capabilities.mjs";
 import { normalizeProposalPath } from "./exchange-schema.mjs";
 import { atomicCreateFileOrSame, atomicWriteFile, readJsonFile } from "./io.mjs";
 import { acceptSourceChange, deprecateItem, deprecateSource, reviewSource, reviseItem } from "./maintenance.mjs";
 import { normalizeRelativePath, resolveExistingInside, resolveProjectRoot, resolveWritableInside } from "./path-policy.mjs";
 import { initializeProject, inspectProjectInitialization, loadProject } from "./project-store.mjs";
 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";
 
 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 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]
@@ -34,13 +46,19 @@ 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]
   project-context check --project PATH [--json]
   project-context dashboard --project PATH [--json]
   project-context sync --project PATH [--changed-path RELATIVE_PATH...] [--json]
   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.
 `;
@@ -48,15 +66,20 @@ 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",
-  "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage",
+  "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"])],
+  ["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"])],
   ["propose", new Set([
@@ -81,13 +104,19 @@ 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"])],
   ["check", new Set(["project", "json", "help"])],
   ["dashboard", new Set(["project", "json", "help"])],
   ["sync", new Set(["project", "changed-path", "json", "help"])],
   ["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) {
@@ -323,6 +352,51 @@ async function runCommand(command, options) {
     ].join("\n") + "\n";
     return { exitCode: 0, stdout: jsonOrText(options, capabilities, summary), stderr: "" };
   }
+  if (command === "status") {
+    const result = await buildProjectStatus(root, PERMANENT_BOUNDARIES);
+    const summary = `Project Context: ${result.status.initialization.state}; health ${result.status.health}; AI Entry ${result.status.entry.state}.\n`;
+    return { exitCode: result.exitCode, stdout: jsonOrText(options, result.status, summary), stderr: "" };
+  }
+  if (command === "evidence") {
+    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"}.`,
+      `Bundle digest: ${bundle.bundleDigest}.`,
+      "Human review is required before transfer.",
+    ].join("\n") + "\n";
+    return { exitCode: 0, stdout: jsonOrText(options, bundle, summary), stderr: "" };
+  }
+  if (command === "upgrade-check") {
+    const assessment = await buildUpgradeAssessment(root, required(options, "from-version"));
+    const summary = [
+      `Upgrade ${assessment.fromVersion} -> ${assessment.targetVersion}: ${assessment.state}.`,
+      `Health: ${assessment.health}; rollback: ${assessment.rollbackClass}.`,
+      `Finding codes: ${assessment.findingCodes.join(", ") || "none"}.`,
+      `Assessment digest: ${assessment.assessmentDigest}.`,
+    ].join("\n") + "\n";
+    return { exitCode: assessment.state === "blocked" || assessment.state === "not-applicable" ? 1 : 0, stdout: jsonOrText(options, assessment, summary), stderr: "" };
+  }
+  if (command === "upgrade-plan") {
+    const plan = await buildMigrationPlanFile(root, required(options, "assessment"));
+    const summary = [
+      `Upgrade plan: ${plan.nextAction.kind}.`,
+      `Targets: ${plan.nextAction.targets.join(", ") || "none"}.`,
+      `Writes: ${plan.nextAction.writes}; human review: ${plan.requiresHumanReview}.`,
+      `Plan digest: ${plan.planDigest}.`,
+    ].join("\n") + "\n";
+    return { exitCode: 0, stdout: jsonOrText(options, plan, summary), stderr: "" };
+  }
+  if (command === "upgrade-apply") {
+    const applied = await applyMigrationPlanFile(root, required(options, "plan"), { write: options.write });
+    const summary = [
+      `Upgrade ${applied.result.mode}: ${applied.result.coreMigration}.`,
+      `Action: ${applied.result.action.kind}; written: ${applied.result.written}.`,
+      `Overall upgrade: ${applied.result.overallUpgrade}.`,
+      `Result digest: ${applied.result.resultDigest}.`,
+    ].join("\n") + "\n";
+    return { exitCode: applied.exitCode, stdout: jsonOrText(options, applied.result, summary), stderr: "" };
+  }
   if (command === "init") {
     const result = await initializeProject(root, required(options, "id"), required(options, "name"), options.write);
     return {
@@ -347,6 +421,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 ?? [],
@@ -357,6 +451,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, {
@@ -539,6 +638,17 @@ async function runCommand(command, options) {
     const summary = options.write ? `${result.action}: ${result.entry.path}\n` : `Preview ${result.action}: ${result.entry.path}\n\n${result.content}`;
     return { exitCode: 0, stdout: options.json ? prettyCanonicalJson(result) : summary, stderr: "" };
   }
+  if (command === "publish-entry" || command === "remove-entry") {
+    const operation = command === "publish-entry" ? publishAiEntry : removeAiEntry;
+    const result = await operation(root, project, {
+      output: required(options, "output"),
+      write: options.write,
+    });
+    const summary = options.write
+      ? `${result.action}: ${result.impact.paths[0]}\n`
+      : `Preview ${result.action}: ${result.impact.paths[0]}\n\n${result.proposed.region ?? ""}`;
+    return { exitCode: 0, stdout: options.json ? prettyCanonicalJson(result) : summary, stderr: "" };
+  }
   fail("command-unknown", `unknown command: ${command}`);
 }
 

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

@@ -288,26 +288,40 @@ export function validateSourceLock(lock) {
 export function validateProjectionLock(lock) {
   object(lock, "projections lock");
   exactKeys(lock, new Set(["schemaVersion", "projections"]), "projections lock");
-  if (lock.schemaVersion !== 1 || !Array.isArray(lock.projections)) fail("schema-invalid", "projections lock is invalid");
+  if (![1, 2].includes(lock.schemaVersion) || !Array.isArray(lock.projections)) fail("schema-invalid", "projections lock is invalid");
   const seen = new Set();
   for (const [index, entry] of lock.projections.entries()) {
     object(entry, `projection entry ${index}`);
-    exactKeys(
-      entry,
-      new Set(["path", "target", "paths", "contractDigest", "bundleDigest", "contentDigest", "itemIds", "rendererVersion"]),
-      `projection entry ${index}`,
-    );
-    entry.path = normalizeRelativePath(entry.path, { label: `projection entry ${index}.path` });
-    if (entry.target !== "agents" && entry.target !== "ruler") fail("schema-invalid-enum", "projection target is invalid");
-    uniqueStrings(entry.paths, `projection entry ${index}.paths`);
-    entry.paths = entry.paths.map((value) => normalizeRelativePath(value, { allowRoot: true, label: "projection scope path" }));
-    for (const key of ["contractDigest", "bundleDigest", "contentDigest"]) {
-      string(entry[key], `projection entry ${index}.${key}`);
-      if (!SHA256.test(entry[key])) fail("schema-invalid", `projection ${key} must be sha256`);
+    const label = `projection entry ${index}`;
+    if (lock.schemaVersion === 1) {
+      exactKeys(entry, new Set(["path", "target", "paths", "contractDigest", "bundleDigest", "contentDigest", "itemIds", "rendererVersion"]), label);
+    } else if (entry.ownership === "file") {
+      exactKeys(entry, new Set(["path", "target", "ownership", "paths", "contractDigest", "bundleDigest", "contentDigest", "itemIds", "rendererVersion"]), label);
+    } else if (entry.ownership === "region") {
+      exactKeys(entry, new Set(["path", "target", "ownership", "regionId", "regionDigest", "rendererVersion", "createdFile"]), label);
+    } else {
+      fail("schema-invalid-enum", `${label}.ownership must be file or region`);
     }
-    uniqueStrings(entry.itemIds, `projection entry ${index}.itemIds`, { empty: true });
-    if (![1, 2, 3].includes(entry.rendererVersion)) {
-      fail("schema-version-unsupported", "projection rendererVersion must be 1, 2, or 3");
+    entry.path = normalizeRelativePath(entry.path, { label: `projection entry ${index}.path` });
+    if (lock.schemaVersion === 2 && entry.ownership === "region") {
+      if (entry.target !== "ai-entry") fail("schema-invalid-enum", "region projection target must be ai-entry");
+      if (entry.regionId !== "project-context-ai-entry") fail("schema-invalid-enum", "AI Entry regionId is invalid");
+      string(entry.regionDigest, `${label}.regionDigest`);
+      if (!SHA256.test(entry.regionDigest)) fail("schema-invalid", "AI Entry regionDigest must be sha256");
+      if (![1, 2, 3].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, or 3");
+      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");
+      uniqueStrings(entry.paths, `${label}.paths`);
+      entry.paths = entry.paths.map((value) => normalizeRelativePath(value, { allowRoot: true, label: "projection scope path" }));
+      for (const key of ["contractDigest", "bundleDigest", "contentDigest"]) {
+        string(entry[key], `${label}.${key}`);
+        if (!SHA256.test(entry[key])) fail("schema-invalid", `projection ${key} must be sha256`);
+      }
+      uniqueStrings(entry.itemIds, `${label}.itemIds`, { empty: true });
+      if (![1, 2, 3].includes(entry.rendererVersion)) {
+        fail("schema-version-unsupported", "projection rendererVersion must be 1, 2, or 3");
+      }
     }
     if (seen.has(entry.path)) fail("schema-duplicate", `projections lock contains duplicate path: ${entry.path}`);
     seen.add(entry.path);

package/src/project-context/dashboard-model.mjs

@@ -201,11 +201,11 @@ function buildItems(contract) {
 }
 
 function projectionStatus(codes) {
-  if (codes.includes("projection-ownership-conflict")) return "conflict";
-  if (codes.includes("projection-missing")) return "missing";
+  if (codes.some((code) => code.endsWith("ownership-conflict"))) return "conflict";
+  if (codes.some((code) => code.endsWith("missing"))) return "missing";
   if (codes.includes("projection-unreadable") || codes.includes("projection-path-invalid")) return "unreadable";
   if (codes.includes("projection-diverged")) return "diverged";
-  if (codes.some((code) => code === "projection-stale" || code === "projection-renderer-stale" || code === "projection-item-missing")) {
+  if (codes.some((code) => code === "projection-stale" || code.endsWith("renderer-stale") || code === "projection-item-missing")) {
     return "stale";
   }
   return codes.length > 0 ? "attention" : "healthy";
@@ -214,7 +214,7 @@ function projectionStatus(codes) {
 function buildProjections(project, findings) {
   return project.projectionsLock.projections.map((entry) => {
     const findingCodes = findings
-      .filter((finding) => finding.path === entry.path && finding.code.startsWith("projection-"))
+      .filter((finding) => finding.path === entry.path && (finding.code.startsWith("projection-") || finding.code.startsWith("ai-entry-")))
       .map((finding) => finding.code);
     return {
       ...structuredClone(entry),

package/src/project-context/dashboard-renderer.mjs

@@ -567,10 +567,10 @@ function renderScopes(model) {
 
 function renderProjection(projection) {
   return `<details class="record projection"><summary><strong class="mono">${escapeHtml(projection.path)}</strong><span>${escapeHtml(projection.target)} · ${bi(`渲染器 ${projection.rendererVersion}`, `Renderer ${projection.rendererVersion}`)}</span>${statusBadge(projection.status)}</summary><div class="detail-body"><dl class="audit-grid">
-    ${auditField(bi("范围路径", "Scope paths"), tokenList(projection.paths), { htmlTerm: true })}
-    ${auditField(bi("知识项 ID", "Item IDs"), tokenList(projection.itemIds), { htmlTerm: true })}
+    ${auditField(bi("范围路径", "Scope paths"), tokenList(projection.paths ?? []), { htmlTerm: true })}
+    ${auditField(bi("知识项 ID", "Item IDs"), tokenList(projection.itemIds ?? []), { htmlTerm: true })}
     ${auditField(bi("问题代码", "Finding codes"), tokenList(projection.findingCodes), { htmlTerm: true })}
-    ${auditField(bi("合同指纹", "Contract digest"), escapeHtml(projection.contractDigest), { mono: true, htmlTerm: true })}
+    ${auditField(bi("合同指纹", "Contract digest"), escapeHtml(projection.contractDigest ?? projection.regionDigest ?? "not-applicable"), { mono: true, htmlTerm: true })}
   </dl></div></details>`;
 }
 

package/src/project-context/discovery.mjs

@@ -1,6 +1,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { sha256 } from "./canonical-json.mjs";
+import { parseAiEntryRegion } from "./ai-entry.mjs";
 import { sourceRegistrationShape, sourceStatus } from "./contract-schema.mjs";
 import { DEFAULT_IGNORES, digestPath, digestPathIdentity, readSourceDigest } from "./source-reader.mjs";
 
@@ -144,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,
         }));
       }
@@ -154,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,
         }));
       }
@@ -166,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,
         }));
       }
@@ -180,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,
     }));
   }
@@ -190,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 },
     }));
@@ -199,7 +200,11 @@ export async function discoverProject(root, contract) {
   const ruleContents = new Map();
   for (const relative of rulePaths) {
     const contents = await readFile(path.join(root, relative), "utf8");
-    if (!contents.startsWith("<!-- managed-by: project-context;")) ruleContents.set(relative, contents);
+    const aiEntry = parseAiEntryRegion(contents);
+    const outsideEntry = aiEntry.state === "present"
+      ? `${contents.slice(0, aiEntry.start)}${contents.slice(aiEntry.end)}`.replace(/^\ufeff/u, "").trim()
+      : null;
+    if (!contents.startsWith("<!-- managed-by: project-context;") && outsideEntry !== "") ruleContents.set(relative, contents);
   }
   const knownRulePaths = new Set(ruleContents.keys());
   const aliasTargets = new Map();
@@ -216,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) }
@@ -238,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/evidence-schema.mjs

@@ -0,0 +1,209 @@
+import { canonicalJson, canonicalValue, digestJson, validateJsonValue } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+
+export const EVIDENCE_INPUT_SCHEMA_VERSION = 1;
+export const EVIDENCE_BUNDLE_SCHEMA_VERSION = 1;
+export const EVIDENCE_INPUT_MAX_UTF8_BYTES = 32 * 1024;
+export const EVIDENCE_OUTPUT_MAX_UTF8_BYTES = 48 * 1024;
+
+const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const FIELD_PATH = /^[a-z][A-Za-z0-9]*(?:\.[a-z][A-Za-z0-9]*)*$/u;
+const CAPABILITIES = new Set(["setup", "takeover", "maintenance", "staged-context", "upgrade", "other-protocol"]);
+const RESULTS = new Set(["passed", "degraded", "blocked", "failed"]);
+const RUNTIMES = new Set(["node", "other", "redacted"]);
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun", "other", "redacted"]);
+const PROJECT_SHAPES = new Set(["single", "monorepo", "multi-context", "redacted"]);
+const OPERATIONS = new Set([
+  "capabilities", "status", "setup-preview", "sync", "check", "context", "preflight", "stage-context",
+  "integration-review", "publish-entry-preview", "remove-entry-preview", "upgrade-baseline", "other-protocol",
+]);
+const REDACTION_METHODS = new Set(["removed", "generalized", "hashed", "redacted", "not-collected"]);
+const STRUCTURALLY_FORBIDDEN_FIELDS = new Set([
+  "approval", "approve", "authorization", "base64", "body", "branch", "branchName", "businessCode", "chat", "codeBody",
+  "cookie", "credential", "credentials", "cwd", "decision", "destination", "diff", "environmentVariables", "externalId", "fileName", "filename",
+  "generatedAt", "hostName", "hostname", "itemIds", "items", "locator", "log", "logs", "name", "output", "path",
+  "paths", "priority", "projectId", "projectName", "release", "repository", "repositoryUrl", "reviewer", "sourceBody",
+  "password", "secret", "sourceIds", "sources", "targetVersion", "timestamp", "token", "upload", "url", "userName", "username", "value",
+]);
+
+function invalid(message, details) {
+  fail("evidence-input-invalid", message, { details });
+}
+
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(`${label} must be an object`);
+}
+
+function exactKeys(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (STRUCTURALLY_FORBIDDEN_FIELDS.has(key)) {
+      fail("evidence-redaction-blocked", `${label} contains a structurally forbidden field: ${key}`, { details: { field: key } });
+    }
+    if (!allowed.has(key)) invalid(`${label} contains unknown field: ${key}`);
+  }
+}
+
+function requiredKeys(value, required, label) {
+  for (const key of required) if (!Object.hasOwn(value, key)) invalid(`${label}.${key} is required`);
+}
+
+function string(value, label) {
+  if (typeof value !== "string" || value.length === 0) invalid(`${label} must be a non-empty string`);
+}
+
+function stableId(value, label) {
+  string(value, label);
+  if (!ID.test(value)) invalid(`${label} must use stable lowercase dot/kebab naming`);
+}
+
+function summary(value, label) {
+  string(value, label);
+  if (/\r|\n|\u2028|\u2029/u.test(value)) invalid(`${label} must be a single line`);
+  if (Buffer.byteLength(value, "utf8") > 500) invalid(`${label} exceeds 500 UTF-8 bytes`);
+  return value;
+}
+
+function enumValue(value, allowed, label) {
+  if (!allowed.has(value)) invalid(`${label} is invalid`);
+  return value;
+}
+
+function array(value, label, max) {
+  if (!Array.isArray(value)) invalid(`${label} must be an array`);
+  if (value.length > max) invalid(`${label} exceeds ${max} entries`);
+}
+
+function uniqueSorted(values, identity = (value) => canonicalJson(value)) {
+  return [...new Map(values.map((value) => [identity(value), value])).values()]
+    .sort((left, right) => identity(left).localeCompare(identity(right)));
+}
+
+function normalizeCodes(value, label) {
+  array(value, label, 32);
+  const normalized = value.map((entry, index) => {
+    stableId(entry, `${label}[${index}]`);
+    return entry;
+  });
+  return uniqueSorted(normalized, (entry) => entry);
+}
+
+function normalizeEnvironment(value) {
+  object(value, "environment");
+  const keys = new Set(["runtime", "runtimeMajor", "packageManager", "projectShape"]);
+  exactKeys(value, keys, "environment");
+  requiredKeys(value, keys, "environment");
+  if (!Number.isInteger(value.runtimeMajor) || value.runtimeMajor < 0 || value.runtimeMajor > 999) {
+    invalid("environment.runtimeMajor must be an integer from 0 through 999");
+  }
+  return {
+    runtime: enumValue(value.runtime, RUNTIMES, "environment.runtime"),
+    runtimeMajor: value.runtimeMajor,
+    packageManager: enumValue(value.packageManager, PACKAGE_MANAGERS, "environment.packageManager"),
+    projectShape: enumValue(value.projectShape, PROJECT_SHAPES, "environment.projectShape"),
+  };
+}
+
+function normalizeObservation(value, label) {
+  object(value, label);
+  const keys = new Set(["code", "summary"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  stableId(value.code, `${label}.code`);
+  return { code: value.code, summary: summary(value.summary, `${label}.summary`) };
+}
+
+function normalizeReproduction(value) {
+  array(value, "reproduction", 20);
+  return value.map((entry, index) => {
+    const label = `reproduction[${index}]`;
+    object(entry, label);
+    const keys = new Set(["operation", "outcome", "findingCodes"]);
+    exactKeys(entry, keys, label);
+    requiredKeys(entry, keys, label);
+    return {
+      operation: enumValue(entry.operation, OPERATIONS, `${label}.operation`),
+      outcome: enumValue(entry.outcome, RESULTS, `${label}.outcome`),
+      findingCodes: normalizeCodes(entry.findingCodes, `${label}.findingCodes`),
+    };
+  });
+}
+
+function normalizeArtifacts(value) {
+  array(value, "artifacts", 32);
+  const normalized = value.map((entry, index) => {
+    const label = `artifacts[${index}]`;
+    object(entry, label);
+    const keys = new Set(["kind", "digest"]);
+    exactKeys(entry, keys, label);
+    requiredKeys(entry, keys, label);
+    stableId(entry.kind, `${label}.kind`);
+    if (typeof entry.digest !== "string" || !SHA256.test(entry.digest)) invalid(`${label}.digest must be sha256`);
+    return { kind: entry.kind, digest: entry.digest };
+  });
+  return uniqueSorted(normalized);
+}
+
+function normalizeRedactions(value) {
+  array(value, "redactions", 32);
+  const normalized = value.map((entry, index) => {
+    const label = `redactions[${index}]`;
+    object(entry, label);
+    const keys = new Set(["field", "method"]);
+    exactKeys(entry, keys, label);
+    requiredKeys(entry, keys, label);
+    string(entry.field, `${label}.field`);
+    if (!FIELD_PATH.test(entry.field)) invalid(`${label}.field must be a dotted input field path`);
+    return { field: entry.field, method: enumValue(entry.method, REDACTION_METHODS, `${label}.method`) };
+  });
+  return uniqueSorted(normalized);
+}
+
+export function normalizeEvidenceInput(input) {
+  try {
+    validateJsonValue(input);
+  } catch (error) {
+    invalid("evidence input must be JSON-compatible", { reason: error.message });
+  }
+  object(input, "evidence input");
+  const keys = new Set([
+    "schemaVersion", "capability", "result", "environment", "expected", "observed", "errorCodes",
+    "reproduction", "artifacts", "redactions",
+  ]);
+  exactKeys(input, keys, "evidence input");
+  requiredKeys(input, keys, "evidence input");
+  if (input.schemaVersion !== EVIDENCE_INPUT_SCHEMA_VERSION) invalid("evidence input schemaVersion must be 1");
+  const normalized = {
+    schemaVersion: EVIDENCE_INPUT_SCHEMA_VERSION,
+    capability: enumValue(input.capability, CAPABILITIES, "capability"),
+    result: enumValue(input.result, RESULTS, "result"),
+    environment: normalizeEnvironment(input.environment),
+    expected: normalizeObservation(input.expected, "expected"),
+    observed: normalizeObservation(input.observed, "observed"),
+    errorCodes: normalizeCodes(input.errorCodes, "errorCodes"),
+    reproduction: normalizeReproduction(input.reproduction),
+    artifacts: normalizeArtifacts(input.artifacts),
+    redactions: normalizeRedactions(input.redactions),
+  };
+  if (Buffer.byteLength(canonicalJson(normalized), "utf8") > EVIDENCE_INPUT_MAX_UTF8_BYTES) {
+    fail("evidence-input-budget-exceeded", `canonical evidence input exceeds ${EVIDENCE_INPUT_MAX_UTF8_BYTES} UTF-8 bytes`);
+  }
+  return canonicalValue(normalized);
+}
+
+export function finalizeEvidenceBundle(bundleWithoutDigest) {
+  const canonical = canonicalValue(bundleWithoutDigest);
+  const bundle = canonicalValue({ ...canonical, bundleDigest: digestJson(canonical) });
+  if (Buffer.byteLength(canonicalJson(bundle), "utf8") > EVIDENCE_OUTPUT_MAX_UTF8_BYTES) {
+    fail("evidence-output-budget-exceeded", `canonical evidence output exceeds ${EVIDENCE_OUTPUT_MAX_UTF8_BYTES} UTF-8 bytes`);
+  }
+  return bundle;
+}
+
+export function verifyEvidenceBundleDigest(bundle) {
+  object(bundle, "evidence bundle");
+  const copy = structuredClone(bundle);
+  const actual = copy.bundleDigest;
+  delete copy.bundleDigest;
+  return typeof actual === "string" && actual === digestJson(canonicalValue(copy));
+}