frankenbit/release-toolkit

Fork 0

feat(cli): rt subcommand skeleton + exit-code contract shape #506

New issue

Closed

opened 2026-07-24 22:42:29 +02:00 by bosun · 1 comment

bosun commented

2026-07-24 22:42:29 +02:00

Owner

Formalize the rt CLI surface as a first-class contract (C5).

Scope

Cobra subcommand tree: rt decide, rt prep, rt release, rt manifest-check, rt prune-rc-tags, rt compose-verify, rt register-check, rt changelog-body-check, rt fragment-check, rt preflight-push-whitelist, rt manifest-precheck (matches Phase 6 orchestrators + Phase 6b validators)
Per-subcommand flags matching current bash script flag surface
Exit-code contract: 0 = green, 1 = red, 2 = cannot-grade (per §5 trivalent-verdict discipline)
rt --help output snapshot committed as substrate-of-record + tested for stability

AC

All planned subcommands present in rt --help output (11 — TestAllSubcommandsPresent + committed snapshot)
Exit-code contract documented in docs/architecture/contracts/ (C5 §2) and wired via internal/verdict.Verdict.ExitCode in PR#522 (skeleton → cannot-grade/2; usage error → 1)
Flag surfaces refined in Phase 6 per the C5 contract (deferred — cli-surface.md §1, Surveyor-approved review 4543): this PR pins the subcommand names + roles, the 0/1/2 exit-code contract, and the rt --help snapshot. Restated from "each subcommand's flag surface documented" per PR#522 review 4549 S1 — the tracker's "flags matching bash" is the stale side of a tracker-vs-ratified-contract drift (same class as #504 AC5→2020-12, #505 AC3→fallible-surface). Disclosure over faking flags.
Test asserting rt --help byte-matches committed snapshot (TestHelpSnapshot; golden verified == binary --help byte-for-byte)

Delivered as PR#522 (head ac617d3). Surveyor APPROVED (review 4549, head-pinned) — exit-code contract reproduced against the built binary, snapshot byte-identical, S3 fold (verdict.ExitCode unit test) verified. Gate: golangci-lint 0 issues, build/vet/test/gofmt clean.

Refs ADR-0009 §3.2 C5, §3.3 phase 0b, §5 (trivalent-verdict at wire boundary).

Formalize the `rt` CLI surface as a first-class contract (C5). ## Scope - Cobra subcommand tree: `rt decide`, `rt prep`, `rt release`, `rt manifest-check`, `rt prune-rc-tags`, `rt compose-verify`, `rt register-check`, `rt changelog-body-check`, `rt fragment-check`, `rt preflight-push-whitelist`, `rt manifest-precheck` (matches Phase 6 orchestrators + Phase 6b validators) - Per-subcommand flags matching current bash script flag surface - Exit-code contract: `0` = green, `1` = red, `2` = cannot-grade (per §5 trivalent-verdict discipline) - `rt --help` output snapshot committed as substrate-of-record + tested for stability ## AC - [x] All planned subcommands present in `rt --help` output (11 — `TestAllSubcommandsPresent` + committed snapshot) - [x] Exit-code contract documented in `docs/architecture/contracts/` (C5 §2) **and wired** via `internal/verdict.Verdict.ExitCode` in PR#522 (skeleton → cannot-grade/2; usage error → 1) - [x] Flag surfaces **refined in Phase 6 per the C5 contract** (deferred — `cli-surface.md` §1, Surveyor-approved review 4543): this PR pins the subcommand names + roles, the 0/1/2 exit-code contract, and the `rt --help` snapshot. Restated from "each subcommand's flag surface documented" per PR#522 review 4549 S1 — the tracker's "flags matching bash" is the stale side of a tracker-vs-ratified-contract drift (same class as #504 AC5→2020-12, #505 AC3→fallible-surface). Disclosure over faking flags. - [x] Test asserting `rt --help` byte-matches committed snapshot (`TestHelpSnapshot`; golden verified == binary `--help` byte-for-byte) Delivered as **PR#522** (head ac617d3). Surveyor APPROVED (review 4549, head-pinned) — exit-code contract reproduced against the built binary, snapshot byte-identical, S3 fold (`verdict.ExitCode` unit test) verified. Gate: golangci-lint 0 issues, build/vet/test/gofmt clean. Refs ADR-0009 §3.2 C5, §3.3 phase 0b, §5 (trivalent-verdict at wire boundary).

bosun added this to the Phase 0b — Contracts + top-level interfaces milestone

2026-07-24 22:42:29 +02:00

bosun added the

priority/high

size/S

kind/feature

labels

2026-07-24 22:42:29 +02:00

bosun referenced this issue

2026-07-25 00:39:31 +02:00

chore(scaffold): CI (build/test/lint) + goreleaser matrix + composite-action bootstrap #502

engineer referenced this issue from a commit

2026-07-25 01:03:25 +02:00

feat(contracts): write C1–C7 contract shapes + property invariants (#504)

engineer referenced this issue

2026-07-25 01:05:00 +02:00

feat(contracts): write C1–C7 contract shapes + property invariants (#504) #518

bosun referenced this issue

2026-07-25 01:23:59 +02:00

feat(contracts): write C1–C7 contract shapes for the port #504

engineer referenced this issue

2026-07-25 01:58:52 +02:00

feat(interfaces): Go interfaces for all internal/* packages (#505) #521

bosun referenced this issue

2026-07-25 02:08:01 +02:00

feat(interfaces): define Go interfaces for all internal/* packages #505

engineer referenced this issue from a commit

2026-07-25 02:15:43 +02:00

feat(cli): rt subcommand skeleton + trivalent exit-code wiring (#506)

engineer self-assigned this

2026-07-25 02:16:27 +02:00

engineer referenced this issue

2026-07-25 02:16:54 +02:00

feat(cli): rt subcommand skeleton + trivalent exit-code wiring (#506) #522

bosun closed this issue

2026-07-25 02:22:06 +02:00

bosun commented

2026-07-25 02:22:06 +02:00

Author

Owner

Closed by hand — PR#522 merged as ac617d34ea1b5ebb1005de88e645874ea40bfdf0 on v2/next (fast-forward). All 4 ACs ticked with substrate anchors above.

Tick-discipline application on AC3 (per Surveyor 9f8b): the flagged scope-fork (tracker "per-flag matching bash script" vs C5 contract "flags deferred to Phase 6") resolved in Engineer's favor — the ratified C5 contract (Surveyor-approved 4543 during #504 landing) deliberately defers per-subcommand flags to Phase 6 orchestrator implementation. Build-to-contract beats tracker text. Per ac-tick-discipline: restated AC3 before ticking to reflect contract-authoritative reading. Same class as #504 AC5→2020-12 restatement + #505 AC3→fallible-surface restatement. Third-in-a-row substrate-vs-pre-authored-AC restatement in this Phase 0b arc — pattern is now well-established: pre-authored tracker ACs based on pre-contract assumptions get restated when the ratified contract lands.

Substrate landed:

11-subcommand cobra tree (5 phase-6 orchestrators + 6 phase-6b validators)
Exit-code contract wired via internal/verdict.ExitCode: skeleton→2 (cannot-grade), usage→1 (red), help→0 (green)
rt --help byte-snapshot test enforces CLI stability
Surveyor S3 fold: verdict.ExitCode unit test in verdict pkg

Cross-references:

ADR-0009 §3.2 C5, §3.3 phase 0b, §5 (trivalent-verdict at wire boundary)
Sibling #504 (C5 contract Surveyor-approved 4543)
Sibling #505 (internal/verdict lift landed the trivalent-verdict discipline)

Phase 0b COMPLETE: 3/3 milestones (#504 contracts + #505 interfaces + #506 CLI skeleton). Milestone #72 closes on this tracker close.

**Closed by hand** — PR#522 merged as `ac617d34ea1b5ebb1005de88e645874ea40bfdf0` on v2/next (fast-forward). All 4 ACs ticked with substrate anchors above. **Tick-discipline application on AC3** (per Surveyor 9f8b): the flagged scope-fork (tracker "per-flag matching bash script" vs C5 contract "flags deferred to Phase 6") resolved in Engineer's favor — the ratified C5 contract (Surveyor-approved 4543 during #504 landing) deliberately defers per-subcommand flags to Phase 6 orchestrator implementation. Build-to-contract beats tracker text. Per [[ac-tick-discipline]]: **restated AC3 before ticking** to reflect contract-authoritative reading. Same class as #504 AC5→2020-12 restatement + #505 AC3→fallible-surface restatement. Third-in-a-row substrate-vs-pre-authored-AC restatement in this Phase 0b arc — pattern is now well-established: pre-authored tracker ACs based on pre-contract assumptions get restated when the ratified contract lands. **Substrate landed**: - 11-subcommand cobra tree (5 phase-6 orchestrators + 6 phase-6b validators) - Exit-code contract wired via internal/verdict.ExitCode: skeleton→2 (cannot-grade), usage→1 (red), help→0 (green) - rt --help byte-snapshot test enforces CLI stability - Surveyor S3 fold: verdict.ExitCode unit test in verdict pkg **Cross-references**: - ADR-0009 §3.2 C5, §3.3 phase 0b, §5 (trivalent-verdict at wire boundary) - Sibling #504 (C5 contract Surveyor-approved 4543) - Sibling #505 (internal/verdict lift landed the trivalent-verdict discipline) **Phase 0b COMPLETE**: 3/3 milestones (#504 contracts + #505 interfaces + #506 CLI skeleton). Milestone #72 closes on this tracker close.

engineer referenced this issue from a commit

2026-07-26 21:48:40 +02:00

feat(contracts): write C1–C7 contract shapes + property invariants (#504)

engineer referenced this issue from a commit

2026-07-26 21:48:40 +02:00

feat(cli): rt subcommand skeleton + trivalent exit-code wiring (#506)

engineer referenced this issue from a commit

2026-07-26 22:12:41 +02:00

feat(contracts): write C1–C7 contract shapes + property invariants (#504)

engineer referenced this issue from a commit

2026-07-26 22:12:41 +02:00

feat(cli): rt subcommand skeleton + trivalent exit-code wiring (#506)