mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js

@@ -1,27 +1,7 @@
 /**
- * prior-feedback-fetcher.js — gh-CLI-backed fetcher for open meta feedback
- * issues that feed the `/mandrel-plan` Phase 0 planner context.
- *
- * Story #2554 / Epic #2547. Tech Spec #2550 specifies that the fetcher MUST
- * return open issues carrying the `meta::framework-gap` and
- * `meta::consumer-improvement` labels, dedupe by issue number across the two
- * arrays, and tolerate every error path (missing `gh` binary, unreachable
- * repo, non-zero exit) by appending to a structured `errors[]` list — the
- * function never throws.
- *
- * Tests inject a `spawnImpl` (or shape-compatible `execImpl`) to exercise
- * the gh-exec surface deterministically; production code defaults to
- * `child_process.spawn`.
- *
- * Story #4135 (Epic #4131, F11) — the envelope additionally carries a
- * `recurringDefectClasses[]` array derived from the `friction::<class>`
- * labels the retro routed-proposals composer stamps onto the meta issues it
- * proposes. That closes the retro→planner loop: a recurring defect class
- * caught by review/mandrel-deliver is filed as a `meta::*` + `friction::<class>`
- * issue, and the next `/mandrel-plan` Phase 0 surfaces the class (with a recurrence
- * count across the open feedback issues) to the decompose-author guidance so
- * the planning floor ratchets up. The derivation is no-op-safe: issues with
- * no `friction::*` label contribute nothing and the array is empty.
+ * Fetches open `meta::*` feedback issues for `/mandrel-plan` Phase 0, plus
+ * the recurring `friction::<class>` counts that close the retro→planner
+ * loop. Never throws; failures land in `errors[]`.
  */
 
 import { META_LABELS } from '../label-constants.js';
@@ -30,25 +10,10 @@ import { runChild } from './graduator-core.js';
 
 const DEFAULT_LIMIT = 50;
 
-/** Prefix stamped on routed-proposal issue labels by the retro composer. */
 const FRICTION_LABEL_PREFIX = 'friction::';
 
 /**
- * Pure: derive recurring-defect-class signals from a list of normalized
- * issues by counting `friction::<class>` labels across them (Story #4135).
- *
- * Each fetched meta issue may carry one `friction::<class>` label (stamped by
- * the retro routed-proposals composer when it proposed the issue). A class
- * that appears across **multiple** open feedback issues is recurring across
- * Epics — exactly the signal F11 surfaces to the planner. The count is the
- * number of distinct open issues carrying the class; the `issues[]` array
- * lists their numbers so the planner can cross-reference.
- *
- * Determinism: classes are sorted by descending recurrence count, ties
- * broken by class name ASC, so a given input always yields a stable order.
- *
- * No-op-safe: issues without a `friction::*` label contribute nothing; an
- * empty / non-array input yields `[]`.
+ * `count` is distinct open issues per class; sorted count desc, then name.
  *
  * @param {Array<{ number: number, labels?: string[] }>} issues
  * @returns {Array<{ class: string, count: number, issues: number[] }>}
@@ -91,19 +56,10 @@ function extractRecurringDefectClasses(issues) {
 }
 
 /**
- * Spawn the given gh CLI with the supplied args and resolve to
- * `{ code, stdout, stderr, spawnError }`. Delegates to the shared
- * `runChild` helper in `graduator-core.js` (Story #3845 folded the three
- * feedback-loop spawn copies into one) — the fetcher only needs JSON-mode
- * reads and structured error capture, which `runChild` provides.
- *
- * Never throws: spawn-time errors are captured as `spawnError` so the caller
- * can classify and surface them through the `errors[]` envelope.
- *
  * @param {object} opts
- * @param {string} opts.ghPath — path to the gh binary (e.g. "gh")
- * @param {string[]} opts.args — positional + flag arguments
- * @param {Function} [opts.spawnImpl] — test seam; defaults to node:child_process spawn
+ * @param {string} opts.ghPath
+ * @param {string[]} opts.args
+ * @param {Function} [opts.spawnImpl]
  * @returns {Promise<{ code: number|null, stdout: string, stderr: string, spawnError: Error|null }>}
  */
 function runGh({ ghPath, args, spawnImpl }) {
@@ -111,9 +67,7 @@ function runGh({ ghPath, args, spawnImpl }) {
 }
 
 /**
- * Build a human-readable error message for a failed gh invocation.
- *
- * @param {string} label — the meta label being fetched
+ * @param {string} label
  * @param {{ code: number|null, stderr: string, spawnError: Error|null }} result
  * @returns {string}
  */
@@ -131,17 +85,8 @@ function formatGhError(label, { code, stderr, spawnError }) {
 }
 
 /**
- * Normalize a single issue record returned by `gh issue list --json`. We keep
- * the shape narrow on purpose: planner context payloads ride on top of an
- * already-budgeted envelope, and trimming early avoids any ambient assumption
- * that downstream consumers can rely on extra fields.
- *
- * `intake` is the one field derived rather than copied: an issue whose body
- * carries the CI-gap intake marker is a filing awaiting graduation, not a
- * finished report, and `/mandrel-plan` offers those a `/mandrel-plan <id>`
- * rewrite. The body itself is NOT carried onto the envelope — the marker
- * check is the whole reason it was fetched, and a planner payload does not
- * need every intake issue's full text.
+ * Deliberately narrow: the planner envelope is budgeted. The body is fetched
+ * only to derive `intake` (CI-gap intake marker) and is not carried.
  *
  * @param {object} raw
  * @returns {{ number: number, title: string, url: string, labels: string[], intake: boolean }|null}
@@ -158,8 +103,7 @@ function normalizeIssue(raw) {
 }
 
 /**
- * Flatten `gh issue list --json labels` into plain names. `gh` returns label
- * objects; a hand-built fixture may return strings. Pure.
+ * Accepts `gh` label objects or plain strings.
  *
  * @param {unknown} raw
  * @returns {string[]}
@@ -172,9 +116,6 @@ function normalizeLabels(raw) {
 }
 
 /**
- * Fetch open issues for a single meta label via `gh issue list`. Errors are
- * captured rather than thrown.
- *
  * @param {object} opts
  * @param {string} opts.owner
  * @param {string} opts.repo
@@ -228,11 +169,8 @@ async function fetchByLabel({ owner, repo, label, ghPath, limit, spawnImpl }) {
 }
 
 /**
- * Append every not-yet-seen issue to one bucket, marking it seen.
- *
- * An issue carrying more than one meta label must reach the planner exactly
- * once, so the `seen` set spans all three buckets and the first bucket to
- * claim a number keeps it. Mutates both arguments — one walk, three buckets.
+ * `seen` spans all buckets so a multi-labelled issue lands once, in the
+ * first bucket to claim it.
  *
  * @param {object[]} bucket
  * @param {object[]} issues
@@ -248,23 +186,15 @@ function dedupeInto(bucket, issues, seen) {
 }
 
 /**
- * Fetch the union of open issues carrying `meta::framework-gap`,
- * `meta::consumer-improvement` or `meta::platform-gap` and split them into
- * three arrays — one per ownership bucket in `github/framework-repo.js`, so
- * a filing's bucket survives all the way to the planner. An issue carrying
- * more than one label appears once, in that precedence order; dedupe-by-number
- * runs across all three arrays so the planner sees each issue exactly once.
- *
- * The returned envelope is best-effort: every failure mode (gh missing, repo
- * not found, non-zero exit, malformed JSON) is captured as a string in
- * `errors[]`. The function never throws.
+ * One array per ownership bucket (framework, consumer, platform); an issue
+ * with several meta labels appears once, in that precedence order.
  *
  * @param {object} opts
- * @param {string} opts.owner — GitHub owner (e.g. "dsj1984")
- * @param {string} opts.repo  — GitHub repo (e.g. "mandrel")
- * @param {string} [opts.ghPath="gh"] — path to the gh binary
- * @param {number} [opts.limit=50] — per-label `--limit` passed to gh
- * @param {Function} [opts.spawnImpl] — test seam for node:child_process spawn
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} [opts.ghPath="gh"]
+ * @param {number} [opts.limit=50] — per label.
+ * @param {Function} [opts.spawnImpl]
  * @returns {Promise<{
  *   frameworkGaps: object[],
  *   consumerImprovements: object[],
@@ -332,19 +262,11 @@ export async function fetchPriorFeedback({
     if (error) errors.push(error);
   }
 
-  // Dedupe by issue number across both arrays. Issues that carry both labels
-  // land in frameworkGaps first (deterministic) and are filtered out of
-  // consumerImprovements.
   const seen = new Set();
   dedupeInto(envelope.frameworkGaps, gapsResult.issues, seen);
   dedupeInto(envelope.consumerImprovements, improvementsResult.issues, seen);
   dedupeInto(envelope.platformGaps, platformResult.issues, seen);
 
-  // Story #4135 (Epic #4131, F11) — close the retro→planner loop: derive the
-  // recurring defect classes from the `friction::<class>` labels carried by
-  // the deduped feedback issues, so the next /mandrel-plan Phase 0 surfaces them to
-  // the decompose-author guidance. No-op-safe when no issue carries a
-  // `friction::*` label (empty array, no behavioural change).
   envelope.recurringDefectClasses = extractRecurringDefectClasses([
     ...envelope.frameworkGaps,
     ...envelope.consumerImprovements,

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -1,36 +1,8 @@
 /**
- * retro-proposals-graduator.js — Auto-graduate the retro's actionable
- * routed proposals into GitHub follow-up issues. Story #4418 / Epic #4406.
- *
- * This is the loop's terminal junction: the retro composer
- * (`retro-proposals.js`) already split the Epic's source-tagged friction
- * into `framework` / `consumer` actionable items, each carrying a
- * pre-drafted `gh issue create` command stanza. Historically an operator
- * had to copy-paste those stanzas by hand, so `/mandrel-plan` Phase 0's
- * `recurringDefectClasses` stayed empty unless someone remembered to run
- * the commands. This module files them mechanically instead — the retro
- * body then lists the real filed issue numbers rather than paste-ready
- * commands.
- *
- * Built on the graduator-core **pre-parsed-findings seam** (Story #4415):
- * the routed proposals are handed to `graduate()` as a pre-parsed
- * `findings` array, so there is no structured-comment parsing. The
- * proposals are not file-scoped, so each finding is **path-less** — the
- * seam skips the `git cat-file` path-exists gate rather than misclassifying
- * the finding `file-removed`.
- *
- * Routing correctness: a routed item already knows its source
- * (`framework` / `consumer`), so we file each source bucket with its own
- * constant classifier and thread the graduator's per-run filing cap across
- * the two buckets. Which repository a source routes to is decided once, in
- * `github/framework-repo.js` — the silent consumer-repo fallback that used
- * to live here (and mis-filed framework work into the consumer's tracker)
- * is gone from the whole path, not just from this module. The `meta::<framework-gap|consumer-improvement>` +
- * `friction::<category>` labels are lifted verbatim from the routed item.
- *
- * Behind the `delivery.feedbackLoop.retroProposals` toggle (default ON,
- * per `graduator-core.js#makeIsAutoFileEnabled`). NEVER throws — every
- * failure path is captured in `errors[]`.
+ * Files the retro's routed `framework`/`consumer` proposals as follow-up
+ * issues via `graduate()`, as path-less pre-parsed findings, so the retro
+ * body can list real issue numbers instead of paste-ready commands. Opt-in
+ * via `delivery.feedbackLoop.retroProposals`; never throws.
  */
 
 import {
@@ -46,24 +18,17 @@ import {
 } from './graduator-core.js';
 
 /**
- * Resolve the toggle from the resolved agentrc config. Defaults to `true`
- * — the feature is opt-out (mirrors auditResultsAutoFile).
- *
  * @param {object|undefined|null} config
  * @returns {boolean}
  */
 export const isAutoFileEnabled = makeIsAutoFileEnabled('retroProposals');
 
 /**
- * The content fingerprint identifying one retro proposal.
- *
- * Fingerprinted on the CATEGORY only — never the rendered title. The title
- * embeds the mutable recurrence count ("… recurred <N> times in …"), so
- * hashing it made a retro re-run after the count changed mint a fresh
- * fingerprint and re-file a duplicate issue for the same category.
+ * Category only: the title embeds a mutable recurrence count, so hashing it
+ * would re-file a duplicate whenever the count changed.
  *
  * @param {{ category?: string }} finding
- * @returns {string} 16-char lowercase hex digest.
+ * @returns {string}
  */
 function proposalFingerprint(finding) {
   return contentFingerprint({
@@ -74,29 +39,10 @@ function proposalFingerprint(finding) {
 }
 
 /**
- * Build the content-hash idempotency marker embedded in filed follow-up
- * bodies. An HTML comment so it survives markdown rendering without leaking
- * into the visible body; the idempotency probe strips the comment delimiters
- * before querying `gh search` (the raw `<!-- … -->` form never matches the
- * index — Story #4657).
- *
- * **Anchor-free by construction (Story #4837).** The marker used to read
- * `epic-<anchorId>-<fp>`. The fingerprint half was stable, but the anchor
- * half was the run's FIRST STORY for a run-scoped roll-up
- * (`run-epilogue.js` passes `anchorId: Number(stories[0])`), so it changed
- * every run and the key could never match a prior filing. Measured: closed
- * issues #4833 and #4834 are one `story-blocked` finding under two anchors —
- * `epic-101-e59976671e0b848b` and `epic-777-e59976671e0b848b` — identical
- * fingerprint, different anchor. Dedup did not malfunction; its key was too
- * narrow. The identity of a recurring friction category is the category,
- * full stop: the anchor is evidence about one occurrence and belongs in the
- * body, never in the key.
+ * Anchor-free: a run anchor changes every run, so a marker carrying it could
+ * never match a prior filing. The category alone is the identity.
  *
- * The `epicId` parameter is retained because `graduate()` owns the calling
- * convention for every graduator's `buildContentMarker`; this one
- * deliberately does not consult it.
- *
- * @param {number} _epicId — unused; see above.
+ * @param {number} _epicId — unused; `graduate()` owns the signature.
  * @param {{ category?: string }} finding
  * @returns {string}
  */
@@ -105,20 +51,8 @@ export function buildContentMarker(_epicId, finding) {
 }
 
 /**
- * Body substrings that identify a follow-up already filed for this finding,
- * handed to the graduator's strongly-consistent read (Story #4837).
- *
- * Two shapes, because the marker format changed under a live backlog:
- *
- *   1. The current anchor-free marker.
- *   2. `-<fp> -->` — the tail every pre-cutover anchored marker ends with
- *      (`<!-- retro-proposal-followup: epic-4828-d185e7279a48d03d -->`),
- *      whatever anchor it carried. Without it the cutover would re-file the
- *      whole already-filed backlog exactly once, which is the failure this
- *      Story exists to stop rather than to perform one last time.
- *
- * Module-local: it reaches `graduate()` on the spec bundle, so the walk is
- * the seam and a second exported symbol would only be one nothing imports.
+ * The current marker plus `-<fp> -->`, the tail of every older anchored
+ * marker (`…: epic-<anchor>-<fp> -->`), so those filings still dedup.
  *
  * @param {{ finding: { category?: string }, contentMarker: string }} args
  * @returns {string[]}
@@ -128,8 +62,6 @@ function buildMatchTokens({ finding, contentMarker }) {
 }
 
 /**
- * Map a routed source to its `meta::*` routing label.
- *
  * @param {string} source
  * @returns {string}
  */
@@ -140,18 +72,6 @@ function metaSourceLabel(source) {
 }
 
 /**
- * The per-graduator behaviour bundle for the retro-proposals walk. Bound to
- * a single source so the constant classifier routes every finding in the
- * bucket to the correct repo (and the label reflects that source).
- *
- * The bundle carries **only** builders. It used to declare a
- * `commentMarker` / `noCommentReason` / `parseFindings` trio purely to satisfy
- * the shared walk's shape — this graduator supplies its findings pre-parsed,
- * so the walk never consulted any of the three. Story #5003 deleted that limb
- * from `graduate()` along with the Epic-era graduator that was its only real
- * consumer, and the placeholder fields went with it: a declared-but-unread
- * field is a standing invitation to write a parser nothing will call.
- *
  * @param {'framework'|'consumer'} source
  * @returns {object}
  */
@@ -185,9 +105,6 @@ function makeSpec(source) {
 }
 
 /**
- * Convert a routed-proposal item into a pre-parsed, path-less finding for
- * the shared `graduate()` walk.
- *
  * @param {object} item — a `RoutedItem` from `composeRoutedProposals`.
  * @param {'framework'|'consumer'} source
  * @param {number} index
@@ -196,8 +113,6 @@ function makeSpec(source) {
 function toFinding(item, source, index) {
   return {
     index,
-    // Path-less — the retro proposals are not file-scoped, so the seam
-    // skips the path-exists gate rather than probing an empty path.
     path: '',
     severity: 'friction',
     category: typeof item?.category === 'string' ? item.category : '',
@@ -211,23 +126,15 @@ function toFinding(item, source, index) {
 }
 
 /**
- * File the retro's actionable routed proposals as GitHub follow-up issues
- * via the graduator pre-parsed-findings seam. Files the `framework` and
- * `consumer` buckets, threading the per-run filing cap across both so the
- * overall cap is respected. Never throws.
+ * The per-run filing cap is threaded across both buckets. Never throws.
  *
  * @param {object} opts
  * @param {number} opts.epicId
- * @param {object} opts.provider — ticketing provider (`postComment`, for the
- *   cross-repo-deferred persistence).
- * @param {object} [opts.config] — resolved agentrc.
- * @param {{owner: string, repo: string}} opts.currentRepo — the repo the
- *   retro is running inside (the consumer's own repo); the cross-repo guard's
- *   anchor.
- * @param {{owner: string, repo: string}} [opts.platformRepo] — the shared
- *   platform/infra bucket, forwarded to the walk's routing SSOT.
- * @param {{owner: string, repo: string}} [opts.frameworkRepo] — where
- *   framework-tagged proposals route.
+ * @param {object} opts.provider
+ * @param {object} [opts.config]
+ * @param {{owner: string, repo: string}} opts.currentRepo
+ * @param {{owner: string, repo: string}} [opts.platformRepo]
+ * @param {{owner: string, repo: string}} [opts.frameworkRepo]
  * @param {{ framework?: object[], consumer?: object[] }} [opts.routedProposals]
  * @param {string} [opts.ghPath='gh']
  * @param {Function} [opts.spawnImpl]
@@ -281,16 +188,10 @@ export async function graduateRetroProposals({
     { source: 'consumer', items: consumer },
   ];
 
-  // One memo of content markers filed so far, SHARED across both buckets: the
-  // two scopes mint an identical marker for the same category by construction
-  // (Story #4657), so without it the framework and consumer buckets could each
-  // file the same category. The shared set makes the second bucket short-
-  // circuit the repeat with no spawn.
+  // Shared across buckets: both mint the same marker for a category, so the
+  // second bucket short-circuits the repeat without a spawn.
   const filedMarkers = new Set();
 
-  // One live-label-set read per routed repo across both buckets (Story #4828):
-  // the two buckets file into at most two repos, and every finding in a bucket
-  // wants the same `meta::*` name.
   const labelCache = new Map();
 
   let remaining = maxFilingsPerRun;
@@ -304,8 +205,6 @@ export async function graduateRetroProposals({
       currentRepo,
       frameworkRepo,
       platformRepo,
-      // Each bucket's source is known — a constant classifier routes the
-      // whole bucket to the correct repo and stamps the correct label.
       classifier: () => source,
       ghPath,
       spawnImpl,
@@ -328,10 +227,6 @@ export async function graduateRetroProposals({
 }
 
 /**
- * Pure: extract the trailing issue number from a `gh issue create` URL
- * (`https://github.com/o/r/issues/123` → 123). Returns `null` when no
- * trailing number is present.
- *
  * @param {string|null|undefined} url
  * @returns {number|null}
  */
@@ -342,11 +237,8 @@ export function issueNumberFromUrl(url) {
 }
 
 /**
- * Pure: return a NEW `routedProposals` whose `framework` / `consumer` items
- * each carry a `filedIssue` field ({ url, number }) when the graduator filed
- * an issue for that item's `source` + `category`. Items with no matching
- * filing are copied unchanged (the body renderer then falls back to the
- * command stanza). The `discarded` bucket is passed through untouched.
+ * Attach `filedIssue: { url, number }` to items matched by
+ * `source:category`; unmatched items render their command stanza.
  *
  * @param {{ framework?: object[], consumer?: object[], discarded?: object[] } | null | undefined} routedProposals
  * @param {Array<{ source?: string, category?: string, url?: string|null }>} filed
@@ -391,27 +283,22 @@ export function enrichRoutedProposalsWithFilings(routedProposals, filed) {
 }
 
 /**
- * Orchestrating seam invoked by the retro post-and-mirror phase: gate the
- * toggle, file the routed proposals, and return the routed proposals
- * enriched with the filed issue references so the body composer renders real
- * issue numbers instead of command stanzas. Never throws — a filing failure
- * degrades to the unenriched proposals (the composer falls back to command
- * stanzas) and the error is surfaced in `errors[]`.
+ * File, then enrich the proposals with the filed issues. Never throws: a
+ * failure degrades to the unenriched proposals plus an `errors[]` entry.
  *
  * @param {object} opts
  * @param {number} opts.epicId
  * @param {object} opts.provider
  * @param {object} [opts.config]
  * @param {string} [opts.frameworkRepo] — `"<owner>/<repo>"` slug.
- * @param {string} [opts.consumerRepo] — `"<owner>/<repo>"` slug (currentRepo).
+ * @param {string} [opts.consumerRepo] — `"<owner>/<repo>"` slug.
  * @param {{ framework?: object[], consumer?: object[], discarded?: object[] }} [opts.routedProposals]
  * @param {string} [opts.ghPath]
  * @param {Function} [opts.spawnImpl]
  * @param {string} [opts.cwd]
  * @param {number} [opts.maxFilingsPerRun]
  * @param {{info?: Function, warn?: Function}} [opts.logger]
- * @param {Function} [opts.graduateFn] — test seam; defaults to
- *   {@link graduateRetroProposals}.
+ * @param {Function} [opts.graduateFn]
  * @returns {Promise<{ routedProposals: object|null, summary: { filed: object[], skipped: object[], errors: string[] } }>}
  */
 export async function fileRetroProposals({
@@ -433,25 +320,16 @@ export async function fileRetroProposals({
     summary: { filed: [], skipped: reason ? [{ reason }] : [], errors: [] },
   });
 
-  // Toggle OFF → leave proposals unenriched; the composer renders the
-  // paste-ready command stanzas.
   if (!isAutoFileEnabled(config)) return passthrough('toggle-disabled');
 
   const currentRepo = parseRepoSlug(consumerRepo);
   if (!currentRepo) {
-    // No resolvable consumer repo — the retro already disables the consumer
-    // pane loudly; skip filing and fall back to command stanzas.
     logger?.warn?.(
       '[retro-proposals-graduator] No resolvable consumer repo — skipping auto-file (falling back to command stanzas).',
     );
     return passthrough('no-current-repo');
   }
-  // An unconfigured framework slug falls back to the Mandrel mirror
-  // constant, NEVER to the consumer's own repo: the retired consumer-repo
-  // fallback silently auto-filed framework-tagged proposals into the
-  // consumer's tracker while the retro body rendered them under "framework
-  // repo" (masked in this repo only because consumer === framework here).
-  // `github/framework-repo.js` is the SSOT for that rule now.
+  // Fall back to the Mandrel constant, never the consumer's own repo.
   const frameworkRepoObj =
     parseRepoSlug(frameworkRepo) ?? parseRepoSlug(DEFAULT_FRAMEWORK_REPO);