Harness Upgrade
Use this Skill for target Harness maintenance. The target boundary is one independent Git Repo root. The canonical target-local Skill remains .evozeus-wrapper/skills/using-evozeus-harness/SKILL.md; its current contract version is v1.1.0.
Required lifecycle
Run every change through this sequence:
- Inspect:resolve the independent Repo root, read
.evozeus-wrapper/wrapper.json, inspect the compact activation marker, and collect historical headings/signatures as read-only discovery candidates.
- Plan:load
contracts/v1/migrations/harness-migration-contract-v1.json; use the trusted-base verifier to validate the stable protocol, both current pointers, every active direct-to-current external profile, and each hash-bound from/to closure. Select exactly one profile only after the target matches its complete immutable authority envelope. Automatic canonical profiles require the whole from closure. The reviewed v0.14 legacy profile additionally requires the frozen source envelope, hash-bound CommonMark adapter and parser lock, one unambiguous three-section AST projection, and an exact full-file complement proof. Emit the protocol, profile, adapter identity, exact from/to state, write/delete/move sets, protected business surfaces, source-release attestation, validation, rollback, and digest. A supervised plan also emits decision=supervised_migration_available, operation_sha256, write_authorization.class=supervised_exact_plan_v1, public release_lineage_records, and the actual path-specific migration_records/current_migration_record.
- Approve:show the complete plan to the user. Automatic migration approves the exact
plan_sha256; supervised legacy migration approves the exact operation_sha256. GitHub ADMIN authority does not approve either digest.
- Apply:recompute the plan inside the same CLI invocation, require
--approve-plan to match the applicable digest, reverify target root, source/tag, both Git indexes, full preimages, inode/mode CAS, verifier profile, adapter assets, and closure, create a receipt-bound snapshot outside the target Repo, stage every postimage, then write only the approved set through the secure mutation batch.
- Verify:check every staged hash/mode and current-closure postimage. For the supervised
SKILL.md transform, also prove the retained business complement byte-for-byte, prove every retired legacy span absent, require exactly one canonical activation block by CommonMark AST, and verify manifest, public release lineage, and profile-bound applied lineage. Run structure only from the trusted-release closure preflight plus its exact notice dependency; never execute target-owned Python during migration verification. Recheck the complete target postcondition after structure returns.
- Rollback:on any apply or verification failure, validate the whole snapshot and receipt before the first restore mutation. Manual rollback requires
--approve.
Commands
python3 scripts/evozeus_wrapper.py harness upgrade-check \
--target /absolute/path/to/skill --json
python3 scripts/evozeus_wrapper.py harness migrate-layout \
--target /absolute/path/to/skill \
--latest-version v0.15.0 \
--dry-run --json
python3 scripts/evozeus_wrapper.py harness migrate-layout \
--target /absolute/path/to/skill \
--latest-version v0.15.0 \
--approve-plan 'sha256:<operation_sha256-or-plan_sha256>' --json
python3 scripts/evozeus_wrapper.py harness rollback-migration \
--target /absolute/path/to/skill \
--snapshot /absolute/path/to/trusted-snapshot \
--approve --json
python3 scripts/evozeus_wrapper.py harness upgrade-all \
--latest-version v0.15.0 --dry-run --json
python3 scripts/evozeus_wrapper.py harness upgrade-all \
--latest-version v0.15.0 --approve \
--approve-plan 'sha256:<exact-batch-plan-digest>' --json
Batch apply requires both --approve and the exact dry-run batch_plan_sha256 through --approve-plan. The approved batch retains each target's exact plan_sha256 and passes that digest into the per-target apply call. If any target is replanned to a different digest, stop the batch before that target write and restore earlier targets from their validated snapshots.
one_time means one explicit CLI invocation. Approval is never saved to a config file, manifest, snapshot preference, or reusable authorization store. A successful apply changes the preimage, so replaying its old digest against that applied state is rejected. If the owner explicitly rolls back and later manually supplies the same digest in a new invocation, that is a new approval event; the contract does not claim global permanent consumption.
Versioned authority profiles
legacy-scattered-to-canonical-v1.0@v1.0.0:manual review, writes=false. Regex, frontmatter, heading, terminal text, path names, and inferred layout remain discovery-only evidence for every protocol version.
legacy-v0.14-three-section-to-canonical-v1.1@v1.0.0:reviewed supervised bridge for the frozen v0.14 source envelope. It is selectable only when the verifier, profile, source/tag, full file/mode envelope, manifest projection, CommonMark AST, adapter proof, and single full-file SKILL.md complement proof all match. It emits supervised_migration_available; only its exact operation_sha256 grants the current invocation one write transaction.
canonical-v1.0-to-v1.1@v1.0.0:the first concrete automatic profile. Planning is available only after the trusted-base verifier resolves its immutable v1.0/v1.1 closures and the target matches the complete v1.0 closure, stable block identity, profile identity, and adapter digest.
prerelease-ambiguous-to-manual-review@v1.0.0:a v1.1 Harness without the exact migration contract and managed-block receipts remains manual, writes=false.
unknown-to-manual-review@v1.0.0:manual review, writes=false.
The runtime does not select a profile by a hard-coded profile id. Each new Harness release adds one immutable current closure and a direct-to-current profile from every still-supported immutable historical closure. history/current.json selects the current closure; profiles/current.json selects the complete active upgrade star. Historical closures and profile files become append-only when their release is published. During unreleased v0.15 development, the v1.1 closure and its profiles may be completed in place; after v0.15 is released, any authority or postimage change requires a new closure/profile version and pointer rotation. The current supervised v1 schema/verifier authorizes only the exact v0.14→v1.1 envelope. v1.2 supervised support first requires a protected source rotation that publishes new schema/verifier/consumer authority; a later data-only PR can then add the new closure/profile/artifacts. Candidate data alone cannot widen v1 authority.
release_lineage_records identifies deterministic release history shared by every target at the same current closure. v1.1 fresh attach, automatic, and supervised paths all materialize harness-skill-v1.0.0-to-v1.1.0.md. migration_records/current_migration_record identifies the actual arrival path: the reviewed v0.14 profile alone creates reviewed-legacy-v0.14.0-to-harness-skill-v1.1.0.md, bound to the exact profile, envelope, wrapper/Harness/instruction transitions, retained complement, and rollback policy. Fresh attach never creates this applied record, and automatic profiles never reference it. The runtime fails closed when these fields overlap, drift, or disagree with verified operations.
Destructive authority comes exclusively from the verified external official profile and its exact evidence chain. Automatic profiles use their immutable closure diff and complete from-closure match. The reviewed legacy profile uses its frozen envelope plus the hash-bound CommonMark adapter proof and exact retained-byte complement; frontmatter and regex remain non-authoritative evidence. A missing field, Setext/ATX/HTML duplicate, mixed newline surface, present must-be-absent path, changed exact byte/mode/inode, target-root or Git-index drift, untrusted source, ambiguous profile match, or unapproved applicable digest blocks all writes.
Source and snapshot trust
- Release identity comes from the fixed
MetaInFLow/EvoZeus-CoEvolve GitHub API tag attestation. The local tag ref object, peeled commit, and clean HEAD must match that attestation; configured Git remotes and origin names supply diagnostics only and grant no trust.
- The tagged contract manifest must bind the contract digest. Every source file used as a postimage must equal both its declared digest and its bytes in that tag.
- Changes to the trusted verifier, migration consumers, protocol, schemas, or repository governance always use two PRs: land the protected source rotation first, then open a data-only migration PR against that reachable Commit. This split applies under every merge strategy. The official PR check classifies the full diff from trusted base code; ordinary PRs return
not_applicable, protected-source PRs return rotation_required without executing candidate code, and data-only migration PRs enter exact candidate verification.
- The trusted protocol declares the complete construction-source allowlist. Candidate closures may bind
templates/target/ or the individually reviewed source scripts named by that protocol. Repository workflow/governance files, ordinary docs, unknown scripts, and every undeclared source path are rejected even when a candidate closure attempts to bind them.
- Every immutable closure
construction_revision must remain an ancestor of the final stacked landing and Release Commit. The verifier checks every historical closure against repository history plus frozen construction-source bytes and modes. Squash, rebase, an unmerged side object, or a stacked landing that drops ancestry blocks main/UAT CI and Release. A merge Commit or a source-first Commit followed by a data-only Commit preserves the required ancestry.
- The official PR workflow runs for every PR, but current verified external state has no
main ruleset/branch protection, required environment, or immutable-release gate. Treat v0.15 official release as an apply prerequisite and verified external governance as a publish prerequisite; do not claim the workflow is already an enforced merge gate.
- An unreleased branch may inspect and plan. Its apply status remains
source_unreleased, writes=false.
- The snapshot base must stay outside the target Repo. Reject symlinks in the base, transaction directory, descriptor, files tree, and backup paths.
- Rollback accepts only a direct child of the trusted snapshot root with the expected schema, transaction identity, plan digest, descriptor digest receipt, backup-set digest, complete metadata, and valid backup hashes.
Protected target surfaces
- The compact activation block uses the stable
evozeus-harness-entry marker and manifest-bound relative link.
- Fresh attach may add the block only when the surface has zero canonical markers and zero historical candidates.
- Historical candidates alone never authorize deletion, relocation, or replacement. Route unmatched candidates to a reviewed adapter/profile backlog.
- Automatic canonical profiles do not write the instruction surface. The reviewed v0.14 supervised profile may replace
SKILL.md only as one full-file postimage whose deleted legacy spans and retained business-byte complement are both proven by the bound CommonMark adapter. No other protected surface becomes writable.
- Pre-existing unknown files at managed destinations are preserved and block bootstrap/repair, including
--force, unless an exact trusted preimage or manifest receipt proves ownership.
Stop conditions
Stop with writes=false when any condition below holds:
.evozeus-wrapper/wrapper.json is missing, ambiguous, incomplete, or conflicts with a legacy manifest.
- The plan lacks one verified automatic or supervised profile, or any independent protocol/profile/adapter identity.
- The source release, remote tag commit, contract, adapter, full from closure, or postimage cannot be verified exactly.
- The target Git status is unavailable or dirty.
- A write path escapes the target, traverses a symlink, has an unsafe parent type, or changed after planning.
--approve-plan is absent or differs from the current operation_sha256 for supervised legacy migration, or from plan_sha256 for automatic migration.
- Snapshot creation or complete pre-rollback validation fails.
Read-only diagnosis can continue after a stop. Any repair requires a new versioned profile or an explicitly reviewed manual procedure.
1---2name: evozeus-wrapper-harness-upgrade3description: Use when inspecting, planning, approving, applying, verifying, or rolling back the versioned Harness Skill migration of an independent target Repo.4metadata:5 source: https://skillmd.com/skills/metainflow/evozeus-wrapper-harness-upgrade6---78# Harness Upgrade910Use this Skill for target Harness maintenance. The target boundary is one independent Git Repo root. The canonical target-local Skill remains `.evozeus-wrapper/skills/using-evozeus-harness/SKILL.md`; its current contract version is `v1.1.0`.1112## Required lifecycle1314Run every change through this sequence:15161. **Inspect**:resolve the independent Repo root, read `.evozeus-wrapper/wrapper.json`, inspect the compact activation marker, and collect historical headings/signatures as read-only discovery candidates.172. **Plan**:load `contracts/v1/migrations/harness-migration-contract-v1.json`; use the trusted-base verifier to validate the stable protocol, both current pointers, every active direct-to-current external profile, and each hash-bound from/to closure. Select exactly one profile only after the target matches its complete immutable authority envelope. Automatic canonical profiles require the whole from closure. The reviewed v0.14 legacy profile additionally requires the frozen source envelope, hash-bound CommonMark adapter and parser lock, one unambiguous three-section AST projection, and an exact full-file complement proof. Emit the protocol, profile, adapter identity, exact from/to state, write/delete/move sets, protected business surfaces, source-release attestation, validation, rollback, and digest. A supervised plan also emits `decision=supervised_migration_available`, `operation_sha256`, `write_authorization.class=supervised_exact_plan_v1`, public `release_lineage_records`, and the actual path-specific `migration_records/current_migration_record`.183. **Approve**:show the complete plan to the user. Automatic migration approves the exact `plan_sha256`; supervised legacy migration approves the exact `operation_sha256`. GitHub `ADMIN` authority does not approve either digest.194. **Apply**:recompute the plan inside the same CLI invocation, require `--approve-plan` to match the applicable digest, reverify target root, source/tag, both Git indexes, full preimages, inode/mode CAS, verifier profile, adapter assets, and closure, create a receipt-bound snapshot outside the target Repo, stage every postimage, then write only the approved set through the secure mutation batch.205. **Verify**:check every staged hash/mode and current-closure postimage. For the supervised `SKILL.md` transform, also prove the retained business complement byte-for-byte, prove every retired legacy span absent, require exactly one canonical activation block by CommonMark AST, and verify manifest, public release lineage, and profile-bound applied lineage. Run structure only from the trusted-release closure preflight plus its exact notice dependency; never execute target-owned Python during migration verification. Recheck the complete target postcondition after structure returns.216. **Rollback**:on any apply or verification failure, validate the whole snapshot and receipt before the first restore mutation. Manual rollback requires `--approve`.2223## Commands2425```bash26python3 scripts/evozeus_wrapper.py harness upgrade-check \27 --target /absolute/path/to/skill --json2829python3 scripts/evozeus_wrapper.py harness migrate-layout \30 --target /absolute/path/to/skill \31 --latest-version v0.15.0 \32 --dry-run --json3334python3 scripts/evozeus_wrapper.py harness migrate-layout \35 --target /absolute/path/to/skill \36 --latest-version v0.15.0 \37 --approve-plan 'sha256:<operation_sha256-or-plan_sha256>' --json3839python3 scripts/evozeus_wrapper.py harness rollback-migration \40 --target /absolute/path/to/skill \41 --snapshot /absolute/path/to/trusted-snapshot \42 --approve --json4344python3 scripts/evozeus_wrapper.py harness upgrade-all \45 --latest-version v0.15.0 --dry-run --json4647python3 scripts/evozeus_wrapper.py harness upgrade-all \48 --latest-version v0.15.0 --approve \49 --approve-plan 'sha256:<exact-batch-plan-digest>' --json50```5152Batch apply requires both `--approve` and the exact dry-run `batch_plan_sha256` through `--approve-plan`. The approved batch retains each target's exact `plan_sha256` and passes that digest into the per-target apply call. If any target is replanned to a different digest, stop the batch before that target write and restore earlier targets from their validated snapshots.5354`one_time` means one explicit CLI invocation. Approval is never saved to a config file, manifest, snapshot preference, or reusable authorization store. A successful apply changes the preimage, so replaying its old digest against that applied state is rejected. If the owner explicitly rolls back and later manually supplies the same digest in a new invocation, that is a new approval event; the contract does not claim global permanent consumption.5556## Versioned authority profiles5758- `legacy-scattered-to-canonical-v1.0@v1.0.0`:manual review, `writes=false`. Regex, frontmatter, heading, terminal text, path names, and inferred layout remain discovery-only evidence for every protocol version.59- `legacy-v0.14-three-section-to-canonical-v1.1@v1.0.0`:reviewed supervised bridge for the frozen v0.14 source envelope. It is selectable only when the verifier, profile, source/tag, full file/mode envelope, manifest projection, CommonMark AST, adapter proof, and single full-file `SKILL.md` complement proof all match. It emits `supervised_migration_available`; only its exact `operation_sha256` grants the current invocation one write transaction.60- `canonical-v1.0-to-v1.1@v1.0.0`:the first concrete automatic profile. Planning is available only after the trusted-base verifier resolves its immutable v1.0/v1.1 closures and the target matches the complete v1.0 closure, stable block identity, profile identity, and adapter digest.61- `prerelease-ambiguous-to-manual-review@v1.0.0`:a v1.1 Harness without the exact migration contract and managed-block receipts remains manual, `writes=false`.62- `unknown-to-manual-review@v1.0.0`:manual review, `writes=false`.6364The runtime does not select a profile by a hard-coded profile id. Each new Harness release adds one immutable current closure and a direct-to-current profile from every still-supported immutable historical closure. `history/current.json` selects the current closure; `profiles/current.json` selects the complete active upgrade star. Historical closures and profile files become append-only when their release is published. During unreleased v0.15 development, the v1.1 closure and its profiles may be completed in place; after v0.15 is released, any authority or postimage change requires a new closure/profile version and pointer rotation. The current supervised v1 schema/verifier authorizes only the exact v0.14→v1.1 envelope. v1.2 supervised support first requires a protected source rotation that publishes new schema/verifier/consumer authority; a later data-only PR can then add the new closure/profile/artifacts. Candidate data alone cannot widen v1 authority.6566`release_lineage_records` identifies deterministic release history shared by every target at the same current closure. v1.1 fresh attach, automatic, and supervised paths all materialize `harness-skill-v1.0.0-to-v1.1.0.md`. `migration_records/current_migration_record` identifies the actual arrival path: the reviewed v0.14 profile alone creates `reviewed-legacy-v0.14.0-to-harness-skill-v1.1.0.md`, bound to the exact profile, envelope, wrapper/Harness/instruction transitions, retained complement, and rollback policy. Fresh attach never creates this applied record, and automatic profiles never reference it. The runtime fails closed when these fields overlap, drift, or disagree with verified operations.6768Destructive authority comes exclusively from the verified external official profile and its exact evidence chain. Automatic profiles use their immutable closure diff and complete from-closure match. The reviewed legacy profile uses its frozen envelope plus the hash-bound CommonMark adapter proof and exact retained-byte complement; frontmatter and regex remain non-authoritative evidence. A missing field, Setext/ATX/HTML duplicate, mixed newline surface, present must-be-absent path, changed exact byte/mode/inode, target-root or Git-index drift, untrusted source, ambiguous profile match, or unapproved applicable digest blocks all writes.6970## Source and snapshot trust7172- Release identity comes from the fixed `MetaInFLow/EvoZeus-CoEvolve` GitHub API tag attestation. The local tag ref object, peeled commit, and clean `HEAD` must match that attestation; configured Git remotes and `origin` names supply diagnostics only and grant no trust.73- The tagged contract manifest must bind the contract digest. Every source file used as a postimage must equal both its declared digest and its bytes in that tag.74- Changes to the trusted verifier, migration consumers, protocol, schemas, or repository governance always use two PRs: land the protected source rotation first, then open a data-only migration PR against that reachable Commit. This split applies under every merge strategy. The official PR check classifies the full diff from trusted base code; ordinary PRs return `not_applicable`, protected-source PRs return `rotation_required` without executing candidate code, and data-only migration PRs enter exact candidate verification.75- The trusted protocol declares the complete construction-source allowlist. Candidate closures may bind `templates/target/` or the individually reviewed source scripts named by that protocol. Repository workflow/governance files, ordinary docs, unknown scripts, and every undeclared source path are rejected even when a candidate closure attempts to bind them.76- Every immutable closure `construction_revision` must remain an ancestor of the final stacked landing and Release Commit. The verifier checks every historical closure against repository history plus frozen construction-source bytes and modes. Squash, rebase, an unmerged side object, or a stacked landing that drops ancestry blocks main/UAT CI and Release. A merge Commit or a source-first Commit followed by a data-only Commit preserves the required ancestry.77- The official PR workflow runs for every PR, but current verified external state has no `main` ruleset/branch protection, required environment, or immutable-release gate. Treat v0.15 official release as an apply prerequisite and verified external governance as a publish prerequisite; do not claim the workflow is already an enforced merge gate.78- An unreleased branch may inspect and plan. Its apply status remains `source_unreleased`, `writes=false`.79- The snapshot base must stay outside the target Repo. Reject symlinks in the base, transaction directory, descriptor, files tree, and backup paths.80- Rollback accepts only a direct child of the trusted snapshot root with the expected schema, transaction identity, plan digest, descriptor digest receipt, backup-set digest, complete metadata, and valid backup hashes.8182## Protected target surfaces8384- The compact activation block uses the stable `evozeus-harness-entry` marker and manifest-bound relative link.85- Fresh attach may add the block only when the surface has zero canonical markers and zero historical candidates.86- Historical candidates alone never authorize deletion, relocation, or replacement. Route unmatched candidates to a reviewed adapter/profile backlog.87- Automatic canonical profiles do not write the instruction surface. The reviewed v0.14 supervised profile may replace `SKILL.md` only as one full-file postimage whose deleted legacy spans and retained business-byte complement are both proven by the bound CommonMark adapter. No other protected surface becomes writable.88- Pre-existing unknown files at managed destinations are preserved and block bootstrap/repair, including `--force`, unless an exact trusted preimage or manifest receipt proves ownership.8990## Stop conditions9192Stop with `writes=false` when any condition below holds:9394- `.evozeus-wrapper/wrapper.json` is missing, ambiguous, incomplete, or conflicts with a legacy manifest.95- The plan lacks one verified automatic or supervised profile, or any independent protocol/profile/adapter identity.96- The source release, remote tag commit, contract, adapter, full from closure, or postimage cannot be verified exactly.97- The target Git status is unavailable or dirty.98- A write path escapes the target, traverses a symlink, has an unsafe parent type, or changed after planning.99- `--approve-plan` is absent or differs from the current `operation_sha256` for supervised legacy migration, or from `plan_sha256` for automatic migration.100- Snapshot creation or complete pre-rollback validation fails.101102Read-only diagnosis can continue after a stop. Any repair requires a new versioned profile or an explicitly reviewed manual procedure.