How Schema, Envelope, and Policy Matter in Software Factories

The first thing that happens when someone submits a spec to a software factory is a gate: three checks that run before any work begins. No code generation, no planning, no dependency resolution. The gate validates that the spec is structurally correct, operationally unambiguous, and compliant with governance. If any of those checks fail, the spec bounces back to the author. This article is about why those three checks exist and why they matter.

The Gate That Comes First

The spec gate sits at the boundary between human intent and autonomous execution. It's the factory's first checkpoint, and it's deliberately simple. No AI, no heuristics, no judgement calls. Just deterministic rules applied to structured data. The gate checks three things: schema (is the artifact structurally valid?), envelope (does it carry the operational contract?), and policy (does it comply with governance rules?). All three must pass before a spec advances to become a plan.

This gate exists because every downstream step assumes the spec is well-formed. Planning, building, verifying, deploying: they all depend on it. If you let structurally broken or ambiguous specs past this point, you waste compute, confuse agents, and erode trust in the outputs. The gate is the factory's immune system. It rejects bad inputs before they become expensive problems.

Schema: Structural Contracts for Every Artifact

Every artifact in the factory is a Pydantic model. Specs, plans, changesets, evidence bundles, verdicts, provenance records: they all validate against a strict schema before they're accepted. This is not boilerplate. It's the backbone of the factory's security model.

A prompt-injected station can try to emit garbage, but it can only emit artifacts that validate against their schema. The core rejects anything that doesn't match. An evidence bundle can't contain free text. Verdicts are enums and numbers, not natural language, because if a gate had to interpret prose the deterministic guarantee would break.

Schema evolution follows one rule: additive only. New fields must be optional. You never repurpose old fields. This means schemas are permanent, durable, and backward-compatible. A spec written against version one of the model still validates against version ten. That stability matters when you're running thousands of specs through an autonomous pipeline.

Envelope: Operational Contracts That Kill Ambiguity

The envelope is the answer to a specific problem: silently ambiguous specs. When a human writes a spec, they often leave implicit assumptions about how the work should behave. How many times to retry on failure. What counts as a timeout. What signals prove the thing works. In a human team those get resolved in conversation. In an autonomous factory they must be explicit.

Every spec carries an envelope with four fields: max_retries, timeout_seconds, failure_behavior, and observability. These are not optional conventions. The spec gate rejects any spec that lacks a valid envelope. This encodes the operational contract as a required template, not a best practice that someone might skip.

The envelope gets checked before a spec becomes a plan. A builder doesn't have to guess how to handle a timeout. The spec tells it. A critic doesn't have to infer what "working" means. The spec declares the observability signals. Per-slice envelope overrides let different parts of the same project carry different contracts, which is essential when you're mixing batch jobs with real-time services in one pipeline.

Policy: Governance as Code, Not Convention

Policy is the governance layer. It answers questions like: who can approve changes to this part of the system? What evidence must a change produce before it merges? How long do audit records need to be retained? In most organisations these are wiki pages or tribal knowledge. In a software factory, they're code.

The factory uses governance tiers (T0 through T3) mapped to path globs. T0 is full lights-out autonomy. T3 requires human sign-off from a qualified reviewer. The tier max-rule says a change spanning multiple tiers inherits the highest one. No averaging out past a sensitive path by bundling it with safe ones.

Policy packs are pure YAML data bundles that define required evidence verbs (test, mutate, analyze), human attestation rules, and retention periods. They compose with union semantics: a change covered by both a PCI policy and a general policy must satisfy the requirements of both. The oracle-strength floor ties autonomy to measured test quality. If a path's mutation kill rate drops below its certified floor, lights-out autonomy is revoked.

The target state is OPA or Cedar evaluation. The current Python gate functions are the reference semantics. Any future reimplementation must reproduce their behaviour exactly.

One Gate, Three Contracts

Schema, envelope, and policy are distinct concepts that converge at a single checkpoint. Schema says "this artifact is structurally valid." Envelope says "this spec is operationally unambiguous." Policy says "this change complies with governance." Each solves a different failure mode, and the gate enforces all three.

This separation matters. If schema and policy were mixed, you couldn't evolve the data model independently of the governance rules. If the envelope were part of the schema, you couldn't override operational contracts per slice without affecting the structural model. Keeping them separate means each layer evolves at its own pace. Schemas grow additively, envelopes get per-slice overrides, policy packs get updated without touching artifact models.

The result is a system where agents produce artifacts and gates decide. The agents can be smart, creative, even unreliable. The gate is the fixed point: deterministic, LLM-free, operating on structured evidence. That structure is what makes autonomous delivery safe enough to run at scale.