@dev-loops/core 0.4.0 → 0.6.0

package/src/loop/spike-exit-contract.mjs

@@ -0,0 +1,138 @@
+/**
+ * Spike-mode exit (P2 of the spike-mode track #965).
+ *
+ * Phase 1 (#964) shipped the spike intake state machine
+ * (`evaluateSpikeIntakeState` → SPIKE_INTAKE_STATE). A spike becomes exitable
+ * only once it carries a Recommendation (`spike_ready_for_exit`). This module is
+ * the exit decision: from that ready state, the operator picks a disposition —
+ *   - DISCARD  — the recommendation is "don't pursue"; drop the spike with ZERO
+ *                tracker artifacts (the findings doc is the whole record).
+ *   - GRADUATE — promote the exploration into a #947-consumable plan file
+ *                (Status/Objective/In scope/Explicit non-goals) built from the
+ *                spike's Question/Approach/Findings/Recommendation, which then
+ *                enters the existing local-first plan→PR promotion path (#952).
+ *
+ * Pure: no fs/network/gh, no `scripts/` import (mirrors spike-intake-contract
+ * and plan-file-promote-contract). The CLI (`scripts/refine/exit-spike.mjs`)
+ * owns all I/O. Fail-closed on an unknown disposition or a non-ready state so
+ * the CLI makes zero mutation on those paths.
+ */
+
+import { SPIKE_INTAKE_STATE } from "./spike-intake-contract.mjs";
+
+/** Dispositions the operator can choose at a ready spike's exit. */
+export const SPIKE_EXIT_DISPOSITION = Object.freeze({
+  /** Drop the spike with no tracker artifact (recommendation: don't pursue). */
+  DISCARD: "discard",
+  /** Promote into a plan file consumable by the #947 local-first flow. */
+  GRADUATE: "graduate",
+});
+
+/** Actions the exit decision can return (1:1 with the eligible dispositions). */
+export const SPIKE_EXIT_ACTION = Object.freeze({
+  DISCARD: "discard",
+  GRADUATE: "graduate",
+});
+
+const DISPOSITION_TO_ACTION = Object.freeze({
+  [SPIKE_EXIT_DISPOSITION.DISCARD]: SPIKE_EXIT_ACTION.DISCARD,
+  [SPIKE_EXIT_DISPOSITION.GRADUATE]: SPIKE_EXIT_ACTION.GRADUATE,
+});
+
+/**
+ * Pure exit-eligibility decision.
+ *
+ * Eligible ONLY from `spike_ready_for_exit` (a Recommendation has been reached).
+ * Any other state — in-progress or ambiguous — fails closed with
+ * `not_ready_for_exit` and no action; the CLI must make zero tracker mutation.
+ * An unrecognized disposition fails closed with `unknown_disposition`.
+ *
+ * @param {object} facts
+ * @param {string} facts.spikeIntakeState  one of SPIKE_INTAKE_STATE values (from evaluateSpikeIntakeState)
+ * @param {string} facts.disposition  one of SPIKE_EXIT_DISPOSITION values
+ * @returns {{ ok: boolean, action?: string, reason?: string, spikeIntakeState?: string | null }}
+ */
+export function evaluateSpikeExit({ spikeIntakeState, disposition } = {}) {
+  // The ready gate: an exit decision is only meaningful once a recommendation
+  // exists. Fail closed otherwise — never guess an exit for an in-progress or
+  // malformed spike.
+  if (spikeIntakeState !== SPIKE_INTAKE_STATE.SPIKE_READY_FOR_EXIT) {
+    return { ok: false, reason: "not_ready_for_exit", spikeIntakeState: spikeIntakeState ?? null };
+  }
+
+  // Own-property check: a bare index lookup would also match inherited
+  // Object.prototype keys (`toString`, `__proto__`, `constructor`), letting an
+  // unknown disposition resolve to a truthy value and bypass the fail-closed
+  // contract. Require a string that is an own key of the map.
+  if (typeof disposition !== "string" || !Object.hasOwn(DISPOSITION_TO_ACTION, disposition)) {
+    return { ok: false, reason: "unknown_disposition", spikeIntakeState };
+  }
+  const action = DISPOSITION_TO_ACTION[disposition];
+
+  return { ok: true, action, spikeIntakeState };
+}
+
+/**
+ * Build a #947-consumable plan-file body from a ready spike's sections.
+ *
+ * The emitted body carries the four base authoring sections the plan-file
+ * format requires (Status / Objective / In scope / Explicit non-goals — see
+ * scripts/refine/validate-plan-file.mjs), so it passes `validatePlanFile` and
+ * enters the existing local-first plan→PR promotion path (#952) unchanged.
+ *
+ * The spike sections map onto the plan as: the Question + Approach become the
+ * Objective's context, the Recommendation becomes the In-scope work, the
+ * Findings record the evidence, and a fixed non-goal keeps the plan from
+ * re-opening the (now-concluded) exploration. Status starts as Draft.
+ *
+ * Idempotent and pure: same input → identical output, no side effects. Fails
+ * closed (throws) on an empty required section so a graduate exit cannot emit a
+ * plan that the validator would reject.
+ *
+ * @param {object} sections
+ * @param {string} sections.question
+ * @param {string} sections.approach
+ * @param {string} sections.findings
+ * @param {string} sections.recommendation
+ * @returns {string} markdown plan-file body
+ */
+export function buildGraduatedPlanBody({ question, approach, findings, recommendation } = {}) {
+  const q = String(question ?? "").trim();
+  const a = String(approach ?? "").trim();
+  const f = String(findings ?? "").trim();
+  const r = String(recommendation ?? "").trim();
+  if (q.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty question");
+  if (a.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty approach");
+  if (f.length === 0) throw new Error("buildGraduatedPlanBody requires non-empty findings");
+  if (r.length === 0) throw new Error("buildGraduatedPlanBody requires a non-empty recommendation");
+
+  return [
+    "# Graduated spike plan",
+    "",
+    "## Status",
+    "",
+    "Draft (graduated from a spike). Needs refinement before promotion.",
+    "",
+    "## Objective",
+    "",
+    `Act on the spike's recommendation. The spike asked: ${q}`,
+    "",
+    "Approach explored:",
+    "",
+    a,
+    "",
+    "## In scope",
+    "",
+    r,
+    "",
+    "Supporting findings from the spike:",
+    "",
+    f,
+    "",
+    "## Explicit non-goals",
+    "",
+    "- Re-running the spike's exploration; that question is concluded.",
+    "- Work beyond the recommendation above.",
+    "",
+  ].join("\n");
+}

package/src/loop/spike-intake-contract.mjs

@@ -0,0 +1,52 @@
+/**
+ * Spike-mode intake state machine.
+ *
+ * A `--spike` startup hands the dev-loop a time-boxed, exploratory artifact that
+ * lives outside the tracker — startable from a local question with no GitHub
+ * issue. A spike is NOT a plan-needing-refinement, so its states are distinct
+ * from PLAN_FILE_INTAKE_STATE: it classifies how far the exploration has
+ * progressed toward an exit decision, not how far a plan has progressed toward
+ * promotion.
+ *
+ * This evaluator mirrors `evaluatePlanFileIntakeState`: a frozen enum plus a
+ * pure, deterministic function with no GitHub or filesystem side effects — the
+ * caller supplies the section-presence facts it has already read.
+ *
+ * The two non-ambiguous states are the seam phase 2 (#965) consumes for its
+ * discard/graduate exits:
+ *   - SPIKE_IN_PROGRESS    — exploration ongoing (no recommendation yet); a
+ *                            discard exit can drop it with no artifact.
+ *   - SPIKE_READY_FOR_EXIT — a recommendation has been reached; phase 2 routes
+ *                            this to graduate (promote into a plan/PR) or
+ *                            discard (recommendation is "don't pursue").
+ */
+
+export const SPIKE_INTAKE_STATE = Object.freeze({
+  /** Valid spike artifact; the Recommendation is not yet reached. */
+  SPIKE_IN_PROGRESS: "spike_in_progress",
+  /** Valid spike artifact carrying a Recommendation; an exit decision can be made. */
+  SPIKE_READY_FOR_EXIT: "spike_ready_for_exit",
+  /** Inputs are malformed or unusable; fail closed. */
+  AMBIGUOUS_FAIL_CLOSED: "ambiguous_fail_closed",
+});
+
+/**
+ * Pure intake-state classifier.
+ *
+ * @param {object} facts
+ * @param {boolean} facts.baseSectionsValid  whether the spike's exploration scaffold (Question/Approach/Findings) is present and non-empty. Recommendation is NOT part of this fact — it is the separate exit-marker carried by `hasRecommendation`, so that a scaffold-valid spike without a Recommendation classifies as in-progress rather than failing closed.
+ * @param {boolean} facts.hasRecommendation  whether a non-empty Recommendation section is present (the exit-marker that flips in-progress → ready-for-exit)
+ * @returns {{ state: string }} one of SPIKE_INTAKE_STATE values
+ */
+export function evaluateSpikeIntakeState({ baseSectionsValid, hasRecommendation } = {}) {
+  // A malformed spike artifact (missing/empty base sections) is unusable intake
+  // input; fail closed instead of guessing an exit.
+  if (baseSectionsValid !== true) {
+    return { state: SPIKE_INTAKE_STATE.AMBIGUOUS_FAIL_CLOSED };
+  }
+  return {
+    state: hasRecommendation === true
+      ? SPIKE_INTAKE_STATE.SPIKE_READY_FOR_EXIT
+      : SPIKE_INTAKE_STATE.SPIKE_IN_PROGRESS,
+  };
+}

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