frontend-project-context 1.3.0 → 1.6.0

package/schemas/project-status.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:project-status:1",
+  "title": "Frontend Project Context Project Status",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "package", "initialization", "project", "snapshots", "health", "entry", "summary", "findingCodes", "sourceIds", "itemIds", "projectionPaths", "readTargets", "workUnits", "nextActions", "boundaries"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": { "name": { "const": "frontend-project-context" }, "version": { "type": "string" } }
+    },
+    "initialization": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "present", "missing"],
+      "properties": {
+        "state": { "enum": ["uninitialized", "partial", "invalid", "initialized"] },
+        "present": { "$ref": "#/$defs/strings" },
+        "missing": { "$ref": "#/$defs/strings" }
+      }
+    },
+    "project": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/project" }] },
+    "snapshots": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/snapshots" }] },
+    "health": { "enum": ["uninitialized", "partial", "invalid", "attention", "clean", "conflict"] },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "path", "rendererVersion"],
+      "properties": {
+        "state": { "enum": ["absent", "current", "stale", "conflict"] },
+        "path": { "type": ["string", "null"] },
+        "rendererVersion": { "type": ["integer", "null"] }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["findings", "changedSources", "pendingItems", "affectedProjections"],
+      "properties": {
+        "findings": { "type": "integer", "minimum": 0 },
+        "changedSources": { "type": "integer", "minimum": 0 },
+        "pendingItems": { "type": "integer", "minimum": 0 },
+        "affectedProjections": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "findingCodes": { "$ref": "#/$defs/strings" },
+    "sourceIds": { "$ref": "#/$defs/strings" },
+    "itemIds": { "$ref": "#/$defs/strings" },
+    "projectionPaths": { "$ref": "#/$defs/strings" },
+    "readTargets": { "type": "array", "items": { "type": "object" } },
+    "workUnits": { "type": "array", "items": { "type": "object" } },
+    "nextActions": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "enum": ["run-setup-preview", "run-sync", "review-pending", "review-source-change", "review-projection", "publish-ai-entry", "resolve-conflict", "ready-for-task"] }
+    },
+    "boundaries": { "type": "object", "additionalProperties": { "const": false } }
+  },
+  "$defs": {
+    "strings": { "type": "array", "uniqueItems": true, "items": { "type": "string" } },
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "project": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name"],
+      "properties": { "id": { "type": "string" }, "name": { "type": "string" } }
+    },
+    "snapshots": {
+      "type": "object", "additionalProperties": false, "required": ["contract", "sourcesLock", "projectionsLock"],
+      "properties": { "contract": { "$ref": "#/$defs/digest" }, "sourcesLock": { "$ref": "#/$defs/digest" }, "projectionsLock": { "$ref": "#/$defs/digest" } }
+    }
+  }
+}

package/schemas/projection-lock.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:projection-lock:2",
+  "title": "Frontend Project Context Projection Lock",
+  "oneOf": [
+    { "$ref": "#/$defs/schema1" },
+    { "$ref": "#/$defs/schema2" }
+  ],
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "fileEntry1": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "target", "paths", "contractDigest", "bundleDigest", "contentDigest", "itemIds", "rendererVersion"],
+      "properties": {
+        "path": { "type": "string" }, "target": { "enum": ["agents", "ruler"] }, "paths": { "type": "array", "items": { "type": "string" } },
+        "contractDigest": { "$ref": "#/$defs/digest" }, "bundleDigest": { "$ref": "#/$defs/digest" }, "contentDigest": { "$ref": "#/$defs/digest" },
+        "itemIds": { "type": "array", "items": { "type": "string" } }, "rendererVersion": { "enum": [1, 2, 3] }
+      }
+    },
+    "fileEntry2": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "target", "ownership", "paths", "contractDigest", "bundleDigest", "contentDigest", "itemIds", "rendererVersion"],
+      "properties": {
+        "path": { "type": "string" }, "target": { "enum": ["agents", "ruler"] }, "ownership": { "const": "file" },
+        "paths": { "type": "array", "items": { "type": "string" } }, "contractDigest": { "$ref": "#/$defs/digest" },
+        "bundleDigest": { "$ref": "#/$defs/digest" }, "contentDigest": { "$ref": "#/$defs/digest" },
+        "itemIds": { "type": "array", "items": { "type": "string" } }, "rendererVersion": { "enum": [1, 2, 3] }
+      }
+    },
+    "regionEntry": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "target", "ownership", "regionId", "regionDigest", "rendererVersion", "createdFile"],
+      "properties": {
+        "path": { "type": "string" }, "target": { "const": "ai-entry" }, "ownership": { "const": "region" },
+        "regionId": { "const": "project-context-ai-entry" }, "regionDigest": { "$ref": "#/$defs/digest" },
+        "rendererVersion": { "const": 1 }, "createdFile": { "type": "boolean" }
+      }
+    },
+    "schema1": {
+      "type": "object", "additionalProperties": false, "required": ["schemaVersion", "projections"],
+      "properties": { "schemaVersion": { "const": 1 }, "projections": { "type": "array", "items": { "$ref": "#/$defs/fileEntry1" } } }
+    },
+    "schema2": {
+      "type": "object", "additionalProperties": false, "required": ["schemaVersion", "projections"],
+      "properties": { "schemaVersion": { "const": 2 }, "projections": { "type": "array", "items": { "oneOf": [{ "$ref": "#/$defs/fileEntry2" }, { "$ref": "#/$defs/regionEntry" }] } } }
+    }
+  }
+}

package/schemas/review-bundle.schema.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:frontend-project-context:schema:review-bundle:1",
+  "$id": "urn:frontend-project-context:schema:review-bundle:2",
   "title": "Frontend Project Context Review Bundle",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "projectId", "planDigest", "baselines", "status", "summary", "actions", "groups", "findings", "invocations"],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "projectId": { "$ref": "#/$defs/id" },
     "planDigest": { "$ref": "#/$defs/digest" },
     "baselines": { "$ref": "#/$defs/baselines" },
@@ -84,7 +84,7 @@
       }
     },
     "actionKind": {
-      "enum": ["accept-source-change", "deprecate-item", "deprecate-source", "propose-item", "publish-projection", "register-source", "request-item-approval", "revise-item"]
+      "enum": ["accept-source-change", "deprecate-item", "deprecate-source", "propose-item", "publish-ai-entry", "publish-projection", "register-source", "remove-ai-entry", "request-item-approval", "revise-item"]
     },
     "invocation": {
       "type": "object",

package/schemas/upgrade-assessment.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:upgrade-assessment:1",
+  "title": "Frontend Project Context Upgrade Assessment",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "product", "fromVersion", "targetVersion", "fromVersionEvidence", "manifestSchemaVersion", "manifestDigest", "initialization", "health", "entryState", "findingCodes", "snapshots", "compatibility", "migrationPath", "rollbackClass", "requiresHumanReview", "state", "boundaries", "assessmentDigest"],
+  "properties": {
+    "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"]},
+    "targetVersion": {"const": "1.6.0"},
+    "fromVersionEvidence": {"const": "host-asserted"},
+    "manifestSchemaVersion": {"const": 2},
+    "manifestDigest": {"$ref": "#/$defs/digest"},
+    "initialization": {"type": "object", "additionalProperties": false, "required": ["state", "present", "missing"], "properties": {"state": {"enum": ["uninitialized", "partial", "initialized", "invalid"]}, "present": {"$ref": "#/$defs/strings"}, "missing": {"$ref": "#/$defs/strings"}}},
+    "health": {"enum": ["uninitialized", "partial", "invalid", "attention", "conflict", "clean"]},
+    "entryState": {"type": "object", "additionalProperties": false, "required": ["state", "path", "rendererVersion"], "properties": {"state": {"type": "string"}, "path": {"type": ["string", "null"]}, "rendererVersion": {"type": ["integer", "null"]}}},
+    "findingCodes": {"$ref": "#/$defs/strings"},
+    "snapshots": {"anyOf": [{"type": "null"}, {"$ref": "#/$defs/snapshots"}]},
+    "compatibility": {"type": "object", "additionalProperties": false, "required": ["stores", "renderers", "protocols"], "properties": {"stores": {"$ref": "#/$defs/compatibility"}, "renderers": {"$ref": "#/$defs/compatibility"}, "protocols": {"$ref": "#/$defs/compatibility"}}},
+    "migrationPath": {"$ref": "#/$defs/strings"},
+    "rollbackClass": {"enum": ["package-only", "reversible-data", "forward-only"]},
+    "requiresHumanReview": {"type": "boolean"},
+    "state": {"enum": ["not-applicable", "blocked", "ready-for-plan", "core-complete"]},
+    "boundaries": {"$ref": "#/$defs/boundaries"},
+    "assessmentDigest": {"$ref": "#/$defs/digest"}
+  },
+  "$defs": {
+    "digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+    "strings": {"type": "array", "uniqueItems": true, "items": {"type": "string"}},
+    "snapshots": {"type": "object", "additionalProperties": false, "required": ["contract", "sourcesLock", "projectionsLock"], "properties": {"contract": {"$ref": "#/$defs/digest"}, "sourcesLock": {"$ref": "#/$defs/digest"}, "projectionsLock": {"$ref": "#/$defs/digest"}}},
+    "compatibility": {"type": "object", "additionalProperties": {"enum": ["compatible", "republish", "regenerate", "invalidate", "unsupported", "not-applicable"]}},
+    "boundaries": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "agentRuntime", "git", "network", "dependencyInstallation", "automaticApproval", "businessCodeWrites", "taskExecution", "stagePathBodyReads", "applyPlan", "scheduler", "daemon", "telemetry", "selfUpdate", "automaticEvidenceUpload", "packageManager", "automaticUpgrade"],
+      "properties": {
+        "provider": {"const": false}, "agentRuntime": {"const": false}, "git": {"const": false}, "network": {"const": false},
+        "dependencyInstallation": {"const": false}, "automaticApproval": {"const": false}, "businessCodeWrites": {"const": false},
+        "taskExecution": {"const": false}, "stagePathBodyReads": {"const": false}, "applyPlan": {"const": false},
+        "scheduler": {"const": false}, "daemon": {"const": false}, "telemetry": {"const": false}, "selfUpdate": {"const": false},
+        "automaticEvidenceUpload": {"const": false}, "packageManager": {"const": false}, "automaticUpgrade": {"const": false}
+      }
+    }
+  }
+}

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

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:upgrade-result-bundle:1",
+  "title": "Frontend Project Context Upgrade Result Bundle",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "product", "fromVersion", "targetVersion", "manifestDigest", "planDigest", "mode", "action", "written", "targets", "snapshots", "actionResult", "findingCodes", "coreMigration", "hostAcceptance", "overallUpgrade", "resultDigest"],
+  "properties": {
+    "schemaVersion": {"const": 1},
+    "kind": {"const": "upgrade-result-bundle"},
+    "product": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"const": "frontend-project-context"}}},
+    "fromVersion": {"type": "string"},
+    "targetVersion": {"const": "1.6.0"},
+    "manifestDigest": {"$ref": "#/$defs/digest"},
+    "planDigest": {"$ref": "#/$defs/digest"},
+    "mode": {"enum": ["preview", "write"]},
+    "action": {"$ref": "#/$defs/action"},
+    "written": {"type": "boolean"},
+    "targets": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["path", "beforeDigest", "afterDigest"], "properties": {"path": {"$ref": "#/$defs/path"}, "beforeDigest": {"anyOf": [{"type": "null"}, {"$ref": "#/$defs/digest"}]}, "afterDigest": {"anyOf": [{"type": "null"}, {"$ref": "#/$defs/digest"}]}}}},
+    "snapshots": {"type": "object", "additionalProperties": false, "required": ["before", "after"], "properties": {"before": {"anyOf": [{"type": "null"}, {"$ref": "#/$defs/snapshots"}]}, "after": {"anyOf": [{"type": "null"}, {"$ref": "#/$defs/snapshots"}]}}},
+    "actionResult": {"type": "string"},
+    "findingCodes": {"type": "array", "uniqueItems": true, "items": {"type": "string"}},
+    "coreMigration": {"enum": ["previewed", "applied", "blocked", "complete"]},
+    "hostAcceptance": {"const": ["dependency-and-lockfile", "independent-new-window", "project-tests-or-ci"]},
+    "overallUpgrade": {"const": "host-validation-required"},
+    "resultDigest": {"$ref": "#/$defs/digest"}
+  },
+  "$defs": {
+    "digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+    "path": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?![A-Za-z]:)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"},
+    "strings": {"type": "array", "uniqueItems": true, "items": {"type": "string"}},
+    "snapshots": {"type": "object", "additionalProperties": false, "required": ["contract", "sourcesLock", "projectionsLock"], "properties": {"contract": {"$ref": "#/$defs/digest"}, "sourcesLock": {"$ref": "#/$defs/digest"}, "projectionsLock": {"$ref": "#/$defs/digest"}}},
+    "action": {"type": "object", "additionalProperties": false, "required": ["id", "kind", "migrationId", "targets", "writes", "semanticImpact"], "properties": {"id": {"type": "string"}, "kind": {"enum": ["verify-complete", "republish-ai-entry", "republish-projection", "built-in-store-migration", "invalidate-ephemeral-protocol"]}, "migrationId": {"type": ["string", "null"]}, "targets": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/path"}}, "writes": {"type": "boolean"}, "semanticImpact": {"enum": ["none", "managed-rendering", "store-structure", "protocol-artifact-invalidation"]}}}
+  }
+}

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

@@ -0,0 +1,320 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { canonicalJson, digestJson, sha256 } from "./canonical-json.mjs";
+import { sourceStatus, validateContract, validateProjectionLock } from "./contract-schema.mjs";
+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 = 1;
+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: 1 -->",
+  "## Project Context startup",
+  "",
+  "Before project work, use the project-local `frontend-project-context` CLI without downloading another version.",
+  "",
+  "1. Run `project-context status --project . --json`.",
+  "2. If state is `partial` or `invalid`, stop writes and report the exact recovery evidence required.",
+  "3. If uninitialized, preview `setup`; if initialized with attention, use `sync` work units; if clean, continue the user task.",
+  "4. Never treat a plan, bundle, receipt, review, or AI suggestion as human approval.",
+  "5. Before declaring completion, restore Project Context to `clean` or report the exact blocker.",
+  AI_ENTRY_END,
+];
+
+function entryOutput(output) {
+  let normalized;
+  try {
+    normalized = normalizeRelativePath(output, { label: "AI Entry output" });
+  } catch (error) {
+    fail("ai-entry-output-invalid", "AI Entry output must stay inside the project", {
+      exitCode: 2,
+      cause: error,
+      details: { path: output },
+    });
+  }
+  if (path.posix.basename(normalized) !== "AGENTS.md") {
+    fail("ai-entry-output-invalid", "AI Entry output must be an AGENTS.md file", {
+      exitCode: 2,
+      details: { path: normalized },
+    });
+  }
+  return normalized;
+}
+
+async function resolveEntryOutput(root, output, write) {
+  const normalized = entryOutput(output);
+  try {
+    return await resolveWritableInside(root, normalized, { createParent: write });
+  } catch (error) {
+    fail("ai-entry-output-invalid", "AI Entry output is not safely writable inside the project", {
+      exitCode: 2,
+      cause: error,
+      details: { path: normalized, reason: error.code ?? "invalid-output" },
+    });
+  }
+}
+
+async function readIfPresent(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function count(content, needle) {
+  return content.split(needle).length - 1;
+}
+
+export function renderAiEntry(newline = "\n") {
+  return ENTRY_LINES.join(newline);
+}
+
+export function parseAiEntryRegion(content) {
+  if (typeof content !== "string") return { state: "absent", region: null };
+  const starts = count(content, AI_ENTRY_START);
+  const ends = count(content, AI_ENTRY_END);
+  if (starts === 0 && ends === 0) return { state: "absent", region: null };
+  if (starts !== 1 || ends !== 1) return { state: "conflict", reason: "marker-count", region: null };
+  const start = content.indexOf(AI_ENTRY_START);
+  const endStart = content.indexOf(AI_ENTRY_END);
+  if (endStart <= start) return { state: "conflict", reason: "marker-order", region: null };
+  const end = endStart + AI_ENTRY_END.length;
+  const between = content.slice(start + AI_ENTRY_START.length, endStart);
+  if (between.includes(AI_ENTRY_START) || between.includes(AI_ENTRY_END)) {
+    return { state: "conflict", reason: "nested-marker", region: null };
+  }
+  return { state: "present", start, end, region: content.slice(start, end) };
+}
+
+function newlineFor(content) {
+  return content?.includes("\r\n") ? "\r\n" : "\n";
+}
+
+function appendRegion(content, region, newline) {
+  if (content === null || content.length === 0) return region;
+  const trailingNewline = content.endsWith("\r\n") || content.endsWith("\n");
+  return `${content}${trailingNewline ? newline : `${newline}${newline}`}${region}`;
+}
+
+function schema2FileEntry(entry) {
+  return entry.ownership ? structuredClone(entry) : { ...structuredClone(entry), ownership: "file" };
+}
+
+function sourceImpact(project, output, afterDigest) {
+  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));
+  const sourceIds = sources.map((source) => source.id);
+  const selected = new Set(sourceIds);
+  const itemIds = project.contract.items
+    .filter((item) => item.sources.some((id) => selected.has(id)) || selected.has(item.verification?.source))
+    .map((item) => item.id)
+    .sort((left, right) => left.localeCompare(right));
+  return { sourceIds, itemIds, afterDigest: sourceIds.length > 0 ? afterDigest : null };
+}
+
+function ownershipConflict(pathname, reason) {
+  fail("ai-entry-ownership-conflict", `AI Entry ownership is not trustworthy: ${pathname}`, {
+    exitCode: 3,
+    details: { path: pathname, reason },
+  });
+}
+
+function entryLock(project, output) {
+  return project.projectionsLock.projections.find((entry) => entry.path === output) ?? null;
+}
+
+function assertEntryOwnership(output, content, lockEntry, parsed) {
+  if (lockEntry && lockEntry.ownership !== "region") {
+    fail("ai-entry-path-conflict", `AI Entry conflicts with a whole-file projection: ${output}`, {
+      exitCode: 3,
+      details: { path: output },
+    });
+  }
+  if (parsed.state === "conflict") ownershipConflict(output, parsed.reason);
+  if (parsed.state === "present" && !lockEntry) ownershipConflict(output, "marker-without-lock");
+  if (parsed.state === "absent" && lockEntry) ownershipConflict(output, "lock-without-marker");
+  if (lockEntry && sha256(parsed.region) !== lockEntry.regionDigest) ownershipConflict(output, "region-digest-mismatch");
+}
+
+function nextProjectionLock(project, output, nextEntry) {
+  return validateProjectionLock({
+    schemaVersion: 2,
+    projections: [
+      ...project.projectionsLock.projections
+        .filter((entry) => entry.path !== output)
+        .map(schema2FileEntry),
+      ...(nextEntry ? [nextEntry] : []),
+    ].sort((left, right) => left.path.localeCompare(right.path)),
+  });
+}
+
+async function commitEntry(project, resolved, existing, nextContent, nextLock, dependencies) {
+  const readJson = dependencies.readJson ?? readJsonFile;
+  const readContent = dependencies.readFile ?? readIfPresent;
+  const writeJson = dependencies.writeJson ?? atomicWriteJson;
+  const writeFile = dependencies.writeFile ?? atomicWriteFile;
+  if (dependencies.beforeCommit) await dependencies.beforeCommit();
+  const currentContract = validateContract(await readJson(project.files.contract, "contract.json"));
+  const currentLock = validateProjectionLock(await readJson(project.files.projectionsLock, "projections.lock.json"));
+  if (digestJson(currentContract) !== project.contractDigest) {
+    fail("ai-entry-state-changed", "contract changed while the AI Entry was being prepared", { exitCode: 1 });
+  }
+  if (digestJson(currentLock) !== project.projectionsLockDigest) {
+    fail("ai-entry-state-changed", "projection lock changed while the AI Entry was being prepared", { exitCode: 1 });
+  }
+  if (await readContent(resolved.absolute) !== existing) {
+    fail("ai-entry-state-changed", "AGENTS.md changed while the AI Entry was being prepared", {
+      exitCode: 1,
+      details: { path: resolved.normalized },
+    });
+  }
+  await writeJson(project.files.projectionsLock, nextLock);
+  try {
+    await writeFile(resolved.absolute, nextContent);
+  } catch (error) {
+    try {
+      const recoveryCurrent = validateProjectionLock(await readJson(project.files.projectionsLock, "projections.lock.json"));
+      if (canonicalJson(recoveryCurrent) === canonicalJson(nextLock)) {
+        await writeJson(project.files.projectionsLock, project.projectionsLock);
+      } else if (error && typeof error === "object") {
+        error.details = { ...(error.details ?? {}), recovery: "projection-lock-restore-skipped-concurrent-change" };
+      }
+    } catch (recoveryError) {
+      if (error && typeof error === "object") {
+        error.details = { ...(error.details ?? {}), recovery: "projection-lock-restore-failed", recoveryMessage: recoveryError.message };
+      }
+    }
+    throw error;
+  }
+}
+
+export async function inspectAiEntry(root, project, output = "AGENTS.md") {
+  const resolved = await resolveEntryOutput(root, output, false);
+  const content = await readIfPresent(resolved.absolute);
+  const parsed = parseAiEntryRegion(content);
+  const lockEntry = entryLock(project, resolved.normalized);
+  if (lockEntry && lockEntry.ownership !== "region") {
+    return { state: "absent", path: null, rendererVersion: null };
+  }
+  if (content === null && lockEntry?.ownership === "region") {
+    return { state: "absent", path: resolved.normalized, rendererVersion: lockEntry.rendererVersion };
+  }
+  try {
+    assertEntryOwnership(resolved.normalized, content, lockEntry, parsed);
+  } catch (error) {
+    if (error?.code === "ai-entry-ownership-conflict" || error?.code === "ai-entry-path-conflict") {
+      return { state: "conflict", path: resolved.normalized, rendererVersion: lockEntry?.rendererVersion ?? null, reason: error.details?.reason ?? error.code };
+    }
+    throw error;
+  }
+  if (!lockEntry) return { state: "absent", path: null, rendererVersion: null };
+  return {
+    state: lockEntry.rendererVersion === AI_ENTRY_RENDERER_VERSION ? "current" : "stale",
+    path: resolved.normalized,
+    rendererVersion: lockEntry.rendererVersion,
+  };
+}
+
+export async function publishAiEntry(root, project, options, dependencies = {}) {
+  const write = Boolean(options.write);
+  const resolved = await resolveEntryOutput(root, options.output, write);
+  const readContent = dependencies.readFile ?? readIfPresent;
+  const existing = await readContent(resolved.absolute);
+  const parsed = parseAiEntryRegion(existing);
+  const currentEntry = entryLock(project, resolved.normalized);
+  assertEntryOwnership(resolved.normalized, existing, currentEntry, parsed);
+  const newline = newlineFor(existing);
+  const region = renderAiEntry(newline);
+  const nextContent = parsed.state === "present"
+    ? `${existing.slice(0, parsed.start)}${region}${existing.slice(parsed.end)}`
+    : appendRegion(existing, region, newline);
+  const nextEntry = {
+    path: resolved.normalized,
+    target: "ai-entry",
+    ownership: "region",
+    regionId: AI_ENTRY_REGION_ID,
+    regionDigest: sha256(region),
+    rendererVersion: AI_ENTRY_RENDERER_VERSION,
+    createdFile: existing === null || currentEntry?.createdFile === true,
+  };
+  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 result = {
+    action,
+    current: {
+      entry: currentEntry ? structuredClone(currentEntry) : null,
+      contentDigest: existing === null ? null : sha256(existing),
+      region: parsed.region,
+    },
+    proposed: {
+      entry: nextEntry,
+      contentDigest: sha256(nextContent),
+      region,
+    },
+    baselines: {
+      contract: project.contractDigest,
+      projectionsLock: project.projectionsLockDigest,
+      content: existing === null ? null : sha256(existing),
+    },
+    migration: {
+      required: project.projectionsLock.schemaVersion === 1,
+      from: project.projectionsLock.schemaVersion,
+      to: 2,
+      trigger: "publish-entry",
+    },
+    impact: { itemIds: impact.itemIds, sourceIds: impact.sourceIds, paths: [resolved.normalized], projectionPaths: [resolved.normalized], afterSourceDigest: impact.afterDigest },
+    written: false,
+  };
+  if (write && action !== "unchanged") {
+    await commitEntry(project, resolved, existing, nextContent, nextLock, dependencies);
+    result.written = true;
+  }
+  return result;
+}
+
+export async function removeAiEntry(root, project, options, dependencies = {}) {
+  const write = Boolean(options.write);
+  const resolved = await resolveEntryOutput(root, options.output, false);
+  const readContent = dependencies.readFile ?? readIfPresent;
+  const existing = await readContent(resolved.absolute);
+  const parsed = parseAiEntryRegion(existing);
+  const currentEntry = entryLock(project, resolved.normalized);
+  assertEntryOwnership(resolved.normalized, existing, currentEntry, parsed);
+  if (!currentEntry) {
+    return {
+      action: "unchanged",
+      current: { entry: null, contentDigest: existing === null ? null : sha256(existing), region: null },
+      proposed: { entry: null, contentDigest: existing === null ? null : sha256(existing), region: null },
+      baselines: { contract: project.contractDigest, projectionsLock: project.projectionsLockDigest, content: existing === null ? null : sha256(existing) },
+      migration: { required: false, from: project.projectionsLock.schemaVersion, to: project.projectionsLock.schemaVersion, trigger: null },
+      impact: { itemIds: [], sourceIds: [], paths: [resolved.normalized], projectionPaths: [resolved.normalized], afterSourceDigest: null },
+      written: false,
+    };
+  }
+  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 result = {
+    action: "remove",
+    current: { entry: structuredClone(currentEntry), contentDigest: sha256(existing), region: parsed.region },
+    proposed: { entry: null, contentDigest: sha256(nextContent), region: null },
+    baselines: { contract: project.contractDigest, projectionsLock: project.projectionsLockDigest, content: sha256(existing) },
+    migration: { required: false, from: project.projectionsLock.schemaVersion, to: 2, trigger: null },
+    impact: { itemIds: impact.itemIds, sourceIds: impact.sourceIds, paths: [resolved.normalized], projectionPaths: [resolved.normalized], afterSourceDigest: impact.afterDigest },
+    written: false,
+  };
+  if (write) {
+    await commitEntry(project, resolved, existing, nextContent, nextLock, dependencies);
+    result.written = true;
+  }
+  return result;
+}