[runs] Spektacular status verb (cross-link; code lands in Spektacular)

[clubanderson]

Part of #8290 (long-running runs umbrella). Spektacular repository: https://github.com/jumppad-labs/spektacular. This issue is filed in hive so the dependency graph lives in one place; the implementation lands in the Spektacular repository.

Goal

Spektacular exposes per-artifact status through a CLI verb or endpoint so Hive never parses state.json from disk. This is the only new Spektacular surface that Epic 1 of #8227 needs.

Why now

On #8227, nicholasjackson (2026-09-22 17:05Z) wrote that spektacular plan file list "does not expose the metadata for a file, this feature needs to be added as it can not be assumed that a spec or plan file is located on local storage or that the metadata is stored in the file, it could be stored in the api's metadata." The 18:31Z reply settled the split: Hive owns the workflow state machine, Spektacular owns per-stage state and exposes it. The stage runner (#8303) polls this verb to advance the lease.

Files and symbols

Spektacular side only. Hive consumes the output through src/pkg/spektacular/runner.go (#8303) using a fake Exec in tests.

Steps

1. Add spektacular spec status <name> --json and spektacular plan status <name> --json, and extend spektacular {spec,plan} file list --json so every entry carries metadata.
2. Each artifact returns {kind, name, document_status, current_step, completed_steps, created_at, updated_at, closed_at} where document_status is draft or final, timestamps are RFC3339, and the values come from filesystem frontmatter or API metadata depending on the configured store.
3. When the artifact does not exist, exit non-zero and print a JSON error object on stdout.
4. Answer the two open questions from the 18:31Z comment in the same change and record the answers on this issue: whether data.name (for example 20260922132517-hcl-encoding-helpers) is a stable join key across spec, plan, and implement; and whether invalidating a plan after final flips document_status back to draft or creates a new document. The answer decides whether Hive rolls a lease back a stage or opens a new generation.

Acceptance

• A Hive integration test can shell out to the verb against a fixture repository and parse the JSON without reading any Spektacular file directly.
• Both store backends (filesystem, API) return the same shape.
• Both open questions have a recorded answer.

Tests

Spektacular's own test suite. On the Hive side, #8303 covers consumption with a fake executor.

Docs and changelog

Spektacular docs. No hive changelog entry (label no-changelog when the hive side has no code).

Release line

Not applicable (Spektacular).

Depends on / blocks

No dependencies. Blocks #8303 and #8314. #8319 (config migration) must be satisfied before this is declared done.

Out of scope

Any Hive code; the Hive-side runner is #8303.

[clubanderson]

Opened the Spektacular PR here: hivecommons/spektacular#45

Recorded answers from the implementation for nicholasjackson to confirm:

1. The stable join key across spec / plan / implement is the artifact name carried in the spec: / plan: frontmatter cross-references; the new status output surfaces those fields so Hive does not read files.
2. Returning a final artifact to draft updates document_status on the same document and clears closed_date; no new document is created.

Hive implication for #2: invalidation should roll the existing lease back a stage with a new generation, matching #8350's resetLeaseStage, rather than opening a new artifact lineage.

Also noting #8319's precondition is already shipped on the Spektacular side: settings schema versions plus migrate are covered by Spektacular changelog 000053_config-schema-versioning-and-migrations.md.

[clubanderson]

Spektacular PR hivecommons/spektacular#45 was reviewed by the Spektacular maintainer on 2026-09-23 and revised the same day (head aa3b0a5). Contract as it now stands: the stable join key is the bare artifact name (the same value state.json records in data.name), not the spec:/plan: frontmatter fields; updated_at is emitted only when the in-progress workflow state matches the artifact and is omitted otherwise; modified_at carries the file mtime under its honest name; spec/plan/changelog file list carry modified_at per entry so one list call can serve many artifacts; plan status reports plan.md only; a missing artifact exits non-zero with error code artifact_not_found; there is no --json flag on file list (output is already JSON). Hive-side alignment is in progress under #8303. This issue closes when PR 45 merges.