@yemi33/minions 0.1.1883 → 0.1.1885

package/docs/runtime-adapters.md

@@ -0,0 +1,213 @@
+# Runtime Adapters
+
+How Minions abstracts over CLI runtimes (Claude Code, GitHub Copilot CLI, future
+adapters). Engine code never special-cases a runtime by name — every CLI-specific
+behavior is hidden behind an adapter object resolved through `resolveRuntime()`.
+
+## What lives in `engine/runtimes/`
+
+| File | Role |
+|------|------|
+| `engine/runtimes/index.js` | Adapter registry. `resolveRuntime(name)`, `listRuntimes()`, `registerRuntime()`. Engine code MUST go through these. |
+| `engine/runtimes/claude.js` | Claude Code adapter. Owns binary probe, `--system-prompt-file`, JSONL parser, model shorthands, budget cap, bare mode. |
+| `engine/runtimes/copilot.js` | GitHub Copilot CLI adapter. Owns standalone-vs-`gh-copilot` resolution, stdin-only prompt delivery, `https://api.githubcopilot.com/models` discovery, effort `'max' → 'xhigh'` mapping. |
+
+`resolveRuntime(name)` throws when `name` is unknown so misconfigurations surface
+at dispatch time instead of producing silent fallbacks deep inside spawn logic.
+The default name is `'claude'` (matches `engine.defaultCli` fallback).
+
+## Adapter Interface
+
+Every adapter exports the following surface. The Claude adapter is the canonical
+implementation — copy it as the template for new runtimes and only override the
+methods that genuinely differ.
+
+| Member | Type / Returns | Purpose |
+|--------|----------------|---------|
+| `name` | string | Adapter identifier (matches the registry key). |
+| `capabilities` | flag object (see below) | Feature flags consumed by engine code. |
+| `resolveBinary({ env, config? })` | `{ bin, native, leadingArgs }` or null | Probe PATH, npm-globals, package overrides; cached to `engine/<name>-caps.json`. `leadingArgs` is `[]` for direct binaries and `['copilot']` for the `gh copilot` extension fallback. |
+| `capsFile` | absolute path | Cache file for `resolveBinary()` results. |
+| `installHint` | string | Surfaced when `resolveBinary()` returns null. Consumed by `engine/preflight.js` and `engine/spawn-agent.js`. |
+| `listModels()` | `Promise<{id,name,provider}[] | null>` | Model catalog or null when discovery isn't supported. |
+| `modelsCache` | absolute path | Cache file for `listModels()` results. |
+| `spawnScript` | absolute path | Path to the runtime-agnostic spawn wrapper (currently `engine/spawn-agent.js` for both runtimes). |
+| `buildArgs(opts)` | `string[]` | CLI args excluding the binary itself. |
+| `buildSpawnFlags(opts)` | `string[]` | Optional; engine-side flags consumed by `engine/spawn-agent.js` (overrides the default `_buildAgentSpawnFlags`). |
+| `buildPrompt(promptText, sysPromptText)` | string | Final prompt delivered to the CLI. Adapters that lack `--system-prompt-file` (Copilot) prepend a `<system>` block here. |
+| `getUserAssetDirs({ homeDir })` | `string[]` | Runtime-native global asset roots passed to spawn as `--add-dir` so worktrees still see them. |
+| `getSkillRoots({ homeDir, project? })` | `[{ scope, dir, projectName? }]` | Where `collectSkillFiles` looks for native + project skill markdown. |
+| `getSkillWriteTargets({ homeDir, project? })` | `{ personal, project }` | Where `extractSkillsFromOutput` writes auto-extracted skills. |
+| `getResumeSessionId(...)` | string or null | Pre-spawn resume probe; runtime-agnostic stamp prevents cross-runtime session-ID confusion. |
+| `saveSession(...)` | void | Writes `agents/<id>/session.json` after a successful turn. |
+| `resolveModel(input)` | string or undefined | Shorthand expansion / passthrough. Returning undefined causes the adapter to omit `--model` and the CLI uses its own default. |
+| `modelLooksFamiliar(model)` | boolean | Heuristic powering the preflight "stale model after CLI switch" warning. |
+| `parseOutput(raw)` | `{ text, usage, sessionId, model }` | Final-event parser. |
+| `parseStreamChunk(line)` | event object or null | Single JSONL line → typed event. |
+| `parseError(rawOutput)` | `{ message, code, retriable }` | Codes: `auth-failure`, `context-limit`, `budget-exceeded`, `crash`, null. |
+| `createStreamConsumer(ctx)` | consumer object | Stream accumulator used by `engine/llm.js`. |
+| `detectPermissionGate`, `getPromptDeliveryMode`, `usesSystemPromptFile`, `classifyFailure` | misc | Adapter-owned policy that engine code reads through accessors instead of branching on `runtime.name`. |
+
+The contract surface is documented inline at the top of `engine/runtimes/claude.js`
+(see the JSDoc block at the start of that file). Keep that block authoritative —
+this table is the human-readable mirror.
+
+## Capability Flags
+
+Engine code branches on flags, never on runtime names. Add a flag whenever a
+real behavioral split appears between adapters.
+
+| Flag | Claude | Copilot | Gates |
+|------|--------|---------|-------|
+| `streaming` | ✓ | ✓ | JSONL events on stdout. |
+| `sessionResume` | ✓ | ✓ | `--resume <id>`. |
+| `midRunSessionId` | ✓ | ✗ | Resumable session ID emitted before the terminal `result` event; when false, steering waits for a checkpoint. |
+| `systemPromptFile` | ✓ | ✗ | sysprompt via `--system-prompt-file` (else inlined into stdin by `buildPrompt`). |
+| `effortLevels` | ✓ | ✓ | `--effort low\|medium\|high\|xhigh`. Copilot maps `'max' → 'xhigh'` inside `resolveModel`/`buildArgs`; Claude leaves `'max'` alone. |
+| `costTracking` | ✓ | ✗ | USD + token counts in the result event. Copilot only emits `premiumRequests`. |
+| `modelShorthands` | ✓ | ✗ | Bare `sonnet`/`opus`/`haiku` accepted. Copilot expects full model IDs (`claude-sonnet-4.5`, `gpt-5.4`). |
+| `modelDiscovery` | ✗ | ✓ | `listModels()` returns a real catalog (Copilot reads `https://api.githubcopilot.com/models`). |
+| `promptViaArg` | ✗ | ✗ | If true, prompt goes via `--prompt <text>` instead of stdin. False on both because Windows ARG_MAX (~32 KB) breaks `-p "<long-prompt>"` outright. |
+| `budgetCap` | ✓ | ✗ | `--max-budget-usd <n>`. |
+| `bareMode` | ✓ | ✗ | `--bare` (suppresses CLAUDE.md auto-discovery). Closest Copilot equivalent is `--no-custom-instructions`, gated separately. |
+| `fallbackModel` | ✓ | ✗ | `--fallback-model <id>` on rate-limit. |
+| `sessionPersistenceControl` | ✓ | ✗ | Engine writes `session.json`. Copilot manages session state internally in `~/.copilot/session-state/`. |
+| `resumePromptCarryover` | ✗ | ✓ | CC resume turns prepend recent visible Q&A in stdin because Copilot's session store is opaque to Minions. |
+| `resumeBookkeepingTurn` | ✓ | — | Claude CLI injects a synthetic "Continue from where you left off." meta turn on `--resume`; CC prompts must tell the model not to treat it as user intent. |
+| `streamConsumer` | ✓ | ✓ | Adapter implements `createStreamConsumer(ctx)` — required by `engine/llm.js` accumulator. |
+
+When a behavior is genuinely uniform across all current adapters, it still gets
+a flag if a future runtime might disagree — flags are cheap.
+
+## CC vs Agent Runtime Independence
+
+Command Center (CC) / doc-chat and the agent fleet are two **independent**
+runtime paths. Setting `engine.ccCli: copilot` for CC alone must NOT switch the
+agent fleet to Copilot, and vice versa. Both paths fall through to
+`engine.defaultCli` (the fleet-wide default), but they never see each other's
+overrides.
+
+Six helpers in `engine/shared.js` are the single source of truth for runtime/model
+resolution. Engine code MUST go through them instead of reading config keys
+directly.
+
+| Helper | Chain |
+|--------|-------|
+| `resolveAgentCli(agent, engine)` | `agent.cli` → `engine.defaultCli` → `'claude'` |
+| `resolveCcCli(engine)` | `engine.ccCli` → `engine.defaultCli` → `'claude'` |
+| `resolveAgentModel(agent, engine)` | `agent.model` → `engine.defaultModel` → undefined |
+| `resolveCcModel(engine)` | `engine.ccModel` → `engine.defaultModel` → undefined |
+| `resolveAgentMaxBudget(agent, engine)` | `agent.maxBudgetUsd` → `engine.maxBudgetUsd`. Honors literal `0`. |
+| `resolveAgentBareMode(agent, engine)` | `agent.bareMode` → `engine.claudeBareMode` → false. Strict null check so per-agent `false` overrides engine `true`. |
+
+Agent dispatch resolves the runtime once at spawn time:
+
+```js
+// engine.js spawnAgent (~line 1158)
+const runtime = resolveRuntime(shared.resolveAgentCli(agentConfig, engineConfig));
+```
+
+CC / doc-chat resolves the runtime via `engine/llm.js` `_resolveRuntimeFor()`:
+
+```js
+// engine/llm.js (~line 247)
+if (!runtimeName && callOpts.engineConfig) runtimeName = resolveCcCli(callOpts.engineConfig);
+```
+
+Tests in `test/unit/runtime-fleet-helpers.test.js` enforce that
+`resolveAgentCli` does NOT fall through to `engine.ccCli` and that `resolveCcCli`
+does NOT inspect any agent settings.
+
+## `--cli` / `--model` / `--effort` Knobs
+
+Three CLI flags switch the fleet without dashboard interaction. They forward
+through `engine/cli.js` `parseRuntimeFleetFlags()` and persist into `config.json`.
+
+| Flag | Persists to | Notes |
+|------|-------------|-------|
+| `--cli <runtime>` | `engine.defaultCli` | Validated against the runtime registry; unknown runtimes exit non-zero with the registered list. Implicitly clears any explicit `engine.ccCli` (with a warning naming the prior value). |
+| `--model <id>` | `engine.defaultModel` | Empty-string sentinel (`--model ''`) **deletes** `engine.defaultModel` — never pin to a literal empty string. Compatibility with `defaultCli` is checked; mismatch emits an incompatibility warning suggesting `--model ''`. |
+| `--effort <level>` | dispatched as `opts.effort` | One of `low|medium|high|xhigh`. Copilot maps `'max' → 'xhigh'`; Claude passes `'max'` through unchanged. Capability-gated by `effortLevels`. |
+
+Examples:
+
+```bash
+minions start --cli copilot --model claude-sonnet-4.5
+minions restart --cli claude --model ''     # '' DELETES defaultModel
+minions config set-cli copilot --model gpt-5.4
+```
+
+Inside the adapters, `buildArgs(opts)` translates the resolved values into the
+CLI-specific argv:
+
+```js
+// engine/runtimes/copilot.js buildArgs
+if (model) args.push('--model', String(model));
+if (mappedEffort) args.push('--effort', mappedEffort);
+```
+
+When `resolveAgentModel` returns undefined the adapter omits `--model` from
+`buildArgs` entirely and the underlying CLI uses its own default.
+
+## Per-Runtime Skill Roots
+
+Skills live in runtime-native directories so a skill placed there is genuinely
+visible to that runtime when invoked outside Minions. The adapter's
+`getSkillRoots()` and `getSkillWriteTargets()` are the discovery and write
+contracts.
+
+| Adapter | Personal skill root | Project skill roots | Auto-extraction write targets |
+|---------|---------------------|---------------------|-------------------------------|
+| Claude  | `~/.claude/skills`  | `<repo>/.claude/skills` | personal: `~/.claude/skills`; project: `<repo>/.claude/skills` |
+| Copilot | `~/.copilot/skills` (+ `~/.agents/skills`) | `<repo>/.github/skills`, `<repo>/.agents/skills` | personal: `~/.copilot/skills`; project: `<repo>/.github/skills` |
+
+`getUserAssetDirs()` returns the union of runtime-native global roots and is
+passed to spawn as `--add-dir` so spawned agents read the same global assets the
+user sees outside Minions. The cross-runtime portable location
+`~/.agents/skills` is included by every adapter that opts into it (Copilot today;
+add it to new adapters when the runtime can read directly from there).
+
+## The "No Runtime-Name Branching" Rule
+
+The whole point of this layer: **engine code MUST gate behavior on
+`runtime.capabilities.*` flags, not on `runtime.name === 'claude'` comparisons.**
+
+If you find yourself wanting to write `if (runtime.name === 'copilot')` in
+engine code, the correct response is one of:
+
+1. Add a capability flag to the contract and set it on every adapter.
+2. Add a method to the adapter and call it through the runtime object.
+3. Move the special case into the adapter's `buildArgs` / `buildPrompt` /
+   `parseOutput` where it belongs.
+
+Tests in `test/unit/runtime-adapters.test.js` and `test/unit/copilot-adapter.test.js`
+enforce the contract; the source-inspection tests in `test/unit.test.js` look
+for `resolveRuntime(...)` call sites and reject runtime-name comparisons in new
+code.
+
+## Adding a New Runtime
+
+1. Create `engine/runtimes/<name>.js` implementing the full adapter contract.
+   Copy `claude.js` as the template and override only the members that differ.
+   Set a useful `installHint`.
+2. Register it in `engine/runtimes/index.js`:
+   ```js
+   registry.set('<name>', require('./<name>'));
+   ```
+3. Add unit coverage modeled on `test/unit/runtime-adapters.test.js`.
+
+Once registered, the dashboard `/api/runtimes` endpoint, the `--cli` flag
+validator, the agent CLI dropdown, the `engine/preflight.js` per-runtime binary
+check, and the model discovery cache all light up automatically. Use capability
+flags — never special-case in engine code.
+
+## See Also
+
+- `CLAUDE.md` → "Runtime Adapters" section — short reference table that mirrors
+  this doc and is enforced by `test/unit.test.js`.
+- `docs/copilot-cli-schema.md` — empirical Copilot CLI behavior captured during
+  the spike that produced the Copilot adapter; cite it when changing
+  Copilot-specific capability flags.
+- `engine/runtimes/claude.js` JSDoc header — authoritative adapter contract.
+- `engine/shared.js` `resolveAgentCli` / `resolveCcCli` etc. — the only
+  supported way to read runtime / model selection from config.

package/docs/team-memory.md

@@ -0,0 +1,116 @@
+# Team Memory
+
+Minions agents share knowledge through a layered memory system. Before an agent does any independent research — web searches, broad codebase exploration, external doc reading — it is expected to check what the team already knows.
+
+This document describes the four-tier read order the engine enforces in dispatch prompts, the rationale, and the constraint that `knowledge/` is **sweep-write-only**.
+
+## Why team memory exists
+
+Multiple agents work the same repository in parallel and across days. Without shared memory:
+
+- Agents re-research the same questions (cost, time, context churn).
+- Agents re-litigate decisions the team already made (drift, regressions).
+- Human-flagged warnings (e.g., "do not self-approve PRs") get ignored because they live outside the prompt.
+
+Team memory closes the loop. The engine injects pinned context and recent team notes into every dispatch prompt automatically, and the playbooks instruct agents to consult `knowledge/` and `notes/inbox/` on disk before going wider. This keeps work cheap, decisions sticky, and prior learnings reusable.
+
+## The four-tier read order
+
+Every agent prompt (built by `engine/playbook.js`) is rendered with the rule: **check team memory first, then look outside.** The canonical read order (from `playbooks/shared-rules.md`) is:
+
+1. **`pinned.md`** — critical context flagged by the human teammate. **READ FIRST.**
+2. **`knowledge/`** — categorized KB entries written by the consolidation sweep.
+3. **`notes.md`** — consolidated team knowledge, decisions, and rolling context.
+4. **`notes/inbox/`** — recent agent findings not yet consolidated.
+
+Agents are also encouraged, after the four primary tiers, to skim `agents/*/live-output.log` for related tasks and the `resultSummary` of prior completed work items on the same topic. Only after exhausting team memory should an agent fall back to web search, broad codebase exploration, or external docs.
+
+### 1. `pinned.md` — human-flagged critical context
+
+`pinned.md` lives at the Minions root (`MINIONS_DIR/pinned.md`). It holds notes the human teammate has explicitly pinned through the dashboard — short, high-signal rules and warnings that **must** be visible to every agent on every dispatch.
+
+The engine injects the file verbatim into the prompt under a "Pinned Context (CRITICAL — READ FIRST)" heading and caps it at 4 KB to protect the prompt budget.
+
+Typical contents include credential constraints (e.g., shared `gh` auth means PR self-approval is blocked), workflow policies (e.g., merging policy, TDD requirement), and active setup state. If pinned context contradicts a playbook instruction, pinned context wins for the duration of the dispatch.
+
+### 2. `knowledge/` — categorized KB entries (sweep-write-only)
+
+`knowledge/` is the long-form team knowledge base. Files are grouped by category:
+
+- `knowledge/architecture/` — design decisions, system overviews
+- `knowledge/conventions/` — coding patterns, repo norms, standards
+- `knowledge/project-notes/` — per-project context and observations
+- `knowledge/build-reports/` — CI/build investigation results
+- `knowledge/reviews/` — PR review findings and rationale
+- `knowledge/agents/<agentId>.md` — per-agent personal memory (curated by the sweep)
+
+Filenames follow the `YYYY-MM-DD-<agent>-<slug>.md` convention so chronological sorting just works.
+
+Agents read `knowledge/` directly with grep/glob/view. They **do not** write to it. See [Sweep-write-only constraint](#sweep-write-only-constraint) below.
+
+### 3. `notes.md` — consolidated team notes
+
+`notes.md` is the rolling team notebook. The consolidation sweep periodically merges high-signal findings from the inbox into dated `### YYYY-MM-DD` sections at the top of `notes.md`, with links back to the underlying KB entries.
+
+The engine injects `notes.md` into every prompt under a "Team Notes (MUST READ)" heading. When the file exceeds `ENGINE_DEFAULTS.maxNotesPromptBytes`, the engine keeps the most recent 10 sections, truncates the body, and appends a footer noting how many older sections live on disk so agents can read the full file when they need depth.
+
+### 4. `notes/inbox/` — fresh agent findings
+
+`notes/inbox/` holds the freshest, un-consolidated learnings. Every agent writes exactly one inbox file at the end of a successful task to a path the playbook supplies (`notes/inbox/<agent>-<work-item-id>-<date>-<time>.md`). The file always begins with a YAML frontmatter block (`id`, `agent`, `date`) so the consolidation sweep can track it.
+
+Inbox notes are the canonical place to record:
+
+- New patterns or conventions discovered while implementing.
+- Gotchas, warnings, or repro recipes for future agents.
+- File-and-line citations supporting any claims.
+
+The consolidation sweep is what eventually promotes inbox notes into `knowledge/` and `notes.md`. Until then, agents should grep the inbox themselves for very recent findings on adjacent work.
+
+#### Failure-path exception
+
+Inbox writes are **success artifacts only**. If a task fails, is blocked, is cancelled, or ends partial, the agent must **not** create an inbox note — the failure is reported through the completion JSON, the PR/work-item comment, or the task-specific failure channel instead. This keeps the inbox a clean signal and prevents noise from drowning out durable findings.
+
+## Rationale
+
+The read order is deliberately ordered by **trust × recency**:
+
+- `pinned.md` is human-curated and authoritative — it overrides everything else.
+- `knowledge/` is curated by the sweep from validated agent findings — high-signal but slightly delayed.
+- `notes.md` mirrors `knowledge/` in summarized form, optimized for prompt injection.
+- `notes/inbox/` is raw, recent, and unverified — useful for the freshest context but treat critically.
+
+Following this order achieves two goals:
+
+1. **Avoid re-research.** If another agent already investigated the same module, fix, or design question, the answer is somewhere in this stack. Reading saves a costly round-trip.
+2. **Respect team decisions.** Pinned policies and consolidated conventions encode prior agreement (often with the human). Skipping team memory and acting on first principles is how regressions and drift happen.
+
+## Sweep-write-only constraint
+
+**Agents must never delete, move, or overwrite files in `knowledge/`.** Only the consolidation sweep (`engine/consolidation.js`) writes to `knowledge/`. This rule is restated in every dispatch prompt under a "Knowledge Base Rules" heading.
+
+Why:
+
+- The sweep classifies inbox notes into the right category, generates the canonical filename, and updates the `notes.md` summary in lockstep with the `knowledge/` write. Manual edits skip those side effects and desync the system.
+- Agents work in parallel. Letting any agent rewrite `knowledge/` entries makes consolidation non-deterministic and makes blame attribution impossible.
+- Knowledge base entries are referenced by date-stamped path. Rewriting an entry breaks every existing link.
+
+If an agent thinks a `knowledge/` file is wrong, the correct response is to **note the disagreement in the agent's own inbox file**. The sweep will pick up the note on the next consolidation cycle and either supersede or correct the existing entry.
+
+The same constraint applies to `knowledge/agents/<agentId>.md` — those are curated by the sweep and should not be hand-edited.
+
+## Quick reference for agents
+
+```
+1. pinned.md           ← critical, human-flagged. Read first.
+2. knowledge/          ← categorized KB. Read, never write.
+3. notes.md            ← consolidated team notes. Read.
+4. notes/inbox/        ← fresh, unconsolidated findings. Read; write one on success.
+```
+
+After the four tiers, optionally consult `agents/*/live-output.log` and prior `resultSummary` fields. Only then go outside.
+
+## See also
+
+- `playbooks/shared-rules.md` — the canonical instruction injected into every dispatch.
+- `engine/playbook.js` — where `pinned.md`, `notes.md`, and per-agent memory get spliced into prompts.
+- `engine/consolidation.js` — the sweep that promotes inbox notes into `knowledge/` and `notes.md`.

package/docs/teams-production.md

@@ -1,5 +1,7 @@
 # Teams Production Endpoint Migration
 
+> Last verified: 2026-05-12. `botbuilder` dependency confirmed in `package.json` (4.23.3); `/api/bot` route confirmed in `dashboard.js` (`handleTeamsBot`).
+
 Guide for migrating the Minions Teams bot from a Dev Tunnel to a stable public HTTPS endpoint for production use. Choose one of the three deployment options below based on your infrastructure.
 
 **Key fact:** The Azure Bot messaging endpoint URL can be changed at any time in the Azure Portal — it takes effect immediately. No bot reinstallation is needed in Teams. This means you can switch between Dev Tunnel and production endpoints freely.
@@ -120,7 +122,7 @@ Containerize the dashboard and deploy to Azure Container Apps with a stable FQDN
    CMD ["node", "dashboard.js"]
    ```
 
-   > Minions has zero npm dependencies beyond Node.js built-ins, so `npm ci` may be a no-op. The botbuilder package (added by this feature branch) is the exception.
+   > Minions ships with `botbuilder` as its only runtime dependency (declared in `package.json`); other operations rely on Node.js built-ins, so `npm ci` is a fast install.
 
 2. **Build and push to Azure Container Registry:**
 

package/docs/watches.md

@@ -0,0 +1,201 @@
+# Watches
+
+Persistent monitoring jobs that fire inbox notifications and follow-up actions when a target hits a condition. Watches survive engine restarts and are checked every 3 ticks (~3 minutes by default).
+
+## What a Watch Is
+
+A watch is a small JSON record persisted to `engine/watches.json`. It binds:
+
+| Field        | Purpose                                                                 |
+|--------------|-------------------------------------------------------------------------|
+| `target`     | The thing to watch (PR number, work item id, plan filename, ...)         |
+| `targetType` | Which registered target type (`pr`, `work-item`, `meeting`, ...)         |
+| `condition`  | One of the conditions the target type accepts (e.g. `merged`, `failed`)  |
+| `interval`   | Min ms between checks (default 5min, floor 60s)                          |
+| `notify`     | `'inbox'` writes an inbox alert on trigger (set `'none'` to suppress)    |
+| `owner`      | Inbox owner that receives notifications (`'human'` by default)           |
+| `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)                |
+| `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:103-145`)*.
+
+## Lifecycle (`WATCH_STATUS`)
+
+Defined in `engine/shared.js:1557`:
+
+| 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:305-310`)* |
+
+Pause/resume flips the `status` field via `POST /api/watches/update` *(source: `engine/watches.js:153-178`, `dashboard.js:6400-6412`)*.
+
+## Conditions (`WATCH_CONDITION`)
+
+Defined in `engine/shared.js:1573-1592`. Conditions split into two families:
+
+### Absolute conditions (`WATCH_ABSOLUTE_CONDITIONS`)
+*(source: `engine/shared.js:1595-1599`)*
+
+`merged`, `build-fail`, `build-pass`, `completed`, `failed`, `concluded`, `approved`, `rejected`.
+
+When `stopAfter === 0`, these are **fire-once** — the engine flips the watch to `expired` after the first trigger so a permanently-merged PR doesn't keep notifying *(source: `engine/watches.js:305-310`)*.
+
+### Change-based conditions
+`status-change`, `any`, `new-comments`, `vote-change`, `stage-complete`, `ran`, `enabled`, `disabled`, `activity-change`.
+
+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:262-266`)*.
+
+## Target Types — `TARGET_TYPES` Registry
+
+Target-type behavior in `engine/watches.js` is **data-driven via a registry** *(source: `engine/watches.js:50-72`)*. Each spec must provide:
+
+- `label` — human name shown in dashboard pickers
+- `description` — short help text
+- `conditions` — non-empty array of accepted condition keys (also acts as the per-type allowlist)
+- `fetchEntity(target, state)` — entity-or-null lookup
+- `captureState(entity)` — snapshot used for change-detection diffs
+- `evaluate(condition, entity, prevState, target)` — returns `{ triggered, message }`
+
+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:62-88`)*.
+
+### Built-in target types
+
+The eight built-ins are registered at module load *(source: `engine/watches.js:399-748`)*. Constants live at `engine/shared.js:1563-1572` (`WATCH_TARGET_TYPE`).
+
+| `targetType`  | Target value                         | Conditions                                                                 | Notes |
+|---------------|--------------------------------------|----------------------------------------------------------------------------|-------|
+| `pr`          | PR number, canonical id, or display id | `merged`, `build-fail`, `build-pass`, `status-change`, `any`, `new-comments`, `vote-change` | Reads from `pull-requests.json` for any project; `new-comments` watches `humanFeedback.lastProcessedCommentDate` |
+| `work-item`   | Work item id                         | `completed`, `failed`, `status-change`, `any`                              | `completed` matches `DONE_STATUSES`; `failed` matches `WI_STATUS.FAILED` |
+| `meeting`     | Meeting id                           | `concluded`, `status-change`, `any`                                        | `concluded` fires on terminal status (`completed`, `archived`) |
+| `plan`        | PRD JSON filename or plan id         | `approved`, `rejected`, `completed`, `status-change`, `any`                | Looked up by `_source` (PRD file), `_sourcePlan` (.md), or `id`; uses `PLAN_STATUS` |
+| `schedule`    | Schedule id                          | `ran`, `enabled`, `disabled`, `status-change`, `any`                       | `ran` fires when `lastRun` advances; `enabled`/`disabled` fire on the flip |
+| `pipeline`    | Pipeline id (latest run is tracked)  | `completed`, `failed`, `stage-complete`, `status-change`, `any`            | `failed` covers `PIPELINE_STATUS.FAILED` and `STOPPED`; `stage-complete` only counts within the same `runId` |
+| `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:208-224`)*.
+
+## 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:4480-4538`)*. The engine builds the state object from cached project files + module reads:
+
+```
+{
+  pullRequests, workItems,    // flattened across all projects + central
+  meetings, plans,            // optional — try/catch'd, missing modules give []
+  scheduleRuns, pipelineRuns,
+  dispatch, agents, config,
+}
+```
+
+`checkWatches` walks every active watch and, inside a single `mutateJsonFileLocked` callback *(source: `engine/watches.js:241-345`)*:
+
+1. Skips paused/expired watches and any watch checked within its `interval`.
+2. Captures a baseline `_lastState` on first check (so change conditions have something to diff).
+3. Calls `evaluateWatch(watch, state)`.
+4. On trigger: increments `triggerCount`, sets `last_triggered`, queues an inbox notification (if `notify === 'inbox'`), and snapshots an action task for any configured `watch.action`.
+5. Applies fire-once / `stopAfter` expiration.
+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**: notifications via `writeToInbox`, follow-up actions via `_runActionTask` (`Promise` per action, failures isolated). Each action's result is persisted back onto the watch as `_lastActionResult` in a follow-up locked write *(source: `engine/watches.js:330-377`)*.
+
+## Follow-Up Actions on Trigger
+
+`watch.action` is an optional structured action that runs after the inbox notification fires. Action types live in a sibling registry in `engine/watch-actions.js` and are validated at create/update time *(source: `engine/watches.js:112-115`, `engine/watch-actions.js:50-73`)*. `GET /api/watches/action-types` returns the live list for dashboard pickers.
+
+### Built-in actions
+
+| Action type            | What it does                                                                                  |
+|------------------------|-----------------------------------------------------------------------------------------------|
+| `notify`               | Explicit inbox write; lets you customize `owner`/`body` instead of the default trigger string |
+| `dispatch-work-item`   | Append a new WI to the project (or central) `work-items.json` with `createdBy: "watch:<id>"`  |
+| `run-skill`            | Wrapper around `dispatch-work-item` that asks the agent to run a specific `.claude` skill     |
+| `webhook`              | `http`/`https` request to an arbitrary URL (10s safety timeout, JSON or string body)          |
+| `cancel-work-item`     | Flip a WI to `WI_STATUS.CANCELLED` across all known work-items files                          |
+| `trigger-pipeline`     | Start a new pipeline run (skipped if the pipeline already has an active run)                  |
+| `archive-plan`         | Set PRD `status="archived"` + `archivedAt`                                                    |
+| `resume-plan`          | Set PRD `status=PLAN_STATUS.ACTIVE` and clear `planStale`                                     |
+
+Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js:1605-1616`); handlers in `engine/watch-actions.js:185-464`.
+
+### Templating
+
+Action params support `{{var}}` substitution from the trigger context *(source: `engine/watch-actions.js:83-99`)*. Built-in vars from `buildTriggerContext` *(source: `engine/watch-actions.js:107-154`)*:
+
+- Always: `target`, `targetType`, `condition`, `watchId`, `triggerCount`, `message`
+- All scalar fields from `newState` (e.g. `status`, `buildStatus`, `reviewStatus`, `lastRun`)
+- Type-specific aliases: `prNumber`, `branch`, `prId`, `prUrl`, `project` (pr); `workItemId`, `workItemTitle`, `project` (work-item); `meetingId`, `meetingTitle` (meeting); `planFile`, `planMd` (plan); `pipelineId`, `runId` (pipeline); `dispatchId` (dispatch); `agentId` (agent)
+
+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:160-178`)*. A bad action never blocks other watches in the same tick, and the failed result is persisted onto the watch as `_lastActionResult` for debugging.
+
+## Dashboard Surface
+
+| Route                          | Method | Handler                       | Purpose                                                                 |
+|--------------------------------|--------|-------------------------------|-------------------------------------------------------------------------|
+| `/watches`                     | GET    | `dashboard/pages/watches.html` | Watches page (sidebar link in `dashboard/layout.html:75`)               |
+| `/api/watches`                 | GET    | `handleWatchesList`           | List all watches                                                        |
+| `/api/watches/target-types`    | GET    | `handleWatchesTargetTypes`    | Live registry from `listTargetTypes()` — used by the create-watch modal |
+| `/api/watches/action-types`    | GET    | `handleWatchesActionTypes`    | Live registry from `listActionTypes()`                                  |
+| `/api/watches`                 | POST   | `handleWatchesCreate`         | Create a watch (body: `target, targetType, condition, interval?, owner?, description?, project?, notify?, stopAfter?, onNotMet?, action?`) |
+| `/api/watches/update`          | POST   | `handleWatchesUpdate`         | Pause/resume/modify (body: `id, status?, interval?, description?, notify?, stopAfter?, onNotMet?, condition?, action?`) |
+| `/api/watches/delete`          | POST   | `handleWatchesDelete`         | Delete (body: `id`)                                                     |
+
+*(source: route table in `dashboard.js:7395-7400`; handlers in `dashboard.js:6370-6422`)*
+
+The watches page is rendered by `dashboard/js/render-watches.js`; the **+ New** button calls `openCreateWatchModal()` which fetches `/api/watches/target-types` and `/api/watches/action-types` to populate the picker dynamically *(source: `dashboard/pages/watches.html:3`, `dashboard/js/render-watches.js:354-414`)*.
+
+The CC state preamble injects a `Watches: <count>` line via `getWatches()` so the chat brain knows how many watches exist *(source: `dashboard.js:1342`)*.
+
+## Command Center Integration
+
+CC creates, pauses, resumes, and deletes watches by calling the REST API directly via its `Bash` tool — the older `===ACTIONS===` `create-watch`/`delete-watch`/`pause-watch`/`resume-watch` actions have been retired *(source: `test/unit.test.js:16976-17008`, `test/unit/watches-module.test.js:673`)*. To use a watch from CC chat, ask it something like:
+
+> "Watch PR 1234 for build-pass and dispatch a verify work-item when it fires."
+
+CC will discover the endpoints from `GET /api/routes` and `POST /api/watches` with the appropriate `targetType`, `condition`, and `action` payload.
+
+## Expected Outputs
+
+When a watch fires:
+
+- `engine/watches.json` entry gets `triggerCount++`, `last_triggered=<ISO>`, `_lastTriggerMessage=<message>`, and a refreshed `_lastState`.
+- An inbox file lands at `notes/inbox/<owner>/watch-<watchId>-<n>.md` (when `notify === 'inbox'`).
+- If `action` is set, a follow-up runs (work item, webhook POST, plan archive, ...) and writes `_lastActionResult` (`{ type, ok, summary, dispatchedItemId?, at }`) back onto the watch.
+- `engine.log.json` gets `Watch triggered: <id> — <message>` and `Watch <id> action <type>: <summary>`.
+
+Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `stopAfter > 0` flips it to `expired` once `triggerCount >= stopAfter`.
+
+## Common Failure Modes
+
+| Symptom                                                                 | Likely cause / debug                                                                 |
+|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
+| 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:262-266`)*. If you see this, suspect manual edits to `watches.json` |
+| 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:297-299`)* |
+| Trigger fires but follow-up `dispatch-work-item` is missing              | Check the engine log for `Watch <id> action <type>: <summary>`. Common reasons: missing `title`, the project's `work-items.json` couldn't be written, or the WI landed in central `work-items.json` 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:334-337`)* |
+| `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick *(source: `engine.js:4484`)*. Inspect `engine/log.json` 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:1557-1616` — `WATCH_STATUS`, `WATCH_TARGET_TYPE`, `WATCH_CONDITION`, `WATCH_ABSOLUTE_CONDITIONS`, `WATCH_ACTION_TYPE` constants
+- `engine/watches.js` — registry, lifecycle, tick integration
+- `engine/watch-actions.js` — action registry and built-in handlers
+- `dashboard/pages/watches.html`, `dashboard/js/render-watches.js` — dashboard UI
+- `test/unit/watches-module.test.js`, `test/unit/watch-actions.test.js` — module-level tests
+- [`auto-discovery.md`](auto-discovery.md) — overall tick cycle context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1883",
+  "version": "0.1.1885",
   "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"

package/playbooks/docs.md

@@ -92,7 +92,7 @@ git commit -m "{{commit_message}}"
 git push -u origin {{branch_name}}
 ```
 
-PR creation is MANDATORY for docs tasks — docs go through the same review flow as code.
+Create the PR for docs tasks — docs go through the same review flow as code.
 Use the appropriate repo-host tooling for PR creation. For Azure DevOps, prefer the
 `az` CLI first and use the ADO MCP only as a fallback.
 

package/playbooks/fix.md

@@ -102,15 +102,4 @@ Your task is complete when each review finding has either been fixed or answered
 
 ## Completion
 
-After finishing, write the JSON completion report described in the shared rules. Also output this structured completion block as a compatibility fallback:
-
-```completion
-status: done | partial | failed
-files_changed: <comma-separated list of key files changed>
-tests: pass | fail | skipped | N/A
-pr: PR-<number> or N/A
-failure_class: N/A
-pending: <any remaining work, or none>
-```
-
-Replace the values with your actual results.
+After finishing, write the JSON completion report described in the shared rules (schema: `docs/completion-reports.md`). A fenced ` ```completion ` block in stdout is accepted only as a compatibility fallback — do not duplicate the schema here.

package/playbooks/implement-shared.md

@@ -84,15 +84,4 @@ Your task is complete when the requested implementation is delivered, the valida
 
 ## Completion
 
-After finishing, write the JSON completion report described in the shared rules. Also output this structured completion block as a compatibility fallback:
-
-```completion
-status: done | partial | failed
-files_changed: <comma-separated list of key files changed>
-tests: pass | fail | skipped | N/A
-pr: N/A
-failure_class: N/A
-pending: <any remaining work, or none>
-```
-
-Replace the values with your actual results.
+After finishing, write the JSON completion report described in the shared rules (schema: `docs/completion-reports.md`). A fenced ` ```completion ` block in stdout is accepted only as a compatibility fallback — do not duplicate the schema here.

package/playbooks/implement.md

@@ -83,12 +83,12 @@ git push -u origin {{branch_name}}
 
 {{pr_create_instructions}}
 
-PR creation is MANDATORY for implement tasks because the engine tracks review and completion from the PR.
+Create the PR for implement tasks — the engine tracks review and completion from the PR.
 
 Include build/test status and run instructions in the PR description. If the project has a runnable app, include the localhost URL.
 
 ## When to Stop
 
-Your task is complete when the requested implementation is delivered, the validation story is truthful and sufficient for review, the branch is pushed, and the PR exists. Your final message MUST include the PR URL so the engine can track it.
+Your task is complete when the requested implementation is delivered, the validation story is truthful and sufficient for review, the branch is pushed, and the PR exists. Include the PR URL in your final message so the engine can track it.
 
 Do NOT run `gh pr merge` or any other merge command on your own PR. The engine reviews and merges PRs through a separate review cycle. Self-merging is prohibited.