session-orchestrator 3.16.0

package/scripts/lib/gitlab-portfolio/markdown-writer.mjs

@@ -0,0 +1,289 @@
+/**
+ * markdown-writer.mjs — Render and write the GitLab Portfolio dashboard file.
+ *
+ * Exports:
+ *   GENERATOR_MARKER   — frontmatter sentinel
+ *   renderPortfolio    — pure render: Map<repo, summary> → markdown string
+ *   writePortfolio     — idempotent write with skip-handwritten / skip-noop / dry-run
+ *
+ * Skip-on-manual-edit: if the existing file's _generator is absent or differs,
+ * return { action: 'skipped-handwritten' } without writing.
+ *
+ * Skip-noop: if the rendered content (modulo the `updated:` timestamp) matches
+ * the existing content byte-for-byte, return { action: 'skipped-noop' }.
+ *
+ * Dry-run: when dryRun: true, never write; return { action: 'dry-run' }.
+ *
+ * Created-preservation: if the existing file has a `created:` frontmatter field,
+ * propagate it into the new render.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseFrontmatter } from '../vault-mirror/utils.mjs';
+
+/** Frontmatter sentinel that identifies generator-owned files. */
+export const GENERATOR_MARKER = 'session-orchestrator-gitlab-portfolio@1';
+
+/** Placeholder used for noop comparison (replaces the live `updated:` value). */
+const UPDATED_PLACEHOLDER = '__UPDATED_PLACEHOLDER__';
+
+// ── Formatting helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Format a Date as "YYYY-MM-DD HH:MM UTC".
+ *
+ * @param {Date} date
+ * @returns {string}
+ */
+function formatDateUTC(date) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return (
+    `${date.getUTCFullYear()}-` +
+    `${pad(date.getUTCMonth() + 1)}-` +
+    `${pad(date.getUTCDate())} ` +
+    `${pad(date.getUTCHours())}:` +
+    `${pad(date.getUTCMinutes())} UTC`
+  );
+}
+
+/**
+ * Format a Date as ISO 8601 (for frontmatter fields).
+ *
+ * @param {Date} date
+ * @returns {string}
+ */
+function toIso(date) {
+  return date.toISOString();
+}
+
+/**
+ * Format a last-activity ISO string for display. Returns '—' if absent.
+ *
+ * @param {string|null|undefined} iso
+ * @returns {string}
+ */
+function fmtActivity(iso) {
+  if (!iso) return '—';
+  // Display as YYYY-MM-DD HH:MM UTC
+  try {
+    const d = new Date(iso);
+    return formatDateUTC(d);
+  } catch {
+    return iso;
+  }
+}
+
+/**
+ * Format a milestone for display.
+ *
+ * @param {{ title: string, due_date: string } | null} ms
+ * @returns {string}
+ */
+function fmtMilestone(ms) {
+  if (!ms) return '—';
+  return ms.due_date ? `${ms.title} (${ms.due_date})` : ms.title;
+}
+
+// ── Render ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Render the portfolio markdown body from per-repo summaries.
+ *
+ * Repos are sorted alphabetically by name for stable output.
+ * topThree within each repo is already sorted by updated_at desc (from summarizeRepo).
+ *
+ * @param {Map<string, {
+ *   openCount: number,
+ *   criticalCount: number,
+ *   staleCount: number,
+ *   nextMilestone: { title: string, due_date: string } | null,
+ *   lastActivity: string | null,
+ *   topThree: Array<{ iid: number|string, title: string, labels: string[], url: string }>,
+ * }>} summaries
+ * @param {{
+ *   now: Date,
+ *   createdIso?: string,
+ *   staleDays?: number,
+ *   updatedPlaceholder?: string,
+ * }} opts
+ * @returns {string}  full markdown (frontmatter + body)
+ */
+export function renderPortfolio(summaries, opts) {
+  const {
+    now,
+    createdIso,
+    staleDays = 30,
+    updatedPlaceholder,
+  } = opts;
+
+  const nowIso = toIso(now);
+  const updatedValue = updatedPlaceholder ?? nowIso;
+  const createdValue = createdIso ?? nowIso;
+
+  // Aggregate totals
+  let totalOpen = 0;
+  let totalCritical = 0;
+  let totalStale = 0;
+  const sortedRepos = [...summaries.keys()].sort((a, b) => a.localeCompare(b));
+
+  for (const repo of sortedRepos) {
+    const s = summaries.get(repo);
+    totalOpen += s.openCount;
+    totalCritical += s.criticalCount;
+    totalStale += s.staleCount;
+  }
+
+  const lines = [];
+
+  // Frontmatter
+  lines.push('---');
+  lines.push(`_generator: ${GENERATOR_MARKER}`);
+  lines.push(`type: dashboard`);
+  lines.push(`created: ${createdValue}`);
+  lines.push(`updated: ${updatedValue}`);
+  lines.push('---');
+  lines.push('');
+
+  // Title + preamble
+  lines.push('# GitLab Portfolio');
+  lines.push('');
+  lines.push(`> Generated ${formatDateUTC(now)}. Re-run /portfolio to refresh.`);
+  lines.push('');
+
+  // Summary table
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Metric | Count |');
+  lines.push('|---|---|');
+  lines.push(`| Total repos | ${sortedRepos.length} |`);
+  lines.push(`| Total open issues | ${totalOpen} |`);
+  lines.push(`| Critical | ${totalCritical} |`);
+  lines.push(`| Stale (>${staleDays} days) | ${totalStale} |`);
+  lines.push('');
+
+  // Repos overview table
+  lines.push('## Repos');
+  lines.push('');
+  lines.push('| Repo | Open | Critical | Stale | Last activity | Next milestone |');
+  lines.push('|---|---|---|---|---|---|');
+
+  for (const repo of sortedRepos) {
+    const s = summaries.get(repo);
+    lines.push(
+      `| ${repo} | ${s.openCount} | ${s.criticalCount} | ${s.staleCount} | ${fmtActivity(s.lastActivity)} | ${fmtMilestone(s.nextMilestone)} |`,
+    );
+  }
+  lines.push('');
+
+  // Per-repo detail
+  lines.push('## Per-Repo Detail');
+  lines.push('');
+
+  for (const repo of sortedRepos) {
+    const s = summaries.get(repo);
+    lines.push(`### ${repo}`);
+    lines.push('');
+    lines.push(`- Last activity: ${fmtActivity(s.lastActivity)}`);
+    lines.push(`- Next milestone: ${fmtMilestone(s.nextMilestone)}`);
+
+    if (s.topThree.length > 0) {
+      lines.push('- Top 3 open issues:');
+      for (const issue of s.topThree) {
+        const labelStr = issue.labels.length > 0 ? `labels: ${issue.labels.join(', ')}` : 'no labels';
+        lines.push(`  - #${issue.iid} ${issue.title} (${labelStr}) — ${issue.url}`);
+      }
+    } else {
+      lines.push('- No open issues.');
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ── Write (idempotent) ─────────────────────────────────────────────────────────
+
+/**
+ * Normalize a markdown string by replacing the `updated:` frontmatter line
+ * with a stable placeholder, enabling byte-for-byte noop comparison.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function normalizeUpdated(content) {
+  // Replace `updated: <anything>` in the frontmatter block with the placeholder.
+  // Only replace within the first frontmatter section (between the first --- pair).
+  return content.replace(
+    /^(updated:\s*)(.+)$/m,
+    `$1${UPDATED_PLACEHOLDER}`,
+  );
+}
+
+/**
+ * Write the portfolio file with idempotency guards.
+ *
+ * @param {{
+ *   outputPath: string,
+ *   content: string,
+ *   now: Date,
+ *   dryRun?: boolean,
+ *   fs?: { readFileSync?: Function, writeFileSync?: Function, mkdirSync?: Function, existsSync?: Function },
+ * }} opts
+ * @returns {{ action: 'written'|'skipped-handwritten'|'skipped-noop'|'dry-run', path: string }}
+ */
+export function writePortfolio(opts) {
+  const {
+    outputPath,
+    content,
+    dryRun = false,
+    fs: injectedFs,
+  } = opts;
+
+  // Resolve fs functions (injectable for tests)
+  const fsReadFile = injectedFs?.readFileSync ?? readFileSync;
+  const fsWriteFile = injectedFs?.writeFileSync ?? writeFileSync;
+  const fsMkdir = injectedFs?.mkdirSync ?? mkdirSync;
+  const fsExists = injectedFs?.existsSync ?? existsSync;
+
+  // Dry-run: never write
+  if (dryRun) {
+    return { action: 'dry-run', path: outputPath };
+  }
+
+  if (fsExists(outputPath)) {
+    let existingContent;
+    try {
+      existingContent = fsReadFile(outputPath, 'utf8');
+    } catch {
+      // Cannot read → treat as non-existent, write fresh
+      existingContent = null;
+    }
+
+    if (existingContent !== null) {
+      const fm = parseFrontmatter(existingContent);
+
+      // Skip-on-manual-edit: no _generator or different generator
+      if (!fm || !fm['_generator']) {
+        return { action: 'skipped-handwritten', path: outputPath };
+      }
+      if (fm['_generator'] !== GENERATOR_MARKER) {
+        return { action: 'skipped-handwritten', path: outputPath };
+      }
+
+      // Skip-noop: compare content modulo `updated:` timestamp
+      const existingNormalized = normalizeUpdated(existingContent);
+      const newNormalized = normalizeUpdated(content);
+      if (existingNormalized === newNormalized) {
+        return { action: 'skipped-noop', path: outputPath };
+      }
+    }
+  }
+
+  // Write
+  const targetDir = dirname(outputPath);
+  fsMkdir(targetDir, { recursive: true });
+  fsWriteFile(outputPath, content, 'utf8');
+
+  return { action: 'written', path: outputPath };
+}

package/scripts/lib/gitlab-portfolio/vcs-detect.mjs

@@ -0,0 +1,182 @@
+/**
+ * vcs-detect.mjs — VCS auto-detection helpers for the gitlab-portfolio skill.
+ *
+ * Exports:
+ *   discoverVaultRepos   — scan vault 01-projects/ for registered repos
+ *   detectVcsForRepo     — resolve 'gitlab' | 'github' | null for a single spec
+ *
+ * Used by cli.mjs as the discovery step before aggregation.
+ */
+
+import os from 'node:os';
+import fsP from 'node:fs/promises';
+import path from 'node:path';
+
+import { parseFrontmatter as _parseFrontmatter } from '../vault-mirror/utils.mjs';
+
+// ── detectVcsForRepo ──────────────────────────────────────────────────────────
+
+/**
+ * Resolve the VCS platform for a single repo spec.
+ *
+ * Priority:
+ *   1. Explicit `frontmatter.gitlab` field present → 'gitlab'
+ *   2. Explicit `frontmatter.github` field present → 'github'
+ *   3. `repo` matches /(?:^|[@/])gitlab\./ or starts with 'gitlab/' → 'gitlab'
+ *   4. `repo` contains 'github.com' or starts with 'github/' → 'github'
+ *   5. `repo` matches host-less <org>/<repo> shorthand /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/ → 'github' (last resort)
+ *   6. Otherwise → null (caller decides)
+ *
+ * @param {{ frontmatter?: Record<string, string>, repo?: string }} input
+ * @returns {'gitlab'|'github'|null}
+ */
+export function detectVcsForRepo(input) {
+  const { frontmatter, repo } = input ?? {};
+
+  // 1. Frontmatter: explicit gitlab field
+  if (frontmatter && frontmatter['gitlab']) {
+    return 'gitlab';
+  }
+
+  // 2. Frontmatter: explicit github field
+  if (frontmatter && frontmatter['github']) {
+    return 'github';
+  }
+
+  if (repo && typeof repo === 'string') {
+    // 3. Host-pattern: any GitLab instance (hostname starts with 'gitlab.') or group prefix
+    if (
+      /(?:^|[@/])gitlab\./.test(repo) ||
+      repo.startsWith('gitlab/')
+    ) {
+      return 'gitlab';
+    }
+
+    // 4. Host-pattern: GitHub
+    if (repo.includes('github.com') || repo.startsWith('github/')) {
+      return 'github';
+    }
+
+    // Shorthand <org>/<repo> with no host marker: assume GitHub (common convention).
+    // We only do this as a last resort — explicit frontmatter fields are preferred.
+    if (/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(repo)) {
+      return 'github';
+    }
+  }
+
+  return null;
+}
+
+// ── discoverVaultRepos ────────────────────────────────────────────────────────
+
+/**
+ * Discover registered repos from a vault directory.
+ *
+ * Scans `<vaultDir>/01-projects/<slug>/_overview.md` frontmatter for `gitlab:`
+ * and/or `github:` keys. If BOTH are present, `gitlab` wins (it is the primary
+ * VCS; `github` is typically a mirror).
+ *
+ * Projects without either field are silently skipped. Missing `_overview.md`
+ * files are silently skipped.
+ *
+ * @param {{
+ *   vaultDir: string,
+ *   fs?: { readdir: Function, readFile: Function, stat: Function },
+ *   parseFrontmatter?: (content: string) => Record<string, string> | null,
+ * }} opts
+ * @returns {Promise<Array<{
+ *   slug: string,
+ *   repo: string,
+ *   vcs: 'gitlab'|'github',
+ *   overviewPath: string,
+ * }>>}
+ */
+export async function discoverVaultRepos(opts) {
+  const {
+    vaultDir: rawVaultDir,
+    fs: injectedFs,
+    parseFrontmatter = _parseFrontmatter,
+  } = opts;
+
+  if (!rawVaultDir || typeof rawVaultDir !== 'string') {
+    return [];
+  }
+
+  // Expand ~ if present
+  const vaultDir = rawVaultDir.startsWith('~')
+    ? path.join(os.homedir(), rawVaultDir.slice(1))
+    : rawVaultDir;
+
+  // Resolve fs functions (injectable for tests)
+  const fsReaddir = injectedFs?.readdir ?? fsP.readdir;
+  const fsReadFile = injectedFs?.readFile ?? fsP.readFile;
+  const fsStat = injectedFs?.stat ?? fsP.stat;
+
+  const projectsDir = path.join(vaultDir, '01-projects');
+
+  // Read the 01-projects directory
+  let entries;
+  try {
+    entries = await fsReaddir(projectsDir);
+  } catch {
+    // 01-projects dir does not exist — return empty
+    return [];
+  }
+
+  const results = [];
+
+  for (const entry of entries) {
+    // Skip dotfiles
+    if (entry.startsWith('.')) continue;
+
+    const entryPath = path.join(projectsDir, entry);
+
+    // Skip non-directories
+    let stat;
+    try {
+      stat = await fsStat(entryPath);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+
+    const slug = entry;
+    const overviewPath = path.join(entryPath, '_overview.md');
+
+    // Read _overview.md — skip if absent
+    let content;
+    try {
+      content = await fsReadFile(overviewPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    // Parse frontmatter
+    const fm = parseFrontmatter(content);
+    if (!fm) continue;
+
+    const gitlabField = fm['gitlab'];
+    const githubField = fm['github'];
+
+    // Determine VCS and repo identifier.
+    // Priority: gitlab > github (gitlab is primary; github is typically a mirror).
+    if (gitlabField && typeof gitlabField === 'string' && gitlabField.trim()) {
+      results.push({
+        slug,
+        repo: gitlabField.trim(),
+        vcs: 'gitlab',
+        overviewPath,
+      });
+    } else if (githubField && typeof githubField === 'string' && githubField.trim()) {
+      results.push({
+        slug,
+        repo: githubField.trim(),
+        vcs: 'github',
+        overviewPath,
+      });
+    }
+    // Neither field present → skip silently
+  }
+
+  return results;
+}

package/scripts/lib/handover-gate.mjs

@@ -0,0 +1,222 @@
+/**
+ * handover-gate.mjs — deterministic routing helper for the /close Handover
+ * Alignment Gate (session-end Phase 1.65).
+ *
+ * PRD: docs/prd/2026-07-07-close-handover-alignment-gate.md
+ * Issue: #769 (Epic #724 — Session-Lifecycle & Close-Friction)
+ *
+ * ## What this module does
+ *
+ * The gate is skill-prose-first with a minimal mechanical core (same pattern as
+ * memory-proposals / phase-skip.mjs): the LLM coordinator runs the AUQ
+ * interaction, and this small pure `.mjs` lib makes the deterministic candidate
+ * classification trivially testable. There is NO I/O here — no disk, no clock,
+ * no randomness — so every function is a pure, deterministic mapping of input
+ * records to a routed shape.
+ *
+ * ## The routing contract (PRD FA2 + §3.A EARS)
+ *
+ * Every carryover candidate lands in EXACTLY ONE of `autoCarry` or `ask` — no
+ * candidate is ever dropped by classification (the Ubiquitous EARS rule). The
+ * coordinator later decides the OB (whether an issue is filed) from these two
+ * buckets: `autoCarry` items are listed in the gate summary but are NOT
+ * user-deselectable; `ask` items become the Middle-Band multiSelect (preselected
+ * = carry).
+ *
+ * A candidate is routed to `autoCarry` when ANY of:
+ *   - `priority === 'critical'` or `priority === 'high'`, OR
+ *   - `bucket === 'spiral-failed'` (the SPIRAL/FAILED safety-net, Phase 1.6), OR
+ *   - `originIssue === null` (Grill decision: dropping a candidate that has no
+ *     origin issue would be real forgetting — SKILL.md:853 Critical Rule stays
+ *     intact).
+ *
+ * A candidate is routed to `ask` when it has an origin issue AND its priority is
+ * `medium` / `low` / `null` AND its bucket is `not-started` / `emergent` /
+ * `partially-done` (i.e. not high-prio, not spiral-failed).
+ *
+ * `malformed` records (missing/empty task text) are routed to `ask` with a
+ * `malformed: true` flag — the helper NEVER throws on them, and the malformed
+ * branch takes precedence over every autoCarry condition (a record with no task
+ * text cannot be meaningfully auto-filed, so the operator decides).
+ *
+ * Empty / non-array input yields `{ autoCarry: [], ask: [] }` — never throws.
+ *
+ * @typedef {Object} NormalizedCandidate
+ * @property {string} task           - task text (required; if absent/empty → malformed:true).
+ * @property {string} sourcePhase    - '1.2' | '1.3' | '1.4' | '1.6' (best-effort string).
+ * @property {number|null} originIssue - issue IID, or null when there is no origin issue.
+ * @property {'critical'|'high'|'medium'|'low'|null} priority
+ * @property {'partially-done'|'not-started'|'emergent'|'spiral-failed'} bucket
+ * @property {boolean} [malformed]   - true when task text is missing/empty.
+ *
+ * @typedef {Object} RoutingResult
+ * @property {NormalizedCandidate[]} autoCarry - not user-deselectable; gate-summary only.
+ * @property {NormalizedCandidate[]} ask       - Middle-Band multiSelect (preselected = carry).
+ */
+
+// ---------------------------------------------------------------------------
+// Coercion tables
+// ---------------------------------------------------------------------------
+
+/** Valid carryover buckets (PRD §3.A). */
+const VALID_BUCKETS = new Set(['partially-done', 'not-started', 'emergent', 'spiral-failed']);
+
+/** Valid priorities (GitLab priority labels, lowercased, label-prefix stripped). */
+const VALID_PRIORITIES = new Set(['critical', 'high', 'medium', 'low']);
+
+/**
+ * Source-phase → bucket inference used when a candidate omits an explicit bucket
+ * (PRD §2 In-Scope: 1.2 Partially Done, 1.3 Not Started, 1.4 unfinished Emergent,
+ * 1.6 SPIRAL/FAILED walk).
+ */
+const PHASE_BUCKET = {
+  '1.2': 'partially-done',
+  '1.3': 'not-started',
+  '1.4': 'emergent',
+  '1.6': 'spiral-failed',
+};
+
+/** Neutral fallback bucket when neither an explicit bucket nor a known phase maps. */
+const DEFAULT_BUCKET = 'not-started';
+
+// ---------------------------------------------------------------------------
+// Field coercers (each pure, each defensive)
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce an origin-issue field. Numeric string ("769") → number; an integer
+ * number passes through; everything else (missing, null, fractional
+ * number/string, non-numeric) → null. Issue IIDs are always integers, so a
+ * fractional number is coerced identically to a fractional numeric string —
+ * both are malformed input and fall through to `null` (routing the candidate
+ * to autoCarry via the no-origin rule, the safe direction).
+ *
+ * @param {unknown} v
+ * @returns {number|null}
+ */
+function coerceOriginIssue(v) {
+  if (typeof v === 'number') return Number.isInteger(v) ? v : null;
+  if (typeof v === 'string') {
+    const t = v.trim();
+    return /^-?\d+$/.test(t) ? Number(t) : null;
+  }
+  return null;
+}
+
+/**
+ * Coerce a priority field: lowercase, trim, strip a leading `priority:` label,
+ * validate against the closed enum. Anything invalid → null.
+ *
+ * @param {unknown} v
+ * @returns {'critical'|'high'|'medium'|'low'|null}
+ */
+function coercePriority(v) {
+  if (v === null || v === undefined) return null;
+  let s = String(v).trim().toLowerCase();
+  if (s.startsWith('priority:')) s = s.slice('priority:'.length).trim();
+  return VALID_PRIORITIES.has(s) ? /** @type {any} */ (s) : null;
+}
+
+/**
+ * Coerce the source-phase field to a best-effort trimmed string ('' when absent).
+ *
+ * @param {unknown} v
+ * @returns {string}
+ */
+function coerceSourcePhase(v) {
+  if (v === null || v === undefined) return '';
+  return String(v).trim();
+}
+
+/**
+ * Resolve the bucket: an explicit valid bucket wins; otherwise infer from the
+ * source phase; otherwise fall back to the neutral default.
+ *
+ * @param {unknown} rawBucket
+ * @param {string} sourcePhase
+ * @returns {'partially-done'|'not-started'|'emergent'|'spiral-failed'}
+ */
+function coerceBucket(rawBucket, sourcePhase) {
+  if (rawBucket !== null && rawBucket !== undefined) {
+    const b = String(rawBucket).trim().toLowerCase();
+    if (VALID_BUCKETS.has(b)) return /** @type {any} */ (b);
+  }
+  return /** @type {any} */ (PHASE_BUCKET[sourcePhase] ?? DEFAULT_BUCKET);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a raw carryover-candidate record into a {@link NormalizedCandidate}.
+ *
+ * Accepts any subset of `{ task, sourcePhase, originIssue, priority, bucket }`
+ * (strings or numbers) and coerces each field. Missing/empty `task` yields
+ * `task: ''` plus `malformed: true` (never throws). Pure and deterministic —
+ * no `Date.now()` / `Math.random()`.
+ *
+ * @param {unknown} raw
+ * @returns {NormalizedCandidate}
+ */
+export function normalizeCandidate(raw) {
+  const rec = raw && typeof raw === 'object' ? /** @type {Record<string, unknown>} */ (raw) : {};
+
+  const sourcePhase = coerceSourcePhase(rec.sourcePhase);
+  const originIssue = coerceOriginIssue(rec.originIssue);
+  const priority = coercePriority(rec.priority);
+  const bucket = coerceBucket(rec.bucket, sourcePhase);
+
+  const hasTask = typeof rec.task === 'string' && rec.task.trim().length > 0;
+
+  /** @type {NormalizedCandidate} */
+  const normalized = {
+    task: hasTask ? /** @type {string} */ (rec.task) : '',
+    sourcePhase,
+    originIssue,
+    priority,
+    bucket,
+  };
+  if (!hasTask) normalized.malformed = true;
+
+  return normalized;
+}
+
+/**
+ * Route a list of raw carryover candidates into `{ autoCarry, ask }`.
+ *
+ * Each candidate is first normalized via {@link normalizeCandidate}, then
+ * classified per the module routing contract. Every candidate lands in exactly
+ * one bucket; nothing is dropped. Empty or non-array input → `{ autoCarry: [],
+ * ask: [] }`. Never throws.
+ *
+ * @param {unknown} candidates
+ * @returns {RoutingResult}
+ */
+export function routeCandidates(candidates) {
+  /** @type {RoutingResult} */
+  const result = { autoCarry: [], ask: [] };
+  if (!Array.isArray(candidates) || candidates.length === 0) return result;
+
+  for (const raw of candidates) {
+    const c = normalizeCandidate(raw);
+
+    // malformed takes precedence over every autoCarry condition — a record with
+    // no task text cannot be meaningfully auto-filed, so the operator decides.
+    if (c.malformed) {
+      result.ask.push(c);
+      continue;
+    }
+
+    const isAutoCarry =
+      c.priority === 'critical' ||
+      c.priority === 'high' ||
+      c.bucket === 'spiral-failed' ||
+      c.originIssue === null;
+
+    if (isAutoCarry) result.autoCarry.push(c);
+    else result.ask.push(c);
+  }
+
+  return result;
+}