akm-cli 0.8.0-rc2 → 0.8.0

package/dist/commands/proposal-drain-policies.js

@@ -0,0 +1,128 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Built-in deterministic triage policy presets (Proposal-Queue Triage, §3.1).
+ *
+ * These are the *only* "rule schema" we ship. Custom needs are served by the
+ * single `--policy <path>` escape hatch, which zod-validates an external policy
+ * file — not by a config-embedded rule engine (see §9, rejected alternatives).
+ *
+ * | preset           | accepts                                                   | rejects     | leaves pending                                     |
+ * |------------------|-----------------------------------------------------------|-------------|----------------------------------------------------|
+ * | `personal-stash` | extract (real content); reflect ≤80 lines; consolidate    | empty diffs | consolidate mid-band, distill dups, contradictions |
+ * | `conservative`   | small extract + consolidate only                          | empty diffs | everything else                                    |
+ * | `manual`         | nothing                                                   | empty diffs | everything else                                    |
+ */
+import fs from "node:fs";
+import { z } from "zod";
+import { UsageError } from "../core/errors";
+import { PROPOSAL_SOURCES } from "../core/proposals";
+// Valid `generator` values for a drain rule are exactly the canonical proposal
+// `source` values (see {@link PROPOSAL_SOURCES} in src/core/proposals.ts). The
+// engine matches rules via `policy.accept.find(r => r.generator === proposal.source)`,
+// so a generator that is not a real source can never match — it would be a
+// silent permanent no-op. Validate against the closed set to surface typos.
+const GeneratorSchema = z.enum(PROPOSAL_SOURCES, {
+    errorMap: () => ({
+        message: `must be one of the known proposal sources: ${PROPOSAL_SOURCES.join(", ")}`,
+    }),
+});
+// ---------------------------------------------------------------------------
+// Built-in presets
+// ---------------------------------------------------------------------------
+/**
+ * `personal-stash` encodes the deterministic core of today's hand-rolled
+ * rubric (the editable `contradicted` memory). It is shipped as a preset, never
+ * hardcoded policy: edit a copy via `--policy <path>` to tune it.
+ */
+export const PERSONAL_STASH = {
+    name: "personal-stash",
+    accept: [
+        // Extract proposals carry freshly-pulled real content — accept when present.
+        { generator: "extract", minContentLines: 1 },
+        // Reflect refinements: accept small ones; larger refinements defer to review.
+        { generator: "reflect", maxDiffLines: 80 },
+        // Consolidate within the diff band; mid-band lands in `defer` below.
+        { generator: "consolidate", maxDiffLines: 200 },
+    ],
+    rejectEmpty: true,
+    // Mid-band consolidate, distill duplicates, and contradiction escalations are
+    // the irreducibly-semantic tail — deferred to the (Phase 3) judgment tier.
+    defer: ["consolidate", "distill"],
+};
+/** `conservative` accepts only small, low-risk extract + consolidate proposals. */
+export const CONSERVATIVE = {
+    name: "conservative",
+    accept: [
+        { generator: "extract", maxDiffLines: 80, minContentLines: 1 },
+        { generator: "consolidate", maxDiffLines: 80 },
+    ],
+    rejectEmpty: true,
+    defer: [],
+};
+/** `manual` accepts nothing; it only clears empty diffs. */
+export const MANUAL = {
+    name: "manual",
+    accept: [],
+    rejectEmpty: true,
+    defer: [],
+};
+const BUILTIN_POLICIES = {
+    "personal-stash": PERSONAL_STASH,
+    conservative: CONSERVATIVE,
+    manual: MANUAL,
+};
+/** Names of the built-in presets, for help text and validation messages. */
+export const BUILTIN_POLICY_NAMES = Object.keys(BUILTIN_POLICIES);
+// ---------------------------------------------------------------------------
+// Custom policy file schema (`--policy <path>`)
+// ---------------------------------------------------------------------------
+const DrainAcceptRuleSchema = z
+    .object({
+    generator: GeneratorSchema,
+    maxDiffLines: z.number().int().positive().optional(),
+    minContentLines: z.number().int().nonnegative().optional(),
+})
+    .strict();
+const DrainPolicySchema = z
+    .object({
+    name: z.string().min(1),
+    accept: z.array(DrainAcceptRuleSchema),
+    rejectEmpty: z.boolean(),
+    defer: z.array(GeneratorSchema),
+})
+    .strict();
+/**
+ * Resolve a `--policy <preset|path>` argument into a {@link DrainPolicy}.
+ *
+ *   - A bare preset name (`personal-stash` / `conservative` / `manual`) returns
+ *     the matching built-in.
+ *   - Anything else is treated as a filesystem path to a JSON policy file, which
+ *     is read and zod-validated.
+ *
+ * Throws a {@link UsageError} on an unknown preset, a missing file, or a file
+ * that fails schema validation.
+ */
+export function resolveDrainPolicy(arg) {
+    const value = (arg ?? "personal-stash").trim();
+    const builtin = BUILTIN_POLICIES[value];
+    if (builtin)
+        return builtin;
+    // Treat as a path to a custom policy file.
+    if (!fs.existsSync(value)) {
+        throw new UsageError(`Unknown policy "${value}". Use a built-in preset (${BUILTIN_POLICY_NAMES.join(", ")}) or a path to a policy file.`, "INVALID_FLAG_VALUE");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(value, "utf8"));
+    }
+    catch (err) {
+        throw new UsageError(`Could not parse policy file "${value}": ${err instanceof Error ? err.message : String(err)}`, "INVALID_FLAG_VALUE");
+    }
+    const validated = DrainPolicySchema.safeParse(parsed);
+    if (!validated.success) {
+        throw new UsageError(`Invalid policy file "${value}": ${validated.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`, "INVALID_FLAG_VALUE");
+    }
+    return validated.data;
+}

package/dist/commands/proposal-drain.js

@@ -0,0 +1,477 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Deterministic proposal-drain engine (Proposal-Queue Triage, Phase 1).
+ *
+ * Drains the *standing pending backlog* of proposals using a deterministic,
+ * no-LLM policy keyed on generator (proposal `source`) and diff size. This is
+ * the engine behind `akm proposal drain` and (later) the `triage` improve
+ * pre-pass.
+ *
+ * Design (see docs/technical/proposal-triage-implementation-plan.md):
+ *   - Reuses `listProposals` (no source filter — generator filtering is
+ *     in-memory) and the `akmProposalAccept` / `akmProposalReject` wrappers from
+ *     `proposal.ts` so the standard `promoted` / `rejected` events are emitted.
+ *     It deliberately does NOT use `runAutoAcceptGate`, which is confidence-gated.
+ *   - Backlog-only: `excludeIds` removes this-run's fresh proposals so triage
+ *     never re-adjudicates the per-run auto-accept gate's decisions (decision #2).
+ *   - Hard guardrails enforced in code: a `maxAccepts` ceiling checked *before*
+ *     the promote loop (remainder → `skippedByCap`); `maxDiffLines` defers large
+ *     accepts; `applyMode: "queue"` (the safe default) never promotes (stage
+ *     only); `rejectEmpty` rejects empty / near-empty diffs.
+ *   - The judgment tier (Phase 3) adjudicates the deferred items: when a
+ *     `judgment` RunnerSpec is supplied the engine pre-fetches context (the live
+ *     asset + sibling pending proposals for the same ref) into a prompt,
+ *     dispatches it to the configured runner (llm → `chatCompletion`, agent →
+ *     `runAgent`, sdk → `runOpencodeSdk`, mirroring `reflect.ts`'s switch), and
+ *     performs the resulting accept / reject *itself* (the runner only judges).
+ *     Items the runner cannot resolve — and any deferred items when no runner is
+ *     configured — surface a `triage_deferred` event so "enabled, no agent"
+ *     never silently looks like full success.
+ *
+ * The promote / reject functions and the runner dispatch are injectable
+ * (mirrors `improve-auto-accept.ts` and reflect's dual test seams) so tests can
+ * run the full engine without touching the filesystem or spawning a process.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseAssetRef } from "../core/asset-ref";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../core/asset-spec";
+import { appendEvent } from "../core/events";
+import { parseFrontmatter } from "../core/frontmatter";
+import { listProposals } from "../core/proposals";
+import { info, warn } from "../core/warn";
+import { runAgent } from "../integrations/agent";
+import { runOpencodeSdk } from "../integrations/agent/sdk-runner";
+import { chatCompletion, stripJsonFences } from "../llm/client";
+import { akmProposalAccept, akmProposalReject } from "./proposal";
+// ---------------------------------------------------------------------------
+// Content helpers
+// ---------------------------------------------------------------------------
+/** Number of non-empty body lines (frontmatter excluded). */
+export function contentBodyLineCount(content) {
+    // Reuse the canonical frontmatter parser so CRLF / BOM are handled
+    // consistently with the rest of the stash (parseFrontmatter returns the body
+    // in `content`).
+    return parseFrontmatter(content)
+        .content.split("\n")
+        .filter((line) => line.trim().length > 0).length;
+}
+/** Total line count of the proposed content (matches the bulk-accept measure). */
+export function contentLineCount(content) {
+    return content.split("\n").length;
+}
+/** An empty / near-empty diff has no meaningful body content. */
+export function isEmptyDiff(proposal) {
+    const content = proposal.payload.content ?? "";
+    if (content.trim().length === 0)
+        return true;
+    return contentBodyLineCount(content) === 0;
+}
+/**
+ * Decide a deterministic verdict for a single backlog proposal under `policy`.
+ * Returns `null` when no rule applies (the proposal is left pending untouched).
+ */
+export function classifyProposal(proposal, policy, maxDiffLines) {
+    const content = proposal.payload.content ?? "";
+    // Empty / near-empty diffs reject first (the reject-empty floor).
+    if (policy.rejectEmpty && isEmptyDiff(proposal)) {
+        return { verdict: "reject", reason: "empty diff" };
+    }
+    const rule = policy.accept.find((r) => r.generator === proposal.source);
+    if (rule) {
+        const lines = contentLineCount(content);
+        const body = contentBodyLineCount(content);
+        // Per-rule and global diff bounds defer large accepts (no silent rewrites).
+        const effectiveMax = Math.min(rule.maxDiffLines ?? Number.POSITIVE_INFINITY, maxDiffLines ?? Number.POSITIVE_INFINITY);
+        if (lines > effectiveMax) {
+            return { verdict: "defer", reason: "mid-band" };
+        }
+        if (rule.minContentLines !== undefined && body < rule.minContentLines) {
+            // Too little content to confidently auto-accept — leave for judgment.
+            return { verdict: "defer", reason: "mid-band" };
+        }
+        return { verdict: "accept" };
+    }
+    if (policy.defer.includes(proposal.source)) {
+        return { verdict: "defer", reason: deferReasonForSource(proposal.source) };
+    }
+    // No matching rule — leave pending, untouched.
+    return null;
+}
+function deferReasonForSource(source) {
+    return source === "distill" ? "possible-dup" : "mid-band";
+}
+// ---------------------------------------------------------------------------
+// Judgment tier (Phase 3)
+// ---------------------------------------------------------------------------
+/** Read the live on-disk content of a proposal's target asset, if it exists. */
+function readLiveAssetContent(stashDir, ref) {
+    try {
+        const parsed = parseAssetRef(ref);
+        const typeDir = TYPE_DIRS[parsed.type];
+        if (!typeDir)
+            return undefined;
+        const typeRoot = path.join(stashDir, typeDir);
+        const assetPath = resolveAssetPathFromName(parsed.type, typeRoot, parsed.name);
+        if (!fs.existsSync(assetPath))
+            return undefined;
+        return fs.readFileSync(assetPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Pre-fetch the context the judgment runner needs to adjudicate one deferred
+ * proposal: the proposed content, the live asset it would overwrite, and the
+ * sibling pending proposals for the same ref (so a dedup verdict can compare).
+ */
+function prefetchJudgmentContext(stashDir, proposal, pending) {
+    const liveAsset = readLiveAssetContent(stashDir, proposal.ref);
+    const siblings = pending.filter((p) => p.ref === proposal.ref && p.id !== proposal.id);
+    return { liveAsset, siblings };
+}
+/** Build the judgment prompt with the proposed content + pre-fetched context. */
+export function buildJudgmentPrompt(proposal, reason, ctx) {
+    const proposed = proposal.payload.content ?? "";
+    const sections = [
+        "You are adjudicating a pending knowledge-base proposal that the deterministic",
+        "triage pass could not resolve. Decide whether to accept, reject, or defer it.",
+        "",
+        `Asset ref: ${proposal.ref}`,
+        `Generator (source): ${proposal.source}`,
+        `Deferred because: ${reason}`,
+        "",
+        "## Proposed content",
+        "```",
+        proposed,
+        "```",
+    ];
+    if (ctx.liveAsset !== undefined) {
+        sections.push("", "## Current live asset (would be overwritten on accept)", "```", ctx.liveAsset, "```");
+    }
+    else {
+        sections.push("", "## Current live asset", "(none — this proposal would create a new asset)");
+    }
+    if (ctx.siblings.length > 0) {
+        sections.push("", "## Other pending proposals for the same ref (dedup context)");
+        for (const sib of ctx.siblings) {
+            sections.push("", `### Sibling ${sib.id} (source: ${sib.source})`, "```", sib.payload.content ?? "", "```");
+        }
+    }
+    sections.push("", "## Your task", 'Return ONLY a JSON object: {"decision": "accept" | "reject" | "defer", "reason": "<short reason>"}.', "- accept: the proposed content is a correct, valuable update worth committing.", "- reject: the proposal is wrong, a duplicate, or contradicts the live asset.", "- defer: you cannot decide from the provided context (leave it pending).", "Output the JSON object and nothing else.");
+    return sections.join("\n");
+}
+/** Parse a {@link JudgmentVerdict} from raw runner output. Lenient. */
+export function parseJudgmentVerdict(raw) {
+    const cleaned = stripJsonFences(raw).trim();
+    if (!cleaned)
+        return null;
+    // Find the first balanced-looking JSON object in the output.
+    const start = cleaned.indexOf("{");
+    const end = cleaned.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(cleaned.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== "object" || obj === null)
+        return null;
+    const decision = obj.decision;
+    const reason = obj.reason;
+    if (decision !== "accept" && decision !== "reject" && decision !== "defer")
+        return null;
+    return { decision, reason: typeof reason === "string" ? reason : "" };
+}
+/**
+ * Dispatch a single judgment prompt to the resolved runner. The switch mirrors
+ * the canonical consumer at `reflect.ts:1060-1090`: llm → `chatCompletion`
+ * (no filesystem), agent → `runAgent`, sdk → `runOpencodeSdk`.
+ */
+async function dispatchJudgment(runner, prompt, seams) {
+    let raw;
+    switch (runner.kind) {
+        case "llm": {
+            const messages = [{ role: "user", content: prompt }];
+            raw = seams.chat
+                ? await seams.chat(runner, messages)
+                : await chatCompletion(runner.connection, messages, {
+                    ...(runner.timeoutMs !== undefined ? { timeoutMs: runner.timeoutMs } : {}),
+                });
+            break;
+        }
+        case "agent": {
+            const stdout = await runProfileJudgment(seams.runAgentFn ?? runAgent, runner.profile, prompt, "agent", runner.timeoutMs);
+            if (stdout === null)
+                return null;
+            raw = stdout;
+            break;
+        }
+        case "sdk": {
+            const stdout = await runProfileJudgment(seams.runSdkFn ?? runOpencodeSdk, runner.profile, prompt, "sdk", runner.timeoutMs);
+            if (stdout === null)
+                return null;
+            raw = stdout;
+            break;
+        }
+    }
+    return parseJudgmentVerdict(raw);
+}
+/**
+ * Shared spawn-runner dispatch for the byte-identical `agent` / `sdk` arms: run
+ * the profile-based runner, log a labelled warning on failure, and return the
+ * captured stdout (or `null` on failure). `label` only changes the warn prefix.
+ */
+async function runProfileJudgment(run, profile, prompt, label, timeoutMs) {
+    const result = await run(profile, prompt, {
+        stdio: "captured",
+        parseOutput: "text",
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+    if (!result.ok) {
+        warn(`[triage] judgment ${label} failed: ${result.error ?? result.reason ?? "unknown error"}`);
+        return null;
+    }
+    return result.stdout;
+}
+/**
+ * Run the judgment tier over the deferred items. The runner only *judges*; the
+ * engine performs the resulting accept (respecting `applyMode`) / reject write.
+ * Returns the ids the engine promoted / rejected, the ids staged (judge said
+ * "accept" but queue mode did not promote), the ids dropped by the accept cap,
+ * and the items still unresolved (verdict "defer", parse failure, or a runner
+ * error).
+ */
+async function runJudgmentTier(input) {
+    const byId = new Map(input.pending.map((p) => [p.id, p]));
+    const promoted = [];
+    const rejected = [];
+    const staged = [];
+    const skippedByCap = [];
+    const stillDeferred = [];
+    // Remaining accept budget shared with the deterministic promote loop.
+    let acceptBudget = Math.max(0, input.remainingAcceptBudget);
+    for (const item of input.deferred) {
+        const proposal = byId.get(item.id);
+        if (!proposal) {
+            stillDeferred.push(item);
+            continue;
+        }
+        const ctx = prefetchJudgmentContext(input.stashDir, proposal, input.pending);
+        const prompt = buildJudgmentPrompt(proposal, item.reason, ctx);
+        let verdict;
+        try {
+            verdict = await dispatchJudgment(input.runner, prompt, input.seams);
+        }
+        catch (err) {
+            warn(`[triage] judgment dispatch failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+            stillDeferred.push(item);
+            continue;
+        }
+        if (!verdict || verdict.decision === "defer") {
+            stillDeferred.push(item);
+            continue;
+        }
+        if (verdict.decision === "reject") {
+            if (input.dryRun) {
+                rejected.push(item.id);
+                continue;
+            }
+            try {
+                input.rejectFn({ stashDir: input.stashDir, id: item.id, reason: verdict.reason || "judgment: reject" });
+                rejected.push(item.id);
+            }
+            catch (err) {
+                warn(`[triage] judgment reject failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+                stillDeferred.push(item);
+            }
+            continue;
+        }
+        // decision === "accept" — gated on applyMode, exactly like the
+        // deterministic accept path (queue mode never writes).
+        if (input.applyMode !== "promote") {
+            // Staged: a queue-mode run never promotes, so the item stays pending but
+            // is RESOLVED (the runner judged it). Track separately so it is NOT
+            // reported as "left unresolved" and a follow-up promote run picks it up.
+            staged.push(item.id);
+            continue;
+        }
+        // Accept cap: once the shared budget is exhausted, route further accepts to
+        // skippedByCap instead of promoting (keeps total promotions ≤ maxAccepts).
+        if (acceptBudget <= 0) {
+            skippedByCap.push(item.id);
+            continue;
+        }
+        if (input.dryRun) {
+            promoted.push(item.id);
+            acceptBudget -= 1;
+            continue;
+        }
+        try {
+            await input.promoteFn({ stashDir: input.stashDir, id: item.id });
+            promoted.push(item.id);
+            acceptBudget -= 1;
+        }
+        catch (err) {
+            warn(`[triage] judgment promote failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+            stillDeferred.push(item);
+        }
+    }
+    return { promoted, rejected, staged, skippedByCap, stillDeferred };
+}
+// ---------------------------------------------------------------------------
+// Engine
+// ---------------------------------------------------------------------------
+/**
+ * Drain the standing pending backlog under a deterministic policy.
+ *
+ * @param opts       Drain options (policy, applyMode, ceilings, dry-run).
+ * @param promoteFn  Injectable override for `akmProposalAccept` (test seam).
+ * @param rejectFn   Injectable override for `akmProposalReject` (test seam).
+ */
+export async function drainProposals(opts, promoteFn = akmProposalAccept, rejectFn = akmProposalReject, judgmentSeams = {}) {
+    const result = { promoted: [], rejected: [], deferred: [], skippedByCap: [], staged: [] };
+    const exclude = opts.excludeIds ?? new Set();
+    const pending = listProposals(opts.stashDir, { status: "pending" }).filter((p) => !exclude.has(p.id));
+    // First, classify every proposal deterministically.
+    const acceptIds = [];
+    const rejectTargets = [];
+    for (const proposal of pending) {
+        const decision = classifyProposal(proposal, opts.policy, opts.maxDiffLines);
+        if (decision === null)
+            continue;
+        if (decision.verdict === "accept") {
+            acceptIds.push(proposal.id);
+        }
+        else if (decision.verdict === "reject") {
+            rejectTargets.push({ id: proposal.id, reason: decision.reason });
+        }
+        else {
+            result.deferred.push({ id: proposal.id, reason: decision.reason });
+        }
+    }
+    // --- Reject empties (independent of the accept ceiling / applyMode) ---
+    for (const target of rejectTargets) {
+        if (opts.dryRun) {
+            result.rejected.push(target.id);
+            continue;
+        }
+        try {
+            rejectFn({ stashDir: opts.stashDir, id: target.id, reason: target.reason });
+            result.rejected.push(target.id);
+        }
+        catch (err) {
+            warn(`[triage] reject failed for ${target.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // --- Accept ceiling: enforced BEFORE the promote loop ---
+    const withinCap = acceptIds.slice(0, Math.max(0, opts.maxAccepts));
+    result.skippedByCap = acceptIds.slice(Math.max(0, opts.maxAccepts));
+    if (result.skippedByCap.length > 0) {
+        info(`[triage] accept ceiling reached: ${withinCap.length} promoted, ${result.skippedByCap.length} skipped by cap (maxAccepts=${opts.maxAccepts})`);
+    }
+    // --- Promotion gate: applyMode "queue" never promotes (stage only) ---
+    // Count deterministic promotions so the judgment tier shares the same accept
+    // budget (deterministic + judgment promotions ≤ maxAccepts).
+    let deterministicPromoted = 0;
+    if (opts.applyMode === "promote" && !opts.dryRun) {
+        info(`[triage] auto-promote active: ${withinCap.length} accepts allowed this run`);
+        for (const id of withinCap) {
+            try {
+                await promoteFn({ stashDir: opts.stashDir, id });
+                result.promoted.push(id);
+                deterministicPromoted += 1;
+            }
+            catch (err) {
+                warn(`[triage] promote failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    else if (opts.applyMode === "promote" && opts.dryRun) {
+        // Dry-run promote: report (and count, for the shared budget) what would be
+        // promoted without writing.
+        result.promoted.push(...withinCap);
+        deterministicPromoted = withinCap.length;
+    }
+    // applyMode "queue": leave accept candidates pending (staged). No promotion.
+    // Remaining accept budget for the judgment tier: maxAccepts minus what was
+    // actually promoted deterministically. Bounds the TOTAL promotions, not just
+    // the deterministic path. Moot in queue mode (it promotes nothing).
+    const remainingAcceptBudget = Math.max(0, Math.max(0, opts.maxAccepts) - deterministicPromoted);
+    // --- Judgment tier (Phase 3): adjudicate the deferred items ---
+    // Only runs when a RunnerSpec is configured. The runner returns a verdict; the
+    // ENGINE performs the resulting accept (respecting applyMode) / reject write.
+    if (opts.judgment && result.deferred.length > 0) {
+        const tier = await runJudgmentTier({
+            stashDir: opts.stashDir,
+            applyMode: opts.applyMode,
+            dryRun: opts.dryRun,
+            runner: opts.judgment,
+            deferred: result.deferred,
+            pending,
+            promoteFn,
+            rejectFn,
+            seams: judgmentSeams,
+            remainingAcceptBudget,
+        });
+        result.promoted.push(...tier.promoted);
+        result.rejected.push(...tier.rejected);
+        result.staged.push(...tier.staged);
+        // Judgment-tier accepts dropped by the shared accept cap surface under
+        // skippedByCap, same as deterministic cap drops.
+        result.skippedByCap.push(...tier.skippedByCap);
+        if (tier.skippedByCap.length > 0) {
+            info(`[triage] accept ceiling reached in judgment tier: ${tier.skippedByCap.length} judged-accept items skipped by cap (maxAccepts=${opts.maxAccepts})`);
+        }
+        // Replace the deferred list with only the items the judgment tier could NOT
+        // resolve (verdict "defer", parse failure, or runner error). Staged
+        // queue-mode accepts are RESOLVED and tracked in result.staged instead.
+        result.deferred = tier.stillDeferred;
+    }
+    emitDrainEvents(opts, result);
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+function emitDrainEvents(opts, result) {
+    const deferredByReason = {};
+    for (const d of result.deferred) {
+        deferredByReason[d.reason] = (deferredByReason[d.reason] ?? 0) + 1;
+    }
+    appendEvent({
+        eventType: "triage_drained",
+        metadata: {
+            promoted: result.promoted.length,
+            rejected: result.rejected.length,
+            deferredByReason,
+            skippedByCap: result.skippedByCap.length,
+            ...(result.staged.length > 0 ? { staged: result.staged.length } : {}),
+            policy: opts.policy.name,
+            applyMode: opts.applyMode,
+            ...(opts.dryRun ? { dryRun: true } : {}),
+        },
+    }, opts.eventsCtx ?? {});
+    // Surface any items the judge could NOT resolve after the (optional) judgment
+    // tier so a backlog of deferred items never silently looks like full success.
+    // This fires when no runner is configured OR the judgment tier ran but could
+    // not resolve every item (verdict "defer", parse failure, or a runner error).
+    // Queue-mode staged accepts are RESOLVED (the judge decided) and live in
+    // result.staged, so they are deliberately excluded from this "unresolved" count.
+    if (result.deferred.length > 0) {
+        appendEvent({
+            eventType: "triage_deferred",
+            metadata: {
+                deferred: result.deferred.length,
+                deferredByReason,
+                reason: opts.judgment ? "judgment tier left items unresolved" : "no judgment runner configured",
+            },
+        }, opts.eventsCtx ?? {});
+    }
+}