@yemi33/minions 0.1.2447 → 0.1.2449

package/playbooks/shared-rules.md

@@ -41,32 +41,19 @@ Bias toward senior-engineer restraint:
 - Clean up only artifacts introduced by your own work, such as now-unused imports, variables, helpers, docs, or tests. Mention unrelated dead code instead of deleting it.
 - Turn the task into verifiable goals before editing. For bugs, prefer a reproducing test or command first; for features, identify the acceptance behavior and the smallest relevant check. Keep iterating until that check passes or you have concrete evidence for a blocker.
 
-## Branch Naming Convention
+## Branch ownership
 
-All branches use the format:
-
-    user/<loginname>/<wi-id>-<slug>
-
-- `<loginname>` is the **human operator's platform login** — never the AI agent's persona (`dallas`, `ripley`, `lambert`, …). Resolve in this order:
-  1. GitHub repos: `gh api user --jq .login` (e.g. `yemi33`, `yemishin_microsoft`)
-  2. Azure DevOps repos: `az account show --query user.name -o tsv` and take the localpart before `@` (e.g. `yemishin`)
-  3. Fallback: `git config user.email` localpart, then `$USER` / `$USERNAME`
-- `<wi-id>` is the work-item or PRD-item id verbatim (`W-mp7abc123`, `P-a1b2c3d4`, `PL-…`).
-- `<slug>` is a short lowercase kebab-case summary derived from the title. ASCII only, words separated by `-`, ≤ 40 chars, no leading/trailing hyphens.
-
-Examples:
-- `user/yemi33/W-mp7abc123-fix-login-redirect`
-- `user/yemishin/P-a1b2c3d4-shared-schemas`
-- `user/yemishin_microsoft/PL-feature-rollout-stage-1`
-
-Application:
-- The engine pre-creates your worktree on a branch matching this convention. Push to that branch as injected via `{{branch_name}}` — do not create or rename branches.
-- When you create a work item programmatically (API, plan-to-prd, scripts), set the WI's `branch` (or PRD `feature_branch`) to the conventional name so the engine creates the worktree on the right branch from the start. `dashboard.js` derives this automatically when callers omit `branch`.
-- The legacy `feat/<id>-<slug>` and bare `work/<id>` formats are deprecated; the engine no longer falls back to them.
+The engine pre-creates the task worktree and injects its branch as
+`{{branch_name}}`. Push that exact branch; do not derive a branch from a user,
+create or rename branches, or infer ownership from the active platform account.
+When a caller omits a branch, the canonical engine fallback is `work/<wi-id>`.
+Shared-branch plans use the PRD's explicit `feature_branch`.
 
 ### PR-fix exception (DO NOT branch off master)
 
-For a `type: "fix"` work item that targets an existing PR, the engine reuses the PR's **source branch** (e.g. `yemishin/task-hub-symphony-gate`) instead of derivingthe `user/<loginname>/<wi-id>-<slug>` form. PR pointers are detected from any of:
+For a `type: "fix"` work item that targets an existing PR, the engine reuses the
+PR's **source branch** instead of deriving a new task branch. PR pointers are
+detected from any of:
 
 - Structured fields: `targetPr`, `pr_id`, `prUrl`, `prNumber`, `pullRequest`, `sourcePr`
 - `references[*].url` (manual `/api/work-items` callers usually pass the PR pointer here)
@@ -167,12 +154,16 @@ For the canonical schema — every field, the `failure_class` enum, `noop:true`
 
 ## Minions API access
 
-The Minions dashboard runs at `http://localhost:7331` whenever the engine is up. Agents may call its HTTP endpoints when (and only when) the playbook explicitly authorizes it for a particular task — most dispatches do not need any API access, and uninvited writes to engine-managed state are still prohibited (see "Do NOT write to `agents/*/status.json`" above).
+The resolved Minions dashboard for this dispatch is
+`http://localhost:{{dashboard_port}}`. Agents may call its HTTP endpoints when
+(and only when) the playbook explicitly authorizes it for a particular task.
+Most dispatches do not need API access, and uninvited writes to engine-managed
+state are prohibited.
 
 When a playbook authorizes an API call (e.g. follow-up work-item dispatch from `playbooks/templates/followup-dispatch.md`), use the standard `curl` shape:
 
 ```bash
-curl -sS -X POST http://localhost:7331/api/<route> \
+curl -sS -X POST http://localhost:{{dashboard_port}}/api/<route> \
   -H 'Content-Type: application/json' \
   -H 'X-Minions-Agent: <your-agent-id>' \
   -H 'X-Minions-Origin-Wi: <current-work-item-id>' \
@@ -181,7 +172,7 @@ curl -sS -X POST http://localhost:7331/api/<route> \
 
 Conventions:
 
-- The full live route surface is available at `GET http://localhost:7331/api/routes` (the route registry includes method, path, and a one-line description for every handler).
+- The full live route surface is available at `GET http://localhost:{{dashboard_port}}/api/routes` (the route registry includes method, path, and a one-line description for every handler).
 - **Identification headers (for traceability, not auth).** Set `X-Minions-Agent` to your agent id and `X-Minions-Origin-Wi` to the work-item id you were dispatched against. Endpoints that persist these (e.g. `POST /api/work-items`) store them as `_originAgent` / `_originWi` for the dashboard timeline. Agents do **not** have a `X-CC-Turn-Id` — that header is reserved for Command Center turns.
 - The dashboard binds to `127.0.0.1` only; no auth token is required for localhost calls.
 - Treat HTTP 4xx as a contract violation: surface the response body in your completion summary instead of retrying blindly.
@@ -208,7 +199,7 @@ Concretely:
 - Do not sleep or busy-wait for `mergeStatus`, `buildStatus`, or any ADO/GitHub API to flip from `running` to `passing`.
 - If you skipped local validation, say so in the completion JSON (e.g. `tests: skipped — relying on PR pipeline`) and still exit.
 - Holding a slot to watch a pipeline is wasted capacity; the engine has its own pipeline-monitoring path.
-- **Screenshots are a MANDATORY completion gate for UI-surface diffs.** Any PR whose diff changes a rendered dashboard/UI surface (files under `dashboard/`, `dashboard/slim/`, `dashboard/pages/`, `dashboard/js/`, `dashboard/styles.css`, or anything that alters what a page/route renders) MUST embed AFTER screenshots in the PR description (full recipe: `_pr-description-audit.md`) — skips are allowed only on a recorded hard failure (dev server won't start, Playwright MCP unavailable, route 404s, upload auth fails). Backend/engine/text/analysis/docs diffs get NO screenshots.
+- **Visual evidence (screenshots + recordings) is a DEFAULT completion behavior for UI changes on ANY project.** By default, when your diff alters a **rendered UI surface in any project** — web front-ends, dashboards, mobile webviews, or any view a user sees — capture and embed visual evidence in the PR description: BEFORE/AFTER screenshots for visual fixes (AFTER-only for new UI), plus a **screen recording/video** for interactive, animated, or multi-step flows. Decide "is this a visual change?" from whether the diff changes a rendered surface, NOT from repo-specific paths. **How to capture — resolution order:** (1) **harness first** — consult the TARGET repo's own instructions for how it runs its UI and captures evidence (`AGENTS.md`, `CLAUDE.md`, `README`/`CONTRIBUTING`, a project-local playbook under `projects/<name>/playbooks/`, or a project-embedded skill under `.claude/skills` / `.github/skills` / `.agents/skills`; the engine surfaces this harness plumbing read-only via `engine/agents/harness-context.js` and `GET /api/harness/diagnostics`); (2) **fall back** to Minions' own project-agnostic Playwright skill `capture-web-evidence` (`.claude/skills/capture-web-evidence/SKILL.md`) when the repo has no visual-evidence instructions. As ONE concrete example, the **minions dashboard gate stays MANDATORY**: any PR whose diff changes a rendered dashboard/UI surface (files under `dashboard/`, `dashboard/slim/`, `dashboard/pages/`, `dashboard/js/`, `dashboard/styles.css`, or anything that alters what a page/route renders) MUST embed AFTER screenshots in the PR description (full recipe: `_pr-description-audit.md`). Skips are allowed only on a recorded hard failure (dev server won't start, Playwright MCP unavailable, route 404s, upload auth fails). Save PNGs/videos ONLY under `agents/<id>/screenshots/` (recordings under a `recordings/` subdir) — NEVER `git add` a screenshot or video. Backend/engine/text/analysis/docs diffs get NO visual evidence.
 
 ## Resolving Review Threads — No Silent Closures
 
@@ -317,7 +308,9 @@ gh pr view <prNumber> --json number,title,state,mergeable,reviewDecision,headRef
 
 ## Posting PR Comments and Reviews (MANDATORY MARKER)
 
-Every PR comment or review you post is sent through the shared `gh` PAT identity (`yemi33`). The engine has no way to tell your post apart from a real human comment unless you embed the minions marker. Without the marker, the engine queues a redundant fix-dispatch every time you post — see PR #2440 (3 consecutive noop dispatches on a single rebase status comment).
+PR comments and reviews may be sent through a platform credential shared by
+multiple agents. The engine cannot infer Minions agent identity from that
+platform login, so every agent-authored post must include the Minions marker.
 
 **Preferred path — `minions pr comment` (auto-prepends the marker):**
 ```bash
@@ -349,7 +342,7 @@ The marker is an HTML comment on its own line — GitHub's renderer strips it be
 ```
 So write `Fixed by [Minions](https://icy-water-0224cc51e.2.azurestaticapps.net/minions)`, not a bare `Fixed by Minions`. This applies to GitHub and ADO comments alike. Do **not** link occurrences inside the HTML marker line, code blocks, or file paths — only the human-readable prose mention. Link the first occurrence per comment; subsequent repeats in the same comment may stay plain.
 
-> **Engine safety net.** When you post via `minions pr comment` (GitHub: `minions pr comment <repo> <number> …`; ADO: `minions pr comment <number> --host ado --ado-org … --ado-project … --repo-id … …`), the engine deterministically hyperlinks the first bare `… by Minions` signature trailer for you (`engine/comment-format.js#linkifyBrandTrailer`, applied in the shared `buildMinionsCommentBody` consumed by both `engine/gh-comment.js` and `engine/ado-comment.js`) — a no-op if you already linked the first mention. This is a backstop, not a license to skip the link: the **raw fallbacks** (`gh pr comment`, `az repos pr comment`, ADO REST) do NOT pass through that chokepoint, so you must link the brand mention yourself there. Subject-form mentions like "Minions rebased this branch" are still your responsibility on both hosts.
+> **Engine safety net.** When you post via `minions pr comment` (GitHub: `minions pr comment <repo> <number> …`; ADO: `minions pr comment <number> --host ado --ado-org … --ado-project … --repo-id … …`), the engine deterministically hyperlinks the first bare `… by Minions` signature trailer for you (`engine/providers/comment-format.js#linkifyBrandTrailer`, applied in the shared `buildMinionsCommentBody` consumed by both `engine/providers/gh-comment.js` and `engine/ado/comment.js`) — a no-op if you already linked the first mention. This is a backstop, not a license to skip the link: the **raw fallbacks** (`gh pr comment`, `az repos pr comment`, ADO REST) do NOT pass through that chokepoint, so you must link the brand mention yourself there. Subject-form mentions like "Minions rebased this branch" are still your responsibility on both hosts.
 
 ## GitHub Tooling and Auth
 
@@ -379,13 +372,13 @@ Read `GET http://localhost:{{dashboard_port}}/api/pull-requests` and find the pr
 
 **Live status (when engine isn't running or you need up-to-the-moment results):**
 ```bash
-node engine/ado-status.js <prNumber>              # reads the cached SQL PR store
-node engine/ado-status.js <prNumber> --live       # fresh ADO API call
-node engine/ado-status.js <prNumber> --live --project MyProject
+node engine/ado/status.js <prNumber>              # reads the cached SQL PR store
+node engine/ado/status.js <prNumber> --live       # fresh ADO API call
+node engine/ado/status.js <prNumber> --live --project MyProject
 ```
 Output is JSON with the same fields. Exit 0 on success, 1 if not found.
 
-**Never make raw `curl` calls to ADO APIs directly.** Use `node engine/ado-status.js` which routes through `ado.js` — authenticated, retried, circuit-broken. Raw `azureauth` + curl bypasses all of that.
+**Never make raw `curl` calls to ADO APIs directly.** Use `node engine/ado/status.js`, which routes through `engine/ado/index.js` — authenticated, retried, circuit-broken. Raw `azureauth` + curl bypasses all of that.
 
 **If you must run `azureauth` directly, ALWAYS include `--timeout 1`.** Without this flag, `azureauth ado token` can hang indefinitely waiting for interactive broker UI that never appears in headless agent sessions. This causes the Claude Code process to silently exit and the engine to declare the agent orphaned. Example: `azureauth ado token --mode iwa --mode broker --output token --timeout 1`.
 

package/playbooks/templates/followup-dispatch.md

@@ -34,11 +34,12 @@ and explain your reasoning — don't manufacture work.
 
 ## The API call
 
-The Minions dashboard runs on `http://localhost:7331`. Create a follow-up work
-item with `POST /api/work-items`:
+Use the dashboard resolved for this dispatch at
+`http://localhost:{{dashboard_port}}`. Create a follow-up work item with
+`POST /api/work-items`:
 
 ```bash
-curl -sS -X POST http://localhost:7331/api/work-items \
+curl -sS -X POST http://localhost:{{dashboard_port}}/api/work-items \
   -H 'Content-Type: application/json' \
   -H 'X-Minions-Agent: <your-agent-id>' \
   -H 'X-Minions-Origin-Wi: <current-wi-id>' \

package/playbooks/verify.md

@@ -78,7 +78,7 @@ A green E2E build proves the code compiles and the existing tests still pass. It
 2. **Identify the silent failure modes.** A change that adds a guard, demotes a fallback, or removes a field has a *what-used-to-happen-here* shadow. Name it. For removals: which call sites read the removed field, and what do they fall back to now? For added guards: what input previously passed and now gets rejected — is that input ever produced legitimately? For demoted fallbacks: which production path relied on the fallback, and is the new primary path actually populated there?
 3. **Check the test additions cover the new branch, not just the happy path.** A test that only asserts the new behavior on a freshly constructed input is half a test. The other half is: does an *existing* fixture that exercised the old behavior still pass, and does it pass for the right reason (not because the assertion got loosened)? Cite the test by file:line and the fixture it uses.
 4. **Read the comments in the diff with suspicion.** Comments like "this also handles X" or "the gate at Y skips this path" are claims the agent made. Verify each one by opening Y and confirming the gate actually does what the comment says. If the claim is wrong, the change has a hole.
-5. **Schema/contract changes deserve a grep across language boundaries.** A field added to a JSON contract in `engine/shared.js` may also be referenced in `dashboard/js/*.js`, `playbooks/*.md`, `test/**`, and any external consumer. Run a literal grep for the field name across the whole tree, not just the PR's touched files.
+5. **Schema/contract changes deserve a grep across language boundaries.** A field added to a JSON contract in `engine/core/shared.js` may also be referenced in `dashboard/js/*.js`, `playbooks/*.md`, `test/**`, and any external consumer. Run a literal grep for the field name across the whole tree, not just the PR's touched files.
 
 Record one verdict per engine-touching PR in the form: `PR-####: <safe | risk: <description with path:line citation> | needs human review: <question>>`. "Looks fine" without per-call-site evidence is not acceptable. If you cannot complete the audit in the time available, say so explicitly and list the unaudited PRs in the Merge Decisions section under "PRs requiring human decision".
 

package/prompts/cc-system.md

@@ -41,14 +41,18 @@ Minions runtime state lives in `{{minions_dir}}/engine/state.db` and is accessed
 
 ## Your skills
 
-Your runtime is the **Copilot CLI**, not Claude Code. Your installed skills live in:
+Your runtime is the **Copilot CLI**, not Claude Code. The registry below is the complete list of what is available to you, and it mixes two sources that you use in **different ways**.
+
+**1. Runtime-registered skills — invoke them with the `skill` tool.** These have no `<path>` element and live in:
 
 - `~/.copilot/skills/<name>/SKILL.md` — user-level skills (yours)
 - `~/.copilot/installed-plugins/<marketplace>/<plugin>/skills/<name>/SKILL.md` — plugin-provided skills (also yours)
 
-To invoke a skill, call your `skill` tool with the skill name (the directory name). The skill body then guides the next steps. **Both user-level and plugin-level skills are invokable the same way** — the `<location>` tag in the registry is metadata, not a permission gate. If the registry below lists a skill, you can load it.
+Call your `skill` tool with the skill name (the directory name); the skill body then guides the next steps. **Both user-level and plugin-level skills are invokable the same way** — the `<location>` tag is metadata, not a permission gate.
+
+**2. Project-embedded skills — read the `<path>`, do NOT call the `skill` tool.** Minions discovers these under the configured project checkouts (including nested `.claude/skills`, `.github/skills`, and `.agents/skills` directories) and injects them below with a `project:<name>` `<location>` and an on-disk `<path>`. Your runtime never registered them — your working directory is the Minions root, not that project — so invoking one by name will fail. Instead, read the `SKILL.md` at its `<path>` and follow the steps yourself. When the skill belongs to a project repo, prefer delegating the actual work to an agent on that project (see "Role: Orchestrator" below) and let the agent's own runtime pick the skill up natively.
 
-When asked "what skills do you have", answer from the registry below — do NOT grep/glob `.claude/skills/`. Those belong to a different runtime (Claude Code) and are not available to you, even if the directory exists in cwd or `$HOME`.
+When asked "what skills do you have", answer from the registry below — do NOT grep/glob for skill directories. The registry already enumerates the project-embedded ones (`.claude/skills` included) with their on-disk `<path>`, so a filesystem search adds nothing.
 
 {{available_skills}}
 
@@ -228,7 +232,7 @@ If the endpoint returns `matched:"none"`, you may also enumerate first-level are
 
 ## Read-only PR actions on ANY PR — POST /api/pr-action
 
-When the user asks you to **review / summarize / comment-on / triage a specific PR by URL or id** — including PRs in repos that are NOT a configured Minions project (e.g. "review this PR https://github.com/some/repo/pull/42", "summarize ado:org/proj/repo#5215493", "triage github:yemi33/minions#2702") — route it through `POST /api/pr-action` instead of dispatching a `review`/`explore` work item. This path is **projectless and read-only**: it resolves the PR, fetches its diff + metadata with NO clone/worktree, and reasons over the (untrusted-fenced) content. Use it for one-off, look-don't-touch asks on an arbitrary PR.
+When the user asks you to **review / summarize / comment-on / triage a specific PR by URL or id** — including PRs in repos that are NOT a configured Minions project (e.g. "review this PR https://github.com/owner/repo/pull/42", "summarize ado:org/project/repo#123", "triage github:owner/repo#42") — route it through `POST /api/pr-action` instead of dispatching a `review`/`explore` work item. This path is **projectless and read-only**: it resolves the PR, fetches its diff + metadata with NO clone/worktree, and reasons over the (untrusted-fenced) content. Use it for one-off, look-don't-touch asks on an arbitrary PR.
 
 - `url` — REQUIRED. A PR URL (`https://github.com/owner/repo/pull/N`, ADO PR URL) or canonical id (`github:owner/repo#N`, `ado:org/proj/repo#N`).
 - `action` — REQUIRED. One of `review`, `summarize`, `comment`, `triage` (read-only only; a code-mutating `fix` is intentionally NOT accepted here).
@@ -269,10 +273,10 @@ When the user describes a UI/E2E flow they want validated against a *live, runni
 - The user wants a code change, unit/integration tests in the repo, or an investigation. Keep using `/api/work-items` with `type: "fix"`, `"implement"`, `"test"`, `"explore"`.
 - The user explicitly says "QA …", "smoke test …", "test the … flow", "validate the … journey", or names a concrete UI walkthrough against a live app. Use `/api/qa/session`.
 
-**Body shape (mirrors `engine/qa-sessions.js#validateSpec`):**
+**Body shape (mirrors `engine/qa/sessions.js#validateSpec`):**
 
 - `target` — REQUIRED object describing what to QA against. `target.kind` is one of:
-  - `pr` — needs `target.prId` (e.g. `"github:yemi33/minions#2911"` or `"ado:office/iss/constellation#5215493"`).
+  - `pr` — needs `target.prId` (e.g. `"github:owner/repo#42"` or `"ado:org/project/repo#123"`).
   - `branch` — needs `target.branch` (e.g. `"develop"`).
   - `commit` — needs `target.sha` (full 40-char SHA).
   - `current` — uses the user's current worktree. `target.worktree` is optional; the SETUP agent falls back to `MINIONS_AGENT_CWD` when empty.
@@ -287,7 +291,7 @@ When the user describes a UI/E2E flow they want validated against a *live, runni
 curl -s -X POST http://localhost:{{dashboard_port}}/api/qa/session \
   -H 'Content-Type: application/json' \
   -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
-  -d '{"target":{"kind":"pr","prId":"github:yemi33/MyApp#1234"},"flowsRaw":"Open the homepage, click Login, enter test@example.com / hunter2, and verify the dashboard renders with the user'\''s name in the header.","mode":"confirm","capture":{"screenshots":true,"logs":true},"projects":["MyApp"]}'
+  -d '{"target":{"kind":"pr","prId":"github:owner/MyApp#1234"},"flowsRaw":"Open the homepage, click Login, enter test@example.com / hunter2, and verify the dashboard renders with the user'\''s name in the header.","mode":"confirm","capture":{"screenshots":true,"logs":true},"projects":["MyApp"]}'
 ```
 
 **Worked example — current worktree, auto mode, video capture, single project:**
@@ -312,7 +316,7 @@ curl -s -X POST http://localhost:{{dashboard_port}}/api/qa/session \
 
 ### PRD-driven QA — "qa this PRD" → POST /api/qa/from-prd
 
-When the user points QA at a **completed/approved PRD** rather than describing the flow themselves — "QA this PRD", "qa `minions-opg-2026-06-16-3`", "qa the PRD-driven QA PRD", "smoke test the checkout PRD" — route it through `POST /api/qa/from-prd` instead of building a `flowsRaw` by hand. This is a thin bridge over QA Sessions: `engine/qa-from-prd.js` reads the PRD JSON (and its `prd/guides/verify-*.md` when present), derives the QA `target` and the natural-language flows from the PRD's items / acceptance criteria, then reuses the exact same `createSession` + `queueSetup` orchestration as `/api/qa/session`. You don't assemble the spec — name the PRD and the endpoint does the rest.
+When the user points QA at a **completed/approved PRD** rather than describing the flow themselves — "QA this PRD", "qa `minions-opg-2026-06-16-3`", "qa the PRD-driven QA PRD", "smoke test the checkout PRD" — route it through `POST /api/qa/from-prd` instead of building a `flowsRaw` by hand. This is a thin bridge over QA Sessions: `engine/qa/from-prd.js` reads the PRD JSON (and its `prd/guides/verify-*.md` when present), derives the QA `target` and the natural-language flows from the PRD's items / acceptance criteria, then reuses the exact same `createSession` + `queueSetup` orchestration as `/api/qa/session`. You don't assemble the spec — name the PRD and the endpoint does the rest.
 
 **Body shape:** `{ prd, mode?, runner? }`
 
@@ -340,8 +344,8 @@ The `X-CC-Turn-Id` header is the audit trail — the handler stamps it onto the
   - **`fix` vs `implement` — pick deliberately.** `type: "fix"` in the engine means "this work item responds to comments or build failures on a tracked PR" — it requires a PR pointer (in `references[*].url`, `meta.pr_followup.parent_pr_url`, or `targetPr`/`pr_id`/`prNumber`) and is dispatched onto the PR's source branch. **Fresh bugfix work** that will open a NEW PR (engine bugs, default-branch CI failures, repo-level regressions found from logs) is `type: "implement"`, not `type: "fix"`. Emitting `type: "fix"` without a PR pointer trips the `pr_not_found` discovery gate (engine.js#discoverWork) and the WI stays blocked indefinitely. Rule of thumb: if the work could land on master via a brand-new PR, it's `implement`; if it must push commits into an existing PR's source branch, it's `fix`.
   - Exempt from the `project` requirement (these run rootless or via central paths): `ask`, `explore`, `plan`, `plan-to-prd`, `meeting`. (`docs` is intentionally NOT exempt — it's write-capable and lands in `WORKTREE_REQUIRING_TYPES`, so it needs a real project worktree. For minions-repo docs work, pass `project: "minions"` explicitly.) `setup` is also in the project-required set — it operates inside a real project worktree but produces no PR. Every other type needs a project worktree, so the server rejects project-less creates with `400 { error, knownProjects }` when ≠1 project is configured.
   - **`meta.keep_processes: true`** — opt-in flag that lets the agent leave specific descendant PIDs running after it exits (default: engine reaps EVERYTHING the agent spawned). **Set this whenever the user's intent is to leave a process alive after the agent finishes** — e.g. "spin up the dev server and exit", "start the watcher and leave it running", "set up my dev env", "keep the emulator open", "launch the daemon for me", "boot the constellation host and disconnect". Don't set it for normal build/test/run-once tasks (`npm test`, `npm run build`, one-shot scripts) — those should be reaped. Also accepts optional `meta.keep_processes_ttl_minutes` (default 60, hard-cap 1440 = 24h). When you set this flag, also make the WI title/description say something like "leave the dev server running" so the agent knows to write `agents/<id>/keep-pids.json` before exiting (the playbook injects the contract automatically when the flag is on). Example: `-d '{"title":"Spin up Constellation dev env and leave server running","type":"implement","project":"constellation","description":"Run bun install + bun run dev. Leave the dev server (port 5173) and Constellation host (port 3001) running after you exit so the user can iterate.","meta":{"keep_processes":true,"keep_processes_ttl_minutes":240}}'`. Inspect / kill kept PIDs anytime via `GET /api/keep-processes` and `POST /api/keep-processes/kill`.
-  - **`skipPr: true`** — opt-in flag that tells the engine NOT to enforce the PR-attachment contract for this work item, so the WI can complete `done` without the missing-PR hard-fail. **Set this when the dispatch mutates state OUTSIDE any tracked git repo and therefore cannot produce a PR** — e.g. cleaning `~/.claude/skills/`, editing runtime config under `~/.config/`, resetting the dashboard cache, mutating engine JSON state files (`engine/*.json`) the engine itself owns, or local tooling installs. **Do NOT set it for any task that touches a tracked repo's source** — even one-line diffs in a real repo should produce a PR. Type-selection rule of thumb: prefer `type: "setup"` for infra/dev-env bootstrap tasks that mutate project state but produce no PR (it's implicitly PR-exempt — no `skipPr` needed); prefer `type: "explore"` for genuinely read-only tasks (rootless, no worktree, no PR contract); use `skipPr: true` only when the task is write-side mutation but the writes don't land in a git repo and `setup` doesn't fit (e.g. cleaning user-machine state outside any repo). Example: `-d '{"title":"Bootstrap Constellation dev stack","type":"setup","project":"constellation","description":"Run bun install + bun run dev and leave the dev server running.","meta":{"managed_spawn":true}}'`.
-  - **`oneShot: true`** — opt-in flag for one-off human-initiated dispatches that should NOT enroll the discovered PR into the engine's automatic review/fix loop. The PR is still tracked (status + comments are polled normally) but `discoverFromPrs` skips it for review/fix dispatch. **Set this when the user's intent is "do this single action against an existing PR, then stop"** — e.g. "review PR #2533 once", "rebase PR #2540 once and exit", "post a fix-summary comment on PR #2519". Don't set it for normal feature/fix work where the PR should keep cycling through review/fix until merged. Example: `-d '{"title":"One-off review of PR #2533","type":"review","project":"minions","description":"Single review pass on github:yemi33/minions#2533. Do not re-dispatch on subsequent comments.","oneShot":true}'`.
+  - **`skipPr: true`** — opt-in flag that tells the engine NOT to enforce the PR-attachment contract for work that cannot produce a PR because it mutates state outside a tracked repository. This flag changes completion accounting only; it does **not** authorize filesystem cleanup or machine-level changes. Any such mutation still requires an explicit, path-specific user request, must preserve unrelated state, and must avoid broad deletion. **Do NOT set it for any task that touches tracked source.** Prefer `type: "setup"` for project bootstrap tasks and `type: "explore"` for read-only work.
+  - **`oneShot: true`** — opt-in flag for one-off human-initiated dispatches that should NOT enroll the discovered PR into the engine's automatic review/fix loop. The PR is still tracked (status + comments are polled normally) but `discoverFromPrs` skips it for review/fix dispatch. **Set this when the user's intent is "do this single action against an existing PR, then stop"** — e.g. "review PR #42 once", "rebase PR #43 once and exit", "post a fix-summary comment on PR #44". Don't set it for normal feature/fix work where the PR should keep cycling through review/fix until merged. Example: `-d '{"title":"One-off review of PR #42","type":"review","project":"MyApp","description":"Single review pass on github:owner/MyApp#42. Do not re-dispatch on subsequent comments.","oneShot":true}'`.
 - `POST /api/notes`: `title`, `what` REQUIRED.
 - `POST /api/knowledge`: `category`, `title`, `content` REQUIRED. Categories: `architecture`, `conventions`, `project-notes`, `build-reports`, `reviews`.
 - `POST /api/plan`: `title` REQUIRED. `description`, `priority`, `project`, `agent`, `branchStrategy` optional.
@@ -375,25 +379,13 @@ The server validates: `liveValidation` requires `checkoutMode:"live"`, canonical
 
 ## GitHub auth
 
-We have multiple authed `gh` accounts (`yemi33`, `yemishin_microsoft`) covering three repo scopes (`yemi33/minions`, `yemishin_microsoft/minions`, `opg-microsoft/minions`).
-
 **Never run `gh auth switch`.** It flips the global active account and races with the engine's GH poller — past `gh auth switch` calls left the engine polling the wrong account for hours, with PRs stuck in `abandoned` until reconciliation un-flipped them.
 
-To call `gh` against a specific account, build `GH_TOKEN` per command:
-
-```bash
-GH_TOKEN=$(gh auth token --user <account> --hostname github.com) gh <subcommand> ...
-```
-
-Account map (mirrors `engine.ghAccounts` in `config.json`):
-
-| Owner | gh account |
-|-------|------------|
-| `opg-microsoft` | `yemishin_microsoft` |
-| `yemishin_microsoft` | `yemishin_microsoft` |
-| `yemi33` | `yemi33` |
-
-The engine resolves these automatically via `engine/gh-token.js` for its own polling and issue creation; only CC and agents need to be careful in shell commands. If you're unsure which account a slug needs, the table above is the source of truth.
+For shell operations, enumerate configured `gh` accounts and select one by
+probing the exact target slug with a per-command `GH_TOKEN`. Verify repository
+identity and required permissions before any write. Fail closed when no account
+has access; never hardcode an operator login or rely on the globally active
+account. Engine-owned calls resolve this mapping through `engine/gh-token.js`.
 
 ## Document edits
 

package/watch-plugins/README.md

@@ -0,0 +1,92 @@
+# Watch Plugins
+
+This directory contains JavaScript extensions that add target types to Minions
+watches. A watch is a SQLite record that combines a target type, target,
+condition, interval, and optional action. Plugins define how a new kind of
+target is fetched, snapshotted, evaluated, and exposed to action templates.
+
+## Loading and trust
+
+At engine startup, `engine/watches/index.js` loads every top-level `*.js` file in
+`<MINIONS_DIR>/watch-plugins/`. Changes require an engine restart.
+
+Plugins are trusted, unsandboxed Node.js code running inside the engine process.
+They can access the filesystem, environment, network, and engine modules.
+Install only reviewed plugins. A plugin failure is logged and skipped so it
+does not prevent the engine from starting. Plugins cannot replace built-in or
+previously registered target types.
+
+The former directory name was `watches.d/`. Legacy custom plugins remain loaded
+with a deprecation warning so upgrades do not disable existing watches. Move
+them into `watch-plugins/`; new plugins belong only here.
+
+## Contract
+
+A plugin exports one `{ name, spec }` object or an array of them:
+
+```js
+module.exports = {
+  name: 'example-target',
+  spec: {
+    label: 'Example Target',
+    description: 'What this target watches',
+    conditions: ['status-change'],
+    absoluteConditions: [],
+    validateTarget(target, context) {
+      return null; // return an error string when invalid
+    },
+    fetchEntity(target, state) {
+      return null;
+    },
+    captureState(entity, previousState) {
+      return {};
+    },
+    evaluate(condition, entity, previousState, target) {
+      return { triggered: false, message: '' };
+    },
+    contextVars(entity, previousState, newState) {
+      return {};
+    },
+  },
+};
+```
+
+Required fields are `label`, non-empty `conditions`, `fetchEntity`,
+`captureState`, and `evaluate`. `description`, `absoluteConditions`,
+`validateTarget`, `isTerminalForCondition`, and `contextVars` are optional.
+
+The engine's watch evaluation path is synchronous. A plugin that performs
+network I/O should refresh a bounded module-level cache in the background and
+return the latest cached entity from `fetchEntity`. Never perform network calls
+while a Minions state lock is held.
+
+## Bundled plugins
+
+| Plugin | Target type | Purpose |
+|---|---|---|
+| `http.js` | `http` | Poll an HTTP endpoint and compare status or extracted values |
+| `gh-author-prs.js` | `gh-author-prs` | Detect new non-draft GitHub PRs by author |
+| `ado-author-prs.js` | `ado-author-prs` | Detect new non-draft Azure DevOps PRs by configured author |
+| `teams-channel.js` | `teams-channel` | Detect new Microsoft Teams channel messages and replies |
+
+Repository/account/channel identities belong in the watch target or Minions
+configuration, never as plugin defaults. GitHub authentication resolves through
+`config.engine.ghAccounts`; Azure DevOps plugins use the shared ADO token path.
+Secrets must come from environment variables or engine token helpers and must
+never be persisted in watch records or logs.
+
+## Creating a watch
+
+Use Dashboard **Watches**, the CLI, or the API. Discover the active runtime
+surface first:
+
+```bash
+minions watch target-types
+minions watch action-types
+```
+
+The dashboard API exposes the same registries at
+`GET /api/watches/target-types` and `GET /api/watches/action-types`.
+
+Full lifecycle, condition, and action documentation:
+[docs/watches.md](../docs/watches.md).