Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

28.2 KB
Raw Blame
/**
 * Layered Intelligence — scope / execution awareness reports
 * (#2842 split of layeredIntelligence.js).
 *
 * The avoid/prefer signals derived from task-learning metrics and proposal
 * execution outcomes, the propose-well-but-execute-poorly cross-reference, and the
 * deterministic hand-off routing decision (auto-hand-off vs file-for-human).
 */

import { EFFECTIVE_RATE_MIN_WINDOW_SAMPLES } from '../taskLearning/store.js';
import { summarizeExecutionFailures, formatExecutionFailure } from '../layeredIntelligenceExecutionFailures.js';
import {
  SCOPE_AWARENESS_MAX_TYPE_LEN, SCOPE_AWARENESS_MAX_PER_LIST, SCOPE_AWARENESS_MIN_SAMPLE,
  SCOPE_AVOID_SUCCESS_THRESHOLD, SCOPE_PREFER_SUCCESS_THRESHOLD,
  PROPOSAL_OUTCOMES, PROPOSAL_EXECUTION_OUTCOMES, PROPOSAL_EXECUTION_MIN_SAMPLE,
} from './constants.js';

/**
 * Clamp a task-type / proposal-domain label so one pathological key (e.g. a mission
 * task type embedding an unbounded mission name) can't blow the scope-awareness block
 * budget. Shared by both avoid/prefer signals below.
 */
export function clampScopeLabel(label) {
  return label.length > SCOPE_AWARENESS_MAX_TYPE_LEN
    ? `${label.slice(0, SCOPE_AWARENESS_MAX_TYPE_LEN - 1)}…`
    : label;
}

/**
 * Resolve an outcome record's grouping key: its trimmed `scope`, or `fallback` when the
 * record carries none. Every per-scope aggregator here needs this, and the `fallback`
 * is the one thing they legitimately disagree on — a report that must not invent a
 * bucket passes `null` and skips the record (computeExecutionByDomain,
 * computeCrossReferenceAnalysis), while a breakdown that must account for every record
 * passes the default `'unknown'` (computePostApprovalCompletion,
 * computeProposalOutcomeMetrics). Keeping the predicate in one place means the four
 * groupings can't drift on what counts as a scope — which would silently split one
 * scope's records across two buckets.
 */
export function scopeKeyOf(record, fallback = 'unknown') {
  const scope = record?.scope;
  return typeof scope === 'string' && scope.trim() ? scope.trim() : fallback;
}

/**
 * Render an avoid/prefer prompt block from pre-classified item lists — the presentation
 * both scope-awareness signals share (#2760 install-wide task-type rates, #2765
 * per-proposal-domain execution rates). Owns the sort (worst-first avoid, best-first
 * prefer), the per-list cap + "…and N more" overflow, and the empty-guard, so a tweak
 * to any of those lands in one place. Callers supply their own classified `avoid`/
 * `prefer` lists, the per-item `fmt`, and the two headers — the only parts that
 * legitimately differ between the two signals. Returns '' when both lists are empty.
 */
function renderAvoidPreferSections({ avoid = [], prefer = [], fmt, avoidHeader, preferHeader }) {
  if (!avoid.length && !prefer.length) return '';
  avoid.sort((a, b) => a.rate - b.rate);  // worst-first — sharpest signal at the top
  prefer.sort((a, b) => b.rate - a.rate); // best-first
  const section = (header, items) => {
    const shown = items.slice(0, SCOPE_AWARENESS_MAX_PER_LIST);
    const more = items.length - shown.length;
    const lines = shown.map(fmt);
    if (more > 0) lines.push(`- …and ${more} more`);
    return `${header}\n${lines.join('\n')}`;
  };
  const sections = [];
  if (avoid.length) sections.push(section(avoidHeader, avoid));
  if (prefer.length) sections.push(section(preferHeader, prefer));
  return sections.join('\n\n');
}

/**
 * Scope-awareness report (#2760). Classifies each CoS task TYPE by its completion rate
 * into low-completion and high-completion lists, as directional context for the
 * reasoner. Pure — takes the already-parsed per-type metrics map (the `summary`
 * gatherSources builds from learning.byTaskType) and returns a report string, or ''
 * when no type has enough runs to qualify either way.
 *
 * IMPORTANT (codex P1): this is per-task-TYPE, install-wide completion telemetry — NOT
 * a per-proposal execution record. An LI proposal is later implemented through a
 * claim/plan/handoff task whose task type does NOT carry the proposal's domain (a
 * handoff becomes `internal-task`; a claimed issue runs under the claim task type), so
 * these buckets are populated by independently-scheduled jobs, not by LI's own
 * proposals bucketed by subject. The block is therefore framed as "work of this KIND
 * tends to (not) get finished here" — useful directional context (especially LI's own
 * reasoning-run type, self-improve:layered-intelligence, which IS LI's execution) — and
 * deliberately NOT a claim that a given proposal maps 1:1 onto a listed type. Proper
 * per-proposal-domain outcome correlation is tracked as a follow-up (#2765).
 *
 * `metricsByType[type] = { lifetimeSuccessRate, lifetimeCompleted, recentSuccessRate, recentCompleted, ... }`.
 *
 * Classification judges on the EFFECTIVE rate — the recency-windowed rate when the
 * window has enough samples, else lifetime — NOT the raw lifetime rate. This matters
 * for the issue's "dynamic adjustment" requirement: the lifetime rate barely decays
 * (an old failure burst depresses it near-permanently), so a scope that has actually
 * recovered would stay stuck on the avoid list for dozens of runs. Using the windowed
 * rate lets a recovered scope leave "avoid" promptly — and, critically, this uses the
 * SAME window floor as the scheduler's own skip logic
 * (EFFECTIVE_RATE_MIN_WINDOW_SAMPLES, the threshold in computeEffectiveSuccessRate /
 * isSkipCandidate): the window is trusted only at >= that many in-window runs, so a
 * single noisy recent result can't flip a lifetime-reliable scope to avoid (or vice
 * versa). Below that floor the lifetime rate governs, exactly as the scheduler does,
 * so this advisory list moves in the same direction the scheduler acts on. The base
 * sample floor still gates on LIFETIME completed: a scope needs enough TOTAL evidence
 * to be judged at all. Each rendered rate is paired with the run count of the SAME
 * basis (windowed count when the window governs, lifetime count otherwise) so the
 * "N% over M runs" line never mixes a windowed rate with a lifetime count.
 *
 * The thresholds (50/75) are deliberately NOT the scheduler's 30% hard-skip line: this
 * steering is advisory (it nudges what LI PROPOSES, it never suppresses execution), so
 * a wider, more cautious net is correct here. LI still MAY propose in an avoid scope
 * when it is genuinely the highest-value work — it just has to justify doing so.
 */
export function computeScopeAwareness({ metricsByType = {} } = {}) {
  const avoid = [];
  const prefer = [];
  for (const [type, m] of Object.entries(metricsByType || {})) {
    const lifetimeN = m?.lifetimeCompleted || 0;
    if (lifetimeN < SCOPE_AWARENESS_MIN_SAMPLE) continue; // not enough total evidence to judge
    // Effective rate: trust the recency window ONLY when it carries enough samples —
    // the same EFFECTIVE_RATE_MIN_WINDOW_SAMPLES floor the scheduler's
    // computeEffectiveSuccessRate uses — so one noisy recent run can't flip a
    // lifetime-reliable scope. Below the floor (including an empty window, where
    // recentSuccessRate is null, not 0 — #2460), lifetime governs. Pair the rate with
    // the count of its own basis so the rendered "N% over M runs" is truthful.
    const useWindow = m?.recentCompleted >= EFFECTIVE_RATE_MIN_WINDOW_SAMPLES
      && typeof m?.recentSuccessRate === 'number';
    const rate = useWindow ? m.recentSuccessRate : m?.lifetimeSuccessRate;
    if (typeof rate !== 'number') continue; // a never-run scope stays neutral
    const n = useWindow ? m.recentCompleted : lifetimeN;
    if (rate < SCOPE_AVOID_SUCCESS_THRESHOLD) avoid.push({ type, rate, n });
    else if (rate >= SCOPE_PREFER_SUCCESS_THRESHOLD) prefer.push({ type, rate, n });
  }
  // Honest framing (#2760, codex P1): these are per-task-TYPE completion rates for the
  // whole install — NOT a per-proposal execution record. An LI proposal is implemented
  // through a claim/plan/handoff task whose type does not carry the proposal's domain,
  // so this is directional context ("work of this kind tends to (not) get finished
  // here"), not a claim that a given proposal maps 1:1 onto a listed type.
  return renderAvoidPreferSections({
    avoid,
    prefer,
    fmt: ({ type, rate, n }) => `- ${clampScopeLabel(type)}: ${Math.round(rate)}% completed over ${n} runs`,
    avoidHeader: `LOW-COMPLETION task types — work of this kind is finished below ${SCOPE_AVOID_SUCCESS_THRESHOLD}% of the time on this install:`,
    preferHeader: `HIGH-COMPLETION task types — finished at or above ${SCOPE_PREFER_SUCCESS_THRESHOLD}%:`
  });
}

/**
 * Aggregate LI proposal EXECUTION outcomes by proposal DOMAIN (scope) (#2765).
 * Pure. Unlike computeScopeAwareness — which borrows install-wide CoS
 * per-task-TYPE completion rates that a proposal only loosely maps onto — this is a
 * TRUE per-proposal record: each data point is one of LI's OWN filed proposals that
 * was handed off and executed, keyed by the domain (scope) it was proposed under.
 *
 * `outcomes` is the app's outcome records (from listOutcomes); only records carrying
 * a resolved `executionOutcome` AND a `scope` contribute. Returns
 * `{ [scope]: { completed, succeeded, successRate, failureSummary } }` (empty when
 * nothing has been executed yet). The acceptance signal for #2765: after one proposal
 * in domain X is executed, only X's bucket moves.
 *
 * `failureSummary` (#2764 §3) carries the per-domain execution-FAILURE taxonomy tally
 * so a low execution rate no longer arrives without its cause: it is the shared
 * `summarizeExecutionFailures` engine run over ONLY this domain's records (the engine
 * itself keeps just the failures), the "filter per-domain, then reuse the existing
 * summariser" join #2764 §3 asks for. Every bucket carries one — a domain with zero
 * failed hand-offs simply reports `total: 0`, the honest "nothing to explain" reading.
 */
export function computeExecutionByDomain(outcomes = []) {
  // Group each executed record by its domain first, so the failure taxonomy can be
  // tallied over that domain's OWN records rather than the install-wide set.
  const recordsByScope = new Map();
  for (const r of Array.isArray(outcomes) ? outcomes : []) {
    if (!r || typeof r !== 'object') continue;
    if (!PROPOSAL_EXECUTION_OUTCOMES.includes(r.executionOutcome)) continue;
    const scope = scopeKeyOf(r, null);
    if (!scope) continue;
    if (!recordsByScope.has(scope)) recordsByScope.set(scope, []);
    recordsByScope.get(scope).push(r);
  }
  // Null prototype: `scope` is an LLM-authored free string, and a "__proto__"
  // key on a plain object would silently rewrite the prototype instead of
  // adding a bucket — vanishing from Object.entries while lookups read the
  // prototype object.
  const byDomain = Object.create(null);
  for (const [scope, records] of recordsByScope) {
    const completed = records.length;
    const succeeded = records.filter(r => r.executionOutcome === 'success').length;
    byDomain[scope] = {
      completed,
      succeeded,
      successRate: Math.round((succeeded / completed) * 100),
      // Reuse the shared taxonomy engine on this domain's slice — it discards the
      // successes internally, so passing the whole slice yields this domain's own
      // failure shape without a second pre-filter here.
      failureSummary: summarizeExecutionFailures(records)
    };
  }
  return byDomain;
}

/**
 * Summarize a list of millisecond durations into the `{ count, averageMs, medianMs,
 * p90Ms, minMs, maxMs }` shape every LI duration report uses. Pure; shared by the
 * post-approval filed-to-completed durations and the approval-funnel time-to-decision
 * medians (#3120) so the two can never disagree on how a median or p90 is picked.
 *
 * The input is filtered to finite, non-negative values (a record with an unparseable
 * timestamp yields NaN and must not be laundered into a 0ms duration) and sorted, so
 * callers can pass raw differences. An EMPTY sample reports `count: 0` with NULL
 * statistics — the sentinel rule: "nothing has completed yet" is not "it completed
 * instantly". The median of an even-length sample is the rounded mean of the two middle
 * values; p90 is the nearest-rank value at ceil(n * 0.9).
 */
export function summarizeDurations(values = []) {
  const durations = (Array.isArray(values) ? values : [])
    .filter(value => Number.isFinite(value) && value >= 0)
    .sort((a, b) => a - b);
  if (durations.length === 0) {
    return { count: 0, averageMs: null, medianMs: null, p90Ms: null, minMs: null, maxMs: null };
  }
  const median = durations.length % 2 === 1
    ? durations[Math.floor(durations.length / 2)]
    : Math.round((durations[(durations.length / 2) - 1] + durations[durations.length / 2]) / 2);
  return {
    count: durations.length,
    averageMs: Math.round(durations.reduce((sum, value) => sum + value, 0) / durations.length),
    medianMs: median,
    p90Ms: durations[Math.max(0, Math.ceil(durations.length * 0.9) - 1)],
    minMs: durations[0],
    maxMs: durations.at(-1)
  };
}

/**
 * Summarize what happens after a proposal has been approved/merged. The existing
 * outcome store already persists both sides of this lifecycle: `outcome: 'merged'`
 * marks approval, while `executionOutcome` records the terminal LI hand-off result.
 * Keep this derivation pure so the prompt and dashboard cannot disagree about the
 * post-approval completion signal.
 *
 * Duration is measured from filing to a successful hand-off completion. That is the
 * only timestamp pair available for every tracker and remains meaningful when the
 * coding hand-off finishes before the tracker issue is reconciled as merged.
 *
 * TWO completion rates, deliberately (#3014) — they answer different questions and
 * conflating them hides the failure mode the metric exists to surface:
 *   - `completionRate`           = completed / ATTEMPTED (completed + abandoned).
 *     "Of the hand-offs that actually terminated, how many succeeded?" — the
 *     execution-quality read, which excludes work still in flight.
 *   - `approvalToCompletionRate` = completed / APPROVED (every merged proposal).
 *     "Of everything the user approved, how much has actually landed?" — the
 *     downstream-effectiveness read. It counts an approved proposal that was never
 *     handed off, or is stuck awaiting execution, as NOT completed, which is exactly
 *     the "approved but LOST" signal a rejection-only view cannot distinguish.
 * Both are `null` (not 0) when their denominator is zero — the sentinel rule: "nothing
 * has been approved / attempted yet" must not read as "everything failed".
 */
export function computePostApprovalCompletion(outcomes = []) {
  const approved = (Array.isArray(outcomes) ? outcomes : []).filter(record =>
    record && typeof record === 'object' && record.outcome === 'merged'
  );

  const summarize = (records) => {
    const completedRecords = records.filter(record => record.executionOutcome === 'success');
    const abandoned = records.filter(record => record.executionOutcome === 'failure').length;
    const completed = completedRecords.length;
    const attempted = completed + abandoned;
    const duration = summarizeDurations(
      completedRecords.map(record => Date.parse(record.executionAt) - Date.parse(record.filedAt))
    );
    return {
      approved: records.length,
      completed,
      abandoned,
      awaitingExecution: records.length - attempted,
      attempted,
      completionRate: attempted > 0 ? (completed / attempted) * 100 : null,
      // Approval → completion (#3014): denominator is every APPROVED proposal, so a
      // merged proposal that is stuck awaiting execution drags this down while leaving
      // `completionRate` untouched. Division-by-zero yields null, never 0.
      approvalToCompletionRate: records.length > 0 ? (completed / records.length) * 100 : null,
      duration
    };
  };

  const recordsByScope = new Map();
  for (const record of approved) {
    const scope = scopeKeyOf(record);
    const records = recordsByScope.get(scope) || [];
    records.push(record);
    recordsByScope.set(scope, records);
  }
  const byScope = Object.create(null);
  for (const [scope, records] of recordsByScope) byScope[scope] = summarize(records);

  return { ...summarize(approved), byScope };
}

/**
 * Render the dominant execution-failure causes from a domain's `failureSummary`
 * (#2764 §3) as a compact clause for the per-domain avoid line. Reuses the shared
 * `formatExecutionFailure` gloss so the wording matches the install-wide failure line
 * in computeOutcomesReport. Returns '' when the domain holds NO diagnosed failure — a
 * pure-`unknown`/`unclassified` (or failure-free) domain adds no cause clause rather
 * than a hollow "failed for unknown reasons" tail on every low-execution line.
 */
export function formatDominantFailureCause(failureSummary, limit = 2) {
  const entries = Array.isArray(failureSummary?.entries) ? failureSummary.entries : [];
  if (entries.length === 0) return '';
  const listed = entries
    .slice(0, limit)
    .map(({ category, count }) => `${formatExecutionFailure(category)} (${count})`)
    .join('; ');
  return `failing mostly on ${listed}`;
}

/**
 * Is this a proposal DOMAIN whose OWN hand-offs chronically fail — enough executed
 * hand-offs to be evidence (PROPOSAL_EXECUTION_MIN_SAMPLE) AND a success rate below
 * the coin-flip avoid line (SCOPE_AVOID_SUCCESS_THRESHOLD)? The single load-bearing
 * definition of "on the avoid list", shared so the reasoner-facing prompt
 * (computeProposalExecutionAwareness) and the deterministic hand-off gate
 * (computeHandoffRouting) can NEVER disagree about which domains qualify — the
 * design requires the prompt's avoid list and the gate to name the same set. Takes
 * a per-domain bucket from computeExecutionByDomain (or undefined when the domain
 * has no execution history → false).
 */
export function isAvoidDomain(bucket) {
  return !!bucket
    && bucket.completed >= PROPOSAL_EXECUTION_MIN_SAMPLE
    && bucket.successRate < SCOPE_AVOID_SUCCESS_THRESHOLD;
}

/**
 * Render the per-proposal-DOMAIN execution avoid/prefer split for the reasoning
 * prompt (#2765) — the real per-proposal signal the #2760 install-wide scope block
 * could only approximate. Returns '' when no domain clears the sample floor, so
 * buildPrompt omits the block. Mirrors computeScopeAwareness's 50/75 thresholds and
 * bounded rendering, but keys on the proposal's own scope and carries NO
 * "directional context only" caveat: this IS how LI's own proposals in each domain
 * fared, so the reasoner can steer toward domains it actually executes and away from
 * domains where its own hand-offs fail even after the proposal was accepted.
 */
export function computeProposalExecutionAwareness({ outcomes = [] } = {}) {
  const byDomain = computeExecutionByDomain(outcomes);
  const avoid = [];
  const prefer = [];
  for (const [scope, bucket] of Object.entries(byDomain)) {
    // The per-domain failure CAUSE (#2764 §3) is surfaced only for domains that clear
    // this floor — i.e. only where the domain is already listed as low-execution. A
    // single failed hand-off below the floor is the install-wide early-signal case the
    // "Why LI's own hand-offs failed" line in computeOutcomesReport already reports, so
    // we do not also emit a one-sample per-domain cause here (it would read as a trend
    // off n=1).
    if (bucket.completed < PROPOSAL_EXECUTION_MIN_SAMPLE) continue; // not enough executions to judge this domain
    if (isAvoidDomain(bucket)) avoid.push({ scope, rate: bucket.successRate, n: bucket.completed, cause: formatDominantFailureCause(bucket.failureSummary) });
    else if (bucket.successRate >= SCOPE_PREFER_SUCCESS_THRESHOLD) prefer.push({ scope, rate: bucket.successRate, n: bucket.completed });
  }
  return renderAvoidPreferSections({
    avoid,
    prefer,
    // Only the avoid list carries a `cause`; a preferred (reliably-executed) domain has
    // no failure shape worth naming, so its clause is simply absent.
    fmt: ({ scope, rate, n, cause }) => `- ${clampScopeLabel(scope)}: LI implemented ${rate}% of its own ${scope} proposals successfully over ${n} executed${cause ? ` — ${cause}` : ''}`,
    avoidHeader: `LOW-EXECUTION proposal domains — LI's OWN hand-offs in these domains succeed below ${SCOPE_AVOID_SUCCESS_THRESHOLD}% of the time; a proposal here needs a strong justification or a narrower slice:`,
    preferHeader: `HIGH-EXECUTION proposal domains — LI reliably implements its own proposals here (at or above ${SCOPE_PREFER_SUCCESS_THRESHOLD}%):`
  });
}

// Header for the cross-reference block (#2764 §3). Names the pattern the block exists
// to surface: a domain LI PROPOSES well (its proposals earn merges) yet EXECUTES
// poorly (its own hand-offs there fail), which neither liOutcomes (merge rate alone)
// nor liProposalExecution (execution rate alone) puts side by side.
const CROSS_REFERENCE_HEADER = "Domains where LI PROPOSES well but EXECUTES poorly — the proposal earns a merge, yet LI's OWN hand-off to implement it tends to fail with the named cause. These are blind spots: you pick the right work here but can't finish it as handed off. Narrow such a proposal to a slice an agent can complete, split it, or route it to a human — don't re-file the same shape expecting a different execution result:";

/**
 * Cross-reference MERGED-proposal success against EXECUTION-failure modes within the
 * SAME domain (#2764 §3). Pure + side-effect-free like the sibling report functions;
 * derives only from the outcome records already loaded (no new store read, no AI/tracker
 * call). The unique signal it adds over liOutcomes (per-scope merge rate) and
 * liProposalExecution (per-domain execution rate) is the CONTRAST between them: a domain
 * whose proposals the user merges but whose hand-offs then fail is "proposes well,
 * executes poorly" — the reasoner should keep proposing there but narrow the scope, not
 * abandon the domain (which a low execution rate read alone might imply).
 *
 * A domain qualifies only when BOTH signals are present: at least one MERGED proposal
 * (the "proposes well" side — otherwise the domain is just failing outright, which
 * liProposalExecution already covers) AND at least one DIAGNOSED failed hand-off (the
 * "executes poorly" side, with a concrete cause to name — a purely `unknown`/
 * `unclassified` failure history has no actionable mode to cross-reference). Merge rate
 * is measured over RESOLVED proposals only — the same denominator summarizeOutcomeStats
 * uses for its rawMergeRate (pending ≠ a merge verdict), not computeOutcomesReport's
 * per-scope rate, which divides by all filed. Sorted sharpest-execution-problem first;
 * bounded like the avoid/prefer lists. Returns '' when no domain qualifies, so
 * buildPrompt omits the block.
 */
export function computeCrossReferenceAnalysis({ outcomes = [] } = {}) {
  const records = Array.isArray(outcomes) ? outcomes : [];
  const byDomain = computeExecutionByDomain(records); // per-domain failure taxonomy (self-guards bad records)

  // Per-domain merge stats over RESOLVED proposals (pending ≠ a merge verdict).
  const mergeByScope = new Map();
  for (const o of records) {
    if (!o || typeof o !== 'object') continue;
    const scope = scopeKeyOf(o, null);
    if (!scope) continue;
    if (!PROPOSAL_OUTCOMES.includes(o.outcome)) continue; // unresolved: no verdict yet
    const agg = mergeByScope.get(scope) || { merged: 0, resolved: 0 };
    agg.resolved += 1;
    if (o.outcome === 'merged') agg.merged += 1;
    mergeByScope.set(scope, agg);
  }

  const qualifying = [];
  for (const [scope, exec] of Object.entries(byDomain)) {
    const merge = mergeByScope.get(scope);
    if (!merge || merge.merged < 1) continue; // "proposes well" side needs a merge
    const { entries, diagnosed, total: failTotal } = exec.failureSummary;
    if (diagnosed < 1) continue; // "executes poorly" side needs a diagnosed failed hand-off
    const top = entries[0];
    qualifying.push({
      scope,
      mergeRate: Math.round((merge.merged / merge.resolved) * 100),
      merged: merge.merged,
      resolved: merge.resolved,
      cause: top.category,
      causeCount: top.count,
      failTotal,
      diagnosed
    });
  }
  if (!qualifying.length) return '';
  // Sharpest execution problem first (most diagnosed failures), ties broken by the
  // strongest "proposes well" contrast (highest merge rate) so the output is stable.
  qualifying.sort((a, b) => b.diagnosed - a.diagnosed || b.mergeRate - a.mergeRate);
  const shown = qualifying.slice(0, SCOPE_AWARENESS_MAX_PER_LIST);
  const more = qualifying.length - shown.length;
  const lines = shown.map(q =>
    `- ${clampScopeLabel(q.scope)}: proposals merge at ${q.mergeRate}% (${q.merged}/${q.resolved}) but hand-offs here fail on ${q.cause} (${q.causeCount} of ${q.failTotal})`
  );
  if (more > 0) lines.push(`- …and ${more} more`);
  return `${CROSS_REFERENCE_HEADER}\n${lines.join('\n')}`;
}

/**
 * Deterministic hand-off routing gate (#2764 §4). Given a proposal and the app's
 * historical outcome records, decides whether a trivial+safe proposal may be
 * auto-handed-off to a coding agent NOW, or must instead be filed for a human —
 * because LI's OWN prior hand-offs in that domain chronically fail. This is the
 * SYSTEM-side enforcement of the same signal the reasoner is merely WARNED about
 * in the liProposalExecution / liCrossReference prompt blocks: even when the
 * reasoner marks a proposal trivial+safe, the gate suppresses the auto-hand-off
 * for a domain whose track record says the hand-off will just fail again.
 *
 * Pure + side-effect-free, like the sibling compute* report functions — derives
 * only from the `li-outcomes` records already loaded (no new AI/tracker/store
 * call). The just-filed proposal cannot skew this: computeExecutionByDomain only
 * counts records carrying a resolved `executionOutcome`, which a freshly-filed
 * proposal has not got yet.
 *
 * Shares the isAvoidDomain classifier with computeProposalExecutionAwareness so the
 * gate and the reasoner-facing prompt can NEVER disagree about which domains are
 * "chronically failing": a domain qualifies only when it has at least
 * PROPOSAL_EXECUTION_MIN_SAMPLE executed hand-offs AND its success rate is below
 * SCOPE_AVOID_SUCCESS_THRESHOLD — the SAME floor + threshold that puts a domain on
 * the reasoner's avoid list.
 *
 * Returns:
 *   - `{ handoff: true, reason: null }` — allow the auto-hand-off, when the
 *     proposal has no scope (can't judge), the domain is below the sample floor,
 *     the domain has no execution history, or its rate is at/above the threshold.
 *   - `{ handoff: false, domain, rate, n, cause, reason }` — SUPPRESS: file for a
 *     human instead. `reason` names the domain, rate, sample size, and (when a
 *     dominant failure cause is diagnosed) the cause — reusing formatDominantFailureCause,
 *     which returns '' for a purely unknown/unclassified domain so the cause clause
 *     is simply omitted there.
 *
 * @param {object} args
 * @param {object} args.proposal - the reasoner's proposal ({ scope, ... }).
 * @param {Array}  [args.outcomes] - the app's li-outcomes records.
 * @returns {{ handoff: boolean, reason: string|null, domain?: string, rate?: number, n?: number, cause?: string }}
 */
export function computeHandoffRouting({ proposal, outcomes = [] } = {}) {
  // No scope → we can't map the proposal to a domain's track record, so we can't
  // justify suppressing the hand-off. Allow, as before §4 existed.
  const domain = typeof proposal?.scope === 'string' && proposal.scope.trim() ? proposal.scope.trim() : null;
  if (!domain) return { handoff: true, reason: null };

  const byDomain = computeExecutionByDomain(outcomes);
  const bucket = byDomain[domain];
  // Below the floor, no bucket, or at/above the threshold → no signal to suppress on,
  // so allow the hand-off exactly as today. isAvoidDomain is the SAME predicate
  // computeProposalExecutionAwareness uses for its avoid list, so the gate and the
  // reasoner-facing prompt agree on which domains are "chronically failing".
  if (!isAvoidDomain(bucket)) return { handoff: true, reason: null };

  const cause = formatDominantFailureCause(bucket.failureSummary);
  const reason = `${domain} hand-offs succeed ${bucket.successRate}% over ${bucket.completed} executed — filing for human review instead of auto-hand-off${cause ? ` (${cause})` : ''}`;
  return { handoff: false, domain, rate: bucket.successRate, n: bucket.completed, cause, reason };
}