@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/rfc-completion-json.md

@@ -19,7 +19,7 @@ This closes a class of spoofable-stdout attacks where agent output (or content q
 
 ## 1. Problem
 
-The engine reconstructs control-plane state from the unstructured stdout of `claude` CLI subprocesses. Eight call sites in `engine/lifecycle.js` and one in `engine/timeout.js` regex-match the agent's output stream:
+The engine reconstructs control-plane state from the unstructured stdout of `claude` CLI subprocesses. Eight call sites in `engine/orchestration/lifecycle.js` and one in `engine/orchestration/timeout.js` regex-match the agent's output stream:
 
 | # | Site | What it scrapes | Spoof surface |
 |---|------|-----------------|---------------|
@@ -31,7 +31,7 @@ The engine reconstructs control-plane state from the unstructured stdout of `cla
 | 6 | `parseStructuredCompletion` (`lifecycle.js:1494`) | Last ` ```completion ` fenced block, parsed as `key: value` | An agent that includes a ` ```completion ` block in a quoted file (e.g. another playbook) overrides its own real status |
 | 7 | `classifyFailure` (`lifecycle.js:2096`) | Failure-class regexes on combined stdout/stderr (`max_turns`, `permission denied`, `merge conflict`, …) | An agent that quotes one error class while genuinely failing on another gets the wrong recovery recipe |
 | 8 | `checkForLearnings` (`lifecycle.js:1266`) | Filesystem scan for `notes/inbox/*<agentId>*<date>*` | Not stdout-based, but date-collisions cause cross-task attribution |
-| 9 | `checkTimeouts` (`engine/timeout.js:189-219`) | Tail of `live-output.log` for `[process-exit]` markers — completion-via-output detection after process tracking is lost | Lower-risk: this is engine/CLI output, not agent-authored content |
+| 9 | `checkTimeouts` (`engine/orchestration/timeout.js:189-219`) | Tail of `live-output.log` for `[process-exit]` markers — completion-via-output detection after process tracking is lost | Lower-risk: this is engine/CLI output, not agent-authored content |
 
 Sites 1–8 are agent-spoofable (intentionally or accidentally). Site 9 is claude-CLI-emitted and stays on stdout — see §6.
 
@@ -89,7 +89,7 @@ The agent must not write the file in pieces. Empty, truncated, or malformed JSON
 
 ### 3.4 Cleanup
 
-`engine/cleanup.js` (every 10 ticks) gains a sweep over `engine/tmp/completion-*.json` older than 24h. The `runPostCompletionHooks` flow already removes the worktree but leaves `engine/tmp/` files for diagnostics — completion files are tiny (<10 KB typical) so a 24h window is generous and matches the existing temp-prompt retention.
+`engine/orchestration/cleanup.js` (every 10 ticks) gains a sweep over `engine/tmp/completion-*.json` older than 24h. The `runPostCompletionHooks` flow already removes the worktree but leaves `engine/tmp/` files for diagnostics — completion files are tiny (<10 KB typical) so a 24h window is generous and matches the existing temp-prompt retention.
 
 ## 4. Schema
 
@@ -207,14 +207,14 @@ The agent must not write the file in pieces. Empty, truncated, or malformed JSON
 | `plan-to-prd` | `status`, `summary` (PRD file existence is checked separately, see lifecycle.js:1721) | `review`, `decomposition`, `meeting` |
 | `explore`, `ask`, `test`, `docs` | `status`, `summary` | `prs`, `review`, `decomposition`, `meeting` |
 
-Validation lives in a new `validateCompletion(obj, taskType)` in `engine/shared.js` and runs in `runPostCompletionHooks` *before* any field is consumed.
+Validation lives in a new `validateCompletion(obj, taskType)` in `engine/core/shared.js` and runs in `runPostCompletionHooks` *before* any field is consumed.
 
 ## 5. Engine Read Path & Migration
 
 ### 5.1 New Helper
 
 ```js
-// engine/lifecycle.js (new — replaces parseStructuredCompletion as primary)
+// engine/orchestration/lifecycle.js (new — replaces parseStructuredCompletion as primary)
 function readCompletionFile(dispatchItem) {
   const p = path.join(ENGINE_DIR, 'tmp', `completion-${dispatchItem.id}.json`);
   if (!fs.existsSync(p)) return null;
@@ -272,7 +272,7 @@ The flag name `engine.requireCompletionFile` mirrors existing engine flags (`aut
 
 These paths stay on stdout / live-output.log:
 
-1. **`engine/timeout.js` completion-via-output detection** (`timeout.js:189-219`). The signal is the engine-written `[process-exit]` sentinel, emitted even if the agent crashed before writing completion.json. Removing it would mean orphans that finished during process-handle loss are never reconciled.
+1. **`engine/orchestration/timeout.js` completion-via-output detection** (`timeout.js:189-219`). The signal is the engine-written `[process-exit]` sentinel, emitted even if the agent crashed before writing completion.json. Removing it would mean orphans that finished during process-handle loss are never reconciled.
 2. **Stale-orphan cleanup via `live-output.log` mtime** (`timeout.js:178`). Completion.json is written once at exit, so `live-output.log` remains the best indirect signal after the engine loses process tracking.
 3. **`parseStreamJsonOutput` for `resultSummary`** in `parseAgentOutput` (`lifecycle.js:1483`). This extracts the human-readable summary from the CLI's stream-json. Even after the flip, `completion.summary` is *also* extracted, but the stream-json text remains the canonical "what did the agent say last" — used in dashboards, agent history, and external notifications. The two coexist: `completion.summary` is for routing decisions, the stream-json text is for display.
 4. **Inbox-file skill scan** (`lifecycle.js:2013-2024`). Some agents write skills into their inbox findings file (a deliberate human-discoverable artifact). The completion file deprecates inline ` ```skill ` blocks in stdout, but the inbox file scan is opt-in and stays — it's a different surface (a real file the agent intentionally wrote, not regex-scraped from stdout).
@@ -290,9 +290,9 @@ These paths stay on stdout / live-output.log:
   "deprecated": "Day 10",
   "reason": "Spoofable surface — agents that quote PR URLs created phantom PR records.",
   "locations": [
-    "engine/lifecycle.js:704 syncPrsFromOutput",
-    "engine/lifecycle.js:734 createdPattern, createdIdPattern",
-    "engine/lifecycle.js:748 prHeaderPattern (inbox scan)"
+    "engine/orchestration/lifecycle.js:704 syncPrsFromOutput",
+    "engine/orchestration/lifecycle.js:734 createdPattern, createdIdPattern",
+    "engine/orchestration/lifecycle.js:748 prHeaderPattern (inbox scan)"
   ],
   "cleanup": "Delete syncPrsFromOutput; keep syncPrsFromCompletion."
 }
@@ -320,7 +320,7 @@ The key shift: **the agent's intent is now in a place no quoted text can reach.*
 
 ### 7.1 Centralized Instruction in `shared-rules.md`
 
-`playbooks/shared-rules.md` is auto-injected into every playbook (per `engine/playbook.js`). The completion-write block lives there once, so per-playbook diffs are minimal.
+`playbooks/shared-rules.md` is auto-injected into every playbook (per `engine/agents/playbook.js`). The completion-write block lives there once, so per-playbook diffs are minimal.
 
 ```markdown
 ## Completion Protocol — Required Before Exit
@@ -400,9 +400,9 @@ The implementation PR ships:
 
 When this RFC is approved and the follow-up plan is drafted, the implementation must satisfy:
 
-1. `MINIONS_COMPLETION_PATH` is set on every spawned agent process (`engine.js` and `engine/spawn-agent.js`).
-2. `engine/shared.js` exports `validateCompletion(obj, taskType)`.
-3. `engine/lifecycle.js` adds `readCompletionFile(dispatchItem)` and threads its return value through `runPostCompletionHooks`.
+1. `MINIONS_COMPLETION_PATH` is set on every spawned agent process (`engine.js` and `engine/agents/spawn-agent.js`).
+2. `engine/core/shared.js` exports `validateCompletion(obj, taskType)`.
+3. `engine/orchestration/lifecycle.js` adds `readCompletionFile(dispatchItem)` and threads its return value through `runPostCompletionHooks`.
 4. Every regex-based site listed in §1 has a completion-aware path with stdout fallback (Phase 0–2) or no fallback (Phase 4).
 5. `playbooks/shared-rules.md` carries the §7.1 instruction; `fix.md` / `implement-shared.md` drop their inline ` ```completion ` block.
 6. `engine.requireCompletionFile` is added to `ENGINE_DEFAULTS` (`shared.js`) defaulting to `false`.
@@ -412,12 +412,12 @@ When this RFC is approved and the follow-up plan is drafted, the implementation
 
 ## 11. References
 
-- `engine/lifecycle.js:1494` — current `parseStructuredCompletion` (legacy ` ```completion ` block reader, half-step toward this design).
-- `engine/lifecycle.js:704` — `syncPrsFromOutput` (Site 1, primary attack surface).
-- `engine/lifecycle.js:1278` — `extractSkillsFromOutput` (Site 5, highest-value attack surface).
-- `engine/timeout.js:189` — completion-via-output detection (stays on stdout per §6).
+- `engine/orchestration/lifecycle.js:1494` — current `parseStructuredCompletion` (legacy ` ```completion ` block reader, half-step toward this design).
+- `engine/orchestration/lifecycle.js:704` — `syncPrsFromOutput` (Site 1, primary attack surface).
+- `engine/orchestration/lifecycle.js:1278` — `extractSkillsFromOutput` (Site 5, highest-value attack surface).
+- `engine/orchestration/timeout.js:189` — completion-via-output detection (stays on stdout per §6).
 - `engine.js:865` — existing env-var injection pattern (`MINIONS_ADO_TOKEN`).
-- `engine/cleanup.js` — temp-file sweep (extended in implementation PR).
+- `engine/orchestration/cleanup.js` — temp-file sweep (extended in implementation PR).
 - `playbooks/shared-rules.md` — auto-injected into every playbook.
 - `docs/deprecated.json` — deprecation tracker driving `/cleanup-deprecated`.
 - `docs/design-state-storage.md` — precedent for design-doc-in-`docs/` rather than `plans/`.

package/docs/runtime-adapters.md

@@ -36,10 +36,10 @@ methods that genuinely differ.
 | `capabilities` | flag object (see below) | Behavioral and declarative flags (see below). |
 | `resolveBinary({ env, config? })` | `{ bin, native, leadingArgs }` or null | Probe PATH, npm-globals, package overrides; cached to `engine/<name>-caps.json`. `leadingArgs` is `[]` for direct binaries and `['copilot']` for the `gh copilot` subcommand fallback. |
 | `capsFile` | absolute path | Cache file for `resolveBinary()` results. |
-| `installHint` | string | Surfaced when `resolveBinary()` returns null. Consumed by `engine/preflight.js` and `engine/spawn-agent.js`. |
+| `installHint` | string | Surfaced when `resolveBinary()` returns null. Consumed by `engine/agents/preflight.js` and `engine/agents/spawn-agent.js`. |
 | `listModels()` | `Promise<{id,name,provider}[] | null>` | Model catalog or null when discovery isn't supported. |
 | `modelsCache` | absolute path | Cache file for `listModels()` results. |
-| `spawnScript` | absolute path | Path to the runtime-agnostic spawn wrapper (currently `engine/spawn-agent.js` for all bundled runtimes). |
+| `spawnScript` | absolute path | Path to the runtime-agnostic spawn wrapper (currently `engine/agents/spawn-agent.js` for all bundled runtimes). |
 | `buildArgs(opts)` | `string[]` | CLI args excluding the binary itself. |
 | `resolveInvocationOptions({ options, engineConfig, config, failureClass })` | object | Optional; maps harness-specific config and retry policy into semantic invocation options. Core code never reads harness-specific invocation keys. |
 | `buildSpawnFlags(opts)` | `string[]` | Optional compatibility flags for older spawn wrappers. New fields travel in the opaque `--runtime-options` bag automatically. |
@@ -54,7 +54,7 @@ methods that genuinely differ.
 | `parseOutput(raw)` | `{ text, usage, sessionId, model }` | Final-event parser. |
 | `parseStreamChunk(line)` | event object or null | Single JSONL line → typed event. |
 | `parseError(rawOutput)` | `{ message, code, retriable }` | Codes: `auth-failure`, `context-limit`, `budget-exceeded`, `model-unavailable` (retriable=true for upstream overload/503; retriable=false for invalid/typo'd model id — Copilot enriches the message via `_warmModelCache()` so it lists the available models), `crash`, null. |
-| `createStreamConsumer(ctx)` | consumer object | Stream accumulator used by `engine/llm.js`. |
+| `createStreamConsumer(ctx)` | consumer object | Stream accumulator used by `engine/agents/llm.js`. |
 | `prepareWorkspace(ctx)` | result object | Optional synchronous hook for harness-owned workspace state, such as trust configuration. |
 | `isSpawnStartupEvent(event)` | boolean | Optional startup-event classifier used by the spawn-phase watchdog. |
 | `shouldSuppressPostMutationError(ctx)` | boolean | Optional harness quirk policy for an error received after a confirmed mutation. |
@@ -79,11 +79,16 @@ does not construct harness CLI argv. The selected adapter:
 
 Legacy named wrapper flags remain for backward compatibility, but they are no
 longer the extension point. A new harness option can be added entirely inside
-its adapter without teaching `engine.js`, `engine/llm.js`, or
-`engine/spawn-agent.js` another CLI flag. Large image payloads are written to a
+its adapter without teaching `engine.js`, `engine/agents/llm.js`, or
+`engine/agents/spawn-agent.js` another CLI flag. Large image payloads are written to a
 protected per-call sidecar; only its path enters the options argument, and the
 wrapper hydrates then deletes it before invoking the adapter.
 
+`disableTools: true` is the semantic boundary for text-only internal calls such
+as KB sweep/rewrite. Claude receives an empty `--tools` set, Copilot receives an
+empty `--available-tools` set without autopilot, and Codex is forced into its
+read-only sandbox. Core callers never branch on runtime names.
+
 Retirement gates for the temporary compatibility surfaces are tracked in
 `docs/deprecated.json`: `legacy-runtime-named-spawn-flags`,
 `versionless-runtime-adapter-compat`, and
@@ -128,10 +133,10 @@ to act on that behavioral split.
 | `sessionPersistenceControl` | ✓ | ✗ | ✗ | Engine writes `session.json`; Copilot and Codex own their runtime stores, while Minions records IDs only for safe resume. |
 | `resumePromptCarryover` | ✗ | ✓ | ✓ | CC resume turns prepend recent visible Q&A in stdin when the runtime session store is opaque to Minions. |
 | `resumeBookkeepingTurn` | ✓ | — | — | Claude CLI injects a synthetic "Continue from where you left off." meta turn on `--resume`; CC prompts must tell the model not to treat it as user intent. |
-| `streamConsumer` | ✓ | ✓ | ✓ | Adapter implements `createStreamConsumer(ctx)` — required by `engine/llm.js` accumulator. |
+| `streamConsumer` | ✓ | ✓ | ✓ | Adapter implements `createStreamConsumer(ctx)` — required by `engine/agents/llm.js` accumulator. |
 | `imageInput` | ✓ | ✓ | ✓ | Runtime accepts `images: [{mimeType, dataBase64}]` and delivers them to the CLI using adapter-owned transport. When false, `_resolveImageOpts` returns a typed `model-unavailable` error. |
 | `skillDiscovery` | ✓ | — | — | Currently set only by Claude to declare native `.claude/skills` discovery. It is metadata-only today; core orchestration has no consumer yet. |
-| `acpWorkerPool` | ✗ | ✓ | ✗ | Runtime supports `<bin> --acp` (Agent Client Protocol), so it can be routed through a persistent worker pool instead of cold-spawning a fresh CLI process per turn/dispatch. Two independent consumers gate on this flag: `engine/cc-worker-pool.js` (CC/doc-chat tabs, `resolveCcUseWorkerPool`) and `engine/agent-worker-pool.js` (fleet agent dispatch, `resolveAgentUseWorkerPool`). Both resolvers hard-return `false` whenever this flag isn't `true` on the resolved runtime, regardless of any operator override, so a future non-ACP runtime can never be silently pooled. See [ACP Worker Pool](#acp-worker-pool-fleet-agent-dispatch) below. |
+| `acpWorkerPool` | ✗ | ✓ | ✗ | Runtime supports `<bin> --acp` (Agent Client Protocol), so it can be routed through a persistent worker pool instead of cold-spawning a fresh CLI process per turn/dispatch. Two independent consumers gate on this flag: `engine/agents/cc-worker-pool.js` (CC/doc-chat tabs, `resolveCcUseWorkerPool`) and `engine/agents/agent-worker-pool.js` (fleet agent dispatch, `resolveAgentUseWorkerPool`). Both resolvers hard-return `false` whenever this flag isn't `true` on the resolved runtime, regardless of any operator override, so a future non-ACP runtime can never be silently pooled. See [ACP Worker Pool](#acp-worker-pool-fleet-agent-dispatch) below. |
 
 When a behavior is genuinely uniform across all current adapters, it still gets
 a flag if a future runtime might disagree — flags are cheap.
@@ -140,13 +145,13 @@ a flag if a future runtime might disagree — flags are cheap.
 
 The `acpWorkerPool` capability backs **two** independent pools that avoid a
 cold harness spawn for every turn/dispatch. Both share the runtime-neutral
-JSON-RPC transport (`engine/acp-transport.js`); the adapter owns worker argv and
+JSON-RPC transport (`engine/agents/acp-transport.js`); the adapter owns worker argv and
 pooled-output encoding.
 
 | Pool | Module | Ownership model | Config | Default |
 |------|--------|------------------|--------|---------|
-| CC / doc-chat | `engine/cc-worker-pool.js` | 1 worker permanently owned per CC tab, kept warm for the tab's lifetime | `engine.ccUseWorkerPool` | `true` (Copilot CC) — see [docs/command-center.md](./command-center.md) |
-| Fleet agent dispatch | `engine/agent-worker-pool.js` | 1 worker leased to exactly one **active** dispatch at a time, returned to a shared free set on release — not owned for the dispatch's whole life | `engine.agentUseWorkerPool` + `engine.agentAcpPoolSize` | `false` (opt-in) |
+| CC / doc-chat | `engine/agents/cc-worker-pool.js` | 1 worker permanently owned per CC tab, kept warm for the tab's lifetime | `engine.ccUseWorkerPool` | `true` (Copilot CC) — see [docs/command-center.md](./command-center.md) |
+| Fleet agent dispatch | `engine/agents/agent-worker-pool.js` | 1 worker leased to exactly one **active** dispatch at a time, returned to a shared free set on release — not owned for the dispatch's whole life | `engine.agentUseWorkerPool` + `engine.agentAcpPoolSize` | `false` (opt-in) |
 
 This section covers the fleet agent pool (P-9b3d5f61 / P-1d8f0b93 / P-4c6e8a72).
 
@@ -171,8 +176,8 @@ concurrent dispatches than the fleet would have run anyway — it only changes
 ### How dispatches route through the pool
 
 When `resolveAgentUseWorkerPool` resolves `true`, `engine.js#spawnAgent` skips
-`node engine/spawn-agent.js` and instead calls `engine/agent-worker-pool.js#acquireWorker`,
-wrapping the lease in `engine/pooled-agent-process.js#PooledAgentProcess` — a
+`node engine/agents/spawn-agent.js` and instead calls `engine/agents/agent-worker-pool.js#acquireWorker`,
+wrapping the lease in `engine/agents/pooled-agent-process.js#PooledAgentProcess` — a
 child_process-shaped facade (`.pid`, `.stdout`/`.stderr`, `.kill()`,
 `'close'`/`'error'`) so the rest of `spawnAgent`'s downstream code (stdout/stderr
 handlers, PID-file writing, live-output.log, timeout/steering cancel-vs-kill,
@@ -216,7 +221,7 @@ its process cwd.
 Dispatch records persist `item.pooled = true` in SQLite, not
 just the in-memory `activeProcesses._pooled` flag (which is wiped on engine
 restart) — the on-disk flag is what tells the restart-reattach path
-(`engine/cli.js`) that a live worker PID is a pooled lease, not a resumable
+(`engine/operations/cli.js`) that a live worker PID is a pooled lease, not a resumable
 cold-spawned child process.
 If checkpoint steering hands a pooled dispatch to a detached cold resume,
 the engine clears `pooled` first and replaces the canonical dispatch PID file,
@@ -265,8 +270,8 @@ pool size trades some isolation for parallelism and fewer respawns.
 
 ### See Also (ACP pool)
 
-- `engine/agent-worker-pool.js` — pool mechanics, assignment strategy, JSDoc header.
-- `engine/pooled-agent-process.js` — the child_process-shaped facade and its
+- `engine/agents/agent-worker-pool.js` — pool mechanics, assignment strategy, JSDoc header.
+- `engine/agents/pooled-agent-process.js` — the child_process-shaped facade and its
   documented output-translation scope limits (no tool-call/model-announcement
   event synthesis — a deliberate parity gap, not an oversight).
 - `test/unit/agent-worker-pool.test.js`, `test/integration/agent-pool-dispatch.test.js`,
@@ -282,7 +287,7 @@ agent fleet to Copilot, and vice versa. Both paths fall through to
 `engine.defaultCli` (the fleet-wide default), but they never see each other's
 overrides.
 
-The helpers in `engine/shared.js` are the single source of truth for
+The helpers in `engine/core/shared.js` are the single source of truth for
 runtime/model and cross-runtime policy resolution. Engine code MUST go through
 them instead of reading config keys directly.
 
@@ -303,10 +308,10 @@ Agent dispatch resolves the runtime once at spawn time:
 const runtime = resolveRuntime(shared.resolveAgentCli(agentConfig, engineConfig));
 ```
 
-CC / doc-chat resolves the runtime via `engine/llm.js` `_resolveRuntimeFor()`:
+CC / doc-chat resolves the runtime via `engine/agents/llm.js` `_resolveRuntimeFor()`:
 
 ```js
-// engine/llm.js (~line 247)
+// engine/agents/llm.js (~line 247)
 if (!runtimeName && callOpts.engineConfig) runtimeName = resolveCcCli(callOpts.engineConfig);
 ```
 
@@ -337,7 +342,7 @@ files.
 ## `--cli` / `--model` / `--effort` Knobs
 
 Three CLI flags switch the fleet without dashboard interaction. They are parsed
-by `engine/cli.js` `_parseRuntimeFlags()` and persist into `config.json`.
+by `engine/operations/cli.js` `_parseRuntimeFlags()` and persist into `config.json`.
 
 | Flag | Persists to | Notes |
 |------|-------------|-------|
@@ -419,7 +424,7 @@ runtime-name branches, and harness-specific invocation config in core paths.
 3. Add unit coverage modeled on `test/unit/runtime-adapters.test.js`.
 
 Once registered, the dashboard `/api/runtimes` endpoint, the `--cli` flag
-validator, the agent CLI dropdown, the `engine/preflight.js` per-runtime binary
+validator, the agent CLI dropdown, the `engine/agents/preflight.js` per-runtime binary
 check, and the model discovery cache all light up automatically. Use capability
 flags — never special-case in engine code.
 
@@ -431,5 +436,5 @@ flags — never special-case in engine code.
   the spike that produced the Copilot adapter; cite it when changing
   Copilot-specific capability flags.
 - `engine/runtimes/contract.js` — authoritative adapter contract and facade.
-- `engine/shared.js` `resolveAgentCli` / `resolveCcCli` etc. — the only
+- `engine/core/shared.js` `resolveAgentCli` / `resolveCcCli` etc. — the only
   supported way to read runtime / model selection from config.

package/docs/security.md

@@ -63,7 +63,7 @@ system. Its threat model:
     and CORS preflights — see `dashboard.js:6007–6091` (and additional
     `isAllowedOrigin` enforcement points in the SSE/CC handlers) and
     `shared.isAllowedOrigin` / `shared.buildSecurityHeaders` in
-    [`engine/shared.js`](../engine/shared.js). Requests whose `Origin` (or
+    [`engine/core/shared.js`](../engine/core/shared.js). Requests whose `Origin` (or
     `Referer`, if `Origin` is absent) is not in the local allowlist are
     rejected with HTTP 403. Callers without an `Origin` header at all
     (Node `http.request`, `curl` without `-H Origin`, CLI tooling) are
@@ -93,7 +93,7 @@ system. Its threat model:
     Entries are matched verbatim against the request `Origin` header
     (scheme + host + port; no path, no wildcards). See
     `shared.isAllowedDashboardOrigin()` in
-    [`engine/shared.js`](../engine/shared.js).
+    [`engine/core/shared.js`](../engine/core/shared.js).
 
 ### Residual risks tracked elsewhere
 
@@ -145,10 +145,10 @@ Structured review learning (see
 [team-memory.md](team-memory.md#security-and-trust-boundaries)) introduces a new
 memory-derived prompt layer, so it observes the same "memory is evidence, not an
 instruction channel" boundary as the rest of retrieval, plus review-specific
-defenses enforced at the persistence boundary in `engine/review-learning.js`:
+defenses enforced at the persistence boundary in `engine/memory/review-learning.js`:
 
 - **Fenced, bounded injection.** Recalled lessons are wrapped with
-  `engine/untrusted-fence.js` and capped at 4 records / 4 KiB, independent of the
+  `engine/core/untrusted-fence.js` and capped at 4 records / 4 KiB, independent of the
   generic memory budget. They carry provenance and instruct the agent to verify
   against live code.
 - **No raw reviewer prose is ever stored.** Candidate/lesson bodies are engine-
@@ -178,7 +178,7 @@ defenses enforced at the persistence boundary in `engine/review-learning.js`:
   PR metadata, or any other on-disk JSON Minions owns.
 - **Tokens are never intentionally logged.** Engine code that shells out to
   `gh` or the ADO CLI threads the token via per-call `GH_TOKEN=...`
-  environment injection (see `engine/gh-token.js`), so the value never
+  environment injection (see `engine/providers/gh-token.js`), so the value never
   appears on a command line or in `live-output.log`.
 - **The log redactor is best-effort, not authoritative.** A best-effort
   redactor scrubs token-shaped strings from logs and agent output, but its
@@ -203,7 +203,7 @@ break operator workflows we want to preserve.
   content (pinned notes, `notes/inbox/*`, PR comment bodies,
   `humanFeedback.feedbackContent`, agent-memory, dashboard doc-chat document/selection
   blocks) inside `<UNTRUSTED-INPUT source="…">…</UNTRUSTED-INPUT>` fences via
-  the helpers in `engine/untrusted-fence.js`. The sysprompt directive in
+  the helpers in `engine/core/untrusted-fence.js`. The sysprompt directive in
   `playbooks/shared-rules.md` (and `prompts/cc-system.md` for CC/doc-chat)
   teaches agents to treat fenced content as a quoted artifact and raise
   `securityFlags.injectionAttempt: true` in the completion report when they

package/docs/self-improvement.md

@@ -88,11 +88,11 @@ Fallback entries are labeled `**By:** Engine (regex fallback)` so you can tell w
 
 ### Auto-Pruning
 
-When `notes.md` exceeds 50KB, the engine trims it to the cap (keeping the header and last 8 consolidations) but **does not silently discard** the older sections — every dropped section is appended to `notes/archive/notes-overflow.md` so nothing is lost (data-loss guard `_capNotesPreservingOverflow` in `engine/consolidation.js`, #218). This keeps the live file bounded while retaining recent institutional knowledge and preserving the rest in the archive.
+When `notes.md` exceeds 50KB, the engine trims it to the cap (keeping the header and last 8 consolidations) but **does not silently discard** the older sections — every dropped section is appended to `notes/archive/notes-overflow.md` so nothing is lost (data-loss guard `_capNotesPreservingOverflow` in `engine/memory/consolidation.js`, #218). This keeps the live file bounded while retaining recent institutional knowledge and preserving the rest in the archive.
 
 ## 2. Per-Agent History
 
-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.
+Each agent's `history.md` retains its last 20 tasks. To bound prompt size, `engine/agents/playbook.js` injects only the five most recent retained entries into the next dispatch.
 
 ### Flow
 
@@ -200,7 +200,7 @@ deterministically. It is fully specified in
 
 Humans can leave actionable comments on ADO or GitHub PRs to trigger fix tasks;
 no `@minions` mention is required. The engine polls PR threads every ~12
-minutes (see `prPollCommentsEvery` in `engine/shared.js`) and dispatches fixes
+minutes (see `prPollCommentsEvery` in `engine/core/shared.js`) and dispatches fixes
 to the PR's author agent.
 
 ### Flow
@@ -218,7 +218,7 @@ Human comments on PR with "fix the error handling here"
 ### How it works
 
 - **Trigger:** Any human comment newer than the per-PR cutoff that survives `_isNonActionableComment()` (preview/CI/Minions-author filter) flips `pr.humanFeedback.pendingFix = true` and queues a fix. There is no "@minions keyword required" gate — `@minions` mentions are merely stripped from `feedbackContent` before it is handed to the fix agent.
-- **Agent detection:** Comments are filtered via `_isNonActionableComment()` in `engine/github.js` / `engine/ado.js`, which composes the body-only predicates from `engine/comment-classifier.js` (`isPreviewStatusBody`, `hasMinionsMarker`) with an identity gate (`viewerDidAuthor === true` on GitHub, `config.engine.minionsAdoIdentities` author match on ADO). Marker presence alone never classifies a comment as agent-authored on either platform.
+- **Agent detection:** Comments are filtered via `_isNonActionableComment()` in `engine/providers/github.js` / `engine/ado/index.js`, which composes the body-only predicates from `engine/providers/comment-classifier.js` (`isPreviewStatusBody`, `hasMinionsMarker`) with an identity gate through the shared `classifyMarkerAuthorship()` seam (`viewerDidAuthor` on GitHub, `config.engine.minionsAdoIdentities` author match on ADO). Marker presence plus an identity *mismatch* never classifies a comment as agent-authored; marker presence with *no usable identity signal* fails safe and does (W-msbf1kf6033f46cb).
 - **Dedup:** Only comments newer than `pr.humanFeedback.lastProcessedCommentDate` are processed
 - **Multiple comments:** All new actionable comments since the cutoff are concatenated chronologically into a single fix task (each body individually fenced in `<UNTRUSTED-INPUT>` per F5 / W-mpeklod3000we69c)
 - **After fix:** `pendingFix` is cleared; PR re-enters normal review cycle