@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

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 default, opencode MiniMax M3 `--mode plan --thinking on`) 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** (`minimax-coding-plan/MiniMax-M3`, always `--thinking on`) 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.6 Sol High** (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.6 Terra)
-
-**Independence (hard gate — model-distinct):** grader model ≠ executor model. MiniMax M3
-(`minimax-coding-plan/MiniMax-M3`, always `--thinking on`) / 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.6 Sol — same
-OpenAI lineage); grade sonnet work with GPT-5.6 Sol High / 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) | `--mode plan --thinking on` | Required for every MiniMax M3 dispatch |
-
-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** (`minimax-coding-plan/MiniMax-M3`, always `--thinking on`) or **kimi K2.7** as the clean default cheap graders for sonnet-executor work;
-escalate to opus 4.8 / GPT-5.6 Sol High 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.

package/extensions/enact-factory/skills/drive-loop/references/contract-schema.md

@@ -1,127 +0,0 @@
-# Contract Schema Reference
-
-Full schema for the JSON object passed to `loop_start`. This is a progressive
-disclosure supplement to `SKILL.md`.
-
----
-
-## Contract (root)
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string (uuid) | yes | Stable unique identifier. Use the WorkItem id or a derived uuid. |
-| `name` | string | yes | Human-readable name shown in loop progress output. |
-| `stages` | Stage[] | yes | Ordered list of stages. Mechanical stages run first; judgment stages may interleave. |
-
----
-
-## Stage
-
-| Field | Type | Required when | Description |
-|-------|------|---------------|-------------|
-| `id` | string | always | Stable slug. Referenced by `loop_grade` and `loop_grader_verdict`. |
-| `name` | string | always | Human-readable label. |
-| `type` | `"mechanical" \| "judgment"` | always | Determines which fields are used and how pass is determined. |
-| `required` | boolean | always | `true` → must pass before closure. `false` → informational only. |
-| `requires` | string[] | optional | Stage ids that must pass before this stage may run. |
-| `command` | string | mechanical | Shell command run by the engine via `loop_grade` in loop root cwd. Exit 0 = pass. |
-| `grader` | GraderSpec | judgment | Specification for the independent grader subagent. |
-| `passCriteria` | string | optional | Plain-text description of what constitutes a pass. Included in grader prompts. |
-
----
-
-## GraderSpec
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `role` | `"architect" \| "critic" \| "code-reviewer" \| "verifier"` | yes | Determines the subagent type spawned. |
-| `model` | string | recommended | Model ID for the grader. **Must differ from the executor model.** Cross-vendor preferred. Omit only if the harness selects automatically. |
-| `harness` | `"paseo" \| "subagent"` | optional | How to dispatch. Default: `subagent`. Use `paseo` when the grader needs multi-step tool access. |
-| `dispatchTool` | string | optional | Factory tool the driver uses to run a Paseo grader and capture a structured verdict — `"factory_paseo_grader_run"` (runs `paseo run --provider <graderModel> --mode auto-review --output-schema --json`, returns `{verdict, evidence}` + `graderModelActual`). On the codex provider `--mode auto-review` routes on-request approvals through the auto-reviewer subagent so the grader doesn't BLOCK (read-only stays enforced by prompt). Replaces `paseo logs` scraping. |
-| `rounds` | integer | optional | Number of independent grading rounds before aggregating. Default: `1`. |
-| `timeoutMs` | integer | optional | Grader session timeout in ms (default 30 min). Timeout → `grader-unavailable` blocker. |
-
----
-
-## Validation Rules
-
-1. Every `type: judgment` stage **must** have `grader` with `role` set.
-2. Every `type: mechanical` stage **must** have `command` set.
-3. `grader.model` must differ from the executor's model — enforced at
-   `loop_grader_dispatch` time.
-4. At least one stage must be `required: true`, or the contract is trivially
-   closed and should not be submitted to the loop.
-5. Stage `id` values must be unique within the contract.
-6. `requires` references must point to existing stage ids; cycles are rejected.
-7. **(Hard requirement #9 — tests stage Linux parity)** The `tests` stage
-   `command` **must** invoke a Linux-parity / containerized runner (e.g.
-   `bash scripts/ci-local.sh`) — not a bare host `npm test`. A host suite can
-   pass green while the same deliverable fails the CI Linux agent due to
-   `HOME`/path divergence.
-8. **(Rule #7 — typecheck:tests)** When the project has a separate test-file
-   typecheck script (`typecheck:tests`), it **must** be included — either as its
-   own mechanical stage or folded into the typecheck stage command (e.g.
-   `npm run typecheck && npm run typecheck:tests`). Omitting it allows test-file
-   type regressions to slip past undetected.
-
----
-
-## Closure Definition
-
-A contract reaches **closure** when:
-
-- Every stage where `required: true` has status `PASSED`.
-- `PASSED` means:
-  - `mechanical`: `loop_grade({ stageId })` ran the command and exit code was 0.
-  - `judgment`: `loop_grader_verdict` recorded `verdict: "GO"` with a valid
-    dispatch-minted `continuationId` (`captureSource`: `relayed` or `direct`).
-- Executor/driver authored a current closure summary via `enact-loop summary write`.
-- `loop_complete` called from phase `verifying`.
-
-Worktree fingerprint drift invalidates stale `passed` verdicts. `loop_retarget`
-preserves verdicts only when `id + type + worktreeFingerprint` match.
-
-Optional stages (`required: false`) do not block closure but their results
-are included in the closure record returned to factory.
-
----
-
-## MCP Tool Reference
-
-| Tool | When to call | Key params |
-|------|-------------|------------|
-| `loop_start` | Once, at the start of the delivery | `{ contract: <Contract JSON> }` |
-| `loop_grade` | For each mechanical stage | `{ stageId, timeoutMs? }` — engine runs command; rejects `status`/`evidence` |
-| `loop_grader_dispatch` | Before spawning the grader subagent | `{ stageId }` → `continuationId` |
-| `loop_grader_verdict` | After grader returns verdict envelope | `{ stageId, continuationId, verdict, evidence, graderAgentId, graderSessionId, captureSource? }` |
-
-Factory-side tool (after loop closure):
-
-| Tool | When to call | Key params |
-|------|-------------|------------|
-| `pushLoopClosure` | Once, after loop signals closure | `{ closureRecord }` |
-
----
-
-## Example: Minimal Contract (single mechanical stage)
-
-```json
-{
-  "id": "wi-9999-minimal",
-  "name": "Minimal: lint only",
-  "stages": [
-    {
-      "id": "lint",
-      "name": "Lint passes",
-      "type": "mechanical",
-      "required": true,
-      "command": "cargo clippy --workspace -- -D warnings"
-    }
-  ]
-}
-```
-
-## Example: Full Contract (mixed mechanical + judgment)
-
-See `SKILL.md` worked example (WI-2041 Bug Delivery) for a four-stage
-mixed contract with two mechanical and two judgment stages.

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

@@ -1,75 +0,0 @@
----
-name: handoff
-description: >-
-  Delegate a WorkItem to a detached agent with a self-contained briefing, and
-  record the assignment on the factory board. Use when asked to "hand off",
-  "delegate this work-item", "assign to an agent", "spin up a detached agent for
-  this item", or when the driver wants to fan out an independent item rather than
-  drive it inline. The factory tracks the handoff via factory_assignment_record.
-metadata:
-  author: Amsterdam Data Labs
-  version: 1.0.0
----
-
-# handoff
-
-> **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>/…`; loop runtime state and closure summaries go under `~/.enact/loop/projects/<key>/…`.
-
-Package a WorkItem into a briefing complete enough that a fresh detached agent
-can deliver it without the driver's context, launch that agent, and **record the
-assignment on the board**. The board-tracking (`factory_assignment_record`) is
-the factory value-add the generic delegate pattern lacks.
-
-## Boundaries (hard)
-
-- **The briefing must be self-contained.** The detached agent does not share
-  your context — everything it needs goes in the brief. A handoff that assumes
-  the receiver "knows what we discussed" is a defect.
-- **Record every handoff.** Call `factory_assignment_record` so the board
-  reflects the assignment. An untracked detached agent is invisible work — fail
-  loud rather than launch without recording.
-- **Scope unchanged.** Handoff delegates the item as-is; it does not toggle
-  repos, change scope, or split the item. Out-of-scope discoveries → new
-  WorkItem (the receiver follows the same rule).
-- **The receiver still drives the loop** (its own contract + cross-vendor
-  grader). Handoff delegates the work, not the gates. When the receiver
-  dispatches a grader via Paseo on the codex provider, it passes
-  `--mode auto-review` so the grader's on-request approvals don't block (the
-  grader stays read-only by prompt); see `drive-loop`.
-
-## Sequence
-
-1. `factory_workitem_get` → build the self-contained briefing:
-   - goal + acceptance criteria + closure requirements
-   - lifecycle state + next required boolean
-   - blockers / dependencies (must be satisfied before handoff)
-   - branch base (`integration`) + worktree, relevant files/paths
-   - the loop contract to run (or instruction to build one via `drive-loop`)
-   - latest timestamped plan / verification / requirements artifact paths when present
-   - current loop closure summary path (`summary-current.json` / `enact-loop summary show`) when resuming an active loop
-2. `EnterWorktree` to isolate the receiver's workspace.
-3. Launch the receiver as a **detached agent** carrying the briefing (a detached
-   subagent, or via the factory's Paseo dispatch) with `notifyOnFinish`; do not
-   poll it.
-4. **`factory_assignment_record({ workItemId, repoRoot, host, operatorLane,
-   dispatcher, paseoAgentId, paseoWorktree, status: 'active' })`** — register the
-   assignment so the board tracks it. (To update its state later — e.g.
-   `paseoStatus`, `status: 'completed'` — call `factory_assignment_record` again
-   with the returned `assignmentId`.)
-
-## Output
-
-`{ workItemId, assignmentId, branch, worktree, recorded: true }`. If
-`factory_assignment_record` fails, treat the handoff as failed — surface it and
-do not leave an unrecorded detached agent running.
-
-## Related
-
-- [`work-with-workitem`](../work-with-workitem/SKILL.md) — the delivery lane the
-  receiver runs.
-- [`drive-loop`](../drive-loop/SKILL.md) — the contract the receiver drives.
-- [`autonomous-runner`](../autonomous-runner/SKILL.md) — the driver that may hand
-  off independent items instead of driving them inline.

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

@@ -1,59 +0,0 @@
----
-name: hyperplan
-description: "Three-round adversarial planning debate that hands a distilled bundle to $plan instead of writing the final plan directly."
----
-
-# Hyperplan
-
-> **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. Loop artifacts go under `~/.enact/factory/projects/<key>/…`.
-
-## 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/factory/projects/<key>/hyperplan/<sessionId>/<YYMMDDHH>-round-1.md`
-- `~/.enact/factory/projects/<key>/hyperplan/<sessionId>/<YYMMDDHH>-round-2.md`
-- `~/.enact/factory/projects/<key>/hyperplan/<sessionId>/<YYMMDDHH>-round-3.md`
-
-Resolve `<key>` from `~/.enact/workspaces.json`; get the timestamp prefix via `date +%y%m%d%H`. **Append-only:** each debate run writes fresh round files; never overwrite prior `YYMMDDHH-round-*.md` artifacts.
-
-## 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.
-`$plan` must read the latest `hyperplan/<sessionId>/<YYMMDDHH>-round-*.md` files before writing new timestamped plan artifacts.
-
-## 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
-
-## Activation
-
-Invoke with `$hyperplan` or `$enact-loop:hyperplan`. The skill is stateless — it produces a debate bundle and hands off to `$plan`. No durable workflow state is started automatically.