Implementation Notes: Immutable and Verifiable Operator-Skill State

Execution Mode

• T1-T7 used scoped implementation workers with parent validation. T8 completed the private/internal and public docs paths. T9 completed parent-owned final acceptance and independent review.

Current Checkpoint

• IP-322 and IP-342 are manually converged onto the current Effect v4 architecture.
• Domain policy lives under apps/cli/src/features/operator-skill; Skills CLI process mechanics live in apps/cli/src/integrations/skills-cli.ts; composition uses application.ts, port.ts, apps/cli/src/platform/feature-application-operations.ts, and apps/cli/src/runtime/config.ts.
• Executable maintenance is separate in apps/cli/src/integrations/cli-maintenance.ts.
• Project context uses .git only. Canonical path containment is owned by the pure canonical-path.ts domain helper.
• This is a manual convergence port. Branch publication and coordinated integration state are parent-owned and were not rerun or asserted in this slice.
• Current evidence: operator, integration, and command suites 133/133; public-output and brand suites 15/15; 148/148 focused total; mutation and migration 66/66; CLI build and typecheck PASS; Effect architecture validators 93/93 with 1,352 expectations; full CLI 626/626 across 56 files; build 526 modules; corrected diff plus untracked lint 48 TypeScript files GREEN.
• Historical RED descriptions below are retained as source-branch history. Current paths and convergence evidence remain authoritative.

T1 Immutable Target

Bounded git log --follow and commit-stat evidence proves 45072f4721d9668177bc4dd006802935ae61e70f is feat: rename cli skill to hi-cli; it renames the skill directory and references from dp-cli to hi-cli. The previously recorded b705dfdfc71b202652f9d67b4b91b0a5394409ce is a later feat: add hi operator skill flow guidance change and is not the identity revision.

Production owns and exports the one deeply frozen target above, including its complete three-file content manifest. Candidate metadata is evidence to validate against that authority, not a source of authority. A resolved result returns the production-owned frozen target and never aliases caller input.

T1 TDD Evidence

• Environment preparation: the first command attempt exited 127 because dependencies were absent (vitest: command not found). bun install --frozen-lockfile restored the existing workspace dependencies without a lockfile change. This setup failure is not counted as behavioral RED.
• Source-branch historical RED: bun run --cwd apps/cli test -- src/features/operator-skill/target.test.ts exited 1 with Cannot find module './target'.
• Incremental REDs proved the pre-GREEN resolver incorrectly accepted moving, incomplete, and non-authoritative targets, selected an incompatible target, and silently chose the first of two compatible targets.
• Review-fix REDs:
  • frozen authority was undefined before production exported it;
  • resolved output was the caller candidate by object identity and changed when the caller mutated it;
  • a source/revision mismatch returned the generic MovingRevision reason;
  • version 9.9.9 at the authoritative source/revision resolved successfully.
• The malformed-version and maximum-exclusive boundary tests passed immediately against existing behavior. They close missing coverage; no false RED was recorded.
• Final GREEN: the focused target suite passed 16/16.
• Type gate: bun run --cwd apps/cli check-types passed.

T1 Behavior Proven

• Exact immutable compatible target selection.
• One exported, deeply frozen production authority; arbitrary candidate claims cannot redefine it.
• Same-input identity repeatability without input mutation.
• Inclusive minimum and exclusive maximum compatibility policy.
• Typed no-compatible-target result, including an empty candidate set.
• Typed ambiguous-compatible-target result with exact candidate indexes.
• Rejection of main, branch-only, missing revision, source/revision mismatch, malformed or arbitrary identity versions, other well-formed identities, and non-authoritative sources.

T2 Installed State

The installed-copy boundary is pure. It accepts already-observed global and project-local inspection results; it does not invoke Skills CLI, read the filesystem, or mutate any skill state. Copies carry exact version, source, revision, compatibility, scope, project root where applicable, and bound agents.

Resolution returns one of four discriminated states:

• Resolved: the effective copy plus every active shadowed copy and every detected incompatible copy.
• Absent: no copy applies to the current directory and active agent after successful inspection; detected non-applicable evidence remains visible.
• DetectionFailed: one or more global/project-local inspections failed; partial detected and incompatible evidence remains visible, but no effective copy is inferred.
• Ambiguous: distinct identities share the highest applicable precedence; candidates are identity-sorted, lower-precedence copies remain shadowed, and no effective copy is invented.

Project-local precedence applies only when the current directory is the project root or its descendant and the copy is bound to the active agent. Otherwise the compatible or incompatible global installed copy remains the effective fallback. Compatibility is reported, not used to hide or rewrite actual installed precedence.

The enclosing project-local inspection is authoritative for its root. Equivalent copy roots normalize to the inspection value. A contradictory copy root produces typed ProjectRootMismatch, excludes the contradictory copy from detected evidence, and prevents effective resolution. Raw JSON fixtures pass through Effect Schema decoding, so invalid discriminants or missing/wrongly typed fields fail rather than being overwritten by test coercion.

T2 TDD Evidence

• Source-branch historical RED: the exact focused command exited 1 because ./installed-state did not exist.
• Incremental REDs observed the global copy incorrectly winning inside the local project, successful empty inspection throwing instead of returning Absent, and a global failure being treated as copy data.
• Review-fix REDs observed input-order selection for reversed distinct global and project-local candidates, silent fallback when a copy root contradicted the enclosing inspection, and malformed fixture scope reaching an undefined decoder.
• Additional matrix assertions passed immediately once the governing precedence behavior existed: global fallback outside the project, active-agent binding, incompatible effective state, partial project-local failure evidence, and shadowed duplicate enumeration.
• Final GREEN: bun run --cwd apps/cli test -- src/features/operator-skill/installed-state.test.ts passed 14/14 and bun run --cwd apps/cli check-types passed.
• Focused Oxfmt and git diff --check passed. Explicit git diff --no-index --check /dev/null <file> checks covered each untracked production, test, and JSON fixture artifact; each emitted no whitespace diagnostic and returned the expected no-index diff exit 1.
• Focused Oxlint could not load the existing configuration because @effect/eslint-plugin cannot resolve @typescript-eslint/utils; no file-level lint result was produced.
• Three autoreview --mode local attempts, including the final review-fix patch, could not start review because installed Codex 0.139.0 rejects configured model gpt-5.6-sol as requiring a newer CLI.

T2 Behavior Proven

• Global-only default resolution.
• Local-over-global precedence inside the matching project and global fallback outside it.
• Active-agent binding across local and global copies.
• Visible incompatible effective copies and active shadowed duplicates.
• Deterministic Ambiguous state for reversed distinct same-scope global and project-local candidates; no arbitrary effective identity.
• Canonical identity ordering for every exposed non-semantic collection, including reversed incompatible candidates, shadowed/detected copies, failures, and bound agents.
• Inspection-authoritative project roots, including normalization of equivalent paths and typed rejection of contradictions.
• Runtime Effect Schema validation of raw JSON fixture discriminants and field shapes.
• Successful empty detection as explicit Absent state.
• Global and project-local detection failures as explicit DetectionFailed state, including partial successful detection evidence.

Convergence Ownership

• No implementation, documentation, or review work remains.
• Branch publication and coordinated integration checks are parent-owned and were not rerun in this documentation slice.
• CLI lint remains environment-blocked before file analysis because the existing @effect/eslint-plugin installation cannot resolve @typescript-eslint/utils; this is a repository environment blocker, not an IP-322 implementation failure.

T3 Skills CLI Port and Integration

SkillsCli is the feature port in apps/cli/src/features/operator-skill/port.ts. The live adapter in apps/cli/src/integrations/skills-cli.ts owns:

• official Skills CLI >=1.5.17 preflight before every operation;
• JSON-only list decoding for project and global scopes;
• explicit cwd, timeout, scope flag, and active-agent arguments;
• immutable source-based add for the T1 target and targeted remove;
• normalized agent bindings from Skills CLI display names;
• typed unavailable, timeout, nonzero-exit, unsupported-version, malformed-output, binding, and verification failures.

Skills CLI JSON is the sole enumeration, path, and scope authority. Only after a successful listing may the live adapter resolve the canonical reported root and the exact files named by the target manifest. Every canonical file path must remain below that canonical root before its content is read. Matching every SHA-256 enriches that observed copy with the frozen source, version, revision, and compatibility. Unsafe, missing, unreadable, malformed-manifest, and identity-mismatch states are typed; a failure after earlier verified entries retains those entries as partial evidence.

The adapter never parses human output, scans a directory, reads a parent/home/project skill path, writes filesystem state, or falls back to filesystem discovery. A listing or version failure therefore cannot become false absence. T4 can replace the live Layer deterministically without importing subprocess or verification mechanics.

T3 TDD and Runtime Evidence

• Source-branch historical RED: the exact focused test command exited 1 because ./skills-cli did not exist.
• Option-B RED: the focused suite exited 1 with 10/14 failures proving absent identity enrichment, version preflight, path/manifest verification, partial evidence, and mutation gates. The next empty-manifest RED exited 1 with 1/16 failures because empty content incorrectly asserted identity. Review RED exited 1 with 2/18 failures because matching files escaped through leaf and intermediate-directory symlinks.
• Final GREEN: bun run --cwd apps/cli test -- src/integrations/skills-cli.test.ts passed 18/18 and bun run --cwd apps/cli check-types passed. The combined target/adapter regression passed 35/35 plus typecheck.
• Runtime fixture: every scoped test creates a unique OS-temp root containing a fake skills executable, PATH entry, trace, project root, exact copied payloads, mismatched/unreadable/missing reported paths, leaf and intermediate-directory symlink escapes, and a valid unreported decoy. The fake process captured the version probe plus exact argv and cwd for both list scopes, both install scopes and agents, and targeted removal in both scopes.
• Failure coverage: old and malformed versions, version/list nonzero exits, malformed JSON, a killed timeout process, a missing executable, binding mismatch, unsafe/missing/unreadable reported paths, malformed/empty manifests, content mismatch, and canonical symlink escape return distinct typed failures. A later mismatch preserves an earlier verified copy. The mismatched reported path never resolves through the valid decoy.
• Cleanup proof: Effect scoped finalization removed every run-owned root. A final temp-root search and process search emitted no matches.
• Closing validation: focused Oxfmt check, git diff --check, explicit no-index whitespace checks for every untracked T3 artifact, CLI typecheck, and CLI build passed. Import guards found subprocess/filesystem production imports only in apps/cli/src/integrations/skills-cli.ts; scan/fallback guards found no directory enumeration or agent-home paths. Temp-root and process searches found no run-owned fixture residue.
• Full bun run --cwd apps/cli check remains environment-blocked before file analysis: existing @effect/eslint-plugin cannot resolve its @typescript-eslint/utils dependency. Focused Oxfmt passed independently.

T4 Lifecycle Status

The Effect lifecycle boundary resolves the T1 compatible target before any inspection and uses only the T3 SkillsCli port for observed state. A successful resolution always requests both global and project scopes. The raw result retains both scope inspections, while the T2 resolver determines effective, shadowed, incompatible, absent, ambiguous, or failed installed state. Project-local evidence therefore never erases the global copy, including when the current directory is outside the project.

Verified hi-cli entries retain source, version, revision, CLI compatibility, scope, project root where applicable, and sorted agent bindings. Legacy dp-cli entries remain a separate deterministic ledger across both scopes. Adapter errors remain their original typed SkillsCliFailure. A verification error also retains its already verified entries as detected copies, but the enclosing installed result stays DetectionFailed; partial evidence cannot become false absence or an invented effective copy.

T4 TDD and Validation Evidence

• Source-branch historical RED: bun run --cwd apps/cli test -- src/features/operator-skill/lifecycle-status.test.ts exited 1 because ./lifecycle did not exist.
• Partial-evidence RED: the focused suite exited 1 with 1/4 failures because the failure inspection returned copies: [] instead of preserving SkillsCliVerificationFailure.verifiedSkills.
• Final GREEN: the exact planned combined command passed target 17/17, installed-state 14/14, live adapter 18/18, and lifecycle 4/4 (53/53 total), then bun run --cwd apps/cli check-types passed.
• Broad regression: bun run --cwd apps/cli test passed all 279/279 CLI tests across 33 files.
• Deterministic test Layers prove repeated status identity, both-scope requests, local-over-global precedence, global fallback outside a project, visible incompatible and legacy copies, typed inspection failure, and partial verified evidence.
• The lifecycle production file imports no subprocess, filesystem, command rendering, scaffold, baseline, or executable-update implementation.
• Focused Oxfmt, focused Oxlint with denied warnings, and git diff --check passed. Structured .agents/skills/autoreview/scripts/autoreview --mode local could not start review because installed Codex 0.139.0 rejects configured model gpt-5.6-sol as requiring a newer Codex version; no model or engine override was used.

T5 Verified Install and Update

T5 classifies mutation as independent external scope writes with an explicit repair ledger. Preflight uses the T4 lifecycle status. Install always ensures global, even when project-local is already effective; an exact active global target returns AlreadyVerified without another external write or reload. Update selects each scope with detected hi-cli evidence. Selected writes run sequentially so each successful-looking adapter call is immediately followed by a complete T4 re-inspection before the next scope starts.

A scope becomes Verified only when post-write evidence matches the complete T4 copy identity: scope/project root, target source, version, revision, compatibility, and the sorted bound-agent set. Distinct same-scope target copies remain competing identities even when both include the active agent. Adapter write errors become typed Failed actions. Successful writes whose re-inspection fails, whose exact target is not observed, or whose target remains ambiguous beside a competing copy become Unverified; they never become success from exit status. Each failed or unverified action retains its operation, scope, frozen target, and a frozen input snapshot as exact retry evidence. Typed verification or binding failure still proves a reported hi-cli exists in that scope, so update selects it for repair even when no copy has yet passed identity verification.

Scopes are deliberately not a transaction. A verified scope remains in the action ledger when a peer fails or is unverified; no rollback is attempted. No automatic retry wraps the external mutation. The typed retry record is the repair path because repeating an external add implicitly is not assumed safe. Any successful write emits structured reload guidance, including mixed outcomes. T5 never calls removal; legacy safety remains T6-owned.

T5 TDD and Validation Evidence

• Source-branch historical RED: bun run --cwd apps/cli test -- src/features/operator-skill/lifecycle-mutation.test.ts -t 'install|update|partial|unverified' exited 1 because ./lifecycle-mutation did not exist.
• Incremental review RED: the focused update repairs case exited 1 with 1/8 failures because a stale hi-cli reported by SkillsCliVerificationFailure became an inspection failure action and received no update write.
• Incremental ambiguity RED: the focused competing active case exited 1 with 1/9 failures because target presence was counted as verified despite a competing active identity in the same scope.
• Incremental idempotency RED: the focused already verified case exited 1 with 1/10 failures because install rewrote an already verified global target and emitted reload guidance.
• Review-repair mutation REDs removed the source, version, revision, compatibility, active-agent, typed binding-failure selection, and scope-selection checks one at a time. Each named focused case exited 1, proving every individual predicate has an independent test sentinel.
• Binding-identity review repair used two vertical tracers. Post-write update RED returned Verified while T4 reported Ambiguous for target copies bound to [codex] and [claude,codex]. Preflight install RED returned AlreadyVerified for the same ambiguous evidence. GREEN exports T4's complete normalized copy-identity serializer and uses one mutation helper for both competing-copy decisions; both paths now remain Ambiguous and Unverified.
• Exact GREEN: bun run --cwd apps/cli test -- src/features/operator-skill/lifecycle-mutation.test.ts && bun run --cwd apps/cli check-types passed 17/17 tests and tsc --noEmit.
• The failure matrix proves local-only install still creates global, global/project update sequencing and project-root attribution, immediate post-write inspection, independent source/version/revision/compatibility/active-agent verification, real typed binding-failure preflight repair selection and post-write preservation, process failure, post-write inspection failure, mixed verified/failed and verified/unverified peers, no rollback, exact retries, and reload guidance after any successful write.
• Source-branch history: the wider operator and CLI regressions passed before the manual convergence port. Current convergence totals are recorded in T9.
• Focused Oxfmt, tracked and untracked whitespace checks, and the T5 dependency/removal import guard passed. Targeted .agents/skills/autoreview/scripts/autoreview --mode local --prompt <binding-identity-scope> --stream-engine-output returned no findings, patch is correct, confidence 0.98; its explanation confirmed that both mutation paths reuse T4's complete identity, including sorted boundAgents. No review finding was accepted or rejected.

T6 Verified Legacy Migration

Migration preflights both global and project scopes before deriving work. Any typed inspection failure refuses the operation before a write because unknown state cannot become absence. Affected scopes come only from observed dp-cli copies bound to the active agent, in deterministic global then project-local order. Project-local evidence is applicable only while cwd is inside the owning project root, using the same exported T4 path predicate as installed-state resolution. Unrelated-agent and outside-project legacy copies neither trigger migration nor invalidate a successful active-agent removal.

Every affected scope must have one exact compatible hi-cli identity before removal: frozen target source, version, revision, compatible status, scope/project root, active binding, and a singular sorted bound-agent identity. Missing, incompatible, unsafe, failed, and binding-distinct ambiguous replacements are installed and re-inspected but remain typed refusal when exact verification does not follow. Successful replacement writes remain installed and require reload even when a peer blocks the barrier. Their immediate ReplacementVerified actions remain chronological ledger facts when final inspection later fails or changes. Final inspection appends phase-distinct BarrierInspectionFailed or BarrierUnverified actions and derives the removal copy map separately, avoiding both lost writes and duplicate success actions.

After individual replacement work, one final complete lifecycle inspection proves all affected replacements simultaneously and preserves each full installed-copy identity as the removal barrier snapshot. Inapplicable project-local failures outside the owning root do not block global work; applicable inspection failure or affected-scope ambiguity/mismatch refuses every removal. Only then does removal proceed independently in global then project order. Every remove attempt immediately triggers another complete lifecycle inspection, including adapter Left, because an external nonzero can still leave partial side effects. One shared barrier guard compares every current, prior, and pending affected scope against its preserved snapshot after both failed and successful attempts. Missing, failed, ambiguous, or identity-changed pending evidence emits LegacyRemovalRefused with BarrierLost, a typed reason, and migrate-only retry; its external remove is skipped. Current or prior invalidation appends a phase-specific RemovalBarrierLost fact without overwriting the chronological LegacyRemovalFailed, LegacyRemovalUnverified, or LegacyRemoved attempt result, then closes the gate for every remaining removal. A successful remove counts as LegacyRemoved only when active-agent legacy is absent, all same-scope unrelated-agent legacy identities remain exact, and the current replacement is byte-for-byte identical at the copy-identity seam. A Left that observably changes active or unrelated legacy appends a separate partial-change fact and emits reload guidance. Successful removals remain changed and no rollback is claimed.

Every failed, unverified, refused, or lost-barrier action carries a frozen operation: "migrate" retry with a frozen phase, affected-scope set, input snapshot, and target. There is no naked-remove retry surface. retryLegacyOperatorSkillMigration(retry, currentInput) preserves the frozen target and affected scopes while revalidating compatibility against the current executable, rejects target drift before mutation, then re-enters preflight and replacement verification for those scopes. It can restore a same-scope replacement even when a partially failed remove also erased both dp-cli and hi-cli; only legacy copies still observed for the active agent remain removal candidates. Ordinary migrateLegacyOperatorSkill(input) stays idempotent when no legacy exists.

T6 TDD and Validation Evidence

• Source-branch historical RED: bun run --cwd apps/cli test -- src/features/operator-skill/lifecycle-migration.test.ts exited 1 because ./lifecycle-migration did not exist.
• Barrier sensitivity RED: deleting the replacement-barrier predicate made the named dual-scope case exit 1 because it received Completed instead of Refused; the predicate was restored before GREEN.
• Review RED: four focused cases failed together before repair. An unrelated-agent legacy copy triggered install/removal, an unrelated residual legacy binding produced LegacyRemovalUnverified, final barrier inspection failure produced Completed, and final binding-distinct ambiguity produced Completed.
• Outside-project RED: global plus project legacy produced both-scope replacement/removal outside the project, and project-only legacy installed then removed. GREEN exports and reuses T4's existing isInsideProject predicate; global migration remains active while project-local migration becomes non-applicable outside the root.
• Structured autoreview RED: after a successful global removal, both missing and uninspectable pending project replacements still reached skills remove; a global replacement whose sorted binding identity changed across removal still became LegacyRemoved. All three focused cases failed before repair. A companion GREEN regression proves current-scope unverified state does not block a peer whose exact snapshot remains valid.
• Final rereview RED: a global remove returning Left partially deleted or binding-changed the pending project replacement, but migration still attempted project removal. Both focused cases failed before repair. GREEN performs immediate full inspection on Left and routes it through the same pending-barrier guard as successful removal. The pre-existing unchanged-peer failure case still removes project legacy.
• Second structured autoreview RED: final inspection failure discarded an immediately verified successful global replacement write, and final ambiguity replaced that ledger entry with a generic replacement-unverified action. Both focused cases failed before repair. GREEN retains ReplacementVerified { wrote: true }, appends BarrierInspectionFailed or BarrierUnverified, and emits no duplicate replacement success when the final barrier passes.
• Final structured autoreview RED: a failed global remove erased its current replacement but produced only LegacyRemovalFailed; a later successful project removal erased the previously verified global replacement but preserved only the earlier LegacyRemoved fact. Both focused cases failed before repair. GREEN reinspects all affected current/prior/pending barrier copies after every attempt, appends phase-specific RemovalBarrierLost, and exposes guarded retry recovery that reinstalls a lost replacement even when the legacy copy disappeared.
• Closing structured autoreview RED: both Left and successful global removals that destroyed the current global replacement still proceeded to project removal; successful removal silently discarded unrelated-agent legacy; a failed removal's observed active-legacy deletion had no partial-change fact or reload; inapplicable project failures blocked global migration outside the root; and retry silently used the newly resolved target instead of its frozen target. Eight focused assertions failed before repair. GREEN closes remaining gates after current/prior barrier loss, preserves unrelated legacy identities, records observed Left changes, filters failures by applicability, and rejects retry target drift.
• Final identity RED: a shared [claude,codex] legacy copy could lose Claude's residual binding and still become LegacyRemoved; peer-scope active or unrelated legacy changes after an earlier attempt were not inspected before their own removal; and Left barrier loss with unchanged legacy omitted reload guidance. Three focused scenarios failed before repair. GREEN snapshots non-active residual bindings from every copy, validates active and residual legacy across all peer scopes after every attempt, refuses changed pending scopes, and counts observed barrier loss as change.
• Final Left accounting RED: pending replacement loss and peer legacy mutation were refused without reload guidance, while a changed current legacy snapshot was compared again after later project success and produced duplicate/misattributed global change. GREEN counts every observed cross-scope mutation as changed and refreshes an inspectable failed scope's legacy baseline after preserving its original facts.
• Live-contract RED: retry absorbed newly observed project legacy outside its frozen global scope, and shared active/non-active legacy relied on residual evidence the live adapter's active-agent-filtered listing cannot provide after mutation. GREEN confines retry to frozen scopes and conservatively refuses observed shared residual bindings before removal.
• Publication RED: a transient project inspection failure blocked a frozen global-only retry, and install-side legacy disappearance still triggered removal from the stale initial snapshot. GREEN filters retry preflight failures to frozen scopes and derives removal candidates from the final barrier's active-legacy snapshot.
• Publication rereview RED: project preflight succeeded during global-only retry, then a project final-barrier failure still refused the frozen global operation. GREEN applies the same frozen-scope filter to final-barrier inspection failures.
• Focused GREEN: lifecycle migration passed 45/45 and bun run --cwd apps/cli check-types passed.
• The matrix additionally covers global-only ordering; inside/outside-project applicability including failure filtering; dual-scope replacement barrier; unsafe, missing, incompatible, ambiguous, and failed replacement refusal; preflight unknown; both partial-removal directions; successful remove with legacy still present; post-remove inspection failure; pending-peer barrier loss after successful and failed remove attempts by absence, inspection failure, and identity mutation; current and prior barrier invalidation with remaining-gate closure; current exact-binding mutation; chronological write/removal preservation with later loss facts; unrelated-agent legacy identity preservation; observed legacy mutation after Left; complete dual-scope success without duplicate actions; ordinary idempotent no-legacy state; guarded recovery after legacy and replacement both disappear; frozen-target drift refusal; binding-distinct competing copies; final simultaneous barrier failure/ambiguity; and reload guidance after every observed change.
• Source-branch history: final mutation/migration and wider CLI regressions passed before the manual convergence port. Current convergence totals are recorded in T9 below.
• Oxfmt wrote and verified the four touched TypeScript files and two T6 evidence files. Focused Oxlint remains environment-blocked before file analysis because existing @effect/eslint-plugin cannot resolve @typescript-eslint/utils; this is the same repository dependency blocker recorded by T2 and T3.

T7 Typed Public Operator Commands

hi operator status|install|update|migrate now composes the feature-owned lifecycle through one live runtime Layer. Status prints the immutable target and every observed copy, then distinguishes effective, shadowed, incompatible, absent, ambiguous, and failed detection state. The runtime normalizes the configured active-agent name and treats the current directory as the project scope when no repository marker exists.

Install and update print every per-scope action. A verified peer remains visible when another scope fails or cannot be verified, the process exits nonzero, and any observed successful write still prints reload guidance. Recovery is executable but guarded: mutation retry tokens freeze operation, scope, cwd, active agent, and target before re-entering post-write inspection; migration retry tokens additionally freeze phase and affected scopes. Invalid/stale tokens and target drift fail without mutation. Inspection failure retries re-enter the operator command rather than converting unknown state into an unconditional install.

The deprecated hi skills rename path prints its exact deprecation hint and delegates to hi operator migrate; it owns no policy. Operator behavior is composed through the feature application/port, platform operations, runtime config, and apps/cli/src/integrations/operator-skill-context.ts. Executable update checks remain separate in apps/cli/src/integrations/cli-maintenance.ts.

T7 Source-Branch Historical RED and Current GREEN Evidence

• Source-branch historical RED: the planned packaged operator command exited 1 because unavailable Skills CLI output printed every copy as not installed instead of detection: failed; the test also proved false absence remained in the old command path.
• Current convergence GREEN: focused operator, integration, and command suites passed 133/133; public-output and brand suites passed 15/15, for 148/148 focused tests. Mutation and migration passed 66/66. CLI build and typecheck passed; the build emitted 526 modules. Effect architecture validators passed 93/93 with 1,352 expectations. Full CLI passed 626/626 across 56 files. The corrected diff plus untracked set passed lint across 48 TypeScript files.
• Final review repair: generic initial global inspection failure blocks install, records a Failed inspection action with a guarded inspection retry, performs zero writes, and leaves reload NotRequired. Typed identity or binding evidence remains sufficient to select repair.
• Final P1 project-scope repair: Skills CLI list/install/remove use the detected project root for project scope, while global scope retains invocation cwd. Nested-monorepo tests cover invocation below the detected root.
• Final P1 retry repair: mutation retries reauthorize the current scope. Generic unknown state performs zero writes with reload NotRequired; absent update returns a typed invalid retry; observed identity/binding update and known global install remain repairable; project install retry is rejected.
• Final P2 binding repair: live Skills CLI preserves dp-cli bound only to an unrelated agent so domain policy can filter it, while active-agent binding failure remains enforced for hi-cli.
• Packaged fixtures cover missing/broken Skills CLI, local-over-global status, verified install, mixed update, absent update, verified migration, unsafe refusal, malformed guarded retries, missing agent context, stream/exit separation, and deprecated delegation.
• Run-owned fake Skills CLI validation proved immutable arguments and post-write inspection for packaged hi and hint, global fallback outside a project, project-local precedence inside it, active-agent binding, mixed verified/failed update, replacement-before-removal migration, and trace cleanup. The owned temp root was removed and no matching process remained.
• Iterative autoreview findings were reproduced and repaired across agent detection, executable recovery, malformed retry boundaries, missing packaged success coverage, absent update semantics, post-write verification, markerless project scope, and stderr capture. The last reviewer emitted heartbeat only and was stopped after the bounded threshold; direct findings-first inspection found no remaining owned T7 issue.

T8 Docs Ingest

• Routed paths: private/internal and public.
• Learning scan outcome: update. Durable knowledge remains in the existing spec, implementation notes, and operator runbook; no duplicate learning page was created.
• Public writer artifacts: fragments.md, beats.md, and shape.md preserve the source facts, accepted reader path, parked internal detail, and chosen two-page structure. The user-directed uninterrupted execution overrode the usual fragment-confirmation pause.
• Flow written: /docs/cli/commands/operator documents status, install, update, migrate, typed outcomes, recovery, reload, and the deprecated delegate.
• Concept written: /docs/cli/product-foundation/operator-skill-state explains immutable authority, effective and shadowed copies, post-write verification, truthful partial success, guarded recovery, typed failures, and lifecycle boundaries.
• Root and private docs now document the immutable 1.0.0 target at revision 45072f4721d9668177bc4dd006802935ae61e70f, compatibility >=2.6.1 <3.0.0, effective/shadowed state, typed failures, verified mutations, partial results, guarded retries, and reload guidance.
• Operator lifecycle remains explicitly separate from scaffold/update follow-through, baseline resolution or publishing, pack selection, executable upgrade, shared-skill source synchronization, and rename redesign. The bare hi guide now directs operators to hi operator; hi skills rename remains documented only as the deprecated compatibility delegate where migration compatibility matters.
• Structured public-doc review found two overstatements: inspection reruns were conflated with guarded write retries, and the planned GREEN still named nonexistent paths plus the destructive wiki wrapper. Both were corrected. Rereview returned no findings, patch is correct, confidence 0.94.

T9 Current Convergence Acceptance

• Focused operator, integration, and command suites passed 133/133.
• Public-output and brand suites passed 15/15.
• Combined focused validation passed 148/148.
• Mutation and migration passed 66/66.
• CLI build and typecheck passed; the build emitted 526 modules.
• Effect architecture validators passed 93/93 with 1,352 expectations.
• Full CLI validation passed 626/626 across 56 files.
• The corrected diff plus untracked set passed lint across 48 TypeScript files.
• Final review proved generic initial global inspection failure blocks install, produces a Failed inspection action with a guarded inspection retry, performs zero writes, and keeps reload NotRequired; typed identity or binding evidence may still repair.
• Project-scoped Skills CLI list/install/remove use detected project root while global scope retains invocation cwd, with nested-monorepo coverage.
• Mutation retries reauthorize current scope: generic unknown is no-write/NotRequired, absent update is typed invalid, observed identity/binding update and known global install remain repairable, and project install retry is rejected.
• Live Skills CLI preserves unrelated-agent-only dp-cli evidence for domain filtering and still enforces active-agent binding failure for hi-cli.
• Current repository placement is apps/cli/src/features/operator-skill, with Skills CLI mechanics in apps/cli/src/integrations/skills-cli.ts and executable maintenance isolated in apps/cli/src/integrations/cli-maintenance.ts.
• Project context is derived from .git only. Canonical path containment is a pure domain helper in canonical-path.ts.
• This documentation records a manual convergence port. Branch publication and coordinated integration state are parent-owned and were not rerun in this slice.