@yemi33/minions 0.1.2423 → 0.1.2425

package/docs/self-improvement.md

@@ -92,16 +92,16 @@ When `notes.md` exceeds 50KB, the engine trims it to the cap (keeping the header
 
 ## 2. Per-Agent History
 
-Each agent maintains a `history.md` file that tracks its last 20 tasks. This is injected into the agent's system prompt so it knows what it did recently.
+Each agent's `history.md` retains its last 20 tasks. To bound prompt size, `engine/playbook.js` injects only the five most recent retained entries into the next dispatch.
 
 ### Flow
 
 ```
 Agent finishes task
   → engine calls updateAgentHistory()
-  → prepends entry to agents/<name>/history.md
+  → prepends entry to agents/<id>/history.md
   → trims to 20 entries
-  → next time agent spawns: history.md injected into system prompt
+  → next time agent spawns: 5 retained entries injected into the prompt
 ```
 
 ### What's tracked per entry
@@ -161,6 +161,40 @@ in the future, avoid the patterns flagged here.
 
 Without this, review findings only exist in the inbox file under the reviewer's name. The author never explicitly sees them unless they happen to read the consolidated notes.md. The feedback loop ensures the author gets a direct, targeted learning from every review.
 
+### 3a. Structured review learning (durable, opt-in)
+
+The narrative feedback file above is per-PR and consolidated into free-text notes.
+**Review learning** is its durable, structured evolution: a verified reviewer
+finding becomes a bounded, project-scoped procedural *lesson* that a later,
+lexically unrelated dispatch touching the same file or symbol recalls
+deterministically. It is fully specified in
+[team-memory.md](team-memory.md#review-learning-lifecycle-storage); the essentials:
+
+- **Trust & taxonomy.** Lessons carry `source_type: review-learning`, system trust,
+  and a stable finding key `<project>|<canonical-pr-id>|<host-namespaced-source-key>`.
+  They are globally excluded from generic FTS recall and only surface through the
+  dedicated project-scoped path.
+- **Capture.** With `review-learning-capture` on, only a completed Minions
+  `changes-requested` verdict creates an unresolved *candidate*; a verified
+  `accepted-fixed` / `satisfied-elsewhere` disposition promotes it to one active
+  lesson. Invalid/stale/deferred close or hold the candidate.
+- **Recall.** With `review-learning-recall` on, a dispatch with a resolved project
+  recalls up to 4 records / 4 KiB as a separately fenced `## Applicable Prior Review
+  Lessons` section, ranked by exact symbol → file → tag overlap.
+- **Application, correction, supersession.** Agents report `applied` /
+  `considered-not-applicable` / `contradicted` outcomes for lessons their trusted
+  retrieval trace showed them; an evidence-backed contradiction quarantines the
+  lesson. Changed rule content supersedes the prior active version, leaving at most
+  one active lesson per finding key.
+- **Promotion.** A high-confidence, repeatedly observed lesson can be human-promoted
+  into repository guidance (`CLAUDE.md` / `AGENTS.md` / Copilot instructions or a
+  project skill) via a normal PR — never by editing a checkout.
+- **Diagnostics, retention & rollback.** Retrieval decisions, a lifecycle timeline,
+  rollout aggregates, and the staged-rollout comparison are exposed under
+  `/api/memory-records/*`. Both flags default off and expire 2027-01-31; disabling
+  recall is a complete prompt rollback (see
+  [team-memory.md → Staged rollout and acceptance](team-memory.md#staged-rollout-and-acceptance)).
+
 ## 4. Human Feedback on PRs
 
 Humans can leave actionable comments on ADO or GitHub PRs to trigger fix tasks;
@@ -196,8 +230,9 @@ The engine tracks per-agent performance metrics in the SQL metrics store. It upd
 
 | Metric | Updated when |
 |--------|-------------|
-| `tasksCompleted` | Agent exits with code 0 |
-| `tasksErrored` | Agent exits with non-zero code |
+| `tasksCompleted` | Lifecycle records a final `DISPATCH_RESULT.SUCCESS` |
+| `tasksRetried` | A non-terminal failure is auto-requeued |
+| `tasksErrored` | Lifecycle records a terminal non-success result |
 | `prsCreated` | Agent completes an implement task |
 | `prsApproved` | Reviewer approves the agent's PR |
 | `prsRejected` | Reviewer requests changes on the agent's PR |
@@ -223,10 +258,9 @@ Metrics:
   lambert      2      0      0      0 (-)      0          4
 ```
 
-### Future use
+### Current and future use
 
-Metrics are currently informational — displayed in status and dashboard. Planned uses:
-- **Routing adaptation:** If an agent's approval rate drops below a threshold, deprioritize them for implementation tasks
+Metrics are displayed in status and the dashboard, and task error rate already affects routing: `_any_` and any-idle fallback/reservation paths choose the eligible agent with the lowest `tasksErrored / (tasksCompleted + tasksErrored)` rate. Approval-rate routing is not implemented. Potential future uses:
 - **Auto-escalation:** If an agent errors 3 times in a row, pause their dispatch and alert
 - **Capacity planning:** Track throughput per agent to optimize `maxConcurrent`
 
@@ -247,10 +281,10 @@ Metrics are currently informational — displayed in status and dashboard. Plann
 │  tasks)  │                    │                          │
 └──────────┘                    │ on completion            │ consolidateInbox()
      ▲                          ▼                          ▼
-     │                 ┌──────────────────┐         ┌──────────┐
-     └─updateHistory───│   Engine         │─prune──→│decisions  │
-                       │   post-hooks     │         │  .md     │
-                       └────────┬─────────┘         └──────────┘
+     │                 ┌──────────────────┐
+     └─updateHistory───│   Engine         │
+                       │   post-hooks     │
+                       └────────┬─────────┘
                                 │
                     ┌───────────┼───────────┐
                     ▼           ▼           ▼
@@ -324,6 +358,6 @@ The canonical block format, fields, and eligibility threshold live in
 | `notes/inbox/*.md` | Agent findings drop-box | Agents |
 | `notes/archive/*.md` | Archived inbox files | Engine (consolidation) |
 | `notes.md` | Accumulated team knowledge | Engine (consolidation) |
-| `agents/<name>/history.md` | Per-agent task history | Engine (post-completion) |
+| `agents/<id>/history.md` | Per-agent task history | Engine (post-completion) |
 | `engine/state.db` `metrics` | Quality metrics per agent | Engine (post-completion + review) |
 | `notes/inbox/feedback-*.md` | Review feedback for authors | Engine (post-review) |

package/docs/skills.md

@@ -43,3 +43,32 @@ Plain Markdown. Include the steps, commands, file paths, and notes another agent
 ## When not to emit a skill
 
 See [`playbooks/shared-rules.md`](../playbooks/shared-rules.md) for the full threshold. In short: do not emit a skill for one-off bug fixes, isolated command output, obvious repo facts, or anything already covered by existing docs, playbooks, or skills.
+
+## Human-approved promotion of review lessons (P-192d3660)
+
+Verified **review lessons** captured in structured memory (`sourceType: review-learning`,
+`memoryType: procedural`) can be promoted into durable repository guidance so vanilla
+Copilot/Claude pick them up through native instruction/skill discovery. Promotion is an
+**operator-only** action in the dashboard **Structured Memory** modal — it never edits a
+checkout. It queues a normal project-bound work item that follows the usual branch → PR →
+review → merge lifecycle.
+
+- **Eligibility** (`engine/promotion.js#evaluateLessonPromotionEligibility`): the lesson must be
+  `active`, high-confidence (`confidence >= 0.8`), and backed by **at least two distinct valid
+  findings** (its own finding plus repeated-finding recurrences, counted by
+  `memory-store.js#getReviewLearningFindingSupport`). The search API annotates eligible lessons
+  with a `repoPromotion` object; the modal shows a **Promote to repo** button only for those.
+- **Targets**: the operator confirms a project and either
+  - `project-skill` — a lowercase kebab-case slug queued as an `implement` work item that creates
+    `<slug>/SKILL.md` (the runtime's native skill root); or
+  - `repository-instruction` — an allowlisted file (`CLAUDE.md`, `AGENTS.md` at any depth, or
+    `.github/copilot-instructions.md`) queued as a `docs` work item.
+- **Queueing** goes through `engine/promotion.js#queuePromotion`, which reuses the same
+  project-bound work-item queueing extracted from `lifecycle.js#extractSkillsFromOutput`
+  (`queueProjectSkillWorkItem`). The queued work item cites the stable originating memory IDs, the
+  bounded proposed rule(s), and the target project/path in `meta.promotion`.
+- **API**: `POST /api/memory-records/<id>/promote` with `{ targetKind, project, path }`. Repeated
+  clicks are deduplicated on `meta.promotion.dedupeKey`; the endpoint returns the existing
+  work-item id (`duplicate: true`) instead of queueing a second item. A `promotion-requested`
+  lifecycle event links the memory → target → work item (and, via the work item's normal PR
+  linkage, the eventual PR).

package/docs/slim-ux/concepts.md

@@ -681,7 +681,7 @@ work sources.
 `checkoutMode: "worktree"` is the default isolated execution model.
 `checkoutMode: "live"` opts a project into guarded in-place execution.
 
-**Existing dashboard.** `dashboard/pages/settings.html` owns project onboarding and removal.
+**Existing dashboard.** `dashboard/js/settings.js` owns project onboarding and removal.
 
 **Endpoints.**
 
@@ -828,7 +828,7 @@ MCP/skill configuration remain owned and discovered by the selected CLI.
 - Settings handlers: `dashboard.js#handleSettingsRead`, `#handleSettingsUpdate`,
   `#handleSettingsReset`, and `#handleSettingsRouting`
 
-**Existing dashboard.** `dashboard/pages/settings.html` is the canonical settings surface.
+**Existing dashboard.** `dashboard/js/settings.js` is the canonical settings surface.
 
 **Endpoints.**
 

package/docs/specs/agent-configurability.md

@@ -1,15 +1,17 @@
 # Spec: Agent & Role Configurability
 
-**Status:** Draft
+**Status:** Draft (Phase 0b shipped; remaining phases unimplemented)
 **Owner:** @calebt
 **Audience:** Minions contributors working on the dashboard, engine config surface, and playbook/system-prompt rendering.
 **Depends on:** [`agent-rename.md`](agent-rename.md) — a **hard prerequisite**. That spec delivers the "names aren't load-bearing" foundation (stable opaque agent **id**, name-agnostic charters, and the agent rename capability) that this Library builds on. The decoupling sections below (§2.8, §4.1a, §4.3c, §5.4) are **summaries that defer to `agent-rename.md`** for the full treatment.
 
 > Companion reading: [`.github/copilot-instructions.md`](../../.github/copilot-instructions.md) and [`CLAUDE.md`](../../CLAUDE.md) for the engine/dashboard split, config conventions, and the feature-flag registry.
+>
+> **Implementation status (2026-07-19):** Phase 0b (`skills` → `expertise`) has shipped. `expertise` is canonical and `skills` remains a read-compat alias tracked in [`docs/deprecated.json`](../deprecated.json). The Role / Agent Library, role model, CRUD, and `agent-library` feature flag remain unimplemented.
 
 ## 1. Motivation
 
-Today a Minions "team" is a fixed roster of five hard-coded agents (`ripley`, `dallas`, `lambert`, `rebecca`, `ralph`) whose personas live in a mix of places: a free-text `role` string in `config.json`, a loosely-related `skills` string array, and a per-agent `charter.md` file. The charter — the real persona — is **per-agent**, so there is no reusable notion of "what it means to be an Engineer." There is **no way to**:
+Today a Minions "team" is a fixed roster of five hard-coded agents (`ripley`, `dallas`, `lambert`, `rebecca`, `ralph`) whose personas live in a mix of places: a free-text `role` string in `config.json`, an `expertise` string array, and a per-agent `charter.md` file. The charter — the real persona — is **per-agent**, so there is no reusable notion of "what it means to be an Engineer." There is **no way to**:
 
 - See an agent's full definition (role charter + expertise + runtime) in one place.
 - Treat a "role" as a reusable, editable unit (a durable charter shared across agents) — it is just a label string today.
@@ -23,7 +25,7 @@ The goal is to make the fleet **user-configurable** through a **Role / Agent Lib
 
 Phases:
 
-- **Phase 0 — Prerequisite migrations.** Establish the feature flag and rename the misnamed `skills` field to `expertise`. (The stable-id formalization and name-agnostic charters are delivered by the **[`agent-rename.md`](agent-rename.md) prerequisite**, which must land first.) All additive + flag-aware.
+- **Phase 0 — Prerequisite migrations.** Phase 0b (`skills` → `expertise`) is shipped; Phase 0a still establishes the feature flag. (The stable-id formalization and name-agnostic charters are delivered by the **[`agent-rename.md`](agent-rename.md) prerequisite**, which must land first.) All additive + flag-aware.
 - **Phase 1 — Expose & edit.** Surface each role's durable charter + each agent's variable expertise in one editable library view; the agent **rename** capability comes from the prerequisite and is surfaced inline here. No new roles or agents yet.
 - **Phase 2 — Create & assign.** Add new roles, and stand up new named agents bound to a role.
 
@@ -33,16 +35,16 @@ This section is the factual baseline the design must respect. Citations are `fil
 
 ### 2.1 Agent object — already id-keyed
 
-Agents live under `config.agents` keyed by a **stable lowercase id** (the object key). `name` is a **separate display field** — there is no explicit `id` field inside the object; the key *is* the id, and `getAgents()` materializes it as `{ id, ...info }` (`engine/queries.js:681-687`). Defaults are hard-coded:
+Agents live under `config.agents` keyed by a **stable lowercase id** (the object key). `name` is a **separate display field** — there is no explicit `id` field inside the object; the key *is* the id, and `getAgents()` materializes it as `{ id, ...info }` (`engine/queries.js:764-845`). Defaults are hard-coded:
 
 ```js
-// engine/shared.js:4398-4404
+// engine/shared.js:4728-4734
 const DEFAULT_AGENTS = {
-  ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', skills: ['architecture', 'codebase-exploration', 'design-review'] },
-  dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        skills: ['implementation', 'typescript', 'docker', 'testing'] },
-  lambert: { name: 'Lambert', emoji: '📊', role: 'Analyst',         skills: ['gap-analysis', 'requirements', 'documentation'] },
-  rebecca: { name: 'Rebecca', emoji: '🧠', role: 'Architect',       skills: ['system-design', 'api-design', 'scalability', 'implementation'] },
-  ralph:   { name: 'Ralph',   emoji: '⚙️', role: 'Engineer',        skills: ['implementation', 'bug-fixes', 'testing', 'scaffolding'] },
+  ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', expertise: ['architecture', 'codebase-exploration', 'design-review'] },
+  dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        expertise: ['implementation', 'typescript', 'docker', 'testing'] },
+  lambert: { name: 'Lambert', emoji: '📊', role: 'Analyst',         expertise: ['gap-analysis', 'requirements', 'documentation'] },
+  rebecca: { name: 'Rebecca', emoji: '🧠', role: 'Architect',       expertise: ['system-design', 'api-design', 'scalability', 'implementation'] },
+  ralph:   { name: 'Ralph',   emoji: '⚙️', role: 'Engineer',        expertise: ['implementation', 'bug-fixes', 'testing', 'scaffolding'] },
 };
 ```
 
@@ -52,29 +54,29 @@ Runtime / budget fields are **optional per-agent overrides** resolved against `e
 
 | Field | Resolver | Falls back to |
 |-------|----------|---------------|
-| `cli` | `resolveAgentCli` (shared.js:3142) | `engine.defaultCli` → `'copilot'` |
-| `model` | `resolveAgentModel` (shared.js:3202) | `engine.defaultModel` → undefined |
-| `maxBudgetUsd` / `monthlyBudgetUsd` | `resolveAgentMaxBudget` (shared.js:3231) | `engine.maxBudgetUsd` |
-| `bareMode` | `resolveAgentBareMode` (shared.js:3254) | `engine.claudeBareMode` → false |
+| `cli` | `resolveAgentCli` (shared.js:3561) | `engine.defaultCli` → `'copilot'` |
+| `model` | `resolveAgentModel` (shared.js:3672) | `engine.defaultModel` → undefined |
+| `maxBudgetUsd` / `monthlyBudgetUsd` | `resolveAgentMaxBudget` (shared.js:3711) | `engine.maxBudgetUsd` |
+| `bareMode` | `resolveAgentBareMode` (shared.js:3734) | `engine.claudeBareMode` → false |
 
 ### 2.2 "Role" is a label, not an entity
 
-`role` is a **free-text string** on the agent. There is no role registry, no role schema, and routing does **not** reference roles — it references agent ids. The dashboard edits role as a plain text input (`dashboard/js/settings.js:72`) and persists it verbatim (`dashboard.js:10684`).
+`role` is a **free-text string** on the agent. There is no role registry, no role schema, and routing does **not** reference roles — it references agent ids. The dashboard edits role as a plain text input (`dashboard/js/settings.js:72`) and persists it verbatim (`dashboard.js:11242-11244`).
 
-### 2.3 `skills` is *expertise*, not real skills
+### 2.3 `expertise` metadata is distinct from executable skills
 
-Two unrelated things share the word "skill" today, and the `agent.skills` field is the **misnamed** one:
+Two unrelated concepts previously shared the word "skill"; Phase 0b made `agent.expertise` canonical while retaining `agent.skills` as a compatibility alias:
 
-1. **`agent.skills`** — a string array of **expertise tags**. It is *not* linked to any executable capability or on-disk skill file. It has exactly two readers:
-   - **Display:** rendered as the `Expertise: …` line in the system prompt (`engine/playbook.js:950`).
-   - **Soft routing:** `pickReReviewAgentHints()` (`engine/lifecycle.js:4613-4624`) scans `agent.skills` for the tags `code-review` / `design-review` to *prefer* (not require) that agent for re-review. This is the one functional consumer — a rename must update it too, not just the display line.
-2. **Real `SKILL.md` files** — discovered from disk (`.claude/skills/`, `~/.claude/skills`, project harness dirs) by `collectSkillFiles()` / `getSkills()` (`engine/queries.js:1263-1400`), scoped global/project/plugin. These are **not** bound to a specific agent or role; every agent sees the same discovered catalog, and `agent.skills` has **no relationship** to them.
+1. **`agent.expertise`** — a string array of descriptive expertise tags. It is *not* linked to any executable capability or on-disk skill file. Readers tolerate legacy configs with `agent.expertise ?? agent.skills`:
+   - **Display:** the `Expertise: …` line in the system prompt (`engine/playbook.js:1094`).
+   - **Soft routing:** `pickReReviewAgentHints()` (`engine/lifecycle.js:5311-5321`) prefers agents tagged `code-review` / `design-review`.
+2. **Real `SKILL.md` files** — discovered from disk by `collectSkillFiles()` / `getSkills()` (`engine/queries.js:1363-1498`), scoped global/project/plugin. These are **not** bound to a specific agent or role; every agent sees the same discovered catalog, and expertise metadata has **no relationship** to them.
 
-Because `agent.skills` is purely expertise metadata (plus a soft reviewer hint), the field is misnamed. **Phase 0b renames it `expertise`** to remove the overload and free the word "skills" for any future real-skill binding (§8).
+The canonical rename has shipped. The legacy alias remains only for compatible reads until the removal gate in `docs/deprecated.json` clears.
 
 ### 2.4 Charter = the real "agent definition"
 
-The substantive persona/instructions for an agent is `agents/<id>/charter.md`, read by `getAgentCharter()` (`engine/queries.js:677-678`) and injected into the system prompt as `## Your Charter` (`engine/playbook.js:942-954`). The system prompt assembled in `buildSystemPrompt()` is:
+The substantive persona/instructions for an agent is `agents/<id>/charter.md`, served by `getAgentDetail()` (`engine/queries.js:847-850`) and read directly by `buildSystemPrompt()` before injection as `## Your Charter` (`engine/playbook.js:1084-1099`). The system prompt is:
 
 ```
 # You are {name} ({role})
@@ -84,7 +86,7 @@ Expertise: {expertise joined}
 ## Your Charter
 {charter.md contents}
 ```
-(`engine/playbook.js:940-955`)
+(`engine/playbook.js:1084-1099`)
 
 Charter is already editable today, but only from the **agent detail panel → Charter tab** (`dashboard/js/detail-panel.js:115-126`) via `POST /api/agents/charter` (`dashboard.js:13205-13211`). It is disconnected from the Settings → Agents table.
 
@@ -97,9 +99,9 @@ Charter is already editable today, but only from the **agent detail panel → Ch
 ### 2.6 Config read / write surface
 
 - **Read:** `queries.getConfig()` (`engine/queries.js:181-225`); Settings read endpoint returns `{ engine, claude, agents, projects, routing }` (`dashboard.js:10362-10391`).
-- **Write:** `POST /api/settings` edits `engine`, `claude`, **existing** `agents[id]` (role, skills, cli, model, budget — `dashboard.js:10682-10705`; **note: `name` is NOT editable today**), and projects, then saves `config.json`. **There is no agent create/delete/rename path** — the loop `for (const [id, updates] of Object.entries(body.agents))` skips unknown ids (`dashboard.js:10683`).
-- **Reset:** restores `engine` defaults + `shared.DEFAULT_AGENTS` (`dashboard.js:10808-10815`).
-- **UI:** Settings → Runtime pane has an **edit-only** Agents table (Role, Skills, CLI, Model, Budget) — `dashboard/js/settings.js:152-157`. No add/remove/rename.
+- **Write:** `POST /api/settings` edits `engine`, `claude`, **existing** `agents[id]` (role, expertise, cli, model, budget — `dashboard.js:11242-11262`; **note: `name` is NOT editable today**), and projects, then saves `config.json`. Legacy `skills` input is normalized to `expertise`; unknown ids are skipped.
+- **Reset:** restores `engine` defaults + `shared.DEFAULT_AGENTS` (`dashboard.js:11434-11440`).
+- **UI:** Settings → Runtime pane has an **edit-only** Agents table (Role, Expertise, CLI, Model, Budget). No add/remove/rename.
 
 ### 2.7 Gaps summary
 
@@ -110,7 +112,7 @@ Charter is already editable today, but only from the **agent detail panel → Ch
 | Reuse one charter across many agents | ✗ (each agent has its own `charter.md`) |
 | Edit a role's charter from the library/settings | ✗ (only the per-agent detail panel) |
 | Rename an agent's display name (+ emoji) | ✗ |
-| `expertise` field named for what it is | ✗ (called `skills`, overloaded) |
+| `expertise` field named for what it is | ✓ (`skills` retained only as a read-compat alias) |
 | Add a new role | ✗ |
 | Add a new named agent | ✗ |
 | Delete an agent | ✗ |
@@ -119,7 +121,7 @@ Charter is already editable today, but only from the **agent detail panel → Ch
 
 > **Summary — full treatment in [`agent-rename.md`](agent-rename.md) §2.**
 
-Agents are **already id-keyed**: every piece of agent-scoped state (charter file, per-agent memory, metrics, dispatch/PR records, inbox prefixes, routing) is keyed by the immutable `config.agents` **key**, never the display `name`. The only consumers of `name` are `buildSystemPrompt`'s `# You are {name}` line and dashboard display text. So the id is the stable handle the role model relies on (an agent can be renamed or reassigned to a different role without touching any id-keyed state), and it must never be mutated. The rename prerequisite formalizes this invariant with a guard + tests.
+Agents are **already id-keyed**: every piece of agent-scoped state (charter file, per-agent memory, metrics, dispatch/PR records, inbox prefixes, routing) is keyed by the immutable `config.agents` **key**, never the display `name`. The name is used for prompt/dashboard display and soft free-text matching in `resolveTaskContext()`, but never as a persistent key. So the id is the stable handle the role model relies on (an agent can be renamed or reassigned to a different role without touching any id-keyed state), and it must never be mutated. The rename prerequisite formalizes this invariant with a guard + tests.
 
 ## 3. Target model: the Role / Agent Library
 
@@ -227,7 +229,7 @@ Why this matters:
 - **Rename touches only the per-agent identity** (`name`/`emoji`); neither expertise nor the role charter is affected (§5.4).
 - **Two agents of one role share the durable charter but differ in the variable expertise.** Dallas and Ralph both resolve the Engineer charter, yet Dallas carries `typescript/docker` and Ralph `bug-fixes/scaffolding` — the payoff of the durable/variable split (§3).
 
-This formalizes what `buildSystemPrompt` already does loosely today (the `# You are {name}` / `Agent ID` / `Expertise` lines are a proto short-form; `engine/playbook.js:947-955`); the spec elevates it to named dimensions. Whether the short-form is rendered as prose lines or an explicit JSON card is an open question (§9).
+This formalizes what `buildSystemPrompt` already does loosely today (the `# You are {name}` / `Agent ID` / `Expertise` lines are a proto short-form; `engine/playbook.js:1092-1099`); the spec elevates it to named dimensions. Whether the short-form is rendered as prose lines or an explicit JSON card is an open question (§9).
 
 ## 4. Phase 0 — Prerequisite migrations
 
@@ -243,17 +245,17 @@ Register `agent-library` (§3.1). No behavior change yet — just the gate other
 
 The stable-id invariant (id = immutable key, name = display-only) and its guard + regression tests land in the rename prerequisite. The role model below assumes it: an agent can be reassigned to a different role or renamed without touching any id-keyed state (§2.8).
 
-### 4.2b Rename `skills` → `expertise`
+### 4.2b Rename `skills` → `expertise` — shipped
 
 `agent.skills` is expertise, not skills (§2.3). Rename the field across the stack, with an **unconditional** back-compat reader:
 
 - **Read shim (always on):** everywhere that reads agent expertise resolves `agent.expertise ?? agent.skills`. Old configs with `skills` keep working untouched — no disk rewrite forced. (Expertise is the per-agent **variable** layer, §3.3 — it lives on the agent, not the role.)
-- **Writers / defaults:** `DEFAULT_AGENTS` use `expertise`. The Settings write path persists `expertise`; if it sees a legacy `skills` key it may migrate it in-memory (mirroring `applyLegacyCcModelMigration`'s no-rewrite pattern).
-- **Update the two readers** named in §2.3: the `Expertise:` line (`engine/playbook.js:950`) and `pickReReviewAgentHints` (`engine/lifecycle.js:4613-4624`) — both read the resolved expertise, so the soft reviewer-preference heuristic keeps matching `code-review`/`design-review`.
-- **Dashboard:** the Agents table column header and its read/write (`dashboard/js/settings.js:73`, `dashboard.js:10685`) move to `expertise`, accepting `skills` on read for compatibility.
-- **Deprecation:** add a `docs/deprecated.json` entry for the `skills` alias with a cleanup path.
+- **Writers / defaults:** `DEFAULT_AGENTS` use `expertise`. The Settings write path accepts legacy `skills`, persists the value as `expertise`, and deletes the old key.
+- **Readers:** the `Expertise:` line (`engine/playbook.js:1094`), `pickReReviewAgentHints` (`engine/lifecycle.js:5311-5321`), and `getAgents` (`engine/queries.js:830-832`) all prefer `expertise` and tolerate `skills`.
+- **Dashboard:** the Agents table uses `expertise` (`dashboard/js/settings.js:73`); settings writes normalize legacy `skills` input to `expertise` (`dashboard.js:11245-11252`).
+- **Deprecation:** `docs/deprecated.json` tracks the compatibility alias and its removal gate.
 
-This rename is independent of the role model and can ship first; it is pure renaming + a back-compat alias, so it is safe even with the feature flag OFF (the alias is unconditional).
+This rename shipped independently of the role model. Cleanup remains gated by the deprecation tracker; the alias is unconditional while it exists.
 
 ### 4.3c Name-agnostic charters — *delivered by the prerequisite*
 
@@ -276,7 +278,7 @@ All UI/API in this phase is gated by `agent-library` (§3.1). The **rename** cap
 
 ### 5.2 Data model (Phase 1)
 
-- Add `DEFAULT_ROLES` to `engine/shared.js`, one per distinct `role` label in `DEFAULT_AGENTS` (`Lead / Explorer`, `Engineer`, `Analyst`, `Architect`). Author each role's **durable `charter`** name-agnostic (§4.3c), seeded from the sanitized union of the corresponding agents' existing `charter.md` files. Each agent's current per-agent skills become its **`expertise`** (the variable layer), so two Engineers keep distinct specializations while sharing one role charter. (Where two agents of the same label have materially different *personas* today, split them into two roles instead — but the default four collapse cleanly.)
+- Add `DEFAULT_ROLES` to `engine/shared.js`, one per distinct `role` label in `DEFAULT_AGENTS` (`Lead / Explorer`, `Engineer`, `Analyst`, `Architect`). Author each role's **durable `charter`** name-agnostic (§4.3c), seeded from the sanitized union of the corresponding agents' existing `charter.md` files. Each agent keeps its current per-agent **`expertise`** (the variable layer), so two Engineers retain distinct specializations while sharing one role charter. (Where two agents of the same label have materially different *personas* today, split them into two roles instead — but the default four collapse cleanly.)
 - Migrate `agent.role` free-text → role key on first load (in-memory, mirroring `applyLegacyCcModelMigration`'s no-disk-rewrite pattern) by slugifying the label and matching against `roles{}`. Unmatched strings remain legacy free text rendered as an ad-hoc role.
 - Resolution rules (§3) sit behind the existing resolver helpers and the feature flag so engine behavior is unchanged when `roles` is absent or the flag is OFF.
 
@@ -319,7 +321,7 @@ The agent **rename** capability (`POST /api/agents/rename` → `{ id, name, emoj
 ## 6. Migration & backward compatibility
 
 - **Feature-flagged & dark by default.** New surfaces are OFF until `agent-library` is enabled (§3.1). Back-compat readers are unconditional so toggling the flag off after edits never breaks a fleet.
-- **Additive config.** `roles` (with `charter`) and agent `expertise` are new and optional. Absent ⇒ legacy path (free-text role, `skills`, per-agent `charter.md`). No forced disk rewrite — migration is in-memory at load, matching `applyLegacyCcModelMigration`.
+- **Additive config.** `roles` (with `charter`) is new and optional. Absent ⇒ legacy path (free-text role, per-agent `expertise` with the `skills` read alias, per-agent `charter.md`). No forced role-model disk rewrite — migration is in-memory at load, matching `applyLegacyCcModelMigration`.
 - **`skills` alias preserved.** Reads resolve `agent.expertise ?? agent.skills`; legacy configs are untouched (§4.2b).
 - **Charters preserved.** `agents/<id>/charter.md` remains readable as the **lowest-priority** charter source (used only when an agent's role has no charter). `minions init`/upgrade already preserves charter files (`bin/minions.js:1361-1368`) — do not regress that.
 - **Name decoupling via the prerequisite.** Name-agnostic charters and the stable-id invariant ship in [`agent-rename.md`](agent-rename.md) (§4.1a, §4.3c). This Library assumes them: role charters are shared name-agnostic prose, and agents are reassigned/renamed without re-keying any state. Legacy user charters with names render verbatim (non-breaking).
@@ -383,7 +385,7 @@ Flag-gated like Phase 1.
 3. **"Charter" terminology** — the spec uses **`charter`** as the durable role-level field name (matching today's `charter.md` and the existing Charter tab). Confirm we keep "charter" user-facing everywhere rather than introducing "definition" as a competing term. *(Tentatively resolved: yes, `charter` on the role; "definition" used only as the generic English word.)*
 4. **Expertise→skill enrichment (§5.3)** — ship the "tag matches discovered SKILL.md → inline description" behavior in P1, or keep expertise purely as the `Expertise:` line until later?
 5. **Default role charters** — author fresh name-agnostic role charters, or mechanically sanitize + merge the existing per-agent `charter.md` files? And how to handle two builtin agents sharing a label but differing in persona today (split into two roles vs. unify)?
-6. **`skills`→`expertise` rollout** — ship the §4.2b rename as its own standalone PR (pure rename + alias, flag-independent) ahead of the Library, to de-risk the bigger change?
+6. **`skills`→`expertise` rollout** — resolved: shipped independently with an unconditional compatibility alias tracked in `docs/deprecated.json`.
 7. **Identity rendering (§3.3)** — render the per-agent short-form as the existing prose lines (`# You are …` / `Agent ID` / `Expertise`), or also emit a compact machine-readable JSON identity card the agent can parse to reason about itself? (Prose is the lowest-risk default; JSON is additive.)
 
 ## 10. Work breakdown (suggested PRD seeds)
@@ -393,7 +395,7 @@ Flag-gated like Phase 1.
 
 **Phase 0 — prerequisites (owned here)**
 - P0-a: Register `agent-library` feature flag (`engine/features.js`) + Settings toggle.
-- P0-b: Rename `skills`→`expertise` with unconditional back-compat alias; update `playbook.js:950`, `lifecycle.js:4613-4624`, `dashboard.js`/`settings.js`, `DEFAULT_AGENTS`; `docs/deprecated.json` entry.
+- P0-b: **Shipped** — `skills`→`expertise` with an unconditional back-compat alias across playbook, lifecycle, queries, Settings, defaults, and `docs/deprecated.json`.
 
 **Phase 1 — expose & edit**
 - P1-a: `DEFAULT_ROLES` (durable charter per role) + per-agent `expertise` (variable) + in-memory legacy role migration + role-tier resolver (engine/shared.js, playbook.js), flag-gated. Seeds role charters from the prerequisite's sanitized `agents/<id>/charter.md`.
@@ -409,4 +411,4 @@ Flag-gated like Phase 1.
 
 ---
 
-_Every new `engine.*`/config surface introduced here must also get a dashboard control and be documented in CLAUDE.md — config without UI is incomplete (see CLAUDE.md "Best Practices" #15). New feature flags follow the FEATURES-registry lifecycle: register with `addedIn`/`expires`, gate, then delete the entry + gates on graduation._
+_Every new `engine.*`/config surface introduced here must also get a dashboard control and be documented in CLAUDE.md — config without UI is incomplete (see CLAUDE.md "Best Practices" #9). New feature flags follow the FEATURES-registry lifecycle: register with `addedIn`/`expires`, gate, then delete the entry + gates on graduation._

package/docs/specs/agent-rename.md

@@ -25,13 +25,13 @@ Citations are `file:line` against the repo at spec-authoring time.
 
 ### 2.1 Agents are already id-keyed
 
-Agents live under `config.agents` keyed by a **stable lowercase id** (the object key). `name` is a **separate display field** — there is no explicit `id` field inside the object; the key *is* the id, and `getAgents()` materializes it as `{ id, ...info }` (`engine/queries.js:681-687`).
+Agents live under `config.agents` keyed by a **stable lowercase id** (the object key). `name` is a **separate display field** — there is no explicit `id` field inside the object; the key *is* the id, and `getAgents()` materializes it as `{ id, ...info }` (`engine/queries.js:764`).
 
 ```js
-// engine/shared.js:4398-4404
+// engine/shared.js:4728-4734
 const DEFAULT_AGENTS = {
-  ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', skills: [...] },
-  dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        skills: [...] },
+  ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', expertise: [...] },
+  dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        expertise: [...] },
   // …
 };
 ```
@@ -42,7 +42,7 @@ Crucially, **nothing derives the id from the name** — `id === lowercase(name)`
 
 | State | Keyed by id at |
 |-------|----------------|
-| Charter file | `agents/<id>/charter.md` (`engine/queries.js:677-679`) |
+| Charter file | `agents/<id>/charter.md` (`engine/queries.js:847-850`) |
 | Per-agent memory | `knowledge/agents/<id>.md`; inbox routes by `agent:` frontmatter → filename prefix (`engine/consolidation.js:106-129,159-182`) |
 | Metrics / spend / error rate | `metrics[id]`, `perAgent[id]` (`engine/routing.js:66-92`) |
 | Dispatch records | `dispatch.active[].agent` (`engine/queries.js:587-605`) |
@@ -50,12 +50,12 @@ Crucially, **nothing derives the id from the name** — `id === lowercase(name)`
 | Inbox files | `notes/inbox/<id>-…` filename prefix (`engine/queries.js:700-713`) |
 | Routing | preferred/fallback agent ids (`routing.md`, `engine/routing.js:31-52`) |
 
-The **only** consumers of the display `name` are `buildSystemPrompt`'s `# You are {name}` line (`engine/playbook.js:947-950`) and dashboard display text. So renaming the display name is safe and needs no state migration **as long as the id key is never mutated**. Changing the id key would orphan every row above — the id must be immutable.
+The display `name` is consumed by `buildSystemPrompt`, dashboard text, and the soft free-text matcher in `resolveTaskContext()` (§2.3), but no persistent state is keyed by it. So renaming the display name is safe and needs no state migration **as long as the id key is never mutated**. Changing the id key would orphan every row above — the id must be immutable.
 
 ### 2.3 Names are load-bearing in two places (the part that must change)
 
 1. **Charters hardcode names.** The shipped charters bake the agent's own name and peers' names into the prose — e.g. `agents/ripley/charter.md` opens `# Ripley — Lead / Explorer`, `**Name:** Ripley`, and says "Handing off structured findings to **Dallas** (Engineer) and **Lambert** (Analyst)". A rename would strew the old name through the prompt.
-2. **Playbook context-resolution matches by name.** `engine/playbook.js:163-240` matches referenced plans/notes by **both** agent `id` **and** `name` (e.g. "Ripley's plan"). After a rename, artifacts that referenced the old *name* stop auto-linking (id-based matches still resolve).
+2. **Playbook context-resolution matches by name.** `resolveTaskContext()` (`engine/playbook.js:171-256`) matches referenced plans/notes by agent `id` and display `name` (e.g. "Ripley's plan"). After a rename, artifacts that referenced the old *name* stop auto-linking (id-based matches still resolve).
 
 These are the two reasons "names are load-bearing" — §4.2 and §4.3 neutralize them.
 
@@ -83,7 +83,7 @@ Agents are **already** id-keyed (§2.1–2.2); this step makes the invariant exp
 
 A charter that hardcodes a proper name (§2.3) breaks the moment an agent is renamed (and later blocks a role-level charter being shared across agents — the configurability payoff). Make the charter body **name-agnostic** so the identity line is the single source of the name:
 
-- **Single source of name.** The agent's name appears *only* in the engine-injected `# You are {name} ({label})` block (`engine/playbook.js:947-950`). The charter prose must use the **second person** ("you", "your") and **never** restate its own proper name (no `# Ripley`, no `**Name:** Ripley`). The agent still knows its name — it reads it from the identity block — so **name-agnostic ≠ name-blind**.
+- **Single source of prompt identity.** The agent's name appears in the engine-injected `# You are {name} ({label})` block (`engine/playbook.js:1092-1094`). The charter prose must use the **second person** ("you", "your") and **never** restate its own proper name (no `# Ripley`, no `**Name:** Ripley`). The agent still knows its name — it reads it from the identity block — so **name-agnostic ≠ name-blind**.
 - **Refer to peers by role, not name.** "hand off to **Dallas** (Engineer)" becomes "hand off to the **Engineer** role" — roles are stable; names are mutable. This keeps a charter valid when *any* agent is renamed.
 - **Rewrite the shipped defaults.** Sanitize the repo's `agents/<id>/charter.md` files name-agnostic. (The configurability spec later seeds role charters from these — but the sanitization lands here, unconditionally.)
 - **Legacy user charters are not auto-rewritten.** A user-authored `charter.md` that still contains a name renders verbatim (back-compat, non-breaking) — it just reads stale after a rename. A **soft, dismissible warning** flags a name embedded in an editable charter, nudging toward second person / role references. No hard block, no silent rewrite of user content.
@@ -100,7 +100,7 @@ A rename changes the agent's **display identity** (`name`, and optionally `emoji
 - **Concurrency & audit:** writes through `mutateJsonFileLocked` on `config.json` (never `safeWrite`); logs `old → new`.
 
 **What updates (display only, picked up live)**
-- The system-prompt identity line `# You are {name} ({label})` on the **next** dispatch (`engine/playbook.js:947-950`).
+- The system-prompt identity line `# You are {name} ({label})` on the **next** dispatch (`engine/playbook.js:1092-1094`).
 - Dashboard display: team cards, agent detail panel, history attribution, Command Center state preamble — all read `name` live on next render.
 - The rename invalidates the system-prompt / status / CC-preamble caches so the new name surfaces promptly.
 
@@ -113,7 +113,7 @@ A rename changes the agent's **display identity** (`name`, and optionally `emoji
 
 **Stale name references in historical free-text (known, accepted, non-breaking)**
 - Rename does **not** cascade into pre-existing free-text: `notes.md`, `pinned.md`, the knowledge base, per-agent memory, and plan/PRD prose keep the old name (non-breaking — just stale).
-- Concrete engine consequence (§2.3): playbook context-resolution matches referenced plans/notes by both `id` and `name` (`engine/playbook.js:163-240`); after a rename, old-name artifacts stop auto-linking to the agent (id matches still resolve). §4.2's guidance minimizes future name-baking.
+- Concrete engine consequence (§2.3): playbook context-resolution matches referenced plans/notes by both `id` and `name` (`engine/playbook.js:171-256`); after a rename, old-name artifacts stop auto-linking to the agent (id matches still resolve). §4.2's guidance minimizes future name-baking.
 - A **soft, non-blocking** "old name still appears in N place(s)" hint may follow a rename; it **never** auto-rewrites user/historical content.
 
 **UI**
@@ -126,7 +126,7 @@ A rename changes the agent's **display identity** (`name`, and optionally `emoji
 - **Stable id.** The id key is immutable; rename touches `name`/`emoji` only. No agent state is re-keyed.
 - **Charters preserved.** `agents/<id>/charter.md` remains the charter source. `minions init`/upgrade already preserves charter files (`bin/minions.js:1361-1368`) — do not regress that. Legacy user charters with names render verbatim and only earn a soft warning.
 - **Routing unaffected.** Routing targets agent ids; rename is invisible to it.
-- **No `name` writer today is broken.** `POST /api/settings` does not edit `name` (`dashboard.js:10672-10758`); the new rename endpoint is the sole `name` writer.
+- **No `name` writer today is broken.** `POST /api/settings` edits existing agent fields but not `name` (`dashboard.js:11242-11268`); the new rename endpoint is the sole `name` writer.
 
 ## 6. Acceptance criteria
 
@@ -142,7 +142,7 @@ A rename changes the agent's **display identity** (`name`, and optionally `emoji
 
 - **Re-keying an agent id.** Rename changes `name`/`emoji` only; there is no change-id path (§4.1).
 - **The Role / Agent Library** itself (roles, durable charters, expertise field, CRUD) — see [`agent-configurability.md`](agent-configurability.md), which depends on this spec.
-- **`skills`→`expertise` field rename** — a separate cleanup owned by the configurability spec.
+- **`skills`→`expertise` field rename** — shipped separately under the configurability spec; it is not part of the rename feature.
 - **Cascading a rename into historical free-text** (notes/KB/memory/plans). Non-goal; only a soft hint is offered.
 
 ## 8. Work breakdown (suggested PRD seeds)
@@ -160,4 +160,4 @@ This spec is a **hard prerequisite** for [`agent-configurability.md`](agent-conf
 
 ---
 
-_Every new config surface here must also get a dashboard control and be documented in CLAUDE.md — config without UI is incomplete (CLAUDE.md "Best Practices" #15). The `agent-rename` flag follows the FEATURES-registry lifecycle: register with `addedIn`/`expires`, gate, then delete the entry + gate on graduation._
+_Every new config surface here must also get a dashboard control and be documented in CLAUDE.md — config without UI is incomplete (CLAUDE.md "Best Practices" #9). The `agent-rename` flag follows the FEATURES-registry lifecycle: register with `addedIn`/`expires`, gate, then delete the entry + gate on graduation._