pre-v1.0 readiness sweep: drive consumer adoption + surface audits #106

New issue

Closed

opened 2026-06-26 14:15:58 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-26 14:15:58 +02:00

Owner

Umbrella tracker for the substrate-stability → v1.0 promotion path

Per operator decision 2026-06-26: defer v1.0 promotion (the v0.7.0 minor cut surfaced the option) until consumer adoption surfaces rough edges + the toolkit substrate has been formally audited for "is this a stable contract?"

The §10 arc-convergence (AGENTS.md §10) provided the EMPIRICAL signal for substrate stability. v1.0 is the FORMAL commitment — SemVer 1.0 says "backwards-compat across minor/patch from here; breaking changes require major." This umbrella tracker drives the work between empirical-convergence (achieved) and formal-commitment (pending).

Two parallel work-streams

(A) Adoption-driven empirical signal

Adopt the toolkit on real consumers to surface what the §10 convergence couldn't predict — actual usage patterns, integration friction, real-world failure modes outside the toolkit's own self-bootstrap.

#420 Cellblock adoption (cellblock#162) — in_progress
#421 tmux-tell migration (tmux-tell#617) — pending, BLOCKED on gap-closure
Future consumers as they emerge

Each adoption is an empirical probe. Catches surfaced during adoption feed back into the v0.7.x → v0.8.x cycle as substrate refinements.

(B) Pre-1.0 surface audit checklist

Before committing to v1.0 backwards-compat, audit each public surface against "is this a stable contract?":

Surface	Audit question
`release-toolkit.yml` config schema	Is every field's semantic + behavior locked? Any field still labeled "experimental" or showing version churn?
`_release.yml` workflow_call inputs (`runs_on`, `toolkit_ref`, `bump_override`, `dry_run`)	Stable contract? Any input that's been renamed or had defaults churned since v0.4.0?
`release.yml` (consumer template) workflow_dispatch inputs	Same question for the consumer-side surface
`.release-toolkit-manifest.json` schema	`schema: 1` field is forward-proof; verify no field has migrated semantics
Fragment file format (frontmatter + body)	(B1) `summary:` is canonical; verify legacy fragments still parse
CHANGELOG.md format conventions	Stable `## [Unreleased]` + `## [vX.Y.Z]` patterns; verify the v0.4.x cleanup didn't leave a back-compat surface
Bash lib API (`cc_`, `fragment_`, `changelog_`, `forgejo_`)	INTERNAL ONLY — explicitly document as "not a stable consumer API"; consumers shouldn't source libs directly
Path-α convention (release-bot + token-override)	Documented in docs/integration.md; verify the §8 Axis A 5th instance (silent-drop quirk) is in the troubleshooting section
Branch-protection compatibility	Three paths (α/β/γ) documented; verify all three still work post-v0.6.2
ADR closure-state	All ADRs in `proposed`/`accepted` consistent with current substrate (ADR-0006 (c) just settled; ADR-0001 through ADR-0005 should also be re-audited for current alignment)

Each row could be its own follow-up issue if the audit surfaces a real gap.

Sequencing (loose; operator-paced)

Now — README refresh ([#3 tracker below] this issue's sibling) + adoption work continues
Through v0.7.x — primary cellblock adoption; tmux-tell unblock work
Through v0.8.x — empirical signals from adoption inform refinements; formal audit pass begins
v0.9.x or v1.0.0-rc.1 — final audit + lock-in decision + ADR-0007 candidate (release-toolkit v1.0 commitment)
v1.0.0 — formal SemVer 1.0 commitment

Timing is empirical, not calendrical. v1.0 lands when:

Adoption has surfaced + closed substantive rough edges
Audit has confirmed each surface is contract-ready
Operator + reviewer signal that the commitment is sound

Refs

Empirical convergence signal: AGENTS.md §10
ADR-0006 (c): architectural decision settled 2026-06-26
Sibling trackers: README refresh (this issue's sibling), label-based bump-control (separate substrate question)
Operator framing 2026-06-26: "Maybe we should start with an adoption first. This will expose some more rough edges for sure. And we should do some audits first, anyway."

## Umbrella tracker for the substrate-stability → v1.0 promotion path Per operator decision 2026-06-26: defer v1.0 promotion (the v0.7.0 minor cut surfaced the option) until consumer adoption surfaces rough edges + the toolkit substrate has been formally audited for "is this a stable contract?" The §10 arc-convergence ([AGENTS.md §10](../../AGENTS.md#10-substrate-grounding-arc-converged-at-v062-2026-06-26)) provided the EMPIRICAL signal for substrate stability. v1.0 is the FORMAL commitment — SemVer 1.0 says "backwards-compat across minor/patch from here; breaking changes require major." This umbrella tracker drives the work between empirical-convergence (achieved) and formal-commitment (pending). ## Two parallel work-streams ### (A) Adoption-driven empirical signal Adopt the toolkit on real consumers to surface what the §10 convergence couldn't predict — actual usage patterns, integration friction, real-world failure modes outside the toolkit's own self-bootstrap. - **#420** Cellblock adoption (cellblock#162) — in_progress - **#421** tmux-tell migration (tmux-tell#617) — pending, BLOCKED on gap-closure - Future consumers as they emerge Each adoption is an empirical probe. Catches surfaced during adoption feed back into the v0.7.x → v0.8.x cycle as substrate refinements. ### (B) Pre-1.0 surface audit checklist Before committing to v1.0 backwards-compat, audit each public surface against "is this a stable contract?": | Surface | Audit question | |---|---| | `release-toolkit.yml` config schema | Is every field's semantic + behavior locked? Any field still labeled "experimental" or showing version churn? | | `_release.yml` workflow_call inputs (`runs_on`, `toolkit_ref`, `bump_override`, `dry_run`) | Stable contract? Any input that's been renamed or had defaults churned since v0.4.0? | | `release.yml` (consumer template) workflow_dispatch inputs | Same question for the consumer-side surface | | `.release-toolkit-manifest.json` schema | `schema: 1` field is forward-proof; verify no field has migrated semantics | | Fragment file format (frontmatter + body) | (B1) `summary:` is canonical; verify legacy fragments still parse | | CHANGELOG.md format conventions | Stable `## [Unreleased]` + `## [vX.Y.Z]` patterns; verify the v0.4.x cleanup didn't leave a back-compat surface | | Bash lib API (`cc_*`, `fragment_*`, `changelog_*`, `forgejo_*`) | INTERNAL ONLY — explicitly document as "not a stable consumer API"; consumers shouldn't source libs directly | | Path-α convention (release-bot + token-override) | Documented in docs/integration.md; verify the §8 Axis A 5th instance (silent-drop quirk) is in the troubleshooting section | | Branch-protection compatibility | Three paths (α/β/γ) documented; verify all three still work post-v0.6.2 | | ADR closure-state | All ADRs in `proposed`/`accepted` consistent with current substrate (ADR-0006 (c) just settled; ADR-0001 through ADR-0005 should also be re-audited for current alignment) | Each row could be its own follow-up issue if the audit surfaces a real gap. ## Sequencing (loose; operator-paced) 1. **Now** — README refresh ([#3 tracker below] this issue's sibling) + adoption work continues 2. **Through v0.7.x** — primary cellblock adoption; tmux-tell unblock work 3. **Through v0.8.x** — empirical signals from adoption inform refinements; formal audit pass begins 4. **v0.9.x or v1.0.0-rc.1** — final audit + lock-in decision + ADR-0007 candidate (release-toolkit v1.0 commitment) 5. **v1.0.0** — formal SemVer 1.0 commitment Timing is empirical, not calendrical. v1.0 lands when: - Adoption has surfaced + closed substantive rough edges - Audit has confirmed each surface is contract-ready - Operator + reviewer signal that the commitment is sound ## Refs - **Empirical convergence signal**: [AGENTS.md §10](../../AGENTS.md#10-substrate-grounding-arc-converged-at-v062-2026-06-26) - **ADR-0006 (c)**: architectural decision settled 2026-06-26 - **Sibling trackers**: README refresh (this issue's sibling), label-based bump-control (separate substrate question) - **Operator framing 2026-06-26**: "Maybe we should start with an adoption first. This will expose some more rough edges for sure. And we should do some audits first, anyway."

quartermaster referenced this issue

2026-06-26 14:33:12 +02:00

feat(release): auto-assign manifest follow-up PR to the user who merged the rolling PR #113

quartermaster referenced this issue

2026-06-26 14:37:28 +02:00

feat(release): configurable publish mode — draft-first (default) vs immediate-publish #114

quartermaster referenced this issue from a commit

2026-06-26 14:40:57 +02:00

docs(integration): document review-gate tradeoff (closes #112)

~~quartermaster referenced this issue 2026-06-26 14:52:03 +02:00~~

docs: AGENTS.md §8 Axis A n=7 across 5 surfaces — merge_whitelist + self-approval banks #115

quartermaster referenced this issue from a commit