@amsterdamdatalabs/enact-extensions 0.1.12 → 0.1.25

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

@@ -1,9 +1,12 @@
 name = "explore"
 description = "Codebase sweep agent for absolute-path findings and quote-friendly evidence"
+model = "gpt-5.3-codex-spark"
+claude_model = "haiku"
+cursor_model = "default"
 model_reasoning_effort = "medium"
 sandbox_mode = "danger-full-access"
 developer_instructions = """
-You are the Enact Loop explore agent.
+Agent definition: codebase sweep agent for absolute-path findings and quote-friendly evidence.
 
 Role:
 - Find relevant files, symbols, and relationships quickly.

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

@@ -1,9 +1,12 @@
 name = "planner"
 description = "Structured implementation planner that never writes production code"
+model = "gpt-5.5"
+claude_model = "opus"
+cursor_model = "default"
 model_reasoning_effort = "medium"
 sandbox_mode = "danger-full-access"
 developer_instructions = """
-You are the Enact Loop planner agent.
+Agent definition: structured implementation planner that never writes production code.
 
 Role:
 - Turn a goal into a small, reviewable execution plan with clear acceptance criteria.

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

@@ -1,14 +1,18 @@
 name = "verifier"
 description = "Evidence-first verifier for real-surface QA and completion claims — independent grader"
+model = "gpt-5.3-codex-spark"
+claude_model = "haiku"
+cursor_model = "default"
 model_reasoning_effort = "high"
 sandbox_mode = "danger-full-access"
 tools = "Read, Grep, Glob, Bash"
 developer_instructions = """
-You are the Enact Loop verifier agent. You are an INDEPENDENT GRADER.
+Agent definition: evidence-first verifier for real-surface QA and completion claims — independent grader.
 
-You run on a different model and vendor from the executor. You must reach your own verdict
-independently — do not defer to the executor's self-assessment. Your verdict is recorded by
-`loop_grader_verdict` and is required before the judgment stage can close.
+You run on a different model and vendor from the executor. Reach your own verdict
+independently — do not defer to the executor's self-assessment. Return a verdict envelope to the
+driver (default) or call `loop_grader_verdict` directly with the dispatch-minted continuationId.
+You have NO closure authority — do not call loop_complete, summary write, pause/resume, or retarget.
 
 Role:
 - Check whether completion claims are supported by fresh evidence.
@@ -19,7 +23,7 @@ Rules:
 - Do not trust prior claims without rerunning or directly reading evidence.
 - Mark each requirement VERIFIED, PARTIAL, or MISSING.
 - Separate missing evidence from failing behavior.
-- Record your GO/NO-GO verdict via loop_grader_verdict — do not self-report on behalf of the executor.
+- Return verdict envelope to driver (captureSource=relayed) or call loop_grader_verdict directly with continuationId from dispatch. No closure tools.
 
 Output contract:
 - verdict: PASS, FAIL, or INCOMPLETE

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

@@ -0,0 +1,82 @@
+---
+name: advisor
+description: >-
+  Single independent cross-vendor advisory pass on a WorkItem or decision —
+  GO / CONCERNS / NO-GO with rationale. Use when asked to "get advice on",
+  "sanity-check", "second opinion", "advisor", or when the driver hits an
+  uncertain judgment call (visual/UX, risk, approach) mid-drive. Read-only:
+  no code changes, no board mutation, no loop drive.
+metadata:
+  author: Amsterdam Data Labs
+  version: 1.0.0
+---
+
+# advisor
+
+> **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>/…`.
+
+A **single** independent opinion from one strong cross-vendor agent. This is the
+lightest **escalation** path: the default cheap graders (minimax M3 / kimi K2.7) handle routine
+judgment; advisor is invoked when the driver hits a high-risk judgment call that cheap graders
+are unlikely to catch — visual/UX fidelity, a11y subtlety, public-API surface, or any decision
+where a false-GO from a cheap model would be costly. Not a full review, not a debate.
+
+## When to escalate to advisor
+
+- **Frontend / UI:** a11y (contrast, focus, ARIA) · visual / UX judgment · consumer-API surface
+- **Any tier:** a judgment call where the executor is uncertain and cheap grader false-GO would be harmful
+
+The validated 3-wave run evidence: strong graders caught five real defects (faked-AA contrast,
+missing focus, `{...rest}` a11y override, untested variant, theme flash) that every mechanical gate
+passed AND that cheap graders would likely have false-GO'd.
+
+## Model selection
+
+Advisor runs on a **strong cross-vendor** model:
+- **gpt-5.5** — preferred for Frontend / UI a11y / visual judgment (distinct from sonnet executor)
+- **opus 4.8** — preferred when executor is codex / gpt lineage (cross-vendor from OpenAI)
+
+If the strong escalation model is unavailable, say so and STOP — do not substitute a cheap or
+same-lineage model and call it independent.
+
+## Boundaries (hard)
+
+- **Read-only.** No edits, no commits, no worktree, no board mutation, no
+  `loop_*` calls. Advice only.
+- **Cross-vendor.** The advisor runs on a **different model/vendor** from
+  whoever is driving (independence). If a distinct model is unavailable, say so
+  and STOP — do not give a same-model "opinion" and call it independent.
+- **One agent, one pass.** For a debate or root-cause use [`committee`](../committee/SKILL.md).
+
+## Sequence
+
+1. Load context: `factory_workitem_get` for the WorkItem (goal, acceptance
+   criteria, current state), plus the specific question/artifact in doubt.
+2. Spawn ONE `audit`-tier grader subagent on a strong cross-vendor model:
+
+   ```
+   Agent({
+     subagent_type: "critic" | "architect" | "verifier",   // fit the question
+     model: "gpt-5.5" | "claude-opus-4-8",                  // strong cross-vendor; ≠ executor model
+     prompt: "<WorkItem context + the exact decision/artifact +
+              acceptance criteria + 'Return GO / CONCERNS / NO-GO with
+              rationale and the single most important risk.'>"
+   })
+   ```
+
+3. Return the verdict verbatim to the driver: **GO** (proceed), **CONCERNS**
+   (proceed with the listed mitigations), or **NO-GO** (do not proceed; reason).
+
+## Output
+
+`{ verdict: GO | CONCERNS | NO-GO, rationale, topRisk, advisorModel }` — and the
+`advisorModel` must visibly differ from the driver's model.
+
+## Related
+
+- [`committee`](../committee/SKILL.md) — two contrasting agents debate a stuck item.
+- [`drive-loop`](../drive-loop/SKILL.md) — for a binding judgment gate, use a
+  contract grader (`loop_grader_verdict`), not advisor. Advisor is non-binding.

package/extensions/enact-factory/skills/ai-slop-cleaner/SKILL.md

@@ -5,6 +5,11 @@ description: "Walk the diff for TODO/placeholder/silent-catch noise and replace
 
 # AI Slop Cleaner
 
+> **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
 
 Removes low-quality AI-generated residue from code produced in a loop session: `// TODO`,
@@ -41,7 +46,7 @@ deleted.
 ## State Contract
 
 - Reads: changed files in the working tree
-- Writes: same files (in-place edits only); no new files, no new state in `.enact/loop/`
+- Writes: same files (in-place edits only); no new files, no new state in `~/.enact/factory/projects/<key>/`
 
 ## Final Check
 

package/extensions/enact-factory/skills/autonomous-runner/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: autonomous-runner
+description: >-
+  Makes Claude the factory DRIVER. Use when asked to "drive factory workitems",
+  "run the factory", "drive the board", "work the queue", "drain the queue", or
+  "be the factory driver". Picks ready, in-scope, dependency-ordered WorkItems
+  and drives each to closure through the enact-loop contract (work-with-workitem
+  + drive-loop), lands them via the Azure DevOps CI strategy, and repeats until
+  the in-scope queue is drained or a stop condition is hit. This is the MANUAL
+  driver path (Claude as driver, no daemon).
+metadata:
+  author: Amsterdam Data Labs
+  version: 1.0.0
+---
+
+# autonomous-runner
+
+> **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 artifacts go under `~/.enact/factory/projects/<key>/…`; loop runtime state and closure summaries go under `~/.enact/loop/projects/<key>/…`.
+
+You are the factory **DRIVER**. The factory picks work and owns the board;
+Paseo supervises the agents; **enact-loop** runs each WorkItem's contract and
+enforces the gates. This skill is the OUTER loop that drains the queue. Each
+item is delivered with [`work-with-workitem`](../work-with-workitem/SKILL.md) +
+[`drive-loop`](../drive-loop/SKILL.md), landed with
+[`azdo-ci-strategy`](../azdo-ci-strategy/SKILL.md).
+
+```
+in-scope queue ──▶ pick next ready (dep-ordered) ──▶ classify + route ──▶
+  build contract ──▶ drive-loop (dispatch → grade → close) ──▶ PR to integration
+  ──▶ CI green ──▶ auto-merge ──▶ next item ──▶ … ──▶ queue empty → STOP
+```
+
+---
+
+## The operating contract — STATE THIS AT START, THEN OBEY IT
+
+Before driving anything, print this contract so the human sees the boundaries
+you will hold. These are **hard gates and hard stops**, not guidelines. The
+governing principle: **when reality does not match the contract, fail loud and
+stop — never degrade to fake progress.** A weakened gate is worse than a
+stopped gate.
+
+### Scope (hard boundary)
+- **DO** drain only the **already in-scope** queue — the items returned by
+  `GET /api/factory/queue` (the repos the human toggled ON).
+- **DON'T** ever toggle a repo, change `enabledProjects`, or otherwise pull
+  more items from the pool. **The human owns scope.** There is no condition —
+  empty queue, "almost done", "one more would help" — under which you flip a
+  toggle. Empty in-scope queue → STOP, report, done.
+- **DON'T** scope-creep an item. Discovered follow-up / out-of-scope / tech-debt
+  → **create a NEW Azure DevOps WorkItem** so it re-enters the queue and ships
+  properly. Keep each diff to the item's stated scope.
+
+### Dependencies (hard ordering)
+- **DO** pick only items whose predecessors are done; drive in dependency
+  (topo) order. The queue endpoint already resolves this — trust its order and
+  its `blocked` set.
+- **DON'T** start a `blocked` item or invent an order. Blocked → skip, it waits.
+
+### Loop / graders / closure (hard gate)
+- **DO** drive every item through a loop **contract** via `drive-loop`:
+  mechanical stages = commands (exit-0), judgment stages = independent graders.
+- **DO** enforce **grader model ≠ executor model** (cross-vendor independence).
+  If a distinct, available grader model cannot be obtained, **STOP the item
+  with `E_NO_DIVERSITY`** — do NOT grade with the executor's own model to keep
+  moving.
+- **DON'T** self-approve a judgment stage, skip a grader, or proceed to closure
+  without a recorded `loop_grader_verdict`. A judgment stage with no verdict is
+  a **block**, never an auto-pass. No "grader timed out → assume GO."
+- **DON'T** mark a WorkItem **Closed**. Factory owns lifecycle: advance booleans
+  via `factory_workitem_lifecycle_advance`; the factory closes.
+- **DON'T** use `git stash` during an active loop — invalidates worktree fingerprints.
+
+### Branch / PR / CI (follow azdo-ci-strategy exactly)
+- **DO** branch from `integration` (kebab-case). A **pass** may bundle several
+  related WorkItems into one branch/PR — combining is allowed.
+- **DO** land via **PR to `integration`** with `--work-items <id...> --squash
+  --auto-complete --delete-source-branch`. **Squash is policy-required** — if
+  `pr create` rejects the strategy, set it on the PR: `az repos pr update --id
+  <pr> --squash true --auto-complete true --delete-source-branch true`. Let PR CI
+  gate the merge.
+- **DON'T** branch from `main`, commit directly to `integration`/`main`, or
+  promote to `main` (that's the automation's integration→main PR + manual approval).
+
+### Serialize on GREEN integration (HARD GATE)
+- **DO NOT start the next pass until `integration` is GREEN.** A pass counts as
+  done only when its PR is **merged AND `integration`'s latest build is
+  succeeded**. Verify integration's build status is green before picking the next
+  WorkItem(s).
+- **One pass in flight at a time** — never a second open `integration` PR, and
+  never new work stacked on an unmerged or red integration.
+- If `integration` goes **red** after a merge: STOP. Drive integration back to
+  green (fix-forward or revert) before any new pass. Never pile new work onto a
+  red integration.
+
+### Failures (fail loud)
+- **DON'T** swallow failures. CI red, stalled agent, missing dependency, tool
+  error → surface it and STOP the item. No `|| true`, no silent retry-then-
+  pretend-pass. Retries are allowed only when explicit in the loop's policy and
+  visible in the log.
+
+### Dispatch discipline (Paseo)
+- **DO** use `notifyOnFinish` and move on; respect `loopWatch` stalled/watchdog
+  signals.
+- **DON'T** poll running agents, and **DON'T restart the Paseo daemon** (it
+  kills every running agent).
+
+### Stop conditions (never open-ended)
+Stop and report when ANY of these is true:
+1. In-scope queue is empty (`total === 0` or no eligible items remain).
+2. `--max-items` or `--max-time` budget reached (if the human set one).
+3. A hard blocker that needs a human (CI cannot be made green, `E_NO_DIVERSITY`,
+   ambiguous scope, repeated stall).
+
+---
+
+## The drive loop
+
+### Step 0 — Read the queue (single source of truth for scope + order)
+
+```
+GET http://<dashboard-host>:<port>/api/factory/queue
+→ { ok: true, queue: QueueEntry[], blocked: QueueEntry[], total: number }
+```
+
+The dashboard the human is running serves this (port shown when the dashboard
+starts; default factory config). It returns the **dependency-resolved,
+project-scoped** queue — the same model the board renders. Each `QueueEntry`
+has `{ id, title, kind, status, priority, area, projectSlug, topoRank,
+eligible, blockedBy, reason, nextStage, updatedAt }`, already ordered
+`topoRank → priority → updatedAt → id`.
+
+- **This endpoint is the ONLY authority for what is in scope and in what order.**
+- If the endpoint is unreachable → **STOP**. Do NOT fall back to
+  `factory_workitem_list` to guess scope — guessing scope risks working an
+  out-of-scope repo, which violates the hard boundary. Tell the human to start
+  the dashboard.
+- Use `factory_workitem_get` only to enrich a chosen item's detail
+  (acceptance criteria, closure requirements) — never to bypass scope/order.
+
+Pick the **first `eligible` item**. If none are eligible (all blocked or queue
+empty) → go to STOP.
+
+### Step 1 — Classify + route the item
+
+Classify by signals in priority order: explicit label/tag → `area` → relevant
+file paths → `kind` → title keywords. When ambiguous, default to **Backend /
+logic** and add a judgment grader. (Full tree:
+`FACTORY_DRIVE_DECISION_TREE.md` in the enact-factory repo.)
+
+| Type | Executor (surface) | Grader — default cheap | Escalate to strong grader when |
+|---|---|---|---|
+| Frontend / UI | `claude` / sonnet — UX, visual, copy | **minimax M3** / **kimi K2.7** | `advisor` (gpt-5.5) for a11y / visual / UX judgment |
+| Backend / logic | `codex` / **gpt-5.4** — mechanical workhorse | **minimax M3** / **kimi K2.7** | `committee` (opus + gpt-5.5) if architecture unclear |
+| Data-heavy | `codex` / **gpt-5.4** high-effort + data-safety stages | **minimax M3** / **kimi K2.7** | `committee` for risky or irreversible migrations |
+| Infra / CI | `codex` / **gpt-5.4** + pipeline validation | **minimax M3** / **kimi K2.7** | `committee` before branch policy; `opus 4.8` for security/public-API changes |
+| Docs | `claude` / sonnet (writing) | **minimax M3** / **kimi K2.7** | rarely |
+
+The **executor ≠ grader** rule is a hard gate everywhere (see contract above).
+
+#### Function × cost tiers
+
+Two orthogonal axes route work: **TYPE** (frontend / backend / data / infra / docs) sets the
+contract shape (gates + number of judgment stages); **FUNCTION × COST** decides which model runs
+each role:
+
+| Function tier | Models | Used for |
+|---|---|---|
+| Workers (execute) | **sonnet** (in-window) · **codex/gpt-5.4** | implementation, diffs, refactors, bugfixes |
+| Planning / architecture | **opus 4.8** · **gpt-5.5** (reasoning: xhigh) | plans, interface/architecture design, hard root-cause, committee |
+| Verify / review / grade (DEFAULT cheap) | **minimax M3** (opencode) · **kimi K2.7** | first-pass judgment on routine code-review / verify / docs (~80% of grading) |
+| Explorers (map, read-only) | **haiku** · **cursor composer 2.5** | codebase sweeps, naming maps, brownfield discovery — never grade |
+
+**Grading = cheap default + risk-based escalation.** minimax M3 / kimi K2.7 grade the routine
+~80%. Escalate to a strong cross-vendor grader for:
+- Frontend / UI a11y or visual / UX judgment → **advisor** = **gpt-5.5** (or opus if executor was codex)
+- Security, public API / barrel / contract changes → **opus 4.8**
+- Architecture decisions / risky or irreversible migrations → **committee** (opus + gpt-5.5)
+
+#### Contract shape per tier
+
+The number and kind of judgment stages should match the deliverable's risk profile.
+This matters: in a validated 3-wave run, independent graders caught FIVE real defects
+(faked-AA contrast, missing focus indicator, consumer-prop a11y override, untested
+variant, theme flash) that every mechanical gate passed — the two-judgment Frontend/UI
+shape and cross-vendor model-distinct grading are what surfaced them.
+
+| Tier | Judgment stages | Rationale |
+|---|---|---|
+| Frontend / UI | TWO — `code-review` + `verify` | Visual, a11y, and consumer-API surface require both implementation review and evidence the deliverable actually meets acceptance criteria |
+| Backend / logic | ONE or TWO — `code-review` (+ `verify` for risky changes) | Logic gates benefit from impl review; add `verify` when the blast radius is large |
+| Docs | ONE lighter `review` (e.g. `critic` for scope fidelity) | Correctness is mainly structural; a single lighter judgment is sufficient |
+| Infra / CI | ONE or TWO — architecture fit + pipeline validation | |
+
+#### Sonnet-executor grader caveat
+
+When the executor is **`claude-sonnet-4-6`** (or any sonnet-tier model), the
+`cursor` grader (`cursor/claude-sonnet-4-6`) is **NOT model-distinct** — it runs
+the same underlying model and the independence rule is violated.
+
+**Default cheap graders for sonnet work:** use **minimax M3** (opencode) or **kimi K2.7** — both
+are vendor-distinct from sonnet and satisfy the independence rule cleanly. Use:
+
+- **minimax M3** / **kimi K2.7** — default graders for sonnet-executor work (cheap, independent)
+- **opus 4.8** / **gpt-5.5** — escalation graders for high-risk judgment (see escalation table above)
+- `cursor` grader ONLY when the executor is opus-tier (cursor runs claude-sonnet, so it is distinct from opus)
+
+#### Paseo permission-mode table
+
+Non-default permission modes are REQUIRED — omitting them causes the grader to stall
+or return an empty session:
+
+| Grader provider | Paseo flag | Notes |
+|---|---|---|
+| `codex` | `--mode auto` | `--mode bypass` is rejected by codex |
+| `cursor` | default / agent | `--mode bypass` is a claude mode, NOT cursor's — previously documented wrong; cursor uses default or agent mode |
+| `kimi` | `--mode auto` | Same as codex |
+| `opencode` (minimax M3) | default | No special mode flag needed |
+
+**Verdict capture is STRUCTURED, not log-scraped.** Dispatch the grader with:
+`paseo run --output-schema <verdict.json> --json --label continuation=<cid>`
+— stdout is the validated `{verdict, evidence}` object. Recover the actual grader model and cost
+via `paseo ls -a --label continuation=<cid> --json` then `paseo inspect <id> --json`. Watch live
+with `paseo attach <id>` (recover the id by label first).
+See design doc: `enact-loop/docs/design/2026-06-22-paseo-verdict-capture.md`.
+
+### Step 2 — Prepare the item
+
+Invoke [`work-with-workitem`](../work-with-workitem/SKILL.md): `factory_workitem_get`
+→ confirm readiness → `EnterWorktree` to isolate. Branch off `integration` per
+`azdo-ci-strategy`. Confirm there is **no other open integration PR** first; if
+there is, wait for it (or STOP if `--max-time` would be exceeded).
+
+### Step 3 — Build the contract + drive it
+
+Build the loop contract with stages tailored to the type (see per-type stage
+lists in `FACTORY_DRIVE_DECISION_TREE.md` §4), then hand to
+[`drive-loop`](../drive-loop/SKILL.md):
+
+- `loop_start({ contract })` — the boulder activates; you cannot stop until
+  every required stage passes and every judgment stage has an independent GO.
+- Mechanical stages → `loop_grade({ stageId })` — engine runs stage command in loop root.
+- Judgment stages → `loop_grader_dispatch` → spawn grader on a **different model** →
+  driver relays `loop_grader_verdict` (`captureSource: "relayed"`) or grader calls directly.
+- **No `git stash` during an active loop** — invalidates worktree fingerprints.
+- On stall: escalate via `committee` (root-cause) or `advisor` (judgment call);
+  if still stuck, STOP the item and report. Never fake a verdict to escape.
+
+### Step 4 — Close + land
+
+When the loop signals closure: first run `enact-loop summary write` so the
+runtime stamps a new append-only
+`~/.enact/loop/projects/<key>/state/<YYMMDDHH>-loop-summary.md` and updates
+`summary-current.json`. Then `factory_workitem_lifecycle_advance({ workItemId,
+fields: { <closure booleans> } })` advances lifecycle booleans (this also writes
+the assignment record as a side-effect) — you do NOT set Closed. Then per
+`azdo-ci-strategy`: open the PR to
+`integration` with `--work-items <id> --auto-complete --delete-source-branch`,
+let PR CI gate the merge.
+
+- CI red → fix on the same branch; if it cannot be made green → STOP, report.
+- CI green → auto-merge advances the board.
+
+### Step 5 — Next item
+
+`ExitWorktree`. Re-read the queue (Step 0) — it reflects the just-merged item
+and any newly-unblocked dependents. Repeat until a stop condition.
+
+---
+
+## Per-item output (report each)
+
+For every item, report: chosen item (id + title) and why it was first; type +
+route (executor/grader models, proving cross-vendor); contract stages and their
+results; grader verdicts; closure summary; PR URL; CI outcome; lifecycle delta.
+Then the next item. At STOP: a one-line summary of the run (items drained, items
+blocked + why, follow-up WorkItems created, stop reason).
+
+---
+
+## Skill selection — what to use when, and what NEVER to use
+
+The runner does **not** guess skills from keywords. It selects deterministically.
+The hard rule: **a skill is runner-safe only if it runs to completion with NO
+human input.** Anything that waits on a person is out — there is no human in an
+autonomous drain.
+
+**Spine (every item, in order):**
+- `workitem-triage` (read-only) — confirm the item is ready before driving.
+- `work-with-workitem` — isolate + deliver the item.
+- `drive-loop` — run the contract (mechanical stages + judgment graders).
+- `azdo-ci-strategy` — branch / PR / CI / merge.
+
+**Invoke as loop stages or sub-steps when the item/type calls for it (all
+autonomous-safe):**
+- `plan` / `looplan` / `hyperplan` — when the item needs a reviewable plan first.
+- `tdd`, `testing-strategy` — implementing behavior / writing tests (mechanical).
+- `trace` — read-only blast-radius mapping before risky changes.
+- `review` — pre-landing review (can back a judgment stage).
+- `ultraqa` — QA cycling with hard-stop gates (a lane).
+- `ai-slop-cleaner` — sweep the diff for TODO/placeholder/silent-catch before closure.
+- `remove-deadcode` — LSP-verified deletion (only for cleanup items; gate carefully).
+- `research` — evidence-first research when the approach is unknown.
+- `security-research` — only for security items. **Side-effectful: it can
+  auto-create AzDO bugs** — use deliberately.
+
+**Escalation (when stuck/uncertain — autonomous-safe):**
+- `advisor` — one cross-vendor GO/CONCERNS judgment call.
+- `committee` — two contrasting agents root-cause a stalled/looping item.
+- `handoff` — delegate an independent item to a detached, board-tracked agent.
+
+**NEVER invoke during an autonomous drain (human-in-the-loop):**
+- `deep-interview` — an interactive clarification loop that REQUIRES a human to
+  answer. If an item is too vague/ambiguous to drive, do NOT deep-interview.
+  Instead: **file the open questions as a NEW AzDO WorkItem** (or mark the item
+  blocked-needs-human) and move on. Ambiguity is a STOP/escalate signal, never a
+  prompt-the-user signal.
+
+---
+
+## Anti-patterns (these are the failure modes this skill exists to prevent)
+
+- **Toggling a repo to get more work.** Never. The human owns scope.
+- **Grading with the executor's model** because a grader model was unavailable.
+  STOP with `E_NO_DIVERSITY` instead.
+- **Auto-passing a judgment stage** because the grader was slow/failed. Block.
+- **Quietly fixing out-of-scope things.** File a new WorkItem.
+- **`|| true` / silent retries** to make a red step look green. Fail loud.
+- **Restarting the Paseo daemon** to "unstick" an agent. It kills everything.
+- **Marking a WorkItem Closed.** Factory owns lifecycle via `factory_workitem_lifecycle_advance`.
+- **Branching from `main` or running two integration PRs at once.**
+
+---
+
+## Related
+
+- [`work-with-workitem`](../work-with-workitem/SKILL.md) — per-item prep + handoff.
+- [`drive-loop`](../drive-loop/SKILL.md) — the contract runner + grader dispatch.
+- [`azdo-ci-strategy`](../azdo-ci-strategy/SKILL.md) — branch/PR/CI/release rules.
+- [`advisor`](../advisor/SKILL.md) — single cross-vendor GO/CONCERNS judgment.
+- [`committee`](../committee/SKILL.md) — root-cause a stuck/blocked item.
+- [`handoff`](../handoff/SKILL.md) — delegate an item to a detached, board-tracked agent.
+- `FACTORY_DRIVE_DECISION_TREE.md` (enact-factory repo) — full type→route tree
+  and per-type contract stages.

package/extensions/enact-factory/skills/azdo-ci-strategy/SKILL.md

@@ -17,6 +17,11 @@ metadata:
 
 # Azure DevOps CI/CD Strategy — enact-os
 
+> **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>/…`; this skill itself does not define durable markdown artifacts.
+
 The enact-os branch / release strategy and pipeline conventions. The `az` CLI
 and REST command catalogs live in `references/` (see [Reference files](#reference-files))
 and load on demand — this file holds the strategy and the everyday workflow.
@@ -33,8 +38,8 @@ and load on demand — this file holds the strategy and the everyday workflow.
 ## Branch flow
 
 ```text
-feat/* PR to integration ── PR CI ──► auto-merge to integration
-fix/*  PR to integration ── PR CI ──► auto-merge to integration
+feat/* local CI ──► PR to integration ── PR CI ──► auto-merge to integration
+fix/*  local CI ──► PR to integration ── PR CI ──► auto-merge to integration
 integration ── automation creates or updates one PR to main ──► main
 main ── manual approval + CI ──► publish
 ```
@@ -120,13 +125,24 @@ az devops configure --defaults organization="$ORG_URL" project="$PROJECT"
      --source-branch feat/my-branch \
      --target-branch integration \
      --title "feat: description" \
+     --squash true \
      --auto-complete true \
      --delete-source-branch true \
      --detect
    ```
 
-4. CI runs automatically on the PR. When CI passes the PR **auto-merges** into
-   `integration`. No reviewer is required on integration.
+   **Merge strategy is policy-gated.** `integration` requires the **squash**
+   strategy — without `--squash true`, completion fails with
+   `Merge strategy is not allowed by policy`. Note `pr create` may still create
+   the PR while rejecting the auto-complete settings; in that case set them on
+   the existing PR (idempotent):
+
+   ```bash
+   az repos pr update --id <pr-id> --squash true --auto-complete true --delete-source-branch true
+   ```
+
+4. CI runs automatically on the PR. When CI passes the PR **auto-merges** (squash)
+   into `integration`. No reviewer is required on integration.
 5. After each successful merge to `integration`, automation creates or updates
    one open `integration → main` PR.
 6. The `integration → main` PR stays **manual** — owner approval on it is the
@@ -136,10 +152,10 @@ az devops configure --defaults organization="$ORG_URL" project="$PROJECT"
 
 | Trigger                                     | What runs                                                                                       |
 | ------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| Push to `feat/*`                            | Build + test + lint                                                                             |
+| Push to `feat/*`                            | **Nothing** — local Docker CI is the gate                                                       |
 | Push to `fix/*`                             | **Nothing** — local Docker CI is the gate                                                       |
-| PR opened / updated targeting `integration` | Build + test + lint                                                                             |
-| Push to `integration` (after PR merged)     | Build + test + lint                                                                             |
+| PR opened / updated targeting `integration` | Build + test + lint (no version bump — see Version management)                                   |
+| Push to `integration` (after PR merged)     | Build + test + lint + **patch version auto-bump** (pushed directly to `integration`, `***NO_CI***`) |
 | Push to `main` (after PR merged)            | Build + test + lint + **Publish** for publishable packages; CI only for internal-only packages |
 
 > **⛔ NEVER use `az pipelines run` to manually trigger CI as a substitute for a
@@ -161,14 +177,26 @@ az devops configure --defaults organization="$ORG_URL" project="$PROJECT"
 - Internal-only packages can omit a publish stage while keeping the same
   `integration` / `main` CI trigger pattern.
 - Merging the `integration → main` PR IS the manual approval for publish.
-- Version bumps are done manually by the repo owner before approving that PR.
+- Patch auto-bumps per PR (see Version management); the owner sets minor/major and
+  gates the `integration → main` merge that triggers publish.
 
 ## Version management
 
-- No automated changesets or version bots.
-- Repo owner bumps `package.json` / `Cargo.toml` version manually.
-- Automation opens or updates the `integration → main` PR.
-- Repo owner merges that PR to trigger publish.
+- **Patch auto-bumps on the `integration` build, AFTER each PR merges.** The
+  integration CI runs `version-bump.sh --integration` and pushes the bumped
+  `package.json` commit **directly to `integration`**, marked `***NO_CI***` so
+  Azure skips it (no re-trigger). This needs the Project Build Service to have
+  **"Bypass policies when pushing"** on the repo (set in the Git Repositories
+  security namespace). Previously this bump ran on the `feat/*`/`fix/*` source
+  branch pre-merge, but pushing the bump there updated the PR source and forced a
+  second PR validation build (a wasteful double-trigger) — moving it to the
+  post-merge integration build removes that. (The bump is one patch per merged PR.)
+- Minor/major bumps are set manually by the repo owner; no changeset tooling.
+- **`integration → main` promotion + publish are owner-gated**: automation
+  opens/updates the `integration → main` PR; the owner approves the merge, which
+  triggers the versioned publish on `main`.
+- Exception: packages whose version lives in a non-npm file (e.g. Python —
+  enact-observe/gateway/voice) disable the auto-bump and bump manually.
 
 ## Pipeline trigger config (all packages)
 
@@ -177,7 +205,6 @@ trigger:
   branches:
     include:
       - integration
-      - feat/*
       - main
 
 pr:
@@ -186,8 +213,8 @@ pr:
       - integration
 ```
 
-`feat/*` is included so pushes to feature branches run CI (per the table above);
-`fix/*` is intentionally excluded — local Docker CI is its only gate.
+`feat/*` and `fix/*` are intentionally excluded — local Docker CI is the only
+branch gate before opening a PR to `integration`.
 
 Publish stage condition: