Module plan 

plan.json v3 — serde types + structural validator (design.md §4, §7, §13).

plan.json is the interface contract the spec-node writes and the supervisor + orchestrator read. It is immutable per revision, versioned, and provenance-bearing. This module provides:

• The serde Plan type (and its parts) mirroring plan-schema.md v3.
• A structural validate_plan / parse_and_validate_plan pass that rejects a bad plan with a domain-typed PlanValidationError (the CLI maps these to its schema_violation envelope at the boundary, exactly as it does for crate::report::ReportValidationError).
• PLAN_V3_JSON_SCHEMA, the checked-in JSON Schema artifact, so external readers/writers validate against a single source of truth. A drift-guard test keeps the Rust types and the JSON Schema in agreement.

v3: baseline provenance is structurally required

v3 promotes the three baseline provenance fields — commit_oid, toolchain, and enumerated_targets_hash — from additive-optional (#[serde(default)] in v2) to required, so a plan that carries no provenance can never be certified. The requirement is enforced in two layers: a document that omits a field fails to deserialize (PlanValidationError::Malformed, because the fields carry no serde default), and one that carries a blank field is rejected by validate_plan (PROVENANCE_REQUIRED_SCHEMA, PlanValidationError::EmptyString) — the same two-layer treatment the other required baseline strings get. This is only the structural half: it proves the evidence is present and non-blank, not that it is well-formed or authentic. The runtime fail-closed gate (verify_plan_baseline / gate_plan_baseline in the CLI) is the other half — it checks the values match the live snapshot (and validates the OID shape + toolchain there).

Compatibility semantics (design.md §13, plan-schema.md “Principles”)

schema_version gates the file with real compatibility semantics — this is not “ignore everything unknown”:

• Readers reject unsupported major versions (SUPPORTED_PLAN_SCHEMAS).
• Readers reject undeclared fields — any key not in the v3 shape is a rejection. On the map-like objects (plan, feature, baseline, chunks[], chunks[].checks[]) this is PlanValidationError::UnknownField, gated by a per-object-shape allowlist ([tolerated_fields]): a field ratified as additive on one shape is tolerated there and nowhere else. On acceptance[] items (a tagged enum) it is a deny_unknown_fields deserialization error (PlanValidationError::Malformed) — the same stance the JSON Schema takes, with no additive seam in v3. The allowlists are empty in v3, so every unknown key is currently rejected; a future minor registers an additive optional field against its shape (and in the JSON Schema) so older readers tolerate it, and only then. Schema growth otherwise goes gap-event → reviewed proposal → versioned schema.

This module is read-only + validation types. It does not touch the reducer, the lock layer, or any event-append path (state-integrity invariants), and it is not yet wired into a live path — T3 (deterministic floor) and T5 (supervisor) consume it.

Structs

Baseline

Baseline snapshot captured at the feat/<slug> fork (owner: supervisor).

Check

An executable check: the general goal plus a flexible runnable form that proves it. The goal (desc) is always communicated and the command (run) is a free-form shell string; precision (cwd, expect_exit) is available but not forced (owner decision 2026-07-23, plan-check-run-contract).

Chunk

One implementation chunk (owner: spec).

Feature

Feature identity block (owner: orchestrator/spec).

Plan

A plan.json v3 document (design.md §4, §7; plan-schema.md).

Enums

Acceptance

A whole-feature acceptance criterion — an executable check or an LLM-judged assertion. Internally tagged on kind, so an unknown kind fails deserialization (surfaced as PlanValidationError::Malformed).

PlanValidationError

A plan.json document failed schema validation.

Tier

Model-tier hint for a chunk. Serialized as its lowercase wire name.

Constants

PLAN_SCHEMA_VERSION

The current plan.json schema major version this crate writes.

PLAN_V3_EXAMPLE

The checked-in canonical plan.json v3 example (plan-schema.md sample), exposed so a spec-node prompt can show the model the exact target shape.

PLAN_V3_JSON_SCHEMA

The checked-in JSON Schema (Draft 2020-12) describing plan.json v3.

PROVENANCE_REQUIRED_SCHEMA

The first schema major at which baseline provenance (commit_oid, toolchain, enumerated_targets_hash) is structurally required at validate_plan: a plan whose schema_version is >= this value must carry all three as non-empty strings.

SUPPORTED_PLAN_SCHEMAS

All plan.json schema major versions this crate can read. A file whose schema_version is not listed here is rejected outright (PlanValidationError::UnsupportedSchemaVersion) — tolerant reading is limited to additive optional fields within a supported major, never to a whole unknown major.

TOLERATED_OPTIONAL_FIELDS

Field names tolerated when they appear as unknown keys in an otherwise-valid plan — the governed-evolution seam (design.md §13). Empty in v3: no additive optional field has been ratified yet, so every unknown key is currently a rejection.

Functions

parse_and_validate_plan

Parse a raw JSON value as a plan.json v3 document and validate it.

plan_v3_json_schema

Return the checked-in JSON Schema source for plan.json v3.

plan_v3_json_schema_example

Return the canonical plan.json v3 example document.

validate_plan

Structural validation of an already-deserialized Plan.