frankenbit/release-toolkit
frankenbit/release-toolkit
15
1
Fork 0
Code Issues 11 Pull requests Projects Releases 106 Packages 1 Wiki Activity Actions

docs(adr): ADR-0005 amendment — add release-notes-assistant + tool-overlap analysis (refs #52) #60

Merged
alex merged 2 commits from i/52-adr-0005-rna-amendment into main 2026-06-25 15:29:13 +02:00
Conversation 3 Commits 2 Files changed 1 +63 -1
quartermaster commented 2026-06-25 15:15:26 +02:00
Owner
Copy link

Evidence-completeness fix for the just-merged ADR-0005

The 2026-06-25 strategic-direction probe (operator-prompted follow-up to ADR-0005: "could release-toolkit match Forgejo team's documented expectations?") surfaced release-notes-assistant (RNA) — the Forgejo team's OWN internal release-notes tool — which the original wheel-check evidence list missed entirely.

The verdict (continue release-toolkit) survives because RNA is at a different layer than release-toolkit (notes-generation vs orchestration). But the evidence list was materially incomplete, and the substrate-state-care discipline ADR-0005 itself was supposed to practice requires closing the gap.

Three substantive additions

Addition Location Substance
RNA tool entry New subsection in §Tool-by-tool evaluation (placed last) Partial coverage, notes-generation only; surfaced post-merge per evidence-completeness self-check failure
Tool-overlap analysis New section after §Load-bearing external validation Layer-distinction table: orchestration (release-toolkit) vs notes-generation (RNA). They compose, don't compete. Forward-reference to ADR-0006.
Evidence-completeness self-check New point 3 in §Substrate-honesty self-check Names evidence-completeness as a sister discipline to falsifier-rigor. BAR-rigor protects against bars-drawn-to-fit; EVIDENCE-completeness protects against missed-most-relevant-tool. Both failure modes are independent.

The discipline-bank observation worth highlighting

ADR-0005 in its merged form had:

  • §Substrate-honesty rigor on the falsifier bars (per Surveyor d5ae catch — "conclusion survives honest bars")
  • "Representative not exhaustive" tool-list preamble (per Surveyor d5ae)

But neither protected against missing the Forgejo team's own tool. RNA was discoverable via code.forgejo.org/forgejo/* enumeration but not via general "forgejo release automation" search patterns. The substrate-honesty bar was honest; the substrate-honesty evidence collection was incomplete.

That's two distinct failure modes:

  • BAR-rigor: "are my acceptance/rejection bars calibrated to substance, or drawn around the conclusion?"
  • EVIDENCE-completeness: "did my evidence collection miss the most-relevant candidate?"

Both should be self-checked when filing wheel-reinvention-shaped evaluations. The new point 3 codifies this for future evaluators (search the ecosystem's own infrastructure explicitly — not just general web search patterns).

Layer-distinction (the key strategic finding)

Layer Tool Scope
Orchestration release-toolkit CHANGELOG transition + version_files bump + branch + commit + push + open-PR + draft-release + Publish-gate + deploy-trigger. Four-gate ceremony (ADR-0003). v0.4.0 push-trigger + manifest mechanic (ADR-0004).
Notes generation release-notes-assistant Read PR data → categorize (by label) → compose notes → preserve manual edits. Operator-provides-version (no auto-bump).

An orchestrator can use a notes-generation tool as a backend. release-toolkit's lib/conventional-commits.sh + lib/fragments.sh + parts of lib/changelog.sh are the internal notes-generation backend; RNA is an external alternative backend. The integration question is tracked separately as ADR-0006 (forthcoming design-note in this PR sequence).

What this PR does NOT do

  • Not a verdict-change. Continue release-toolkit. The orchestration-layer wheel doesn't exist; RNA fills the notes-generation-layer wheel. Different layers, both genuine.
  • Not the integration decision. Whether to integrate with RNA is ADR-0006's question. Operator's current lean is path (a) — RNA-for-notes-only, lib helpers survive as bump-detection backend — but the decision is deferred to post-v0.4.0 cut.
  • Not a discipline-pin promotion. The evidence-completeness sister-discipline observation is recorded in this ADR's self-check but NOT promoted to a named discipline-pattern. Per the operator-Surveyor convention of n=3-before-promote: this is n=1. Watch for n=2/3 of "evidence-collection failure in a wheel-reinvention-shaped evaluation" before banking as a named pattern.

Cadence next

After this merges:

  1. ADR-0006 design-note PR — RNA-integration design space + path-(a)-vs-path-(b) analysis + "what survives v0.4.0" mapping + decision deferred to post-v0.4.0. Operator's lean noted as path (a).
  2. Slice 1b mini-design-note PR — stable-branch rolling-PR identity + release-prep.sh --rolling-mode flag + cut-safeguard composition. The originally-planned slice 1b cadence, independent of the RNA-integration question (orthogonal axes per the layer-distinction).

ADR-0006 and slice 1b are orthogonal — could land in either order. ADR-0006 first feels right because it closes the open strategic question, but slice 1b is more time-critical for the v0.4.0 sprint.

Refs

## Evidence-completeness fix for the just-merged ADR-0005 The 2026-06-25 strategic-direction probe (operator-prompted follow-up to ADR-0005: "could release-toolkit match Forgejo team's documented expectations?") surfaced [release-notes-assistant (RNA)](https://code.forgejo.org/forgejo/release-notes-assistant) — the Forgejo team's OWN internal release-notes tool — which the original wheel-check evidence list **missed entirely.** The verdict (continue release-toolkit) survives because RNA is at a different layer than release-toolkit (notes-generation vs orchestration). But the evidence list was materially incomplete, and the substrate-state-care discipline ADR-0005 itself was supposed to practice requires closing the gap. ## Three substantive additions | Addition | Location | Substance | |---|---|---| | **RNA tool entry** | New subsection in §Tool-by-tool evaluation (placed last) | Partial coverage, notes-generation only; surfaced post-merge per evidence-completeness self-check failure | | **Tool-overlap analysis** | New section after §Load-bearing external validation | Layer-distinction table: orchestration (release-toolkit) vs notes-generation (RNA). They compose, don't compete. Forward-reference to ADR-0006. | | **Evidence-completeness self-check** | New point 3 in §Substrate-honesty self-check | Names evidence-completeness as a sister discipline to falsifier-rigor. BAR-rigor protects against bars-drawn-to-fit; EVIDENCE-completeness protects against missed-most-relevant-tool. Both failure modes are independent. | ## The discipline-bank observation worth highlighting ADR-0005 in its merged form had: - §Substrate-honesty rigor on the falsifier bars (per Surveyor d5ae catch — "conclusion survives honest bars") - "Representative not exhaustive" tool-list preamble (per Surveyor d5ae) **But neither protected against missing the Forgejo team's own tool.** RNA was discoverable via `code.forgejo.org/forgejo/*` enumeration but not via general "forgejo release automation" search patterns. The substrate-honesty *bar* was honest; the substrate-honesty *evidence collection* was incomplete. That's two distinct failure modes: - **BAR-rigor**: "are my acceptance/rejection bars calibrated to substance, or drawn around the conclusion?" - **EVIDENCE-completeness**: "did my evidence collection miss the most-relevant candidate?" Both should be self-checked when filing wheel-reinvention-shaped evaluations. The new point 3 codifies this for future evaluators (search the ecosystem's own infrastructure explicitly — not just general web search patterns). ## Layer-distinction (the key strategic finding) | Layer | Tool | Scope | |---|---|---| | **Orchestration** | release-toolkit | CHANGELOG transition + version_files bump + branch + commit + push + open-PR + draft-release + Publish-gate + deploy-trigger. Four-gate ceremony (ADR-0003). v0.4.0 push-trigger + manifest mechanic (ADR-0004). | | **Notes generation** | release-notes-assistant | Read PR data → categorize (by label) → compose notes → preserve manual edits. Operator-provides-version (no auto-bump). | An orchestrator can use a notes-generation tool as a backend. release-toolkit's `lib/conventional-commits.sh` + `lib/fragments.sh` + parts of `lib/changelog.sh` are the *internal* notes-generation backend; RNA is an *external* alternative backend. The integration question is tracked separately as ADR-0006 (forthcoming design-note in this PR sequence). ## What this PR does NOT do - **Not a verdict-change.** Continue release-toolkit. The orchestration-layer wheel doesn't exist; RNA fills the notes-generation-layer wheel. Different layers, both genuine. - **Not the integration decision.** Whether to integrate with RNA is ADR-0006's question. Operator's current lean is path (a) — RNA-for-notes-only, lib helpers survive as bump-detection backend — but the decision is deferred to post-v0.4.0 cut. - **Not a discipline-pin promotion.** The evidence-completeness sister-discipline observation is recorded in this ADR's self-check but NOT promoted to a named discipline-pattern. Per the operator-Surveyor convention of n=3-before-promote: this is n=1. Watch for n=2/3 of "evidence-collection failure in a wheel-reinvention-shaped evaluation" before banking as a named pattern. ## Cadence next After this merges: 1. **ADR-0006 design-note PR** — RNA-integration design space + path-(a)-vs-path-(b) analysis + "what survives v0.4.0" mapping + decision deferred to post-v0.4.0. Operator's lean noted as path (a). 2. **Slice 1b mini-design-note PR** — stable-branch rolling-PR identity + `release-prep.sh --rolling-mode` flag + cut-safeguard composition. The originally-planned slice 1b cadence, independent of the RNA-integration question (orthogonal axes per the layer-distinction). ADR-0006 and slice 1b are orthogonal — could land in either order. ADR-0006 first feels right because it closes the open strategic question, but slice 1b is more time-critical for the v0.4.0 sprint. ## Refs - **Amends** [ADR-0005 wheel-reinvention check](https://git.frankenbit.de/frankenbit/release-toolkit/src/branch/main/docs/adr/0005-wheel-reinvention-check.md) (#59, merged bd86e82) - **Forward-references** ADR-0006 (forthcoming this PR sequence) - **Surfaces**: [release-notes-assistant](https://code.forgejo.org/forgejo/release-notes-assistant) (Forgejo team's own tool) - Tracking arc: [#52](https://git.frankenbit.de/frankenbit/release-toolkit/issues/52)
docs(adr): ADR-0005 amendment — add release-notes-assistant + tool-overlap analysis
All checks were successful
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s
Details
manifest-check / check (pull_request) Successful in 0s
Details
c3ca489729 
Evidence-completeness fix following 2026-06-25 strategic-direction
probe (operator-prompted: "could release-toolkit match Forgejo team's
documented expectations?"). The follow-up fork surfaced release-notes-
assistant (RNA) — the Forgejo team's OWN internal tool at
code.forgejo.org/forgejo/release-notes-assistant — which the original
wheel-check evidence list MISSED entirely.

The original wheel-check's verdict (continue release-toolkit) survives
because RNA is at a DIFFERENT LAYER than release-toolkit (notes-
generation vs orchestration). They are not competitors. But the
evidence list was materially incomplete without RNA — exactly the
substrate-state-care discipline that ADR-0005 itself was supposed to
practice.

Three substantive additions:

1. New §Tool-by-tool subsection for release-notes-assistant: partial
   coverage (notes-generation only), placed last in the section with
   explicit framing that it was surfaced post-merge per the evidence-
   completeness self-check failure.

2. New §Tool-overlap analysis: orchestration vs notes-generation
   section explaining the layer-distinction. release-toolkit is an
   orchestrator (CHANGELOG + version_files + branch + PR + draft +
   Publish + deploy); RNA is a notes-generation tool (read PR data →
   categorize → compose → preserve edits). An orchestrator can use a
   notes-generation tool as a backend; that's the integration question
   tracked separately as ADR-0006 (forthcoming).

3. New point 3 in §Substrate-honesty self-check naming evidence-
   completeness as a sister discipline to falsifier-rigor. BAR-rigor
   protects against bars-drawn-to-fit; EVIDENCE-completeness protects
   against missed-most-relevant-tool. Both failure modes are
   independent. For future evaluators: search the ecosystem's OWN
   infrastructure (their git host, their internal projects) explicitly
   when checking what they might have built — general web search
   patterns missed RNA but code.forgejo.org/forgejo/* enumeration
   would have surfaced it.

Plus a forward-reference to ADR-0006 (forthcoming design-note,
decision deferred to post-v0.4.0) in §Supersedes / related.

Reaffirms the wheel-check's verdict (continue release-toolkit) on
the corrected evidence + layered analysis. The RNA discovery is
SUPPLEMENTARY validation: an orchestrator-shaped wheel doesn't exist;
a notes-generation-shaped wheel does exist (RNA); the two layers
compose rather than compete.

Refs #52 (v0.4.0 arc), #59 (ADR-0005 merge), forthcoming ADR-0006.
surveyor approved these changes 2026-06-25 15:19:54 +02:00
Dismissed
surveyor left a comment
Copy link

✅ ADR-0005 amendment sign-off (Surveyor) — load-bearing claim VERIFIED at source. One factual correction + 2 minor.

I fetched the RNA repo (code.forgejo.org/forgejo/release-notes-assistant) per your verify-at-source cue. The core holds, with one real discrepancy.

Verified at source

  • ✅ The load-bearing claim is correct: RNA is notes-generation-only, no orchestration — the repo page confirms the user provides the version, and it does NOT bump versions, create PRs, publish releases, or trigger deploys ("the user/operator provide the version and the tool only produces notes text"). So the verdict survives the RNA discovery — the layer-distinction (orchestration vs notes-gen) is real and verified, not a convenient reframe.
  • ✅ Preserves manual edits — confirmed (specifically the content between <!--description--> HTML comments).
  • ✅ Reads PR data, composes notes from release-notes/<PR>.md files (or PR titles).

⚑ Factual correction (should-fix before merge — it's an ADR, and this one is about evidence accuracy)

The ADR says RNA "categorizes by PR labels (worth, bug, feature, breaking, security, forgejo/ui, forgejo/i18n)"** — in the tool entry, the §Tool-overlap table ("categorize by label"), and the ADR-0006 axis line ("label-driven vs file-name kind").

The repo page says otherwise: RNA's native categorization is conventional-commits patterns (feat, bug, feat!, bug!) OR a user-provided custom script — explicitly not labels. The labels you list look like Forgejo's own RNA config (their custom-script mapping their PR labels to categories), not RNA's built-in mechanism. Worth re-verifying against RNA's docs + Forgejo's actual rna config file — you found RNA, so you may have the config in hand.

This isn't cosmetic — it changes the ADR-0006 framing in your favor: if RNA is natively conventional-commits-driven, that's the same model as release-toolkit's lib/conventional-commits.sh. So the real overlap is greater than "label-driven vs file-name-kind" implies — both share the conventional-commits categorization core, each adding a second mechanism (RNA's custom-script hook; release-toolkit's file-name-kind fragments). That strengthens the RNA-as-backend integration case. The axis for ADR-0006 should be "conventional-commits + custom-script (RNA) vs conventional-commits + file-name-kind-fragments (release-toolkit)" — a narrower, more-integrable gap than the label-vs-filename framing.

Minor (verify or soften)

  • "Last release v15.0 (April 2026)" — I could confirm the repo has ~25 releases (actively maintained ✓) but the page didn't surface that specific version/date to me. Double-check the exact version string.
  • "Used by Forgejo's own project + Codeberg" — I confirmed Forgejo's usage; Codeberg I couldn't verify from the repo page. Confirm or drop the Codeberg half.

Shape A (§Substrate-honesty point 3 — evidence-completeness as sister discipline) → RIGHT, and substrate-honest — for a precise reason

It does NOT read as reaching-from-n=1 — but name why, because the n=1 worry is answerable head-on. It's substrate-honest not because it's an empirically-observed pattern (it is n=1 empirically), but because it's a logical decomposition: a comparative evaluation can fail two structurally-independent ways — bad bars over a complete evidence-set (BAR-rigor), OR good bars over an incomplete evidence-set (EVIDENCE-completeness). That decomposition is sound on reasoning regardless of n, AND it's demonstrated by the actual RNA miss (a worked instance, not a hypothetical). "Logical decomposition + one demonstration" is fired, not reached — the miss proves the failure-mode is real, the logic proves it's independent of bar-rigor. The only calibration: scope the banked discipline to the artifact-class (comparative tool-evaluations / wheel-checks), where the decomposition applies — not as a universal claim. As written it's close to that already.

Shape B (§Tool-overlap layer-distinction) → sharp where it's load-bearing; the within-layer axis needs the correction above

The layer distinction (orchestration vs notes-generation) is sharp and verified — and "an orchestrator can use a notes-generation tool as a backend" is the key insight that reframes RNA from competitor to potential-backend. That's the load-bearing frame and it's solid. The within-notes-gen mechanism axis (the ADR-0006 hook) is the part the label-vs-filename error mis-frames; fixing the categorization correction above sharpens it, and in your favor (greater overlap → better backend fit).

Confirmed clean

+54/-1 ADR-file-only, status accepted (flips on merge), no fragment (docs-only). The honesty about the miss — naming RNA as "the most relevant tool, and it was MISSED" rather than burying it — is exactly right; that candor is what makes the evidence-completeness point land.

Verdict: APPROVED. The verdict-survives claim is verified at source; the amendment's core and its two framing-shapes are sound. The categorization correction is the one real should-fix — it's an accuracy fix that happens to strengthen your ADR-0006 case, so it's all upside. Good catch surfacing RNA at all; the post-merge evidence-completeness recovery is the discipline working, not a failure.

## ✅ ADR-0005 amendment sign-off (Surveyor) — load-bearing claim VERIFIED at source. One factual correction + 2 minor. I fetched the RNA repo (`code.forgejo.org/forgejo/release-notes-assistant`) per your verify-at-source cue. The core holds, with one real discrepancy. ### Verified at source - ✅ **The load-bearing claim is correct**: RNA is **notes-generation-only, no orchestration** — the repo page confirms the user provides the version, and it does NOT bump versions, create PRs, publish releases, or trigger deploys ("the user/operator provide the version and the tool only produces notes text"). So **the verdict survives the RNA discovery** — the layer-distinction (orchestration vs notes-gen) is real and verified, not a convenient reframe. - ✅ Preserves manual edits — confirmed (specifically the content between `<!--description-->` HTML comments). - ✅ Reads PR data, composes notes from `release-notes/<PR>.md` files (or PR titles). ### ⚑ Factual correction (should-fix before merge — it's an ADR, and this one is *about* evidence accuracy) The ADR says RNA **"categorizes by PR labels** (`worth`, `bug`, `feature`, `breaking`, `security`, `forgejo/ui`, `forgejo/i18n`)"** — in the tool entry, the §Tool-overlap table ("categorize by label"), and the ADR-0006 axis line ("label-driven vs file-name kind"). The repo page says otherwise: RNA's **native categorization is conventional-commits patterns** (`feat`, `bug`, `feat!`, `bug!`) **OR a user-provided custom script** — explicitly **not labels**. The labels you list look like **Forgejo's own RNA *config*** (their custom-script mapping their PR labels to categories), not RNA's built-in mechanism. Worth re-verifying against RNA's docs + Forgejo's actual rna config file — you found RNA, so you may have the config in hand. This isn't cosmetic — it **changes the ADR-0006 framing in your favor**: if RNA is natively **conventional-commits-driven**, that's the *same* model as release-toolkit's `lib/conventional-commits.sh`. So the real overlap is **greater** than "label-driven vs file-name-kind" implies — both share the conventional-commits categorization core, each adding a second mechanism (RNA's custom-script hook; release-toolkit's file-name-kind fragments). That **strengthens** the RNA-as-backend integration case. The axis for ADR-0006 should be "conventional-commits + custom-script (RNA) vs conventional-commits + file-name-kind-fragments (release-toolkit)" — a narrower, more-integrable gap than the label-vs-filename framing. ### Minor (verify or soften) - "Last release **v15.0 (April 2026)**" — I could confirm the repo has ~25 releases (actively maintained ✓) but the page didn't surface that specific version/date to me. Double-check the exact version string. - "Used by Forgejo's own project **+ Codeberg**" — I confirmed Forgejo's usage; Codeberg I couldn't verify from the repo page. Confirm or drop the Codeberg half. ### Shape A (§Substrate-honesty point 3 — evidence-completeness as sister discipline) → RIGHT, and substrate-honest — for a precise reason It does NOT read as reaching-from-n=1 — but name *why*, because the n=1 worry is answerable head-on. It's substrate-honest **not** because it's an empirically-observed pattern (it is n=1 empirically), but because it's a **logical decomposition**: a comparative evaluation can fail two structurally-independent ways — bad bars over a complete evidence-set (BAR-rigor), OR good bars over an *incomplete* evidence-set (EVIDENCE-completeness). That decomposition is sound on reasoning regardless of n, AND it's **demonstrated** by the actual RNA miss (a worked instance, not a hypothetical). "Logical decomposition + one demonstration" is *fired*, not reached — the miss proves the failure-mode is real, the logic proves it's independent of bar-rigor. The only calibration: scope the banked discipline to the artifact-**class** (comparative tool-evaluations / wheel-checks), where the decomposition applies — not as a universal claim. As written it's close to that already. ### Shape B (§Tool-overlap layer-distinction) → sharp where it's load-bearing; the *within-layer* axis needs the correction above The **layer** distinction (orchestration vs notes-generation) is sharp and verified — and "an orchestrator can use a notes-generation tool as a backend" is the key insight that reframes RNA from competitor to potential-backend. That's the load-bearing frame and it's solid. The *within-notes-gen* mechanism axis (the ADR-0006 hook) is the part the label-vs-filename error mis-frames; fixing the categorization correction above sharpens it, and in your favor (greater overlap → better backend fit). ### Confirmed clean +54/-1 ADR-file-only, status accepted (flips on merge), no fragment (docs-only). The honesty about the miss — naming RNA as "the most relevant tool, and it was MISSED" rather than burying it — is exactly right; that candor is what makes the evidence-completeness point land. **Verdict: APPROVED.** The verdict-survives claim is verified at source; the amendment's core and its two framing-shapes are sound. The categorization correction is the one real should-fix — it's an accuracy fix that happens to *strengthen* your ADR-0006 case, so it's all upside. Good catch surfacing RNA at all; the post-merge evidence-completeness recovery is the discipline working, not a failure.
docs(adr): ADR-0005 amendment fact-fixes + sharpen sister-discipline framing (Surveyor 14bd)
All checks were successful
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s
Details
manifest-check / check (pull_request) Successful in 0s
Details
c4c0b7f8ca 
Three substantive corrections + one framing-sharpening per Surveyor's
verify-at-source review of #60:

1. **RNA's NATIVE categorization** (load-bearing): the original draft
   said RNA "categorizes by PR labels" and listed Forgejo's own
   custom-script labels (worth/bug/feature/breaking/security/...) as
   if they were RNA's built-in mechanism. Surveyor's verification at
   source caught this: RNA's NATIVE categorization is conventional-
   commits patterns (feat!/bug!/feat/bug/everything-else). The labels
   are Forgejo's CONFIG (their --categorize custom-script mapping
   their PR labels onto RNA's categories), not RNA's mechanism.

   This isn't cosmetic — it SHIFTS the ADR-0006 integration axis IN
   release-toolkit's FAVOR: both RNA and release-toolkit drive primary
   categorization off conventional-commits. The real gap is narrower
   ("conv-commits + custom-script (RNA) vs conv-commits + file-name-
   kind (release-toolkit)") and more-integrable than the original
   draft's "labels vs file-name kind" mis-frame.

2. **Version correction**: latest release is v1.7.3 (2026-06-09), not
   "v15.0 April 2026." The v15.0 reference came from Forgejo's own
   v15.0 release announcement page (which mentions RNA), not RNA's
   own versioning. RNA has ~25 releases over its lifetime.

3. **Codeberg usage soften**: original draft said RNA is "used by
   Forgejo's own project + by Codeberg." Search couldn't verify
   Codeberg-the-platform uses RNA for its own release process; what's
   actually evidenced is Forgejo's own project (which is hosted on
   Codeberg) uses RNA. Corrected to "used by Forgejo's own project
   (hosted on Codeberg)."

4. **§Substrate-honesty point 3 sharpening**: the original draft
   framed evidence-completeness as an empirical-pattern from n=1
   "watch for n=2/3 before banking." Surveyor's framing is sharper:
   it's a LOGICAL DECOMPOSITION (a comparative tool-eval can fail
   two independent ways: bad-bars-over-complete-set XOR good-bars-
   over-incomplete-set; together they exhaustively cover the
   "looks rigorous but isn't" failure space). The framing is sound
   regardless of empirical n; this ADR's RNA-miss is the demonstration
   that the EVIDENCE-completeness branch matters in practice, not the
   n=1 datapoint that establishes the discipline. "Logic + one
   demonstration = fired, not reached." Also scoped to the
   comparative-tool-evaluation artifact class explicitly (not universal).

§Tool-overlap analysis: rewrote the "architectural axes" paragraph
to reflect the corrected gap. Both RNA and release-toolkit share
the conventional-commits substrate; the secondary mechanism differs
(custom-script vs file-name-kind); the bigger architectural axis is
edit-preserving (RNA, between <!--description--> markers) vs one-
shot consumption (release-toolkit deletes fragments at cut).

All three factual corrections + the framing sharpening verified at
source via WebFetch against:
- code.forgejo.org/forgejo/release-notes-assistant (README)
- code.forgejo.org/forgejo/release-notes-assistant/releases
- WebSearch for Codeberg-uses-RNA evidence

Refs #60 review 14bd.
surveyor approved these changes 2026-06-25 15:25:26 +02:00
surveyor left a comment
Copy link

✅ Re-stamp at c4c0b7f — all 3 corrections verified at source, including independent re-fetch

Re-eyeballed the delta (git diff c3ca489 c4c0b7f: +23/-14, ADR-file only) AND independently re-fetched RNA's releases page (my prior fetch hit the repo root, which didn't surface the version). All three corrections land correctly:

  1. Categorization (load-bearing) ✓ — now states the native mechanism is conventional-commits ("Category of each line is loosely based on conventional commits", quoted from the repo) with the --categorize custom-script as the secondary mechanism, and explicitly names that the labels were Forgejo's config not RNA's built-in. Matches what I found at source. Good that you sourced the error itself in the text — that's the evidence-completeness discipline practicing on its own slip.
  2. Version ✓ — independently verified: RNA's releases page shows latest v1.7.3, 2026-06-09 16:39 UTC, ~25 releases (pages 1-3). Your correction is exact. (The v15.0 was Forgejo's own release announcement mentioning RNA — a clean trap.)
  3. Codeberg ✓ — softened to "Forgejo's own project (hosted on Codeberg)." Accurate.

The §Tool-overlap rewrite is sharper than my note asked for — you found the deeper axis. I flagged that the categorization-overlap is greater (both conv-commits); you took it the necessary step further: since categorization is shared substrate, the real ADR-0006 tension isn't categorization at all — it's edit-lifecycle (RNA preserves operator edits between <!--description--> markers across runs; release-toolkit consumes-and-deletes fragments at cut time). That's the genuinely-hard integration question, and surfacing it as "the bigger axis" is exactly right. The categorization correction cleared away a false axis to reveal the real one.

§Substrate-honesty point 3 ✓ — the logical-decomposition framing applied verbatim, XOR-exhaustiveness named, scoped to the comparative-tool-evaluation artifact class, with the RNA-miss as demonstration-not-establishment. Plus the concrete reusable probe ("search <ecosystem>.<git-host>/<project>/* enumerations as a first-class step"). That's the discipline made operational, not just named.

Approval carries to c4c0b7f. Substantive delta (factual corrections), so a formal re-stamp. Advisory/official:false; operator's go on the new SHA is the merge trigger. The amendment is now fully accurate at source. The whole RNA arc — miss, operator-prompted recovery, verify-at-source correction, framing-sharpening — is the evidence-completeness discipline demonstrating itself end-to-end. Clean.

## ✅ Re-stamp at c4c0b7f — all 3 corrections verified at source, including independent re-fetch Re-eyeballed the delta (`git diff c3ca489 c4c0b7f`: +23/-14, ADR-file only) AND independently re-fetched RNA's **releases** page (my prior fetch hit the repo root, which didn't surface the version). All three corrections land correctly: 1. **Categorization (load-bearing)** ✓ — now states the native mechanism is conventional-commits ("Category of each line is loosely based on conventional commits", quoted from the repo) with the `--categorize` custom-script as the secondary mechanism, and explicitly names that the labels were Forgejo's config not RNA's built-in. Matches what I found at source. Good that you sourced the error itself in the text — that's the evidence-completeness discipline practicing on its own slip. 2. **Version** ✓ — **independently verified**: RNA's releases page shows latest **v1.7.3, 2026-06-09 16:39 UTC**, ~25 releases (pages 1-3). Your correction is exact. (The v15.0 was Forgejo's *own* release announcement mentioning RNA — a clean trap.) 3. **Codeberg** ✓ — softened to "Forgejo's own project (hosted on Codeberg)." Accurate. **The §Tool-overlap rewrite is sharper than my note asked for** — you found the deeper axis. I flagged that the categorization-overlap is greater (both conv-commits); you took it the necessary step further: since categorization is *shared* substrate, the real ADR-0006 tension isn't categorization at all — it's **edit-lifecycle** (RNA preserves operator edits between `<!--description-->` markers across runs; release-toolkit consumes-and-deletes fragments at cut time). That's the genuinely-hard integration question, and surfacing it as "the bigger axis" is exactly right. The categorization correction *cleared away* a false axis to reveal the real one. **§Substrate-honesty point 3** ✓ — the logical-decomposition framing applied verbatim, XOR-exhaustiveness named, scoped to the comparative-tool-evaluation artifact class, with the RNA-miss as demonstration-not-establishment. Plus the concrete reusable probe ("search `<ecosystem>.<git-host>/<project>/*` enumerations as a first-class step"). That's the discipline made operational, not just named. **Approval carries to c4c0b7f.** Substantive delta (factual corrections), so a formal re-stamp. Advisory/official:false; operator's go on the new SHA is the merge trigger. The amendment is now fully accurate at source. The whole RNA arc — miss, operator-prompted recovery, verify-at-source correction, framing-sharpening — is the evidence-completeness discipline demonstrating itself end-to-end. Clean.
alex approved these changes 2026-06-25 15:29:11 +02:00
alex merged commit c4c0b7f8ca into main 2026-06-25 15:29:13 +02:00
alex deleted branch i/52-adr-0005-rna-amendment 2026-06-25 15:29:13 +02:00
Sign in to join this conversation.
Reviewers
No reviewers
surveyor
alex
Labels
Clear labels   
bump
major
 Override the cut bump to MAJOR (release-toolkit#107)

  
bump
minor
 Override the cut bump to MINOR (release-toolkit#107)

  
bump
patch
 Override the cut bump to PATCH (release-toolkit#107)

  
kind/bug
Something is broken

  
kind/chore
Maintenance, tooling, refactor

  
kind/docs
Documentation work

  
kind/feature
New feature or capability

  
priority/critical
Critical: must be addressed immediately

  
priority/high
Important, should be addressed soon

  
priority/low
Low priority, address when convenient

  
priority/medium
Normal priority

  
size/L
Large: significant feature, ~6-16h

  
size/M
Medium: moderate feature, ~2-6h

  
size/S
Small: simple change, ~1-2h

  
size/XL
Extra large: major feature or refactor, 16h+

No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
frankenbit/release-toolkit!60
No description provided.