Adopt an evidence-bound, two-phase local release process

[projectious]

Recommendation

Adopt a repository-owned release command modeled on the release process proven in projectious-work/aibox. The goal is a repeatable, resumable release ritual that validates the exact candidate, publishes complete artifacts and documentation, and leaves authoritative post-publication evidence.

Reference process to replicate

1. Version-line authority

• Maintain a development branch and a protected release-integration branch for each supported version line.
• Derive the required release branch from the requested semantic version; reject releases from any other branch.
• Require PR-based promotion into protected branches. Never force-push a release branch.
• Tag only the designated release-integration branch, then merge tagged history into main through a PR.

2. Phase 0: state and doctor reports

Before version/tag mutation:

1. Generate a release-state report covering pinned dependencies, tool/runtime versions, release assets, and other floating inputs.
2. Run project and runtime doctors into a durable report.
3. Block on every error. Surface warnings and actionable information for explicit resolution or a linked tracked deferral.

Suggested outputs:

• dist/RELEASE-STATE.md
• dist/RELEASE-DOCTORS.md

3. Candidate-bound validation

After version metadata is correct, bind validation to:

• exact candidate commit SHA;
• requested version;
• clean/dirty tree state;
• toolchain fingerprint;
• environment-specific scope where relevant.

Run independent gates with bounded concurrency and separate logs. Reuse evidence only when every binding still matches. Typical gates:

• format/lint/type checks;
• unit and integration tests;
• real E2E/runtime tests;
• dependency and supply-chain audit;
• release artifact builds;
• native binary/version smoke;
• project-specific readiness/evidence gates.

Store local evidence under a candidate-specific directory such as dist/release-evidence/vX.Y.Z/<commit>/.

4. Documentation gate before publication

Make documentation validation mandatory whenever tag or release publication is selected:

• require tracked release-notes/vX.Y.Z.md;
• require compatibility/support metadata for the version;
• verify root README and contributor/maintenance guidance;
• build the complete documentation site with production settings;
• fail before tagging if any required surface is missing or the docs build fails.

Deploy documentation only after the candidate passes this gate.

5. Publication

From the protected release branch:

• promote the validated candidate through a PR if necessary;
• prepare/reuse curated tracked release notes;
• create and push an annotated tag;
• create the GitHub release with all required archives, checksums, license, and correct prerelease/latest classification;
• deploy documentation;
• emit an explicit prompt/report for any host-only completion phase.

Do not create a bare GitHub release that omits artifacts.

6. Optional host-only phase

If some targets or containers require a separate host/runtime:

• sync the host checkout to the exact release branch and verify the tag is reachable from it;
• preserve dirty checkouts in named stashes before switching;
• build/upload host-specific artifacts;
• publish container images;
• run a downstream-style smoke against published artifacts;
• verify public manifests/assets and record timings.

7. Final verification

Verify the public release, expected assets/checksums, installer behavior, published packages/images if applicable, documentation URL, release-branch/tag ancestry, and final worktree state. A local green test run alone is not release completion.

Suggested interface

./scripts/maintain.sh release X.Y.Z
./scripts/maintain.sh release X.Y.Z --steps phase0
./scripts/maintain.sh release X.Y.Z --steps checks,build
./scripts/maintain.sh release-host X.Y.Z   # only if host-only work exists

Equivalent naming is fine; one repository-owned entrypoint should orchestrate the ritual.

Acceptance criteria

• Version-to-release-branch mapping is explicit and tested.
• Protected release branches are PR-only and tags are cut only there.
• State and doctor reports run before version/tag mutation.
• Errors block; warnings/actionable infos are resolved or linked to tracked deferrals.
• Validation evidence is exact-commit/version/toolchain/environment bound.
• Independent gates use bounded concurrency and retain per-gate logs.
• Tracked release notes and a production documentation build are mandatory pre-publication gates.
• Release publication attaches every required artifact/checksum/license file.
• Any host-only phase verifies branch/tag provenance before building.
• Public release, package/assets, documentation, and repository state are verified after publication.
• The full workflow and recovery/resume behavior are documented for maintainers.

Why this fits processkit

processkit already has strong schema, doctor, migration, and release-audit concepts. This process would make those checks part of a single executable publication contract and ensure its CLI/runtime packages, release assets, compatibility guidance, and public documentation are released from the same validated candidate.

[projectious]

Implemented the repository-owned core in #152 (merged to v1.x-dev): explicit/tested version-line mapping, exact candidate evidence binding, Phase 0 state/doctor reports, tracked deferrals, three bounded concurrent gates with separate logs, mandatory tracked notes and production docs validation, signed artifact publication including LICENSE, resumable markers, documentation deployment, and public checksum/signature/tag/release verification.\n\nThe issue remains open intentionally for the operational pieces that should not be overstated: enforcing PR-only protection on all designated release branches and completing the optional host-only/multi-target phase (also tracked by #135). The current release-host command fails closed until that provenance/build/smoke contract exists.

[projectious]

Resolved by the evidence-bound release workflow now on v1.x-dev.

Final acceptance review:

• explicit version-to-branch mapping is implemented and contract-tested;
• main and v1.x-dev both enforce PR reviews, admin enforcement, no force
  pushes/deletions, and conversation resolution;
• phase 0 records candidate version, commit, clean-tree state, toolchain, host,
  release state, doctor output, and tracked deferrals;
• audit, tests, and docs run as separate bounded logs against one candidate;
• release notes, landing docs, artifacts, checksums, signatures, and license
  checks are release gates;
• public-download verification checks checksums, signatures, and the annotated
  tag;
• reusable state markers document and support recovery/resume;
• the optional host command currently fails closed before artifact production,
  so it cannot build from unverified provenance. Production and smoke testing
  for all hosts is tracked in v1.x: complete trusted four-platform release distribution #165.

Validation completed:

• scripts/test-maintain-local.sh
• bash -n scripts/maintain.sh
• scripts/maintain.sh release-branch v1.0.0-alpha.5

Closing the process proposal as implemented; #165 owns the remaining native
host production work.