@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/extensions/enact-factory/skills/drive-loop/references/contract-schema.md

@@ -1,127 +0,0 @@
-# Contract Schema Reference
-
-Full schema for the JSON object passed to `loop_start`. This is a progressive
-disclosure supplement to `SKILL.md`.
-
----
-
-## Contract (root)
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string (uuid) | yes | Stable unique identifier. Use the WorkItem id or a derived uuid. |
-| `name` | string | yes | Human-readable name shown in loop progress output. |
-| `stages` | Stage[] | yes | Ordered list of stages. Mechanical stages run first; judgment stages may interleave. |
-
----
-
-## Stage
-
-| Field | Type | Required when | Description |
-|-------|------|---------------|-------------|
-| `id` | string | always | Stable slug. Referenced by `loop_grade` and `loop_grader_verdict`. |
-| `name` | string | always | Human-readable label. |
-| `type` | `"mechanical" \| "judgment"` | always | Determines which fields are used and how pass is determined. |
-| `required` | boolean | always | `true` → must pass before closure. `false` → informational only. |
-| `requires` | string[] | optional | Stage ids that must pass before this stage may run. |
-| `command` | string | mechanical | Shell command run by the engine via `loop_grade` in loop root cwd. Exit 0 = pass. |
-| `grader` | GraderSpec | judgment | Specification for the independent grader subagent. |
-| `passCriteria` | string | optional | Plain-text description of what constitutes a pass. Included in grader prompts. |
-
----
-
-## GraderSpec
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `role` | `"architect" \| "critic" \| "code-reviewer" \| "verifier"` | yes | Determines the subagent type spawned. |
-| `model` | string | recommended | Model ID for the grader. **Must differ from the executor model.** Cross-vendor preferred. Omit only if the harness selects automatically. |
-| `harness` | `"paseo" \| "subagent"` | optional | How to dispatch. Default: `subagent`. Use `paseo` when the grader needs multi-step tool access. |
-| `dispatchTool` | string | optional | Factory tool the driver uses to run a Paseo grader and capture a structured verdict — `"factory_paseo_grader_run"` (runs `paseo run --provider <graderModel> --mode auto-review --output-schema --json`, returns `{verdict, evidence}` + `graderModelActual`). On the codex provider `--mode auto-review` routes on-request approvals through the auto-reviewer subagent so the grader doesn't BLOCK (read-only stays enforced by prompt). Replaces `paseo logs` scraping. |
-| `rounds` | integer | optional | Number of independent grading rounds before aggregating. Default: `1`. |
-| `timeoutMs` | integer | optional | Grader session timeout in ms (default 30 min). Timeout → `grader-unavailable` blocker. |
-
----
-
-## Validation Rules
-
-1. Every `type: judgment` stage **must** have `grader` with `role` set.
-2. Every `type: mechanical` stage **must** have `command` set.
-3. `grader.model` must differ from the executor's model — enforced at
-   `loop_grader_dispatch` time.
-4. At least one stage must be `required: true`, or the contract is trivially
-   closed and should not be submitted to the loop.
-5. Stage `id` values must be unique within the contract.
-6. `requires` references must point to existing stage ids; cycles are rejected.
-7. **(Hard requirement #9 — tests stage Linux parity)** The `tests` stage
-   `command` **must** invoke a Linux-parity / containerized runner (e.g.
-   `bash scripts/ci-local.sh`) — not a bare host `npm test`. A host suite can
-   pass green while the same deliverable fails the CI Linux agent due to
-   `HOME`/path divergence.
-8. **(Rule #7 — typecheck:tests)** When the project has a separate test-file
-   typecheck script (`typecheck:tests`), it **must** be included — either as its
-   own mechanical stage or folded into the typecheck stage command (e.g.
-   `npm run typecheck && npm run typecheck:tests`). Omitting it allows test-file
-   type regressions to slip past undetected.
-
----
-
-## Closure Definition
-
-A contract reaches **closure** when:
-
-- Every stage where `required: true` has status `PASSED`.
-- `PASSED` means:
-  - `mechanical`: `loop_grade({ stageId })` ran the command and exit code was 0.
-  - `judgment`: `loop_grader_verdict` recorded `verdict: "GO"` with a valid
-    dispatch-minted `continuationId` (`captureSource`: `relayed` or `direct`).
-- Executor/driver authored a current closure summary via `enact-loop summary write`.
-- `loop_complete` called from phase `verifying`.
-
-Worktree fingerprint drift invalidates stale `passed` verdicts. `loop_retarget`
-preserves verdicts only when `id + type + worktreeFingerprint` match.
-
-Optional stages (`required: false`) do not block closure but their results
-are included in the closure record returned to factory.
-
----
-
-## MCP Tool Reference
-
-| Tool | When to call | Key params |
-|------|-------------|------------|
-| `loop_start` | Once, at the start of the delivery | `{ contract: <Contract JSON> }` |
-| `loop_grade` | For each mechanical stage | `{ stageId, timeoutMs? }` — engine runs command; rejects `status`/`evidence` |
-| `loop_grader_dispatch` | Before spawning the grader subagent | `{ stageId }` → `continuationId` |
-| `loop_grader_verdict` | After grader returns verdict envelope | `{ stageId, continuationId, verdict, evidence, graderAgentId, graderSessionId, captureSource? }` |
-
-Factory-side tool (after loop closure):
-
-| Tool | When to call | Key params |
-|------|-------------|------------|
-| `pushLoopClosure` | Once, after loop signals closure | `{ closureRecord }` |
-
----
-
-## Example: Minimal Contract (single mechanical stage)
-
-```json
-{
-  "id": "wi-9999-minimal",
-  "name": "Minimal: lint only",
-  "stages": [
-    {
-      "id": "lint",
-      "name": "Lint passes",
-      "type": "mechanical",
-      "required": true,
-      "command": "cargo clippy --workspace -- -D warnings"
-    }
-  ]
-}
-```
-
-## Example: Full Contract (mixed mechanical + judgment)
-
-See `SKILL.md` worked example (WI-2041 Bug Delivery) for a four-stage
-mixed contract with two mechanical and two judgment stages.

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

@@ -1,75 +0,0 @@
----
-name: handoff
-description: >-
-  Delegate a WorkItem to a detached agent with a self-contained briefing, and
-  record the assignment on the factory board. Use when asked to "hand off",
-  "delegate this work-item", "assign to an agent", "spin up a detached agent for
-  this item", or when the driver wants to fan out an independent item rather than
-  drive it inline. The factory tracks the handoff via factory_assignment_record.
-metadata:
-  author: Amsterdam Data Labs
-  version: 1.0.0
----
-
-# handoff
-
-> **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>/…`.
-
-Package a WorkItem into a briefing complete enough that a fresh detached agent
-can deliver it without the driver's context, launch that agent, and **record the
-assignment on the board**. The board-tracking (`factory_assignment_record`) is
-the factory value-add the generic delegate pattern lacks.
-
-## Boundaries (hard)
-
-- **The briefing must be self-contained.** The detached agent does not share
-  your context — everything it needs goes in the brief. A handoff that assumes
-  the receiver "knows what we discussed" is a defect.
-- **Record every handoff.** Call `factory_assignment_record` so the board
-  reflects the assignment. An untracked detached agent is invisible work — fail
-  loud rather than launch without recording.
-- **Scope unchanged.** Handoff delegates the item as-is; it does not toggle
-  repos, change scope, or split the item. Out-of-scope discoveries → new
-  WorkItem (the receiver follows the same rule).
-- **The receiver still drives the loop** (its own contract + cross-vendor
-  grader). Handoff delegates the work, not the gates. When the receiver
-  dispatches a grader via Paseo on the codex provider, it passes
-  `--mode auto-review` so the grader's on-request approvals don't block (the
-  grader stays read-only by prompt); see `drive-loop`.
-
-## Sequence
-
-1. `factory_workitem_get` → build the self-contained briefing:
-   - goal + acceptance criteria + closure requirements
-   - lifecycle state + next required boolean
-   - blockers / dependencies (must be satisfied before handoff)
-   - branch base (`integration`) + worktree, relevant files/paths
-   - the loop contract to run (or instruction to build one via `drive-loop`)
-   - latest timestamped plan / verification / requirements artifact paths when present
-   - current loop closure summary path (`summary-current.json` / `enact-loop summary show`) when resuming an active loop
-2. `EnterWorktree` to isolate the receiver's workspace.
-3. Launch the receiver as a **detached agent** carrying the briefing (a detached
-   subagent, or via the factory's Paseo dispatch) with `notifyOnFinish`; do not
-   poll it.
-4. **`factory_assignment_record({ workItemId, repoRoot, host, operatorLane,
-   dispatcher, paseoAgentId, paseoWorktree, status: 'active' })`** — register the
-   assignment so the board tracks it. (To update its state later — e.g.
-   `paseoStatus`, `status: 'completed'` — call `factory_assignment_record` again
-   with the returned `assignmentId`.)
-
-## Output
-
-`{ workItemId, assignmentId, branch, worktree, recorded: true }`. If
-`factory_assignment_record` fails, treat the handoff as failed — surface it and
-do not leave an unrecorded detached agent running.
-
-## Related
-
-- [`work-with-workitem`](../work-with-workitem/SKILL.md) — the delivery lane the
-  receiver runs.
-- [`drive-loop`](../drive-loop/SKILL.md) — the contract the receiver drives.
-- [`autonomous-runner`](../autonomous-runner/SKILL.md) — the driver that may hand
-  off independent items instead of driving them inline.

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

@@ -1,59 +0,0 @@
----
-name: hyperplan
-description: "Three-round adversarial planning debate that hands a distilled bundle to $plan instead of writing the final plan directly."
----
-
-# Hyperplan
-
-> **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 `$hyperplan` when a plan needs adversarial pressure before execution starts.
-
-## Debate Team
-
-Use exactly this 4-agent team:
-
-- `critic`
-- `critic`
-- `architect`
-- `explore`
-
-The original openagent placeholder names are not used here.
-
-## Rounds
-
-Run exactly 3 rounds:
-
-1. independent analysis
-2. cross-attack
-3. defend, refine, or concede
-
-Persist each round under:
-
-- `~/.enact/factory/projects/<key>/hyperplan/<sessionId>/<YYMMDDHH>-round-1.md`
-- `~/.enact/factory/projects/<key>/hyperplan/<sessionId>/<YYMMDDHH>-round-2.md`
-- `~/.enact/factory/projects/<key>/hyperplan/<sessionId>/<YYMMDDHH>-round-3.md`
-
-Resolve `<key>` from `~/.enact/workspaces.json`; get the timestamp prefix via `date +%y%m%d%H`. **Append-only:** each debate run writes fresh round files; never overwrite prior `YYMMDDHH-round-*.md` artifacts.
-
-## Handoff Rule
-
-The lead agent does not write the final implementation plan directly.
-After round 3, hand the distilled debate bundle to a separate `$plan` invocation.
-`$plan` must read the latest `hyperplan/<sessionId>/<YYMMDDHH>-round-*.md` files before writing new timestamped plan artifacts.
-
-## Execution Notes
-
-- use `explore` to gather the evidence bundle before critique
-- use the two `critic` agents to take opposing positions in the cross-attack round
-- use `architect` to synthesize the final structured verdict and tradeoffs
-- do not skip a round because the first opinion looked sufficient
-
-## Activation
-
-Invoke with `$hyperplan` or `$enact-loop:hyperplan`. The skill is stateless — it produces a debate bundle and hands off to `$plan`. No durable workflow state is started automatically.

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

@@ -1,120 +0,0 @@
----
-name: looplan
-description: "Plan-first loop execution wrapper: write a durable plan, enter the loop, drive to verified closure. Use when the work needs a reviewable plan before the loop starts."
----
-
-# 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
-execution behind a plan the user or reviewer can inspect, then advances into the `$loop` contract
-runner with explicit stage verification.
-
-Looplan is the combination of `$plan` (write artifacts, define slices and verification) and `$loop`
-(durable contract-runner with closure gates). Neither sub-skill is optional.
-
-## Use When
-
-- the request is clear enough to plan but carries meaningful risk or complexity
-- a written plan artifact needs to exist before any code changes
-- verification stages need to be defined up front, not discovered mid-execution
-- the user wants to review the plan before execution begins
-
-## Do Not Use When
-
-- the request is still ambiguous — route through `$deep-interview` first, then return here
-- the work is trivial and a plan would add no value
-
-## Lifecycle
-
-```
-intent → $plan (write plan + verification map) → user review → $loop start → running → verifying → completed
-```
-
-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 (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/factory/projects/<key>/plans/<YYMMDDHH>-<phase>-verification.md`.
-4. Present the plan for review. Do not advance until it is approved.
-
-### Phase 2 — Execute
-
-5. Start the loop with the goal and stages from the plan:
-   ```
-   loop_start  goal="<goal>"  contract=<stages from plan>
-   ```
-6. Confirm the loop is running: `loop_status`
-7. Execute each plan slice.
-   - 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
-
-9. When all stages have evidence, advance to verifying:
-   ```
-   loop_advance  toPhase=verifying
-   ```
-10. Run `$review` against the completed work and plan artifacts.
-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>"
-    ```
-12. If review returns changes requested, advance back to running and address findings.
-
-## State Contract
-
-Reads:
-- `~/.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/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` — 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/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,103 +0,0 @@
----
-name: plan
-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
-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
-- **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
-
-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 (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?
-3. Split the work into waves and slices:
-   - interface or contracts first
-   - implementation second
-   - verification and wiring last
-4. Write **new** timestamped artifacts (do not edit prior plan files):
-   - 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/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

@@ -1,46 +0,0 @@
----
-name: remove-deadcode
-description: "LSP-verified symbol deletion with entry-point guards and candidate-parallel execution."
----
-
-# 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.
-
-## Preconditions
-
-- collect candidate symbols before any deletion
-- load optional entry-point guard list from `~/.enact/factory/projects/<key>/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

@@ -1,83 +0,0 @@
----
-name: research
-description: "Evidence-first research mode for current patterns, implementation risks, and decision support."
----
-
-# 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.
-
-## 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/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
-
-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({ 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
-
-- 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, 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.