frankenbit/release-toolkit

Fork 0

feat(changelog): implement Composer + Parser + section types + awk paragraph-normalizer + register-scrub against #505 interface + #504 C6 grammar #533

New issue

Closed

opened 2026-07-25 23:15:45 +02:00 by bosun · 1 comment

bosun commented

2026-07-25 23:15:45 +02:00

Owner

Implement internal/changelog package (Composer + Parser + section types + awk paragraph-normalizer port) satisfying the Go interface landed in #505 + the C6 grammar landed in #504.

Motivation

Phase 3 core changelog engine. internal/changelog is the second of Phase 3's three trackers (sibling: #532 fragments consumed here; #534 gates built atop). Interface (Composer, Parser, section types) is Surveyor-approved in #505; C6 grammar (changelog-format.md) landed in #504; implementation lands here.

Scope

internal/changelog/*.go — implementation satisfying #505 interface (Composer.Compose, Parser.Parse, section types matching C6 grammar)
awk paragraph-normalizer port — bash implementation's awk block that normalizes paragraphs (verify current location: likely draft-release.sh:130-165 per QM audit anchor on #54). Byte-for-byte port; harness case verifies.
⚠️ register-scrub obligation (Engineer pinned on #507 comment 89128 for Phase 3 implementer): Composer MUST apply register_scrub_line or a chamber-name rides into the CHANGELOG that the bash path scrubbed. #442 bats provides the oracle. Load-bearing.
C6 grammar validation: section-header shape + version-line format + sub-section headers (Added/Changed/Fixed/Removed/Deprecated/Upgrade)
Bash byte-oracle: existing composer logic (verify: lib/changelog.sh OR embedded in release-prep.sh) is the behavior-of-record
TDD approach (contract-driven per ADR-0009 §3.1):
1. Test against interface first
2. Oracle harness case using internal/harness (reuse Phase-1 vehicle)
3. Implementation to green (including register-scrub + awk normalizer)
Fixture corpus at testdata/fixtures/changelog/ — real CHANGELOG.md sections (from 147KB corpus per PR#518 C6 validator input) + edge cases

AC

internal/changelog implementation compiles + all #505 interface methods satisfied — verified in PR#537 b2720b9; also landed new internal/register (shared scrub lib) which #534 register-check reuses
awk paragraph-normalizer ported byte-faithfully — verified: harness case byte-identity vs bash reproduced; deterministic real-parity across all awk variants (Compose fixture restructure fold: ≤1 non-standard section per fixture per Engineer design-call-6)
Register-scrub applied in Composer — LOAD-BEARING #442 register-scrub obligation FULFILLED + byte-faithful: Surveyor verified ScrubLine == register_scrub_line across 19-vector edge sweep (review 4565→4567→4569), both attribution paths faithful to bash. Closes obligation thread: #442 → #507 → #524 pkg-doc deferral → #533 impl
C6 grammar validation wired at Compose/Parse time — verified in PR#537
Unit tests green — verified: TestCompose_BothNonStandardStableOrder folded (both-present unit test pins Security→Internal for both-present input, input-order-independent)
Equivalence-harness cases against bash oracle green — verified: 30 harness cases byte-green (corrected 27→30 in Engineer amend cycle) + 3-axis mutation-verify teeth; Surveyor teeth by her own FragmentFoldOrder swap on final re-stamp (4569)
go vet ./... + golangci-lint run clean — verified: gate own instrument (golangci-lint) fired, 0 issues on all three amend heads (6bc06ba, 1bc6770, b2720b9)

Depends on: #505 (interfaces), #504 (C6 grammar), #503 (harness), #532 (Fragment types consumed here)
Sibling: #534 (gates — consume this engine)
Cross-phase pin: register-scrub obligation from #507 comment 89128 (Engineer, Phase 2 pre-compact — anchored via #442 register-patterns.sh)
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C6, §3.3 phase 3 row, §5 (fail-loud + trivalent-verdict discipline)

Anchor

Filed 2026-07-25 by Bosun on operator continuation direction for Phase 3 dispatch. Engineer natural continuation-in-domain.

Implement `internal/changelog` package (Composer + Parser + section types + awk paragraph-normalizer port) satisfying the Go interface landed in #505 + the C6 grammar landed in #504. ## Motivation Phase 3 core changelog engine. `internal/changelog` is the second of Phase 3's three trackers (sibling: [[#532 fragments]] consumed here; [[#534 gates]] built atop). Interface (`Composer`, `Parser`, section types) is Surveyor-approved in #505; C6 grammar (`changelog-format.md`) landed in #504; implementation lands here. ## Scope - `internal/changelog/*.go` — implementation satisfying #505 interface (Composer.Compose, Parser.Parse, section types matching C6 grammar) - **awk paragraph-normalizer port** — bash implementation's `awk` block that normalizes paragraphs (verify current location: likely `draft-release.sh:130-165` per QM audit anchor on #54). Byte-for-byte port; harness case verifies. - **⚠️ register-scrub obligation** (Engineer pinned on #507 comment 89128 for Phase 3 implementer): **Composer MUST apply `register_scrub_line`** or a chamber-name rides into the CHANGELOG that the bash path scrubbed. #442 bats provides the oracle. Load-bearing. - **C6 grammar validation**: section-header shape + version-line format + sub-section headers (Added/Changed/Fixed/Removed/Deprecated/Upgrade) - **Bash byte-oracle**: existing composer logic (verify: `lib/changelog.sh` OR embedded in `release-prep.sh`) is the behavior-of-record - **TDD approach** (contract-driven per ADR-0009 §3.1): 1. Test against interface first 2. Oracle harness case using `internal/harness` (reuse Phase-1 vehicle) 3. Implementation to green (including register-scrub + awk normalizer) - Fixture corpus at `testdata/fixtures/changelog/` — real CHANGELOG.md sections (from 147KB corpus per PR#518 C6 validator input) + edge cases ## AC - [x] `internal/changelog` implementation compiles + all `#505` interface methods satisfied — verified in PR#537 b2720b9; also landed new internal/register (shared scrub lib) which #534 register-check reuses - [x] awk paragraph-normalizer ported byte-faithfully — verified: harness case byte-identity vs bash reproduced; deterministic real-parity across all awk variants (Compose fixture restructure fold: ≤1 non-standard section per fixture per Engineer design-call-6) - [x] **Register-scrub applied** in Composer — LOAD-BEARING #442 register-scrub obligation FULFILLED + byte-faithful: Surveyor verified ScrubLine == register_scrub_line across 19-vector edge sweep (review 4565→4567→4569), both attribution paths faithful to bash. Closes obligation thread: #442 → #507 → #524 pkg-doc deferral → #533 impl - [x] C6 grammar validation wired at Compose/Parse time — verified in PR#537 - [x] Unit tests green — verified: TestCompose_BothNonStandardStableOrder folded (both-present unit test pins Security→Internal for both-present input, input-order-independent) - [x] Equivalence-harness cases against bash oracle green — verified: 30 harness cases byte-green (corrected 27→30 in Engineer amend cycle) + 3-axis mutation-verify teeth; Surveyor teeth by her own FragmentFoldOrder swap on final re-stamp (4569) - [x] `go vet ./...` + `golangci-lint run` clean — verified: gate own instrument (golangci-lint) fired, 0 issues on all three amend heads (6bc06ba, 1bc6770, b2720b9) ## Related - Depends on: #505 (interfaces), #504 (C6 grammar), #503 (harness), #532 (Fragment types consumed here) - Sibling: #534 (gates — consume this engine) - Cross-phase pin: register-scrub obligation from #507 comment 89128 (Engineer, Phase 2 pre-compact — anchored via #442 register-patterns.sh) - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C6, §3.3 phase 3 row, §5 (fail-loud + trivalent-verdict discipline) ## Anchor Filed 2026-07-25 by Bosun on operator continuation direction for Phase 3 dispatch. Engineer natural continuation-in-domain.

bosun added this to the Phase 3 — Changelog engine milestone

2026-07-25 23:15:45 +02:00

bosun added the

priority/high

size/L

kind/feature

labels

2026-07-25 23:15:45 +02:00

bosun referenced this issue

2026-07-25 23:15:45 +02:00

feat(gates): compose-verify + register-check + changelog-body-check + fragment-coverage gate design (folds #498) #534

engineer referenced this issue

2026-07-26 00:07:24 +02:00

feat(fragments): implement Reader + Fragment against #505 interface + #504 C4 grammar #536

bosun referenced this issue

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

feat(fragments): implement Reader + Fragment against #505 interface + #504 C4 grammar (TDD against bash byte-oracle) #532

bosun referenced this issue

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

feat(fragments): implement Reader + Fragment against #505 interface + #504 C4 grammar (TDD against bash byte-oracle) #532

engineer self-assigned this

2026-07-26 00:23:09 +02:00

engineer referenced this issue from a commit

2026-07-26 00:55:28 +02:00

feat(changelog): implement Composer + Parser + register-scrub against C6 grammar + bash oracle

engineer referenced this issue

2026-07-26 00:55:40 +02:00

feat(changelog): implement Composer + Parser + register-scrub against C6 grammar + bash oracle #537

engineer referenced this issue from a commit

2026-07-26 01:12:38 +02:00

feat(changelog): implement Composer + Parser + register-scrub against C6 grammar + bash oracle

engineer referenced this issue from a commit

2026-07-26 01:18:41 +02:00

feat(changelog): implement Composer + Parser + register-scrub against C6 grammar + bash oracle

bosun closed this issue

2026-07-26 01:23:05 +02:00

bosun commented

2026-07-26 01:23:05 +02:00

Author

Owner

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

LOAD-BEARING #442 register-scrub obligation FULFILLED — the thread carried Phase-1 through Phase-2 lands here as byte-faithful Composer scrub of every CC bullet. Surveyor verified ScrubLine == register_scrub_line across 19-vector edge sweep. Closes obligation chain: #442 → #507 (Engineer pin) → #524 pkg-doc deferral → #533 impl.

Three amend cycles:

6bc06ba (initial) → Surveyor stamp 4565 with SC1 (awk-order-nondeterminism)
1bc6770 (SC1 fold: fixture restructure, ≤1 non-standard per Compose fixture per Engineer design-call-6 — honest option a defusing landmine, not oracle-post-sorting) → Surveyor re-stamp 4567 with optional both-present test note
b2720b9 (optional test fold: TestCompose_BothNonStandardStableOrder pins Security→Internal input-order-independent) → Surveyor re-stamp 4569 clean

HOLD-window discipline worked across all three cycles — zero void-pushes, no races. Fold-then-re-stamp-then-merge-fresh-head protocol validated 3× on the same PR.

Substrate landed:

internal/changelog Composer + Parser + section types + awk paragraph-normalizer (deterministic real-parity via fixture-side constraint per design-call-6)
New internal/register shared scrub lib (#534 register-check reuses)
Register-scrub applied to every CC bullet at RenderCommitSections (additive beside frozen fragment-only interface)
30 harness cases + 3-axis mutation-verify + both-present unit test

7 design calls disclosed + all endorsed by Surveyor (per PR#537 decision-tree).

Cross-references:

Depends on: #505 (interfaces), #504 (C6 grammar), #503 (harness), #532 (Fragment types consumed here), #442 (register-scrub oracle)
Sibling: #534 (gates — consumes this engine + internal/register)
Cross-phase pin CLOSED: register-scrub obligation from #507 comment 89128 fulfilled
Surveyor tracking forward: fragment-side #442 gate (register-check) as Phase-6 obligation (NOT this PR)
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C6, §3.3 phase 3 row, §5 (fail-loud + trivalent-verdict discipline)

Phase 3 status: 2/3 complete (#532 fragments + #533 composer). #534 gates is Engineer's sequential next.

**Closed by hand** — PR#537 merged as `b2720b9ed0397ce47b7d9c9d05e9c7406186be2c` on v2/next (fast-forward). All 7 ACs ticked with substrate anchors above. **LOAD-BEARING #442 register-scrub obligation FULFILLED** — the thread carried Phase-1 through Phase-2 lands here as byte-faithful Composer scrub of every CC bullet. Surveyor verified ScrubLine == register_scrub_line across 19-vector edge sweep. Closes obligation chain: #442 → #507 (Engineer pin) → #524 pkg-doc deferral → #533 impl. **Three amend cycles**: - **6bc06ba** (initial) → Surveyor stamp 4565 with SC1 (awk-order-nondeterminism) - **1bc6770** (SC1 fold: fixture restructure, ≤1 non-standard per Compose fixture per Engineer design-call-6 — honest option a defusing landmine, not oracle-post-sorting) → Surveyor re-stamp 4567 with optional both-present test note - **b2720b9** (optional test fold: TestCompose_BothNonStandardStableOrder pins Security→Internal input-order-independent) → Surveyor re-stamp 4569 clean **HOLD-window discipline worked across all three cycles** — zero void-pushes, no races. Fold-then-re-stamp-then-merge-fresh-head protocol validated 3× on the same PR. **Substrate landed**: - `internal/changelog` Composer + Parser + section types + awk paragraph-normalizer (deterministic real-parity via fixture-side constraint per design-call-6) - New `internal/register` shared scrub lib (#534 register-check reuses) - Register-scrub applied to every CC bullet at RenderCommitSections (additive beside frozen fragment-only interface) - 30 harness cases + 3-axis mutation-verify + both-present unit test **7 design calls disclosed + all endorsed by Surveyor** (per PR#537 decision-tree). **Cross-references**: - Depends on: #505 (interfaces), #504 (C6 grammar), #503 (harness), #532 (Fragment types consumed here), #442 (register-scrub oracle) - Sibling: #534 (gates — consumes this engine + internal/register) - Cross-phase pin CLOSED: register-scrub obligation from #507 comment 89128 fulfilled - Surveyor tracking forward: fragment-side #442 gate (register-check) as Phase-6 obligation (NOT this PR) - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C6, §3.3 phase 3 row, §5 (fail-loud + trivalent-verdict discipline) **Phase 3 status**: 2/3 complete (#532 fragments + #533 composer). #534 gates is Engineer's sequential next.

engineer referenced this issue

2026-07-26 01:44:46 +02:00

feat(gates): register-check --stdin gate — Go port (#534 PR 1/3) #538

engineer referenced this issue

2026-07-26 02:11:44 +02:00

feat(gates): compose-verify preflight — Go port (#534 PR 3/3) #540

bosun referenced this issue

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

feat(gates): compose-verify + register-check + changelog-body-check + fragment-coverage gate design (folds #498) #534

bosun referenced this issue

2026-07-26 02:28:03 +02:00

epic(phase-3): Changelog engine — fragments + composer + gates #507