@yemi33/minions 0.1.2286 → 0.1.2287

package/dashboard.js

@@ -37,6 +37,7 @@ const _dashboardVersion = {
 };
 const shared = require('./engine/shared');
 const queries = require('./engine/queries');
+const prdStore = require('./engine/prd-store');
 const ado = require('./engine/ado');
 const gh = require('./engine/github');
 const ghToken = require('./engine/gh-token');
@@ -429,6 +430,21 @@ function mergeSettingsConfigUpdate(current, candidate, body, patch = {}) {
       // `worktreeMode`. Drop any stale legacy key on every settings save so a
       // migrated project never carries both fields.
       delete currentProject.worktreeMode;
+      // M006 — mirror liveValidation: check both candidateProject (modified
+      // in-memory config) and the original body update. When handleSettingsUpdate
+      // deletes the field (null or empty type sent), candidateProject won't have
+      // it but the body update will — mirror the deletion to disk.
+      if (Object.prototype.hasOwnProperty.call(candidateProject, 'liveValidation')) {
+        if (candidateProject.liveValidation && typeof candidateProject.liveValidation === 'object' && candidateProject.liveValidation.type) {
+          currentProject.liveValidation = candidateProject.liveValidation;
+        } else {
+          delete currentProject.liveValidation;
+        }
+      } else if (Object.prototype.hasOwnProperty.call(update, 'liveValidation')) {
+        // Body sent liveValidation key but handleSettingsUpdate deleted it from
+        // the in-memory config (null / empty type) — propagate to disk.
+        delete currentProject.liveValidation;
+      }
     }
   }
   shared.pruneDefaultClaudeConfig(current);
@@ -1299,7 +1315,7 @@ function collectArchivedWorkItems(minionsDir = MINIONS_DIR, projects = PROJECTS)
   }
   return archived;
 }
-function linkPullRequestForTracking({ url, title, project: projectName, contextOnly, autoObserve, context, workItemId }, config = CONFIG, options = {}) {
+function linkPullRequestForTracking({ url, title, project: projectName, contextOnly, context, workItemId }, config = CONFIG, options = {}) {
   if (!url) {
     const err = new Error('url required');
     err.statusCode = 400;
@@ -1315,12 +1331,7 @@ function linkPullRequestForTracking({ url, title, project: projectName, contextO
   const linkedWorkItemId = getWorkItemIdFromPrLinkContext(context, workItemId);
   const contextText = typeof context === 'string' ? context : (context == null ? '' : JSON.stringify(context));
   const metadata = normalizePrMetadata(options.metadata);
-  // W-mq5s5ttx000j7ab8-c: canonical `contextOnly` field with `autoObserve`
-  // deprecated alias. Explicit canonical wins; otherwise fall back to the
-  // alias (autoObserve:true → contextOnly:false); otherwise default false.
-  const resolvedContextOnly = typeof contextOnly === 'boolean'
-    ? contextOnly
-    : (autoObserve === undefined ? false : !autoObserve);
+  const resolvedContextOnly = typeof contextOnly === 'boolean' ? contextOnly : false;
   const result = shared.upsertPullRequestRecord(prPath, {
     id: prId,
     prNumber: parseInt(prNum, 10) || null,
@@ -6974,7 +6985,11 @@ const server = http.createServer(async (req, res) => {
       if (!fs.existsSync(PRD_DIR)) fs.mkdirSync(PRD_DIR, { recursive: true });
 
       const planFile = 'manual-' + shared.uid() + '.json';
-      safeWrite(path.join(PRD_DIR, planFile), manualPrd.plan);
+      const manualPrdPath = path.join(PRD_DIR, planFile);
+      safeWrite(manualPrdPath, manualPrd.plan);
+      // Phase 10 step 2 — this create uses safeWrite (not mutateJsonFileLocked),
+      // so mirror to SQL explicitly. Best-effort.
+      prdStore.mirrorPrdToSql(manualPrdPath, manualPrd.plan);
       invalidatePlansCache();
       return jsonReply(res, 200, { ok: true, id: manualPrd.id, file: planFile });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
@@ -8303,6 +8318,10 @@ const server = http.createServer(async (req, res) => {
         cleanupPlanWorktrees(body.file, planObj || {}, PROJECTS, getConfig());
       } catch (e) { console.error('plan worktree cleanup:', e.message); }
       safeUnlink(planPath);
+      // Phase 10 step 2 — a deleted PRD must also leave SQL, or the read-flip
+      // (step 3) would resurrect it from a stale mirror row. Best-effort; no-op
+      // for non-PRD paths (parsePrdPath returns null for plan .md deletes).
+      if (body.file.endsWith('.json')) prdStore.removePrdFromSql(planPath);
       // Neutralize the `.backup` sidecar so `safeJson` auto-restore can't
       // RESURRECT the PRD we just deleted (the live file is gone, but a stray
       // `prd/<plan>.json.backup` would be auto-restored on the next safeJson read
@@ -9858,6 +9877,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         _emitTimingLog(_lifecycle, _tSessionReady, Date.now(), 'cancelled-pre-stream');
         return resolveResult({ text: accumulated, sessionId: sessionHandle.sessionId, code: 0, usage: {}, raw: accumulated, stderr: '' });
       }
+      let poolSegmentId = 0;
+      let segmentStart = 0;
       await sessionHandle.stream(prompt, {
         systemPromptText: systemPrompt,
         onChunk: (delta) => {
@@ -9866,7 +9887,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           accumulated += delta;
           _touchCcLiveStream(liveState);
           liveState.text = accumulated;
-          if (liveState.writer) liveState.writer({ type: 'chunk', text: accumulated });
+          const segmentText = accumulated.slice(segmentStart);
+          if (liveState.writer) liveState.writer({ type: 'chunk', text: segmentText, segmentId: poolSegmentId });
         },
         onToolUse: (name, input, toolCallId) => {
           if (_tFirstTool == null) _tFirstTool = Date.now();
@@ -9877,6 +9899,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           if (Array.isArray(toolUses)) toolUses.push(entry);
           if (Array.isArray(liveState.tools)) liveState.tools.push(entry);
           if (liveState.writer) liveState.writer({ type: 'tool', name, input: _lightToolInput(safeInput), id: toolCallId || null });
+          // Advance segment tracking so the next onChunk creates a fresh segment
+          poolSegmentId++;
+          segmentStart = accumulated.length;
         },
         onToolUpdate: (toolCallId, status) => {
           _touchCcLiveStream(liveState);
@@ -10865,6 +10890,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // the per-project dropdown. resolveCheckoutMode honors the legacy
           // worktreeMode field; 'worktree' (default) or 'live'.
           checkoutMode: shared.resolveCheckoutMode(p),
+          // M006 — surface liveValidation so the Settings UI can pre-fill
+          // the type input and autoDispatch toggle. Null when not configured.
+          liveValidation: (p.liveValidation && typeof p.liveValidation === 'object' && p.liveValidation.type)
+            ? { type: p.liveValidation.type, autoDispatch: !!p.liveValidation.autoDispatch }
+            : null,
           workSources: {
             pullRequests: { enabled: p.workSources?.pullRequests?.enabled !== false, cooldownMinutes: p.workSources?.pullRequests?.cooldownMinutes ?? 30 },
             workItems: { enabled: p.workSources?.workItems?.enabled !== false, cooldownMinutes: p.workSources?.workItems?.cooldownMinutes ?? 0 }
@@ -11289,10 +11319,19 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             // Drop the legacy field so a migrated project never carries both.
             delete proj.worktreeMode;
           }
+          // M006 — per-project liveValidation: { type, autoDispatch }.
+          // Only meaningful when checkoutMode is 'live'. Null / missing type
+          // clears the field; explicit object with a non-empty type persists it.
+          if (Object.prototype.hasOwnProperty.call(update, 'liveValidation')) {
+            const lv = update.liveValidation;
+            if (!lv || typeof lv !== 'object' || !lv.type || typeof lv.type !== 'string' || !lv.type.trim()) {
+              delete proj.liveValidation;
+            } else {
+              proj.liveValidation = { type: lv.type.trim(), autoDispatch: !!lv.autoDispatch };
+            }
+          }
         }
       }
-
-      shared.pruneDefaultClaudeConfig(config);
       mutateDashboardConfig(current => mergeSettingsConfigUpdate(current, config, body, _configPatch));
       // Refresh in-memory CONFIG so subsequent reads see the update
       reloadConfig();
@@ -13357,7 +13396,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // /api/prd/regenerate removed — use /api/plans/approve which does diff-aware update
 
     // Agents
-    { method: 'POST', path: '/api/pull-requests/link', desc: 'Manually link an external PR for tracking', params: 'url, title?, project?, contextOnly?, autoObserve? (deprecated alias for !contextOnly), context?, workItemId?', handler: async (req, res) => {
+    { method: 'POST', path: '/api/pull-requests/link', desc: 'Manually link an external PR for tracking', params: 'url, title?, project?, contextOnly?, context?, workItemId?', handler: async (req, res) => {
       const body = await readBody(req);
       const { url } = body;
       if (!url) return jsonReply(res, 400, { error: 'url required' });

package/docs/deprecated.json

@@ -3,26 +3,10 @@
     "id": "agent-config-skills-field",
     "description": "Legacy per-agent descriptive-metadata array `agents.<id>.skills` in config.json, renamed to `agents.<id>.expertise` to remove the name collision with executable runtime/harness skills (SKILL.md). The field is metadata only (capability tags like `architecture`, `bug-fixes`); nothing in the dispatch path reads it for behavior. A read-compat shim honors the old key so operator configs still carrying `skills` (and no `expertise`) keep working.",
     "code": [
-      {
-        "file": "engine/playbook.js",
-        "lines": "950",
-        "note": "buildSystemPrompt reads `agent.expertise ?? agent.skills ?? []` for the `Expertise:` identity line"
-      },
-      {
-        "file": "engine/lifecycle.js",
-        "lines": "4620-4621",
-        "note": "pickReReviewAgentHints reads `agent.expertise` with an `agent.skills` array fallback"
-      },
-      {
-        "file": "engine/queries.js",
-        "lines": "731",
-        "note": "getAgents normalizes `expertise: a.expertise ?? a.skills ?? []` so the dashboard/settings UI always receives `expertise`"
-      },
-      {
-        "file": "dashboard.js",
-        "lines": "10708-10716",
-        "note": "settings POST accepts a legacy `updates.skills` key, persists as `config.agents[id].expertise`, and deletes the old `skills` key"
-      }
+      { "file": "engine/playbook.js", "lines": "950", "note": "buildSystemPrompt reads `agent.expertise ?? agent.skills ?? []` for the `Expertise:` identity line" },
+      { "file": "engine/lifecycle.js", "lines": "4620-4621", "note": "pickReReviewAgentHints reads `agent.expertise` with an `agent.skills` array fallback" },
+      { "file": "engine/queries.js", "lines": "731", "note": "getAgents normalizes `expertise: a.expertise ?? a.skills ?? []` so the dashboard/settings UI always receives `expertise`" },
+      { "file": "dashboard.js", "lines": "10708-10716", "note": "settings POST accepts a legacy `updates.skills` key, persists as `config.agents[id].expertise`, and deletes the old `skills` key" }
     ],
     "removalGate": "Telemetry / a config sweep across all known engines must show no persisted `config.agents.<id>.skills` key (only `expertise`) for >=30 consecutive days, confirming every operator config has been re-saved through the dashboard (which drops the legacy key) or hand-migrated.",
     "targetRemovalDate": "2026-09-17",
@@ -47,10 +31,7 @@
   {
     "id": "legacy-done-aliases",
     "location": "engine/cleanup.js:1165-1166",
-    "constants": [
-      "LEGACY_DONE_ALIASES",
-      "LEGACY_NEEDS_REVIEW_STATUS"
-    ],
+    "constants": ["LEGACY_DONE_ALIASES", "LEGACY_NEEDS_REVIEW_STATUS"],
     "reason": "Read-side tolerance: cleanup sweep auto-migrates four obsolete work-item / PRD status strings ('in-pr', 'implemented', 'complete', 'needs-human-review') to the canonical 'done' / 'failed' values. The aliases are no longer written anywhere in the engine; the constants exist only to repair stale on-disk values from old engine versions.",
     "targetRemovalDate": null,
     "notes": "Keep indefinitely until telemetry / a sweep log shows zero migrations performed for 30 consecutive days across all known projects (work-items.json + prd/*.json). At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js (definitions at :1165-1166; usage at :1168-1183 for work items and :1269-1272 for PRD missing_features) can be deleted. Total cost on disk today: 4 strings."
@@ -59,21 +40,9 @@
     "id": "config-claude-binary-override",
     "description": "Legacy `config.claude.binary` runtime-resolution override. Older `minions init` versions persisted a `config.claude.binary` field that pointed the Claude runtime at a specific binary path. The runtime adapter still honors this override on every Claude spawn; the engine emits a `deprecated-config-claude` warning at config-load time but does NOT delete the override, so the override branch in claude.js is load-bearing for any install that still carries a non-default value.",
     "code": [
-      {
-        "file": "engine/runtimes/claude.js",
-        "lines": "82-86",
-        "note": "resolveBinary() respects config.claude.binary on every Claude spawn (probes npm package dir or direct binary path)"
-      },
-      {
-        "file": "engine/shared.js",
-        "lines": "2482-2496",
-        "note": "warnings.push({ id: 'deprecated-config-claude' }) — surface-only; never deletes the override"
-      },
-      {
-        "file": "engine/shared.js",
-        "lines": "3120-3124",
-        "note": "DEFAULT_CLAUDE.binary baseline that the warning + prune logic compares against"
-      }
+      { "file": "engine/runtimes/claude.js", "lines": "82-86", "note": "resolveBinary() respects config.claude.binary on every Claude spawn (probes npm package dir or direct binary path)" },
+      { "file": "engine/shared.js", "lines": "2482-2496", "note": "warnings.push({ id: 'deprecated-config-claude' }) — surface-only; never deletes the override" },
+      { "file": "engine/shared.js", "lines": "3120-3124", "note": "DEFAULT_CLAUDE.binary baseline that the warning + prune logic compares against" }
     ],
     "removalGate": "Telemetry: the `deprecated-config-claude` warning emitted at engine/shared.js:2492-2495 must report zero hits across all known engines for >=30 consecutive days, AND a sweep of every persisted config.json must show no `config.claude.binary` value that diverges from DEFAULT_CLAUDE.binary. Only then is the override branch in resolveBinary() (engine/runtimes/claude.js:82-86) removable, along with the `_deprecatedConfigClaudeFields` membership for `binary` and the warning emitter at engine/shared.js:2482-2496.",
     "targetRemovalDate": null,
@@ -83,41 +52,13 @@
     "id": "legacy-cc-model-migration",
     "description": "applyLegacyCcModelMigration: in-memory shim that promotes legacy `engine.ccModel` to `engine.defaultModel` when defaultModel is unset, so single-model installs keep working after the runtime fleet refactor (P-3b8e5f1d). No on-disk rewrite — the persisted config.json continues to carry the legacy `ccModel` field. Called unconditionally on every engine boot from cli.start().",
     "code": [
-      {
-        "file": "engine/shared.js",
-        "lines": "2407",
-        "note": "applyLegacyCcModelMigration definition (function signature + once-per-process flag via _resetLegacyCcModelMigrationFlag)"
-      },
-      {
-        "file": "engine/cli.js",
-        "lines": "477",
-        "note": "Boot call site inside start(); wrapped in try/catch so a migration failure cannot block startup"
-      },
-      {
-        "file": "CLAUDE.md",
-        "lines": "316",
-        "note": "Architectural documentation calling out the in-memory promotion contract"
-      },
-      {
-        "file": "docs/slim-ux/concepts.md",
-        "lines": "671",
-        "note": "Surface-level concepts doc cross-reference"
-      },
-      {
-        "file": "test/unit.test.js",
-        "lines": "19801",
-        "note": "Source-inspection test pinning the CLAUDE.md description against the function name"
-      },
-      {
-        "file": "test/unit/runtime-fleet-helpers.test.js",
-        "lines": "209-254",
-        "note": "Behavioural unit tests (promotion, no-op when defaultModel set, no-op when ccModel unset, empty-string handling, once-only logging, null-safety)"
-      },
-      {
-        "file": "test/unit/runtime-fleet-helpers.test.js",
-        "lines": "500-505",
-        "note": "Source-inspection test pinning the cli.js boot call site"
-      }
+      { "file": "engine/shared.js", "lines": "2407", "note": "applyLegacyCcModelMigration definition (function signature + once-per-process flag via _resetLegacyCcModelMigrationFlag)" },
+      { "file": "engine/cli.js", "lines": "477", "note": "Boot call site inside start(); wrapped in try/catch so a migration failure cannot block startup" },
+      { "file": "CLAUDE.md", "lines": "316", "note": "Architectural documentation calling out the in-memory promotion contract" },
+      { "file": "docs/slim-ux/concepts.md", "lines": "671", "note": "Surface-level concepts doc cross-reference" },
+      { "file": "test/unit.test.js", "lines": "19801", "note": "Source-inspection test pinning the CLAUDE.md description against the function name" },
+      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "209-254", "note": "Behavioural unit tests (promotion, no-op when defaultModel set, no-op when ccModel unset, empty-string handling, once-only logging, null-safety)" },
+      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "500-505", "note": "Source-inspection test pinning the cli.js boot call site" }
     ],
     "removalGate": "Telemetry: the once-per-boot deprecation log line emitted by applyLegacyCcModelMigration (via the injected logger at engine/shared.js:2407) must show zero promotion events across all known engines for >=30 consecutive days, AND a sweep of every persisted config.json must confirm no `engine.ccModel` field remains. Once both conditions hold, removal deletes the function + _resetLegacyCcModelMigrationFlag export at engine/shared.js:4977, the boot call at engine/cli.js:477, the CLAUDE.md:316 paragraph and docs/slim-ux/concepts.md:671 reference, and the tests at runtime-fleet-helpers.test.js:209-254 + :500-505 + unit.test.js:19801.",
     "targetRemovalDate": null,
@@ -127,39 +68,14 @@
     "id": "sql-state-json-mirrors",
     "description": "Phase X.5 follow-up to the SQL state migration (commits 62bd6a2c..1111cf54, phases 0–7). Every engine state file that previously used mutateJsonFileLocked now routes through a SQL store, but each store still writes a JSON dual-write mirror after every mutation because a handful of direct-readers (a few unit tests + a couple of inline safeJson calls) have not been migrated to the SQL read path. Once those readers are confirmed routed through the SQL store (or rewritten to use the store's read helper), the mirror writers can be deleted and the JSON files retired.",
     "code": [
-      {
-        "file": "engine/dispatch-store.js",
-        "note": "_mirrorJsonFromSql + _readDispatchJsonFallback — used when SQL is empty AND JSON has content (test seeding + first-time hydrate)"
-      },
-      {
-        "file": "engine/work-items-store.js",
-        "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope) — same fallback contract as dispatch-store"
-      },
-      {
-        "file": "engine/pull-requests-store.js",
-        "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope)"
-      },
-      {
-        "file": "engine/logs-store.js",
-        "note": "engine/log.json mirror written by shared._flushLogBuffer's byJsonPath loop — Phase 4.5 will retire"
-      },
-      {
-        "file": "engine/metrics-store.js",
-        "note": "_mirrorJsonFromSql + _readJsonObjectFallback"
-      },
-      {
-        "file": "engine/watches-store.js",
-        "note": "_mirrorJsonFromSql + _readJsonArrayFallback"
-      },
-      {
-        "file": "engine/small-state-store.js",
-        "note": "_mirrorScheduleRunsJson, _mirrorPipelineRunsJson, _mirrorManagedProcessesJson, _mirrorWorktreePoolJson + each store's _readJson fallback path"
-      },
-      {
-        "file": "CLAUDE.md",
-        "lines": "47-66, 240-265",
-        "note": "State Files + Concurrency sections still describe JSON files as the source of truth; they describe a layered SQLite-then-mirror reality in places but the headline contract still reads as JSON-primary. Rewrite these sections to make SQL-as-source-of-truth the headline and the JSON mirrors a transitional compatibility detail."
-      }
+      { "file": "engine/dispatch-store.js", "note": "_mirrorJsonFromSql + _readDispatchJsonFallback — used when SQL is empty AND JSON has content (test seeding + first-time hydrate)" },
+      { "file": "engine/work-items-store.js", "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope) — same fallback contract as dispatch-store" },
+      { "file": "engine/pull-requests-store.js", "note": "_mirrorJsonFromSql + _readJsonArrayFallback (per scope)" },
+      { "file": "engine/logs-store.js", "note": "engine/log.json mirror written by shared._flushLogBuffer's byJsonPath loop — Phase 4.5 will retire" },
+      { "file": "engine/metrics-store.js", "note": "_mirrorJsonFromSql + _readJsonObjectFallback" },
+      { "file": "engine/watches-store.js", "note": "_mirrorJsonFromSql + _readJsonArrayFallback" },
+      { "file": "engine/small-state-store.js", "note": "_mirrorScheduleRunsJson, _mirrorPipelineRunsJson, _mirrorManagedProcessesJson, _mirrorWorktreePoolJson + each store's _readJson fallback path" },
+      { "file": "CLAUDE.md", "lines": "47-66, 240-265", "note": "State Files + Concurrency sections still describe JSON files as the source of truth; they describe a layered SQLite-then-mirror reality in places but the headline contract still reads as JSON-primary. Rewrite these sections to make SQL-as-source-of-truth the headline and the JSON mirrors a transitional compatibility detail." }
     ],
     "removalGate": "All direct-readers of the mirror JSON files must be confirmed routed through their respective SQL store's read helper. Specifically: (a) grep the codebase for `safeJson`, `safeJsonArr`, `safeJsonObj`, `readFileSync(...work-items.json|pull-requests.json|metrics.json|watches.json|schedule-runs.json|pipeline-runs.json|managed-processes.json|worktree-pool.json|log.json|dispatch.json...)` and confirm every hit is either (i) a test fixture that can move to the SQL helper, or (ii) intentionally documented as bypassing SQL. (b) Run the full test suite with each store's _mirrorJsonFromSql temporarily neutered (returning early before safeWrite) and confirm 0 failures — that proves no production code path depends on the mirror. Once both conditions hold, removal deletes each store's _mirrorJsonFromSql call site in shared.js (mutateWorkItems/mutatePullRequests/etc.), the corresponding _readJsonArrayFallback paths, and the JSON file gitignore entries. CLAUDE.md update can ship independently as soon as someone has bandwidth.",
     "targetRemovalDate": null,
@@ -169,51 +85,15 @@
     "id": "prune-default-claude-config",
     "description": "pruneDefaultClaudeConfig: active sanitizer that strips generated `config.claude.{binary,outputFormat,allowedTools,permissionMode}` defaults from persisted config.json so the `deprecated-config-claude` warning stops tripping on stale defaults left by older `minions init` versions. Sub-cluster of `config-claude-binary-override` — the prune deliberately preserves non-default user overrides (binary/allowedTools), which is what keeps the override branch in engine/runtimes/claude.js load-bearing.",
     "code": [
-      {
-        "file": "engine/shared.js",
-        "lines": "3126",
-        "note": "pruneDefaultClaudeConfig definition: preserves non-default binary/allowedTools, always strips permissionMode + outputFormat"
-      },
-      {
-        "file": "engine/shared.js",
-        "lines": "5673",
-        "note": "Module export entry"
-      },
-      {
-        "file": "dashboard.js",
-        "lines": "202",
-        "note": "Called when loading config for the dashboard UI"
-      },
-      {
-        "file": "dashboard.js",
-        "lines": "9116",
-        "note": "Called during first config save handler"
-      },
-      {
-        "file": "dashboard.js",
-        "lines": "9331",
-        "note": "Called during second config save path"
-      },
-      {
-        "file": "dashboard.js",
-        "lines": "9450",
-        "note": "Called during third config save path"
-      },
-      {
-        "file": "minions.js",
-        "lines": "385",
-        "note": "Called during CLI init/update flow"
-      },
-      {
-        "file": "test/unit.test.js",
-        "lines": "2260-2303",
-        "note": "Behavioural unit tests (default strip, override preservation, outputFormat unconditional strip) + dashboard call-site source pin"
-      },
-      {
-        "file": "test/unit/runtime-fleet-helpers.test.js",
-        "lines": "546",
-        "note": "Source-inspection test pinning the dashboard handler call site"
-      }
+      { "file": "engine/shared.js", "lines": "3126", "note": "pruneDefaultClaudeConfig definition: preserves non-default binary/allowedTools, always strips permissionMode + outputFormat" },
+      { "file": "engine/shared.js", "lines": "5673", "note": "Module export entry" },
+      { "file": "dashboard.js", "lines": "202", "note": "Called when loading config for the dashboard UI" },
+      { "file": "dashboard.js", "lines": "9116", "note": "Called during first config save handler" },
+      { "file": "dashboard.js", "lines": "9331", "note": "Called during second config save path" },
+      { "file": "dashboard.js", "lines": "9450", "note": "Called during third config save path" },
+      { "file": "minions.js", "lines": "385", "note": "Called during CLI init/update flow" },
+      { "file": "test/unit.test.js", "lines": "2260-2303", "note": "Behavioural unit tests (default strip, override preservation, outputFormat unconditional strip) + dashboard call-site source pin" },
+      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "546", "note": "Source-inspection test pinning the dashboard handler call site" }
     ],
     "removalGate": "Telemetry: pruneDefaultClaudeConfig must return false (no mutation) for every call across all known engines for >=30 consecutive days (add an `_engine.pruneDefaultClaudeConfigStrips` counter if needed to observe this), AND the parent `config-claude-binary-override` entry must have already cleared its own gate. The dependency is strict: removing the prune while users still rely on the override branch would surface the `deprecated-config-claude` warning on every stale generated default. Once both conditions hold, removal is the function definition (engine/shared.js:3126), the export at :5673, all 5 call sites (dashboard.js:202, :9116, :9331, :9450; minions.js:385), and the tests at unit.test.js:2260-2303 + runtime-fleet-helpers.test.js:546.",
     "targetRemovalDate": null,
@@ -226,10 +106,7 @@
     "status": "removed",
     "removedDate": "2026-06-25",
     "code": [
-      {
-        "file": "engine/ado.js",
-        "note": "isAdoThrottled() arg-less branch and the global-OR fold over the per-org Map. Single call site to migrate: shared.getAdoOrgBase(project) is already in scope at every consumer."
-      }
+      { "file": "engine/ado.js", "note": "isAdoThrottled() arg-less branch and the global-OR fold over the per-org Map. Single call site to migrate: shared.getAdoOrgBase(project) is already in scope at every consumer." }
     ],
     "removalGate": "Two conditions must hold simultaneously: (a) grep `engine/ado.js` for `isAdoThrottled\\s*\\(\\s*\\)` and confirm zero arg-less call sites remain across the engine — every caller passes a concrete `orgBase` resolved via `shared.getAdoOrgBase(project)`; (b) `GET /api/diagnostics/ado-throttle` on a live engine has been observed for >=2 consecutive weeks reporting per-org keys (proves the per-org Map is populated under load and the global-OR isn't masking a regression). Once both hold, removal deletes the arg-less branch in isAdoThrottled and the global-OR fold; callers that still pass no argument become an immediate, surfaced bug rather than a silent over-throttle.",
     "targetRemovalDate": "2026-08-03",
@@ -273,13 +150,10 @@
     "id": "pr-observe-observe-body-param",
     "description": "Legacy `observe` body parameter on `POST /api/pull-requests/observe`. The W-mq5s5ttx000j7ab8 endpoint sub-WI introduces canonical `contextOnly` as the inverse (`observe: false` ⇔ `contextOnly: true`) and keeps `observe` accepted for backward compat. Registering the deprecation here so the alias has a documented removal path; the WI explicitly notes this entry is the implementer's call (it is kept for backward compat and may live longer than the underscore-prefixed record fields).",
     "code": [
-      {
-        "file": "dashboard.js",
-        "note": "POST /api/pull-requests/observe handler reads `body.contextOnly` first, then falls back to `!body.observe` for backwards compat."
-      }
+      { "file": "dashboard.js", "note": "POST /api/pull-requests/observe handler reads `body.contextOnly` first, then falls back to `!body.observe` for backwards compat." }
     ],
     "deprecated": "2026-06-08",
     "targetRemovalDate": null,
     "notes": "targetRemovalDate intentionally null — unlike the record-field aliases (`_contextOnly`, `_autoObserve`, `_manual`) which carry a 7-day clock, the `observe` body param is documented as a longer-lived back-compat alias. Set targetRemovalDate to a concrete future date once the dashboard UI + any client scripts are confirmed to POST `contextOnly` exclusively. Removal scope when the date is set: drop the `body.observe` fallback in dashboard.js, drop `observe` from the route registry params, and update any client still POSTing `observe`."
   }
-]
+]

package/docs/live-checkout-mode.md

@@ -152,6 +152,60 @@ git for-each-ref --format '%(refname:short) %(upstream:track)' refs/heads \
 
 The engine has no opinion about local branches; this hygiene is the operator's responsibility in live mode.
 
+## Hybrid mode / deferred validation
+
+> **Requires `checkoutMode: 'live'`** — `liveValidation` is ignored when `checkoutMode` is `'worktree'` (the default).
+
+Hybrid mode lets you run *coding* work items (implement, fix, docs, …) in isolated worktrees while keeping *validation* work items (build-and-test, test, verify, …) serialized in live checkout — the setup where build caches, native toolchains, and test infrastructure only exist in one canonical checkout.
+
+### Full flow
+
+1. **Coding WI dispatched** — because `liveValidation.type` is set and this WI's type is *not* the validation type, `resolveCheckoutMode(project, workItem.type)` returns `'worktree'`. The engine creates an isolated worktree as normal, runs the agent, and pushes a PR branch.
+2. **Coding WI completes** — if `liveValidation.autoDispatch: true`, the lifecycle hook (`engine/lifecycle.js`) auto-creates a validation WI of type `liveValidation.type` targeting the same PR branch.
+3. **Validation WI dispatched** — `resolveCheckoutMode(project, 'build-and-test')` returns `'live'` (matches `liveValidation.type`). The engine runs `prepareLiveCheckout` in the operator's canonical checkout, which checks out the coding WI's branch in-place and runs the validation agent.
+4. **Validation WI completes** — `restoreLiveCheckoutAtDispatchEnd` checks the operator's tree back to the original ref.
+
+### Config snippet
+
+```jsonc
+{
+  "projects": [{
+    "name": "android-aosp",
+    "localPath": "/home/yemi/aosp",
+    "checkoutMode": "live",
+    "liveValidation": {
+      "type": "build-and-test",
+      "autoDispatch": true
+    }
+  }]
+}
+```
+
+Configure via Dashboard → Settings → Projects → **Live validation (deferred build/test)** section. The section is greyed-out when `checkoutMode` is not `'live'`.
+
+### Agent behavior contract
+
+When a coding agent is dispatched on a project with `liveValidation.autoDispatch: true`, the agent's playbook includes a note that inline build/test runs are not required:
+
+> Skip inline build and test verification steps — a separate validation dispatch will run these in the live checkout after this coding WI completes. Push the branch and report success; the validation WI handles build/test confirmation.
+
+This prevents coding agents (running in isolated worktrees) from attempting builds that may fail due to missing native toolchains, caches, or environment variables only present in the canonical checkout.
+
+### Migration guidance
+
+If your project is on `checkoutMode: live` and you want parallel coding WIs, add:
+
+```jsonc
+"liveValidation": { "type": "build-and-test", "autoDispatch": true }
+```
+
+No other config changes needed. The engine automatically:
+- Dispatches coding WIs into isolated worktrees (escaping the live-checkout cap of 1)
+- Dispatches validation WIs serially in live checkout (preserving your build environment)
+- Auto-creates validation WIs after each coding WI's PR is pushed
+
+To opt back out, clear `liveValidation` from the project config (or set to `null` via Dashboard → Settings).
+
 ## Non-goals
 
 Live-checkout mode is deliberately small. These are NOT supported and will not be added:

package/docs/project-skills.md

@@ -13,7 +13,6 @@ This document is the contract every playbook author and project teammate needs t
 | `engine/discover-project-skills.js` | Bounded filesystem walk + classification heuristic. The crash-safe primitive. |
 | `engine/playbook-intents.js` | Single source of truth for the playbook → intent set mapping. |
 | `engine/playbook.js` | Calls discovery + filter at render time, injects `{{project_skills_block}}` into the rendered prompt. |
-| `engine/discover-review-skills.js` | Thin re-export shim. Backward-compat only — new code uses `discover-project-skills.js`. |
 
 ## What gets discovered
 

package/engine/cleanup.js

@@ -458,6 +458,40 @@ function reapAgentScratch(worktreeRoot) {
   return reaped;
 }
 
+// Disposable agent-deliverable scratch that piles up in knowledge/: per-batch
+// cleanup implementation/analysis notes and the regenerable consolidated digests.
+// These are gitignored working notes nothing reads back — emitted by the
+// simplify/KB-cleanup sweeps at daily cadence, they accumulate forever otherwise.
+// The pattern is intentionally NARROW: curated KB entries and the per-agent
+// memory files (knowledge/agents/<id>.md) never match it and are never touched.
+const KNOWLEDGE_SCRATCH_RE = /(?:kb-cleanup-batch|consolidated-digest|consolidated-ci-health)/i;
+const KNOWLEDGE_SCRATCH_TTL_MS = 48 * 60 * 60 * 1000; // 48h — keep a couple days for reference, reap older
+const KNOWLEDGE_SCRATCH_MAX_SCAN = 5000;
+
+function reapKnowledgeScratch(minionsDir = MINIONS_DIR) {
+  const dir = path.join(minionsDir, 'knowledge');
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return 0; } // no knowledge dir → nothing to do
+  const cutoff = Date.now() - KNOWLEDGE_SCRATCH_TTL_MS;
+  let reaped = 0;
+  const limit = Math.min(names.length, KNOWLEDGE_SCRATCH_MAX_SCAN);
+  for (let i = 0; i < limit; i++) {
+    const name = names[i];
+    // Only top-level .md files whose name matches the disposable-scratch pattern.
+    if (!name.endsWith('.md') || !KNOWLEDGE_SCRATCH_RE.test(name)) continue;
+    const full = path.join(dir, name);
+    let stat;
+    try { stat = fs.statSync(full); } catch { continue; }
+    if (!stat.isFile() || stat.mtimeMs >= cutoff) continue; // recent — keep for reference
+    try { fs.unlinkSync(full); reaped++; }
+    catch { /* locked / in use — leave it for a later pass */ }
+  }
+  if (reaped > 0) {
+    log('info', `Reaped ${reaped} stale knowledge-scratch notes (>${Math.round(KNOWLEDGE_SCRATCH_TTL_MS / 3600000)}h) from ${dir}`);
+  }
+  return reaped;
+}
+
 // ─── Cleanup Orchestrator ────────────────────────────────────────────────────
 
 async function runCleanup(config, verbose = false) {
@@ -742,7 +776,11 @@ async function runCleanup(config, verbose = false) {
     }
 
     // Get PRs for this project
-    const prs = safeJson(projectPrPath(project)) || [];
+    // Array.isArray guard: safeJson(p) || [] only substitutes [] for falsy values;
+    // a truthy non-array (e.g. {}, 42, true) bypasses the fallback and causes a
+    // TypeError in the for-of loop below. Array.isArray covers that case.
+    const _prsRaw = safeJson(projectPrPath(project));
+    const prs = Array.isArray(_prsRaw) ? _prsRaw : [];
     const mergedBranches = new Set();
     for (const pr of prs) {
       if (pr.status === shared.PR_STATUS.MERGED || pr.status === shared.PR_STATUS.ABANDONED) {
@@ -960,7 +998,10 @@ async function runCleanup(config, verbose = false) {
       // Remove all marked worktrees
       // Re-read PR status immediately before deletion — a PR can be reopened between
       // the initial status check and the actual deletion (Bug #15: TOCTOU race)
-      const freshPrs = safeJson(projectPrPath(project)) || [];
+      // Array.isArray guard: same as the prs read above — non-array truthy JSON
+      // bypasses || [] and would throw inside the try-catch, silently skipping deletions.
+      const _freshPrsRaw = safeJson(projectPrPath(project));
+      const freshPrs = Array.isArray(_freshPrsRaw) ? _freshPrsRaw : [];
       const freshMergedBranches = new Set();
       const freshMergedPrByBranch = new Map();
       for (const pr of freshPrs) {
@@ -1585,6 +1626,13 @@ async function runCleanup(config, verbose = false) {
     }
   } catch (e) { log('warn', `pruneStaleBackupSidecars: ${e.message}`); }
 
+  // 17. Reap stale gitignored knowledge-scratch notes (kb-cleanup-batch / digests)
+  // that the simplify/KB-cleanup sweeps emit into knowledge/ and never read back.
+  cleaned.knowledgeScratch = 0;
+  try {
+    cleaned.knowledgeScratch = reapKnowledgeScratch();
+  } catch (e) { log('warn', `reapKnowledgeScratch: ${e.message}`); }
+
   return cleaned;
 }
 
@@ -1738,4 +1786,5 @@ module.exports = {
   cleanupMergedPrLocalBranch, // exported for lifecycle cleanup and testing
   collectPhantomBranchesForProject, // P-e0b4f7a5 — exported for testing
   reapAgentScratch,                 // exported for testing
+  reapKnowledgeScratch,             // exported for testing
 };

package/engine/features.js

@@ -78,6 +78,20 @@ const FEATURES = {
     addedIn: '0.1.1916',
     requiredCcRuntime: 'copilot',
   },
+  // prdReadsFromSql — Phase 10 step 3 read-flip. When ON, getPrdInfo sources its
+  // PRD list (existingPrds / verifyPrsByPlan / allPrdItems) from the SQL mirror
+  // (prds/prd_items/prd_verify_prs) after reconciling it from disk, instead of
+  // scanning prd/*.json directly. JSON stays canonical and the dual-write keeps
+  // SQL in sync; reconciliation catches PRDs written outside the chokepoint. The
+  // two code paths are proven output-equivalent by db-phase10-read-flip.test.js.
+  // Reversible: set `features.prdReadsFromSql: false` to fall back to the file
+  // scan instantly. Temporary migration gate — remove once the read-flip soaks.
+  'prdReadsFromSql': {
+    description: 'Source the dashboard PRD/plan read (getPrdInfo) from the SQL mirror instead of scanning prd/*.json. Reversible; the two paths are output-equivalent (Phase 10 step 3).',
+    default: true,
+    addedIn: '0.1.2090',
+    expires: '2026-12-01',
+  },
 };
 
 const ENV_TRUTHY = new Set(['1', 'true', 'on', 'yes']);

package/engine/llm.js

@@ -405,6 +405,7 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
     maxBudget, bare, fallbackModel,
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
     images,
+    tmpDir: llmTmpDir,
   };
   // Capability-gate per-flag opts before prompt construction so adapters can
   // make resume-aware prompt decisions from the same opts used for argv.

package/engine/playbook.js

@@ -1007,11 +1007,11 @@ function renderPlaybook(type, vars) {
 // ─── Playbook Section Validator ──────────────────────────────────────────────
 
 // Required structural section patterns — warn (do not throw) when absent.
-// Pluralisation: /^## Tools?\b/m matches both '## Tool' and '## Tools'.
+// NOTE: '## Tools' / '## Constraints' are NOT included because none of the
+// production playbooks use those headers. Only '## Your Task' is universally
+// present — it is injected by renderPlaybook via the playbook template.
 const _REQUIRED_PROMPT_SECTIONS = [
-  { pattern: /^## Your Task\b/m,   label: '## Your Task' },
-  { pattern: /^## Tools?\b/m,      label: '## Tools' },
-  { pattern: /^## Constraints\b/m, label: '## Constraints' },
+  { pattern: /^## Your Task\b/m, label: '## Your Task' },
 ];
 
 /**