@dev-loops/core 0.5.0 → 0.7.1

package/src/loop/queue-driver.mjs

@@ -9,6 +9,7 @@ import {
   transitionEntry,
   snapshotEntry,
   nextReadyEntry,
+  findEntry,
   allDone,
   RECOVERABLE_FAILURES,
   appendBugIssue,
@@ -19,7 +20,13 @@ import {
   boardColumnForLoopState,
   loadStateColumnMap,
 } from "./queue-board-sync.mjs";
-import { resolveNextUpOrder } from "./queue-board-ordering.mjs";
+import {
+  resolveNextUpOrder,
+  REASON_NEXT_UP_EMPTY,
+  REASON_BOARD_QUERY_ERROR,
+  REASON_NEXT_UP_TARGET_MISSING_LOCALLY,
+  EMPTY_NEXT_UP_MESSAGE,
+} from "./queue-board-ordering.mjs";
 
 export const DEFAULT_QUEUE_DRIVER_OPTIONS = {
   mergeAuthorized: false,
@@ -92,23 +99,88 @@ export async function runQueue(repoRoot, repo, options = {}) {
   // (e.g. a configured "Ready for Review") still syncs. (#793 round-1 #1)
   const lastSyncedColumn = new Map();
 
-  // Optional board-aware ordering: fetch Next Up order before processing.
-  // Fail-open: if the board is unreachable, orderHint stays empty and the
-  // driver falls back to the existing queue order.
-  const ordering = opts.useBoardOrdering !== false && !allDone(queue)
+  // Next Up is the NORMATIVE, fail-closed pickup source (#1091). When a board is
+  // configured, the driver picks ONLY entries whose target is in Next Up, by
+  // POSITION ascending; entries absent from Next Up are never auto-picked. It
+  // NEVER falls back to Backlog or to the non-board local queue order.
+  //
+  // Single-issue/PR runs do not reach this gating at all — they run via the
+  // dev-loop routing path, not the queue driver — so an explicit --issue/--pr
+  // target is inherently unaffected by Next Up.
+  const ordering = !allDone(queue)
     ? await resolveNextUpOrder(repo, repoRoot, opts.env ?? process.env, opts.queueBoardSyncDependencies ?? {})
-    : { ok: true, order: [], reason: "board ordering disabled or queue idle" };
-  const orderHint = ordering.ok ? ordering.order : [];
+    : { ok: true, configured: false, order: [], reason: "queue idle" };
+
+  // (b) Board-query ERROR → surface it and stop. Do NOT fall back to Backlog
+  // or local order (fail-closed). Distinct from an empty Next Up below.
+  if (ordering.ok === false) {
+    return {
+      ok: false,
+      stopped: true,
+      reason: REASON_BOARD_QUERY_ERROR,
+      message: `Next Up query failed (${ordering.reason}); refusing to fall back to Backlog/local order`,
+      error: ordering.reason ?? "board query failed",
+      results: [],
+      queue,
+      ordering,
+    };
+  }
+
+  // Board-gated only when a board is configured.
+  const boardGated = ordering.configured === true;
+  const orderHint = ordering.order;
+  const allowedTargets = boardGated ? new Set(orderHint) : null;
+
+  // (a) Empty Next Up (successful query, zero items) → fail CLOSED: idle/stop
+  // with an actionable, machine-readable outcome. Never pull from Backlog.
+  if (boardGated && orderHint.length === 0) {
+    return {
+      ok: true,
+      idle: true,
+      reason: REASON_NEXT_UP_EMPTY,
+      message: EMPTY_NEXT_UP_MESSAGE,
+      results: [],
+      queue,
+      ordering,
+    };
+  }
+
+  // (a2) Next Up resolved one or more targets that have NO matching local queue
+  // entry (membership reconcile not run/persisted, or the board changed between
+  // reconcile and this query). Filtering them out would return a silent empty
+  // idle while real Next Up work goes undispatched — so fail CLOSED with an
+  // actionable stop instead. Distinct from the genuine empty-Next-Up idle above.
+  // Never pull from Backlog. (#1091)
+  if (boardGated) {
+    const missingTargets = orderHint.filter((t) => !findEntry(queue, t));
+    if (missingTargets.length > 0) {
+      return {
+        ok: false,
+        stopped: true,
+        reason: REASON_NEXT_UP_TARGET_MISSING_LOCALLY,
+        missingTargets,
+        message:
+          "Next Up contains items with no local queue entry — run membership reconcile / re-add them",
+        results: [],
+        queue,
+        ordering,
+      };
+    }
+  }
 
   let autoFiledCount = 0;
   const results = [];
   let incomplete = false;
 
   while (!allDone(queue)) {
-    const entry = nextReadyEntry(queue, opts.reDispatchMaxRetries, orderHint);
+    const entry = nextReadyEntry(queue, opts.reDispatchMaxRetries, orderHint, allowedTargets);
     if (!entry) {
+      // When board-gated, entries absent from Next Up are intentionally NOT
+      // picked (and are not "blocked by deps") — only unfinished Next Up members
+      // count toward an incomplete verdict.
       const remaining = queue.entries.filter(
         (e) => e.status !== "done" && e.status !== "blocked" && e.status !== "failed"
+             && (!allowedTargets || allowedTargets.has(e.target))
       );
       if (remaining.length > 0) {
         incomplete = true;

package/src/loop/queue-state.mjs

@@ -183,9 +183,20 @@ function applyOrderHint(ordered, orderHint) {
   return [...inHint, ...rest];
 }
 
-export function nextReadyEntry(queue, maxRetries = 1, orderHint = []) {
+/**
+ * Pick the next ready entry.
+ *
+ * @param {object} queue
+ * @param {number} maxRetries
+ * @param {number[]} orderHint - preferred order (targets sorted to the front).
+ * @param {Set<number>|null} allowedTargets - when non-null, ONLY entries whose
+ *   target is in this set are eligible. Used for board-gated (Next Up)
+ *   selection (#1091): entries absent from Next Up are never auto-picked.
+ */
+export function nextReadyEntry(queue, maxRetries = 1, orderHint = [], allowedTargets = null) {
   const ordered = topologicalOrder(queue.entries);
-  const sorted = applyOrderHint(ordered, orderHint);
+  const restricted = allowedTargets ? ordered.filter((e) => allowedTargets.has(e.target)) : ordered;
+  const sorted = applyOrderHint(restricted, orderHint);
   for (const entry of sorted) {
     if (entry.status === "queued" && entryDependenciesSatisfied(queue, entry)) {
       return entry;

package/src/loop/run-context.mjs

@@ -4,8 +4,14 @@
  * The dev-loop async path keys off the harness-neutral `DEVLOOPS_RUN_ID` env var to
  * identify an inspectable per-subagent run (runner ownership, async-start enforcement,
  * human-comment gating), and provides a mint-and-propagate path for harnesses (e.g. Claude
- * Code) that inject no native per-subagent run id. The harness sets `DEVLOOPS_RUN_ID` when
- * dispatching an async subagent.
+ * Code) that inject no native per-subagent run id. For those harnesses dev-loops itself mints
+ * and sets `DEVLOOPS_RUN_ID` when dispatching an async subagent.
+ *
+ * Other harnesses may already inject their own run-id var: the Pi runtime injects
+ * `PI_SUBAGENT_RUN_ID` (not `DEVLOOPS_RUN_ID`) into each async subagent's child env, so that
+ * name is honored as a recognized run-id alias (precedence after the neutral primary). It is
+ * an externally-injected Pi-runtime contract var, not a dev-loops-owned var — dev-loops still
+ * mints/propagates only the neutral `DEVLOOPS_RUN_ID`.
  *
  * This module is pure except for the explicit file/IO helpers (writeRunContext/readRunContext),
  * which take an injectable `fs` and `root` for testability.
@@ -17,9 +23,10 @@ import path from "node:path";
 
 /**
  * Env var names that carry the async-context run id, in resolution precedence order.
- * The neutral `DEVLOOPS_RUN_ID` is the sole marker.
+ * The neutral `DEVLOOPS_RUN_ID` is primary; `PI_SUBAGENT_RUN_ID` is the alias the Pi
+ * runtime injects into async-subagent child envs (the only run-id marker present under Pi).
  */
-export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID"]);
+export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID", "PI_SUBAGENT_RUN_ID"]);
 
 /** Neutral env var name used when minting/propagating a run id. */
 export const NEUTRAL_RUN_ID_VAR = "DEVLOOPS_RUN_ID";

package/src/loop/ui-e2e-scoping.mjs

@@ -0,0 +1,162 @@
+// UI e2e auto-scoping (issue #976).
+//
+// Deterministic, path-triggered criterion: a PR that adds or modifies a
+// *rendered* HTML artifact (a presentation deck, an article page, or the
+// inspect-run viewer's served page/component) MUST run the shared UI e2e
+// assertions (mobile + desktop) AND have that artifact registered in the e2e
+// suite (DECK_REGISTRY / ARTICLE_REGISTRY / VIEWER_REGISTRY). Inclusion is
+// triggered by the changed-file set, never by a human annotating the PR.
+//
+// This module is the testable core of that criterion: classify changed paths
+// → rendered-artifact set → check each is registered → fail closed if a
+// rendered artifact changed with no registered/passing coverage.
+
+// Explicit path globs for rendered artifacts. Kept conservative and explicit
+// (issue #976 scope discipline): only artifacts that render to a page/component.
+export const RENDERED_ARTIFACT_GLOBS = Object.freeze([
+  "docs/articles/*.html",
+  "docs/presentations/*.html",
+]);
+
+// The inspect-run viewer is served from a component, not a static .html file,
+// so its trigger is the served-page source (matches the existing
+// inspect-run-viewer-ci-changes.mjs trigger seam).
+export const VIEWER_SOURCE_PATHS = Object.freeze([
+  "scripts/loop/inspect-run-viewer.mjs",
+]);
+
+// Registered artifacts — keyed by FULL repo-relative path (not basename), so
+// docs/articles/X.html and docs/presentations/X.html (which share basenames,
+// e.g. introducing-dev-loops.html) are DISTINCT and can never alias onto each
+// other. Mirrors the registries' actual on-disk locations:
+//   decks   → DECK_REGISTRY served from docs/presentations/<deck>
+//   articles→ ARTICLE_REGISTRY served from docs/articles/<file>
+// Note: kept as an explicit list here rather than importing the harness
+// (which pulls @playwright/test into core); the ui-e2e-scoping.test.mjs sync
+// test fails if a registry entry is added without updating this list, so it
+// can't silently drift.
+export const REGISTERED_ARTIFACT_PATHS = Object.freeze([
+  "docs/presentations/introducing-dev-loops.html",
+  "docs/presentations/dev-loops-deep-dive.html",
+  "docs/articles/introducing-dev-loops.html",
+  "docs/articles/dev-loops-deep-dive.html",
+]);
+
+export const VIEWER_ARTIFACT_ID = "inspect-run-viewer";
+
+// CI check names that constitute the shared UI e2e coverage. The detect layer
+// reads these from the statusCheckRollup to set uiE2ePassed. Note: a plain
+// name match against the rollup is enough; the gate only needs to know whether
+// the suite passed for this head. Each rendered-artifact family has a stable CI
+// job whose name appears here; an absent check is unknown → fails closed.
+export const UI_E2E_CHECK_NAMES = Object.freeze(["viewer-smoke", "deck-smoke", "article-smoke"]);
+
+function normalizePath(filePath) {
+  return String(filePath ?? "").trim().replace(/^\.\/+/u, "");
+}
+
+// Match a single explicit "dir/*.ext" glob (one path segment, no recursion).
+function matchesGlob(normalizedPath, glob) {
+  const [dir, file] = [glob.slice(0, glob.lastIndexOf("/")), glob.slice(glob.lastIndexOf("/") + 1)];
+  if (!file.startsWith("*.")) return normalizedPath === glob;
+  const ext = file.slice(1); // ".html"
+  if (!normalizedPath.startsWith(`${dir}/`)) return false;
+  const rest = normalizedPath.slice(dir.length + 1);
+  return rest.length > 0 && !rest.includes("/") && rest.endsWith(ext);
+}
+
+// Classify one changed path into a rendered-artifact descriptor, or null.
+// A descriptor carries the path, a stable `id` (the deck filename or the
+// viewer id) and whether that id is registered in the e2e suite.
+export function classifyRenderedArtifactPath(filePath) {
+  const normalized = normalizePath(filePath);
+  if (normalized.length === 0) return null;
+
+  if (VIEWER_SOURCE_PATHS.includes(normalized)) {
+    return { path: normalized, kind: "viewer", id: VIEWER_ARTIFACT_ID, registered: true };
+  }
+
+  for (const glob of RENDERED_ARTIFACT_GLOBS) {
+    if (matchesGlob(normalized, glob)) {
+      // Key registration on the FULL repo-relative path so an article and a
+      // deck that share a basename are distinct artifacts. id is the full path
+      // too, so the fail-closed reason names the exact file to register.
+      return {
+        path: normalized,
+        kind: normalized.startsWith("docs/articles/") ? "article" : "deck",
+        id: normalized,
+        registered: REGISTERED_ARTIFACT_PATHS.includes(normalized),
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Deterministic UI e2e scoping check.
+ *
+ * @param {string[]} changedPaths - PR changed-file paths.
+ * @param {{ uiE2ePassed?: boolean|null }} [coverage]
+ *   uiE2ePassed: whether the shared UI e2e suite passed for this head.
+ *   null/undefined means "not run / unknown" → fails closed.
+ * @returns {{
+ *   required: boolean,
+ *   artifacts: Array<{path,kind,id,registered}>,
+ *   unregistered: string[],
+ *   satisfied: boolean,
+ *   reason: string|null,
+ * }}
+ */
+export function evaluateUiE2eScoping(changedPaths = [], { uiE2ePassed = null } = {}) {
+  const artifacts = [];
+  const seen = new Set();
+  for (const p of Array.isArray(changedPaths) ? changedPaths : []) {
+    const descriptor = classifyRenderedArtifactPath(p);
+    if (descriptor && !seen.has(descriptor.path)) {
+      seen.add(descriptor.path);
+      artifacts.push(descriptor);
+    }
+  }
+
+  const required = artifacts.length > 0;
+  if (!required) {
+    return { required: false, artifacts, unregistered: [], satisfied: true, reason: null };
+  }
+
+  // Fail closed: any touched rendered artifact that is not registered blocks
+  // and names itself so the fix is unambiguous (register it in the suite).
+  const unregistered = artifacts.filter((a) => !a.registered).map((a) => a.id);
+  if (unregistered.length > 0) {
+    return {
+      required: true,
+      artifacts,
+      unregistered,
+      satisfied: false,
+      reason:
+        `UI e2e coverage is required: this PR changes rendered artifact(s) ` +
+        `${unregistered.join(", ")} that are not registered in the shared UI e2e suite ` +
+        `(DECK_REGISTRY or ARTICLE_REGISTRY in test/playwright/harness/deck-fit-harness.mjs, ` +
+        `or VIEWER_REGISTRY in test/playwright/harness/inspect-run-viewer-harness.mjs). ` +
+        `Register the artifact and add a spec that runs ` +
+        `the mobile + desktop assertions before this gate can pass.`,
+    };
+  }
+
+  // All touched artifacts are registered — coverage must have actually passed.
+  if (uiE2ePassed !== true) {
+    const touched = artifacts.map((a) => a.id).join(", ");
+    return {
+      required: true,
+      artifacts,
+      unregistered: [],
+      satisfied: false,
+      reason:
+        `UI e2e coverage is required: this PR changes rendered artifact(s) ${touched}, ` +
+        `but the shared UI e2e suite (mobile + desktop) has not passed for this head ` +
+        `(uiE2ePassed=${String(uiE2ePassed)}). Run the UI/mobile e2e loop and let it pass ` +
+        `before this gate can proceed.`,
+    };
+  }
+
+  return { required: true, artifacts, unregistered: [], satisfied: true, reason: null };
+}

package/bin/capture-deep-persona-signals.mjs

@@ -1,143 +0,0 @@
-#!/usr/bin/env node
-import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { parseReviewThreads, readInput, parseJsonText, formatCliError } from "../src/github/review-threads.mjs";
-import { extractDeepPersonaSignals } from "../src/debt/deep-persona-signals.mjs";
-
-export const USAGE = [
-  "Usage: capture-deep-persona-signals.mjs --input <path> --pr-number <n> --pr-url <url> [--output-dir <path>]",
-  "",
-  "Arguments:",
-  "  --input <path>        Path to normalized review-thread JSON (required)",
-  "  --pr-number <n>       PR number for metadata (required)",
-  "  --pr-url <url>        PR URL for metadata (required)",
-  "  --output-dir <path>   Output directory for emitted artifact (default: .pi/debt/signals/)",
-].join("\n");
-
-/**
- * Parse CLI arguments for the capture-deep-persona-signals CLI.
- *
- * @param {string[]} argv - Argument list (e.g. process.argv.slice(2))
- * @returns {{ inputPath: string, prNumber: string, prUrl: string, outputDir: string }}
- */
-export function parseArgs(argv) {
-  const args = [...argv];
-  const options = {
-    inputPath: undefined,
-    prNumber: undefined,
-    prUrl: undefined,
-    outputDir: ".pi/debt/signals",
-  };
-
-  while (args.length > 0) {
-    const token = args.shift();
-
-    switch (token) {
-      case "--input": {
-        const value = args.shift();
-        if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-          throw Object.assign(new Error("Missing value for --input"), { usage: USAGE });
-        }
-        options.inputPath = value;
-        break;
-      }
-      case "--pr-number": {
-        const value = args.shift();
-        if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-          throw Object.assign(new Error("Missing value for --pr-number"), { usage: USAGE });
-        }
-        if (!/^\d+$/.test(value)) {
-          throw Object.assign(new Error(`--pr-number must be a positive integer, got: ${value}`), { usage: USAGE });
-        }
-        options.prNumber = value;
-        break;
-      }
-      case "--pr-url": {
-        const value = args.shift();
-        if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-          throw Object.assign(new Error("Missing value for --pr-url"), { usage: USAGE });
-        }
-        options.prUrl = value;
-        break;
-      }
-      case "--output-dir": {
-        const value = args.shift();
-        if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-          throw Object.assign(new Error("Missing value for --output-dir"), { usage: USAGE });
-        }
-        options.outputDir = value;
-        break;
-      }
-      default:
-        throw Object.assign(new Error(`Unknown argument: ${token}`), { usage: USAGE });
-    }
-  }
-
-  if (!options.inputPath) {
-    throw Object.assign(new Error("--input is required"), { usage: USAGE });
-  }
-  if (!options.prNumber) {
-    throw Object.assign(new Error("--pr-number is required"), { usage: USAGE });
-  }
-  if (!options.prUrl) {
-    throw Object.assign(new Error("--pr-url is required"), { usage: USAGE });
-  }
-
-  return /** @type {{ inputPath: string, prNumber: string, prUrl: string, outputDir: string }} */ (options);
-}
-
-/**
- * Generate the output filename.
- * @param {string} prNumber
- * @returns {string}
- */
-export function outputFilename(prNumber) {
-  const ts = new Date().toISOString().replace(/[:.]/g, "-");
-  return `deep-persona-signals-${prNumber}-${ts}.json`;
-}
-
-export async function run(argv = process.argv.slice(2)) {
-  const options = parseArgs(argv);
-
-  // Read and parse the review-thread input
-  const rawText = await readInput({ inputPath: options.inputPath });
-  const parsed = parseReviewThreads(parseJsonText(rawText));
-
-  // Extract deep-persona signals
-  const signals = extractDeepPersonaSignals(parsed, {
-    prNumber: options.prNumber,
-    prUrl: options.prUrl,
-  });
-
-  // Build artifact envelope
-  const artifact = {
-    version: 1,
-    generatedAt: new Date().toISOString(),
-    prNumber: Number(options.prNumber),
-    prUrl: options.prUrl,
-    source: "pr_review_deep_persona",
-    signalCount: signals.length,
-    signals,
-  };
-
-  // Write to output directory
-  const outDir = resolve(options.outputDir);
-  await mkdir(outDir, { recursive: true });
-  const outPath = join(outDir, outputFilename(options.prNumber));
-  await writeFile(outPath, JSON.stringify(artifact, null, 2) + "\n", "utf8");
-
-  process.stdout.write(JSON.stringify({ ok: true, outputPath: outPath, signalCount: signals.length }) + "\n");
-}
-
-// Only auto-run when executed directly (not imported)
-const scriptPath = fileURLToPath(import.meta.url);
-if (process.argv[1] === scriptPath) {
-  run().catch((error) => {
-    if (error.usage) {
-      process.stderr.write(error.usage + "\n\n");
-    }
-    process.stderr.write(formatCliError(error) + "\n");
-    process.exitCode = 1;
-  });
-}