@amsterdamdatalabs/enact-extensions 0.1.12 → 0.1.25

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

@@ -5,13 +5,19 @@ description: "Contract-runner loop engine. Drives declared stages (mechanical an
 
 # enact-loop
 
+> **Storage is GLOBAL — never write to a repo-local `.enact` dir.** Resolve the project's global dir:
+> 1. `ROOT="$(git rev-parse --show-toplevel)"`
+> 2. In `~/.enact/workspaces.json` → `workspaces`, find the entry whose `.root` == `$ROOT`; its object key is `<name>-<id>` (e.g. `enact-loop-b9762d`).
+> 3. Loop runtime state lives under `~/.enact/loop/projects/<key>/…`.
+
 ## Purpose
 
 `$enact-loop` is the persistence wrapper for bounded work. Given a contract (an ordered set of
 stages), the loop drives each stage to closure and refuses to exit until every required stage has
-passed. Mechanical stages self-report via command evidence. Judgment stages require an **independent
-grader** running on a different model — the engine rejects any verdict self-reported by the
-executor.
+passed. Mechanical stages are graded by the engine: `loop_grade` runs the stage `command` in the
+loop root and derives pass/fail from exit code (caller-supplied `status`/`evidence` are rejected).
+Judgment stages require an **independent grader** on a different model — the executor must not
+fabricate or self-report judgment verdicts.
 
 ## Use When
 
@@ -32,6 +38,7 @@ Stage {
   name: string
   type: 'mechanical' | 'judgment'
   required: boolean
+  requires?: string[]   # stage ids that must pass before this stage runs
   command?: string        # mechanical stages only
   grader?: GraderSpec     # judgment stages only
   passCriteria?: string
@@ -42,17 +49,24 @@ GraderSpec {
   model?: string      # e.g. claude-opus-4-8 — always specify; omitting causes E_GRADER_MODEL_UNSET
   harness?: paseo | subagent                            # default: paseo
   rounds?: integer    # max grading rounds before escalation (default: 3)
+  timeoutMs?: integer # grader session timeout (default: 30 min); timeout → grader-unavailable blocker
+  fallbackModels?: string[]  # tried in order on re-dispatch after spawn failure (529/overload)
 }
 ```
 
 ## Stage Types
 
-**Mechanical** stages are automated: the executor runs the declared `command` and self-reports the
-result via `loop_grade`. No independent grader is needed.
+**Mechanical** stages are engine-run: call `loop_grade({ stageId, timeoutMs? })` and the runtime
+executes the stage `command` in the loop root cwd, capturing exit code and output. Caller-supplied
+`status` or `evidence` are rejected. No independent grader is needed.
 
-**Judgment** stages require an independent grader. The executor dispatches via
-`loop_grader_dispatch`; the grader records its verdict via `loop_grader_verdict`. The engine
-rejects any verdict where grader identity overlaps with executor identity.
+**Judgment** stages require an independent grader. The executor/driver dispatches via
+`loop_grader_dispatch`, then records the verdict via `loop_grader_verdict` (default:
+`captureSource: "relayed"` — grader returns a verdict envelope; driver records with the minted
+`continuationId`). A grader child session may call `loop_grader_verdict` directly (`captureSource:
+"direct"`) but only with a `continuationId` minted by dispatch — otherwise
+`E_UNKNOWN_GRADER_SESSION`. The engine rejects verdicts where grader identity overlaps executor
+identity.
 
 ## The Independence Rule
 
@@ -89,7 +103,7 @@ idle → running → verifying → completed (terminal)
 - ambiguous goal → clarify first, then start the loop with the refined goal
 - goal is clear → start immediately: `loop_start`
 - blocked on external dependency → `loop_block`, resolve, then `loop_advance` back to `running`
-- all required stages passed → write summary.md, then `loop_complete` (only from phase=verifying)
+- all required stages passed → `enact-loop summary write`, then `loop_complete` (only from phase=verifying)
 
 ## Workflow
 
@@ -98,14 +112,19 @@ idle → running → verifying → completed (terminal)
    ```
    loop_start  goal="<goal>"  preset=<preset>|contract=<stages JSON>
    ```
+   Built-in presets: `frontend-ui` (5 mechanical: lint/typecheck/test/build/visual,
+   then **two** judgment stages — `code-review` **and** `verify` — the shape that
+   reliably catches both correctness and acceptance defects), `docs` (mechanical +
+   one lighter `review`), plus `docs-workflow` / `custom-pipeline`. Use a preset to
+   get the right judgment shape by default instead of hand-authoring stages.
 3. Implement the work while in phase `running`.
 4. Advance to verification:
    ```
    loop_advance  toPhase=verifying
    ```
-5. For each **mechanical** stage: run the command, then `loop_grade`.
-6. For each **judgment** stage: call `loop_grader_dispatch`, await the grader's
-   `loop_grader_verdict`.
+5. For each **mechanical** stage (respecting `requires` preconditions): `loop_grade({ stageId })`.
+6. For each **judgment** stage: `loop_grader_dispatch({ stageId })` → spawn grader → record via
+   `loop_grader_verdict` (`captureSource: "relayed"` from driver, or `"direct"` from grader child).
 7. When all required stages are `passed`: run `enact-loop summary write` (pipe body sections;
    CLI stamps the fingerprint header), then `loop_complete`.
 8. If a stage fails: fix the root cause, do not fabricate evidence, re-run and re-grade.
@@ -115,21 +134,42 @@ idle → running → verifying → completed (terminal)
 **Step 1 — Dispatch a grader:**
 
 ```
-loop_grader_dispatch  stageId=<id>
+loop_grader_dispatch  stageId=<id>  [model=<grader-model>]
 ```
 
 - mints an unforgeable `continuationId` and `graderSessionId` via the runtime
-- resolves the grader model from `stage.grader.model ?? loop.graderModel`
+- resolves the grader model: an explicit `model` override is used **verbatim**
+  (after the `≠ executor` check); otherwise `stage.grader.model ?? loop.graderModel`,
+  advancing through `fallbackModels` on re-dispatch after a spawn failure
 - requires the resolved model to differ from the executor's (`E_NO_DIVERSITY` otherwise)
 - launches the grader agent (read-only, same cwd) via Paseo `--provider <graderModel>`
 - returns the `continuationId` you must pass to step 2
 
-**Step 2 — Record the grader's verdict** (grader calls this, not the executor):
+**Step 2 — Record the grader's verdict** (driver-relayed is the default):
 
 ```
-loop_grader_verdict  stageId=<id>  verdict=GO|NO-GO  evidence="<findings>"  continuationId=<id>
+loop_grader_verdict  stageId=<id>  continuationId=<id>  verdict=GO|NO-GO  evidence="<findings>"
+  graderAgentId=<id>  graderSessionId=<id>  captureSource=relayed
+  recordedByAgentId=<executor>  recordedByModel=<model>  recordedBySessionId=<session>
+  [graderModelActual=<model-that-actually-ran>]
 ```
 
+`graderModelActual` records the model that *actually* ran the grader (e.g. the
+Paseo-resolved provider), separate from the dispatch-resolved request — the
+verdict stores it as the authoritative grader model (keeping the dispatched one
+as `graderModelDispatched`) and the independence check runs against it. Supply it
+when the host ran a different/fallback model than dispatched; omit it otherwise.
+
+Grader child sessions may call `loop_grader_verdict` directly with `captureSource=direct` instead.
+Direct calls without a dispatch-minted `continuationId` fail with `E_UNKNOWN_GRADER_SESSION`.
+Grader MCP sessions are **runtime-gated**: only `loop_grader_verdict`, `loop_status`,
+`loop_stop_evaluate` — pass `_meta.enactLoop` with `sessionRole: grader` and bound `continuationId`.
+Incomplete grader metadata (e.g. `role=grader` without `sessionId`) fails closed with
+`E_INCOMPLETE_GRADER_SESSION` rather than defaulting to executor.
+Grader timeout surfaces as `grader-unavailable` blocker — re-dispatch; never assume GO.
+Spawn failure (529): `loop_grader_report_spawn_failure` then re-dispatch (uses `fallbackModels`).
+While grader is in flight, Stop **allows** exit without `loop_pause` churn.
+
 The engine rejects the verdict if grader identity overlaps executor identity or the
 `continuationId` was not minted by this runtime.
 
@@ -137,9 +177,68 @@ The engine rejects the verdict if grader identity overlaps executor identity or
 `grader-independence-missing` if you do. If a grader returns NO-GO: fix the issue, stay in
 `verifying`, and re-dispatch. Exceeding the round limit escalates with a blocker.
 
+## Operational notes — grader independence, fallback, and worktree discipline
+
+> Context: in a validated 3-wave run, independent graders caught FIVE real defects that
+> all mechanical gates passed — model-distinct cross-vendor grading is the mechanism that
+> surfaces defects mechanical gates cannot see.
+
+### Grader independence is MODEL-DISTINCT
+
+The independence rule is checked by model identity, not by vendor or surface name.
+**A sonnet executor + a cursor-sonnet grader is NOT distinct** — `cursor/claude-sonnet-4-6`
+runs the same underlying model. The engine will emit `grader-independence-missing` and
+block closure. Ensure the resolved `grader.model` differs from the executor's model string.
+
+**Default cheap graders:** **minimax M3** (opencode) and **kimi K2.7** are vendor-distinct from
+both sonnet and codex, making them always-independent defaults (~80% of grading). Escalate to
+**opus 4.8** or **gpt-5.5** for high-risk judgment (a11y / visual / security / architecture).
+`cursor` is only distinct when the executor is opus-tier (cursor runs claude-sonnet).
+
+### fallbackModels rotation on spawn failure (529 / overload)
+
+1. Call `loop_grader_report_spawn_failure({ continuationId, error })` to record the failure.
+2. Re-call `loop_grader_dispatch` — with no `model`, the runtime auto-selects the next
+   `fallbackModels` entry; pass an explicit `model` to **pin a specific grader** (the override
+   is honored verbatim and is not consumed by the rotation pointer).
+3. Record the verdict under the minted `continuationId`; set `graderModelActual` to the model
+   that actually ran so provenance is accurate. Independence holds as long as the actual grader
+   model ≠ executor model.
+
+### Worktree fingerprint — when verdicts are invalidated vs. preserved
+
+| Change type | Effect on verdicts |
+|---|---|
+| Edit a **tracked** source file | Fingerprint changes → all prior `passed` verdicts invalidated (`BLOCKER_FILESYSTEM_STATE_CHANGED`) → re-grade required |
+| Add an **untracked** new file (e.g. a new test file) | Fingerprint unchanged → prior GO verdicts remain valid |
+
+This means you can add new test files mid-loop without forcing re-grading of already-passed stages.
+Never use `git stash` mid-loop — it mutates tracked-file state and invalidates all verdicts.
+
+### `loop_pause` / `loop_resume` around long async grading
+
+While a grader is dispatched and in flight, the Stop boulder already allows exit without `loop_pause`.
+Use `loop_pause` / `loop_resume` explicitly when you need to hand off control for extended human
+review or an async wait that is not grader-dispatch-in-flight, to avoid unnecessary Stop churn.
+
+### Graders are read-only
+
+Grader child sessions must review the artifact and emit a verdict — nothing else.
+They MUST NOT call `loop_*` management tools (complete, pause, resume, retarget, block, abort)
+or `factory_*` tools. The runtime rejects these calls from grader sessions.
+
+**Verdict capture is STRUCTURED, not log-scraped.** Dispatch with:
+`paseo run --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: recover the id by label then `paseo attach <id>`.
+Fallback only: if structured capture is unavailable, embed evidence inline in the `evidence` field.
+Design doc: `enact-loop/docs/design/2026-06-22-paseo-verdict-capture.md`.
+
 ## Access Control — `.enact/` is CLI-mediated
 
-The agent **NEVER edits `.enact/` files directly**. All loop state mutation goes through the
+The agent **NEVER edits `~/.enact/` files directly**. All loop state mutation goes through the
 `enact-loop` CLI or `loop_*` MCP tools — never raw file edits. Read state via:
 
 ```bash
@@ -147,9 +246,41 @@ enact-loop status --json          # current loop state as JSON
 enact-loop summary show           # display the current closure summary
 ```
 
+## Session roles and closure authority
+
+| Role | May call | Must NOT call |
+|------|----------|---------------|
+| **Executor/driver** | `loop_grade`, `loop_grader_dispatch`, `loop_grader_verdict` (relayed), `loop_pause`, `loop_resume`, `loop_retarget`, `loop_complete`, `enact-loop summary write` | — |
+| **Grader child** | `loop_grader_verdict` (direct), `loop_status`, `loop_stop_evaluate` | `loop_complete`, summary write, `loop_pause`/`loop_resume`/`loop_retarget`, closure tools |
+
+Grader child sessions: review, emit verdict, stop cleanly. They have **no closure authority**.
+
+**No `git stash` during an active loop** — stash mid-loop invalidates worktree state and stale
+verdict fingerprints.
+
+## Worktree fingerprint
+
+Each verdict is stamped with a worktree fingerprint. When the workspace changes (e.g. after
+retarget or filesystem drift), stale `passed` verdicts are invalidated (`BLOCKER_FILESYSTEM_STATE_CHANGED`).
+`loop_retarget` preserves verdicts only when `id + type + worktreeFingerprint` match unchanged stages.
+
+## Workspace root resolution
+
+Loop state is keyed to the **launch workspace** — no ancestor `.git` walk:
+
+| Surface | Root source |
+|---------|-------------|
+| CLI subcommands | `process.cwd()` — run from the driven project |
+| MCP | `enact-loop mcp <workspace>` positional arg (bundle uses `"."` = host MCP cwd) |
+| Hooks | `payload.cwd` from hook JSON |
+
+Wrong cwd → different project store → "no active loop".
+
 ## Closure
 
-Closure requires a written, CURRENT `.enact/loop/state/summary.md`. When all required stages pass
+Closure requires a written, CURRENT timestamped summary under
+`~/.enact/loop/projects/<key>/state/<YYMMDDHH>-loop-summary.md`. The runtime records the active
+path in `~/.enact/loop/projects/<key>/state/summary-current.json`. When all required stages pass
 (and every judgment stage has an independent verdict), the loop is closure-ready and enters the
 `verifying` phase. The Stop boulder then **BLOCKS exit** and injects a generic markdown
 **TEMPLATE** whose first line is a fingerprint header:
@@ -195,6 +326,12 @@ EOF
 Once a current summary exists, the boulder allows exit. `completeLoop` / `blockLoop` / `abortLoop`
 all **REQUIRE** a current summary and throw `E_CLOSURE_SUMMARY_MISSING` otherwise.
 
+When a later `loop_start` begins a new loop, the prior terminal loop's active state is archived
+under `~/.enact/loop/projects/<key>/archive/<loop-id>-<contract-id>/` before the new active
+`state/loop.json` is written. That archive keeps the closed loop's `loop.json`,
+`closure-manifest.json`, `grader-sessions.json`, `summary-current.json`, and every timestamped
+closure summary for auditability.
+
 **This summary is the handoff**: enact-factory's brain reads it (together with the Paseo agent's
 last message) to decide the next action after the loop completes.
 
@@ -211,15 +348,15 @@ last message) to decide the next action after the loop completes.
 | `loop_start` | Start loop with goal + contract/preset; stamps executorIdentity |
 | `loop_status` | Read current loop state |
 | `loop_advance` | Phase transition |
-| `loop_grade` | Record a mechanical stage result (self-report; status + command evidence) |
+| `loop_grade` | Run a mechanical stage command in loop root; args: `stageId`, optional `timeoutMs` |
 | `loop_grader_dispatch` | Dispatch an independent grader for a judgment stage (returns continuationId) |
-| `loop_grader_verdict` | Record an independent grader's GO/NO-GO (grader calls this, not executor) |
+| `loop_grader_verdict` | Record GO/NO-GO; `captureSource`: `relayed` (driver default) or `direct` (grader child) |
 | `loop_pause` | Pause the loop for human review; Stop allows exit while paused |
 | `loop_resume` | Resume a paused loop; restores the pre-pause phase |
 | `loop_retarget` | Replace the active contract with a new one (same loop id) |
-| `loop_block` | Mark blocked with a reason; requires current summary.md |
-| `loop_complete` | Close the loop; requires current summary.md + phase=verifying + all stages passed |
-| `loop_abort` | Abort with a reason; requires current summary.md |
+| `loop_block` | Mark blocked with a reason; requires current closure summary |
+| `loop_complete` | Close the loop; requires current closure summary + phase=verifying + all stages passed |
+| `loop_abort` | Abort with a reason; requires current closure summary |
 | `loop_contract_parity` | Run contract-parity check |
 | `loop_stop_evaluate` | Evaluate Stop boulder policy (called by the Stop hook) |
 
@@ -230,7 +367,7 @@ last message) to decide the next action after the loop completes.
 enact-loop status --json                          # current loop state as JSON
 enact-loop summary show                           # display the current closure summary
 
-# Write the closure summary (CLI stamps the fingerprint header; never write summary.md directly)
+# Write the closure summary (CLI stamps fingerprint header into a new YYMMDDHH-loop-summary.md; never write summaries directly)
 enact-loop summary write <<'EOF'
 ## Summary
 ...
@@ -254,18 +391,21 @@ The Stop hook calls `enact-loop hook stop` → `loop_stop_evaluate`. The boulder
 - any `required` stage is still `pending` or `failed`
 - any judgment stage is `passed` but lacks a valid independent verdict (`grader-independence-missing`)
 - a required grader is unavailable (`grader-unavailable`)
-- the loop is closure-ready (all stages passed, independence satisfied) but `summary.md` is absent
-  or stale (`closure-summary-missing`) — resolve by running `enact-loop summary write`
+- the loop is closure-ready (all stages passed, independence satisfied) but no current closure summary exists
+  or the summary fingerprint is stale (`closure-summary-missing`) — resolve by running `enact-loop summary write`
 - the loop phase is not terminal (exception: `paused` allows exit)
 
 ## State
 
 `.enact/` is CLI-mediated — never read or write `.enact/` files directly.
 
-- Read state: `enact-loop status --json` (loop state) · `enact-loop summary show` (closure summary)
+- Read state: `enact-loop status --json` (loop state) · `enact-loop summary show` (current closure summary)
 - Mutate state: `loop_*` MCP tools or `enact-loop` CLI subcommands only
-- Closure summary at `.enact/loop/state/summary.md` is written via `enact-loop summary write`
-  (CLI stamps the fingerprint header); it is read by enact-factory's brain after loop completion.
+- Active loop state stays in `~/.enact/loop/projects/<key>/state/`; closed loops move to
+  `~/.enact/loop/projects/<key>/archive/<loop-id>-<contract-id>/` on the next `loop_start`
+- Closure summaries are append-only timestamped files at
+  `~/.enact/loop/projects/<key>/state/<YYMMDDHH>-loop-summary.md`, written via `enact-loop summary write`
+  (CLI stamps the fingerprint header and updates `summary-current.json`); read by enact-factory's brain after loop completion.
 - SessionStart hook auto-resumes an active (`running` or `verifying`) loop when the prompt
   contains `$enact-loop`. Paused loops are NOT auto-resumed.
 
@@ -281,9 +421,16 @@ stages:
     name: Tests passing
     type: mechanical
     required: true
-    command: npm test
+    command: bash scripts/ci-local.sh
     passCriteria: All tests exit 0
 
+  - id: typecheck
+    name: Type check clean
+    type: mechanical
+    required: true
+    command: npm run typecheck && npm run typecheck:tests
+    passCriteria: No type errors in src or test files
+
   - id: lint
     name: Lint clean
     type: mechanical
@@ -303,6 +450,18 @@ stages:
     passCriteria: Reviewer approves with no blocking issues
 ```
 
+**Tests stage must mirror CI (hard requirement #9).** A bare `npm test` on the
+host is not acceptable — the host suite can pass green while the same deliverable
+fails the Linux CI agent due to `HOME`/path divergence. The `command` for the
+`tests` stage must invoke a Linux-parity / containerized runner (e.g.
+`bash scripts/ci-local.sh`) that reproduces the CI environment locally.
+
+**Include `typecheck:tests` (rule #7).** When the project has a separate
+test-file typecheck script, include it — either as its own mechanical stage or
+folded into the typecheck stage command (`npm run typecheck && npm run
+typecheck:tests`). A src-only `typecheck` lets test-file type regressions slip
+past undetected.
+
 ### Docs Workflow
 
 ```yaml

package/extensions/enact-wiki/.agents/plugin.json

@@ -15,7 +15,8 @@
   "targets": [
     "claude",
     "codex",
-    "cursor"
+    "cursor",
+    "enact"
   ],
   "skills": "./skills/",
   "mcpServers": "./.mcp.json",

package/extensions/net-revenue-management/.agents/plugin.json

@@ -17,7 +17,8 @@
   "targets": [
     "claude",
     "codex",
-    "cursor"
+    "cursor",
+    "enact"
   ],
   "skills": "./skills/",
   "mcpServers": "./.mcp.json",

package/extensions/plugin-dev/.agents/plugin.json

@@ -17,7 +17,8 @@
   "targets": [
     "claude",
     "codex",
-    "cursor"
+    "cursor",
+    "enact"
   ],
   "skills": "./skills/",
   "agents": "./agents/",

package/extensions/plugin-dev/skills/start/SKILL.md

@@ -37,7 +37,7 @@ Welcome to the Enact Plugin Manager!
 - Canonical manifest: .agents/plugin.json
 - Shared components: skills/ (passive + invocable), agents/, hooks/, .mcp.json
 - Host copies: .claude-plugin/, .codex-plugin/, .cursor-plugin/
-- Example: ../enact-operator/extensions/ (sibling top-level submodule of enact-os)
+- Example: extensions/plugin-dev/
 
 Load the plugin-structure skill, then run create-plugin for the full workflow.
 ```
@@ -61,13 +61,13 @@ Option 1:
 Option 2:
 
 - label: "Validate an existing plugin"
-- description: "Run plugin-validator on an existing bundle (e.g. ../enact-operator/extensions)."
+- description: "Run plugin-validator on an existing bundle (e.g. extensions/plugin-dev)."
 
 ## Step 4: Route Based on Choice
 
 **Create a plugin** → invoke `create-plugin` with `$ARGUMENTS`.
 
-**Validate an existing plugin** → invoke `plugin-validator` agent on the path the user provides (default: `../enact-operator/extensions`).
+**Validate an existing plugin** → invoke `plugin-validator` agent on the path the user provides (default: `extensions/plugin-dev`).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/enact-extensions",
-  "version": "0.1.12",
+  "version": "0.1.25",
   "description": "Create and validate Enact multi-platform plugin manifests",
   "license": "UNLICENSED",
   "type": "module",

package/scripts/check-hooks.mjs

@@ -2,11 +2,11 @@
 /**
  * Repo guard: validate every plugin's hooks before they ship.
  *
- * Born from real breakage: enact-operator shipped hook entries for a
- * doom-loop CLI that had been deleted (module-not-found at runtime), and
- * enact-factory's npm package omitted `extensions/` from its files whitelist
- * so `enact-factory hook ...` could never load. Both passed every static check
- * yet failed the moment Claude Code fired the hook. plugin-dev meanwhile
+ * Born from real breakage: a bundle shipped hook entries for a deleted
+ * CLI (module-not-found at runtime), and an npm package omitted `extensions/`
+ * from its files whitelist so its hook command could never load. Both passed
+ * every static check yet failed the moment Claude Code fired the hook.
+ * plugin-dev meanwhile
  * declared a `hooks` component whose hooks.json was `{ "hooks": {} }` — a
  * component that installs nothing.
  *

package/scripts/check-principles.mjs

@@ -13,7 +13,8 @@
  *      install).
  *  E3  Skill hygiene. Each `skills/<dir>/` needs a `SKILL.md` with `name` +
  *      `description` frontmatter, and no `README.md`.
- *  E4  `targets` must not include "enact" (enact is the canonical source).
+ *  E4  Surface targets are normalized repo-wide:
+ *      - every bundled plugin targets claude/codex/cursor/enact
  */
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -26,6 +27,7 @@ const errors = [];
 const warnings = [];
 const err = (p, m) => errors.push(`[ERROR] ${p}: ${m}`);
 const warn = (p, m) => warnings.push(`[warn]  ${p}: ${m}`);
+const ALL_SURFACE_TARGETS = ["claude", "codex", "cursor", "enact"];
 
 function frontmatter(file) {
   const t = readFileSync(file, "utf8");
@@ -43,6 +45,11 @@ function isDir(p) {
   try { return statSync(p).isDirectory(); } catch { return false; }
 }
 
+function normalizedTargets(value) {
+  if (!Array.isArray(value)) return null;
+  return value.filter((entry) => typeof entry === "string");
+}
+
 if (!existsSync(EXT)) {
   console.error(`No extensions dir at ${EXT}`);
   process.exit(1);
@@ -62,9 +69,17 @@ for (const name of readdirSync(EXT)) {
   if ("commands" in m) err(id, `manifest declares "commands" — commands are skills; remove it`);
   if (isDir(join(root, "commands"))) err(id, `has a commands/ dir — commands are skills; migrate to skills/`);
 
-  // E4 — targets must not include enact
-  if (Array.isArray(m.targets) && m.targets.includes("enact"))
-    err(id, `targets includes "enact" — enact is the canonical source, never a target`);
+  // E4 — repo-wide surface targeting contract
+  const expectedTargets = ALL_SURFACE_TARGETS;
+  const actualTargets = normalizedTargets(m.targets);
+  if (!actualTargets) {
+    err(id, `manifest must declare "targets": ${JSON.stringify(expectedTargets)}`);
+  } else if (JSON.stringify(actualTargets) !== JSON.stringify(expectedTargets)) {
+    err(
+      id,
+      `targets must be ${JSON.stringify(expectedTargets)}; found ${JSON.stringify(actualTargets)}`,
+    );
+  }
 
   // E2 — declare components that exist on disk
   for (const comp of ["skills", "agents", "hooks"]) {