@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/extensions/enact-operator/skills/deep-interview/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: deep-interview
+description: "Intent-first clarification loop for vague, risky, or product-heavy work before planning or execution."
+---
+
+# Deep Interview
+
+## Purpose
+
+Use `$deep-interview` to turn a fuzzy request into an execution-ready spec. This is not generic brainstorming. It is a focused clarification loop that removes ambiguity before planning or coding.
+
+## Use When
+
+- the request describes outcomes, not behavior
+- the user is still discovering what they want
+- scope, non-goals, or decision boundaries are unclear
+- a wrong assumption would create expensive rework
+
+## Do Not Use When
+
+- the request already names files, symbols, and acceptance criteria
+- the user explicitly wants immediate execution and the risk is low
+- the only missing work is architectural decomposition, not intent clarity
+
+## Execution Policy
+
+- ask one question at a time
+- ask only the highest-leverage unresolved question
+- use repo facts before asking about codebase internals
+- force clarity on non-goals and decision boundaries before handoff
+- keep the interview moving toward a durable artifact, not an endless conversation
+
+## Question Order
+
+1. Why does this need to exist?
+2. What should be true when it is done?
+3. How far should it go?
+4. What should explicitly stay out?
+5. What may Enact Operator decide without checking again?
+6. What constraints or preferences are hard?
+
+## Workflow
+
+1. Read current `.enact/operator/` artifacts and inspect the repo if this is brownfield work.
+2. Capture the current hypothesis in `.enact/operator/plans/<phase>-requirements.md`.
+3. Run a one-question loop until these are explicit:
+   - goal
+   - in-scope
+   - out-of-scope
+   - acceptance criteria
+   - decision boundaries
+4. Refresh the session/state record when the interview starts or resumes:
+   - MCP: `operator_session_start`
+   - CLI fallback: `enact-operator session start`
+5. Update:
+   - `.enact/operator/plans/<phase>-requirements.md`
+   - `.enact/operator/research/summary.md`
+   - `.enact/operator/state/planning-state.json`
+6. Hand off to `$plan` when the spec is concrete.
+
+## Output Standard
+
+The finished interview should leave behind:
+
+- clear goal
+- explicit non-goals
+- decision boundaries
+- testable acceptance criteria
+- constraints that downstream execution must honor
+
+## Stop Conditions
+
+Do not hand off while either of these is missing:
+
+- non-goals
+- decision boundaries
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.

package/extensions/enact-operator/skills/doctor/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: doctor
+description: "Health-check mode for Enact Operator install, repo state, plugin wiring, hook status, and runtime degradation."
+---
+
+# Doctor
+
+## Purpose
+
+Use `$doctor` when setup, runtime behavior, hooks, or the source plugin bundle feels wrong. This skill is for diagnosis plus the shortest correct remediation path.
+
+## Workflow
+
+1. Run the primary health surface:
+   - MCP: `operator_doctor`
+   - CLI fallback: `enact-operator doctor`
+2. If the problem is plugin-source-related, inspect:
+   - MCP: `operator_plugin_list` / `operator_plugin_validate`
+   - CLI fallback: `enact-operator plugins validate`
+3. If the problem is hook-related, inspect:
+   - MCP: `operator_hooks_status`
+   - CLI fallback: `enact-operator hooks status`
+4. If the problem is session or team-runtime-related, inspect:
+   - `operator_session_status`
+   - `operator_team_status`
+   - `operator_hud`
+5. Turn findings into concrete fixes, not generic advice.
+
+## What to Check
+
+- Node and Codex availability
+- MCP server configured in `~/.codex/config.toml`
+- `.enact/operator/` initialized in the current repo
+- tmux availability vs degraded mock mode
+- source plugin bundle validity; host install and marketplace drift are owned by enact-extensions
+- hook installation state vs feature availability
+- session, inbox, review, and task drift
+
+## Output Standard
+
+- what is healthy
+- what is degraded
+- what is broken
+- the exact command or file change to fix each issue
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.

package/extensions/enact-operator/skills/hud/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: hud
+description: "Runtime-truth mode for reading tasks, sessions, reviews, inbox, and team state before acting."
+---
+
+# HUD
+
+## Purpose
+
+Use `$hud` before trusting your memory of what the runtime is doing. The HUD is the fastest way to catch task drift, stale executor state, or fake progress.
+
+## Primary Surfaces
+
+- MCP: `operator_hud`
+- CLI fallback: `enact-operator hud`
+
+## Read It For
+
+- current session and branch
+- active modes
+- queued vs active vs review tasks
+- inbox and review pressure
+- team backend state and stale executors
+- install-registry drift
+- doctor warnings that change operator decisions
+- if `operator_*` tools are not visible yet, load/search the Enact Operator MCP namespace before reading runtime state
+
+## Workflow
+
+1. Read the HUD.
+2. If anything looks wrong, drill down with:
+   - `operator_session_status`
+   - `operator_task_list`
+   - `operator_reviews_list`
+   - `operator_inbox_list`
+   - `operator_team_status`
+   - `operator_ledger_recent`
+3. Compare it against the actual `.enact/operator/` artifacts if needed.
+4. Fix state drift before continuing execution.
+
+## Rules
+
+- if the HUD says a mode is active, there must be durable evidence
+- if the HUD says the team is healthy but inbox or reviews are piling up, the runtime is not healthy
+- prefer MCP state tools when another agent needs machine-readable output
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.

package/extensions/enact-operator/skills/hyperplan/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: hyperplan
+description: "Three-round adversarial planning debate that hands a distilled bundle to $plan instead of writing the final plan directly."
+---
+
+# Hyperplan
+
+## Purpose
+
+Use `$hyperplan` when a plan needs adversarial pressure before execution starts.
+
+## Debate Team
+
+Use exactly this 4-agent team:
+
+- `critic`
+- `critic`
+- `architect`
+- `explore`
+
+The original openagent placeholder names are not used here.
+
+## Rounds
+
+Run exactly 3 rounds:
+
+1. independent analysis
+2. cross-attack
+3. defend, refine, or concede
+
+Persist each round under:
+
+- `.enact/operator/hyperplan/<sessionId>/round-1.md`
+- `.enact/operator/hyperplan/<sessionId>/round-2.md`
+- `.enact/operator/hyperplan/<sessionId>/round-3.md`
+
+## Handoff Rule
+
+The lead agent does not write the final implementation plan directly.
+After round 3, hand the distilled debate bundle to a separate `$plan` invocation.
+
+## Execution Notes
+
+- use `explore` to gather the evidence bundle before critique
+- use the two `critic` agents to take opposing positions in the cross-attack round
+- use `architect` to synthesize the final structured verdict and tradeoffs
+- do not skip a round because the first opinion looked sufficient

package/extensions/enact-operator/skills/plan/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: plan
+description: "Execution-plan mode that turns intent into small, verifiable slices backed by durable .enact/operator artifacts."
+---
+
+# Plan
+
+## Purpose
+
+Use `$plan` to create execution-ready slices. The output is not a strategy memo. It is the prompt-quality plan that downstream execution can follow without improvising core behavior.
+
+## Use When
+
+- the work is bigger than a one-shot edit
+- the request is clear enough to plan but not yet safe to execute
+- verification, dependencies, or sequencing need to be locked in
+
+## Do Not Use When
+
+- the task is still ambiguous enough for `$deep-interview`
+- the change is a trivial single-file fix
+- the user explicitly wants direct execution and the risk is low
+
+## Execution Policy
+
+- gather repo facts before asking about internals
+- plans are prompts for execution, not prose for humans only
+- every slice must fit in one focused context window
+- every slice must have explicit verification
+- prefer a small number of high-quality slices over a long TODO dump
+
+## Plan Anatomy
+
+Each slice should answer:
+
+- what files are likely to change
+- what the slice must do
+- how to verify it
+- what counts as done
+- what it depends on
+
+## Workflow
+
+1. Read current intent artifacts:
+   - `.enact/operator/plans/*-requirements.md`
+   - `.enact/operator/plans/brownfield-map.md`
+   - `.enact/operator/research/summary.md`
+2. Derive the must-haves from the goal backward:
+   - what must be true when this is done?
+   - what artifacts and connections are required for those truths?
+3. Split the work into waves and slices:
+   - interface or contracts first
+   - implementation second
+   - verification and wiring last
+4. Write or refine:
+   - active phase plan
+   - verification map
+   - any required task queue items
+5. If Ultrawork is active, link the plan id into session state:
+   - MCP: `operator_ultrawork_link_plan`
+   - CLI fallback: `enact-operator ultrawork link-plan <planId>`
+
+## Quality Bar
+
+- no vague acceptance criteria
+- no "make it work" tasks
+- no giant slice that hides three subsystems
+- no verify step that depends on hope
+
+## Deliverables
+
+- `.enact/operator/plans/<phase>.md`
+- `.enact/operator/plans/<phase>-verification.md`
+- updated brownfield map or research summary when needed
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.

package/extensions/enact-operator/skills/ralph/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: ralph
+description: "Self-referential execution loop with mandatory verification gates. Use when the user wants work completed end-to-end with fresh evidence before stopping."
+lane: true
+mcpToolPrefix: operator_ralph_
+---
+
+# Ralph
+
+## Purpose
+
+`$ralph` is the persistence wrapper for Operator work. It runs a goal forward through implementation, records gate verifications, and refuses to exit until all mandatory gates pass. It is the right mode when partial completion is unacceptable and fresh evidence is required before closeout.
+
+## Use When
+
+- the user wants work shipped without a premature stop
+- verification must be recorded, not assumed
+- multiple audit gates (doctor, provider-boundary, replacement-readiness, tests) must all pass before done
+- a previous attempt left work in an incomplete or unverified state
+
+## Execution Policy
+
+- start from the repo and `.enact/operator/` truth, not chat memory
+- if `operator_*` tools are not visible yet, load/search the Enact Operator MCP namespace before doing ralph lifecycle actions
+- drive ralph through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- keep ralph, task, inbox, and review state current as you go
+- when no external `taskId` is linked, local Operator task discipline is mandatory; Ralph owns a local task and must keep it authoritative
+- do not stop until every mandatory gate is recorded as `passed` or the loop is explicitly aborted
+
+## Routing Rules
+
+- ambiguous goal -> run `$deep-interview` first, then start ralph with the clarified goal
+- goal is clear -> start ralph immediately (MCP: `operator_ralph_start`)
+- work is blocked on an external dependency -> `operator_ralph_block` with the reason, resolve, then advance back to `running`
+- all gates pass -> `operator_ralph_complete` is allowed only from phase=verifying
+
+## Lifecycle
+
+Phases in order: `idle` -> `running` -> `verifying` -> `completed`
+
+Side exits from `running`: `blocked` (returns to `running` after resolution) or `aborted`
+
+1. Start:
+   - MCP: `operator_ralph_start` with `goal`
+   - CLI: `enact-operator ralph start "<goal>"`
+2. Implement the work while in phase `running`.
+3. Advance to verification:
+   - MCP: `operator_ralph_advance` with `toPhase=verifying`
+   - CLI: `enact-operator ralph advance verifying`
+4. Record each gate verdict:
+   - MCP: `operator_ralph_verify` with `gateId` and `status`
+   - CLI: `enact-operator ralph verify <gateId> <passed|failed> --evidence "<text>"`
+5. All gates green:
+   - MCP: `operator_ralph_complete` with `summary`
+   - CLI: `enact-operator ralph complete "<summary>"`
+6. If a gate fails: fix the underlying task, stay in phase `verifying`, re-verify.
+
+## Mandatory Gates
+
+| Gate ID                    | Name                        |
+|----------------------------|-----------------------------|
+| `doctor`                   | Operator doctor              |
+| `provider-boundary`        | Provider boundary audit     |
+| `replacement-readiness`    | Replacement readiness audit |
+| `tests`                    | Real test suite             |
+
+These four gates are present by default. Do not skip them. Each must be recorded as `passed` before `complete` is allowed.
+
+Additional rule:
+
+- if the current Ralph run also carries a `contract-parity` gate in state,
+  treat it as mandatory and resolve it through the real gate output before
+  completion. Do not fabricate parity evidence.
+
+## Workflow
+
+1. Read current state:
+   - MCP: `operator_ralph_status`
+   - CLI: `enact-operator ralph status`
+2. If no ralph is active, start one:
+   - MCP: `operator_ralph_start` with `goal`
+   - CLI: `enact-operator ralph start "<goal>"`
+3. Implement the work. Keep changes atomic and verifiable.
+4. When implementation is done, advance to `verifying`:
+   - MCP: `operator_ralph_advance` with `toPhase=verifying`, `note="Implementation complete"`
+5. Run the doctor and record:
+   - Run: `operator_doctor` (or CLI `enact-operator doctor`)
+   - Record: `operator_ralph_verify` with `gateId=doctor`, `status=passed`, `evidence="doctor output clean"`
+6. Run the provider-boundary audit and record:
+   - Run: `operator_audit_provider_boundary`
+   - Record: `operator_ralph_verify` with `gateId=provider-boundary`, `status=passed`, `evidence="<audit output>"`
+7. Run the replacement-readiness audit and record:
+   - Run: `operator_audit_replacement_readiness`
+   - Record: `operator_ralph_verify` with `gateId=replacement-readiness`, `status=passed`, `evidence="<audit output>"`
+8. Run the test suite and record:
+   - Record: `operator_ralph_verify` with `gateId=tests`, `status=passed`, `evidence="N tests passed"`
+9. If a `contract-parity` gate is present, run it through the MCP surface:
+   - `operator_contract_parity_run`
+   - use its returned status/evidence directly when recording the gate
+10. If state drift is suspected during verification, run the hygiene gate
+   through the Operator surface and fail closed on contradictions:
+   - `runStateHygieneCheck` is the underlying verifier
+   - use `operator_operator_snapshot` / `operator_hud` / `operator_workflow_reconcile`
+     to gather state evidence before recording verdicts
+11. If any verification fails: fix the root cause, do NOT fabricate evidence. Re-run and re-record.
+12. Once all four gates are `passed`:
+    - MCP: `operator_ralph_complete` with `summary`
+    - CLI: `enact-operator ralph complete "<one-line summary>"`
+13. Check HUD:
+    - MCP: `operator_hud`
+    - CLI: `enact-operator hud`
+
+## State Contract
+
+- State file: `.enact/operator/state/ralph.json`
+- Ralph reads and writes this file throughout the loop.
+- On completion, the file reflects phase=completed, all gates passed, evidence recorded.
+- On abort, phase=aborted with a reason string.
+- Do not manually edit the state file. Use the MCP tools or equivalent CLI commands.
+
+## MCP Tools
+
+The full Ralph lifecycle is exposed through the `enact-operator` MCP server:
+
+- `operator_ralph_start` — start a new ralph loop
+- `operator_ralph_status` — read current ralph state
+- `operator_ralph_advance` — transition to a new phase
+- `operator_ralph_verify` — record a gate verdict with evidence
+- `operator_ralph_pause` — pause an active loop
+- `operator_ralph_resume` — resume a paused loop
+- `operator_ralph_block` — mark blocked with a reason
+- `operator_ralph_complete` — close the loop with a summary (phase=verifying with all gates passed)
+- `operator_ralph_abort` — abort with a reason
+
+Supporting tools used during the workflow: `operator_doctor`, `operator_audit_provider_boundary`, `operator_audit_replacement_readiness`, `operator_hud`.
+
+Important:
+
+- `contract-parity` is provider-first. Operator may call the running
+  `enact-context` server surface through its adapter layer to prove declared
+  commands/events/UI/tests/hooks. That is expected and correct.
+- `state-hygiene` is no longer a stub. If it fails, Ralph should not close.
+
+## CLI Equivalents
+
+```bash
+# Start a new loop
+enact-operator ralph start "Implement provider hot-swap without downtime"
+
+# Start with explicit task links and custom gates
+enact-operator ralph start "Fix install path" --task-id abc123 --gate "lint:Lint check"
+
+# Read state
+enact-operator ralph status
+
+# Advance phase
+enact-operator ralph advance verifying --note "All code written"
+
+# Record a gate
+enact-operator ralph verify doctor passed --evidence "No errors, 3 warnings"
+enact-operator ralph verify tests failed --evidence "2 failures in suite"
+
+# Pause and resume
+enact-operator ralph pause --note "Waiting on upstream merge"
+enact-operator ralph resume --note "Upstream merged"
+
+# Block and return
+enact-operator ralph block "Cannot proceed without env var ENACT_API_KEY"
+enact-operator ralph advance running --note "Env var added"
+
+# Complete or abort
+enact-operator ralph complete "Provider hot-swap ships cleanly, all 4 gates green"
+enact-operator ralph abort "Goal invalidated by architecture change"
+```
+
+## Activation
+
+This skill is wired to Operator's UserPromptSubmit hook. When a prompt contains
+an explicit marker like `$enact-operator:ralph "<goal>"` or `$ralph "<goal>"`
+and the workspace-context hook preset is installed (verified via
+`operator_hooks_status`), the hook automatically:
+
+1. Detects the marker
+2. Starts the durable state at `.enact/operator/state/ralph.json` before the agent reads its first turn of context
+3. Adds an MCP-first context note telling the agent to load/search the Enact Operator MCP namespace immediately and continue through `operator_*` tools
+4. Records the activation in `.enact/operator/state/skill-active.json`
+
+That injected startup note is not AzDo-only. If no external `taskId` is linked, treat the local task as mandatory runtime state: read it through `operator_task_list` and keep it current throughout the run.
+
+If hooks are not installed, OR the marker did not include a goal, OR you
+want explicit control, call `operator_operator_activate` with `{skill: 'ralph',
+goal: '<goal>'}` from the MCP tool surface. The result is idempotent — if
+a ralph loop is already active, the activation is a no-op.
+
+## Final Check
+
+- Phase is `completed`, not `running` or `verifying` (check via `operator_ralph_status`).
+- All four mandatory gates show `passed` in the ralph state.
+- Every gate has non-empty evidence text — not a placeholder.
+- `operator_hud` shows no active ralph loop outstanding.
+- No fabricated evidence. Each gate result comes from a real command run.

package/extensions/enact-operator/skills/ralph/gemini.md

@@ -0,0 +1,18 @@
+# Ralph (Gemini Variant)
+
+You are running Ralph with a Gemini model identity.
+
+Keep the same durable runtime contract as the default Ralph skill:
+
+- drive the goal to completion with real state updates
+- record evidence for every mandatory gate
+- fail closed when evidence is missing or contradictory
+- do not claim completion until all required gates are passed
+
+## TOOL_CALL_MANDATE
+
+- keep tool usage explicit, short, and sequential
+- prefer direct MCP/tool results over narrative summaries
+- when a gate depends on a command or runtime check, run it first and cite the result
+- if a required tool is not visible, load/search the operator MCP namespace before continuing
+- do not substitute inferred status for tool-backed evidence

package/extensions/enact-operator/skills/ralplan/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: ralplan
+description: "Plan-first Operator execution wrapper: write a durable plan, enter the Ralph loop, drive to verified completion."
+lane: true
+mcpToolPrefix: operator_ralplan_
+---
+
+# Ralplan
+
+## Purpose
+
+Use `$ralplan` when the work needs a reviewable execution plan before the Ralph loop starts. Ralplan is the disciplined alternative to `$autopilot` — it gates execution behind a plan the user or reviewer can inspect, then advances into Ralph's self-referential loop with explicit verification checkpoints.
+
+Ralplan is the combination of `$plan` (write artifacts, define slices and verification) and `$ralph` (durable execution loop with phase gates). Neither sub-skill is optional.
+
+## Use When
+
+- The request is clear enough to plan but carries meaningful risk or complexity
+- A written plan artifact needs to exist before any code changes
+- Verification gates need to be defined up front, not discovered mid-execution
+- The user wants to review the plan before execution begins
+
+## Do Not Use When
+
+- The request is still ambiguous — route through `$deep-interview` first, then return here
+- The work is trivial and a plan would add no value
+- The user explicitly wants unattended delivery without a plan review — use `$autopilot`
+
+## Execution Policy
+
+- start from the repo and `.enact/operator/` truth, not chat memory
+- drive the workflow through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- keep ralph, task, and review state current as you go
+- do not advance to the Ralph loop before the plan artifact exists and is reviewed
+
+## Lifecycle
+
+```
+intent → $plan (write plan + verification map) → user review → $ralph start → running → verifying → completed
+```
+
+Each transition is explicit. Never advance to the Ralph loop before the plan artifact exists and is reviewed.
+
+## Workflow
+
+### Phase 1 — Plan
+
+1. Read current Operator artifacts:
+   - MCP: `operator_session_status`, `operator_state_read`
+   - CLI:
+     ```
+     enact-operator session status
+     enact-operator state read
+     ```
+2. Write the plan to `.enact/operator/plans/<phase>.md` following `$plan` conventions:
+   - Named files per slice
+   - Explicit verification per slice
+   - Exit conditions stated
+3. Write the verification map to `.enact/operator/plans/<phase>-verification.md`.
+4. Link the plan artifact to ultrawork if an ultrawork session is active:
+   - MCP: `operator_ultrawork_link_plan` with the plan id
+5. Present the plan for review. Do not advance until it is approved.
+
+### Phase 2 — Execute
+
+6. Start the Ralph loop with the goal and verification gates from the plan:
+   - MCP: `operator_ralph_start` with `goal`
+   - CLI: `enact-operator ralph start "<goal>" --gate g1:"<Gate Name>" --gate g2:"<Gate Name>"`
+7. Confirm Ralph is running:
+   - MCP: `operator_ralph_status`
+   - CLI: `enact-operator ralph status`
+8. Execute each plan slice. After each slice, record evidence:
+   - MCP: `operator_ralph_verify` with `gateId` and `status=passed`
+   - CLI: `enact-operator ralph verify <gateId> passed --evidence "<evidence text>"`
+9. If blocked, record the blocker and pause:
+   - MCP: `operator_ralph_block` with reason, then `operator_ralph_pause`
+   - CLI:
+     ```
+     enact-operator ralph block --note "<reason>"
+     enact-operator ralph pause
+     ```
+   Resolve the block, then resume:
+   - MCP: `operator_ralph_resume`
+   - CLI: `enact-operator ralph resume`
+
+### Phase 3 — Verify and Complete
+
+10. When all gates have evidence, advance to the verifying phase:
+    - MCP: `operator_ralph_advance` with `toPhase=verifying`
+    - CLI: `enact-operator ralph advance verifying`
+11. Run `$review` against the completed work and plan artifacts.
+12. If review passes, complete the Ralph session:
+    - MCP: `operator_ralph_complete` with `summary`
+    - CLI: `enact-operator ralph complete`
+13. If review returns changes requested, advance back to running and address findings:
+    - MCP: `operator_ralph_advance` with `toPhase=running`
+    - CLI: `enact-operator ralph advance running --note "<what changed>"`
+
+## State Contract
+
+Reads:
+- `.enact/operator/plans/` (plan and verification map written in Phase 1)
+- `.enact/operator/state/ralph-state.json` (Ralph loop state)
+
+Writes:
+- `.enact/operator/plans/<phase>.md`
+- `.enact/operator/plans/<phase>-verification.md`
+- Ralph state via MCP tools or CLI commands
+
+## MCP Tools
+
+- `operator_session_status` — read current session state
+- `operator_state_read` — read active operator state
+- `operator_ralph_start` — start a new ralph loop with goal and gates
+- `operator_ralph_status` — read current ralph state
+- `operator_ralph_advance` — transition to a new phase
+- `operator_ralph_verify` — record a gate verdict with evidence
+- `operator_ralph_block` — mark blocked with a reason
+- `operator_ralph_pause` — pause the active loop
+- `operator_ralph_resume` — resume a paused loop
+- `operator_ralph_complete` — close the loop with a summary
+- `operator_ralph_abort` — abort the loop with a reason
+- `operator_ultrawork_link_plan` — link the plan artifact to an active ultrawork session
+
+## Commands
+
+```
+enact-operator session status
+enact-operator state read
+enact-operator ralph start "<goal>" --gate <id>:<name>
+enact-operator ralph status
+enact-operator ralph advance <phase>
+enact-operator ralph verify <gateId> passed --evidence "<text>"
+enact-operator ralph verify <gateId> failed --evidence "<text>"
+enact-operator ralph block --note "<reason>"
+enact-operator ralph pause
+enact-operator ralph resume
+enact-operator ralph complete
+enact-operator ralph abort
+```
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.
+## Final Check
+
+- Plan artifact exists at `.enact/operator/plans/<phase>.md` before Ralph was started
+- All verification gates have evidence recorded, not just a passed status
+- `$review` verdict is approved
+- `operator_ralph_status` shows phase as `completed`
+- No stale Ralph state file remains active under `.enact/operator/state/`