@yemi33/minions 0.1.1964 → 0.1.1965

package/docs/README.md

@@ -36,6 +36,13 @@ Operational runbooks for engine operators and fleet maintainers.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
 - [onboarding.md](onboarding.md) — First-run setup: installing the CLI, linking a project, the doctor preflight, and the first dispatch.
 
+## Design notes & explorations
+
+In-progress UX or architecture proposals; not yet shipped behavior.
+
+- [slim-ux/concepts.md](slim-ux/concepts.md) — Slim-UX dashboard concept exploration (project picker, inline project link, decoupled folder picker).
+- [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Companion architecture suggestions for the slim-UX track.
+
 ---
 
 **Adding a new doc?** Drop the file in `docs/` and add a one-line entry above under the right audience group. Keep entries alphabetical within each group.

package/docs/auto-discovery.md

@@ -1,6 +1,6 @@
 # Auto-Discovery & Execution Pipeline
 
-> Last verified: 2026-05-16 against `engine.js` `tickInner()` (lines 5381-5717).
+> Last verified: 2026-05-17 against `engine.js` `tickInner()` (lines 5360-5993).
 
 How the minions engine finds work and dispatches agents automatically.
 

package/docs/watches.md

@@ -17,6 +17,7 @@ A watch is a small JSON record persisted to `engine/watches.json`. It binds:
 | `stopAfter`  | `0` = run forever for change conditions / fire-once for absolute; `N` = expire after N triggers |
 | `onNotMet`   | `null` or `'notify'` — write a per-poll inbox note when the condition is not yet met |
 | `action`     | Optional follow-up action (see "Follow-Up Actions" below)                |
+| `requires`   | Optional guard: array of predicate objects evaluated against `state` / `entity` / `prevState`; trigger is suppressed when any guard fails (false-or-error). Used to gate a watch on "PR is mergeable AND build passing" etc. |
 | `status`     | `WATCH_STATUS.ACTIVE` \| `PAUSED` \| `TRIGGERED` \| `EXPIRED`            |
 
 `createWatch()` allocates a `watch-<uid>` id, defaults the fields above, and persists atomically via `mutateJsonFileLocked` *(source: `engine/watches.js:184`)*.
@@ -53,6 +54,17 @@ When `stopAfter === 0`, these are **fire-once** — the engine flips the watch t
 
 Change-based and tick-counted conditions compare the live entity against the watch's `_lastState` snapshot and run forever when `stopAfter === 0`. Baseline `_lastState` is captured on the first check so the very next change triggers the watch *(source: `engine/watches.js:434, 520`)*.
 
+### Predicate conditions
+
+Several condition keys evaluate a derived predicate on the captured entity/state rather than comparing to `_lastState`. Built-in predicates per target type:
+
+- **PR** — `head-commit-change` (headRefOid advanced), `mergeable-flipped` (mergeable true↔false), `ready-for-merge` (active+approved+passing+mergeable+!draft compound), `behind-master` (`pr.behindBy > 0`), `draft-flipped` (isDraft true↔false).
+- **work-item** — `stalled` (no captured-state change for `WATCH_STALLED_DEFAULT_TICKS` checks, default 12 = ~60min), `retry-limit-reached` (`_retryCount >= ENGINE_DEFAULTS.maxRetries`), `dependency-met` (`_pendingReason` transitioned away from `dependency_unmet`).
+- **plan** — `all-items-done` (`items_done === items_total > 0`), `item-failed-n-times` (any `missing_features[*]._retryCount >= ENGINE_DEFAULTS.maxRetries`).
+- **pipeline** — `stage-advanced` (`current_stage_id` changed within the same `runId`), `stuck-in-stage` (current stage unchanged for `WATCH_STUCK_STAGE_DEFAULT_TICKS` checks, default 12).
+
+Compound state-assertion predicates (`ready-for-merge`, `retry-limit-reached`, `all-items-done`, `item-failed-n-times`) live in `WATCH_ABSOLUTE_CONDITIONS` so they fire-once when `stopAfter === 0` — without that they would re-fire every tick while the assertion holds *(source: `engine/shared.js` `WATCH_ABSOLUTE_CONDITIONS`)*.
+
 ## Target Types — `TARGET_TYPES` Registry
 
 Target-type behavior in `engine/watches.js` is **data-driven via a registry** *(source: `engine/watches.js:101, 124-160`)*. Each spec must provide:
@@ -89,6 +101,10 @@ The eight built-ins are registered at module load *(source: `engine/watches.js:6
 
 `evaluateWatch` dispatches to `tt.evaluate(...)`; unknown target types return `"Unknown target type: ..."` and unknown conditions return `"Unknown condition: ..."` — both are non-triggering *(source: `engine/watches.js:318+`)*.
 
+### User-extensible target types via `watches.d/`
+
+`engine/watches.js` boot-loads optional plugin files from `~/.minions/watches.d/*.js` (and the equivalent under `MINIONS_DIR` for tests). Each plugin module exports `{ name, spec }` (or an array thereof) and is passed straight to `registerTargetType()`. Plugins can override built-ins by name, so a user can extend or replace shipped behavior without editing engine code. The shipped `http` target type (live URL polling: `status-change`, `failed`, `ran`, `any`) lands as the first reference plugin — see `watches.d/http.js` for the canonical example.
+
 ## Tick Integration
 
 `engine.js` calls `checkWatches(config, state)` every 3 ticks (~3 min at the default 60s tick) inside its own `safe('checkWatches', ...)` block *(source: `engine.js:5449-5507`)*. The engine builds the state object from cached project files + module reads:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1964",
+  "version": "0.1.1965",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"