Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): make bug-lane Slack refusal pages informational, not alarming (#3979)
Andrew Mikofalvy1322e95ec4c8
diff --git a/.github/scripts/bug-lane-refusal-payload.mjs b/.github/scripts/bug-lane-refusal-payload.mjsindex 4745065fd..c3d6664a1 100644--- a/.github/scripts/bug-lane-refusal-payload.mjs+++ b/.github/scripts/bug-lane-refusal-payload.mjs@@ -26,8 +26,24 @@* chosen deliberately: over-reporting severity costs a human a minute of* reading, under-reporting it costs a bad release.*+ * The page itself stays informational rather than alarming: no emoji, no+ * shouty header block, and no per-file listing (CARRIES BEHAVIOR / INERT) in+ * the channel. That per-path detail is genuinely not surfaced anywhere once+ * this returns — `classifyRefs`'s `detail` strings are computed and then+ * discarded, since nothing here writes to `console`, `::notice::`, or+ * `$GITHUB_STEP_SUMMARY`. What IS still visible without opening this file's+ * own output: the raw conflicting paths, which the pick loop already prints+ * to the run log independently (the "Verify the synthetic tree" step's+ * `--diff-filter=U` output), and the aggregate answer — config drift vs.+ * behavior-carrying — via the reason phrase below. Slack section blocks have+ * no expand/collapse control, so there is no way to fold the per-path detail+ * into the message itself without either always showing it or never showing+ * it; this file chooses never, on the belief that the aggregate answer is+ * what the channel needs to decide "does this need a human," and an operator+ * who needs the paths themselves is already going to open the run.+ ** Usage:- * node bug-lane-refusal-payload.mjs --input <json> [--repo owner/name]+ * node bug-lane-refusal-payload.mjs --input <json>** Emits the payload as JSON on stdout. Everything is assembled through* JSON.stringify, so a commit subject containing quotes cannot corrupt the@@ -38,8 +54,6 @@ import { execFileSync } from 'node:child_process';import { pathToFileURL } from 'node:url';import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';-const DEFAULT_REPO = 'inkeep/open-knowledge';-/*** Leaf keys whose divergence cannot change what a release does.*@@ -164,11 +178,6 @@ export function classifyRefs(refs, gitShow) {});}-/**- * The headline has one job: let a reader scanning the channel tell a fix that- * genuinely cannot ship from one that is only blocked by churn, without- * opening the run.- *//*** The classifier ran on this ref and found NO conflicting path.*@@ -178,233 +187,208 @@ export function classifyRefs(refs, gitShow) {*/const classifiedWithNoPaths = (r) => Array.isArray(r.files) && r.files.length === 0;-export function describeRefusal({ verdict, refs }) {- if (verdict === 'could-not-verify') {- return {- // Deliberately not "failed": the tiers ran out of budget, so there is no- // result to report about the batch either way. Every clause of the `fail`- // wording below would be false here, and the one an operator acts on- // ("not a retry candidate") would be the exact inverse of the truth.- headline: 'Bug lane: could not verify the synthetic tree',- meaning:- 'The fast tiers ran out of their time budget rather than finishing. Nothing was verified, so this says nothing about the queued fixes.',- };- }- if (verdict === 'fail') {- return {- headline: 'Bug lane: verification failed on the synthetic tree',- // Says what is known and stops there. This used to assert "a real- // conflict with the stable", which is one of two causes and not the one- // that actually happened: the tiers can be red because the STABLE's own- // tree is red, in which case every fix refuses and none of them is at- // fault. Reading a base failure as an incompatible fix is how a lane-wide- // outage looks like a run of bad luck with the fixes.- meaning:- 'The fast tiers went red on BOTH attempts, or the install failed. Past flake-class, so either the fix depends on something the stable lacks or the stable is red on its own.',- };- }- if (refs.length > 0 && refs.every((r) => r.inert)) {- return {- headline: 'Bug lane: point release blocked by config drift, not by the fix',- meaning:- 'Every collision is in a path that neither ships nor gates verification. The fix itself applies cleanly to the stable.',- };- }- // No recorded conflicting path anywhere. The severe headline below asserts- // "at least one collision carries behavior", and with zero paths there is no- // collision to say that about — saying it anyway is how a pick that applied- // EMPTY (the stable already had the fix) got reported as a fix that depends- // on later work. The verify stage now routes empty picks away from here- // entirely, so reaching this branch means the pick failed some third way;- // report the uncertainty instead of inventing a cause for it.- if (refs.length > 0 && refs.every(classifiedWithNoPaths)) {- return {- headline: 'Bug lane: the pick failed without a conflicting path',- meaning:- 'The cherry-pick exited non-zero but left no conflicting file, so its cause is not visible from here. Read the run log before concluding anything about the fix.',- };- }- return {- headline: 'Bug lane: the fix does not apply to the current stable',- meaning:- 'At least one collision is in a path that carries behavior, so the fix depends on something that landed after the stable was cut.',- };+/**+ * The one thing worth telling a reader who is only scanning the channel: why+ * this did not ship, in three words or fewer, phrased as a noun so it reads+ * after "due to". Everything else — which files, which tests — lives in the+ * run, one click away, not in the page.+ */+export function reasonPhrase({ verdict, refs }) {+ if (verdict === 'could-not-verify') return 'verification timeout';+ // Deliberately does not say WHOSE verification is red. The tiers run on+ // the SYNTHETIC tree (stable + picked fixes), so a red run means either the+ // fix depends on something the stable lacks, or the stable is red on its+ // own — asserting either one here would be the exact over-claim the+ // two-cause hedge in `actionLine`'s `fail` branch exists to avoid.+ if (verdict === 'fail') return 'red verification';+ if (refs.length > 0 && refs.every((r) => r.inert)) return 'config drift';+ // No recorded conflicting path anywhere. Calling this a "conflict" would+ // assert a collision the classifier has no evidence for — the same+ // over-claim that once reported an empty pick (the stable already had the+ // fix) as a fix depending on later work.+ if (refs.length > 0 && refs.every(classifiedWithNoPaths)) return 'unclear pick failure';+ return 'behavior-carrying conflict';}/**- * What an operator can actually do. Deliberately does not offer- * `resolve_paths` for the inert case: its allowlist is code and covers only- * `pnpm-workspace.yaml`, so naming a package manifest refuses with- * `resolve-path-not-allowlisted` before the tree is touched. Sending someone- * to a door that is locked is worse than saying it is locked.+ * Scoped to the FIX, never the lane. On every verdict but `fail` that+ * distinction is academic — but a `fail` can mean the stable itself is red,+ * in which case the lane refuses every fix until that is repaired (see+ * `actionLine`'s `fail` branch), so an unscoped "no action needed" here would+ * assert the lane is fine on the one verdict where it might not be.*/-export function optionsFor({ verdict, refs }) {+function noActionSentence(verdict) {if (verdict === 'could-not-verify') {- return [- 'Nothing here is evidence about the fixes — the tiers did not finish, so no test passed or failed on their account.',- 'The batch stays pending and the next tick retries it. Unlike a red verification, this IS a retry candidate.',- 'If this keeps happening the runner or the budget is the thing to look at — but identical refusals stay silent, so check the lane\u2019s recent runs rather than waiting to be paged again.',- ];+ return 'No action needed — the lane retries this batch automatically on its next tick.';}if (verdict === 'fail') {- return [- 'Check the failures above against the fixes first — a failure in code no fix touches means the STABLE is red, which no amount of re-running or re-picking will clear.',- 'If the failures do sit in code a fix touches, that fix depends on later work. Either way it is not a retry candidate.',- 'The fixes ride their cycle’s stable. Forcing them past a red verification is not an option this lane offers.',- ];- }- if (refs.length > 0 && refs.every(classifiedWithNoPaths)) {- return [- 'Open the run log and read the cherry-pick output — the failure left no conflicting path, so the log is the only place the cause exists.',- 'Do not hand-cut a point release off this page alone. Confirm what actually failed first; the fix may already be in the stable.',- ];- }- const allInert = refs.length > 0 && refs.every((r) => r.inert);- if (allInert) {- return [- 'Do nothing — the fix ships with its cycle’s stable on the ordinary soak. Since the collision carries no behavior, waiting costs only time.',- 'If the fix is urgent enough to hand-cut: it IS self-contained over the stable, so the usual "pick a smaller commit" advice does not apply. `resolve_paths` does not cover this path (allowlist is code, `pnpm-workspace.yaml` only), so it needs a human decision — see RELEASES.md, "When the conflict is config drift, not a dependency".',- ];+ return 'The fix itself needs nothing — it ships in the normal 24h soak lane in a future version.';}+ // Not "in a future version": on an evidence-free pick (`unclear pick+ // failure`) the likelier reading is the fix already shipped, so nothing+ // new is coming — `rides its cycle's stable` holds under either reading.+ return "No action needed — it rides its cycle's stable.";+}++function refLabel(entry) {+ const tickets = (entry.tickets ?? []).join(', ');+ return [`\`${entry.ref.slice(0, 9)}\``, tickets && `(${tickets})`].filter(Boolean).join(' ');+}++/** Who the headline is about. Only `conflict` has a specific ref to name. */+function headlineSubject({ verdict, refs }) {+ if (verdict !== 'conflict' || refs.length === 0) return 'The queued fix(es)';+ const [first, ...rest] = refs;+ const label = refLabel(first);+ return rest.length > 0 ? `${label} and ${rest.length} more` : label;+}++/**+ * The whole first line a reader needs: what failed to ship, why (three words+ * or fewer), what the stable is now, and that nothing is owed in response.+ */+export function buildHeadline({ verdict, refs, stable }) {return [- 'Let it ride its cycle’s stable. A behavior-carrying collision means the fix genuinely depends on later work.',- 'If it must ship sooner, the answer is a smaller self-contained commit, not a forced pick — see RELEASES.md, "When a guard refuses".',- ];+ `Bug lane: ${headlineSubject({ verdict, refs })} did not ship in the fast lane due to ${reasonPhrase({ verdict, refs })}.`,+ `Latest stable remains \`${stable}\`.`,+ noActionSentence(verdict),+ ].join(' ');}const MAX_REFS_SHOWN = 5;-const MAX_FILES_SHOWN = 8;-function refLines(refs) {- const lines = [];- for (const entry of refs.slice(0, MAX_REFS_SHOWN)) {- const tickets = (entry.tickets ?? []).join(', ');- const label = [`\`${entry.ref.slice(0, 9)}\``, tickets && `(${tickets})`]- .filter(Boolean)- .join(' ');- const shown = entry.files.slice(0, MAX_FILES_SHOWN);- // "conflicted in 0 files:" followed by nothing is the shape that made a- // page unreadable — it states a conflict and then lists no evidence for- // it, while the line below cheerfully reports every file applying cleanly.- // Say the actual fact instead.- if (entry.files.length === 0) {- const total = Number(entry.totalFiles);- lines.push(- `${label} — the pick failed but git reported no conflicting file` +- `${Number.isFinite(total) && total > 0 ? `; all ${total} file${total === 1 ? '' : 's'} in the commit applied cleanly` : ''}.`,- );- continue;- }- lines.push(- `${label} — conflicted in ${entry.files.length} file${entry.files.length === 1 ? '' : 's'}:`,+/**+ * One line per ref: the count of conflicting files and how many applied+ * cleanly, never the paths or the per-file INERT/CARRIES-BEHAVIOR verdict —+ * see the top-of-file docstring for where that detail actually goes.+ */+function refSummaryLine(entry) {+ const label = refLabel(entry);+ const total = Number(entry.totalFiles);+ if (entry.files.length === 0) {+ return (+ `${label} — the pick failed but git reported no conflicting file` ++ `${Number.isFinite(total) && total > 0 ? `; all ${total} file${total === 1 ? '' : 's'} applied cleanly` : ''}.`);- for (const f of shown) {- lines.push(` • \`${f.path}\` — ${f.inert ? 'INERT' : 'CARRIES BEHAVIOR'} (${f.detail})`);- }- if (entry.files.length > shown.length) {- lines.push(` • …and ${entry.files.length - shown.length} more`);- }- // The reassurance that makes an inert verdict legible: naming what DID- // apply is what separates "one line drifted" from "this fix is broken".- const clean = Number(entry.totalFiles) - entry.files.length;- if (Number.isFinite(clean) && clean > 0) {- lines.push(` ${clean} other file${clean === 1 ? '' : 's'} in the commit applied cleanly.`);- }}+ const clean = Number.isFinite(total) ? total - entry.files.length : Number.NaN;+ return (+ `${label} — conflicted in ${entry.files.length} file${entry.files.length === 1 ? '' : 's'}` ++ `${Number.isFinite(clean) && clean > 0 ? `; ${clean} applied cleanly` : ''}.`+ );+}++function refSummaryLines(refs) {+ const lines = refs.slice(0, MAX_REFS_SHOWN).map(refSummaryLine);if (refs.length > MAX_REFS_SHOWN) {lines.push(`…and ${refs.length - MAX_REFS_SHOWN} more ref(s); see the run.`);}return lines;}-const MAX_FAILURES_SHOWN = 8;-/**- * "Why it refused", for a red tier.- *- * A `fail` verdict has no conflicting paths among the refs that REACHED the- * tiers — every survivor cherry-picked cleanly, which is the only way it got- * there — so `refLines` had nothing to say about the failure itself and the- * section rendered as a bare heading above an instruction to go read the log.- * That is the most severe verdict the lane has and it was carrying the least- * information of any of them. (`refs` can still be non-empty on a `fail`: it- * holds refs DROPPED before the tiers ran, which `buildSlackPayload` renders- * under its own heading rather than as the reason the tiers went red.)- *- * Naming the failures is also what lets a reader tell the two causes apart- * without opening anything: a failing test in a package the fixes never touched- * is the stable being red on its own, not a fix that depends on later work.+ * "Why it refused", for a red tier. Names at most the first failure and a+ * count — the full list is what the run log is for.*/-function failureLines(failures, verdict) {+function failureSummaryLines(failures, verdict) {if (verdict === 'could-not-verify') {- // No lead line: the bullet already carries the budget and the exit code,- // and a heading restating it was the redundancy the previous commit set out- // to remove. The `fail` arm's lead earns its place by adding the attempt- // count; there is nothing equivalent to add here.- //- // Which attempt ran out is deliberately not claimed. A first-attempt blow- // is never retried, but the RETRY can blow its own budget too, so "there- // was no second attempt" holds on one path and not the other.if (failures.length === 0) {- return ['The tiers ran out of their time budget. Read the run log for where the time went.'];+ return [+ 'The tiers ran out of their time budget, so nothing was verified about the queued fixes — see the run for where the time went.',+ ];}- return failures.map((f) => ` • ${f}`);+ // Which attempt ran out is deliberately not claimed: a first-attempt blow+ // is never retried, but the retry can blow its own budget too. Does not+ // restate "the tiers did not finish" — in production `failures[0]` always+ // opens with exactly that phrase already, followed by the budget and+ // exit code (the workflow overwrites it unconditionally for this+ // verdict).+ const rest = failures.length > 1 ? ` and ${failures.length - 1} more` : '';+ return [`\`${failures[0]}\`${rest} — nothing was verified about the queued fixes.`];}if (failures.length === 0) {- // Hedged, because `verdict=fail` has two sites in the workflow: the- // retry-exhausted tier path, and the `pnpm install --frozen-lockfile`- // failure that exits BEFORE either attempt runs and so can never populate- // this list. Asserting "both attempts" would be false in exactly the case- // that reaches this branch most reliably, which is the same- // cause-conflation this page is being fixed to stop doing.+ // Hedged: `verdict=fail` has two sites in the workflow, and the+ // `pnpm install --frozen-lockfile` failure exits BEFORE either attempt+ // runs, so it never populates `failures`.return [- 'The tiers went red on both attempts, or the install itself failed before either ran. This run captured no failing test or task name — read the run log directly.',+ 'Both attempts went red, or the install itself failed before either ran — see the run log.',];}- const shown = failures.slice(0, MAX_FAILURES_SHOWN);- const lines = ['Failing on the second attempt, so not flake-class:'];- for (const failure of shown) lines.push(` • \`${failure}\``);- if (failures.length > shown.length) {- lines.push(` • …and ${failures.length - shown.length} more`);+ const rest = failures.length > 1 ? ` and ${failures.length - 1} more` : '';+ // The two-cause hedge lives in `actionLine`'s `fail` branch, which renders+ // on every `fail` including the zero-failures case this array never+ // reaches, rather than here.+ return [`\`${failures[0]}\`${rest} — not flake-class, failing on the second attempt too.`];+}++/**+ * What an operator can actually do, in one line. Branches verdict-first,+ * mirroring `reasonPhrase` — a `fail` or `could-not-verify` batch's `refs`+ * holds only refs DROPPED before the tiers ran, which is unrelated evidence+ * to the reason the batch itself refused, so those two verdicts must resolve+ * before any refs-based branching runs.+ *+ * Deliberately does not offer `resolve_paths` for the inert case: its+ * allowlist is code and covers only `pnpm-workspace.yaml` (the only path+ * `classifyConflictPath` ever marks inert is a `package.json`, which the+ * allowlist does not cover), so naming a package manifest refuses with+ * `resolve-path-not-allowlisted` before the tree is touched. Sending someone+ * to a door that is locked is worse than saying it is locked — this line+ * keeps that disqualifier inline rather than only implying it.+ */+export function actionLine({ verdict, refs }) {+ // "Identical refusals stay silent" is not repeated here — the unconditional+ // footer below already states it once, for every verdict.+ if (verdict === 'could-not-verify') {+ return "If this keeps happening, check the lane's recent runs.";}- lines.push(- 'If none of these sit in code the fixes touch, the stable is red on its own and the lane will refuse every fix until that is repaired.',- );- return lines;+ // A red tier's `refs` (if any) are dropped-before-the-tiers-ran evidence,+ // not the reason THIS batch refused — advising on them here would be the+ // exact cause-conflation the headline's cause-neutral reason phrase exists+ // to avoid. Phrased conditionally ("if a failure is named above") because+ // `failureSummaryLines` renders no named failure when the install itself+ // fails before either attempt runs, so this line still has to hold on that+ // path. Says "a failure", not "a failing test", because the verify step+ // falls back to turbo's failed-task lines when what went red is a+ // typecheck, which prints no per-test name at all.+ if (verdict === 'fail') {+ return 'If a failure is named above, check it against the fixes — one in code no fix touches means the stable is red on its own, which no re-run or smaller commit will clear; one a fix does touch means that fix depends on later work.';+ }+ if (refs.length > 0 && refs.every((r) => r.inert)) {+ return 'The collision is config drift, not a dependency, so the fix is already self-contained. `resolve_paths` does not cover this path, so hand-cutting needs a human decision — see RELEASES.md, "When the conflict is config drift, not a dependency".';+ }+ // No recorded conflicting path anywhere — the likeliest cause is that the+ // stable already shipped the fix, not that the commit needs re-cutting.+ // Confidently recommending a smaller commit here would assert the fix is+ // NOT self-contained over the stable, the opposite of what `apply-conflict`+ // (RELEASES.md) means for this class.+ if (refs.length > 0 && refs.every(classifiedWithNoPaths)) {+ return 'Read the cherry-pick output in the run before concluding anything — the fix may already be in the stable.';+ }+ return 'If it must ship sooner, the answer is a smaller self-contained commit, not a forced pick — see RELEASES.md, "When a guard refuses".';}-export function buildSlackPayload({- verdict,- stable,- refs,- runUrl,- failures = [],- repo = DEFAULT_REPO,-}) {- const { headline, meaning } = describeRefusal({ verdict, refs });- const summary = `⛔ ${headline}`;+export function buildSlackPayload({ verdict, stable, refs, runUrl, failures = [] }) {+ const headline = buildHeadline({ verdict, refs, stable });const body = [- `*Over \`${stable}\` on \`${repo}\`.* ${meaning}`,+ headline,'','*Why it refused*',...(verdict === 'fail' || verdict === 'could-not-verify'- ? failureLines(failures, verdict)- : refLines(refs)),+ ? failureSummaryLines(failures, verdict)+ : refSummaryLines(refs)),// A red tier does not imply an empty `refs`. The pick loop writes its// `conflicts` output for every DROPPED ref and then lets the survivors run// the tiers, so a partial drop followed by a red tier arrives here with- // real drop evidence. `refLines` used to render it, badly labelled; the- // partial-drop page cannot cover the gap because its own step is gated on- // `verdict == 'pass'`. Losing the labelling problem must not also lose the- // information, so the drops keep their own heading.+ // real drop evidence, under its own heading rather than as the reason the+ // tiers went red....((verdict === 'fail' || verdict === 'could-not-verify') && refs.length > 0- ? ['', '*Also dropped from this batch, before the tiers ran*', ...refLines(refs)]+ ? ['', '*Also dropped from this batch, before the tiers ran*', ...refSummaryLines(refs)]: []),'',- '*What you can do*',- ...optionsFor({ verdict, refs }).map((o, i) => `${i + 1}. ${o}`),+ actionLine({ verdict, refs }),'',- // Only the run link is conditional; the blank separators above are+ // Only the run link is conditional; the blank separator above is// deliberate and must survive....(runUrl ? [`<${runUrl}|Run log>`] : []),'_Further identical refusals stay silent; the lane pages again only if the refusal changes._',@@ -412,11 +396,11 @@ export function buildSlackPayload({return {// `text` is the notification / a11y fallback Slack recommends alongside blocks.- text: summary,- blocks: [- { type: 'header', text: { type: 'plain_text', text: summary, emoji: true } },- { type: 'section', text: { type: 'mrkdwn', text: body } },- ],+ text: headline,+ // A single section block, no `header` block: the header rendered its text+ // large and bold, which is exactly the alarm the plain, lower-case+ // headline above is meant to defuse.+ blocks: [{ type: 'section', text: { type: 'mrkdwn', text: body } }],};}@@ -442,7 +426,6 @@ export function parseArgs(argv) {? parsed.failures.filter((entry) => typeof entry === 'string' && entry.trim() !== ''): [],runUrl: parsed.runUrl || '',- repo: args.repo || parsed.repo || DEFAULT_REPO,};}diff --git a/.github/scripts/bug-lane-refusal-payload.test.mjs b/.github/scripts/bug-lane-refusal-payload.test.mjsindex 8dbe764f0..b4264bcfb 100644--- a/.github/scripts/bug-lane-refusal-payload.test.mjs+++ b/.github/scripts/bug-lane-refusal-payload.test.mjs@@ -3,14 +3,15 @@ import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';import { describe, expect, test } from 'vitest';import {+ actionLine,+ buildHeadline,buildSlackPayload,changedJsonKeys,classifyConflictPath,classifyRefs,- describeRefusal,INERT_JSON_KEYS,- optionsFor,parseArgs,+ reasonPhrase,} from './bug-lane-refusal-payload.mjs';const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');@@ -35,9 +36,9 @@ const appManifest = (e2e) =>describe('changedJsonKeys', () => {test('reports dotted leaf paths, not subtrees', () => {- expect(changedJsonKeys({ scripts: { a: '1', b: '2' } }, { scripts: { a: '1', b: '3' } })).toEqual(- ['scripts.b'],- );+ expect(+ changedJsonKeys({ scripts: { a: '1', b: '2' } }, { scripts: { a: '1', b: '3' } }),+ ).toEqual(['scripts.b']);});test('catches added and removed leaves, not just modified ones', () => {@@ -68,7 +69,11 @@ describe('classifyConflictPath', () => {test('a published manifest is never inert, whatever key moved', () => {const pub = (e2e) =>JSON.stringify({ name: '@inkeep/open-knowledge', scripts: { 'test:e2e': e2e } });- const got = classifyConflictPath({ path: 'packages/cli/package.json', before: pub('a'), after: pub('b') });+ const got = classifyConflictPath({+ path: 'packages/cli/package.json',+ before: pub('a'),+ after: pub('b'),+ });expect(got.inert).toBe(false);expect(got.detail).toMatch(/published/);});@@ -125,7 +130,11 @@ describe('classifyConflictPath', () => {test('a path the fix never changed is not called harmless', () => {const same = appManifest('a.e2e.ts');- const got = classifyConflictPath({ path: 'packages/app/package.json', before: same, after: same });+ const got = classifyConflictPath({+ path: 'packages/app/package.json',+ before: same,+ after: same,+ });expect(got.inert).toBe(false);expect(got.detail).toMatch(/without the fix changing it/);});@@ -165,33 +174,50 @@ describe('classifyRefs', () => {});});-describe('describeRefusal', () => {+describe('reasonPhrase and buildHeadline', () => {// Production-shaped. `classifyRefs` derives `inert` as// `files.length > 0 && files.every(...)`, so a ref carrying the flag ALWAYS// carries the paths it was derived from; an empty `files` is a distinct// state (the pick failed without conflicting) and gets its own class below.const inert = [- { ref: 'a', inert: true, files: [{ path: 'packages/app/package.json', inert: true, detail: 'test:e2e only' }] },+ {+ ref: 'a',+ inert: true,+ files: [{ path: 'packages/app/package.json', inert: true, detail: 'test:e2e only' }],+ },];const behavioral = [- { ref: 'a', inert: false, files: [{ path: 'packages/server/src/boot.ts', inert: false, detail: 'carries behavior' }] },+ {+ ref: 'a',+ inert: false,+ files: [{ path: 'packages/server/src/boot.ts', inert: false, detail: 'carries behavior' }],+ },];const noPaths = [{ ref: 'a', inert: false, totalFiles: 37, files: [] }];+ test('the reason phrase is three words or fewer', () => {+ const words = (s) => s.split(/\s+/).length;+ expect(words(reasonPhrase({ verdict: 'could-not-verify', refs: [] }))).toBeLessThanOrEqual(3);+ expect(words(reasonPhrase({ verdict: 'fail', refs: [] }))).toBeLessThanOrEqual(3);+ expect(words(reasonPhrase({ verdict: 'conflict', refs: inert }))).toBeLessThanOrEqual(3);+ expect(words(reasonPhrase({ verdict: 'conflict', refs: noPaths }))).toBeLessThanOrEqual(3);+ expect(words(reasonPhrase({ verdict: 'conflict', refs: behavioral }))).toBeLessThanOrEqual(3);+ });+test('the four refusal classes read differently at a glance', () => {- const h = (args) => describeRefusal(args).headline;- const drift = h({ verdict: 'conflict', refs: inert });- const real = h({ verdict: 'conflict', refs: behavioral });- const red = h({ verdict: 'fail', refs: [] });- const unknown = h({ verdict: 'conflict', refs: noPaths });+ const r = (args) => reasonPhrase(args);+ const drift = r({ verdict: 'conflict', refs: inert });+ const real = r({ verdict: 'conflict', refs: behavioral });+ const red = r({ verdict: 'fail', refs: [] });+ const unknown = r({ verdict: 'conflict', refs: noPaths });expect(new Set([drift, real, red, unknown]).size).toBe(4);- expect(drift).toMatch(/config drift, not by the fix/);- expect(real).toMatch(/does not apply/);+ expect(drift).toMatch(/config drift/);+ expect(real).toMatch(/conflict/);});- test('one behavior-carrying ref in a mixed batch picks the severe headline', () => {- expect(describeRefusal({ verdict: 'conflict', refs: [...inert, ...behavioral] }).headline).toMatch(- /does not apply/,+ test('one behavior-carrying ref in a mixed batch picks the severe reason', () => {+ expect(reasonPhrase({ verdict: 'conflict', refs: [...inert, ...behavioral] })).toBe(+ 'behavior-carrying conflict',);});@@ -201,45 +227,103 @@ describe('describeRefusal', () => {// no evidence for — telling the reader the fix depended on later work when// it was already released.test('no recorded conflicting path never claims a behavior-carrying collision', () => {- const { headline, meaning } = describeRefusal({ verdict: 'conflict', refs: noPaths });- expect(headline).not.toMatch(/does not apply to the current stable/);- expect(meaning).not.toMatch(/carries behavior/);- expect(meaning).toMatch(/no conflicting file/);+ expect(reasonPhrase({ verdict: 'conflict', refs: noPaths })).not.toMatch(/behavior/);});// A batch where one ref genuinely collided must still report the severe// case; the no-path class is only for a batch with no evidence at all.- test('a mixed batch with real paths keeps the severe headline', () => {- expect(describeRefusal({ verdict: 'conflict', refs: [...noPaths, ...behavioral] }).headline).toMatch(- /does not apply/,+ test('a mixed batch with real paths keeps the severe reason', () => {+ expect(reasonPhrase({ verdict: 'conflict', refs: [...noPaths, ...behavioral] })).toBe(+ 'behavior-carrying conflict',+ );+ });++ test('the headline names the specific ref and ticket on a conflict', () => {+ const headline = buildHeadline({+ verdict: 'conflict',+ refs: [{ ref: 'abcdef1234567890', tickets: ['PRD-1'], inert: false, files: [] }],+ stable: 'v1.2.3',+ });+ expect(headline).toContain('`abcdef123` (PRD-1)');+ expect(headline).toContain('v1.2.3');+ expect(headline).toContain('No action needed');+ });++ // A `fail`/`could-not-verify` batch has no single ref to blame — the tiers+ // ran against every survivor together — so the headline names the batch,+ // not a commit that may not be the one at fault.+ test('a red tier or a budget blow names the batch, not a specific ref', () => {+ expect(buildHeadline({ verdict: 'fail', refs: [], stable: 'v1' })).toContain(+ 'The queued fix(es)',);+ expect(buildHeadline({ verdict: 'could-not-verify', refs: [], stable: 'v1' })).toContain(+ 'The queued fix(es)',+ );+ });++ // `could-not-verify` retries the fast lane automatically; a `conflict`+ // rides its cycle's stable instead (`fail` gets its own wording, tested+ // separately). Stating one sentence for both would tell the wrong story+ // about at least one of them.+ test('the no-action sentence differs for a budget blow', () => {+ const retried = buildHeadline({ verdict: 'could-not-verify', refs: [], stable: 'v1' });+ const soaked = buildHeadline({ verdict: 'conflict', refs: inert, stable: 'v1' });+ expect(retried).toMatch(/retries this batch automatically/);+ expect(soaked).toMatch(/rides its cycle's stable/);+ expect(retried).not.toMatch(/rides its cycle's stable/);});});-describe('optionsFor', () => {+describe('actionLine', () => {const withPath = (inertFlag) => [- { ref: 'x', inert: inertFlag, files: [{ path: 'p/package.json', inert: inertFlag, detail: 'd' }] },+ {+ ref: 'x',+ inert: inertFlag,+ files: [{ path: 'p/package.json', inert: inertFlag, detail: 'd' }],+ },];- test('the inert case never points at resolve_paths, which would refuse', () => {- const opts = optionsFor({ verdict: 'conflict', refs: withPath(true) });- expect(opts.join('\n')).not.toMatch(/-f resolve_paths=/);- expect(opts.join('\n')).toMatch(/allowlist is code/);+ test('the inert case never points at resolve_paths, which would refuse, but still names the disqualifier', () => {+ const line = actionLine({ verdict: 'conflict', refs: withPath(true) });+ expect(line).not.toMatch(/-f resolve_paths=/);+ expect(line).toMatch(/config drift/);+ // `classifyConflictPath` only ever marks a `package.json` inert, and the+ // `resolve_paths` allowlist covers only `pnpm-workspace.yaml` — so the+ // line must say the flag does not apply here, not just omit it.+ expect(line).toMatch(/resolve_paths.*does not cover this path/);});test('inert and behavioral give different advice', () => {- const a = optionsFor({ verdict: 'conflict', refs: withPath(true) });- const b = optionsFor({ verdict: 'conflict', refs: withPath(false) });+ const a = actionLine({ verdict: 'conflict', refs: withPath(true) });+ const b = actionLine({ verdict: 'conflict', refs: withPath(false) });expect(a).not.toEqual(b);- expect(b.join('\n')).toMatch(/smaller self-contained commit/);+ expect(b).toMatch(/smaller self-contained commit/);});// Without evidence the advice must not send someone to hand-cut a release:- // the likeliest cause of a pathless failure is that the fix already shipped.+ // the likeliest cause of a pathless failure is that the fix already+ // shipped, which "the answer is a smaller self-contained commit" denies.test('no recorded path sends the reader to the log, not to a hand-cut release', () => {- const opts = optionsFor({ verdict: 'conflict', refs: [{ ref: 'x', inert: false, files: [] }] }).join('\n');- expect(opts).not.toMatch(/smaller self-contained commit/);- expect(opts).toMatch(/run log/);+ const line = actionLine({ verdict: 'conflict', refs: [{ ref: 'x', inert: false, files: [] }] });+ expect(line).not.toMatch(/smaller self-contained commit/);+ expect(line).toMatch(/run/);+ expect(line).toMatch(/already be in the stable/);+ });++ test('a budget blow points at the lane’s recent runs, not at a resolution', () => {+ expect(actionLine({ verdict: 'could-not-verify', refs: [] })).toMatch(/recent runs/);+ });++ // A red tier whose DROPPED refs happen to be config-drift-inert must not+ // render refs-based advice for a refusal that has nothing to do with those+ // refs — `fail` resolves before any refs-based branch runs, mirroring+ // `reasonPhrase`.+ test('a red tier never renders refs-based advice, even when the dropped refs are inert', () => {+ const line = actionLine({ verdict: 'fail', refs: withPath(true) });+ expect(line).not.toMatch(/needs a human decision/);+ expect(line).not.toMatch(/config drift/);+ expect(line).not.toMatch(/smaller self-contained commit/);+ expect(line).toMatch(/stable is red on its own/);});});@@ -258,7 +342,7 @@ describe('buildSlackPayload', () => {// of its own — every surviving ref cherry-picked cleanly, which is the only// way it reached the tiers. Without the failure list the section renders as a// bare heading above an instruction to go read the log.- test('a red tier names the failing tests instead of an empty reason', () => {+ test('a red tier names the failing test instead of an empty reason', () => {const body = buildSlackPayload({verdict: 'fail',stable: 'v0.62.1',@@ -267,12 +351,18 @@ describe('buildSlackPayload', () => {failures: ['src/skill-bundles.test.ts > every bundle has a SKILL.md on disk whose frontmatter name matches',],- }).blocks[1].text.text;+ }).blocks[0].text.text;expect(body).toContain('skill-bundles.test.ts');expect(body).toContain('not flake-class');- // The discrimination the empty page could not offer.- expect(body).toContain('the stable is red on its own');+ // The discrimination that keeps a red tier from reading as a budget blow.+ expect(body).toContain('red verification');+ expect(body).not.toContain('verification timeout');expect(body).not.toMatch(/\*Why it refused\*\n\n/);+ // The two-cause hedge: neither the reason phrase nor the failure line+ // asserts which side is red.+ expect(body).toContain('the stable is red on its own');+ expect(body).toContain('check it against the fixes');+ expect(body).toContain('depends on later work');});// A red tier does NOT imply an empty batch: the pick loop records every@@ -280,18 +370,24 @@ describe('buildSlackPayload', () => {// followed by a red tier carries both kinds of evidence. The partial-drop// page is gated on `verdict == 'pass'`, so if this page omits the drops// nothing on that tick tells the operator a ref was dropped at all.- test('a red tier with dropped refs still accounts for the drops', () => {+ test('a red tier with dropped refs still accounts for the drops, without advising on them', () => {const body = buildSlackPayload({verdict: 'fail',stable: 'v0.62.1',runUrl: '',failures: ['src/thing.test.ts > a case'],- refs,- }).blocks[1].text.text;+ refs, // the fixture's dropped ref is config-drift-inert.+ }).blocks[0].text.text;expect(body).toContain('src/thing.test.ts');expect(body).toContain('Also dropped from this batch');- expect(body).toContain('packages/app/package.json');expect(body).toContain('PRD-7835');+ expect(body).toContain('conflicted in 1 file');+ // The per-file breakdown is deliberately gone from the channel message.+ expect(body).not.toContain('packages/app/package.json');+ // The actual refusal is the red tier, not this unrelated dropped ref's+ // pre-tier collision — the page must not advise on the drop.+ expect(body).not.toContain('needs a human decision');+ expect(body).toContain('check it against the fixes');});test('a red tier with no dropped refs adds no drop section', () => {@@ -301,7 +397,7 @@ describe('buildSlackPayload', () => {runUrl: '',failures: ['src/thing.test.ts > a case'],refs: [],- }).blocks[1].text.text;+ }).blocks[0].text.text;expect(body).not.toContain('Also dropped from this batch');});@@ -312,12 +408,17 @@ describe('buildSlackPayload', () => {refs: [],runUrl: '',failures: [],- }).blocks[1].text.text;- expect(body).toContain('captured no failing test or task name');+ }).blocks[0].text.text;+ expect(body).toContain('Both attempts went red');expect(body).not.toMatch(/\*Why it refused\*\n\n/);+ // The exact route the action line's "if a failure is named above" hedges+ // for: nothing above names one, so the line must not presuppose it does.+ expect(body).toMatch(/if a failure is named above/i);});- test('a red tier caps the failure list and says how many it dropped', () => {+ // The channel gets the first failure and a count, not the whole list — the+ // full list is what the run log is for.+ test('a red tier names only the first failure, with a count of the rest', () => {const failures = Array.from({ length: 11 }, (_, i) => `suite > case ${i}`);const body = buildSlackPayload({verdict: 'fail',@@ -325,59 +426,87 @@ describe('buildSlackPayload', () => {refs: [],runUrl: '',failures,- }).blocks[1].text.text;- expect(body).toContain('case 7');- expect(body).not.toContain('case 8');- expect(body).toContain('…and 3 more');+ }).blocks[0].text.text;+ expect(body).toContain('case 0');+ expect(body).not.toContain('case 1');+ expect(body).toContain('and 10 more');+ // The two-cause hedge ships regardless of the cap — it comes from+ // `actionLine`, which does not see `failures` at all, not from the+ // (capped) list above it.+ expect(body).toContain('the stable is red on its own');});- test('names the ticket, the path, the verdict and what applied cleanly', () => {+ test('names the ticket, the reason and the stable, without the per-file breakdown', () => {const body = buildSlackPayload({verdict: 'conflict',stable: 'v0.48.9',refs,runUrl: 'https://example.test/run/1',- }).blocks[1].text.text;+ }).blocks[0].text.text;expect(body).toContain('PRD-7835');- expect(body).toContain('packages/app/package.json');expect(body).toContain('v0.48.9');- expect(body).toContain('27 other files in the commit applied cleanly');+ expect(body).toContain('config drift');+ expect(body).toContain('conflicted in 1 file; 27 applied cleanly');+ expect(body).not.toContain('packages/app/package.json');});- // The verbatim shape of the page that went out for PRD-7310 over v0.50.2:+ // The verbatim shape of a page that went out over v0.50.2:// 37 files, none conflicting, because the stable already shipped the fix.- // It rendered "conflicted in 0 files:" with nothing under it, immediately- // followed by "37 other files applied cleanly" — a stated conflict with no- // evidence, contradicted by its own next line.+ // It used to render "conflicted in 0 files:" with nothing under it,+ // immediately followed by "37 other files applied cleanly" — a stated+ // conflict with no evidence, contradicted by its own next line.test('a pathless failure renders no empty conflict list and no phantom count', () => {const body = buildSlackPayload({verdict: 'conflict',stable: 'v0.50.2',- refs: [{ ref: '4cef9c5a587dc26ea4bcb5fe2ab134a1fa8ec00d', tickets: ['PRD-7310'], totalFiles: 37, inert: false, files: [] }],+ refs: [+ {+ ref: '4cef9c5a587dc26ea4bcb5fe2ab134a1fa8ec00d',+ tickets: ['PRD-7310'],+ totalFiles: 37,+ inert: false,+ files: [],+ },+ ],runUrl: '',- }).blocks[1].text.text;+ }).blocks[0].text.text;expect(body).not.toContain('conflicted in 0 files');- expect(body).not.toContain('37 other files');expect(body).toContain('PRD-7310');expect(body).toContain('no conflicting file');- expect(body).toContain('all 37 files in the commit applied cleanly');+ expect(body).toContain('all 37 files applied cleanly');});test('keeps the silence-is-deliberate note', () => {- const body = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs, runUrl: '' }).blocks[1]- .text.text;+ const body = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs, runUrl: '' })+ .blocks[0].text.text;expect(body).toMatch(/Further identical refusals stay silent/);});+ // No shouty header block and no emoji — the page is informational, not an+ // incident. `text` (the notification/a11y fallback) carries the same+ // headline the single section block does.+ test('has no emoji and no header block', () => {+ const payload = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs, runUrl: '' });+ expect(payload.blocks).toHaveLength(1);+ expect(payload.blocks[0].type).toBe('section');+ expect(JSON.stringify(payload)).not.toMatch(/[\u{1F000}-\u{1FFFF}☀-➿]/u);+ expect(payload.text).toBe(payload.blocks[0].text.text.split('\n')[0]);+ });+test('a commit subject containing quotes cannot corrupt the payload', () => {const hostile = [{ ...refs[0], tickets: ['"}, {"type":"section","text":"pwned'], files: refs[0].files },];- const payload = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs: hostile, runUrl: '' });- expect(JSON.parse(JSON.stringify(payload)).blocks).toHaveLength(2);+ const payload = buildSlackPayload({+ verdict: 'conflict',+ stable: 'v1',+ refs: hostile,+ runUrl: '',+ });+ expect(JSON.parse(JSON.stringify(payload)).blocks).toHaveLength(1);});- test('caps a large batch instead of blowing Slack’s block limit', () => {+ test('caps a large batch of refs instead of blowing Slack’s block limit', () => {const many = Array.from({ length: 12 }, (_, i) => ({ref: `${i}`.repeat(12),tickets: [],@@ -390,9 +519,9 @@ describe('buildSlackPayload', () => {})),}));const body = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs: many, runUrl: '' })- .blocks[1].text.text;+ .blocks[0].text.text;expect(body).toMatch(/and 7 more ref\(s\)/);- expect(body).toMatch(/and 12 more/);+ expect(body).toContain('conflicted in 20 files');expect(body.length).toBeLessThan(3000);});});@@ -490,32 +619,50 @@ describe('workflow wiring', () => {runUrl: 'https://example.test/run',failures: ['the tiers did not finish within 1500s'],});- const page = (verdict) => payload(verdict).blocks[1].text.text;+ const page = (verdict) => payload(verdict).blocks[0].text.text;- test('says nothing was verified, rather than naming a cause', () => {+ test('says the batch retries itself, rather than naming a cause', () => {// The headline is its own surface: it is what Slack shows in a list, so- // "failed" there is the first thing an operator reads and acts on.- expect(JSON.stringify(payload('could-not-verify'))).toContain('could not verify');+ // the reason there is the first thing an operator reads.+ expect(JSON.stringify(payload('could-not-verify'))).toContain('verification timeout');const body = page('could-not-verify');- expect(body).toContain('Nothing was verified');// ROUTING, not just the branch. Every assertion below this comment used// to be satisfiable by rendering NOTHING: revert the verdict test on the- // `failureLines` call and this page becomes a `*Why it refused*` heading- // over a blank line, which is the exact shape `refLines` warns about --- // stating a refusal and listing no evidence for it.+ // `failureSummaryLines` call and this page becomes a `*Why it refused*`+ // heading over a blank line, an empty-evidence shape this file avoids+ // throughout (`refSummaryLine`'s own zero-files branch states the fact+ // rather than an empty conflict count, for the same reason).expect(body).toContain('did not finish within 1500s');+ // The reason this verdict exists: nothing was learned about the batch.+ expect(body).toContain('nothing was verified about the queued fixes');expect(body).not.toMatch(/\*Why it refused\*\n\n/);- // The one thing this whole verdict exists to tell an operator. Nothing- // else in this file asserts any `optionsFor` string for it, so emptying- // that branch rendered a bare header and stayed green.- expect(body).toContain('IS a retry candidate');- // Every one of these is false on a blow, and the last is the inverse of- // the truth — the batch is precisely a retry candidate.+ // The one thing this whole verdict exists to tell an operator: it is not+ // riding the soak, it retries the fast lane on its own.+ expect(body).toContain('retries this batch automatically');+ // Every one of these is a `fail`/default-verdict phrase and must not leak+ // onto a budget blow — the batch went unverified, not red.expect(body).not.toContain('not flake-class');- expect(body).not.toContain('depends on later work');- expect(body).not.toContain('not a retry candidate');- expect(body).not.toContain('the stable is red on its own');+ expect(body).not.toContain('red verification');+ expect(body).not.toContain('24h soak lane');+ expect(body).not.toContain("rides its cycle's stable");+ });++ // Unreachable in production today — the workflow overwrites `FAILURES`+ // unconditionally on this verdict, so `failures` is never actually empty+ // here — but `failureSummaryLines` is a pure function, and its own+ // zero-failures contract for this verdict is worth pinning regardless of+ // what currently calls it that way.+ test('a budget blow with no captured failures still says nothing was verified', () => {+ const body = buildSlackPayload({+ verdict: 'could-not-verify',+ stable: 'v1',+ refs: [],+ runUrl: '',+ failures: [],+ }).blocks[0].text.text;+ expect(body).toContain('ran out of their time budget');+ expect(body).toContain('nothing was verified about the queued fixes');});// Mirrors the `fail` parity case: a partial drop followed by a budget blow@@ -536,21 +683,29 @@ describe('workflow wiring', () => {],runUrl: 'https://example.test/run',failures: ['the tiers did not finish within 1500s (exit 124)'],- }).blocks[1].text.text;+ }).blocks[0].text.text;expect(body).toContain('Also dropped from this batch');expect(body).toContain('abc1234');- // Rendering the page showed `undefined - CARRIES BEHAVIOR (undefined)`- // from a fixture that passed bare strings where refLines reads objects.- // Asserting the ref alone did not see it, so assert the file line too.- expect(body).toContain('packages/core/src/index.ts');+ expect(body).toContain('conflicted in 1 file');+ // Rendering the page used to show `undefined - CARRIES BEHAVIOR+ // (undefined)` from a fixture that passed bare strings where the old+ // per-file renderer read objects. The per-file breakdown is gone now,+ // but the guard against `undefined` leaking into the page stays.expect(body).not.toContain('undefined');});test('still says all of that for a genuine red tier', () => {const body = page('fail');expect(body).toContain('not flake-class');- expect(body).toContain('not a retry candidate');+ expect(body).toContain('red verification');expect(body).not.toContain('ran out of');+ // The fix riding the soak is not the same claim as the lane being+ // fine — the fail-specific no-action sentence must not promise what+ // the unscoped default line does. Asserted both ways: the arm's own+ // wording must render (a `return ''` here would otherwise ship green),+ // and the unscoped default's wording must not leak onto it.+ expect(body).toContain('The fix itself needs nothing');+ expect(body).not.toContain("No action needed — it rides its cycle's stable");});});@@ -562,6 +717,13 @@ describe('workflow wiring', () => {expect(shellOf('Page on a refusal')).not.toMatch(/\$\{[A-Za-z_]+:-\{/);});+ // The plain-text fallback fires when the script itself fails to compose —+ // the least-informed path, and the one most likely to be hand-edited+ // without ever running the `.mjs` suite. It must stay emoji-free too.+ test('the plain-text fallback is emoji-free', () => {+ expect(shellOf('Page on a refusal')).not.toMatch(/[\u{1F000}-\u{1FFFF}☀-➿]/u);+ });+// Steps share one workspace, and verify leaves it detached at the stable tag// — which predates this script, so it is simply not on disk by the time the// page runs. Without a restore the page degrades to the fallback forever,diff --git a/.github/workflows/bug-lane-verify.yml b/.github/workflows/bug-lane-verify.ymlindex 00bb649a8..40e9ceba2 100644--- a/.github/workflows/bug-lane-verify.yml+++ b/.github/workflows/bug-lane-verify.yml@@ -760,7 +760,7 @@ jobs:# marker unwritten so the next tick tries again.if ! payload="$(node .github/scripts/bug-lane-refusal-payload.mjs --input "$INPUT")"; thenecho "::warning::bug-lane: could not compose the refusal page; falling back to a plain message."- payload="$(jq -nc --arg t "⛔ Bug lane refused ${FIX_REFS} (${VERDICT}) over ${STABLE}. ${RUN_URL}" '{text: $t}')"+ payload="$(jq -nc --arg t "Bug lane: ${FIX_REFS} did not ship in the fast lane (${VERDICT}) over ${STABLE}. ${RUN_URL}" '{text: $t}')"fiif curl -sS --fail -X POST -H 'Content-type: application/json' --data "$payload" "$WEBHOOK_URL"; thendelivered=true