Spec: Immutable and Verifiable Operator-Skill State

User Input

in @linear project https://linear.app/devpunks/project/harness-intelligence-23aceec78aca/issues we have new modules M7 M8 M9 for the refactor and re architecture around effect v4. so now please start a $delivery-phase FOR EACH SINGLE ONE of the EPICS. complete all epics and their inner stories with a delivery phase per epic

DO NOT MISS ON ANY OF THE STORIES

do this in full parallel. dont merge on main the subsequent pr

Context

The independently installed hi-cli operator skill tells agents how to operate Harness Intelligence, but it can change separately from the CLI executable and project baseline. Operators and agents need reproducible evidence of which compatible copy is active, where it came from, which copies it shadows, and whether each requested mutation actually took effect. This epic covers IP-340, IP-341, and IP-342 as one lifecycle contract while keeping operator-skill state separate from project packs and scaffold state.

Story Coverage

• IP-340: resolve an immutable compatible target from the authoritative shared Devpunks skills source and report its version, source, revision, and CLI compatibility.
• IP-341: maintain a global default, honor an intentional project-local override only inside that project, expose the effective and shadowed copies, and treat detection failures truthfully.
• IP-342: verify every mutation, preserve successful independent scopes when another fails, remove legacy copies only after replacement, and return exact recovery guidance.

Non-Goals

• Installing or updating from a moving source branch.
• Treating the operator skill as a project pack, managed scaffold asset, baseline artifact, or executable upgrade.
• Letting a project-local copy suppress creation of the global default.
• Hiding duplicate, shadowed, failed, or unverified state.
• Rolling back successful independent scopes because another scope failed.
• Treating an external command's successful exit as proof of the intended state.
• Inventing the release mechanism, compatibility-range representation, scope-flag syntax, or final implementation names in this spec.

Acceptance Criteria

Reproducible target

• The shared Devpunks skills repository is the authoritative source for hi-cli.
• Explicit CLI compatibility metadata resolves an immutable released version or commit.
• Status reports the installed version, source, revision, and compatibility with the active CLI.
• Resolving and updating the same compatible target produces the same target identity.
• Operator-skill lifecycle remains independent from project packs, scaffold reconciliation, and executable upgrade.

Effective scope

• hi operator install ensures a global default.
• A project-local copy overrides the global copy only within that project; the global copy remains the fallback elsewhere.
• Status identifies the effective copy for the current directory and active agent.
• Status reports every detected shadowed copy rather than hiding it.
• Default update addresses every detected hi-cli scope.
• A detection or listing failure is reported as a typed failure and is never interpreted as absence.

Verified mutation and recovery

• Every apparently successful mutation is followed by inspection of the resulting version, source, revision, and active-agent binding.
• A scope counts as successful only when the intended compatible copy is verified as active for that scope.
• Successful scopes remain changed and are reported when another scope fails.
• Every failed or unverified scope returns a typed failure and an exact retry action.
• A legacy dp-cli copy is removed only after every affected fallback has a verified compatible hi-cli replacement.
• Any successful write produces reload or reactivation guidance, including partial-success cases.
• One feature-owned lifecycle boundary owns inspection, immutable installation, legacy removal, and effective-copy verification policy.
• One external Skills CLI adapter owns external command syntax, JSON parsing, timeouts, agent binding, and subprocess failures.
• Missing or broken external tooling is a typed adapter failure; it never produces false absence or a filesystem fallback.
• Tests can substitute the external adapter deterministically.

Constraints

• IP-340 and IP-341 must both complete before IP-342 can verify mutations against a resolved compatible target and effective scope.
• IP-330 characterization evidence must exist before the owning operator-skill architecture changes.
• Operator-skill state remains separate from .devpunks settings, project context plans, scaffold receipts, baseline state, and executable version state.
• Detection failure cannot be collapsed into an empty installed-state result.
• Every expected external failure remains typed and actionable at the lifecycle boundary.
• Delivery participates in the coordinated Effect v4 cutover on one unmerged and undeployed branch. No per-epic merge to main, moving-source fallback, dual path, or temporary compatibility surface may ship.

Dependency Readiness

• Status: No Stack Required
• Dependency: IP-330
• Evidence: Draft PR #76 and apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/IMPLEMENTATION-NOTES.md record accepted IP-330 characterization evidence and IP-330 is Done.
• Reason: IP-330 readiness is proven on the coordinated delivery PR. IP-340 and IP-341 still precede IP-342 as internal execution order, not PR stack topology.

Branch/Base Intent

• Implement IP-322 on an isolated child branch/worktree derived from team/stefan/refactor-cli-architecture.
• Open the IP-322 pull request with base team/stefan/refactor-cli-architecture, never main.
• Keep the child pull request and coordinated architecture line unmerged and undeployed until the final repository cutover gate authorizes integration.
• Keep IP-340, IP-341, and IP-342 in this single child pull request; their dependency order is task topology, not stacked pull requests.

Review Status

• Spec status: Approved; IP-330 readiness is proven by the accepted IP-319 implementation evidence.
• Content and independent review: Passed against the complete Linear parent/child scope, accepted Q48-Q51 grill decisions, and the create-spec quality bar with no blocking findings.
• Human approval state: complete; delivery is authorized to continue to planning on the coordinated draft PR.
• Open questions: none that affect content trust; exact names and compatibility encoding remain implementation tuning by accepted decision.

Decision Log