Skip to content

Release Tooling

Jump to bottom
coo1white edited this page Jun 8, 2026 · 1 revision

Release Tooling (v0.1.33)

The mechanical part of cutting a tag becomes three deterministic scripts plus a de-duplicated release gate; the kernel runtime is untouched. Shipped in v0.1.33. Repo doc: docs/release-tooling.7.md.

The design mantra for this layer:

One source of truth.
Mechanical surfaces are DERIVED, fail-closed.
Move the toil into tooling, not the author.
Print gate edits; never auto-edit a gate.
The kernel is untouched.

The Borrowed Idea: Base-System Separation (Mechanism vs Policy)

Release Tooling reuses the same base-system separation CW applies elsewhere: there is ONE source of truth and the mechanical surfaces are DERIVED from it, fail-closed. The version source of truth is package.json; every structured version surface is rewritten FROM it (mechanism), while the author still owns the decision of WHAT version to cut and WHAT a feature is (policy). The kernel — orchestrator, dispatch, runtime — issues nothing new; this is purely build/release machinery.

Before v0.1.33 a release meant hand-editing the version across ~17 surfaces and recreating the same doc/test/CHANGELOG shapes by hand — slow, and the source of stale-version gate failures. v0.1.33 moves that toil into tooling so an author spends time on the feature, not the boilerplate.

bump:version  ->  new:feature  ->  forward-ref  ->  de-duplicated release:check

1. One Version Source, Many Derived Surfaces

bump:version (node scripts/bump-version.js <new-version>, e.g. npm run bump:version -- 0.1.33) rewrites every STRUCTURED version surface from a single source, package.json: package.json, package-lock.json, src/version.ts, manifest/plugin.manifest.json (then gen:manifests propagates to the vendor manifests), every apps/*/app.json (top-level version only, never compatibility.minVersion), and the scripts/tests that hard-code the current version as a current-version reference. It then rebuilds dist/, runs version:sync, and reports the remaining prose-doc surfaces.

2. Targeted Replace Preserves History

The version string is swapped with a TARGETED old -> new replace, so historical references are preserved — a prior minVersion, a pre-vX note, a fixed demo version all survive the bump. This is why app.json rewrites touch the top-level version only and never compatibility.minVersion.

3. The Checker Reads the Bump Source

version-sync-check.js reads the expected version from package.json — the same source bump:version writes to — so the checker can never drift from the bump source. There is one version source of truth and no second source for the checker to fall out of step with.

4. Scaffold the Per-Tag Boilerplate

new:feature (node scripts/new-feature.js <slug> "<Title>" ["summary"]) scaffolds the per-tag boilerplate: the docs/<slug>.7.md skeleton, a runnable test/<slug>-smoke.js stub, and a CHANGELOG entry. It then PRINTS the exact gate-file edits — capability registry, version:sync assertions, the docs presence list, the npm test chain.

5. Print Gate Edits, Never Auto-Edit Them

Gate files are printed, never auto-edited, so a scaffold can never silently break a release gate. The author applies the printed edits deliberately; the tool does not reach into the gate definitions on its own.

6. Forward-Reference Docs, Append-Only and Idempotent

forward-ref (node scripts/forward-ref-docs.js "<Title>" "<summary>") appends a ## <Title> (vX) forward-reference section to every doc version:sync requires to carry the current version — the repo's per-release documentation pattern. It is APPEND-ONLY and idempotent: it never rewrites a historical version label, and re-running it for the same version is a no-op.

7. The Gate Drops Duplicates, Not Coverage

release:check previously ran npm test AND then re-ran ~15 of those same smoke tests individually (plus redundant eval:replay/fixture-compat re-runs). Every individual step was already covered by npm test, so they were removed — the gate keeps full coverage while dropping the duplicate wall time. The steps that remain are the ones NOT covered by npm test: build, type check, npm test, canonical-apps, golden-path, parity, vendor-manifest drift, and version:sync.

Boundary

Release Tooling touches only the build/release surfaces. It adds no runtime capability, no CLI/MCP verb, and no run-state schema change; the kernel is unchanged. Older releases cut by hand remain valid — the scripts only standardize the mechanical surfaces a tag must update.

Why It Matters

Stale-version gate failures were a recurring tax on every release, and ~17 hand-edited surfaces is exactly the kind of repetitive, error-prone work a deterministic script does better. By deriving the mechanical surfaces from one source and de-duplicating the gate, a tag becomes a predictable operation that keeps full coverage at lower wall time — and the kernel stays out of it entirely.

See Also

Organized from local Obsidian notes and reconciled with the current coo1white/cool-workflow repository state.

Cool Workflow

Start here

Go deeper

Source docs

Clone this wiki locally