frontend-project-context 1.3.1 → 1.6.0

package/src/project-context/capabilities.mjs

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

package/src/project-context/checker.mjs

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { AI_ENTRY_RENDERER_VERSION, parseAiEntryRegion } from "./ai-entry.mjs";
 import { sha256 } from "./canonical-json.mjs";
 import { sourceStatus } from "./contract-schema.mjs";
 import { readSourceDigest, verifyItem } from "./source-reader.mjs";
@@ -74,7 +75,23 @@ export async function checkProject(root, project) {
     try {
       content = await readFile(resolved.absolute, "utf8");
     } catch (error) {
-      findings.push({ code: error?.code === "ENOENT" ? "projection-missing" : "projection-unreadable", path: entry.path });
+      findings.push({
+        code: entry.ownership === "region"
+          ? error?.code === "ENOENT" ? "ai-entry-missing" : "projection-unreadable"
+          : error?.code === "ENOENT" ? "projection-missing" : "projection-unreadable",
+        path: entry.path,
+      });
+      continue;
+    }
+    if (entry.ownership === "region") {
+      const parsed = parseAiEntryRegion(content);
+      if (parsed.state !== "present" || sha256(parsed.region) !== entry.regionDigest) {
+        findings.push({ code: "ai-entry-ownership-conflict", path: entry.path });
+        continue;
+      }
+      if (entry.rendererVersion !== AI_ENTRY_RENDERER_VERSION) {
+        findings.push({ code: "ai-entry-renderer-stale", path: entry.path, expected: AI_ENTRY_RENDERER_VERSION, actual: entry.rendererVersion });
+      }
       continue;
     }
     const marker = parseProjectionMarker(content);
@@ -113,7 +130,7 @@ export async function checkProject(root, project) {
 }
 
 export function checkExitCode(findings) {
-  return findings.some((finding) => finding.code === "projection-ownership-conflict") ? 3 : findings.length > 0 ? 1 : 0;
+  return findings.some((finding) => ["projection-ownership-conflict", "ai-entry-ownership-conflict", "ai-entry-path-conflict"].includes(finding.code)) ? 3 : findings.length > 0 ? 1 : 0;
 }
 
 export function blockingContextFindings(findings) {
@@ -127,6 +144,6 @@ export function blockingContextFindings(findings) {
 }
 
 export function findingSeverity(finding) {
-  if (finding.code === "projection-ownership-conflict") return "conflict";
+  if (["projection-ownership-conflict", "ai-entry-ownership-conflict", "ai-entry-path-conflict"].includes(finding.code)) return "conflict";
   return blockingContextFindings([finding]).length > 0 ? "blocked" : "attention";
 }

package/src/project-context/cli.mjs

@@ -8,21 +8,31 @@ 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";
 
 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]
@@ -35,6 +45,8 @@ Usage:
   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 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]
@@ -45,10 +57,10 @@ Usage:
 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",
+  "project", "id", "name", "input", "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",
 ]);
 const LIST_FLAGS = new Set([
   "ids", "path", "changed-path", "sources", "overrides", "affected-items", "receipt", "receipt-bundle", "main-changed-path", "branch-changed-path",
@@ -57,6 +69,11 @@ const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending"])
 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([
@@ -82,6 +99,8 @@ const COMMAND_OPTIONS = new Map([
   ["approve", new Set(["project", "proposal", "pending", "ids", "by", "rationale", "write", "json", "full-json", "help"])],
   ["context", new Set(["project", "path", "task", "locale", "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"])],
@@ -323,6 +342,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, required(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 {
@@ -539,6 +603,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 (entry.rendererVersion !== 1) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1");
+      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";
 
@@ -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();

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));
+}