@yemi33/minions 0.1.2305 → 0.1.2306

package/docs/completion-reports.md

@@ -85,6 +85,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
 | `pending` | string | Any remaining work, or `none`. |
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |
+| `invalidates` | string[] | Optional. List of work-item IDs (e.g. `["W-abc123"]`) whose goals are superseded by this completion. The engine cancels each listed WI that is currently in `pending` or `queued` status, stamping `cancellationReason: "invalidated-by:<source-wi-id>"`. WIs in any other status (dispatched, done, failed, cancelled) are skipped with a warning — they are NOT cancelled. Missing IDs also log a warning and are skipped. Only processed on successful (`effectiveSuccess`) completions. See [Goal invalidation](#goal-invalidation). |
 | `meta.review` | object | Optional, review tasks only. Records project-local review-skill outcome — see [Review skill outcomes](#review-skill-outcomes). Aliased by the generalized `meta.skill` (W-mq1cczi90006b21f). |
 | `meta.skill` | object | Optional. Records project-local skill outcome for ANY playbook type that surfaces a `## Project skills` block (implement / fix / plan / review / etc.). See [Project skill outcomes](#project-skill-outcomes). |
 | `meta.descriptionAudit` | object | Optional, `fix` / `implement` dispatches that push commits. Records the PR description audit + screenshot-refresh outcome — see [PR description audit](#pr-description-audit). |
@@ -191,6 +192,30 @@ Record the outcome under `meta.descriptionAudit`. All fields are optional and ba
 
 Dispatchers can suppress the audit entirely by setting `meta.skipDescriptionAudit: true` on the work item — the playbook then renders an explicit "audit suppressed" notice instead of the audit steps. Use this for skill-meta updates, doc-only fixes whose PR description text won't be affected by the diff, and follow-up dispatches that explicitly own the description themselves.
 
+## Goal invalidation
+
+P-mqyp0009y025z6a7. An optional `invalidates: string[]` field in the completion report lets a completing work item cancel the goals of sibling or downstream WIs that are no longer needed.
+
+```json
+{
+  "status": "success",
+  "summary": "Implemented approach A; approach B work items are no longer needed.",
+  "invalidates": ["W-approach-b-001", "W-approach-b-002"]
+}
+```
+
+**Semantics:**
+
+- `invalidates` is an array of work-item ID strings (same format as WI IDs: `W-xxx`).
+- The field is **optional and additive** — existing completion reports without it are unaffected.
+- The engine processes `invalidates[]` only on **successful** completions (code 0, no `agentReportedFailure`, no `skipDoneStatus`).
+- Each listed WI is cancelled only if it is currently in `pending` or `queued` status. WIs in any other status (`dispatched`, `done`, `failed`, `cancelled`, …) are **not** cancelled; a warning is logged instead.
+- Missing WI IDs (IDs not found in any project's work-items) produce a warning but do **not** throw — the rest of the `invalidates[]` list is still processed.
+- Each cancellation stamps `cancellationReason: "invalidated-by:<source-wi-id>"` and `cancelledAt` on the cancelled WI.
+- A `work_items` state event is emitted for each successful cancellation so the dashboard reflects it.
+
+**Implementation:** `engine/lifecycle.js#applyGoalInvalidation`, called from `runPostCompletionHooks` after the source WI is marked done.
+
 ## Harness usage (`harnessUsed`)
 
 P-a8f3c2d1. Optional self-report of the harness affordances the agent actually

package/docs/copilot-cli-schema.md

@@ -26,6 +26,7 @@
 | `capabilities.bareMode` | **`false`** | No `--bare`. Closest equivalent is `--no-custom-instructions` (suppresses AGENTS.md only, not all auto-discovery). |
 | `capabilities.fallbackModel` | **`false`** | No `--fallback-model` flag. |
 | `capabilities.sessionPersistenceControl` | **`false`** | Copilot manages session state internally in `~/.copilot/session-state/`. Engine cannot opt out without `--config-dir`. |
+| `capabilities.imageInput` | **`true`** | Base64 image payloads are materialized to temp files and passed as `--attachment <path>` (repeatable flag, W-mqv7324u0021db5d). See §10a. |
 
 | Default | Value |
 |---|---|
@@ -182,6 +183,7 @@ Empirically confirmed flags for non-interactive Copilot invocations:
 | `--stream on` / `--stream off` | optional | Default is `on`. See §4. |
 | `--enable-reasoning-summaries` | optional | Maps from `opts.reasoningSummaries`; only Anthropic models populate `assistant.reasoning_delta`. |
 | `--add-dir <path>` | injected by spawn-agent | Same role as on the Claude path — registers extra read-allowed dirs (skill discovery). |
+| `--attachment <path>` | injected for image inputs | Passes an image file to the model. Repeatable. The adapter writes each base64 image payload to a temp file, emits one `--attachment` per file, and deletes temps after spawn (W-mqv7324u0021db5d). Gated by `capabilities.imageInput`. |
 | `-v` / `--verbose` | **never emit** | Does not exist on Copilot. The Claude adapter emits `--verbose`; the Copilot adapter MUST NOT. |
 
 ### 3.1 `--autopilot` vs single-shot
@@ -602,7 +604,8 @@ When implementing `engine/runtimes/copilot.js`:
 3. `buildArgs(opts)` always emits:
    `--output-format json -s --allow-all --no-ask-user --autopilot --log-level error`
    plus the conditional flags from §3, plus `--no-custom-instructions` /
-   `--disable-builtin-mcps` per `opts.suppressAgentsMd` / `opts.disableBuiltinMcps`.
+   `--disable-builtin-mcps` per `opts.suppressAgentsMd` / `opts.disableBuiltinMcps`,
+   plus `--attachment <path>` (repeatable) for each image in `opts.images` (§10a).
    **Never** emit `--verbose`.
 4. `buildPrompt()` injects `<system>...</system>\n\n` block when sysprompt is
    non-empty; passthrough otherwise (§2).
@@ -643,6 +646,33 @@ When the spike's findings disagree with the plan text, **this document wins**
 
 ---
 
+## 10a. Image Attachments — `--attachment` (W-mqv7324u0021db5d)
+
+`capabilities.imageInput: true`. The Copilot CLI accepts image files via
+`--attachment <path>` (the flag is repeatable). The adapter's `buildArgs(opts)`
+materializes each base64 payload from `opts.images` to a temp file in
+`opts.tmpDir`, appends `--attachment <path>` per file, and arranges cleanup after
+`spawn` returns.
+
+```js
+// Simplified adapter flow (see engine/runtimes/copilot.js _buildAttachmentArgs)
+for (const img of opts.images ?? []) {
+  const ext = MIME_TO_EXT[img.mimeType] ?? 'bin';
+  const filePath = path.join(opts.tmpDir, `attachment-${i}.${ext}`);
+  fs.writeFileSync(filePath, Buffer.from(img.dataBase64, 'base64'));
+  args.push('--attachment', filePath);
+}
+```
+
+**Supported MIME types** (empirically confirmed against Copilot v1.0.36):
+`image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+
+When `capabilities.imageInput` is false (e.g., Codex adapter), the engine's
+`_resolveImageOpts` returns a typed `model-unavailable` error before spawn so
+callers get a clean rejection instead of a silent drop.
+
+---
+
 ## Provenance
 
 - Test host: Windows 11, PowerShell 7+, `copilot.exe` 1.0.36 from WinGet.

package/docs/design-state-storage.md

@@ -2,7 +2,7 @@
 
 > Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Accepted — implementation in progress**
 
-> **Implementation status (as of 2026-06):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–9 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool, qa_runs + qa_sessions, pr_links, cooldowns + pending_rebases + cc_sessions + doc_sessions, and steering_deliveries — see `CHANGELOG.md` and `engine/db/migrations/`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. Phase 8 added the first opt-out toggle for the JSON sidecars (`engine.qaDualWriteJson`, default true). Phase 9.4 went further and deleted the silent SQL-unavailable JSON fallbacks in the engine — SQL is now the only reader/writer for everything migrated; the JSON mirror layer is dual-written as a passive mirror and slated for deletion in Phase 9.5. The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
+> **Implementation status (as of 2026-06):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–10 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool, qa_runs + qa_sessions, pr_links, cooldowns + pending_rebases + cc_sessions + doc_sessions, and steering_deliveries (Phases 0–9); plans + prds + prd_items + prd_verify_prs (Phase 10, migration `015-plans-prds.js`) — see `CHANGELOG.md` and `engine/db/migrations/`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. Phase 8 added the first opt-out toggle for the JSON sidecars (`engine.qaDualWriteJson`, default true). Phase 9.4 went further and deleted the silent SQL-unavailable JSON fallbacks in the engine — SQL is now the only reader/writer for everything migrated; the JSON mirror layer is dual-written as a passive mirror and slated for deletion in Phase 9.5. Phase 10 dual-writes PRD state to SQL (`engine/prd-store.js`) and flips reads to SQL when the `prdReadsFromSql` feature flag is ON (default ON — reversible). The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
 
 ## Executive Summary
 

package/docs/live-checkout-mode.md

@@ -54,7 +54,7 @@ By default the dirty tree refusal (Guarantee 2) is terminal — the engine never
 3. If ON: `git fetch origin` + `git reset --hard origin/<branch>`, then **re-run the porcelain preflight once**. If the tree is now clean, dispatch proceeds normally. If the reset failed or the tree is *still* dirty, it falls back to the safe `{ ok:false, reason:'dirty' }` refusal — the engine never dispatches onto an unexpected tree.
 4. On a successful reset it writes a single `live-checkout-autoreset-<wiId>` inbox note listing **exactly which paths were discarded**, so the operator can recover them from `git reflog` / `git fsck --lost-found`.
 
-This is **DESTRUCTIVE** — it permanently discards the operator's uncommitted changes in the live checkout — which is why it is **OFF by default** and strictly opt-in. Use it only for unattended/CI-style live checkouts where the tree is expected to track the remote and any local drift is disposable.
+This is **DESTRUCTIVE** — it permanently discards the operator's uncommitted changes in the live checkout. As of W-mqzbbhn2 it is **ON by default**: discarding disposable dirt via reset-to-remote keeps live-checkout branches aligned with origin instead of accumulating `minions: auto-save agent WIP` commits on every dirty exit. Set `liveCheckoutAutoReset: false` (per-project or fleet-wide) to restore the terminal dirty-tree refusal for live checkouts whose local drift you want preserved.
 
 - **Fleet-wide:** Dashboard → Settings → `Live-checkout auto-reset (fleet-wide)` (`engine.liveCheckoutAutoReset`).
 - **Per-project override:** set `liveCheckoutAutoReset: true|false` on the project object in `config.json` (see the config snippet under *Enabling live mode*). A per-project boolean overrides the fleet-wide default for that project. *(Per-project Settings-UI persistence is deferred — the per-project override is config.json-only for now.)*
@@ -103,6 +103,8 @@ Live-mode agents run **in-place** in the operator's checkout, so when a dispatch
 
 - **Original-ref capture.** `prepareLiveCheckout` records the operator's starting ref *before* the first checkout: `git symbolic-ref --short HEAD` → `{ originalRef:<branch>, originalRefType:'branch' }`, falling back to `git rev-parse HEAD` → `{ originalRef:<sha>, originalRefType:'detached' }`. `spawnAgent` persists `originalRef` / `originalRefType` onto the dispatch record via `mutateDispatch`, so the restore survives an engine restart, where the in-memory spawn closure is gone and only the persisted record remains.
 - **Self-healing dirty recovery (PL-live-checkout-reliability-hardening).** Before the plain checkout, if the tree is **dirty AND HEAD is on the agent branch** (and that branch differs from `originalRef`), the dirt is provably **agent-authored** — the engine created that branch and verified the tree clean before switching to it. The leftovers are committed onto the **agent branch** (`git add -A` + `git commit --no-verify -m "minions: auto-save agent WIP (dispatch …)"`), so the plain `git checkout <originalRef>` then succeeds and the operator tree returns clean. This is the fix for the *"no recovery from dirty checkout"* deadlock, where an agent's crash-leftover WIP refused the restore, stranded the tree dirty on the agent branch, and then made **every future WI** for that project fail `LIVE_CHECKOUT_DIRTY` until a human cleaned it. It only ever mutates the engine-created branch, never the operator's branch, never discards (the WIP lands as a visible, revertable commit / on its PR), and gitignored artifacts are never staged (so a tree dirty only with ignored build output never reaches here). Best-effort: a failed auto-commit falls through to the manual-recovery alert below.
+- **Retry-with-backoff on the WIP auto-save commit (#608).** The `git add -A` + `git commit` above (and the equivalent self-heal commit described below) go through `_commitAgentWipWithRetry`: a bounded retry (3 attempts, linear backoff) that fires only when the commit fails with an `index.lock` / "another git process" message — i.e. a transient collision with a concurrent git invocation — never on a genuine failure like "nothing to commit". Previously a single failed attempt (e.g. a `.git/index.lock` race) silently aborted the auto-save, leaving the tree dirty on the agent branch and letting the pollution below take hold.
+- **Orphaned-agent-branch self-heal at dispatch start (#608).** If dispatch-end restore is ever skipped or interrupted (crash, forced kill, an engine restart racing the restore), the *next* dispatch for that project can start with HEAD already sitting on a stray `work/<wi-id>` branch from the previous run — and, before this fix, `prepareLiveCheckout`'s dirty-tree check ran *before* `originalRef` was even captured, so the function returned `{ reason: 'dirty' }` immediately and the branch was never noticed or cleaned, silently repeating for every subsequent dispatch. `prepareLiveCheckout` now recognizes this case: if the tree is still dirty after the existing auto-clean-artifacts recheck, and the current branch (read from the already-fetched `git status --porcelain -b` header, no extra git call) matches the `work/<id>` naming convention (`_looksLikeAgentBranch`) and differs from this dispatch's own target branch, the WIP is committed onto that stray branch (again via `_commitAgentWipWithRetry`) and HEAD is switched back to `mainRef` before the normal flow continues. This only ever touches a branch matching the engine's own naming convention — an operator's own feature branch (e.g. `feature/x`) is never mistaken for engine litter and is left untouched.
 - **AUTO-RESTORE (best-effort, never `--force`).** At dispatch-end `restoreLiveCheckoutAtDispatchEnd` issues a **plain** `git checkout <originalRef>` — no `--force`, no `-B`, no reset, no clean, no stash. It no-ops when there is nothing to restore: no captured `originalRef`, the agent branch *is* the original ref, or HEAD already sits on the original ref (matched against the branch name *or* the raw sha so the detached-HEAD case is recognized). It is strictly best-effort: every error is swallowed and logged, and a restore never alters the dispatch result.
 - **Fallback notify (only when a safe switch is impossible).** If git declines the plain checkout — most likely because the agent left uncommitted changes a checkout would overwrite — the refusal is **honored**: the tree is left exactly as the agent left it and a deduped `live-checkout-branch-<dispatchId>` inbox alert tells the operator how to switch back manually (`git -C <localPath> checkout <originalRef>`). The engine never forces the switch. An **unexpected** restore error (git missing, repo corruption, a GVFS blob fetch on the switch-back) now also writes this alert, so a non-refusal failure never silently strands the tree.
 - **Terminal-failure alert.** When the dispatch ends in a non-success terminal state, a deduped `live-checkout-failed-<dispatchId>` inbox alert is written so the operator knows a live-mode run failed inside their own checkout (where any partial work is visible). This is independent of the restore and fires even when the restore itself succeeds.
@@ -178,7 +180,7 @@ The engine has no opinion about local branches; this hygiene is the operator's r
 Live-checkout mode is deliberately small. These are NOT supported and will not be added:
 
 - **No `auto` mode.** The choice between `worktree` and `live` is per-project and operator-set. The engine will not auto-detect submodules / `repo` workspaces and silently switch modes.
-- **No auto-stash on dirty refusal.** The engine refuses and exits; it never `git stash`es to "make room" for a dispatch. Stashes silently mutate the operator's tree and conflate engine state with operator state. (The opt-in `liveCheckoutAutoReset` is the one sanctioned escape hatch — but it **discards** rather than stashes, is OFF by default, and is gated on explicit per-project / fleet-wide opt-in. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
+- **No auto-stash on dirty refusal.** The engine refuses and exits; it never `git stash`es to "make room" for a dispatch. Stashes silently mutate the operator's tree and conflate engine state with operator state. (The `liveCheckoutAutoReset` escape hatch — ON by default as of W-mqzbbhn2 — **discards** rather than stashes; set it to `false` per-project / fleet-wide to keep the terminal dirty-tree refusal. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
 - **No concurrent dispatches per project.** The cap is 1; raising it would require per-WI subdirectories, which live mode explicitly does not provide.
 - **No per-WI subdirectory isolation.** Live mode is one-checkout-per-project by design. If you need isolation, use `checkoutMode: 'worktree'` (the default).
 - **No per-WI override.** `checkoutMode` is per-project only. There is no `meta.checkoutMode` on a work item that overrides the project setting.
@@ -190,7 +192,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | File | Purpose |
 |---|---|
 | `engine/shared.js` — `CHECKOUT_MODES`, `validateCheckoutMode`, `resolveCheckoutMode`, `isLiveCheckoutProject` | Enum + validator + back-compat resolver (P-a3f9b201; consolidated W-mqiaw974). |
-| `engine/shared.js` — `resolveLiveCheckoutAutoReset` + `ENGINE_DEFAULTS.liveCheckoutAutoReset` | Pure precedence resolver (per-project boolean > fleet-wide engine default > false) + the fleet-wide default (OFF). Gates the opt-in dirty-tree auto-reset in `prepareLiveCheckout` (W-mqvejug6000eeb20). |
+| `engine/shared.js` — `resolveLiveCheckoutAutoReset` + `ENGINE_DEFAULTS.liveCheckoutAutoReset` | Pure precedence resolver (per-project boolean > fleet-wide engine default > false) + the fleet-wide default (ON as of W-mqzbbhn2). Gates the dirty-tree auto-reset in `prepareLiveCheckout` (W-mqvejug6000eeb20). |
 | `engine/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live projects (P-a3f9b202). |
 | `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, mid-operation / detached-HEAD preflight (incl. `BISECT_LOG`; throw-on-git-dir-failure; exit-1-only detached), original-ref capture, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch` classification** for partial-clone hydration failures, **opt-in dirty auto-reset** (`git fetch origin` + `reset --hard origin/<branch>` + re-check + `live-checkout-autoreset-<wiId>` note when `liveCheckoutAutoReset` is on), **50 MB git maxBuffer** (P-a3f9b203; preflight + capture P-b2e8d4a6; hardening PL-live-checkout-reliability-hardening; auto-reset + maxBuffer W-mqvejug6000eeb20). |
 | `engine/live-checkout.js` — `restoreLiveCheckoutAtDispatchEnd` | Dispatch-end auto-restore (plain `git checkout <originalRef>`, never `--force`/reset/clean/stash, best-effort) + **self-healing dirty recovery** (auto-commit agent WIP onto the agent branch) + `live-checkout-failed-<dispatchId>` terminal-failure alert + `live-checkout-branch-<dispatchId>` fallback notify (now also on unexpected restore errors) (P-d9e6b2c4; self-heal PL-live-checkout-reliability-hardening). |

package/engine/ado.js

@@ -42,6 +42,23 @@ function isGitHubProject(project) {
   return String(project?.repoHost || '').toLowerCase() === 'github';
 }
 
+// #3758 — True when at least one configured project is NOT a GitHub project
+// (i.e., could plausibly need ADO). Tick-loop entry points
+// (pollPrStatus/pollPrHumanComments/reconcilePrs) use this to stay fully
+// inert on a GitHub-only install: without it, a config with adoPollEnabled
+// left at its default attempts az/azureauth token acquisition every poll for
+// no reason, producing a permanent, noisy — and, per the failure this
+// closes, potentially fatal — failure loop.
+//
+// Deliberately does NOT require adoOrg/adoProject to already be populated:
+// several legitimate ADO projects start with those fields blank and get them
+// repaired in-place (from a tracked PR URL, canonical PR id, or `git remote`)
+// by repairAdoProjectConfig() inside forEachActivePr/reconcilePrs itself —
+// gating on adoOrg/adoProject here would skip that repair before it ever ran.
+function hasAdoProjectConfigured(config) {
+  return shared.getProjects(config).some(p => !isGitHubProject(p));
+}
+
 function isAdoGuid(value) {
   return ADO_GUID_RE.test(String(value || '').trim());
 }
@@ -1165,6 +1182,13 @@ async function forEachActivePr(config, token, callback) {
             if (currentPrs[idx].reviewStatus === REVIEW_STATUS.APPROVED && after.reviewStatus !== REVIEW_STATUS.APPROVED) {
               after.reviewStatus = REVIEW_STATUS.APPROVED;
             }
+            // Never downgrade status from 'merged' — permanent terminal state. A
+            // stale/out-of-order poll response could otherwise overwrite a concurrent
+            // success/merge write-back (mirrors github.js:564-570 and the central
+            // ADO write-back guard at ado.js:1327-1330).
+            if (currentPrs[idx].status === PR_STATUS.MERGED && after.status !== PR_STATUS.MERGED) {
+              after.status = PR_STATUS.MERGED;
+            }
             shared.applyPrFieldDelta(currentPrs[idx], before, after);
           }
           // Don't push if not found — it was deleted by another writer, respect that
@@ -1328,6 +1352,10 @@ async function forEachActivePr(config, token, callback) {
 async function pollPrStatus(config) {
   _adoPollHadAuthFailure = false; // reset before polling — set again if errors recur
 
+  // #3758 — inert when no project actually uses ADO. Skip token acquisition
+  // entirely rather than spawning az/azureauth for a GitHub-only install.
+  if (!hasAdoProjectConfigured(config)) return;
+
   const token = await getAdoToken();
   if (!token) {
     const w = consumeNoAdoTokenWarning();
@@ -1882,6 +1910,9 @@ async function pollPrStatus(config) {
 // ─── Poll Human Comments on PRs ──────────────────────────────────────────────
 
 async function pollPrHumanComments(config) {
+  // #3758 — inert when no project actually uses ADO.
+  if (!hasAdoProjectConfigured(config)) return;
+
   const token = await getAdoToken();
   if (!token) return;
 
@@ -2100,6 +2131,9 @@ async function pollPrHumanComments(config) {
  * in pull-requests.json, and add them. Matches PRs to work items by branch name.
  */
 async function reconcilePrs(config) {
+  // #3758 — inert when no project actually uses ADO.
+  if (!hasAdoProjectConfigured(config)) return;
+
   const token = await getAdoToken();
   if (!token) {
     const w = consumeNoAdoTokenWarning();
@@ -2984,4 +3018,7 @@ module.exports = {
   isPrValidationBuild,
   shouldRequeueStaleBuild,
   PR_BUILD_REQUEUE_INTERVAL_MS,
+  // #3758 — exported for unit tests of GitHub-only-config inertness.
+  isGitHubProject,
+  hasAdoProjectConfigured,
 };

package/engine/consolidation.js

@@ -1136,6 +1136,52 @@ function consolidateWithRegex(items, files, config) {
 
 // ─── Knowledge Base Classification ───────────────────────────────────────────
 
+// Matches the reusable-knowledge section headers agents conventionally use in
+// their inbox findings notes ("## Patterns / Conventions", "## Bugs & Gotchas",
+// "## Dependencies", etc. — see notes.md consolidation history). Presence
+// signals the note carries generalizable knowledge worth a full-body KB copy;
+// absence means the note is most likely a narrow, one-off deliverable (a
+// single PR review, a task status update, a one-time plan) that should get a
+// condensed stub instead of a full-body duplicate (issue #604).
+// The keyword doesn't have to open the heading — "#### Bugs & Gotchas" (the
+// exact header this module itself generates for regex-fallback consolidation
+// entries, see catLabels above) puts "Bugs" before "Gotchas". Allow up to a
+// few leading heading words (bounded to avoid ReDoS) before the keyword.
+const REUSABLE_SIGNAL_RE = /^#{1,4}\s*(?:[\w&/-]+\s+){0,4}(patterns?(\s*(&|and|\/)\s*conventions?)?|conventions?|gotchas?|dependencies|best practices?)\b/im;
+
+function hasReusableSignal(content) {
+  return REUSABLE_SIGNAL_RE.test(content || '');
+}
+
+/**
+ * Build a condensed KB stub for narrowly-scoped, one-off notes instead of
+ * duplicating the full body (issue #604 — classifyToKnowledgeBase was copying
+ * every consolidated inbox note's ENTIRE body into knowledge/<category>/,
+ * doubling disk usage and paying a recurring context/token cost on every
+ * future dispatch that primes from knowledge/ before notes/inbox/).
+ *
+ * Deterministic and LLM-free: keeps the note's H1 title (if any) plus its
+ * first substantive paragraph as a short abstract, then links back to the
+ * archived note for anyone who needs the full detail. Existing full-body KB
+ * files already on disk are untouched — this only changes how NEW entries
+ * are written.
+ */
+function buildCondensedKbBody(content, titleLine, archiveRelPath) {
+  const body = String(content || '').trim();
+  const withoutTitle = titleLine ? body.replace(/^#\s+.+(\r?\n)+/, '') : body;
+  const firstBlock = (withoutTitle.split(/\r?\n\s*\r?\n/).find(b => b.trim().length > 0) || '').trim();
+  const MAX_LEN = 500;
+  let abstract = firstBlock;
+  if (abstract.length > MAX_LEN) {
+    abstract = abstract.slice(0, MAX_LEN).replace(/\s+\S*$/, '').trim() + '\u2026';
+  }
+  const parts = [];
+  if (titleLine) parts.push(titleLine.trim());
+  parts.push(abstract || '_(no summary available)_');
+  parts.push(`_Full note: \`${archiveRelPath}\`._`);
+  return parts.join('\n\n') + '\n';
+}
+
 async function classifyToKnowledgeBase(items, config) {
 
   if (!fs.existsSync(KNOWLEDGE_DIR)) fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
@@ -1174,9 +1220,18 @@ async function classifyToKnowledgeBase(items, config) {
     const kbFilename = `${dateStamp()}-${agent}-${titleSlug}.md`;
     const kbPath = shared.uniquePath(path.join(categoryDirs[category], kbFilename));
 
-    const frontmatter = `---\nsource: ${item.name}\nagent: ${agent}\ncategory: ${category}\ndate: ${dateStamp()}\n---\n\n`;
+    // Reserve full-body KB copies for content that's actually general/reusable
+    // (patterns, conventions, gotchas); narrowly-scoped one-off notes get a
+    // condensed stub + link back to the archived note instead (issue #604).
+    const reusable = category === 'conventions' || hasReusableSignal(content);
+    const archiveRelPath = `notes/archive/${dateStamp()}-${item.name}`;
+    const kbBody = reusable
+      ? content
+      : buildCondensedKbBody(content, titleMatch ? titleMatch[0] : null, archiveRelPath);
+
+    const frontmatter = `---\nsource: ${item.name}\nagent: ${agent}\ncategory: ${category}\ndate: ${dateStamp()}\nreusable: ${reusable}\n---\n\n`;
     try {
-      safeWrite(kbPath, frontmatter + content);
+      safeWrite(kbPath, frontmatter + kbBody);
       classified++;
     } catch (err) {
       log('warn', `Failed to classify ${item.name} to knowledge base: ${err.message}`);
@@ -1340,4 +1395,6 @@ module.exports = {
   archiveInboxFiles,
   _capNotesPreservingOverflow,
   NOTES_MAX_BYTES,
+  hasReusableSignal,
+  buildCondensedKbBody,
 };

package/engine/lifecycle.js

@@ -4981,6 +4981,77 @@ function pickReReviewAgentHints(config, opts = {}) {
   return out;
 }
 
+/**
+ * P-mqyp0009y025z6a7 — Goal invalidation.
+ *
+ * When a completing WI's report carries a non-empty `invalidates: [wi-id, …]`
+ * array, cancel each listed WI that is currently pending or queued.
+ *
+ * Rules:
+ *   - Only cancels WIs in status 'pending' or 'queued'.
+ *   - WIs in any other status (dispatched, done, failed, cancelled, …) are
+ *     skipped with a warning log — they are not cancelled.
+ *   - Missing WI IDs produce a warning but do not throw.
+ *   - Uses mutateWorkItems (SQL-canonical) so the dashboard reflects the change.
+ */
+function applyGoalInvalidation(sourceWiId, invalidates, config) {
+  if (!Array.isArray(invalidates) || invalidates.length === 0) return;
+
+  const wiPaths = getWorkItemPaths(config);
+  const cancellableStatuses = new Set([WI_STATUS.PENDING, WI_STATUS.QUEUED]);
+  const cancellationReason = `invalidated-by:${sourceWiId}`;
+
+  for (const targetId of invalidates) {
+    if (!targetId || typeof targetId !== 'string') continue;
+
+    // Find which file contains the WI.
+    let foundPath = null;
+    let foundStatus = null;
+    for (const wiPath of wiPaths) {
+      try {
+        const items = readOptionalJsonStrict(wiPath, 'work-items', Array.isArray) || [];
+        const item = items.find(i => i && i.id === targetId);
+        if (item) {
+          foundPath = wiPath;
+          foundStatus = item.status;
+          break;
+        }
+      } catch { /* best-effort scan */ }
+    }
+
+    if (!foundPath) {
+      log('warn', `Goal invalidation: WI ${targetId} listed in invalidates[] by ${sourceWiId} not found — skipping`);
+      continue;
+    }
+
+    if (!cancellableStatuses.has(foundStatus)) {
+      log('warn', `Goal invalidation: WI ${targetId} is in status '${foundStatus}' — only pending/queued WIs are cancelled; skipping`);
+      continue;
+    }
+
+    // Cancel the WI via mutateWorkItems so the SQL store + state event are updated.
+    try {
+      mutateWorkItems(foundPath, (items) => {
+        if (!Array.isArray(items)) return items;
+        const wi = items.find(i => i && i.id === targetId);
+        if (!wi) return items;
+        // Re-check status inside the lock to avoid TOCTOU races.
+        if (!cancellableStatuses.has(wi.status)) {
+          log('warn', `Goal invalidation: WI ${targetId} changed to '${wi.status}' before cancel lock acquired — skipping`);
+          return items;
+        }
+        wi.status = WI_STATUS.CANCELLED;
+        wi.cancellationReason = cancellationReason;
+        wi.cancelledAt = ts();
+        log('info', `Goal invalidation: cancelled WI ${targetId} (${cancellationReason})`);
+        return items;
+      });
+    } catch (err) {
+      log('warn', `Goal invalidation: failed to cancel WI ${targetId}: ${err.message}`);
+    }
+  }
+}
+
 async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config, opts) {
 
   const detectPhantom = !!(opts && opts.detectPhantom);
@@ -5459,6 +5530,11 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     promoteCompletionArtifacts(meta, agentId, dispatchItem.id, structuredCompletion, { resultSummary });
     // M003 — auto-dispatch a live-validation WI when a coding WI completes.
     try { autoDispatchLiveValidationWi(meta, config); } catch (err) { log('warn', `autoDispatchLiveValidationWi: ${err.message}`); }
+    // P-mqyp0009y025z6a7 — goal invalidation: cancel any pending/queued WIs
+    // listed in the completion report's optional `invalidates[]` field.
+    if (structuredCompletion && Array.isArray(structuredCompletion.invalidates) && structuredCompletion.invalidates.length > 0) {
+      try { applyGoalInvalidation(meta.item.id, structuredCompletion.invalidates, config); } catch (err) { log('warn', `applyGoalInvalidation: ${err.message}`); }
+    }
   }
   // Failure retry is handled by completeDispatch in dispatch.js — not duplicated here.
   // Only clear _decomposing flag on failure so decompose items don't get permanently stuck.
@@ -5927,12 +6003,83 @@ function syncPrdFromPrs(config) {
         if (sourcePlan) stampPrdItemPrUrl(itemId, sourcePlan, pr.url);
       }
     }
+    // Advance PRD top-level status when all items are done and all linked PRs merged
+    advancePrdStatusOnAllItemsDone(config);
   } catch (err) {
     // Non-fatal — log and continue
     try { log('warn', `syncPrdFromPrs error: ${err?.message || err}`); } catch { /* engine not available */ }
   }
 }
 
+// ─── PRD Top-Level Status Auto-Completion (P-d7e8f9a1) ───────────────────────
+// Runs at the end of syncPrdFromPrs (same PR-poll cadence). Advances PRD
+// status to 'completed' when every missing_features item satisfies both:
+//   1. A work item with that id exists in done status (DONE_STATUSES)
+//   2. The linked PR (WI._pr) is merged — or the item has no linked PR
+//      (non-code items that never raised a PR)
+// Paused, rejected, awaiting-approval, completed, and archived PRDs are
+// skipped via _PRD_FROZEN_STATUSES. The locked write is idempotent.
+function advancePrdStatusOnAllItemsDone(config) {
+  if (!fs.existsSync(PRD_DIR)) return;
+  let prdFiles;
+  try { prdFiles = fs.readdirSync(PRD_DIR).filter(f => f.endsWith('.json')); } catch { return; }
+  if (!prdFiles.length) return;
+
+  const allWorkItems = queries.getWorkItems(config);
+  if (!allWorkItems.length) return;
+
+  // Index done WIs by id for O(1) lookup
+  const doneWiById = new Map();
+  for (const wi of allWorkItems) {
+    if (wi.id && DONE_STATUSES.has(wi.status)) doneWiById.set(wi.id, wi);
+  }
+  if (!doneWiById.size) return;
+
+  // Collect all PRs by id across all projects for merged-status lookup
+  const prById = new Map();
+  for (const project of shared.getProjects(config)) {
+    for (const pr of safeJsonArr(shared.projectPrPath(project))) {
+      if (pr?.id) prById.set(pr.id, pr);
+    }
+  }
+
+  for (const file of prdFiles) {
+    try {
+      const fpath = path.join(PRD_DIR, file);
+      const plan = safeJsonNoRestore(fpath);
+      if (!plan?.missing_features?.length) continue;
+      // Skip frozen PRDs — paused/rejected/awaiting-approval/completed/archived
+      if (_PRD_FROZEN_STATUSES.has(plan.status)) continue;
+
+      const allDone = plan.missing_features.every(feature => {
+        const wi = doneWiById.get(feature.id);
+        if (!wi) return false; // no done WI for this feature
+        // If the WI has a linked PR, it must be merged
+        if (wi._pr) {
+          const pr = prById.get(wi._pr);
+          if (!pr) return true; // PR no longer in tracker (swept after merge) — allow
+          return pr.status === PR_STATUS.MERGED;
+        }
+        // No linked PR — non-code item or PR not tracked; done WI is sufficient
+        return true;
+      });
+
+      if (!allDone) continue;
+
+      mutateJsonFileLocked(fpath, (data) => {
+        // Re-check under lock — another writer may have frozen this PRD
+        if (_PRD_FROZEN_STATUSES.has(data.status)) return data;
+        data.status = PLAN_STATUS.COMPLETED;
+        if (!data.completedAt) data.completedAt = ts();
+        return data;
+      }, { skipWriteIfUnchanged: true });
+      log('info', `PRD auto-advance: ${file} → completed (all items done, all linked PRs merged)`);
+    } catch (err) {
+      log('warn', `advancePrdStatusOnAllItemsDone error for ${file}: ${err?.message || err}`);
+    }
+  }
+}
+
 // ─── Persist verify/E2E aggregate PRs onto the PRD JSON (W-mqps9jlb) ──────────
 // The PRD view's "E2E Aggregate PRs" section (dashboard/js/render-prd.js#
 // renderE2eSection) sources its PRs from the LIVE tracker (pull-requests.json).
@@ -6400,7 +6547,9 @@ module.exports = {
   mergeArtifactNotes,
   promoteCompletionArtifacts,
   runPostCompletionHooks,
+  applyGoalInvalidation,
   syncPrdFromPrs,
+  advancePrdStatusOnAllItemsDone,
   persistVerifyPrsToPrd,
   resolveWorkItemPath,
   isItemCompleted,