@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{pr-fix-target.js → providers/pr-fix-target.js}

@@ -1,5 +1,5 @@
 /**
- * engine/pr-fix-target.js — Execution-target choice surface for projectless PR
+ * engine/providers/pr-fix-target.js — Execution-target choice surface for projectless PR
  * fixes ("never clone silently").
  *
  * Plan: projectless-pr-actions, Phase 2, item P-ppa10005. This module is the
@@ -7,13 +7,13 @@
  * unconfigured repo until the user explicitly picks an execution target. It does
  * NOT execute anything — the executors land in:
  *   - temp-clone   → P-ppa10006 (ephemeral clone, fix, push, discard) [DEFAULT]
- *                    — IMPLEMENTED in engine/pr-temp-clone.js
+ *                    — IMPLEMENTED in engine/providers/pr-temp-clone.js
  *   - clone-keep   → P-ppa10007 (auto-clone + persistent project registration)
- *                    — IMPLEMENTED in engine/pr-clone-keep.js
+ *                    — IMPLEMENTED in engine/providers/pr-clone-keep.js
  *   - remote-patch → P-ppa10008 (GitHub Contents API, trivial single-file, NO test run)
- *                    — IMPLEMENTED in engine/pr-remote-patch.js
+ *                    — IMPLEMENTED in engine/providers/pr-remote-patch.js
  *   - devbox       → P-ppa10011 (ephemeral clone+fix+push ON A DEVBOX, zero local
- *                    footprint) — IMPLEMENTED in engine/pr-devbox.js. Never default,
+ *                    footprint) — IMPLEMENTED in engine/providers/pr-devbox.js. Never default,
  *                    never auto-selected; explicit consent only.
  *
  * Load-bearing invariant (read before extending): "never clone silently". A fix
@@ -34,10 +34,10 @@
  *                            P-ppa10006/7/8 executors land).
  */
 
-const shared = require('./shared');
+const shared = require('../core/shared');
 const prResolve = require('./pr-resolve');
 const { PrActionError } = require('./pr-action');
-const prFixTargetStore = require('./pr-fix-target-store');
+const prFixTargetStore = require('../persistence/pr-fix-target-store');
 
 // ── Execution targets ─────────────────────────────────────────────────────────
 
@@ -126,9 +126,9 @@ function _routedRecord(plan, target, extra = {}) {
       module: desc.executorModule || null,
       validates: desc.validates,
       trivialOnly: desc.trivialOnly,
-      // temp-clone's executor landed in P-ppa10006 (engine/pr-temp-clone.js),
-      // clone-keep's in P-ppa10007 (engine/pr-clone-keep.js), and remote-patch's
-      // in P-ppa10008 (engine/pr-remote-patch.js). `implemented` reflects whether
+      // temp-clone's executor landed in P-ppa10006 (engine/providers/pr-temp-clone.js),
+      // clone-keep's in P-ppa10007 (engine/providers/pr-clone-keep.js), and remote-patch's
+      // in P-ppa10008 (engine/providers/pr-remote-patch.js). `implemented` reflects whether
       // a real executor backs the choice.
       implemented: !!desc.implemented,
     },
@@ -181,7 +181,7 @@ function findConfiguredProjectForRef(ref, config) {
 //
 // P-ppa10009: optionally remember the user's execution-target pick keyed by repo
 // scope so a repeat fix on the same repo doesn't re-prompt. Persisted SQL-first
-// via engine/pr-fix-target-store.js. Absence of a remembered choice still
+// via engine/persistence/pr-fix-target-store.js. Absence of a remembered choice still
 // prompts — the safe "never clone silently" default is preserved.
 
 /** The remembered execution-target id for a ref's repo scope, or null. */
@@ -338,8 +338,8 @@ function planPrFix(input = {}, opts = {}) {
  *
  * IMPORTANT: this still does NOT clone or spawn — selection only routes. The
  * returned `routed` record carries `executor.implemented` (true once a real
- * executor backs the choice: temp-clone → engine/pr-temp-clone.js; clone-keep →
- * engine/pr-clone-keep.js; remote-patch → engine/pr-remote-patch.js). The caller is
+ * executor backs the choice: temp-clone → engine/providers/pr-temp-clone.js; clone-keep →
+ * engine/providers/pr-clone-keep.js; remote-patch → engine/providers/pr-remote-patch.js). The caller is
  * responsible for invoking the executor; this surface never clones, keeping
  * "never clone silently" absolute.
  *

package/engine/{pr-remote-patch.js → providers/pr-remote-patch.js}

@@ -1,9 +1,9 @@
 /**
- * engine/pr-remote-patch.js — Remote patch fast path (the "no validation"
+ * engine/providers/pr-remote-patch.js — Remote patch fast path (the "no validation"
  * execution target for a projectless one-off PR fix).
  *
  * Plan: projectless-pr-actions, Phase 2, item P-ppa10008. The execution-target
- * choice surface (engine/pr-fix-target.js) routes `remote-patch` here once the
+ * choice surface (engine/providers/pr-fix-target.js) routes `remote-patch` here once the
  * user has EXPLICITLY picked it (the "never clone silently" invariant lives
  * upstream — by the time we run, the user has consented to a no-clone push).
  *
@@ -38,7 +38,7 @@
  *    repo; the defaults are real (shellSafeGh + fetchPrBranches).
  */
 
-const shared = require('./shared');
+const shared = require('../core/shared');
 const prResolve = require('./pr-resolve');
 const ghToken = require('./gh-token');
 const { PrActionError } = require('./pr-action');
@@ -136,7 +136,7 @@ function _normalizePatch(patch) {
  * branch, and normalize/validate the single-file patch. NOTHING is mutated here.
  *
  * `input` — `{ url }`, a normalized ref, or a routed plan from
- *   engine/pr-fix-target.js#resolvePrFixTarget.
+ *   engine/providers/pr-fix-target.js#resolvePrFixTarget.
  * `opts.patch` — REQUIRED single-file patch (see `_normalizePatch`).
  * `opts.fetchPrBranches` — override the branch fetch (test seam).
  * `opts.prUrl` — original user URL (preferred for surfacing).

package/engine/{pr-resolve.js → providers/pr-resolve.js}

@@ -1,5 +1,5 @@
 /**
- * engine/pr-resolve.js — Projectless PR reference resolver + diff/metadata fetcher.
+ * engine/providers/pr-resolve.js — Projectless PR reference resolver + diff/metadata fetcher.
  *
  * Plan: projectless-pr-actions, item P-ppa10001. Foundation for all projectless
  * PR actions (review / summarize / comment / triage with no configured project
@@ -14,20 +14,20 @@
  *     for that PR WITHOUT a configured project or clone, via `gh` (GitHub) and the
  *     ADO REST API (`_apis/git/...`).
  *
- * Token routing is per-slug through engine/gh-token.js#resolveTokenForSlug; for an
+ * Token routing is per-slug through engine/providers/gh-token.js#resolveTokenForSlug; for an
  * unknown GitHub slug (no mapping, no fleet default) it falls back across the
  * authed accounts configured in `engine.ghAccounts` rather than relying on the
  * active `gh auth` profile. It NEVER runs `gh auth switch`. ADO tokens come from
- * engine/ado-token.js (`az account get-access-token` / azureauth).
+ * engine/ado/token.js (`az account get-access-token` / azureauth).
  *
  * All shell-outs use argv form (shell:false) and slug/number are validated before
  * interpolation, so poisoned PR refs cannot inject shell metacharacters.
  */
 
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const ghToken = require('./gh-token');
-const adoToken = require('./ado-token');
+const adoToken = require('../ado/token');
 
 const { safeJson, MINIONS_DIR, log } = shared;
 
@@ -174,7 +174,7 @@ function normalizePrRef(input) {
  * Shared by the 6 PR-action executor modules (pr-clone-keep, pr-devbox,
  * pr-remote-patch, pr-temp-clone, pr-track, pr-fix-target), which previously
  * each defined a byte-identical copy of this function. `PrActionError` must be
- * passed in by the caller — pr-resolve.js does not import engine/pr-action.js
+ * passed in by the caller — pr-resolve.js does not import engine/providers/pr-action.js
  * (that would introduce a new cross-module dependency in that direction).
  */
 function resolvePrActionRef(input, PrActionError) {
@@ -412,7 +412,7 @@ function _stripRefsHeads(ref) {
 
 /**
  * Fetch the source/target branch names + a clone URL for a PR with NO configured
- * project and NO local clone. The temp-clone fix executor (engine/pr-temp-clone.js)
+ * project and NO local clone. The temp-clone fix executor (engine/providers/pr-temp-clone.js)
  * needs the PR's HEAD branch to clone + push the fix back to, plus the clone URL
  * (fork-aware on GitHub). Token routing mirrors `fetchPrPayload` (per-slug GH
  * tokens / ADO bearer); shell-outs are argv-form and validated.

package/engine/{pr-temp-clone.js → providers/pr-temp-clone.js}

@@ -1,10 +1,10 @@
 /**
- * engine/pr-temp-clone.js — Temp-clone fix executor (the DEFAULT execution target
+ * engine/providers/pr-temp-clone.js — Temp-clone fix executor (the DEFAULT execution target
  * for a projectless one-off PR fix).
  *
  * Plan: projectless-pr-actions, Phase 2, item P-ppa10006. This is the first
  * executor in the chain that actually MUTATES code. The execution-target choice
- * surface (engine/pr-fix-target.js) routes `temp-clone` here once the user has
+ * surface (engine/providers/pr-fix-target.js) routes `temp-clone` here once the user has
  * explicitly picked it (the "never clone silently" invariant lives upstream — by
  * the time we run, the user has chosen to clone).
  *
@@ -40,7 +40,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const shared = require('./shared');
+const shared = require('../core/shared');
 const prResolve = require('./pr-resolve');
 const ghToken = require('./gh-token');
 const { PrActionError } = require('./pr-action');
@@ -78,7 +78,7 @@ function _tmpRoot(opts = {}) {
  * and compute the ephemeral clone dir. NOTHING is created or cloned here.
  *
  * `input` — `{ url }`, a normalized ref, or a routed plan from
- *   engine/pr-fix-target.js#resolvePrFixTarget.
+ *   engine/providers/pr-fix-target.js#resolvePrFixTarget.
  * `opts.fetchPrBranches` — override the branch fetch (test seam).
  * `opts.prUrl` — original user URL (preferred for surfacing).
  * `opts.tmpRoot` — override the ephemeral-clone root.
@@ -129,7 +129,7 @@ async function _resolveToken(plan, opts = {}) {
     return resolve(plan.sourceRepoSlug || plan.ref.slug) || null;
   }
   if (plan.ref.host === 'ado') {
-    const acquire = opts._acquireAdoToken || require('./ado-token').acquireAdoToken;
+    const acquire = opts._acquireAdoToken || require('../ado/token').acquireAdoToken;
     const acquired = await acquire();
     return (acquired && acquired.token) || null;
   }

package/engine/{pr-track.js → providers/pr-track.js}

@@ -1,5 +1,5 @@
 /**
- * engine/pr-track.js — Promote a one-off PR to TRACKED auto-fix (enrollment
+ * engine/providers/pr-track.js — Promote a one-off PR to TRACKED auto-fix (enrollment
  * wiring).
  *
  * Plan: projectless-pr-actions, Phase 3, item P-ppa10010. The "Track for auto-fix"
@@ -8,14 +8,13 @@
  *   pollers → PR discovery → review / fix / re-review → auto-merge.
  *
  * There is NO new fix engine here — enrollment is "mostly wiring":
- *   1. The canonical auto-managed signal is a SINGLE field: `contextOnly:false`
- *      (`shared.isAutoManagedPrRecord` — engine/shared.js). Enrolling a PR means
- *      ensuring a tracked record exists with `contextOnly:false` so the existing
- *      PR-discovery auto-managed gate flips on.
+ *   1. Enrolling with `contextOnly:false` enables both per-PR automation
+ *      controls through the manual-link path, so the existing discovery gate
+ *      admits review and fix dispatches.
  *   2. If the PR's repo is NOT a configured project, ongoing auto-fix needs a
  *      PERSISTENT checkout, so promotion surfaces the SAME execution-target
- *      choice as a one-off fix (engine/pr-fix-target.js, P-ppa10005) but with
- *      "Clone & keep" (engine/pr-clone-keep.js, P-ppa10007 — the persistent
+ *      choice as a one-off fix (engine/providers/pr-fix-target.js, P-ppa10005) but with
+ *      "Clone & keep" (engine/providers/pr-clone-keep.js, P-ppa10007 — the persistent
  *      project executor) as the implied/default selection. NOTHING is cloned
  *      until the user picks.
  *   3. Once the repo is project-ready (already configured, or after Clone & keep
@@ -43,7 +42,7 @@ const prFixTarget = require('./pr-fix-target');
 const { PrActionError } = require('./pr-action');
 
 // For ongoing auto-fix the checkout must persist across ticks, so "Clone & keep"
-// (engine/pr-clone-keep.js, P-ppa10007) is the implied selection when promoting a
+// (engine/providers/pr-clone-keep.js, P-ppa10007) is the implied selection when promoting a
 // PR whose repo is not yet a configured project. temp-clone discards its clone
 // after one push, so it can never back ongoing tracking.
 const TRACK_RECOMMENDED_TARGET = 'clone-keep';
@@ -92,7 +91,7 @@ function buildPrTrackTargetPrompt(plan) {
  * point — it does NOT write anything.
  *
  * Delegates configured-project detection + the choice surface to
- * engine/pr-fix-target.js (so the "never clone silently" invariant + the
+ * engine/providers/pr-fix-target.js (so the "never clone silently" invariant + the
  * configured-vs-unconfigured logic live in exactly one place), then re-flavors
  * the unconfigured branch for ongoing tracking (Clone & keep recommended).
  *
@@ -151,10 +150,9 @@ function planPrTrack(input = {}, opts = {}) {
 }
 
 /**
- * Build the canonical enrollment signal for a PR (or plan/ref). Enrollment is a
- * single field: `contextOnly:false` — that is the ONE thing
- * `shared.isAutoManagedPrRecord` reads to decide a PR is auto-managed. The caller
- * feeds `{ url, contextOnly }` to the existing manual-link path
+ * Build the canonical enrollment signal for a PR (or plan/ref). The caller
+ * feeds `{ url, contextOnly:false }` to the existing manual-link path, which
+ * enables Auto Fix and Auto Review together
  * (dashboard.js#linkPullRequestForTracking), which creates the record if missing
  * and promotes an existing context-only record (upsert refuses to demote).
  *

package/engine/{shared-branch-pr-reconcile.js → providers/shared-branch-pr-reconcile.js}

@@ -23,10 +23,10 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const queries = require('./queries');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
 const github = require('./github');
-const ado = require('./ado');
+const ado = require('../ado');
 
 const { log } = shared;
 const PRD_DIR = queries.PRD_DIR;
@@ -143,7 +143,7 @@ async function _reconcilePrdForProject(plan, file, project, planIds) {
  * the sweep.
  */
 async function reconcileSharedBranchPrs(config) {
-  const planFiles = require('./prd-store').listPrdRows().filter(row => !row.archived);
+  const planFiles = require('../planning/prd-store').listPrdRows().filter(row => !row.archived);
 
   for (const { filename: file, plan } of planFiles) {
     try {

package/engine/qa/auto-prd-qa.js

@@ -0,0 +1,313 @@
+/**
+ * engine/qa/auto-prd-qa.js — automatic QA for successfully verified PRDs.
+ *
+ * W-msal3ser01q4ccb3. Opt-in via `engine.autoQaCompletedPrds` (default false).
+ * When ON, a PRD whose verification actually SUCCEEDED gets a PRD-driven QA
+ * Session automatically, through the exact same orchestration the manual
+ * `POST /api/qa/from-prd` bridge uses (engine/qa/prd-session.js).
+ *
+ * ── Why the trigger is verify-completion, not `status: completed` ───────────
+ * `checkPlanCompletion` flips the PRD to `completed` and only THEN creates the
+ * verify work item(s). Triggering on the status flip would therefore fire
+ * before verification has run and before the verify agent has written the
+ * canonical `prd/guides/verify-<plan>.md` — the guide the spec builder prefers
+ * as its flow source. So the trigger is: a verify work item completed, its
+ * guide exists on disk, and EVERY verify work item belonging to that plan is
+ * `done`.
+ *
+ * ── Idempotency ────────────────────────────────────────────────────────────
+ * The dedupe key is a "verify generation": a hash of the plan filename plus
+ * every verify WI's `id@completedAt`. It is durable (stamped on the PRD row in
+ * SQL via prd-store) so it survives ticks, engine restarts, lifecycle retries,
+ * and duplicate completion callbacks — an in-memory flag would not. A reopened
+ * PRD re-verified later produces DIFFERENT `completedAt` values, hence a new
+ * generation and a legitimately new QA session; the same generation always
+ * collapses to exactly one.
+ *
+ * The generation is CLAIMED inside the prd-store mutation before any session is
+ * created, and the claim is never released — a failed launch records its error
+ * and stops, so a broken QA path cannot become an unbounded auto-retry loop.
+ * PRD completion state is never touched: QA failure stays visible in QA state
+ * only.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const shared = require('../core/shared');
+const queries = require('../core/queries');
+const prdStore = require('../planning/prd-store');
+const qaFromPrd = require('./from-prd');
+const qaPrdSession = require('./prd-session');
+
+const { log, ts, WORK_TYPE, DONE_STATUSES } = shared;
+
+// Bounded per-PRD launch history. Keeps the dedupe durable across the handful
+// of generations a re-opened PRD can accumulate without growing the PRD row.
+const AUTO_QA_LAUNCH_HISTORY = 5;
+
+// Reasons returned when no session is launched. Stable strings so tests and
+// callers can assert on them instead of on log text.
+const SKIP_REASON = Object.freeze({
+  DISABLED: 'disabled',
+  NOT_VERIFY: 'not-verify-work-item',
+  NO_SOURCE_PLAN: 'no-source-plan',
+  UNSAFE_PLAN_FILE: 'unsafe-plan-filename',
+  PRD_NOT_FOUND: 'prd-not-found',
+  VERIFY_GUIDE_MISSING: 'verify-guide-missing',
+  NO_VERIFY_ITEMS: 'no-verify-work-items',
+  VERIFY_INCOMPLETE: 'verify-incomplete',
+  ALREADY_LAUNCHED: 'already-launched',
+  PRD_NOT_QA_READY: 'prd-not-qa-ready',
+});
+
+function _isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+function _planSlug(planFile) {
+  return String(planFile).replace(/\.json$/i, '');
+}
+
+function verifyGuidePath(planFile) {
+  return path.join(shared.MINIONS_DIR, 'prd', 'guides', `verify-${_planSlug(planFile)}.md`);
+}
+
+/**
+ * Has the verify agent persisted the canonical guide for this plan? Presence,
+ * not content, is the gate — the spec builder does its own emptiness check and
+ * falls back through manual-qa-<plan>.md → acceptance criteria, preserving the
+ * documented flow priority.
+ */
+function hasVerifyGuide(planFile) {
+  try { return fs.statSync(verifyGuidePath(planFile)).isFile(); }
+  catch { return false; }
+}
+
+/**
+ * Every verify work item that belongs to `planFile`, across all project scopes
+ * and central. Mirrors the lookup in lifecycle.js#checkPlanCompletion.
+ */
+function collectVerifyItems(planFile, config) {
+  const all = queries.getWorkItems(config);
+  if (!Array.isArray(all)) return [];
+  return all.filter(w => w
+    && w.sourcePlan === planFile
+    && (w.itemType === WORK_TYPE.VERIFY || w.type === WORK_TYPE.VERIFY));
+}
+
+/**
+ * Cross-repo fan-in gate. A plan fans verification out to one verify WI per
+ * touched project; QA covers the plan as a whole, so it must wait for ALL of
+ * them and launch ONCE — not once per verify completion.
+ *
+ * Anything that is not a DONE status blocks: a pending/dispatched sibling means
+ * the generation is still forming, and a failed/cancelled sibling means the
+ * verification did not succeed, so no QA runs at all.
+ */
+function verifyItemsAllSucceeded(items) {
+  if (!Array.isArray(items) || items.length === 0) return false;
+  return items.every(w => w && DONE_STATUSES.has(w.status));
+}
+
+/**
+ * Stable identity for one completion generation of a plan's verification.
+ * `completedAt` is what makes a re-verified PRD a new generation:
+ * shared.reopenWorkItem deletes it, and the next successful completion stamps a
+ * fresh timestamp.
+ */
+function computeVerifyGeneration(planFile, items) {
+  const parts = items
+    .map(w => `${w.id || ''}@${w.completedAt || ''}`)
+    .sort();
+  return crypto.createHash('sha256')
+    .update(`${planFile}\n${parts.join('\n')}`)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function _readLaunches(prd) {
+  const autoQa = prd && prd._autoQa && typeof prd._autoQa === 'object' && !Array.isArray(prd._autoQa)
+    ? prd._autoQa
+    : null;
+  return autoQa && Array.isArray(autoQa.launches) ? autoQa.launches : [];
+}
+
+/**
+ * Compare-and-set the generation claim under the prd-store transaction. Returns
+ * true only for the caller that actually inserted it, so concurrent verify
+ * completions (cross-repo fan-in landing in the same tick) and duplicate
+ * completion callbacks collapse to a single launch.
+ */
+function claimGeneration(planFile, generation) {
+  let claimed = false;
+  prdStore.mutatePrd(planFile, (data) => {
+    const launches = _readLaunches(data);
+    if (launches.some(l => l && l.generation === generation)) return data;
+    const next = launches.concat([{
+      generation,
+      status: 'claimed',
+      sessionId: null,
+      setupWorkItemId: null,
+      claimedAt: ts(),
+    }]);
+    data._autoQa = { launches: next.slice(-AUTO_QA_LAUNCH_HISTORY) };
+    claimed = true;
+    return data;
+  });
+  return claimed;
+}
+
+function recordLaunchOutcome(planFile, generation, patch) {
+  try {
+    prdStore.mutatePrd(planFile, (data) => {
+      const launches = _readLaunches(data);
+      const next = launches.map(l => (l && l.generation === generation ? { ...l, ...patch } : l));
+      data._autoQa = { launches: next.slice(-AUTO_QA_LAUNCH_HISTORY) };
+      return data;
+    });
+  } catch (e) {
+    log('warn', `auto-qa: recording launch outcome for ${planFile}/${generation} failed: ${e.message}`);
+  }
+}
+
+/**
+ * Post-verify hook. Called from lifecycle.js#runPostCompletionHooks after a
+ * work item completes successfully.
+ *
+ * Never throws: every failure degrades to `{ launched: false }` plus a warn, so
+ * an auto-QA problem can never regress the verify work item or the PRD.
+ *
+ * @param {object} item   the completed work item (meta.item)
+ * @param {object} config live engine config
+ * @returns {{ launched: boolean, reason?: string, generation?: string, sessionId?: string,
+ *             setupWorkItemId?: string|null, error?: string }}
+ */
+function maybeAutoQaAfterVerify(item, config) {
+  if (!shared.resolveAutoQaCompletedPrds(config && config.engine)) {
+    return { launched: false, reason: SKIP_REASON.DISABLED };
+  }
+  if (!item || (item.itemType !== WORK_TYPE.VERIFY && item.type !== WORK_TYPE.VERIFY)) {
+    return { launched: false, reason: SKIP_REASON.NOT_VERIFY };
+  }
+  const planFile = _isNonEmptyString(item.sourcePlan) ? item.sourcePlan.trim() : null;
+  if (!planFile) return { launched: false, reason: SKIP_REASON.NO_SOURCE_PLAN };
+  // The plan filename reaches path.join for the guide lookup and prd-store for
+  // the claim; reuse the builder's traversal guard rather than trusting it.
+  if (!qaFromPrd._isSafePrdFileName(planFile)) {
+    return { launched: false, reason: SKIP_REASON.UNSAFE_PLAN_FILE };
+  }
+
+  let prd = null;
+  try { prd = prdStore.readPrd(planFile); }
+  catch (e) {
+    log('warn', `auto-qa: reading PRD ${planFile} failed: ${e.message}`);
+    return { launched: false, reason: SKIP_REASON.PRD_NOT_FOUND };
+  }
+  if (!prd || typeof prd !== 'object') {
+    return { launched: false, reason: SKIP_REASON.PRD_NOT_FOUND };
+  }
+
+  // Gate on the canonical verify guide, not on the PRD status flip: the guide
+  // is the artifact that proves verification actually ran to completion.
+  if (!hasVerifyGuide(planFile)) {
+    return { launched: false, reason: SKIP_REASON.VERIFY_GUIDE_MISSING };
+  }
+
+  let verifyItems;
+  try { verifyItems = collectVerifyItems(planFile, config); }
+  catch (e) {
+    log('warn', `auto-qa: collecting verify work items for ${planFile} failed: ${e.message}`);
+    return { launched: false, reason: SKIP_REASON.NO_VERIFY_ITEMS };
+  }
+  if (verifyItems.length === 0) {
+    return { launched: false, reason: SKIP_REASON.NO_VERIFY_ITEMS };
+  }
+  if (!verifyItemsAllSucceeded(verifyItems)) {
+    return { launched: false, reason: SKIP_REASON.VERIFY_INCOMPLETE };
+  }
+
+  const generation = computeVerifyGeneration(planFile, verifyItems);
+
+  // Cheap pre-check outside the claim so the steady-state re-scan does no write.
+  if (_readLaunches(prd).some(l => l && l.generation === generation)) {
+    return { launched: false, reason: SKIP_REASON.ALREADY_LAUNCHED, generation };
+  }
+
+  let claimed = false;
+  try { claimed = claimGeneration(planFile, generation); }
+  catch (e) {
+    log('warn', `auto-qa: claiming generation ${generation} for ${planFile} failed: ${e.message}`);
+    return { launched: false, reason: SKIP_REASON.ALREADY_LAUNCHED, generation, error: e.message };
+  }
+  if (!claimed) {
+    return { launched: false, reason: SKIP_REASON.ALREADY_LAUNCHED, generation };
+  }
+
+  try {
+    const created = qaPrdSession.createQaSessionFromPrd(planFile, {
+      // `auto` runs SETUP → DRAFT → EXECUTE without waiting for approval; an
+      // automatic session has no operator standing by to approve the draft.
+      mode: 'auto',
+      createdBy: 'engine:auto-qa-verified-prd',
+      provenanceExtra: {
+        autoTrigger: {
+          reason: 'verified-prd',
+          generation,
+          verifyWorkItemIds: verifyItems.map(w => w.id).filter(Boolean).sort(),
+          triggeredBy: item.id || null,
+          at: ts(),
+        },
+      },
+      resolveTargets: (spec) => qaPrdSession.resolveTargetsFromConfig(spec, config),
+    });
+    recordLaunchOutcome(planFile, generation, {
+      status: 'launched',
+      sessionId: created.sessionId,
+      setupWorkItemId: created.setupWorkItemId || null,
+      launchedAt: ts(),
+    });
+    log('info', `auto-qa: launched QA session ${created.sessionId} for verified PRD ${planFile} `
+      + `(generation ${generation}, verify WIs: ${verifyItems.map(w => w.id).join(', ')})`);
+    return {
+      launched: true,
+      generation,
+      sessionId: created.sessionId,
+      setupWorkItemId: created.setupWorkItemId || null,
+    };
+  } catch (e) {
+    // The claim is intentionally NOT released: recording the error and stopping
+    // is what keeps a broken QA path from re-firing every tick. QA failure is
+    // visible in QA/PRD auto-qa state and never regresses PRD completion.
+    const reason = e && e.reason ? e.reason : e.message;
+    const isNotReady = qaFromPrd.isQaFromPrdError(e) && /not QA-ready/i.test(String(reason));
+    recordLaunchOutcome(planFile, generation, {
+      status: 'error',
+      error: String(reason).slice(0, 500),
+      sessionId: (e && e.sessionId) || null,
+      erroredAt: ts(),
+    });
+    log('warn', `auto-qa: QA session for verified PRD ${planFile} not created: ${reason}`);
+    return {
+      launched: false,
+      reason: isNotReady ? SKIP_REASON.PRD_NOT_QA_READY : 'launch-failed',
+      generation,
+      error: String(reason),
+    };
+  }
+}
+
+module.exports = {
+  maybeAutoQaAfterVerify,
+  // Exported for tests / callers that need the individual gates.
+  verifyGuidePath,
+  hasVerifyGuide,
+  collectVerifyItems,
+  verifyItemsAllSucceeded,
+  computeVerifyGeneration,
+  claimGeneration,
+  recordLaunchOutcome,
+  SKIP_REASON,
+  AUTO_QA_LAUNCH_HISTORY,
+};