frontend-project-context 1.2.0 → 1.3.0

package/schemas/stage-receipt.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:stage-receipt:1",
+  "title": "Frontend Project Context Stage Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "projectId", "taskId", "stageId", "planDigest", "inputBundleDigest", "status", "changedPaths", "acceptanceResults", "verificationResults", "decisions", "openIssues"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "stage-receipt" },
+    "projectId": { "$ref": "#/$defs/id" },
+    "taskId": { "$ref": "#/$defs/id" },
+    "stageId": { "$ref": "#/$defs/id" },
+    "planDigest": { "$ref": "#/$defs/digest" },
+    "inputBundleDigest": { "$ref": "#/$defs/digest" },
+    "status": { "enum": ["completed", "blocked"] },
+    "changedPaths": { "$ref": "#/$defs/paths" },
+    "acceptanceResults": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "evidence"],
+        "properties": {
+          "id": { "$ref": "#/$defs/id" },
+          "status": { "enum": ["observed", "not-observed"] },
+          "evidence": { "$ref": "#/$defs/paths" }
+        }
+      }
+    },
+    "verificationResults": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "summary", "evidence"],
+        "properties": {
+          "id": { "$ref": "#/$defs/id" },
+          "status": { "enum": ["passed", "failed", "observed", "skipped"] },
+          "summary": { "type": "string", "minLength": 1 },
+          "evidence": { "$ref": "#/$defs/paths" }
+        }
+      }
+    },
+    "decisions": { "$ref": "#/$defs/texts" },
+    "openIssues": { "$ref": "#/$defs/texts" },
+    "nextStageId": { "$ref": "#/$defs/id" }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "paths": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "texts": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+  }
+}

package/schemas/task-context-plan.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:task-context-plan:1",
+  "title": "Frontend Project Context Task Context Plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "projectId", "task", "workspace", "snapshots", "budget", "stages"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "task-context-plan" },
+    "projectId": { "$ref": "#/$defs/id" },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "goal", "acceptance"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "$ref": "#/$defs/text" },
+        "goal": { "$ref": "#/$defs/text" },
+        "acceptance": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "text"],
+            "properties": { "id": { "$ref": "#/$defs/id" }, "text": { "$ref": "#/$defs/text" } }
+          }
+        }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["branchLabel", "baseRevision"],
+      "properties": { "branchLabel": { "$ref": "#/$defs/text" }, "baseRevision": { "$ref": "#/$defs/text" } }
+    },
+    "snapshots": { "$ref": "#/$defs/snapshots" },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maxUtf8Bytes", "maxReadTargets"],
+      "properties": {
+        "maxUtf8Bytes": { "type": "integer", "minimum": 1 },
+        "maxReadTargets": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "objective", "dependsOn", "paths", "acceptanceIds"],
+        "properties": {
+          "id": { "$ref": "#/$defs/id" },
+          "title": { "$ref": "#/$defs/text" },
+          "objective": { "$ref": "#/$defs/text" },
+          "dependsOn": { "$ref": "#/$defs/ids" },
+          "paths": { "$ref": "#/$defs/paths" },
+          "acceptanceIds": { "$ref": "#/$defs/nonEmptyIds" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+    "text": { "type": "string", "minLength": 1 },
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "path": { "type": "string", "minLength": 1 },
+    "ids": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+    "nonEmptyIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+    "paths": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/path" } },
+    "snapshots": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contract", "sourcesLock", "projectionsLock"],
+      "properties": {
+        "contract": { "$ref": "#/$defs/digest" },
+        "sourcesLock": { "$ref": "#/$defs/digest" },
+        "projectionsLock": { "$ref": "#/$defs/digest" }
+      }
+    }
+  }
+}

package/src/project-context/capabilities.mjs

@@ -0,0 +1,74 @@
+import { ASSIST_BUNDLE_SCHEMA_VERSION } from "./assist.mjs";
+import { DASHBOARD_SCHEMA_VERSION } from "./dashboard-model.mjs";
+import {
+  ACTION_KINDS,
+  ACTION_PLAN_SCHEMA_VERSION,
+  CAPABILITIES_SCHEMA_VERSION,
+  COMMANDS,
+  EXCHANGE_PROTOCOL_VERSION,
+  PACKAGE_VERSION,
+  REVIEW_BUNDLE_SCHEMA_VERSION,
+} from "./exchange-schema.mjs";
+import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
+import { RENDERER_VERSION } from "./renderer.mjs";
+import {
+  CONTEXT_BUDGET_UNIT,
+  INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+  STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+  STAGE_RECEIPT_SCHEMA_VERSION,
+  TASK_CONTEXT_PLAN_SCHEMA_VERSION,
+} from "./task-context-schema.mjs";
+
+function schemas() {
+  return {
+    actionPlan: ACTION_PLAN_SCHEMA_VERSION,
+    assistBundle: ASSIST_BUNDLE_SCHEMA_VERSION,
+    capabilities: CAPABILITIES_SCHEMA_VERSION,
+    contract: 2,
+    dashboardViewModel: DASHBOARD_SCHEMA_VERSION,
+    integrationReviewBundle: INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+    projectionLock: 1,
+    projectionRenderer: RENDERER_VERSION,
+    proposal: 1,
+    reviewBundle: REVIEW_BUNDLE_SCHEMA_VERSION,
+    sourceLock: 1,
+    stageContextBundle: STAGE_CONTEXT_BUNDLE_SCHEMA_VERSION,
+    stageReceipt: STAGE_RECEIPT_SCHEMA_VERSION,
+    taskContextPlan: TASK_CONTEXT_PLAN_SCHEMA_VERSION,
+  };
+}
+
+export async function buildCapabilities(root) {
+  const initialization = await inspectProjectInitialization(root);
+  let project = null;
+  if (initialization.status === "initialized") {
+    const loaded = await loadProject(root);
+    project = { id: loaded.contract.project.id, name: loaded.contract.project.name };
+  }
+  return {
+    schemaVersion: CAPABILITIES_SCHEMA_VERSION,
+    package: { name: "frontend-project-context", version: PACKAGE_VERSION },
+    exchangeProtocolVersion: EXCHANGE_PROTOCOL_VERSION,
+    schemas: schemas(),
+    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,
+    },
+  };
+}

package/src/project-context/cli.mjs

@@ -16,6 +16,7 @@ import { normalizeRelativePath, resolveExistingInside, resolveProjectRoot, resol
 import { initializeProject, inspectProjectInitialization, loadProject } from "./project-store.mjs";
 import { publishProjection } from "./projection-store.mjs";
 import { renderContextBundle } from "./renderer.mjs";
+import { buildIntegrationReviewBundleFiles, buildStageContextBundleFiles } from "./task-context.mjs";
 
 const HELP = `project-context — model-neutral project contract compiler
 
@@ -38,6 +39,8 @@ Usage:
   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...] [--changed-path RELATIVE_PATH...] [--json]
+  project-context integration-review --project PATH --plan FILE [--receipt FILE...] [--main-changed-path RELATIVE_PATH...] [--branch-changed-path RELATIVE_PATH...] [--json]
 
 All commands are read-only unless their own --write flag is present.
 `;
@@ -45,9 +48,11 @@ 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",
+  "expected-digest", "expected-item-digest", "expected-source-digest", "locale", "plan", "stage",
+]);
+const LIST_FLAGS = new Set([
+  "ids", "path", "changed-path", "sources", "overrides", "affected-items", "receipt", "main-changed-path", "branch-changed-path",
 ]);
-const LIST_FLAGS = new Set(["ids", "path", "changed-path", "sources", "overrides", "affected-items"]);
 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"])],
@@ -81,6 +86,8 @@ const COMMAND_OPTIONS = new Map([
   ["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", "changed-path", "json", "help"])],
+  ["integration-review", new Set(["project", "plan", "receipt", "main-changed-path", "branch-changed-path", "json", "help"])],
 ]);
 
 export function parseArgs(argv) {
@@ -330,6 +337,24 @@ async function runCommand(command, options) {
     const summary = `Preflight ${bundle.status}: ${bundle.summary.reviewable} reviewable, ${bundle.summary.blocked} blocked action(s).\n`;
     return { exitCode: bundle.status === "reviewable" ? 0 : 1, stdout: jsonOrText(options, bundle, summary), stderr: "" };
   }
+  if (command === "stage-context") {
+    const bundle = await buildStageContextBundleFiles(root, required(options, "plan"), {
+      stageId: required(options, "stage"),
+      receiptPaths: options.receipt ?? [],
+      changedPaths: options["changed-path"] ?? [],
+    });
+    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 === "integration-review") {
+    const bundle = await buildIntegrationReviewBundleFiles(root, required(options, "plan"), {
+      receiptPaths: options.receipt ?? [],
+      mainChangedPaths: options["main-changed-path"] ?? [],
+      branchChangedPaths: options["branch-changed-path"] ?? [],
+    });
+    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: "" };
+  }
   const project = await loadProject(root);
   if (command === "register") {
     const result = await registerSource(root, project, {

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

@@ -2,7 +2,7 @@ import { canonicalValue, digestJson, validateJsonValue } from "./canonical-json.
 import { fail } from "./errors.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 
-export const PACKAGE_VERSION = "1.2.0";
+export const PACKAGE_VERSION = "1.3.0";
 export const EXCHANGE_PROTOCOL_VERSION = 1;
 export const ACTION_PLAN_SCHEMA_VERSION = 1;
 export const REVIEW_BUNDLE_SCHEMA_VERSION = 1;
@@ -21,8 +21,8 @@ export const ACTION_KINDS = Object.freeze([
 
 export const COMMANDS = Object.freeze([
   "accept-source-change", "approve", "capabilities", "check", "context", "dashboard", "deprecate",
-  "deprecate-source", "discover", "init", "preflight", "propose", "publish", "register", "review-source",
-  "revise", "setup", "sync",
+  "deprecate-source", "discover", "init", "integration-review", "preflight", "propose", "publish", "register",
+  "review-source", "revise", "setup", "stage-context", "sync",
 ]);
 
 const ACTION_KIND_SET = new Set(ACTION_KINDS);

package/src/project-context/exchange.mjs

@@ -3,17 +3,10 @@ import { approvePendingItems, approveProposal } from "./approver.mjs";
 import { registerSource, buildItemProposal } from "./authoring.mjs";
 import { blockingContextFindings, checkProject } from "./checker.mjs";
 import { canonicalJson, digestJson, prettyCanonicalJson, sha256 } from "./canonical-json.mjs";
-import { DASHBOARD_SCHEMA_VERSION } from "./dashboard-model.mjs";
 import { ProjectContextError, fail } from "./errors.mjs";
 import {
-  ACTION_KINDS,
-  ACTION_PLAN_SCHEMA_VERSION,
   assertActionPlanConflictFree,
-  CAPABILITIES_SCHEMA_VERSION,
-  COMMANDS,
-  EXCHANGE_PROTOCOL_VERSION,
   itemPrimitiveInput,
-  PACKAGE_VERSION,
   REVIEW_BUNDLE_SCHEMA_VERSION,
   validateActionPlan,
   validateReviewBundle,
@@ -21,17 +14,12 @@ import {
 import { readJsonFile } from "./io.mjs";
 import { acceptSourceChange, deprecateItem, deprecateSource, reviewSource, reviseItem } from "./maintenance.mjs";
 import { resolveExistingInside, resolveWritableInside } from "./path-policy.mjs";
-import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
+import { loadProject } from "./project-store.mjs";
 import { publishProjection } from "./projection-store.mjs";
-import { RENDERER_VERSION } from "./renderer.mjs";
-import { ASSIST_BUNDLE_SCHEMA_VERSION } from "./assist.mjs";
+export { buildCapabilities } from "./capabilities.mjs";
 
 const INTERNAL_AUTHORITY_SENTINEL = "exchange-preflight-not-authority";
 const INTERNAL_TIMESTAMP = "1970-01-01T00:00:00.000Z";
-const CONTRACT_SCHEMA_VERSION = 2;
-const PROPOSAL_SCHEMA_VERSION = 1;
-const SOURCE_LOCK_SCHEMA_VERSION = 1;
-const PROJECTION_LOCK_SCHEMA_VERSION = 1;
 const GROUP_BY_ACTION = new Map([
   ["accept-source-change", "source-change"],
   ["register-source", "source-change"],
@@ -47,52 +35,6 @@ function uniqueSorted(values) {
   return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
 
-function schemas() {
-  return {
-    actionPlan: ACTION_PLAN_SCHEMA_VERSION,
-    assistBundle: ASSIST_BUNDLE_SCHEMA_VERSION,
-    capabilities: CAPABILITIES_SCHEMA_VERSION,
-    contract: CONTRACT_SCHEMA_VERSION,
-    dashboardViewModel: DASHBOARD_SCHEMA_VERSION,
-    projectionLock: PROJECTION_LOCK_SCHEMA_VERSION,
-    projectionRenderer: RENDERER_VERSION,
-    proposal: PROPOSAL_SCHEMA_VERSION,
-    reviewBundle: REVIEW_BUNDLE_SCHEMA_VERSION,
-    sourceLock: SOURCE_LOCK_SCHEMA_VERSION,
-  };
-}
-
-export async function buildCapabilities(root) {
-  const initialization = await inspectProjectInitialization(root);
-  let project = null;
-  if (initialization.status === "initialized") {
-    const loaded = await loadProject(root);
-    project = { id: loaded.contract.project.id, name: loaded.contract.project.name };
-  }
-  return {
-    schemaVersion: CAPABILITIES_SCHEMA_VERSION,
-    package: { name: "frontend-project-context", version: PACKAGE_VERSION },
-    exchangeProtocolVersion: EXCHANGE_PROTOCOL_VERSION,
-    schemas: schemas(),
-    commands: [...COMMANDS],
-    actionKinds: [...ACTION_KINDS],
-    initialization: initialization.status,
-    initialized: initialization.status === "initialized",
-    project,
-    boundaries: {
-      provider: false,
-      agentRuntime: false,
-      git: false,
-      network: false,
-      dependencyInstallation: false,
-      automaticApproval: false,
-      businessCodeWrites: false,
-      applyPlan: false,
-      scheduler: false,
-      daemon: false,
-    },
-  };
-}
 
 function allProjectionPaths(project) {
   return project.projectionsLock.projections.map((entry) => entry.path).sort();