@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/extensions/enact-loop/skills/enact-loop/SKILL.md

@@ -1,494 +1,64 @@
 ---
 name: enact-loop
-description: "Contract-runner loop engine. Drives declared stages (mechanical and judgment) to closure; the Stop boulder refuses to exit until every required stage passes and independent graders have signed off every judgment stage."
+description: Declare and drive a generic Stage graph through interactive Executor, mechanical, StageVerifier, and LoopGrader stages.
+disable-model-invocation: false
 ---
 
-# enact-loop
-
-> **Storage is GLOBAL — never write to a repo-local `.enact` dir.** Resolve the project's global dir:
-> 1. `ROOT="$(git rev-parse --show-toplevel)"`
-> 2. In `~/.enact/workspaces.json` → `workspaces`, find the entry whose `.root` == `$ROOT`; its object key is `<name>-<id>` (e.g. `enact-loop-b9762d`).
-> 3. Loop runtime state lives under `~/.enact/loop/projects/<key>/…`.
+# Enact Loop
 
 ## Purpose
 
-`$enact-loop` is the persistence wrapper for bounded work. Given a contract (an ordered set of
-stages), the loop drives each stage to closure and refuses to exit until every required stage has
-passed. Mechanical stages are graded by the engine: `loop_grade` runs the stage `command` in the
-loop root and derives pass/fail from exit code (caller-supplied `status`/`evidence` are rejected).
-Judgment stages require an **independent grader** on a different model — the executor must not
-fabricate or self-report judgment verdicts.
+Drive bounded work to a declared contract. The runtime closes a loop only after every required stage passes.
 
 ## Use When
 
-- work must not stop until all required stages pass
-- judgment gates (architect-GO, code review, scope fidelity, QA) require independent sign-off
-- a previous attempt left work in an incomplete or unverified state
-- partial completion is unacceptable
-
-## Contract Schema
-
-A **contract** is the declarative closure spec. Declare it inline or pass a YAML/JSON file.
-
-```
-Contract { id, name, stages[] }
-
-Stage {
-  id: string
-  name: string
-  type: 'mechanical' | 'judgment'
-  required: boolean
-  requires?: string[]   # stage ids that must pass before this stage runs
-  command?: string        # mechanical stages only
-  grader?: GraderSpec     # judgment stages only
-  passCriteria?: string
-}
-
-GraderSpec {
-  role: architect | critic | code-reviewer | verifier   # required
-  model?: string      # e.g. claude-opus-4-8 — always specify; omitting causes E_GRADER_MODEL_UNSET
-  harness?: paseo | subagent                            # default: paseo
-  rounds?: integer    # max grading rounds before escalation (default: 3)
-  timeoutMs?: integer # grader session timeout (default: 30 min); timeout → grader-unavailable blocker
-  fallbackModels?: string[]  # tried in order on re-dispatch after spawn failure (529/overload)
-}
-```
-
-## Stage Types
-
-**Mechanical** stages are engine-run: call `loop_grade({ stageId, timeoutMs? })` and the runtime
-executes the stage `command` in the loop root cwd, capturing exit code and output. Caller-supplied
-`status` or `evidence` are rejected. No independent grader is needed.
-
-**Judgment** stages require an independent grader. The executor/driver dispatches via
-`loop_grader_dispatch`, then records the verdict via `loop_grader_verdict` (default:
-`captureSource: "relayed"` — grader returns a verdict envelope; driver records with the minted
-`continuationId`). A grader child session may call `loop_grader_verdict` directly (`captureSource:
-"direct"`) but only with a `continuationId` minted by dispatch — otherwise
-`E_UNKNOWN_GRADER_SESSION`. The engine rejects verdicts where grader identity overlaps executor
-identity.
-
-## The Independence Rule
-
-Judgment stages must be graded by a **different model** than the executor (model-distinct, not
-vendor/surface-distinct). The loop rejects a verdict whose grader model, session, or agent equals
-the executor's. Graders are dispatched out-of-session via Paseo `--provider <model>` (use
-`--mode auto-review` so on-request approvals don't block; see Verdict capture) for
-cross-surface grading; in-surface graders just need a supported model that differs from the
-executor's.
+- Work needs explicit stages, evidence, and closure.
+- Prompt-driven work needs an interactive Executor Stage with immutable input and pass-only completion evidence.
+- A mechanical Stage must be executed by the engine.
+- A current-plus-predecessor Stage needs StageVerifier review.
+- The complete loop needs LoopGrader judgment.
+- A previous attempt is incomplete, blocked, or unverified.
 
-The engine enforces independence at `recordStage` AND `completeLoop` (defense in depth). The Stop
-boulder re-checks at session exit. Violations emit `grader-independence-missing` and block closure.
+## Do Not Use When
 
-## Loop Phases
-
-```
-idle → running → verifying → completed (terminal)
-              ↘ blocked → running | verifying
-              ↘ paused  → running | verifying   (Stop ALLOWS exit while paused)
-              ↘ aborted (terminal)
-```
-
-- **idle** — loop declared, not yet started
-- **running** — executor actively working
-- **verifying** — executor running closure checks
-- **completed** — all required stages passed, loop closed
-- **blocked** — waiting on an external dependency (`loop_block` / `loop_advance` to resume)
-- **paused** — deliberate human suspension via `loop_pause`; the Stop boulder ALLOWS exit while
-  paused; SessionStart does NOT auto-resume a paused loop; stays paused until `loop_resume` is
-  explicitly called
-- **aborted** — cancelled with a reason (terminal)
-
-## Routing Rules
-
-- ambiguous goal → clarify first, then start the loop with the refined goal
-- goal is clear → start immediately: `loop_start`
-- blocked on external dependency → `loop_block`, resolve, then `loop_advance` back to `running`
-- all required stages passed → `enact-loop summary write`, then `loop_complete` (only from phase=verifying)
+- The request is only for triage or a proposed contract; use `loop-intake`.
+- The request is only to inspect limits or counters; use `loop-budget`.
+- The goal, workspace, acceptance evidence, or authority is too ambiguous to declare a contract.
 
 ## Workflow
 
-1. Read current state: `loop_status`
-2. If no active loop, start one:
-   ```
-   loop_start  goal="<goal>"  preset=<preset>|contract=<stages JSON>
-   ```
-   Built-in presets: `frontend-ui` (5 mechanical: lint/typecheck/test/build/visual,
-   then **two** judgment stages — `code-review` **and** `verify` — the shape that
-   reliably catches both correctness and acceptance defects), `docs` (mechanical +
-   one lighter `review`), plus `docs-workflow` / `custom-pipeline`. Use a preset to
-   get the right judgment shape by default instead of hand-authoring stages.
-3. Implement the work while in phase `running`.
-4. Advance to verification:
-   ```
-   loop_advance  toPhase=verifying
-   ```
-5. For each **mechanical** stage (respecting `requires` preconditions): `loop_grade({ stageId })`.
-6. For each **judgment** stage: `loop_grader_dispatch({ stageId })` → spawn grader → record via
-   `loop_grader_verdict` (`captureSource: "relayed"` from driver, or `"direct"` from grader child).
-7. When all required stages are `passed`: run `enact-loop summary write` (pipe body sections;
-   CLI stamps the fingerprint header), then `loop_complete`.
-8. If a stage fails: fix the root cause, do not fabricate evidence, re-run and re-grade.
-
-## Judgment Grading Protocol
-
-**Step 1 — Dispatch a grader:**
-
-```
-loop_grader_dispatch  stageId=<id>  [model=<grader-model>]
-```
-
-- mints an unforgeable `continuationId` and `graderSessionId` via the runtime
-- resolves the grader model: an explicit `model` override is used **verbatim**
-  (after the `≠ executor` check); otherwise `stage.grader.model ?? loop.graderModel`,
-  advancing through `fallbackModels` on re-dispatch after a spawn failure
-- requires the resolved model to differ from the executor's (`E_NO_DIVERSITY` otherwise)
-- launches the grader agent (read-only, same cwd) via Paseo `--provider <graderModel>`
-  (use `--mode auto-review` so on-request approvals don't block; see Verdict capture)
-- returns the `continuationId` you must pass to step 2
-
-**Step 2 — Record the grader's verdict** (driver-relayed is the default):
-
-```
-loop_grader_verdict  stageId=<id>  continuationId=<id>  verdict=GO|NO-GO  evidence="<findings>"
-  graderAgentId=<id>  graderSessionId=<id>  captureSource=relayed
-  recordedByAgentId=<executor>  recordedByModel=<model>  recordedBySessionId=<session>
-  [graderModelActual=<model-that-actually-ran>]
-```
-
-`graderModelActual` records the model that *actually* ran the grader (e.g. the
-Paseo-resolved provider), separate from the dispatch-resolved request — the
-verdict stores it as the authoritative grader model (keeping the dispatched one
-as `graderModelDispatched`) and the independence check runs against it. Supply it
-when the host ran a different/fallback model than dispatched; omit it otherwise.
-
-Grader child sessions may call `loop_grader_verdict` directly with `captureSource=direct` instead.
-Direct calls without a dispatch-minted `continuationId` fail with `E_UNKNOWN_GRADER_SESSION`.
-Grader MCP sessions are **runtime-gated**: only `loop_grader_verdict`, `loop_status`,
-`loop_stop_evaluate` — pass `_meta.enactLoop` with `sessionRole: grader` and bound `continuationId`.
-Incomplete grader metadata (e.g. `role=grader` without `sessionId`) fails closed with
-`E_INCOMPLETE_GRADER_SESSION` rather than defaulting to executor.
-Grader timeout surfaces as `grader-unavailable` blocker — re-dispatch; never assume GO.
-Spawn failure (529): `loop_grader_report_spawn_failure` then re-dispatch (uses `fallbackModels`).
-While grader is in flight, Stop **allows** exit without `loop_pause` churn.
-
-The engine rejects the verdict if grader identity overlaps executor identity or the
-`continuationId` was not minted by this runtime.
-
-**NEVER self-report a judgment verdict.** The boulder blocks Stop and re-prompts with
-`grader-independence-missing` if you do. If a grader returns NO-GO: fix the issue, stay in
-`verifying`, and re-dispatch. Exceeding the round limit escalates with a blocker.
-
-## Operational notes — grader independence, fallback, and worktree discipline
-
-> Context: in a validated 3-wave run, independent graders caught FIVE real defects that
-> all mechanical gates passed — model-distinct cross-vendor grading is the mechanism that
-> surfaces defects mechanical gates cannot see.
-
-### Grader independence is MODEL-DISTINCT
-
-The independence rule is checked by model identity, not by vendor or surface name.
-**A sonnet executor + a cursor-sonnet grader is NOT distinct** — `cursor/claude-sonnet-4-6`
-runs the same underlying model. The engine will emit `grader-independence-missing` and
-block closure. Ensure the resolved `grader.model` differs from the executor's model string.
-
-**Default cheap graders:** **minimax M3** (opencode) and **kimi K2.7** are vendor-distinct from
-both sonnet and codex, making them always-independent defaults (~80% of grading). Escalate to
-**opus 4.8** or **gpt-5.5** for high-risk judgment (a11y / visual / security / architecture).
-`cursor` is only distinct when the executor is opus-tier (cursor runs claude-sonnet).
-
-### fallbackModels rotation on spawn failure (529 / overload)
-
-1. Call `loop_grader_report_spawn_failure({ continuationId, error })` to record the failure.
-2. Re-call `loop_grader_dispatch` — with no `model`, the runtime auto-selects the next
-   `fallbackModels` entry; pass an explicit `model` to **pin a specific grader** (the override
-   is honored verbatim and is not consumed by the rotation pointer).
-3. Record the verdict under the minted `continuationId`; set `graderModelActual` to the model
-   that actually ran so provenance is accurate. Independence holds as long as the actual grader
-   model ≠ executor model.
-
-### Worktree fingerprint — when verdicts are invalidated vs. preserved
-
-| Change type | Effect on verdicts |
-|---|---|
-| Edit a **tracked** source file | Fingerprint changes → all prior `passed` verdicts invalidated (`BLOCKER_FILESYSTEM_STATE_CHANGED`) → re-grade required |
-| Add an **untracked** new file (e.g. a new test file) | Fingerprint unchanged → prior GO verdicts remain valid |
-
-This means you can add new test files mid-loop without forcing re-grading of already-passed stages.
-Never use `git stash` mid-loop — it mutates tracked-file state and invalidates all verdicts.
-
-### `loop_pause` / `loop_resume` around long async grading
-
-While a grader is dispatched and in flight, the Stop boulder already allows exit without `loop_pause`.
-Use `loop_pause` / `loop_resume` explicitly when you need to hand off control for extended human
-review or an async wait that is not grader-dispatch-in-flight, to avoid unnecessary Stop churn.
-
-### Graders are read-only
-
-Grader child sessions must review the artifact and emit a verdict — nothing else.
-They MUST NOT call `loop_*` management tools (complete, pause, resume, retarget, block, abort)
-or `factory_*` tools. The runtime rejects these calls from grader sessions.
-
-**Verdict capture is STRUCTURED, not log-scraped.** Dispatch with:
-`paseo run --provider <graderModel> --mode auto-review --output-schema <verdict.json> --json --label continuation=<cid>`
-— stdout is the validated `{verdict, evidence}` object (verified on codex / cursor / opencode / kimi;
-coexists with tool use). With the codex provider, `--mode auto-review` routes the grader's eligible
-`on-request` approvals through codex's auto-reviewer subagent instead of BLOCKING — without it a
-grader can stall waiting on an approval (e.g. a cargo/network fetch during build verification). The
-grader stays read-only BY PROMPT; auto-review only governs approval handling and composes with the
-`--output-schema` structured verdict capture. Codex mode enum (authoritative): `read-only` · `auto`
-· `auto-review` · `full-access`. Flip a running grader with `paseo agent mode <id> auto-review`.
-Recover actual grader model + cost via
-`paseo ls -a --label continuation=<cid> --json` + `paseo inspect <id> --json`.
-Watch live: recover the id by label then `paseo attach <id>`.
-Fallback only: if structured capture is unavailable, embed evidence inline in the `evidence` field.
-Design doc: `enact-loop/docs/design/2026-06-22-paseo-verdict-capture.md`.
-
-## Access Control — `.enact/` is CLI-mediated
-
-The agent **NEVER edits `~/.enact/` files directly**. All loop state mutation goes through the
-`enact-loop` CLI or `loop_*` MCP tools — never raw file edits. Read state via:
-
-```bash
-enact-loop status --json          # current loop state as JSON
-enact-loop summary show           # display the current closure summary
-```
-
-## Session roles and closure authority
-
-| Role | May call | Must NOT call |
-|------|----------|---------------|
-| **Executor/driver** | `loop_grade`, `loop_grader_dispatch`, `loop_grader_verdict` (relayed), `loop_pause`, `loop_resume`, `loop_retarget`, `loop_complete`, `enact-loop summary write` | — |
-| **Grader child** | `loop_grader_verdict` (direct), `loop_status`, `loop_stop_evaluate` | `loop_complete`, summary write, `loop_pause`/`loop_resume`/`loop_retarget`, closure tools |
-
-Grader child sessions: review, emit verdict, stop cleanly. They have **no closure authority**.
-
-**No `git stash` during an active loop** — stash mid-loop invalidates worktree state and stale
-verdict fingerprints.
-
-## Worktree fingerprint
-
-Each verdict is stamped with a worktree fingerprint. When the workspace changes (e.g. after
-retarget or filesystem drift), stale `passed` verdicts are invalidated (`BLOCKER_FILESYSTEM_STATE_CHANGED`).
-`loop_retarget` preserves verdicts only when `id + type + worktreeFingerprint` match unchanged stages.
-
-## Workspace root resolution
-
-Loop state is keyed to the **launch workspace** — no ancestor `.git` walk:
-
-| Surface | Root source |
-|---------|-------------|
-| CLI subcommands | `process.cwd()` — run from the driven project |
-| MCP | `enact-loop mcp <workspace>` positional arg (bundle uses `"."` = host MCP cwd) |
-| Hooks | `payload.cwd` from hook JSON |
-
-Wrong cwd → different project store → "no active loop".
-
-## Closure
-
-Closure requires a written, CURRENT timestamped summary under
-`~/.enact/loop/projects/<key>/state/<YYMMDDHH>-loop-summary.md`. The runtime records the active
-path in `~/.enact/loop/projects/<key>/state/summary-current.json`. When all required stages pass
-(and every judgment stage has an independent verdict), the loop is closure-ready and enters the
-`verifying` phase. The Stop boulder then **BLOCKS exit** and injects a generic markdown
-**TEMPLATE** whose first line is a fingerprint header:
-
-```
-<!-- enact-loop-summary loop:<id> fp:<phase|stagesPassed|historyLen> -->
-```
-
-The template defines these sections (keep the whole file under 100 lines):
-
-- **Summary** — one-line statement of what was accomplished or why blocking/aborting
-- **Stage state** — list of stages with their final status
-- **Blockers** — any unresolved blockers (if blocking/aborting)
-- **Failures** — any stages that failed and the root cause
-- **Evidence** — key commands run and observed outputs
-- **Recommendations** — suggested next actions
-
-To write the summary, **pipe the body sections to the CLI** — the CLI stamps the fingerprint
-header automatically:
-
-```bash
-enact-loop summary write <<'EOF'
-## Summary
-<one-line summary>
-
-## Stage state
-<stage list>
-
-## Blockers
-<none|list>
-
-## Failures
-<none|list>
-
-## Evidence
-<commands + observed output>
-
-## Recommendations
-<next actions>
-EOF
-```
-
-Once a current summary exists, the boulder allows exit. `completeLoop` / `blockLoop` / `abortLoop`
-all **REQUIRE** a current summary and throw `E_CLOSURE_SUMMARY_MISSING` otherwise.
-
-When a later `loop_start` begins a new loop, the prior terminal loop's active state is archived
-under `~/.enact/loop/projects/<key>/archive/<loop-id>-<contract-id>/` before the new active
-`state/loop.json` is written. That archive keeps the closed loop's `loop.json`,
-`closure-manifest.json`, `grader-sessions.json`, `summary-current.json`, and every timestamped
-closure summary for auditability.
-
-**This summary is the handoff**: enact-factory's brain reads it (together with the Paseo agent's
-last message) to decide the next action after the loop completes.
-
-**Closure sequence — required for ALL terminal transitions:**
-
-1. `enact-loop summary write` — pipe body sections; CLI stamps the fingerprint header
-2. Then call: `loop_complete summary="<one-line>"` OR `loop_block reason="<reason>"` OR
-   `loop_abort reason="<reason>"`
-
-## MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `loop_start` | Start loop with goal + contract/preset; stamps executorIdentity |
-| `loop_status` | Read current loop state |
-| `loop_advance` | Phase transition |
-| `loop_grade` | Run a mechanical stage command in loop root; args: `stageId`, optional `timeoutMs` |
-| `loop_grader_dispatch` | Dispatch an independent grader for a judgment stage (returns continuationId) |
-| `loop_grader_verdict` | Record GO/NO-GO; `captureSource`: `relayed` (driver default) or `direct` (grader child) |
-| `loop_pause` | Pause the loop for human review; Stop allows exit while paused |
-| `loop_resume` | Resume a paused loop; restores the pre-pause phase |
-| `loop_retarget` | Replace the active contract with a new one (same loop id) |
-| `loop_block` | Mark blocked with a reason; requires current closure summary |
-| `loop_complete` | Close the loop; requires current closure summary + phase=verifying + all stages passed |
-| `loop_abort` | Abort with a reason; requires current closure summary |
-| `loop_contract_parity` | Run contract-parity check |
-| `loop_stop_evaluate` | Evaluate Stop boulder policy (called by the Stop hook) |
-
-## CLI
-
-```bash
-# Read state (never read .enact/ files directly)
-enact-loop status --json                          # current loop state as JSON
-enact-loop summary show                           # display the current closure summary
-
-# Write the closure summary (CLI stamps fingerprint header into a new YYMMDDHH-loop-summary.md; never write summaries directly)
-enact-loop summary write <<'EOF'
-## Summary
-...
-EOF
-
-# Validate a contract file before using it with loop_start
-enact-loop contract validate <path/to/contract.json|yaml>
-
-# Health check — verify MCP server reachability and runtime state; optionally validate
-# that a contract's grader model differs from the executor model
-enact-loop doctor --contract <file> [--executor-model M] [--grader-model M]
-```
-
-`contract validate` exits 0 + `✓ valid contract: <id> (<n> stages)` on success; exits 1 with an
-error list on failure. Common errors: missing required fields, judgment stage without `grader`,
-mechanical stage with `grader` (use `command` instead), malformed YAML/JSON.
-
-## Boulder Behavior
-
-The Stop hook calls `enact-loop hook stop` → `loop_stop_evaluate`. The boulder blocks exit if:
-- any `required` stage is still `pending` or `failed`
-- any judgment stage is `passed` but lacks a valid independent verdict (`grader-independence-missing`)
-- a required grader is unavailable (`grader-unavailable`)
-- the loop is closure-ready (all stages passed, independence satisfied) but no current closure summary exists
-  or the summary fingerprint is stale (`closure-summary-missing`) — resolve by running `enact-loop summary write`
-- the loop phase is not terminal (exception: `paused` allows exit)
-
-## State
+1. Read `loop_status`; clarify the goal if needed.
+2. Declare a contract using the exact `executor`, `mechanical`, `stage-verifier`, and `loop-grader` types needed by the outcome. Dependencies form the graph; no domain-specific Stage ids are required. Use `executor` for prompt-driven interactive work and `mechanical` only for a real executable command.
+3. Start with `loop_start`, perform the declared work in `running`, then advance with `loop_advance toPhase=verifying`.
+4. For an `executor` Stage, the authenticated active Executor first calls `loop_executor_stage_input({ stageId })`, performs the returned exact `prompt.text`, then calls `loop_executor_stage_complete` with the response's exact `identity`, `inputFingerprint`, and `executorContinuationId`, plus non-empty `evidenceRefs`, a lower-case SHA-256 `outputDigest`, and any mapped `assertionResults`. The operation is pass-only; status, command result, and Executor identity are not caller inputs.
+5. Run each `mechanical` Stage through `loop_stage_run`; do not use Executor completion for a declared command.
+6. For a `stage-verifier` Stage, reserve with `loop_stage_verifier_dispatch`, bind the launched reviewer with `loop_stage_verifier_register_session`, persist observed transport with `loop_stage_verifier_observation_record`, and submit its role-specific verdict through `loop_stage_verifier_verdict`. Record launch failure only through `loop_stage_verifier_report_spawn_failure`.
+7. For a `loop-grader` Stage, use the distinct `loop_grader_dispatch`, `loop_grader_register_session`, `loop_grader_observation_record`, `loop_grader_verdict`, and `loop_grader_report_spawn_failure` surface. Do not select either role through a generic role flag.
+8. Resume the same Executor after a StageVerifier GO. Fix a NO-GO within the declared contract; pause for human amendment when the contract must change. When every required Stage and assertion passes, write the summary and close with `loop_complete`.
+9. Read [the contract reference](references/loop-contract.md) before declaring complex dependencies or budgets.
 
-`.enact/` is CLI-mediated — never read or write `.enact/` files directly.
+## Output
 
-- Read state: `enact-loop status --json` (loop state) · `enact-loop summary show` (current closure summary)
-- Mutate state: `loop_*` MCP tools or `enact-loop` CLI subcommands only
-- Active loop state stays in `~/.enact/loop/projects/<key>/state/`; closed loops move to
-  `~/.enact/loop/projects/<key>/archive/<loop-id>-<contract-id>/` on the next `loop_start`
-- Closure summaries are append-only timestamped files at
-  `~/.enact/loop/projects/<key>/state/<YYMMDDHH>-loop-summary.md`, written via `enact-loop summary write`
-  (CLI stamps the fingerprint header and updates `summary-current.json`); read by enact-factory's brain after loop completion.
-- SessionStart hook auto-resumes an active (`running` or `verifying`) loop when the prompt
-  contains `$enact-loop`. Paused loops are NOT auto-resumed.
+Return the loop id, phase, contract, interactive Executor evidence, mechanical evidence, role-specific verdicts, blockers, and closure summary.
 
-## Example Contracts
+## State Contract
 
-### Delivery Contract
+The runtime owns loop state and derives its project key from the launch workspace. Inspect state through loop tools; never fabricate evidence, stage status, or a judgment verdict.
 
-```yaml
-id: delivery
-name: Feature Delivery
-stages:
-  - id: tests
-    name: Tests passing
-    type: mechanical
-    required: true
-    command: bash scripts/ci-local.sh
-    passCriteria: All tests exit 0
+## Boundaries
 
-  - id: typecheck
-    name: Type check clean
-    type: mechanical
-    required: true
-    command: npm run typecheck && npm run typecheck:tests
-    passCriteria: No type errors in src or test files
+### In scope
 
-  - id: lint
-    name: Lint clean
-    type: mechanical
-    required: true
-    command: npm run lint
-    passCriteria: No lint errors
+Declaring, executing, grading, blocking, resuming, and closing an enact-loop contract.
 
-  - id: code-review
-    name: Code review
-    type: judgment
-    required: true
-    grader:
-      role: code-reviewer
-      model: claude-opus-4-8
-      harness: paseo
-      rounds: 3
-    passCriteria: Reviewer approves with no blocking issues
-```
+### Out of scope
 
-**Tests stage must mirror CI (hard requirement #9).** A bare `npm test` on the
-host is not acceptable — the host suite can pass green while the same deliverable
-fails the Linux CI agent due to `HOME`/path divergence. The `command` for the
-`tests` stage must invoke a Linux-parity / containerized runner (e.g.
-`bash scripts/ci-local.sh`) that reproduces the CI environment locally.
+Using an Executor session as StageVerifier or LoopGrader, using pass-only Executor completion for a mechanical or judgment Stage, editing runtime state files, bypassing a failed required Stage, or treating a proposed contract as approval.
 
-**Include `typecheck:tests` (rule #7).** When the project has a separate
-test-file typecheck script, include it — either as its own mechanical stage or
-folded into the typecheck stage command (`npm run typecheck && npm run
-typecheck:tests`). A src-only `typecheck` lets test-file type regressions slip
-past undetected.
+### Fog of war
 
-### Docs Workflow
+If scope, acceptance, dependency, or reviewer identity is unknown, block or clarify instead of starting or completing a loop.
 
-```yaml
-id: docs-workflow
-name: Documentation Update
-stages:
-  - id: build
-    name: Docs build clean
-    type: mechanical
-    required: true
-    command: npm run docs:build
+## Completion
 
-  - id: scope-fidelity
-    name: Scope fidelity
-    type: judgment
-    required: true
-    grader:
-      role: critic
-      model: claude-opus-4-8
-      rounds: 2
-    passCriteria: Critic confirms docs match the stated scope
-```
+Prove closure with `loop_status` after `enact-loop summary write` and `loop_complete`; every required Stage must be `passed`, every required assertion must be met, and every judgment verdict must use its exact role-specific surface.

package/extensions/enact-loop/skills/enact-loop/references/loop-contract.md

@@ -0,0 +1,114 @@
+# Enact-loop contract reference
+
+## Contract shape
+
+Declare a generic contract with an id, name, optional opaque skill reference, and Stages. A Stage has an opaque id, name, exact type, required flag, optional dependency ids, and optional prompt, evidence schema, and stop conditions. Use `executor` for interactive prompt-driven work; use `mechanical` only when the engine must run a real command.
+
+```yaml
+id: <loop-id>
+name: <outcome name>
+skill:
+  id: <optional opaque skill id>
+stages:
+  - id: produce
+    name: Produce the artifact
+    type: executor
+    required: true
+    prompt:
+      text: <exact prompt text>
+      sha256: <lower-case SHA-256 of text>
+  - id: validate
+    name: Validate the artifact
+    type: mechanical
+    required: true
+    requires: [produce]
+    command: <executable validation command>
+    passCriteria: The artifact satisfies its declared mechanical checks
+  - id: inspect-current
+    name: Inspect current work and predecessors
+    type: stage-verifier
+    required: true
+    requires: [validate]
+    stageVerifier:
+      role: stage-verifier
+      rounds: 3
+  - id: judge-complete
+    name: Judge whole-loop completeness
+    type: loop-grader
+    required: true
+    requires: [inspect-current]
+    loopGrader:
+      role: loop-grader
+      rounds: 3
+```
+
+Interactive Executor Stages declare no command. Their authenticated active Executor records pass-only completion against the exact immutable input packet. Mechanical Stages require an executable command; `loop_stage_run` executes it in the supplied root and derives its outcome from the exit code. Caller-supplied status or evidence does not replace execution.
+
+StageVerifier and LoopGrader are separate Stage types and separate transport surfaces. Each requires a reviewer session and agent identity distinct from the Executor. Dispatch reserves the role-specific continuation required for observation and verdict recording. Missing, unknown, overlapping, or cross-wired identity blocks closure.
+
+## Phase transitions
+
+`idle → running → verifying → completed` is the normal path. A loop may become `blocked` while waiting for an external dependency or `paused` by explicit human action. `aborted` is terminal. Resume a blocked or paused loop only after the reported condition is addressed.
+
+Use `loop_advance toPhase=verifying` only after the declared Stage inputs and evidence are ready. Use `loop_complete` only from `verifying` after every required Stage passed.
+
+## Executor Stage protocol
+
+1. From the authenticated active Executor session, call `loop_executor_stage_input({ stageId })`. It idempotently persists the pending Stage's exact `enact.loop.stage-input/v1` packet and returns `{ stageInput, identity, inputFingerprint, executorContinuationId, prompt: { text, sha256 } }` without running freshness or timeout mutation.
+2. Perform the returned exact `prompt.text` without changing the declared contract; `prompt.sha256` is already bound inside `stageInput.renderedPromptDigest`.
+3. Call `loop_executor_stage_complete` with exactly:
+
+   - `stageId`
+   - the returned `identity` (`loopRunId`, `subjectRef`, `stageId`, positive `attempt`, `contractDigest`, and `cumulativeFingerprint`)
+   - the returned `inputFingerprint`
+   - the returned `executorContinuationId`
+   - one or more immutable `evidenceRefs`
+   - a lower-case SHA-256 `outputDigest`
+   - optional `assertionResults` only for assertions mapped to this Stage; every mapped required assertion must be `met`.
+
+4. The tool derives Executor identity from the authenticated session, records only `passed`, and rejects a foreign session, continuation, input packet, Stage type, assertion, or repeat completion. It accepts no caller `status`, command, or Executor-identity field.
+
+## StageVerifier protocol
+
+1. Call `loop_stage_verifier_dispatch` for the `stage-verifier` Stage.
+2. Launch the lightweight reviewer outside Loop and bind its session through `loop_stage_verifier_register_session`.
+3. Persist observed transport through `loop_stage_verifier_observation_record`.
+4. Record only a StageVerifier verdict with `loop_stage_verifier_verdict`.
+5. On launch failure, call `loop_stage_verifier_report_spawn_failure`; on NO-GO, fix within contract and reserve a new round.
+
+## LoopGrader protocol
+
+1. Call `loop_grader_dispatch` only for the `loop-grader` Stage.
+2. Bind the final reviewer with `loop_grader_register_session` and persist observed transport with `loop_grader_observation_record`.
+3. Record only a LoopGrader verdict with `loop_grader_verdict`.
+4. On launch failure, call `loop_grader_report_spawn_failure`; on NO-GO, fix within contract and reserve a new round.
+
+For both roles, use `captureSource=relayed` when a driver relays the role envelope and `captureSource=direct` only for the bound reviewer session. A timeout or launch failure is a blocker, not a GO. No generic role selector or compatibility judgment surface exists.
+
+CLI relay equivalents are role-specific too:
+
+```text
+enact-loop stage-verifier observation-record --file <json>
+enact-loop stage-verifier verdict --file <json>
+enact-loop loop-grader observation-record --file <json>
+enact-loop loop-grader verdict --file <json>
+```
+
+## Dependencies and budgets
+
+`requires` must form an acyclic graph. A dependent stage cannot run or dispatch before all required predecessors pass.
+
+```yaml
+executionBudget:
+  maxMechanicalAttempts: 3
+  maxTotalMechanicalAttempts: 8
+  maxTotalJudgmentDispatches: 2
+failurePolicy:
+  maxMechanicalFailures: 3
+```
+
+Set every budget deliberately. A zero budget is an explicit no-op. Mechanical-attempt exhaustion blocks the loop; judgment-dispatch exhaustion refuses that dispatch. `failurePolicy.maxMechanicalFailures` is independent of the execution budget and blocks repeated failing mechanical work when configured.
+
+## Evidence and summary
+
+Use `loop_operations_snapshot` and `loop_status` for durable runtime facts. Do not read or edit runtime ledger files directly. Before closing, run `enact-loop summary write`; it records the required closure summary and fingerprint.