@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/specs/agent-configurability.md

@@ -35,10 +35,10 @@ 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:764-845`). 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/core/queries.js:764-845`). Defaults are hard-coded:
 
 ```js
-// engine/shared.js:4728-4734
+// engine/core/shared.js:4728-4734
 const DEFAULT_AGENTS = {
   ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', expertise: ['architecture', 'codebase-exploration', 'design-review'] },
   dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        expertise: ['implementation', 'typescript', 'docker', 'testing'] },
@@ -48,9 +48,9 @@ const DEFAULT_AGENTS = {
 };
 ```
 
-Crucially, **nothing derives the id from the name** — `id === lowercase(name)` is coincidental, not enforced. Routing only lowercases routing-table cells, not names (`engine/routing.js:31-52`); agent lookup is by key with case-insensitive normalization against existing keys (`engine/routing.js:160-189`). So `name !== lowercase(id)` is already safe. This is the foundation that makes **rename = change `name`, keep `id`** trivial (see §2.8; full treatment in [`agent-rename.md`](agent-rename.md)).
+Crucially, **nothing derives the id from the name** — `id === lowercase(name)` is coincidental, not enforced. Routing only lowercases routing-table cells, not names (`engine/orchestration/routing.js:31-52`); agent lookup is by key with case-insensitive normalization against existing keys (`engine/orchestration/routing.js:160-189`). So `name !== lowercase(id)` is already safe. This is the foundation that makes **rename = change `name`, keep `id`** trivial (see §2.8; full treatment in [`agent-rename.md`](agent-rename.md)).
 
-Runtime / budget fields are **optional per-agent overrides** resolved against `engine.*` fleet defaults via helpers in `engine/shared.js`:
+Runtime / budget fields are **optional per-agent overrides** resolved against `engine.*` fleet defaults via helpers in `engine/core/shared.js`:
 
 | Field | Resolver | Falls back to |
 |-------|----------|---------------|
@@ -68,15 +68,15 @@ Runtime / budget fields are **optional per-agent overrides** resolved against `e
 Two unrelated concepts previously shared the word "skill"; Phase 0b made `agent.expertise` canonical while retaining `agent.skills` as a compatibility alias:
 
 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.
+   - **Display:** the `Expertise: …` line in the system prompt (`engine/agents/playbook.js:1094`).
+   - **Soft routing:** `pickReReviewAgentHints()` (`engine/orchestration/lifecycle.js:5311-5321`) prefers agents tagged `code-review` / `design-review`.
+2. **Real `SKILL.md` files** — discovered from disk by `collectSkillFiles()` / `getSkills()` (`engine/core/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.
 
 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`, 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:
+The substantive persona/instructions for an agent is `agents/<id>/charter.md`, served by `getAgentDetail()` (`engine/core/queries.js:847-850`) and read directly by `buildSystemPrompt()` before injection as `## Your Charter` (`engine/agents/playbook.js:1084-1099`). The system prompt is:
 
 ```
 # You are {name} ({role})
@@ -86,7 +86,7 @@ Expertise: {expertise joined}
 ## Your Charter
 {charter.md contents}
 ```
-(`engine/playbook.js:1084-1099`)
+(`engine/agents/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.
 
@@ -94,11 +94,11 @@ Charter is already editable today, but only from the **agent detail panel → Ch
 
 ### 2.5 Routing
 
-`routing.md` is a markdown table mapping work-type → preferred/fallback **agent id** (`routing.md:8-27`), parsed by `engine/routing.js:31-52`. `resolveAgent()` (`engine/routing.js:192`) resolves the route, honoring `_author_` / `_any_` tokens, idleness, budget, and the self-review ban. Routing is edited via `POST /api/settings/routing`, which overwrites `routing.md` wholesale (`dashboard.js:10799-10805`).
+`routing.md` is a markdown table mapping work-type → preferred/fallback **agent id** (`routing.md:8-27`), parsed by `engine/orchestration/routing.js:31-52`. `resolveAgent()` (`engine/orchestration/routing.js:192`) resolves the route, honoring `_author_` / `_any_` tokens, idleness, budget, and the self-review ban. Routing is edited via `POST /api/settings/routing`, which overwrites `routing.md` wholesale (`dashboard.js:10799-10805`).
 
 ### 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`).
+- **Read:** `queries.getConfig()` (`engine/core/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, 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.
@@ -182,7 +182,7 @@ The **durable** persona resolves entirely from the role; the **variable** expert
 
 A single registry flag gates everything user-visible in this spec:
 
-- Register `agent-library` in the `FEATURES` registry (`engine/features.js`) as `{ description, default: false, addedIn, expires }`.
+- Register `agent-library` in the `FEATURES` registry (`engine/core/features.js`) as `{ description, default: false, addedIn, expires }`.
 - **Engine** gates new behavior with `features.isFeatureOn('agent-library', config)`; **dashboard JS** gates new UI with `MinionsFeatures.isOn('agent-library')`.
 - Toggle via Settings → Experimental flags, `config.features['agent-library']: true`, or `MINIONS_FEATURE_AGENT_LIBRARY=1`. Resolution order: env → `config.features` → registry default (default OFF).
 - **What the flag gates:** the Library page/API (`/api/roles*`), agent rename UI, role/agent CRUD UI, and the role-tier resolution layer.
@@ -229,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: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).
+This formalizes what `buildSystemPrompt` already does loosely today (the `# You are {name}` / `Agent ID` / `Expertise` lines are a proto short-form; `engine/agents/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
 
@@ -251,7 +251,7 @@ The stable-id invariant (id = immutable key, name = display-only) and its guard
 
 - **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 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`.
+- **Readers:** the `Expertise:` line (`engine/agents/playbook.js:1094`), `pickReReviewAgentHints` (`engine/orchestration/lifecycle.js:5311-5321`), and `getAgents` (`engine/core/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.
 
@@ -278,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 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.)
+- Add `DEFAULT_ROLES` to `engine/core/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.
 
@@ -343,7 +343,7 @@ Flag-gated like Phase 1.
 ### 7.2 Data model / engine
 
 - New agent ids validated: lowercase slug, unique, not colliding with `temp-*` reserved prefix, and **immutable thereafter** (§2.8).
-- `resolveAgent` already iterates `config.agents` generically, so new agents are picked up with no engine change (`engine/routing.js:192-249`). Deleting an agent must also cancel/skip pending dispatches targeting it and leave its history intact (mirror the conservative posture of project removal in `engine/projects.js`).
+- `resolveAgent` already iterates `config.agents` generically, so new agents are picked up with no engine change (`engine/orchestration/routing.js:192-249`). Deleting an agent must also cancel/skip pending dispatches targeting it and leave its history intact (mirror the conservative posture of project removal in `engine/planning/projects.js`).
 - A new agent with no `charter.md` inherits its role's **durable charter** automatically — the payoff of §3 — and carries its own **variable expertise**.
 
 ### 7.3 API (Phase 2)
@@ -394,11 +394,11 @@ Flag-gated like Phase 1.
 - Stable-id formalization, name-agnostic charters, and the `POST /api/agents/rename` capability ship there (its `AR-a…AR-f` breakdown). This Library's Phase 1 depends on it.
 
 **Phase 0 — prerequisites (owned here)**
-- P0-a: Register `agent-library` feature flag (`engine/features.js`) + Settings toggle.
+- P0-a: Register `agent-library` feature flag (`engine/core/features.js`) + Settings toggle.
 - 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`.
+- P1-a: `DEFAULT_ROLES` (durable charter per role) + per-agent `expertise` (variable) + in-memory legacy role migration + role-tier resolver (engine/core/shared.js, playbook.js), flag-gated. Seeds role charters from the prerequisite's sanitized `agents/<id>/charter.md`.
 - P1-b: `GET /api/roles`, `POST /api/roles/update` (charter/label/runtime), agent `expertise`/`role` on `POST /api/settings` (dashboard.js). (Rename endpoint comes from the prerequisite.)
 - P1-c: Library UI (role list + role-charter editor + nested agents with per-agent expertise chips + role reassignment + inline rename surfacing the prerequisite's endpoint) reusing the charter editor pattern, flag-gated.
 - P1-d: Tests (resolver, durable/variable split, source-inspection) + `docs/deprecated.json` updates + settings-parity note in CLAUDE.md.

package/docs/specs/agent-rename.md

@@ -25,10 +25,10 @@ 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:764`).
+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/core/queries.js:764`).
 
 ```js
-// engine/shared.js:4728-4734
+// engine/core/shared.js:4728-4734
 const DEFAULT_AGENTS = {
   ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', expertise: [...] },
   dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        expertise: [...] },
@@ -36,32 +36,32 @@ const DEFAULT_AGENTS = {
 };
 ```
 
-Crucially, **nothing derives the id from the name** — `id === lowercase(name)` is coincidental, not enforced. Routing only lowercases routing-table cells, not names (`engine/routing.js:31-52`); agent lookup is by key with case-insensitive normalization against existing keys (`engine/routing.js:160-189`). So `name !== lowercase(id)` is already safe — the foundation that makes **rename = change `name`, keep `id`** trivial.
+Crucially, **nothing derives the id from the name** — `id === lowercase(name)` is coincidental, not enforced. Routing only lowercases routing-table cells, not names (`engine/orchestration/routing.js:31-52`); agent lookup is by key with case-insensitive normalization against existing keys (`engine/orchestration/routing.js:160-189`). So `name !== lowercase(id)` is already safe — the foundation that makes **rename = change `name`, keep `id`** trivial.
 
 ### 2.2 Every agent-scoped state is keyed by id
 
 | State | Keyed by id at |
 |-------|----------------|
-| 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`) |
-| PR records | `pr.agent` (`engine/queries.js:431-446`) |
-| Inbox files | `notes/inbox/<id>-…` filename prefix (`engine/queries.js:700-713`) |
-| Routing | preferred/fallback agent ids (`routing.md`, `engine/routing.js:31-52`) |
+| Charter file | `agents/<id>/charter.md` (`engine/core/queries.js:847-850`) |
+| Per-agent memory | `knowledge/agents/<id>.md`; inbox routes by `agent:` frontmatter → filename prefix (`engine/memory/consolidation.js:106-129,159-182`) |
+| Metrics / spend / error rate | `metrics[id]`, `perAgent[id]` (`engine/orchestration/routing.js:66-92`) |
+| Dispatch records | `dispatch.active[].agent` (`engine/core/queries.js:587-605`) |
+| PR records | `pr.agent` (`engine/core/queries.js:431-446`) |
+| Inbox files | `notes/inbox/<id>-…` filename prefix (`engine/core/queries.js:700-713`) |
+| Routing | preferred/fallback agent ids (`routing.md`, `engine/orchestration/routing.js:31-52`) |
 
 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.** `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).
+2. **Playbook context-resolution matches by name.** `resolveTaskContext()` (`engine/agents/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.
 
 ## 3. Feature flag
 
-- Register `agent-rename` in the `FEATURES` registry (`engine/features.js`) as `{ description, default: false, addedIn, expires }`.
+- Register `agent-rename` in the `FEATURES` registry (`engine/core/features.js`) as `{ description, default: false, addedIn, expires }`.
 - **Engine/dashboard** gate the rename **endpoint + UI** with `features.isFeatureOn('agent-rename', config)` / `MinionsFeatures.isOn('agent-rename')`.
 - Toggle via Settings → Experimental flags, `config.features['agent-rename']: true`, or `MINIONS_FEATURE_AGENT_RENAME=1`. Resolution order: env → `config.features` → registry default (default OFF).
 - **What the flag gates:** the `POST /api/agents/rename` endpoint and the rename UI affordance.
@@ -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 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**.
+- **Single source of prompt identity.** The agent's name appears in the engine-injected `# You are {name} ({label})` block (`engine/agents/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,20 +100,20 @@ 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:1092-1094`).
+- The system-prompt identity line `# You are {name} ({label})` on the **next** dispatch (`engine/agents/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.
 
 **What does NOT change (id-keyed, untouched — §2.2)**
 - Charter/memory paths, metrics/spend/error-rate buckets, dispatch records, PR `agent` refs, inbox prefixes, routing.
-- **Author matching is id-based:** `_author_` routing resolves to the author *agent id* and `pr.agent` groups by id (`engine/queries.js:431-446`), so rename never breaks self-review bans or PR-author follow-ups.
+- **Author matching is id-based:** `_author_` routing resolves to the author *agent id* and `pr.agent` groups by id (`engine/core/queries.js:431-446`), so rename never breaks self-review bans or PR-author follow-ups.
 
 **In-flight dispatches**
 - A currently-running agent finishes under the system prompt it was **already spawned with** — rename does **not** kill or re-spawn it. The new name applies to the **next** dispatch. Live-output, completion reports, and history are id-keyed, so they attribute correctly throughout.
 
 **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: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.
+- Concrete engine consequence (§2.3): playbook context-resolution matches referenced plans/notes by both `id` and `name` (`engine/agents/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**
@@ -147,8 +147,8 @@ A rename changes the agent's **display identity** (`name`, and optionally `emoji
 
 ## 8. Work breakdown (suggested PRD seeds)
 
-- AR-a: Register `agent-rename` feature flag (`engine/features.js`) + Settings toggle.
-- AR-b: Formalize stable-id invariant + rename-safety guard + regression tests (`engine/shared.js`, `engine/queries.js`, tests). *(Unconditional.)*
+- AR-a: Register `agent-rename` feature flag (`engine/core/features.js`) + Settings toggle.
+- AR-b: Formalize stable-id invariant + rename-safety guard + regression tests (`engine/core/shared.js`, `engine/core/queries.js`, tests). *(Unconditional.)*
 - AR-c: Sanitize shipped `agents/<id>/charter.md` to be name-agnostic (second person, peers-by-role) + content test (no proper names) + post-rename render test. *(Unconditional.)*
 - AR-d: `POST /api/agents/rename` (full §4.3 contract: name+emoji, validation, idempotency, duplicate-warning, cache invalidation, in-flight safety, audit log) — flag-gated.
 - AR-e: Rename UI in the Settings agents table / detail panel (inline validation + soft duplicate-name warning) — flag-gated; soft name-in-charter warning.

package/docs/team-memory.md

@@ -74,7 +74,7 @@ remain intentionally file-backed documents and coordination artifacts.
 ### Offline review-learning backfill
 
 `minions memory backfill-review-learnings [--dry-run] [--limit <N>] [--project <p>]`
-(module `engine/review-learning-backfill.js`) is a strict, offline recovery
+(module `engine/memory/review-learning-backfill.js`) is a strict, offline recovery
 command that reconstructs durable review-learning lessons from legacy artifacts
 (trusted completion artifacts + their dispatch context, tracked PR records,
 legacy feedback inbox/archive files, and migration-027 quarantined candidates).
@@ -290,7 +290,7 @@ project, agent, normalized area, disposition, work-item/dispatch references,
 compact metadata, and timestamp. Event replay is idempotent. Event pruning
 removes only old event rows and never deletes a memory record.
 
-The boundary in `engine/review-learning.js` redacts secret-shaped values and
+The boundary in `engine/memory/review-learning.js` redacts secret-shaped values and
 enforces these UTF-8/count limits:
 
 | Value | Limit |
@@ -335,7 +335,7 @@ IDs, hashes, reason codes, and bounded traces (never raw prompt/reviewer bodies)
   plus per-event-type counters for a finding/memory/project.
 - `GET /api/memory-records/rollout` returns the bounded rollout aggregates above.
 
-Retention is folded into the periodic `engine/cleanup.js` cadence and is
+Retention is folded into the periodic `engine/orchestration/cleanup.js` cadence and is
 deliberately decoupled from KB file TTL: unresolved review-learning candidates
 expire (`status: expired`) after 180 days; compact lifecycle events are pruned
 past one year and above the 50,000-row cap; active procedural lessons persist
@@ -345,7 +345,7 @@ record emits a `retracted`/`restored` lifecycle event for the operator timeline.
 
 ### Query construction and selection
 
-`engine/memory-retrieval.js` builds a task query from the work-item title,
+`engine/memory/memory-retrieval.js` builds a task query from the work-item title,
 description, work type, failure class, source plan, references, PR title, and PR
 branch. The SQL store:
 
@@ -373,7 +373,7 @@ dashboard's structured-memory search.
 ### Reserved deterministic review-lesson recall
 
 Review-learning records are recalled through a dedicated path that never depends
-on an FTS hit (`engine/memory-retrieval.js#retrieveApplicableReviewLearnings`),
+on an FTS hit (`engine/memory/memory-retrieval.js#retrieveApplicableReviewLearnings`),
 and they are **globally excluded** from the generic FTS pack
 (`searchMemoryRecords` drops `source_type='review-learning'` unless a caller
 passes `includeReviewLearning`, which only the operator dashboard search does).
@@ -389,22 +389,39 @@ project context, the path:
    scoping preventing any cross-project leak;
 3. derives normalized affected-file, symbol, and tag hints from the same task
    context (`deriveReviewFacetHints`, mirroring the capture-side normalization);
-4. ranks exact **symbol → file → tag** overlap first, then lexical relevance,
-   confidence, and recency, keeping only applicable lessons; and
+4. ranks exact **symbol → file → tag** overlap first, then **feature-branch
+   affinity** (descriptive tokens shared between the current dispatch's PR
+   branch / PR title and the lesson), then lexical relevance, confidence, and
+   recency, keeping only applicable lessons — so a lesson from a prior PR on the
+   same branch or feature outranks one that merely shares an incidental token;
+   and
 5. injects at most **4 records or 4 KiB** (independent of the generic memory
    budget) as a separately fenced `## Applicable Prior Review Lessons` section,
-   wrapped with `engine/untrusted-fence.js`.
+   wrapped with `engine/core/untrusted-fence.js`.
+
+For PR-authoring dispatches (every non read-only work type — implement, fix,
+test, verify, decompose, docs, review), the section is framed as an explicit
+**pre-PR checklist**: a trusted, un-fenced directive above the fenced lessons
+instructs the agent to confirm each recalled finding is addressed (or does not
+apply) against the live code before opening or updating the PR, and to record
+one `reviewLearningApplications` entry per lesson (`applied`,
+`considered-not-applicable`, or `contradicted`) in its completion report. Read-
+only dispatches (ask, explore, plan, meeting) open no PR and keep the plain
+informational framing. The checklist reuses the existing recalled-lesson
+selection and the `reviewLearningApplications` contract — no new payload or
+retrieval budget.
 
 Each run records bounded telemetry through `recordRetrievalRun` with
 `retrieval_kind='review-learning'`, the dispatch and work-item ids, selected
 record ids, per-record scores, and reason codes (`exact-symbol`, `exact-file`,
-`exact-tag`, `lexical`, `not-applicable`, `record-cap`, `byte-cap`) — never any
-prompt or comment body. Projectless Command Center / unrelated central work
-receive no section.
+record ids, per-record scores, and reason codes (`exact-symbol`, `exact-file`,
+`exact-tag`, `feature-branch`, `lexical`, `not-applicable`, `record-cap`,
+`byte-cap`) — never any prompt or comment body. Projectless Command Center /
+unrelated central work receive no section.
 
 ## Prompt assembly and fallback
 
-`engine/playbook.js` renders the requested playbook, adds shared rules, then
+`engine/agents/playbook.js` renders the requested playbook, adds shared rules, then
 appends memory context in this order:
 
 1. **Pinned Context**, when `pinned.md` is non-empty.
@@ -447,7 +464,7 @@ or XML-like wrapper overhead added to the final prompt.
 
 Memory content is evidence, not a new instruction channel. Before prompt
 insertion, pinned context, retrieved records, team notes, and personal memory
-are wrapped with `engine/untrusted-fence.js`:
+are wrapped with `engine/core/untrusted-fence.js`:
 
 ```text
 <UNTRUSTED-INPUT source="kind:provenance">...</UNTRUSTED-INPUT>
@@ -578,7 +595,7 @@ restart-ordering, or data cleanup is involved.
 ### Promotion into repository guidance
 
 A verified, **repeatedly observed** lesson can be promoted (human-approved) into
-guidance that vanilla runtimes discover natively (`engine/promotion.js`,
+guidance that vanilla runtimes discover natively (`engine/memory/promotion.js`,
 `POST /api/memory-records/<id>/promote`). Promotion is eligible only at confidence
 ≥ `0.8` and ≥ 2 distinct valid findings (the rule recurred at least once). It never
 edits an operator checkout: every promotion queues a normal project-bound work item
@@ -699,25 +716,25 @@ Markdown tiers are automatically copied into the prompt.
 
 ## Implementation map
 
-- [`engine/consolidation.js`](../engine/consolidation.js) - inbox digest,
+- [`engine/memory/consolidation.js`](../engine/memory/consolidation.js) - inbox digest,
   classification, personal routing, pruning, reconciliation, and summary.
 - [`engine/db/migrations/017-agent-memory.js`](../engine/db/migrations/017-agent-memory.js)
   - schema and one-time Markdown backfill.
 - [`engine/db/migrations/027-review-learning-lifecycle.js`](../engine/db/migrations/027-review-learning-lifecycle.js)
   - in-place retrieval/lifecycle schema extension and exact legacy-feedback
     quarantine.
-- [`engine/review-learning.js`](../engine/review-learning.js) - dispositions,
+- [`engine/memory/review-learning.js`](../engine/memory/review-learning.js) - dispositions,
   stable finding/area identities, redaction, bounds, record validation, event
   keys, and candidate transitions.
-- [`engine/memory-store.js`](../engine/memory-store.js) - record validation,
+- [`engine/memory/memory-store.js`](../engine/memory/memory-store.js) - record validation,
   lifecycle, FTS5 query, candidate/lesson helpers, bounded telemetry, and
   rollout aggregates.
-- [`engine/memory-retrieval.js`](../engine/memory-retrieval.js) - task query,
+- [`engine/memory/memory-retrieval.js`](../engine/memory/memory-retrieval.js) - task query,
   reranking, deduplication, provenance formatting, and byte packing.
-- [`engine/playbook.js`](../engine/playbook.js) - pinned/retrieved/legacy prompt
+- [`engine/agents/playbook.js`](../engine/agents/playbook.js) - pinned/retrieved/legacy prompt
   assembly and fallback.
-- [`engine/lifecycle.js`](../engine/lifecycle.js) - episodic completion capture.
-- [`engine/untrusted-fence.js`](../engine/untrusted-fence.js) - provenance fence
+- [`engine/orchestration/lifecycle.js`](../engine/orchestration/lifecycle.js) - episodic completion capture.
+- [`engine/core/untrusted-fence.js`](../engine/core/untrusted-fence.js) - provenance fence
   and UTF-8-safe truncation.
 - [`dashboard.js`](../dashboard.js) and
   [`dashboard/js/memory-search.js`](../dashboard/js/memory-search.js) -

package/docs/timeouts-and-liveness.md

@@ -4,25 +4,78 @@ What kills (or doesn't kill) a live agent. CLAUDE.md → Timeouts & Liveness
 keeps the core invariant; the spawn-phase watchdog, steering safety nets,
 and stale-orphan detection details live here.
 
-> Source of truth: `engine/timeout.js`, `engine/spawn-phase-watchdog.js`,
-> `engine/shared.js` (`ENGINE_DEFAULTS`, `getProcessCpuSeconds`,
-> `killImmediate`), `engine/steering-store.js`. See also:
-> [engine-restart.md](engine-restart.md). Last verified: 2026-06-09.
+> Source of truth: `engine/orchestration/timeout.js`, `engine/agents/spawn-phase-watchdog.js`,
+> `engine/core/shared.js` (`ENGINE_DEFAULTS`, `getProcessCpuSeconds`,
+> `terminateProcess`), `engine/persistence/steering-store.js`. See also:
+> [engine-restart.md](engine-restart.md). Last verified: 2026-07-29.
 
 ## Core invariant
 
 **A live tracked agent is never killed for being silent.** Long builds,
 installs, multi-file edits routinely produce no stdout for many minutes.
 
-Only two things kill a live tracked process (`engine/timeout.js`):
+Only two things terminate a live tracked process (`engine/orchestration/timeout.js`):
 
 1. **Hard wall-clock timeout** `engine.agentTimeout` (default 5h from
    `startedAt`; per-fan-out `meta.deadline`).
-2. **Steering kill** — explicit human steering → `killImmediate()` so the
-   agent re-spawns with `--resume <session>`.
+2. **Steering termination** — explicit human steering → the registered
+   tracked-process gateway so the agent re-spawns with `--resume <session>`.
 
 **Don't add output-silence timers for live tracked processes.**
 
+## Completion boundary: terminal exit + a dispatch-owned report (W-ms9tcs3o01y03383)
+
+The invariant above governs when a **live** agent may be killed. Its mirror
+image governs when a **finished** agent must be released: a dispatch is done the
+moment BOTH halves hold.
+
+1. The tracked child exited terminally and successfully (`code === 0` from the
+   `close` event, so exit is confirmed by construction), and
+2. a structurally valid completion report exists whose `nonce` proves it was
+   written by *this* dispatch (minted per spawn, carried across steering
+   resumes).
+
+`engine.js#resolveCloseCompletionBoundary` answers that question through the
+single shared trust predicate `shared.acceptCompletionReportForNonce`, which the
+resume-stall watchdog in `engine/orchestration/timeout.js` uses too. It **fails
+closed** on every other shape — non-zero exit, missing report, malformed report,
+missing or mismatched nonce — so no existing failure or timeout path is
+weakened.
+
+When the boundary holds, queued resume bookkeeping is **released, not spawned**
+(`engine.js#releasePendingSteeringResumeForCompletedTurn`). A completed turn can
+never produce the first-output heartbeat that a `--resume` spawn is waiting for,
+so starting one only parks the dispatch for a full
+`engine.resumeHeartbeatTimeout`. Real incident
+(`lambert-plan-to-prd-ms9skh2q01a91a35`): the agent finished at 03:19:20Z with a
+valid report on disk, the engine spawned a resume purely to deliver a deferred
+human steering message, and the dispatch did not terminalize until 03:24:32Z —
+310 seconds of pure bookkeeping.
+
+Releasing the resume does **not** drop the human's message. The steering files
+stay UNREAD on disk, so the agent's next dispatch picks them up through
+`steering.buildPendingSteeringPrompt` — the same durability contract as the
+no-sessionId `[steering-pending]` branch, and exactly what the operator was told
+when the message was deferred ("queued until the agent reaches a resumable
+checkpoint **or the next dispatch**").
+
+### Completion-path observability
+
+Completed dispatch records carry `completionPath`, drawn from the closed
+`shared.DISPATCH_COMPLETION_PATH` vocabulary, so the three outcomes stay
+distinguishable after the fact:
+
+| Value | Meaning |
+|-------|---------|
+| `process-close` | Normal completion: the close handler finalized the dispatch. |
+| `report-recovery-immediate` | Terminal exit + dispatch-owned report; queued resume bookkeeping was released instead of spawned. |
+| `output-detection` | Close event never reached the engine (restart/reattach); recovered from the `[process-exit]` sentinel. |
+| `resume-stall-report` | A **still-live** resume blew its heartbeat budget, but a dispatch-owned report proved the turn had succeeded. |
+| `resume-stall-timeout` | A still-live resume genuinely stalled with no durable evidence. |
+
+`resume-stall-*` now means what it says: a live resume that really did stall.
+A finished turn no longer masquerades as one.
+
 ## Stale-orphan detection
 
 `engine.heartbeatTimeout` (default 5 min) is the **grace window after the
@@ -48,9 +101,50 @@ Bypassed when `canReapDeadProcess` is true (confirmed-dead at restart).
 After engine restart, gated on `engineRestartGraceUntil` (default
 20 min) — see [engine-restart.md](engine-restart.md).
 
+Dispatches whose PID is positively dead at startup bypass that wait and are
+classified as `engine-restart`. They retry against a separate bounded
+infrastructure counter, so a daemon restart cannot exhaust the task's semantic
+agent retry budget.
+
+### Evidence gate: "unobservable" is not "dead" (W-ms6dmv99005o26f4)
+
+Every liveness observation is **tri-state** — alive, conclusively absent, or
+unobservable — and only *conclusive absence* may drive a destructive decision.
+Collapsing the third state into "dead" caused the fleet-wide false-orphan storm
+of 2026-07-29T17:44Z, where a dozen live dispatches were orphaned within ~10s
+(`Orphaned — no process, silent for 5s/6s/11s/12s/27s`) and had retries consumed
+and worktrees GC'd, while the agent processes were still running.
+
+| Probe | Helper | Conclusive absence | Unobservable |
+|-------|--------|--------------------|--------------|
+| `process.kill(pid, 0)` | `shared.inspectPidLiveness` | `ESRCH` | any other errno. `EPERM` means the kernel **found** the process and refused the signal → `alive: true` |
+| Fleet enumeration | `shared.captureProcessSnapshot` | a snapshot containing the observing process | `listAllProcesses()` threw, returned `[]`, or omitted `selfPid` → `{ ok: false }` |
+| Start-time identity | `shared.inspectProcessIdentity` | PID absent from a trusted snapshot | no usable snapshot, or the platform reported no creation time |
+| Command line | `shared.inspectProcessCommandLineForAgent` | a readable command line, or absence from a trusted snapshot | the per-PID probe threw or returned empty |
+
+Two decisions are gated on `conclusive`:
+
+- **Restart reattach** (`engine/operations/cli.js`). `evaluateReattachEvidence` still
+  *refuses* to reattach an unverified PID — that part is unchanged and must stay
+  fail-closed — but `shouldMarkConfirmedDeadAtRestart` only sets
+  `engineRestartGraceExempt` when the refusal was conclusive. An inconclusive
+  refusal falls back to the normal `minAliveBeforeOrphanMs` +
+  `engineRestartGraceUntil` window instead of orphaning on the next tick.
+- **Orphan cmdline cross-check** (`engine/orchestration/timeout.js`).
+  `evaluateLivePidCommandLine` demotes an alive OS PID to "dead" only on an
+  *observed* non-agent command line. A failed probe keeps the dispatch, exactly
+  as if the cross-check had not run. This link needs no engine restart at all — a
+  PowerShell/`ps` probe outage under fleet load was enough on its own.
+
+Genuine recycled PIDs, observed non-agent command lines, and `ESRCH` PIDs are
+still reaped immediately; the bounded grace window is unchanged. Boolean facades
+(`isPidAlive`, `isProcessCommandLineMatchingAgent`, `getProcessIdentity`) keep
+their historical "false/null == not known to be alive" contract, which leaves
+fail-closed kill guards such as `isRecordedAgentProcess` conservative.
+
 ## Steering safety nets (W-mq066js7000fff1f-c)
 
-Three knobs backstop the steering pipeline. `engine/timeout.js`
+Three knobs backstop the steering pipeline. `engine/orchestration/timeout.js`
 defensively requires `./steering-store` and swallows `MODULE_NOT_FOUND`
 only, so the gates work even before the store has shipped.
 
@@ -76,6 +170,20 @@ without a `sessionId` is **stranded** — `[steering-warn]` +
 `status='stranded'`. Re-warn is guarded by
 `_deferredSteeringStrandedFiles`.
 
+### Completed-turn resume release (W-ms9tcs3o01y03383)
+
+Checkpoint promotion is skipped entirely when the close handler's completion
+boundary holds (terminal exit 0 + dispatch-owned report). Any resume intent a
+live steering kill already staged (`_steeringMessage` / `_steeringSessionId` /
+`_steeringEntry` / `_steeringDeferredCheckpoint`) is cleared, rows already moved
+to `re_spawning` roll back to `queued`, and `[steering-pending]` is appended to
+`live-output.log`. The `_steeringNoSession` re-queue (#1014) is released the same
+way: re-queueing to `pending` is right for an agent interrupted mid-work and
+wrong for one that provably finished, because it discards a real success and
+re-runs completed work. The message files are never acked or deleted, so
+delivery moves to the agent's next dispatch instead of blocking terminalization.
+See [Completion boundary](#completion-boundary-terminal-exit--a-dispatch-owned-report-w-ms9tcs3o01y03383).
+
 ### Stale-session purge
 
 `onAgentClose` clears `session.json` on `No conversation found`.
@@ -91,7 +199,7 @@ dropped, please re-send.
 
 ## Spawn-phase watchdog (W-mq0e2dae000a003d)
 
-`engine/spawn-phase-watchdog.js#checkSpawnPhaseStalls` runs every tick
+`engine/agents/spawn-phase-watchdog.js#checkSpawnPhaseStalls` runs every tick
 alongside `checkTimeouts` / `checkSteering` and kills children wedged
 in MCP-init. Four gates, **ALL** required:
 
@@ -110,7 +218,7 @@ in MCP-init. Four gates, **ALL** required:
 
 On fire:
 
-- Kill via `shared.killImmediate`.
+- Terminate via the registered `engine.spawn-phase.stall` gateway site.
 - Write a structured `spawn-phase-stall-<id>` inbox note with the
   live-output tail.
 - Complete the dispatch with

package/docs/tutorials/01-install-and-connect.md

@@ -37,7 +37,7 @@ The installer validates feed access, installs the package, and then runs the
 supported `minions init --force` synchronization — so no separate `minions init`
 is needed. It authenticates with a short-lived token from your existing `az`
 login; no PAT is created, accepted, or stored. See
-[internal-install.md](internal-install.md) for options and troubleshooting.
+[internal-install.md](../internal-install.md) for options and troubleshooting.
 
 If you do not have access to the ISS `ProjectFeed-ISS` feed, install the public
 package from npm instead (a separate release channel, not the OPG path):