@amsterdamdatalabs/enact-extensions 0.1.1 → 0.1.5

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

@@ -0,0 +1,99 @@
+---
+name: cancel
+description: "Explicit termination of any active Operator mode (ralph, ultrawork, team). Cleans up state and leaves no dangling sessions."
+---
+
+# Cancel
+
+## Purpose
+Stops all active Operator execution modes cleanly. Each running mode (ralph loops, ultrawork sessions, team sessions) must be explicitly aborted or shut down — not just ignored. After cancel completes, no session remains in a running, claimed, or paused state.
+
+## Use When
+- A ralph loop, ultrawork session, or team session must be stopped before it completes
+- A session is stuck, blocked indefinitely, or no longer relevant
+- The operator wants a clean slate before starting a new workflow
+
+## 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 cancellation work
+- drive cancellation through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- keep state current as you go — confirm each abort before moving to the next mode
+
+## Lifecycle
+
+### Step 1 — Inventory active modes
+Check each execution surface for active state:
+- MCP: `operator_ralph_status`, `operator_ultrawork_status`, `operator_team_status`
+- CLI:
+  ```
+  enact-operator ralph status
+  enact-operator ultrawork status
+  enact-operator team status
+  ```
+
+### Step 2 — Cancel ralph loops
+For each loop returned by ralph status that is not already complete:
+- MCP: `operator_ralph_abort` with `reason`
+- CLI: `enact-operator ralph abort <loopId>`
+
+### Step 3 — Cancel ultrawork sessions
+For each session returned by ultrawork status that is not already complete:
+- MCP: `operator_ultrawork_abort` with `reason`
+- CLI: `enact-operator ultrawork abort <sessionId>`
+
+### Step 4 — Shut down team sessions
+For each team session returned by team status that is live:
+- MCP: `operator_team_shutdown`
+- CLI fallback: `enact-operator team shutdown`
+
+### Step 5 — Verify clean state
+Re-run each status command and confirm no active sessions remain:
+- MCP: `operator_ralph_status`, `operator_ultrawork_status`, `operator_team_status`
+- CLI:
+  ```
+  enact-operator ralph status
+  enact-operator ultrawork status
+  enact-operator team status
+  ```
+
+### Step 6 — Confirm with doctor
+- MCP: `operator_doctor`
+- CLI: `enact-operator doctor`
+
+## State Contract
+- Reads: active session IDs from ralph status, ultrawork status, team status
+- Writes: abort/shutdown records in `.enact/operator/state/` (managed by MCP tools or CLI commands)
+- Does NOT delete `.enact/operator/` audit history unless the operator explicitly requests it
+
+## MCP Tools
+
+- `operator_ralph_status` — read current ralph state
+- `operator_ralph_abort` — abort a ralph loop with a reason
+- `operator_ultrawork_status` — read current ultrawork state
+- `operator_ultrawork_abort` — abort an ultrawork session with a reason
+- `operator_team_status` — read current team session state
+- `operator_doctor` — confirm runtime health after cancellation
+
+Prefer `operator_team_shutdown` when the Operator MCP namespace is available. The CLI remains a fallback operator surface.
+
+## Commands
+```
+enact-operator ralph status
+enact-operator ralph abort <loopId>
+enact-operator ultrawork status
+enact-operator ultrawork abort <sessionId>
+enact-operator team status
+enact-operator team shutdown
+enact-operator doctor
+```
+
+## 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
+- `operator_ralph_status` shows no loops in `running` or `paused` state
+- `operator_ultrawork_status` shows no sessions in `running` or `blocked` state
+- `operator_team_status` shows no active team session
+- `operator_doctor` reports clean
+- Audit history in `.enact/operator/` is intact unless operator requested a clear

package/extensions/enact-operator/skills/configure-notifications/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: configure-notifications
+description: "Operator-level notification configuration: read and write .enact/operator/state/notifications.json to control Operator runtime visibility."
+---
+
+# Configure Notifications
+
+## Purpose
+Manages operator notification preferences for Operator runtime events. Notification configuration is stored in `.enact/operator/state/notifications.json`. This skill reads the current config, applies the requested changes, and verifies that Operator health is unaffected. There is no dedicated CLI command for notifications yet; this skill is operator-driven via direct file editing.
+
+## Use When
+- The operator wants to change which Operator events trigger notifications
+- Notification delivery is broken or generating noise and needs to be adjusted
+- Setting up notification preferences for the first time in a new project
+
+## Workflow
+1. Read the current notification configuration:
+   ```
+   enact-operator state read notifications
+   ```
+   If no file exists, the default is all events enabled.
+
+2. Identify the notification contract. The file at `.enact/operator/state/notifications.json` is the operator's truth. Its shape:
+   ```json
+   {
+     "events": {
+       "ralph.complete": true,
+       "ralph.fail": true,
+       "ultrawork.complete": true,
+       "ultrawork.block": true,
+       "team.task.complete": true,
+       "team.task.blocked": true,
+       "doctor.fail": true
+     },
+     "delivery": {
+       "console": true,
+       "hud": true
+     }
+   }
+   ```
+
+3. Edit `.enact/operator/state/notifications.json` with the requested changes.
+
+4. Verify the configuration is valid JSON (no trailing commas, well-formed):
+   ```
+   node -e "JSON.parse(require('fs').readFileSync('.enact/operator/state/notifications.json','utf8'))"
+   ```
+
+5. Run doctor to confirm Operator runtime is unaffected:
+   ```
+   enact-operator doctor
+   ```
+
+6. Check the HUD to confirm visibility settings reflect the new configuration:
+   ```
+   enact-operator hud
+   ```
+
+## State Contract
+- Reads: `.enact/operator/state/notifications.json`
+- Writes: `.enact/operator/state/notifications.json`
+
+## Commands
+```
+enact-operator state read notifications
+enact-operator doctor
+enact-operator hud
+```
+
+## 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
+- `.enact/operator/state/notifications.json` is valid JSON
+- Requested event flags match the operator's intent
+- `enact-operator doctor` passes after the edit
+- `enact-operator hud` reflects updated visibility settings

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.