jg-agent-hq 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0
+
+- Publish the consumer-tested package through the configured GitHub Actions trusted publisher before deploying the website. Verify release ordering and archive integrity, and safely skip identical published versions.
+- Support whole-plan approval, execution, completion and revision when no milestone breakdown is needed. Preserve an absent milestone file and require explicit reconciliation when removing a sequence.
+- Keep native thread execution scope on ordinary follow-ups, enforcing revocation and the single implementation owner for whole-plan execution. Preserve explicitly requested, revision-guarded feedback assessment without restoring execution authority. Keep existing-turn permission replies and session renaming separate from new execution admission.
+
 ## 0.2.0
 
 - Preserve coordinator-owned, revision-bound plan comparison evidence through plan operations. Expose its bounded count in status without copying review bodies into responses.

package/README.md

@@ -21,7 +21,7 @@ This public package provides a local controller and browser-safe contracts. Appl
 
 Use pnpm 12.4.0. Run `pnpm install`, then `pnpm check:package` to build, exercise the built API and packed consumer, typecheck and check formatting. `pnpm test:unit` and `pnpm test:integration` select their own categories after a build. The private website workspace has separate checks; install Chromium with `pnpm --dir website exec playwright install chromium`, then run `pnpm --dir website check`. `pnpm check` runs both boundaries.
 
-Work on `development`; reviewed changes reach `main` through a pull request. npm releases are manual and use the exact tested tarball.
+Work on `development`; reviewed changes reach `main` through a pull request. After both Node checks pass on `main`, `check.yml` publishes the exact consumer-tested tarball through npm's configured trusted publisher, then deploys the website. No local npm login or token is needed. An identical published version is skipped; changed contents require a new version.
 
 ## Lock ownership
 
@@ -57,11 +57,11 @@ Use `jg-agent-hq request --state-root <directory>` with a closed HQ command on s
 
 `plan-status --directory <path>` and `plan-milestones --directory <path>` inspect a selected ordinary planning directory. No project registry is required. Mutations use the existing `request` JSON command with `kind: 'plan'`; see the [plan command reference](api/README.md#plan-coordination).
 
-Finalization assigns milestone UUIDs and returns the complete canonical sequence. Plan approval, sequence approval and scoped execution authorization are separate explicit operator actions. None sends native input or answers tool permissions. `coordination.json` holds current records beside the plan. SQLite retains write replay identities and a replaceable, paged milestone projection. Keep both when recovering interrupted writes. A pending write blocks further mutation until its original action is reconciled.
+Finalization assigns milestone UUIDs and returns the complete canonical sequence when a breakdown exists. A plan without a breakdown remains one unit: finalization returns null content, plan approval suffices, and whole-plan execution uses an empty milestone selection with a null milestone ID. No milestone file is created merely to make a small plan executable. Plan approval, sequence approval and scoped execution authorization are separate explicit operator actions. None sends native input or answers tool permissions. `coordination.json` holds current records beside the plan. SQLite retains write replay identities and a replaceable, paged milestone projection. Keep both when recovering interrupted writes. A pending write blocks further mutation until its original action is reconciled.
 
 Coordinators can retain revision-bound compatibility reviews in that same file. Core operations preserve the records without assessing them or granting authority. The integrating coordinator owns review freshness and conflict gates.
 
-Begin a revision before native planning. HQ stops bound implementation threads and their owned background work, captures partial-work evidence, and keeps execution paused while the CLI revises the plan and regenerates milestones. The finalizer carries exact matches automatically and asks for one confirmation covering every unmatched completed or partial milestone. Equivalent rewording preserves the original completion evidence. Changed requirements remain pending. Present and approve the canonical sequence, then explicitly authorize the new execution scope and mode. Neither approval nor restart resumes implementation. See the [revision recovery contract](api/README.md#revision-and-progress-recovery).
+Begin a revision before native planning. HQ stops bound implementation threads and their owned background work, captures partial-work evidence, and keeps execution paused while the CLI revises the plan and regenerates milestones. The finalizer carries exact matches automatically and asks for one confirmation covering every unmatched completed or partial milestone. Equivalent rewording preserves the original completion evidence. Changed requirements remain pending. Present and approve the canonical sequence, then explicitly authorize the new execution scope and mode. Neither approval nor restart resumes implementation. Whole-plan checkpoints and completion evidence also work without a milestone file. Removing a sequence requires explicit confirmation covering its retained milestone evidence before whole-plan execution can begin. See the [revision recovery contract](api/README.md#revision-and-progress-recovery).
 
 ## Cross-provider feedback
 
@@ -87,6 +87,7 @@ Collect one completed reviewer message by its exact native turn/item reference.
 - `src/store/`: SQLite discovery metadata and the action/control ledger in one worker.
 - `src/contracts/`: browser-safe command and response contracts.
 - `scripts/package/`: build-output cleanup and packed-consumer checks.
+- `scripts/release/`: registry version/integrity checks and trusted publication of the tested archive.
 - `scripts/test-support/`: disposable external CLI fixtures.
 - `vitest/`: separate unit and integration selection.
 - `api/README.md`: canonical public API reference.

package/api/README.md

@@ -179,18 +179,20 @@ Send `{ kind: 'plan', command }` through the existing local request API. Every c
 | `reconciliation`  | `target`, `collection: 'sources' \| 'drafts' \| 'evidence' \| 'correspondences'`, optional `limit` (32/128) and `cursor`. Returns retained evidence by indexed seek page.                                                                                |
 | `approve`         | `target`, `action`, `expected`, `scope: 'plan' \| 'sequence'`, `presentationHash`. The hash must match the exact presented plan or finalized sequence. Sequence approval also requires current plan approval.                                            |
 | `revoke`          | `target`, `action`, `expected`, `scope: 'plan' \| 'sequence' \| 'execution' \| 'all'`. Revoking a plan also revokes sequence and execution authority; revoking a sequence also revokes execution authority.                                              |
-| `authorize`       | `target`, `action`, `expected`, `mode: 'supervised' \| 'auto'`, selected unique `milestoneIds`. Records permission for this exact execution scope without starting an agent.                                                                             |
-| `check-execution` | `target`, `expected`, `authorizationId`, `milestoneId`, `mode`. Rejects missing, revoked, stale, wrong-mode or out-of-scope authority. It sends no native input.                                                                                         |
+| `authorize`       | `target`, `action`, `expected`, `mode: 'supervised' \| 'auto'`, selected unique `milestoneIds` (empty only for a plan without a breakdown). Records permission for this exact execution scope without starting an agent.                                 |
+| `check-execution` | `target`, `expected`, `authorizationId`, nullable `milestoneId`, `mode`. Rejects missing, revoked, stale, wrong-mode or out-of-scope authority. It sends no native input.                                                                                |
 
 `expected` is the exact `{ planDigest, breakdownDigest }` returned by inspection. Each mutating `action` has a UUID `id`, `operatorId` and `source: { kind: 'user-action' | 'user-message', reference }`. These are trusted local operator inputs. The module never infers approval from natural-language claims, an agent response or imported feedback. Its owner-only local IPC and files do not isolate hostile code executing as the same OS user. Native permissions remain separate action kinds with their own exact native request identities.
 
+Milestones are optional. Finalizing a plan with no milestone file returns `content: null` and does not create a file. That unit needs plan approval and explicit execution authorization, with `milestoneIds: []`; execution checks, completion and native execution scopes select it with `milestoneId: null`. A real breakdown requires a nonempty selection of its stable IDs and its separate sequence approval. Null cannot select a milestone or bypass sequence approval. Whole-plan completion retains its exact plan contract/digest, actual check references and checkout evidence, with null shared-sequence digest. Completed work cannot be authorized again under that unchanged contract.
+
 A first-use sequence has one `**Milestone ID:** <uuid>` immediately below each `**Status:**` line. Blank lines may separate the heading from its status; no intervening requirement prose is allowed. The initial finalizer rejects duplicate, malformed or misplaced IDs and inconsistent framing. It refreshes existing Overview status rows and returns the complete canonical file for presentation before approval. A changed finalized contract goes through checkpoint reconciliation. A raw or changed sequence cannot inherit finalized status or sequence authority. A done marker remains visible but blocks execution without completion evidence.
 
 The milestone contract includes its stable UUID, title without its ordinal, all requirement prose, shared sequence requirements and the approval statement. Status and identity marker lines are excluded from the prose; only the derived Overview table is excluded from shared text. Prose next to that table remains contractual. Sequence order is significant. Renumbering preserves execution identity; changed requirements, dependencies, scope, reservations or order require applicable approval. Full-file hashes preserve exact UTF-8 bytes and are distinct from normalized execution revisions. Administrative frontmatter excluded by the trusted contract parser, session labels, status advancement and coordination receipts do not change execution digests.
 
 Plan and milestone artifacts are bounded to 1 MiB each; coordination evidence is bounded to 8 MiB and a sequence to 1,024 milestones. Reads do not scan planning trees. Milestone pages use ordinal seek ordering with unique ascending ordinals. Cursors bind the selected directory, page size, execution revisions and exact milestone inspection hash. Any changed artifact requires a fresh page; renumbering or status-only edits still preserve approval. A SQLite projection is rebuilt only when the selected milestone file's full hash changes. Every read verifies its source file; the projection is replaceable and never grants authority.
 
-Mutations hold the shared metadata lock at `<coordinationRoot>/.runtime/hq.lock` (`coordinationRoot` defaults to `stateRoot`), retain a durable action identity and intended write before changing files, sync temporary files and atomically replace each artifact. Use `serve --coordination-root <directory>` when the canonical coordination lock is separate from runtime storage. Repeating an action UUID with the identical payload never reapproves revoked work. A changed payload conflicts. An interrupted write remains blocked and can be retried with its original action only when files match the recorded baseline or exact intended output. Conflicting edits are preserved. Completed write bodies are removed from SQLite while replay identity remains. The current finalization receipt retains the operator event, execution revision, canonical file hash and timestamp independently of write recovery bodies. Status reads expose `pendingActionId` for unresolved writes; they never approve or resume work.
+Mutations hold the shared metadata lock at `<coordinationRoot>/.runtime/hq.lock` (`coordinationRoot` defaults to `stateRoot`), retain a durable action identity and intended write before changing files, sync temporary files and atomically replace each artifact. Use `serve --coordination-root <directory>` when the canonical coordination lock is separate from runtime storage. Repeating an action UUID with the identical payload never reapproves revoked work. A changed payload conflicts. An interrupted write remains blocked and can be retried with its original action only when files match the recorded baseline or exact intended output. Conflicting edits are preserved. Completed write bodies are removed from SQLite while replay identity remains. The current finalization receipt retains the operator event, execution revision, nullable canonical file hash and timestamp independently of write recovery bodies. Status reads expose `pendingActionId` for unresolved writes; they never approve or resume work.
 
 `coordination.json` includes required `comparisons`, an array bounded to 1,024 records validated by `PlanComparisonSchema`. Each record binds `sourceRevision`, `targetDirectory`, `targetRevision`, a `compatible` or `contradiction` verdict, `reason`, `reviewedAt` and reviewer provenance (`provider`, `cliVersion`, nullable observed `model`, and native message `reference`). A trusted coordinator writes these records while holding the same metadata lock. Core operations preserve them; status exposes only `comparisonCount`. They never change execution digests or grant authority. The coordinator owns relevance, freshness, semantic judgments, bounded review reads and any execution gate, including contradictions. The standalone core does not assess compatibility.
 
@@ -202,11 +204,13 @@ Begin revision before invoking a planning skill. Execution admission closes unde
 
 The local host supplies checkout evidence as `{ repository, directory, claimReference, paths }`. Paths are exact relative task paths. The core streams their contents, records link targets without following them, includes missing paths as deletions, and captures the current Git branch/HEAD. It does not stage or reset files and rejects traversal, parent-link escapes, `.git` and excluded archive/backup directories. Check commands and references are trusted operator evidence; this primitive does not execute arbitrary submitted commands or treat an imported agent claim as verification.
 
-After native `jg-plan` removes milestones and native `jg-breakdown` regenerates them, close the planning controller before finalization. Only unique exact normalized title and complete-contract matches retain identity automatically. Every unmatched checkpoint source, including done and partial work, appears in one saved proposal. Confirmation decisions use `sourceIds`, `targetIds`, `relation` (`equivalent`, `requirements-changed`, `omitted`, `reopened`) and explicit one-to-one `retainedPairs`. One source ID cannot be assigned to multiple targets. Grouped decisions retain split/merged evidence. A complete equivalent mapping preserves verified completion or partial status; rewording does not create new checks. A changed requirement gets fresh pending identity. Explicit reopening preserves evidence while invalidating its completion credit. Unverified done markers cannot become verified through an equivalent mapping.
+After native `jg-plan` revises the contract and an explicitly requested `jg-breakdown` regenerates a needed sequence, close the planning controller before finalization. Only unique exact normalized title and complete-contract matches retain identity automatically. Every unmatched checkpoint source, including done and partial work, appears in one saved proposal. Confirmation decisions use `sourceIds`, `targetIds`, `relation` (`equivalent`, `requirements-changed`, `omitted`, `reopened`) and explicit one-to-one `retainedPairs`. One source ID cannot be assigned to multiple targets. Grouped decisions retain split/merged evidence. A complete equivalent mapping preserves verified completion or partial status; rewording does not create new checks. A changed requirement gets fresh pending identity. Explicit reopening preserves evidence while invalidating its completion credit. Unverified done markers cannot become verified through an equivalent mapping.
+
+A whole-plan checkpoint retains null milestones and an empty milestone inventory. If a revision removes a sequence because the remaining scope no longer needs one, every unmatched checkpoint milestone still requires explicit omission confirmation. Its verified evidence remains available; absence alone never resets progress or authorizes whole-plan execution.
 
 The proposal and assigned identities are persisted before the canonical file is replaced. Retry the same action and payload after a partial write; do not regenerate UUIDs or confirm a different proposal. Present the complete canonical output before sequence approval. Applicable plan and sequence approvals are required again after digest changes. Approval does not resume work: send a fresh `authorize` with the intended mode and scope. Execution authority is also bound to the current runtime epoch.
 
-Guided native input adds `plan: { kind: 'execution', authorizationId, milestoneId, mode, revision }` or `{ kind: 'planning', revisionId, invocationId }` to its action envelope. The controller binds this context atomically to the managed thread. Planning starts with the exact authorized native skill. A live thread cannot switch scopes; close it before an explicit resume under a different scope. Queued input retains its original scope and cannot run under stale approval or during revision. Ordinary input on a bound thread remains subject to its current gate. Native permissions are still separate exact-request replies.
+Guided native input adds `plan: { kind: 'execution', authorizationId, milestoneId, mode, revision }` or `{ kind: 'planning', revisionId, invocationId }` to its action envelope. The controller binds this context atomically to the managed thread. Planning starts with the exact authorized native skill. A live thread cannot switch scopes; close it before an explicit resume under a different scope. Queued input retains its original scope and cannot run under stale approval or during revision. Ordinary input on a bound thread retains that exact scope and remains subject to its current gate, including after revocation or completion. It cannot silently become unscoped input. Renaming and explicit replies to an existing native permission/question remain separate, revision-guarded controls; neither starts a new implementation turn or restores execution authority. Native permissions still require the exact pending request.
 
 Selected status/admission/queue observations detect external contract edits or milestone deletion, persist a closed gate and request exact bound-thread interruption. These observations grant no operator authority and report uncertain in-flight effects. The finalized baseline retains identities and completion evidence for explicit reconciliation of direct CLI edits. Invalid artifacts fail explicitly. No directory scan or filesystem watcher is used. Status projects Revising, approval/breakdown requirements, Ready, In progress, Completed and Blocked independently of provider process state.
 
@@ -246,7 +250,7 @@ Creation may still be pending when its response arrives. Read `show` until its c
 
 Collection reads exactly the requested native page through the provider adapter and accepts only one non-truncated agent message from the handoff's completed reviewer turn. Finding bodies are limited to 8 KiB UTF-8, never silently shortened. To select a later page, use the same `limit`, turn filter and preceding cursor as the native items read. A different message or changed body cannot overwrite collected findings. Full histories remain with the native CLIs. Persisted reviewer references retain the exact native session, turn and item identities.
 
-Feedback resolves installed `jg-feedback` in the author thread and carries the selected findings with exact source, reviewer, item, revision and commit references. Source contract or selected Git HEAD changes invalidate an unsent preview. The action's optional `expectedPlan` guards the author's captured revision under the existing plan lock; explicit `null` requires an unbound thread. This guard applies only to `message` and `queue`, grants no execution scope, and cannot answer tool permissions. Known native identities cannot be reassigned; existing control admission preserves the exact author for queued feedback. Existing revision gates pause stale queued feedback. Neither handoff delivery nor a completed assessment turn means recommendations were accepted or implementation was authorized.
+Feedback resolves installed `jg-feedback` in the author thread and carries the selected findings with exact source, reviewer, item, revision and commit references. Source contract or selected Git HEAD changes invalidate an unsent preview. The action's optional `expectedPlan` guards the author's captured revision under the existing plan lock; explicit `null` requires an unbound thread. This guard applies only to `message` and `queue`, grants no execution scope, and cannot answer tool permissions. An explicitly selected native `jg-feedback` skill with a matching `expectedPlan` uses a neutral revision guard, so assessment remains available after execution is revoked or completed. It preserves the thread's existing implementation binding; ordinary input still requires valid execution authority. Queued assessment keeps that same revision guard at automatic or explicit dispatch. Known native identities cannot be reassigned; existing control admission preserves the exact author for queued feedback. Existing revision gates pause stale queued feedback. Neither handoff delivery nor a completed assessment turn means recommendations were accepted or implementation was authorized.
 
 Delivery is `prepared`, `queued`, `submitted`, `delivered`, `uncertain`, `failed` or `canceled`; native `completion` is separately null, `completed`, `failed` or `interrupted`. Acknowledgement alone becomes `delivered`. Busy destinations use native next-turn queues, including while waiting for permissions; feedback is never written as a permission answer. Pending native permissions remain explicit actions on their own channels. No automatic feedback, response loop, approval or publication follows collection.
 

package/dist/contracts/actions/types.d.ts

@@ -112,7 +112,7 @@ export type IActionCommand = z.infer<typeof ActionCommandSchema>;
 export declare const PlanActionScopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"execution">;
     authorizationId: z.ZodUUID;
-    milestoneId: z.ZodUUID;
+    milestoneId: z.ZodNullable<z.ZodUUID>;
     mode: z.ZodEnum<{
         supervised: "supervised";
         auto: "auto";
@@ -132,7 +132,7 @@ export declare const ActionPlanContextSchema: z.ZodObject<{
     scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"execution">;
         authorizationId: z.ZodUUID;
-        milestoneId: z.ZodUUID;
+        milestoneId: z.ZodNullable<z.ZodUUID>;
         mode: z.ZodEnum<{
             supervised: "supervised";
             auto: "auto";
@@ -267,7 +267,7 @@ export declare const ActionEnvelopeSchema: z.ZodObject<{
     plan: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"execution">;
         authorizationId: z.ZodUUID;
-        milestoneId: z.ZodUUID;
+        milestoneId: z.ZodNullable<z.ZodUUID>;
         mode: z.ZodEnum<{
             supervised: "supervised";
             auto: "auto";
@@ -286,7 +286,7 @@ export declare const ActionEnvelopeSchema: z.ZodObject<{
         scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"execution">;
             authorizationId: z.ZodUUID;
-            milestoneId: z.ZodUUID;
+            milestoneId: z.ZodNullable<z.ZodUUID>;
             mode: z.ZodEnum<{
                 supervised: "supervised";
                 auto: "auto";
@@ -354,7 +354,7 @@ export declare const ActionReceiptSchema: z.ZodObject<{
         scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"execution">;
             authorizationId: z.ZodUUID;
-            milestoneId: z.ZodUUID;
+            milestoneId: z.ZodNullable<z.ZodUUID>;
             mode: z.ZodEnum<{
                 supervised: "supervised";
                 auto: "auto";
@@ -430,7 +430,7 @@ export declare const ActionSummarySchema: z.ZodObject<{
         scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"execution">;
             authorizationId: z.ZodUUID;
-            milestoneId: z.ZodUUID;
+            milestoneId: z.ZodNullable<z.ZodUUID>;
             mode: z.ZodEnum<{
                 supervised: "supervised";
                 auto: "auto";

package/dist/contracts/actions/types.js

@@ -78,7 +78,7 @@ export const PlanActionScopeSchema = z.discriminatedUnion('kind', [
     z.strictObject({
         kind: z.literal('execution'),
         authorizationId: z.uuid(),
-        milestoneId: z.uuid(),
+        milestoneId: z.uuid().nullable(),
         mode: z.enum(['supervised', 'auto']),
         revision: PlanRevisionSchema,
     }),

package/dist/contracts/handoffs/types.d.ts

@@ -12,7 +12,7 @@ export declare const HandoffSourceSchema: z.ZodObject<{
         scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"execution">;
             authorizationId: z.ZodUUID;
-            milestoneId: z.ZodUUID;
+            milestoneId: z.ZodNullable<z.ZodUUID>;
             mode: z.ZodEnum<{
                 supervised: "supervised";
                 auto: "auto";
@@ -126,7 +126,7 @@ export declare const HandoffSummarySchema: z.ZodObject<{
             scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"execution">;
                 authorizationId: z.ZodUUID;
-                milestoneId: z.ZodUUID;
+                milestoneId: z.ZodNullable<z.ZodUUID>;
                 mode: z.ZodEnum<{
                     supervised: "supervised";
                     auto: "auto";
@@ -229,7 +229,7 @@ export declare const HandoffSchema: z.ZodObject<{
             scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"execution">;
                 authorizationId: z.ZodUUID;
-                milestoneId: z.ZodUUID;
+                milestoneId: z.ZodNullable<z.ZodUUID>;
                 mode: z.ZodEnum<{
                     supervised: "supervised";
                     auto: "auto";
@@ -363,7 +363,7 @@ export declare const HandoffResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                     kind: z.ZodLiteral<"execution">;
                     authorizationId: z.ZodUUID;
-                    milestoneId: z.ZodUUID;
+                    milestoneId: z.ZodNullable<z.ZodUUID>;
                     mode: z.ZodEnum<{
                         supervised: "supervised";
                         auto: "auto";
@@ -496,7 +496,7 @@ export declare const HandoffResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 scope: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
                     kind: z.ZodLiteral<"execution">;
                     authorizationId: z.ZodUUID;
-                    milestoneId: z.ZodUUID;
+                    milestoneId: z.ZodNullable<z.ZodUUID>;
                     mode: z.ZodEnum<{
                         supervised: "supervised";
                         auto: "auto";

package/dist/contracts/plans/types.d.ts

@@ -81,7 +81,7 @@ export declare const PlanCompletionSchema: z.ZodObject<{
             reference: z.ZodString;
         }, z.core.$strict>;
     }, z.core.$strict>;
-    milestoneId: z.ZodUUID;
+    milestoneId: z.ZodNullable<z.ZodUUID>;
     revision: z.ZodObject<{
         planDigest: z.ZodString;
         breakdownDigest: z.ZodNullable<z.ZodString>;
@@ -89,7 +89,7 @@ export declare const PlanCompletionSchema: z.ZodObject<{
     contractDigest: z.ZodString;
     title: z.ZodString;
     contract: z.ZodString;
-    sharedDigest: z.ZodString;
+    sharedDigest: z.ZodNullable<z.ZodString>;
     checkouts: z.ZodArray<z.ZodObject<{
         repository: z.ZodString;
         directory: z.ZodString;
@@ -128,7 +128,7 @@ export declare const PlanCheckpointSchema: z.ZodObject<{
         breakdownDigest: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>;
     plan: z.ZodString;
-    milestones: z.ZodString;
+    milestones: z.ZodNullable<z.ZodString>;
     entries: z.ZodArray<z.ZodObject<{
         ordinal: z.ZodNumber;
         title: z.ZodString;
@@ -192,7 +192,7 @@ export declare const PlanProposalSchema: z.ZodObject<{
         planDigest: z.ZodString;
         breakdownDigest: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>;
-    inspectionHash: z.ZodString;
+    inspectionHash: z.ZodNullable<z.ZodString>;
     drafts: z.ZodArray<z.ZodObject<{
         ordinal: z.ZodNumber;
         title: z.ZodString;
@@ -285,7 +285,7 @@ export declare const PlanRevisionWorkflowSchema: z.ZodObject<{
             breakdownDigest: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>;
         plan: z.ZodString;
-        milestones: z.ZodString;
+        milestones: z.ZodNullable<z.ZodString>;
         entries: z.ZodArray<z.ZodObject<{
             ordinal: z.ZodNumber;
             title: z.ZodString;
@@ -335,7 +335,7 @@ export declare const PlanRevisionWorkflowSchema: z.ZodObject<{
             planDigest: z.ZodString;
             breakdownDigest: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>;
-        inspectionHash: z.ZodString;
+        inspectionHash: z.ZodNullable<z.ZodString>;
         drafts: z.ZodArray<z.ZodObject<{
             ordinal: z.ZodNumber;
             title: z.ZodString;
@@ -482,7 +482,7 @@ export declare const PlanCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strict>;
     kind: z.ZodLiteral<"finalize">;
 }, z.core.$strict>, z.ZodObject<{
-    milestoneId: z.ZodUUID;
+    milestoneId: z.ZodNullable<z.ZodUUID>;
     checks: z.ZodArray<z.ZodObject<{
         command: z.ZodString;
         outcome: z.ZodLiteral<"passed">;
@@ -668,7 +668,7 @@ export declare const PlanCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         breakdownDigest: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>;
     authorizationId: z.ZodUUID;
-    milestoneId: z.ZodUUID;
+    milestoneId: z.ZodNullable<z.ZodUUID>;
     mode: z.ZodEnum<{
         supervised: "supervised";
         auto: "auto";
@@ -757,7 +757,7 @@ export declare const PlanFinalizationSchema: z.ZodObject<{
         planDigest: z.ZodString;
         breakdownDigest: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>;
-    fileHash: z.ZodString;
+    fileHash: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodNumber;
 }, z.core.$strict>;
 export declare const PlanComparisonSchema: z.ZodObject<{
@@ -831,7 +831,7 @@ export declare const PlanCoordinationSchema: z.ZodObject<{
             planDigest: z.ZodString;
             breakdownDigest: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>;
-        fileHash: z.ZodString;
+        fileHash: z.ZodNullable<z.ZodString>;
         createdAt: z.ZodNumber;
     }, z.core.$strict>>;
     planApproval: z.ZodNullable<z.ZodObject<{
@@ -943,7 +943,7 @@ export declare const PlanCoordinationSchema: z.ZodObject<{
                 reference: z.ZodString;
             }, z.core.$strict>;
         }, z.core.$strict>;
-        milestoneId: z.ZodUUID;
+        milestoneId: z.ZodNullable<z.ZodUUID>;
         revision: z.ZodObject<{
             planDigest: z.ZodString;
             breakdownDigest: z.ZodNullable<z.ZodString>;
@@ -951,7 +951,7 @@ export declare const PlanCoordinationSchema: z.ZodObject<{
         contractDigest: z.ZodString;
         title: z.ZodString;
         contract: z.ZodString;
-        sharedDigest: z.ZodString;
+        sharedDigest: z.ZodNullable<z.ZodString>;
         checkouts: z.ZodArray<z.ZodObject<{
             repository: z.ZodString;
             directory: z.ZodString;
@@ -1065,7 +1065,7 @@ export declare const PlanCoordinationSchema: z.ZodObject<{
                 breakdownDigest: z.ZodNullable<z.ZodString>;
             }, z.core.$strict>;
             plan: z.ZodString;
-            milestones: z.ZodString;
+            milestones: z.ZodNullable<z.ZodString>;
             entries: z.ZodArray<z.ZodObject<{
                 ordinal: z.ZodNumber;
                 title: z.ZodString;
@@ -1115,7 +1115,7 @@ export declare const PlanCoordinationSchema: z.ZodObject<{
                 planDigest: z.ZodString;
                 breakdownDigest: z.ZodNullable<z.ZodString>;
             }, z.core.$strict>;
-            inspectionHash: z.ZodString;
+            inspectionHash: z.ZodNullable<z.ZodString>;
             drafts: z.ZodArray<z.ZodObject<{
                 ordinal: z.ZodNumber;
                 title: z.ZodString;
@@ -1168,7 +1168,7 @@ export declare const PlanCoordinationSchema: z.ZodObject<{
             breakdownDigest: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>;
         plan: z.ZodString;
-        milestones: z.ZodString;
+        milestones: z.ZodNullable<z.ZodString>;
         entries: z.ZodArray<z.ZodObject<{
             ordinal: z.ZodNumber;
             title: z.ZodString;
@@ -1269,7 +1269,7 @@ export declare const PlanCoordinationSummarySchema: z.ZodObject<{
             planDigest: z.ZodString;
             breakdownDigest: z.ZodNullable<z.ZodString>;
         }, z.core.$strict>;
-        fileHash: z.ZodString;
+        fileHash: z.ZodNullable<z.ZodString>;
         createdAt: z.ZodNumber;
     }, z.core.$strict>>;
     planApproval: z.ZodNullable<z.ZodObject<{
@@ -1486,7 +1486,7 @@ export declare const PlanStatusSchema: z.ZodObject<{
                 planDigest: z.ZodString;
                 breakdownDigest: z.ZodNullable<z.ZodString>;
             }, z.core.$strict>;
-            fileHash: z.ZodString;
+            fileHash: z.ZodNullable<z.ZodString>;
             createdAt: z.ZodNumber;
         }, z.core.$strict>>;
         planApproval: z.ZodNullable<z.ZodObject<{
@@ -1716,7 +1716,7 @@ export declare const PlanReconciliationEntrySchema: z.ZodDiscriminatedUnion<[z.Z
                 reference: z.ZodString;
             }, z.core.$strict>;
         }, z.core.$strict>;
-        milestoneId: z.ZodUUID;
+        milestoneId: z.ZodNullable<z.ZodUUID>;
         revision: z.ZodObject<{
             planDigest: z.ZodString;
             breakdownDigest: z.ZodNullable<z.ZodString>;
@@ -1724,7 +1724,7 @@ export declare const PlanReconciliationEntrySchema: z.ZodDiscriminatedUnion<[z.Z
         contractDigest: z.ZodString;
         title: z.ZodString;
         contract: z.ZodString;
-        sharedDigest: z.ZodString;
+        sharedDigest: z.ZodNullable<z.ZodString>;
         checkouts: z.ZodArray<z.ZodObject<{
             repository: z.ZodString;
             directory: z.ZodString;
@@ -1871,7 +1871,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     planDigest: z.ZodString;
                     breakdownDigest: z.ZodNullable<z.ZodString>;
                 }, z.core.$strict>;
-                fileHash: z.ZodString;
+                fileHash: z.ZodNullable<z.ZodString>;
                 createdAt: z.ZodNumber;
             }, z.core.$strict>>;
             planApproval: z.ZodNullable<z.ZodObject<{
@@ -2091,7 +2091,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     planDigest: z.ZodString;
                     breakdownDigest: z.ZodNullable<z.ZodString>;
                 }, z.core.$strict>;
-                fileHash: z.ZodString;
+                fileHash: z.ZodNullable<z.ZodString>;
                 createdAt: z.ZodNumber;
             }, z.core.$strict>>;
             planApproval: z.ZodNullable<z.ZodObject<{
@@ -2279,7 +2279,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                         reference: z.ZodString;
                     }, z.core.$strict>;
                 }, z.core.$strict>;
-                milestoneId: z.ZodUUID;
+                milestoneId: z.ZodNullable<z.ZodUUID>;
                 revision: z.ZodObject<{
                     planDigest: z.ZodString;
                     breakdownDigest: z.ZodNullable<z.ZodString>;
@@ -2287,7 +2287,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 contractDigest: z.ZodString;
                 title: z.ZodString;
                 contract: z.ZodString;
-                sharedDigest: z.ZodString;
+                sharedDigest: z.ZodNullable<z.ZodString>;
                 checkouts: z.ZodArray<z.ZodObject<{
                     repository: z.ZodString;
                     directory: z.ZodString;
@@ -2435,7 +2435,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     planDigest: z.ZodString;
                     breakdownDigest: z.ZodNullable<z.ZodString>;
                 }, z.core.$strict>;
-                fileHash: z.ZodString;
+                fileHash: z.ZodNullable<z.ZodString>;
                 createdAt: z.ZodNumber;
             }, z.core.$strict>>;
             planApproval: z.ZodNullable<z.ZodObject<{
@@ -2574,7 +2574,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>;
     }, z.core.$strip>;
-    content: z.ZodString;
+    content: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"milestones">;
     result: z.ZodObject<{

package/dist/contracts/plans/types.js

@@ -64,12 +64,12 @@ export const PlanWorktreeProofSchema = PlanCheckoutSchema.extend({
 export const PlanCompletionSchema = z.strictObject({
     id: z.uuid(),
     action: PlanOperatorActionSchema,
-    milestoneId: z.uuid(),
+    milestoneId: z.uuid().nullable(),
     revision: PlanRevisionSchema,
     contractDigest: PlanDigestSchema,
     title: z.string().min(1).max(4096),
     contract: z.string().max(1_048_576),
-    sharedDigest: PlanDigestSchema,
+    sharedDigest: PlanDigestSchema.nullable(),
     checkouts: z.array(PlanWorktreeProofSchema).max(128),
     checks: z.array(PlanCheckSchema).min(1).max(32),
     completedAt: z.number().int(),
@@ -84,7 +84,7 @@ export const PlanSnapshotMilestoneSchema = PlanMilestoneSchema.extend({
 export const PlanCheckpointSchema = z.strictObject({
     revision: PlanRevisionSchema,
     plan: z.string().max(1_048_576),
-    milestones: z.string().max(1_048_576),
+    milestones: z.string().max(1_048_576).nullable(),
     entries: z.array(PlanSnapshotMilestoneSchema).max(1024),
     checkouts: z.array(PlanWorktreeProofSchema).max(128),
     threadIds: z.array(z.uuid()).max(32),
@@ -111,7 +111,7 @@ export const PlanDraftMilestoneSchema = PlanSnapshotMilestoneSchema.extend({
 export const PlanProposalSchema = z.strictObject({
     id: z.uuid(),
     revision: PlanRevisionSchema,
-    inspectionHash: PlanDigestSchema,
+    inspectionHash: PlanDigestSchema.nullable(),
     drafts: z.array(PlanDraftMilestoneSchema).max(1024),
     unmatchedSourceIds: z.array(z.uuid()).max(1024),
     confirmation: z
@@ -193,7 +193,7 @@ export const PlanCommandSchema = z.discriminatedUnion('kind', [
     z.strictObject({
         kind: z.literal('complete'),
         ...MutationFields,
-        milestoneId: z.uuid(),
+        milestoneId: z.uuid().nullable(),
         checks: z.array(PlanCheckSchema).min(1).max(32),
         checkouts: z.array(PlanCheckoutSchema).max(128),
     }),
@@ -234,7 +234,6 @@ export const PlanCommandSchema = z.discriminatedUnion('kind', [
         mode: z.enum(['supervised', 'auto']),
         milestoneIds: z
             .array(z.uuid())
-            .min(1)
             .max(1024)
             .refine((ids) => new Set(ids).size === ids.length),
     }),
@@ -243,7 +242,7 @@ export const PlanCommandSchema = z.discriminatedUnion('kind', [
         target: PlanTargetSchema,
         expected: PlanRevisionSchema,
         authorizationId: z.uuid(),
-        milestoneId: z.uuid(),
+        milestoneId: z.uuid().nullable(),
         mode: z.enum(['supervised', 'auto']),
     }),
 ]);
@@ -259,7 +258,7 @@ export const PlanExecutionSchema = z.strictObject({
     action: PlanOperatorActionSchema,
     revision: PlanRevisionSchema,
     mode: z.enum(['supervised', 'auto']),
-    milestoneIds: z.array(z.uuid()).min(1).max(1024),
+    milestoneIds: z.array(z.uuid()).max(1024),
     createdAt: z.number().int(),
     revokedBy: PlanOperatorActionSchema.nullable(),
 });
@@ -267,7 +266,7 @@ export const PlanExecutionSchema = z.strictObject({
 export const PlanFinalizationSchema = z.strictObject({
     action: PlanOperatorActionSchema,
     revision: PlanRevisionSchema,
-    fileHash: PlanDigestSchema,
+    fileHash: PlanDigestSchema.nullable(),
     createdAt: z.number().int(),
 });
 // coordinators own semantic review; the core preserves its exact revision-bound evidence
@@ -385,7 +384,7 @@ export const PlanResultSchema = z.discriminatedUnion('kind', [
     z.object({
         kind: z.literal('finalized'),
         result: PlanStatusSchema,
-        content: z.string().max(1_048_576),
+        content: z.string().max(1_048_576).nullable(),
     }),
     z.object({
         kind: z.literal('milestones'),