# Framework Package Release Shared reference for `post`, `build`, and `ship`. Canonical policy for validating linked framework source, preparing `@crossplatformai/*` versions, user-owned publication, promoting `-next` packages, and verifying exact registry versions before a consumer production release. Load it when release work is in scope. Do not load a separate `release-framework-packages` skill. When temporary links are involved, also load `temporary-pnpm-package-links`; that standalone skill owns generic manifest, lockfile, Syncpack, resolver/config, ESLint override, linked-validation, and manual-finalization ownership policy. ## Publication And Unlink Ownership AI agents must never publish packages or mutate registry state, even when a Build Launch Prompt, task-level approval, or user message explicitly asks them to publish. Agents must never unlink a temporary package, install its registry replacement, validate the replacement, stage the replacement state, or commit it. Publication and consumer dependency replacement are user-owned manual release finalization. `post` frames release work, `build` prepares and verifies approved framework package versions after linked consumer validation, and `ship` commits that preparation. None of those phases may run `pnpm release`, `npm publish`, `npm dist-tag`, production release commands, or other registry mutation. Those commands are never minimum or baseline QA. Framework publication and consumer production release are distinct. The user may publish a framework package after linked-source validation while its consumer remains linked. The consumer must not be deployed, distributed, or released to production until the user installs and verifies the exact registry dependency. ## Release Safety Rules - Complete consumer implementation, renderer validation, QA, review, staging, development commits, production-mode validation builds, and approved framework version preparation may continue while a temporary link remains. - Production-mode builds are validation only. They do not authorize consumer deployment, distribution, or production release. - Agents must refuse every registry publication command and every unlink or registry-replacement action under all approval states. - Version-bump commits must be fully shipped through `ship` before the user publishes the corresponding package. Preserve the clean-working-tree readiness requirement for the user's release command. - Version format determines the channel: `x.y.z` maps to `latest`, `x.y.z-next.n` maps to `next`, and unsupported formats are blocked. - Preserve package validation, release-channel, version-selection, registry-state expectation, and clean-tree guidance when preparing the release candidate. ## Planning Metadata (`post`) Capture in the Build Launch Prompt when release work is in scope: 1. release mode: new package preparation, `next` prerelease, `next` iteration, stable promotion, consumer registry verification follow-up, or mixed bulk coordination 2. framework repository path and affected package paths 3. consumer repository paths and affected apps/packages, plus explicit exclusions 4. package matrix: package name, path, current version, target version, release type, NPM dist-tag expectation, and whether the version already exists on NPM when known 5. version-format decision (`x.y.z` -> `latest`, `x.y.z-next.n` -> `next`, unsupported blocked) 6. git-history evidence when choosing between `next` iteration and stable promotion 7. first-time package readiness checklist when preparing a new package (see below) 8. linked consumer validation evidence and temporary-link metadata required by `temporary-pnpm-package-links` 9. confirmation that publication, unlinking, replacement installation and validation, staging, and the replacement commit are user-owned 10. sequencing model: per-package or bulk coordination 11. clean-working-tree requirement for the user's later publication 12. interactive-terminal constraint for the user's later publication 13. NPM registry-state expectations and exact registry version to verify 14. user-owned NPM verification commands, such as `npm view @crossplatformai/{name}@next`, `@latest`, or `dist-tags` 15. required framework QA before the preparation commit and required linked consumer QA already completed against the source that will be published 16. manual release finalization status: `pending | complete` 17. completion reporting: `implementation: complete against validated linked source` 18. expected Ship evidence (see Ship Evidence And Refusal) Publication and unlinking must not appear in agent acceptance criteria or commit partitions. Mention pending manual finalization only as a concise out-of-scope follow-up. ## Validation-First Sequence Use this order: 1. Validate the complete consumer feature and every in-scope renderer against linked framework source until implementation and QA indicate no code changes are anticipated. 2. Prepare the approved framework package version and metadata from that already exercised source. 3. Run the authoritative final QA selected from the completed diff and invoke `ship` for coherent preparation commits. 4. Report the linked-source implementation as complete and manual release finalization as pending. 5. The user publishes the validated framework package while the consumer may remain linked. 6. The user replaces the link with the exact registry version and owns installation, residue removal, verification, QA, staging, and the replacement commit. 7. Only after the exact registry dependency is verified may the consumer be deployed, distributed, or released to production. Framework publication is not a prerequisite for implementing or validating the consumer feature. Manual steps 5 and 6 remain outside agent commits and acceptance criteria. For sequencing the agent-supported preparation, choose one model: 1. **Per-package**: after linked consumer validation, prepare one package version, run focused QA as needed, run the authoritative final manifest, and invoke `ship`. Repeat for each approved package. 2. **Bulk coordination**: after linked consumer validation, update all approved framework package versions, run focused framework QA as needed, then run authoritative final QA and ship coherent preparation commits while preserving repository boundaries. Release preparation uses coherent narrative commits. Do not create a release-only count mechanism. Version-bump commit messages must satisfy `ship`'s rules. ## Build Execution Require the release metadata before editing. Confirm target framework and consumer repositories from the handoff and repo guidance before non-read commands. Do not hardcode a fixed consumer list. ### New Package Readiness When first-time NPM publication is planned, verify or implement only approved package metadata: `private: false`; `license: "SEE LICENSE IN LICENSE"`; `repository` with the correct package directory; `publishConfig.access: public`; `files` includes only intended published files; required publish scripts when the repo uses them; `LICENSE` exists; `.gitignore` when expected; `README.md` when required; no package-level `.npmrc` unless explicitly approved. ### Linked Consumer Validation Require evidence that the consumer implementation and relevant web, Electron, and mobile surfaces were validated against the linked source before version preparation. Follow `temporary-pnpm-package-links` for the approved linked state, lockfile proof, resolver/config and ESLint override evidence, and production-release guard. Do not replace the link during Build. Production-mode consumer builds may be used as validation, but deployment, distribution, and production release remain blocked until the user verifies the exact registry version. ### Per-Package And Bulk Preparation Follow the handoff sequencing model. Per-package: inspect the package's `package.json`, edit only the approved version/metadata, run focused QA as needed, then run the authoritative final manifest and invoke `ship`. Bulk: edit all approved framework package versions, run focused framework QA, then run authoritative final QA and ship coherent units preserving repository boundaries. Run authoritative required QA in each affected framework repository against the completed diff. Classify content mutations and rerun the manifest portions they invalidate. Any failed required QA blocks `ship`. ## Manual Release Finalization After agent-supported preparation is shipped, the user owns publication and consumer replacement. Agents may report the exact package/version matrix, expected dist-tag, clean-tree requirement, registry verification expectation, and manual-finalization status. They must not execute, validate, stage, or commit any publication or unlinking action. Manual finalization being pending does not make a completed linked-source consumer implementation partial. It only keeps consumer deployment, distribution, and production release blocked. ## Ship Evidence And Refusal The Ship handoff must include, when this reference was used: release mode; sequencing model; unconditional user ownership of publication and unlinking; package/version matrix with current/target version, release type, path, and expected dist-tag; git-history or planning evidence for `next` iteration vs stable promotion when applicable; new-package readiness results when applicable; linked consumer validation evidence required by `temporary-pnpm-package-links`; framework files changed and QA results; clean-tree readiness; confirmation that no publish, registry mutation, unlink, replacement installation, replacement validation, replacement staging, or replacement commit action ran; and the two completion statuses. `ship` refuses when: staged package version changes do not match the approved matrix; staged versions use unsupported formats other than `x.y.z` or `x.y.z-next.n`; release preparation lacks release mode, sequencing model, package/version matrix, linked consumer validation evidence, or clean-tree readiness; an agent ran or proposes any registry publication or unlink/replacement action; manual publication or unlinking appears as an agent commit unit, acceptance criterion, or checkpoint; or a consumer production release is proposed before exact registry dependency verification. Release preparation commit messages must satisfy `ship`'s commit-message rules. Per-package version bump commits should usually use `chore(): bump version to x.y.z` when the full header is 50 characters or fewer; otherwise use a shorter valid scope or subject without truncating words.