@amsterdamdatalabs/enact-extensions 0.1.10 → 0.1.24

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

@@ -5,6 +5,11 @@ description: "Plan-first loop execution wrapper: write a durable plan, enter the
 
 # Looplan
 
+> **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>/…`; loop runtime state under `~/.enact/loop/projects/<key>/…`.
+
 ## Purpose
 
 Use `$looplan` when the work needs a reviewable execution plan before the loop starts. Looplan gates
@@ -34,16 +39,22 @@ intent → $plan (write plan + verification map) → user review → $loop start
 
 Each transition is explicit. Never advance to the loop before the plan artifact exists and is reviewed.
 
+## Timestamped Artifact Naming
+
+All durable factory markdown artifacts use `YYMMDDHH-<slug>.md` where `YYMMDDHH=$(date +%y%m%d%H)`.
+Use the **same** prefix for the plan and verification map written in one planning pass.
+**Never overwrite** a prior plan file — each looplan run writes fresh timestamped artifacts.
+
 ## Workflow
 
 ### Phase 1 — Plan
 
-1. Read current artifacts and inspect the repo for brownfield context.
-2. Write the plan to `.enact/loop/plans/<phase>.md` following `$plan` conventions:
+1. Read current artifacts and inspect the repo for brownfield context (latest timestamped files per `$plan` resolution rules).
+2. Write the plan to `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>.md` following `$plan` conventions:
    - Named files per slice
    - Explicit verification per slice
    - Exit conditions stated
-3. Write the verification map to `.enact/loop/plans/<phase>-verification.md`.
+3. Write the verification map to `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>-verification.md`.
 4. Present the plan for review. Do not advance until it is approved.
 
 ### Phase 2 — Execute
@@ -54,8 +65,12 @@ Each transition is explicit. Never advance to the loop before the plan artifact
    ```
 6. Confirm the loop is running: `loop_status`
 7. Execute each plan slice.
-   - Mechanical stages: run the command, then `loop_grade`.
-   - Judgment stages: `loop_grader_dispatch`, await `loop_grader_verdict`.
+   - Mechanical stages: `loop_grade({ stageId })` — the engine runs the stage `command` in the
+     loop root and records pass/fail from exit code. Do **not** run the command separately and
+     self-report `status` or `evidence` (rejected by the runtime).
+   - Judgment stages: `loop_grader_dispatch({ stageId })` → independent grader reviews → driver
+     relays GO/NO-GO via `loop_grader_verdict` with the minted `continuationId` (default:
+     `captureSource: "relayed"`). Grader child sessions have **no closure authority**.
 8. If blocked: `loop_block` with reason, resolve, then `loop_advance` back to `running`.
 
 ### Phase 3 — Verify and Complete
@@ -65,7 +80,7 @@ Each transition is explicit. Never advance to the loop before the plan artifact
    loop_advance  toPhase=verifying
    ```
 10. Run `$review` against the completed work and plan artifacts.
-11. If review passes, complete the loop:
+11. Write the closure summary via `enact-loop summary write` (CLI stamps fingerprint header into a new `YYMMDDHH-loop-summary.md`), then complete the loop:
     ```
     loop_complete  summary="<one-line summary>"
     ```
@@ -74,30 +89,32 @@ Each transition is explicit. Never advance to the loop before the plan artifact
 ## State Contract
 
 Reads:
-- `.enact/loop/plans/*` (plan and verification map written in Phase 1)
-- `.enact/loop/state/loop.json` (loop state)
+- `~/.enact/factory/projects/<key>/plans/*` (latest timestamped plan + verification map from Phase 1)
+- `~/.enact/loop/projects/<key>/state/loop.json` (loop state)
+- `~/.enact/loop/projects/<key>/state/summary-current.json` (pointer to current closure summary)
 
 Writes:
-- `.enact/loop/plans/<phase>.md`
-- `.enact/loop/plans/<phase>-verification.md`
-- Loop state via MCP tools
+- `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>.md`
+- `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>-verification.md`
+- Loop state and closure summary via MCP/CLI only (never raw file edits)
 
 ## MCP Tools
 
 - `loop_start` — start a new loop with goal and stages
 - `loop_status` — read current loop state
 - `loop_advance` — transition to a new phase
-- `loop_grade` — record a mechanical stage result with evidence
-- `loop_grader_dispatch` — dispatch an independent grader for a judgment stage
-- `loop_grader_verdict` — record an independent grader's GO/NO-GO
+- `loop_grade` — run a mechanical stage `command` (`stageId` + optional `timeoutMs`); engine-derived pass/fail only
+- `loop_grader_dispatch` — mint `continuationId` and dispatch an independent grader for a judgment stage
+- `loop_grader_verdict` — record GO/NO-GO (driver-relayed default; direct only from registered grader child with valid `continuationId`)
 - `loop_block` — mark blocked with a reason
 - `loop_complete` — close the loop with a summary
 - `loop_abort` — abort with a reason
 
 ## Final Check
 
-- Plan artifact exists at `.enact/loop/plans/<phase>.md` before loop was started
-- All stages have evidence recorded, not just a passed status
-- Judgment stages have valid independent grader verdicts
+- Plan artifact exists at `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>.md` before loop was started
+- Mechanical stages passed via engine-run `loop_grade` (command exit code), not caller-supplied status
+- Judgment stages have valid independent grader verdicts (minted `continuationId`, driver-relayed or direct with provenance)
 - `$review` verdict is approved
+- `enact-loop summary write` produced a current timestamped closure summary before `loop_complete`
 - `loop_status` shows phase as `completed`

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

@@ -1,10 +1,15 @@
 ---
 name: plan
-description: "Execution-plan mode that turns intent into small, verifiable slices backed by durable .enact/loop artifacts."
+description: "Execution-plan mode that turns intent into small, verifiable slices backed by durable global loop artifacts."
 ---
 
 # Plan
 
+> **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 `$plan` to create execution-ready slices. The output is not a strategy memo. It is the
@@ -29,6 +34,32 @@ prompt-quality plan that downstream execution can follow without improvising cor
 - 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
+- **never overwrite an existing plan artifact in place** — each planning pass writes a new timestamped file
+
+## Timestamped Artifact Naming
+
+All durable factory markdown artifacts use `YYMMDDHH-<slug>.md` where `YYMMDDHH=$(date +%y%m%d%H)` (8 digits, hour granularity).
+
+Examples:
+- `plans/26062203-foundations-hardening.md`
+- `plans/26062203-foundations-hardening-verification.md`
+- `plans/26062203-foundations-hardening-requirements.md`
+- `plans/26062203-foundations-brownfield-map.md`
+- `research/26062203-auth-token-research.md`
+
+Use the **same** `YYMMDDHH` prefix for a plan and its verification map written in the same pass.
+
+## Active Artifact Resolution
+
+When reading (not writing), resolve the latest matching artifact:
+
+1. Prefer the path recorded in the current session/run if one was emitted.
+2. Else pick the lexicographically greatest `YYMMDDHH` among files matching the semantic suffix:
+   - requirements: `*-requirements.md`
+   - plan: `*-{phase}.md` (exclude `-verification` and `-requirements`)
+   - verification: `*-{phase}-verification.md`
+   - brownfield: `*-brownfield-map.md`
+3. If no timestamped file exists, fall back to legacy unprefixed names only for migration reads — never write new unprefixed files.
 
 ## Plan Anatomy
 
@@ -42,9 +73,10 @@ Each slice should answer:
 
 ## Workflow
 
-1. Read current intent artifacts:
-   - `.enact/loop/plans/*-requirements.md`
-   - `.enact/loop/plans/brownfield-map.md`
+1. Read current intent artifacts (latest by rules above):
+   - `~/.enact/factory/projects/<key>/plans/*-requirements.md`
+   - `~/.enact/factory/projects/<key>/plans/*-brownfield-map.md`
+   - any `hyperplan/<sessionId>/` debate bundle from `$hyperplan` when present
 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?
@@ -52,7 +84,7 @@ Each slice should answer:
    - interface or contracts first
    - implementation second
    - verification and wiring last
-4. Write or refine:
+4. Write **new** timestamped artifacts (do not edit prior plan files):
    - active phase plan
    - verification map
    - loop contract stages (mechanical vs. judgment per slice)
@@ -66,6 +98,6 @@ Each slice should answer:
 
 ## Deliverables
 
-- `.enact/loop/plans/<phase>.md`
-- `.enact/loop/plans/<phase>-verification.md`
-- updated brownfield map or research summary when needed
+- `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>.md`
+- `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>-verification.md`
+- write **new** `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<topic>-brownfield-map.md` when the brownfield map changes (append-only; never edit a prior brownfield file in place)

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

@@ -5,6 +5,11 @@ description: "LSP-verified symbol deletion with entry-point guards and candidate
 
 # Remove Deadcode
 
+> **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 `$remove-deadcode` to remove provably unused code symbols without damaging runtime entry points.
@@ -12,7 +17,7 @@ Use `$remove-deadcode` to remove provably unused code symbols without damaging r
 ## Preconditions
 
 - collect candidate symbols before any deletion
-- load optional entry-point guard list from `.enact/loop/remove-deadcode/entry-points.txt`
+- load optional entry-point guard list from `~/.enact/factory/projects/<key>/remove-deadcode/entry-points.txt`
 
 ## Required Safety Contract
 

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

@@ -5,6 +5,15 @@ description: "Evidence-first research mode for current patterns, implementation
 
 # Research
 
+> **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>/…`.
+
+## Active Artifact Resolution
+
+When reading prior research, pick the lexicographically greatest `YYMMDDHH` among files in `research/<YYMMDDHH>-*.md`. Never write unprefixed research filenames.
+
 ## Purpose
 
 Use `$research` when the correct implementation depends on facts you do not yet have, either from the repo or from current external sources.
@@ -24,7 +33,7 @@ Use `$research` when the correct implementation depends on facts you do not yet
    - external truth
    - assumptions
 3. Gather only the evidence needed to decide.
-4. Write the result into `.enact/loop/research/summary.md`.
+4. Write the result into `~/.enact/factory/projects/<key>/research/<YYMMDDHH>-<kebab-title>.md` (e.g. `research/26062101-auth-token-research.md`). Resolve `<key>` from `~/.enact/workspaces.json` as described in the Storage banner above; get the timestamp prefix via `date +%y%m%d%H`.
 5. Update any linked loop contract or task state if the research is part of an active execution lane.
 
 ## Parallel Sweep
@@ -43,8 +52,9 @@ Anti-stop rule: do not stop at the first result. Continue each lane until at lea
 - 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_grade({ stageId })` — engine runs the mechanical stage `command`; caller-supplied
+    `status`/`evidence` are rejected
+  - `loop_grader_dispatch` + driver-relayed `loop_grader_verdict` (minted `continuationId`) for judgment stages
   - `loop_contract_parity` (for contract-parity checks)
 
 ## Deliverables
@@ -70,4 +80,4 @@ Anti-stop rule: do not stop at the first result. Continue each lane until at lea
 
 ## 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.
+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, use them for stage recording that flows from research output — mechanical via `loop_grade({ stageId })`, judgment via dispatched grader + relayed verdict — not by citing research markdown as pass evidence.

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

@@ -5,6 +5,11 @@ description: "Findings-first pre-landing review against code, plan completion, v
 
 # Review
 
+> **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 artifacts go under `~/.enact/factory/projects/<key>/…`; loop runtime under `~/.enact/loop/projects/<key>/…`.
+
 ## Purpose
 
 Use `$review` to answer one question: is this actually ready to land? Review is not a summary pass.
@@ -17,16 +22,29 @@ It is a bug, regression, coverage, and state-integrity pass.
 - 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
 
+## Active Artifact Resolution
+
+Resolve the plan and verification map to review:
+
+1. Prefer paths recorded in the active loop/run session when available.
+2. Else under `~/.enact/factory/projects/<key>/plans/`, pick the lexicographically greatest `YYMMDDHH` among:
+   - plan files matching `*-{phase}.md` (exclude `-verification` and `-requirements`)
+   - verification files matching `*-{phase}-verification.md` with the **same** `YYMMDDHH` prefix as the plan when possible
+3. Fall back to legacy unprefixed plan names only for reads during migration — never treat them as the write contract.
+
+For loop closure, read the current summary via `enact-loop summary show` or `summary-current.json` under `~/.enact/loop/projects/<key>/state/`.
+
 ## Review Order
 
 1. Read the changed code.
-2. Read the active plan and verification map.
+2. Read the active plan and verification map (resolved per rules above).
 3. Check what was supposed to happen vs what actually landed.
 4. Verify:
    - tests and typechecks
    - docs drift
-   - `.enact/loop/` state drift
+   - `~/.enact/factory/projects/<key>/` state drift
    - judgment stages have valid independent grader verdicts
+   - closure summary exists and fingerprint is current when the loop is closure-ready
 5. Produce a verdict:
    - approved
    - changes requested
@@ -39,6 +57,7 @@ It is a bug, regression, coverage, and state-integrity pass.
 - stale docs or setup instructions
 - task marked done but still pending review evidence
 - judgment stages with self-reported verdicts (flag as grader-independence-missing)
+- closure-ready loop without a current timestamped summary artifact
 
 ## Output Standard
 

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

@@ -5,7 +5,10 @@ description: "Multi-agent security research with hunter/PoC split and optional c
 
 # Security Research
 
-## Purpose
+> **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. Security findings go under `~/.enact/factory/projects/<key>/security/…`.
 
 Use `$security-research` to run a focused vulnerability hunt, produce ranked findings, and optionally create Azure DevOps Bug work items for critical issues.
 
@@ -28,7 +31,7 @@ Use `$security-research` to run a focused vulnerability hunt, produce ranked fin
 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`.
+4. Write report to `~/.enact/factory/projects/<key>/security/<sessionId>/<YYMMDDHH>-findings.md` (e.g. `security/abc123/26062101-findings.md`). Resolve `<key>` from `~/.enact/workspaces.json`; get the timestamp prefix via `date +%y%m%d%H`.
 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.

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

@@ -5,6 +5,11 @@ description: "Red-green-refactor mode for behavior with clear inputs, outputs, a
 
 # TDD
 
+> **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>/…`.
+
 ## Purpose
 
 Use `$tdd` when behavior can be specified before implementation. TDD is for design pressure and
@@ -46,7 +51,8 @@ No production code without a failing test first.
 - 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
+- record the verify command in the current timestamped plan artifact (for example
+  `~/.enact/factory/projects/<key>/plans/<YYMMDDHH>-<phase>.md`) or in linked task notes
 
 ## Output Standard
 

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

@@ -8,6 +8,11 @@ description: >
 
 # testing-strategy
 
+> **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>/…`. Local `_evidence/` remains a repo-local proof surface for Mode 1 only.
+
 ## Purpose
 
 Enforce a consistent, lightweight approach across the three testing modes used

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

@@ -5,6 +5,11 @@ description: "Execution-path mapping for entry points, data flow, side effects,
 
 # Trace
 
+> **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>/…`.
+
 ## Purpose
 
 Use `$trace` before a risky edit or review when you need to know what code path actually runs, what

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

@@ -6,6 +6,11 @@ lane: true
 
 # UltraQA
 
+> **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 artifacts go under `~/.enact/factory/projects/<key>/…`; loop runtime state lives under `~/.enact/loop/projects/<key>/…`.
+
 ## 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.
 
@@ -16,7 +21,7 @@ Combines `$loop` (durable contract-runner with closure gates) with an explicit s
 
 ## Execution Policy
 
-- start from the repo and `.enact/loop/` truth, not chat memory
+- start from the repo and `~/.enact/factory/projects/<key>/` 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
@@ -24,25 +29,25 @@ Combines `$loop` (durable contract-runner with closure gates) with an explicit s
 ## 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>"`
+   - CLI fallback: use the `enact-loop` runtime only for `status` / `summary write`; contract start remains MCP-first
 2. Check current loop status before each iteration:
    - MCP: `loop_status`
-   - CLI: `enact-loop loop status`
+   - CLI fallback: `enact-loop status --json`
 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.
+4. Record each mechanical gate via the engine:
+   - MCP: `loop_grade({ stageId, timeoutMs? })` — engine runs the stage command in loop root; rejects caller `status`/`evidence`
 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:
+6. If a judgment review is required, dispatch a grader and relay the verdict:
+   - MCP: `loop_grader_dispatch({ stageId })` → driver relays via `loop_grader_verdict` (`captureSource: "relayed"`)
+7. When all required stages are passed, write the closure summary then complete the loop:
+   - CLI: `enact-loop summary write` (stamps fingerprint into `~/.enact/loop/projects/<key>/state/<YYMMDDHH>-loop-summary.md` and updates `summary-current.json`)
    - MCP: `loop_complete` with `summary`
-   - CLI: `enact-loop loop complete`
+   - CLI fallback: use MCP for completion; `summary write` is the required CLI closure step
 
 ## Proof Path
 
@@ -51,15 +56,15 @@ Combines `$loop` (durable contract-runner with closure gates) with an explicit s
 - 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`)
+- Reads: `enact-loop status --json` (current loop state), `enact-loop summary show` / `summary-current.json` (current closure summary), test and lint output
+- Writes: loop state via MCP tools (`loop_grade`, `loop_advance`, `loop_complete`) and `enact-loop summary write` for the append-only closure summary artifact
 
 ## 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_grade` — run a mechanical stage command in loop root (engine-derived pass/fail)
 - `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
@@ -69,11 +74,12 @@ Combines `$loop` (durable contract-runner with closure gates) with an explicit s
 
 ## 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.
+Invoke with `$ultraqa` or `$enact-loop:ultraqa`. The SessionStart hook auto-resumes any active loop; use `enact-loop status --json` to inspect the current state. 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`
+- `loop_grade` passed all mechanical stages (engine-run, exit 0) before `loop_complete`
 - Judgment stages have valid independent grader verdicts from `loop_grader_verdict`
 - No gate was skipped or bypassed
+- `enact-loop summary write` produced the current timestamped closure summary before `loop_complete`
 - `loop_complete` was called; no loop left in `running` or `verifying` state

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

@@ -5,6 +5,11 @@ description: "Lightweight Azure DevOps work-item delivery lane: implement and ha
 
 # Work With Workitem
 
+> **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>/…`.
+
 ## Purpose
 
 Use `$work-with-workitem` for agent-driven delivery tied to a single Azure DevOps work item.

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

@@ -10,6 +10,11 @@ description: >-
 
 # workitem-triage
 
+> **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 and queue-state handoff notes go under `~/.enact/factory/projects/<key>/…` when a downstream skill persists them.
+
 ## 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.
 

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

@@ -18,16 +18,17 @@
   "targets": [
     "claude",
     "codex",
-    "cursor"
+    "cursor",
+    "enact"
   ],
   "skills": "./skills/",
   "hooks": "./hooks/hooks.json",
-  "validate": "enact-loop doctor",
+  "validate": "node scripts/validate.mjs",
   "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.",
+    "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 on a different model — no self-grading. Mechanical stages are engine-run via loop_grade (exit code 0 = pass).",
     "developerName": "enact-loop",
     "category": "Developer Tools",
     "capabilities": [
@@ -35,7 +36,7 @@
       "independent judgment grading",
       "stop boulder enforcement",
       "session auto-resume",
-      "mechanical stage self-report",
+      "engine-run mechanical grading",
       "loop lifecycle MCP tools"
     ]
   },

package/extensions/enact-loop/scripts/validate.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const root = process.cwd();
+const failures = [];
+
+function fail(message) {
+  failures.push(message);
+}
+
+function readJson(relativePath) {
+  const path = join(root, relativePath);
+  if (!existsSync(path)) {
+    fail(`${relativePath} is missing`);
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    fail(`${relativePath} is not valid JSON: ${message}`);
+    return null;
+  }
+}
+
+function assertEqual(actual, expected, label) {
+  if (actual !== expected) {
+    fail(`${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+function assertArrayIncludes(values, expected, label) {
+  if (!Array.isArray(values) || !values.includes(expected)) {
+    fail(`${label}: expected array to include ${JSON.stringify(expected)}`);
+  }
+}
+
+function findCommandHook(groups, expectedCommand) {
+  if (!Array.isArray(groups)) return null;
+  for (const group of groups) {
+    if (!Array.isArray(group?.hooks)) continue;
+    for (const hook of group.hooks) {
+      if (hook?.type === "command" && hook?.command === expectedCommand) {
+        return { group, hook };
+      }
+    }
+  }
+  return null;
+}
+
+const manifest = readJson(".agents/plugin.json");
+if (manifest) {
+  assertEqual(manifest.name, "enact-loop", "manifest.name");
+  assertEqual(manifest.skills, "./skills/", "manifest.skills");
+  assertEqual(manifest.hooks, "./hooks/hooks.json", "manifest.hooks");
+  assertEqual(manifest.mcpServers, "./.mcp.json", "manifest.mcpServers");
+  assertEqual(manifest.validate, "node scripts/validate.mjs", "manifest.validate");
+
+  for (const target of ["claude", "codex", "cursor", "enact"]) {
+    assertArrayIncludes(manifest.targets, target, "manifest.targets");
+  }
+}
+
+const mcp = readJson(".mcp.json");
+if (mcp) {
+  const server = mcp.mcpServers?.["enact-loop"];
+  if (!server) {
+    fail('.mcp.json must declare mcpServers["enact-loop"]');
+  } else {
+    assertEqual(server.command, "enact-loop", 'mcpServers["enact-loop"].command');
+    if (!Array.isArray(server.args)) {
+      fail('mcpServers["enact-loop"].args must be an array');
+    } else {
+      assertEqual(server.args[0], "mcp", 'mcpServers["enact-loop"].args[0]');
+      assertEqual(server.args[1], ".", 'mcpServers["enact-loop"].args[1]');
+    }
+  }
+}
+
+const hooks = readJson("hooks/hooks.json");
+if (hooks) {
+  const sessionStart = findCommandHook(hooks.hooks?.SessionStart, "enact-loop hook session-start");
+  if (!sessionStart) {
+    fail('hooks.SessionStart must run "enact-loop hook session-start"');
+  } else {
+    assertEqual(sessionStart.group.matcher, "startup|resume|clear", "hooks.SessionStart.matcher");
+    assertEqual(sessionStart.hook.statusMessage, "Resuming active loop", "hooks.SessionStart.statusMessage");
+  }
+
+  const stop = findCommandHook(hooks.hooks?.Stop, "enact-loop hook stop");
+  if (!stop) {
+    fail('hooks.Stop must run "enact-loop hook stop"');
+  } else {
+    assertEqual(stop.hook.timeout, 30, "hooks.Stop.timeout");
+  }
+}
+
+const skillPath = "skills/enact-loop/SKILL.md";
+if (!existsSync(join(root, skillPath))) {
+  fail(`${skillPath} is missing`);
+} else {
+  const skill = readFileSync(join(root, skillPath), "utf8");
+  if (!/^---\s*\n[\s\S]*?\n---\s*\n/.test(skill)) {
+    fail(`${skillPath} must contain YAML frontmatter`);
+  }
+  if (!/^name:\s*enact-loop\s*$/m.test(skill)) {
+    fail(`${skillPath} frontmatter must declare name: enact-loop`);
+  }
+  if (!/loop_grader_dispatch/.test(skill) || !/loop_grader_verdict/.test(skill)) {
+    fail(`${skillPath} must document independent judgment grading tools`);
+  }
+}
+
+if (failures.length > 0) {
+  for (const failure of failures) {
+    console.error(`[enact-loop validate] ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log("[enact-loop validate] ok");