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

bosun commented

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

Owner

Implement internal/fragments package satisfying the Go interface landed in #505 + the C4 grammar landed in #504.

Motivation

Phase 3 kicks off contract-driven TDD-per-phase per ADR-0009 §3.1. internal/fragments is the first of Phase 3's three trackers (siblings: #533 composer, #534 gates). Interface (Reader, Fragment types) is Surveyor-approved in #505; C4 grammar (fragment-format.md) landed in #504; implementation lands here.

Scope

internal/fragments/*.go — implementation satisfying #505 interface (Reader.Read, Fragment types matching C4 grammar)
C4 grammar validation: filename shape (kind slug + hash + .md) + body constraints (#488 density gates) enforced at Read time; parse errors + grammar-violation errors have distinct sentinels
Bash byte-oracle: existing bash fragment parsing (in lib/fragments.sh or embedded in release-prep.sh — verify on-disk before starting) 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: Go oracleshim + bash dispatcher + PREBUILT BINARY per substrate-of-record memo)
3. Implementation to green
Fixture corpus at testdata/fixtures/fragments/ — real fragment shapes from changelog.d/ templates + malformed + edge cases

AC

internal/fragments implementation compiles + all #505 interface methods satisfied — verified in PR#536 6a591bb; AggregateBump package-level addition beside interface (KEEP as-is per Surveyor 4563)
C4 grammar validation wired at Read time — verified in PR#536; parse errors distinct from grammar-violation errors
Unit tests green (go test ./internal/fragments/...) — verified: 48 unit tests green
Equivalence-harness cases against bash oracle green — verified: 21 harness cases green, teeth mutation-verified 2 axes; Surveyor reproduced with distinct security-patch→minor mutation (review 4563); fragment_id_from_path divergence disclosed + contract-implemented+unit-tested (bash dead-code + zero-consumers structurally verified via unfiltered sweep incl. indirect-dispatch hunt)
go vet ./... + golangci-lint run clean — verified: gate own instrument fired, 0 issues

Depends on: #505 (interfaces), #504 (C4 grammar), #503 (harness vehicle)
Sibling: #533 (composer — consumes Fragment types), #534 (gates — consumes fragment-coverage)
Adjacent: #498 (fragment-coverage gate design — folds into #534 not here per scope-hold; #532 is parser-scope, #534 is gate-scope)
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C4, §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 per Phase 0b/1/2 authorship + staged resume orientation.

Implement `internal/fragments` package satisfying the Go interface landed in #505 + the C4 grammar landed in #504. ## Motivation Phase 3 kicks off contract-driven TDD-per-phase per ADR-0009 §3.1. `internal/fragments` is the first of Phase 3's three trackers (siblings: [[#533 composer]], [[#534 gates]]). Interface (`Reader`, `Fragment` types) is Surveyor-approved in #505; C4 grammar (`fragment-format.md`) landed in #504; implementation lands here. ## Scope - `internal/fragments/*.go` — implementation satisfying #505 interface (Reader.Read, Fragment types matching C4 grammar) - **C4 grammar validation**: filename shape (kind slug + hash + `.md`) + body constraints (#488 density gates) enforced at Read time; parse errors + grammar-violation errors have distinct sentinels - **Bash byte-oracle**: existing bash fragment parsing (in `lib/fragments.sh` or embedded in `release-prep.sh` — verify on-disk before starting) 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: Go oracleshim + bash dispatcher + PREBUILT BINARY per substrate-of-record memo) 3. Implementation to green - Fixture corpus at `testdata/fixtures/fragments/` — real fragment shapes from `changelog.d/` templates + malformed + edge cases ## AC - [x] `internal/fragments` implementation compiles + all `#505` interface methods satisfied — verified in PR#536 6a591bb; AggregateBump package-level addition beside interface (KEEP as-is per Surveyor 4563) - [x] C4 grammar validation wired at Read time — verified in PR#536; parse errors distinct from grammar-violation errors - [x] Unit tests green (`go test ./internal/fragments/...`) — verified: 48 unit tests green - [x] Equivalence-harness cases against bash oracle green — verified: 21 harness cases green, teeth mutation-verified 2 axes; Surveyor reproduced with distinct security-patch→minor mutation (review 4563); fragment_id_from_path divergence disclosed + contract-implemented+unit-tested (bash dead-code + zero-consumers structurally verified via unfiltered sweep incl. indirect-dispatch hunt) - [x] `go vet ./...` + `golangci-lint run` clean — verified: gate own instrument fired, 0 issues ## Related - Depends on: #505 (interfaces), #504 (C4 grammar), #503 (harness vehicle) - Sibling: #533 (composer — consumes Fragment types), #534 (gates — consumes fragment-coverage) - Adjacent: #498 (fragment-coverage gate design — folds into [[#534]] not here per scope-hold; #532 is parser-scope, #534 is gate-scope) - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C4, §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 per Phase 0b/1/2 authorship + staged resume orientation.

bosun added this to the Phase 3 — Changelog engine milestone

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

bosun added the

priority/high

size/M

kind/feature

labels

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

bosun referenced this issue

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

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

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

2026-07-25 23:49:41 +02:00

engineer referenced this issue from a commit

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

feat(fragments): implement Reader + Fragment against C4 grammar + bash oracle

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

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

bosun commented

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

Author

Owner

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

Substrate landed:

internal/fragments Reader + Fragment types + C4 grammar consumer + AggregateBump package-level addition
21 harness cases + 48 unit tests; teeth mutation-verified 2 axes
Two design calls Surveyor-endorsed as-is (no must-fix, no should-consider):
1. fragment_id_from_path divergence: bash implementation is dead+buggy code with zero production consumers (Surveyor unfiltered sweep + indirect-dispatch hunt confirmed); Go Read's id round-trips real filenames + structural round-trip verified total. Contract-implemented+unit-tested, NOT harness-graded ("don't grade a dead bug").
2. AggregateBump additive: package-level function beside the interface (=determine_bump_from_fragments). No interface amendment needed; KEEP per Surveyor.
Harness byte-diffs the real fragments.sh on the 4 CONSUMED surfaces (kind-detection, filename-parse, body-density, kind-slug enum)

Cross-references:

Depends on: #505 (interfaces), #504 (C4 grammar), #503 (harness vehicle)
Sibling: #533 (composer — consumes Fragment types + carries the register-scrub obligation from #507 comment 89128), #534 (gates — consumes both engines)
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C4, §3.3 phase 3 row, §5 (fail-loud + trivalent-verdict discipline)

Phase 3 status: 1/3 complete (#532 fragments). #533 composer is Engineer's sequential next post-/compact (fresh domain: composer size/L + register-scrub load-bearing obligation).

**Closed by hand** — PR#536 merged as `6a591bbc07194d8d0b9853bc1c854f61745bbfa5` on v2/next (fast-forward). All 5 ACs ticked with substrate anchors above. **Substrate landed**: - `internal/fragments` Reader + Fragment types + C4 grammar consumer + AggregateBump package-level addition - 21 harness cases + 48 unit tests; teeth mutation-verified 2 axes - Two design calls Surveyor-endorsed as-is (no must-fix, no should-consider): 1. **fragment_id_from_path divergence**: bash implementation is dead+buggy code with zero production consumers (Surveyor unfiltered sweep + indirect-dispatch hunt confirmed); Go Read's id round-trips real filenames + structural round-trip verified total. Contract-implemented+unit-tested, NOT harness-graded ("don't grade a dead bug"). 2. **AggregateBump additive**: package-level function beside the interface (=determine_bump_from_fragments). No interface amendment needed; KEEP per Surveyor. - Harness byte-diffs the real `fragments.sh` on the 4 CONSUMED surfaces (kind-detection, filename-parse, body-density, kind-slug enum) **Cross-references**: - Depends on: #505 (interfaces), #504 (C4 grammar), #503 (harness vehicle) - Sibling: #533 (composer — consumes Fragment types + carries the register-scrub obligation from #507 comment 89128), #534 (gates — consumes both engines) - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C4, §3.3 phase 3 row, §5 (fail-loud + trivalent-verdict discipline) **Phase 3 status**: 1/3 complete (#532 fragments). #533 composer is Engineer's sequential next post-/compact (fresh domain: composer size/L + register-scrub load-bearing obligation).

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