@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/skills.md

@@ -4,7 +4,7 @@ Agents emit a fenced `skill` block when they discover a durable, reusable workfl
 
 The engine extracts valid blocks from agent stdout and from inbox findings (`notes/inbox/*.md`) and writes them into the selected runtime's native personal skills directory (e.g. `~/.claude/skills/<name>/SKILL.md` for Claude, the equivalent personal skills directory for Copilot). Project-scoped skills queue a work item that lands the file by PR in the selected runtime's native project skill root.
 
-Packaged `scope: minions` skills are synchronized into every registered runtime's personal skill directory during `minions init` and upgrades. A packaged skill replaces an existing same-name personal copy so contract fixes take effect immediately.
+Packaged `scope: minions` skills are synchronized into every registered runtime's personal skill directory during `minions init` and upgrades (the sync source is the repo-root `skills/` directory, scanned by `shared.syncBundledPersonalSkills`). A packaged skill replaces an existing same-name personal copy so contract fixes take effect immediately. The bundled `scope: minions` skill under that sync source today is `check-self-authored-review-comment`. Separately, `capture-web-evidence` (`.claude/skills/capture-web-evidence/SKILL.md`) — a **project-agnostic** Playwright flow for capturing BEFORE/AFTER screenshots and screen recordings for a web or mobile-webview UI change in ANY project — is the fallback when the target repo has no visual-evidence instructions of its own (harness-first resolution; see `playbooks/_pr-description-audit.md` → "Visual evidence handling"). It lives under `.claude/skills/` (not the `skills/` sync source), so it is not copied into personal skill dirs by the bundled-skill sync; instead it is discovered natively from `.claude/skills/` and its recipe is inlined in the always-injected PR-description-audit playbook.
 
 ## Block format
 
@@ -44,6 +44,55 @@ Plain Markdown. Include the steps, commands, file paths, and notes another agent
 
 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.
 
+## Skill discovery (read side)
+
+Discovery is how already-on-disk skills are surfaced to the registry so agents
+and Command Center (CC) can resolve a named skill instead of grepping the
+filesystem. It is separate from the write path (the ` ```skill ` block above).
+
+- **Inventory** — `engine/core/queries.js#collectSkillFiles` / `getSkills` (consumed by
+  `/api/tools` in a child process, and by the CC registry) unions:
+  - runtime-native user/plugin roots from each adapter's `getSkillRoots`
+    (`~/.copilot/skills`, `~/.claude/skills`, `~/.agents/skills`, installed plugins);
+  - project skill roots for every configured project. In addition to the
+    repo-root roots the adapters expose (`<repo>/.claude/skills`,
+    `<repo>/.github/skills`, `<repo>/.agents/skills`), a **bounded walk** finds
+    **project-embedded skills nested anywhere under the checkout** — e.g.
+    `loop/app/android/android/.claude/skills/*` in a monorepo. Each discovered
+    skill is tagged with its `projectName` and on-disk `dir`.
+- **CC `<available_skills>` registry** — the Command Center system prompt block is
+  built by `engine/core/shared.js#buildAvailableSkillsBlock`. It merges the
+  user/plugin skills from `listCopilotSkills` with the **project-embedded skills**
+  discovered above (passed as `renderCcSystemPrompt({ projectSkills })` from
+  `dashboard.js#collectCcProjectSkills`, sourced from the child-process-backed
+  `/api/tools` inventory — see "Bounds & safety" below).
+  Project skills render a `<path>` element so CC can open the `SKILL.md`
+  directly: CC's runtime never registered them, so they are **read**, not
+  invoked with the `skill` tool (`prompts/cc-system.md` teaches the split).
+  User/plugin skills win a name collision (matches Copilot CLI's
+  user-wins precedence). The static/legacy CC prompt keeps user/plugin-only
+  discovery so dashboard boot never triggers a cold monorepo walk.
+
+**Bounds & safety** — the nested walk is breadth-first (shallowest-first, so the
+budget is spent on the levels most likely to hold repo-root skills) and bounded
+so a massive monorepo can't stall discovery (caps in `engine/core/queries.js`): max
+directory depth (`SKILL_WALK_MAX_DEPTH = 12`), a directory-dirent cap
+(`SKILL_WALK_MAX_ENTRIES = 40000` — only directory entries count; files are free
+and never starve the walk), and a heavy-dir prune set
+(`SKILL_WALK_PRUNE_DIRS`: `.git`, `node_modules`, `bin`, `obj`, `build`, `dist`,
+`out`, `target`, `.gradle`, `vendor`, `DerivedData`, …). Marker dir names
+(`.claude` / `.github` / `.agents`) are derived from the adapter-provided project
+roots — discovery never branches on runtime names. Results are memoized by the
+shared 30s skills cache (`SKILLS_CACHE_TTL`, keyed on home dir + project
+localPaths; flushed by `invalidateSkillsCache`), so the walk runs at most once
+per cache window and stays off the `/api/status` hot path. Crucially the walk
+runs **in the `/api/tools` child process** (`engine/agents/tools-inventory.js`), never in
+the dashboard process: the CC turn path reads that child-backed inventory cache
+only and, on a cold or stale cache, kicks off `_refreshToolsInventory()` and
+degrades the turn to user/plugin skills. Deferring an in-process walk with
+`setImmediate` would not be enough — it runs in the check phase of the *same*
+event loop and would still stall `/api/status` polling and every open SSE stream.
+
 ## Human-approved promotion of review lessons (P-192d3660)
 
 Verified **review lessons** captured in structured memory (`sourceType: review-learning`,
@@ -53,7 +102,7 @@ Copilot/Claude pick them up through native instruction/skill discovery. Promotio
 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
+- **Eligibility** (`engine/memory/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
@@ -63,7 +112,7 @@ review → merge lifecycle.
     `<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
+- **Queueing** goes through `engine/memory/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`.

package/docs/slim-ux/concepts.md

@@ -36,8 +36,8 @@ dashboard then builds synthetic action results for the UI.
 
 - System prompt: `prompts/cc-system.md`
 - Session records: `engine/state.db` table `cc_sessions`
-- Shared invocation path: `dashboard.js#ccCall` and `engine/llm.js#callLLM`
-- Runtime selection: `engine/shared.js#resolveCcCli` and `engine/runtimes/index.js#resolveRuntime`
+- Shared invocation path: `dashboard.js#ccCall` and `engine/agents/llm.js#callLLM`
+- Runtime selection: `engine/core/shared.js#resolveCcCli` and `engine/runtimes/index.js#resolveRuntime`
 
 **Backing symbols.**
 
@@ -45,8 +45,8 @@ dashboard then builds synthetic action results for the UI.
   `dashboard.js#handleCommandCenterStream`
 - Turn/action correlation: `dashboard.js#_ccTurnCreations` and
   `dashboard.js#_buildSyntheticActionResultsForTurn`
-- Session persistence: `engine/small-state-store.js` CC-session helpers
-- Per-response tool-turn cap: `engine/shared.js#ENGINE_DEFAULTS.ccMaxTurns` (default 50)
+- Session persistence: `engine/persistence/small-state-store.js` CC-session helpers
+- Per-response tool-turn cap: `engine/core/shared.js#ENGINE_DEFAULTS.ccMaxTurns` (default 50)
 
 **Existing dashboard.** `dashboard/pages/home.html` contains the classic CC surface; the Slim home
 surface uses the same server handlers and sessions.
@@ -80,15 +80,15 @@ dependencies, and lifecycle state.
 
 - Durable records: `engine/state.db` table `work_items`
 - In-flight execution records: `engine/state.db` table `dispatches`
-- Read/write facade: `engine/work-items-store.js`
+- Read/write facade: `engine/planning/work-items-store.js`
 
 **Backing symbols.**
 
-- Statuses: `engine/shared.js#WI_STATUS`
-- Work types: `engine/shared.js#WORK_TYPE`
-- Queue admission: `engine/dispatch.js#addToDispatch`
-- Lifecycle updates: `engine/lifecycle.js#updateWorkItemStatus`
-- Completion predicate: `engine/lifecycle.js#isItemCompleted`
+- Statuses: `engine/core/shared.js#WI_STATUS`
+- Work types: `engine/core/shared.js#WORK_TYPE`
+- Queue admission: `engine/orchestration/dispatch.js#addToDispatch`
+- Lifecycle updates: `engine/orchestration/lifecycle.js#updateWorkItemStatus`
+- Completion predicate: `engine/orchestration/lifecycle.js#isItemCompleted`
 
 The common path is `pending` (or `queued`) -> `dispatched` -> `done` or `failed`. `paused`,
 `decomposed`, and `cancelled` are also canonical states. Failures can retry up to
@@ -125,8 +125,13 @@ Plan Markdown -> plan-to-prd Work Item -> PRD rows -> Work Items -> verify Work
 ```
 
 The `plan-to-prd` agent writes `agents/<id>/prd-result.json`. On successful completion,
-`engine/lifecycle.js` validates that sidecar against the expected plan and imports it into the SQL
-PRD store before the plan-to-PRD Work Item can finish.
+`engine/orchestration/lifecycle.js` validates that sidecar against the expected plan and imports it into the SQL
+PRD store before the plan-to-PRD Work Item can finish. The expected result identity
+(`_prdFilename`) is pinned on the Work Item and is **retry-stable**, so a valid sidecar left
+behind by an interrupted attempt is recoverable: the next tick imports it (pre-spawn, in
+`engine.js#discoverCentralWorkItems`) instead of dispatching a second conversion. Validation
+and the atomic one-shot consume live in `engine/planning/prd-result-sidecar.js` — both import
+sites share it. See [plan-lifecycle.md](../plan-lifecycle.md#plan-to-prd-result-sidecar).
 
 **Where it lives.**
 
@@ -139,12 +144,12 @@ Executable lifecycle state is SQL-backed. Manual archive moves the Markdown sour
 
 **Backing symbols.**
 
-- Plan statuses: `engine/shared.js#PLAN_STATUS`
-- Atomic conversion enqueue: `engine/shared.js#queuePlanToPrd`
-- Completion gate: `engine/lifecycle.js#checkPlanCompletion`
-- Manual archive: `engine/lifecycle.js#archivePlan`
-- Plan worktree cleanup: `engine/lifecycle.js#cleanupPlanWorktrees`
-- PRD sidecar import: `engine/lifecycle.js#runPostCompletionHooks`
+- Plan statuses: `engine/core/shared.js#PLAN_STATUS`
+- Atomic conversion enqueue: `engine/core/shared.js#queuePlanToPrd`
+- Completion gate: `engine/orchestration/lifecycle.js#checkPlanCompletion`
+- Manual archive: `engine/orchestration/lifecycle.js#archivePlan`
+- Plan worktree cleanup: `engine/orchestration/lifecycle.js#cleanupPlanWorktrees`
+- PRD sidecar import: `engine/orchestration/lifecycle.js#runPostCompletionHooks`
 
 **Existing dashboard.** `dashboard/pages/plans.html` owns the classic Plans and PRD tabs and all
 lifecycle actions.
@@ -185,18 +190,18 @@ complexity, dependencies, project, type, and a status of `missing`, `updated`, o
 - Parent records: `engine/state.db` table `prds`
 - Item records: `engine/state.db` table `prd_items`
 - Verify-PR links: `engine/state.db` table `prd_verify_prs`
-- Read/write facade: `engine/prd-store.js`
+- Read/write facade: `engine/planning/prd-store.js`
 
 Archived PRDs remain in SQL. Current manual archive sets the PRD's archive metadata in place.
 
 **Backing symbols.**
 
-- Item statuses: `engine/shared.js#PRD_ITEM_STATUS`
-- Materializable statuses: `engine/shared.js#PRD_MATERIALIZABLE`
-- SQL writes and item upserts: `engine/prd-store.js#writePrd` and `#_upsertPrd`
-- Reads: `engine/prd-store.js#readPrd` and `#listPrdRows`
-- Work Item -> PRD status sync: `engine/lifecycle.js#syncPrdItemStatus`
-- Reconciliation sweep: `engine/lifecycle.js#reconcilePrdStatuses`
+- Item statuses: `engine/core/shared.js#PRD_ITEM_STATUS`
+- Materializable statuses: `engine/core/shared.js#PRD_MATERIALIZABLE`
+- SQL writes and item upserts: `engine/planning/prd-store.js#writePrd` and `#_upsertPrd`
+- Reads: `engine/planning/prd-store.js#readPrd` and `#listPrdRows`
+- Work Item -> PRD status sync: `engine/orchestration/lifecycle.js#syncPrdItemStatus`
+- Reconciliation sweep: `engine/orchestration/lifecycle.js#reconcilePrdStatuses`
 - Stable Work Item join: `work_items.prd_item_id -> prd_items.id`
 
 **Existing dashboard.** `dashboard/pages/plans.html` renders the PRD graph/list. The Slim Plans tile
@@ -229,11 +234,11 @@ information belongs in team `notes.md`, the Knowledge Base, or both.
 
 **Backing symbols.**
 
-- Writer and ID parser: `engine/shared.js#writeToInbox` and `#parseNoteId`
-- Consolidation entry point: `engine/consolidation.js#consolidateInbox`
-- LLM merge: `engine/consolidation.js#consolidateWithLLM`
-- Classification: `engine/consolidation.js#classifyToKnowledgeBase`
-- Source archival: `engine/consolidation.js#archiveInboxFiles`
+- Writer and ID parser: `engine/core/shared.js#writeToInbox` and `#parseNoteId`
+- Consolidation entry point: `engine/memory/consolidation.js#consolidateInbox`
+- LLM merge: `engine/memory/consolidation.js#consolidateWithLLM`
+- Classification: `engine/memory/consolidation.js#classifyToKnowledgeBase`
+- Source archival: `engine/memory/consolidation.js#archiveInboxFiles`
 
 **Existing dashboard.** `dashboard/pages/inbox.html` surfaces Notes, the inbox, and KB controls.
 
@@ -264,10 +269,10 @@ agent memory is kept separately under `knowledge/agents/`.
 
 **Backing symbols.**
 
-- Canonical categories: `engine/shared.js#KB_CATEGORIES`
-- Query/read layer: `engine/queries.js#KNOWLEDGE_DIR` and KB readers
-- Classification: `engine/consolidation.js#classifyToKnowledgeBase`
-- Compaction and TTL sweep: `engine/kb-sweep.js`
+- Canonical categories: `engine/core/shared.js#KB_CATEGORIES`
+- Query/read layer: `engine/core/queries.js#KNOWLEDGE_DIR` and KB readers
+- Classification: `engine/memory/consolidation.js#classifyToKnowledgeBase`
+- Compaction and TTL sweep: `engine/memory/kb-sweep.js`
 
 **Existing dashboard.** `dashboard/pages/inbox.html` contains the KB browser and sweep controls.
 
@@ -299,10 +304,10 @@ layer, while `kb-pins.json` protects selected KB entries from sweep removal.
 
 **Backing symbols.**
 
-- Pin-index path: `engine/shared.js#PINNED_ITEMS_PATH`
-- Pin-index reader: `engine/shared.js#getPinnedItems`
+- Pin-index path: `engine/core/shared.js#PINNED_ITEMS_PATH`
+- Pin-index reader: `engine/core/shared.js#getPinnedItems`
 - Markdown parser: `dashboard.js#parsePinnedEntries`
-- Prompt injection and untrusted-input fencing: `engine/playbook.js`
+- Prompt injection and untrusted-input fencing: `engine/agents/playbook.js`
 
 **Existing dashboard.** The home and Knowledge surfaces expose pinned context and pin/unpin
 controls.
@@ -331,9 +336,9 @@ agents, and engine alerts.
 
 **Backing symbols.**
 
-- Directory: `engine/queries.js#INBOX_DIR`
-- Writer: `engine/shared.js#writeToInbox`
-- Consolidation: `engine/consolidation.js#consolidateInbox`
+- Directory: `engine/core/queries.js#INBOX_DIR`
+- Writer: `engine/core/shared.js#writeToInbox`
+- Consolidation: `engine/memory/consolidation.js#consolidateInbox`
 - Manual handlers: `dashboard.js#handleInboxPersist`, `#handleInboxPromoteKb`,
   `#handleInboxOpen`, and `#handleInboxDelete`
 
@@ -366,12 +371,12 @@ Item enters the queue, including nested string fields.
 
 **Backing symbols.**
 
-- Cron parsing: `engine/scheduler.js#parseCronField` and `#parseCronExpr`
-- Match decision: `engine/scheduler.js#shouldRunNow`
-- Variable map: `engine/scheduler.js#buildScheduleTemplateVars`
-- Recursive substitution: `engine/scheduler.js#applyScheduleTemplateVarsRecursive`
-- Work Item factory: `engine/scheduler.js#createScheduledWorkItem`
-- Discovery: `engine/scheduler.js#discoverScheduledWork`
+- Cron parsing: `engine/orchestration/scheduler.js#parseCronField` and `#parseCronExpr`
+- Match decision: `engine/orchestration/scheduler.js#shouldRunNow`
+- Variable map: `engine/orchestration/scheduler.js#buildScheduleTemplateVars`
+- Recursive substitution: `engine/orchestration/scheduler.js#applyScheduleTemplateVarsRecursive`
+- Work Item factory: `engine/orchestration/scheduler.js#createScheduledWorkItem`
+- Discovery: `engine/orchestration/scheduler.js#discoverScheduledWork`
 
 **Existing dashboard.** `dashboard/pages/schedule.html` provides definition CRUD, run-now, and
 natural-language-to-cron assistance.
@@ -397,21 +402,21 @@ notifies or runs a configured follow-up action. The eight built-in target types
 
 `pr`, `work-item`, `meeting`, `plan`, `schedule`, `pipeline`, `dispatch`, and `agent`.
 
-Additional target types can be loaded from `<MINIONS_DIR>/watches.d/*.js`.
+Additional target types can be loaded from `<MINIONS_DIR>/watch-plugins/*.js`.
 
 **Where it lives.** `engine/state.db` table `watches`.
 
 **Backing symbols.**
 
-- Statuses and built-in target names: `engine/shared.js#WATCH_STATUS` and
+- Statuses and built-in target names: `engine/core/shared.js#WATCH_STATUS` and
   `#WATCH_TARGET_TYPE`
-- Conditions: `engine/shared.js#WATCH_CONDITION`
-- Fire-once fallback set: `engine/shared.js#WATCH_ABSOLUTE_CONDITIONS`
-- Target registry: `engine/watches.js#TARGET_TYPES` and `#registerTargetType`
-- CRUD: `engine/watches.js#createWatch`, `#updateWatch`, and `#deleteWatch`
-- Evaluation: `engine/watches.js#evaluateWatch` and `#checkWatches`
-- Plugin loader: `engine/watches.js#_loadPluginTargetTypes`
-- Follow-up action registry: `engine/watch-actions.js`
+- Conditions: `engine/core/shared.js#WATCH_CONDITION`
+- Fire-once fallback set: `engine/core/shared.js#WATCH_ABSOLUTE_CONDITIONS`
+- Target registry: `engine/watches/index.js#TARGET_TYPES` and `#registerTargetType`
+- CRUD: `engine/watches/index.js#createWatch`, `#updateWatch`, and `#deleteWatch`
+- Evaluation: `engine/watches/index.js#evaluateWatch` and `#checkWatches`
+- Plugin loader: `engine/watches/index.js#_loadPluginTargetTypes`
+- Follow-up action registry: `engine/watches/actions.js`
 
 The engine schedules `checkWatches` every `ENGINE_DEFAULTS.watchPollEvery` ticks. The default is 18
 ticks, approximately three minutes at the default 10-second engine tick. Each watch can impose a
@@ -450,13 +455,13 @@ Definitions intentionally remain file-backed; run history is SQL-backed.
 
 **Backing symbols.**
 
-- Definition directory and CRUD: `engine/pipeline.js#PIPELINES_DIR`, `#getPipelines`,
+- Definition directory and CRUD: `engine/orchestration/pipeline.js#PIPELINES_DIR`, `#getPipelines`,
   `#getPipeline`, `#savePipeline`, and `#deletePipeline`
-- Stage/status enums: `engine/shared.js#STAGE_TYPE` and `#PIPELINE_STATUS`
-- Run reads: `engine/pipeline.js#getPipelineRuns` ->
-  `engine/small-state-store.js#readPipelineRuns`
-- Run mutations: `engine/shared.js#mutatePipelineRuns`
-- Lifecycle: `engine/pipeline.js#startRun`, `#updateRunStage`, `#upsertRunStage`, and
+- Stage/status enums: `engine/core/shared.js#STAGE_TYPE` and `#PIPELINE_STATUS`
+- Run reads: `engine/orchestration/pipeline.js#getPipelineRuns` ->
+  `engine/persistence/small-state-store.js#readPipelineRuns`
+- Run mutations: `engine/core/shared.js#mutatePipelineRuns`
+- Lifecycle: `engine/orchestration/pipeline.js#startRun`, `#updateRunStage`, `#upsertRunStage`, and
   `#completeRun`
 
 **Existing dashboard.** `dashboard/pages/pipelines.html` provides definition editing, triggering,
@@ -487,12 +492,12 @@ runtime, prompt sidecar, process/session metadata, worktree, branch/PR locks, an
 
 **Backing symbols.**
 
-- Transactional mutation: `engine/dispatch.js#mutateDispatch`
-- Queue insertion and dedupe: `engine/dispatch.js#addToDispatch`
-- PR/branch lock detection: `engine/dispatch.js#findActivePrOrBranchLock`
-- Completion: `engine/dispatch.js#completeDispatch`
-- Result enum: `engine/shared.js#DISPATCH_RESULT`
-- Store implementation: `engine/dispatch-store.js`
+- Transactional mutation: `engine/orchestration/dispatch.js#mutateDispatch`
+- Queue insertion and dedupe: `engine/orchestration/dispatch.js#addToDispatch`
+- PR/branch lock detection: `engine/orchestration/dispatch.js#findActivePrOrBranchLock`
+- Completion: `engine/orchestration/dispatch.js#completeDispatch`
+- Result enum: `engine/core/shared.js#DISPATCH_RESULT`
+- Store implementation: `engine/persistence/dispatch-store.js`
 
 **Existing dashboard.** `dashboard/pages/engine.html` shows dispatch history and logs; home/work
 surfaces show active execution context.
@@ -515,14 +520,14 @@ execution workspace. A **Completion** report is its trusted exit contract.
 - `review[]` -- candidates rejected by the optional pre-dispatch acceptance gate
 
 **Where it lives.** `engine/state.db` table `dispatches`, reconstructed by
-`engine/dispatch-store.js#readDispatchSectioned`.
+`engine/persistence/dispatch-store.js#readDispatchSectioned`.
 
 **Backing symbols.**
 
-- Dashboard/query view: `engine/queries.js#getDispatchQueue`
-- Queue mutation: `engine/dispatch.js#mutateDispatch`
-- Acceptance-review routing: `engine/dispatch.js#_routeToReviewQueue`
-- Concurrency default: `engine/shared.js#ENGINE_DEFAULTS.maxConcurrent` (default 5)
+- Dashboard/query view: `engine/core/queries.js#getDispatchQueue`
+- Queue mutation: `engine/orchestration/dispatch.js#mutateDispatch`
+- Acceptance-review routing: `engine/orchestration/dispatch.js#_routeToReviewQueue`
+- Concurrency default: `engine/core/shared.js#ENGINE_DEFAULTS.maxConcurrent` (default 5)
 
 The queue enforces Work Item and dispatch-key dedupe, fix-target and branch locks, dependency
 readiness, concurrency, retry policy, and budget/cooldown gates.
@@ -553,11 +558,11 @@ a mismatch invalidates every reported signal and fails the dispatch as
 
 **Backing symbols.**
 
-- Path builder: `engine/shared.js#dispatchCompletionReportPath`
-- Recognized core fields: `engine/shared.js#COMPLETION_FIELDS`
-- File parsing: `engine/lifecycle.js#parseCompletionReportFile`
-- Required-report gate: `engine/lifecycle.js#requiredCompletionReportFailure`
-- Dispatch terminalization: `engine/dispatch.js#completeDispatch`
+- Path builder: `engine/core/shared.js#dispatchCompletionReportPath`
+- Recognized core fields: `engine/core/shared.js#COMPLETION_FIELDS`
+- File parsing: `engine/orchestration/lifecycle.js#parseCompletionReportFile`
+- Required-report gate: `engine/orchestration/lifecycle.js#requiredCompletionReportFailure`
+- Dispatch terminalization: `engine/orchestration/dispatch.js#completeDispatch`
 
 Core fields include `status`, `summary`, `files_changed`, `tests`, `pr`, `not_changed`,
 `failure_class`, `retryable`, `needs_rerun`, `verdict`, `artifacts`, `nonce`, and
@@ -582,16 +587,16 @@ review verdict, and Minions linkage. It is not the host PR itself.
 
 - PR records: `engine/state.db` table `pull_requests`
 - Cross-record links: `engine/state.db` table `pr_links`
-- Store facade: `engine/pull-requests-store.js`
+- Store facade: `engine/persistence/pull-requests-store.js`
 
 **Backing symbols.**
 
-- Statuses and polling eligibility: `engine/shared.js#PR_STATUS` and
+- Statuses and polling eligibility: `engine/core/shared.js#PR_STATUS` and
   `#PR_POLLABLE_STATUSES`
-- GitHub integration: `engine/github.js`
-- Azure DevOps integration: `engine/ado.js`
-- Agent-output/report sync: `engine/lifecycle.js#syncPrsFromOutput`
-- Required-attachment gate: `engine/lifecycle.js#isPrAttachmentRequired`
+- GitHub integration: `engine/providers/github.js`
+- Azure DevOps integration: `engine/ado/index.js`
+- Agent-output/report sync: `engine/orchestration/lifecycle.js#syncPrsFromOutput`
+- Required-attachment gate: `engine/orchestration/lifecycle.js#isPrAttachmentRequired`
 
 **Existing dashboard.** `dashboard/pages/prs.html` is the classic PR screen; Slim embeds that same
 screen for PR details.
@@ -622,18 +627,18 @@ constraint. The legacy config key `skills` is accepted only as a compatibility f
 
 **Where it lives.**
 
-- Default roster: `engine/shared.js#DEFAULT_AGENTS`
+- Default roster: `engine/core/shared.js#DEFAULT_AGENTS`
 - Per-agent config: `config.json` under `agents.<id>`
 - Charter: `agents/<id>/charter.md`
 - Metrics and dispatch history: SQL-backed runtime state
 
 **Backing symbols.**
 
-- Roster/status projection: `engine/queries.js#getAgents`
-- Detail projection: `engine/queries.js#getAgentDetail`
-- Identity/charter prompt: `engine/playbook.js#buildSystemPrompt`
-- Soft re-review preference: `engine/lifecycle.js#pickReReviewAgentHints`
-- Runtime selection: `engine/shared.js#resolveAgentCli`
+- Roster/status projection: `engine/core/queries.js#getAgents`
+- Detail projection: `engine/core/queries.js#getAgentDetail`
+- Identity/charter prompt: `engine/agents/playbook.js#buildSystemPrompt`
+- Soft re-review preference: `engine/orchestration/lifecycle.js#pickReReviewAgentHints`
+- Runtime selection: `engine/core/shared.js#resolveAgentCli`
 - Bundled adapters: `engine/runtimes/index.js` (`claude`, `copilot`, `codex`)
 
 **Existing dashboard.** Agent cards and detail views show status, runtime/model, charter, output,
@@ -672,11 +677,11 @@ work sources.
 
 **Backing symbols.**
 
-- Config projection: `engine/shared.js#getProjects`
-- Scope helpers: `engine/shared.js#stateScope`, `#readWorkItems`, and
+- Config projection: `engine/core/shared.js#getProjects`
+- Scope helpers: `engine/core/shared.js#stateScope`, `#readWorkItems`, and
   `#readPullRequests`
-- Checkout mode: `engine/shared.js#resolveCheckoutMode`
-- Canonical removal: `engine/projects.js#removeProject`
+- Checkout mode: `engine/core/shared.js#resolveCheckoutMode`
+- Canonical removal: `engine/planning/projects.js#removeProject`
 
 `checkoutMode: "worktree"` is the default isolated execution model.
 `checkoutMode: "live"` opts a project into guarded in-place execution.
@@ -715,10 +720,10 @@ Adapters may discover additional compatible roots without changing orchestration
 
 **Backing symbols.**
 
-- Frontmatter parser: `engine/shared.js#parseSkillFrontmatter`
-- Discovery: `engine/queries.js#collectSkillFiles`
-- Dashboard projections: `engine/queries.js#getSkills` and `#getSkillIndex`
-- Extraction: `engine/lifecycle.js#extractSkillsFromOutput`
+- Frontmatter parser: `engine/core/shared.js#parseSkillFrontmatter`
+- Discovery: `engine/core/queries.js#collectSkillFiles`
+- Dashboard projections: `engine/core/queries.js#getSkills` and `#getSkillIndex`
+- Extraction: `engine/orchestration/lifecycle.js#extractSkillsFromOutput`
 - Adapter contract: `getSkillRoots()` and `getSkillWriteTargets()` in
   `engine/runtimes/{claude,copilot,codex}.js`
 
@@ -748,7 +753,7 @@ configuration is runtime-native; repository/user harness files are not merged in
 **Backing symbols.**
 
 - Dashboard inventory: `dashboard.js#getMcpServers`
-- Watched config paths: `engine/queries.js` slow-state dependency collector
+- Watched config paths: `engine/core/queries.js` slow-state dependency collector
 - Runtime preparation/discovery: `engine/runtimes/*`
 - Copilot built-in suppression: `engine.copilotDisableBuiltinMcps`
 
@@ -780,10 +785,10 @@ dispatch, work discovery, snapshots, and diagnostics.
 **Backing symbols.**
 
 - Tick: `engine.js#tick` / `#tickInner`
-- Defaults: `engine/shared.js#ENGINE_DEFAULTS`
+- Defaults: `engine/core/shared.js#ENGINE_DEFAULTS`
 - Watch cadence: `ENGINE_DEFAULTS.watchPollEvery` (18 ticks by default)
-- Cold-process reattachment: `engine/cli.js` startup reattachment path
-- Stale-orphan grace: `engine/timeout.js` with `ENGINE_DEFAULTS.heartbeatTimeout`
+- Cold-process reattachment: `engine/operations/cli.js` startup reattachment path
+- Stale-orphan grace: `engine/orchestration/timeout.js` with `ENGINE_DEFAULTS.heartbeatTimeout`
 
 Tracked live agents are not killed merely for output silence. Cold agents can be reattached after
 an engine restart through persisted PID/session data and `agents/<id>/live-output.log`; pooled ACP
@@ -823,8 +828,8 @@ MCP/skill configuration remain owned and discovered by the selected CLI.
 
 **Backing symbols.**
 
-- Loader: `engine/queries.js#getConfig`
-- Defaults: `engine/shared.js#ENGINE_DEFAULTS`
+- Loader: `engine/core/queries.js#getConfig`
+- Defaults: `engine/core/shared.js#ENGINE_DEFAULTS`
 - Settings handlers: `dashboard.js#handleSettingsRead`, `#handleSettingsUpdate`,
   `#handleSettingsReset`, and `#handleSettingsRouting`
 
@@ -845,20 +850,20 @@ resolution are intentionally independent.
 
 ## 22. Feature Flag
 
-**What it is.** A temporary product/UX gate registered in `engine/features.js`. Resolution order
+**What it is.** A temporary product/UX gate registered in `engine/core/features.js`. Resolution order
 is environment override (`MINIONS_FEATURE_<ID>`) -> `config.features[id]` -> registry default.
 Unknown flag IDs fail loudly.
 
 Feature flags are not a substitute for permanent `engine.*` configuration. The `slim-ux` flag gates
 the redesigned dashboard.
 
-**Where it lives.** `engine/features.js#FEATURES`.
+**Where it lives.** `engine/core/features.js#FEATURES`.
 
 **Backing symbols.**
 
-- Resolver: `engine/features.js#isFeatureOn`
-- Listing: `engine/features.js#listFeatures`
-- Registry check: `engine/features.js#hasFeature`
+- Resolver: `engine/core/features.js#isFeatureOn`
+- Listing: `engine/core/features.js#listFeatures`
+- Registry check: `engine/core/features.js#hasFeature`
 
 **Existing dashboard.** Settings exposes registered experimental flags and their current values.
 
@@ -884,11 +889,11 @@ uses the single global `ROUTING_PATH`.
 
 **Backing symbols.**
 
-- Path and reader: `engine/routing.js#ROUTING_PATH` and `#getRouting`
-- Parser: `engine/routing.js#parseRoutingTable`
-- Cache: `engine/routing.js#getRoutingTableCached`
-- Work-type lookup: `engine/routing.js#routeForWorkType`
-- Final resolution: `engine/routing.js#resolveAgent`
+- Path and reader: `engine/orchestration/routing.js#ROUTING_PATH` and `#getRouting`
+- Parser: `engine/orchestration/routing.js#parseRoutingTable`
+- Cache: `engine/orchestration/routing.js#getRoutingTableCached`
+- Work-type lookup: `engine/orchestration/routing.js#routeForWorkType`
+- Final resolution: `engine/orchestration/routing.js#resolveAgent`
 
 **Existing dashboard.** Settings exposes the routing table editor.
 
@@ -910,8 +915,8 @@ of engagement. It is loaded into that Agent's system prompt for each dispatch.
 
 **Backing symbols.**
 
-- Prompt loading/injection: `engine/playbook.js#buildSystemPrompt`
-- Dashboard detail read: `engine/queries.js#getAgentDetail`
+- Prompt loading/injection: `engine/agents/playbook.js#buildSystemPrompt`
+- Dashboard detail read: `engine/core/queries.js#getAgentDetail`
 - Dashboard write handler: the `/api/agents/charter` route in `dashboard.js`
 
 The prompt and detail surfaces each read the charter at their respective system-prompt/detail
@@ -942,7 +947,7 @@ outcomes or the operator explicitly intervenes.
 
 **Backing symbols.**
 
-- Paths/status maps: `engine/meeting.js#MEETINGS_DIR`,
+- Paths/status maps: `engine/orchestration/meeting.js#MEETINGS_DIR`,
   `#MEETING_NOTE_ARTIFACT_ROOT`, `#ROUND_STATUS_BY_NAME`, and
   `#ROUND_NUMBER_BY_NAME`
 - Round outcome helpers: `#getRoundFailures` and `#allParticipantsFinishedRound`