Improve step template reviewability and local development with a source-first workflow

[bcullman]

Summary

The current step-template workflow uses step-templates/*.json as both source and artifact. That creates real problems:

• script changes are buried inside JSON strings and are hard to review
• diffs are noisy and make PRs harder to understand
• local development and validation are more awkward than they need to be
• maintaining templates safely requires more manual effort around packed artifacts

A source-first workflow would address those problems by keeping template metadata and script content in normal source files, while continuing to generate the existing JSON output through build tooling.

Benefits of a source-first workflow

• script changes become reviewable as normal source diffs
• PRs become easier to read and reason about
• local development becomes simpler and more reliable
• template maintenance becomes safer and more repeatable
• the existing packed JSON format can remain the published output

Prior work

Related issues and prior attempts:

• Template "diffability" #575 Template "diffability"
• Format template for humans to read #1542 Format template for humans to read
• Tothegills/for humans change example #1543 Tothegills/for humans change example

In particular, #575 captures the core problem well: step-template scripts are difficult to review when they live inside JSON strings.

Scope

Any solution in this area should cover:

• tooling to support a source-first template layout
• build integration to regenerate step-templates/*.json
• proof that a source-first approach can generate the same output as the current JSON-based workflow
• follow-up documentation and repository migration