@dev-loops/core 1.0.2 → 1.0.4-pre.0

package/src/loop/gate-fanin.mjs

@@ -68,6 +68,51 @@ export function backoffMaxConcurrent(maxConcurrent) {
   return Math.max(1, Math.floor(cap / 2));
 }
 
+/** 30s/60s/120s same-unit retry schedule (`GATE-EXEC-DISPATCH-RETRY-BACKOFF`). */
+const DISPATCH_RETRY_BACKOFF_SCHEDULE_MS = Object.freeze([30_000, 60_000, 120_000]);
+
+/**
+ * True when `errorClass` names a transient provider error (429 rate-limit or
+ * any 5xx), the class `GATE-EXEC-DISPATCH-RETRY-BACKOFF` retries — as opposed
+ * to a hard 4xx (e.g. `402`), which never is.
+ * @param {string|number} errorClass
+ * @returns {boolean}
+ */
+function isTransientDispatchErrorClass(errorClass) {
+  const s = String(errorClass ?? "").trim();
+  return s === "429" || /^5\d\d$/.test(s) || s.toLowerCase() === "5xx";
+}
+
+/**
+ * Pure retry-decision policy for `GATE-EXEC-DISPATCH-RETRY-BACKOFF`: whether a
+ * failed dispatch retries the SAME unit, and when a batch reduction is due.
+ *
+ * A transient failure (429 / 5xx) always retries — the round is never aborted
+ * on a transient error, safe because a retry overwrites the same idempotent
+ * per-angle findings artifact path (`GATE-EXEC-COLLECTABLE-DISPATCH`), never
+ * minting a second one. `delayMs` follows the 30s/60s/120s schedule (holding
+ * at 120s past the 3rd attempt); `reduceConcurrency` flips true starting at
+ * the 3rd exhausted attempt (`attempt` index 2), signaling the caller to halve
+ * the active batch via `backoffMaxConcurrent` — this function only signals
+ * WHEN, the halving itself stays `backoffMaxConcurrent`'s job.
+ *
+ * A hard 4xx (e.g. `402 Insufficient Balance`) is never transient: it escalates
+ * to the supervisor/operator immediately instead of retrying into the same wall.
+ *
+ * @param {number} attempt — 0-based count of prior failed attempts on this unit
+ * @param {string|number} errorClass — e.g. `"429"`, `"500"`, `"5xx"`, `"402"`
+ * @returns {{ retry: true, delayMs: number, reduceConcurrency: boolean } | { retry: false, escalate: true }}
+ */
+export function planDispatchRetry(attempt, errorClass) {
+  if (!isTransientDispatchErrorClass(errorClass)) {
+    return { retry: false, escalate: true };
+  }
+  const n = Number.isInteger(attempt) && attempt >= 0 ? attempt : 0;
+  const lastIndex = DISPATCH_RETRY_BACKOFF_SCHEDULE_MS.length - 1;
+  const delayMs = DISPATCH_RETRY_BACKOFF_SCHEDULE_MS[Math.min(n, lastIndex)];
+  return { retry: true, delayMs, reduceConcurrency: n >= lastIndex };
+}
+
 /**
  * Reviewer-budget preflight for a gate fan-out.
  *
@@ -783,6 +828,7 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
           disposition: deriveDisposition(severity, { isBlocking, locatable: hasLocatableShape(f) }),
         };
         if (typeof f.file === "string" && f.file.trim().length > 0) entry.file = f.file.trim();
+        if (Array.isArray(f.files)) entry.files = f.files.filter((file) => typeof file === "string" && file.trim().length > 0).map((file) => file.trim());
         if (typeof f.line === "number" && Number.isFinite(f.line)) entry.line = f.line;
         if (typeof f.recommendation === "string" && f.recommendation.trim().length > 0) {
           entry.recommendation = f.recommendation.trim();
@@ -826,6 +872,38 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
  */
 export const JUDGE_DISPOSITIONS = Object.freeze(["act", "defer", "reject"]);
 
+/**
+ * The `scopeDrift.verdict` vocabulary — the single shared source. The validator
+ * below consumes it directly, and a divergence-guard test asserts the judge
+ * persona surface (`agents/judge.agent.md`) documents exactly this set, so the
+ * producer and enforcer cannot silently drift apart.
+ */
+export const SCOPE_DRIFT_VERDICTS = Object.freeze(["within_scope", "drift_detected"]);
+
+/**
+ * Aliases a persona-following judge reaches for, normalized to the canonical
+ * vocabulary before validation. `none` is the intuitive no-drift spelling; it
+ * maps to `within_scope` so a semantically-correct verdict passes with no
+ * resend or hand-edit, disposition and rationale byte-intact.
+ */
+export const SCOPE_DRIFT_VERDICT_ALIASES = Object.freeze({ none: "within_scope" });
+
+/**
+ * Normalize a `scopeDrift.verdict` alias to its canonical value. Canonical and
+ * unknown values pass through untouched; validation rejects unknowns.
+ * @param {unknown} verdict
+ * @returns {unknown}
+ */
+export function normalizeScopeDriftVerdict(verdict) {
+  // Only a primitive string spelling normalizes. `hasOwnProperty.call` coerces
+  // its key argument, so without this guard a boxed `new String("none")` or an
+  // object whose `toString()` returns `"none"` would alias to `within_scope` —
+  // a fail-open contradicting the validator's non-string-fails-closed contract.
+  return typeof verdict === "string" && Object.prototype.hasOwnProperty.call(SCOPE_DRIFT_VERDICT_ALIASES, verdict)
+    ? SCOPE_DRIFT_VERDICT_ALIASES[verdict]
+    : verdict;
+}
+
 /**
  * Validate a judge verdict artifact shape (the `judge` agent's only write).
  * Pure; throws on a malformed verdict rather than enriching findings with
@@ -856,8 +934,9 @@ export function validateJudgeVerdict(verdict) {
     throw new Error("judge verdict.scopeDrift must be an object");
   }
   const sd = /** @type {Record<string, unknown>} */ (v.scopeDrift);
-  if (sd.verdict !== "within_scope" && sd.verdict !== "drift_detected") {
-    throw new Error("judge verdict.scopeDrift.verdict must be 'within_scope' or 'drift_detected'");
+  const normalizedVerdict = normalizeScopeDriftVerdict(sd.verdict);
+  if (!SCOPE_DRIFT_VERDICTS.includes(/** @type {string} */ (normalizedVerdict))) {
+    throw new Error(`judge verdict.scopeDrift.verdict must be one of: ${SCOPE_DRIFT_VERDICTS.join(", ")}`);
   }
   if (typeof sd.rationale !== "string" || sd.rationale.trim().length === 0) {
     throw new Error("judge verdict.scopeDrift.rationale must be a non-empty string");
@@ -904,7 +983,7 @@ export function validateJudgeVerdict(verdict) {
       }
     }
   }
-  return { headSha: v.headSha, scopeDrift: v.scopeDrift, dispositions: v.dispositions };
+  return { headSha: v.headSha, scopeDrift: { ...sd, verdict: normalizedVerdict }, dispositions: v.dispositions };
 }
 
 /**

package/src/loop/issue-refinement-artifact.mjs

@@ -949,14 +949,95 @@ function sectionHasBody(section) {
   return false;
 }
 
+// A top-level list marker line (any GFM/CommonMark family: `-`/`*`/`+`,
+// ordered `N.`/`N)`, optional leading blockquote `>` runs) with NO checkbox.
+// `validatePrBodySpec`-local: unlike `parseChecklistItems` (whose
+// `checked: null` state fires ONLY for the bare-dash form — see its
+// docstring), this recognizes every marker family, so a mixed AC/DoD section
+// (`- [ ] works` next to `* plain`) cannot escape detection just because the
+// plain line used a non-dash marker. No leading-space match before the
+// marker/blockquote keeps this top-level only: an indented continuation
+// (`  - detail`) is sub-content and is not matched. The negative lookahead
+// excludes a real checkbox line so `- [ ] works` is never double-counted; the
+// lookahead treats end-of-line as a checkbox terminator too (`(?:\s|$)`), so
+// an empty checkbox placeholder (`- [ ]`/`- [x]`, no trailing text) is
+// excluded rather than mis-caught as a plain bullet — `parseChecklistItems`
+// already documents empty placeholders as skipped, and this scan must not
+// contradict that.
+const TOP_LEVEL_NON_CHECKBOX_BULLET_PATTERN = /^(?:>\s*)*(?:[-*+]|\d+[.)])\s+(?!\[[ xX]\](?:\s|$))(.+?)\s*$/u;
+
+// A spaced Markdown thematic break (`* * *`, `- - -`) also matches
+// `TOP_LEVEL_NON_CHECKBOX_BULLET_PATTERN` (marker, whitespace, more marker
+// text) but is a divider, not a bullet — `parseChecklistItems` never treats
+// it as an item, so counting it here would reject a legitimate AC/DoD
+// section over a divider line. `***`/`---` (no spaces) already fail the
+// bullet pattern's `\s+` requirement, so only the spaced form needs this
+// guard. Same-marker-only via the backreference, and only `-`/`*`/`_` per
+// the CommonMark thematic-break rule (3+ of the SAME char, optional spaces,
+// nothing else) — `+` is NOT a valid thematic-break marker, so `+ + +`
+// stays correctly counted as a real (single-item) plain bullet.
+const THEMATIC_BREAK_RE = /^([-*_])(?:[ \t]*\1){2,}[ \t]*$/u;
+
+/**
+ * Scan a flattened section body for top-level non-checkbox bullet lines
+ * (`TOP_LEVEL_NON_CHECKBOX_BULLET_PATTERN`). Fence-skipped via the shared
+ * `stepFence` so a fenced fake bullet cannot spoof this check. Thematic-break
+ * divider lines (`THEMATIC_BREAK_RE`) are excluded — see its docstring.
+ */
+function scanTopLevelNonCheckboxBulletLines(text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const found = [];
+  let fence = null;
+  for (const line of text.split(/\r?\n/u)) {
+    const step = stepFence(fence, line);
+    fence = step.fence;
+    if (step.insideFence) continue;
+    const match = TOP_LEVEL_NON_CHECKBOX_BULLET_PATTERN.exec(line);
+    if (!match || match[1].trim().length === 0) continue;
+    const strippedLine = line.replace(/^(?:>\s*)*/u, "").trim();
+    if (THEMATIC_BREAK_RE.test(strippedLine)) continue;
+    found.push(match[1].trim());
+  }
+  return found;
+}
+
+/**
+ * Scan every section the completeness block would read (ALL sections matching
+ * `patterns`, deep-flattened past `###` sub-headings via
+ * `findAllSectionsByPatterns` + `flattenSectionDeep` — the same union
+ * `extractPrBodyUncheckedChecklistItems` reads) for top-level plain bullets
+ * of ANY marker (no checkbox). Shares the section-set read with the
+ * completeness block on purpose: a plain bullet invisible to
+ * `validatePrBodySpec`'s own single-section read but visible to the
+ * completeness block (a duplicate AC/DoD heading, or a bullet nested under a
+ * `###` sub-heading) must still reject here, or the two surfaces diverge on
+ * the same checkbox-marker fail-open class this module closes for the simple
+ * single-section case. Local `scanTopLevelNonCheckboxBulletLines` scan, not
+ * `parseChecklistItems`'s `checked: null` state, so a non-dash plain bullet
+ * (`*`/`+`/ordered) is caught too — `parseChecklistItems` and the shared
+ * deterministic pre-approval completeness-block logic it backs (see
+ * acceptance-criteria-verification.md) stay untouched.
+ */
+function scanPlainBullets(sections, patterns) {
+  const matched = findAllSectionsByPatterns(sections, patterns);
+  const items = [];
+  for (let i = 0; i < sections.length; i += 1) {
+    if (!matched.includes(sections[i])) continue;
+    items.push(...scanTopLevelNonCheckboxBulletLines(flattenSectionDeep(sections, i)));
+  }
+  return items;
+}
+
 /**
  * Validate that a PR body carries every invariant required to serve as the
  * lightweight spec-of-record: Objective/why, in-scope, explicit non-goals,
- * testable Acceptance criteria (>=1 checklist item), Definition of done
- * (>=1 checklist item), Open questions/risks, and — unless issue-less mode is
+ * testable Acceptance criteria (>=1 checkbox item), Definition of done
+ * (>=1 checkbox item), Open questions/risks, and — unless issue-less mode is
  * requested — a GitHub closing-keyword issue reference. Reuses the generic
  * markdown logic so there is no parallel validator. Fails closed: every missing
- * invariant is reported under its distinct `missing_*` code. Pure; no I/O.
+ * invariant is reported under its distinct `missing_*` code (plus the two
+ * `*_not_checkboxes` codes for a plain-bullet AC/DoD section — see
+ * `scanPlainBullets`). Pure; no I/O.
  *
  * Issue-less mode (`issueLess: true`): the closing-issue linkage flips from
  * REQUIRED to FORBIDDEN (the PR is the sole artifact), failing closed under
@@ -1044,21 +1125,48 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
     }
   }
 
+  // Checkbox markers are REQUIRED (not just any bullet): the completeness
+  // block (extractPrBodyUncheckedChecklistItems) only ever sees checkbox
+  // items, so a plain bullet here would fail-open the completeness check
+  // even though this validator accepted it. The plain-bullet scan reads the
+  // SAME section set the completeness block reads (scanPlainBullets), not
+  // just the first section, so a duplicate heading or a bullet nested under a
+  // `###` sub-heading cannot hide from this check either. The scan runs
+  // INDEPENDENTLY of parseChecklistItems (not gated on it finding items) and
+  // is checked FIRST: an AC/DoD section made entirely of non-dash plain
+  // bullets (`* plain`, `1. plain`) yields zero parsed checkbox items, so
+  // gating the scan on "items found" would misreport that case as
+  // missing_acceptance_criteria/missing_definition_of_done instead of the
+  // distinct *_not_checkboxes code.
   const acSection = findSectionByPatterns(sections, ACCEPTANCE_SECTION_PATTERNS);
-  const acItems = acSection ? extractChecklistItems(acSection.bodyLines.join("\n")) : [];
-  if (acItems.length === 0) {
+  const acParsed = acSection ? parseChecklistItems(acSection.bodyLines.join("\n")) : [];
+  const acItems = acParsed.filter((item) => item.checked !== null).map((item) => item.text);
+  const acPlainBullets = scanPlainBullets(sections, ACCEPTANCE_SECTION_PATTERNS);
+  if (acPlainBullets.length > 0) {
+    errors.push({
+      code: "acceptance_criteria_not_checkboxes",
+      message: `Acceptance criteria must use checkbox markers ('- [ ]'/'- [x]'), not plain bullets (found ${acPlainBullets.length} plain bullet(s)); plain bullets fail-open the completeness block.`,
+    });
+  } else if (acParsed.length === 0) {
     errors.push({
       code: "missing_acceptance_criteria",
-      message: "Missing testable Acceptance criteria (no checklist items found).",
+      message: "Missing testable Acceptance criteria (no checkbox items found).",
     });
   }
 
   const dodSection = findSectionByPatterns(sections, DOD_SECTION_PATTERNS);
-  const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
-  if (dodItems.length === 0) {
+  const dodParsed = dodSection ? parseChecklistItems(dodSection.bodyLines.join("\n")) : [];
+  const dodItems = dodParsed.filter((item) => item.checked !== null).map((item) => item.text);
+  const dodPlainBullets = scanPlainBullets(sections, DOD_SECTION_PATTERNS);
+  if (dodPlainBullets.length > 0) {
+    errors.push({
+      code: "definition_of_done_not_checkboxes",
+      message: `Definition of done must use checkbox markers ('- [ ]'/'- [x]'), not plain bullets (found ${dodPlainBullets.length} plain bullet(s)); plain bullets fail-open the completeness block.`,
+    });
+  } else if (dodParsed.length === 0) {
     errors.push({
       code: "missing_definition_of_done",
-      message: "Missing Definition of done (no checklist items found).",
+      message: "Missing Definition of done (no checkbox items found).",
     });
   }