Runtime Bindings resolution, defaults, doctor, and explain

[zack-nova]

Parent

#136

What to build

Build the Runtime Bindings resolution and diagnostics substrate on top of schema 2, then expose the P0 hyard vars doctor and hyard vars explain behavior. This slice should let users and CI see whether Package Variables resolve, where selected values came from, and which installed or selected packages declared them.

Acceptance criteria

• Resolution selects scoped Runtime Bindings before global Runtime Bindings, then declaration defaults, then unresolved required variables.
• Declaration defaults are treated as declaration-side fallbacks and reported with source: default; they are not written to .harness/vars.yaml by resolution.
• value_from.env resolves from the process environment, and value_from.file resolves non-sensitive file content for selected variables.
• hyard vars doctor reports P0 errors for invalid schema, missing required Runtime Bindings, malformed value source references, and unset value_from.env variables.
• hyard vars doctor reports P0 warnings for undeclared bindings and missing value_from.file paths.
• hyard vars explain [name] reports resolved/unresolved status, selected value source, required flag, sensitive flag placeholder support, declaring installed package or orbit ids, and selected scope in text and JSON output.
• P0 doctor and explain do not implement template usage scanning, unknown template reference scanning, shadowed candidate display, or full precedence trees.

Blocked by

• Runtime Bindings schema v2 and canonical validation #137

[zack-nova]

This was generated by AI during triage.

Triage Notes

• Dependency release closeout for Runtime Bindings schema v2 and canonical validation #137: PR Implement Runtime Bindings schema v2 #144 landed successfully at merge commit 760c38334b3de16830449d509c25a8258d90b168.
• ## Blocked by lists only Runtime Bindings schema v2 and canonical validation #137. No other blockers remain open or unmerged.
• State update: replace state:blocked with state:needs-triage so this issue can be re-evaluated for implementation readiness.

[zack-nova]

This was generated by AI during triage.

Triage Notes

• Confirmed Runtime Bindings schema v2 and canonical validation #137 is unblocked: PR Implement Runtime Bindings schema v2 #144 merged on 2026-05-12 at 760c38334b3de16830449d509c25a8258d90b168 and Runtime Bindings schema v2 and canonical validation #137 is closed with state:merged.
• Current metadata is delivery-ready: exactly one state label, exactly one type label (type:feature), and AFK-compatible delivery mode (delivery-mode:afk).
• No split required. This is one cohesive P0 Runtime Bindings diagnostics slice, with explicit exclusions for template usage scanning, unknown template reference scanning, shadowed candidate display, and full precedence trees.
• Decision: prepare for implementation by adding the Dev Brief, then move to state:ready-for-dev.

Dev Brief

Type: feature

Delivery mode: afk

HITL rationale:

Not applicable; repository validation gates are objective for this slice.

Summary:

Build Runtime Bindings resolution and diagnostics on top of schema 2, then expose P0 hyard vars doctor and hyard vars explain [name] behavior so users and CI can see whether Package Variables resolve, where selected values came from, and which installed or selected packages declared them.

Current behavior / context:

#137 established the public schema 2 Runtime Bindings substrate at .harness/vars.yaml, including inline value, explicit value_from.env / value_from.file, scoped bindings under scoped_variables.<namespace>.variables, hyard vars path, and hyard vars validate. Existing lower-level binding and install snapshot code already tracks declarations and install-backed package/orbit context, but the P0 selected-resolution, doctor diagnostics, and explain reporting are not yet implemented.

Desired behavior:

Resolution should select scoped Runtime Bindings before global Runtime Bindings, then declaration defaults, then unresolved required variables. Defaults remain declaration-side fallbacks, report as source: default, and are not written to .harness/vars.yaml by resolution. value_from.env resolves from the process environment, while value_from.file resolves non-sensitive file content for selected variables.

hyard vars doctor should report P0 errors for invalid schema, missing required Runtime Bindings, malformed value source references, and unset value_from.env variables. It should report P0 warnings for undeclared bindings and missing value_from.file paths.

hyard vars explain [name] should support text and JSON output reporting resolved/unresolved status, selected value source, required flag, sensitive flag placeholder/redaction behavior, declaring installed package or orbit ids, and selected scope.

Key interfaces / constraints:

• Keep the public surface under hyard vars; command wrappers should stay thin and durable behavior should live in existing packages.
• Use .harness/vars.yaml as the canonical Runtime Bindings path and schema 2 as the only public schema for this work.
• Preserve the Git-native model and current install snapshot truth under .harness/installs/*.yaml / hosted package records; do not introduce services, databases, worktrees, or background state.
• Candidate implementation areas include cmd/hyard/cli/vars.go, cmd/orbit/cli/bindings, cmd/orbit/cli/harness/*bindings*, install-record declaration snapshots, and related CLI/integration tests.
• Diagnostics for sensitive variables must avoid exposing resolved secret values; P0 placeholder/redaction support is enough.
• value_from.file should not be accepted for sensitive declarations in selected resolution diagnostics.

Acceptance criteria:

• Resolution selects scoped Runtime Bindings before global Runtime Bindings, then declaration defaults, then unresolved required variables.
• Declaration defaults are treated as declaration-side fallbacks and reported with source: default; they are not written to .harness/vars.yaml by resolution.
• value_from.env resolves from the process environment, and value_from.file resolves non-sensitive file content for selected variables.
• hyard vars doctor reports P0 errors for invalid schema, missing required Runtime Bindings, malformed value source references, and unset value_from.env variables.
• hyard vars doctor reports P0 warnings for undeclared bindings and missing value_from.file paths.
• hyard vars explain [name] reports resolved/unresolved status, selected value source, required flag, sensitive flag placeholder support, declaring installed package or orbit ids, and selected scope in text and JSON output.
• P0 doctor and explain do not implement template usage scanning, unknown template reference scanning, shadowed candidate display, or full precedence trees.

Validation plan:

• Unit: add focused tests for schema 2 selected resolution precedence, declaration defaults, env/file source resolution, malformed sources, missing env, missing file warnings, undeclared binding warnings, and sensitive placeholder/redaction behavior.
• Integration: add hyard vars doctor and hyard vars explain CLI tests for text and JSON output against runtime/install fixtures.
• Manual: not required for AFK handoff; command behavior should be covered by automated tests.
• Regression risk: run mise run fix followed by mise run ci; because this changes public command behavior, also run sh ./scripts/test_release_surface_hyard.sh if help text or release-surface output changes.

Out of scope:

• Template usage scanning.
• Unknown template reference scanning.
• Shadowed candidate display.
• Full precedence trees.
• Typed validation, enum validation, migration, JSON Schema generation, and secret-manager integration.