@yemi33/minions 0.1.2379 → 0.1.2381

package/engine/lifecycle.js

@@ -7,29 +7,26 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const shared = require('./shared');
-const { safeRead, safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, mutateJsonFileLocked, mutateWorkItems, execAsync, projectPrPath, getPrLinks,
+const { safeRead, safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, mutateJsonFileLocked, mutateWorkItems, execAsync, getPrLinks,
   log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, REVIEW_STATUS, RETRY_DELAY_MS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { resolveRuntime } = require('./runtimes');
 const adoGitAuth = require('./ado-git-auth');
 const queries = require('./queries');
 const harness = require('./harness');
+const smallStateStore = require('./small-state-store');
+const prdStore = require('./prd-store');
 const { isBranchActive } = require('./cooldown');
 const { worktreeMatchesBranch, getWorktreeBranch, cleanupMergedPrLocalBranch } = require('./cleanup');
 const { getConfig, getInboxFiles, getNotes, getPrs, getDispatch,
-  MINIONS_DIR, ENGINE_DIR, PLANS_DIR, PRD_DIR, INBOX_DIR, AGENTS_DIR } = queries;
+  MINIONS_DIR, ENGINE_DIR, PLANS_DIR, INBOX_DIR, AGENTS_DIR } = queries;
 
 // ─── Plan Completion Detection ───────────────────────────────────────────────
 function checkPlanCompletion(meta, config) {
 
   const planFile = meta.item?.sourcePlan;
   if (!planFile) return;
-  const planPath = path.join(PRD_DIR, planFile);
-  // Use safeJsonNoRestore — if the active PRD has been archived, the .backup
-  // sidecar may still be sitting in prd/. safeJson would auto-restore it and
-  // resurrect the archived PRD as active (W-mouptdh1000h9f39). PRDs are
-  // terminal artifacts; missing primary means "gone", not "needs recovery".
-  const plan = safeJsonNoRestore(planPath);
+  const plan = prdStore.readPrd(planFile);
   if (!plan?.missing_features) return;
 
   const projects = shared.getProjects(config);
@@ -54,7 +51,7 @@ function checkPlanCompletion(meta, config) {
   const reopenStaleCompletedPlan = (reason) => {
     if (plan.status !== PLAN_STATUS.COMPLETED && !plan._completionNotified) return false;
     log('warn', `Plan ${planFile}: re-opening stale completed PRD — ${reason}`);
-    mutateJsonFileLocked(planPath, (data) => {
+    prdStore.mutatePrd(planFile, (data) => {
       if (data.status === PLAN_STATUS.COMPLETED) data.status = PLAN_STATUS.ACTIVE;
       delete data.completedAt;
       data._completionNotified = false;
@@ -180,8 +177,7 @@ function checkPlanCompletion(meta, config) {
   const prsCreated = [];
   for (const p of projects) {
     try {
-      const prPath = shared.projectPrPath(p);
-      const prs = safeJsonArr(prPath);
+      const prs = shared.readPullRequests(p);
       const prLinks = getPrLinks();
       for (const pr of prs) {
         const linkedItemIds = prLinks[pr.id] || [];
@@ -223,8 +219,7 @@ function checkPlanCompletion(meta, config) {
     shared.writeToInbox('engine', summarySlug, summary);
     log('info', `PRD completion summary written to notes/inbox/${summarySlug}`);
 
-    // Persist completed status + _completionNotified via file lock
-    mutateJsonFileLocked(planPath, (data) => {
+    prdStore.mutatePrd(planFile, (data) => {
       data.status = PLAN_STATUS.COMPLETED;
       data.completedAt = plan.completedAt;
       data._completionNotified = true;
@@ -258,17 +253,15 @@ function checkPlanCompletion(meta, config) {
     log('warn', `Plan ${planFile}: no primary project found — skipping PR/verify creation`);
     return;
   }
-  const wiPath = shared.projectWorkItemsPath(primaryProject);
-
   // 3. For shared-branch plans, create PR work item
-  if (plan.branch_strategy === 'shared-branch' && plan.feature_branch && wiPath) {
+  if (plan.branch_strategy === 'shared-branch' && plan.feature_branch) {
     const existingPrItem = allWorkItems.find(w => w.sourcePlan === planFile && w.itemType === 'pr');
     if (!existingPrItem) {
       const id = 'PL-' + shared.uid();
       const featureBranch = plan.feature_branch;
       const mainBranch = shared.resolveMainBranch(primaryProject.localPath, primaryProject.mainBranch);
       const itemSummary = doneItems.map(w => '- ' + w.id + ': ' + (w.title || 'Untitled').replace('Implement: ', '')).join('\n');
-      mutateWorkItems(wiPath, workItems => {
+      mutateWorkItems(primaryProject, workItems => {
         if (workItems.some(w => w.sourcePlan === planFile && w.itemType === 'pr')) return workItems;
         workItems.push({
           id, title: `Create PR for plan: ${plan.plan_summary || planFile}`,
@@ -295,7 +288,7 @@ function checkPlanCompletion(meta, config) {
     const projectPrs = {};
     const prLinks = getPrLinks();
     for (const p of projects) {
-      const prs = safeJsonArr(shared.projectPrPath(p))
+      const prs = shared.readPullRequests(p)
         .filter(pr => {
           const linkedIds = prLinks[pr.id] || [];
           return pr.status === PR_STATUS.ACTIVE && linkedIds.some(itemId => doneItems.find(w => w.id === itemId));
@@ -338,9 +331,8 @@ function checkPlanCompletion(meta, config) {
         }
         const verifyProject = existingVerify.project || projName;
         const vProject = shared.resolveProjectSource(verifyProject, projects, { allowCentral: false }).project || p;
-        const vWiPath = shared.projectWorkItemsPath(vProject);
         let reopened = false;
-        mutateWorkItems(vWiPath, items => {
+        mutateWorkItems(vProject, items => {
           const v = items.find(w => w.id === existingVerify.id);
           if (isReopenableVerify(v)) {
             shared.reopenWorkItem(v);
@@ -476,9 +468,8 @@ function checkPlanCompletion(meta, config) {
       ].join('\n');
 
       const verifyId = 'PL-' + shared.uid();
-      const vWiPath = shared.projectWorkItemsPath(p);
       let created = false;
-      mutateWorkItems(vWiPath, workItems => {
+      mutateWorkItems(p, workItems => {
         // Re-check under lock to prevent races
         if (workItems.some(w => w.sourcePlan === planFile && w.itemType === WORK_TYPE.VERIFY && (w.project === projName || (!w.project && projName === primaryProject.name)))) {
           return workItems;
@@ -517,18 +508,16 @@ function checkPlanCompletion(meta, config) {
 
 // ─── Archive Plan ───────────────────────────────────────────────────────────
 function archivePlan(planFile, plan, projects, config) {
-  const planPath = path.join(PRD_DIR, planFile);
-
   // Archive in place by flagging the authoritative SQL PRD.
   try {
-    if (safeJsonNoRestore(planPath)) {
-      mutateJsonFileLocked(planPath, (data) => {
+    if (prdStore.readPrd(planFile)) {
+      prdStore.mutatePrd(planFile, (data) => {
         if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
         data.status = 'archived';
         data.archived = true;
         data.archivedAt = new Date().toISOString();
         return data;
-      }, { defaultValue: {} });
+      });
       log('info', `Archived PRD in place: ${planFile} (archived flag set)`);
     }
   } catch (err) {
@@ -585,7 +574,7 @@ function cleanupPlanWorktrees(planFile, plan, projects, config) {
 
     for (const p of projects) {
       try {
-        const prs = safeJsonArr(shared.projectPrPath(p));
+        const prs = shared.readPullRequests(p);
         const prLinks = getPrLinks();
         for (const pr of prs) {
           const linkedIds = prLinks[pr.id] || [];
@@ -619,34 +608,29 @@ function cleanupPlanWorktrees(planFile, plan, projects, config) {
   } catch (err) { log('warn', `Plan worktree cleanup: ${err.message}`); }
 }
 
-// ─── Work Item Path Resolution ───────────────────────────────────────────────
+// ─── Work Item Scope Resolution ──────────────────────────────────────────────
 
-/** Resolve the work-items.json path from dispatch meta. Reused by retry paths. */
-function resolveWorkItemPath(meta) {
+function resolveWorkItemScope(meta) {
   if (meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout') {
-    return path.join(MINIONS_DIR, 'work-items.json');
+    return 'central';
   }
   if (meta.source === 'work-item' && meta.project?.name) {
-    return path.join(MINIONS_DIR, 'projects', meta.project.name, 'work-items.json');
+    return meta.project.name;
   }
   return null;
 }
 
-function getWorkItemPaths(config) {
-  const paths = [path.join(MINIONS_DIR, 'work-items.json')];
-  for (const p of shared.getProjects(config || {})) {
-    if (p && p.name) paths.push(shared.projectWorkItemsPath(p));
-  }
-  return paths;
+function getWorkItemScopes(config) {
+  return ['central', ...shared.getProjects(config || {})];
 }
 
 function findWorkItemRecord(itemId, config) {
   if (!itemId) return null;
-  for (const wiPath of getWorkItemPaths(config)) {
+  for (const scope of getWorkItemScopes(config)) {
     try {
-      const items = readOptionalJsonStrict(wiPath, 'work-items', Array.isArray) || [];
+      const items = shared.readWorkItems(scope);
       const item = items.find(i => i && i.id === itemId);
-      if (item) return { item, path: wiPath };
+      if (item) return { item, scope };
     } catch { /* best-effort lineage lookup */ }
   }
   return null;
@@ -707,11 +691,11 @@ function updateWorkItemStatus(meta, status, reason) {
     return;
   }
 
-  const wiPath = resolveWorkItemPath(meta);
-  if (!wiPath) return;
+  const wiScope = resolveWorkItemScope(meta);
+  if (!wiScope) return;
 
   let completionGuarded = false;
-  mutateJsonFileLocked(wiPath, (items) => {
+  mutateWorkItems(wiScope, (items) => {
     if (!items || !Array.isArray(items)) return items;
     const target = items.find(i => i.id === itemId);
     if (!target) return items;
@@ -783,7 +767,7 @@ function updateWorkItemStatus(meta, status, reason) {
       }
     }
     return items;
-  }, { defaultValue: [], skipWriteIfUnchanged: true });
+  });
 
   if (completionGuarded) {
     log('info', `Work item ${itemId} already completed — ignoring ${status} status update`);
@@ -803,15 +787,15 @@ function storeAffectedFilesFromCompletion(meta, structuredCompletion) {
   if (files.length === 0) return;
   const itemId = meta?.item?.id;
   if (!itemId) return;
-  const wiPath = resolveWorkItemPath(meta);
-  if (!wiPath) return;
-  mutateJsonFileLocked(wiPath, (items) => {
+  const wiScope = resolveWorkItemScope(meta);
+  if (!wiScope) return;
+  mutateWorkItems(wiScope, (items) => {
     if (!Array.isArray(items)) return items;
     const target = items.find(i => i.id === itemId);
     if (!target) return items;
     target.affected_files = files;
     return items;
-  }, { skipWriteIfUnchanged: true });
+  });
 }
 
 const _VALID_PRD_STATUSES = new Set([...Object.values(WI_STATUS), 'missing']);
@@ -832,16 +816,11 @@ function syncPrdItemStatus(itemId, status, sourcePlan) {
   if (!itemId) return;
   if (!_VALID_PRD_STATUSES.has(status)) return;
   try {
-    const prdDir = path.join(MINIONS_DIR, 'prd');
     const files = sourcePlan
       ? [sourcePlan]
-      : require('./prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
+      : prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
     for (const pf of files) {
-      const fpath = path.join(prdDir, pf);
-      // Lock-free peek: most PRDs won't contain the ID, so skip the lock cost.
-      // safeJsonNoRestore so an archived PRD's .backup sidecar can't resurrect
-      // the active PRD just because a done WI still references it.
-      const plan = safeJsonNoRestore(fpath);
+      const plan = prdStore.readPrd(pf);
       // Frozen PRDs (paused/rejected/awaiting-approval/completed) must not have
       // their item statuses mutated by a late-arriving WI status update — that
       // would silently flip a paused/rejected PRD's items and feed the
@@ -850,7 +829,7 @@ function syncPrdItemStatus(itemId, status, sourcePlan) {
       const feature = plan?.missing_features?.find(f => f.id === itemId);
       if (!feature || feature.status === status) continue;
       let updated = false;
-      mutateJsonFileLocked(fpath, (fresh) => {
+      prdStore.mutatePrd(pf, (fresh) => {
         // Re-check under the lock — status may have frozen between peek and lock.
         if (_PRD_FROZEN_STATUSES.has(fresh?.status)) return fresh;
         const f = fresh?.missing_features?.find(x => x.id === itemId);
@@ -859,7 +838,7 @@ function syncPrdItemStatus(itemId, status, sourcePlan) {
           updated = true;
         }
         return fresh;
-      }, { skipWriteIfUnchanged: true });
+      });
       if (updated) return;
     }
   } catch (err) { log('warn', `PRD status sync: ${err.message}`); }
@@ -872,30 +851,28 @@ function syncPrdItemStatus(itemId, status, sourcePlan) {
 function stampPrdItemWorkItemId(itemId, sourcePlan) {
   if (!itemId || !sourcePlan) return;
   try {
-    const fpath = path.join(PRD_DIR, sourcePlan);
-    const plan = safeJsonNoRestore(fpath);
+    const plan = prdStore.readPrd(sourcePlan);
     const feature = plan?.missing_features?.find(f => f.id === itemId);
     if (!feature || feature.workItemId === itemId) return;
-    mutateJsonFileLocked(fpath, (fresh) => {
+    prdStore.mutatePrd(sourcePlan, (fresh) => {
       const f = fresh?.missing_features?.find(x => x.id === itemId);
       if (f && f.workItemId !== itemId) f.workItemId = itemId;
       return fresh;
-    }, { skipWriteIfUnchanged: true });
+    });
   } catch (err) { log('warn', `stampPrdItemWorkItemId: ${err.message}`); }
 }
 
 function stampPrdItemPrUrl(itemId, sourcePlan, prUrl) {
   if (!itemId || !sourcePlan || !prUrl) return;
   try {
-    const fpath = path.join(PRD_DIR, sourcePlan);
-    const plan = safeJsonNoRestore(fpath);
+    const plan = prdStore.readPrd(sourcePlan);
     const feature = plan?.missing_features?.find(f => f.id === itemId);
     if (!feature || feature.pr_url === prUrl) return;
-    mutateJsonFileLocked(fpath, (fresh) => {
+    prdStore.mutatePrd(sourcePlan, (fresh) => {
       const f = fresh?.missing_features?.find(x => x.id === itemId);
       if (f && f.pr_url !== prUrl) f.pr_url = prUrl;
       return fresh;
-    }, { skipWriteIfUnchanged: true });
+    });
   } catch (err) { log('warn', `stampPrdItemPrUrl: ${err?.message || err}`); }
 }
 
@@ -907,7 +884,7 @@ function stampPrdItemPrUrl(itemId, sourcePlan, prUrl) {
 //    different ID than the original PRD feature, leaving the PRD status stale.
 
 function reconcilePrdStatuses(config) {
-  const prdFiles = require('./prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
+  const prdFiles = prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
   if (prdFiles.length === 0) return;
 
   const allWorkItems = queries.getWorkItems(config);
@@ -922,9 +899,8 @@ function reconcilePrdStatuses(config) {
 
   for (const file of prdFiles) {
     try {
-      const fpath = path.join(PRD_DIR, file);
       const logMessages = [];
-      mutateJsonFileLocked(fpath, (plan) => {
+      prdStore.mutatePrd(file, (plan) => {
         if (!plan?.missing_features) return plan;
         // Skip frozen PRDs — paused/rejected/awaiting-approval/completed require no reconciliation
         if (_PRD_FROZEN_STATUSES.has(plan.status)) return plan;
@@ -943,7 +919,7 @@ function reconcilePrdStatuses(config) {
           }
         }
         return plan;
-      }, { skipWriteIfUnchanged: true });
+      });
       for (const message of logMessages) log('info', message);
     } catch (err) { log('warn', `PRD backward-scan for ${file}: ${err.message}`); }
   }
@@ -1141,15 +1117,14 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
 
   const agentName = config.agents?.[agentId]?.name || agentId;
   let added = 0;
-  const centralPrPath = path.join(MINIONS_DIR, 'pull-requests.json');
 
-  // Group new PRs by target file path
-  const newPrsByPath = new Map(); // prPath -> [{ prId, newEntry }]
+  const newPrsByScope = new Map();
 
   for (const prId of prEvidence.keys()) {
     const targetProject = useCentral ? null : resolveProjectForPr(prId);
     const targetName = targetProject ? targetProject.name : '_central';
-    const prPath = targetProject ? shared.projectPrPath(targetProject) : centralPrPath;
+    const source = targetProject || 'central';
+    const scope = shared.stateScope(source);
     const prUrl = extractPrUrl(prId);
     const fullId = shared.getCanonicalPrId(targetProject, prId, prUrl);
 
@@ -1160,7 +1135,7 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
       title = meta?.item?.title || '';
     }
 
-    if (!newPrsByPath.has(prPath)) newPrsByPath.set(prPath, { name: targetName, project: targetProject, entries: [] });
+    if (!newPrsByScope.has(scope)) newPrsByScope.set(scope, { source, name: targetName, project: targetProject, entries: [] });
     const entry = {
       id: fullId,
       prNumber: parseInt(prId, 10) || prId,
@@ -1186,15 +1161,15 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
     // "review this PR" via CC) must stay reference-only. QA-session setup and
     // other oneShot+skipPr PR-targeted work are operational context, not an
     // observe toggle, so they must not demote a real tracked PR.
-    newPrsByPath.get(prPath).entries.push({ prId, fullId, entry });
+    newPrsByScope.get(scope).entries.push({ prId, fullId, entry });
   }
 
   const entryBranch = meta?.branch || '';
 
-  for (const [prPath, { name, project: targetProject, entries }] of newPrsByPath) {
+  for (const { source, name, project: targetProject, entries } of newPrsByScope.values()) {
     for (const { prId, fullId, entry } of entries) {
       let duplicateOnBranch = null;
-      const result = shared.upsertPullRequestRecord(prPath, entry, {
+      const result = shared.upsertPullRequestRecord(source, entry, {
         project: targetProject,
         itemId: meta?.item?.id || null,
         beforeInsert: (prs, normalizedEntry) => {
@@ -1244,7 +1219,7 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
       }
       if (result.created || result.linked) added++;
     }
-    log('info', `Synced PR(s) from ${agentName}'s output to ${name === '_central' ? 'central' : name}/pull-requests.json`);
+    log('info', `Synced PR(s) from ${agentName}'s output to ${name === '_central' ? 'central' : name} state`);
   }
   return added;
 }
@@ -1261,7 +1236,7 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
 //
 // `enrollPrFromCanonicalId` is the write-side fix: given a canonical PR id and
 // the owning project, fetch live state from GitHub (or ADO, best-effort) and
-// insert a `contextOnly: true` row into the project's `pull-requests.json`.
+// insert a `contextOnly: true` row into the project's PR state.
 // Idempotent — no-op if a record already exists. Always marks the record as
 // context-only so the engine doesn't try to re-dispatch fix/review loops on
 // an already-merged PR (matches the #1772 enrollment-flag semantics).
@@ -1367,21 +1342,18 @@ async function enrollPrFromCanonicalId(canonicalPrId, project, opts = {}) {
     // pr-links stays consistent (#779 pattern).
     if (opts.itemId && Array.isArray(existing.prdItems) && !existing.prdItems.includes(opts.itemId)) {
       try {
-        // W-mrduef3q000m2172 — derive targetPath from the scope the store
+        // W-mrduef3q000m2172 — use the scope the store
         // actually returned `existing` under (existing._scope), NOT from the
         // current call's `project` argument. When the two differ (e.g. the
         // record lives under 'central' but this enrollment call was made
         // with a specific project), re-deriving from `project` sends the
-        // upsert to the WRONG scope's file/array. upsertPullRequestRecord's
+        // upsert to the wrong scope. upsertPullRequestRecord's
         // tombstone guard then finds no matching record in that (wrong)
         // scope and falls through to insert-as-new, silently clearing any
         // userDeleted tombstone on the real record. See issue writeup for
         // the confirmed repro.
-        const store = require('./pull-requests-store');
-        const targetPath = existing._scope
-          ? store._filePathForScope(existing._scope)
-          : (project ? shared.projectPrPath(project) : path.join(MINIONS_DIR, 'pull-requests.json'));
-        shared.upsertPullRequestRecord(targetPath, {
+        const targetScope = existing._scope || project || 'central';
+        shared.upsertPullRequestRecord(targetScope, {
           id: normalizedCanonicalId,
           prNumber,
           url: existing.url || '',
@@ -1439,8 +1411,7 @@ async function enrollPrFromCanonicalId(canonicalPrId, project, opts = {}) {
     return { enrolled: false, reason: 'unsupported_scope' };
   }
 
-  const prPath = project ? shared.projectPrPath(project) : path.join(MINIONS_DIR, 'pull-requests.json');
-  if (!prPath) return { enrolled: false, reason: 'no_pr_path' };
+  const source = project || 'central';
 
   const entry = {
     id: normalizedCanonicalId,
@@ -1462,12 +1433,12 @@ async function enrollPrFromCanonicalId(canonicalPrId, project, opts = {}) {
   if (liveState && liveState.closedAt && !liveState.mergedAt) entry.closedAt = liveState.closedAt;
 
   try {
-    const result = shared.upsertPullRequestRecord(prPath, entry, {
+    const result = shared.upsertPullRequestRecord(source, entry, {
       project,
       itemId: opts.itemId || null,
     });
     if (result.created) {
-      log('info', `enrollPrFromCanonicalId: enrolled ${normalizedCanonicalId} (status=${status}) into ${project?.name || 'central'}/pull-requests.json`);
+      log('info', `enrollPrFromCanonicalId: enrolled ${normalizedCanonicalId} (status=${status}) into ${project?.name || 'central'} state`);
     }
     return {
       enrolled: !!(result.created || result.linked),
@@ -1548,11 +1519,10 @@ function stampWiPrRef(meta, config) {
   const prUrl = found.url;
   const prNumber = found.prNumber ?? found.number ?? null;
 
-  // Stamp the on-disk WI record.
-  const wiPath = resolveWorkItemPath(meta);
-  if (wiPath) {
+  const wiScope = resolveWorkItemScope(meta);
+  if (wiScope) {
     try {
-      mutateWorkItems(wiPath, items => {
+      mutateWorkItems(wiScope, items => {
         const wi = items.find(i => i.id === itemId);
         if (wi && !wi._pr) {
           if (prId) wi._pr = prId;
@@ -1589,7 +1559,7 @@ function isPrAttachmentRequired(type, item, meta = {}) {
   // PR — the agent updates meta.pr in place. The meta.pr short-circuit beats
   // the explicit-flag fallthrough so a legacy requiresPr:true fix doesn't
   // trigger the contract when there's already a PR attached.
-  if ((type === WORK_TYPE.FIX || type === WORK_TYPE.TEST) && meta?.pr) return false;
+  if ((shared.isFixLikeWorkType(type) || type === WORK_TYPE.TEST) && meta?.pr) return false;
 
   // Standalone test work is usually pure build/run/verify. It should only be
   // PR-required when the caller explicitly marks it as file-changing work.
@@ -1598,7 +1568,7 @@ function isPrAttachmentRequired(type, item, meta = {}) {
   return explicit
     || type === WORK_TYPE.IMPLEMENT
     || type === WORK_TYPE.IMPLEMENT_LARGE
-    || type === WORK_TYPE.FIX;
+    || shared.isFixLikeWorkType(type);
 }
 
 function readOptionalJsonStrict(filePath, label, validate) {
@@ -1622,10 +1592,10 @@ function hasCanonicalPrAttachment(itemId, config) {
   if (Object.values(getPrLinks()).some(linkedIds => (linkedIds || []).includes(itemId))) return true;
   const projects = shared.getProjects(config);
   for (const p of projects) {
-    const prs = readOptionalJsonStrict(shared.projectPrPath(p), 'project pull-requests', Array.isArray) || [];
+    const prs = shared.readPullRequests(p);
     if (prs.some(pr => (pr.prdItems || []).includes(itemId))) return true;
   }
-  const centralPrs = readOptionalJsonStrict(path.join(MINIONS_DIR, 'pull-requests.json'), 'central pull-requests', Array.isArray) || [];
+  const centralPrs = shared.readPullRequests('central');
   return centralPrs.some(pr => (pr.prdItems || []).includes(itemId));
 }
 
@@ -1826,7 +1796,7 @@ function _attachFoundPrToWi(found, meta, agentId, resultSummary, config) {
     itemType: meta.item?.itemType || '',
   };
   applyScheduleContextToPrEntry(entry, meta?.item, config);
-  shared.upsertPullRequestRecord(shared.projectPrPath(found.project), entry, {
+  shared.upsertPullRequestRecord(found.project, entry, {
     project: found.project,
     itemId: meta.item.id,
   });
@@ -1894,7 +1864,7 @@ function _outputHasRuntimeResultEvent(output) {
 }
 
 function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity, opts) {
-  const noPrWiPath = resolveWorkItemPath(meta);
+  const noPrWiScope = resolveWorkItemScope(meta);
   const isHard = severity !== 'soft';
   const isPhantom = !!(opts && opts.phantom);
   let syncFailedToPrd = false;
@@ -1907,8 +1877,8 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity,
   let phantomRetryExhausted = false;
   let phantomRetryCount = 0;
   let systematicPhantomFired = false;
-  if (isHard && isPhantom && noPrWiPath) {
-    mutateJsonFileLocked(noPrWiPath, data => {
+  if (isHard && isPhantom && noPrWiScope) {
+    mutateWorkItems(noPrWiScope, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === meta.item.id);
       if (!w) return data;
@@ -1974,7 +1944,7 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity,
         phantomRetryCount = phantomRetries;
       }
       return data;
-    }, { skipWriteIfUnchanged: true });
+    });
     if (phantomRetryDeferred) {
       // Soft inbox note: the runtime crashed but we're retrying; surface the
       // event without flagging the WI as silent failure.
@@ -2009,8 +1979,8 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity,
       reason = `${reason} — phantom retries exhausted (${phantomRetryCount}/${ENGINE_DEFAULTS.maxPhantomRetries})`;
     }
   }
-  if (noPrWiPath) {
-    mutateJsonFileLocked(noPrWiPath, data => {
+  if (noPrWiScope) {
+    mutateWorkItems(noPrWiScope, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === meta.item.id);
       if (!w) return data;
@@ -2037,7 +2007,7 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity,
         w._lastReviewReason = reason;
       }
       return data;
-    }, { skipWriteIfUnchanged: true });
+    });
   }
   if (isHard && syncFailedToPrd) {
     syncPrdItemStatus(meta.item.id, WI_STATUS.FAILED, meta.item.sourcePlan);
@@ -2071,10 +2041,10 @@ function markMissingPrAttachment(meta, agentId, reason, resultSummary, severity,
 }
 
 function markPrAttachmentVerificationError(meta, agentId, reason, resultSummary) {
-  const wiPath = resolveWorkItemPath(meta);
+  const wiScope = resolveWorkItemScope(meta);
   let syncFailedToPrd = false;
-  if (wiPath) {
-    mutateWorkItems(wiPath, data => {
+  if (wiScope) {
+    mutateWorkItems(wiScope, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === meta.item.id);
       if (!w) return data;
@@ -2088,7 +2058,7 @@ function markPrAttachmentVerificationError(meta, agentId, reason, resultSummary)
       delete w._missingPrAttachment;
       delete w._unverifiedPrAttachment;
       return data;
-    }, { skipWriteIfUnchanged: true });
+    });
   }
   if (syncFailedToPrd) {
     syncPrdItemStatus(meta.item.id, WI_STATUS.FAILED, meta.item.sourcePlan);
@@ -2169,7 +2139,7 @@ async function enforcePrAttachmentContract(type, meta, agentId, config, resultSu
 
 // W-mqsk1ip00006cbae — After a verify WI transitions to done, assert that a PR
 // exists: either a direct reference on the item (_pr/_prUrl) or a matching
-// entry in pull-requests.json for the plan (by sourcePlan). If no PR is found,
+// tracked PR entry for the plan (by sourcePlan). If no PR is found,
 // flip the WI to failed with failure_class: verify-missing-pr and write an
 // inbox alert so operators can investigate.
 //
@@ -2199,10 +2169,10 @@ function enforceVerifyPrContract(type, meta, agentId, config, resultSummary) {
     try {
       const projects = shared.getProjects(config);
       for (const p of projects) {
-        const prs = readOptionalJsonStrict(shared.projectPrPath(p), 'project pull-requests', Array.isArray) || [];
+        const prs = shared.readPullRequests(p);
         if (prs.some(pr => pr.sourcePlan === item.sourcePlan)) return null;
       }
-      const centralPrs = readOptionalJsonStrict(path.join(MINIONS_DIR, 'pull-requests.json'), 'central pull-requests', Array.isArray) || [];
+      const centralPrs = shared.readPullRequests('central');
       if (centralPrs.some(pr => pr.sourcePlan === item.sourcePlan)) return null;
     } catch (err) {
       log('warn', `enforceVerifyPrContract: sourcePlan PR check failed for ${item.id}: ${err.message}`);
@@ -2212,13 +2182,13 @@ function enforceVerifyPrContract(type, meta, agentId, config, resultSummary) {
   // No PR found — flip WI to failed and surface an alert.
   const failureClass = FAILURE_CLASS.VERIFY_MISSING_PR;
   const reason = `Verify WI ${item.id} completed done but no PR was found ` +
-    `(no _prUrl/_pr on item, no canonical attachment, and no pull-requests.json entry for plan ` +
+    `(no _prUrl/_pr on item, no canonical attachment, and no tracked PR entry for plan ` +
     `${item.sourcePlan || '(none)'}). Flipped to failed so the plan does not silently advance. ` +
     `(Branch: ${meta.branch || '(none)'}, agent: ${agentId})`;
 
-  const wiPath = resolveWorkItemPath(meta);
-  if (wiPath) {
-    mutateWorkItems(wiPath, data => {
+  const wiScope = resolveWorkItemScope(meta);
+  if (wiScope) {
+    mutateWorkItems(wiScope, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === item.id);
       if (!w) return data;
@@ -2228,7 +2198,7 @@ function enforceVerifyPrContract(type, meta, agentId, config, resultSummary) {
       w.failedAt = ts();
       delete w.completedAt;
       return data;
-    }, { skipWriteIfUnchanged: true });
+    });
   }
 
   if (item.sourcePlan) {
@@ -2312,10 +2282,6 @@ function reviewPrRefMatchesDispatchTarget(reportedPr, dispatchPr, project) {
   return !(reportedScoped && dispatchScoped);
 }
 
-function centralPrPath() {
-  return path.join(MINIONS_DIR, 'pull-requests.json');
-}
-
 function resolveReviewPrContext(pr, project, config, structuredCompletion = null) {
   const reportedPr = reviewPrRefFromCompletion(structuredCompletion);
   if (reportedPr && pr && !reviewPrRefMatchesDispatchTarget(reportedPr, pr, project)) return null;
@@ -2330,28 +2296,26 @@ function resolveReviewPrContext(pr, project, config, structuredCompletion = null
   }
 
   for (const candidateProject of projectCandidates) {
-    const prPath = shared.projectPrPath(candidateProject);
-    const prs = safeJsonArr(prPath);
+    const prs = shared.readPullRequests(candidateProject);
     for (const ref of refs) {
       const refUrl = typeof ref === 'object' ? ref.url || '' : String(ref || '');
       if (!shared.isPrCompatibleWithProject(candidateProject, ref, refUrl)) continue;
       const target = shared.findPrRecord(prs, ref, candidateProject);
-      if (target) return { pr: { ...target }, project: candidateProject, prPath };
+      if (target) return { pr: { ...target }, project: candidateProject, scope: candidateProject.name };
     }
   }
 
-  const centralPath = centralPrPath();
-  const centralPrs = safeJsonArr(centralPath);
+  const centralPrs = shared.readPullRequests('central');
   const centralRefs = reportedPr ? [reportedPr] : refs;
   for (const ref of centralRefs) {
     const target = shared.findPrRecord(centralPrs, ref, null);
-    if (target) return { pr: { ...target }, project: null, prPath: centralPath };
+    if (target) return { pr: { ...target }, project: null, scope: 'central' };
   }
 
   if (reportedPr) return null;
 
   return pr?.id
-    ? { pr, project: project || null, prPath: project ? shared.projectPrPath(project) : centralPath }
+    ? { pr, project: project || null, scope: project?.name || 'central' }
     : null;
 }
 
@@ -2372,7 +2336,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
   }
   const reviewPr = reviewContext.pr;
   const reviewProject = reviewContext.project;
-  const prPath = reviewContext.prPath;
+  const prScope = reviewContext.scope;
   const reviewerName = config.agents?.[agentId]?.name || agentId;
 
   // Check actual review status from the platform (agent may have approved or requested changes)
@@ -2383,7 +2347,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
   // BUG-H14 (P-h14-repohost): resolve repoHost from the PR's canonical id
   // FIRST. The previous code derived hostForChecks from the fallback project
   // (`reviewProject || getProjects(config)[0]`) and silently defaulted to
-  // 'ado' on miss — so a github:* PR found in the central pull-requests.json
+  // 'ado' on miss — so a github:* PR found in central state
   // (reviewProject=null) with an ADO project as projects[0] was mis-routed to
   // ado.checkLiveReviewStatus. The fallback project is still consulted when
   // the id is unparseable, but there is no silent 'ado' default — an
@@ -2504,7 +2468,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
     const maxMissingRetries = config?.engine?.maxReviewVerdictMissingRetries ?? ENGINE_DEFAULTS.maxReviewVerdictMissingRetries;
     let missingCount = 0;
     let retriesExhausted = false;
-    shared.mutateJsonFileLocked(prPath, (prs) => {
+    shared.mutatePullRequests(prScope, (prs) => {
       if (!Array.isArray(prs)) return prs;
       const target = shared.findPrRecord(prs, reviewPr, reviewProject);
       if (!target) return prs;
@@ -2524,7 +2488,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
       // normal needsReview gate re-dispatches a fresh review next tick.
       if (retriesExhausted) target.lastReviewedAt = ts();
       return prs;
-    }, { defaultValue: [] });
+    });
 
     const reason = `Review dispatch for ${reviewPr.id} completed without posting a VERDICT: comment ` +
       `(reviewer: ${reviewerName}, dispatch: ${dispatchItem?.id || structuredCompletion?.dispatchId || '(unknown)'}). ` +
@@ -2545,7 +2509,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
     return;
   }
 
-  shared.mutateJsonFileLocked(prPath, (prs) => {
+  shared.mutatePullRequests(prScope, (prs) => {
     if (!Array.isArray(prs)) return prs;
     const target = shared.findPrRecord(prs, reviewPr, reviewProject);
     if (!target) return prs;
@@ -3171,7 +3135,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
     options = { automationCauseKey: options, dispatchId: legacyDispatchId };
   }
   const explicitlyChangedBranch = options.branchChanged !== false;
-  const prPath = project ? shared.projectPrPath(project) : centralPrPath();
+  const prScope = project || 'central';
   const automationCauseKey = options.automationCauseKey || options.dispatchItem?.meta?.automationCauseKey || '';
   const fixDispatchId = options.dispatchItem?.id || options.dispatchId || legacyDispatchId || '';
   const cause = shared.getPrFixAutomationCause({
@@ -3180,7 +3144,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
     task: options.dispatchItem?.task,
   });
   let result = null;
-  shared.mutateJsonFileLocked(prPath, (prs) => {
+  shared.mutatePullRequests(prScope, (prs) => {
     if (!Array.isArray(prs)) return prs;
     const target = shared.findPrRecord(prs, pr, project);
     if (!target) return prs;
@@ -3384,7 +3348,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
 function updatePrAfterFixError(pr, project, source, options = {}) {
   if (!pr?.id) return null;
   if (!options || typeof options !== 'object' || Array.isArray(options)) return null;
-  const prPath = project ? shared.projectPrPath(project) : centralPrPath();
+  const prScope = project || 'central';
   const dispatchItem = options.dispatchItem || null;
   const errorMessage = String(options.errorMessage || '').slice(0, 200);
   const errorClass = String(options.errorClass || 'agent-error');
@@ -3394,7 +3358,7 @@ function updatePrAfterFixError(pr, project, source, options = {}) {
     task: dispatchItem?.task,
   });
   let result = null;
-  shared.mutateJsonFileLocked(prPath, (prs) => {
+  shared.mutatePullRequests(prScope, (prs) => {
     if (!Array.isArray(prs)) return prs;
     const target = shared.findPrRecord(prs, pr, project);
     if (!target) return prs;
@@ -3478,7 +3442,7 @@ function findDependentActivePrs(mergedItemId, config) {
 
   const projects = shared.getProjects(config);
   for (const p of projects) {
-    const prs = safeJsonArr(projectPrPath(p));
+    const prs = shared.readPullRequests(p);
     for (const pr of prs) {
       if (!pr.branch || pr.status !== PR_STATUS.ACTIVE) continue;
       const linked = (pr.prdItems || []).some(id => dependentWis.some(wi => wi.id === id));
@@ -3560,10 +3524,8 @@ async function rebaseBranchOntoMain(pr, project, config) {
   }
 }
 
-const PENDING_REBASES_PATH = path.join(ENGINE_DIR, 'pending-rebases.json');
-
 function queuePendingRebase(pr, project, mergedItemId) {
-  mutateJsonFileLocked(PENDING_REBASES_PATH, (pending) => {
+  smallStateStore.applyPendingRebasesMutation((pending) => {
     const prDisplayId = shared.getPrDisplayId(pr);
     if (pending.some(e => e.projectName === project.name && shared.getPrDisplayId(e.prId) === prDisplayId)) return pending; // already queued
     pending.push({ prId: pr.id, branch: pr.branch, projectName: project.name, mergedItemId, queuedAt: ts(), attempts: 0 });
@@ -3575,10 +3537,10 @@ async function processPendingRebases(config) {
   // Atomically drain the queue under lock so concurrent queuePendingRebase calls
   // during processing don't lose entries (they append to the now-empty file).
   let snapshot = [];
-  mutateJsonFileLocked(PENDING_REBASES_PATH, (data) => {
+  smallStateStore.applyPendingRebasesMutation((data) => {
     snapshot = [...data];
     return []; // drain file
-  }, { defaultValue: [] });
+  });
   if (snapshot.length === 0) return;
 
   const remaining = [];
@@ -3606,9 +3568,9 @@ async function processPendingRebases(config) {
   }
   // Merge remaining items back under lock — entries queued during processing are preserved
   if (remaining.length > 0) {
-    mutateJsonFileLocked(PENDING_REBASES_PATH, (data) => {
+    smallStateStore.applyPendingRebasesMutation((data) => {
       data.push(...remaining);
-    }, { defaultValue: [] });
+    });
   }
 }
 
@@ -3619,7 +3581,7 @@ async function handlePostMerge(pr, project, config, newStatus) {
   const prNum = shared.getPrNumber(pr);
 
   // `project.localPath` guard: central/observed PRs (e.g. ADO PRs tracked in
-  // ~/.minions/pull-requests.json with no configured project) are polled via a
+  // central PRs with no configured project are polled via a
   // *synthesized* project that has no localPath (engine/ado.js + engine/github.js
   // central-poll loops). There is no checkout to clean for those, and an
   // unguarded path.resolve(undefined) here threw "paths[0] argument must be of
@@ -3664,13 +3626,11 @@ async function handlePostMerge(pr, project, config, newStatus) {
   if (mergedItemIds.length > 0) {
     const mergedItemSet = new Set(mergedItemIds);
     // Mark PRD feature as implemented
-    const prdDir = path.join(MINIONS_DIR, 'prd');
     try {
-      const planFiles = require('./prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
+      const planFiles = prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
       let updated = 0;
       for (const pf of planFiles) {
-        const planPath = path.join(prdDir, pf);
-        mutateJsonFileLocked(planPath, (plan) => {
+        prdStore.mutatePrd(pf, (plan) => {
           if (!plan?.missing_features) return plan;
           if (shared.isPrdArchived(plan)) return plan; // step 4: never mutate an archived (in-place) PRD's items
           for (const feature of plan.missing_features) {
@@ -3680,18 +3640,17 @@ async function handlePostMerge(pr, project, config, newStatus) {
             }
           }
           return plan;
-        }, { skipWriteIfUnchanged: true });
+        });
       }
       if (updated > 0) log('info', `Post-merge: marked ${mergedItemIds.join(', ')} as done for ${pr.id}`);
     } catch (err) { log('warn', `Post-merge PRD update: ${err.message}`); }
 
     // Mark work item as done
-    const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-    for (const p of shared.getProjects(config)) wiPaths.push(shared.projectWorkItemsPath(p));
+    const workItemScopes = ['central', ...shared.getProjects(config)];
     const remainingMergedIds = new Set(mergedItemIds);
-    for (const wiPath of wiPaths) {
+    for (const scope of workItemScopes) {
       try {
-        mutateWorkItems(wiPath, items => {
+        mutateWorkItems(scope, items => {
           for (const item of items) {
             if (!remainingMergedIds.has(item.id)) continue;
             if (item.status !== WI_STATUS.DONE) {
@@ -3753,7 +3712,7 @@ function checkForLearnings(agentId, agentInfo, taskDesc) {
   }
   // Info, not warn: not writing learnings is a soft signal (the agent finished
   // and the engine continues fine). Operators don't need to act on it; keeping
-  // it at warn floods log.json (~50 entries/day) with non-actionable noise.
+  // it at warn floods the engine log (~50 entries/day) with non-actionable noise.
   log('info', `${agentInfo?.name || agentId} didn't write learnings — no follow-up queued`);
 }
 
@@ -3846,9 +3805,8 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeN
         const projectSkillRoot = skillWriteTargets(effectiveRuntime, proj).project
           || path.resolve(proj.localPath, '.claude', 'skills');
         const projectSkillPath = path.join(projectSkillRoot, skillDirName, 'SKILL.md');
-        const centralPath = path.join(MINIONS_DIR, 'work-items.json');
         let skillId = null;
-        mutateJsonFileLocked(centralPath, data => {
+        mutateWorkItems('central', data => {
           data = data || [];
           if (data.some(i => i.title === `Add skill: ${name}` && i.status !== WI_STATUS.FAILED)) return data;
           skillId = `SK${String(data.filter(i => i.id?.startsWith('SK')).length + 1).padStart(3, '0')}`;
@@ -3856,7 +3814,7 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeN
             description: `Create project-level skill \`${skillDirName}/SKILL.md\` in ${project}.\n\nWrite this file to \`${projectSkillPath}\` via a PR.\n\n## Skill Content\n\n\`\`\`\n${enrichedBlock}\n\`\`\``,
             priority: 'low', status: WI_STATUS.QUEUED, created: ts(), createdBy: `engine:skill-extraction:${agentName}` });
           return data;
-        }, { skipWriteIfUnchanged: true });
+        });
         if (skillId) {
           log('info', `Queued work item ${skillId} to PR project skill "${name}" into ${project}`);
         }
@@ -4189,9 +4147,9 @@ function handleInjectionFlag(dispatchItem, agentId, structuredCompletion, config
   }
 
   try {
-    const wiPath = dispatchItem?.meta ? resolveWorkItemPath(dispatchItem.meta) : null;
-    if (wiPath && dispatchItem?.meta?.item?.id) {
-      mutateWorkItems(wiPath, (items) => {
+    const wiScope = dispatchItem?.meta ? resolveWorkItemScope(dispatchItem.meta) : null;
+    if (wiScope && dispatchItem?.meta?.item?.id) {
+      mutateWorkItems(wiScope, (items) => {
         const wi = items.find((w) => w.id === dispatchItem.meta.item.id);
         if (wi) {
           wi._securityFlag = {
@@ -4367,8 +4325,8 @@ function mergeArtifactNotes(existing, additions) {
 function promoteCompletionArtifacts(meta, agentId, dispatchId, structuredCompletion, opts = {}) {
   const itemId = meta?.item?.id;
   if (!itemId) return { artifacts: [], notes: [] };
-  const wiPath = resolveWorkItemPath(meta);
-  if (!wiPath) return { artifacts: [], notes: [] };
+  const wiScope = resolveWorkItemScope(meta);
+  if (!wiScope) return { artifacts: [], notes: [] };
 
   const artifacts = normalizeCompletionArtifacts(structuredCompletion?.artifacts);
   const structuredNotes = artifacts.map(completionArtifactToNoteEntry).filter(Boolean);
@@ -4381,7 +4339,7 @@ function promoteCompletionArtifacts(meta, agentId, dispatchId, structuredComplet
     return { artifacts, notes };
   }
 
-  mutateJsonFileLocked(wiPath, data => {
+  mutateWorkItems(wiScope, data => {
     if (!Array.isArray(data)) return data;
     const wi = data.find(i => i.id === itemId);
     if (!wi) return data;
@@ -4398,7 +4356,7 @@ function promoteCompletionArtifacts(meta, agentId, dispatchId, structuredComplet
     if (resultSummary) wi.resultSummary = resultSummary;
     wi._artifacts = arts;
     return data;
-  }, { defaultValue: [], skipWriteIfUnchanged: true });
+  });
 
   return { artifacts, notes, agentId, dispatchId };
 }
@@ -4487,13 +4445,13 @@ function _deferRetryWithCounter(meta, detection, counterField, maxCount, pending
   const itemId = meta?.item?.id;
   const reason = detection?.reason || 'Nonterminal completion summary';
   if (!itemId) return reason;
-  const wiPath = resolveWorkItemPath(meta);
-  if (!wiPath) return reason;
+  const wiScope = resolveWorkItemScope(meta);
+  if (!wiScope) return reason;
 
   let finalStatus = WI_STATUS.PENDING;
   let systematicPhantom = null;
   try {
-    mutateJsonFileLocked(wiPath, data => {
+    mutateWorkItems(wiScope, data => {
       if (!Array.isArray(data)) return data;
       const w = data.find(i => i.id === itemId);
       if (!w) return data;
@@ -4578,7 +4536,7 @@ function _deferRetryWithCounter(meta, detection, counterField, maxCount, pending
         log('warn', `Work item ${itemId} failed — repeated ${pendingReason} after ${maxCount} attempts`);
       }
       return data;
-    }, { defaultValue: [], skipWriteIfUnchanged: true });
+    });
     syncPrdItemStatus(itemId, finalStatus, meta.item?.sourcePlan);
   } catch (err) {
     log('warn', `${pendingReason} gate: ${err.message}`);
@@ -4840,7 +4798,7 @@ function extractDecompositionJson(stdout, runtimeName) {
  * Parses the optional `followups` array on the agent's completion report,
  * logs each entry at `info` so operators can trace fan-out, and warns when
  * a claimed `wi_id` doesn't match any record in central or per-project
- * work-items.json. The mismatch warning catches dispatches that were reverted
+ * work-item state. The mismatch warning catches dispatches that were reverted
  * (HTTP 409 from /api/work-items dedup), fingerprinted away by the standard
  * dedup window, or otherwise didn't actually land — situations where the
  * agent claimed a follow-up exists but the dashboard/engine has no record.
@@ -4893,12 +4851,12 @@ function processCompletionFollowups(completion, agentId, dispatchItem, config) {
     log('info', `Followup audit (${agentId || 'unknown'} wi=${wiId}): dispatched ${followupWiId}${title ? ` — ${title}` : ''}${parentCommentId ? ` (comment=${parentCommentId})` : ''}${reason ? ` — ${reason}` : ''}`);
     const allIds = loadExistingIds();
     if (allIds.size > 0 && !allIds.has(followupWiId)) {
-      log('warn', `Followup audit (${agentId || 'unknown'} wi=${wiId}): claimed followup ${followupWiId} not found in any work-items.json — dispatch may have been deduped, reverted, or never landed`);
+      log('warn', `Followup audit (${agentId || 'unknown'} wi=${wiId}): claimed followup ${followupWiId} not found in work-item state — dispatch may have been deduped, reverted, or never landed`);
     }
     if (parentItem && (parentSchedule.scheduleId || parentProject)) {
       let stamped = false;
-      for (const wiPath of getWorkItemPaths(config)) {
-        mutateWorkItems(wiPath, items => {
+      for (const scope of getWorkItemScopes(config)) {
+        mutateWorkItems(scope, items => {
           const target = Array.isArray(items) ? items.find(i => i && i.id === followupWiId) : null;
           if (!target) return items;
           if (!target.parent_id && target.id !== wiId) target.parent_id = wiId;
@@ -4949,12 +4907,11 @@ function handleDecompositionResult(stdout, meta, config, runtimeName) {
 
   // Find and update the parent work item
   const projects = shared.getProjects(config);
-  const allPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-  for (const p of projects) allPaths.push(shared.projectWorkItemsPath(p));
+  const allScopes = ['central', ...projects];
 
-  for (const wiPath of allPaths) {
+  for (const scope of allScopes) {
     let found = false;
-    mutateJsonFileLocked(wiPath, data => {
+    mutateWorkItems(scope, data => {
       if (!Array.isArray(data)) return data;
       const p = data.find(i => i.id === parentId);
       if (!p) return data;
@@ -5000,7 +4957,7 @@ function handleDecompositionResult(stdout, meta, config, runtimeName) {
         data.push(childItem);
       }
       return data;
-    }, { skipWriteIfUnchanged: true });
+    });
     if (!found) continue;
     log('info', `Decomposition: ${parentId} → ${subItems.length} sub-items: ${subItems.map(s => s.id).join(', ')}`);
     return subItems.length;
@@ -5049,18 +5006,14 @@ function handleHarnessIterationResult(stdout, structuredCompletion, meta, config
   }
   if (!Array.isArray(nextItems) || nextItems.length === 0) return 0;
 
-  // Mirror handleDecompositionResult: scan central + per-project work-items.json
-  // and append into the file that owns the evaluator (the trio always lands in
-  // the central file in practice — scheduler.discoverScheduledWork writes
-  // directly to engine/work-items.json via engine.js — but iterate defensively).
+  // Append into the scope that owns the evaluator.
   const projects = shared.getProjects(config);
-  const allPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-  for (const p of projects) allPaths.push(shared.projectWorkItemsPath(p));
+  const allScopes = ['central', ...projects];
 
   let appendedTo = null;
-  for (const wiPath of allPaths) {
+  for (const scope of allScopes) {
     let found = false;
-    mutateJsonFileLocked(wiPath, data => {
+    mutateWorkItems(scope, data => {
       if (!Array.isArray(data)) return data;
       const evaluator = data.find(i => i.id === evaluatorItem.id);
       if (!evaluator) return data;
@@ -5072,12 +5025,12 @@ function handleHarnessIterationResult(stdout, structuredCompletion, meta, config
         data.push(it);
       }
       return data;
-    }, { defaultValue: [] });
-    if (found) { appendedTo = wiPath; break; }
+    });
+    if (found) { appendedTo = shared.stateScope(scope); break; }
   }
 
   if (!appendedTo) {
-    log('warn', `Harness ${evaluatorItem._harness.missionId}: evaluator ${evaluatorItem.id} not found in any work-items.json — iteration skipped`);
+    log('warn', `Harness ${evaluatorItem._harness.missionId}: evaluator ${evaluatorItem.id} not found in work-item state — iteration skipped`);
     return 0;
   }
 
@@ -5112,7 +5065,7 @@ function handleHarnessIterationResult(stdout, structuredCompletion, meta, config
  *     ban. If even the deferred ANY_AGENT placeholder cannot be built, log and
  *     skip — the existing discovery-driven re-review path (engine.js:~4249)
  *     will re-evaluate on the next tick.
- *   - All RMW on dispatch.json goes through addToDispatch (mutateDispatch), per
+ *   - All dispatch RMW goes through addToDispatch (mutateDispatch), per
  *     the concurrency rules in CLAUDE.md.
  */
 function dispatchReReviewForFix(fixDispatchItem, meta, config, opts = {}) {
@@ -5134,12 +5087,9 @@ function dispatchReReviewForFix(fixDispatchItem, meta, config, opts = {}) {
   const project = meta.project || null;
   let livePr = pr;
   try {
-    const prPath = project ? shared.projectPrPath(project) : null;
-    if (prPath) {
-      const prs = shared.safeJsonArr(prPath);
-      const target = shared.findPrRecord(prs, pr, project);
-      if (target) livePr = target;
-    }
+    const prs = shared.readPullRequests(project || 'central');
+    const target = shared.findPrRecord(prs, pr, project);
+    if (target) livePr = target;
   } catch { /* fall through to dispatch meta copy */ }
   if (livePr.status && livePr.status !== PR_STATUS.ACTIVE) {
     log('info', `Re-review skipped for ${pr.id}: PR status is ${livePr.status}`);
@@ -5258,29 +5208,28 @@ function pickReReviewAgentHints(config, opts = {}) {
 function applyGoalInvalidation(sourceWiId, invalidates, config) {
   if (!Array.isArray(invalidates) || invalidates.length === 0) return;
 
-  const wiPaths = getWorkItemPaths(config);
+  const workItemScopes = getWorkItemScopes(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 foundScope = null;
     let foundStatus = null;
-    for (const wiPath of wiPaths) {
+    for (const scope of workItemScopes) {
       try {
-        const items = readOptionalJsonStrict(wiPath, 'work-items', Array.isArray) || [];
+        const items = shared.readWorkItems(scope);
         const item = items.find(i => i && i.id === targetId);
         if (item) {
-          foundPath = wiPath;
+          foundScope = scope;
           foundStatus = item.status;
           break;
         }
       } catch { /* best-effort scan */ }
     }
 
-    if (!foundPath) {
+    if (!foundScope) {
       log('warn', `Goal invalidation: WI ${targetId} listed in invalidates[] by ${sourceWiId} not found — skipping`);
       continue;
     }
@@ -5292,7 +5241,7 @@ function applyGoalInvalidation(sourceWiId, invalidates, config) {
 
     // Cancel the WI via mutateWorkItems so the SQL store + state event are updated.
     try {
-      mutateWorkItems(foundPath, (items) => {
+      mutateWorkItems(foundScope, (items) => {
         if (!Array.isArray(items)) return items;
         const wi = items.find(i => i && i.id === targetId);
         if (!wi) return items;
@@ -5463,7 +5412,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // PR follow-up audit (W-mpej3cox00099466) — when the agent declares
   // `followups: [{wi_id, title, reason, parent_comment_id}]` in its completion
   // report, log each entry and verify the claimed WI ids actually landed in
-  // some project's work-items.json. A mismatch (claimed wi_id with no matching
+  // some project scope. A mismatch (claimed wi_id with no matching
   // record) is logged at warn so operators can spot dispatches that were
   // reverted, fingerprinted-deduped, or otherwise didn't take.
   if (structuredCompletion) {
@@ -5512,7 +5461,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // syncPrsFromOutput only enrolls PRs whose URL appeared in this dispatch's
   // output. When meta.item._pr was stamped from an earlier dispatch (e.g. via
   // reconcileItemsWithPrs against pr-links) but the canonical row never made
-  // it into pull-requests.json, the dashboard's PRD-progress synthesis
+  // it into tracked PR state, the dashboard's PRD-progress synthesis
   // defaults to ACTIVE forever. This catches those cases at the end of every
   // post-completion run.
   try {
@@ -5545,7 +5494,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // Auto-recover: if a failed implement/fix/test agent created PRs, it likely succeeded before the failure surfaced.
   // P-d2a8f6c1: skip auto-recovery for nonce-mismatched dispatches — a forged
   // report shouldn't be able to ride PRs into a "done" status.
-  const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX || type === WORK_TYPE.TEST;
+  const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || shared.isFixLikeWorkType(type) || type === WORK_TYPE.TEST;
   const autoRecovered = !nonceMismatch && !agentReportedFailure && !isSuccess && prsCreatedCount > 0 && prCreatingType && !!meta?.item?.id;
   if (autoRecovered) {
     log('info', `Auto-recovery: agent failed but created ${prsCreatedCount} PR(s) — upgrading ${meta.item.id} to done`);
@@ -5579,10 +5528,10 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       // the DONE update so the parent stays pending. The dispatch retry layer
       // will requeue it through the standard cooldown/backoff path.
       skipDoneStatus = true;
-      const wiPath = resolveWorkItemPath(meta);
-      if (wiPath) {
+      const wiScope = resolveWorkItemScope(meta);
+      if (wiScope) {
         try {
-          mutateJsonFileLocked(wiPath, data => {
+          mutateWorkItems(wiScope, data => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i.id === meta.item.id);
             if (wi) {
@@ -5591,7 +5540,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
               wi._pendingReason = 'decompose_no_children';
             }
             return data;
-          }, { skipWriteIfUnchanged: true });
+          });
         } catch (err) { log('warn', `Decompose retry-prep cleanup: ${err.message}`); }
       }
       log('warn', `Decomposition for ${meta.item.id}: success report but no children created — parent left pending for retry`);
@@ -5600,7 +5549,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
 
   // Tri-agent harness iteration (W-mq07a9gf000jbc2b): if the evaluator just
   // completed successfully and verdict says retry, append the next Gen+Eval
-  // pair into the same work-items.json. Engine will dispatch them on the
+  // pair into the same work-item scope. Engine will dispatch them on the
   // next tick. No interaction with skipDoneStatus — the evaluator itself
   // still marks DONE; iteration is a sibling write, not a parent decomp.
   if (effectiveSuccess && meta?.item?._harness?.role === harness.HARNESS_ROLE.EVALUATOR) {
@@ -5628,10 +5577,10 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       log('info', `Review ${meta.item.id} bailed out (review already posted) — treating as DONE without retry`);
     } else if (!verdict) {
       skipDoneStatus = true;
-      const wiPath = resolveWorkItemPath(meta);
-      if (wiPath) {
+      const wiScope = resolveWorkItemScope(meta);
+      if (wiScope) {
         try {
-          mutateJsonFileLocked(wiPath, data => {
+          mutateWorkItems(wiScope, data => {
             if (!Array.isArray(data)) return data;
             const w = data.find(i => i.id === meta.item.id);
             if (!w) return data;
@@ -5656,7 +5605,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
               log('warn', `Review ${meta.item.id} failed — no verdict after ${ENGINE_DEFAULTS.maxRetries} retries`);
             }
             return data;
-          }, { skipWriteIfUnchanged: true });
+          });
         } catch (err) { log('warn', `review verdict check: ${err.message}`); }
       }
     }
@@ -5683,7 +5632,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
         if (!prd || !shared.prdMatchesSourcePlan(prd.source_plan, meta.item.planFile)) {
           throw new Error(`sidecar source_plan "${prd?.source_plan ?? '(unknown)'}" does not match "${meta.item.planFile}"`);
         }
-        prdStore.writePrd(path.join(PRD_DIR, expectedFile), prd);
+        prdStore.writePrd(expectedFile, prd);
         fs.unlinkSync(resultPath);
       } catch (e) {
         log('warn', `plan-to-prd ${meta.item.id}: could not import result sidecar: ${e.message}`);
@@ -5707,14 +5656,14 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       }
     }
     // Migrate _prdFilename when the source_plan scan found our PRD under a
-    // different on-disk filename (e.g. agent bumped past a clobbered name, or
+    // different filename (e.g. agent bumped past a clobbered name, or
     // a previous tick pinned a stale name). Future readers (artifacts, dashboard
     // links) need to point at the actual file.
     if (prdFound && resolvedPrdFilename && resolvedPrdFilename !== expectedFile) {
-      const wiPath = resolveWorkItemPath(meta);
-      if (wiPath) {
+      const wiScope = resolveWorkItemScope(meta);
+      if (wiScope) {
         try {
-          mutateJsonFileLocked(wiPath, data => {
+          mutateWorkItems(wiScope, data => {
             if (!Array.isArray(data)) return data;
             const w = data.find(i => i.id === meta.item.id);
             if (!w) return data;
@@ -5723,7 +5672,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
               w._artifacts.prd = resolvedPrdFilename;
             }
             return data;
-          }, { skipWriteIfUnchanged: true });
+          });
           meta.item._prdFilename = resolvedPrdFilename;
           log('info', `plan-to-prd ${meta.item.id}: migrated _prdFilename "${expectedFile}" → "${resolvedPrdFilename}" (matched by source_plan, likely collision)`);
         } catch (err) { log('warn', `plan-to-prd _prdFilename migration: ${err.message}`); }
@@ -5731,10 +5680,10 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
     if (!prdFound) {
       skipDoneStatus = true;
-      const wiPath = resolveWorkItemPath(meta);
-      if (wiPath) {
+      const wiScope = resolveWorkItemScope(meta);
+      if (wiScope) {
         try {
-          mutateJsonFileLocked(wiPath, data => {
+          mutateWorkItems(wiScope, data => {
             if (!Array.isArray(data)) return data;
             const w = data.find(i => i.id === meta.item.id);
             if (!w) return data;
@@ -5764,7 +5713,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
               log('warn', `plan-to-prd ${meta.item.id} failed — no PRD result after ${ENGINE_DEFAULTS.maxRetries} retries`);
             }
             return data;
-          }, { skipWriteIfUnchanged: true });
+          });
         } catch (err) { log('warn', `plan-to-prd PRD check: ${err.message}`); }
       }
     }
@@ -5843,26 +5792,28 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       try { stampPrdItemWorkItemId(meta.item.id, meta.item.sourcePlan); } catch (err) { log('warn', `stampPrdItemWorkItemId: ${err.message}`); }
     }
     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}`); }
     }
   }
+  if (effectiveSuccess && !skipDoneStatus) {
+    // Coding WIs and direct PR-sourced fix dispatches share this follow-up path.
+    try { autoDispatchLiveValidationWi(meta, config, dispatchItem); } catch (err) { log('warn', `autoDispatchLiveValidationWi: ${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.
   if (!effectiveSuccess && meta?.item?.id && type === WORK_TYPE.DECOMPOSE) {
-    const wiPath = resolveWorkItemPath(meta);
-    if (wiPath) {
+    const wiScope = resolveWorkItemScope(meta);
+    if (wiScope) {
       try {
-        mutateJsonFileLocked(wiPath, data => {
+        mutateWorkItems(wiScope, data => {
           if (!Array.isArray(data)) return data;
           const wi = data.find(i => i.id === meta.item.id);
           if (wi) delete wi._decomposing;
           return data;
-        }, { skipWriteIfUnchanged: true });
+        });
       } catch (err) { log('warn', `Decompose cleanup: ${err.message}`); }
     }
   }
@@ -5956,7 +5907,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   if (qaSessionId && qaSessionPhase) {
     try {
       const qaSessions = require('./qa-sessions');
-      const wiPath = resolveWorkItemPath(meta);
+      const scope = resolveWorkItemScope(meta);
       const project = meta?.project?.name || meta?.item?.project || null;
       const failureReason = typeof resultSummary === 'string' && resultSummary
         ? resultSummary
@@ -5964,7 +5915,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       if (qaSessionPhase === 'setup') {
         qaSessions.handleSetupComplete(qaSessionId, {
           success: !!effectiveSuccess,
-          wiPath,
+          scope,
           project,
           failureClass: (structuredCompletion && structuredCompletion.failure_class) || null,
           reason: failureReason,
@@ -6000,7 +5951,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
           qaSessions.handleDraftComplete(qaSessionId, {
             success: true,
             testFile,
-            wiPath,
+            scope,
             project,
             qaRunId,
             reason: failureReason,
@@ -6045,7 +5996,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
 
   let prFixBranchChange = null;
   let prFixBuildStillFailing = null;
-  if (type === WORK_TYPE.FIX && effectiveSuccess && meta?.pr?.id) {
+  if (shared.isFixLikeWorkType(type) && effectiveSuccess && meta?.pr?.id) {
     try {
       prFixBranchChange = await detectPrFixBranchChange(meta, config);
     } catch (err) {
@@ -6078,13 +6029,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
 
-  // Scheduled task back-reference: update schedule-runs.json and write linked inbox note
+  // Scheduled task back-reference: update SQL state and write a linked inbox note.
   if (meta?.item?._scheduleId) {
     try {
       const scheduleId = meta.item._scheduleId;
       const itemId = meta.item.id;
-      const schedRunsPath = path.join(ENGINE_DIR, 'schedule-runs.json');
-      mutateJsonFileLocked(schedRunsPath, (runs) => {
+      shared.mutateScheduleRuns((runs) => {
         // P-c549d07e — preserve existing fields (esp. recentWorkItemIds ring
         // populated at dispatch time by engine/scheduler.writeScheduleRunEntry).
         // The literal-object replacement that lived here previously silently
@@ -6098,7 +6048,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
           lastCompletedAt: ts(),
         };
         return runs;
-      }, { defaultValue: {} });
+      });
       const status = effectiveSuccess ? 'succeeded' : 'failed';
       if (effectiveSuccess) {
         // Write a completion note to inbox with back-references only for successful scheduled runs.
@@ -6188,7 +6138,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   } else if (type === WORK_TYPE.REVIEW) {
     log('warn', `Skipping PR review metadata update for ${meta?.pr?.id || meta?.pr?.url || '(unknown PR)'} because review dispatch ${dispatchItem.id} did not complete cleanly`);
   }
-  if (type === WORK_TYPE.FIX && effectiveSuccess) {
+  if (shared.isFixLikeWorkType(type) && effectiveSuccess) {
     updatePrAfterFix(meta?.pr, meta?.project, meta?.source, {
       branchChanged: fixCompletionChangedBranch(structuredCompletion),
       automationCauseKey: meta?.automationCauseKey,
@@ -6225,7 +6175,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
         }
       } catch (err) { log('warn', `PRD sync after fix: ${err.message}`); }
     }
-  } else if (type === WORK_TYPE.FIX && meta?.pr?.id) {
+  } else if (shared.isFixLikeWorkType(type) && meta?.pr?.id) {
     // W-mph6br6a0006a2b9 (F9): the fix dispatch did not complete cleanly
     // (agent crash, non-zero exit, hard contract failure, or nonce mismatch),
     // so updatePrAfterFix above was skipped. Without a write here the PR's
@@ -6296,24 +6246,20 @@ function syncPrdFromPrs(config) {
     const allProjects = shared.getProjects(config);
 
     // Exact prdItems match only — no fuzzy matching
-    const allPrs = allProjects.flatMap(p => safeJsonArr(shared.projectPrPath(p)));
+    const allPrs = allProjects.flatMap(p => shared.readPullRequests(p));
 
     let totalReconciled = 0;
     for (const project of allProjects) {
-      const wiPath = shared.projectWorkItemsPath(project);
-      const items = safeJsonArr(wiPath);
+      const items = shared.readWorkItems(project);
       const hasReconcilable = items.some(wi =>
         (wi.status === WI_STATUS.PENDING && !wi._pr) || wi.status === WI_STATUS.FAILED);
       if (!hasReconcilable) continue;
       let reconciled = 0;
-      // skipWriteIfUnchanged: per-poll reconcile runs every prPollStatusEvery
-      // ticks. Without the flag it'd unconditionally rewrite project work-items.json,
-      // tripping the cli.js watcher into a tick storm even with zero reconciliation.
-      const reconciledItems = mutateJsonFileLocked(wiPath, data => {
+      const reconciledItems = mutateWorkItems(project, data => {
         if (!Array.isArray(data)) return data;
         reconciled = reconcileItemsWithPrs(data, allPrs);
         return data;
-      }, { skipWriteIfUnchanged: true });
+      });
       if (reconciled > 0) {
         // Sync done status to PRD JSON for each newly reconciled item
         for (const wi of (reconciledItems || [])) {
@@ -6336,7 +6282,7 @@ function syncPrdFromPrs(config) {
         let sourcePlan = pr.sourcePlan;
         if (!sourcePlan) {
           for (const project of allProjects) {
-            const items = safeJsonArr(shared.projectWorkItemsPath(project));
+            const items = shared.readWorkItems(project);
             const wi = items.find(w => w.id === itemId);
             if (wi?.sourcePlan) { sourcePlan = wi.sourcePlan; break; }
           }
@@ -6377,15 +6323,14 @@ function advancePrdStatusOnAllItemsDone(config) {
   // 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))) {
+    for (const pr of shared.readPullRequests(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);
+      const plan = prdStore.readPrd(file);
       if (!plan?.missing_features?.length) continue;
       // Skip frozen PRDs — paused/rejected/awaiting-approval/completed/archived
       if (_PRD_FROZEN_STATUSES.has(plan.status)) continue;
@@ -6405,13 +6350,13 @@ function advancePrdStatusOnAllItemsDone(config) {
 
       if (!allDone) continue;
 
-      mutateJsonFileLocked(fpath, (data) => {
-        // Re-check under lock — another writer may have frozen this PRD
+      prdStore.mutatePrd(file, (data) => {
+        // Re-check transactionally — 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}`);
@@ -6419,17 +6364,17 @@ function advancePrdStatusOnAllItemsDone(config) {
   }
 }
 
-// ─── Persist verify/E2E aggregate PRs onto the PRD JSON (W-mqps9jlb) ──────────
+// ─── Persist verify/E2E aggregate PRs onto the PRD (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).
+// renderE2eSection) sources its PRs from the live tracker.
 // A merged aggregate PR therefore VANISHES from the PRD page once its record is
 // swept — by the daily-remove-merged-prs schedule, a manual delete, or a
 // merge-back/reconcile flow. To make the PRD view survive removal of the live
 // record we durably stamp a compact reference array (`prd.verifyPrs`) onto the
-// owning PRD JSON.
+// owning PRD.
 //
 // This runs per-tick (right after syncPrdFromPrs). It reads the NORMALIZED
-// pull-requests.json schema, so a single sweep covers BOTH the GitHub and ADO
+// shared PR schema, so a single sweep covers both GitHub and ADO
 // pollers at once (engine/github.js + engine/ado.js are intentional mirrors
 // writing the same schema) — the durable single-source approach the task
 // allows in lieu of hooking each poller's merged transition separately. Because
@@ -6488,7 +6433,7 @@ function persistVerifyPrsToPrd(config) {
     const refsByPlan = new Map(); // planFile -> Map(id -> ref)
     for (const project of projects) {
       let prs;
-      try { prs = safeJsonArr(shared.projectPrPath(project)); } catch { continue; }
+      try { prs = shared.readPullRequests(project); } catch { continue; }
       for (const pr of (prs || [])) {
         if (!pr || !pr.id) continue;
         if (!_isVerifyAggregatePr(pr)) continue;
@@ -6503,20 +6448,19 @@ function persistVerifyPrsToPrd(config) {
     if (refsByPlan.size === 0) return;
 
     for (const [planFile, refMap] of refsByPlan) {
-      // Resolve the PRD file (active or archived). sourcePlan is a bare filename.
-      const candidates = [path.join(PRD_DIR, planFile), path.join(PRD_DIR, 'archive', planFile)];
-      const fpath = candidates.find(p => safeJsonNoRestore(p));
-      if (!fpath) continue;
-
-      // Lock-free peek (mirrors syncPrdItemStatus): only take the write lock
-      // when the persisted refs would actually change. safeJsonNoRestore so an
-      // archived PRD's .backup sidecar can't resurrect stale state.
+      let archived = false;
       let plan;
-      try { plan = safeJsonNoRestore(fpath); } catch { continue; }
+      try {
+        plan = prdStore.readPrd(planFile);
+        if (!plan) {
+          archived = true;
+          plan = prdStore.readPrd(planFile, { archived: true });
+        }
+      } catch { continue; }
       if (!plan || typeof plan !== 'object') continue;
       if (!_verifyPrsNeedUpdate(plan.verifyPrs, refMap)) continue;
 
-      mutateJsonFileLocked(fpath, (fresh) => {
+      prdStore.mutatePrd(planFile, (fresh) => {
         if (!fresh || typeof fresh !== 'object') return fresh;
         const byId = new Map();
         for (const e of (Array.isArray(fresh.verifyPrs) ? fresh.verifyPrs : [])) {
@@ -6528,7 +6472,7 @@ function persistVerifyPrsToPrd(config) {
         }
         fresh.verifyPrs = [...byId.values()];
         return fresh;
-      }, { skipWriteIfUnchanged: true });
+      }, { archived });
     }
   } catch (err) {
     try { log('warn', `persistVerifyPrsToPrd error: ${err?.message || err}`); } catch { /* engine not available */ }
@@ -6759,14 +6703,13 @@ function pruneScopeMismatchDuplicatePrs(config) {
   for (const [targetProjectName, entries] of relocationsByTargetProject) {
     const targetProject = projects.find(p => p.name === targetProjectName);
     if (!targetProject) continue;
-    const targetPrPath = projectPrPath(targetProject);
     for (const { rec, owningScope } of entries) {
       const entry = { ...rec };
       delete entry._scope;
       delete entry._invalidProjectScope;
       delete entry.project; // let upsertPullRequestRecord backfill from targetProject
       try {
-        const result = shared.upsertPullRequestRecord(targetPrPath, entry, {
+        const result = shared.upsertPullRequestRecord(targetProject, entry, {
           project: targetProject,
           itemIds: Array.isArray(rec.prdItems) ? rec.prdItems : null,
         });
@@ -6797,10 +6740,9 @@ function pruneScopeMismatchDuplicatePrs(config) {
   for (const [projectName, idsToDelete] of deletesByProject) {
     const project = projects.find(p => p.name === projectName);
     if (!project) continue;
-    const prPath = projectPrPath(project);
     const pruneIds = pruneDeletesByProject.get(projectName) || new Set();
     try {
-      shared.mutatePullRequests(prPath, (prs) => {
+      shared.mutatePullRequests(project, (prs) => {
         const deletedIds = prs.filter(p => idsToDelete.has(p?.id)).map(p => p.id);
         const next = prs.filter(p => !idsToDelete.has(p?.id));
         for (const id of deletedIds) {
@@ -6831,9 +6773,8 @@ function collapseAllDuplicatePrRecords(config) {
 
   for (const project of projects) {
     if (!project || !project.name) continue;
-    const prPath = projectPrPath(project);
     try {
-      const result = shared.collapseDuplicatePrRecords(prPath, { project });
+      const result = shared.collapseDuplicatePrRecords(project, { project });
       collapsed += result.collapsed || 0;
       scanned++;
     } catch (err) {
@@ -6841,14 +6782,13 @@ function collapseAllDuplicatePrRecords(config) {
     }
   }
 
-  // Central file (no project context — normalization uses URL-only scope).
-  const centralPath = path.join(MINIONS_DIR, 'pull-requests.json');
+  // Central scope has no project context; normalization uses URL-only scope.
   try {
-    const result = shared.collapseDuplicatePrRecords(centralPath, {});
+    const result = shared.collapseDuplicatePrRecords('central', {});
     collapsed += result.collapsed || 0;
     scanned++;
   } catch (err) {
-    log('warn', `collapseAllDuplicatePrRecords: failed for central file: ${err?.message || err}`);
+    log('warn', `collapseAllDuplicatePrRecords: failed for central scope: ${err?.message || err}`);
   }
 
   if (collapsed > 0) {
@@ -6862,37 +6802,9 @@ function collapseAllDuplicatePrRecords(config) {
 // a coding WI (not one of the validation types itself). Skips if the coding WI
 // has no PR.
 //
-// W-mrdq22j700056c6c — gated to real code-authoring completions only. Only
-// item.type in {implement, implement:large, fix} ever spawns a follow-up
-// validation WI. Every other work-item type (review, test, verify, setup,
-// explore, ask, docs, decompose, ...) is excluded even when it resolves a PR
-// ref and autoDispatch is on, because those completions don't author a code
-// diff worth re-validating — e.g. a `review` dispatch that merely comments on
-// someone else's PR previously spawned a spurious "Validate: Review opg PR
-// #792 ..." follow-up. See the ELIGIBLE_TYPES check below.
-//
-// Files exactly ONE validation WI per coding-WI completion (W-mrhybval0001).
-// `liveValidation.type` still governs CHECKOUT ROUTING — the set of work-item
-// types that run in-place on the live checkout (see resolveCheckoutMode's
-// membership check) — but auto-validation no longer fans that array out into
-// one validation WI per type. That earlier behavior (W-mr2m1ute000a9c01)
-// conflated "which types run live" with "how many validation tasks to file";
-// a multi-select routing config would silently spawn N validation WIs after
-// every coding completion. Validation is a single downstream step, so we
-// collapse to one WI.
-//
-// liveValidation.type may be a single string (legacy / back-compat) or an
-// array of strings (multi-select hybrid types). We choose ONE validation type
-// for the single WI. It MUST be a member of lvTypes, otherwise resolveCheckoutMode
-// would route the validation WI to a worktree instead of the live checkout
-// (defeating hybrid validation). Preference order: the canonical `test` type
-// when configured, else the first configured live type. The completing item's
-// own type is excluded so a validation-type WI can't recursively validate
-// itself (anti-loop).
-//
-// Only these item.type values ever trigger this hook (see ELIGIBLE_TYPES
-// below) — real code-authoring completions, not review/test/verify/setup/
-// explore/ask/docs/decompose completions.
+// Only real code-authoring completions trigger the hook. The follow-up is
+// always a canonical `test` WI with the PR-focused `build-and-test` playbook;
+// liveValidation.type controls routing, not the semantic type of the task.
 //
 // Deduplicates per codingWiId: any non-terminal WI with
 // meta.liveValidationFor === codingWiId blocks a second dispatch, so only one
@@ -6914,22 +6826,30 @@ function collapseAllDuplicatePrRecords(config) {
 // verify, setup, explore, ask, docs, decompose, ...) is excluded even when it
 // resolves a PR ref, because those completions don't author a code diff
 // worth re-validating.
-const ELIGIBLE_LIVE_VALIDATION_TYPES = new Set([WORK_TYPE.IMPLEMENT, WORK_TYPE.IMPLEMENT_LARGE, WORK_TYPE.FIX]);
+const ELIGIBLE_LIVE_VALIDATION_TYPES = new Set([
+  WORK_TYPE.IMPLEMENT,
+  WORK_TYPE.IMPLEMENT_LARGE,
+  WORK_TYPE.FIX,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
+]);
 
-function autoDispatchLiveValidationWi(meta, config) {
-  const item = meta?.item;
-  if (!item?.id || !item?.type) return;
+function autoDispatchLiveValidationWi(meta, config, dispatchItem = null) {
+  const item = meta?.item || null;
+  const sourceType = item?.type || dispatchItem?.type || null;
+  const sourceKey = item?.id || dispatchItem?.id || null;
+  if (!sourceKey || !sourceType) return;
+  if (!item && !meta?.pr) return;
 
   // Never re-trigger off the completion of a WI that was itself auto-created
   // as a live-validation follow-up — that's what causes the infinite
   // "Validate: Validate: ..." cascade (W-mr9u39az000db5c2 / issue #708).
-  if (item.meta && item.meta.liveValidationFor) return;
+  if (item?.meta && item.meta.liveValidationFor) return;
 
-  // W-mrdq22j700056c6c — only implement/implement:large/fix completions ever
+  // Only implement/implement:large/fix/build-fix-complex completions ever
   // author a real code diff worth validating. Review, test, verify, setup,
   // explore, ask, docs, decompose, etc. completions must never spawn a
   // "Validate: ..." follow-up, even when they resolve a PR reference.
-  if (!ELIGIBLE_LIVE_VALIDATION_TYPES.has(item.type)) return;
+  if (!ELIGIBLE_LIVE_VALIDATION_TYPES.has(sourceType)) return;
 
   // Issue #716 — QA Session infrastructure WIs (SETUP/DRAFT/EXECUTE, tagged
   // via meta.sessionId and always dispatched with skipPr:true) never own a
@@ -6939,7 +6859,7 @@ function autoDispatchLiveValidationWi(meta, config) {
   // for all three phases) spawns spurious "Validate: QA Session ..." WIs the
   // moment any PR reference resolves against it (see the skipPr guard below
   // resolveWorkItemPrRecord in engine.js for the matching pre-dispatch fix).
-  if (item.skipPr || (item.meta && item.meta.sessionId)) return;
+  if (item?.skipPr || (item?.meta && item.meta.sessionId)) return;
 
   const projectName = meta?.project?.name;
   if (!projectName) return;
@@ -6949,23 +6869,8 @@ function autoDispatchLiveValidationWi(meta, config) {
   const project = projects.find(p => p && p.name === projectName);
   if (!project) return;
 
-  const lv = project.liveValidation;
-  if (!lv || lv.autoDispatch !== true || !lv.type) return;
-
-  const lvTypes = Array.isArray(lv.type) ? lv.type : [lv.type];
-
-  // Candidate validation types = configured live types minus the completing
-  // item's own type (avoid an infinite validate-the-validation loop).
-  const candidates = lvTypes.filter(t => t && t !== item.type);
-  if (candidates.length === 0) return;
-
-  // Collapse to a SINGLE validation type: prefer the canonical `test` type when
-  // it is a configured live type, else the first configured live type. Either
-  // way the chosen type is a member of lvTypes, so the validation WI routes to
-  // the live checkout (not a worktree).
-  const validationType = candidates.includes(WORK_TYPE.TEST)
-    ? WORK_TYPE.TEST
-    : candidates[0];
+  const validationType = shared.resolveLiveValidationAutoDispatchType(project);
+  if (!validationType) return;
 
   // Resolve PR reference: prefer the canonical stamped _pr field (set by
   // stampWiPrRef which runs earlier in runPostCompletionHooks), then fall
@@ -6977,15 +6882,26 @@ function autoDispatchLiveValidationWi(meta, config) {
   // (W-mq18ec6h000p7b87) and would otherwise let a non-fix WI (e.g.
   // 'implement'/'docs') that merely *mentions* an unrelated PR number in
   // prose trigger a live-validation dispatch against the wrong PR.
-  const prRef = item._pr || item._prUrl || shared.extractStructuredWorkItemPrRef(item) || null;
+  const prRef = item
+    ? (item._pr || item._prUrl || shared.extractStructuredWorkItemPrRef(item) || null)
+    : (meta?.pr || null);
   if (!prRef) return;
 
-  const codingWiId = item.id;
-  const wiPath = resolveWorkItemPath(meta);
-  if (!wiPath) return;
+  const prUrl = item?._prUrl || (typeof prRef === 'object'
+    ? (prRef.url || prRef.webUrl || prRef.remoteUrl || null)
+    : (/^https?:\/\//i.test(String(prRef)) ? String(prRef) : null));
+  const prId = typeof prRef === 'object'
+    ? (prRef.id || prRef.pr_id || prRef.prId || prRef.pullRequestId || shared.getPrNumber(prRef))
+    : String(prRef);
+  const prTarget = prUrl || (prId != null ? String(prId) : null);
+  if (!prTarget) return;
+
+  const codingWiId = sourceKey;
+  const wiScope = item ? resolveWorkItemScope(meta) : projectName;
+  if (!wiScope) return;
 
   try {
-    mutateWorkItems(wiPath, items => {
+    mutateWorkItems(wiScope, items => {
       if (!Array.isArray(items)) return items;
 
       // Dedup: only one validation WI in flight per coding WI. Any non-terminal
@@ -7004,7 +6920,7 @@ function autoDispatchLiveValidationWi(meta, config) {
         return items;
       }
 
-      const proposedTitle = 'Validate: ' + (item.title || codingWiId);
+      const proposedTitle = 'Validate: ' + (item?.title || meta?.pr?.title || codingWiId);
       // Defense-in-depth (belt-and-suspenders alongside the meta.liveValidationFor
       // guard above): never create a doubly-nested "Validate: Validate: ..."
       // title even if some future caller manages to invoke this function
@@ -7019,11 +6935,20 @@ function autoDispatchLiveValidationWi(meta, config) {
         title: proposedTitle,
         type: validationType,
         status: WI_STATUS.PENDING,
-        depends_on: [codingWiId],
-        references: [prRef],
-        meta: { liveValidationFor: codingWiId, liveValidationType: validationType },
+        depends_on: item?.id ? [codingWiId] : [],
+        targetPr: prTarget,
+        pr_id: prId != null ? String(prId) : prTarget,
+        references: prUrl
+          ? [{ url: prUrl, label: 'Source PR' }]
+          : [prTarget],
+        meta: {
+          liveValidationFor: codingWiId,
+          liveValidationType: validationType,
+          playbook: 'build-and-test',
+          ...(dispatchItem?.id ? { sourceDispatchId: dispatchItem.id } : {}),
+        },
         project: projectName,
-        priority: item.priority || 'medium',
+        priority: item?.priority || 'medium',
         created: ts(),
         createdBy: 'lifecycle:live-validation-auto-dispatch',
       };
@@ -7083,7 +7008,7 @@ module.exports = {
   syncPrdFromPrs,
   advancePrdStatusOnAllItemsDone,
   persistVerifyPrsToPrd,
-  resolveWorkItemPath,
+  resolveWorkItemScope,
   isItemCompleted,
   classifyFailure,
   diagnoseEmptyOutput,