@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/extensions/enact-factory/skills/cmux-leader/SKILL.md

@@ -1,74 +0,0 @@
----
-name: cmux-leader
-description: "Become the cmux LEADER — spawn, root-per-repo, brief, poll, unblock, and verify parallel claude follower terminals from a neutral leader. Use when orchestrating multi-session work across sibling terminals. Followers reply via the cmux-send skill."
----
-
-# cmux-leader — you are the LEADER
-
-You run inside a cmux workspace and orchestrate **follower** claude sessions in sibling terminals.
-You coordinate; followers do the hands-on work. Keep your own context for the plan and the gates.
-
-## Hard rules (learned the hard way)
-
-- **One surface per directory.** A working tree cannot have two drivers — two followers, or leader +
-  a follower, in the same repo causes git collisions and duplicate PRs. If two must touch one repo,
-  give each its own `git worktree`.
-- **Verify cwd BEFORE launching claude.** `new-split`/`new-surface` do NOT take a working-directory
-  flag — a new pane inherits the parent's cwd. Always `cd <repo>` then confirm `pwd` *before* you run
-  `claude`, or the follower boots in the wrong repo.
-- **Lead from a NEUTRAL dir** (the common parent of all repos). The enact-loop Stop hook resolves the
-  active loop by SHELL cwd — if you `cd` into a follower's repo you inherit its Stop boulder and it
-  blocks your exit. Inspect a follower's repo with `git -C <path> …`, never a persistent `cd`.
-- **Spawn on demand.** Don't pre-create followers for ungreenlit work — idle sessions burn tokens.
-  Create one only when a concrete task is ready; `close-surface` it when its work is done.
-- **Before opening a PR, check no follower already opened one** for that branch (avoid duplicate PRs).
-- **Don't accept self-reported green** — verify against real output (tests, build, PR state).
-- **Max 5 claude sessions**, horizontal splits, one workspace.
-
-## Commands I use
-
-```bash
-# Orient (re-discover every turn; surface numbers renumber)
-cmux list-panes
-cmux list-pane-surfaces [--pane pane:N]      # name each surface
-cmux tree                                    # process/Surface tree (optional)
-
-# Read a follower
-cmux read-screen --surface surface:N [--lines 40] [--scrollback]
-
-# Drive a follower  (send → 2×Enter → ctrl+b → verify EMPTY box)
-cmux send --surface surface:N "text\n"
-cmux send-key --surface surface:N enter      # Enter #1
-cmux send-key --surface surface:N enter      # Enter #2 — one Enter often does NOT land
-cmux send-key --surface surface:N ctrl+b     # flush a QUEUED msg — no-op while only thinking
-cmux read-screen --surface surface:N --lines 6   # confirm the ❯ box is EMPTY (it landed)
-cmux send-key --surface surface:N ctrl+c     # interrupt a runaway
-
-# Spawn a follower (root it correctly, THEN launch claude)
-cmux new-split right --focus false                 # -> surface:N
-cmux send --surface surface:N "cd /abs/repo && pwd\n"
-cmux read-screen --surface surface:N --lines 5     # CONFIRM pwd == the repo
-cmux send --surface surface:N "claude\n"
-
-# Close a finished/dead follower
-cmux close-surface --surface surface:N
-```
-
-## Messaging — always use the cmux-send skill
-
-Every follower briefing must tell the follower to use the **cmux-send** skill. Each message: prefix
-`[LEADER] to [FOLLOWER-<name>] `, end with `Respond back once you are done with using prefix
-"[FOLLOWER-<name>] to [LEADER] "`. After every `send`, fire **two** `send-key … enter` (one Enter
-often does not land) + one `ctrl+b`, then `read-screen` and confirm the `❯` box is **empty** — an
-empty inbox is the only proof it submitted.
-
-## Leader loop
-
-1. **Shard** the goal into independent slices, one repo per follower.
-2. **Spawn & brief** — split → `cd <repo>` (verify pwd) → `claude` → self-contained briefing (role,
-   scope, exit criteria, "use cmux-send to reply, report in one line").
-3. **Poll on a ~15-min cadence** — never go idle while followers run. Re-discover topology, `read-screen`
-   each, classify (working / idle-done / parked / blocked / ctx≥80%), and act: parked → `send-key enter`
-   ×2 + `ctrl+b`, then verify the `❯` box is empty; ctx≥80% → tell it to `/compact`; blocked → answer;
-   idle-done → assign next or `close-surface`.
-4. **Verify & gate** — confirm real output before treating a slice as green; drive merges from the leader.

package/extensions/enact-factory/skills/cmux-send/SKILL.md

@@ -1,50 +0,0 @@
----
-name: cmux-send
-description: "How to correctly message a cmux surface — the send→verify→enter protocol and the [from] to [to] envelope. Use whenever messaging a cmux session (leader→follower or follower→leader)."
----
-
-# cmux-send — message a cmux surface correctly
-
-Two parts are easy to get wrong: **submitting** the message and **wrapping** it.
-
-## 1. Submit protocol (send → 2×Enter → ctrl+b → verify empty box)
-
-```bash
-cmux send --surface surface:N "<one-line message>\n"   # \n = Enter (often not enough alone)
-cmux send-key --surface surface:N enter                 # Enter #1
-cmux send-key --surface surface:N enter                 # Enter #2 — one Enter frequently does NOT land
-cmux send-key --surface surface:N ctrl+b                 # flush if a bash command is running
-cmux read-screen --surface surface:N --lines 6          # VERIFY: the ❯ box is EMPTY (message left)
-```
-
-- **Send TWO Enter keys, not one.** A single `send-key … enter` (or the trailing `\n`) frequently
-  fails to submit while the follower is booting or thinking — the text parks in the `❯` box. Two
-  Enters is the reliable default; a leftover empty Enter is harmless.
-- **Then one `ctrl+b`.** It flushes a *queued* message only when the follower has a **running bash
-  command** to background; while it is purely thinking `ctrl+b` is a harmless no-op. Sending it
-  unconditionally costs nothing and frees the queue the moment a command is running.
-- **Always confirm an EMPTY inbox.** `read-screen` after submitting and check the `❯` box is clear
-  (no parked text, no "Press up to edit queued messages"). An empty box is the only proof it landed —
-  do not assume submission, verify it.
-- **To submit a parked message, `send-key … enter` (×2), NOT `ctrl+b` alone.** `ctrl+b` does nothing
-  while the follower is only thinking.
-- **One line only.** Every literal `\n` submits, so a multi-line prompt fires early and fragments.
-- `read-screen` takes `--surface`, not `--pane`.
-
-## 2. Message envelope (every message)
-
-- **Start with:** `[<from-surface-name>] to [<to-surface-name>] `
-- **End with:** `Respond back once you are done with using prefix "[<to-surface-name>] to [<from-surface-name>] "`
-
-Surface names are the human labels (e.g. `LEADER`, `FOLLOWER-enact-wiki`), not `surface:N`. Map them
-with `cmux list-pane-surfaces [--pane pane:N]`.
-
-### Example (leader → follower)
-
-```bash
-cmux send --surface surface:3 "[LEADER] to [FOLLOWER-enact-wiki] <instruction on one line>. Respond back once you are done with using prefix \"[FOLLOWER-enact-wiki] to [LEADER] \"\n"
-cmux send-key --surface surface:3 enter      # ×2 — one Enter often does not land
-cmux send-key --surface surface:3 enter
-cmux send-key --surface surface:3 ctrl+b      # flush if a command is running (no-op while thinking)
-cmux read-screen --surface surface:3 --lines 6   # confirm the ❯ box is EMPTY
-```

package/extensions/enact-factory/skills/committee/SKILL.md

@@ -1,80 +0,0 @@
----
-name: committee
-description: >-
-  Two contrasting-vendor agents root-cause a stuck, blocked, or looping WorkItem
-  and produce a plan. Use when asked to "convene a committee", "root-cause this",
-  "the item is stuck/looping", "debate the approach", or when the driver's loop
-  stalls and needs a way forward. Produces a plan that feeds `plan` / `drive-loop`;
-  may propose a different approach. Read + plan only — no implementation.
-metadata:
-  author: Amsterdam Data Labs
-  version: 1.0.0
----
-
-# committee
-
-> **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>`.
-> 3. Factory planning artifacts go under `~/.enact/factory/projects/<key>/…`.
-
-Two **contrasting-vendor** agents independently diagnose a stuck WorkItem, then
-their findings are reconciled into a single forward plan. Heavier than
-[`advisor`](../advisor/SKILL.md) (one strong opinion); this is the **strong escalation** for
-architecture decisions and risky or irreversible changes. Use when an item is **stalled, blocked,
-or looping** and the path is unclear, OR when a risky migration / architecture decision requires
-two independent strong perspectives before proceeding.
-
-## When to escalate to committee
-
-- Architecture decisions (interface shape, system redesign, approach selection)
-- Risky or irreversible migrations (data, schema, breaking API changes)
-- Items blocked at the loop level where `advisor`'s single opinion is insufficient
-- Branch policy / CI strategy changes with wide blast radius
-
-## Model selection
-
-Committee always uses **opus 4.8 + gpt-5.5** — the two strongest available models from different
-vendors. This pairing provides genuine diversity: one OpenAI-lineage, one Anthropic-lineage.
-
-## Boundaries (hard)
-
-- **Diagnose + plan only.** No code changes, no commits, no board mutation. The
-  output is a plan; implementation happens later via `drive-loop`.
-- **Two distinct vendors: opus 4.8 + gpt-5.5.** Both members run on models that are different
-  from each other and from the executor (genuine diversity). If two distinct models are
-  unavailable, run what you can and STATE the reduced diversity loudly — do not
-  pretend two same-model passes are a committee.
-- **Reconcile honestly.** If the two disagree, surface the disagreement and the
-  decisive evidence; do not paper over it.
-
-## Sequence
-
-1. Assemble the dossier: `factory_workitem_get` (goal, acceptance, current
-   state, `blockedBy`), the loop status / stall reason, recent failing output.
-2. Spawn TWO agents on **opus 4.8 + gpt-5.5**, with contrasting lenses:
-
-   ```
-   Agent({ subagent_type: "critic",    model: "claude-opus-4-8", prompt: "<dossier> — root-cause why this is stuck; what is the real blocker?" })
-   Agent({ subagent_type: "architect", model: "gpt-5.5",         prompt: "<dossier> — is the current approach right? propose the smallest viable path to closure." })
-   ```
-
-3. Reconcile their findings into ONE plan: the root cause, the chosen approach
-   (note if it differs from the original), and ordered next steps mapped to
-   loop stages.
-4. Hand the result to `$plan` so it is persisted as a new timestamped
-   `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>.md` artifact rather
-   than left only in chat output.
-
-## Output
-
-`{ rootCause, approach (kept | changed + why), steps[], dissent? , members[] }`
-where `members[]` shows the two distinct models. The `steps[]` are ready to feed
-[`plan`](../plan/SKILL.md) or directly into a [`drive-loop`](../drive-loop/SKILL.md)
-contract.
-
-## Related
-
-- [`advisor`](../advisor/SKILL.md) — when one opinion is enough.
-- [`plan`](../plan/SKILL.md) — turn the committee's steps into an execution plan.
-- [`drive-loop`](../drive-loop/SKILL.md) — execute the chosen path to closure.

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

@@ -1,68 +0,0 @@
----
-name: deep-interview
-description: "Intent-first clarification loop for vague, risky, or product-heavy work before planning or execution."
----
-
-# Deep Interview
-
-> **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-evolve-a38d1e`).
-> 3. Factory planning artifacts go under `~/.enact/factory/projects/<key>/…`.
-
-## 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
-- **never overwrite a prior requirements file in place** — each durable snapshot gets a fresh `YYMMDDHH` prefix
-
-## Workflow
-
-1. Inspect the repo for brownfield context if relevant.
-2. Capture the current hypothesis in a **new** `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>-requirements.md` (e.g. `plans/26062101-auth-requirements.md`). Resolve `<key>` from `~/.enact/workspaces.json`; get the timestamp prefix via `date +%y%m%d%H`.
-3. Run a one-question loop until these are explicit:
-   - goal
-   - in-scope
-   - out-of-scope
-   - acceptance criteria
-   - decision boundaries
-4. During the interview, revise the **same** requirements file for the current pass only. A new interview session or phase restart writes a **new** timestamped file instead of editing an old one.
-5. Hand off to `$plan` when the spec is concrete. `$plan` resolves the latest `*-requirements.md` per its Active Artifact Resolution rules.
-
-## 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

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

@@ -1,394 +0,0 @@
----
-name: drive-loop
-description: >-
-  Teaches factory how to drive a WorkItem through the enact-loop contract runner
-  using subagents. Use when delivering a work-item, running the loop, driving a
-  work-item to closure, executing the loop contract, dispatching grader subagents,
-  or integrating factory with enact-loop. Triggers on "drive a work-item",
-  "run the loop", "deliver work-item via loop", "loop contract", "grader dispatch",
-  "loop closure".
-metadata:
-  author: Amsterdam Data Labs
-  version: 1.0.0
----
-
-# drive-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>`.
-> 3. Factory artifacts go under `~/.enact/factory/projects/<key>/…`; loop runtime state and closure summaries go under `~/.enact/loop/projects/<key>/…`.
-
-## Model
-
-**enact-loop** is a domain-neutral contract-runner. **enact-factory** is the
-orchestrator. The relationship is process-boundary integration only — no
-cross-repo imports, no shared types. Integration is via the `enact-loop` MCP
-tools or CLI.
-
-```
-Factory builds CONTRACT (JSON)
-  → hands to enact-loop (MCP: loop_start | CLI: enact-loop)
-  → loop drives each STAGE to closure
-  → boulder (Stop hook) blocks the agent until every required stage has a PASS
-     and every judgment stage has an independent GO verdict
-  → CONTROL RETURNS TO FACTORY
-  → factory calls pushLoopClosure (enact-factory MCP/CLI)
-  → lifecycle booleans advance → WorkItem progresses on the board
-```
-
-No cross-repo imports. The integration boundary is the `enact-loop` MCP tools
-and the `enact-factory` MCP/CLI.
-
----
-
-## Contract Schema
-
-Embed the contract as plain JSON when calling `loop_start`. All fields are
-required unless marked optional.
-
-```json
-{
-  "id": "<uuid>",
-  "name": "<human-readable name>",
-  "stages": [
-    {
-      "id": "<stage-id>",
-      "name": "<stage name>",
-      "type": "mechanical | judgment",
-      "required": true,
-      "command": "<shell command>",
-      "grader": {
-        "role": "architect | critic | code-reviewer | verifier",
-        "model": "<model-id — MUST differ from executor>",
-        "fallbackModels": ["<optional fallback models on 529/overload>"],
-        "harness": "paseo | subagent",
-        "rounds": 1
-      },
-      "passCriteria": "<optional plain-text pass condition>"
-    }
-  ]
-}
-```
-
-### Rules
-
-| Stage type | Required fields | Pass condition |
-|------------|----------------|----------------|
-| `mechanical` | `command` | exit-0 from the command |
-| `judgment` | `grader` (with `role`) | independent GO verdict |
-
-- `grader.model` **MUST** differ from the executor model. Cross-vendor is
-  preferred (e.g. executor = codex, grader = claude-opus-4-8). No self-grading.
-- `grader.fallbackModels` — optional ordered list tried on re-dispatch after spawn failure
-  (`loop_grader_report_spawn_failure` on 529/overload). Does not consume the round budget.
-- `requires` — stages run in contract order; `loop_grade` fails loudly if prerequisites are not
-  passed: `Cannot pass stage "X": requires stages not yet passed: …`.
-- `required: true` → stage must pass before closure is declared.
-- Closure = all required stages passed.
-
----
-
-## Workflow
-
-### Step 1 — Build the contract from the WorkItem
-
-Inspect the WorkItem's `closureRequirements`. Map each requirement to a stage:
-
-- Deterministic check → `type: mechanical`, set `command`.
-- Subjective quality gate → `type: judgment`, set `grader`.
-
-> **Authoring note — mechanical stage commands:**
-> The `tests` stage command must mirror CI's containerized/Linux-parity
-> environment (e.g. `bash scripts/ci-local.sh`), not a bare host run. A
-> host-passing suite can still fail the CI Linux agent due to `HOME`/path
-> divergence. Where the project exposes a `typecheck:tests` script, include it
-> — as its own mechanical stage or folded into the typecheck command
-> (`npm run typecheck && npm run typecheck:tests`) — so test-file type
-> regressions do not slip past.
-
-### Step 2 — Start the loop
-
-```
-MCP:  loop_start({ contract: <contract JSON> })
-CLI:  enact-loop --contract ./contract.json
-```
-
-The loop runner takes ownership of the session's Stop hook (the boulder). The
-agent cannot stop until the loop signals closure.
-
-### Step 3 — Drive mechanical stages
-
-For each mechanical stage the loop surfaces (after any `requires` preconditions pass):
-
-1. Call `loop_grade({ stageId, timeoutMs? })` — the engine runs the stage `command` in the loop
-   root cwd and records pass/fail from exit code.
-2. Caller-supplied `status`, `pass`, or `output` are **rejected** — do not run the command
-   separately and self-report.
-
-Repeat until the stage passes or the loop escalates to a retry/fail policy.
-
-### Step 4 — Drive judgment stages (INDEPENDENT GRADER SUBAGENT)
-
-For each judgment stage:
-
-1. Call `loop_grader_dispatch({ stageId, childSessionId?, childAgentId? })` — mints `continuationId`.
-2. Spawn an **independent subagent** on a **different model** (never the executor's model or
-   session). Pass grader role metadata so the grader MCP session is gated:
-   `_meta.enactLoop: { sessionRole: "grader", sessionId, continuationId }` or env vars
-   `ENACT_LOOP_SESSION_ROLE=grader`, `ENACT_LOOP_CONTINUATION_ID=<uuid>`.
-
-   ```
-   Agent({
-     subagent_type: "<role>",   // architect | critic | code-reviewer | verifier
-     model: "<grader model>",   // MUST differ from executor
-     prompt: "<artifact + passCriteria + GO/NO-GO instruction>"
-   })
-   ```
-
-3. The grader reviews and returns a verdict envelope (GO/NO-GO + evidence). Grader child sessions
-   have **no closure authority** — runtime rejects dispatch/resume/complete/grade/summary tools.
-   Graders may only call `loop_grader_verdict`, `loop_status`, `loop_stop_evaluate`.
-4. On grader spawn failure (529/overload): `loop_grader_report_spawn_failure({ continuationId, error })`
-   then re-dispatch (auto-selects next `fallbackModels` entry).
-5. **Driver-relayed (default):** executor records via `loop_grader_verdict` with
-   `captureSource: "relayed"` and the minted `continuationId`.
-   **Direct:** grader child may call `loop_grader_verdict` with `captureSource: "direct"`.
-   Without dispatch → `E_UNKNOWN_GRADER_SESSION`. Grader timeout → `grader-unavailable` blocker.
-
-> **Paseo graders — use `factory_paseo_grader_run` for structured capture.** When a judgment
-> stage runs on Paseo (`harness: "paseo"`, or `grader.dispatchTool: "factory_paseo_grader_run"`),
-> the factory MCP tool `factory_paseo_grader_run` runs the grader with
-> `paseo run --output-schema --json --wait-timeout` so **stdout is the validated `{verdict,
-> evidence}` object** — no `paseo logs | grep`. It bakes in the per-provider `--mode`
-> (codex `auto-review` so on-request approvals don't block, kimi `auto`, cursor/opencode default) and recovers the actual resolved model via
-> `paseo ls --label` / `inspect`, which you relay as `graderModelActual` on `loop_grader_verdict`.
-> Full design: `enact-loop/docs/design/2026-06-22-paseo-verdict-capture.md`.
-
-The boulder prevents the session from completing until every judgment stage has a GO from an
-independent grader.
-
-### Step 5 — Closure → factory lifecycle advance
-
-When all required stages pass (executor/driver owns closure):
-
-1. Run `enact-loop summary write` (driver only — graders cannot author summaries).
-2. Call `loop_complete` via MCP.
-3. Treat `~/.enact/loop/projects/<key>/state/` as the active surface only.
-   The next `loop_start` archives the prior terminal loop into
-   `~/.enact/loop/projects/<key>/archive/<loop-id>-<contract-id>/`, including
-   `loop.json`, `closure-manifest.json`, `grader-sessions.json`,
-   `summary-current.json`, and the loop's timestamped summaries.
-4. Call `pushLoopClosure` (enact-factory MCP/CLI) with the loop's closure record.
-5. Factory maps closure → lifecycle booleans → WorkItem advances on the board.
-
-**Branch base:** `integration`. **No `git stash` during an active loop** — stash invalidates
-worktree fingerprints and stale verdicts.
-
-**Stacked-wave squash merges:** feature PRs squash into `integration`; later waves may conflict in
-shared barrel/test/snapshot files. When the wave branch is a superset of `integration`, resolution
-is usually `git checkout --ours -- <paths>` on those shared files — do not panic.
-
-**Summary + active loop:** CLI and MCP must share the same workspace root. `summary write` stamps
-`summary-current.json` keyed to active `loop.id`. If closure fails with loop-id mismatch, re-run
-summary write from the same cwd as MCP (`enact-loop mcp .`).
-
----
-
-## Agent Roster (grader candidates)
-
-Use these roles as `grader.role`. Each must run on a model/session distinct
-from the executor.
-
-| Role | Use for |
-|------|---------|
-| `architect` | design correctness, interface shape, system fit |
-| `critic` | adversarial quality and risk review |
-| `code-reviewer` | implementation correctness, test coverage, style |
-| `verifier` | evidence that the deliverable meets acceptance criteria |
-| `explore` | read-only scoping (typically pre-grader, not a grader itself) |
-| `planner` | plan review (judgment on the plan artifact, not execution) |
-
----
-
-## Tiered contract shaping + grader ops
-
-> This matters: in a validated 3-wave run, the two-judgment Frontend/UI contract shape
-> and cross-vendor model-distinct graders caught FIVE real defects (faked-AA contrast,
-> missing focus indicator, consumer-prop a11y override, untested variant, theme flash)
-> that all mechanical gates passed.
-
-### Shape the contract by tier
-
-| Tier | Mechanical stages | Judgment stages |
-|---|---|---|
-| Frontend / UI | tests, typecheck, lint, build, a11y-scan | `code-review` (impl correctness) + `verify` (acceptance criteria met) |
-| Backend / logic | tests, typecheck, lint | `code-review` (+ optional `verify` for high blast-radius) |
-| Docs | build | ONE lighter `review` (e.g. `critic` for scope fidelity) |
-| Infra / CI | pipeline-validation, tests | architecture-fit + pipeline-correctness |
-
-Frontend/UI gets **two** judgment stages because visual, a11y, and consumer-API
-surfaces require both implementation review and evidence the deliverable meets
-acceptance criteria in a real surface.
-
-### Paseo grader operational notes
-
-#### Grader selection — cheap default + risk-based escalation
-
-**minimax M3** (opencode) and **kimi K2.7** are the default cheap graders for routine judgment
-(~80% of grading). Escalate to a strong cross-vendor grader when:
-- Frontend / UI a11y or visual / UX judgment → `advisor` = **gpt-5.5** (or opus 4.8 if executor was codex)
-- Security, public API / barrel / contract changes → **opus 4.8**
-- Architecture decisions / risky or irreversible migrations → `committee` (opus 4.8 + gpt-5.5)
-
-**Independence (hard gate — model-distinct):** grader model ≠ executor model. minimax M3 / kimi K2.7
-are vendor-distinct from both sonnet and codex workers, so default cheap graders are always
-independent. On escalation keep cross-vendor: grade codex work with **opus** (not gpt-5.5 — same
-OpenAI lineage); grade sonnet work with gpt-5.5 / opus / minimax / kimi.
-
-#### Permission modes (REQUIRED — non-default modes prevent stall/empty sessions)
-
-| Provider | Paseo flag | Notes |
-|---|---|---|
-| `codex` | `--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 on an approval (e.g. a cargo/network fetch during build verification). `--mode bypass` is rejected by codex |
-| `cursor` | default / agent | `--mode bypass` is a claude mode, NOT cursor's — previously documented wrong |
-| `kimi` | `--mode auto` | Same as codex |
-| `opencode` (minimax M3) | default | No special mode flag needed |
-
-Codex mode enum (authoritative): `read-only` · `auto` · `auto-review` · `full-access`. The grader
-stays read-only BY PROMPT; `auto-review` only governs approval handling and composes with
-`--output-schema` verdict capture. Flip a running grader with `paseo agent mode <id> auto-review`.
-
-#### Sonnet-executor caveat
-
-`cursor` (`cursor/claude-sonnet-4-6`) is NOT model-distinct from a sonnet executor.
-Use **minimax M3** or **kimi K2.7** as the clean default cheap graders for sonnet-executor work;
-escalate to opus 4.8 / gpt-5.5 for high-risk judgment. Reserve `cursor` for opus-tier executors.
-
-#### Verdict capture — structured `--output-schema`, not log-scraped
-
-Dispatch the grader 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). On the codex provider, `--mode auto-review` keeps on-request approvals from
-blocking the grader (read-only stays enforced by prompt). Recover actual grader model + cost via
-`paseo ls -a --label continuation=<cid> --json` + `paseo inspect <id> --json`. Watch live by
-recovering the id by label then `paseo attach <id>`.
-Design doc: `enact-loop/docs/design/2026-06-22-paseo-verdict-capture.md`.
-
-#### fallbackModels rotation on spawn failure
-
-1. Record the failure: `loop_grader_report_spawn_failure({ continuationId, error })`.
-2. Re-dispatch: `loop_grader_dispatch` auto-selects the next `fallbackModels` entry.
-3. With no `model`, re-dispatch auto-advances `fallbackModels`; pass an explicit `model` to **pin
-   a specific grader** (the override is honored verbatim, not consumed by the pointer). Record the
-   verdict under the minted `continuationId` and set `graderModelActual` to the model that actually
-   ran. Independence holds as long as the actual grader model ≠ executor model.
-
-#### Verdict relay when structured capture is unavailable
-
-Preferred: call `factory_paseo_grader_run` (wraps `paseo run --output-schema <verdict.json>
---json --wait-timeout --label continuation=<cid>`) — stdout is the validated `{verdict, evidence}`
-object, no log parsing — and it returns the resolved `graderModelActual` for provenance.
-Fallback (provider without schema support): `paseo wait <id> --json` and read `.message` (the final
-assistant text is guaranteed there) — never raw `paseo logs` scraping.
-
----
-
-## Worked Example — Bug Delivery
-
-```json
-{
-  "id": "wi-2041-bug-null-crash",
-  "name": "Bug WI-2041: null crash in session handler",
-  "stages": [
-    {
-      "id": "unit-tests",
-      "name": "Unit tests pass",
-      "type": "mechanical",
-      "required": true,
-      "command": "cd codex-rs && cargo test --features codex-cli/enact --no-fail-fast -- --test-threads=2",
-      "passCriteria": "exit 0, no test failures"
-    },
-    {
-      "id": "regression-evidence",
-      "name": "Regression test covers the crash path",
-      "type": "mechanical",
-      "required": true,
-      "command": "grep -r 'null_session' codex-rs/src --include='*.rs' -l",
-      "passCriteria": "at least one file references the regression path"
-    },
-    {
-      "id": "code-review",
-      "name": "Independent code review: GO on fix correctness",
-      "type": "judgment",
-      "required": true,
-      "grader": {
-        "role": "code-reviewer",
-        "model": "claude-opus-4-8",
-        "harness": "subagent",
-        "rounds": 1
-      },
-      "passCriteria": "fix is minimal, regression is covered, no obvious regressions introduced"
-    },
-    {
-      "id": "verifier-signoff",
-      "name": "Verifier confirms acceptance criteria met",
-      "type": "judgment",
-      "required": true,
-      "grader": {
-        "role": "verifier",
-        "model": "claude-opus-4-8",
-        "harness": "subagent",
-        "rounds": 1
-      },
-      "passCriteria": "WI-2041 acceptance criteria satisfied; crash path eliminated"
-    }
-  ]
-}
-```
-
-**Execution trace:**
-
-1. Factory builds this contract from WI-2041's `closureRequirements`.
-2. `loop_start({ contract })` — boulder active.
-3. Loop surfaces `unit-tests` → `loop_grade({ stageId: "unit-tests" })` — engine runs cargo test.
-4. Loop surfaces `regression-evidence` → `loop_grade({ stageId: "regression-evidence" })`.
-5. Loop surfaces `code-review` →
-   `loop_grader_dispatch({ stageId: "code-review" })` →
-   spawn `code-reviewer` subagent on `claude-opus-4-8` →
-   driver relays GO via
-   `loop_grader_verdict({ stageId: "code-review", continuationId, verdict: "GO", evidence: "...", captureSource: "relayed", ... })`.
-6. Loop surfaces `verifier-signoff` →
-   `loop_grader_dispatch({ stageId: "verifier-signoff" })` →
-   spawn `verifier` subagent → driver relays GO via `loop_grader_verdict`.
-7. All required stages passed → `enact-loop summary write` → `loop_complete`.
-8. Factory calls `pushLoopClosure(closureRecord)` → WI-2041 advances to Done.
-
----
-
-## Anti-patterns
-
-- **Never self-grade judgment stages.** Grader must run on a different model and session.
-- **Never self-report mechanical passes.** Use `loop_grade({ stageId })` — the engine runs the command.
-- **Never stash during an active loop.** Stash invalidates worktree fingerprints.
-- **Never skip the boulder.** Do not call loop completion tools unless all
-  required stages have passed — the boulder enforces this, but do not attempt
-  to work around it.
-- **Never import enact-loop types directly.** The boundary is MCP/CLI only.
-  No shared module imports between factory and loop.
-- **Judgment without a grader spec is invalid.** Every `type: judgment` stage
-  must have a `grader` field with at least `role` set.
-
----
-
-## Related Skills
-
-- `workitem-triage` — read-only triage of the WorkItem board (use before
-  building the contract to confirm the WorkItem is ready for delivery).
-- `azdo-ci-strategy` — branch/PR/release strategy for integrating delivered
-  work into `integration` and `main`.
-- `testing-strategy` — when a mechanical stage runs tests, use this skill to
-  pick the right test mode.
-
-See `references/contract-schema.md` for the full contract schema reference.