Add lock schema compatibility gate for compiled .lock.yml files

[davidahmann]

Problem

Compiled .lock.yml files are consumed by multiple commands, but there is no explicit schema compatibility gate. If lock metadata evolves, older/newer files can be partially interpreted without a hard failure.

Expected behavior

• Every generated lock file carries an explicit lock schema version marker.
• Lock consumers validate schema compatibility before parsing lock content.
• Incompatible lock files fail closed with deterministic remediation guidance.

Acceptance / validation

• Add a compatibility matrix (supported schema versions).
• Add unit tests covering:
  • compatible lock version passes
  • unsupported future version fails with actionable error
  • malformed or missing version behavior is deterministic
• Validate affected commands that read lock files still pass existing tests.

[pelikhan]

The schema is GitHub actions file. Are you parsing other data?

[davidahmann]

Great question. We still treat .lock.yml as standard GitHub Actions YAML.

The compatibility gate I proposed is for gh-aw-specific lock metadata conventions that our CLI reads from compiled locks (for example frontmatter hash comments and stop-time metadata), not for replacing GitHub’s workflow schema.

If helpful, I can narrow scope to only metadata-dependent paths and avoid blocking plain workflow-name resolution paths that only need the standard name: field.

[pelikhan]

I see. I could write all the metadata as JSON payload in the header to make it easier, with associated schema. What info are you looking for.

[davidahmann]

Agree, and I think JSON header metadata is a good direction.

For #16360, the key thing I’m trying to protect is gh-aw metadata compatibility, not replace GitHub Actions YAML schema.

Minimum metadata I’m looking for in a header payload:

• meta_schema_version (for compatibility checks)
• frontmatter_hash (staleness detection)
• source_workflow (source .md identity)
• effective_stop_time (if configured; avoids scraping env lines)
• compiler_version (optional but useful for diagnostics)

Suggested shape (single comment line is fine):
# gh-aw-meta: {"meta_schema_version":1,"frontmatter_hash":"...","source_workflow":"...","effective_stop_time":"...","compiler_version":"..."}

Scope-wise, I’d only gate readers that depend on this metadata. Paths that only need standard workflow YAML fields (like name) can stay schema-agnostic.

If this direction works for you, I can narrow the issue/PR language to “metadata compatibility gate” and keep it incremental.