akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/proposal/drain.js

@@ -2,39 +2,20 @@
 // 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:
- *   - 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.
- *     Deterministic by design; only the configured drain policy decides.
- *   - Backlog-only: `excludeIds` removes this-run's fresh proposals so triage
- *     never re-adjudicates a current run's output (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 through the shared resolved/lowered execution boundary,
- *     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 reflect's dual test seams) so tests can run the full engine without
- * touching the filesystem or spawning a process.
+ * The proposal drain behind `akm proposal drain` and improve's triage pre-pass.
+ * One rule decides the pending backlog:
+ *   - an empty diff is rejected;
+ *   - a proposal whose quality judge passed on this exact content (a `staged`
+ *     gate decision carrying its content hash) is accepted, unless its target
+ *     changed since mint — then it is auto-rejected as `stale-target`, never
+ *     overwritten;
+ *   - everything else needs a judge: the judgment tier decides it when a runner
+ *     is configured, and whatever stays undecided is left for review
+ *     (`review_needed` in the improve ledger).
+ * `maxAccepts` caps promotions across both tiers; `applyMode: "queue"` never
+ * promotes; `excludeIds` keeps this run's fresh proposals out; a proposal the
+ * distill quality gate routed to a human is left for that human.
  */
-import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
@@ -44,165 +25,111 @@ import { ConfigError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { escapeJsonStringControls, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 import { info, warn } from "../../core/warn.js";
-import { acquireLoweredExecutionDispatchLease, dispatchLoweredExecutionRequest, disposeLoweredExecutionDispatchLease, lowerResolvedExecutionRequestWithRunner, } from "../../integrations/agent/execution-lowering.js";
-import { prepareInlineExecutionWithRunner } from "../../integrations/agent/inline-execution.js";
+import { buildExecution, resolveExecution } from "../../integrations/agent/execution.js";
+import { assertRunnerCredentials, runExecution, } from "../../integrations/agent/runner-dispatch.js";
+import { errMessage, noticeSet } from "../improve/stage.js";
 import { akmProposalAccept, akmProposalReject } from "./proposal.js";
-import { listProposals, listProposalsReadOnly, preflightProposalPromotion, proposalContent, recordGateDecision, } from "./repository.js";
-// ---------------------------------------------------------------------------
-// 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. */
+import { isRetireProposal, STALE_TARGET_GATE_REASON } from "./proposal-types.js";
+import { listProposals, listProposalsReadOnly, preflightProposalPromotion, proposalContent, proposalContentHash, readFreshProposalTarget, recordGateDecision, } from "./repository.js";
+/** The gate label on every decision the drain records. */
+const DRAIN_GATE = "triage";
+/** An empty diff: no non-blank body line outside the frontmatter. */
 export function isEmptyDiff(proposal) {
     const content = proposalContent(proposal);
     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 = proposalContent(proposal);
-    // Empty / near-empty diffs reject first (the reject-empty floor).
-    if (policy.rejectEmpty && isEmptyDiff(proposal)) {
-        return { verdict: "reject", reason: "empty diff", gate: { reason: "empty-diff" } };
-    }
-    const rule = policy.accept.find((r) => {
-        if (r.generator !== proposal.source)
-            return false;
-        if (r.requireType !== undefined) {
-            const fm = parseFrontmatter(proposalContent(proposal)).data;
-            if (typeof fm.type !== "string" || fm.type !== r.requireType)
-                return false;
-        }
-        return true;
-    });
-    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",
-                gate: { reason: "max-diff-lines", measured: lines, thresholds: { maxDiffLines: effectiveMax } },
-            };
-        }
-        if (rule.minContentLines !== undefined && body < rule.minContentLines) {
-            // Too little content to confidently auto-accept — leave for judgment.
-            return {
-                verdict: "defer",
-                reason: "mid-band",
-                gate: { reason: "min-content-lines", measured: body, thresholds: { minContentLines: rule.minContentLines } },
-            };
-        }
-        return { verdict: "accept", gate: { reason: "policy-accept" } };
-    }
-    if (policy.defer.includes(proposal.source)) {
-        const reason = deferReasonForSource(proposal.source);
-        return { verdict: "defer", reason, gate: { reason } };
-    }
-    // No matching rule — leave pending, untouched.
-    return null;
-}
-function deferReasonForSource(source) {
-    return source === "distill" ? "possible-dup" : "mid-band";
+    return !parseFrontmatter(content)
+        .content.split("\n")
+        .some((line) => line.trim().length > 0);
 }
-/**
- * Map a thrown error's message to one of `DrainResult.failed`'s stable reason
- * codes, falling back to `fallback` for anything not specifically recognized.
- * Recognizes the write-time guards a proposal can trip during promotion
- * (see repository.ts's `promoteProposalWithLease` / `preflightProposalPromotion`).
- */
 function categorizeDrainFailure(message, fallback) {
     if (/target (?:changed after|was created after) proposal/.test(message))
-        return "stale-target";
+        return STALE_TARGET_GATE_REASON;
     if (/failed validation:/.test(message))
         return "validation";
     return fallback;
 }
-function pushDrainFailure(result, id, err, fallbackReason) {
-    const message = err instanceof Error ? err.message : String(err);
-    result.failed.push({ id, reason: categorizeDrainFailure(message, fallbackReason), detail: message });
-    return message;
-}
 /**
- * Mirror repository.ts's `promoteProposalWithLease` stale-target guard so a
- * dry-run preflight predicts the same refusal a real promote would hit,
- * without writing anything. `assetPath` is the path `preflightProposalPromotion`
- * already resolved for this proposal.
+ * The one accept path both tiers share. A dry run exercises the same stamped
+ * candidate, lint and freshness boundary a promotion would (tests that pass no
+ * config keep the classification-only seam). A stale target is not a merit
+ * rejection, so instead of failing identically every run it is auto-rejected
+ * once; the ledger records `failed`, keeping the ref re-proposable.
  */
-function assertProposalTargetFresh(proposal, assetPath) {
-    const backup = fs.existsSync(assetPath) ? fs.readFileSync(assetPath) : undefined;
-    const currentHash = backup ? createHash("sha256").update(backup).digest("hex") : undefined;
-    if (proposal.beforeHash !== undefined && (!backup || currentHash !== proposal.beforeHash)) {
-        throw new Error(`Proposal target changed after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+async function acceptProposal(opts, proposal, id, reason, promoteFn, rejectFn) {
+    const gateDecision = { outcome: "auto-accepted", reason, gate: DRAIN_GATE };
+    try {
+        if (!opts.dryRun) {
+            await promoteFn({
+                stashDir: opts.stashDir,
+                id,
+                ...(opts.target ? { target: opts.target } : {}),
+                ...(opts.config ? { config: opts.config } : {}),
+                gateDecision,
+            });
+        }
+        else if (opts.config) {
+            if (!proposal)
+                throw new Error(`Proposal ${id} disappeared during drain preflight.`);
+            const preflight = preflightProposalPromotion(opts.config, proposal, {
+                ...(opts.target ? { target: opts.target } : {}),
+                gateDecision,
+            });
+            readFreshProposalTarget(proposal, preflight.assetPath, preflight.stampedContent);
+        }
+        return "promoted";
     }
-    if (proposal.beforeHash === undefined &&
-        backup !== undefined &&
-        proposal.changes.some((change) => change.op === "create")) {
-        throw new Error(`Proposal target was created after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+    catch (err) {
+        const message = errMessage(err);
+        if (categorizeDrainFailure(message, "") !== STALE_TARGET_GATE_REASON)
+            return { message };
+        if (opts.dryRun)
+            return "rejected";
+        try {
+            await rejectFn({
+                stashDir: opts.stashDir,
+                id,
+                reason: `stale-target: ${message}`,
+                gateDecision: { outcome: "auto-rejected", reason: STALE_TARGET_GATE_REASON, gate: DRAIN_GATE },
+            });
+            return "rejected";
+        }
+        catch (rejectErr) {
+            warn(`[triage] stale-target auto-reject failed for ${id}: ${errMessage(rejectErr)}`);
+            return { message };
+        }
     }
 }
-// ---------------------------------------------------------------------------
-// Judgment tier (Phase 3)
-// ---------------------------------------------------------------------------
-/** Read the live on-disk content of a proposal's target asset, if it exists. */
-function readLiveAssetContent(stashDir, ref) {
+/** Reject one proposal (nothing in a dry run); the error message on failure. */
+async function rejectProposal(opts, id, reason, gateReason, rejectFn) {
+    if (opts.dryRun)
+        return undefined;
     try {
-        const parsed = parseRefInput(ref);
-        const typeDir = stashDirFor(parsed.type);
-        if (!typeDir)
-            return undefined;
-        const typeRoot = path.join(stashDir, typeDir);
-        const assetPath = assetPathForName(parsed.type, typeRoot, parsed.name);
-        if (!fs.existsSync(assetPath))
-            return undefined;
-        return fs.readFileSync(assetPath, "utf8");
-    }
-    catch {
+        await rejectFn({
+            stashDir: opts.stashDir,
+            id,
+            reason,
+            gateDecision: { outcome: "auto-rejected", reason: gateReason, gate: DRAIN_GATE },
+        });
         return undefined;
     }
+    catch (err) {
+        return errMessage(err);
+    }
 }
-/**
- * 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. */
+/** The judgment prompt: the proposal, the live asset it would overwrite, and same-ref siblings. */
 export function buildJudgmentPrompt(proposal, reason, ctx) {
-    const proposed = proposalContent(proposal);
     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.",
+        "You are adjudicating a pending knowledge-base proposal no quality judge has",
+        "passed yet. Decide whether to accept, reject, or defer it.",
         "",
         `Asset ref: ${proposal.ref}`,
         `Generator (source): ${proposal.source}`,
-        `Deferred because: ${reason}`,
+        `Left for judgment because: ${reason === "needs-judgment" ? "no quality judge has passed this content yet" : reason}`,
         "",
         "## Proposed content",
         "```",
-        proposed,
+        proposalContent(proposal),
         "```",
     ];
     if (ctx.liveAsset !== undefined) {
@@ -220,15 +147,12 @@ export function buildJudgmentPrompt(proposal, reason, ctx) {
     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. */
+/** A verdict from raw runner output (the first JSON object), or null. */
 export function parseJudgmentVerdict(raw) {
     const cleaned = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(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)
+    if (start === -1 || end <= start)
         return null;
     let obj;
     try {
@@ -237,479 +161,244 @@ export function parseJudgmentVerdict(raw) {
     catch {
         return null;
     }
-    if (typeof obj !== "object" || obj === null)
-        return null;
-    const decision = obj.decision;
-    const reason = obj.reason;
+    const { decision, reason } = (obj ?? {});
     if (decision !== "accept" && decision !== "reject" && decision !== "defer")
         return null;
     return { decision, reason: typeof reason === "string" ? reason : "" };
 }
-async function dispatchJudgment(runner, prompt, seams, lease) {
-    const prepared = prepareInlineExecutionWithRunner({
-        content: prompt,
-        runner,
-        invocationKind: "direct",
-    });
-    const lowered = lowerResolvedExecutionRequestWithRunner(prepared.request, prepared.runner);
-    const chat = seams.chat;
-    const llmRunner = lowered.runner.kind === "llm" ? lowered.runner : undefined;
-    const dispatchOptions = {
-        lease,
-        ...(seams.runAgentFn ? { runAgent: seams.runAgentFn } : {}),
-        ...(seams.runSdkFn ? { runSdk: seams.runSdkFn } : {}),
-        ...(chat && llmRunner
-            ? {
-                chat: async (connection, messages) => chat({ ...llmRunner, connection }, messages),
-            }
-            : {}),
-    };
-    let result;
+/** Lower the judgment prompt through the frozen runner and dispatch it. */
+async function dispatchJudgment(runner, prompt, seams) {
+    let notices = [];
     try {
-        result = await dispatchLoweredExecutionRequest(lowered, dispatchOptions);
+        const prepared = resolveExecution({ content: prompt, runner });
+        const lowered = buildExecution(prepared.request, prepared.runner);
+        notices = lowered.notices;
+        const chat = seams.chat;
+        const llmRunner = lowered.runner.kind === "llm" ? lowered.runner : undefined;
+        const result = await runExecution(lowered, {
+            ...(seams.runAgentFn ? { runAgent: seams.runAgentFn } : {}),
+            ...(seams.runSdkFn ? { runSdk: seams.runSdkFn } : {}),
+            ...(chat && llmRunner
+                ? { chat: async (connection, messages) => chat({ ...llmRunner, connection }, messages) }
+                : {}),
+        });
+        if (!result.ok)
+            return { verdict: null, notices, error: result.error ?? result.reason ?? "unknown error" };
+        return { verdict: parseJudgmentVerdict(result.stdout), notices };
     }
     catch (error) {
         if (error instanceof ConfigError)
             throw error;
-        return {
-            verdict: null,
-            notices: lowered.notices,
-            error: error instanceof Error ? error.message : String(error),
-        };
+        return { verdict: null, notices, error: errMessage(error) };
     }
-    if (!result.ok) {
-        return {
-            verdict: null,
-            notices: lowered.notices,
-            error: result.error ?? result.reason ?? "unknown error",
-        };
-    }
-    return { verdict: parseJudgmentVerdict(result.stdout), notices: lowered.notices };
-}
-/** Validate symbolic judgment credentials without contacting a provider. */
-async function preflightJudgmentRunner(runner) {
-    const prepared = prepareInlineExecutionWithRunner({
-        content: "Validate the selected proposal judgment runner before mutation.",
-        runner,
-        invocationKind: "direct",
-    });
-    const lowered = lowerResolvedExecutionRequestWithRunner(prepared.request, prepared.runner);
-    return acquireLoweredExecutionDispatchLease(lowered);
-}
-function judgedContentHash(proposal) {
-    return createHash("sha256").update(proposalContent(proposal), "utf8").digest("hex");
 }
 /**
- * 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).
+ * The judgment tier: the runner only judges; the drain performs the accept
+ * (under `applyMode` and the remaining accept budget) or the reject. A defer, an
+ * unparseable verdict or a runner error leaves the item undecided.
  */
-async function runJudgmentTier(input) {
-    const byId = new Map(input.pending.map((p) => [p.id, p]));
-    const promoted = [];
-    const rejected = [];
-    const staged = [];
-    const skippedByCap = [];
+async function runJudgmentTier(opts, result, pending, acceptBudget, promoteFn, rejectFn, seams) {
+    const byId = new Map(pending.map((p) => [p.id, p]));
+    const notices = noticeSet();
     const stillDeferred = [];
-    const noticesByKey = new Map();
-    // Remaining accept budget shared with the deterministic promote loop.
-    let acceptBudget = Math.max(0, input.remainingAcceptBudget);
-    for (const item of input.deferred) {
+    const cappedBefore = result.skippedByCap.length;
+    for (const item of result.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 dispatch;
-        try {
-            dispatch = await dispatchJudgment(input.runner, prompt, input.seams, input.lease);
-        }
-        catch (err) {
-            if (err instanceof ConfigError)
-                throw err;
-            warn(`[triage] judgment dispatch failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
-            stillDeferred.push(item);
-            continue;
-        }
-        for (const notice of dispatch.notices) {
-            const key = JSON.stringify(notice);
-            if (!noticesByKey.has(key))
-                noticesByKey.set(key, notice);
-        }
-        if (dispatch.error) {
+        const prompt = buildJudgmentPrompt(proposal, item.reason, {
+            liveAsset: readLiveAssetContent(opts.stashDir, proposal.ref),
+            siblings: pending.filter((p) => p.ref === proposal.ref && p.id !== proposal.id),
+        });
+        const dispatch = await dispatchJudgment(opts.judgment, prompt, seams);
+        notices.add(dispatch.notices);
+        if (dispatch.error)
             warn(`[triage] judgment dispatch failed for ${item.id}: ${dispatch.error}`);
-            stillDeferred.push(item);
-            continue;
-        }
-        const verdict = dispatch.verdict;
+        const verdict = dispatch.error ? null : dispatch.verdict;
         if (!verdict || verdict.decision === "defer") {
             stillDeferred.push(item);
             continue;
         }
         if (verdict.decision === "reject") {
-            if (input.dryRun) {
-                rejected.push(item.id);
+            const failure = await rejectProposal(opts, item.id, verdict.reason || "judgment: reject", "judgment-reject", rejectFn);
+            if (failure === undefined) {
+                result.rejected.push(item.id);
+            }
+            else {
+                warn(`[triage] judgment reject failed for ${item.id}: ${failure}`);
+                stillDeferred.push(item);
+            }
+            continue;
+        }
+        // Queue mode never writes the asset: the verdict is staged for a later promote run.
+        if (opts.applyMode !== "promote") {
+            if (opts.dryRun) {
+                result.staged.push(item.id);
                 continue;
             }
             try {
-                await input.rejectFn({
-                    stashDir: input.stashDir,
-                    id: item.id,
-                    reason: verdict.reason || "judgment: reject",
-                    gateDecision: { outcome: "auto-rejected", reason: "judgment-reject", gate: input.gateLabel },
+                recordGateDecision(opts.stashDir, item.id, {
+                    outcome: "staged",
+                    reason: "judgment-accept",
+                    contentHash: proposalContentHash(proposal),
+                    gate: DRAIN_GATE,
                 });
-                rejected.push(item.id);
+                result.staged.push(item.id);
             }
             catch (err) {
-                warn(`[triage] judgment reject failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+                warn(`[triage] failed to stage judgment for ${item.id}: ${errMessage(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);
-            if (!input.dryRun) {
-                try {
-                    recordGateDecision(input.stashDir, item.id, {
-                        outcome: "staged",
-                        reason: "judgment-accept",
-                        contentHash: judgedContentHash(proposal),
-                        gate: input.gateLabel,
-                    });
-                }
-                catch (err) {
-                    warn(`[triage] failed to stage judgment for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
-                    staged.pop();
-                    stillDeferred.push(item);
-                }
-            }
-            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);
+            result.skippedByCap.push(item.id);
             continue;
         }
-        if (input.dryRun) {
-            try {
-                if (input.config) {
-                    preflightProposalPromotion(input.config, proposal, {
-                        ...(input.target ? { target: input.target } : {}),
-                        gateDecision: { outcome: "auto-accepted", reason: "judgment-accept", gate: input.gateLabel },
-                    });
-                }
-            }
-            catch (err) {
-                warn(`[triage] judgment preflight failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
-                stillDeferred.push(item);
-                continue;
-            }
-            promoted.push(item.id);
+        const outcome = await acceptProposal(opts, proposal, item.id, "judgment-accept", promoteFn, rejectFn);
+        if (outcome === "promoted") {
+            result.promoted.push(item.id);
             acceptBudget -= 1;
-            continue;
         }
-        try {
-            await input.promoteFn({
-                stashDir: input.stashDir,
-                id: item.id,
-                ...(input.target ? { target: input.target } : {}),
-                ...(input.config ? { config: input.config } : {}),
-                gateDecision: { outcome: "auto-accepted", reason: "judgment-accept", gate: input.gateLabel },
-            });
-            promoted.push(item.id);
-            acceptBudget -= 1;
+        else if (outcome === "rejected") {
+            result.rejected.push(item.id);
         }
-        catch (err) {
-            warn(`[triage] judgment promote failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+        else {
+            warn(`[triage] judgment ${opts.dryRun ? "preflight" : "promote"} failed for ${item.id}: ${outcome.message}`);
             stillDeferred.push(item);
         }
     }
-    return {
-        promoted,
-        rejected,
-        staged,
-        skippedByCap,
-        stillDeferred,
-        notices: Object.freeze([...noticesByKey.values()]),
-    };
+    const capped = result.skippedByCap.length - cappedBefore;
+    if (capped > 0) {
+        info(`[triage] accept ceiling reached in judgment tier: ${capped} judged-accept items skipped by cap (maxAccepts=${opts.maxAccepts})`);
+    }
+    if (notices.list().length > 0)
+        result.notices = notices.list();
+    result.deferred = stillDeferred;
+}
+/** The live asset a proposal would overwrite, if any. */
+function readLiveAssetContent(stashDir, ref) {
+    try {
+        const parsed = parseRefInput(ref);
+        const typeDir = stashDirFor(parsed.type);
+        if (!typeDir)
+            return undefined;
+        const assetPath = assetPathForName(parsed.type, path.join(stashDir, typeDir), parsed.name);
+        return fs.existsSync(assetPath) ? fs.readFileSync(assetPath, "utf8") : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
-/** Classify the queue without mutating proposal, event, or promotion state. */
-function classifyPendingProposals(opts) {
+/**
+ * Drain the pending backlog. `promoteFn` / `rejectFn` / `judgmentSeams` are
+ * test seams.
+ */
+export async function drainProposals(opts, promoteFn = akmProposalAccept, rejectFn = akmProposalReject, judgmentSeams = {}) {
     const exclude = opts.excludeIds ?? new Set();
-    // A configured judgment runner must be credential-validated before any live
-    // state connection or migration. Its classification pass therefore reads an
-    // isolated SQLite snapshot; deterministic-only drains retain the historical
-    // live/migrating queue read.
-    const pending = (opts.judgment ? listProposalsReadOnly : listProposals)(opts.stashDir, {
-        status: "pending",
-    }).filter((proposal) => !exclude.has(proposal.id));
-    const acceptIds = [];
-    const acceptGateReasons = new Map();
-    const rejectTargets = [];
-    const deferred = [];
-    const deferredGateDecisions = [];
-    const gateLabel = `triage:${opts.policy.name}`;
-    const needsJudge = new Set();
+    // A judgment runner's credentials are validated before any live state
+    // connection, so its classification reads an isolated snapshot.
+    const pending = (opts.judgment ? listProposalsReadOnly : listProposals)(opts.stashDir, { status: "pending" }).filter((proposal) => !exclude.has(proposal.id));
+    const result = { promoted: [], rejected: [], deferred: [], skippedByCap: [], staged: [], failed: [] };
+    const accepts = [];
+    const empties = [];
     for (const proposal of pending) {
-        // An authoritative rejection from another gate stays pending and is never
-        // silently overwritten by this triage policy.
-        if (proposal.gateDecision?.outcome === "auto-rejected" && !proposal.gateDecision.gate?.startsWith("triage:")) {
+        // A consolidate pair-pass `retire` proposal is never auto-decided here,
+        // whatever `applyMode` says (alpha.9 brief §A "Review"; spec §25.6):
+        // untouched, still pending, waiting for a direct `akm proposal accept`.
+        // Checked before isEmptyDiff, which reads proposalContent() and has
+        // nothing meaningful to read on a delete-primary change anyway.
+        if (isRetireProposal(proposal))
             continue;
-        }
-        if (proposal.gateDecision?.outcome === "staged" &&
-            proposal.gateDecision.gate === gateLabel &&
-            proposal.gateDecision.contentHash === judgedContentHash(proposal)) {
-            acceptIds.push(proposal.id);
-            acceptGateReasons.set(proposal.id, "judgment-accept");
+        const decision = proposal.gateDecision;
+        // Another gate's rejection stands; a human-review deferral from the distill
+        // quality gate is left for that human.
+        if (decision?.outcome === "auto-rejected" && !decision.gate?.startsWith(DRAIN_GATE))
             continue;
-        }
-        const decision = classifyProposal(proposal, opts.policy, opts.maxDiffLines);
-        if (decision === null)
+        if (decision?.outcome === "deferred" && decision.gate === "quality-gate")
             continue;
-        if (decision.verdict === "defer") {
-            deferredGateDecisions.push({
-                id: proposal.id,
-                decision: {
-                    outcome: "deferred",
-                    reason: decision.gate.reason,
-                    ...(decision.gate.measured !== undefined ? { measured: decision.gate.measured } : {}),
-                    ...(decision.gate.thresholds ? { thresholds: decision.gate.thresholds } : {}),
-                    gate: gateLabel,
-                },
-            });
-            if (!decision.gate.thresholds)
-                needsJudge.add(proposal.id);
-        }
-        if (decision.verdict === "accept") {
-            acceptIds.push(proposal.id);
-            acceptGateReasons.set(proposal.id, "policy-accept");
+        if (isEmptyDiff(proposal)) {
+            empties.push(proposal.id);
         }
-        else if (decision.verdict === "reject") {
-            rejectTargets.push({ id: proposal.id, reason: decision.reason });
+        else if (decision?.outcome === "staged" && decision.contentHash === proposalContentHash(proposal)) {
+            accepts.push({ id: proposal.id, reason: decision.gate === "quality-gate" ? "judge-passed" : "judgment-accept" });
         }
         else {
-            deferred.push({ id: proposal.id, reason: decision.reason });
+            result.deferred.push({ id: proposal.id, reason: "needs-judgment" });
         }
     }
-    return {
-        pending,
-        acceptIds,
-        acceptGateReasons,
-        rejectTargets,
-        deferred,
-        deferredGateDecisions,
-        gateLabel,
-        needsJudge,
-    };
-}
-/**
- * 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 classification = classifyPendingProposals(opts);
-    const { pending, acceptIds, acceptGateReasons, rejectTargets, deferredGateDecisions, gateLabel, needsJudge } = classification;
-    const result = {
-        promoted: [],
-        rejected: [],
-        deferred: classification.deferred,
-        skippedByCap: [],
-        staged: [],
-        failed: [],
-    };
-    // A configured judgment runner makes every deferred item dispatch-eligible.
-    // Validate its symbolic credentials before applying any deterministic gate,
-    // reject, promote, or event mutation. Provider/runtime failures remain the
-    // judgment tier's fail-soft responsibility after this configuration fence.
-    const dispatchLease = opts.judgment && result.deferred.length > 0 ? await preflightJudgmentRunner(opts.judgment) : undefined;
-    try {
-        for (const { id, decision } of deferredGateDecisions)
-            stampGateDecision(opts, id, decision);
-        // --- Reject empties (independent of the accept ceiling / applyMode) ---
-        for (const target of rejectTargets) {
-            if (opts.dryRun) {
-                result.rejected.push(target.id);
-                continue;
-            }
-            try {
-                await rejectFn({
-                    stashDir: opts.stashDir,
-                    id: target.id,
-                    reason: target.reason,
-                    gateDecision: { outcome: "auto-rejected", reason: "empty-diff", gate: gateLabel },
-                });
-                result.rejected.push(target.id);
-            }
-            catch (err) {
-                const message = pushDrainFailure(result, target.id, err, "reject-error");
-                warn(`[triage] reject failed for ${target.id}: ${message}`);
-            }
+    if (opts.judgment && result.deferred.length > 0) {
+        // Symbolic credentials are checked before any gate, reject or promote.
+        const prepared = resolveExecution({
+            content: "Validate the selected proposal judgment runner before mutation.",
+            runner: opts.judgment,
+        });
+        assertRunnerCredentials(buildExecution(prepared.request, prepared.runner).runner);
+    }
+    for (const id of empties) {
+        const failure = await rejectProposal(opts, id, "empty diff", "empty-diff", rejectFn);
+        if (failure === undefined) {
+            result.rejected.push(id);
         }
-        // --- 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})`);
+        else {
+            result.failed.push({ id, reason: categorizeDrainFailure(failure, "reject-error"), detail: failure });
+            warn(`[triage] reject failed for ${id}: ${failure}`);
         }
-        // --- 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) {
+    }
+    const cap = Math.max(0, opts.maxAccepts);
+    const withinCap = accepts.slice(0, cap);
+    result.skippedByCap = accepts.slice(cap).map((a) => a.id);
+    if (result.skippedByCap.length > 0) {
+        info(`[triage] accept ceiling reached: ${withinCap.length} promoted, ${result.skippedByCap.length} skipped by cap (maxAccepts=${opts.maxAccepts})`);
+    }
+    let promotedHere = 0;
+    if (opts.applyMode === "promote") {
+        if (!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,
-                        ...(opts.target ? { target: opts.target } : {}),
-                        ...(opts.config ? { config: opts.config } : {}),
-                        gateDecision: {
-                            outcome: "auto-accepted",
-                            reason: acceptGateReasons.get(id) ?? "policy-accept",
-                            gate: gateLabel,
-                        },
-                    });
-                    result.promoted.push(id);
-                    deterministicPromoted += 1;
-                }
-                catch (err) {
-                    const message = pushDrainFailure(result, id, err, "promote-error");
-                    warn(`[triage] promote failed for ${id}: ${message}`);
-                }
+        const byId = new Map(pending.map((proposal) => [proposal.id, proposal]));
+        for (const { id, reason } of withinCap) {
+            const outcome = await acceptProposal(opts, byId.get(id), id, reason, promoteFn, rejectFn);
+            if (outcome === "promoted") {
+                result.promoted.push(id);
+                promotedHere += 1;
             }
-        }
-        else if (opts.applyMode === "promote" && opts.dryRun) {
-            // Exercise the same stamped candidate, lint, and stale-target boundary as
-            // real promotion so a dry-run's predicted promotions match what a real
-            // run would do. Tests that omit config retain the classification-only seam.
-            const byId = new Map(pending.map((proposal) => [proposal.id, proposal]));
-            for (const id of withinCap) {
-                try {
-                    if (opts.config) {
-                        const proposal = byId.get(id);
-                        if (!proposal)
-                            throw new Error(`Proposal ${id} disappeared during drain preflight.`);
-                        const preflight = preflightProposalPromotion(opts.config, proposal, {
-                            ...(opts.target ? { target: opts.target } : {}),
-                            gateDecision: {
-                                outcome: "auto-accepted",
-                                reason: acceptGateReasons.get(id) ?? "policy-accept",
-                                gate: gateLabel,
-                            },
-                        });
-                        assertProposalTargetFresh(proposal, preflight.assetPath);
-                    }
-                    result.promoted.push(id);
-                    deterministicPromoted += 1;
-                }
-                catch (err) {
-                    const message = pushDrainFailure(result, id, err, "promote-error");
-                    warn(`[triage] preflight failed for ${id}: ${message}`);
-                }
+            else if (outcome === "rejected") {
+                result.rejected.push(id);
             }
-        }
-        // 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) {
-            if (!dispatchLease)
-                throw new TypeError("proposal judgment work requires an operation dispatch lease");
-            const tier = await runJudgmentTier({
-                stashDir: opts.stashDir,
-                applyMode: opts.applyMode,
-                dryRun: opts.dryRun,
-                runner: opts.judgment,
-                lease: dispatchLease,
-                deferred: result.deferred,
-                pending,
-                promoteFn,
-                rejectFn,
-                seams: judgmentSeams,
-                ...(opts.target ? { target: opts.target } : {}),
-                ...(opts.config ? { config: opts.config } : {}),
-                remainingAcceptBudget,
-                gateLabel,
-            });
-            result.promoted.push(...tier.promoted);
-            result.rejected.push(...tier.rejected);
-            result.staged.push(...tier.staged);
-            if (tier.notices.length > 0)
-                result.notices = tier.notices;
-            // 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;
-        }
-        else if (result.deferred.length > 0) {
-            // #577: no judgment runner configured — items deferred *because they need a
-            // judge* (mid-band / possible-dup, no threshold reason) stay pending solely
-            // for lack of one. Re-stamp those as `no-judge-configured` so the operator
-            // sees a per-proposal reason instead of inferring it from the run-level
-            // triage_deferred aggregate. Band-deferred items keep their specific reason
-            // (e.g. `max-diff-lines`), which is more actionable than "no judge".
-            for (const item of result.deferred) {
-                if (needsJudge.has(item.id)) {
-                    stampGateDecision(opts, item.id, { outcome: "deferred", reason: "no-judge-configured", gate: gateLabel });
-                }
+            else {
+                result.failed.push({
+                    id,
+                    reason: categorizeDrainFailure(outcome.message, "promote-error"),
+                    detail: outcome.message,
+                });
+                warn(`[triage] ${opts.dryRun ? "preflight" : "promote"} failed for ${id}: ${outcome.message}`);
             }
         }
-        emitDrainEvents(opts, result);
-        return result;
     }
-    finally {
-        if (dispatchLease)
-            disposeLoweredExecutionDispatchLease(dispatchLease);
+    if (opts.judgment && result.deferred.length > 0) {
+        await runJudgmentTier({ ...opts, judgment: opts.judgment }, result, pending, cap - promotedHere, promoteFn, rejectFn, judgmentSeams);
     }
-}
-/**
- * Persist a gate decision onto a proposal, honouring the dry-run contract
- * (a dry run performs zero writes, so it records nothing) and never letting a
- * persistence failure abort the drain (#577). Best-effort by design.
- */
-function stampGateDecision(opts, id, decision) {
-    if (opts.dryRun)
-        return;
-    try {
-        recordGateDecision(opts.stashDir, id, decision);
-    }
-    catch (err) {
-        warn(`[triage] failed to record gate decision for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+    // #577: whatever stays undecided is left for review (`review_needed` in the ledger).
+    if (!opts.dryRun) {
+        const reviewReason = opts.judgment ? "judgment-deferred" : "no-judge-configured";
+        for (const item of result.deferred) {
+            try {
+                recordGateDecision(opts.stashDir, item.id, { outcome: "deferred", reason: reviewReason, gate: DRAIN_GATE });
+            }
+            catch (err) {
+                warn(`[triage] failed to record gate decision for ${item.id}: ${errMessage(err)}`);
+            }
+        }
     }
+    emitDrainEvents(opts, result);
+    return result;
 }
-// ---------------------------------------------------------------------------
-// Events
-// ---------------------------------------------------------------------------
 function emitDrainEvents(opts, result) {
     const deferredByReason = {};
-    for (const d of result.deferred) {
+    for (const d of result.deferred)
         deferredByReason[d.reason] = (deferredByReason[d.reason] ?? 0) + 1;
-    }
     appendEvent({
         eventType: "triage_drained",
         metadata: {
@@ -718,17 +407,11 @@ function emitDrainEvents(opts, result) {
             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.
+    // Undecided items must never look like full success. Staged accepts were decided.
     if (result.deferred.length > 0) {
         appendEvent({
             eventType: "triage_deferred",