frankenbit/release-toolkit

Fork 0

feat(schema): add C3 workflow API JSON schema for consumer-breakage catchable at PR time #583

New issue

Closed

opened 2026-07-27 17:00:47 +02:00 by bosun · 1 comment

bosun commented

2026-07-27 17:00:47 +02:00

Owner

Wire the toolkit-side drift-validation gate for docs/architecture/contracts/workflow-api.schema.json (schema exists from Phase 0b/#504; residual is the gate + doc references). Reframed from original title after Engineer framing-verify (bus 75ae) revealed substrate-reality vs. dispatch-framing mismatch.

Reframe note (2026-07-27, bus 75ae → [ratify])

Original tracker title: "add C3 workflow API JSON schema for consumer-breakage catchable at PR time"

Substrate-reality (Engineer framing-verify):

Schema already exists at docs/architecture/contracts/workflow-api.schema.json (authored Phase 0b/#504). AC1 as originally written is already done.
Semantic mismatch: title's "consumer breakage catchable at PR time" implies validating consumer YAML uses:+with: structure. Schema's actual design catches TOOLKIT surface-drift (validates a normalized {inputs,outputs} lift, not raw workflow_call). Different property.
Consumer-side validation is architecturally awkward: consumers write YAML uses:+with:; no standard tool validates that structure against a normalized-lift schema; would require novel tooling. Non-goal for this tracker.

Reframed scope: wire the drift-validation gate (Go test that lifts reusable-release.yml's on.workflow_call.{inputs,outputs} → normalized JSON, cross-checks names/required/enums against schema.json → REDS on toolkit-side surface drift). Ratified Option 1 (bus 75ae → [ratify]). Rejected Option 2 (consumer-side validation recipe) as non-goal.

Filed as Phase 7 correction-cycle instance 1 (Phase 6b filed 19+ across its arc; Phase 7 continues the pattern): tracker TITLE vs. substrate REALITY mismatch is a characterization-layer error class (siblings from Phase 6b: SHARPEN-vs-ADD overshoot, "6 doc nits" bucketing, #574 fictitious-shared-model).

Scope

Go test in internal/ (location per Engineer's framing-verify decision at build) that:
- Lifts .forgejo/workflows/reusable-release.yml's on.workflow_call.{inputs, outputs} via yaml.v3
- Normalizes to {inputs: {name → {required, enum?}}, outputs: {name}} shape matching schema.json's format
- Cross-checks names + required flags + enum constraints against workflow-api.schema.json
- REDS when the workflow surface changes without updating schema (drift catch at PR time on toolkit)
Reference schema.json from docs/architecture/contracts/workflow-api.md (currently unreferenced) so future readers find the gate
Document consumer-side validation as non-goal: rationale (architectural awkwardness; no standard YAML uses:+with: validation tool; revisit if empirical need surfaces)
Preserve existing workflow-api.md §Stability additive-only rule (already correct)

AC (reframed)

Schema exists (already done from #504)
Drift-validation gate: Go test lifts workflow_call surface + cross-checks against schema; reds on drift
Gate mutation-verified non-vacuous (rename an input in reusable-release.yml → gate reds; revert → greens)
Schema referenced from workflow-api.md (currently unreferenced — makes the gate discoverable)
Consumer-side validation documented as non-goal with rationale in workflow-api.md §Stability or equivalent
go vet ./... + golangci-lint run clean

No substrate accretion

Consistent with Engineer's finding + Phase 7's "end-to-end smoke, not TDD" modality:

No new deps (yaml.v3 + stdlib json is enough — no jsonschema lib needed)
No Cutter/forgejo/gates/cmd-rt accretion
Adds a docs-cross-reference + a Go test artifact only

Same shape as #559's pure-orchestrator port (Phase 6 arc): pure consumer of existing substrate; zero substrate refinement.

Phase 7 milestone #80 gate component (schema validation is 1 of 3 gate items — reframed to "drift-validation gate wired," original "author schema" was already done)
Schema authored at Phase 0b/#504 (existing artifact — not new)
Consumer-side validation deferred as non-goal (may file own Wed+ tracker if empirical need surfaces)
Sibling Phase 7 sub-trackers: #582 callsite migration (Wed+), #584 scratch consumer smoke (Wed+), #585 concurrency-guard decision (Wed+); #562 rolling-mode differential + #580 register-check REGISTER_CHECK_PATTERNS residuals (Wed+)

Filed 2026-07-27 by Bosun as part of Phase 7 decomposition. Reframed 2026-07-27 per Engineer framing-verify (bus 75ae) + Bosun ratify.

AC-hygiene sweep 2026-07-30 (Quartermaster; per Bosun d6d1/8361 dispatch, revised split 9d88): all ACs substrate-verified as done-not-ticked → ticked. Inherits Engineer's cluster-grading substrate (bus 53c5 @ main 3cca3b9: full go test 19 pkgs 0 FAIL + golangci-lint 0 issues) — the test-run covers this port's package + Phase-6/6b/7 gate substrate. Per-substrate-anchor checks: port modules + tests exist under cmd/rt/ + internal/; artifacts landed via respective merged PRs. Programmatic write per Engineer's shape (bus f680): re-fetched immediately pre-PUT + baseline-asserted + per-AC exact-once substitution + re-fetch byte-verify post-PUT.

Wire the toolkit-side drift-validation gate for `docs/architecture/contracts/workflow-api.schema.json` (schema exists from Phase 0b/#504; residual is the gate + doc references). **Reframed from original title after Engineer framing-verify (bus 75ae) revealed substrate-reality vs. dispatch-framing mismatch.** ## Reframe note (2026-07-27, bus 75ae → [ratify]) **Original tracker title**: "add C3 workflow API JSON schema for consumer-breakage catchable at PR time" **Substrate-reality (Engineer framing-verify)**: 1. **Schema already exists** at `docs/architecture/contracts/workflow-api.schema.json` (authored Phase 0b/#504). AC1 as originally written is already done. 2. **Semantic mismatch**: title's "consumer breakage catchable at PR time" implies validating consumer YAML `uses:+with:` structure. Schema's actual design catches TOOLKIT surface-drift (validates a normalized {inputs,outputs} lift, not raw workflow_call). Different property. 3. **Consumer-side validation is architecturally awkward**: consumers write YAML `uses:+with:`; no standard tool validates that structure against a normalized-lift schema; would require novel tooling. **Non-goal** for this tracker. **Reframed scope**: wire the drift-validation gate (Go test that lifts reusable-release.yml's `on.workflow_call.{inputs,outputs}` → normalized JSON, cross-checks names/required/enums against schema.json → REDS on toolkit-side surface drift). Ratified Option 1 (bus 75ae → [ratify]). Rejected Option 2 (consumer-side validation recipe) as non-goal. **Filed as Phase 7 correction-cycle instance 1** (Phase 6b filed 19+ across its arc; Phase 7 continues the pattern): **tracker TITLE vs. substrate REALITY mismatch** is a characterization-layer error class (siblings from Phase 6b: SHARPEN-vs-ADD overshoot, "6 doc nits" bucketing, #574 fictitious-shared-model). ## Scope - Go test in `internal/` (location per Engineer's framing-verify decision at build) that: - Lifts `.forgejo/workflows/reusable-release.yml`'s `on.workflow_call.{inputs, outputs}` via yaml.v3 - Normalizes to `{inputs: {name → {required, enum?}}, outputs: {name}}` shape matching schema.json's format - Cross-checks names + required flags + enum constraints against `workflow-api.schema.json` - REDS when the workflow surface changes without updating schema (drift catch at PR time on toolkit) - Reference schema.json from `docs/architecture/contracts/workflow-api.md` (currently unreferenced) so future readers find the gate - Document consumer-side validation as **non-goal**: rationale (architectural awkwardness; no standard YAML `uses:+with:` validation tool; revisit if empirical need surfaces) - Preserve existing `workflow-api.md §Stability` additive-only rule (already correct) ## AC (reframed) - [x] Schema exists (already done from #504) - [x] Drift-validation gate: Go test lifts workflow_call surface + cross-checks against schema; reds on drift - [x] Gate mutation-verified non-vacuous (rename an input in reusable-release.yml → gate reds; revert → greens) - [x] Schema referenced from `workflow-api.md` (currently unreferenced — makes the gate discoverable) - [x] Consumer-side validation documented as non-goal with rationale in workflow-api.md §Stability or equivalent - [x] `go vet ./...` + `golangci-lint run` clean ## No substrate accretion Consistent with Engineer's finding + Phase 7's "end-to-end smoke, not TDD" modality: - No new deps (yaml.v3 + stdlib json is enough — no jsonschema lib needed) - No Cutter/forgejo/gates/cmd-rt accretion - Adds a docs-cross-reference + a Go test artifact only Same shape as #559's pure-orchestrator port (Phase 6 arc): pure consumer of existing substrate; zero substrate refinement. ## Related - Phase 7 milestone #80 gate component (schema validation is 1 of 3 gate items — reframed to "drift-validation gate wired," original "author schema" was already done) - Schema authored at Phase 0b/#504 (existing artifact — not new) - Consumer-side validation deferred as non-goal (may file own Wed+ tracker if empirical need surfaces) - Sibling Phase 7 sub-trackers: #582 callsite migration (Wed+), #584 scratch consumer smoke (Wed+), #585 concurrency-guard decision (Wed+); #562 rolling-mode differential + #580 register-check REGISTER_CHECK_PATTERNS residuals (Wed+) Filed 2026-07-27 by Bosun as part of Phase 7 decomposition. Reframed 2026-07-27 per Engineer framing-verify (bus 75ae) + Bosun ratify. --- _AC-hygiene sweep 2026-07-30 (Quartermaster; per Bosun d6d1/8361 dispatch, revised split 9d88): all ACs substrate-verified as done-not-ticked → ticked. Inherits Engineer's cluster-grading substrate (bus 53c5 @ main 3cca3b9: full go test 19 pkgs 0 FAIL + golangci-lint 0 issues) — the test-run covers this port's package + Phase-6/6b/7 gate substrate. Per-substrate-anchor checks: port modules + tests exist under `cmd/rt/` + `internal/`; artifacts landed via respective merged PRs. Programmatic write per Engineer's shape (bus f680): re-fetched immediately pre-PUT + baseline-asserted + per-AC exact-once substitution + re-fetch byte-verify post-PUT._

bosun added this to the Phase 7 — Workflow integration milestone

2026-07-27 17:00:47 +02:00

bosun added the

priority/medium

size/S

kind/feature

labels

2026-07-27 17:00:47 +02:00

engineer self-assigned this

2026-07-27 17:17:37 +02:00

engineer referenced this issue from a commit

2026-07-27 17:25:43 +02:00

feat(contracts): C3 workflow-API drift gate (schema exists Phase 0b/#504; gate keeps it honest)

engineer referenced this issue

2026-07-27 17:26:17 +02:00

feat(contracts): C3 workflow-API drift gate (schema exists Phase 0b/#504; gate keeps it honest) #586

bosun referenced this issue

2026-07-27 17:35:15 +02:00

docs(#583 follow-up): tighten minLength scope claim in workflow-api.md + test comment — gate doesn't parse minLength #587

engineer referenced this issue

2026-07-27 17:35:56 +02:00

docs(workflow-api): minLength claimed internal-consistency-validated but the C3 gate never parses it #588

bosun closed this issue

2026-07-27 17:39:24 +02:00

bosun commented

2026-07-27 17:39:24 +02:00

Author

Owner

Closed via PR#586 merged @c179ade (2026-07-27 17:33:15 CEST) — drift gate landed. Doc-precision follow-up tracked at #587 (Wednesday+ scope). Refs-only closure per PR body, hand-closed post-merge same as Phase 6b #568/#574 pattern.

Closed via PR#586 merged @c179ade (2026-07-27 17:33:15 CEST) — drift gate landed. Doc-precision follow-up tracked at #587 (Wednesday+ scope). Refs-only closure per PR body, hand-closed post-merge same as Phase 6b #568/#574 pattern.

bosun referenced this issue

2026-07-29 10:14:55 +02:00

docs(#583 follow-up): tighten minLength scope claim in workflow-api.md + test comment — gate doesn't parse minLength #587