--- id: PX-PLAN-TXNM7OUB type: plan title: CI Release Preparation spec: PX-SPEC-DZLVGRW4 status: approved depends_on: - PX-PLAN-_BUERPCN - PX-PLAN-XQFSKHHG --- ## Outcome Luci prepares a versioned release candidate on a release branch without publishing it. Development and builds remain one workspace with one repository version. Future npm distribution uses independent extension packages sharing that version; publication, MFA, credentials, and the final npm release cycle require separate planning. ## Preparation flow CI prepares reviewable release state, not a published release. ```mermaid flowchart LR request["Source commit and requested version"] --> validate["Validate request"] validate --> version["Apply shared version in CI"] version --> verify["Build and verify candidate"] verify --> branch["Prepared release branch"] ``` ## Behaviors 1. Accept an explicit source commit, target release branch, and requested semantic version. Reject invalid input, protected development-branch targets, and conflicting existing release state before mutation. Do not infer a bump or choose a version from an incomplete compatibility matrix. 2. Apply the requested version in CI through Mise-owned automation. Update authoritative version metadata and the lockfile consistently; generated package versions derive from that same value. Preserve declared Pi compatibility rather than changing support as a side effect of preparation. 3. Build and verify the candidate from that versioned source using existing release-build, snapshot, and package-verification capabilities. Retain verification results and candidate provenance identifying source commit, shared version, and artifact digests. Keep failed preparation from producing a branch that appears ready. 4. Commit the prepared version metadata to the explicit release branch only after successful verification. Guard against branch movement and conflicting concurrent preparations instead of overwriting them. An identical retry is idempotent; a different source or version requires an explicit new request. Report the prepared branch and evidence for human review without tagging, merging, or publishing. ## Constraints - Mise remains the public automation interface; Luci workflow definitions delegate execution to Mise. - Reuse existing release preparation rather than introducing a second version or artifact authority. - Git write access is limited to the intended release-branch operation; credential provisioning needs separate approval. - Do not request npm credentials, configure MFA, invoke npm publication, or publish candidate artifacts to a public package channel. - Prevent preparation commits from recursively triggering further preparation. - Preserve unrelated work and existing normal-CI and hook behavior. - This amendment defines preparation only; it does not authorize a local version bump, commit, push, or release during planning. ## Deferred - Npm publication, authentication/MFA, package selection, account setup, and the final release cycle. - Broader Pi × Node × OS compatibility exploration and empirical changes to the declared minimum. - Hook-cadence changes and unrelated CI restructuring. - Reconciliation of the broader architecture spec and core distribution wording before implementing future independent npm publication. ## Verification - [ ] Invalid requests and conflicting release state fail before version or branch mutation. - [ ] CI applies one requested version consistently to authoritative metadata, lockfile, and generated candidate packages. - [ ] Failed verification leaves the remote release branch unchanged. - [ ] Successful preparation produces the requested release branch with matching source, version, and verification evidence. - [ ] Identical retries do not create duplicate preparation commits; branch races fail safely. - [ ] Preparation performs no npm publication, public package upload, tag creation, development-branch merge, or recursive preparation.