@dev-loops/core 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -56,6 +56,7 @@
     "./loop/steering": "./src/loop/steering.mjs",
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
     "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",
+    "./loop/ui-e2e-scoping": "./src/loop/ui-e2e-scoping.mjs",
     "./refinement/ac-dod-matrix": "./src/refinement/ac-dod-matrix.mjs",
     "./harness": "./src/harness/index.mjs",
     "./loop/worktree-guard": "./src/loop/worktree-guard.mjs",

package/src/claude/asset-generation.mjs

@@ -169,6 +169,32 @@ export function transformAgent({ source, raw, version = "latest" }) {
   return `${lines.join("\n")}\n${body}`;
 }
 
+/**
+ * Transform a canonical `commands/<name>.command.md` into a Claude `.claude/commands/<name>.md`
+ * slash command (#972). Commands are thin wrappers over the public dev-loop contract: the body
+ * is a prompt (with `$ARGUMENTS`) that invokes the existing entrypoint, so there is NO routing
+ * logic here. Frontmatter keeps Claude's command fields (`description`, `argument-hint`); the body
+ * is passed through `stripPiOnlyBlocks` + `rewriteCliInvocation` like agents/skills.
+ * @param {{ source: string, raw: string, version?: string }} input
+ * @returns {string} Full generated file content.
+ */
+export function transformCommand({ source, raw, version = "latest" }) {
+  const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
+  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
+
+  const lines = ["---"];
+  if (frontmatter.description != null) {
+    lines.push(`description: ${JSON.stringify(String(frontmatter.description))}`);
+  }
+  if (frontmatter["argument-hint"] != null) {
+    lines.push(`argument-hint: ${JSON.stringify(String(frontmatter["argument-hint"]))}`);
+  }
+  lines.push("---");
+  lines.push(GENERATED_NOTE(source));
+  lines.push("");
+  return `${lines.join("\n")}\n${body}`;
+}
+
 /**
  * Transform a canonical `skills/<name>/SKILL.md` into a Claude `.claude/skills/<name>/SKILL.md`.
  * @param {{ source: string, raw: string, version?: string }} input

package/src/loop/async-start-contract.mjs

@@ -13,6 +13,7 @@
  * Async context marker (required when workflow.asyncStartMode is `required`)
  * — see `@dev-loops/core/loop/run-context`:
  * - DEVLOOPS_RUN_ID env var (neutral, harness-agnostic)
+ * - PI_SUBAGENT_RUN_ID env var (the alias the Pi runtime injects)
  *
  * Allowed modes:
  * - workflow.asyncStartMode: required | allowed
@@ -159,14 +160,20 @@ export function validateAsyncStartContext({
     };
   }
 
-  // No marker found — fail closed
+  // No marker found — fail closed.
+  // Derive the marker hint from ASYNC_CONTEXT_MARKERS (primary first, aliases after)
+  // so the message never drifts from the recognized-marker list.
+  const [primaryMarker, ...aliasMarkers] = ASYNC_CONTEXT_MARKERS;
+  const markerHint = aliasMarkers.length
+    ? `Set ${primaryMarker} (or the ${aliasMarkers.join("/")} alias) to proceed. `
+    : `Set ${primaryMarker} to proceed. `;
   return {
     status: ASYNC_START_STATUS.REJECTED,
     reason:
       "No async context detected. " +
       "The dev-loop must run within a visible async subagent session, " +
       "not as a detached local process. " +
-      `Set ${ASYNC_CONTEXT_MARKERS[0]} to proceed. ` +
+      markerHint +
       "Repository-maintained workflow policy controls any exceptions.",
     detectedMarker: null,
   };

package/src/loop/pr-gate-coordination.mjs

@@ -1,11 +1,13 @@
 import { DISPOSITION, STATE } from "./copilot-loop-state.mjs";
 import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
+import { evaluateUiE2eScoping } from "./ui-e2e-scoping.mjs";
 
 export const PR_CHECKPOINT = Object.freeze({
   DRAFT_REVIEW: "draft_review",
   POST_DRAFT_EXTERNAL_REVIEW: "post_draft_external_review",
   FEEDBACK_RESOLUTION: "feedback_resolution",
   CONFLICT_RESOLUTION: "conflict_resolution",
+  UI_E2E_SCOPING: "ui_e2e_scoping",
   PRE_APPROVAL_GATE_WINDOW: "pre_approval_gate_window",
   FINAL_APPROVAL_READY: "final_approval_ready",
   PRE_APPROVAL_GATE_NEEDED: "pre_approval_gate_needed",
@@ -48,6 +50,7 @@ export const PR_CHECKPOINT_ACTION = Object.freeze({
   RECONCILE_DRAFT_GATE: "reconcile_draft_gate",
   REPORT_BLOCKED: "report_blocked",
   REPORT_DONE: "report_done",
+  RUN_UI_E2E_SUITE: "run_ui_e2e_suite",
 });
 
 function normalizeGateComment(summary = null) {
@@ -687,6 +690,10 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const requireRetrospectiveInternalTooling = input.requireRetrospectiveInternalTooling === true;
   const retrospectiveCheckpoint = input.retrospectiveCheckpoint;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
+  // UI e2e auto-scoping (#976): the PR changed-file set + whether the shared UI
+  // e2e suite passed for this head. Inclusion is path-triggered, never annotated.
+  const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : [];
+  const uiE2ePassed = input.uiE2ePassed === true ? true : (input.uiE2ePassed === false ? false : null);
   const refinementArtifact = input.refinementArtifact && typeof input.refinementArtifact === "object"
     ? input.refinementArtifact
     : null;
@@ -836,6 +843,45 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
+  // UI e2e auto-scoping precondition (#976). Path-triggered + fail-closed:
+  // if the PR's changed files touch a rendered artifact (a deck under
+  // docs/articles|presentations, or the inspect-run viewer source), it MUST be
+  // registered in the shared UI e2e suite AND that suite must have passed for
+  // this head. A rendered-artifact change with no registered/passing coverage
+  // blocks here with a reason naming the artifact. Distinct seam from the
+  // mergeability (#980) and retrospective (#982) preconditions to minimize
+  // merge-time conflict. Non-UI changes pass through untouched (required=false).
+  const uiE2eScoping = evaluateUiE2eScoping(changedFiles, { uiE2ePassed });
+  if (uiE2eScoping.required && !uiE2eScoping.satisfied) {
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE]);
+    pushUnique(forbiddenActions, [
+      PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+      PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
+      PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+      PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+      PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+    ]);
+    return buildResult({
+      repo: input.repo ?? null,
+      pr: Number.isInteger(input.pr) ? input.pr : null,
+      currentHeadSha,
+      lifecycleState: effectiveLifecycleState,
+      loopDisposition: DISPOSITION.ACTION_REQUIRED,
+      gateBoundary: PR_CHECKPOINT.UI_E2E_SCOPING,
+      draftGateAlreadySatisfied,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE,
+      reason: uiE2eScoping.reason,
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      copilotReviewRoundCount,
+    });
+  }
+
   if (prDraft || effectiveLifecycleState === STATE.PR_DRAFT) {
     if (refinementArtifactStatus === REFINEMENT_ARTIFACT_STATUS.MISSING) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);

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 };
+}