@amsterdamdatalabs/enact-extensions 0.1.12 → 0.1.25

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

@@ -0,0 +1,80 @@
+---
+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

@@ -5,6 +5,11 @@ description: "Intent-first clarification loop for vague, risky, or product-heavy
 
 # 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
@@ -30,29 +35,20 @@ brainstorming. It is a focused clarification loop that removes ambiguity before
 - use repo facts before asking about codebase internals
 - force clarity on non-goals and decision boundaries before handoff
 - keep the interview moving toward a durable artifact, not an endless conversation
-
-## Question Order
-
-1. Why does this need to exist?
-2. What should be true when it is done?
-3. How far should it go?
-4. What should explicitly stay out?
-5. What may the agent decide without checking again?
-6. What constraints or preferences are hard?
+- **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 `.enact/loop/plans/<phase>-requirements.md`.
+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. Update:
-   - `.enact/loop/plans/<phase>-requirements.md`
-5. Hand off to `$plan` when the spec is concrete.
+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
 

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

@@ -14,6 +14,11 @@ metadata:
 
 # 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
@@ -56,6 +61,7 @@ required unless marked optional.
       "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
       },
@@ -74,6 +80,10 @@ required unless marked optional.
 
 - `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.
 
@@ -88,6 +98,15 @@ 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
 
 ```
@@ -100,11 +119,12 @@ agent cannot stop until the loop signals closure.
 
 ### Step 3 — Drive mechanical stages
 
-For each mechanical stage the loop surfaces:
+For each mechanical stage the loop surfaces (after any `requires` preconditions pass):
 
-1. Run the stage's `command`.
-2. Capture stdout/stderr and exit code.
-3. Record the result: `loop_grade({ stageId, pass: <bool>, output: <string> })`.
+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.
 
@@ -112,9 +132,11 @@ Repeat until the stage passes or the loop escalates to a retry/fail policy.
 
 For each judgment stage:
 
-1. Call `loop_grader_dispatch({ stageId, role: <grader role> })`.
-2. Spawn an **independent subagent** on a **different model** (never the
-   executor's model or session):
+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({
@@ -124,20 +146,52 @@ For each judgment stage:
    })
    ```
 
-3. The grader returns a GO or NO-GO verdict with rationale.
-4. Record the verdict: `loop_grader_verdict({ stageId, verdict: "GO | NO-GO", rationale })`.
-
-The boulder prevents the session from completing until every judgment stage
-has a GO from an independent grader.
+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/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 the loop signals closure (all required stages passed):
+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.
 
-1. Control returns to factory.
-2. Call `pushLoopClosure` (enact-factory MCP/CLI) with the loop's closure
-   record.
-3. 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 .`).
 
 ---
 
@@ -157,6 +211,85 @@ from the executor.
 
 ---
 
+## 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` | `--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 |
+
+#### 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 --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). 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
@@ -214,29 +347,26 @@ from the executor.
 
 1. Factory builds this contract from WI-2041's `closureRequirements`.
 2. `loop_start({ contract })` — boulder active.
-3. Loop surfaces `unit-tests` → executor runs `cargo test` → exit 0 →
-   `loop_grade({ stageId: "unit-tests", pass: true, output: "..." })`.
-4. Loop surfaces `regression-evidence` → executor runs grep → match found →
-   `loop_grade({ stageId: "regression-evidence", pass: true, output: "..." })`.
+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", role: "code-reviewer" })` →
+   `loop_grader_dispatch({ stageId: "code-review" })` →
    spawn `code-reviewer` subagent on `claude-opus-4-8` →
-   grader returns GO →
-   `loop_grader_verdict({ stageId: "code-review", verdict: "GO", rationale: "..." })`.
+   driver relays GO via
+   `loop_grader_verdict({ stageId: "code-review", continuationId, verdict: "GO", evidence: "...", captureSource: "relayed", ... })`.
 6. Loop surfaces `verifier-signoff` →
-   `loop_grader_dispatch(...)` →
-   spawn `verifier` subagent on `claude-opus-4-8` →
-   grader returns GO →
-   `loop_grader_verdict({ stageId: "verifier-signoff", verdict: "GO", rationale: "..." })`.
-7. All required stages passed → loop signals closure → boulder lifts.
+   `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.** The executor that wrote the code cannot be the grader.
-  Grader must run on a different model and in a different session.
+- **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.

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

@@ -23,7 +23,8 @@ disclosure supplement to `SKILL.md`.
 | `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. |
-| `command` | string | mechanical | Shell command run by the executor. Exit 0 = pass. |
+| `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. |
 
@@ -36,7 +37,9 @@ disclosure supplement to `SKILL.md`.
 | `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 --output-schema --json`, returns `{verdict, evidence}` + `graderModelActual`). 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. |
 
 ---
 
@@ -49,6 +52,17 @@ disclosure supplement to `SKILL.md`.
 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.
 
 ---
 
@@ -58,8 +72,14 @@ A contract reaches **closure** when:
 
 - Every stage where `required: true` has status `PASSED`.
 - `PASSED` means:
-  - `mechanical`: `loop_grade` was called with `pass: true`.
-  - `judgment`: `loop_grader_verdict` was called with `verdict: "GO"`.
+  - `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.
@@ -71,9 +91,9 @@ are included in the closure record returned to factory.
 | Tool | When to call | Key params |
 |------|-------------|------------|
 | `loop_start` | Once, at the start of the delivery | `{ contract: <Contract JSON> }` |
-| `loop_grade` | After each mechanical stage run | `{ stageId, pass, output }` |
-| `loop_grader_dispatch` | Before spawning the grader subagent | `{ stageId, role }` |
-| `loop_grader_verdict` | After the grader subagent returns | `{ stageId, verdict: "GO\|NO-GO", rationale }` |
+| `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):
 

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

@@ -0,0 +1,72 @@
+---
+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.
+
+## 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

@@ -5,6 +5,11 @@ description: "Three-round adversarial planning debate that hands a distilled bun
 
 # 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.
@@ -30,14 +35,17 @@ Run exactly 3 rounds:
 
 Persist each round under:
 
-- `.enact/loop/hyperplan/<sessionId>/round-1.md`
-- `.enact/loop/hyperplan/<sessionId>/round-2.md`
-- `.enact/loop/hyperplan/<sessionId>/round-3.md`
+- `~/.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