Upgrading

Adoption and upgrades

Treat the reusable standard and an active project's records as different kinds of content. Review an update in the intended checkout, preserve local changes, and merge the standard without replacing the project's accepted plan or memory. Each project selects its own defaults; updates do not synchronize project memory or configure automatic updates in other projects.

Upgrade to the alpha series

Install the new external CLI before selecting an alpha version; managers from 1.5.0 and earlier only accept numeric final IDs. Follow the exact commands in release policy. Existing schema-1 project records and manager state remain supported. A later manager state write upgrades installation state to schema 2 with archive-digest receipts; historical releases get null receipts. Task and role record schemas stay unchanged. Alpha does not grant permission to reset or overwrite them.

The current manager can inspect an older selected installation with status, run its verified retained snapshot through an isolated compatibility shim, and perform the external bootstrap/update migration below. It cannot install or newly select a release older than 1.8.7-alpha.1, the first native isolated runner release. bootstrap-refresh also requires a target at or above that floor. The shim keeps the already selected old runner available if a refresh succeeds but an update fails; that runner keeps its historical behavior and record limits. Historical reselection below the floor requires a separately reviewed backup or legacy path.

Managed installs and preserved files

The installer and updater add versioned default snapshots and missing root files while preserving every existing project file and directory. Use them to adopt a current managed-install release, then select the desired version independently for each project. New installs are pinned with manual updates. The root VERSION remains the initial seed version; installation state identifies the currently selected defaults.

An older project's launchers are preserved by ordinary updates. During adoption use a reviewed new external systemx command or manager.py from outside the target to select new defaults. Existing old shell and PowerShell scripts are not silently replaced and may not expose new commands. The eight stock root bootstrap and launcher files have a narrow explicit refresh path below. This matters for the 1.8.8-and-later check-only startup policy: a preserved old root manager can still select a release at startup. Keep --auto manual until the reviewed external 1.8.9 manager refreshes the stock root bootstrap and the new release is selected. After that, a pinned installation may opt into --auto on-start notices without unlocking; selection stays manual. Review any custom root guidance against the selected release, and use validate to check the existing records before continuing. Adoption does not migrate or clear incompatible legacy ledgers, rewrite old generated views, or assert application readiness. Perform any needed record reconciliation explicitly.

Refresh the root bootstrap before a changed release

An ordinary changed-release update, including its dry run, refuses a target whose root manager.py, lifecycle.py, versions.py, systemx_paths.py, SYSTEMX.sh, SYSTEMX.ps1, INSTALL.sh, or INSTALL.ps1 differs from the intended release. Use a reviewed new tool outside the target to preview and, if appropriate, refresh those eight stock files. For an offline reviewed checkout, replace both paths in this sequence:

python3 -I -B "/path/to/reviewed-template/.SYSTEMX/manager.py" bootstrap-refresh \
  --target "/path/to/project" --source "/path/to/reviewed-template/.SYSTEMX"
python3 -I -B "/path/to/reviewed-template/.SYSTEMX/manager.py" bootstrap-refresh \
  --target "/path/to/project" --source "/path/to/reviewed-template/.SYSTEMX" --apply
python3 -I -B "/path/to/reviewed-template/.SYSTEMX/manager.py" policy \
  --target "/path/to/project" --pin none --auto manual
python3 -I -B "/path/to/reviewed-template/.SYSTEMX/manager.py" update \
  --target "/path/to/project" --source "/path/to/reviewed-template/.SYSTEMX" --dry-run
python3 -I -B "/path/to/reviewed-template/.SYSTEMX/manager.py" update \
  --target "/path/to/project" --source "/path/to/reviewed-template/.SYSTEMX"
python3 -I -B "/path/to/reviewed-template/.SYSTEMX/manager.py" policy \
  --target "/path/to/project" --pin current
python3 -I -B "/path/to/reviewed-template/.SYSTEMX/manager.py" run \
  --target "/path/to/project" --offline -- validate

On Windows, use py -3 -I -B with the same external manager path. Review the preview's add, replace, and conflicts fields before applying it. bootstrap-refresh accepts existing root bytes only if they match the target release or an intact retained release. It may add a stock bootstrap file only when that path is absent and the file was absent from every intact retained historical release. For example, a genuine v1.5.0 installation can gain the later versions.py. A file that existed in any retained release but is now missing, or whose contents are customized or unrecognized, blocks refresh for manual review. Applying creates only absent add files and backs up only replace originals under .SYSTEMX/.systemx/history/bootstrap-.../. An add-only refresh has no original to back up. The refreshed stock wrappers invoke the manager with Python -I -B. The operation leaves project records, version selection, and the pin untouched. Keep the reported backup path as evidence.

The later update remains additive and selects the new defaults snapshot. bootstrap-refresh refuses a target release below 1.8.7-alpha.1 or earlier than the current selected version; it is not a rollback operation. A later selection inside the supported range works only when the stock bootstrap files already match and project records remain compatible. An exact remote --version can be paired with an independently obtained --archive-sha256 for refresh and update. Never run the old root manager to perform this migration.

Existing 1.1.0 projects

1. Record the current Git state and preserve a recoverable copy or commit under the project's normal workflow.
2. Review changes to tooling, tests, guidance, templates, version, and provenance. Preserve project.json, WORK/TASKS.json, AGENTS/REGISTRY.json, all agent memories, GLOBAL/CONTEXT.md, PLAN/MASTER-PLAN.md, MEMORY/PROJECT.md, and session records. Merge instructional additions around populated content.
3. Add the blank WORK/FOCUS.json only if it does not exist. Preserve an existing focus record. CURRENT.md is a new generated view: if the project already has a hand-written file by that name, preserve it as a dated session checkpoint before adopting the generator. Review links to that former file.
4. Run bash .SYSTEMX/SYSTEMX.sh refresh-work, then validate. Both use the existing task IDs, statuses, evidence, and history; no task schema migration or renumbering is required.
5. Select the existing objective and relevant task IDs using focus. Link the preserved checkpoint if useful, then inspect context --agent agent.0.

Use ordinary validate on the adopted project. validate --template is for blank public distributions and should reject real project records. The updated validator also checks chronological history and rejects stale current blockers, reviewers, or terminal next actions. If a manual edit or old integration left inconsistent metadata, reconcile it against original evidence; do not fabricate timestamps or clear acceptance history merely to satisfy the validator.

Example after the project already has TASK-001:

bash .SYSTEMX/SYSTEMX.sh focus --objective "Finish the accepted milestone" --task TASK-001
bash .SYSTEMX/SYSTEMX.sh task-ready
bash .SYSTEMX/SYSTEMX.sh context --agent agent.0

The focus record is a compact pointer. It contains no hand-maintained task status, blocker, next action, totals, or runtime health. Those come from the task ledger or freshly inspected evidence. The command replaces the selection; include every task ID to retain in the next focus.

Other SYSTEMX layouts

Existing projects may use status/, TODO/, MasterPlan/, plans/, CURRENT.md, or domain-specific ledgers. Inventory their actual authorities before migration. Do not copy the blank template over them or import historical queues as if they were new assignments.

Preserve original IDs and acceptance credit in their existing ledger. Keep one authority during a staged adoption: either retain that project's ledger and adopt the written guidance only, or design and verify an explicit migration. The generic CLI currently accepts TASK-001 task IDs and M-001 milestone IDs; it is not a lossless importer for arbitrary legacy IDs, receipt schemas, or controllers. A mapping must retain provenance, dependencies, open obligations, and original evidence before switching authority. Parallel advisory views must never become independent completion ledgers.

Keep domain extensions in the host project's chosen directories and link them from Global context. Trading controllers, contract release policies, provider deployment scripts, local dashboards, and active-project history are not part of this universal template. Keep operational/private content outside public build outputs.

Adding SYSTEMX PROJECTS

Update the outer installation to a release containing docs/PROJECTS.md and scripts/project_workspaces.py; review/unpin the current version first, then re-pin after verification. Existing root tasks and memory remain in place. Use projects add NAME to preview a new blank child and --apply to create it; never install another .SYSTEMX under the outer folder.

If Projects/REGISTRY.json already exists, additive updates preserve it. A custom schema or populated legacy .SYSTEMXP may need a reviewed migration to the generic registry and record contracts. New commands reject unknown schemas and occupied destinations without replacing them. Preserve the original records, IDs, evidence, and private source references. Do not copy real project records into the public template or blank creation seeds.

Agent X/Y/Z adoption

Update the selected defaults to a compatible release, verify it, and keep the version pinned. Preview roles-init in each intended scope before applying it. An update alone preserves registries and does not activate roles. The public seed registry remains Agent 0 only so existing managed launchers can verify upgraded defaults. Once agent.x, agent.y, or agent.z is registered, older tool versions cannot interpret those IDs: keep a compatible selected release. Historical recovery requires a reviewed backup or legacy path and a record compatibility check. Never delete events or review records to make a downgrade appear successful. Project REVIEWS/POLICY.json is preserved; adopt later default questions only through an explicit versioned policy edit. Agent Y's project-owned portable jobs and memory are preserved by an update; a new default does not launch the configured provider or resume an interrupted run. Its ignored state/agent-y/ sidecars contain host-local execution paths and configured arguments; preserve them for same-host recovery, but do not publish them or assume they work after moving the project to another host. Inspect the selected repo, process, branch, and PR state before retrying.

Adopt AUTOBOT and DATA additively

The 1.10.0-alpha.2 defaults add AUTOBOT/Agent Alpha and DATA scaffolds/audit. Update/select reviewed defaults first using the existing bootstrap-refresh, backup, and pin rules. Existing specialist files, brand/rules/memory, local payloads, and old results are never reset to the new seeds. Optional agent.a activation is explicit and separate from X/Y/Z. Child panel/DATA initialization is selected and additive. Older runners cannot interpret a newly activated reserved role; keep compatible defaults selected or recover through a reviewed backup/migration.

Agent Y coordination-path policy compatibility

The ROOT/AUTOBOT coordination guard reserves .SYSTEMX/ROOT/ and .SYSTEMX/AUTOBOT/ for their authorized record owner. New preparation, an existing selected job's run and pr-ready, and returned-diff checks enforce that policy before the relevant side effect.

An earlier valid job can retain its original protected scope for historical inspection. List/show/validate and the existing abandonment, cancellation, and recovery flows remain available under their normal lifecycle gates; historical readability does not authorize execution or readiness. Other path, secret, and containment guards still apply. Preserve the complete job and task evidence. Do not erase history, split the ledger, or silently rewrite old allowed paths to make an action pass. Review the intended coordination change with Agent 0 or its authorized owner, then choose the next bounded action explicitly. See Agent Y and Security and support.

Removed application-specific reference bundles

Fresh generic releases omit application-specific integration packages and their SDK/domain fixtures. Ordinary additive updates still preserve existing local files, including an older copied reference bundle. Their presence after an update does not make them a current SYSTEMX feature.

If your adopted project used such content, review its ownership and references, then move maintained integration code/docs to the host project under its own versioning. Retain recoverable evidence and update Global/MAP pointers. Removal from the published template does not authorize deleting local user files or rewriting historical release evidence. Use ordinary validation for adopted records; strict --template inventory validation is for the pristine current distribution.