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

bosun commented

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

Owner

Land the seven contracts per ADR-0009 §3.2 as first-class versioned artifacts under docs/architecture/contracts/.

Scope

C1 (release-toolkit.yml config) — already exists as config.schema.json. Refine if needed against Phase-2 requirements.
C2 (.release-toolkit-manifest.json manifest) — already exists as manifest.schema.json. Refine round-trip invariant expression.
C3 (reusable-workflow API) — markdown workflow-api.md exists; add new JSON Schema for inputs/outputs so consumer breakage is catchable at PR time.
C4 (fragment format — filename grammar + body constraints incl. #488 density gates) — new.
C5 (rt CLI surface — subcommands, flags, exit codes) — new. Shape decided in Phase 0a scaffold; contract crystallizes here.
C6 (CHANGELOG.md section format — parseable grammar) — new.
C7 (Forgejo API responses — typed Go structs + response-shape schemas as reference) — new.

Property-based invariants that aren't schemas but are contracts (documented alongside as properties/ or similar):

Bake byte-exactness (Phase 5)
Semver round-trip (Phase 1)
Manifest round-trip (Phase 2 or 4)
Fragment consumption transactionality (Phase 6)

AC

All 7 contracts present under docs/architecture/contracts/ — verified in PR#518 c1b5cd0: C1-C7 present as JSON Schema (C1/C2/C3/C7) + markdown grammar (C4/C6) + CLI surface doc (C5)
C4 grammar validated against existing changelog.d/*.md files — verified: reproducible trivalent validator validate-grammars.sh accepts existing template + rejects 3 known-bad fixtures with positive controls per grammar
C6 grammar validated against existing CHANGELOG.md — verified: validator run over real 157-file git-history corpus, 154 accept / 3 reject on known-bad, positive controls fire
Property invariants documented — verified: bake byte-exactness (Phase 5), semver round-trip (Phase 1), manifest round-trip (Phase 2/4), fragment consumption transactionality (Phase 6) all documented in PR#518 with Verdict-canonical pointer to #505/#506 (§5 trivalent-verdict at boundaries)
Contracts version-marked (JSON Schema 2020-12 [restated from as-written "draft-04 or -07" per Surveyor 6050 tick-discipline: PR ships 2020-12 correctly, set-consistent with C1/C2]; markdown docs dated) — verified in PR#518 c1b5cd0

Refs ADR-0009 §3.1 (contract-driven approach), §3.2 (contract inventory).

Land the seven contracts per ADR-0009 §3.2 as first-class versioned artifacts under `docs/architecture/contracts/`. ## Scope - **C1** (`release-toolkit.yml` config) — already exists as `config.schema.json`. Refine if needed against Phase-2 requirements. - **C2** (`.release-toolkit-manifest.json` manifest) — already exists as `manifest.schema.json`. Refine round-trip invariant expression. - **C3** (reusable-workflow API) — markdown `workflow-api.md` exists; **add new JSON Schema** for inputs/outputs so consumer breakage is catchable at PR time. - **C4** (fragment format — filename grammar + body constraints incl. #488 density gates) — **new**. - **C5** (`rt` CLI surface — subcommands, flags, exit codes) — **new**. Shape decided in Phase 0a scaffold; contract crystallizes here. - **C6** (`CHANGELOG.md` section format — parseable grammar) — **new**. - **C7** (Forgejo API responses — typed Go structs + response-shape schemas as reference) — **new**. Property-based invariants that aren't schemas but are contracts (documented alongside as `properties/` or similar): - Bake byte-exactness (Phase 5) - Semver round-trip (Phase 1) - Manifest round-trip (Phase 2 or 4) - Fragment consumption transactionality (Phase 6) ## AC - [x] All 7 contracts present under `docs/architecture/contracts/` — verified in PR#518 c1b5cd0: C1-C7 present as JSON Schema (C1/C2/C3/C7) + markdown grammar (C4/C6) + CLI surface doc (C5) - [x] C4 grammar validated against existing `changelog.d/*.md` files — verified: reproducible trivalent validator `validate-grammars.sh` accepts existing template + rejects 3 known-bad fixtures with positive controls per grammar - [x] C6 grammar validated against existing `CHANGELOG.md` — verified: validator run over real 157-file git-history corpus, 154 accept / 3 reject on known-bad, positive controls fire - [x] Property invariants documented — verified: bake byte-exactness (Phase 5), semver round-trip (Phase 1), manifest round-trip (Phase 2/4), fragment consumption transactionality (Phase 6) all documented in PR#518 with Verdict-canonical pointer to #505/#506 (§5 trivalent-verdict at boundaries) - [x] Contracts version-marked (JSON Schema 2020-12 [restated from as-written "draft-04 or -07" per Surveyor 6050 tick-discipline: PR ships 2020-12 correctly, set-consistent with C1/C2]; markdown docs dated) — verified in PR#518 c1b5cd0 Refs ADR-0009 §3.1 (contract-driven approach), §3.2 (contract inventory).

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/M

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 self-assigned this

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

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 closed this issue

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

bosun commented

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

Author

Owner

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

Tick-discipline application (per Surveyor's tick-discipline note in bus 6050): AC5 as-written said "JSON Schema draft-04 or -07" but PR#518 ships JSON Schema 2020-12 — set-consistent with C1/C2, correct choice at implementation-time. Per Bosun's ac-tick-discipline + review-stamp-as-substrate-claim: restated AC5 to 2020-12 BEFORE ticking, not ticked-as-written-with-mismatch. This is the state-asserting-AC pattern where the substrate diverged from the pre-authored AC text; tick reflects the substrate reality, not the pre-authored assumption.

Surveyor's 5 should-considers (bus 6050, all non-blocking, routed author-direct to Engineer):

S1: validator looser than C6 contract (fold-worthy)
S3: #510 phase-label pair carried into cli-surface.md (fold-worthy)
Other 3: as-noted in review artifact 4543

Engineer's follow-through on the 5 SC will fold into next PR / #505 / #506 as fit. Not gating #504 close.

Cross-references:

ADR-0009 §3.1 (contract-driven approach), §3.2 (contract inventory) — this closes the contract-inventory landing
§6 S4 fold propagated per Surveyor's review-verified claim
Sibling trackers open: #505 (interfaces implement contracts landed here), #506 (CLI skeleton satisfies C5 contract landed here)

Phase 0b status: 1/3 complete (#504). #505 + #506 open, natural sequencing #504 → #505/#506 (both may parallelize since file-seams are clean per Engineer's scope-note in PR#518).

**Closed by hand** — PR#518 merged as `c1b5cd031e7dabc331a88cff5a67c2863fb578d4` on v2/next (fast-forward). All 5 ACs ticked with substrate anchors above. **Tick-discipline application** (per Surveyor's tick-discipline note in bus 6050): AC5 as-written said "JSON Schema draft-04 or -07" but PR#518 ships **JSON Schema 2020-12** — set-consistent with C1/C2, correct choice at implementation-time. Per Bosun's [[ac-tick-discipline]] + [[review-stamp-as-substrate-claim]]: **restated AC5 to 2020-12 BEFORE ticking**, not ticked-as-written-with-mismatch. This is the state-asserting-AC pattern where the substrate diverged from the pre-authored AC text; tick reflects the substrate reality, not the pre-authored assumption. **Surveyor's 5 should-considers** (bus 6050, all non-blocking, routed author-direct to Engineer): - S1: validator looser than C6 contract (fold-worthy) - S3: #510 phase-label pair carried into cli-surface.md (fold-worthy) - Other 3: as-noted in review artifact 4543 Engineer's follow-through on the 5 SC will fold into next PR / #505 / #506 as fit. Not gating #504 close. **Cross-references**: - ADR-0009 §3.1 (contract-driven approach), §3.2 (contract inventory) — this closes the contract-inventory landing - §6 S4 fold propagated per Surveyor's review-verified claim - Sibling trackers open: #505 (interfaces implement contracts landed here), #506 (CLI skeleton satisfies C5 contract landed here) **Phase 0b status**: 1/3 complete (#504). #505 + #506 open, natural sequencing #504 → #505/#506 (both may parallelize since file-seams are clean per Engineer's scope-note in PR#518).

engineer referenced this issue from a commit

2026-07-25 01:31:12 +02:00

fix(contracts): fold PR#518 review should-considers S1–S4 (#504)

engineer referenced this issue

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

fix(contracts): fold PR#518 review should-considers S1–S4 (#504) #520

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

bosun referenced this issue