Strict Package Template Reference rendering

[zack-nova]

Parent

#136

What to build

Replace the public package template variable behavior with strict namespaced Package Template References. Package-owned runtime rendering should use {{ vars.<name> }} only, fail closed for broken Harness Yard references, and leave GitHub Actions expressions outside the Harness Yard renderer.

Acceptance criteria

• Package-owned runtime file rendering recognizes {{ vars.<name> }} as the P0 Package Template Reference syntax.
• The renderer fails before writing package-owned runtime output for unsupported namespaces such as package.*, runtime.*, context.*, and secrets.*.
• The renderer fails for unknown vars.* references that are not declared Package Variables.
• The renderer fails for declared variables that remain unresolved after Runtime Bindings/default resolution.
• The renderer fails for malformed Harness Yard template syntax and includes the file path when available.
• GitHub Actions expressions such as ${{ secrets.GITHUB_TOKEN }} are preserved and are not interpreted as Harness Yard Package Template References.
• Pre-release $name template references are not part of the public rendering contract.

Blocked by

• Runtime Bindings schema v2 and canonical validation #137
• Runtime Bindings resolution, defaults, doctor, and explain #138

[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.
• This issue still lists Runtime Bindings resolution, defaults, doctor, and explain #138 in ## Blocked by, and Runtime Bindings resolution, defaults, doctor, and explain #138 remains open.
• State update: leave state:blocked in place until the remaining blocker is resolved.

[zack-nova]

This was generated by AI during triage.

Triage Notes

• Dependency release closeout for Runtime Bindings resolution, defaults, doctor, and explain #138: PR Implement Runtime Bindings doctor and explain #145 landed successfully at merge commit 816afbf8d30ba71bc59fdf65e2d8686fa325dfa6.
• ## Blocked by lists Runtime Bindings schema v2 and canonical validation #137 and Runtime Bindings resolution, defaults, doctor, and explain #138. Runtime Bindings schema v2 and canonical validation #137 is closed with state:merged; Runtime Bindings resolution, defaults, doctor, and explain #138 has landed.
• 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

• Current labels satisfy tracker gates for handoff: exactly one state label (state:needs-triage), exactly one type label (type:feature), and AFK-compatible delivery mode (delivery-mode:afk).
• Declared blockers Runtime Bindings schema v2 and canonical validation #137 and Runtime Bindings resolution, defaults, doctor, and explain #138 are both closed with state:merged; no open blocker remains for this slice.
• Scope is narrow enough for one issue: replace pre-release public package-owned runtime rendering behavior with the strict Package Template Reference contract from ADR 0005 and the release surface docs.
• Handoff target: state:ready-for-dev after this Dev Brief is recorded.

Dev Brief

Type: feature

Delivery mode: afk

HITL rationale:

• Not required; the behavior is specified by ADR 0005, release-surface docs, and objective tests.

Summary:

• Implement strict namespaced Package Template Reference rendering for package-owned runtime output. {{ vars.<name> }} is the P0 public syntax; unsupported Harness Yard namespaces, unknown variables, unresolved declared variables, and malformed Harness Yard template syntax must fail before package-owned runtime files are written.

Current behavior / context:

• Runtime Bindings schema v2 and resolution/default handling have landed in Runtime Bindings schema v2 and canonical validation #137 and Runtime Bindings resolution, defaults, doctor, and explain #138.
• Current template rendering code still scans/substitutes pre-release $name references in cmd/orbit/cli/template and can preserve unresolved references through compatibility paths.
• RenderTemplateFiles currently operates on Markdown candidate files, while the public release contract describes package-owned runtime file rendering generally and explicitly excludes GitHub Actions ${{ ... }} expressions from Harness Yard interpretation.

Desired behavior:

• Package-owned runtime rendering recognizes {{ vars.<name> }} as the only public Harness Yard Package Template Reference syntax.
• The initial Harness Yard template context supports only the vars namespace.
• References such as {{ package.name }}, {{ runtime.name }}, {{ context.foo }}, {{ secrets.token }}, or any other non-vars namespace fail closed with an unsupported namespace diagnostic.
• {{ vars.<name> }} fails if <name> is not declared as a Package Variable.
• Declared variables fail if Runtime Bindings/default resolution leaves them unresolved.
• Malformed Harness Yard template syntax fails closed and includes the package-owned file path when available.
• GitHub Actions expressions such as ${{ secrets.GITHUB_TOKEN }} are preserved literally and are not parsed as Harness Yard references.
• Pre-release $name references are not treated as the public package-owned runtime rendering contract.

Key interfaces / constraints:

• Keep command files thin; route durable renderer behavior into existing packages, likely under cmd/orbit/cli/template and install preview/materialization paths.
• Preserve the Git-native model and existing package-owned runtime write paths; rendering failures must occur during preview/materialization before filesystem writes.
• Use Runtime Bindings/default resolution results from the schema v2 work; do not introduce new binding precedence or secret-manager behavior.
• Preserve binary or invalid UTF-8 pass-through behavior; for text package-owned runtime files, do not rely on .md extension alone if Harness Yard references must be rendered or rejected.
• Diagnostics should identify variable/reference names and include the file path when available; spelling suggestions are not required.
• Do not interpret ${{ ... }} as Harness Yard syntax.

Acceptance criteria:

• Package-owned runtime file rendering recognizes {{ vars.<name> }} as the P0 Package Template Reference syntax.
• Rendering fails before writing package-owned runtime output for unsupported namespaces such as package.*, runtime.*, context.*, and secrets.*.
• Rendering fails for unknown vars.* references that are not declared Package Variables.
• Rendering fails for declared variables that remain unresolved after Runtime Bindings/default resolution.
• Rendering fails for malformed Harness Yard template syntax and includes the file path when available.
• GitHub Actions expressions such as ${{ secrets.GITHUB_TOKEN }} are preserved and are not interpreted as Harness Yard Package Template References.
• Pre-release $name template references are not part of the public rendering contract.

Validation plan:

• Unit: add focused renderer tests for successful {{ vars.<name> }}, unsupported namespaces, unknown vars.*, unresolved declared variables, malformed syntax with path, GitHub Actions preservation, and $name non-contract behavior.
• Integration: add install/apply tests proving failures happen before package-owned runtime files are written and success writes rendered values through local/remote package install paths as appropriate.
• Manual: not required for AFK handoff.
• Regression risk: run mise run fix, then mise run ci; because this changes release-surface rendering behavior, also run sh ./scripts/test_release_surface_hyard.sh if help/docs/install surface text changes.

Out of scope:

• Expanding hyard vars doctor into template usage scanning.
• Adding typed variables, enum validation, migrations, IDE schemas, or secret-manager integrations.
• Public help/docs cleanup beyond text directly affected by this renderer change.
• Reintroducing schema v1, .orbit/vars.yaml, unresolved public placeholders, --strict-bindings, or public --allow-unresolved-bindings behavior as release-facing surfaces.