@amsterdamdatalabs/enact-extensions 0.1.1 → 0.1.3

package/extensions/enact-factory/skills/testing-strategy/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: testing-strategy
+description: >
+  Defines when and how to write tests in the enact-gateway codebase. Trigger
+  keywords: testing, write a test, TDD, bug fix, regression test, live test,
+  e2e, integration test, test harness, evidence, red-green, scenario, validate.
+---
+
+# testing-strategy
+
+## Purpose
+
+Enforce a consistent, lightweight approach across the three testing modes used
+in `enact-gateway`. The mode is determined by the behavior under test — not by
+preference. Pick once, follow the contract for that mode.
+
+---
+
+## Decision Rule
+
+| Situation | Mode |
+|-----------|------|
+| Pure function or isolated logic | Mode 0 — plain unit test |
+| Bug fix (any scope) | Mode 1 — TDD + `_evidence` |
+| Bug fix where behavior is runtime / live / cross-service (gateway → observe / iggy / questdb) | Mode 1 RED→GREEN + the regression test is a Mode-2 harness scenario |
+| New live-provider, cross-service, or e2e behavior | Mode 2 — harness scenario under `tests/integration/` or `tests/e2e/` |
+
+---
+
+## Mode 0 — Plain Unit Tests
+
+Use for: pure functions, simple transformations, isolated module logic.
+
+- File location: co-located with the source file, e.g. `src/foo/bar.spec.ts`.
+- Stack: Jest + ts-jest (resolved from `packages/backend`).
+- No harness ceremony. No fixtures directory. No `output/` directory.
+- Run: `npm run test --workspace=packages/backend` (or `npx jest <pattern>`).
+
+Do NOT force the harness onto plain unit tests. Co-located `.spec.ts` is
+sufficient and preferred.
+
+---
+
+## Mode 1 — Bug Fix: TDD with Captured `_evidence`
+
+### Contract
+
+1. **RED** — write a failing test that reproduces the bug before touching
+   implementation code. Capture the failure output:
+   ```
+   _evidence/<scenario>/red.txt
+   ```
+2. **Fix** — implement the minimal change that makes the test pass.
+3. **GREEN** — capture the passing output:
+   ```
+   _evidence/<scenario>/green.txt
+   ```
+
+`_evidence/` is **gitignored** — it is local proof, never committed source.
+
+### Regression test placement
+
+- If the bug is in pure/isolated logic, a co-located `.spec.ts` is sufficient.
+- If the bug involves runtime behavior — real provider calls, streaming,
+  cross-service interaction (gateway → observe / iggy / questdb) — the
+  regression test **must** be a Mode-2 harness scenario, not an ad-hoc script.
+
+### AzDO closure gate
+
+A bug work item in Azure DevOps (area `Enact\<leaf>`) must not be closed until:
+- A regression test exists (either `.spec.ts` or harness scenario).
+- `_evidence/<scenario>/red.txt` and `green.txt` are present locally.
+- The AzDO "Tests passing" Build boolean is green.
+
+---
+
+## Mode 2 — Live / Integration Test Harness
+
+### Directory layout
+
+```
+tests/
+  integration/<scenario>/      # harness scenarios (non-billable, require a live gateway)
+    fixtures/
+      input.json               # request body POSTed to the gateway
+    run.py (or run.ts)         # sends the request, writes output/<timestamp>.json
+    validate.py (or validate.ts) # reads latest output, prints PASS:/FAIL: per check
+    output/                    # gitignored; populated by run.py
+  e2e/                         # live, billable suites — OPT-IN only
+    <suite>.e2e-spec.ts        # Jest spec; skipped unless ENACT_LIVE_PROVIDER_TESTS=1
+    <scenario>/                # standalone scenario dirs (same run.py/validate.py shape)
+  lib/                         # shared harness helpers (import from here, do not duplicate)
+```
+
+> **Known issue:** `cli.py` currently globs `domains/*/*` but scenarios are
+> now laid out flat at `tests/integration/<scenario>/`. This mismatch is being
+> fixed; do not work around it by restructuring existing scenarios.
+
+### Scenario contract
+
+**`fixtures/input.json`** — the full JSON request body. Secrets are never
+stored here; only structure.
+
+**`run.py`** — self-contained runner:
+- Reads `ENACT_GATEWAY_BASE_URL` (default `http://127.0.0.1:43201`).
+- Reads `ENACT_GATEWAY_API_KEY` or `GATEWAY_API_KEY` for the bearer token.
+  If absent, writes `status: "skip"` and exits 0 — no tokens spent.
+- Reads `ENACT_GATEWAY_TIMEOUT_SECS` (default `30`).
+- POSTs `fixtures/input.json` to `<base_url>/v1/responses`.
+- Writes `output/<YYYYMMDDTHHmmss>.json` with one of:
+  - `{"status": "ok", "http_status": 200, "response_body": {...}, ...}`
+  - `{"status": "http_error", "http_status": <N>, "reason": "...", ...}`
+  - `{"status": "skip", "reason": "...", ...}`
+- Prints the output path and exits 0 (even for `http_error` — validate decides).
+
+**`validate.py`** — assertion layer:
+- Reads the latest file in `output/` (sort by name, take last).
+- If `status == "skip"`: prints `SKIP: <reason>` and exits 0.
+- If `status != "ok"`: prints `FAIL: ...` and exits 1.
+- For each behavioral check: prints `PASS: <label>` or `FAIL: <label>`.
+- Exits non-zero if any check failed.
+
+Secrets are **only ever passed by env-var name**, never committed to fixtures or
+source.
+
+### Task runner
+
+```bash
+# from tests/integration/
+uv run tasks list                              # list all discovered scenarios
+uv run tasks run <scenario>                    # run + validate
+uv run tasks run <scenario> --run-only         # skip validate
+uv run tasks run <scenario> --validate-only    # skip run (re-validate last output)
+uv run tasks run --all                         # run every scenario
+```
+
+### Live / billable suites (`tests/e2e/`)
+
+Live tests make **real, billable upstream calls**. They are OPT-IN and skipped
+in all normal / CI runs unless the flag is set explicitly:
+
+```bash
+# from packages/backend
+ENACT_LIVE_PROVIDER_TESTS=1 \
+LIVE_GATEWAY_URL=http://127.0.0.1:43201 \
+LIVE_KEY_ENACT_CODING=engw_... \
+LIVE_KEY_OPENCODE_GO=engw_... \
+LIVE_KEY_NANOGPT=engw_... \
+LIVE_KEY_OPENROUTER=engw_... \
+  npx jest --config ../../tests/e2e/jest-e2e.json --runInBand
+```
+
+Each `describe` block gates on its own key env-var, so individual profiles can
+be run in isolation by omitting the others.
+
+---
+
+## Output / Definition of Done
+
+A test is complete when:
+
+| Mode | Done when |
+|------|-----------|
+| Mode 0 | `npx jest <file>` exits 0; coverage covers the changed logic |
+| Mode 1 | `_evidence/<scenario>/red.txt` captured before fix; `green.txt` captured after; regression test in place |
+| Mode 2 — harness | `uv run tasks run <scenario>` exits 0 with all `PASS:` lines printed; or `SKIP:` when key absent (acceptable in CI) |
+| Mode 2 — live suite | Suite exits 0 under `ENACT_LIVE_PROVIDER_TESTS=1` with a live gateway; CI skips without the flag |

package/extensions/enact-factory/skills/workitem-triage/SKILL.md

@@ -0,0 +1,22 @@
+# workitem-triage
+
+## Purpose
+Provide a read-only triage surface for Factory WorkItems. This skill is for assessing queue state and individual WorkItem details without allowing scheduling, mutation, or execution actions.
+
+## Activation Contract
+- Activate with `factory_skill_activate` and `skill="workitem-triage"`.
+- Deactivate with `factory_skill_deactivate` when triage is complete.
+- While active, visible MCP tools must be limited to:
+  - `factory_workitem_list`
+  - `factory_workitem_get`
+
+## Forbidden Operations
+- Do not call scheduler, assignment, lifecycle, watchdog, sync, or closure mutation tools while this skill is active.
+- Do not update WorkItem state, queue entries, assignments, or process state.
+- Do not dispatch agent lanes or terminate processes.
+
+## Output Contract
+- Return concise, factual triage output only.
+- Include WorkItem ids, statuses, and blockers when present.
+- If required data is missing, explicitly state unknowns instead of inferring.
+- Keep recommendations non-mutating unless the operator explicitly switches out of triage mode.

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

@@ -0,0 +1,57 @@
+{
+  "name": "enact-operator",
+  "version": "0.1.0",
+  "description": "First-party Enact Operator plugin surfaces for skills, commands, agents, MCP, and runtime hook registrations.",
+  "author": {
+    "name": "amsterdamdatalabs"
+  },
+  "homepage": "https://amsterdamdatalabs.com",
+  "repository": "https://dev.azure.com/amsterdamdatalabs/Enact/_git/enact-operator",
+  "license": "UNLICENSED",
+  "keywords": [
+    "enact",
+    "operator",
+    "orchestration",
+    "workflow"
+  ],
+  "targets": [
+    "claude",
+    "codex",
+    "cursor"
+  ],
+  "skills": "./skills/",
+  "agents": "./agents/",
+  "commands": "./commands/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Enact Operator",
+    "shortDescription": "Installable surfaces for Enact Operator workflows.",
+    "longDescription": "Bundles the operator-owned Enact catalog. enact-extensions owns install, registration, hook wiring, enable/disable, status, and uninstall. Hook registrations call stable enact-operator runtime commands such as enact-operator hook user-prompt-submit; hook implementations stay in the enact-operator package.",
+    "developerName": "enact-operator",
+    "category": "Developer Tools",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "capabilities": [
+      "skills",
+      "slash commands",
+      "operator workflows",
+      "team orchestration",
+      "operator setup",
+      "doctor and readiness audits",
+      "plan and execution workflows",
+      "review and QA workflows",
+      "federated context and memory workflows"
+    ]
+  },
+  "operator": {
+    "firstParty": true,
+    "bundledMcpProviders": [
+      "enact-factory",
+      "enact-context",
+      "enact-wiki"
+    ],
+    "operatorScope": "project"
+  },
+  "hooks": "./hooks/hooks.json"
+}

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

@@ -0,0 +1,3 @@
+{
+  "apps": {}
+}

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

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "enact-operator": {
+      "command": "enact-operator",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}

package/extensions/enact-operator/_taxonomy.md

@@ -0,0 +1,86 @@
+# Enact Operator Extension Taxonomy
+
+`extensions/` has three extension tiers. Each entry belongs to exactly one tier.
+
+## Pure skills
+
+Pure skills live at `extensions/skills/<name>/SKILL.md`.
+
+- No MCP tool surface
+- No persisted lane state
+- Prompt/context guidance only
+
+Current pure skills:
+
+- `ai-slop-cleaner`
+- `analyze`
+- `ask`
+- `autoresearch-goal`
+- `cancel`
+- `configure-notifications`
+- `deep-interview`
+- `doctor`
+- `hud`
+- `hyperplan`
+- `plan`
+- `remove-deadcode`
+- `research`
+- `review`
+- `security-research`
+- `setup`
+- `skill`
+- `tdd`
+- `trace`
+- `wiki`
+- `work-with-workitem`
+
+## Agents
+
+Codex subagents live at `extensions/agents/*.toml`.
+
+- Stateless worker contracts
+- Dispatched through Codex subagents
+- Installed into the Codex agents directory by setup
+
+The old exact-name collisions `architect`, `executor`, and `reviewer` were removed from `extensions/skills/` once their Codex agent TOMLs existed. The remaining helper surfaces such as `plan`, `review`, `research`, `trace`, and `analyze` are pure skills, not agent files.
+
+## Operator lanes
+
+Operator lanes remain under `extensions/skills/<name>/SKILL.md`, but they are explicitly tagged with:
+
+- `lane: true`
+- `mcpToolPrefix: operator_<lane>_`
+
+Lanes add:
+
+- MCP tool surfaces
+- persisted operator state
+- runtime lifecycle semantics
+
+**Classification rule:** an entry is a **root lane** if and only if it has both (a) a durable operator state file under `.enact/operator/state/` AND (b) an `mcpToolPrefix` field in its `SKILL.md` frontmatter. Any entry that satisfies only one criterion, or neither, is a wrapper or continuity overlay, not a root lane.
+
+### Root lanes
+
+Root lanes are the four autonomous runtime execution lanes that the scheduler assigns tasks to. Each has a durable state file and its own `mcpToolPrefix`.
+
+- `ralph`
+- `ultrawork`
+- `team`
+- `autopilot`
+
+### Continuity overlays
+
+Continuity overlays have an MCP surface and durable state, but serve as multi-session goal artifacts that wrap one or more root lanes rather than acting as independent scheduler candidates.
+
+- `ultragoal`
+
+### Wrappers
+
+Wrappers delegate execution to a root lane (typically ralph) and carry no independent durable state file of their own.
+
+- `ralplan`
+- `ultraqa`
+
+## Disambiguation rule
+
+No entry may straddle tiers. If a surface needs Codex subagent dispatch, it belongs in `extensions/agents/`. If it needs Operator MCP tools and durable state, it is a lane. Everything else is a pure skill.

package/extensions/enact-operator/agents/README.md

@@ -0,0 +1,5 @@
+# Enact Operator Agents
+
+Codex-compatible agent TOMLs live in this directory.
+
+The taxonomy contract is documented in [`../_taxonomy.md`](../_taxonomy.md). During the active migration, the legacy agent-style skill directories in `../skills/` are the source material for the TOML ports that land here.

package/extensions/enact-operator/agents/architect.toml

@@ -0,0 +1,25 @@
+name = "architect"
+description = "Architectural review and GO/NO-GO verdict with evidence pointers"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator architect agent.
+
+Role:
+- Read-only architectural reviewer.
+- Diagnose root causes from code and docs already on disk.
+- Produce a GO or NO-GO verdict with concrete evidence pointers.
+
+Rules:
+- Never edit files.
+- Never speculate when you can read the source.
+- Cite exact file paths and line references for material claims.
+- Call out tradeoffs, not just the favored direction.
+
+Output contract:
+- verdict: GO or NO-GO
+- reasons: concise bullet list
+- evidencePointers: file references
+- tradeoffs: short list
+"""

package/extensions/enact-operator/agents/code-reviewer.toml

@@ -0,0 +1,24 @@
+name = "code-reviewer"
+description = "Binding code review pass enforcing unconditional approval or actionable findings"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator code-reviewer agent.
+
+Role:
+- Perform the binding review pass after an implementation batch.
+- Prioritize correctness, regressions, and missing verification over style.
+
+Rules:
+- Never edit files.
+- Review only from the actual diff and surrounding code.
+- Every finding must cite a file reference and explain impact.
+- If no actionable issues remain, emit the token UNCONDITIONAL_APPROVE.
+- Otherwise, return a blocking verdict with the findings ordered by severity.
+
+Output contract:
+- verdict: UNCONDITIONAL_APPROVE or REQUEST_CHANGES
+- findings: severity-ordered list with evidence
+- residual_risks: optional short list
+"""

package/extensions/enact-operator/agents/critic.toml

@@ -0,0 +1,30 @@
+name = "critic"
+description = "Adversarial debate participant for hyperplan and high-risk decision review"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator critic agent.
+
+Role:
+- Attack weak assumptions in plans, proposals, and risky implementation choices.
+- Operate as an adversarial reviewer, not a collaborator trying to be agreeable.
+
+Rules:
+- Never edit files.
+- Surface the strongest counterargument first.
+- Prefer concrete failure modes over vague concern language.
+- When a decision looks sound, say that plainly instead of inventing objections.
+
+Round protocol:
+1. Independent critique.
+2. Cross-attack on the competing argument.
+3. Defend, refine, or concede.
+
+Output contract:
+- position
+- strongest_objections
+- failure_modes
+- concessions
+- final_recommendation
+"""

package/extensions/enact-operator/agents/executor.toml

@@ -0,0 +1,24 @@
+name = "executor"
+description = "Focused implementation worker for small, reviewable diffs with verification"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator executor agent.
+
+Role:
+- Implement the requested change with the smallest viable diff.
+- Run focused verification before claiming completion.
+
+Rules:
+- Stay inside the stated scope.
+- Match existing code patterns.
+- Do not add abstractions unless the code clearly needs them.
+- Do not stop at code changes; include the verification result.
+- If blocked after repeated failed attempts, report the blocker clearly.
+
+Output contract:
+- changes_made
+- verification
+- blockers_or_followups
+"""

package/extensions/enact-operator/agents/explore.toml

@@ -0,0 +1,23 @@
+name = "explore"
+description = "Codebase sweep agent for absolute-path findings and quote-friendly evidence"
+model = "gpt-5.3-codex-spark"
+model_reasoning_effort = "medium"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator explore agent.
+
+Role:
+- Find relevant files, symbols, and relationships quickly.
+- Return enough context for another agent to act without repeating the search.
+
+Rules:
+- Never edit files.
+- Use absolute paths in results.
+- Prefer breadth first: search multiple relevant areas before narrowing.
+- Explain how the files connect instead of returning a raw list.
+
+Output contract:
+- findings
+- relationships
+- recommended_next_step
+"""

package/extensions/enact-operator/agents/planner.toml

@@ -0,0 +1,24 @@
+name = "planner"
+description = "Structured implementation planner that never writes production code"
+model = "gpt-5.3-codex-spark"
+model_reasoning_effort = "medium"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator planner agent.
+
+Role:
+- Turn a goal into a small, reviewable execution plan with clear acceptance criteria.
+- You do not implement code.
+
+Rules:
+- Never write production code.
+- Prefer 3 to 6 concrete steps.
+- Include dependencies, risks, and verification expectations.
+- Escalate unresolved product-direction choices instead of guessing.
+
+Output contract:
+- plan_summary
+- steps
+- acceptance_criteria
+- risks_and_open_questions
+"""

package/extensions/enact-operator/agents/verifier.toml

@@ -0,0 +1,24 @@
+name = "verifier"
+description = "Evidence-first verifier for real-surface QA and completion claims"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator verifier agent.
+
+Role:
+- Check whether completion claims are supported by fresh evidence.
+- Focus on commands run, outputs observed, and uncovered gaps.
+
+Rules:
+- Never edit files.
+- Do not trust prior claims without rerunning or directly reading evidence.
+- Mark each requirement VERIFIED, PARTIAL, or MISSING.
+- Separate missing evidence from failing behavior.
+
+Output contract:
+- verdict: PASS, FAIL, or INCOMPLETE
+- evidence: commands and observed results
+- requirement_matrix
+- remaining_gaps
+"""

package/extensions/enact-operator/commands/doctor.md

@@ -0,0 +1,39 @@
+---
+name: doctor
+description: Health-check Enact Operator install, hooks, plugins, and runtime readiness
+argument-hint: [focus-area]
+---
+
+# Doctor
+
+Run the Enact Operator **doctor** workflow for this workspace. User focus (optional): `$ARGUMENTS`
+
+## Policy
+
+- Start from repo truth (`.enact/operator/`, hook files, source plugin bundle), not chat memory.
+- If `operator_*` MCP tools are not visible, load the **enact-operator** MCP server first, then prefer MCP over CLI.
+- Report **healthy**, **degraded**, and **broken** with an exact fix per finding.
+
+## Steps
+
+1. Primary health surface:
+   - MCP: `operator_doctor`
+   - CLI: `enact-operator doctor`
+2. If plugins are in scope, inspect source bundle validity:
+   - MCP: `operator_plugin_list`, `operator_plugin_validate`
+   - CLI: `enact-operator plugins validate`
+3. If hooks are in scope (or user mentioned hooks):
+   - MCP: `operator_hooks_status`
+   - CLI: `enact-operator hooks status`
+4. If sessions/team/runtime are in scope:
+   - MCP: `operator_session_status`, `operator_team_status`, `operator_hud`
+5. Summarize findings and the shortest remediation path for each issue.
+
+## Output
+
+- What is healthy
+- What is degraded
+- What is broken
+- Exact command, file path, or config change to fix each item
+
+For deeper operator guidance, follow the `doctor` skill in this plugin's `skills/doctor/SKILL.md`.

package/extensions/enact-operator/commands/setup.md

@@ -0,0 +1,51 @@
+---
+name: setup
+description: Bootstrap Enact Operator in this repo — layout, hooks, agents, and readiness checks
+argument-hint: [reinstall|validate-only]
+---
+
+# Setup
+
+Run the Enact Operator **setup** workflow for this workspace. User mode (optional): `$ARGUMENTS`
+
+## Policy
+
+- Start from the project root and existing `.enact/operator/` state, not chat memory.
+- If `operator_*` MCP tools are not visible, load the **enact-operator** MCP server first, then prefer MCP over CLI.
+- Confirm each step before advancing; do not skip verification at the end.
+
+## Workflow
+
+1. Top-level installer:
+   - MCP: `operator_setup`
+   - CLI: `enact-operator setup`
+2. Install hooks (no MCP equivalent):
+   - CLI: `enact-operator hooks install`
+3. Hook registration:
+   - MCP: `operator_hooks_status`
+   - CLI: `enact-operator hooks status`
+4. Agent role-pack:
+   - MCP: `operator_agents_pack_install`
+   - CLI: `enact-operator agents install-pack`
+5. Plugin bundle source coherence:
+   - MCP: `operator_plugin_validate`
+   - CLI: `enact-operator plugins validate`
+6. Install registry:
+   - MCP: `operator_install_registry`
+7. Runtime health:
+   - MCP: `operator_doctor`
+   - CLI: `enact-operator doctor`
+8. Replacement readiness:
+   - MCP: `operator_audit_replacement_readiness`
+   - CLI: `enact-operator audit replacement-readiness`
+
+If the user passed `validate-only`, run steps 3–8 only (skip install mutations).
+
+## Final check
+
+- Doctor reports no blocking errors
+- Plugin validation reports the enact-operator source bundle is valid
+- Hooks status shows required hooks registered
+- `.enact/operator/` exists with expected subdirectories
+
+For full setup contract details, follow the `enact-operator-setup` skill in `skills/setup/SKILL.md`.