mandrel 2.55.0 → 2.57.0

package/.agents/scripts/lib/github/framework-repo.js

@@ -1,6 +1,152 @@
 /**
- * Canonical framework repository slug used by follow-up / graduator
- * paths when the consumer config does not supply owner/repo.
+ * framework-repo.js — the follow-up **ownership routing** SSOT: which
+ * repository a finding, a retro proposal, or a CI-gap intake issue is filed
+ * in, and what to say when that question has no answer.
+ *
+ * ## Three buckets, not two
+ *
+ * A defect surfaced by one repository's CI is not necessarily that
+ * repository's to fix. Ownership splits three ways:
+ *
+ *   - `consumer`  — the repo the run is standing in (`github.owner`/`repo`).
+ *   - `framework` — the Mandrel framework itself
+ *     (`github.followUpRepos.framework`, defaulted to the mirror constant).
+ *   - `platform`  — a shared platform / infrastructure repo that neither of
+ *     the other two owns: a shared base config, a runner fleet, a
+ *     cross-repo toolchain (`github.followUpRepos.platform`, **no default**
+ *     — nothing can guess a shared repo's slug).
+ *
+ * ## Why there is no `?? currentRepo` fallback
+ *
+ * The two-bucket predecessor resolved a framework-tagged item with
+ * `frameworkRepo ? frameworkRepo : currentRepo`. When the config key was
+ * absent that expression filed framework-owned work into the **consumer's**
+ * repo while the rendered retro claimed it went to the framework repo — a
+ * silent mis-file, recorded in `retro-proposals-graduator.js`'s own file-top
+ * comment. The failure was invisible in this repository precisely because
+ * consumer === framework here.
+ *
+ * So an unresolvable bucket is a first-class outcome, never a fallback:
+ * `routeOwnership` returns `routable: false` plus the `missingKey` that
+ * would fix it, and every caller must decide **out loud** what to do with
+ * that — file locally and say so in the body (the CI-gap filer), or defer
+ * and surface it where an operator will see it (the graduators). What no
+ * caller may do is route it somewhere plausible and stay quiet.
  */
 
+/**
+ * Canonical framework repository slug, used when the consumer config does
+ * not supply `github.followUpRepos.framework`. The `framework` bucket is the
+ * one bucket with a knowable default: it is this framework.
+ */
 export const DEFAULT_FRAMEWORK_REPO = 'dsj1984/mandrel';
+
+/** The closed ownership-bucket set. */
+export const OWNERSHIP_BUCKETS = Object.freeze([
+  'consumer',
+  'framework',
+  'platform',
+]);
+
+/**
+ * The `.agentrc.json` key behind each bucket, quoted verbatim when a bucket
+ * is unroutable so the operator is told which key to set rather than that
+ * "routing failed".
+ */
+const OWNERSHIP_CONFIG_KEYS = Object.freeze({
+  consumer: 'github.owner / github.repo',
+  framework: 'github.followUpRepos.framework',
+  platform: 'github.followUpRepos.platform',
+});
+
+/**
+ * Parse an `"<owner>/<repo>"` slug into `{ owner, repo }`, or `null` when the
+ * slug is absent, empty, or malformed. A `null` return is the signal an
+ * unroutable bucket is built from — never a reason to substitute another
+ * repo.
+ *
+ * @param {string|null|undefined} slug
+ * @returns {{ owner: string, repo: string } | null}
+ */
+export function parseRepoSlug(slug) {
+  if (typeof slug !== 'string') return null;
+  const parts = slug.trim().split('/');
+  if (parts.length !== 2) return null;
+  const [owner, repo] = parts;
+  if (!owner || !repo) return null;
+  return { owner, repo };
+}
+
+/**
+ * Render a `{ owner, repo }` pair back to its slug, or `null` when the pair
+ * is absent/malformed.
+ *
+ * @param {{ owner?: string, repo?: string }|null|undefined} repo
+ * @returns {string|null}
+ */
+export function formatRepoSlug(repo) {
+  if (!repo || typeof repo !== 'object') return null;
+  const { owner, repo: name } = /** @type {{owner?: string, repo?: string}} */ (
+    repo
+  );
+  if (typeof owner !== 'string' || typeof name !== 'string') return null;
+  if (!owner.trim() || !name.trim()) return null;
+  return `${owner.trim()}/${name.trim()}`;
+}
+
+/**
+ * Resolve every ownership bucket from a resolved `.agentrc` config.
+ *
+ * `framework` falls back to {@link DEFAULT_FRAMEWORK_REPO}; `platform` has no
+ * default and stays `null` when unconfigured; `consumer` is `null` when
+ * `github.owner`/`github.repo` are unset. A `null` bucket is an honest
+ * "unknown", which {@link routeOwnership} turns into a named, reportable
+ * outcome.
+ *
+ * @param {object} [config] — resolved `.agentrc` config.
+ * @returns {{ consumer: ({owner: string, repo: string}|null), framework: ({owner: string, repo: string}|null), platform: ({owner: string, repo: string}|null) }}
+ */
+export function resolveOwnershipRepos(config) {
+  const github = config?.github ?? {};
+  const followUp = github?.followUpRepos ?? {};
+  const owner = typeof github.owner === 'string' ? github.owner.trim() : '';
+  const repo = typeof github.repo === 'string' ? github.repo.trim() : '';
+  return {
+    consumer: owner && repo ? { owner, repo } : null,
+    framework:
+      parseRepoSlug(followUp.framework) ??
+      parseRepoSlug(DEFAULT_FRAMEWORK_REPO),
+    platform: parseRepoSlug(followUp.platform),
+  };
+}
+
+/**
+ * Route one ownership bucket to the repository its work belongs in.
+ *
+ * Total: an unknown bucket, an absent repos map, and an unconfigured bucket
+ * all resolve to `routable: false` with the `missingKey` that would fix it —
+ * never to a substituted repository.
+ *
+ * @param {object} opts
+ * @param {string} opts.bucket — one of {@link OWNERSHIP_BUCKETS}.
+ * @param {{consumer?: object|null, framework?: object|null, platform?: object|null}} opts.repos
+ *   — resolved buckets, from {@link resolveOwnershipRepos} or assembled by a
+ *   caller that already holds the repo objects.
+ * @param {{owner: string, repo: string}|null} [opts.currentRepo] — the repo
+ *   the run is standing in, used only to report `crossRepo`.
+ * @returns {{ bucket: string, routedRepo: ({owner: string, repo: string}|null), routable: boolean, missingKey: (string|null), crossRepo: boolean }}
+ */
+export function routeOwnership({ bucket, repos, currentRepo = null } = {}) {
+  const known = OWNERSHIP_BUCKETS.includes(bucket);
+  const routedRepo = known ? (repos?.[bucket] ?? null) : null;
+  const routable = Boolean(routedRepo?.owner && routedRepo?.repo);
+  const missingKey = routable
+    ? null
+    : (OWNERSHIP_CONFIG_KEYS[bucket] ?? `unknown ownership bucket "${bucket}"`);
+  const crossRepo =
+    routable &&
+    Boolean(currentRepo) &&
+    (routedRepo.owner !== currentRepo.owner ||
+      routedRepo.repo !== currentRepo.repo);
+  return { bucket, routedRepo, routable, missingKey, crossRepo };
+}

package/.agents/scripts/lib/label-constants.js

@@ -119,7 +119,11 @@ export const ACCEPTANCE_NA = ACCEPTANCE_LABELS.N_A;
  * loop). `meta::framework-gap` is applied to issues that surface a defect or
  * missing capability in the framework itself; `meta::consumer-improvement`
  * is applied to issues that surface improvements to a consumer project
- * (workflow tweaks, ergonomic asks, doc polish). The `/mandrel-plan` Phase 0
+ * (workflow tweaks, ergonomic asks, doc polish); `meta::platform-gap` is
+ * applied to issues owned by neither — a shared base config, a runner fleet,
+ * a cross-repo toolchain. The three mirror the ownership buckets in
+ * `lib/github/framework-repo.js`, so a routed filing's label and its
+ * destination repository cannot disagree. The `/mandrel-plan` Phase 0
  * fetcher (see `lib/feedback-loop/prior-feedback-fetcher.js`) reads open
  * issues carrying either label and surfaces them to the planner so retro
  * signals are routed into durable substrates rather than lost in chat.
@@ -127,6 +131,7 @@ export const ACCEPTANCE_NA = ACCEPTANCE_LABELS.N_A;
 export const META_LABELS = {
   FRAMEWORK_GAP: 'meta::framework-gap',
   CONSUMER_IMPROVEMENT: 'meta::consumer-improvement',
+  PLATFORM_GAP: 'meta::platform-gap',
 };
 
 /**

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -76,7 +76,7 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
    */
   TOOL_DEGRADED: 'tool-degraded',
   /**
-   * The light delivery path refused a scope — a suitability-gate `ask-operator`
+   * The light delivery path refused a scope — a suitability-gate escalation
    * or a blocked diff backstop. Story #4856 added it because neither rejection
    * emitted anything, so an over-tight ceiling could only reach the framework
    * as anecdote; the roll-up aggregating these by category is what makes the

package/.agents/scripts/lib/observability/source-classifier.js

@@ -107,6 +107,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-workflow-citations.js',
   'check-workflow-cli-lint.js',
   'check-workflow-timeouts.js',
+  'ceremony-derive.js',
   'cleanup-repo-test-temp.js',
   'coverage-capture.js',
   'deliver-light.js',
@@ -115,6 +116,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'diagnose.js',
   'drain-pending-cleanup.js',
   'evidence-gate.js',
+  'file-ci-gap.js',
   'generate-config-docs.js',
   'generate-lens-checklists.js',
   'generate-skills-index.js',

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -43,11 +43,12 @@
  *                  The Story escalates to `agent::blocked`; it never
  *                  silently proceeds to close.
  *
- * ## The undisableable cap
+ * ## The cap
  *
- * `maxRounds` arrives already clamped by `lib/config/acceptance-eval.js`
- * into `[1, ceiling]`, but this reducer defends the invariant a second
- * time: a non-positive or non-integer cap is coerced to 1, so there is no
+ * `maxRounds` arrives normalized by `lib/config/acceptance-eval.js` as a
+ * non-negative integer (Story #5313: `0` means "score once, no redraft").
+ * This reducer maps that onto an effective cap of scored rounds: a cap of
+ * `0`, a negative value or a non-integer is coerced to 1, so there is no
  * input — config or verdict — that yields an unbounded `redraft` chain.
  * When `round >= effectiveCap` and criteria remain unmet, the only
  * possible action is `block`.

package/.agents/scripts/lib/orchestration/ceremony-routing.js

@@ -19,10 +19,10 @@
  *
  * ## Ceremony profiles (`delivery.routing.ceremonyProfile`)
  *
- *   - `minimal`  — always `inline` (skip fresh critic + sampling floor).
+ *   - `minimal`  — always `inline` (no fresh critic spawn).
  *                  Use for tiny N=1 Stories the operator trusts.
- *   - `standard` — level-routed (default). Low → inline (+ sampling floor);
- *                  high → fresh.
+ *   - `standard` — level-routed (default). Low → inline; high or
+ *                  underivable → fresh.
  *   - `strict`   — always `fresh` regardless of the derived level.
  *
  * ## The load-bearing invariant (M4-B acceptance floor — DO NOT VIOLATE)
@@ -51,9 +51,7 @@
  *
  *   - `high` level       → `fresh`   (a sensitive path was touched — a
  *                                     fresh-context maker-blind spawn).
- *   - `low` level        → `inline`  (the contract-identical inline critic),
- *                                     UNLESS the maker-checker sampling floor
- *                                     selects this cluster → `fresh`.
+ *   - `low` level        → `inline`  (the contract-identical inline critic).
  *   - missing / unknown  → `fresh`   (fail-safe: the diff could not be
  *                                     enumerated, so there is no evidence the
  *                                     change is unremarkable; treat it as
@@ -61,15 +59,14 @@
  *                                     exactly as `resolveDepth` degrades to
  *                                     `standard` on the same signal).
  *
- * ## Maker-checker sampling floor
+ * ## No sampling floor (Story #5313)
  *
- * Even at a `low` derived level under `standard`, a fraction of clusters
- * (`freshCriticSampleRate`, default 0.2) is forced `fresh` so a low level never
- * means zero independent checking. The selection is **deterministic** in the
- * cluster index (a fixed stride), so it is stable across re-runs and —
- * critically — never changes the cluster count: it only re-labels which of
- * the fixed set of clusters run fresh. Profiles `minimal` and `strict`
- * ignore the sampling floor.
+ * The maker-checker sampling floor (`delivery.routing.freshCriticSampleRate`,
+ * `sampledFresh`) bounded independent checking by a cluster-index stride —
+ * a count, not a risk signal — and was retired with the delivery diet. The
+ * standard profile now routes purely off the derived level, so the decision
+ * carries no `sampled` field and `clusterIndex` is accepted only for call-site
+ * compatibility (it never changes the outcome).
  *
  * Pure and total: inputs in, decision out. No I/O, no throws. `null` /
  * `undefined` / malformed inputs degrade to `fresh` + `full` ceremony.
@@ -119,49 +116,19 @@ function normalizeCeremonyProfile(value) {
 }
 
 /**
- * Decide whether the sampling floor forces this low-risk cluster fresh.
- *
- * Deterministic in the cluster index: with rate `r` (0 < r ≤ 1) the stride is
- * `round(1 / r)` and every `stride`-th cluster (0-based indices 0, stride,
- * 2·stride, …) is forced fresh, yielding ≈`r` of clusters fresh. `r <= 0`
- * disables the floor (no cluster forced); `r >= 1` forces every cluster.
- *
- * @param {number} clusterIndex  Zero-based cluster position (from the
- *   caller-owned fan-out — an INPUT, never mutated here).
- * @param {number} rate          Sampling rate, already clamped into [0, 1] by
- *   `getDeliveryRouting`.
- * @returns {boolean} `true` when the floor forces this cluster fresh.
- */
-export function sampledFresh(clusterIndex, rate) {
-  if (typeof rate !== 'number' || !Number.isFinite(rate) || rate <= 0) {
-    return false;
-  }
-  if (rate >= 1) return true;
-  const idx =
-    typeof clusterIndex === 'number' &&
-    Number.isInteger(clusterIndex) &&
-    clusterIndex >= 0
-      ? clusterIndex
-      : 0;
-  const stride = Math.max(1, Math.round(1 / rate));
-  return idx % stride === 0;
-}
-
-/**
- * Resolve the acceptance ceremony for one cluster from the ceremony profile,
- * the derived change level, and the maker-checker sampling floor. See the
- * module header for the tier rules and the untouchable cluster-count invariant.
+ * Resolve the acceptance ceremony for one cluster from the ceremony profile
+ * and the derived change level. See the module header for the tier rules and
+ * the untouchable cluster-count invariant.
  *
  * @param {{
  *   derivedLevel?: (ChangeLevel|string|null|undefined),
  *   clusterIndex?: (number|null|undefined),
- *   freshCriticSampleRate?: (number|null|undefined),
  *   ceremonyProfile?: (CeremonyProfile|string|null|undefined),
- * }} [input]
+ * }} [input] `clusterIndex` is accepted for call-site compatibility only
+ *   (Story #5313 retired the sampling floor that read it).
  * @returns {{
  *   mode: CeremonyMode,
  *   reason: string,
- *   sampled: boolean,
  *   profile: CeremonyProfile,
  *   verdictOwner: VerdictOwner,
  * }}
@@ -172,27 +139,20 @@ export function resolveCeremonyForRisk(input = {}) {
 }
 
 /**
- * Internal mode/reason resolution — the tier rules and sampling floor.
- * `resolveCeremonyForRisk` decorates the result with the single
- * `verdictOwner` derived from the mode (Story #4723).
+ * Internal mode/reason resolution — the tier rules. `resolveCeremonyForRisk`
+ * decorates the result with the single `verdictOwner` derived from the mode
+ * (Story #4723).
  *
  * @param {Parameters<typeof resolveCeremonyForRisk>[0]} [input]
  * @returns {{
  *   mode: CeremonyMode,
  *   reason: string,
- *   sampled: boolean,
  *   profile: CeremonyProfile,
  * }}
  */
 function resolveCeremonyDecision(input = {}) {
   const derivedLevel =
     input && typeof input === 'object' ? input.derivedLevel : undefined;
-  const clusterIndex =
-    input && typeof input === 'object' ? input.clusterIndex : undefined;
-  const rate =
-    input && typeof input === 'object'
-      ? input.freshCriticSampleRate
-      : undefined;
   const profile = normalizeCeremonyProfile(
     input && typeof input === 'object' ? input.ceremonyProfile : undefined,
   );
@@ -201,7 +161,6 @@ function resolveCeremonyDecision(input = {}) {
     return {
       mode: 'inline',
       reason: 'ceremonyProfile=minimal: inline critic (no fresh spawn)',
-      sampled: false,
       profile,
     };
   }
@@ -209,7 +168,6 @@ function resolveCeremonyDecision(input = {}) {
     return {
       mode: 'fresh',
       reason: 'ceremonyProfile=strict: fresh-context critic',
-      sampled: false,
       profile,
     };
   }
@@ -218,24 +176,13 @@ function resolveCeremonyDecision(input = {}) {
     return {
       mode: 'fresh',
       reason: 'sensitive path touched: fresh-context critic',
-      sampled: false,
       profile,
     };
   }
   if (derivedLevel === 'low') {
-    if (sampledFresh(clusterIndex, rate)) {
-      return {
-        mode: 'fresh',
-        reason:
-          'low-level cluster forced fresh by the maker-checker sampling floor',
-        sampled: true,
-        profile,
-      };
-    }
     return {
       mode: 'inline',
       reason: 'no sensitive path touched: contract-identical inline critic',
-      sampled: false,
       profile,
     };
   }
@@ -245,7 +192,6 @@ function resolveCeremonyDecision(input = {}) {
     mode: 'fresh',
     reason:
       'change level underivable: fail-safe fresh-context critic + full ceremony',
-    sampled: false,
     profile,
   };
 }