mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/orchestration/audit-lens-routing.js

@@ -0,0 +1,128 @@
+/**
+ * audit-lens-routing.js — risk-envelope → audit-lens roster helpers.
+ *
+ * Extracted from `code-review.js` so the review runner stays focused on
+ * executing a review pass, while callers that only need risk→lens mapping
+ * (ceremony routing, plan-run epilogue consumers, unit tests) import a
+ * smaller pure module.
+ */
+
+import { selectAuditStrategy } from '../dynamic-workflow/capability.js';
+
+/**
+ * The axes whose presence (at `high` risk) routes a specific post-delivery
+ * audit lens. Mirrors the audit-workflow names under
+ * `.agents/workflows/audit-*.md`. Story #3939 broadened the routing so every
+ * high-risk REQUIRED axis maps to a lens rather than leaving three of them
+ * (`data-migration`, `destructive-mutation`, `billing`) routing nothing:
+ *
+ *   - `security`             → `audit-security`     (auth/secret boundary)
+ *   - `public-api`           → `audit-architecture` (the canonical
+ *                              architectural axis; a breaking public surface)
+ *   - `data-migration`       → `audit-quality`      (migration correctness +
+ *                              regression coverage)
+ *   - `destructive-mutation` → `audit-security`     (irreversible mutation is
+ *                              an auth/abuse boundary; co-routes with
+ *                              `security`, de-duplicated)
+ *   - `billing`              → `audit-privacy`      (money + the PII/consent
+ *                              surface that travels with it)
+ *   - `critical-workflow`    → `audit-quality`      (the load-bearing path
+ *                              warrants the deepest coverage pass)
+ *
+ * The `visible-behavior` axis intentionally routes NO lens: it forces the
+ * acceptance-spec disposition at plan time and no audit lens maps cleanly to
+ * it. Any other axis (or a low/medium-risk axis) contributes no lens.
+ *
+ * Every key here MUST be a value in the `axis` enum of
+ * `.agents/schemas/risk-verdict.schema.json` — the verdict-derived envelope
+ * can only ever carry schema-valid axes, so a key absent from that enum is
+ * unreachable dead routing (Story #3889 removed the unreachable
+ * `architecture` key; the architectural axis is `public-api`).
+ */
+const AXIS_TO_LENS = Object.freeze({
+  security: 'audit-security',
+  'public-api': 'audit-architecture',
+  'data-migration': 'audit-quality',
+  'destructive-mutation': 'audit-security',
+  billing: 'audit-privacy',
+  'critical-workflow': 'audit-quality',
+});
+
+/**
+ * Stable output order for routed lenses so the lens list is deterministic
+ * regardless of axis ordering in the verdict. Every lens any axis can route
+ * appears here exactly once; `resolveAuditLenses` filters this canonical
+ * order down to the matched set (Story #3939).
+ */
+const LENS_ORDER = Object.freeze([
+  'audit-security',
+  'audit-architecture',
+  'audit-quality',
+  'audit-privacy',
+]);
+
+/**
+ * Resolve the set of post-delivery audit lenses a judged risk envelope routes.
+ *
+ * High-risk axes map to their audit lens via {@link AXIS_TO_LENS}; only axes
+ * judged `high` contribute (a `low`/`medium` axis carries no lens). The result
+ * is de-duplicated and stably ordered by {@link LENS_ORDER} so an envelope
+ * listing the `public-api` axis more than once routes `['audit-architecture']`
+ * once, not twice — and two distinct axes routing the same lens (e.g.
+ * `security` + `destructive-mutation` both → `audit-security`) collapse to a
+ * single entry. A low-risk envelope — or any envelope with no high-risk routed
+ * axis — resolves to an empty array (no lens beyond the existing baseline
+ * gates).
+ *
+ * Pure function — no I/O, no side effects.
+ *
+ * @param {{ axes?: Array<{ axis?: string, level?: string }> }} [envelope]
+ * @returns {string[]} Ordered, de-duplicated audit-lens identifiers.
+ */
+export function resolveAuditLenses(envelope = {}) {
+  const axes = Array.isArray(envelope?.axes) ? envelope.axes : [];
+  const matched = new Set();
+  for (const entry of axes) {
+    if (!entry || entry.level !== 'high') continue;
+    const lens = AXIS_TO_LENS[entry.axis];
+    if (lens) matched.add(lens);
+  }
+  return LENS_ORDER.filter((lens) => matched.has(lens));
+}
+
+/**
+ * Build the post-delivery audit-lens execution plan for a judged risk
+ * envelope. Each routed lens (see {@link resolveAuditLenses}) is paired with a
+ * strategy decision from the **existing** `selectAuditStrategy` engine — no new
+ * audit machinery is introduced. A low-risk envelope resolves to an empty
+ * `lenses` array and runs no audit beyond the baseline gates (Story #3876).
+ *
+ * Pure with respect to the injected `selectAuditStrategyFn` (default is the
+ * shared dynamic-workflow engine, which is itself pure over its snapshot).
+ *
+ * @param {{ axes?: Array<{ axis?: string, level?: string }> }} [envelope]
+ * @param {{
+ *   snapshot?: object,
+ *   forceStrategy?: ('orchestrated'|'sequential'|null),
+ *   selectAuditStrategyFn?: typeof selectAuditStrategy,
+ * }} [opts]
+ * @returns {{ lenses: string[], plan: Array<{ lens: string, strategy: string, reason: string, forced: boolean }> }}
+ */
+export function planAuditLenses(envelope = {}, opts = {}) {
+  const {
+    snapshot = {},
+    forceStrategy = null,
+    selectAuditStrategyFn = selectAuditStrategy,
+  } = opts;
+  const lenses = resolveAuditLenses(envelope);
+  const plan = lenses.map((lens) => {
+    const decision = selectAuditStrategyFn({ snapshot, forceStrategy });
+    return {
+      lens,
+      strategy: decision.strategy,
+      reason: decision.reason,
+      forced: decision.forced,
+    };
+  });
+  return { lenses, plan };
+}

package/.agents/scripts/lib/orchestration/bookkeeping-outbox.js

@@ -0,0 +1,273 @@
+/**
+ * bookkeeping-outbox.js — Epic #4476 (M5): buffered GitHub bookkeeping.
+ *
+ * Delivery bookkeeping — structured-comment upserts (progress, friction,
+ * wave-stall, …) and `agent::*` label flips — is human-visible surface that,
+ * in an **unattended** (`--yes` / headless) run, no operator is watching in
+ * real time. Emitting each one as a live GitHub round-trip mid-run costs an
+ * LLM turn per transition for a surface nobody reads until the run finishes.
+ *
+ * This module lets those non-urgent mutations be **buffered to a local NDJSON
+ * outbox** during the run and **reconciled to GitHub once at finalize**.
+ * GitHub stays the source of truth *at rest* (post-reconcile); only the
+ * per-transition chatter moves off the token stream. The outbox file survives
+ * a crash, so crash recovery drains whatever was buffered before the finalize
+ * reconcile ran.
+ *
+ * ## What is NEVER buffered
+ * The `agent::blocked` HITL gate (`.agents/instructions.md` §1.J) is the single
+ * authoritative runtime pause point. A genuine blocker MUST surface on GitHub
+ * **immediately**, not batched to finalize — an operator can only resume a run
+ * they can see is blocked. The {@link transitionStateOrBuffer} facade forces
+ * `agent::blocked` (and any caller-marked `urgent`) transition through the
+ * live path regardless of headless mode.
+ *
+ * ## Attended runs are unchanged
+ * Buffering is gated on the explicit `headless` signal (Story #4427's
+ * `--headless`/`--yes` plumbing). An attended run passes `headless: false` and
+ * every comment/label posts live exactly as before — byte-for-byte behaviour.
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+
+import { runTempDir } from '../config/temp-paths.js';
+import { STATE_LABELS } from './ticketing/reads.js';
+import { upsertStructuredComment } from './ticketing/state.js';
+import { transitionTicketState } from './ticketing/transition.js';
+
+/** Canonical basename for the per-run bookkeeping outbox. */
+const OUTBOX_BASENAME = 'bookkeeping-outbox.ndjson';
+
+/**
+ * Resolve the canonical outbox path for a run:
+ * `temp/run-<id>/bookkeeping-outbox.ndjson`.
+ *
+ * Uses `runTempDir` directly; callers may still pass an `epicId`-named
+ * variable while the broader file/flag rename remains out of this pass.
+ *
+ * @param {number} epicId
+ * @param {object} [config] Resolved config (tempRoot).
+ * @returns {string}
+ */
+export function outboxPathFor(epicId, config) {
+  return path.join(runTempDir(epicId, config), OUTBOX_BASENAME);
+}
+
+/**
+ * Append one operation record to the outbox, creating the parent dir on
+ * demand. Best-effort at the storage layer is the caller's concern; here we
+ * let a genuine fs failure propagate so a mis-configured outbox path surfaces
+ * loudly in tests.
+ *
+ * @param {string} outboxPath
+ * @param {object} op
+ */
+function appendOp(outboxPath, op) {
+  mkdirSync(path.dirname(outboxPath), { recursive: true });
+  appendFileSync(outboxPath, `${JSON.stringify(op)}\n`, 'utf8');
+}
+
+/**
+ * Buffer a structured-comment upsert. The op captures everything
+ * `upsertStructuredComment` needs at drain time so the reconcile is a pure
+ * replay with no re-derivation.
+ *
+ * @param {{ outboxPath: string, ticketId: number, marker: string,
+ *           body: string, attrs?: Record<string, string|number>|null,
+ *           ts?: string }} args
+ */
+export function enqueueComment({
+  outboxPath,
+  ticketId,
+  marker,
+  body,
+  attrs = null,
+  ts = new Date().toISOString(),
+}) {
+  appendOp(outboxPath, {
+    kind: 'comment',
+    ts,
+    ticketId,
+    marker,
+    body,
+    ...(attrs ? { attrs } : {}),
+  });
+}
+
+/**
+ * Buffer an `agent::*` label transition.
+ *
+ * @param {{ outboxPath: string, ticketId: number, state: string,
+ *           ts?: string }} args
+ */
+export function enqueueLabel({
+  outboxPath,
+  ticketId,
+  state,
+  ts = new Date().toISOString(),
+}) {
+  appendOp(outboxPath, { kind: 'label', ts, ticketId, state });
+}
+
+/**
+ * Parse the outbox into an ordered array of operation records. Malformed
+ * lines are skipped (never throw). A missing / empty outbox yields `[]`.
+ *
+ * @param {string} outboxPath
+ * @returns {Array<object>}
+ */
+export function readOutbox(outboxPath) {
+  if (!outboxPath || !existsSync(outboxPath)) return [];
+  let raw;
+  try {
+    raw = readFileSync(outboxPath, 'utf8');
+  } catch {
+    return [];
+  }
+  if (!raw) return [];
+  const ops = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line) continue;
+    try {
+      const op = JSON.parse(line);
+      if (op && typeof op === 'object') ops.push(op);
+    } catch {
+      // skip a torn / malformed line — a partial write from a crash is not
+      // fatal to the rest of the batch.
+    }
+  }
+  return ops;
+}
+
+/**
+ * Drain the outbox to GitHub in FIFO order and clear it on success. Both sink
+ * operations are idempotent (comment upserts are marker-scoped;
+ * `transitionTicketState` applies one state via the canonical
+ * remove-all-then-add path), so a re-run after a partial drain converges. A
+ * per-op failure is recorded and the drain continues — a single bad ticket
+ * must not strand the rest of the batch. The outbox file is only truncated
+ * when EVERY op succeeded, so a crash mid-drain leaves the un-applied
+ * remainder for the next reconcile.
+ *
+ * @param {{ outboxPath: string,
+ *           provider: import('../ITicketingProvider.js').ITicketingProvider,
+ *           logger?: { warn?: (m: string) => void } }} args
+ * @returns {Promise<{ drained: number, comments: number, labels: number,
+ *   errors: Array<{ op: object, error: string }>, cleared: boolean }>}
+ */
+export async function reconcileOutbox({ outboxPath, provider, logger }) {
+  const ops = readOutbox(outboxPath);
+  const result = {
+    drained: 0,
+    comments: 0,
+    labels: 0,
+    errors: [],
+    cleared: false,
+  };
+  if (ops.length === 0) {
+    result.cleared = true;
+    return result;
+  }
+
+  for (const op of ops) {
+    try {
+      if (op.kind === 'comment') {
+        await upsertStructuredComment(
+          provider,
+          op.ticketId,
+          op.marker,
+          op.body,
+          op.attrs ?? null,
+        );
+        result.comments += 1;
+        result.drained += 1;
+      } else if (op.kind === 'label') {
+        await transitionTicketState(provider, op.ticketId, op.state);
+        result.labels += 1;
+        result.drained += 1;
+      } else {
+        result.errors.push({ op, error: `unknown op kind "${op.kind}"` });
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      result.errors.push({ op, error: message });
+      logger?.warn?.(
+        `[bookkeeping-outbox] reconcile op failed (${op.kind} #${op.ticketId}): ${message}`,
+      );
+    }
+  }
+
+  // Only truncate when the whole batch landed — otherwise the un-applied
+  // ops must survive for the next reconcile (crash-recovery contract).
+  if (result.errors.length === 0) {
+    try {
+      writeFileSync(outboxPath, '', 'utf8');
+      result.cleared = true;
+    } catch {
+      // A clear failure is non-fatal: the ops all landed, and the idempotent
+      // sinks make a redundant re-drain a no-op.
+    }
+  }
+  return result;
+}
+
+/**
+ * Facade: post a structured comment live, OR buffer it to the outbox when the
+ * run is headless. Comments are never urgent (the operator reads them at
+ * finalize), so headless always buffers when an `outboxPath` is available.
+ *
+ * @param {{ provider: object, ticketId: number, marker: string, body: string,
+ *           attrs?: Record<string, string|number>|null, headless?: boolean,
+ *           outboxPath?: string|null }} args
+ * @returns {Promise<{ buffered: boolean }>}
+ */
+export async function postCommentOrBuffer({
+  provider,
+  ticketId,
+  marker,
+  body,
+  attrs = null,
+  headless = false,
+  outboxPath = null,
+}) {
+  if (headless && outboxPath) {
+    enqueueComment({ outboxPath, ticketId, marker, body, attrs });
+    return { buffered: true };
+  }
+  await upsertStructuredComment(provider, ticketId, marker, body, attrs);
+  return { buffered: false };
+}
+
+/**
+ * Facade: flip an `agent::*` state live, OR buffer it when headless — EXCEPT
+ * `agent::blocked` (and any caller-marked `urgent` flip), which ALWAYS goes
+ * live so the HITL gate surfaces immediately (§1.J).
+ *
+ * @param {{ provider: object, ticketId: number, state: string,
+ *           headless?: boolean, outboxPath?: string|null,
+ *           urgent?: boolean }} args
+ * @returns {Promise<{ buffered: boolean }>}
+ */
+export async function transitionStateOrBuffer({
+  provider,
+  ticketId,
+  state,
+  headless = false,
+  outboxPath = null,
+  urgent = false,
+}) {
+  const mustSurfaceNow = urgent || state === STATE_LABELS.BLOCKED;
+  if (headless && outboxPath && !mustSurfaceNow) {
+    enqueueLabel({ outboxPath, ticketId, state });
+    return { buffered: true };
+  }
+  await transitionTicketState(provider, ticketId, state);
+  return { buffered: false };
+}

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

@@ -0,0 +1,204 @@
+/**
+ * lib/orchestration/ceremony-routing.js — ceremony-profile + risk-routed
+ * acceptance ceremony resolver.
+ *
+ * The sibling of `review-depth.js` (risk → review depth) and
+ * `audit-lens-routing.js#resolveAuditLenses` (risk → audit lens): it folds the
+ * operator ceremony profile and the planner-judged risk envelope into a
+ * per-cluster ceremony decision for the single-delivery acceptance critic —
+ * **fresh-context spawn** vs the contract-identical **inline** critic. It
+ * does NOT invent a new risk score and it does NOT own clustering.
+ *
+ * ## Ceremony profiles (`delivery.routing.ceremonyProfile`)
+ *
+ *   - `minimal`  — always `inline` (skip fresh critic + sampling floor).
+ *                  Use for tiny N=1 Stories the operator trusts.
+ *   - `standard` — risk-routed (default). Low → inline (+ sampling floor);
+ *                  medium/high → fresh.
+ *   - `strict`   — always `fresh` regardless of risk.
+ *
+ * ## The load-bearing invariant (M4-B acceptance floor — DO NOT VIOLATE)
+ *
+ * Risk-routing chooses fresh-vs-inline **PER CLUSTER**. It NEVER changes the
+ * cluster COUNT. The cluster count is `ceil(totalACs / clusterCeiling)` with
+ * the non-disableable `[1, 8]` clamp, owned entirely by
+ * `acceptance-clusters.js` and untouched here. A low-risk Story still gets one
+ * verdict per cluster — just possibly authored inline instead of by a fresh
+ * sub-agent. This module takes the cluster index as an INPUT and returns a
+ * decision for that one cluster; it has no way to add or remove clusters.
+ *
+ * ## Tier rules (per cluster, `standard` profile)
+ *
+ *   - `high` risk        → `fresh`   (a fresh-context maker-blind spawn).
+ *   - `medium` risk      → `fresh`   (fail toward more ceremony, never less —
+ *                                     matches `review-depth`'s fail-to-middle).
+ *   - `low` risk         → `inline`  (the contract-identical inline critic),
+ *                                     UNLESS the maker-checker sampling floor
+ *                                     selects this cluster → `fresh`.
+ *   - missing / unknown  → `fresh`   (fail-safe: a Story that skipped `/plan`
+ *                                     has no risk verdict; treat it as needing
+ *                                     the full fresh-context ceremony, exactly
+ *                                     as `review-depth` degrades to `standard`
+ *                                     and `deriveRiskEnvelope` degrades to
+ *                                     review-required).
+ *
+ * ## Maker-checker sampling floor
+ *
+ * Even at `low` risk under `standard`, a fraction of clusters
+ * (`freshCriticSampleRate`, default 0.2) is forced `fresh` so low risk 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.
+ *
+ * Pure and total: inputs in, decision out. No I/O, no throws. `null` /
+ * `undefined` / malformed inputs degrade to `fresh` + `full` ceremony.
+ *
+ * @typedef {'fresh'|'inline'} CeremonyMode
+ * @typedef {'low'|'medium'|'high'} RiskLevel
+ * @typedef {'minimal'|'standard'|'strict'} CeremonyProfile
+ */
+
+/** @type {readonly CeremonyProfile[]} */
+export const CEREMONY_PROFILES = Object.freeze([
+  'minimal',
+  'standard',
+  'strict',
+]);
+
+/**
+ * Normalize an operator/config ceremony profile. Unknown values degrade to
+ * `standard` (fail toward the documented default, not toward less ceremony).
+ *
+ * @param {unknown} value
+ * @returns {CeremonyProfile}
+ */
+export function normalizeCeremonyProfile(value) {
+  if (value === 'minimal' || value === 'standard' || value === 'strict') {
+    return value;
+  }
+  return 'standard';
+}
+
+/**
+ * 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 fixed
+ *   `ceil(totalACs / clusterCeiling)` 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,
+ * judged risk level, and the maker-checker sampling floor. See the module
+ * header for the tier rules and the untouchable cluster-count invariant.
+ *
+ * @param {{
+ *   overallLevel?: (RiskLevel|string|null|undefined),
+ *   clusterIndex?: (number|null|undefined),
+ *   freshCriticSampleRate?: (number|null|undefined),
+ *   ceremonyProfile?: (CeremonyProfile|string|null|undefined),
+ * }} [input]
+ * @returns {{
+ *   mode: CeremonyMode,
+ *   reason: string,
+ *   sampled: boolean,
+ *   profile: CeremonyProfile,
+ * }}
+ */
+export function resolveCeremonyForRisk(input = {}) {
+  const overallLevel =
+    input && typeof input === 'object' ? input.overallLevel : 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,
+  );
+
+  if (profile === 'minimal') {
+    return {
+      mode: 'inline',
+      reason: 'ceremonyProfile=minimal: inline critic (no fresh spawn)',
+      sampled: false,
+      profile,
+    };
+  }
+  if (profile === 'strict') {
+    return {
+      mode: 'fresh',
+      reason: 'ceremonyProfile=strict: fresh-context critic',
+      sampled: false,
+      profile,
+    };
+  }
+
+  if (overallLevel === 'high') {
+    return {
+      mode: 'fresh',
+      reason: 'high-risk: fresh-context critic',
+      sampled: false,
+      profile,
+    };
+  }
+  if (overallLevel === 'medium') {
+    return {
+      mode: 'fresh',
+      reason: 'medium-risk: fresh-context critic (fail toward more ceremony)',
+      sampled: false,
+      profile,
+    };
+  }
+  if (overallLevel === 'low') {
+    if (sampledFresh(clusterIndex, rate)) {
+      return {
+        mode: 'fresh',
+        reason:
+          'low-risk cluster forced fresh by the maker-checker sampling floor',
+        sampled: true,
+        profile,
+      };
+    }
+    return {
+      mode: 'inline',
+      reason: 'low-risk: contract-identical inline critic',
+      sampled: false,
+      profile,
+    };
+  }
+  // Missing / unknown / malformed risk → fail-safe fresh + full ceremony,
+  // matching how review-depth.js and deriveRiskEnvelope degrade on an
+  // unjudged Story.
+  return {
+    mode: 'fresh',
+    reason:
+      'risk absent/unknown: fail-safe fresh-context critic + full ceremony',
+    sampled: false,
+    profile,
+  };
+}