Operator-Skill State

The hi-cli operator skill supplies instructions to the active Harness agent. It can change independently from the CLI executable and project scaffold, so its identity, location, and mutation results need their own evidence.

Immutable Authority

The lifecycle recognizes one compatible target: hi-cli version 2.0.0 at revision dbfd199e89ab17f6241270ab1f23ea50c294926f, compatible with CLI versions >=4.0.0 <5.0.0. Resolution requires the exact source, revision, version, compatibility range, and content manifest. Moving branches and caller-supplied identity claims cannot redefine that authority.

Effective and Shadowed Copies

Skills CLI aggregates provider agent bindings for a scope and skill into one canonical returned path. The lifecycle uses that path to inspect the global and current-project records:

inside the matching project: project-local            -> effective, verified or outdated
                             compatible global        -> shadowed fallback

outside that project:        compatible global        -> effective fallback

Shadowed, incompatible, and non-applicable evidence stays visible. A canonical listed copy whose content identity differs from the immutable target remains visible as outdated, unverified inventory. Normal precedence still applies, so an outdated project-local copy shadows a verified global fallback and status recommends hi operator update. Distinct equally applicable identities produce an ambiguous result. Unsafe paths, list failures, and missing, unreadable, or malformed evidence produce a typed detection failure and preserve any partial observed evidence; unknown state is never reported as absence or outdated inventory.

Verification After Every Write

Install, update, and migration replace outdated inventory and treat an external command exit as provisional. The lifecycle reinspects immediately, uses Skills CLI's returned canonical path to byte-verify content, then records source, version, revision, compatibility, aggregated provider agents, scope, and project root. The path is not retained as copy identity, so same-content path changes are accepted after re-verification. This evidence proves one canonical copy per scope and skill; Skills CLI owns correctness of the underlying target fan-out. A persistent post-write mismatch remains unverified and causes the command to exit nonzero.

Each scope has its own action outcome. A verified action remains truthful when a peer scope fails or cannot be verified. The combined command reports every verified, failed, unverified, or refused action and exits nonzero when the requested operation is incomplete. It does not claim rollback of successful work.

Migration adds a removal barrier for each affected legacy scope. The canonical replacement's provider-reported agents must cover every provider-reported agent binding on the legacy dp-cli records before Harness delegates an unscoped removal to Skills CLI. Missing coverage or a persistent, changed, missing, ambiguous, or uninspectable replacement closes the barrier, preserves dp-cli, and refuses unsafe removal. Skills CLI owns the removal fan-out.

Recovery and Reload

Failed or unverified writes carry a guarded retry with the frozen target and operation context. Retrying re-enters lifecycle inspection and verification, so stale or changed evidence cannot silently authorize a write or legacy removal.

Inspection failure uses a direct command rerun without a guarded write token. The rerun evaluates the complete current lifecycle and can reconsider every scope now detected. It does not convert the earlier unknown state into permission to write.

Harness does not resolve an active agent for a normal or recovery command. It invokes Skills CLI without --agent, and Skills CLI owns harness detection and target selection. HI_OPERATOR_AGENT is not part of this lifecycle.

Any observed successful write produces reload guidance, including mixed outcomes. Reload or reactivate $hi-cli before relying on changed operator instructions.

Lifecycle Boundaries

Operator-skill state does not reconcile .devpunks scaffold output, select packs, resolve or publish baselines, update the CLI executable, or synchronize the shared skill source. Those jobs remain with scaffold/update commands, pack configuration, baseline tooling, hi upgrade, and the shared-skill source workflow.

Use hi operator to inspect or mutate the operator skill through this verified lifecycle.