@amsterdamdatalabs/enact-extensions 0.1.3 → 0.1.8

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

@@ -0,0 +1,71 @@
+---
+name: plan
+description: "Execution-plan mode that turns intent into small, verifiable slices backed by durable .enact/loop artifacts."
+---
+
+# Plan
+
+## Purpose
+
+Use `$plan` to create execution-ready slices. The output is not a strategy memo. It is the
+prompt-quality plan that downstream execution can follow without improvising core behavior.
+
+## Use When
+
+- the work is bigger than a one-shot edit
+- the request is clear enough to plan but not yet safe to execute
+- verification, dependencies, or sequencing need to be locked in
+
+## Do Not Use When
+
+- the task is still ambiguous enough for `$deep-interview`
+- the change is a trivial single-file fix
+- the user explicitly wants direct execution and the risk is low
+
+## Execution Policy
+
+- gather repo facts before asking about internals
+- plans are prompts for execution, not prose for humans only
+- every slice must fit in one focused context window
+- every slice must have explicit verification
+- prefer a small number of high-quality slices over a long TODO dump
+
+## Plan Anatomy
+
+Each slice should answer:
+
+- what files are likely to change
+- what the slice must do
+- how to verify it
+- what counts as done
+- what it depends on
+
+## Workflow
+
+1. Read current intent artifacts:
+   - `.enact/loop/plans/*-requirements.md`
+   - `.enact/loop/plans/brownfield-map.md`
+2. Derive the must-haves from the goal backward:
+   - what must be true when this is done?
+   - what artifacts and connections are required for those truths?
+3. Split the work into waves and slices:
+   - interface or contracts first
+   - implementation second
+   - verification and wiring last
+4. Write or refine:
+   - active phase plan
+   - verification map
+   - loop contract stages (mechanical vs. judgment per slice)
+
+## Quality Bar
+
+- no vague acceptance criteria
+- no "make it work" tasks
+- no giant slice that hides three subsystems
+- no verify step that depends on hope
+
+## Deliverables
+
+- `.enact/loop/plans/<phase>.md`
+- `.enact/loop/plans/<phase>-verification.md`
+- updated brownfield map or research summary when needed

package/extensions/enact-factory/skills/remove-deadcode/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: remove-deadcode
+description: "LSP-verified symbol deletion with entry-point guards and candidate-parallel execution."
+---
+
+# Remove Deadcode
+
+## Purpose
+
+Use `$remove-deadcode` to remove provably unused code symbols without damaging runtime entry points.
+
+## Preconditions
+
+- collect candidate symbols before any deletion
+- load optional entry-point guard list from `.enact/loop/remove-deadcode/entry-points.txt`
+
+## Required Safety Contract
+
+For each candidate symbol, the deletion gate is strict:
+
+1. If symbol is listed in the entry-point guard file, skip deletion unconditionally.
+2. Otherwise call `lsp_find_references` (via enact-context).
+3. If references are non-empty, abort deletion for that symbol and emit an explanatory message.
+4. Only delete when references are exactly zero and the symbol is not guarded.
+
+## Execution Model
+
+- batching is explicit: enumerate all candidates first
+- then dispatch parallel `executor` subagents, one candidate per subagent
+- each subagent must apply the same guard-list and `lsp_find_references` checks
+
+## Behavioral Constraints
+
+- no heuristic-only deletion
+- no bypass of entry-point guard list
+- no GitHub-specific assumptions or workflows in deletion decisions
+
+## Verification Expectations
+
+- unit test: non-empty `lsp_find_references` result must refuse deletion
+- unit test: guard-listed symbol must be skipped even when reference count is zero

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

@@ -0,0 +1,73 @@
+---
+name: research
+description: "Evidence-first research mode for current patterns, implementation risks, and decision support."
+---
+
+# Research
+
+## Purpose
+
+Use `$research` when the correct implementation depends on facts you do not yet have, either from the repo or from current external sources.
+
+## Execution Policy
+
+- start with brownfield evidence from the repo
+- use primary sources for technical questions
+- end with a decision-ready recommendation, not a wall of notes
+- persist findings so the next pass does not repeat the work
+
+## Workflow
+
+1. Identify the actual unknowns.
+2. Separate:
+   - repo truth
+   - external truth
+   - assumptions
+3. Gather only the evidence needed to decide.
+4. Write the result into `.enact/loop/research/summary.md`.
+5. Update any linked loop contract or task state if the research is part of an active execution lane.
+
+## Parallel Sweep
+
+Run concurrent research agents for independent evidence lanes. The floor is 2 concurrent agents whenever there are both repo-truth and external-truth unknowns.
+
+- minimum concurrent-agent floor: 2
+- recommended split: one agent for internal repo evidence and one agent for external primary sources
+- increase concurrency only when unknowns are independent and synthesis cost remains manageable
+
+Anti-stop rule: do not stop at the first result. Continue each lane until at least one corroborating source is collected per lane, or until an explicit blocker is documented.
+
+## Runtime Clarification
+
+- `$research` is an evidence pass, not a closure-owning runtime lane.
+- If research output is being used to support closure on a live loop, rely
+  on the real loop proof surfaces rather than treating research notes as
+  equivalent to stage evidence:
+  - `loop_grade` (for mechanical stages with command evidence)
+  - `loop_grader_dispatch` + `loop_grader_verdict` (for judgment stages)
+  - `loop_contract_parity` (for contract-parity checks)
+
+## Deliverables
+
+- current pattern or contract summary
+- risk list
+- recommendation with concrete tradeoffs
+- open questions that still block planning or execution
+
+### Internal Evidence
+
+- repo paths inspected
+- commands or tools used
+- concrete findings tied to files, code, or runtime state
+- unresolved internal gaps
+
+### External Evidence
+
+- primary sources consulted
+- dated facts and version-sensitive constraints
+- corroboration across at least one additional source
+- unresolved external gaps
+
+## Activation
+
+Invoke with `$research` or `$enact-loop:research`. This skill is a stateless evidence pass — no durable workflow state is started automatically. If enact-loop MCP tools are available, prefer them for any stage recording that flows from the research output.

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

@@ -0,0 +1,48 @@
+---
+name: review
+description: "Findings-first pre-landing review against code, plan completion, verification evidence, and loop state."
+---
+
+# Review
+
+## Purpose
+
+Use `$review` to answer one question: is this actually ready to land? Review is not a summary pass.
+It is a bug, regression, coverage, and state-integrity pass.
+
+## Execution Policy
+
+- findings first, summary second
+- prefer evidence over author claims
+- check the code, the tests, the plan, and the loop artifacts
+- if the current context authored the change, prefer a separate reviewer role for approval
+
+## Review Order
+
+1. Read the changed code.
+2. Read the active plan and verification map.
+3. Check what was supposed to happen vs what actually landed.
+4. Verify:
+   - tests and typechecks
+   - docs drift
+   - `.enact/loop/` state drift
+   - judgment stages have valid independent grader verdicts
+5. Produce a verdict:
+   - approved
+   - changes requested
+   - blocked
+
+## Mandatory Checks
+
+- missing or fake verification
+- uncovered changed paths
+- stale docs or setup instructions
+- task marked done but still pending review evidence
+- judgment stages with self-reported verdicts (flag as grader-independence-missing)
+
+## Output Standard
+
+- findings ordered by severity
+- file references and why they matter
+- residual risk
+- final verdict and next action

package/extensions/enact-factory/skills/security-research/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: security-research
+description: "Multi-agent security research with hunter/PoC split and optional critical bug auto-creation in Azure DevOps."
+---
+
+# Security Research
+
+## Purpose
+
+Use `$security-research` to run a focused vulnerability hunt, produce ranked findings, and optionally create Azure DevOps Bug work items for critical issues.
+
+## Parameters
+
+- `autoCreateBugs: boolean` (default `true`)
+- when `false`, no `factory_workitem_sync_once` call is allowed regardless of severity
+
+## Team Topology
+
+- 3 hunter agents:
+- hunter 1: CWE classification
+- hunter 2: CVSS v4 scoring
+- hunter 3: OWASP category mapping
+- 2 PoC engineer agents:
+- PoC 1 and PoC 2: exploitability proof and reproduction quality
+
+## Required Workflow
+
+1. Launch hunters to identify and classify potential vulnerabilities.
+2. Launch PoC engineers on top-ranked findings to validate exploitability.
+3. Merge outputs into a single findings report.
+4. Write report to `.enact/factory/security/<sessionId>/findings.md`.
+5. Rank findings in the report by CVSS v4 severity.
+6. For each finding with CVSS v4 `>= 9.0`, if `autoCreateBugs=true`, call `factory_workitem_sync_once` to create a `Bug` work item.
+7. If `autoCreateBugs=false`, skip all bug auto-creation calls.
+
+## Azure DevOps-Only Contract
+
+- use factory MCP work-item surfaces for bug creation
+- no GitHub Security Advisories, GitHub issue creation, or GitHub-specific security automation assumptions
+
+## Behavioral Constraints
+
+- CVSS scoring must be v4, not v3 fallback
+- critical auto-bug creation threshold is fixed at `>= 9.0`
+- findings must include at least one of: CWE, CVSS v4 vector/score, OWASP mapping
+
+## Verification Expectations
+
+- integration test: findings report includes at least one CWE classification entry
+- integration test: with `autoCreateBugs=false`, verify no `factory_workitem_sync_once` call is made
+
+## Activation
+
+Invoke with `$security-research` or `$enact-factory:security-research`. This skill uses enact-factory MCP tools for work-item creation. No durable workflow state is started automatically — the skill produces findings within a single session.

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

@@ -0,0 +1,56 @@
+---
+name: tdd
+description: "Red-green-refactor mode for behavior with clear inputs, outputs, and regression value."
+---
+
+# TDD
+
+## Purpose
+
+Use `$tdd` when behavior can be specified before implementation. TDD is for design pressure and
+regression safety, not for ritual.
+
+## Good TDD Candidates
+
+- business rules
+- API contracts
+- parsing, formatting, or validation
+- state transitions
+- algorithms and utility behavior
+
+## Skip TDD For
+
+- pure layout and styling work
+- config-only changes
+- trivial glue code
+- exploratory prototypes where behavior is not yet known
+
+## Iron Law
+
+No production code without a failing test first.
+
+## Cycle
+
+1. Red
+   - write the smallest failing test for the next behavior
+   - run it and prove it fails for the right reason
+2. Green
+   - write the minimum code to make it pass
+   - rerun the test and the relevant suite
+3. Refactor
+   - clean up only after green
+   - keep the suite green after every change
+
+## Rules
+
+- one behavior per cycle
+- do not batch multiple features into one red-green pass
+- prefer regression tests for changed behavior
+- record the verify command in the plan or task notes
+
+## Output Standard
+
+- what behavior the test locked in
+- the failing signal
+- the minimal implementation
+- the final verification command

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

@@ -0,0 +1,37 @@
+---
+name: trace
+description: "Execution-path mapping for entry points, data flow, side effects, and blast radius before risky work."
+---
+
+# Trace
+
+## Purpose
+
+Use `$trace` before a risky edit or review when you need to know what code path actually runs, what
+it touches, and what could break downstream.
+
+## Workflow
+
+1. Find the entry points.
+2. Follow data flow through the changed or targeted path.
+3. Map side effects:
+   - storage writes
+   - network calls
+   - UI state changes
+   - background work
+4. Identify risky branches and missing guards.
+5. Name the concrete files the next pass should touch.
+
+## Suggested Tools
+
+- `ctx_search` for symbol and path discovery
+- `ctx_read` for call-path confirmation
+- `ctx_semantic_search` or `ctx_graph` when lexical search is not enough
+
+## Output Standard
+
+- entry points
+- downstream side effects
+- risky branches
+- likely blast radius
+- recommended edit boundary

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

@@ -0,0 +1,79 @@
+---
+name: ultraqa
+description: "QA cycling workflow with hard-stop verification gates: tests, lint, smoke execution, and loop-contract persistence."
+lane: true
+---
+
+# UltraQA
+
+## Purpose
+Combines `$loop` (durable contract-runner with closure gates) with an explicit set of QA gates. Each gate must pass before the loop advances. The cycle is: implement a fix, run all gates, advance only when green, repeat until every gate is clean in a single run.
+
+## Use When
+- Verification has failed and a structured fix-verify cycle is needed
+- A feature must be proven working end-to-end before merging
+- A hard record of each verification pass and failure is required
+
+## Execution Policy
+
+- start from the repo and `.enact/loop/` truth, not chat memory
+- drive the QA loop through loop MCP tools; CLI commands are the fallback
+- keep loop state current as you go
+- do not stop until all gates pass in a single clean run
+
+## Workflow
+1. Start a loop contract scoped to the QA goal:
+   - MCP: `loop_start` with `goal` and QA gate stages as the contract
+   - CLI: `enact-loop loop start --goal "<what must be verified>"`
+2. Check current loop status before each iteration:
+   - MCP: `loop_status`
+   - CLI: `enact-loop loop status`
+3. Run each QA gate in sequence. All must pass before advancing:
+   - Unit and integration tests (run the project's test command)
+   - Lint and type checks (run the project's lint command)
+   - Doctor / readiness check (run the project's doctor command if present)
+   - Real-execution smoke test (invoke the primary feature with real inputs, not mocks)
+4. Record each gate result:
+   - MCP: `loop_grade` with `stageId`, `status=passed|failed`, and `evidence="<command + output>"`
+   - All gate results must include command evidence, not just a pass/fail assertion.
+5. After all mechanical gates pass, advance to verifying:
+   - MCP: `loop_advance` with `toPhase=verifying`
+6. If a judgment review is required before completing, dispatch a grader:
+   - MCP: `loop_grader_dispatch` with `stageId`; await `loop_grader_verdict`
+7. When all required stages are passed, complete the loop:
+   - MCP: `loop_complete` with `summary`
+   - CLI: `enact-loop loop complete`
+
+## Proof Path
+
+- Use `loop_contract_parity` for contract-parity checks when QA is part of closure.
+- Judgment stages require an independent grader (different vendor/model) via `loop_grader_dispatch`.
+- Do not substitute inferred status for command-backed evidence.
+
+## State Contract
+- Reads: `.enact/loop/state/loop.json` (loop state), test and lint output
+- Writes: loop state via MCP tools (`loop_grade`, `loop_advance`, `loop_complete`)
+
+## MCP Tools
+
+- `loop_start` — start a loop contract scoped to the QA goal
+- `loop_status` — read current loop state
+- `loop_advance` — transition to the next phase
+- `loop_grade` — record a mechanical gate result with command evidence
+- `loop_grader_dispatch` — dispatch an independent grader for a judgment gate
+- `loop_grader_verdict` — record an independent grader's GO/NO-GO
+- `loop_block` — mark blocked with a reason
+- `loop_complete` — close the loop after all gates pass
+- `loop_abort` — abort the loop with a reason
+- `loop_contract_parity` — run contract-parity check
+
+## Activation
+
+Invoke with `$ultraqa` or `$enact-loop:ultraqa`. The SessionStart hook auto-resumes any active loop from `.enact/loop/state/loop.json`. The Stop boulder blocks exit until all required stages are passed and the loop phase is terminal.
+
+## Final Check
+- Every gate (tests, lint, doctor, smoke) passed in a single iteration with command evidence
+- `loop_grade` recorded as `passed` for all mechanical stages before `loop_complete`
+- Judgment stages have valid independent grader verdicts from `loop_grader_verdict`
+- No gate was skipped or bypassed
+- `loop_complete` was called; no loop left in `running` or `verifying` state

package/extensions/enact-factory/skills/work-with-workitem/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: work-with-workitem
+description: "Lightweight Azure DevOps work-item delivery lane: implement and hand off; factory owns tracking and closure."
+---
+
+# Work With Workitem
+
+## Purpose
+
+Use `$work-with-workitem` for agent-driven delivery tied to a single Azure DevOps work item.
+
+## Domain Boundary
+
+- agent scope is intentionally lightweight: load, isolate, implement, PR, handoff, cleanup
+- enact-factory owns CI heartbeat tracking, branch policy waits, auto-merge, and lifecycle advance to `Closed`
+- this skill must not add CI polling loops or unbounded branch-policy waiting
+
+## Azure DevOps-Only Contract
+
+- use `factory_workitem_get` and `factory_assignment_record` for work-item reads and closing notes
+- use `az repos pr create --work-items <id>` to link the PR to the work item
+- do not assume or reference GitHub APIs, GitHub Actions, GitHub checks, or GitHub branch protection primitives
+
+## Required Sequence
+
+1. `factory_workitem_get` loads the target work item and confirms readiness.
+2. `EnterWorktree` isolates the implementation workspace.
+3. Execute implementation (use a loop contract or inline execution for simple tasks).
+4. Create atomic commits with clear work-item-linked intent.
+5. Run `az repos pr create --work-items <id>` and capture the PR URL.
+6. Call `factory_assignment_record` with a closing note that includes PR URL and commit SHA.
+7. `ExitWorktree` cleans up the isolated workspace.
+
+## Behavioral Constraints
+
+- no CI poll loop in this skill; CI heartbeat belongs to `factory_watchdog_status`
+- no merge waiting or policy-wait ownership in this skill
+- no lifecycle mutation to `Closed` from this skill
+- if PR creation fails, record failure context and exit through normal cleanup
+
+## Verification Expectations
+
+- integration target is a work item tagged `test-fixture`
+- verify PR link uses `--work-items <id>`
+- verify `factory_assignment_record` includes PR URL and commit SHA
+- verify `ExitWorktree` cleanup is executed
+- do not verify CI completion or merge here
+
+## Activation
+
+Invoke with `$work-with-workitem` or `$enact-factory:work-with-workitem`. The skill uses enact-factory MCP tools (`factory_workitem_get`, `factory_assignment_record`) for all work-item interactions. No durable workflow state is started automatically — the skill runs to completion within a single session.

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

@@ -1,3 +1,13 @@
+---
+name: workitem-triage
+description: >-
+  Read-only triage of Enact Factory WorkItems — assess queue state and
+  individual WorkItem details without scheduling, mutation, or execution. Use
+  when reviewing the board, checking a WorkItem's status/blockers, or triaging
+  the queue. Triggers on "triage", "workitem status", "queue state",
+  "$workitem-triage".
+---
+
 # workitem-triage
 
 ## Purpose
@@ -20,3 +30,8 @@ Provide a read-only triage surface for Factory WorkItems. This skill is for asse
 - 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.
+
+## Related
+- For the Azure DevOps branch/PR/release strategy and the `az` CLI/REST recipes
+  (branch policies, PR creation/promotion, build-failure diagnosis), see the
+  sibling `azdo-ci-strategy` skill.

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

@@ -0,0 +1,46 @@
+{
+  "name": "enact-loop",
+  "version": "0.1.0",
+  "description": "Generic contract-runner state machine. Drives declared stages (mechanical and judgment) to closure; judgment gates are graded by independent agents on a different vendor/model.",
+  "author": {
+    "name": "amsterdamdatalabs"
+  },
+  "homepage": "https://amsterdamdatalabs.com",
+  "repository": "https://dev.azure.com/amsterdamdatalabs/Enact/_git/enact-loop",
+  "license": "UNLICENSED",
+  "keywords": [
+    "enact",
+    "loop",
+    "contract-runner",
+    "verification",
+    "independent-grading"
+  ],
+  "targets": [
+    "claude",
+    "codex",
+    "cursor"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "validate": "enact-loop doctor",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Enact Loop",
+    "shortDescription": "Contract-runner loop with independent judgment grading.",
+    "longDescription": "Runs any declared contract (ordered stages: mechanical and judgment) to closure. The Stop boulder refuses to exit until every required stage passes. Judgment stages are graded by independent agents running on a different vendor/model — no self-grading. Mechanical stages self-report via command evidence. Designed as the slim successor to enact-operator.",
+    "developerName": "enact-loop",
+    "category": "Developer Tools",
+    "capabilities": [
+      "contract-runner state machine",
+      "independent judgment grading",
+      "stop boulder enforcement",
+      "session auto-resume",
+      "mechanical stage self-report",
+      "loop lifecycle MCP tools"
+    ]
+  },
+  "factory": {
+    "firstParty": true,
+    "operatorScope": "global"
+  }
+}

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

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

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

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-loop hook session-start",
+            "statusMessage": "Resuming active loop"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-loop hook stop",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}