Adoption installs two small repository-local launchers: code-polishyw for
POSIX shells and code-polishyw.ps1 for PowerShell. They contain bootstrap and
dispatch logic, not a Code Polishy release or its toolchain. The wrapper reads
the repository lock and delegates ordinary commands to the exact release in
the shared per-user installation prefix.
setup is the only wrapper action allowed to acquire anything. A v2
lock contains one HTTPS archive URL, checksum, and size for every supported
host. Those values are derived from an exact checksum-pinned publication index
by initial adoption or the upgrade planner. The wrapper selects the current host, downloads the
archive, verifies its checksum, and uses the archive's own engine to perform the
bounded bundle installation. It does not clone Code Polishy, install a language
toolchain, or build a release.
Wrapper setup --source PATH is an explicit recovery path for a local Code
Polishy checkout. The source installer still proves that the built release
satisfies the target v2 lock. It cannot create or replace repository authority,
and the wrapper never silently falls back to source.
The target lock remains the release authority. Source identity checks prevent a mutable branch or lightweight tag from standing in for a release, but the installer must also verify the completed staged release and prove that its version, release digest, host, and capabilities satisfy the target lock. That proof occurs before a release directory, launcher, or publication output is committed. A source checkout cannot silently replace the lock with what it built.
The public release-manifest verify operation checks the current host before
validating the installed tree. Source-install replacement and repair therefore
reject an installation recorded for another host before reusing it.
Normal wrapper dispatch never clones, downloads, builds, changes PATH, or
selects a fallback release. The wrapper checks that the exact release directory
and its release-local launcher are present, then delegates once. That launcher
verifies the installed release before executing the command. Installing an
older release may replace the convenience launcher in the shared bin
directory, but cannot replace the launcher a repository wrapper selects.
Shared storage lets
repositories with the same lock reuse one installation while different locked
releases coexist. A repository-reviewed archive checksum authenticates bytes
relative to that repository's lock; it does not establish builder identity or
replace the separately planned provenance work.
The agent-guidance transaction owns both wrappers alongside the canonical
AGENTS.md prefix and report-artifact ignore rules. Installation creates
missing wrappers; synchronization replaces only files carrying the managed
marker and writes canonical modes when it creates or replaces a wrapper. It
also removes an exact obsolete managed CLAUDE.md stub while preserving custom
files. Freshness compares exact bytes and Git-representable executable status,
so group and other write bits applied by a checkout umask do not create
perpetual drift. An unrelated pre-existing wrapper is a conflict, so the entire
transaction preserves every target. agents check reports missing, stale,
non-regular, or conflicting wrappers.
The root wrapper paths are built-in sensitive control inputs. A byte-identical copy of the locked release's canonical template is a managed control artifact, not application source, so adoption does not distort the target's module model. A modified or conflicting copy loses that classification and remains subject to normal executable-source coverage in addition to the adoption-status finding.
This repository can validate an incoming source build before that release is
published and replaces its own lock. During that interval, the root wrappers
deliberately remain canonical for the outgoing locked release and can differ
from the incoming templates. They retain agents module ownership until the
lock-last upgrade transaction replaces them, so incoming policy validation does
not force an early authority cutover.
The publication index is canonical, bounded, versioned, and checksum-pinned by the adoption or upgrade request. Every descriptor must name one version, source revision, and release digest across the complete supported host set. The planner resolves archive names relative to the HTTPS index URL and copies those exact URLs, checksums, and sizes into the next repository lock. Setup trusts only that reviewed lock and the installed manifest verification; mutable release-page metadata never participates in selection.
Initial adoption can pass the index URL and checksum to lock. That operation
requires the executing installed release to match the index and records the
same v2 publication authority without redownloading an archive. A
publication index and checksum are mandatory; source-only adoption is not a
repository lock mode.
GitHub release publication copies the exact version's changelog section into the release body before archive identities. Missing, empty, or duplicate sections stop publication so removals and migration instructions cannot be lost behind download metadata.
Upgrade is deliberately two phase. upgrade plan accepts a verified publication
index and reuses a matching current-host candidate only after verifying its
manifest identity and complete installed tree. Otherwise it downloads and
installs the candidate without changing repository authority. Connection, TLS,
and response-header setup remain bounded, while an exact-size, digest-checked
archive transfer has no fixed whole-body deadline. The planner authenticates the
capability delta and runs the outgoing and incoming engines against the same
repository. The durable plan identifies added, removed, and changed diagnostics
so a policy bump cannot disguise application cleanup as a simple version edit.
The incoming diagnostic preview authenticates the outgoing installed release against the repository lock before recognizing its exact canonical wrappers as managed control artifacts. Recognition happens before language-module discovery, so an outgoing launcher path does not create incoming application ownership or tool-coverage requirements. The preview changes no repository bytes or authority. Customized wrappers remain executable source with ordinary coverage checks; ordinary checks accept only the current release's canonical templates. Apply repeats the authenticated preview and still performs the normal transactional wrapper replacement at cutover.
The incoming planner verifies an outgoing installation with the launcher's existing historical manifest readers. Each reader preserves that schema's original tool fields and identity calculation; the complete installed tree and outgoing lock must still authenticate before its engine runs. Capability catalogs and retained comparison proofs likewise authenticate version 6 identities, the first schema that bound a catalog. Earlier releases without that evidence report an unavailable capability delta rather than inferred changes. Incoming installation and verification still require the current schema.
An engine cannot interpret future manifest fields. The planner distinguishes a
newer schema from a malformed supported schema without treating future fields
as validated. For a newer schema it authenticates the complete archive against
the publication index, extracts one bounded installer binary, and invokes that
binary's install-bundle command. The incoming installer owns verification of
its schema and complete tree. Its installed manifest must match the index before
planning hands off to that incoming engine. The handoff retains the original
index, checksum, configuration, and installation prefix. Supported-schema
errors still fail without a bootstrap fallback.
Repository roots are made absolute before invoking either diagnostic engine. This also preserves compatibility with historical engines whose report containment checks require absolute roots. The repository lock and outgoing guidance remain authoritative throughout planning. Older clients without this handoff can use the documented authenticated manual bootstrap.
upgrade apply revalidates the outgoing lock, installed candidate, and incoming
diagnostic snapshot. New error diagnostics require an explicit acceptance or a
new plan after cleanup. Apply stages canonical guidance, obsolete-stub cleanup,
both wrappers, ignore rules, and the incoming lock as one rollback-capable
transaction; the lock is renamed last. That rename is the guidance cutover.
Upgrade never edits governed application source.
Upgrade artifacts use the incoming release digest as their stable directory identity rather than hashing rendered lock bytes. Apply accepts an older plan only when its plan and capability-record paths share one bounded digest directory, authenticates that record against the plan, and republishes it under the stable identity before cutover.