Adopt reviewed GapSet API contract

Move the CLI onto its 0.2 compatibility line so agents can review the complete canonical GapSet before Compile. Preserve the ordinary response bound while giving Analysis and artifacts generous endpoint-specific limits.

Author: raghubetina

README.md

@@ -4,10 +4,11 @@
 Foundation Plans with their users, then submit a valid Plan for the current bounded compilation and private GitHub
 publication journey.
 
-The current `0.1.x` line includes local Plan initialization, application-key and UUID generation, conditional
+The current `0.2.x` source line includes local Plan initialization, application-key and UUID generation, conditional
 whole-document push, whole-graph analysis polling, compile-and-publish orchestration, and read-only retained
-Compilation download. Remote commands require a compatible First Draft service and are intended for coordinated
-trials; publishing this CLI does not make the wider service generally available.
+Compilation download. Analysis status exposes the complete reviewed GapSet before Compile. Remote commands require
+a compatible First Draft service and are intended for coordinated trials; publishing this CLI does not make the
+wider service generally available.
 
 ## Install
 

RELEASING.md

@@ -36,14 +36,16 @@ binds its Foundation Plan format to the implemented CLI constant.
 
 The `script/release_compatibility_check` evaluator in `firstdraft/firstdraft` reads this declaration with the matching
 declarations from exact, clean checkouts of `firstdraft/firstdraft` and `firstdraft/skills`. It implements SemVer 2.0
-precedence. This CLI requires the service's `0.2.0` API contract because the always-present GitHub Publication
-progress projection is incompatible with the strict response shape accepted by the published
-`@firstdraft.com/cli@0.1.0-alpha.2`. Comparator arrays form one conjunction, while `foundation_plan_formats` lists
-alternatives. A prerelease satisfies a comparator set only when a comparator explicitly names a prerelease with the
-same major, minor, and patch numbers. Skills names the candidate CLI version explicitly, so a stale comparator makes
-the three-repository candidate ineligible. `firstdraft.release-compatibility/1` is intentionally closed. The
-evaluator in `firstdraft/firstdraft` rejects an unrecognized format and unknown keys, so adding a key requires a
-coordinated compatibility-format bump rather than silently changing version 1.
+precedence. CLI `0.2.x` requires the service's `0.3.x` API contract because Analysis now returns the complete reviewed
+GapSet and digest. The released CLI `0.1.0` accepts only API `0.2.x`, uses a generic 2 MiB response bound for Analysis,
+and cannot safely consume every schema-valid API `0.3.x` result. CLI `0.2.x` retains that generic bound but gives
+Analysis and Compilation artifacts dedicated 128 MiB bounds. Comparator arrays form one conjunction, while
+`foundation_plan_formats` lists alternatives. A prerelease satisfies a comparator set only when a comparator
+explicitly names a prerelease with the same major, minor, and patch numbers. Skills names the candidate CLI version
+explicitly, so a stale comparator makes the three-repository candidate ineligible.
+`firstdraft.release-compatibility/1` is intentionally closed. The evaluator in `firstdraft/firstdraft` rejects an
+unrecognized format and unknown keys, so adding a key requires a coordinated compatibility-format bump rather than
+silently changing version 1.
 
 A compatible result establishes candidate eligibility, not authorization or runtime proof. Exact Git SHAs identify
 the three-repository candidate. A merge to `main` is integration only: report the merged SHA and ask the user whether

docs/commands.md

@@ -3,10 +3,10 @@
 This page owns the detailed public semantics of the current command surface. Run `firstdraft --help` or a command
 group's `--help` for concise executable syntax. See [Errors and recovery](errors.md) before retrying a failed mutation.
 
-The current `0.1.x` line contains the auditable command shell, local Foundation Plan initialization, local
+The current `0.2.x` source line contains the auditable command shell, local Foundation Plan initialization, local
 application-key and UUID generation, conditional whole-document push, whole-graph analysis status polling,
-compile-and-publish orchestration, and read-only retained-Compilation download. The current `0.1.0` CLI requires the
-service's `0.2.x` API contract. See the [release policy](../RELEASING.md) for versioning and channel semantics and
+compile-and-publish orchestration, and read-only retained-Compilation download. CLI `0.2.x` requires the service's
+`0.3.x` API contract. See the [release policy](../RELEASING.md) for versioning and channel semantics and
 [release history](release-history.md) for the transition from prereleases.
 
 ## Command map
@@ -116,11 +116,19 @@ or `superseded`. Every validated analysis status is a successful read with exit
 `analysis.status` value and inspect `analysis.diagnostics` rather than treating a completed analysis with issues as
 a transport failure.
 
+The projection includes the exact Head digest, Analyzer and Compiler releases, selected target, and
+`analysis.gap_set` plus `analysis.gap_set_sha256`. A `valid` run always returns the complete parsed canonical
+`firstdraft.foundation-gaps/2` object, including every ordered gap record and an empty `gaps` array when nothing is
+missing. Both GapSet fields are `null` for every other status. The CLI validates the GapSet's Head, Project,
+generation, releases, target, canonical digest, and complete record shapes, then prints the records without
+truncating or rewriting them.
+
 Status reads require the API origin pinned by a successful push. They never select an origin from the current
 environment, expose the private ETag, follow redirects, or modify local state. Each request has a bounded timeout,
-every response is byte-bounded and fully validated, and polling will not silently switch to a replacement analysis.
-The wait repeats only validated `processing` responses and stops on its first failed read. A network failure is safe
-to retry a bounded number of times because the command sends only `GET` requests. See
+ordinary response reads retain a 2 MiB bound, while this potentially gap-heavy response has a dedicated 128 MiB
+bound. Every response is fully validated, and polling will not silently switch to a replacement analysis. The wait
+repeats only validated `processing` responses and stops on its first failed read. A network failure is safe to retry
+a bounded number of times because the command sends only `GET` requests. See
 [read-only failures](errors.md#read-only-status-failures) if the problem persists.
 
 ## Compile and publish the current Plan
@@ -133,10 +141,10 @@ firstdraft plan compile
 
 `plan compile` is the single terminal action. It first pushes the exact current bytes in
 `.firstdraft/foundation-plan.json`, even when those bytes are unchanged, and saves the accepted ETag using the same
-contract as `plan push`. It then waits up to two minutes for an analysis whose graph version exactly matches that
-accepted push, polling past a terminal result retained for an older Head. Invalid JSON, schema diagnostics, semantic
-diagnostics, a failed analysis, a superseded analysis, or a recurring diagnostic stop the command with structured
-output; no Compilation or Publication is requested.
+contract as `plan push`. It then waits up to two minutes for an analysis whose graph version and
+`head_source_sha256` exactly match that accepted push, polling past a terminal result retained for an older Head.
+Invalid JSON, schema diagnostics, semantic diagnostics, a failed analysis, a superseded analysis, or a recurring
+diagnostic stop the command with structured output; no Compilation or Publication is requested.
 
 Only a `valid` analysis proceeds to the internal GitHub Publication lifecycle. Invoking `plan compile` is the
 authorization to request that lifecycle. Immediately before its conditional mutation, the CLI re-reads the local
@@ -152,7 +160,7 @@ URLs, raw server projections, local paths, or environment values. Success writes
 GitHub repository URL plus a newline to stdout. If the command fails after progress has begun, its structured JSON
 error envelope is the final stderr document after the progress lines.
 
-The closed API `0.2.x` progress-reason allowlist is `github.configuration_missing`, `github.oauth_unavailable`,
+The closed API `0.3.x` progress-reason allowlist is `github.configuration_missing`, `github.oauth_unavailable`,
 `github.api_unavailable`, `github.reauthorization_required`, `github.account_mismatch`,
 `github.installation_unavailable`, `github.installation_not_ready`, `github.preflight_unavailable`, the legacy-only
 `github.preflight_unclassified`, and these stage-specific fallbacks: `github.preflight_unavailable.configuration`,
@@ -208,4 +216,5 @@ ETag, exact-byte SHA-256, canonical UTF-8 JSON envelope, provenance, metadata-on
 strict Base64 contents, file digests, modes, owners, and source-subject UUIDs. It writes only into a uniquely created
 sibling directory, verifies the complete tree, and atomically renames it into the still-absent destination. On
 POSIX, directories use mode `0755` and files use artifact-declared `0644` or `0755`; Windows verifies structure,
-contents, and digests without claiming POSIX mode bits.
+contents, and digests without claiming POSIX mode bits. The declared and streamed artifact envelope is bounded at
+128 MiB.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstdraft.com/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Command-line interface for First Draft",
   "license": "MIT",
   "type": "module",

package.json

@@ -1,9 +1,9 @@
 {
   "format": "firstdraft.release-compatibility/1",
   "component": "cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "requires": {
-    "api_contract": [">= 0.2.0", "< 0.3.0"],
+    "api_contract": [">= 0.3.0", "< 0.4.0"],
     "foundation_plan_formats": ["firstdraft.foundation-plan.sketch/0.19"]
   }
 }

release/compatibility.json

@@ -332,6 +332,7 @@ async function exercisePackedCompilation(projectDirectory) {
   );
   const statusPath = `/v1/projects/${projectId}/compilations/${compilationId}`;
   const artifactPath = `${statusPath}/artifact`;
+  const analyzerRelease = "foundation-plan-rails/application-2026-08";
   const compilerRelease = "foundation-plan-rails/compiler-scalar-2026-08";
   const target = { id: "rails", profile: "rails-sketch/2026-08" };
   const contents = Buffer.from("class Movie < ApplicationRecord\nend\n");
@@ -406,14 +407,30 @@ async function exercisePackedCompilation(projectDirectory) {
       completed_at: "2026-07-30T12:00:02.000000Z",
     },
   };
+  const gapSet = {
+    format: "firstdraft.foundation-gaps/2",
+    source: { sha256: headSha256 },
+    project: { id: projectId, graph_version: 1 },
+    analysis: { release: analyzerRelease },
+    compiler_release: compilerRelease,
+    target,
+    gaps: [],
+  };
   const analysis = {
     project: { id: projectId, graph_version: 1 },
     analysis: {
       id: analysisId,
       graph_version: 1,
-      analyzer_release: "foundation-plan-analyzer/2026-08",
+      head_source_sha256: headSha256,
+      analyzer_release: analyzerRelease,
+      compiler_release: compilerRelease,
+      target,
       status: "valid",
       diagnostics: [],
+      gap_set: gapSet,
+      gap_set_sha256: sha256(
+        Buffer.from(`${JSON.stringify(gapSet, null, 2)}\n`),
+      ),
       started_at: "2026-07-30T12:00:00.000Z",
       completed_at: "2026-07-30T12:00:01.000Z",
     },

scripts/smoke-package.js

@@ -36,9 +36,9 @@ export async function sendRequest(fetchFunction, endpoint, request) {
   }
 }
 
-/** @param {Response} response */
-export async function readResponseBody(response) {
-  const bytes = await readResponseBytes(response);
+/** @param {Response} response @param {number} [maximumBytes] */
+export async function readResponseBody(response, maximumBytes) {
+  const bytes = await readResponseBytes(response, maximumBytes);
 
   let text;
   try {

src/api-response.js

@@ -105,6 +105,9 @@ export async function compilePlan({
   const acceptedGraphVersion = /** @type {{graph_version: number}} */ (
     pushed.body.project
   ).graph_version;
+  const acceptedHeadSourceSha256 = /** @type {{source_sha256: string}} */ (
+    pushed.body.foundation_plan
+  ).source_sha256;
 
   let status;
   onProgress({ phase: "analysis", status: "waiting" });
@@ -133,7 +136,8 @@ export async function compilePlan({
   }
   if (
     status.body.project.graph_version !== acceptedGraphVersion ||
-    status.body.analysis.graph_version !== acceptedGraphVersion
+    status.body.analysis.graph_version !== acceptedGraphVersion ||
+    status.body.analysis.head_source_sha256 !== acceptedHeadSourceSha256
   ) {
     throw new PlanStatusChangedError(status.body);
   }