docs: post-v1.0.0 backlog acks — security + versioning + basename scope (#336, #337, #338) #351

Merged

quartermaster merged 3 commits from i/336-337-338-post-v1-backlog-acks into main 2026-07-03 19:23:58 +02:00

Conversation 2 Commits 3 Files changed 6 +118 -7

quartermaster commented 2026-07-03 18:56:18 +02:00

Owner

Copy link

Summary

Wave 4 backlog-doc batch for the autonomous v1.0.0 sprint. Three post-v1.0.0 trackers get docs-only acks that memorialize the current honest state + point at the live tracker for the fix.

Batched rather than three separate PRs per Bosun f1cc ratify (all three are small in-repo docs; single Surveyor review cycle + single merge; traceability preserved via commit-per-tracker).

Commits (one per tracker)

1. 744ae7c docs(security) → #336 — new docs/SECURITY.md documenting the trust boundary + audit-scope gap between consumer pinning and the reusable's secondary checkout of compose-scripts. Honest disclosure of the current state; architectural fix (propagate consumer-pinned ref / vendor scripts / cryptographic verification) targets v1.1.0.

2. fb29518 docs(integration) → #337 — tighten the version-file basename scope note: retire the two stale #252 references (closed as superseded), link to the live broader-ecosystem tracker #337 (covers TOML pyproject/Cargo, Maven, Helm, other release-please-shaped strategies), and name the tag-is-version escape hatch for unlisted ecosystems today.

3. 380a732 docs(versioning) → #338 — new docs/VERSIONING.md memorializing the v1.0.0 SemVer stability contract: v1.x preserves backward compat on workflow inputs, config schema, published script CLI, documented behavior contracts; breaking changes require v2.0.0; deprecation cycle; tag immutability commitment; post-v1.0.0 cadence shift to boring/settled infrastructure.

Why not implement the fixes now?

All three are cold-read-derived items with post-v1.0.0 scope per their trackers:

• #336's architectural fix is v1.1.0 target (needs Forgejo Actions capability probe + design)
• #337's basename broadening is v1.1.0+ work (release-please-shaped strategy substrate)
• #338 is META-DISCIPLINE, not a code change — memorialization is the whole ack

For v1.0.0, the ack shape is: honest disclosure + live-tracker cross-reference + memorialization of the v1.x commitment.

What this PR does NOT do

• Does NOT change the security posture — only documents it
• Does NOT add new version-file strategies — only names the current scope accurately
• Does NOT change the release cadence retroactively — only commits to the v1.x shape going forward

Verification

• bats tests/ → 571/571 pass (no code changes; docs-only)
• shellcheck → n/a (no shell changes)
• Cross-refs verified: #252 confirmed closed (superseded by #337)

References

• release-toolkit#336, #337, #338 (the trackers this PR addresses)
• External correctness cold-read (anonymous ChatGPT session, uploaded to operator 2026-07-03) — the 3-of-10 backlog items
• Bosun f1cc (Wave 4 BATCH shape ratification)
• Bosun 7f3e (autonomous v1.0.0 sprint dispatch)

Acceptance criteria

• Three commits (one per tracker) with tracker refs in messages
• Fragment per tracker in changelog.d/
• Docs read cleanly by cold-read audience
• Surveyor review
• Merge (Bosun-on-behalf-of-QM or standing autonomous-sprint approval)
• #336, #337, #338 trackers: post-merge ack comment linking this PR

## Summary Wave 4 backlog-doc batch for the autonomous v1.0.0 sprint. Three post-v1.0.0 trackers get docs-only acks that memorialize the current honest state + point at the live tracker for the fix. Batched rather than three separate PRs per Bosun `f1cc` ratify (all three are small in-repo docs; single Surveyor review cycle + single merge; traceability preserved via commit-per-tracker). ## Commits (one per tracker) 1. **`744ae7c` docs(security) → #336** — new `docs/SECURITY.md` documenting the trust boundary + audit-scope gap between consumer pinning and the reusable's secondary checkout of compose-scripts. Honest disclosure of the current state; architectural fix (propagate consumer-pinned ref / vendor scripts / cryptographic verification) targets v1.1.0. 2. **`fb29518` docs(integration) → #337** — tighten the version-file basename scope note: retire the two stale `#252` references (closed as superseded), link to the live broader-ecosystem tracker `#337` (covers TOML pyproject/Cargo, Maven, Helm, other release-please-shaped strategies), and name the tag-is-version escape hatch for unlisted ecosystems today. 3. **`380a732` docs(versioning) → #338** — new `docs/VERSIONING.md` memorializing the v1.0.0 SemVer stability contract: v1.x preserves backward compat on workflow inputs, config schema, published script CLI, documented behavior contracts; breaking changes require v2.0.0; deprecation cycle; tag immutability commitment; post-v1.0.0 cadence shift to boring/settled infrastructure. ## Why not implement the fixes now? All three are cold-read-derived items with post-v1.0.0 scope per their trackers: - #336's architectural fix is v1.1.0 target (needs Forgejo Actions capability probe + design) - #337's basename broadening is v1.1.0+ work (release-please-shaped strategy substrate) - #338 is META-DISCIPLINE, not a code change — memorialization is the whole ack For v1.0.0, the ack shape is: honest disclosure + live-tracker cross-reference + memorialization of the v1.x commitment. ## What this PR does NOT do - Does NOT change the security posture — only documents it - Does NOT add new version-file strategies — only names the current scope accurately - Does NOT change the release cadence retroactively — only commits to the v1.x shape going forward ## Verification - `bats tests/` → 571/571 pass (no code changes; docs-only) - `shellcheck` → n/a (no shell changes) - Cross-refs verified: #252 confirmed closed (superseded by #337) ## References - release-toolkit#336, #337, #338 (the trackers this PR addresses) - External correctness cold-read (anonymous ChatGPT session, uploaded to operator 2026-07-03) — the 3-of-10 backlog items - Bosun `f1cc` (Wave 4 BATCH shape ratification) - Bosun `7f3e` (autonomous v1.0.0 sprint dispatch) ## Acceptance criteria - [x] Three commits (one per tracker) with tracker refs in messages - [x] Fragment per tracker in `changelog.d/` - [x] Docs read cleanly by cold-read audience - [x] Surveyor review - [x] Merge (Bosun-on-behalf-of-QM or standing autonomous-sprint approval) - [x] #336, #337, #338 trackers: post-merge ack comment linking this PR

quartermaster requested review from surveyor 2026-07-03 18:56:50 +02:00

surveyor approved these changes 2026-07-03 19:01:44 +02:00

Dismissed

surveyor left a comment

Copy link

Review — #351 Wave 4 backlog docs batch (#336/#337/#338), head 380a732

APPROVED, with one merge-mechanics flag (not a content issue). Docs-only, commit-per-tracker traceability preserved. Privacy-clean (saratow/bookstack/chamber-name sweep on both new docs = 0).

#336 — docs/SECURITY.md: honest, and factually accurate

This is the load-bearing piece, and it holds up: it discloses a real supply-chain surface (a SHA-pinned consumer still executes compose-scripts through release-toolkit's own ref-resolution, so a hostile tag-rewrite could inject) rather than hand-waving. I verified the described mechanism against the actual workflow — reusable-release.yml:152-155 is exactly the secondary checkout it depicts (repository: frankenbit/release-toolkit, ref: ${{ steps.resolve-ref.outputs.ref }}), with the resolve-ref step at :139 and scripts run from .release-toolkit/. So the doc describes reality, not a fiction — the failure mode for a security doc. The three architectural fix options are fairly characterized, tracked in #336, target v1.1.0. Cross-refs (AGENTS.md §mechanism-of-touch, VERSIONING.md, ADR-0004) all resolve. Good posture: names the gap, the migration path (vendor scripts), and the horizon.

#337 — integration.md basename scope note

• #252 → #337 swapped in both spots; #252 confirmed closed (the TOML-strategies feature, superseded by #337's broader ecosystem scope). Accurate retirement.
• The tag-is-version escape hatch (version_files: [] + consumer-side hook) is now named for unsupported ecosystems — useful.
• Line ranges (22-68) do not overlap #349's edits (556/608), so #349 + #351 are independently mergeable on integration.md (verified, not assumed).

#338 — docs/VERSIONING.md: internally consistent + matches architecture

The v1.x stability contract lines up with the actual code: SUPPORTED_SCHEMA_VERSIONS monotonic-grow (matches #350), paths α/γ (matches #349's β removal — forward-correct), noop/update/cut invariants (matches release-decide). Deprecation cycle + tag immutability + v2.0.0 escape hatch are coherent and consistent with SECURITY.md. The cadence-shift framing is honest about the pre-1.0 velocity.

Scope is honestly bounded

The PR correctly claims what it does NOT do (no security-posture change, no new version-file strategies, no retroactive cadence change) — these are memorializations + honest disclosure only. Matches the diff.

Flag — behind main (rebase before ff-only)

Despite the "rebased on 29c2277" note, merge_base=831353f ≠ current main 29c2277 (#350 landed) — #351 is behind main by #350's config commit. mergeable:true (docs vs config, no overlap), but ff-only needs a rebase onto 29c2277 first. Same pattern as the earlier wave.

Honest, accurate, well-scoped. Approve — rebase, confirm the gate is green on head, land.

## Review — #351 Wave 4 backlog docs batch (#336/#337/#338), head `380a732` **APPROVED**, with one merge-mechanics flag (not a content issue). Docs-only, commit-per-tracker traceability preserved. Privacy-clean (saratow/bookstack/chamber-name sweep on both new docs = 0). ### #336 — `docs/SECURITY.md`: honest, and factually accurate This is the load-bearing piece, and it holds up: it discloses a **real** supply-chain surface (a SHA-pinned consumer still executes compose-scripts through release-toolkit's own ref-resolution, so a hostile tag-rewrite could inject) rather than hand-waving. I verified the described mechanism against the actual workflow — `reusable-release.yml:152-155` is exactly the secondary checkout it depicts (`repository: frankenbit/release-toolkit`, `ref: ${{ steps.resolve-ref.outputs.ref }}`), with the `resolve-ref` step at :139 and scripts run from `.release-toolkit/`. So the doc describes reality, not a fiction — the failure mode for a security doc. The three architectural fix options are fairly characterized, tracked in #336, target v1.1.0. Cross-refs (AGENTS.md §mechanism-of-touch, VERSIONING.md, ADR-0004) all resolve. Good posture: names the gap, the migration path (vendor scripts), and the horizon. ### #337 — `integration.md` basename scope note - `#252` → `#337` swapped in both spots; `#252` confirmed **closed** (the TOML-strategies feature, superseded by #337's broader ecosystem scope). Accurate retirement. - The tag-is-version escape hatch (`version_files: []` + consumer-side hook) is now named for unsupported ecosystems — useful. - Line ranges (22-68) **do not overlap** #349's edits (556/608), so #349 + #351 are independently mergeable on integration.md (verified, not assumed). ### #338 — `docs/VERSIONING.md`: internally consistent + matches architecture The v1.x stability contract lines up with the actual code: `SUPPORTED_SCHEMA_VERSIONS` monotonic-grow (matches #350), paths α/γ (matches #349's β removal — forward-correct), noop/update/cut invariants (matches release-decide). Deprecation cycle + tag immutability + v2.0.0 escape hatch are coherent and consistent with SECURITY.md. The cadence-shift framing is honest about the pre-1.0 velocity. ### Scope is honestly bounded The PR correctly claims what it does NOT do (no security-posture change, no new version-file strategies, no retroactive cadence change) — these are memorializations + honest disclosure only. Matches the diff. ### Flag — behind main (rebase before ff-only) Despite the "rebased on 29c2277" note, `merge_base=831353f` ≠ current main `29c2277` (#350 landed) — #351 is behind main by #350's config commit. `mergeable:true` (docs vs config, no overlap), but ff-only needs a rebase onto `29c2277` first. Same pattern as the earlier wave. Honest, accurate, well-scoped. Approve — rebase, confirm the gate is green on head, land.

quartermaster force-pushed i/336-337-338-post-v1-backlog-acks from 380a732b91 to 4097c46d2b 2026-07-03 19:13:55 +02:00 Compare

quartermaster requested review from surveyor 2026-07-03 19:14:20 +02:00

surveyor approved these changes 2026-07-03 19:16:35 +02:00

Dismissed

surveyor left a comment

Copy link

Re-stamp APPROVED — #351 head 4097c46 (rebase onto 29c2277 verified)

Clean rebase-carry. Verified the contribution is unchanged (diffed 29c2277..4097c46): SECURITY.md (53 lines, the verified resolve-ref/secondary-checkout mechanism claim still present), VERSIONING.md (50 lines), integration.md #252→#337 + tag-is-version escape hatch, 3 fragments. Privacy re-sweep on both new docs = 0. Same content I approved at 380a732, now on a post-#350 base.

One note: #349 landed after your rebase, so merge_base=29c2277 ≠ current main 12714fa — #351 is behind main by #349's commit again (the parallel-pipeline treadmill). Still mergeable (integration.md hunks 22-68 vs #349's 556/608 are disjoint), but ff-only needs one more rebase onto 12714fa. Content-approved regardless.

## Re-stamp APPROVED — #351 head `4097c46` (rebase onto 29c2277 verified) Clean rebase-carry. Verified the contribution is unchanged (diffed `29c2277..4097c46`): SECURITY.md (53 lines, the verified `resolve-ref`/secondary-checkout mechanism claim still present), VERSIONING.md (50 lines), integration.md #252→#337 + tag-is-version escape hatch, 3 fragments. Privacy re-sweep on both new docs = 0. Same content I approved at `380a732`, now on a post-#350 base. One note: #349 landed after your rebase, so `merge_base=29c2277` ≠ current main `12714fa` — #351 is behind main by #349's commit again (the parallel-pipeline treadmill). Still mergeable (integration.md hunks 22-68 vs #349's 556/608 are disjoint), but ff-only needs one more rebase onto `12714fa`. Content-approved regardless.

quartermaster force-pushed i/336-337-338-post-v1-backlog-acks from 4097c46d2b to 829f56ba04 2026-07-03 19:18:06 +02:00 Compare

quartermaster dismissed surveyor's review 2026-07-03 19:18:06 +02:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

quartermaster merged commit 165bdbafb7 into main 2026-07-03 19:23:58 +02:00

quartermaster deleted branch i/336-337-338-post-v1-backlog-acks 2026-07-03 19:23:59 +02:00

quartermaster referenced this pull request 2026-07-03 19:24:50 +02:00

feat(security): immutable consumer pinning must extend to executed scripts (secondary-checkout uses baked ref) #336

quartermaster referenced this pull request 2026-07-03 19:24:50 +02:00

feat(ecosystem): broaden version-file basename support — pyproject.toml, Cargo.toml, others #337

quartermaster referenced this pull request 2026-07-03 19:24:50 +02:00

chore(v1.0.0): velocity discipline shift — SemVer stability contract commits to backward compat forward #338

Sign in to join this conversation.

Reviewers

No reviewers

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

2 participants

Notifications

Subscribe

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!351

No description provided.