@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{lifecycle.js → orchestration/lifecycle.js}

@@ -1,26 +1,26 @@
 /**
- * engine/lifecycle.js — Post-completion hooks, PR sync, agent history/metrics, plan chaining.
+ * engine/orchestration/lifecycle.js — Post-completion hooks, PR sync, agent history/metrics, plan chaining.
  * Extracted from engine.js.
  */
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const shared = require('./shared');
+const shared = require('../core/shared');
 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, hasUnfinishedToolCall } = require('./runtimes');
-const adoGitAuth = require('./ado-git-auth');
-const queries = require('./queries');
-const harness = require('./harness');
-const reviewLearning = require('./review-learning');
-const smallStateStore = require('./small-state-store');
-const prdStore = require('./prd-store');
-const memoryStore = require('./memory-store');
-const promotion = require('./promotion');
+const { resolveRuntime, hasUnfinishedToolCall } = require('../runtimes');
+const adoGitAuth = require('../ado/git-auth');
+const queries = require('../core/queries');
+const harness = require('../agents/harness');
+const reviewLearning = require('../memory/review-learning');
+const smallStateStore = require('../persistence/small-state-store');
+const prdStore = require('../planning/prd-store');
+const memoryStore = require('../memory/memory-store');
+const promotion = require('../memory/promotion');
 const { isBranchActive } = require('./cooldown');
-const { resolveExecutionModel } = require('./execution-model');
+const { resolveExecutionModel } = require('../core/execution-model');
 const { worktreeMatchesBranch, getWorktreeBranch, cleanupMergedPrLocalBranch } = require('./cleanup');
 const { getConfig, getInboxFiles, getNotes, getPrs, getDispatch,
   MINIONS_DIR, ENGINE_DIR, PLANS_DIR, INBOX_DIR, AGENTS_DIR } = queries;
@@ -356,7 +356,7 @@ function checkPlanCompletion(meta, config) {
       // a crafted `plan.feature_branch` (e.g. `main; rm -rf ~`) or PR
       // `branch` field reaches the Bash tool via template literal
       // interpolation. github.js validates pr.branch on API persistence
-      // (engine/github.js:612-622), but feature_branch has no upstream
+      // (engine/providers/github.js:612-622), but feature_branch has no upstream
       // validator and mainBranch can fall through unvalidated from project
       // config when `git rev-parse` can't verify it (shared.js:1328). Defense
       // in depth lives here, at the actual interpolation site.
@@ -728,6 +728,8 @@ function updateWorkItemStatus(meta, status, reason) {
         delete target.failReason;
         delete target.failedAt;
         delete target._retryCount;
+        delete target._infrastructureRetryCount;
+        delete target._lastInfrastructureFailureClass;
         delete target._retriesByAgent;
         target.completedAgents = Object.entries(target.agentResults)
           .filter(([, r]) => r.status === WI_STATUS.DONE)
@@ -745,6 +747,8 @@ function updateWorkItemStatus(meta, status, reason) {
         delete target.failReason;
         delete target.failedAt;
         delete target._retryCount;
+        delete target._infrastructureRetryCount;
+        delete target._lastInfrastructureFailureClass;
         delete target._retriesByAgent;
         // P-e0b4f7a5 — successful completion (including a phantom-retry
         // succeeding) clears the phantom markers so cleanup can reap the
@@ -1195,12 +1199,12 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
         log('warn', `Duplicate PR detected: ${fullId} on branch ${entry.branch || entryBranch} — already tracked as ${duplicateOnBranch.id}. Skipping.`);
         // Best-effort close the duplicate on GitHub (non-blocking, fire-and-forget).
         // The closing comment is wrapped with the minions marker so the PR-comment
-        // classifier (engine/github.js _isMinionsAuthoredComment, sub-task -b)
+        // classifier (engine/providers/github.js _isMinionsAuthoredComment, sub-task -b)
         // recognizes it as engine-authored and never queues a fix-dispatch on it.
         try {
           const ghSlug = outputText.match(/github\.com\/([^/]+\/[^/]+)/)?.[1];
           if (ghSlug) {
-            const { buildMinionsCommentBody } = require('./gh-comment');
+            const { buildMinionsCommentBody } = require('../providers/gh-comment');
             const dupComment = buildMinionsCommentBody({
               agentId: 'engine',
               kind: 'positive-signal',
@@ -1261,7 +1265,7 @@ async function _fetchGitHubPrStateForEnrollment(slug, prNumber) {
   }
   let token = null;
   try {
-    const ghToken = require('./gh-token');
+    const ghToken = require('../providers/gh-token');
     if (typeof ghToken.resolveTokenForSlug === 'function') {
       token = ghToken.resolveTokenForSlug(slug);
     }
@@ -1291,7 +1295,7 @@ function _liveGitHubStateToPrStatus(liveState) {
 
 function _existingPrRecordForCanonicalId(canonicalPrId) {
   try {
-    const store = require('./pull-requests-store');
+    const store = require('../persistence/pull-requests-store');
     if (typeof store.readAllPullRequests !== 'function') return null;
     const all = store.readAllPullRequests() || [];
     return all.find(pr => pr && pr.id === canonicalPrId) || null;
@@ -1398,7 +1402,7 @@ async function enrollPrFromCanonicalId(canonicalPrId, project, opts = {}) {
     try {
       const adoParts = scope.slice('ado:'.length).split('/');
       if (adoParts.length === 3) {
-        const ado = require('./ado');
+        const ado = require('../ado');
         if (typeof ado.fetchAdoPrMetadata === 'function') {
           const meta = await ado.fetchAdoPrMetadata(prNumber, adoParts[0], adoParts[1], adoParts[2], project);
           if (meta) {
@@ -1501,7 +1505,7 @@ function stampWiPrRef(meta, config) {
   const projects = (config && Array.isArray(config.projects))
     ? config.projects : shared.getProjects(config || {});
 
-  const prStore = require('./pull-requests-store');
+  const prStore = require('../persistence/pull-requests-store');
   const allPrs = prStore.readAllPullRequests();
   let found = allPrs.find(r => Array.isArray(r.prdItems) && r.prdItems.includes(itemId)) || null;
 
@@ -1646,10 +1650,12 @@ function runFileCapture(file, args, opts = {}) {
     const timer = timeout ? setTimeout(() => {
       timedOut = true;
       if (!child) return;
-      shared.killGracefully(child, 1000);
+      shared.terminateProcess('engine.lifecycle.hook-timeout-graceful', child, {
+        graceMs: 1000,
+      });
       // Hard-kill fallback if the child ignores SIGTERM. Cleared on close.
       hardKillTimer = setTimeout(() => {
-        try { shared.killImmediate(child); } catch {}
+        try { shared.terminateProcess('engine.lifecycle.hook-timeout-force', child); } catch {}
       }, 2500);
     }, timeout) : null;
     try {
@@ -1662,14 +1668,20 @@ function runFileCapture(file, args, opts = {}) {
     child.stderr?.setEncoding('utf8');
     child.stdout?.on('data', chunk => {
       if (stdout.length + chunk.length > MAX_BUFFER) {
-        if (!killedForBuffer) { killedForBuffer = true; try { shared.killImmediate(child); } catch {} }
+        if (!killedForBuffer) {
+          killedForBuffer = true;
+          try { shared.terminateProcess('engine.lifecycle.hook-buffer-limit', child); } catch {}
+        }
         return;
       }
       stdout += chunk;
     });
     child.stderr?.on('data', chunk => {
       if (stderr.length + chunk.length > MAX_BUFFER) {
-        if (!killedForBuffer) { killedForBuffer = true; try { shared.killImmediate(child); } catch {} }
+        if (!killedForBuffer) {
+          killedForBuffer = true;
+          try { shared.terminateProcess('engine.lifecycle.hook-buffer-limit', child); } catch {}
+        }
         return;
       }
       stderr += chunk;
@@ -1747,7 +1759,7 @@ async function findOpenPrForBranch(meta, config) {
     return null;
   }
   if (host === 'ado') {
-    const found = await require('./ado').findOpenPrOnBranch(projectObj, meta.branch);
+    const found = await require('../ado').findOpenPrOnBranch(projectObj, meta.branch);
     return found ? { project: projectObj, prNumber: found.prNumber, url: found.url } : null;
   }
   log('debug', `Skipping branch PR lookup for unsupported repo host "${host}" on ${projectObj.name}`);
@@ -2368,8 +2380,8 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
     : null;
   const hostForChecks = hostFromCanonical || projectObjForChecks?.repoHost || null;
   let checkFn = null;
-  if (hostForChecks === 'github') checkFn = require('./github').checkLiveReviewStatus;
-  else if (hostForChecks === 'ado') checkFn = require('./ado').checkLiveReviewStatus;
+  if (hostForChecks === 'github') checkFn = require('../providers/github').checkLiveReviewStatus;
+  else if (hostForChecks === 'ado') checkFn = require('../ado').checkLiveReviewStatus;
   else log('warn', `Cannot resolve repoHost for review of ${reviewPr.id} (unparseable canonical id and no project config); skipping live review check.`);
   try {
     if (projectObjForChecks && checkFn) {
@@ -2410,9 +2422,9 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
   if (canDismissOwnPriorNegative) {
     try {
       const reconcileFn = hostForChecks === 'github'
-        ? require('./github').dismissPriorViewerChangesRequestedReviews
+        ? require('../providers/github').dismissPriorViewerChangesRequestedReviews
         : hostForChecks === 'ado'
-          ? require('./ado').resetReviewerNegativeVote
+          ? require('../ado').resetReviewerNegativeVote
           : null;
       if (typeof reconcileFn === 'function') {
         const result = await reconcileFn(reviewPr, projectObjForChecks);
@@ -2584,15 +2596,19 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
 
   log('info', `Updated ${reviewPr.id} → minions review: ${postReviewStatus || REVIEW_STATUS.WAITING} by ${reviewerName}`);
   if (updatedTarget) {
-    createReviewFeedbackForAuthor(agentId, updatedTarget, config, {
-      reviewContent: reviewNote,
-      project: reviewProject,
-      dispatchId: dispatchItem?.id || structuredCompletion?.dispatchId || null,
-      sourceItem: dispatchItem?.meta?.item?.id || null,
-      postReviewStatus,
-      reviewVerdict: verdictRaw,
-      findingIdentity: shared.prReviewFindingIdentity(updatedTarget),
-    });
+    try {
+      createReviewFeedbackForAuthor(agentId, updatedTarget, config, {
+        reviewContent: reviewNote,
+        project: reviewProject,
+        dispatchId: dispatchItem?.id || structuredCompletion?.dispatchId || null,
+        sourceItem: dispatchItem?.meta?.item?.id || null,
+        postReviewStatus,
+        reviewVerdict: verdictRaw,
+        findingIdentity: shared.prReviewFindingIdentity(updatedTarget),
+      });
+    } catch (err) {
+      log('warn', `Review-learning candidate capture failed for ${reviewPr.id}: ${err.message}`);
+    }
   }
 }
 
@@ -2715,13 +2731,13 @@ async function detectPrFixBranchChange(meta, config) {
 }
 
 // #639 — lazy requires for the host-specific live build/conflict checkers.
-// engine/github.js and engine/ado.js both lazy-require lifecycle.js (see
+// engine/providers/github.js and engine/ado/index.js both lazy-require lifecycle.js (see
 // their `lifecycleModule()` helpers), so a top-level require here would form
 // an import cycle. Deferring to first call avoids that.
 let _githubPrModule = null;
-function githubPrModule() { if (!_githubPrModule) _githubPrModule = require('./github'); return _githubPrModule; }
+function githubPrModule() { if (!_githubPrModule) _githubPrModule = require('../providers/github'); return _githubPrModule; }
 let _adoPrModule = null;
-function adoPrModule() { if (!_adoPrModule) _adoPrModule = require('./ado'); return _adoPrModule; }
+function adoPrModule() { if (!_adoPrModule) _adoPrModule = require('../ado'); return _adoPrModule; }
 
 // #639 — No-op fix detection previously only proved whether the agent pushed
 // a NEW commit; it never checked whether the build the fix was dispatched
@@ -3113,7 +3129,7 @@ function clearPrNoOpFixAttempt(target, cause) {
 }
 
 // W-mpx44p05000ze8d8 — Proactive GC for stale `_noOpFixes` records. Called
-// from `engine/ado.js` + `engine/github.js` `pollPrStatus` after the live PR
+// from `engine/ado/index.js` + `engine/providers/github.js` `pollPrStatus` after the live PR
 // fields (headSha, buildStatus, humanFeedback, mergeStatus, reviewStatus,
 // lastPushedAt, etc.) have been refreshed for the current tick. Any
 // `_noOpFixes[cause]` whose stored `evidenceFingerprint` no longer matches
@@ -3604,7 +3620,7 @@ async function handlePostMerge(pr, project, config, newStatus) {
 
   // `project.localPath` guard: central/observed PRs (e.g. ADO PRs tracked in
   // central PRs with no configured project are polled via a
-  // *synthesized* project that has no localPath (engine/ado.js + engine/github.js
+  // *synthesized* project that has no localPath (engine/ado/index.js + engine/providers/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
   // type string" — caught upstream and logged as "failed to poll central PR".
@@ -3876,7 +3892,7 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeN
       const ccContent = `---\nname: ${name}\ndescription: ${description}\n---\n\n${marker}\n\n${body.trim()}\n`;
       if (!fs.existsSync(skillDir)) fs.mkdirSync(skillDir, { recursive: true });
       shared.safeWrite(skillPath, ccContent);
-      try { require('./queries').invalidateSkillsCache(); } catch {}
+      try { require('../core/queries').invalidateSkillsCache(); } catch {}
       log('info', `Extracted skill "${name}" from ${agentName} → ${skillPath}`);
 
     }
@@ -5194,7 +5210,7 @@ function detectNonTerminalResultSummary(_resultSummary, structuredCompletion, co
   // the PR-attachment contract hard-fails them with no retry.
   //
   // Only enabled at call sites where there is no other success signal (e.g.
-  // engine/timeout.js completeFromOutput). runPostCompletionHooks has richer
+  // engine/orchestration/timeout.js completeFromOutput). runPostCompletionHooks has richer
   // signals (PRs created, plan-to-prd PRD file existence, autoRecover) and
   // must not be demoted by this heuristic.
   if (opts && opts.detectPhantom) {
@@ -5950,7 +5966,7 @@ function dispatchReReviewForFix(fixDispatchItem, meta, config, opts = {}) {
   }
 
   const routing = require('./routing');
-  const playbook = require('./playbook');
+  const playbook = require('../agents/playbook');
   const dispatchModule = require('./dispatch');
 
   const reviewAuthor = livePr.agent || pr.agent || null;
@@ -6153,7 +6169,7 @@ function captureTaskMemoryEpisode(dispatchItem, agentId, outcome, structuredComp
   ].join('\n');
 
   try {
-    return require('./memory-store').upsertMemoryRecord({
+    return require('../memory/memory-store').upsertMemoryRecord({
       memoryType: 'episodic',
       scopeType: project ? 'project' : (agentId ? 'agent' : 'global'),
       scopeKey: project || agentId || '',
@@ -6520,24 +6536,28 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     let prdFound = false;
     let resolvedPrdFilename = null;
     const expectedFile = meta.item._prdFilename;
-    const prdStore = require('./prd-store');
+    const prdStore = require('../planning/prd-store');
+    const prdResultSidecar = require('../planning/prd-result-sidecar');
     const agentId = meta._agentId || meta.item.dispatched_to;
-    const resultPath = agentId ? path.join(AGENTS_DIR, agentId, 'prd-result.json') : null;
-    if (expectedFile && resultPath && fs.existsSync(resultPath)) {
-      try {
-        const envelope = shared.safeJsonNoRestore(resultPath);
-        const filename = envelope?.filename || expectedFile;
-        const prd = envelope?.prd || envelope;
-        if (filename !== expectedFile) {
-          throw new Error(`sidecar filename "${filename}" does not match expected "${expectedFile}"`);
-        }
-        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(expectedFile, prd);
-        fs.unlinkSync(resultPath);
-      } catch (e) {
-        log('warn', `plan-to-prd ${meta.item.id}: could not import result sidecar: ${e.message}`);
+    if (expectedFile && agentId) {
+      // W-msa0mrus00mh466f — a revision import must land the PRD back in a
+      // coherent state in the SAME write that imports it: status returns to
+      // awaiting-approval, staleness clears, the source-plan sync fields are
+      // re-baselined and the revision pointers are dropped. The relation is
+      // handed to the sidecar module (which owns the single writePrd) rather
+      // than re-written here, so no reader can observe a completed revision
+      // still paired with the stale recovery controls.
+      const outcome = prdResultSidecar.consumePrdResultSidecar({
+        agentsDir: AGENTS_DIR,
+        agentId,
+        expectedFilename: expectedFile,
+        planFile: meta.item.planFile,
+        workItemId: meta.item.id,
+        revisionForPrd: meta.item._revisionForPrd,
+        plansDir: PLANS_DIR,
+      });
+      if (!outcome.imported && outcome.code !== prdResultSidecar.PRD_RESULT_OUTCOME.ABSENT) {
+        log('warn', `plan-to-prd ${meta.item.id}: could not import result sidecar: ${outcome.reason}`);
       }
     }
     for (const { filename, archived, plan } of prdStore.listPrdRows()) {
@@ -6549,8 +6569,27 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       }
     }
     if (!prdFound && meta.item.planFile) {
+      // Fallback scan. The canonical hit is a live PRD that declares this plan
+      // markdown as its `source_plan`.
+      //
+      // The second clause is a legacy carve-out: a work item whose `planFile`
+      // names a PRD file rather than the source plan markdown (the shape
+      // /api/plans/revise produced before W-msa1y79a01271b91) can NEVER match by
+      // source_plan — prdMatchesSourcePlan compares basenames and a `.json` key
+      // never equals a `.md` one — so the gate would fail every attempt until
+      // maxRetries. Treating a planFile that directly names a live PRD as a hit
+      // lets such an item converge onto the PRD it actually pointed at, and the
+      // migration block below repoints `_prdFilename` at it.
+      //
+      // This deliberately does NOT relax the sidecar-import `source_plan` guard
+      // above: that guard is what stopped a mis-addressed sidecar from being
+      // written under a freshly-minted filename and duplicating the PRD.
+      const planFileKey = shared.sourcePlanKey(meta.item.planFile);
+      const planFileNamesPrd = planFileKey.toLowerCase().endsWith('.json');
       for (const { filename, archived, plan } of prdStore.listPrdRows()) {
-        if (!archived && shared.prdMatchesSourcePlan(plan.source_plan, meta.item.planFile)) {
+        if (archived) continue;
+        if (shared.prdMatchesSourcePlan(plan.source_plan, meta.item.planFile)
+          || (planFileNamesPrd && filename === planFileKey)) {
           prdFound = true;
           resolvedPrdFilename = filename;
           break;
@@ -6594,7 +6633,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
             // buildWorkItemDispatchVars()'s retry_context var (W-mrbq53ra000lf2e5) so the
             // retried agent knows the PRD file was never found instead of silently
             // repeating the same mistake.
-            const gateReason = `Validation gate (#893): no PRD result sidecar was imported for planFile "${meta.item.planFile || w.planFile || '(unknown)'}" (expected filename "${expectedFile || '(unset)'}") after the previous attempt completed. Write agents/<agent-id>/prd-result.json exactly as specified in the playbook before finishing.`;
+            // W-ms9tcry701xz0389 — the reason deliberately carries NO filename.
+            // It is replayed verbatim into the retry prompt, and a filename
+            // captured here is a snapshot of the FAILED attempt; quoting it can
+            // only compete with the authoritative `{{prd_filename}}` the next
+            // dispatch renders. Name the plan and the contract, not the value.
+            const gateReason = `Validation gate (#893): no PRD result sidecar was imported for planFile "${meta.item.planFile || w.planFile || '(unknown)'}" after the previous attempt completed. Write agents/<agent-id>/prd-result.json exactly as the playbook's Output section specifies — including the "filename" the engine pins for this dispatch — before finishing.`;
             if (retries < ENGINE_DEFAULTS.maxRetries) {
               w.status = WI_STATUS.PENDING;
               w._retryCount = retries + 1;
@@ -6846,7 +6890,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // id lives at `dispatchItem.meta.item.meta.qaRunId` in production, NOT
   // at `dispatchItem.meta.qaRunId`. Accept both locations to mirror the
   // keep_processes / managed_spawn skip-worktree-removal pattern below
-  // (engine/lifecycle.js, "_wiMetaForSkip" block) — that way fast-path
+  // (engine/orchestration/lifecycle.js, "_wiMetaForSkip" block) — that way fast-path
   // dispatchers that synthesize meta.qaRunId at the top level keep
   // working too. The agent writes agents/<id>/qa-run-result.json before
   // exit. qa-runs consumes the file exactly once and verifies its runId
@@ -6858,12 +6902,12 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     && completionContractFailure?.nonTerminal !== true
     && Number(meta?.item?._retryCount || 0) < ENGINE_DEFAULTS.maxRetries;
   if (qaRunId && lifecycleGateCanRetry) {
-    try { require('./qa-runs').prepareResultSidecar(agentId || '_unknown', qaRunId); }
+    try { require('../qa/runs').prepareResultSidecar(agentId || '_unknown', qaRunId); }
     catch (e) { log('warn', `qa-validate deferred sidecar cleanup for ${qaRunId}: ${e.message}`); }
     log('warn', `qa-validate run ${qaRunId} remains pending while completion validation retries`);
   } else if (qaRunId) {
     try {
-      const qaRuns = require('./qa-runs');
+      const qaRuns = require('../qa/runs');
       const consumed = qaRuns.consumeResultSidecar(agentId || '_unknown', qaRunId);
       if (consumed.cleanupError) {
         log('warn', `qa-validate sidecar cleanup for ${qaRunId}: ${consumed.cleanupError}`);
@@ -6879,6 +6923,10 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
           status: parsed.status,
           summary: typeof parsed.summary === 'string' ? parsed.summary : '',
           artifacts: Array.isArray(parsed.artifacts) ? parsed.artifacts : [],
+          // W-msb9kgs402813a97-c — per-journey outcomes drive the EXECUTE
+          // evidence gate. Forwarded only when the agent declared them, so
+          // legacy qa-validate sidecars keep their historical record shape.
+          journeyCoverage: parsed.journeyCoverage,
         });
         log('info', `qa-validate run ${qaRunId} → ${parsed.status} (${(parsed.artifacts || []).length} artifacts)`);
       } else {
@@ -6910,7 +6958,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
 
   // P-a3f7c1b2 — QA Session lifecycle hook. The SETUP / DRAFT / EXECUTE work
   // items carry `meta.sessionId` and `meta.sessionPhase` (set by the
-  // qa-sessions chain helpers — see engine/qa-sessions.js). On each agent
+  // qa-sessions chain helpers — see engine/qa/sessions.js). On each agent
   // exit we delegate to the matching handler, which validates the state
   // transition and queues the next phase WI when applicable. The qa-validate
   // qaRunId hook above (line 4340) already handles the qa-runs sidecar for
@@ -6925,7 +6973,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   const qaSessionPhase = meta?.sessionPhase || meta?.item?.meta?.sessionPhase;
   if (qaSessionId && qaSessionPhase && !lifecycleGateCanRetry) {
     try {
-      const qaSessions = require('./qa-sessions');
+      const qaSessions = require('../qa/sessions');
       const scope = resolveWorkItemScope(meta);
       const project = meta?.project?.name || meta?.item?.project || null;
       const failureReason = typeof resultSummary === 'string' && resultSummary
@@ -6944,14 +6992,31 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
         }
       } else if (qaSessionPhase === 'draft') {
         // The DRAFT agent reports the relative test file path in its
-        // structured completion as `testFile` (or the playbook can write a
-        // qa-session-draft-result.json sidecar in a future iteration). For
-        // now read it from structuredCompletion when present; the session
-        // record still works without it (EXECUTE prompt falls back to the
-        // generic test.<ext> hint).
+        // structured completion as `testFile`; the session record still works
+        // without it (EXECUTE prompt falls back to the generic test.<ext>
+        // hint).
         const testFile = structuredCompletion && typeof structuredCompletion.testFile === 'string'
           ? structuredCompletion.testFile
           : null;
+        // W-msb9kgs402813a97-b — the DRAFT visual-journey manifest rides its
+        // own single-use sidecar (agents/<id>/qa-session-draft-result.json),
+        // consumed here exactly once. Consumed on EVERY draft completion, not
+        // just successful ones, so a failed attempt cannot leave a manifest
+        // behind for the next dispatch of the same session to inherit.
+        const visualJourney = require('../qa/visual-journey');
+        let draftManifest = null;
+        try {
+          const consumed = visualJourney.consumeDraftResultSidecar(agentId || '_unknown', qaSessionId);
+          if (consumed.cleanupError) {
+            log('warn', `qa-session draft sidecar cleanup for ${qaSessionId}: ${consumed.cleanupError}`);
+          }
+          if (consumed.ok) draftManifest = consumed.manifest;
+          else if (consumed.reason !== 'missing') {
+            log('warn', `qa-session ${qaSessionId} draft sidecar ${consumed.reason} at ${consumed.filePath}`);
+          }
+        } catch (sidecarErr) {
+          log('warn', `qa-session draft sidecar read for ${qaSessionId}: ${sidecarErr.message}`);
+        }
         const session = qaSessions.getSession(qaSessionId);
         if (session && session.spec && session.spec.mode === 'auto' && effectiveSuccess) {
           // Auto-mode chains EXECUTE; we need a qa-runs record up-front. The
@@ -6960,9 +7025,9 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
           // the qa-runs record is created here on the auto path.
           let qaRunId = null;
           try {
-            const qaRuns = require('./qa-runs');
+            const qaRuns = require('../qa/runs');
             const run = qaRuns.createRun({
-              runbookId: 'qa-session-' + qaSessionId,
+              runbookId: qaSessions.sessionOwnedRunbookId(qaSessionId),
               targetName: session.managedSpawnName,
               project: project || session.spec.project || null,
             });
@@ -6970,31 +7035,55 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
           } catch (createErr) {
             log('warn', `qa-session auto-mode createRun failed for ${qaSessionId}: ${createErr.message}`);
           }
-          qaSessions.handleDraftComplete(qaSessionId, {
+          const draftOutcome = qaSessions.handleDraftComplete(qaSessionId, {
             success: true,
             testFile,
+            manifest: draftManifest,
             scope,
             project,
             qaRunId,
             reason: failureReason,
           });
+          // The visual-journey gate can refuse a draft AFTER the qa-run above
+          // was created. EXECUTE never runs, so terminalize the record here
+          // instead of leaving it pending forever.
+          if (qaRunId && draftOutcome && draftOutcome.nextState === qaSessions.QA_SESSION_STATE.FAILED) {
+            try {
+              require('../qa/runs').completeRun(qaRunId, {
+                status: 'errored',
+                summary: (qaSessions.getSession(qaSessionId) || {}).error
+                  || 'QA Session DRAFT rejected before EXECUTE',
+                artifacts: [],
+              });
+            } catch (runErr) {
+              log('warn', `qa-session ${qaSessionId} could not terminalize orphaned run ${qaRunId}: ${runErr.message}`);
+            }
+          }
         } else {
           qaSessions.handleDraftComplete(qaSessionId, {
             success: !!effectiveSuccess,
             testFile,
+            manifest: draftManifest,
             reason: failureReason,
           });
         }
       } else if (qaSessionPhase === 'execute') {
         // The qaRunId block above (line 4340) already wrote the terminal
-        // qa-runs record. Re-read it to drive the session state.
+        // qa-runs record. Re-read it to drive the session state — and hand
+        // the record itself to the session layer so the W-msb9kgs402813a97-c
+        // evidence gate reads the same artifacts/journeyCoverage rather than
+        // re-querying.
         let qaRunStatus = null;
+        let qaRunRecord = null;
         const linkedQaRunId = meta?.qaRunId || meta?.item?.meta?.qaRunId;
         if (linkedQaRunId) {
           try {
-            const qaRuns = require('./qa-runs');
+            const qaRuns = require('../qa/runs');
             const run = qaRuns.getRun(linkedQaRunId);
-            if (run && run.status) qaRunStatus = run.status;
+            if (run) {
+              qaRunRecord = run;
+              if (run.status) qaRunStatus = run.status;
+            }
           } catch (readErr) {
             log('warn', `qa-session execute qa-run lookup failed for ${qaSessionId}: ${readErr.message}`);
           }
@@ -7002,6 +7091,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
         qaSessions.handleExecuteComplete(qaSessionId, {
           success: !!effectiveSuccess,
           qaRunStatus,
+          qaRun: qaRunRecord,
           summary: resultSummary || null,
           reason: failureReason,
         });
@@ -7014,6 +7104,24 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // Plan chaining removed — user must explicitly execute plan-to-prd after reviewing the plan
   if (effectiveSuccess && meta?.item?.sourcePlan) checkPlanCompletion(meta, config);
 
+  // W-msal3ser01q4ccb3 — auto-QA for successfully verified PRDs (opt-in via
+  // engine.autoQaCompletedPrds, default off). Deliberately hooked on a
+  // SUCCESSFUL verify work item rather than on the PRD's `status: completed`
+  // flip: checkPlanCompletion above sets that status BEFORE verification runs,
+  // so triggering there would race the verify agent and miss the canonical
+  // prd/guides/verify-<plan>.md the QA spec builder prefers. `skipDoneStatus`
+  // is honoured because the verify-missing-PR guard flips the WI to `failed`
+  // without clearing effectiveSuccess. Everything else — guide presence,
+  // cross-repo fan-in, durable dedupe — is re-derived from persisted state
+  // inside the hook so a restart or duplicate callback cannot double-launch.
+  if (effectiveSuccess && !skipDoneStatus && type === WORK_TYPE.VERIFY && meta?.item?.sourcePlan) {
+    try {
+      require('../qa/auto-prd-qa').maybeAutoQaAfterVerify(meta.item, config);
+    } catch (err) {
+      log('warn', `auto-qa after verify: ${err.message}`);
+    }
+  }
+
   // Archive is manual — user archives plans from the dashboard when ready
 
   // Scheduled task back-reference: update SQL state and write a linked inbox note.
@@ -7023,7 +7131,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       const itemId = meta.item.id;
       shared.mutateScheduleRuns((runs) => {
         // P-c549d07e — preserve existing fields (esp. recentWorkItemIds ring
-        // populated at dispatch time by engine/scheduler.writeScheduleRunEntry).
+        // populated at dispatch time by engine/orchestration/scheduler.writeScheduleRunEntry).
         // The literal-object replacement that lived here previously silently
         // clobbered the ring on every successful completion.
         const existing = typeof runs[scheduleId] === 'object' && runs[scheduleId] ? runs[scheduleId] : {};
@@ -7065,7 +7173,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // returns, and their workdir validator checks `<cwd>` on disk. If the
   // worktree is deleted here first, every sidecar pointing at the worktree
   // fails with a bogus `invalid-workdir: directory does not exist`
-  // rejection. The cleanup sweep (engine/cleanup.js) reaps the worktree
+  // rejection. The cleanup sweep (engine/orchestration/cleanup.js) reaps the worktree
   // afterwards: when acceptance fails, the >2h age sweep picks it up; when
   // acceptance succeeds, the managed-spawn cwd anchor in cleanup.js keeps
   // the worktree alive while the engine-owned services run inside it.
@@ -7152,7 +7260,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     // reviewer slot can't sit at -5 indefinitely. Idempotent via the PR-target
     // dedup in addToDispatch; agent assignment is a soft preference (review-
     // skilled agents first, then any idle agent) — NEVER block on a specific
-    // reviewer. See engine/ado.js:resetReviewerNegativeVote for the verdict-
+    // reviewer. See engine/ado/index.js:resetReviewerNegativeVote for the verdict-
     // flip reset that fires on the resulting APPROVE.
     try {
       dispatchReReviewForFix(dispatchItem, meta, config, { agentId, resultSummary });
@@ -7236,7 +7344,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
 function handleQaSessionSetupCompletion(meta, opts = {}) {
   const qaSessionId = meta?.sessionId || meta?.item?.meta?.sessionId;
   if (!qaSessionId) return null;
-  const qaSessions = require('./qa-sessions');
+  const qaSessions = require('../qa/sessions');
   const scope = opts.scope || resolveWorkItemScope(meta);
   const project = opts.project !== undefined
     ? opts.project
@@ -7259,7 +7367,7 @@ function handleQaSessionSetupCompletion(meta, opts = {}) {
 // (e.g., manually raised PRs, cross-plan PRs, or PRs created while engine was paused).
 function syncPrdFromPrs(config) {
   try {
-    const { reconcileItemsWithPrs } = require('../engine');
+    const { reconcileItemsWithPrs } = require('../../engine');
     config = config || queries.getConfig();
     const allProjects = shared.getProjects(config);
 
@@ -7325,7 +7433,7 @@ function syncPrdFromPrs(config) {
 // Paused, rejected, awaiting-approval, completed, and archived PRDs are
 // skipped via _PRD_FROZEN_STATUSES. The locked write is idempotent.
 function advancePrdStatusOnAllItemsDone(config) {
-  const prdFiles = require('./prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
+  const prdFiles = require('../planning/prd-store').listPrdRows().filter(row => !row.archived).map(row => row.filename);
   if (!prdFiles.length) return;
 
   const allWorkItems = queries.getWorkItems(config);
@@ -7393,7 +7501,7 @@ function advancePrdStatusOnAllItemsDone(config) {
 //
 // This runs per-tick (right after syncPrdFromPrs). It reads the NORMALIZED
 // shared PR schema, so a single sweep covers both GitHub and ADO
-// pollers at once (engine/github.js + engine/ado.js are intentional mirrors
+// pollers at once (engine/providers/github.js + engine/ado/index.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
 // it re-stamps every tick, the persisted copy is KEPT CURRENT through the
@@ -7673,7 +7781,7 @@ function pruneScopeMismatchDuplicatePrs(config) {
   }
 
   // Index all PRs by repository-scoped identity across all projects.
-  const store = require('./pull-requests-store');
+  const store = require('../persistence/pull-requests-store');
   const allPrs = store.readAllPullRequests() || [];
   const byId = new Map();
   for (const pr of allPrs) {
@@ -8097,7 +8205,7 @@ module.exports = {
   // exercise both paths directly.
   recordWorktreeHeldPause,
   clearWorktreeHeldPause,
-  // W-mpx44p05000ze8d8 — exported so engine/ado.js + engine/github.js can
+  // W-mpx44p05000ze8d8 — exported so engine/ado/index.js + engine/providers/github.js can
   // drop stale `_noOpFixes` records during their PR status poll, and so
   // unit tests can exercise the sweep helper directly.
   sweepStalePrNoOpFixes,