@yemi33/minions 0.1.1884 → 0.1.1886

package/README.md

@@ -6,6 +6,8 @@ Zero dependencies — uses only Node.js built-in modules.
 
 Inspired by and initially scaffolded from [Brady Gaster's Squad](https://bradygaster.github.io/squad/).
 
+📚 **Documentation:** see [docs/README.md](docs/README.md) for the full audience-grouped docs index.
+
 ## Prerequisites
 
 - **Node.js** 18+ (LTS recommended)
@@ -40,6 +42,41 @@ git clone https://github.com/yemi33/minions.git ~/.minions
 node ~/.minions/minions.js init
 ```
 
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `minions init` | Bootstrap `~/.minions/` with default agents and config |
+| `minions update` | Update to latest version (npm update + apply) |
+| `minions version` | Show installed vs package version |
+| `minions doctor` | Check prerequisites and runtime health |
+| `minions scan [dir] [depth]` | Scan for git repos and multi-select to add (default: ~, depth 3) |
+| `minions add <dir>` | Link a single project (auto-detects settings from git, prompts to confirm) |
+| `minions remove <dir-or-name> [--keep-data \| --purge --force]` | Unlink a project: cancels pending work items, drains dispatch + kills active agents, cleans worktrees, disables linked schedules, archives `projects/<name>/` to `projects/.archived/<name>-YYYYMMDD/`. Use `--keep-data` to leave the data dir in place, or `--purge --force` to delete it. |
+| `minions list` | List all linked projects with descriptions |
+| `minions restart` | Start engine and dashboard together (recommended after reboot) |
+| `minions start` | Start engine daemon (ticks every 60s, auto-syncs MCP servers) |
+| `minions stop` | Stop the engine |
+| `minions status` | Show agents, projects, dispatch queue, quality metrics |
+| `minions pause` / `resume` | Pause/resume dispatching |
+| `minions dispatch` | Force a dispatch cycle |
+| `minions discover` | Dry-run work discovery |
+| `minions queue` | Show dispatch queue (pending, active, completed) |
+| `minions sources` | Show work source status per project |
+| `minions work <title> [opts]` | Add to central work queue |
+| `minions spawn <agent> <prompt>` | Manually spawn an agent |
+| `minions plan <file\|text> [proj]` | Run a plan |
+| `minions kill` | Kill all active agents and reset their dispatches to pending |
+| `minions complete <dispatch-id>` | Manually mark a dispatch as completed |
+| `minions config set-cli <R> [--model M]` | Persist the default runtime/model without starting the engine |
+| `minions mcp-sync` | Sync MCP servers from `~/.claude.json` |
+| `minions cleanup` | Run cleanup manually (temp files, worktrees, zombies) |
+| `minions dash` | Open dashboard (starts if not already running, port 7331) |
+| `minions nuke --confirm` | Factory reset runtime state and reset config to defaults |
+| `minions uninstall --confirm` | Remove Minions state and uninstall the npm package |
+
+You can also run scripts directly: `node ~/.minions/engine.js start`, `node ~/.minions/dashboard.js`, etc.
+
 ## Upgrading
 
 ```bash
@@ -64,6 +101,8 @@ minions init --force
 
 ## Quick Start
 
+> **New contributor?** Walk through [docs/onboarding.md](docs/onboarding.md) first — an 8-step, first-30-minutes guide from clone → doctor → init → add → dashboard tour → first dispatch → first plan → first PR review, with debugging pointers.
+
 ```bash
 # 1. Init + scan — finds all git repos on your machine, multi-select to add
 minions init
@@ -120,41 +159,6 @@ To give the minions its first task, open the dashboard Command Center and add a
 minions work "Explore the codebase and document the architecture"
 ```
 
-## CLI Reference
-
-| Command | Description |
-|---------|-------------|
-| `minions init` | Bootstrap `~/.minions/` with default agents and config |
-| `minions update` | Update to latest version (npm update + apply) |
-| `minions version` | Show installed vs package version |
-| `minions doctor` | Check prerequisites and runtime health |
-| `minions scan [dir] [depth]` | Scan for git repos and multi-select to add (default: ~, depth 3) |
-| `minions add <dir>` | Link a single project (auto-detects settings from git, prompts to confirm) |
-| `minions remove <dir-or-name> [--keep-data \| --purge --force]` | Unlink a project: cancels pending work items, drains dispatch + kills active agents, cleans worktrees, disables linked schedules, archives `projects/<name>/` to `projects/.archived/<name>-YYYYMMDD/`. Use `--keep-data` to leave the data dir in place, or `--purge --force` to delete it. |
-| `minions list` | List all linked projects with descriptions |
-| `minions restart` | Start engine and dashboard together (recommended after reboot) |
-| `minions start` | Start engine daemon (ticks every 60s, auto-syncs MCP servers) |
-| `minions stop` | Stop the engine |
-| `minions status` | Show agents, projects, dispatch queue, quality metrics |
-| `minions pause` / `resume` | Pause/resume dispatching |
-| `minions dispatch` | Force a dispatch cycle |
-| `minions discover` | Dry-run work discovery |
-| `minions queue` | Show dispatch queue (pending, active, completed) |
-| `minions sources` | Show work source status per project |
-| `minions work <title> [opts]` | Add to central work queue |
-| `minions spawn <agent> <prompt>` | Manually spawn an agent |
-| `minions plan <file\|text> [proj]` | Run a plan |
-| `minions kill` | Kill all active agents and reset their dispatches to pending |
-| `minions complete <dispatch-id>` | Manually mark a dispatch as completed |
-| `minions config set-cli <R> [--model M]` | Persist the default runtime/model without starting the engine |
-| `minions mcp-sync` | Sync MCP servers from `~/.claude.json` |
-| `minions cleanup` | Run cleanup manually (temp files, worktrees, zombies) |
-| `minions dash` | Open dashboard (starts if not already running, port 7331) |
-| `minions nuke --confirm` | Factory reset runtime state and reset config to defaults |
-| `minions uninstall --confirm` | Remove Minions state and uninstall the npm package |
-
-You can also run scripts directly: `node ~/.minions/engine.js start`, `node ~/.minions/dashboard.js`, etc.
-
 ## Architecture
 
 ```
@@ -214,7 +218,7 @@ You can also run scripts directly: `node ~/.minions/engine.js start`, `node ~/.m
 
 - **Auto-discovers work** from plans (`plans/*.json`), pull requests, and work queues across all linked projects
 - **Plan pipeline** — `/plan` spawns a plan agent, chains to plan-to-prd, produces `plans/{project}-{date}.json` with `status: "awaiting-approval"`. Supports shared-branch and parallel strategies.
-- **Human approval gate** — plans require approval before materializing as work items. Dashboard provides Approve / Discuss & Revise / Reject. Discussion launches an interactive Claude Code session.
+- **Human approval gate** — plans require approval before materializing as work items. Dashboard provides Approve / Discuss & Revise / Reject. Discussion launches an interactive Command Center session via the configured runtime CLI (`config.engine.ccCli`).
 - **Dispatches AI agents** (Claude CLI) with full project context, git worktrees, and MCP server access
 - **Routes intelligently** — fixes first, then reviews, then implementation, matched to agent strengths
 - **LLM-powered consolidation** — Claude Haiku summarizes notes (threshold: 5 files). Regex fallback. Source references required.
@@ -649,34 +653,43 @@ To move to a new machine: `npm install -g @yemi33/minions && minions init --forc
     minions.js             <- Unified CLI entry point (npm package)
   minions.js               <- Project management: init, add, remove, list
   engine.js              <- Engine daemon + orchestrator
-  engine/
-    shared.js            <- Shared utilities: IO, process spawning, config helpers
-    queries.js           <- Read-only state queries (used by engine + dashboard)
-    cli.js               <- CLI command handlers (start, stop, status, plan, etc.)
-    lifecycle.js          <- Post-completion hooks, plan chaining, PR sync, metrics
-    consolidation.js     <- Haiku-powered inbox consolidation, knowledge base
-    ado.js               <- ADO token management, PR polling, PR reconciliation
-    llm.js               <- callLLM() with session resume, trackEngineUsage()
-    spawn-agent.js       <- Agent spawn wrapper (resolves claude cli.js)
-    preflight.js         <- Prerequisite checks (Node, Git, Claude CLI, API key)
-    scheduler.js         <- Cron-style scheduled task discovery
-    pipeline.js          <- Multi-stage pipeline orchestration
-    meeting.js           <- Meeting creation, rounds, conclusion
-    cleanup.js           <- Worktree + temp file cleanup
-    timeout.js           <- Agent timeout and orphan detection
-    cooldown.js          <- Dispatch cooldown with exponential backoff
-    github.js            <- GitHub PR polling, comment polling, reconciliation
-    routing.js           <- Agent routing and temp agent management
-    dispatch.js          <- Dispatch queue mutations (add, complete, retry)
-    ado-mcp-wrapper.js   <- ADO MCP authentication wrapper
-    check-status.js      <- Quick status check without full engine load
-    control.json         <- running/paused/stopped (runtime, generated)
-    dispatch.json        <- pending/active/completed queue (runtime, generated)
-    log.json             <- Audit trail, capped at 2500 (runtime, generated)
-    metrics.json         <- Per-agent quality metrics (runtime, generated)
-    cooldowns.json       <- Dispatch cooldown tracking (runtime, generated)
-    schedule-runs.json   <- Last-run timestamps for scheduled tasks (runtime, generated)
-    pipeline-runs.json   <- Pipeline run history per pipeline (runtime, generated)
+  engine/                <- See CLAUDE.md "Key Modules" table for per-file roles
+    # Core orchestration
+    shared.js            queries.js            cli.js
+    lifecycle.js         dispatch.js           cooldown.js
+    timeout.js           steering.js           recovery.js
+    pre-dispatch-eval.js
+    # Discovery, routing, playbooks
+    routing.js           playbook.js           cleanup.js
+    # Knowledge / consolidation
+    consolidation.js     kb-sweep.js
+    # LLM + runtime adapters
+    llm.js               model-discovery.js    spawn-agent.js
+    runtimes/            <- Per-runtime CLI adapters (claude, copilot, etc.)
+    # Lifecycle helpers
+    preflight.js         restart-health.js     scheduler.js
+    pipeline.js          meeting.js
+    # Project + feature management
+    projects.js          project-discovery.js  features.js
+    watches.js           watch-actions.js
+    # Repo-host integrations
+    github.js            issues.js
+    ado.js               ado-token.js          ado-mcp-wrapper.js
+    ado-status.js        check-status.js
+    # Notifications
+    teams.js             teams-cards.js
+    # Runtime state (generated, gitignored)
+    control.json         <- running/paused/stopped
+    dispatch.json        <- pending/active/completed queue
+    log.json             <- audit trail, capped at 2500
+    metrics.json         <- per-agent quality + runtime metrics
+    cooldowns.json       <- dispatch cooldown tracking
+    schedule-runs.json   <- last-run timestamps for scheduled tasks
+    pipeline-runs.json   <- pipeline run history per pipeline
+    watches.json         <- persistent watch jobs
+    completions/         <- per-dispatch agent completion JSON reports
+    <runtime>-caps.json  <- adapter capability cache (claude-caps.json, copilot-caps.json, …)
+    <runtime>-models.json <- adapter model catalog cache
   dashboard.js           <- Web dashboard server
   dashboard/
     layout.html          <- Page layout shell with sidebar navigation
@@ -730,6 +743,7 @@ To move to a new machine: `npm install -g @yemi33/minions && minions init --forc
     inbox/               <- Agent findings drop-box (generated)
     archive/             <- Processed inbox files (generated)
   docs/
+    README.md            <- Docs index (grouped by audience)
     auto-discovery.md    <- Auto-discovery pipeline docs
     self-improvement.md  <- Self-improvement loop docs
     plan-lifecycle.md    <- Full plan pipeline: plan → PRD → implement → verify

package/docs/README.md

@@ -0,0 +1,36 @@
+# Minions Documentation Index
+
+A navigable index of every Markdown file under `docs/`. Entries are grouped by audience.
+
+## User-facing
+
+Hands-on stories and distribution guides for people running or evaluating Minions.
+
+- [blog-first-successful-dispatch.md](blog-first-successful-dispatch.md) — Narrative walkthrough of the first end-to-end agent dispatch and the seven failed spawn attempts that preceded it.
+- [distribution.md](distribution.md) — How Minions is published as the `@yemi33/minions` npm package and what the two-repo (origin / personal) sync strips.
+
+## Contributor-facing
+
+Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
+
+- [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
+- [copilot-cli-schema.md](copilot-cli-schema.md) — Behavior and schema reference for the GitHub Copilot CLI adapter (capability flags, stdin vs `-p`, model discovery, effort levels).
+- [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target.
+- [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
+- [pr-review-fix-loop.md](pr-review-fix-loop.md) — How the engine moves a PR from creation through review, fix dispatch, and re-review, including stale-status guards.
+- [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
+- [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop.
+
+## Operations
+
+Operational runbooks for engine operators, fleet maintainers, and Teams integrators.
+
+- [auto-discovery.md](auto-discovery.md) — Auto-discovery and execution pipeline: the per-tick orchestration loop and the four work-discovery sources.
+- [engine-restart.md](engine-restart.md) — How agents survive an engine restart: state persistence, the 20-minute startup grace period, and orphan reattachment via PID files and `live-output.log`.
+- [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.
+- [teams-production.md](teams-production.md) — Three deployment options (Azure App Service, Container Apps, self-hosted VM) for migrating the Teams bot from a Dev Tunnel to a stable HTTPS endpoint.
+- [teams-setup.md](teams-setup.md) — End-to-end guide for connecting Minions to Microsoft Teams via Azure Bot Framework and a Dev Tunnel.
+
+---
+
+**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/archive/distribution.md

@@ -0,0 +1,97 @@
+# Distribution & Publishing
+
+> **ARCHIVED 2026-05-12.** This document describes a defunct two-repo "personal vs. origin" architecture (`yemishin_microsoft/minions` → `yemi33/minions`) and a manual `/sync-to-personal` workflow that no longer exists. The current model is single-repo: `yemi33/minions` publishes itself to npm via `.github/workflows/publish.yml` on every push to `master`. The doc also incorrectly claims package contents are gated by a `files` field in `package.json` — they are actually gated by `.npmignore`. Kept for historical reference; do not follow these steps.
+
+Minions is distributed as an npm package (`@yemi33/minions`) from a sanitized copy of the main repo.
+
+## Two-Repo Architecture
+
+| Repo | Purpose | What's included |
+|------|---------|----------------|
+| **origin** (`yemishin_microsoft/minions`) | Full working repo with all session state | Everything — history, notes, decisions, work items, CLAUDE.md |
+| **personal** (`yemi33/minions`) | Clean distribution for others | Engine, dashboard, playbooks, charters, skills, docs, npm package files |
+
+## What Gets Stripped
+
+These files are removed during sync to personal:
+
+| Category | Pattern | Reason |
+|----------|---------|--------|
+| Agent history | `agents/*/history.md` | Session-specific task logs |
+| Notes archive | `notes/archive/*` | Historical agent findings |
+| Notes inbox | `notes/inbox/*` | Pending agent findings |
+| Notes summary | `notes.md` | Consolidated knowledge (runtime) |
+| Work items | `work-items.json` | Runtime dispatch tracking |
+| Project instructions | `CLAUDE.md` | Org-specific context |
+
+## npm Package
+
+**Package:** `@yemi33/minions`
+**Registry:** https://www.npmjs.com/package/@yemi33/minions
+
+### What's in the package
+
+Controlled by the `files` field in `package.json`:
+- `bin/minions.js` — CLI entry point
+- `engine.js`, `dashboard.js`, `dashboard/` (fragments), `minions.js` — core scripts
+- `engine/spawn-agent.js`, `engine/ado-mcp-wrapper.js` — engine helpers
+- `agents/*/charter.md` — agent role definitions
+- `playbooks/*.md` — task templates
+- `config.template.json` — starter config
+- `routing.md`, `team.md` — editable team config
+- `skills/`, `docs/` — documentation and workflows
+
+### How `minions init` works
+
+1. Copies all package files from `node_modules/@yemi33/minions/` to `~/.minions/`
+2. Creates `config.json` from `config.template.json` if it doesn't exist
+3. Creates runtime directories (`engine/`, `notes/inbox/`, `notes/archive/`, etc.)
+4. Runs `minions.js init` to populate config with default agents
+5. On `--force`, overwrites `.js` and `.html` files but preserves user-modified `.md` files
+
+### How updates work
+
+- Users run `npm update -g @yemi33/minions` then `minions init --force` to update engine code
+- `npx @yemi33/minions` always fetches the latest version
+
+## Auto-Publishing
+
+A GitHub Action on the personal repo auto-publishes to npm on every push to master.
+
+### How it works
+
+1. Push to `yemi33/minions` master triggers `.github/workflows/publish.yml`
+2. Action queries npm for the current published version
+3. Bumps patch version (e.g., `0.1.5` → `0.1.6`)
+4. Publishes to npm with the new version
+5. Commits the version bump back to the repo with `[skip ci]` to prevent loops
+
+### Why version comes from npm, not the repo
+
+The sync-to-personal workflow force-pushes, which overwrites any version bump commits from previous action runs. So the action reads the latest version from the npm registry and bumps from there.
+
+### Setup requirements
+
+- `NPM_TOKEN` secret on `yemi33/minions` — a granular access token with publish permissions and 2FA bypass enabled
+- The workflow file (`.github/workflows/publish.yml`) is gitignored on the org repo and force-added during sync
+
+## Sync Workflow
+
+Run `/sync-to-personal` or manually:
+
+```bash
+# 1. Create dist branch, strip files, add workflow, force-push
+git checkout -b dist-clean
+git rm --cached agents/*/history.md notes.md work-items.json CLAUDE.md
+git rm -r --cached notes/archive/ notes/inbox/ notes/
+# ... add .gitkeep files, .gitignore entries, workflow file
+git add -f .github/workflows/publish.yml
+git commit -m "Strip for distribution"
+git push personal dist-clean:master --force
+
+# 2. Return to master
+git checkout master
+git branch -D dist-clean
+```
+
+

package/docs/auto-discovery.md

@@ -1,5 +1,7 @@
 # Auto-Discovery & Execution Pipeline
 
+> Last verified: 2026-05-12 against `engine.js` `tickInner()` (lines 4439-4750).
+
 How the minions engine finds work and dispatches agents automatically.
 
 ## The Tick Loop
@@ -8,16 +10,27 @@ The engine runs a tick every 60 seconds (configurable via `config.json` → `eng
 
 ```
 tick()
-  1. checkTimeouts()            Enforce runtime limits and stale-orphan cleanup
-  2. consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
-  2.5 runCleanup()              Periodic cleanup (every 10 ticks ≈ 10min)
-  2.6 pollPrStatus()            Poll ADO + GitHub for build, review, merge status (wall-clock cadence from prPollStatusEvery × tickInterval, default ≈ 12min)
-  2.7 pollPrHumanComments()     Poll PR threads for human @minions comments (wall-clock cadence from prPollCommentsEvery × tickInterval, default ≈ 12min)
-  3. discoverWork()             Scan ALL linked projects for new tasks
-  4. updateSnapshot()           Write identity/now.md
-  5. dispatch                   Spawn agents for pending items (up to maxConcurrent)
+  1.  checkTimeouts()            Enforce runtime limits and stale-orphan cleanup
+  1a. checkSteering()            Drain steering messages queued by the dashboard
+  1b. checkIdleThreshold()       Notify on excessive agent idleness
+  1c. meetingTimeouts()          Advance round-based meetings whose timer fired
+  2.  consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
+  2.5 runCleanup()               Periodic cleanup (every 10 ticks ≈ 10min)
+  2.55 checkWatches()            Persistent watch jobs (every 3 tick-equivalents)
+  2.6 pollPrStatus()             Poll ADO + GitHub for build, review, merge status (wall-clock cadence from prPollStatusEvery × tickInterval, default ≈ 12min)
+       processPendingRebases()   Run any rebase work queued from the previous tick
+       syncPrdFromPrs()          Backfill PRD item status from active PRs
+       checkPlanCompletion()     Mark plans completed when all features done/in-pr
+  2.7 pollPrHumanComments()      Poll PR threads for human @minions comments (wall-clock cadence from prPollCommentsEvery × tickInterval, default ≈ 12min)
+       reconcilePrs() (ADO+GH)   Reconciliation sweep (runs regardless of poll flags)
+  2.9 stallRecovery()            Auto-retry failed items blocking pending deps (every 20 ticks)
+  3.  discoverWork()             Scan ALL linked projects for new tasks
+  4.  updateSnapshot()           Write identity/now.md
+  5.  dispatch                   Spawn agents for pending items (up to maxConcurrent)
 ```
 
+> When `control.state === 'stopping'`, only steps 1–1c run; discovery and dispatch are skipped while live agents drain.
+
 ## Work Discovery
 
 `discoverWork()` iterates every project in `config.projects[]` and runs four core discovery sources: pull requests, per-project work items, central work items, and pipeline/scheduled tasks. Results are prioritized: fixes > reviews > implements > work-items.

package/docs/completion-reports.md

@@ -0,0 +1,215 @@
+# Completion Reports
+
+Every Minions agent ends its dispatch by writing a JSON completion report. The report is the engine's primary, machine-readable signal that the work item is finished and is the source of truth for status, retry decisions, dashboard surfaces, and downstream automation. Fenced ` ```completion ` blocks in stdout are still parsed as a compatibility fallback, but the JSON file always wins when both exist.
+
+This document is the canonical schema. Playbooks should cross-link here instead of restating the field list.
+
+## Where the report is written
+
+The engine injects the absolute path two ways before spawning each agent:
+
+- `MINIONS_COMPLETION_REPORT` environment variable
+- The same path appears in the rendered playbook prompt
+
+Path shape (resolved by `shared.dispatchCompletionReportPath()` in `engine/shared.js`):
+
+```
+<MINIONS_DIR>/engine/completions/<dispatch-id>.json
+```
+
+The agent must write the JSON to that exact path before exiting. Any character outside `[a-zA-Z0-9._-]` in the dispatch id is replaced with `-` by the engine when computing the path.
+
+## Top-level schema
+
+```json
+{
+  "status": "success",
+  "summary": "what changed and how it was validated",
+  "verdict": null,
+  "pr": "PR id/url or N/A",
+  "failure_class": "N/A",
+  "retryable": false,
+  "needs_rerun": false,
+  "noop": false,
+  "artifacts": [
+    {"type": "pr", "path": "https://github.com/owner/repo/pull/123", "title": "PR-123"}
+  ]
+}
+```
+
+### Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `status` | string | One of `success`, `partial`, `failed`. Aliases `done` / `complete` are accepted on read for `success`. The engine refuses to mark a work item done without a status. |
+| `summary` | string | Short prose describing what changed and how it was validated. Truncated to 500 chars in dashboard surfaces (`engine/queries.js`). Do not summarize validation as "tests passed" — name the commands that ran. |
+| `verdict` | string \| null | Required for review tasks: `approved` or `changes-requested`. `null` for non-review tasks. Aliases: `approve`, `request_changes`, `changes_requested`. |
+| `pr` | string | PR URL, `PR-<number>`, or `N/A`. The engine uses this to attach the PR to the work item; missing-PR detection treats anything other than a recognizable URL/PR id as missing unless `noop: true` is set. |
+| `failure_class` | string | One of the `failure_class` enum values below, or `N/A`. Drives retry policy in `engine/dispatch.js` and recovery routing in `engine/recovery.js`. |
+| `retryable` | boolean | `true` if the engine should auto-retry the dispatch on failure. Overrides the default per-class retry policy when present. |
+| `needs_rerun` | boolean | `true` if the same work needs to be re-dispatched (vs. retried). Used by build-fix and review-fix loops. |
+| `artifacts` | array | Durable artifacts the agent created or updated; surfaces in the dashboard work-item detail modal. See [Artifacts](#artifacts). |
+
+### Optional fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `noop` | boolean | Canonical no-op signal. See [No-op semantics](#no-op-semantics). |
+| `noopReason` | string | Human-readable rationale shown when `noop: true`. Falls back to `summary` if absent. |
+| `files_changed` | string \| array | Comma-separated list (or array) of key files changed. |
+| `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
+| `pending` | string | Any remaining work, or `none`. |
+
+## `failure_class` enum
+
+Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated string.
+
+| Value | When to use | Default escalation |
+|---|---|---|
+| `config-error` | CLI not found, exit code 78, malformed config | Never retry |
+| `permission-blocked` | Trust gate, permission denied, auth failure | Never retry |
+| `merge-conflict` | Git merge conflict in worktree or dependency | Retry same agent |
+| `build-failure` | Compilation, lint, or test failure introduced by the agent | Retry same agent |
+| `timeout` | Hard runtime timeout or stale-orphan timeout | Retry with fresh session |
+| `empty-output` | Agent produced no meaningful output | Flag for human review |
+| `spawn-error` | Process failed to start or crashed immediately | Retry with fresh session |
+| `network-error` | API rate limit, DNS, connectivity | Default retry logic |
+| `out-of-context` | Context window exhausted | Flag for human review |
+| `max-turns` | Claude CLI `error_max_turns` — work in progress | Retry same agent |
+| `unknown` | Unclassified failure | Default retry logic |
+
+Use `"N/A"` when `status` is `success` or `partial` without a failure.
+
+## No-op semantics
+
+A no-op completion declares that the agent correctly **declined** to do the work — the change was already shipped on master, the dispatch premise was wrong, the flagged review comment was an author-note, etc.
+
+To signal a no-op:
+
+```json
+{
+  "status": "success",
+  "summary": "PR #2372 Linux CI fix already shipped by parallel agent — nothing to do",
+  "pr": "N/A",
+  "noop": true,
+  "noopReason": "Fix already on master at commit abc1234"
+}
+```
+
+Engine behavior when `noop: true` (`engine/lifecycle.js` `parseCompletionNoop` + `runPostCompletionHooks`):
+
+- The work item is marked `done` with the rationale stored as `_noopReason` (visible in the dashboard).
+- The PR-attachment contract is **skipped**, so an empty `pr` field will not be flagged as a silent failure or auto-retried.
+- Any non-success `status` combined with `noop: true` is treated as a contradiction and falls through to the normal contract.
+
+Without `noop: true`, an empty PR field will be flagged as a missing-PR-attachment failure and auto-retried up to `ENGINE_DEFAULTS.maxRetries` times.
+
+## `retryable` and `needs_rerun`
+
+Both default to `false`. Together they let the agent override the engine's default retry policy:
+
+- `retryable: true` — engine should treat the failure as transient and re-dispatch (subject to `maxRetries` and the per-class escalation policy).
+- `retryable: false` — engine should not auto-retry; the failure is terminal for this dispatch.
+- `needs_rerun: true` — even on `status: success`, the same work item should be re-dispatched (used by review-fix and build-fix loops where one pass cannot complete the work).
+
+When the agent sets either field, it overrides the per-`failure_class` default in `isRetryableFailureReason()` (`engine/dispatch.js`).
+
+## Artifacts
+
+`artifacts` is an array of objects with this shape:
+
+```json
+{"type": "pr", "path": "https://github.com/owner/repo/pull/123", "title": "PR-123: Stale HEAD guard"}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `type` | string | One of `note`, `plan`, `prd`, `pr`, `file`. |
+| `path` | string | Relative repo path, absolute path, or URL. |
+| `title` | string | Short label used in the dashboard list. |
+
+The dashboard caps the rendered list at 20 artifacts per report (`engine/queries.js`). Include every durable artifact you created or updated — PRs, plan/PRD files, key source files, inbox notes — so the work-item detail modal can show them.
+
+## Validation and source-of-truth precedence
+
+The engine reads completion signals in this order (`engine/lifecycle.js`):
+
+1. The JSON report at `MINIONS_COMPLETION_REPORT` — primary.
+2. A fenced ` ```completion ` block in the agent's stdout — fallback only.
+3. Process exit code and stdout heuristics — last-resort recovery.
+
+If the JSON report exists and is well-formed, the engine ignores the fenced block. If the JSON is missing or malformed (logged as a warning), the engine falls back to the fenced block, then to stdout parsing.
+
+## Examples
+
+### Successful implement
+
+```json
+{
+  "status": "success",
+  "summary": "Added stale-HEAD guard to push step in spawn-agent.js; verified with new unit test test/unit/spawn-agent.test.js (4632 passed, 0 failed)",
+  "verdict": null,
+  "pr": "https://github.com/yemi33/minions/pull/2360",
+  "failure_class": "N/A",
+  "retryable": false,
+  "needs_rerun": false,
+  "artifacts": [
+    {"type": "pr", "path": "https://github.com/yemi33/minions/pull/2360", "title": "PR-2360"},
+    {"type": "file", "path": "engine/spawn-agent.js", "title": "Stale-HEAD guard"},
+    {"type": "file", "path": "test/unit/spawn-agent.test.js", "title": "New unit test"}
+  ]
+}
+```
+
+### Successful review
+
+```json
+{
+  "status": "success",
+  "summary": "Verified completeRun sweep is inside mutateJsonFileLocked callback and pre-existing terminal stages are preserved.",
+  "verdict": "approved",
+  "pr": "https://github.com/yemi33/minions/pull/2313",
+  "failure_class": "N/A",
+  "retryable": false,
+  "needs_rerun": false,
+  "artifacts": [
+    {"type": "pr", "path": "https://github.com/yemi33/minions/pull/2313", "title": "PR-2313"}
+  ]
+}
+```
+
+### Failed build
+
+```json
+{
+  "status": "failed",
+  "summary": "test/unit.test.js — c-c-multi-tab.test.js:409 fails on stale _joinCcPromptParts 4-arg signature; needs master rebase.",
+  "verdict": null,
+  "pr": "N/A",
+  "failure_class": "build-failure",
+  "retryable": true,
+  "needs_rerun": false,
+  "artifacts": []
+}
+```
+
+### No-op
+
+```json
+{
+  "status": "success",
+  "summary": "Fix already shipped on master at commit eb2e7230 by parallel agent.",
+  "pr": "N/A",
+  "noop": true,
+  "noopReason": "Linux CI fix already on master before this dispatch started"
+}
+```
+
+## Related
+
+- `engine/shared.js` — `FAILURE_CLASS`, `COMPLETION_FIELDS`, `dispatchCompletionReportPath()`
+- `engine/lifecycle.js` — `parseCompletionReportFile()`, `parseCompletionNoop()`, `enforcePrAttachmentContract()`
+- `engine/dispatch.js` — `isRetryableFailureReason()`, `writeFailedAgentReport()`
+- `engine/recovery.js` — per-`failure_class` recovery recipes
+- `docs/rfc-completion-json.md` — original RFC describing the protocol's design
+- `playbooks/shared-rules.md` — the per-task "Completion Reports" instruction every playbook inherits

package/docs/distribution.md

@@ -1,17 +1,17 @@
 # Distribution & Publishing
 
-Minions is distributed as an npm package (`@yemi33/minions`) from a sanitized copy of the main repo.
+Minions is distributed as an npm package (`@yemi33/minions`) from a sanitized package boundary.
 
-## Two-Repo Architecture
+## Distribution Boundary
 
-| Repo | Purpose | What's included |
+| Surface | Purpose | What's included |
 |------|---------|----------------|
-| **origin** (`yemishin_microsoft/minions`) | Full working repo with all session state | Everything — history, notes, decisions, work items, CLAUDE.md |
-| **personal** (`yemi33/minions`) | Clean distribution for others | Engine, dashboard, playbooks, charters, skills, docs, npm package files |
+| **source repository** | Private development and automation | Working code, project history, and release workflows |
+| **npm package** (`@yemi33/minions`) | Public installation for users | Engine, dashboard, playbooks, charters, skills, docs, and package files |
 
 ## What Gets Stripped
 
-These files are removed during sync to personal:
+These files are excluded from published packages:
 
 | Category | Pattern | Reason |
 |----------|---------|--------|
@@ -71,25 +71,9 @@ The sync-to-personal workflow force-pushes, which overwrites any version bump co
 ### Setup requirements
 
 - `NPM_TOKEN` secret on `yemi33/minions` — a granular access token with publish permissions and 2FA bypass enabled
-- The workflow file (`.github/workflows/publish.yml`) is gitignored on the org repo and force-added during sync
+- The workflow file (`.github/workflows/publish.yml`) is not included in the npm package
 
 ## Sync Workflow
 
-Run `/sync-to-personal` or manually:
-
-```bash
-# 1. Create dist branch, strip files, add workflow, force-push
-git checkout -b dist-clean
-git rm --cached agents/*/history.md notes.md work-items.json CLAUDE.md
-git rm -r --cached notes/archive/ notes/inbox/ notes/
-# ... add .gitkeep files, .gitignore entries, workflow file
-git add -f .github/workflows/publish.yml
-git commit -m "Strip for distribution"
-git push personal dist-clean:master --force
-
-# 2. Return to master
-git checkout master
-git branch -D dist-clean
-```
-
+Repository and package publishing automation should keep private repository names, tokens, runtime state, and internal-only metadata out of public docs and public package contents.
 

package/docs/engine-restart.md

@@ -1,5 +1,7 @@
 # Engine Restart & Agent Survival
 
+> Last verified: 2026-05-12 against `engine.js` (`engineRestartGraceUntil`, line 161) and `engine/shared.js` `ENGINE_DEFAULTS` (`restartGracePeriod: 1200000`, `heartbeatTimeout: 300000`, `agentTimeout: 18000000`).
+
 ## The Problem
 
 When the engine restarts, it loses its in-memory process handles (`activeProcesses` Map). Claude CLI agents spawned before the restart may still be running as OS processes, but the engine can't monitor their process state, detect exit codes, or manage their lifecycle. Stale-orphan detection keeps these dispatch records from staying active forever after the restart grace period expires.