Runtime Bindings schema v2 and canonical validation

[zack-nova]

Parent

#136

What to build

Implement the first public Runtime Bindings document contract end to end for the canonical .harness/vars.yaml path. This slice should make schema 2 parseable, validatable, and stably writable with inline values, explicit value sources, and existing Scoped Bindings shape, without depending on install onboarding or template rendering changes.

Acceptance criteria

• .harness/vars.yaml is the canonical Runtime Bindings path for public validation/path behavior; .orbit/vars.yaml is not used as a public compatibility path.
• Runtime Bindings schema 2 accepts variables.<name>.value, variables.<name>.value_from.env, variables.<name>.value_from.file, and scoped_variables.<namespace>.variables.<name> with the same binding leaf shape.
• Schema validation rejects schema 1, scalar shorthand, invalid variable names, invalid scoped namespaces, binding leaves with both value and value_from, binding leaves with neither, and blank value_from entries.
• Stable marshaling preserves the schema 2 shape for global and scoped Runtime Bindings.
• hyard vars path reports .harness/vars.yaml as the canonical Runtime Bindings file.
• hyard vars validate validates the schema 2 file and returns actionable errors for invalid shape.

Blocked by

None - can start immediately

[zack-nova]

This was generated by AI during triage.

Triage Notes

• 2026-05-12T08:00Z development preflight blocked. Live issue has exactly one state label (state:ready-for-dev), exactly one type label (type:feature), and AFK-compatible delivery mode (delivery-mode:afk), but the configured tracker location has no ## Dev Brief issue comment.
• Required next action: add a complete ## Dev Brief issue comment, then move the issue back to state:ready-for-dev.

[zack-nova]

This was generated by AI during triage.

Dev Brief

Type: feature

Delivery mode: afk

HITL rationale:

N/A - delivery mode is afk; this slice can be implemented and reviewed through objective repository gates.

Summary:

Implement the first public Runtime Bindings document contract for the canonical .harness/vars.yaml path. This slice should make schema 2 parseable, validatable, and stably writable for inline values, explicit value sources, and the existing Scoped Bindings shape.

Current behavior / context:

Harness Yard has pre-release Runtime Bindings behavior and documentation around .harness/vars.yaml, but implementation still needs the public schema 2 contract wired end to end for validation/path behavior. The broader parent issue #136 covers the full Runtime Bindings product reset; this issue is the first implementation slice and should stay focused on document schema, canonical path, stable marshaling, and hyard vars path / hyard vars validate behavior.

Desired behavior:

.harness/vars.yaml is treated as the canonical public Runtime Bindings file. Runtime Bindings schema 2 accepts global bindings under variables and scoped bindings under scoped_variables.<namespace>.variables, with each binding leaf using exactly one of inline value or explicit value_from.env / value_from.file. Validation rejects pre-release schema and malformed binding shapes with actionable errors, and stable marshaling preserves the schema 2 global and scoped structure.

Key interfaces / constraints:

• Public Runtime Bindings path: .harness/vars.yaml.
• Do not add public .orbit/vars.yaml compatibility for this slice.
• Public schema version: schema_version: 2.
• Binding leaf shape: exactly one of value or value_from.
• Supported explicit sources: value_from.env and value_from.file.
• Scoped Bindings shape remains scoped_variables.<namespace>.variables.<name>.
• Use existing packages and command surfaces; keep command files thin and route durable behavior into the existing implementation packages.
• Validate identifiers before using them in paths or public document locations.

Acceptance criteria:

• .harness/vars.yaml is the canonical Runtime Bindings path for public validation/path behavior; .orbit/vars.yaml is not used as a public compatibility path.
• Runtime Bindings schema 2 accepts variables.<name>.value, variables.<name>.value_from.env, variables.<name>.value_from.file, and scoped_variables.<namespace>.variables.<name> with the same binding leaf shape.
• Schema validation rejects schema 1, scalar shorthand, invalid variable names, invalid scoped namespaces, binding leaves with both value and value_from, binding leaves with neither, and blank value_from entries.
• Stable marshaling preserves the schema 2 shape for global and scoped Runtime Bindings.
• hyard vars path reports .harness/vars.yaml as the canonical Runtime Bindings file.
• hyard vars validate validates the schema 2 file and returns actionable errors for invalid shape.

Validation plan:

• Unit: add or update focused Runtime Bindings schema tests for schema 2 parsing, validation rejection cases, scoped bindings, and stable marshaling.
• Integration: add or update CLI coverage for hyard vars path and hyard vars validate against valid and invalid schema 2 files.
• Release surface: run sh ./scripts/test_release_surface_hyard.sh because this touches public command/path behavior.
• Repository gates: run mise run fix and mise run ci before review.
• Regression risk: verify existing package/install tests that still depend on Runtime Bindings behavior are updated intentionally rather than bypassed.

Out of scope:

• Install onboarding for missing Runtime Bindings.
• Package template rendering changes, including strict {{ vars.<name> }} rendering.
• hyard vars init, hyard vars doctor, and hyard vars explain behavior beyond any shared code required by path and validate.
• Sensitive Package Variable policy and redaction behavior.
• Declaration defaults, declaration merging, and scoped/global precedence beyond preserving the scoped document shape.
• Public .orbit/vars.yaml compatibility.
• Schema 1 migration or compatibility.
• $name template references and other historical pre-release template behavior.