@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/escalation.js

@@ -0,0 +1,1009 @@
+// The optional escalation feature (the never-hand-to-a-human rule).
+//
+// OFF BY DEFAULT. With `[escalation] enabled = false` — what every shipped
+// config carries — nothing here runs: no rule is evaluated, no note is
+// rendered into any prompt, no mutation is built. `tests/escalation.test.ts`
+// pins that as a property, not a hope.
+//
+// ---------------------------------------------------------------------------
+// THE TWO INVARIANTS, AND HOW THEY ARE STRUCTURAL RATHER THAN PROMPTED
+// ---------------------------------------------------------------------------
+//
+// 1. THE REVIEWER STILL DECIDES. Escalation is additive notification beside a
+//    finished verdict; it never defers, never parks, never hands the review
+//    back (manifesto belief 2; there is no park).
+//
+//    Enforced by SHAPE, not by discipline: nothing in this module's public
+//    surface returns, produces or contains a `Verdict`. `deliverEscalations`
+//    resolves to `EscalationOutcome[]` — a delivery record — so there is no
+//    channel through which a verdict could be withheld, altered or postponed.
+//    The one caller (`src/verdicts.ts`) invokes it AFTER the verdict has been
+//    applied and the PR transitioned, wrapped so a throw cannot reach the
+//    verdict path. `tests/escalation.test.ts` re-reads this source and fails
+//    if the word `Verdict` ever appears in an exported signature here, and
+//    `tests/verdicts.test.ts` pins the verdict landed with escalation on
+//    against the same round with it off.
+//
+// 2. ESCALATE A QUESTION, NEVER A REVIEW. The human is never asked to "review
+//    this PR". They are pointed at one thing — a file and line range, a
+//    migration, a named decision — the smallest thing that actually needs
+//    their eyes. Handing someone a whole review is what this system exists to
+//    stop; an escalation that does it has failed even when it fired on exactly
+//    the right PR.
+//
+//    Enforced five ways — four braces and one belt. (a) `EscalationScope` is a
+//    discriminated union with no "the whole PR" member. (b)
+//    `validateEscalationRequest` refuses a scope whose path or decision is
+//    blank — an escalation with nothing to look at is not an escalation.
+//    (c) EVERY path in a scope must be a file THIS PR ACTUALLY TOUCHES —
+//    including a `decision` scope's optional one — compared exactly against
+//    the diff, so `path: "the entire diff"` or `path: "**"` cannot spell a
+//    whole-PR escalation. (d) the comment body is RENDERED from the scope
+//    by `renderEscalationComment`, and `decision` is capped to a NAME, not a
+//    paragraph. (e) the belt: all three free-text slots — `question`,
+//    `decision`, and a session's `why` — go through `asksForWholeReview`.
+//
+//    (a)–(d) are the BRACES and they are exact: a whole-PR *scope* is
+//    unspellable. (e) is a heuristic over natural language, it will never be
+//    complete, and it is deliberately tuned to under-block rather than over-
+//    block — a false positive is a SILENT DROP, and the braces are what the
+//    guarantee rests on.
+//
+// This is the discipline the codebase already has twice — `[check this]`
+// inline comments and the `### For a human to double-check` review section
+// both hand a person a small, minutes-verifiable job beside a finished verdict
+// (see `packages/pi-plugin/src/severity.ts`). Escalation is that mechanism WITH A NAMED
+// RECIPIENT, not a new one, and the rendered text deliberately reads like
+// them.
+//
+// ---------------------------------------------------------------------------
+// TRIGGERS
+// ---------------------------------------------------------------------------
+//
+// * Operator-defined DETERMINISTIC rules always fire. Paths touched, a PR
+//   label, a severity floor, a named check failing — `evaluateEscalationRules`
+//   is a pure function over facts the daemon already has, inspectable and
+//   testable with no LLM anywhere near it.
+// * The PR's session MAY ALSO escalate on its own judgement, when the operator
+//   turned that on. It is bounded three ways and must stay so: it can only
+//   reach a login in `[escalation] targets` (filtered here, daemon-side, not
+//   asked of the model), it can never replace a verdict (invariant 1), and it
+//   rides the same per-PR cap, the same dedup ledger and the same mutation
+//   gate as everything else.
+//
+// ---------------------------------------------------------------------------
+// DELIVERY
+// ---------------------------------------------------------------------------
+//
+// One path, daemon-owned, for both trigger kinds and both shapes — which is
+// what makes the target bound and the scope check structural instead of
+// prompt-level.
+//
+// * `comment` (the default): a gated `create_review` with `event: "COMMENT"`
+//   and `reviewPurpose: "escalation"` — the same mechanically-authored gated
+//   comment the migration pre-check posts. No new mutation
+//   kind, no new posting route, and (like the pre-check) it never claims the
+//   head, because it carries no verdict.
+// * `review_request`: the comment, PLUS the `request_reviewer` gate kind, so
+//   the PR enters that person's review-requested queue. GitHub's own UI frames
+//   that as "review this pull request" — precisely the framing invariant 2
+//   rules out — so the comment is NOT optional on this shape: it is what
+//   carries the narrow ask. `deliverEscalations` posts the comment first and
+//   requests only after it succeeded.
+//
+// Both ride the ONE MutationGate. `request_reviewer` is an ORDINARY kind:
+// suppressed in dry-run like everything else, never `forceLive`, never in
+// `APP_SELF_CONFIG_KINDS`.
+import { createHash } from "node:crypto";
+import { GitHubRequestError } from "./github.js";
+import { codePath } from "@quickchatai/pi-quickreview/src/codespan.js";
+import { globBody } from "@quickchatai/pi-quickreview/src/glob.js";
+import { severityRank } from "@quickchatai/pi-quickreview/src/severityrank.js";
+/**
+ * Stable identity of a scope, for the dedup ledger.
+ *
+ * Line numbers are deliberately not in the key. The unit a
+ * human experiences is "you were pointed at this file" — keying on the line
+ * range would make an escalation at lines 12–30 and one at 14–32 two distinct
+ * asks producing near-identical notes, which is the nag the ledger exists to
+ * prevent. Two genuinely different places in one file cost one escalation
+ * between them; `max_per_pr` bounds that anyway.
+ */
+export function scopeKey(scope) {
+    switch (scope.kind) {
+        case "code":
+            return `code:${scope.path}`;
+        case "migration":
+            return `migration:${scope.path}`;
+        case "decision":
+            // The decision text IS the identity here, and it is capped and
+            // whitespace-collapsed by normalizeScope, so it cannot drift by spacing.
+            return `decision:${scope.decision}:${scope.path ?? ""}`;
+    }
+}
+/** The scope as one operator-facing phrase — the "Look at:" line. Paths are
+ * the PR author's file names, so each renders through `codePath`: a name
+ * holding backticks or newlines stays inside its own code span instead of
+ * writing prose (or an @-mention) into a bot-authored comment. */
+export function renderScope(scope) {
+    switch (scope.kind) {
+        case "code": {
+            const lines = scope.start_line && scope.end_line && scope.end_line !== scope.start_line
+                ? `, lines ${scope.start_line}–${scope.end_line}`
+                : scope.start_line
+                    ? `, line ${scope.start_line}`
+                    : "";
+            return `${codePath(scope.path)}${lines}`;
+        }
+        case "migration":
+            return scope.migration
+                ? `migration ${codePath(scope.migration)} (${codePath(scope.path)})`
+                : `the migration in ${codePath(scope.path)}`;
+        case "decision":
+            return scope.path
+                ? `the decision "${scope.decision}" (${codePath(scope.path)})`
+                : `the decision "${scope.decision}"`;
+    }
+}
+/**
+ * Coerce a scope out of whatever a session wrote (or a rule assembled).
+ * Returns null when there is nothing concrete to look at — which is the
+ * refusal invariant 2 asks for, expressed as a value rather than a throw.
+ */
+export function normalizeScope(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const r = raw;
+    const str = (v) => (typeof v === "string" ? v.trim() : "");
+    const num = (v) => {
+        const n = typeof v === "string" && /^\d+$/.test(v.trim()) ? Number(v) : typeof v === "number" ? v : NaN;
+        return Number.isInteger(n) && n > 0 ? n : undefined;
+    };
+    const kind = str(r.kind).toLowerCase();
+    const path = str(r.path);
+    if (kind === "migration") {
+        if (!path)
+            return null;
+        const migration = str(r.migration).slice(0, 80);
+        return migration ? { kind: "migration", path, migration } : { kind: "migration", path };
+    }
+    if (kind === "decision") {
+        // Capped and whitespace-collapsed HERE, so `decision` cannot become a
+        // paragraph-length free-text field carrying a whole-review ask.
+        // `validateEscalationRequest` additionally puts it through
+        // `asksForWholeReview` (session origin), exactly like `question`.
+        const decision = decisionName(str(r.decision));
+        if (!decision)
+            return null;
+        return path ? { kind: "decision", decision, path } : { kind: "decision", decision };
+    }
+    // Default and by far the common case: a place in the code.
+    if (!path)
+        return null;
+    const start = num(r.start_line);
+    // An end without a start is meaningless, so a lone `end_line` is dropped.
+    const end = start === undefined ? undefined : num(r.end_line);
+    return {
+        kind: "code",
+        path,
+        ...(start !== undefined ? { start_line: start } : {}),
+        ...(end !== undefined ? { end_line: Math.max(end, start) } : {}),
+    };
+}
+/** Longest question we will carry. A paragraph is not a narrow ask. */
+export const MAX_ESCALATION_QUESTION = 400;
+/** Longest `decision` name. A decision is a NAME, not an essay — an uncapped
+ * one would be a route to a whole-review ask. */
+export const MAX_ESCALATION_DECISION = 120;
+/**
+ * Invariant 2's belt, and it is only a belt.
+ *
+ * The braces are structural: the union has no whole-PR member, a `code`/
+ * `migration` path must be a file the PR actually touches, the body is
+ * rendered from the scope, and `decision` is capped. What is left is two short
+ * free-text slots — `question` and `decision` — and this is what keeps a
+ * whole-review ask out of them.
+ *
+ * It must catch whole-review phrasings ("Could you cast an eye over all of
+ * it?", "Are you happy with everything here?") without treating `whole`,
+ * `entire`, `everything` as damning on their own. Those are the standard
+ * vocabulary of SCOPE-OF-EFFECT questions, and a scope-of-effect question is
+ * the canonical thing this feature exists to ask:
+ *
+ *     Does this lock the whole row, or just the counter?
+ *     Is the entire cache invalidated here, or only the tenant slice?
+ *
+ * A false positive here is a SILENT DROP — `escalation_refused`, no delivery,
+ * nobody told. Over-blocking is therefore the more expensive direction, not
+ * the safe one: it is the difference between a feature that works when
+ * switched on and one that quietly does not.
+ *
+ * So a breadth word only damns when it is talking about THE CHANGE:
+ *
+ *   BREADTH   — a word that means "the lot": whole, entire, everything,
+ *               all of it, a second pair of eyes, top to bottom… On its own
+ *               it means nothing; "the whole row" is as narrow as it gets.
+ *   ARTIFACT  — the change named as a whole: PR, diff, branch, the changes.
+ *   ASK       — a review-ish verb: review, sign off, cast an eye, happy with.
+ *
+ *   refuse ⟺ (BREADTH ∧ (ARTIFACT ∨ ASK)) ∨ (ARTIFACT ∧ ASK)
+ *
+ * "the whole row" has BREADTH and neither of the others — narrow, allowed.
+ * "the whole diff" has BREADTH and ARTIFACT — refused. Pure intensifiers
+ * (`at all`, `overall`) are deliberately NOT breadth words: "is this index
+ * used at all?" is a perfectly narrow question.
+ *
+ * It will never be complete — natural language is not a closed set. Whole-PR
+ * phrasings that name no artifact and use no breadth word ("Is this safe to
+ * merge?", "LGTM?", "Any objections?") get through, and that is accepted: the
+ * BRACES are what make a whole-PR *scope* unspellable, and this is only the
+ * belt over the free-text slots. Both sides are pinned in
+ * `tests/escalation.test.ts` — the phrasings it must catch, and the narrow
+ * questions it must not touch.
+ */
+// NB `at all` and `overall` are absent on purpose: they are pure
+// intensifiers, not breadth — "is this index used at all?" is narrow.
+const BREADTH_RE = /\b(?:whole|entire|everything|in general|as a whole|top to bottom|end[- ]to[- ]end|full review|all of (?:it|this|them|these)|it all|(?:second|another|extra|fresh) (?:pair|set) of eyes|review it|look at it)\b/i;
+const WHOLE_ARTIFACT_RE = /\b(?:pull\s*requests?|prs?|mrs?|merge\s*requests?|diffs?|branch|change\s?sets?|changes|patch|submission|the code here)\b/i;
+const REVIEW_ASK_RE = /\b(?:review(?:ed|ing|s)?|look(?:ed|ing)?\s+(?:at|over|through)|read(?:ing)?\s+(?:through|over)|check(?:ing|s)?\s+(?:over|through)|cast\s+(?:an?\s+)?eye|eyes?|glance|skim|scan|go(?:ing)?\s+through|sign(?:ing|s)?\s+off|approv(?:e|al|ing)|happy\s+with|comfortable\s+with|opinion\s+on|thoughts\s+on|merged?|ship(?:s|ped|ping)?|bless)\b/i;
+/**
+ * Does this text ask for a review of the change rather than a look at one
+ * thing? Applied to all THREE free-text slots — `question`, a `decision`
+ * name, and (for a session-origin escalation only) `why`.
+ */
+export function asksForWholeReview(text) {
+    const artifact = WHOLE_ARTIFACT_RE.test(text);
+    const ask = REVIEW_ASK_RE.test(text);
+    // A breadth word damns only when it is talking about the change — either by
+    // naming it, or by asking for a review of it.
+    if (BREADTH_RE.test(text) && (artifact || ask))
+        return true;
+    return artifact && ask;
+}
+/**
+ * Turn a candidate — a fired rule's assembly, or whatever a session wrote into
+ * its verdict file — into a deliverable request, or refuse it.
+ *
+ * Every gate invariant 2 and the target bound need lives here, in one
+ * function, so there is exactly one place to read and exactly one to test.
+ */
+export function validateEscalationRequest(raw, cfg, 
+/**
+ * WHERE THIS CANDIDATE CAME FROM — an argument, never a field on `raw`.
+ *
+ * This is a trust boundary. For a session candidate `raw` IS the verdict
+ * file's `escalations` entry, which the model writes, so an `origin` read
+ * off the candidate would let a session set `"origin": "rule"`, buy the
+ * rule-origin belt exemption on all three free-text slots, and forge the
+ * audit trail besides (the ledger row and the rendered comment both name
+ * the rule it claimed).
+ *
+ * `verdicts.ts` builds the two groups separately, so origin is a property
+ * of the CALL SITE.
+ */
+origin, 
+/**
+ * The PR's changed files. Every path in a scope must name one of them, so
+ * `path: "the entire diff"` or `path: "**"` cannot spell a whole-PR
+ * escalation.
+ *
+ * REQUIRED IN PRACTICE. `deliverEscalations` always passes it, and when the
+ * file listing is unavailable it passes `[]` — so every path-bearing scope
+ * is refused rather than waved through. Silence beats a whole-PR ask, and
+ * that is the same direction every other unreadable fact takes here. The
+ * parameter is optional only so `decision`-scoped unit cases and callers
+ * with no diff in reach can still validate the rest.
+ */
+changedPaths) {
+    if (!cfg.enabled)
+        return { ok: false, refusal: "disabled" };
+    if (typeof raw !== "object" || raw === null)
+        return { ok: false, refusal: "no-scope" };
+    const r = raw;
+    const str = (v) => (typeof v === "string" ? v.trim() : "");
+    const target = str(r.target).replace(/^@/, "");
+    if (!target)
+        return { ok: false, refusal: "no-target" };
+    // THE BOUND. Filtered daemon-side against the operator's list — never asked
+    // of the model, never negotiable by the text of a verdict file.
+    if (!cfg.targets.includes(target))
+        return { ok: false, refusal: "target-not-configured" };
+    // NB `r.origin` is deliberately NOT read. The caller says where this came
+    // from; a candidate that labels itself is labelling its own trust level.
+    if (origin === "session" && !cfg.session_judgement)
+        return { ok: false, refusal: "session-judgement-off" };
+    const scope = normalizeScope(r.scope);
+    if (!scope)
+        return { ok: false, refusal: "no-scope" };
+    // EVERY path in a scope must be a REAL file in this PR's diff — including a
+    // `decision` scope's OPTIONAL path, which would otherwise render any string
+    // and mint a distinct dedup key. Compared exactly against what GitHub
+    // returned — no globbing, no prefix match, nothing an invented string could
+    // satisfy.
+    const scopePath = scope.path;
+    if (scopePath !== undefined && changedPaths !== undefined && !changedPaths.includes(scopePath)) {
+        return { ok: false, refusal: "path-not-in-diff" };
+    }
+    const oneLine = (v) => str(v).replace(/\s+/g, " ").slice(0, MAX_ESCALATION_QUESTION);
+    const question = oneLine(r.question);
+    if (!question)
+        return { ok: false, refusal: "no-question" };
+    const why = oneLine(r.why);
+    // ---- the belt, and exactly whose text it guards -------------------------
+    //
+    // All THREE free-text slots — `question`, a `decision` name, and `why` —
+    // but only on a SESSION-origin escalation, because that is the text a MODEL
+    // wrote. Rule-origin text is the operator's own config plus our template:
+    //
+    //   * `why` is rendered verbatim by design; an operator may word their
+    //     reason however they like. (A session's `why` IS belted, or a narrow
+    //     question could ride beside a "**Why you:** just review the whole
+    //     thing and sign off".)
+    //   * a rule's `question` and `decision` are composed by `questionForRule`
+    //     and `scopeForRule` from the operator's own rule name, label or check
+    //     name. Belting those means an operator who names a label
+    //     "review the whole thing" gets their fired rule SILENTLY DROPPED —
+    //     a false positive is a silent drop, and this feature's worst failure
+    //     is a configured rule that quietly does nothing.
+    //
+    // Model-written text CAN reach a rule-built scope — a finding's reason and
+    // its path both come from the reasoning record. Neither is handled here:
+    // the reason is filtered where it enters (`scopeForRule`), so a trip costs
+    // that candidate its scope rather than dropping the operator's whole rule,
+    // and the path is caught by the path-in-diff check above, which sits OUTSIDE
+    // this origin gate on purpose.
+    //
+    // `origin` is an ARGUMENT. A candidate cannot elect itself into the exempt
+    // group by writing `"origin": "rule"` — see the parameter's docstring.
+    if (origin === "session") {
+        if (asksForWholeReview(question))
+            return { ok: false, refusal: "asks-for-whole-review" };
+        if (scope.kind === "decision" && asksForWholeReview(scope.decision)) {
+            return { ok: false, refusal: "asks-for-whole-review" };
+        }
+        if (asksForWholeReview(why))
+            return { ok: false, refusal: "asks-for-whole-review" };
+    }
+    // Likewise the rule NAME: only a rule-origin candidate may carry one, and
+    // that one was written by `evaluateEscalationRules` from the operator's own
+    // config. A session naming a rule would forge the ledger row and the
+    // "_Escalated by the configured rule `x`._" line for a rule that need not
+    // even exist.
+    const rule = origin === "rule" ? str(r.rule) : "";
+    return {
+        ok: true,
+        request: {
+            target,
+            scope,
+            question,
+            why: why || "named by the operator as the person to ask about this",
+            origin,
+            ...(rule ? { rule } : {}),
+        },
+    };
+}
+/** Is `severity` at or above `floor`? Unknown spellings never satisfy a floor
+ * — a rule must not fire on a severity nobody can read. */
+export function severityAtLeast(severity, floor) {
+    const s = severityRank(severity);
+    return s !== undefined && s <= severityRank(floor);
+}
+/**
+ * Glob match, deliberately small: `*` matches within a path segment, `**`
+ * across segments, everything else is literal. No dependency, and the whole
+ * grammar fits in the config comment an operator reads.
+ */
+export function pathMatches(pattern, path) {
+    return new RegExp(`^${globBody(pattern)}$`).test(path);
+}
+// One predicate per condition, shared by `ruleFires` (does any fact match?)
+// and `scopeForRule` (which fact matched?), so the two never disagree.
+const sameName = (a, b) => a.toLowerCase() === b.toLowerCase();
+const pathHits = (rule, path) => rule.paths.some((pat) => pathMatches(pat, path));
+const labelHits = (rule, label) => rule.labels.some((n) => sameName(n, label));
+const checkHits = (rule, check) => rule.failing_checks.some((n) => sameName(n, check));
+const findingHits = (rule, f) => severityAtLeast(String(f.severity ?? ""), rule.min_severity);
+/** A `decision` name: whitespace collapsed, trimmed, capped. */
+function decisionName(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, MAX_ESCALATION_DECISION);
+}
+/** Did this rule's conditions all hold? A rule with no condition never fires
+ * (config validation refuses one, so this is belt). */
+export function ruleFires(rule, facts) {
+    let declared = 0;
+    if (rule.paths.length > 0) {
+        declared++;
+        if (!facts.changed_paths.some((p) => pathHits(rule, p)))
+            return false;
+    }
+    if (rule.labels.length > 0) {
+        declared++;
+        if (!facts.labels.some((l) => labelHits(rule, l)))
+            return false;
+    }
+    if (rule.failing_checks.length > 0) {
+        declared++;
+        if (!facts.failing_checks.some((c) => checkHits(rule, c)))
+            return false;
+    }
+    if (rule.min_severity) {
+        declared++;
+        if (!facts.findings.some((f) => findingHits(rule, f)))
+            return false;
+    }
+    return declared > 0;
+}
+/** The scope one matching finding points at: its anchor, else the decision
+ * its title names (belted), else none. */
+function findingScope(hit) {
+    if (hit.path)
+        return { kind: "code", path: hit.path };
+    // The finding's reason is model-written text reaching a rule-built scope,
+    // so it is belted HERE, at the boundary it enters — not in
+    // `validateEscalationRequest`, where a trip would drop the operator's whole
+    // rule instead of just this candidate name. A reason that asks for a whole
+    // review simply yields no scope, and the caller reports
+    // `no-scope-derivable`.
+    //
+    // It is not the only model-written field that gets here: `hit.path` above
+    // comes from the same findings record. That one needs no belt because the
+    // unconditional path-in-diff check in `validateEscalationRequest` sits
+    // OUTSIDE the origin gate and catches it — deliberately, since a path is
+    // checkable against a fact and prose is not.
+    if (hit.title) {
+        const decision = decisionName(hit.title);
+        if (!asksForWholeReview(decision))
+            return { kind: "decision", decision };
+    }
+    return null;
+}
+/**
+ * The scope a fired rule points at. A rule names a CLASS of thing, so the
+ * scope is derived from the fact that actually matched — the touched file, the
+ * finding's anchor, the failing check — never "the PR".
+ */
+export function scopeForRule(rule, facts) {
+    if (rule.paths.length > 0) {
+        const hit = facts.changed_paths.find((p) => pathHits(rule, p));
+        if (hit)
+            return /(^|\/)migrations?\//i.test(hit)
+                ? { kind: "migration", path: hit }
+                : { kind: "code", path: hit };
+    }
+    if (rule.min_severity) {
+        // The first matching finding that yields a scope the PR admits (an anchor
+        // in the diff, or a decision); else the first one's, so its refusal is
+        // what gets reported.
+        const scopes = facts.findings.filter((f) => findingHits(rule, f)).map((f) => findingScope(f));
+        const usable = scopes.find((sc) => sc && (sc.kind !== "code" || facts.changed_paths.includes(sc.path)));
+        if (usable)
+            return usable;
+        if (scopes[0])
+            return scopes[0];
+    }
+    if (rule.failing_checks.length > 0) {
+        const hit = facts.failing_checks.find((c) => checkHits(rule, c));
+        if (hit)
+            return { kind: "decision", decision: `the failing check "${hit}"` };
+    }
+    if (rule.labels.length > 0) {
+        const hit = facts.labels.find((l) => labelHits(rule, l));
+        if (hit)
+            return {
+                kind: "decision",
+                decision: `what the "${hit}" label is asking for on this pull request`,
+            };
+    }
+    return null;
+}
+/**
+ * The question a fired rule asks. Narrow by construction — it names the scope
+ * and the rule, and asks for a judgement on that one thing.
+ *
+ * This wording and the label decision above use natural phrasing: the belt
+ * (`asksForWholeReview`) does not run on rule-origin text, so a rule-built
+ * string never needs rewording to dodge it. `tests/escalation.test.ts` pins
+ * that a fired rule is never dropped by its wording, the operator's own
+ * included.
+ */
+export function questionForRule(rule, scope) {
+    const full = `Your rule "${rule.name}" fires on this change. Is ${renderScope(scope)} right, in your judgement?`;
+    // Validation cuts a question at MAX_ESCALATION_QUESTION, which could drop the
+    // closing delimiter of a rendered path; a long one is left to the note's
+    // "Look at" line, which carries the scope whole.
+    if (full.length <= MAX_ESCALATION_QUESTION)
+        return full;
+    return `Your rule "${rule.name}" fires on this change. Is the scope under "Look at" right, in your judgement?`;
+}
+/**
+ * Evaluate the operator's rules. Pure: same facts in, same escalations out,
+ * no I/O, no model. This is the function `tests/escalation.test.ts` drives to
+ * prove the deterministic half is inspectable without an LLM.
+ */
+export function evaluateEscalationRules(cfg, facts, 
+/**
+ * Called when a rule FIRED but its candidate did not survive validation.
+ *
+ * A deterministic rule that silently produces nothing is the worst failure
+ * this feature has: the operator configured it, it
+ * matched, and nobody was told — including the operator. Session-origin
+ * candidates already log `escalation_refused` at delivery; this is the same
+ * visibility for the half that is refused before delivery is even reached.
+ * Optional so the function stays pure for its own tests.
+ */
+onRefused) {
+    if (!cfg.enabled)
+        return [];
+    const out = [];
+    for (const rule of cfg.rules) {
+        if (!ruleFires(rule, facts))
+            continue;
+        const scope = scopeForRule(rule, facts);
+        if (!scope) {
+            // Nothing concrete to point at ⇒ no escalation (invariant 2), but the
+            // operator's rule DID fire, so this is not silence.
+            onRefused?.(rule, "no-scope-derivable");
+            continue;
+        }
+        const candidate = {
+            target: rule.to,
+            scope,
+            question: questionForRule(rule, scope),
+            why: rule.why,
+            rule: rule.name,
+        };
+        // Validated against the SAME facts the scope came from — so a rule firing
+        // on a finding anchored outside the diff is refused here rather than
+        // pointing a person at a file this PR does not touch. Origin is passed,
+        // not embedded: this call site IS the operator's half.
+        const v = validateEscalationRequest(candidate, cfg, "rule", facts.changed_paths);
+        if (v.ok)
+            out.push(v.request);
+        else
+            onRefused?.(rule, v.refusal);
+    }
+    return out;
+}
+// ---- the rendered note ----------------------------------------------------
+/** The marker every escalation comment opens with — one grammar, greppable,
+ * and never confusable with the three finding markers in `packages/pi-plugin/src/severity.ts`. */
+export const ESCALATION_TAG = "[one thing to look at]";
+/**
+ * The escalation body. Everything structural is composed from the scope, which
+ * is exact: it names one file, migration or decision, and a path in it is a
+ * file this PR touches.
+ *
+ * The free-text slots are `question`, a `decision` name and `why`. On a
+ * SESSION escalation all three are belted by `asksForWholeReview` (a heuristic
+ * — see its docstring). On a RULE escalation `why` is the operator's own text
+ * and is rendered VERBATIM by design, so this function can and will render
+ * whatever they wrote there, "please review this PR" included. That is their
+ * call to make about their own reviewers; what it cannot do is change the
+ * scope the note points at.
+ */
+export function renderEscalationComment(req, ctx) {
+    const round = ctx.round_no ? ` (round ${ctx.round_no})` : "";
+    const lines = [
+        `${ESCALATION_TAG} @${req.target} — one specific thing, not a review of this pull request.`,
+        "",
+        `**Look at:** ${renderScope(req.scope)}`,
+        `**Why you:** ${req.why}`,
+        `**The question:** ${req.question}`,
+        "",
+        ctx.review_posted
+            ? `This review is already decided and posted${round} — the verdict is **${ctx.verdict}** and it does not ` +
+                "wait on you. This note asks only for your eyes on the item above."
+            : `This review is already decided${round} — the verdict is **${ctx.verdict}** and it does not wait on you. ` +
+                "This note asks only for your eyes on the item above. (The review itself is not confirmed on this pull " +
+                "request yet; if you cannot find it, that is why, and it is not something you need to chase.)",
+    ];
+    if (ctx.review_requested) {
+        lines.push("", 
+        // Conditional on purpose: this note is posted BEFORE the request is
+        // made, and the request can still fail (GitHub 422s the PR author or a
+        // non-collaborator) — so it must not promise the queue entry.
+        "_A review request is also being sent to you, so this pull request may appear in your " +
+            "review-requested queue: that is how the notification is delivered, and GitHub words it as " +
+            '"review this pull request". It is not what is being asked. The item above is._');
+    }
+    if (req.origin === "rule" && req.rule) {
+        lines.push("", `_Escalated by the configured rule \`${req.rule}\`._`);
+    }
+    return lines.join("\n");
+}
+// ---- the prompt-side half -------------------------------------------------
+// The targets a round order carries and the round-prompt block live in
+// packages/pi-plugin/src/escalationprompt.ts (the review core renders the prompt); re-exported.
+export { promptTargetsFor, renderEscalationPromptNote, } from "@quickchatai/pi-quickreview/src/escalationprompt.js";
+/** The most `escalations` entries one verdict file is read for. */
+const MAX_SESSION_ESCALATIONS = 10;
+/**
+ * Pull the `escalations` array out of a verdict file, tolerantly.
+ *
+ * Deliberately total: anything unreadable comes back as `[]` with a note.
+ * A malformed escalation must never fail a verdict — that would be invariant 1
+ * lost at the parser.
+ */
+export function normalizeSessionEscalations(raw) {
+    if (raw === undefined || raw === null)
+        return { entries: [] };
+    if (!Array.isArray(raw))
+        return { entries: [], note: "escalations was not an array — ignored" };
+    const objects = raw.filter((e) => typeof e === "object" && e !== null);
+    const entries = objects.slice(0, MAX_SESSION_ESCALATIONS);
+    const notes = [];
+    if (objects.length < raw.length)
+        notes.push(`${raw.length - objects.length} escalation entr(ies) were not objects — ignored`);
+    if (entries.length < objects.length)
+        notes.push(`${objects.length - entries.length} escalation entr(ies) past the first ${MAX_SESSION_ESCALATIONS} — ignored`);
+    return { entries, ...(notes.length ? { note: notes.join("; ") } : {}) };
+}
+/** Stable evidence attached to the one narrow comment, never a retry nonce. */
+function escalationMarker(pr, target, key, head) {
+    return `<!-- qcr-escalation:${createHash("sha256")
+        .update(JSON.stringify([pr, target, key, head]))
+        .digest("hex")} -->`;
+}
+const activeEscalations = new WeakMap();
+function recoveryOutcome(row, executed, requested) {
+    return {
+        target: row.target,
+        scope_key: row.scope_key,
+        origin: row.origin,
+        refused: null,
+        comment_executed: executed,
+        ...(row.shape === "review_request" ? { review_requested: requested ?? false } : {}),
+    };
+}
+/** A 422 is the existing terminal policy; network/5xx failures still owe the queue write. */
+function terminalRequestFailure(error) {
+    const status = typeof error === "object" && error !== null
+        ? error.status
+        : undefined;
+    return (status === 422 ||
+        (status === undefined && /requested_reviewers[^\n]*(?:→|HTTP)\s*422\b/.test(String(error))));
+}
+async function continueEscalation(deps, row, journal = true) {
+    const { store, adapter, cfg } = deps;
+    if (deps.isDraining?.() ||
+        (row.next_attempt_at && row.next_attempt_at > new Date().toISOString()))
+        return recoveryOutcome(row, row.phase === "request_pending");
+    const log = deps.log ?? (() => { });
+    const busy = activeEscalations.get(store) ?? new Set();
+    activeEscalations.set(store, busy);
+    if (busy.has(row.pr))
+        return recoveryOutcome(row, false);
+    busy.add(row.pr);
+    const note = (error) => {
+        if (journal)
+            store.noteEscalationRecovery(row, error);
+    };
+    const finish = () => {
+        if (journal)
+            store.finishEscalationRecovery(row);
+    };
+    try {
+        if (!cfg.targets.includes(row.target)) {
+            note("paused: target no longer configured");
+            return recoveryOutcome(row, false);
+        }
+        if (row.phase === "request_pending" && cfg.shape !== "review_request") {
+            note("paused: review-request shape disabled");
+            return recoveryOutcome(row, true);
+        }
+        let deliveredNow = false;
+        if (row.phase === "posting") {
+            let found;
+            let readError;
+            try {
+                found = await adapter.findEscalationComment?.(row.pr, row.head_sha, row.marker, row.body);
+            }
+            catch (error) {
+                readError = `comment read unavailable: ${String(error)}`;
+            }
+            if (!found) {
+                note(readError ?? "comment delivery remains unknown; no matching marker confirmed");
+                store.logEvent("escalation_comment_unknown", row.pr, {
+                    target: row.target,
+                    scope_key: row.scope_key,
+                });
+                return recoveryOutcome(row, false);
+            }
+            store.settleEscalationComment(row);
+            deliveredNow = true;
+            store.logEvent("escalation_comment_recovered", row.pr, {
+                target: row.target,
+                scope_key: row.scope_key,
+                comment_id: found.id,
+            });
+            row = { ...row, phase: "request_pending" };
+        }
+        else if (row.phase === "prepared") {
+            if (store.escalationCount(row.pr) >= cfg.max_per_pr) {
+                finish();
+                store.logEvent("escalation_capped", row.pr, {
+                    target: row.target,
+                    scope_key: row.scope_key,
+                    max_per_pr: cfg.max_per_pr,
+                });
+                return { ...recoveryOutcome(row, false), refused: "capped" };
+            }
+            if (journal &&
+                store.escalationCount(row.pr) + store.escalationPostingCount(row.pr) >= cfg.max_per_pr) {
+                note("capacity reserved by unresolved comment POST");
+                return { ...recoveryOutcome(row, false), refused: "capped" };
+            }
+            if (journal && !store.claimEscalationComment(row))
+                return recoveryOutcome(row, false);
+            let result;
+            try {
+                result = await adapter.createReview(row.pr, { commit_id: row.head_sha, event: "COMMENT", body: row.body }, { purpose: "escalation" });
+            }
+            catch (error) {
+                if (journal &&
+                    error instanceof GitHubRequestError &&
+                    error.status >= 400 &&
+                    error.status < 500 &&
+                    error.status !== 408) {
+                    if (error.status === 422 || error.status === 400 || error.status === 410)
+                        finish();
+                    else
+                        store.retryEscalationComment(row, `comment POST refused: ${String(error)}`, new Date(Date.now() + Math.max(30_000, error.retryAfterMs ?? 0)).toISOString());
+                }
+                else
+                    note(`comment POST outcome unknown: ${String(error)}`);
+                store.logEvent("escalation_comment_failed", row.pr, {
+                    target: row.target,
+                    scope_key: row.scope_key,
+                    origin: row.origin,
+                    round_no: row.round_no,
+                    error: String(error),
+                });
+                log(`escalation: #${row.pr} → @${row.target} comment failed: ${String(error)}`);
+                return recoveryOutcome(row, false);
+            }
+            if (result.blocked) {
+                // pr-unreadable is a failed GitHub read inside the guard, not a
+                // decision about the PR: the obligation stays owed and is retried.
+                if (journal && result.blocked === "pr-unreadable")
+                    store.retryEscalationComment(row, `comment blocked: ${result.blocked}`, new Date(Date.now() + 30_000).toISOString());
+                else
+                    finish();
+                store.logEvent("escalation_blocked", row.pr, {
+                    target: row.target,
+                    scope_key: row.scope_key,
+                    reason: result.blocked,
+                });
+                return recoveryOutcome(row, false);
+            }
+            if (!result.executed) {
+                // Preserve both dry-run intents; neither spends a delivery cap slot.
+                let requested = false;
+                if (row.shape === "review_request" && adapter.requestEscalationReview) {
+                    try {
+                        requested = (await adapter.requestEscalationReview(row.pr, [row.target])).executed;
+                    }
+                    catch (error) {
+                        log(`escalation: dry-run reviewer intent failed`, error);
+                    }
+                }
+                finish();
+                store.logEvent("escalation_not_executed", row.pr, {
+                    target: row.target,
+                    scope_key: row.scope_key,
+                    shape: row.shape,
+                    origin: row.origin,
+                    round_no: row.round_no,
+                    dry_run_file: result.dryRunFile ?? null,
+                });
+                return recoveryOutcome(row, false, requested);
+            }
+            if (journal)
+                store.settleEscalationComment(row);
+            else
+                store.recordEscalation(row.pr, row);
+            deliveredNow = true;
+            row = { ...row, phase: "request_pending" };
+        }
+        let requested = false;
+        if (row.shape === "review_request") {
+            if (deps.isDraining?.()) {
+                note("reviewer request pending while stopping");
+                return recoveryOutcome(row, true);
+            }
+            if (cfg.shape !== "review_request") {
+                note("paused: review-request shape disabled");
+                return recoveryOutcome(row, true);
+            }
+            if (!adapter.requestEscalationReview)
+                note("reviewer request adapter unavailable");
+            else
+                try {
+                    const result = await adapter.requestEscalationReview(row.pr, [row.target]);
+                    requested = result.executed;
+                    if (requested)
+                        finish();
+                    else
+                        note(`reviewer request not executed: ${result.blocked ?? "dry run"}`);
+                }
+                catch (error) {
+                    if (terminalRequestFailure(error))
+                        finish();
+                    else
+                        note(`reviewer request pending: ${String(error)}`);
+                    store.logEvent("escalation_request_failed", row.pr, {
+                        target: row.target,
+                        scope_key: row.scope_key,
+                        error: String(error),
+                    });
+                    log(`escalation: #${row.pr} → @${row.target} review request failed: ${String(error)}`);
+                }
+        }
+        if (deliveredNow) {
+            store.logEvent("escalation_delivered", row.pr, {
+                target: row.target,
+                scope_key: row.scope_key,
+                shape: row.shape,
+                origin: row.origin,
+                rule: row.rule,
+                round_no: row.round_no,
+                comment_executed: true,
+                review_requested: requested,
+            });
+            log(`escalation: #${row.pr} → @${row.target} (${row.scope_key}, ${row.shape}, ${row.origin})`);
+        }
+        else if (requested)
+            store.logEvent("escalation_request_recovered", row.pr, {
+                target: row.target,
+                scope_key: row.scope_key,
+            });
+        return recoveryOutcome(row, true, requested);
+    }
+    catch (error) {
+        // A successful POST followed by a local receipt failure remains in
+        // posting. Its marker is reconciled on a later sweep, never re-posted.
+        let confirmed = false;
+        try {
+            confirmed = store.escalationDelivered(row.pr, `${row.target}|${row.scope_key}`);
+            note(`local delivery checkpoint unavailable: ${String(error)}`);
+            store.logEvent("escalation_recovery_pending", row.pr, {
+                target: row.target,
+                scope_key: row.scope_key,
+                error: String(error),
+            });
+        }
+        catch {
+            /* the previously durable journal still carries the obligation */
+        }
+        log(`escalation: local recovery checkpoint failed on #${row.pr}`, error);
+        return recoveryOutcome(row, confirmed);
+    }
+    finally {
+        busy.delete(row.pr);
+    }
+}
+/** Resume durable obligations even when no later round proposes the candidate. */
+export async function resumeEscalations(deps) {
+    if (!deps.cfg.enabled || deps.dryRun || deps.isDraining?.())
+        return [];
+    const outcomes = [];
+    for (const row of deps.store.pendingEscalationRecoveries()) {
+        if (deps.isDraining?.())
+            break;
+        try {
+            outcomes.push(await continueEscalation(deps, row));
+        }
+        catch (error) {
+            deps.log?.(`escalation: recovery failed on #${row.pr}`, error);
+        }
+    }
+    return outcomes;
+}
+/**
+ * Deliver escalations for one round.
+ *
+ * NOTE THE RETURN TYPE. `EscalationOutcome[]` carries no verdict and no
+ * "should the review wait" signal, because there is nothing this function may
+ * say about the verdict — that is invariant 1 expressed as a type. The caller
+ * has already applied the verdict before this runs.
+ */
+export async function deliverEscalations(deps, args) {
+    const log = deps.log ?? (() => { });
+    const { cfg, store } = deps;
+    const outcomes = [];
+    if (!cfg.enabled || !args.head_sha)
+        return outcomes;
+    // The two groups stay separate all the way to validation, and each carries
+    // its origin as a property of WHERE IT CAME FROM rather than of what it
+    // says about itself. Rules first: they are the deterministic half, and on a
+    // capped PR the operator's own rules should win the budget.
+    const queued = [
+        ...(args.ruleRequests ?? []).map((raw) => ({ raw: raw, origin: "rule" })),
+        ...(args.sessionCandidates ?? []).map((raw) => ({ raw, origin: "session" })),
+    ];
+    for (const { raw, origin } of queued) {
+        const v = validateEscalationRequest(raw, cfg, origin, args.changed_paths ?? []);
+        if (!v.ok) {
+            store.logEvent("escalation_refused", args.pr, {
+                reason: v.refusal,
+                origin,
+                round_no: args.round_no ?? null,
+                candidate: raw,
+            });
+            log(`escalation: #${args.pr} refused (${origin}) — ${v.refusal}`);
+            outcomes.push({
+                target: "",
+                scope_key: "",
+                origin,
+                refused: v.refusal,
+                comment_executed: false,
+            });
+            continue;
+        }
+        const req = v.request;
+        const key = scopeKey(req.scope);
+        const pending = store.escalationRecovery(args.pr, req.target, key);
+        if (pending) {
+            // A replay in dry-run must leave the preexisting live obligation untouched.
+            outcomes.push(deps.dryRun ? recoveryOutcome(pending, false) : await continueEscalation(deps, pending));
+            continue;
+        }
+        if (store.escalationDelivered(args.pr, `${req.target}|${key}`)) {
+            outcomes.push({
+                target: req.target,
+                scope_key: key,
+                origin: req.origin,
+                refused: "already-delivered",
+                comment_executed: false,
+            });
+            continue;
+        }
+        if (store.escalationCount(args.pr) >= cfg.max_per_pr) {
+            store.logEvent("escalation_capped", args.pr, {
+                target: req.target,
+                scope_key: key,
+                max_per_pr: cfg.max_per_pr,
+            });
+            outcomes.push({
+                target: req.target,
+                scope_key: key,
+                origin: req.origin,
+                refused: "capped",
+                comment_executed: false,
+            });
+            continue;
+        }
+        const wantsRequest = cfg.shape === "review_request";
+        const body = renderEscalationComment(req, {
+            verdict: args.verdict,
+            ...(args.round_no !== undefined ? { round_no: args.round_no } : {}),
+            review_requested: wantsRequest,
+            ...(args.review_posted !== undefined ? { review_posted: args.review_posted } : {}),
+        });
+        const marker = escalationMarker(args.pr, req.target, key, args.head_sha);
+        const input = {
+            pr: args.pr,
+            target: req.target,
+            scope_key: key,
+            head_sha: args.head_sha,
+            body: `${body}\n\n${marker}`,
+            marker,
+            shape: cfg.shape,
+            origin: req.origin,
+            rule: req.rule ?? null,
+            round_no: args.round_no ?? null,
+        };
+        const row = deps.dryRun
+            ? {
+                ...input,
+                phase: "prepared",
+                last_error: null,
+                next_attempt_at: null,
+                updated_at: new Date().toISOString(),
+            }
+            : store.prepareEscalationRecovery(input);
+        outcomes.push(await continueEscalation(deps, row, !deps.dryRun));
+    }
+    return outcomes;
+}
+//# sourceMappingURL=escalation.js.map