@amsterdamdatalabs/enact-extensions 0.1.5 → 0.1.10

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

@@ -0,0 +1,327 @@
+---
+name: enact-loop
+description: "Contract-runner loop engine. Drives declared stages (mechanical and judgment) to closure; the Stop boulder refuses to exit until every required stage passes and independent graders have signed off every judgment stage."
+---
+
+# enact-loop
+
+## Purpose
+
+`$enact-loop` is the persistence wrapper for bounded work. Given a contract (an ordered set of
+stages), the loop drives each stage to closure and refuses to exit until every required stage has
+passed. Mechanical stages 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.
+
+## Use When
+
+- work must not stop until all required stages pass
+- judgment gates (architect-GO, code review, scope fidelity, QA) require independent sign-off
+- a previous attempt left work in an incomplete or unverified state
+- partial completion is unacceptable
+
+## Contract Schema
+
+A **contract** is the declarative closure spec. Declare it inline or pass a YAML/JSON file.
+
+```
+Contract { id, name, stages[] }
+
+Stage {
+  id: string
+  name: string
+  type: 'mechanical' | 'judgment'
+  required: boolean
+  command?: string        # mechanical stages only
+  grader?: GraderSpec     # judgment stages only
+  passCriteria?: string
+}
+
+GraderSpec {
+  role: architect | critic | code-reviewer | verifier   # required
+  model?: string      # e.g. claude-opus-4-8 — always specify; omitting causes E_GRADER_MODEL_UNSET
+  harness?: paseo | subagent                            # default: paseo
+  rounds?: integer    # max grading rounds before escalation (default: 3)
+}
+```
+
+## 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.
+
+**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.
+
+## The Independence Rule
+
+Judgment stages must be graded by a **different model** than the executor (model-distinct, not
+vendor/surface-distinct). The loop rejects a verdict whose grader model, session, or agent equals
+the executor's. Graders are dispatched out-of-session via Paseo `--provider <model>` for
+cross-surface grading; in-surface graders just need a supported model that differs from the
+executor's.
+
+The engine enforces independence at `recordStage` AND `completeLoop` (defense in depth). The Stop
+boulder re-checks at session exit. Violations emit `grader-independence-missing` and block closure.
+
+## Loop Phases
+
+```
+idle → running → verifying → completed (terminal)
+              ↘ blocked → running | verifying
+              ↘ paused  → running | verifying   (Stop ALLOWS exit while paused)
+              ↘ aborted (terminal)
+```
+
+- **idle** — loop declared, not yet started
+- **running** — executor actively working
+- **verifying** — executor running closure checks
+- **completed** — all required stages passed, loop closed
+- **blocked** — waiting on an external dependency (`loop_block` / `loop_advance` to resume)
+- **paused** — deliberate human suspension via `loop_pause`; the Stop boulder ALLOWS exit while
+  paused; SessionStart does NOT auto-resume a paused loop; stays paused until `loop_resume` is
+  explicitly called
+- **aborted** — cancelled with a reason (terminal)
+
+## Routing Rules
+
+- ambiguous goal → clarify first, then start the loop with the refined goal
+- goal is clear → start immediately: `loop_start`
+- blocked on external dependency → `loop_block`, resolve, then `loop_advance` back to `running`
+- all required stages passed → write summary.md, then `loop_complete` (only from phase=verifying)
+
+## Workflow
+
+1. Read current state: `loop_status`
+2. If no active loop, start one:
+   ```
+   loop_start  goal="<goal>"  preset=<preset>|contract=<stages JSON>
+   ```
+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`.
+7. When all required stages are `passed`: run `enact-loop summary write` (pipe body sections;
+   CLI stamps the fingerprint header), then `loop_complete`.
+8. If a stage fails: fix the root cause, do not fabricate evidence, re-run and re-grade.
+
+## Judgment Grading Protocol
+
+**Step 1 — Dispatch a grader:**
+
+```
+loop_grader_dispatch  stageId=<id>
+```
+
+- mints an unforgeable `continuationId` and `graderSessionId` via the runtime
+- resolves the grader model from `stage.grader.model ?? loop.graderModel`
+- 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):
+
+```
+loop_grader_verdict  stageId=<id>  verdict=GO|NO-GO  evidence="<findings>"  continuationId=<id>
+```
+
+The engine rejects the verdict if grader identity overlaps executor identity or the
+`continuationId` was not minted by this runtime.
+
+**NEVER self-report a judgment verdict.** The boulder blocks Stop and re-prompts with
+`grader-independence-missing` if you do. If a grader returns NO-GO: fix the issue, stay in
+`verifying`, and re-dispatch. Exceeding the round limit escalates with a blocker.
+
+## Access Control — `.enact/` is CLI-mediated
+
+The agent **NEVER edits `.enact/` files directly**. All loop state mutation goes through the
+`enact-loop` CLI or `loop_*` MCP tools — never raw file edits. Read state via:
+
+```bash
+enact-loop status --json          # current loop state as JSON
+enact-loop summary show           # display the current closure summary
+```
+
+## Closure
+
+Closure requires a written, CURRENT `.enact/loop/state/summary.md`. When all required stages pass
+(and every judgment stage has an independent verdict), the loop is closure-ready and enters the
+`verifying` phase. The Stop boulder then **BLOCKS exit** and injects a generic markdown
+**TEMPLATE** whose first line is a fingerprint header:
+
+```
+<!-- enact-loop-summary loop:<id> fp:<phase|stagesPassed|historyLen> -->
+```
+
+The template defines these sections (keep the whole file under 100 lines):
+
+- **Summary** — one-line statement of what was accomplished or why blocking/aborting
+- **Stage state** — list of stages with their final status
+- **Blockers** — any unresolved blockers (if blocking/aborting)
+- **Failures** — any stages that failed and the root cause
+- **Evidence** — key commands run and observed outputs
+- **Recommendations** — suggested next actions
+
+To write the summary, **pipe the body sections to the CLI** — the CLI stamps the fingerprint
+header automatically:
+
+```bash
+enact-loop summary write <<'EOF'
+## Summary
+<one-line summary>
+
+## Stage state
+<stage list>
+
+## Blockers
+<none|list>
+
+## Failures
+<none|list>
+
+## Evidence
+<commands + observed output>
+
+## Recommendations
+<next actions>
+EOF
+```
+
+Once a current summary exists, the boulder allows exit. `completeLoop` / `blockLoop` / `abortLoop`
+all **REQUIRE** a current summary and throw `E_CLOSURE_SUMMARY_MISSING` otherwise.
+
+**This summary is the handoff**: enact-factory's brain reads it (together with the Paseo agent's
+last message) to decide the next action after the loop completes.
+
+**Closure sequence — required for ALL terminal transitions:**
+
+1. `enact-loop summary write` — pipe body sections; CLI stamps the fingerprint header
+2. Then call: `loop_complete summary="<one-line>"` OR `loop_block reason="<reason>"` OR
+   `loop_abort reason="<reason>"`
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `loop_start` | Start loop with goal + contract/preset; stamps executorIdentity |
+| `loop_status` | Read current loop state |
+| `loop_advance` | Phase transition |
+| `loop_grade` | Record a mechanical stage result (self-report; status + command evidence) |
+| `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_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_contract_parity` | Run contract-parity check |
+| `loop_stop_evaluate` | Evaluate Stop boulder policy (called by the Stop hook) |
+
+## CLI
+
+```bash
+# Read state (never read .enact/ files directly)
+enact-loop status --json                          # current loop state as JSON
+enact-loop summary show                           # display the current closure summary
+
+# Write the closure summary (CLI stamps the fingerprint header; never write summary.md directly)
+enact-loop summary write <<'EOF'
+## Summary
+...
+EOF
+
+# Validate a contract file before using it with loop_start
+enact-loop contract validate <path/to/contract.json|yaml>
+
+# Health check — verify MCP server reachability and runtime state; optionally validate
+# that a contract's grader model differs from the executor model
+enact-loop doctor --contract <file> [--executor-model M] [--grader-model M]
+```
+
+`contract validate` exits 0 + `✓ valid contract: <id> (<n> stages)` on success; exits 1 with an
+error list on failure. Common errors: missing required fields, judgment stage without `grader`,
+mechanical stage with `grader` (use `command` instead), malformed YAML/JSON.
+
+## Boulder Behavior
+
+The Stop hook calls `enact-loop hook stop` → `loop_stop_evaluate`. The boulder blocks exit if:
+- any `required` stage is still `pending` or `failed`
+- any judgment stage is `passed` but lacks a valid independent verdict (`grader-independence-missing`)
+- a required grader is unavailable (`grader-unavailable`)
+- the loop is closure-ready (all stages passed, independence satisfied) but `summary.md` is absent
+  or 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)
+- 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.
+- SessionStart hook auto-resumes an active (`running` or `verifying`) loop when the prompt
+  contains `$enact-loop`. Paused loops are NOT auto-resumed.
+
+## Example Contracts
+
+### Delivery Contract
+
+```yaml
+id: delivery
+name: Feature Delivery
+stages:
+  - id: tests
+    name: Tests passing
+    type: mechanical
+    required: true
+    command: npm test
+    passCriteria: All tests exit 0
+
+  - id: lint
+    name: Lint clean
+    type: mechanical
+    required: true
+    command: npm run lint
+    passCriteria: No lint errors
+
+  - id: code-review
+    name: Code review
+    type: judgment
+    required: true
+    grader:
+      role: code-reviewer
+      model: claude-opus-4-8
+      harness: paseo
+      rounds: 3
+    passCriteria: Reviewer approves with no blocking issues
+```
+
+### Docs Workflow
+
+```yaml
+id: docs-workflow
+name: Documentation Update
+stages:
+  - id: build
+    name: Docs build clean
+    type: mechanical
+    required: true
+    command: npm run docs:build
+
+  - id: scope-fidelity
+    name: Scope fidelity
+    type: judgment
+    required: true
+    grader:
+      role: critic
+      model: claude-opus-4-8
+      rounds: 2
+    passCriteria: Critic confirms docs match the stated scope
+```

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

@@ -21,7 +21,6 @@
   ],
   "skills": "./skills/",
   "agents": "./agents/",
-  "commands": "./commands/",
   "mcpServers": "./.mcp.json",
   "apps": "./.app.json",
   "interface": {

package/extensions/enact-operator/hooks/hooks.json

@@ -20,22 +20,6 @@
             "command": "enact-operator hook user-prompt-submit"
           }
         ]
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "enact-operator hook doom-loop-counter reset"
-          }
-        ]
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "enact-operator hook doom-loop-search-guard reset"
-          }
-        ]
       }
     ],
     "PreToolUse": [
@@ -60,25 +44,6 @@
             "statusMessage": "Reviewing Operator tool output"
           }
         ]
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "enact-operator hook doom-loop-counter",
-            "statusMessage": "Checking Operator tool-call budget"
-          }
-        ]
-      },
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "enact-operator hook doom-loop-search-guard",
-            "statusMessage": "Checking Operator search deduplication"
-          }
-        ]
       }
     ],
     "Stop": [

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

@@ -0,0 +1,42 @@
+---
+name: wiki
+description: "Wiki-style reference lookup and persistence via the enact-wiki provider. Use when durable project documentation or knowledge retrieval is needed."
+---
+
+# Wiki
+
+## Purpose
+Provides access to the project's durable wiki and knowledge base via the enact-wiki MCP server. This skill does not re-implement wiki storage or retrieval — it delegates all operations to enact-wiki tools. Research artifacts and analysis outputs can be persisted to the wiki via this skill.
+
+## Use When
+- Looking up a documented decision, design, or reference
+- Research findings should be persisted as a durable wiki entry
+- Checking "does the wiki have anything on X?"
+
+## Workflow
+1. Identify the query or document to persist.
+2. Delegate the operation to the enact-wiki provider using its wiki MCP tools.
+   - For a lookup: invoke the enact-wiki wiki query tool with the search term.
+   - For a write: invoke the enact-wiki wiki add tool with the content and title.
+   - For a list: invoke the enact-wiki wiki list tool.
+   - For a read of a specific entry: invoke the enact-wiki wiki read tool with the entry identifier.
+3. If the operation returns content, present it directly without reformatting.
+4. If persisting a research artifact (e.g., from `.enact/loop/research/` or `.enact/factory/security/`), read the file first, then pass the content to the enact-wiki wiki add tool.
+5. Wiki state is owned by the enact-wiki provider — do not store wiki content locally as a substitute.
+
+## State Contract
+- Reads: enact-wiki wiki store (via MCP tool calls), local research files when persisting
+- Writes: enact-wiki wiki store (via MCP tool calls); no local wiki shadow files
+
+## Dependencies
+- Requires enact-wiki MCP server to be connected. If it is not available, report that and stop.
+
+## Activation
+
+Invoke with `$wiki` or `$enact-wiki:wiki`. The skill delegates all operations to enact-wiki MCP tools — no durable workflow state is started automatically.
+
+## Final Check
+- The query returned a result or a clear "not found" from enact-wiki
+- For writes, the enact-wiki tool confirmed the entry was saved
+- No wiki content was stored locally as a substitute for the enact-wiki store
+- If enact-wiki was unavailable, the caller was notified explicitly

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

@@ -1,7 +1,7 @@
 {
   "name": "plugin-dev",
   "version": "0.1.0",
-  "description": "Toolkit for authoring Enact plugins: scaffold and validate agents, commands, hooks, skills, and MCP integrations from an ENACT-native source manifest with Claude Code, Codex, and Cursor projections.",
+  "description": "Toolkit for authoring Enact plugins: scaffold and validate agents, skills, hooks, and MCP integrations from an ENACT-native source manifest with Claude Code, Codex, and Cursor projections.",
   "author": {
     "name": "amsterdamdatalabs"
   },
@@ -20,9 +20,7 @@
     "cursor"
   ],
   "skills": "./skills/",
-  "commands": "./commands/",
-  "hooks": "./hooks/hooks.json",
-  "mcpServers": "./.mcp.json",
+  "agents": "./agents/",
   "interface": {
     "displayName": "Plugin Dev",
     "shortDescription": "Scaffold and validate ENACT-native plugins with Claude Code, Codex, and Cursor projections.",
@@ -31,8 +29,8 @@
     "capabilities": [
       "multi-platform manifests",
       "plugin validation",
-      "slash commands",
-      "skills and hooks"
+      "skills authoring",
+      "agents authoring"
     ]
   },
   "factory": {

package/extensions/plugin-dev/agents/plugin-validator.md

@@ -4,7 +4,7 @@ description: Use when the user asks to validate an Enact plugin, check plugin st
 model: inherit
 color: yellow
 tools: Read, Grep, Glob, Bash
-skills: plugin-structure, hook-development, command-development, skill-development, mcp-integration
+skills: plugin-structure, hook-development, skill-development, mcp-integration
 ---
 
 You validate **Enact multi-platform plugins** (Claude, Codex, Cursor) using repo truth and `@enact/extensions` when available.

package/extensions/plugin-dev/skills/agent-development/SKILL.md

@@ -56,15 +56,15 @@ You are a code reviewer. Analyze code for issues and provide feedback.
 
 For complete format with all options, see [Agent File Structure](#agent-file-structure).
 
-## When to Use Agents vs Commands vs Skills
+## When to Use Agents vs Skills
 
-| Component    | Best For                    | Triggering                       | Example Use Case                    |
-| ------------ | --------------------------- | -------------------------------- | ----------------------------------- |
-| **Agents**   | Autonomous multi-step tasks | Proactive or description-matched | Code review after implementation    |
-| **Commands** | User-initiated actions      | Explicit `/command` invocation   | `/deploy production`                |
-| **Skills**   | Knowledge and guidance      | Model-invoked based on context   | Domain expertise for PDF processing |
+| Component             | Best For                    | Triggering                       | Example Use Case                    |
+| --------------------- | --------------------------- | -------------------------------- | ----------------------------------- |
+| **Agents**            | Autonomous multi-step tasks | Proactive or description-matched | Code review after implementation    |
+| **Skills (passive)**  | Knowledge and guidance      | Model-invoked based on context   | Domain expertise for PDF processing |
+| **Skills (invocable)**| User-initiated actions      | Explicit `/skill` invocation     | `/deploy production`                |
 
-> **See also:** For command development, load the `command-development` skill. For skill development, load the `skill-development` skill.
+> **See also:** For skill development (passive and invocable), load the `skill-development` skill. There is no separate "command" component — invocable skills replace commands.
 
 ### Choose Agents When