Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): say why the bug lane refused, not just that it did (PRD-7862) (#3337)
Andrew Mikofalvyb996bd8eefe7
diff --git a/.github/scripts/bug-lane-refusal-payload.mjs b/.github/scripts/bug-lane-refusal-payload.mjsnew file mode 100644index 000000000..4a061d714--- /dev/null+++ b/.github/scripts/bug-lane-refusal-payload.mjs@@ -0,0 +1,309 @@+#!/usr/bin/env node+/**+ * The Slack page for a bug-lane refusal.+ *+ * WHY this is not a format string in the workflow. A refusal that names a SHA+ * and a verdict tells a reader nothing they can act on, and `apply-conflict` in+ * particular reads as "this fix is incompatible with the stable" when the far+ * likelier cause is that an unrelated commit rewrote the same line of CI+ * config since the stable was cut. That is the same distinction the point+ * release runbook already draws for `pnpm-workspace.yaml` — config drift is+ * not a dependency — and it was never surfaced for this lane, so every+ * refusal read as the severe case. The reader has one question, "does this+ * need a manual point release?", and answering it requires knowing WHICH+ * paths collided and whether any of them carries behavior.+ *+ * This explains; it does not resolve. The lane keeps the unconditional hard+ * fail — automated dispatches never set `resolve_paths`, and nothing here+ * changes that. The classification decides what the message SAYS, never what+ * the lane DOES.+ *+ * Classification is fail-closed. A path is inert only when it is positively+ * proven to be both non-shipping and non-gating; anything unreadable,+ * unparseable, or merely unrecognized is reported as behavior-carrying. A+ * false "inert" would invite an operator to force through a fix that really+ * does depend on something the stable lacks, so the failure direction is+ * chosen deliberately: over-reporting severity costs a human a minute of+ * reading, under-reporting it costs a bad release.+ *+ * Usage:+ * node bug-lane-refusal-payload.mjs --input <json> [--repo owner/name]+ *+ * Emits the payload as JSON on stdout. Everything is assembled through+ * JSON.stringify, so a commit subject containing quotes cannot corrupt the+ * body.+ */++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.+ *+ * `scripts.test:e2e` is the Playwright CI subset: a single ~10 KB line listing+ * every spec file the tier runs. Every commit that adds an e2e test appends to+ * it, which is exactly what a well-formed bug fix does, so it is the highest+ * churn line in the repo and collides with any sibling append that landed+ * since the stable. It is `test:e2e` specifically and not `test:*`: turbo runs+ * `test` as the lane's own verification tier, so a drifted `scripts.test`+ * WOULD change the verdict, while `test:e2e` is a separate task that the lane+ * never invokes.+ *+ * Entries are added only with both halves proven: the file does not reach a+ * user (enforced separately, below, by requiring the package be private) and+ * the key does not gate the verification the lane runs.+ */+export const INERT_JSON_KEYS = Object.freeze(new Set(['scripts.test:e2e']));++/** Dotted leaf paths, so `scripts.test:e2e` is one key rather than a subtree. */+function flattenJson(value, prefix = '', out = {}) {+ if (value === null || typeof value !== 'object' || Array.isArray(value)) {+ out[prefix] = JSON.stringify(value);+ return out;+ }+ for (const [k, v] of Object.entries(value)) {+ flattenJson(v, prefix ? `${prefix}.${k}` : k, out);+ }+ return out;+}++/** Leaf keys that differ between two parsed JSON documents, in sorted order. */+export function changedJsonKeys(before, after) {+ const a = flattenJson(before);+ const b = flattenJson(after);+ const keys = new Set([...Object.keys(a), ...Object.keys(b)]);+ return [...keys].filter((k) => a[k] !== b[k]).sort();+}++/**+ * Is this conflicted path provably inert, and why?+ *+ * The question asked is deliberately about the FIX's own edit, not about the+ * conflict hunk: a textual conflict says two sides touched one line, while+ * what an operator needs to know is whether the change the fix is trying to+ * make carries behavior. So this reads what the fix changed relative to its+ * own parent and judges that.+ */+export function classifyConflictPath({ path, before, after }) {+ const unknown = (why) => ({ path, inert: false, detail: why });++ if (!path.endsWith('package.json')) {+ return unknown('carries behavior (or cannot be proven not to)');+ }+ let parsedBefore;+ let parsedAfter;+ try {+ parsedBefore = JSON.parse(before);+ parsedAfter = JSON.parse(after);+ } catch {+ return unknown('unreadable at one of the two revisions');+ }+ // The non-shipping half. A published package's manifest reaches users+ // whatever key moved, so it is never eligible regardless of the key.+ if (parsedAfter.private !== true) {+ return unknown('a published package manifest');+ }+ const keys = changedJsonKeys(parsedBefore, parsedAfter);+ // No line-level change means the conflict did not come from the fix, so+ // there is nothing here to judge as harmless.+ if (keys.length === 0) {+ return unknown('conflicted without the fix changing it');+ }+ const offenders = keys.filter((k) => !INERT_JSON_KEYS.has(k));+ if (offenders.length > 0) {+ return unknown(`changes ${offenders.join(', ')}`);+ }+ return {+ path,+ inert: true,+ detail: `${keys.join(', ')} only — private package, not in turbo \`test\`. Does not ship, does not gate.`,+ };+}++/** The real git boundary; injected as a fake in tests. */+export function makeGitShow(cwd = process.cwd()) {+ return (rev, path) => {+ try {+ return execFileSync('git', ['show', `${rev}:${path}`], {+ cwd,+ encoding: 'utf8',+ env: gitCleanEnv(),+ maxBuffer: 64 * 1024 * 1024,+ });+ } catch {+ return null;+ }+ };+}++/**+ * Classify every conflicted path of every dropped ref.+ *+ * A ref is only as resolvable as its worst path, so `inert` on the ref is the+ * conjunction: one behavior-carrying collision means the whole pick is the+ * severe case no matter how many harmless ones sit beside it.+ */+export function classifyRefs(refs, gitShow) {+ return refs.map((entry) => {+ const files = (entry.conflicts ?? []).map((path) => {+ const before = gitShow(`${entry.ref}^`, path);+ const after = gitShow(entry.ref, path);+ if (before === null || after === null) {+ return { path, inert: false, detail: 'unreadable at one of the two revisions' };+ }+ return classifyConflictPath({ path, before, after });+ });+ return {+ ...entry,+ files,+ inert: files.length > 0 && files.every((f) => f.inert),+ };+ });+}++/**+ * 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.+ */+export function describeRefusal({ verdict, refs }) {+ if (verdict === 'fail') {+ return {+ headline: 'Bug lane: verification failed on the synthetic tree',+ meaning:+ 'The fast tiers went red on BOTH attempts, or the install failed. Past flake-class: treat it as a real conflict with the stable.',+ };+ }+ 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.',+ };+ }+ 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.',+ };+}++/**+ * 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.+ */+export function optionsFor({ verdict, refs }) {+ if (verdict === 'fail') {+ return [+ 'Read the failing tier in the run log before anything else — a red synthetic tree is a real incompatibility, not a retry candidate.',+ 'The fixes ride their cycle’s stable. Forcing them past a red verification is not an option this lane offers.',+ ];+ }+ 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 [+ '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".',+ ];+}++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);+ lines.push(+ `${label} — conflicted in ${entry.files.length} file${entry.files.length === 1 ? '' : 's'}:`,+ );+ 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.`);+ }+ }+ if (refs.length > MAX_REFS_SHOWN) {+ lines.push(`…and ${refs.length - MAX_REFS_SHOWN} more ref(s); see the run.`);+ }+ return lines;+}++export function buildSlackPayload({ verdict, stable, refs, runUrl, repo = DEFAULT_REPO }) {+ const { headline, meaning } = describeRefusal({ verdict, refs });+ const summary = `⛔ ${headline}`;+ const body = [+ `*Over \`${stable}\` on \`${repo}\`.* ${meaning}`,+ '',+ '*Why it refused*',+ ...refLines(refs),+ '',+ '*What you can do*',+ ...optionsFor({ verdict, refs }).map((o, i) => `${i + 1}. ${o}`),+ '',+ // Only the run link is conditional; the blank separators above are+ // deliberate and must survive.+ ...(runUrl ? [`<${runUrl}|Run log>`] : []),+ '_Further identical refusals stay silent; the lane pages again only if the refusal changes._',+ ].join('\n');++ 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 } },+ ],+ };+}++export function parseArgs(argv) {+ const args = {};+ const rest = argv.slice(2);+ for (let i = 0; i < rest.length; i += 1) {+ const key = rest[i];+ if (!key.startsWith('--')) continue;+ args[key.slice(2)] = rest[i + 1] ?? '';+ i += 1;+ }+ if (!args.input) throw new Error('--input is required');+ const parsed = JSON.parse(args.input);+ return {+ verdict: parsed.verdict || 'conflict',+ stable: parsed.stable || '(unknown stable)',+ refs: Array.isArray(parsed.refs) ? parsed.refs : [],+ runUrl: parsed.runUrl || '',+ repo: args.repo || parsed.repo || DEFAULT_REPO,+ };+}++if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {+ try {+ const parsed = parseArgs(process.argv);+ const refs = classifyRefs(parsed.refs, makeGitShow());+ process.stdout.write(JSON.stringify(buildSlackPayload({ ...parsed, refs })));+ } catch (err) {+ process.stderr.write(`${err.message}\n`);+ process.exit(1);+ }+}diff --git a/.github/scripts/bug-lane-refusal-payload.test.mjs b/.github/scripts/bug-lane-refusal-payload.test.mjsnew file mode 100644index 000000000..967c93d55--- /dev/null+++ b/.github/scripts/bug-lane-refusal-payload.test.mjs@@ -0,0 +1,330 @@+import { readFileSync } from 'node:fs';+import { dirname, join } from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, test } from 'vitest';+import {+ buildSlackPayload,+ changedJsonKeys,+ classifyConflictPath,+ classifyRefs,+ describeRefusal,+ INERT_JSON_KEYS,+ optionsFor,+ parseArgs,+} from './bug-lane-refusal-payload.mjs';++const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');+const bugLane = readFileSync(join(REPO_ROOT, '.github', 'workflows', 'bug-lane.yml'), 'utf8');++/** A private manifest whose only fix-side change is the Playwright subset. */+const appManifest = (e2e) =>+ JSON.stringify({+ name: '@inkeep/open-knowledge-app',+ private: true,+ scripts: { test: 'vitest run', 'test:e2e': `playwright test ${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'],+ );+ });++ test('catches added and removed leaves, not just modified ones', () => {+ expect(changedJsonKeys({ a: 1 }, { a: 1, b: 2 })).toEqual(['b']);+ expect(changedJsonKeys({ a: 1, b: 2 }, { a: 1 })).toEqual(['b']);+ });++ test('does not confuse a stringified value with a structural change', () => {+ expect(changedJsonKeys({ a: '1' }, { a: 1 })).toEqual(['a']);+ });+});++describe('classifyConflictPath', () => {+ // The incident this exists for: a bug fix appended one Playwright spec to+ // the CI subset, an unrelated feature had appended six since the stable, and+ // the whole point release was refused over a line that does not ship.+ test('the e2e-subset append is inert', () => {+ const got = classifyConflictPath({+ path: 'packages/app/package.json',+ before: appManifest('a.e2e.ts b.e2e.ts'),+ after: appManifest('a.e2e.ts b.e2e.ts preview-tab-promotion.e2e.ts'),+ });+ expect(got.inert).toBe(true);+ expect(got.detail).toContain('scripts.test:e2e');+ expect(got.detail).toMatch(/does not ship/i);+ });++ 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') });+ expect(got.inert).toBe(false);+ expect(got.detail).toMatch(/published/);+ });++ test('a sibling key riding along disqualifies the whole path', () => {+ const before = appManifest('a.e2e.ts');+ const after = JSON.stringify({+ name: '@inkeep/open-knowledge-app',+ private: true,+ scripts: { test: 'vitest run', 'test:e2e': 'playwright test a.e2e.ts b.e2e.ts' },+ dependencies: { react: '19.2.0' },+ });+ const got = classifyConflictPath({ path: 'packages/app/package.json', before, after });+ expect(got.inert).toBe(false);+ expect(got.detail).toContain('dependencies.react');+ });++ // `scripts.test` IS the tier the lane runs to verify the synthetic tree, so+ // treating it like its `test:e2e` sibling would let a drifted verification+ // command be reported as harmless.+ test('scripts.test is not inert even though test:e2e is', () => {+ expect(INERT_JSON_KEYS.has('scripts.test')).toBe(false);+ const after = JSON.stringify({+ name: '@inkeep/open-knowledge-app',+ private: true,+ scripts: { test: 'vitest run --changed', 'test:e2e': 'playwright test a.e2e.ts' },+ });+ const got = classifyConflictPath({+ path: 'packages/app/package.json',+ before: appManifest('a.e2e.ts'),+ after,+ });+ expect(got.inert).toBe(false);+ expect(got.detail).toContain('scripts.test');+ });++ test.each([+ ['a source file', 'packages/app/src/components/FileTree.tsx', 'x', 'y'],+ ['a lockfile', 'pnpm-lock.yaml', 'a', 'b'],+ ['a workflow', '.github/workflows/release.yml', 'a', 'b'],+ ])('fails closed on %s', (_label, path, before, after) => {+ expect(classifyConflictPath({ path, before, after }).inert).toBe(false);+ });++ test('fails closed on unparseable JSON rather than assuming', () => {+ const got = classifyConflictPath({+ path: 'packages/app/package.json',+ before: '{not json',+ after: appManifest('a.e2e.ts'),+ });+ expect(got.inert).toBe(false);+ expect(got.detail).toMatch(/unreadable/);+ });++ 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 });+ expect(got.inert).toBe(false);+ expect(got.detail).toMatch(/without the fix changing it/);+ });+});++describe('classifyRefs', () => {+ const gitShow = (blobs) => (rev, path) => blobs[`${rev}:${path}`] ?? null;++ test('a ref is inert only when every one of its paths is', () => {+ const blobs = {+ 'abc^:packages/app/package.json': appManifest('a.e2e.ts'),+ 'abc:packages/app/package.json': appManifest('a.e2e.ts b.e2e.ts'),+ 'abc^:packages/app/src/x.ts': 'a',+ 'abc:packages/app/src/x.ts': 'b',+ };+ const [onlyConfig] = classifyRefs(+ [{ ref: 'abc', conflicts: ['packages/app/package.json'] }],+ gitShow(blobs),+ );+ expect(onlyConfig.inert).toBe(true);++ const [withSource] = classifyRefs(+ [{ ref: 'abc', conflicts: ['packages/app/package.json', 'packages/app/src/x.ts'] }],+ gitShow(blobs),+ );+ expect(withSource.inert).toBe(false);+ });++ test('an unreadable blob fails closed instead of throwing', () => {+ const [entry] = classifyRefs([{ ref: 'abc', conflicts: ['gone.json'] }], gitShow({}));+ expect(entry.inert).toBe(false);+ expect(entry.files[0].detail).toMatch(/unreadable/);+ });++ test('a ref with no recorded conflicts is not vacuously inert', () => {+ expect(classifyRefs([{ ref: 'abc', conflicts: [] }], gitShow({}))[0].inert).toBe(false);+ });+});++describe('describeRefusal', () => {+ const inert = [{ ref: 'a', inert: true, files: [] }];+ const behavioral = [{ ref: 'a', inert: false, files: [] }];++ test('the three 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: [] });+ expect(new Set([drift, real, red]).size).toBe(3);+ expect(drift).toMatch(/config drift, not by the fix/);+ expect(real).toMatch(/does not apply/);+ });++ 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/,+ );+ });+});++describe('optionsFor', () => {+ test('the inert case never points at resolve_paths, which would refuse', () => {+ const opts = optionsFor({ verdict: 'conflict', refs: [{ ref: 'a', inert: true, files: [] }] });+ expect(opts.join('\n')).not.toMatch(/-f resolve_paths=/);+ expect(opts.join('\n')).toMatch(/allowlist is code/);+ });++ test('inert and behavioral give different advice', () => {+ const a = optionsFor({ verdict: 'conflict', refs: [{ ref: 'x', inert: true, files: [] }] });+ const b = optionsFor({ verdict: 'conflict', refs: [{ ref: 'x', inert: false, files: [] }] });+ expect(a).not.toEqual(b);+ expect(b.join('\n')).toMatch(/smaller self-contained commit/);+ });+});++describe('buildSlackPayload', () => {+ const refs = [+ {+ ref: '103e961036fc053824b98f1e44a4616d6d4d9d87',+ tickets: ['PRD-7835'],+ totalFiles: 28,+ inert: true,+ files: [{ path: 'packages/app/package.json', inert: true, detail: 'scripts.test:e2e only' }],+ },+ ];++ test('names the ticket, the path, the verdict and what applied cleanly', () => {+ const body = buildSlackPayload({+ verdict: 'conflict',+ stable: 'v0.48.9',+ refs,+ runUrl: 'https://example.test/run/1',+ }).blocks[1].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');+ });++ test('keeps the silence-is-deliberate note', () => {+ const body = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs, runUrl: '' }).blocks[1]+ .text.text;+ expect(body).toMatch(/Further identical refusals stay silent/);+ });++ 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);+ });++ test('caps a large batch instead of blowing Slack’s block limit', () => {+ const many = Array.from({ length: 12 }, (_, i) => ({+ ref: `${i}`.repeat(12),+ tickets: [],+ totalFiles: 2,+ inert: false,+ files: Array.from({ length: 20 }, (_, j) => ({+ path: `p${j}.ts`,+ inert: false,+ detail: 'carries behavior',+ })),+ }));+ const body = buildSlackPayload({ verdict: 'conflict', stable: 'v1', refs: many, runUrl: '' })+ .blocks[1].text.text;+ expect(body).toMatch(/and 7 more ref\(s\)/);+ expect(body).toMatch(/and 12 more/);+ expect(body.length).toBeLessThan(3000);+ });+});++describe('parseArgs', () => {+ test('requires --input', () => {+ expect(() => parseArgs(['node', 'x'])).toThrow(/--input is required/);+ });++ test('defaults a missing refs array rather than throwing', () => {+ expect(parseArgs(['node', 'x', '--input', '{"verdict":"fail"}']).refs).toEqual([]);+ });+});++describe('workflow wiring', () => {+ /** Exact bounds of a step: its `- name:` up to the next sibling step. */+ const step = (name) => {+ const rest = bugLane.slice(bugLane.indexOf(`- name: ${name}`));+ const end = rest.indexOf('\n - name: ');+ return end === -1 ? rest : rest.slice(0, end);+ };++ /**+ * The step's executable shell, with whole-line comments removed. Assertions+ * about what the shell DOES must not be satisfiable — or broken — by prose+ * that quotes the very form it warns against.+ */+ const shellOf = (name) =>+ step(name)+ .split('\n')+ .filter((l) => !/^\s*#/.test(l))+ .join('\n');++ test('the verify step records conflicted paths before aborting the pick', () => {+ const verify = step('Verify the synthetic tree');+ const conflictCapture = verify.indexOf('--diff-filter=U');+ const abort = verify.indexOf('cherry-pick --abort');+ expect(conflictCapture).toBeGreaterThan(-1);+ // An abort clears the index, so capturing after it yields an empty list and+ // the page silently loses the only datum that makes it actionable.+ expect(conflictCapture).toBeLessThan(abort);+ });++ test('the refusal page builds its body through this script', () => {+ expect(step('Page on a refusal')).toContain('bug-lane-refusal-payload.mjs');+ });++ // `${V:-{\}}` expands to a LITERAL `{\}` — a brace in a parameter-expansion+ // default is not escapable there. jq --argjson then refuses, and the enriched+ // page degrades to the plain fallback on every single run, with nothing in+ // the log saying the enrichment never happened.+ test('the page does not default a JSON var with a brace expansion', () => {+ expect(shellOf('Page on a refusal')).not.toMatch(/\$\{[A-Za-z_]+:-\{/);+ });++ // 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,+ // and nothing in the log says the enrichment never happened.+ test('the page restores the lane scripts the detached tree dropped', () => {+ const shell = shellOf('Page on a refusal');+ const restore = shell.indexOf('git checkout "$GITHUB_SHA"');+ const invoke = shell.indexOf('bug-lane-refusal-payload.mjs');+ expect(restore).toBeGreaterThan(-1);+ expect(restore).toBeLessThan(invoke);+ });++ // `git checkout <ref> -- a b` is atomic: one path missing at that ref aborts+ // the whole restore, so combining them would let an unrelated rename leave+ // the page silently degraded. Asserted as the shape it must have — one+ // single-token pathspec, driven by a loop — rather than by trying to exclude+ // every way two could be written.+ test('the restore names one path at a time', () => {+ expect(shellOf('Page on a refusal')).toMatch(+ /for p in [^\n]*\n\s*git checkout "\$GITHUB_SHA" -- "\$p"/,+ );+ });++ test('the lane still never authorizes conflict resolution when dispatching', () => {+ expect(bugLane).not.toContain('resolve_paths');+ });+});diff --git a/.github/scripts/bug-lane.mjs b/.github/scripts/bug-lane.mjsindex 169c92351..945f07001 100644--- a/.github/scripts/bug-lane.mjs+++ b/.github/scripts/bug-lane.mjs@@ -179,6 +179,19 @@ export async function evaluateBugLane({};}+/**+ * Qualifying sha -> the Bug tickets that qualified it. Only qualifying commits+ * are included: a rejected commit's links describe why it was NOT picked, and+ * surfacing them downstream would invite a reader to think it shipped.+ */+export function ticketsByRef(result) {+ const out = {};+ for (const c of result.perCommit) {+ if (c.qualifies && c.linkedIssues.length > 0) out[c.sha] = [...c.linkedIssues];+ }+ return out;+}+// --- workflow-runtime wiring (real git boundary) ---function runGit(args) {@@ -271,7 +284,15 @@ async function main() {if (process.env.GITHUB_OUTPUT) {appendFileSync(process.env.GITHUB_OUTPUT,- [`fix_refs=${result.fixRefs.join(',')}`, `stable=${stable}`, ''].join('\n'),+ [+ `fix_refs=${result.fixRefs.join(',')}`,+ `stable=${stable}`,+ // sha -> the Bug tickets that qualified it, so a refusal page can name+ // the bug a reader recognises instead of only a SHA. One line: the map+ // is bounded by the qualifying set, which is single digits.+ `fix_tickets=${JSON.stringify(ticketsByRef(result))}`,+ '',+ ].join('\n'),);}}diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjsindex a2f31b065..321ee0b9a 100644--- a/.github/scripts/release-cascade-shape.test.mjs+++ b/.github/scripts/release-cascade-shape.test.mjs@@ -554,7 +554,14 @@ describe('the bug lane verifies the synthetic tree at the same bar as main', ()bugLane.indexOf('- name: Page on a refusal'),bugLane.indexOf('- name: Record that this refusal was paged'),);- expect(page).toContain('Further identical refusals stay silent');+ // The sentence lives in the payload builder the step shells out to, so the+ // contract is "the step composes a body that carries it" rather than "the+ // YAML contains the literal". Assert both halves: the step reaches the+ // builder, and the builder still emits the sentence.+ expect(page).toContain('bug-lane-refusal-payload.mjs');+ expect(+ readFileSync(join(WORKFLOWS, '..', 'scripts', 'bug-lane-refusal-payload.mjs'), 'utf8'),+ ).toContain('Further identical refusals stay silent');});test('a suppressed refusal still leaves a trace in the run', () => {diff --git a/.github/workflows/bug-lane.yml b/.github/workflows/bug-lane.ymlindex 079981456..39bea9b49 100644--- a/.github/workflows/bug-lane.yml+++ b/.github/workflows/bug-lane.yml@@ -141,15 +141,42 @@ jobs:IFS=',' read -ra REFS <<< "$FIX_REFS"SURVIVORS=()DROPPED=()+ # Which paths collided, per dropped ref, as JSON for the refusal page.+ # "conflict" alone cannot distinguish a fix that genuinely depends on+ # later work from one blocked by an unrelated rewrite of a line of CI+ # config, and that is the whole question a reader has.+ CONFLICT_JSON='[]'for ref in "${REFS[@]}"; doif git cherry-pick "$ref"; thenSURVIVORS+=("$ref")else+ # BEFORE the abort: --abort clears the index, and with it the+ # unmerged-path list this reads. Capturing after yields nothing.+ # A plain read loop rather than `mapfile` so the shell does not+ # depend on a bash 4 builtin.+ CONFLICTED=()+ while IFS= read -r f; do+ [[ -n "$f" ]] && CONFLICTED+=("$f")+ done < <(git diff --name-only --diff-filter=U || true)+ TOTAL_FILES=$(git show --pretty=format: --name-only "$ref" | grep -c . || true)+ # `${a[@]+"${a[@]}"}` so an empty array is not an unbound-variable+ # error under `set -u`: a pick can fail without conflicting (an+ # empty commit), and that must still mint a report.+ CONFLICT_JSON=$(jq -c \+ --arg ref "$ref" \+ --argjson total "${TOTAL_FILES:-0}" \+ --args '. + [{ref: $ref, totalFiles: $total, conflicts: $ARGS.positional}]' \+ <<< "$CONFLICT_JSON" ${CONFLICTED[@]+"${CONFLICTED[@]}"})git cherry-pick --abort || trueDROPPED+=("$ref")- echo "::notice::bug-lane: ${ref} does not apply cleanly onto ${STABLE}; dropped from this batch — it will ship with its cycle's stable instead."+ echo "::notice::bug-lane: ${ref} does not apply cleanly onto ${STABLE} (conflicted in: ${CONFLICTED[*]:-none}); dropped from this batch — it will ship with its cycle's stable instead."fidone+ {+ echo "conflicts<<CONFLICTS_EOF"+ echo "$CONFLICT_JSON"+ echo "CONFLICTS_EOF"+ } >> "$GITHUB_OUTPUT"if [[ ${#DROPPED[@]} -gt 0 ]]; thenecho "dropped_refs=$(IFS=','; echo "${DROPPED[*]}")" >> "$GITHUB_OUTPUT"fi@@ -337,8 +364,11 @@ jobs:SLACK_RELEASES_WEBHOOK_URL: ${{ secrets.SLACK_RELEASES_WEBHOOK_URL }}SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}FIX_REFS: ${{ steps.evaluate.outputs.fix_refs }}+ FIX_TICKETS: ${{ steps.evaluate.outputs.fix_tickets }}SURVIVING_REFS: ${{ steps.verify.outputs.surviving_refs }}DROPPED_REFS: ${{ steps.verify.outputs.dropped_refs }}+ CONFLICTS: ${{ steps.verify.outputs.conflicts }}+ STABLE: ${{ steps.evaluate.outputs.stable }}VERDICT: ${{ steps.verify.outputs.verdict }}run: |set -uo pipefail@@ -353,23 +383,45 @@ jobs:echo "::notice::No Slack webhook secret set — refusal page skipped."elseRUN_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"- # Name only the refs each verdict is actually about: on conflict the- # whole qualifying set conflicted; on fail only the survivors reached- # the verification stage.- if [[ "$VERDICT" == "conflict" ]]; then- TEXT="⛔ Bug lane: no qualifying fix is self-contained over the stable — all of ${FIX_REFS} conflict. They ride their cycle's 24h path; investigate whether any needs a manual point release. ${RUN_URL}"- else- TEXT="⛔ Bug lane: verification failed on the synthetic tree for ${SURVIVING_REFS} — the fast tiers went red on BOTH attempts, or the install failed. Either way this is past flake-class: treat it as a real conflict with the stable, not a retryable blip."- if [[ -n "${DROPPED_REFS}" ]]; then- TEXT="${TEXT} Also dropped for conflict: ${DROPPED_REFS}."- fi- TEXT="${TEXT} The fixes ride their cycle's 24h path. ${RUN_URL}"+ # The verify step left the workspace detached at the stable tag,+ # which predates this tooling — every step shares one workspace, so+ # the builder below is simply absent from disk. Restore the lane's+ # own scripts from the ref the workflow is running from. Restored+ # per path, never as one pathspec: `git checkout <ref> -- a b` is+ # atomic, so a path missing at that ref would silently take the+ # other one down with it and leave the page permanently degraded.+ # The synthetic tree has already served its purpose here — verify+ # is done, and dispatch (which reads no repo file) is mutually+ # exclusive with this step.+ for p in .github/scripts scripts; do+ git checkout "$GITHUB_SHA" -- "$p" 2>/dev/null \+ || echo "::warning::bug-lane: could not restore ${p}; the page may fall back."+ done+ # Defaults go through intermediate variables, NOT `${V:-{\}}`: a+ # brace in a parameter-expansion default is taken literally+ # (backslash and all), so jq --argjson would reject it and every+ # page would silently degrade to the fallback below.+ TICKETS_JSON="${FIX_TICKETS:-}"+ [[ -z "$TICKETS_JSON" ]] && TICKETS_JSON='{}'+ CONFLICTS_JSON="${CONFLICTS:-}"+ [[ -z "$CONFLICTS_JSON" ]] && CONFLICTS_JSON='[]'+ # Join each dropped ref to the tickets that qualified it, so the+ # page names the bug rather than only a SHA.+ INPUT="$(jq -nc \+ --arg verdict "$VERDICT" \+ --arg stable "$STABLE" \+ --arg runUrl "$RUN_URL" \+ --argjson conflicts "$CONFLICTS_JSON" \+ --argjson tickets "$TICKETS_JSON" \+ '{verdict: $verdict, stable: $stable, runUrl: $runUrl,+ refs: [$conflicts[] | . + {tickets: ($tickets[.ref] // [])}]}')"+ # A page that cannot be composed must not become silence: fall back+ # to the bare facts rather than skipping the POST, and leave the+ # marker unwritten so the next tick tries again.+ if ! payload="$(node .github/scripts/bug-lane-refusal-payload.mjs --input "$INPUT")"; then+ echo "::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}')"fi- # Say that the silence which follows is deliberate. Without this a- # reader cannot tell "paged once, still refusing every tick" from- # "resolved", and would read the quiet channel as good news.- TEXT="${TEXT} Further identical refusals stay silent; the lane pages again only if the refusal changes."- payload="$(jq -nc --arg t "$TEXT" '{text: $t}')"if curl -sS --fail -X POST -H 'Content-type: application/json' --data "$payload" "$WEBHOOK_URL"; thendelivered=trueelse