@yemi33/minions 0.1.2220 → 0.1.2222

package/dashboard/js/refresh.js

@@ -136,7 +136,7 @@ const RENDER_VERSIONS = {
   inbox: 2,
   projects: 3,
   notes: 1,
-  prd: 2,
+  prd: 3,
   prs: 3,
   archivedPrds: 1,
   engine: 4,

package/dashboard/js/render-prd.js

@@ -143,9 +143,19 @@ function renderPrd(prd, prog) {
   section.innerHTML = '';
 }
 
+// Color a PR status for the PRD page pills/glyphs: merged -> green,
+// abandoned/closed (any terminal-non-merged) -> red, active/other -> neutral
+// default text color (no accent highlight).
+function _prStatusColor(status) {
+  if (status === 'merged') return 'var(--green)';
+  if (!status || status === 'active') return 'var(--text)';
+  return 'var(--red)';
+}
+
 function _renderPrLink(pr, opts) {
   var size = (opts && opts.size) || '10px';
   var statusIcon = pr.status === 'merged' ? '✓' : pr.status === 'abandoned' ? '✗' : '○';
+  var iconColor = _prStatusColor(pr.status);
   // P-79b47b0c — render as an in-stack modal chip via renderArtifactLink
   // (was a raw <a target="_blank">). The status icon stays as a non-link
   // prefix so the chip body remains the canonical id, matching the WI/PRD
@@ -154,7 +164,7 @@ function _renderPrLink(pr, opts) {
     ? renderArtifactLink({ type: 'pr', id: pr.id, label: pr.id, title: (pr.title || '') + ' (' + (pr.status || 'active') + ')' })
     : '<code>' + escHtml(pr.id) + '</code>';
   return '<span style="font-size:' + size + ';margin-left:4px;display:inline-flex;align-items:center;gap:3px">' +
-    '<span title="' + escHtml(pr.status || 'active') + '">' + statusIcon + '</span>' + chip + '</span>';
+    '<span style="color:' + iconColor + '" title="' + escHtml(pr.status || 'active') + '">' + statusIcon + '</span>' + chip + '</span>';
 }
 
 function _renderPrdWorkItemIdBadge(workItemId, prdItemId, size, padding) {
@@ -621,7 +631,7 @@ function renderPrdProgress(prog) {
     if (prs.length > 0) {
       html += '<div style="font-size:var(--text-sm);font-weight:600;color:var(--blue);margin-bottom:4px">E2E Aggregate PRs</div>';
       html += prs.map(pr => {
-        const statusColor = pr.status === 'active' ? 'var(--green)' : pr.status === 'merged' ? 'var(--purple)' : 'var(--muted)';
+        const statusColor = _prStatusColor(pr.status);
         // P-79b47b0c — render PR id as in-stack chip (was raw <a target="_blank">).
         const prChip = (typeof renderArtifactLink === 'function')
           ? renderArtifactLink({ type: 'pr', id: pr.id, label: pr.id, title: pr.title || pr.id })

package/dashboard/js/settings.js

@@ -70,7 +70,7 @@ async function openSettings() {
     return '<tr>' +
       '<td style="font-weight:600">' + escHtml(a.emoji || '') + ' ' + escHtml(a.name || id) + '</td>' +
       '<td><input data-agent="' + escHtml(id) + '" data-field="role" value="' + escHtml(a.role || '') + '" style="width:100%;padding:4px 6px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-size:var(--text-base)"></td>' +
-      '<td><input data-agent="' + escHtml(id) + '" data-field="skills" value="' + escHtml((a.skills || []).join(', ')) + '" style="width:100%;padding:4px 6px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-size:var(--text-base)"></td>' +
+      '<td><input data-agent="' + escHtml(id) + '" data-field="expertise" value="' + escHtml((a.expertise || []).join(', ')) + '" style="width:100%;padding:4px 6px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-size:var(--text-base)"></td>' +
       '<td data-runtime-cli="' + escHtml(id) + '" style="min-width:110px">' +
         // Initial loading placeholder — initRuntimeFleetUI() replaces this with a
         // <select> populated from /api/runtimes once the registry resolves.
@@ -379,6 +379,7 @@ async function openSettings() {
       settingsField('Worktree Root', 'set-worktreeRoot', e.worktreeRoot || '../worktrees', '', 'Relative or absolute path for git worktrees; on Windows prefer a short path like C:\\wt') +
       settingsField('Assert-Clean Status Probe Timeout', 'set-assertCleanStatusTimeoutMs', e.assertCleanStatusTimeoutMs || 10000, 'ms', 'Timeout for the `git status --porcelain` preflight probe in assertCleanSharedWorktree. Raise this (e.g. 60000) on GVFS/Plastic-backed monorepos where sparse hydration runs longer than the 10s default. On timeout the engine quarantines the bad worktree and emits a RETRYABLE failure so the next dispatch starts fresh. Clamped 1000–120000ms.') +
       settingsField('Orphan-holder scan timeout', 'set-orphanHolderScanTimeoutMs', e.orphanHolderScanTimeoutMs || 5000, 'ms', 'Cap on the cross-platform scan (PowerShell / /proc walk / lsof) that identifies the OS process holding a stuck worktree\'s cwd. Bumps up only matter on heavily-loaded hosts where the holder scan races the sweep tick. Clamped 1000–30000ms.') +
+      settingsField('Worktree-holder reap probe timeout', 'set-statusProbeKillTimeoutMs', e.statusProbeKillTimeoutMs || 12000, 'ms', 'Windows-only. Timeout for the pre-quarantine worktree-holder reap probe (legacy git.exe-cmdline sweep + PEB-CWD scan that kills an orphaned agent process tree whose CWD pins the worktree dir, causing EBUSY on rename AND `git worktree remove --force`). The old hardcoded 2000ms was the proximate cause of the reaper being a no-op under concurrent-agent load (PowerShell cold-start + process enumeration exceeded 2s → ETIMEDOUT → reaped nothing). ETIMEDOUT is always swallowed (reap nothing; quarantine still proceeds), so raising this only widens the success window. Clamped 2000–60000ms.') +
     '</div>';
 
   const paneCopilot =
@@ -998,6 +999,7 @@ async function saveSettings() {
       ccUseWorkerPool: !!document.getElementById('set-ccUseWorkerPool')?.checked,
       autoReapOrphanWorktreeHolders: !!document.getElementById('set-autoReapOrphanWorktreeHolders')?.checked,
       orphanHolderScanTimeoutMs: document.getElementById('set-orphanHolderScanTimeoutMs')?.value,
+      statusProbeKillTimeoutMs: document.getElementById('set-statusProbeKillTimeoutMs')?.value,
       adoPollEnabled: document.getElementById('set-adoPollEnabled').checked,
       ghPollEnabled: document.getElementById('set-ghPollEnabled').checked,
       pollingPaused: document.getElementById('set-pollingPaused').checked,

package/dashboard.js

@@ -10437,6 +10437,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // 30s ceiling (the scan runs once per orphan-sweep tick and a slow
           // scan must not block the rest of the sweep for minutes).
           orphanHolderScanTimeoutMs: [1000, 30000],
+          // W-mqila0t5 — Windows worktree-holder reap probe timeout. 2s floor
+          // (PowerShell cold-start + PEB enumeration needs headroom; the old
+          // 2000ms hardcode was the no-op bug); 60s ceiling (the reap runs once
+          // on the quarantine path and ETIMEDOUT is swallowed, so a long probe
+          // never wedges dispatch — it just falls through to force-remove).
+          statusProbeKillTimeoutMs: [2000, 60000],
           idleAlertMinutes: [1], shutdownTimeout: [30000], restartGracePeriod: [60000],
           meetingRoundTimeout: [60000],
           // W-mq066js7000fff1f-c (Gap B/C): steering safety-net knobs.
@@ -10678,7 +10684,15 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         for (const [id, updates] of Object.entries(body.agents)) {
           if (!config.agents[id]) continue;
           if (updates.role !== undefined) config.agents[id].role = String(updates.role);
-          if (updates.skills !== undefined) config.agents[id].skills = Array.isArray(updates.skills) ? updates.skills : String(updates.skills).split(',').map(s => s.trim()).filter(Boolean);
+          // Descriptive capability tags. Field renamed `skills` -> `expertise`
+          // (issue: name collision with executable runtime skills). Accept the
+          // legacy `skills` key from older clients and persist as `expertise`.
+          const expertiseUpdate = updates.expertise !== undefined ? updates.expertise
+            : (updates.skills !== undefined ? updates.skills : undefined);
+          if (expertiseUpdate !== undefined) {
+            config.agents[id].expertise = Array.isArray(expertiseUpdate) ? expertiseUpdate : String(expertiseUpdate).split(',').map(s => s.trim()).filter(Boolean);
+            delete config.agents[id].skills;
+          }
           if (updates.monthlyBudgetUsd !== undefined) {
             const val = updates.monthlyBudgetUsd === '' || updates.monthlyBudgetUsd === null ? undefined : Number(updates.monthlyBudgetUsd);
             if (val === undefined || isNaN(val)) delete config.agents[id].monthlyBudgetUsd;

package/docs/README.md

@@ -15,7 +15,8 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
-- [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library: Phase 1 exposes & edits each role's definition + skills; Phase 2 adds role/agent CRUD. Covers the additive `config.roles` model, resolver tiering, migration from per-agent `charter.md`, and API/UI surface.
+- [specs/agent-rename.md](specs/agent-rename.md) — Design spec for **agent rename & name decoupling** — the prerequisite for the Role/Agent Library. Formalizes the stable opaque agent id, makes charters name-agnostic, and adds `POST /api/agents/rename` (display name + emoji). Feature-flagged (`agent-rename`) and fully backward-compatible.
+- [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library, feature-flagged behind `agent-library` and fully backward-compatible. Builds on `agent-rename.md`. Role = the reusable durable charter; agent = a thin instance (identity + variable expertise + role pointer). Phase 0 renames `skills`→`expertise`; Phase 1 exposes/edits role charters + per-agent expertise; Phase 2 adds role/agent CRUD with builtin delete-protection.
 - [completion-reports.md](completion-reports.md) — Canonical schema for the per-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
 - [constants.md](constants.md) — Cross-cutting status / type / condition constants (`WI_STATUS`, `WORK_TYPE`, `PR_STATUS`, `WATCH_CONDITION`, …) and the no-magic-strings invariant.
 - [constellation-bridge.md](constellation-bridge.md) — Read-only cross-repo bridge: `engine.constellationBridge.enabled` flag, marker-file contract, and the `minions bridge` subcommand for local debugging.
@@ -33,6 +34,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
 - [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `checkoutMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.
 - [managed-spawn.md](managed-spawn.md) — Engine-owned long-running services (managed-spawn primitive): sidecar schema, healthcheck examples, lifecycle, dashboard API, and the WI 1 (build) → WI 2 (test) chained-validation pattern.
+- [named-agents.md](named-agents.md) — The named-agent roster (Ripley / Dallas / Lambert / Rebecca / Ralph): per-agent `config.json` shape, the per-agent → `engine.*` → runtime resolution chain, how `routing.md` (not the `role`/`skills` metadata) drives dispatch, descriptive vs runtime skills, and per-agent memory files.
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [pr-auto-fix-dispatch.md](pr-auto-fix-dispatch.md) — Short reference table mapping each PR auto-fix / review dispatch site in `engine.js#discoverFromPrs` to its gate flag, plus the `pollingPaused` / `autoFixPaused` master kill-switches and the per-provider polling gates.
 - [pr-comment-followup.md](pr-comment-followup.md) — PR-comment follow-up dispatch contract: fix/review agents may spin off a new WI via `POST /api/work-items` with `meta.pr_followup` instead of broadening the current PR or rebutting the comment.

package/docs/auto-discovery.md

@@ -19,7 +19,7 @@ tick()
   2.5 runCleanup()               Periodic cleanup (every 60 ticks ≈ 10min)
   2.52 sweepKeepProcesses()      keep_processes TTL/dead-PID sweep (every 180 ticks)
   2.53 sweepManagedSpawn()       managed_spawn TTL/dead-PID/log-rotate sweep (every 180 ticks)
-  2.54 pruneWorktreesPeriodic()  Periodic worktree GC: in-root + out-of-root git registry sweep (every worktreePruneIntervalTicks ≈ 30 ticks; catches Windows EPERM/EBUSY stragglers and `git worktree list` entries outside worktreeRoot)
+  2.54 pruneWorktreesPeriodic()  Periodic worktree GC: in-root + out-of-root git registry sweep + locked-`initializing` missing-dir reclaim (every worktreePruneIntervalTicks ≈ 30 ticks; catches Windows EPERM/EBUSY stragglers, `git worktree list` entries outside worktreeRoot, and branch-bricking locked missing-dir entries plain prune can't reap)
   2.55 checkWatches()            Persistent watch jobs (every 18 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

package/docs/deprecated.json

@@ -1,4 +1,17 @@
 [
+  {
+    "id": "agent-config-skills-field",
+    "description": "Legacy per-agent descriptive-metadata array `agents.<id>.skills` in config.json, renamed to `agents.<id>.expertise` to remove the name collision with executable runtime/harness skills (SKILL.md). The field is metadata only (capability tags like `architecture`, `bug-fixes`); nothing in the dispatch path reads it for behavior. A read-compat shim honors the old key so operator configs still carrying `skills` (and no `expertise`) keep working.",
+    "code": [
+      { "file": "engine/playbook.js", "lines": "950", "note": "buildSystemPrompt reads `agent.expertise ?? agent.skills ?? []` for the `Expertise:` identity line" },
+      { "file": "engine/lifecycle.js", "lines": "4620-4621", "note": "pickReReviewAgentHints reads `agent.expertise` with an `agent.skills` array fallback" },
+      { "file": "engine/queries.js", "lines": "731", "note": "getAgents normalizes `expertise: a.expertise ?? a.skills ?? []` so the dashboard/settings UI always receives `expertise`" },
+      { "file": "dashboard.js", "lines": "10708-10716", "note": "settings POST accepts a legacy `updates.skills` key, persists as `config.agents[id].expertise`, and deletes the old `skills` key" }
+    ],
+    "removalGate": "Telemetry / a config sweep across all known engines must show no persisted `config.agents.<id>.skills` key (only `expertise`) for >=30 consecutive days, confirming every operator config has been re-saved through the dashboard (which drops the legacy key) or hand-migrated.",
+    "targetRemovalDate": "2026-09-17",
+    "notes": "Safe to remove on or after 2026-09-17 (~3 release windows) once the removal gate clears. Removal scope: drop the `?? agent.skills` / `?? a.skills` fallbacks in engine/playbook.js:950, engine/lifecycle.js:4620-4621, and engine/queries.js:731; drop the `updates.skills` legacy branch + `delete config.agents[id].skills` in dashboard.js:10708-10716; and update docs/named-agents.md to stop mentioning the legacy key. Does NOT touch the unrelated executable-skills system (queries.js harnesses, runtime adapters, dashboard renderSkills, SKILL.md tooling)."
+  },
   {
     "id": "qa-json-sidecars",
     "location": "engine/small-state-store.js _mirrorQaRunsJson + _mirrorQaSessionsJson; engine/shared.js _qaMutator (mirror call); dashboard/js/settings.js set-qaDualWriteJson toggle",

package/docs/named-agents.md

@@ -0,0 +1,216 @@
+# Named Agents — configuration, roles, and skills
+
+Minions dispatches a small roster of **named agents** — personas like Ripley or Dallas
+that own work items, open PRs, and review each other's changes. This doc explains who
+they are, the full per-agent config shape, how work actually routes to one of them, what
+the descriptive `expertise` tags and the real executable `skills` are (and why they used to
+share a name), and how each agent accrues personal memory across dispatches.
+
+> Orientation only — the load-bearing contracts live in code. Cross-references:
+> [`CLAUDE.md`](../CLAUDE.md), [`.github/copilot-instructions.md`](../.github/copilot-instructions.md),
+> [`docs/runtime-adapters.md`](runtime-adapters.md), [`docs/workspace-manifests.md`](workspace-manifests.md),
+> [`docs/team-memory.md`](team-memory.md), and [`docs/skills.md`](skills.md).
+
+## 1. The roster
+
+The five named agents are defined under `agents` in `config.json` (gitignored; the
+shipped `config.template.json` carries no agents — operators populate the roster locally).
+Each entry is keyed by a lowercase agent id (`ripley`, `dallas`, …).
+
+| Id | Name | Emoji | Role | `expertise` (descriptive) | `cli` |
+|----|------|-------|------|------------------------|-------|
+| `ripley` | Ripley | 🏗️ | Lead / Explorer | `architecture`, `codebase-exploration`, `design-review` | `copilot` |
+| `dallas` | Dallas | 🔧 | Engineer | `implementation`, `typescript`, `docker`, `testing` | `copilot` |
+| `lambert` | Lambert | 📊 | Analyst | `gap-analysis`, `requirements`, `documentation` | `copilot` |
+| `rebecca` | Rebecca | 🧠 | Architect | `system-design`, `api-design`, `scalability`, `implementation` | `copilot` |
+| `ralph` | Ralph | ⚙️ | Engineer | `implementation`, `bug-fixes`, `testing`, `scaffolding` | `copilot` |
+
+The `name`, `emoji`, `role`, and `expertise` fields are **human-facing metadata** — they
+label the agent in the dashboard and document intent. They do **not** drive dispatch (see
+§3) and the `expertise` array is not executable (see §4).
+
+## 2. How an agent is configured
+
+The full per-agent config shape supported under `config.agents.<id>`:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `name` | string | Display name (e.g. `"Ripley"`). |
+| `role` | string | Human-facing role label (e.g. `"Lead / Explorer"`). Metadata only. |
+| `emoji` | string | Dashboard glyph. |
+| `expertise` | string[] | Descriptive capability tags. Metadata only — see §4. Legacy configs that still use the old key name `skills` are read transparently. |
+| `cli` | string | Runtime CLI for this agent's spawns: `copilot`, `claude`, or `codex`. |
+| `model` | string | Per-agent model override (omitted → runtime picks its own default). |
+| `maxBudgetUsd` | number | Per-spawn USD cap. **`0` is a valid cap** (read-only / dry-run agents), not "unlimited". |
+| `bareMode` | boolean | Run Claude in `--bare` mode (Claude-runtime knob). |
+| `hermeticHarness` | boolean | Strip user-scope skill/command/MCP roots from the worktree; `--add-dir` resolves to `[minionsDir]` only. |
+| `workspace_manifest` | object | Optional permission scoping — see below. |
+
+### Three-tier resolution chain
+
+Most knobs resolve **per-agent override → `engine.*` fleet default → runtime default**.
+The resolver helpers live in [`engine/shared.js`](../engine/shared.js):
+
+| Helper | Chain |
+|--------|-------|
+| `resolveAgentCli(agent, engine)` | `agent.cli` → `engine.defaultCli` → `ENGINE_DEFAULTS.defaultCli` (`'copilot'`). |
+| `resolveAgentModel(agent, engine)` | `agent.model` → `engine.defaultModel` → `undefined` (adapter omits `--model`, CLI uses its own default). |
+| `resolveAgentMaxBudget(agent, engine)` | `agent.maxBudgetUsd` → `engine.maxBudgetUsd` → `undefined` (no cap). Nullish-coalesced so `0` is honored. |
+| `resolveAgentBareMode(agent, engine)` | `agent.bareMode` → `engine.claudeBareMode` → `false`. Strict null check so a per-agent `false` overrides an engine `true`. |
+| `resolveAgentHermeticHarness(agent, engine)` | `agent.hermeticHarness` → `engine.hermeticHarness` → `false`. Same strict-override semantics. |
+
+Empty string / `null` / `undefined` all count as "unset" for the string knobs, so an agent
+inherits the fleet default rather than blanking the value.
+
+### Agent vs Command Center independence
+
+The Command Center (CC) / doc-chat path is a fleet-wide singleton with **no notion of
+"which agent"**, so it resolves through separate helpers: `resolveCcCli(engine)`
+(`engine.ccCli` → `engine.defaultCli` → fallback) and `resolveCcModel(engine)`
+(`engine.ccModel` → `engine.defaultModel` → `undefined`). These **do not cross over**:
+`ccCli` / `ccModel` never affect a named-agent spawn, and `agent.cli` / `agent.model` never
+affect CC. Both paths share the `engine.defaultCli` / `engine.defaultModel` fleet defaults,
+but only as the middle tier.
+
+### Workspace manifest (optional)
+
+`agents.<id>.workspace_manifest` declares declarative permission scoping. Shape and
+defaults (`WORKSPACE_MANIFEST_DEFAULTS` in `engine/shared.js`):
+
+| Key | Default | Effect |
+|-----|---------|--------|
+| `allowed_tools` | `null` (permissive) | Whitelist of tool names; merged into the runtime `--allowedTools` flag. `[]` = deny-all. |
+| `allowed_repos` | `null` (permissive) | Repo allow-list; enforced at dispatch time. `[]` = deny-all. |
+| `allowed_external_urls` | `null` (permissive) | URL allow-list (supports `*.example.com` wildcards). |
+| `memory_scope` | `'shared'` | One of `private`, `shared`, `read-only-shared`. |
+
+Enforcement helpers (also in `engine/shared.js`): `validateWorkspaceManifest`,
+`resolveAgentManifest`, `agentCanUseRepo`, `agentCanUseTool`, `agentCanFetchUrl`,
+`agentMemoryScope`, `mergeManifestAllowedTools`. Today the engine actively enforces (a) the
+**repo gate** at dispatch time in `engine.js spawnAgent`
+(`FAILURE_CLASS.WORKSPACE_MANIFEST_REPO`, non-retryable) and (b) the **tool merge** into the
+runtime `--allowedTools` flag at spawn time. Defaults are permissive — an agent with no
+manifest is unaffected. Full schema and rollout guidance:
+[`docs/workspace-manifests.md`](workspace-manifests.md).
+
+## 3. How roles are defined / how work routes to an agent
+
+The `role` and `expertise` config fields are **descriptive metadata**. The actual dispatch
+decision is **data-driven by [`routing.md`](../routing.md)**, which `engine.js` parses — so
+keep that file's table format exact.
+
+Routing maps a `work_type` to a `preferred` agent and a `fallback`:
+
+| Work Type | Preferred | Fallback |
+|-----------|-----------|----------|
+| implement | dallas | ralph |
+| implement:large | rebecca | dallas |
+| review | ripley | lambert |
+| fix | `_author_` | `_any_` |
+| plan | ripley | rebecca |
+| plan-to-prd | lambert | rebecca |
+| explore | ripley | rebecca |
+| test | dallas | ralph |
+| ask | ripley | rebecca |
+| verify | dallas | ralph |
+| decompose | ripley | rebecca |
+| meeting | ripley | lambert |
+| docs | lambert | `_any_` |
+| setup | dallas | `_any_` |
+| qa-validate / qa-session-* | dallas | ralph |
+
+**Sentinels.** `_author_` routes a `fix` (review-feedback) item back to the PR author for
+context; `_any_` routes to any available idle agent (lowest error rate first).
+`implement:large` is selected for items with `estimated_complexity: "large"`. If both
+preferred and fallback are busy, the engine falls back to any idle agent.
+
+**Dispatch rules** (from `routing.md`):
+
+- **Eager by default** — the engine spawns every agent that can start work, not one at a time.
+- **No self-review** — auto review dispatch always picks a non-author. When no non-author
+  reviewer is idle, the dispatch waits in `dispatch.pending` with
+  `_pendingReason: 'no_non_author_reviewer'` and promotes automatically once one frees up.
+  An explicit operator dispatch (`agent: <author>`) is honored as an override but logged as
+  a warning.
+- **Routing selects an owner; it does not narrow the task.** The assigned agent behaves as
+  if the user typed the same task into a CLI directly — Minions adds only safety, status,
+  and review guardrails.
+
+### Per-agent retry reassignment
+
+Total retries are capped by `ENGINE_DEFAULTS.maxRetries` (default 3). Separately, each work
+item tracks per-agent attempts in `_retriesByAgent: { agentId: count }`. When the **same**
+agent fails the **same** item `maxRetriesPerAgent` times (default 2; overridable via
+`engine.maxRetriesPerAgent` and the dashboard Settings field), discovery force-reassigns to
+a different eligible agent via `resolveAgent(workType, config, { excludeAgent })`. If no
+alternate is available it stays with the same agent and dedups an engine inbox note. Setting
+`agentLock: true` (or `hardAgent: true`) hard-pins the agent and bypasses reassignment —
+operator intent wins. The counter is cleared on successful completion alongside
+`_retryCount`. Helpers: `bumpAgentRetryCount`, `getAgentRetryCount`,
+`resolveMaxRetriesPerAgent` in `engine/shared.js`.
+
+## 4. How skills are defined
+
+Historically "skills" meant two unrelated things in Minions. The descriptive per-agent
+metadata array was renamed `skills` → `expertise` to remove that collision, so the only
+"skills" left are the real executable ones. The two concepts to keep separate:
+
+**(a) The descriptive `expertise` array in config** (`agents.<id>.expertise`). A list of
+capability tags like `architecture` or `bug-fixes`. This is **metadata only** — labels for
+humans, not executable behavior. Nothing in the dispatch path reads it. (This field was
+formerly named `skills`; legacy configs that still use that key are read transparently via
+an `expertise ?? skills` fallback — see [`docs/deprecated.json`](deprecated.json).)
+
+**(b) Real runtime skills** — `SKILL.md` files the runtime CLI actually loads. These are
+auto-extracted from agent output: when an agent emits a fenced ```` ```skill ```` block
+(with YAML frontmatter carrying at least a `name`), `extractSkillsFromOutput` in
+[`engine/lifecycle.js`](../engine/lifecycle.js) writes it out. The engine also scans
+`notes/inbox/` notes for skill blocks, since agents often write them there instead of stdout.
+
+- **`scope: minions`** (the default when `scope` is omitted) → written to the runtime's
+  **personal** skill directory as `<name>/SKILL.md`, so it becomes a user-level skill
+  available in normal runtime windows too.
+- **`scope: project`** (with a `project:` field) → the engine queues a low-priority
+  `implement` work item to **PR the skill into the project repo's** skill directory rather
+  than writing it directly.
+
+Near-duplicate names are flagged to `engine/skills-flagged.json` and skipped (no existing
+skill is deleted or renamed). See [`docs/skills.md`](skills.md) for the block format.
+
+**Runtime differences.** The destination directory is runtime-specific
+(`getSkillRoots` / `getSkillWriteTargets` in the runtime adapters under
+[`engine/runtimes/`](../engine/runtimes/)):
+
+| Runtime | Personal write target | Project write target | Also reads |
+|---------|-----------------------|----------------------|------------|
+| Claude (`claude.js`) | `~/.claude/skills/` | `<repo>/.claude/skills/` | `~/.agents/skills/` |
+| Copilot (`copilot.js`) | `~/.copilot/skills/` | `<repo>/.github/skills/` | `~/.copilot`, `~/.agents/skills/` |
+
+The capability matrix for each runtime is in [`docs/runtime-adapters.md`](runtime-adapters.md).
+
+## 5. Per-agent memory & charters
+
+Each named agent has a personal memory file at
+`knowledge/agents/<agentId>.md` (e.g. `knowledge/agents/dallas.md`) — a personal notebook
+injected into that agent's prompt on every dispatch. The format convention is documented in
+[`knowledge/agents/README.md`](../knowledge/agents/README.md).
+
+**Written exclusively by the consolidation pipeline.** `appendToAgentMemory` in
+[`engine/consolidation.js`](../engine/consolidation.js) routes each `notes/inbox/` finding
+to its author's file. Authorship comes from the inbox note's YAML frontmatter `agent:`
+field, with the **filename prefix** (`<agent>-…md`) as fallback (`extractInboxAgent`). Key
+properties:
+
+- **Append-only** — agents must not edit their own memory files directly; write to
+  `notes/inbox/` and let the sweep route it.
+- **~25 KB cap** (`AGENT_MEMORY_BUDGET_BYTES`) — oldest sections pruned at section
+  boundaries to stay under budget.
+- **Only configured `config.agents` keys get a file** — the agent must be in the known-team
+  set; `temp-*` ids are skipped. This is a strict superset of broadcast consolidation: the
+  shared `notes.md` digest still happens; per-agent routing is *in addition*.
+
+**Prompt injection order.** [`engine/playbook.js`](../engine/playbook.js) injects, in this
+order, `pinned.md` → `notes.md` → `knowledge/agents/<agentId>.md` (when present). Missing
+files are silently skipped. The per-agent file is fenced as `<UNTRUSTED-INPUT>` and capped
+to the notes prompt budget before injection. The companion read-side reference is
+[`docs/team-memory.md`](team-memory.md).