v0.3.0 release boundary

v0.3.0 is a focused reliability release candidate for people adopting the public npm package. It ships the verified macOS Keychain correction and adds only those upgrade transitions that can restore their prior Codex state after interruption. It does not expand Roku device behavior.

Architecture invariant

The established language ownership remains unchanged: Python handles device operations, flows, analysis, and MCP; Node.js handles installation, packaging, launch, marketplace, and repository integration.

Evidence behind the boundary

Evidence	Decision
The published v0.2.0 package passed clean-install smoke tests on macOS, Linux, and Windows.	Preserve the package, language, and host-support boundaries.
A real v0.2.0 macOS setup timed out while storing the developer password.	Include the merged native Keychain fix and retain a sanitized manual macOS gate.
Fresh setup deliberately refuses an existing marketplace, leaving users with a manual remove-and-install procedure.	Make recoverable upgrades the only new product capability.
No reproducible demand currently requires new MCP tools, flow semantics, or artifact viewers.	Defer those themes until adoption evidence identifies a concrete problem.
Existing physical Roku evidence covers one recorded host/device combination.	Preserve the evidence boundary; do not imply broader hardware coverage.

In scope

1. macOS configuration reliability

• Ship the native Keychain storage path completed by issue #20.
• Reject empty passwords before changing an existing item.
• Keep passwords out of subprocess arguments, streams, captured output, errors, and committed evidence.
• Preserve the saved target and installed plugins when credential storage fails.
• Retain process-scoped ROKU_DEV_PASSWORD behavior on Linux and Windows.

2. Transactional upgrades

The transactional upgrade state model defines the safe boundary. Implementation is limited to states for which the exact prior marketplace source, version/ref, installed-plugin set, and enabled/disabled choices can be reconstructed. For each supported state, the upgrade must:

• preflight Node, Python, Git, Codex, target version, and current marketplace/plugin state before mutation;
• preserve device configuration and Keychain contents;
• apply marketplace and plugin changes in a documented order;
• restore the exact prior supported state if any bounded command fails, times out, or is cancelled;
• report rollback failures separately from the initiating failure; and
• be idempotent after either a successful upgrade or a successful rollback.

Local marketplaces, unversioned sources, orphaned or mixed plugin sets, unknown source metadata, and any state that cannot be reconstructed exactly must be refused without mutation. The documented manual procedure remains the fallback for refused states.

3. Documentation and release integration

• Document supported and refused upgrade states, recovery, and configuration preservation.
• Add the upgrade path to the CLI help, getting-started material, troubleshooting, npm distribution notes, and documentation portal.
• Extend package and published-package evidence without weakening the existing clean-install smoke.

Explicitly out of scope

• New MCP tools, device actions, authentication rules, product endpoints, or deployment behavior.
• Relaxing flow validation or treating action/screenshot completion as proof of UI correctness.
• A graphical report viewer, structured artifact browser, or new flow-schema ergonomics without a reproducible adopter problem.
• PyPI distribution, a bundled Python runtime, native installers, or automatic background updates.
• Signed release artifacts or an additional checksum system beyond npm provenance and Git tag comparison.
• Moving the documentation portal away from GitHub Pages or creating a separate website repository.
• Broader Roku hardware claims or requiring every host/device permutation.
• Official marketplace submission work not required for the versioned Git marketplace workflow.

Deferred work should become a focused issue only when it has a reproducible user scenario, a clear security requirement, or measured maintenance evidence.

Release gates

v0.3.0 is ready to tag only when all of the following are true:

1. Issue #13’s state-transition model identifies every supported and refused starting state, and implementation exists only for reconstructible states.
2. Focused tests cover successful upgrade, no-op/retry behavior, each refused state, interruption at every mutation boundary, rollback success, rollback failure reporting, cancellation, and timeout.
3. The upgrade matrix passes on macOS, Linux, and Windows using isolated Codex state. These are host tests, not physical Roku claims.
4. A manual Codex-profile check confirms one supported v0.2.x-to-v0.3.0 upgrade, preserved plugin enablement choices, and retained device configuration. Record only sanitized outcomes.
5. The final native Keychain path has a sanitized macOS result showing hidden input, successful storage, password_available: true, and password_source: keychain. This has been observed on the development branch and must remain covered by tests on the release commit.
6. npm run validate, npm run test:package, website checks, release verification, and the complete GitHub Actions matrix pass on the release commit.
7. Package, lockfile, plugin manifests, release notes, Git tag, npm package, and version-specific published-package contract all agree on 0.3.0 / v0.3.0.
8. The packed inventory and post-publication clean-install smoke preserve the existing credential, lifecycle-script, executable, runtime-engine, MCP-contract, tag-provenance, and artifact-safety checks.
9. Physical Roku operations remain unchanged, or any necessary device-facing change receives separate, evidence-aware hardware validation. Command completion alone is never a UI pass.
10. Tagging, GitHub release publication, and npm publication remain explicit user-approved actions after the release-preparation PR merges.

Readiness rule

Security or correctness defects in supported workflows block the release. Speculative, low-impact, or unsupported-state improvements do not expand this boundary; record them for a later milestone.