mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/ci-gap-intake.js

@@ -1,46 +1,9 @@
 /**
- * ci-gap-intake.js — the mechanism behind `rules/ci-remediation.md` Option 2.
- *
- * ## What was here before: nothing
- *
- * The rule told a delivering agent to "file a `meta::framework-gap` issue
- * carrying the run link and the failure signature". That sentence was the
- * whole implementation. The agent hand-ran `gh issue create` in whatever
- * repository it happened to be standing in, which produced two failures every
- * time:
- *
- *   1. **Unactionable.** A hand-typed issue has no `## Spec`, no
- *      `acceptance[]` / `verify[]` and no `agent::*` label, so
- *      `/mandrel-deliver` cannot take it. `/mandrel-plan` Phase 0 re-surfaces
- *      it as a recurring-defect row forever and nothing ever acts on it.
- *   2. **Mis-routed.** It lands in the consumer's repo no matter who owns the
- *      fault — including when the root cause is a shared base config or the
- *      runner host, which no amount of work in the consumer repo can fix.
- *
- * ## Two phases, never one
- *
- * Delivery files an **intake issue**; planning graduates it. This module
- * never invokes `/mandrel-plan`, never blocks on it, and never authors a
- * Story body. It runs mid-delivery while the Story is heading to
- * `agent::blocked` with nobody at the keyboard, so a synchronous planning
- * call would couple the CI path to an interactive workflow. Instead the
- * intake issue is written in a shape Phase 0 can recognise (the
- * {@link CI_GAP_INTAKE_MARKER}) and `/mandrel-plan <id>` rewrites it into a
- * Story on the next planning pass.
- *
- * ## Dedup is the point, not a nicety
- *
- * Runner-host contention is a repeat offender: the same signature reds an
- * unrelated PR weekly. The Nth occurrence must land on the existing ticket —
- * an occurrence count is the evidence that turns "a flake" into "a defect
- * worth someone's afternoon". Routing goes through `findings/route-finding.js`,
- * the same fingerprint dedup `audit-to-stories` and `qa-explore` share, so
- * there is one dedup implementation in the repo rather than three.
- *
- * Pure orchestration: **no network I/O lives here.** Every GitHub side effect
- * flows through injected ports (`searchIssues`, `createIssue`, `updateIssue`),
- * so the unit tests run with no network and the CLI wires them to the
- * provider.
+ * ci-gap-intake.js — `rules/ci-remediation.md` Option 2: file an intake issue
+ * in the repo that owns the fault; `/mandrel-plan <id>` graduates it later
+ * (never called from here — this runs unattended). A repeat signature lands
+ * on the existing ticket: the occurrence count is the evidence. Ports are
+ * injected.
  */
 
 import {
@@ -51,34 +14,19 @@ import {
 import { OWNERSHIP_BUCKETS, routeOwnership } from '../github/framework-repo.js';
 import { META_LABELS } from '../label-constants.js';
 
-/**
- * Body marker identifying a CI-gap intake issue. `/mandrel-plan` Phase 0
- * keys graduation off it, so it is a contract: bump the version suffix only
- * alongside a reader that understands both.
- */
+/** Contract with `/mandrel-plan` Phase 0; bump only alongside its reader. */
 export const CI_GAP_INTAKE_MARKER = '<!-- ci-gap-intake: v1 -->';
 
-/**
- * The verdicts that route to Option 2 in `rules/ci-remediation.md`. Closed by
- * construction: this is the rule's own set, not a second taxonomy invented
- * here. Each becomes a `friction::<verdict>` label, which is what
- * `prior-feedback-fetcher.js` already counts into `recurringDefectClasses[]`.
- */
+/** Each becomes a `friction::<verdict>` label counted by Phase 0. */
 export const INTAKE_VERDICTS = Object.freeze([
   'pre-existing',
   'capacity',
   'unreproducible-tier',
 ]);
 
-/**
- * The Option-1 verdict. Named rather than merely absent so refusing it can
- * say *why*: a defect in the diff under review is fixed at source on the
- * branch, and filing an intake issue for it would launder a real defect into
- * someone else's backlog.
- */
+/** Option 1: a defect in the diff is fixed on the branch, never filed. */
 export const REFUSED_VERDICT = 'defect-in-diff';
 
-/** Ownership bucket → the `meta::*` label that marks who owns the work. */
 const BUCKET_META_LABEL = Object.freeze({
   consumer: META_LABELS.CONSUMER_IMPROVEMENT,
   framework: META_LABELS.FRAMEWORK_GAP,
@@ -86,13 +34,8 @@ const BUCKET_META_LABEL = Object.freeze({
 });
 
 /**
- * Validate a verdict against the rule's Option-2 set.
- *
- * Throws rather than defaulting: a mis-verdicted filing routes real work to
- * the wrong owner, and the caller can always fix the flag.
- *
  * @param {string} verdict
- * @returns {string} the validated verdict
+ * @returns {string}
  */
 function assertIntakeVerdict(verdict) {
   if (verdict === REFUSED_VERDICT) {
@@ -109,10 +52,8 @@ function assertIntakeVerdict(verdict) {
 }
 
 /**
- * Validate an ownership bucket against the closed set.
- *
  * @param {string} bucket
- * @returns {string} the validated bucket
+ * @returns {string}
  */
 function assertOwnershipBucket(bucket) {
   if (!OWNERSHIP_BUCKETS.includes(bucket)) {
@@ -124,10 +65,6 @@ function assertOwnershipBucket(bucket) {
 }
 
 /**
- * The failure signature: the first distinctive line of the captured
- * failed-job log. Mirrors `ci-rerun-guard.js`'s reading of the same digest
- * field — this is the line a human recognises a repeat occurrence by.
- *
  * @param {object} digest
  * @returns {string}
  */
@@ -140,12 +77,7 @@ function failureSignature(digest) {
 }
 
 /**
- * Normalise a signature line into fingerprint-stable text.
- *
- * Run-specific noise — timestamps, ports, run ids, hex object ids, absolute
- * temp paths — makes two occurrences of the SAME defect fingerprint
- * differently, which is precisely the dedup failure this module exists to
- * avoid. Stripping it is what lets the Nth occurrence find the first.
+ * Strip run-specific noise so repeat occurrences fingerprint identically.
  *
  * @param {string} line
  * @returns {string}
@@ -163,17 +95,14 @@ function normaliseSignature(line) {
 }
 
 /**
- * Build the canonical finding the dedup layer fingerprints.
- *
- * `area` folds in the verdict so the same signature reached under two
- * different verdicts stays two findings — the verdict is who owns the fix,
- * and merging those would merge two different pieces of work.
+ * `area` folds in the verdict: the same signature under two verdicts is two
+ * different owners' work.
  *
  * @param {object} opts
- * @param {object} opts.digest — the CI failure digest.
+ * @param {object} opts.digest
  * @param {string} opts.verdict
  * @param {string} opts.bucket
- * @returns {object} canonical finding for `route-finding.js`
+ * @returns {object}
  */
 function buildIntakeFinding({ digest, verdict, bucket }) {
   return {
@@ -186,8 +115,6 @@ function buildIntakeFinding({ digest, verdict, bucket }) {
 }
 
 /**
- * Render one `## Occurrences` row.
- *
  * @param {object} occurrence
  * @returns {string}
  */
@@ -201,7 +128,6 @@ function renderOccurrenceRow({ at, runUrl, headSha, prNumber }) {
   return `| ${cells.join(' | ')} |`;
 }
 
-/** Header of the occurrences table, matched verbatim when appending a row. */
 const OCCURRENCES_HEADER = [
   '## Occurrences',
   '',
@@ -210,10 +136,7 @@ const OCCURRENCES_HEADER = [
 ].join('\n');
 
 /**
- * Render the `## Routing` block — the half of this module that exists purely
- * so a mis-route can never again be silent. It states the bucket, the
- * destination, and, when there is no destination, the exact config key that
- * would give it one.
+ * Makes a mis-route visible: names the destination or the missing key.
  *
  * @param {object} routing
  * @returns {string}
@@ -240,8 +163,6 @@ function renderRouting(routing) {
 }
 
 /**
- * Render the intake issue body.
- *
  * @param {object} opts
  * @returns {string}
  */
@@ -288,14 +209,9 @@ function renderIntakeBody({
 }
 
 /**
- * Append one occurrence row to an existing intake body.
+ * Grafts a fresh table when a hand-edited body lost it.
  *
- * Appends to the existing table when the body carries one, and otherwise
- * grafts a fresh table onto the end — an intake issue an operator has
- * hand-edited must still accumulate occurrences rather than silently losing
- * them.
- *
- * @param {string} body — the existing issue body.
+ * @param {string} body
  * @param {object} occurrence
  * @returns {string}
  */
@@ -306,8 +222,7 @@ function appendOccurrence(body, occurrence) {
     return [existing.trimEnd(), '', OCCURRENCES_HEADER, row].join('\n');
   }
   const lines = existing.split('\n');
-  // The table runs to the first blank line after the header; inserting there
-  // (rather than appending to the body) keeps any footer below it intact.
+  // Insert at the table's end, not the body's, so the footer stays intact.
   const headerIdx = lines.findIndex((l) => l.trim() === '## Occurrences');
   let insertAt = lines.length;
   for (let i = headerIdx + 1; i < lines.length; i += 1) {
@@ -320,9 +235,6 @@ function appendOccurrence(body, occurrence) {
 }
 
 /**
- * Compose the intake issue title. Verdict-prefixed so a tracker list reads as
- * a triage queue rather than a wall of stack traces.
- *
  * @param {object} opts
  * @returns {string}
  */
@@ -332,14 +244,8 @@ function buildIntakeTitle({ digest, verdict }) {
 }
 
 /**
- * Append this occurrence to the intake issue already tracking the signature.
- *
- * The Nth occurrence is the evidence that turns "a flake" into a defect worth
- * someone's afternoon, so it lands on the existing ticket rather than minting
- * a second one.
- *
  * @param {object} opts
- * @returns {Promise<object>} the intake result envelope.
+ * @returns {Promise<object>}
  */
 async function recordRecurrence({
   matchedIssue,
@@ -376,17 +282,11 @@ async function recordRecurrence({
 }
 
 /**
- * Create the intake issue in the routed repository, degrading to a local
- * filing when that write is refused.
- *
- * A cross-repo write needs a token scoped to the target repo, which an
- * operator may simply not have granted. The refusal becomes a local filing
- * that names the repo the work belongs in — never a silent drop, and never a
- * pretend-success. `routing` is mutated so the caller's envelope and the
- * re-rendered body agree on where this landed.
+ * A refused cross-repo write degrades to a local filing naming the owning
+ * repo; `routing` is mutated so envelope and body agree.
  *
  * @param {object} opts
- * @param {Function} opts.render — re-render the body for a mutated routing.
+ * @param {Function} opts.render
  * @returns {Promise<{ created: object, body: string }>}
  */
 async function createWithDegrade({
@@ -428,26 +328,22 @@ async function createWithDegrade({
 }
 
 /**
- * File (or update) the intake issue for one CI-gap verdict.
- *
- * Never throws for an I/O reason — every port failure lands in `errors[]` so
- * a filing fault cannot itself fail the delivery that is already blocking.
- * An invalid verdict or bucket DOES throw: that is operator input, caught
- * before any side effect, and silently proceeding would file the wrong thing.
+ * Port failures land in `errors[]`; only an invalid verdict or bucket throws,
+ * before any side effect.
  *
  * @param {object} opts
- * @param {object} opts.digest — CI failure digest (from `ci-rerun-guard.js`).
- * @param {string} opts.verdict — one of {@link INTAKE_VERDICTS}.
- * @param {string} opts.bucket — ownership bucket (`consumer|framework|platform`).
- * @param {string} [opts.evidence] — the verdict's proof reading.
- * @param {object} opts.repos — resolved ownership buckets.
+ * @param {object} opts.digest
+ * @param {string} opts.verdict
+ * @param {string} opts.bucket
+ * @param {string} [opts.evidence]
+ * @param {object} opts.repos
  * @param {{owner: string, repo: string}} opts.currentRepo
  * @param {number|null} [opts.prNumber]
- * @param {boolean} [opts.dryRun] — compose everything, write nothing.
- * @param {object} opts.ports — `{ searchIssues, createIssue, updateIssue }`.
+ * @param {boolean} [opts.dryRun]
+ * @param {object} opts.ports
  * @param {object} [opts.logger]
- * @param {string} [opts.now] — ISO timestamp seam for deterministic tests.
- * @returns {Promise<object>} the intake result envelope.
+ * @param {string} [opts.now]
+ * @returns {Promise<object>}
  */
 export async function fileCiGapIntake({
   digest,
@@ -474,8 +370,7 @@ export async function fileCiGapIntake({
   };
 
   const routed = routeOwnership({ bucket, repos, currentRepo });
-  // An unroutable bucket files where the run is standing and says so in the
-  // body — the one thing it must never do is look routed.
+  // Unroutable → file locally and say so; never look routed.
   const routing = {
     bucket,
     routable: routed.routable,
@@ -506,8 +401,7 @@ export async function fileCiGapIntake({
     matchedIssue = routedDecision.matchedIssue;
     fingerprint = routedDecision.fingerprint;
   } catch (err) {
-    // A degraded lookup must not mint a duplicate on a repeat offender, so
-    // the filing stops here rather than guessing `new`.
+    // A degraded lookup stops rather than guessing `new` and duplicating.
     errors.push(`dedup lookup failed: ${err?.message ?? err}`);
     return {
       decision: 'lookup-failed',
@@ -531,8 +425,7 @@ export async function fileCiGapIntake({
     occurrence,
   });
 
-  // An open match is an occurrence of a defect already tracked; only a `new`
-  // or a regression of something closed long ago earns a fresh ticket.
+  // Only `new` or a closed-ticket regression earns a fresh ticket.
   const isRecurrence =
     (decision === 'update-existing' || decision === 'duplicate') &&
     matchedIssue?.number;