@yemi33/minions 0.1.2285 → 0.1.2287

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' },
 ];
 
 /**

package/engine/prd-store.js

@@ -0,0 +1,264 @@
+// engine/prd-store.js
+//
+// Phase 10 step 2: SQL mirror for PRD state. PRD content writes go to the
+// canonical prd/*.json file AND are mirrored into the plans/prds/prd_items/
+// prd_verify_prs tables created by migration 015. JSON stays canonical and is
+// still the only thing read in this step — the SQL side is a passive mirror so
+// the read-flip (step 3) has a trustworthy source.
+//
+// All entry points are BEST-EFFORT: a SQLite failure (Node < 22.5, locked DB,
+// schema not yet migrated) must never break a PRD JSON write. Callers wrap via
+// the thin `mirror*`/`remove*` helpers which swallow and return {ok:false}.
+
+const path = require('path');
+const fs = require('fs');
+
+function _toMs(v) {
+  if (v == null) return null;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  const parsed = Date.parse(v);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function _bool01(v) { return v ? 1 : 0; }
+
+// Resolve <MINIONS_DIR>/prd/<f>.json → {filename, archived:0}; the
+// prd/archive/<f>.json variant → {filename, archived:1}; anything else → null.
+// Path comparison is normalized + case-insensitive on the directory prefix so
+// Windows drive-letter / separator differences don't cause a miss.
+function parsePrdPath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return null;
+  let minionsDir;
+  try { minionsDir = require('./shared').MINIONS_DIR; } catch { return null; }
+  if (!minionsDir) return null;
+  const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
+  const full = norm(filePath);
+  const prdRoot = norm(path.join(minionsDir, 'prd'));
+  const archiveRoot = norm(path.join(minionsDir, 'prd', 'archive'));
+  if (!full.endsWith('.json')) return null;
+  const base = path.basename(filePath);
+  if (full === norm(path.join(archiveRoot, base)) && full.startsWith(archiveRoot + '/')) {
+    return { filename: base, archived: 1 };
+  }
+  if (full === norm(path.join(prdRoot, base)) && full.startsWith(prdRoot + '/')) {
+    return { filename: base, archived: 0 };
+  }
+  return null;
+}
+
+// (filename, archived) → plans.id, preferring the same archived bucket.
+function _resolvePlanId(db, sourcePlan, archived) {
+  if (!sourcePlan) return null;
+  const same = db.prepare('SELECT id FROM plans WHERE filename=? AND archived=? ORDER BY id LIMIT 1').get(sourcePlan, archived);
+  if (same) return same.id;
+  const other = db.prepare('SELECT id FROM plans WHERE filename=? ORDER BY id LIMIT 1').get(sourcePlan);
+  return other ? other.id : null;
+}
+
+// Core upsert: write/replace the prds row + its prd_items + prd_verify_prs for
+// (filename, archived). Returns the prds.id. Runs inside a transaction.
+function _upsertPrd(db, filename, archived, prd, now) {
+  const sourcePlan = prd.source_plan || prd.sourcePlan || null;
+  const planId = _resolvePlanId(db, sourcePlan, archived);
+  const existing = db.prepare('SELECT id, created_at FROM prds WHERE filename=? AND archived=?').get(filename, archived);
+
+  let prdId;
+  if (existing) {
+    prdId = existing.id;
+    db.prepare(`
+      UPDATE prds SET plan_id=?, project=?, version=?, status=?,
+        completed_at=?, completion_notified=?, plan_stale=?, source_plan=?,
+        source_plan_modified_at=?, data=?, updated_at=? WHERE id=?
+    `).run(
+      planId, prd.project || null, prd.version != null ? String(prd.version) : null, prd.status || null,
+      _toMs(prd.completedAt || prd.completed_at), _bool01(prd._completionNotified), _bool01(prd.planStale),
+      sourcePlan, prd.sourcePlanModifiedAt || prd.source_plan_modified_at || null,
+      JSON.stringify(prd), now, prdId,
+    );
+    db.prepare('DELETE FROM prd_items WHERE prd_id=?').run(prdId);
+    db.prepare('DELETE FROM prd_verify_prs WHERE prd_id=?').run(prdId);
+  } else {
+    const info = db.prepare(`
+      INSERT INTO prds (plan_id, filename, project, version, status, archived,
+        completed_at, completion_notified, plan_stale, source_plan,
+        source_plan_modified_at, data, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      planId, filename, prd.project || null, prd.version != null ? String(prd.version) : null, prd.status || null, archived,
+      _toMs(prd.completedAt || prd.completed_at), _bool01(prd._completionNotified), _bool01(prd.planStale),
+      sourcePlan, prd.sourcePlanModifiedAt || prd.source_plan_modified_at || null,
+      JSON.stringify(prd), _toMs(prd.generated_at || prd.createdAt) || now, now,
+    );
+    prdId = Number(info.lastInsertRowid);
+  }
+
+  const insItem = db.prepare(`
+    INSERT INTO prd_items (prd_id, feature_id, name, project, status, type, work_item_id, data, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const features = Array.isArray(prd.missing_features) ? prd.missing_features : [];
+  for (const ft of features) {
+    if (!ft || typeof ft !== 'object') continue;
+    try {
+      insItem.run(prdId, ft.id || null, ft.name || null, ft.project || prd.project || null,
+        ft.status || null, ft.type || null, ft.workItemId || ft.work_item_id || null,
+        JSON.stringify(ft), now);
+    } catch { /* dup (prd_id, feature_id) → skip */ }
+  }
+
+  const insVp = db.prepare(`
+    INSERT INTO prd_verify_prs (prd_id, pr_id, url, title, status, project, merged_at, data, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const verifyPrs = Array.isArray(prd.verifyPrs) ? prd.verifyPrs : [];
+  for (const vp of verifyPrs) {
+    if (!vp || typeof vp !== 'object') continue;
+    try {
+      insVp.run(prdId, vp.id != null ? String(vp.id) : null, vp.url || null, vp.title || null,
+        vp.status || null, vp.project || prd.project || null, _toMs(vp.mergedAt || vp.merged_at),
+        JSON.stringify(vp), now);
+    } catch { /* best-effort */ }
+  }
+  return prdId;
+}
+
+// Mirror a PRD object to SQL for the given prd/*.json path. Best-effort.
+function mirrorPrdToSql(filePath, prd) {
+  const parsed = parsePrdPath(filePath);
+  if (!parsed || !prd || typeof prd !== 'object' || Array.isArray(prd)) return { ok: false, reason: 'not-a-prd' };
+  try {
+    const { getDb, withTransaction } = require('./db');
+    const db = getDb();
+    withTransaction(db, () => _upsertPrd(db, parsed.filename, parsed.archived, prd, Date.now()));
+    try { require('./db-events').emitStateEvent('prds', { filename: parsed.filename, archived: parsed.archived }); } catch { /* event optional */ }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: e && e.message };
+  }
+}
+
+// Remove a PRD (and its items/verify rows) from SQL for the given path. Best-effort.
+function removePrdFromSql(filePath) {
+  const parsed = parsePrdPath(filePath);
+  if (!parsed) return { ok: false, reason: 'not-a-prd' };
+  try {
+    const { getDb, withTransaction } = require('./db');
+    const db = getDb();
+    withTransaction(db, () => {
+      const row = db.prepare('SELECT id FROM prds WHERE filename=? AND archived=?').get(parsed.filename, parsed.archived);
+      if (!row) return;
+      db.prepare('DELETE FROM prd_items WHERE prd_id=?').run(row.id);
+      db.prepare('DELETE FROM prd_verify_prs WHERE prd_id=?').run(row.id);
+      db.prepare('DELETE FROM prds WHERE id=?').run(row.id);
+    });
+    try { require('./db-events').emitStateEvent('prds', { filename: parsed.filename, archived: parsed.archived, removed: true }); } catch { /* optional */ }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: e && e.message };
+  }
+}
+
+// Read one PRD back from SQL as the original object (the `data` blob). Used by
+// the divergence test now and the read-flip in step 3.
+function readPrdFromSql(filePath) {
+  const parsed = parsePrdPath(filePath);
+  if (!parsed) return null;
+  try {
+    const { getDb } = require('./db');
+    const row = getDb().prepare('SELECT data FROM prds WHERE filename=? AND archived=?').get(parsed.filename, parsed.archived);
+    return row ? JSON.parse(row.data) : null;
+  } catch { return null; }
+}
+
+// Per-process mtime cache so reconciliation re-mirrors only files that actually
+// changed on disk since this process last saw them (empty after restart → the
+// first read re-mirrors everything once). Keyed `${archived} ${filename}`.
+const _reconcileMtimes = new Map();
+
+function _prdDirsFor(minionsDir) {
+  return [
+    { dir: path.join(minionsDir, 'prd'), archived: 0 },
+    { dir: path.join(minionsDir, 'prd', 'archive'), archived: 1 },
+  ];
+}
+
+// Reconcile the SQL mirror from the prd/ + prd/archive/ directories: re-mirror
+// files that are new or changed on disk (catches PRDs written OUTSIDE the
+// mutateJsonFileLocked chokepoint — e.g. the plan-to-prd agent writing the JSON
+// directly, or an archive file-move), and drop SQL rows whose backing file is
+// gone. Best-effort; safe to call on every read. Returns a small stats object.
+function reconcilePrdsFromDisk() {
+  let minionsDir;
+  try { minionsDir = require('./shared').MINIONS_DIR; } catch { return { ok: false }; }
+  if (!minionsDir) return { ok: false };
+  let db;
+  try { db = require('./db').getDb(); } catch { return { ok: false }; }
+
+  let mirrored = 0, removed = 0;
+  const seen = new Set(); // `${archived} ${filename}` present on disk
+  for (const { dir, archived } of _prdDirsFor(minionsDir)) {
+    let files;
+    try { files = fs.readdirSync(dir).filter(f => f.endsWith('.json')); } catch { continue; }
+    for (const f of files) {
+      const key = `${archived} ${f}`;
+      seen.add(key);
+      const full = path.join(dir, f);
+      let mtime;
+      try { mtime = Math.round(fs.statSync(full).mtimeMs); } catch { continue; }
+      if (_reconcileMtimes.get(key) === mtime) continue; // unchanged since last seen
+      const prd = _readJsonObj(full);
+      if (!prd) continue;
+      try {
+        const { withTransaction } = require('./db');
+        withTransaction(db, () => _upsertPrd(db, f, archived, prd, Date.now()));
+        _reconcileMtimes.set(key, mtime);
+        mirrored += 1;
+      } catch { /* best-effort */ }
+    }
+  }
+  // Drop rows whose backing file disappeared (delete/move not caught by a hook).
+  try {
+    const rows = db.prepare('SELECT id, filename, archived FROM prds').all();
+    for (const r of rows) {
+      const key = `${r.archived} ${r.filename}`;
+      if (seen.has(key)) continue;
+      try {
+        require('./db').withTransaction(db, () => {
+          db.prepare('DELETE FROM prd_items WHERE prd_id=?').run(r.id);
+          db.prepare('DELETE FROM prd_verify_prs WHERE prd_id=?').run(r.id);
+          db.prepare('DELETE FROM prds WHERE id=?').run(r.id);
+        });
+        _reconcileMtimes.delete(key);
+        removed += 1;
+      } catch { /* best-effort */ }
+    }
+  } catch { /* best-effort */ }
+  return { ok: true, mirrored, removed };
+}
+
+// List every PRD row as { filename, archived, plan } where plan is the parsed
+// data blob. Sorted by (archived, filename) for deterministic consumer order
+// (matches the disk-scan order once the caller also sorts). Read-flip source.
+function listPrdRows() {
+  try {
+    const db = require('./db').getDb();
+    const rows = db.prepare('SELECT filename, archived, data FROM prds ORDER BY archived, filename').all();
+    const out = [];
+    for (const r of rows) {
+      let plan;
+      try { plan = JSON.parse(r.data); } catch { continue; }
+      out.push({ filename: r.filename, archived: !!r.archived, plan });
+    }
+    return out;
+  } catch { return []; }
+}
+
+module.exports = {
+  parsePrdPath,
+  mirrorPrdToSql,
+  removePrdFromSql,
+  readPrdFromSql,
+  reconcilePrdsFromDisk,
+  listPrdRows,
+  _reconcileMtimes, // exported for tests (reset between cases)
+  _upsertPrd, // exported for tests
+};

package/engine/queries.js

@@ -2150,70 +2150,108 @@ function getPrdInfo(config) {
     { dir: PRD_DIR, archived: false },
     { dir: path.join(PRD_DIR, 'archive'), archived: true },
   ];
-  for (const { dir, archived } of planDirs) {
+
+  // Phase 10 step 3 (read-flip) — both the disk scan and the SQL-mirror source
+  // funnel each PRD through this one processor, so the consumed shape
+  // (existingPrds / verifyPrsByPlan / allPrdItems) is identical by construction.
+  // The only difference is where `plan` + `mtimeMs` come from. Equivalence of the
+  // two paths is proven by test/unit/db-phase10-read-flip.test.js.
+  const processPrd = (pf, archived, plan, mtimeMs) => {
+    if (!plan || !plan.missing_features) return;
+    // Staleness: gate on actual source-plan content change rather than mtime
+    // alone (W-mqfevwr60018bd09). Pure path / pure mtime drifts return
+    // stale=false so a repointed source_plan doesn't masquerade as a revision.
+    let planStale = false;
+    if (!archived && plan.source_plan) {
+      try { planStale = shared.isSourcePlanContentStale(PLANS_DIR, plan).stale; } catch { /* optional */ }
+    }
+    existingPrds.push({
+      file: pf,
+      status: plan.status || 'active',
+      planStale: planStale || plan.planStale || false,
+      completedAt: plan.completedAt || '',
+      _archived: archived,
+    });
+    if (Array.isArray(plan.verifyPrs) && plan.verifyPrs.length > 0) {
+      verifyPrsByPlan[pf] = plan.verifyPrs.map(r => ({
+        id: r.id, url: r.url || '', title: r.title || '',
+        status: r.status || 'active', project: r.project || '',
+        ...(r.mergedAt ? { mergedAt: r.mergedAt } : {}),
+      }));
+    }
+    for (const f of plan.missing_features) {
+      allPrdItems.push({
+        ...f, _source: pf, _planStatus: plan.status || 'active',
+        _planSummary: plan.plan_summary || pf, _planProject: plan.project || '',
+        _archived: archived, _sourcePlan: plan.source_plan || '',
+        _branchStrategy: plan.branch_strategy || 'parallel',
+        _planStale: planStale || plan.planStale || false, _lastSyncedFromPlan: plan.lastSyncedFromPlan || null,
+        _prdUpdatedAt: new Date(mtimeMs).toISOString(),
+        _prdCompletedAt: plan.completedAt || '',
+      });
+    }
+  };
+
+  let useSqlReads = false;
+  try { useSqlReads = require('./features').isFeatureOn('prdReadsFromSql', config); } catch { /* fall back to disk */ }
+
+  if (useSqlReads) {
+    // SQL source: reconcile the mirror from disk (catches PRDs written outside
+    // the dual-write chokepoint — plan-to-prd agent direct writes, archive
+    // moves, deletes), then read each PRD's content from SQL. Files still live on
+    // disk in this phase, so stat them for the mtime fields + `age`.
     try {
-      const planFiles = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
-      for (const pf of planFiles) {
+      const prdStore = require('./prd-store');
+      prdStore.reconcilePrdsFromDisk();
+      for (const { filename, archived, plan } of prdStore.listPrdRows()) {
         try {
-          const filePath = path.join(dir, pf);
-          const stat = fs.statSync(filePath);
-          if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
-
-          // Per-file mtime cache: only re-read files that changed
-          const cached = _prdFileCache.get(filePath);
-          let plan;
-          if (cached && cached.mtimeMs === stat.mtimeMs) {
-            plan = cached.plan;
-          } else {
-            plan = readJsonNoRestore(filePath);
-            _prdFileCache.set(filePath, { mtimeMs: stat.mtimeMs, plan });
-          }
-          if (!plan || !plan.missing_features) continue;
-
-          // Staleness: gate on actual source-plan content change rather
-          // than mtime alone (W-mqfevwr60018bd09). Pure path / pure mtime
-          // drifts return stale=false here so a repointed source_plan
-          // doesn't masquerade as a real revision in the cached PRD info.
-          let planStale = false;
-          if (!archived && plan.source_plan) {
-            try {
-              planStale = shared.isSourcePlanContentStale(PLANS_DIR, plan).stale;
-            } catch { /* optional */ }
-          }
-          existingPrds.push({
-            file: pf,
-            status: plan.status || 'active',
-            planStale: planStale || plan.planStale || false,
-            completedAt: plan.completedAt || '',
-            _archived: archived,
-          });
-          if (Array.isArray(plan.verifyPrs) && plan.verifyPrs.length > 0) {
-            verifyPrsByPlan[pf] = plan.verifyPrs.map(r => ({
-              id: r.id, url: r.url || '', title: r.title || '',
-              status: r.status || 'active', project: r.project || '',
-              ...(r.mergedAt ? { mergedAt: r.mergedAt } : {}),
-            }));
-          }
-          for (const f of plan.missing_features) {
-            allPrdItems.push({
-              ...f, _source: pf, _planStatus: plan.status || 'active',
-              _planSummary: plan.plan_summary || pf, _planProject: plan.project || '',
-              _archived: archived, _sourcePlan: plan.source_plan || '',
-              _branchStrategy: plan.branch_strategy || 'parallel',
-              _planStale: planStale || plan.planStale || false, _lastSyncedFromPlan: plan.lastSyncedFromPlan || null,
-              _prdUpdatedAt: new Date(stat.mtimeMs).toISOString(),
-              _prdCompletedAt: plan.completedAt || '',
-            });
-          }
+          const dir = archived ? path.join(PRD_DIR, 'archive') : PRD_DIR;
+          let mtimeMs = 0;
+          try {
+            const stat = fs.statSync(path.join(dir, filename));
+            mtimeMs = stat.mtimeMs;
+            if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
+          } catch { /* file may have just moved/deleted between reconcile and read */ }
+          processPrd(filename, archived, plan, mtimeMs);
         } catch { /* optional */ }
       }
-      // Clean stale entries from file cache when dirs changed
-      if (dirsChanged) {
-        for (const cachedPath of _prdFileCache.keys()) {
-          if (cachedPath.startsWith(dir) && !fs.existsSync(cachedPath)) _prdFileCache.delete(cachedPath);
+    } catch {
+      // Hard SQL failure → fall back to the disk scan so the dashboard never
+      // goes blank on a transient DB problem.
+      useSqlReads = false;
+    }
+  }
+
+  if (!useSqlReads) {
+    for (const { dir, archived } of planDirs) {
+      try {
+        const planFiles = fs.readdirSync(dir).filter(f => f.endsWith('.json')).sort();
+        for (const pf of planFiles) {
+          try {
+            const filePath = path.join(dir, pf);
+            const stat = fs.statSync(filePath);
+            if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
+
+            // Per-file mtime cache: only re-read files that changed
+            const cached = _prdFileCache.get(filePath);
+            let plan;
+            if (cached && cached.mtimeMs === stat.mtimeMs) {
+              plan = cached.plan;
+            } else {
+              plan = readJsonNoRestore(filePath);
+              _prdFileCache.set(filePath, { mtimeMs: stat.mtimeMs, plan });
+            }
+            processPrd(pf, archived, plan, stat.mtimeMs);
+          } catch { /* optional */ }
         }
-      }
-    } catch { /* optional */ }
+        // Clean stale entries from file cache when dirs changed
+        if (dirsChanged) {
+          for (const cachedPath of _prdFileCache.keys()) {
+            if (cachedPath.startsWith(dir) && !fs.existsSync(cachedPath)) _prdFileCache.delete(cachedPath);
+          }
+        }
+      } catch { /* optional */ }
+    }
   }
 
   if (allPrdItems.length === 0) return { progress: null, status: null };