@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/watches.md

@@ -20,41 +20,41 @@ A watch is a record persisted in `engine/state.db`. It binds:
 | `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 through the watch store *(source: `engine/watches.js` and `engine/watches-store.js`)*.
+`createWatch()` allocates a `watch-<uid>` id, defaults the fields above, and persists through the watch store *(source: `engine/watches/index.js` and `engine/watches/store.js`)*.
 
 ## Lifecycle (`WATCH_STATUS`)
 
-Defined in `engine/shared.js` (`WATCH_STATUS`):
+Defined in `engine/core/shared.js` (`WATCH_STATUS`):
 
 | Status      | Meaning                                                                 |
 |-------------|-------------------------------------------------------------------------|
 | `active`    | Eligible for evaluation each tick                                       |
 | `paused`    | Skipped by `checkWatches`; persists indefinitely until resumed/deleted  |
 | `triggered` | Reserved status (set on demand by callers; not auto-applied)            |
-| `expired`   | Auto-set when `stopAfter` is reached, or on first trigger for absolute conditions when `stopAfter === 0`. The watch is left on disk for audit but no longer evaluated *(source: `engine/watches.js:499-513`)* |
+| `expired`   | Auto-set when `stopAfter` is reached, or on first trigger for absolute conditions when `stopAfter === 0`. The watch is retained for audit but no longer evaluated *(source: `engine/watches/index.js`)* |
 
-Pause/resume flips the `status` field via `POST /api/watches/update` *(source: `engine/watches.js` `updateWatch`, `dashboard.js` `handleWatchesUpdate`)*.
+Pause/resume flips the `status` field via `POST /api/watches/update` *(source: `engine/watches/index.js` `updateWatch`, `dashboard.js` `handleWatchesUpdate`)*.
 
 ## Conditions (`WATCH_CONDITION`)
 
-Defined in `engine/shared.js` (`WATCH_CONDITION`). Conditions split into two families:
+Defined in `engine/core/shared.js` (`WATCH_CONDITION`). Conditions split into two families:
 
 ### Absolute conditions (`WATCH_ABSOLUTE_CONDITIONS`)
-*(source: `engine/shared.js` `WATCH_ABSOLUTE_CONDITIONS`)*
+*(source: `engine/core/shared.js` `WATCH_ABSOLUTE_CONDITIONS`)*
 
 `merged`, `build-fail`, `build-pass`, `completed`, `failed`, `concluded`, `approved`, `rejected`, `ready-for-merge`, `retry-limit-reached`, `all-items-done`, `item-failed-n-times`.
 
-When `stopAfter === 0`, these are **fire-once** — the engine flips the watch to `expired` after the first trigger so a permanently-merged PR (or a permanently-true compound state assertion like `ready-for-merge`) doesn't keep notifying *(source: `engine/watches.js:499-513`)*.
+When `stopAfter === 0`, these are **fire-once** — the engine flips the watch to `expired` after the first trigger so a permanently-merged PR (or a permanently-true compound state assertion like `ready-for-merge`) doesn't keep notifying *(source: `engine/watches/index.js`)*.
 
 > **Per-target override (W-mp7hg58e000b5212):** the global `WATCH_ABSOLUTE_CONDITIONS` set is the legacy fallback. Each target type now declares its own `absoluteConditions: [...]` array in its spec; `registerTargetType` normalizes that into a `Set` that takes precedence at evaluation time. The plugin contract (see below) uses this to keep absolute-vs-change semantics local to each target type. Plugins that omit `absoluteConditions` get an empty set (all change-based).
 
 ### Change-based conditions
-`status-change`, `any`, `new-comments`, `vote-change`, `stage-complete`, `ran`, `enabled`, `disabled`, `activity-change`, plus the predicate conditions added under P-w4e2f6a1 / P-w5b8d2c9 for the `pr`, `work-item`, `plan`, and `pipeline` target types (`head-commit-change`, `mergeable-flipped`, `behind-master`, `draft-flipped`, `stalled`, `dependency-met`, `stage-advanced`, `stuck-in-stage`). See `engine/shared.js` `WATCH_CONDITION` for the canonical enum.
+`status-change`, `any`, `new-comments`, `vote-change`, `stage-complete`, `ran`, `enabled`, `disabled`, `activity-change`, plus the predicate conditions added under P-w4e2f6a1 / P-w5b8d2c9 for the `pr`, `work-item`, `plan`, and `pipeline` target types (`head-commit-change`, `mergeable-flipped`, `behind-master`, `draft-flipped`, `stalled`, `dependency-met`, `stage-advanced`, `stuck-in-stage`). See `engine/core/shared.js` `WATCH_CONDITION` for the canonical enum.
 
-These 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:436-440, 558-559`)*.
+These 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/index.js`)*.
 
 ### Tick-counted conditions
-`stalled`, `stuck-in-stage` — require N consecutive unchanged captures (default `WATCH_STALLED_DEFAULT_TICKS = 12`, `WATCH_STUCK_STAGE_DEFAULT_TICKS = 12`, both in `engine/shared.js`). Counters (`_unchangedTicks`, `_stuckStageTicks`) are recomputed inside `_captureState` by comparing the fresh snapshot against `prevState`.
+`stalled`, `stuck-in-stage` — require N consecutive unchanged captures (default `WATCH_STALLED_DEFAULT_TICKS = 12`, `WATCH_STUCK_STAGE_DEFAULT_TICKS = 12`, both in `engine/core/shared.js`). Counters (`_unchangedTicks`, `_stuckStageTicks`) are recomputed inside `_captureState` by comparing the fresh snapshot against `prevState`.
 
 ### Predicate conditions
 
@@ -65,11 +65,11 @@ Several condition keys evaluate a derived predicate on the captured entity/state
 - **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`)*.
+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/core/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:122-174`)*. Each spec uses the following fields; entries are required unless marked optional:
+Target-type behavior in `engine/watches/index.js` is **data-driven via a registry**. Each spec uses the following fields; entries are required unless marked optional:
 
 - `label` — human name shown in dashboard pickers
 - `description` — **(optional)** short help text; defaults to `''` in `listTargetTypes()`
@@ -78,22 +78,22 @@ Target-type behavior in `engine/watches.js` is **data-driven via a registry** *(
 - `fetchEntity(target, state)` — entity-or-null lookup; must return the fetched resource or null
 - `captureState(entity, prevState)` — snapshot object used for change-detection diffs; `prevState` parameter lets counters and custom fields carry across checks
 - `evaluate(condition, entity, prevState, target)` — returns `{ triggered: boolean, message: string }`; core condition-check logic
-- `isTerminalForCondition(condition, entity, prevState)` — *(optional)* W-mqa63opd000ha836. When a watch's `condition` cannot possibly fire again because the target reached a permanent terminal state (e.g. a PR was merged/closed/abandoned and the watch is on `build-fail`, `build-pass`, `vote-change`, `new-comments`, `head-commit-change`, `mergeable-flipped`, `behind-master`, `ready-for-merge`, or `draft-flipped`), return `true` and the engine auto-expires the watch. Default returns `false` so existing target types keep polling forever. The main check loop invokes this only when `triggerCount > 0` **or** the prev-state status already matched current entity — so a watch armed on an already-terminal PR with `condition: merged` still fires once via the absolute-condition fire-once path *(source: `engine/watches.js:150-158, 537-550`)*.
+- `isTerminalForCondition(condition, entity, prevState)` — *(optional)* W-mqa63opd000ha836. When a watch's `condition` cannot possibly fire again because the target reached a permanent terminal state (e.g. a PR was merged/closed/abandoned and the watch is on `build-fail`, `build-pass`, `vote-change`, `new-comments`, `head-commit-change`, `mergeable-flipped`, `behind-master`, `ready-for-merge`, or `draft-flipped`), return `true` and the engine auto-expires the watch. Default returns `false` so existing target types keep polling forever. The main check loop invokes this only when `triggerCount > 0` **or** the prev-state status already matched current entity — so a watch armed on an already-terminal PR with `condition: merged` still fires once via the absolute-condition fire-once path *(source: `engine/watches/index.js`)*.
 - `contextVars(entity, prevState, newState)` — *(optional)* returns object with extra action-template variables contributed by the target type (e.g., `{ httpStatus: 200, prevExtracted: 'foo' }`)
 
-The registry IS the allowlist for `createWatch` and `/api/watches/target-types`; the old hardcoded "pr or work-item" check is gone. Add a new target type at runtime with `registerTargetType(type, spec)` and look one up with `getTargetType(type)`. `listTargetTypes()` returns the serializable form used by the dashboard *(source: `engine/watches.js:122-174`)*.
+The registry IS the allowlist for `createWatch` and `/api/watches/target-types`; the old hardcoded "pr or work-item" check is gone. Add a new target type at runtime with `registerTargetType(type, spec)` and look one up with `getTargetType(type)`. `listTargetTypes()` returns the serializable form used by the dashboard.
 
-### User-extensible via `watches.d/` (W-mp7hg58e000b5212)
+### User-extensible via `watch-plugins/`
 
-At engine boot, every `*.js` file in `<MINIONS_DIR>/watches.d/` is auto-loaded **after** the built-in registrations *(source: `engine/watches.js:1401-1436`)*, so plugins can both add new target types and override built-ins. A plugin file exports either `{ name, spec }` or an array of such objects. Failures are logged-and-skipped — one bad plugin must not break boot or block other plugins. Reloads require an engine restart.
+At engine boot, every `*.js` file in `<MINIONS_DIR>/watch-plugins/` is auto-loaded **after** the built-in registrations. Plugins can add target types but cannot replace an existing type. A plugin file exports either `{ name, spec }` or an array of such objects. Failures are logged-and-skipped — one bad plugin must not break boot or block other plugins. Reloads require an engine restart.
 
-Canonical example: `watches.d/http.js` (W-mp7i22mu00191b07) — a generic HTTP poller covering the full plugin contract including `captureState` (custom snapshot fields) and `contextVars` (custom action-template vars like `{{httpStatus}}`, `{{prevExtracted}}`).
+Canonical example: `watch-plugins/http.js` — a generic HTTP poller covering the full plugin contract including `captureState` and `contextVars`.
 
-This source checkout also includes `ado-author-prs`, `gh-author-prs`, and `teams-channel` plugins under `watches.d/`. They are dynamically loaded plugins, not members of the eight built-in target types; `GET /api/watches/target-types` is the authoritative list for the running installation.
+This source checkout also includes `ado-author-prs`, `gh-author-prs`, and `teams-channel` plugins under `watch-plugins/`. They are dynamically loaded plugins, not members of the eight built-in target types; `GET /api/watches/target-types` is the authoritative list for the running installation.
 
 ### Built-in target types
 
-The eight built-ins are registered at module load *(source: `engine/watches.js` — the long `registerTargetType(...)` block)*. Constants live in `WATCH_TARGET_TYPE` in `engine/shared.js`.
+The eight built-ins are registered at module load *(source: `engine/watches/index.js`)*. Constants live in `WATCH_TARGET_TYPE` in `engine/core/shared.js`.
 
 | `targetType`  | Target value                         | Conditions                                                                 | Notes |
 |---------------|--------------------------------------|----------------------------------------------------------------------------|-------|
@@ -106,13 +106,13 @@ The eight built-ins are registered at module load *(source: `engine/watches.js`
 | `dispatch`    | Dispatch entry id                    | `completed`, `failed`, `status-change`, `any`                              | Looks across `pending` / `active` / `completed` lists |
 | `agent`       | Agent id                             | `activity-change`, `status-change`, `any`                                  | `activity-change` fires only on transitions in/out of `'working'` |
 
-`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:320-365`)*.
+`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/index.js`)*.
 
-### Plugin folder (`watches.d/`) — user-extensible target types
+### Plugin folder (`watch-plugins/`) — user-extensible target types
 
-W-mp7hg58e000b5212 added a **plugin folder** so operators can register new target types without editing engine source. At engine boot, `engine/watches.js` scans `<MINIONS_DIR>/watches.d/*.js` *after* the eight built-ins are registered (so plugins can override a built-in by re-using its key — last-write-wins) and calls `registerTargetType()` for each export *(source: `engine/watches.js:1401-1436`)*.
+The plugin folder lets operators register new target types without editing engine source. At engine boot, `engine/watches/index.js` scans `<MINIONS_DIR>/watch-plugins/*.js` after the eight built-ins are registered and calls `registerTargetType()` for each unique export. Duplicate names are logged and skipped.
 
-Each `watches.d/<name>.js` file must export `{ name, spec }` (or an array of those):
+Each `watch-plugins/<name>.js` file must export `{ name, spec }` (or an array of those):
 
 ```js
 module.exports = {
@@ -132,9 +132,9 @@ module.exports = {
 };
 ```
 
-Resolution is `path.join(shared.MINIONS_DIR, 'watches.d')` so it works in both dev checkouts and installed `~/.minions/` layouts. Missing folder is silent; per-file failures are isolated (load errors log a `WARN` line, don't abort boot). Tests can re-scan via the exported `_loadPluginTargetTypes()`.
+Resolution is `path.join(shared.MINIONS_DIR, 'watch-plugins')` so it works in both dev checkouts and installed `~/.minions/` layouts. Missing folder is silent; per-file failures are isolated. Legacy custom plugins under `watches.d/` remain compatibility-loaded with a warning until operators move them. Tests can re-scan via the exported `_loadPluginTargetTypes()`. Plugins are unsandboxed trusted code; see [`watch-plugins/README.md`](../watch-plugins/README.md) before adding one.
 
-**Canonical plugin example:** [`watches.d/http.js`](../watches.d/http.js) (W-mp7i22mu00191b07) ships a generic `http` target type — point a watch at any URL or `{ url, method, headers, body, extract, expected, regex, timeoutMs }` config and the plugin exposes `status-change`, `value-change`, `value-equals`, `value-matches`, and `http-error` conditions. Auth headers support `{{env.GH_TOKEN}}`-style substitution at fetch time (secrets are never persisted in watch records). All conditions are change-based (`absoluteConditions: []`).
+**Canonical plugin example:** [`watch-plugins/http.js`](../watch-plugins/http.js) ships a generic `http` target type — point a watch at any URL or `{ url, method, headers, body, extract, expected, regex, timeoutMs }` config and the plugin exposes `status-change`, `value-change`, `value-equals`, `value-matches`, and `http-error` conditions. Auth headers support `{{env.GH_TOKEN}}`-style substitution at fetch time. All conditions are change-based.
 
 ## Tick Integration
 
@@ -159,11 +159,11 @@ Resolution is `path.join(shared.MINIONS_DIR, 'watches.d')` so it works in both d
 6. On non-trigger: writes a per-poll inbox note when `onNotMet === 'notify'`.
 7. Refreshes `_lastState` for the next check.
 
-I/O happens **outside the lock**. Trigger actions, including the implicit inbox notification, run through `_runActionTask`. Only `onNotMet === 'notify'` polling notes use the direct notification queue and `writeToInbox`. Each action result is persisted back onto the watch as `_lastActionResult` in a follow-up locked write. An implicit notify makes the effective action array-shaped, so its result uses the `type: 'chain'` / `steps[]` shape; an explicit action without an implicit notify preserves the legacy single-action result shape *(source: `engine/watches.js:459-495,515-521,601-684`)*.
+I/O happens **outside the lock**. Trigger actions, including the implicit inbox notification, run through `_runActionTask`. Only `onNotMet === 'notify'` polling notes use the direct notification queue and `writeToInbox`. Each action result is persisted back onto the watch as `_lastActionResult` in a follow-up locked write. An implicit notify makes the effective action array-shaped, so its result uses the `type: 'chain'` / `steps[]` shape; an explicit action without an implicit notify preserves the legacy single-action result shape *(source: `engine/watches/index.js`)*.
 
 ## Follow-Up Actions on Trigger
 
-`watch.action` is an optional structured action (or action chain). When the implicit inbox notification is enabled, configured actions follow it in the same effective chain. Action types live in a sibling registry in `engine/watch-actions.js` and are validated at create/update time *(source: `engine/watches.js:189-245` `createWatch`, `engine/watch-actions.js:95-105` `registerActionType`)*. `GET /api/watches/action-types` returns the live list for dashboard pickers.
+`watch.action` is an optional structured action (or action chain). When the implicit inbox notification is enabled, configured actions follow it in the same effective chain. Action types live in `engine/watches/actions.js` and are validated at create/update time. `GET /api/watches/action-types` returns the live list for dashboard pickers.
 
 ### Built-in actions
 
@@ -180,11 +180,11 @@ I/O happens **outside the lock**. Trigger actions, including the implicit inbox
 | `resume-plan`          | Set PRD `status=PLAN_STATUS.ACTIVE` and clear `planStale`                                     |
 | `cc-triage`            | Invoke Command Center headlessly via the loopback `POST /api/command-center/triage` endpoint with the trigger context (and optional completion-report / live-output artifacts). Wraps the prompt in `<UNTRUSTED-INPUT>`, uses a default 10-min timeout (capped at 1 h), and is isolated from the user CC session |
 
-Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js`); handlers in `engine/watch-actions.js`.
+Constants live in `WATCH_ACTION_TYPE` (`engine/core/shared.js`); handlers live in `engine/watches/actions.js`.
 
 ### Templating
 
-Action params support `{{var}}` substitution from the trigger context *(source: `engine/watch-actions.js:133-230`)*. Built-in vars from `buildTriggerContext`:
+Action params support `{{var}}` substitution from the trigger context *(source: `engine/watches/actions.js`)*. Built-in vars from `buildTriggerContext`:
 
 - Always: `target`, `targetType`, `condition`, `watchId`, `triggerCount`, `message`
 - All scalar fields from `newState` (e.g. `status`, `buildStatus`, `reviewStatus`, `lastRun`)
@@ -194,7 +194,7 @@ Unknown vars are left as `{{var}}` so callers can detect them downstream.
 
 ### Failure isolation
 
-Action handlers must return `{ ok: false, summary }` rather than throw — `runWatchAction` wraps them in try/catch as a backstop *(source: `engine/watch-actions.js:262-293`)*. A bad action never blocks other watches in the same tick, and the failed result is persisted onto the watch as `_lastActionResult` for debugging. Multi-step action chains run via `runWatchActionChain` *(source: `engine/watch-actions.js:310-355`)* — each step's `{ok, summary, result}` is templated into the next step's params as `{{steps.N.result.<field>}}`.
+Action handlers must return `{ ok: false, summary }` rather than throw — `runWatchAction` wraps them in try/catch as a backstop. A bad action never blocks other watches in the same tick, and the failed result is persisted onto the watch as `_lastActionResult` for debugging. Multi-step action chains run via `runWatchActionChain` in `engine/watches/actions.js`.
 
 ## Dashboard Surface
 
@@ -227,8 +227,8 @@ CC will discover the endpoints from `GET /api/routes` and `POST /api/watches` wi
 When a watch fires:
 
 - The SQL watch record gets `triggerCount++`, `last_triggered=<ISO>`, `_lastTriggerMessage=<message>`, and a refreshed `_lastState`.
-- When `notify === 'inbox'`, the engine prepends an implicit `{type: 'notify'}` action to the action chain (if present) or runs notify standalone, so the inbox alert participates in action-chain execution and `_lastActionResult` *(source: `engine/watches.js:459-496`)*. This is the **trigger-time notify**, paired with an optional explicit `action`.
-- When `onNotMet === 'notify'` (and the condition has NOT yet fired), the engine instead queues a direct poll notification outside the action chain — independent of any `action` field *(source: `engine/watches.js:515-521`)*. This is a separate **onNotMet-notify**, useful for "still watching, condition not met yet" progress updates.
+- When `notify === 'inbox'`, the engine prepends an implicit `{type: 'notify'}` action to the action chain (if present) or runs notify standalone, so the inbox alert participates in action-chain execution and `_lastActionResult` *(source: `engine/watches/index.js`)*. This is the **trigger-time notify**, paired with an optional explicit `action`.
+- When `onNotMet === 'notify'` (and the condition has NOT yet fired), the engine instead queues a direct poll notification outside the action chain — independent of any `action` field *(source: `engine/watches/index.js`)*. This is a separate **onNotMet-notify**, useful for "still watching, condition not met yet" progress updates.
 - If an action runs, `_lastActionResult` stores either the single-action shape (`{ type, ok, summary, dispatchedItemId, at }`) or the chain shape (`{ type: "chain", ok, summary, aborted, steps, at }`).
 - The SQL engine log gets `Watch triggered: <id> — <message>` and `Watch <id> action <type-or-chain[N]>: <summary>`.
 
@@ -241,21 +241,22 @@ Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `
 | Watch never fires                                                       | Check `status === 'active'`; check `last_checked` advancing each cycle; confirm engine tick is running and `interval` isn't longer than your test window |
 | `evaluateWatch` returns `"<label> <target> not found"`                   | `fetchEntity` got nothing back — wrong `target` (e.g. PR display id vs canonical id), the target type isn't loaded, or the underlying file (PR cache, plan PRD) doesn't exist |
 | `"Unknown target type"` / `"Unknown condition"`                         | The registry doesn't recognise the value. Check `GET /api/watches/target-types` to see what's registered server-side; condition must be in that target type's `conditions[]` |
-| Change condition fires immediately on first tick                        | Won't happen — baseline `_lastState` is captured on the first check before `evaluate` runs *(source: `engine/watches.js`)*. If you see this, inspect the persisted watch through the API |
+| Change condition fires immediately on first tick                        | Won't happen — baseline `_lastState` is captured on the first check before `evaluate` runs *(source: `engine/watches/index.js`)*. If you see this, inspect the persisted watch through the API |
 | Absolute watch fires forever instead of once                            | `stopAfter` is set to a non-zero value; only `stopAfter === 0` triggers fire-once expiration |
 | Action runs but inbox notification doesn't                              | `notify` field isn't `'inbox'`, or `owner` is empty. `notify` and `action` are independent — both can fire, or only one |
 | `_lastActionResult.ok === false` with `"unknown action type"`           | The `action.type` isn't registered. List with `listActionTypes()` / `GET /api/watches/action-types` |
-| Webhook action returns `"only http/https allowed"`                      | URLs must use `http://` or `https://` schemes; other protocols are rejected by design *(source: `engine/watch-actions.js` `WEBHOOK` handler)* |
+| Webhook action returns `"only http/https allowed"`                      | URLs must use `http://` or `https://` schemes; other protocols are rejected by design *(source: `engine/watches/actions.js` `WEBHOOK` handler)* |
 | Trigger fires but follow-up `dispatch-work-item` is missing              | Check the engine log for `Watch <id> action <type>: <summary>`. Common reasons: missing `title`, a project-scope write failed, or the WI landed in the central scope because no project was specified |
-| Watch `_lastActionResult` shows `"timeout"` for webhook                 | Webhooks have a 10s safety timeout to keep the watches tick fast *(source: `engine/watch-actions.js:550-553`)* |
+| Watch `_lastActionResult` shows `"timeout"` for webhook                 | Webhooks have a 10s safety timeout to keep the watches tick fast *(source: `engine/watches/actions.js`)* |
 | `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick. Inspect the engine log for `Watch check error (<id>)` lines. Regression #1088: the block must use `getProjects(config)`, never the long-removed `PROJECTS` constant |
 
 ## See Also
 
-- `engine/shared.js` — `WATCH_STATUS`, `WATCH_TARGET_TYPE`, `WATCH_CONDITION`, `WATCH_ABSOLUTE_CONDITIONS`, `WATCH_ACTION_TYPE` constants
-- `engine/watches.js` — registry, lifecycle, tick integration, `watches.d/` plugin loader
-- `engine/watch-actions.js` — action registry and built-in handlers (including `minions-api`)
-- `watches.d/http.js` — canonical user-extensible target type plugin
+- `engine/core/shared.js` — `WATCH_STATUS`, `WATCH_TARGET_TYPE`, `WATCH_CONDITION`, `WATCH_ABSOLUTE_CONDITIONS`, `WATCH_ACTION_TYPE` constants
+- `engine/watches/index.js` — registry, lifecycle, tick integration, `watch-plugins/` loader
+- `engine/watches/actions.js` — action registry and built-in handlers
+- `engine/watches/store.js` — SQL-backed watch persistence
+- `watch-plugins/http.js` — canonical user-extensible target type plugin
 - `dashboard/pages/watches.html`, `dashboard/js/render-watches.js` — dashboard UI
 - `test/unit/watches-module.test.js`, `test/unit/watch-actions.test.js`, `test/unit/watches-plugin-loader.test.js` — module-level tests
 - [`auto-discovery.md`](auto-discovery.md) — overall tick cycle context

package/docs/workspace-manifests.md

@@ -38,7 +38,7 @@ A manifest lives on each agent definition under `workspace_manifest`. All fields
 The defaults are deliberately permissive so the manifest can be rolled out incrementally:
 
 ```js
-// engine/shared.js
+// engine/core/shared.js
 const WORKSPACE_MANIFEST_DEFAULTS = {
   allowed_tools:         null,   // no tool restriction
   allowed_repos:         null,   // no repo restriction
@@ -59,13 +59,13 @@ A config that never mentions `workspace_manifest` produces the exact same dispat
 | **URL fetch** | Advisory today | `allowed_external_urls` is validated at config load. No runtime helper function — a future runtime adapter hook can wire URL-fetch intercepts against the manifest. |
 | **Memory scope** | Advisory today | `memory_scope` field is stored in the manifest (`private` = agent only sees its own `knowledge/agents/<id>.md`; `shared` = full team knowledge (current default); `read-only-shared` = reads shared memory but should not write inbox/notes). No runtime enforcement helper — full enforcement at the consolidation layer is future work. |
 
-## Helpers (in `engine/shared.js`)
+## Helpers (in `engine/core/shared.js`)
 
 ```js
 const { MEMORY_SCOPES, WORKSPACE_MANIFEST_DEFAULTS,
         validateWorkspaceManifest, resolveAgentManifest,
         agentCanUseRepo,
-        mergeManifestAllowedTools, formatManifestRejection } = require('./engine/shared');
+        mergeManifestAllowedTools, formatManifestRejection } = require('./engine/core/shared');
 ```
 
 - `validateWorkspaceManifest(manifest)` → `{ ok, errors }`. `null`/`undefined` is valid (uses defaults).
@@ -95,7 +95,7 @@ Because rejections route through the standard `completeDispatch(... ERROR ...)`
 
 ## Related
 
-- `engine/shared.js` — manifest helpers and `FAILURE_CLASS`.
+- `engine/core/shared.js` — manifest helpers and `FAILURE_CLASS`.
 - `engine.js spawnAgent()` — dispatch-time enforcement.
 - `test/unit/workspace-manifest.test.js` — full validator + gate + integration tests.
 - [`completion-reports.md`](completion-reports.md) — how the dispatch failure surfaces in the standard completion contract.