Release Policy

Prerelease policy

.SYSTEMX is in beta prerelease. Review the exact version before use. Guidance, interfaces, defaults, and compatibility may change during development. The MIT license provides the terms and warranty disclaimer. Passing template tests does not certify a downstream project for production. Keep recoverable backups and test your workflows before adopting or updating.

Branches and exact versions

main is the default public template branch. Alpha1 retains the integration history of the earlier alpha series. Both contain the consolidated history of the earlier template branches at the first alpha publication. Branches are moving references; use an exact release tag for repeatable installation. Keep only main and Alpha1 as standing branches. Feature branches are temporary: after their work is included in both standing branches and no open pull request or worktree needs them, remove the branch references. Their commits remain in history, and published release tags remain available. The merged feature branches were cleaned up on 2026-09-28.

The current installation version is 1.11.0-beta.4, tagged v1.11.0-beta.4 from the reviewed source recorded in Versions and changelog. The v1.9.0-alpha.1 tag was withdrawn after a distribution mismatch; do not install it or use it as a fallback. The initial v1.10.0-alpha.1 annotated tag was not published as a release and is superseded by alpha.2 after review found two validation issues. Its tag identity remains unchanged.

The first explicitly labeled alpha is 1.6.0-alpha.1, tagged v1.6.0-alpha.1. It follows the existing 1.5.0 history without reusing or rewriting old versions. The Python package spells that same version 1.6.0a1. Subsequent alpha snapshots increment the alpha number, or start a new base version when appropriate. Published tags and assets are not intentionally replaced; corrections get a new version. GitHub's immutable-release setting was enabled for this repository on 2026-10-05. It protects subsequently published releases, not older tags or releases retroactively. A tag alone is not a cryptographic release identity: maintainers should publish checksums for artifacts and verify the tag still names the reviewed commit. Daily development does not mean an automatic release every day.

Prior numeric versions and GitHub release labels are retained for compatibility. Those historical labels are not a production-readiness certification. The current development series is explicitly published as GitHub prereleases. There is no stable-release date, support SLA, or promise of compatibility throughout prerelease development. Changes should document migrations and preserve project-owned data.

Pins and update channels

• New projects are pinned to their chosen version and use manual updates.
• An exact prerelease tag or reviewed source explicitly selects those defaults.
• Unpinned final-version projects discover only final releases. An alpha tag incorrectly labeled final on GitHub is refused by stable discovery.
• Unpinned prerelease projects discover candidates according to the selected channel. The beta manager supports alpha < beta < final ordering and published beta/final candidates for beta discovery. A final selection returns the project to final-only discovery.
• The check-only manager introduced in 1.8.8 uses opt-in --auto on-start to check release metadata at most once per 24 hours after a successful check and reports a newer version. It works while a project remains pinned. Startup never downloads or selects a release. Prereleases can change interfaces within a major version, so review each version before manually selecting it.
• An explicit manual selection that changes stock root bootstrap or launcher files requires an external reviewed tool and a backed-up bootstrap-refresh before retrying the update. A startup notice changes neither those files nor the selected version.
• Discovery never silently downgrades a project. This manager can install and newly select only releases 1.8.7-alpha.1 or newer; bootstrap-refresh targets that same range. It can still run an already selected, verified older snapshot through an isolated compatibility shim; the old runner retains its historical behavior. An explicit older selection within the supported range needs unpinning, unchanged stock bootstrap/launcher files, and compatibility review. Bootstrap refresh will not roll those files backward. Earlier releases need a separately reviewed backup or legacy recovery path.

The channel is derived from activeVersion; a startup notice does not change it. No new setting is inserted into user task or policy records. Schema-1 INSTALLATION.json is read compatibly and gains schema-2 archive-digest receipts on a later manager state write. A null receipt for an older installed release cannot retroactively prove a remote pin. Alpha discovery inspects up to 1,000 GitHub releases and fails with exact-version guidance if that bound is exhausted. Drafts, unsupported version forms, and inconsistently labeled releases are excluded. Failed startup checks retain verified installed defaults.

Until the project's preserved root manager has been refreshed to 1.8.8 or later, an existing on-start installation can still select an update under its earlier startup behavior. Keep --auto manual (or run the reviewed external manager with --offline) during that migration.

Since 1.8.9, the manager bounds advisory release discovery to a five-second wait before the local runner continues with installed defaults. That wait is a caller limit, not proof that the underlying network request was cancelled. It remains a metadata-only check; selection and archive retrieval stay manual. The same manager also rejects empty explicit target/source paths and bounds local management-file reads. Use the selected release's exact versioned documentation when adopting these changes.

Repository protection scope

As verified on 2026-10-07, the upstream GitHub repository has secret scanning, secret-scanning push protection, and Dependabot vulnerability alerts enabled. Automated Dependabot security updates remain disabled. An active branch ruleset blocks deletion and non-fast-forward pushes for main and Alpha1; it has no pull-request, review, or status-check requirement. GitHub Actions remains disabled for this repository, and the beta source contains no Actions workflow. Maintainers run and retain applicable local release checks. These settings reduce selected publication risks; they do not scan every secret, authenticate a publisher, or certify the template. A project created from this template must configure its own repository protections and checks.

Upgrade an existing project to the current beta

Managers from 1.5.0 and earlier cannot parse alpha IDs. Upgrade the external tool environment first, from outside the project's .SYSTEMX folder. Use the interpreter belonging to that environment. The example below targets 1.11.0-beta.4. Verify the tag and the exact codeload ZIP digest through a channel you trust before the manual update steps.

python -m pip --log dotsystemx-beta-install.log install --upgrade "git+https://github.com/WayneTechLab/dotSYSTEMX.git@v1.11.0-beta.4"
systemx --version
systemx status --target "/path/to/project"
systemx bootstrap-refresh --target "/path/to/project" --source "/path/to/reviewed-dotSYSTEMX/.SYSTEMX"
systemx bootstrap-refresh --target "/path/to/project" --source "/path/to/reviewed-dotSYSTEMX/.SYSTEMX" --apply
systemx policy --target "/path/to/project" --pin none --auto manual
systemx update --target "/path/to/project" --version 1.11.0-beta.4 \
  --archive-sha256 3bf57ef2938815e801c7ca2959c8d9814f952f9a7e2ff8fa39b32fe79fc927de --dry-run
systemx update --target "/path/to/project" --version 1.11.0-beta.4 \
  --archive-sha256 3bf57ef2938815e801c7ca2959c8d9814f952f9a7e2ff8fa39b32fe79fc927de
systemx policy --target "/path/to/project" --pin current
systemx run --target "/path/to/project" --offline -- validate
systemx run --target "/path/to/project" --offline -- context --agent agent.0

Review the bootstrap preview before applying; use a reviewed source whose bootstrap matches the intended release. The new external manager backs up recognized stock root bootstrap and launcher files that it replaces. It may add a genuinely absent stock file, such as versions.py on an intact historical v1.5.0 install, only if no retained release ever contained that file. A file missing from the root despite appearing in a retained release, or customized or unrecognized content, remains a conflict. If it reports neither additions nor replacements, skip --apply. update blocks when the root bootstrap still differs, preventing new state metadata behind an old launcher. A reviewed checkout's new manager.py offers the same commands without a package install. The root VERSION and project records are preserved. Do not reinstall the old tool to operate a project still selecting an alpha version. Historical reselection below 1.8.7-alpha.1 needs a separately reviewed backup or legacy path and record/schema compatibility check. See the installation migration steps.

Updates add snapshots and missing files. They never remove or replace existing project files or directories; only manager-owned selection/history metadata is updated. The separately requested bootstrap-refresh is an explicit, backed-up exception for stock root bootstrap code. Fresh adoption refuses preexisting executable defaults with different content rather than retaining incompatible scripts. Existing project records remain schema 1. A future record migration must be explicit and preserve source records and evidence. For removal, use the logged uninstall and restore workflow.

Public distribution and support

GitHub hosts the source, template, wiki, versioned folder archive, and Python wheel. The current beta prerelease lists its files and checksums. The library is not currently published to PyPI. No hosted application, background service, telemetry collector, or MCP server is deployed by the source distribution. Network use is for requested release retrieval and opted-in startup discovery; configured project commands can have their own effects and must be reviewed separately.

For remote install, update, and first-run, an explicit --version can be paired with --archive-sha256. Supply the independently obtained digest of the exact codeload tag ZIP fetched by the manager. A wheel or separately built archive entry in the release's SHA256SUMS.txt is a different byte stream. The manager checks the pin before ZIP parsing and records whether the digest was explicitly pinned or merely observed. The distribution manifest checks internal consistency; neither it nor a checksum fetched from that same movable tag independently authenticates the publisher. In the check-only manager, opted-in startup discovery reads only release metadata and never downloads or selects an archive. After reviewing the notice, perform an explicit update with a separately trusted digest.

GitHub Actions is disabled for this repository, and no workflow is included in the beta source. Historical CI links describe earlier releases. Local validation and exact public release readback supply the beta evidence. Maintainers run release checks locally and attach resulting evidence to releases:

python3 -I -B .SYSTEMX/scripts/release.py --check
python3 -I -B -m unittest discover -s .SYSTEMX/tests -v
bash .SYSTEMX/SYSTEMX.sh validate --template

The direct manager, runner, and release scripts enter Python -I before imports, and named local helpers load from source bytes rather than unlisted modules or substituted .pyc files. The installed console command resolves its package through initial import paths before restarting isolated for manager import. Use a reviewed virtual environment's Python with -I -B -m systemx when those paths are untrusted. The importable library inherits its host Python trust environment. Publication builders reject symbolic links at their final output paths before writing release artifacts.

Repeat applicable checks on supported operating systems and Python versions before claiming cross-platform coverage. Historical CI links in the changelog refer to earlier releases, not current automation. Python 3.9 is the compatibility floor; prefer a currently maintained interpreter. Drive requires locally available regular files and coordinated writers. Chat requires an export or authorized writable tools; saving a chat alone does not persist project files.

Use support, contributing, and private security reporting. Review logs before sharing; paths, project names, and exported context may be private.

Version references: Semantic Versioning, Python version specifiers, and GitHub release API.