Add bench prep — generate PREP readiness evidence from the scaffolded service

Goal

Add a bench prep subcommand that generates a draft Platform Readiness Enablement Process (PREP) evidence report for a bench, pre-filling the per-category readiness questionnaires from artifacts the scaffold already produces.

PREP evidence is authored as per-category markdown questionnaires in gitlab-org/architecture/readiness and submitted via MR against a tracking Assessment issue. A bench-scaffolded service already emits most of that evidence as a byproduct of the paved path (CI pipeline, Fairway manifest, LabKit wiring, three-layer structure). bench prep closes the loop: read the service's own artifacts, emit populated questionnaire drafts, and flag the categories bench cannot evidence for the team to complete.

Like bench register (#35 (closed)), this is a report-generating imperative action, not configuration persisted in bench.yaml. It generates evidence; it does not certify — platform stakeholders still review and approve.

Command surface

bench prep \
  --assembly <name>          # scope to one assembly; default: whole bench
  --format <md|json>         # md = readiness-repo questionnaire layout (default); json = machine-readable
  --out <dir>                # output directory; default: ./prep/
  --check                    # CI mode: exit non-zero if any category has no evidence
  • Service/bench name is read from bench.yaml (bench.name), not a positional arg.
  • Default (bench prep) writes one markdown file per PREP category under ./prep/, mirroring the readiness-repo template layout.
  • --check prints a per-category evidence summary and exits non-zero when a required category is unaddressed — suitable as a CI gate.

Evidence sources

Each category is pre-filled from a known artifact in the scaffolded repo. Categories bench cannot synthesize get a TODO(team): stub with the questionnaire prompt rather than a fabricated pass.

Click to expand example sources table
PREP category Auto-filled from Confidence
Service Architecture bench.yaml (assembly/service topology, runtime, listeners); enforced three-layer structure High
Build & Deployment .gitlab-ci.yml / common-ci-tasks (goreleaser, container signing, chart generation) High
Deployment generated .runway/<assembly>/fairway.yaml High
Observability LabKit v2 logging/metrics/tracing wiring detected in the scaffold Medium
Operational Lifecycle caproni.yaml; mise task inventory Medium
Performance & Scalability performance-contract scaffolding, if present Low (stub if absent)
Quality Assurance test + lint config discovered in the repo Medium
Security & Compliance — Team-owned stub
Documentation & Support README.md presence; otherwise stub Team-owned stub
Installation & Configuration — Team-owned stub
Platform Strategy — Team-owned stub

The authoritative category list and questionnaire templates live in gitlab-org/architecture/readiness; treat that repo as the contract this command targets.

Example Implementation flow

  1. Read + validate bench.yaml (reuse bench check internals).
  2. Resolve the target assemblies (whole bench, or --assembly).
  3. For each PREP category, run a collector: a pure function over the discovered repo artifacts that returns either populated evidence or an "unaddressed" marker.
  4. Render each category through its questionnaire template into --out.
  5. --check: aggregate collector results; exit non-zero if any non-team-owned category is unaddressed.

Considerations

  • Opening an MR against gitlab-org/architecture/readiness automatically (pairs with #35 (closed)'s infra-mgmt flow; add once bench prep output is stable).
  • Creating the Assessment tracking issue
  • Deep evidence for team-owned categories (Security & Compliance, Platform Strategy) — bench emits stubs; teams author these.
  • Coupling to a pinned readiness-template version; revisit if the readiness repo restructures its questionnaires.

Related

  • Roadmap item referenced in the Theseus docs (bench prep — PREP evidence generation).
  • Sibling imperative-action command: #35 (closed) (bench project register).
  • PREP category → Theseus-artifact mapping originates in the Theseus vision doc's "PREP connection" section.
  • Authoritative source: readiness assessment repository.
Edited by Lucas Charles