diff --git a/plugins/stewards/need-parts.ts b/plugins/stewards/need-parts.ts index 38c603a7..5df8e3e4 100644 --- a/plugins/stewards/need-parts.ts +++ b/plugins/stewards/need-parts.ts @@ -136,6 +136,29 @@ export function mergeNeedParts(input: { key: string; lane: string | null; note?: return { what, how, why: MERGE_WHY, details: how }; } +/** The marker a project-steward merge ask carries when the lane gate is already met (BB-386 fix 4). */ +export const MERGE_WORKAROUND_MARK = "Workaround"; + +/** + * BB-386 fix 4: the project steward must not invent an owner gate. When it + * asks the owner to merge a pull request whose lane gate is already met and + * whose decide list routes it to the project steward, no owner's merge is the + * gate, so the ask is a workaround. This returns the marker and the gate's + * verdict to attach to the item, or null when the ask is legitimate (the gate + * is not met, or the pull request is the user's to decide). The item is never + * refused: the owner still receives it, marked. + */ +export function mergeWorkaroundParts(input: { key: string; lane: string | null; headSha: string | null; gateMet: boolean; decision: "project" | "user" }): { why: string; details: string } | null { + if (!input.gateMet || input.decision !== "project") return null; + const lane = input.lane === null || input.lane === "" ? "lane unknown" : input.lane; + const sha = input.headSha === null || input.headSha === "" ? "the current head" : input.headSha.slice(0, 7); + const verdict = `gate met at ${sha} (${lane}), decide: ${input.decision}`; + return { + why: `${MERGE_WORKAROUND_MARK}: ${input.key}'s lane gate is already met (${lane}) at ${sha}, so the owner's merge is not the gate. The plugin still delivers it to you; merge it with bb stewards merge ${input.key}.`, + details: `This item is a workaround: ${input.key} is gate-met (${lane}) at ${sha} and the decide list routes it to the project steward, so the owner's approval or merge is not the gate. Merge it with bb stewards merge ${input.key}. Verdict: ${verdict}.`, + }; +} + /** The one line, context, why and details of a lesson review/retire decide item. */ export function lessonDecideParts(input: { file: string; lessonText: string; boundary: boolean; retire: boolean; branch: string | null; prUrl: string | null }): { what: string; how: string; why: string; details: string } { const what = clampNeedLine(`${input.retire ? "Retire" : "Review"} the lesson for ${input.file}`); diff --git a/plugins/stewards/readability.test.ts b/plugins/stewards/readability.test.ts index 4da0bef3..ff3e3c59 100644 --- a/plugins/stewards/readability.test.ts +++ b/plugins/stewards/readability.test.ts @@ -13,6 +13,7 @@ import { forwardWhy, lessonDecideParts, mergeNeedParts, + mergeWorkaroundParts, mixedEvidenceDecideParts, needLineProblem, playbookRefreshQuestionParts, @@ -97,6 +98,17 @@ describe("every plugin-composed item reads in three plain parts", () => { expect(readabilityProblems({ need: parts.what, context: parts.how, why: parts.why })).toEqual([]); }); + it("a merge workaround states the marker and the gate verdict, and only for a met project lane", () => { + const parts = mergeWorkaroundParts({ key: "acme/web#74", lane: "no-review", headSha: "aaaaaaa1", gateMet: true, decision: "project" })!; + expect(parts.why).toContain("Workaround"); + expect(parts.why).toContain("aaaaaaa"); + expect(parts.details).toContain("gate met at aaaaaaa (no-review), decide: project"); + expect(readabilityProblems({ need: "Merge acme/web#74", context: parts.details, why: parts.why })).toEqual([]); + // No marker when the gate is not met, or when the lane is the user's. + expect(mergeWorkaroundParts({ key: "acme/web#74", lane: "no-review", headSha: "aaaaaaa1", gateMet: false, decision: "project" })).toBeNull(); + expect(mergeWorkaroundParts({ key: "acme/web#74", lane: "owner-reviewed", headSha: "aaaaaaa1", gateMet: true, decision: "user" })).toBeNull(); + }); + it("a deps adoption decide item is short and readable", () => { const need = adoptionNeedLine("SC-111", "acme/sandbox", ["medium", "high"]); expect(readabilityProblems({ need, context: adoptionHow(true), why: ADOPTION_WHY })).toEqual([]); diff --git a/plugins/stewards/server.test.ts b/plugins/stewards/server.test.ts index 66a9fd73..8708a332 100644 --- a/plugins/stewards/server.test.ts +++ b/plugins/stewards/server.test.ts @@ -5408,6 +5408,131 @@ describe("questions to the user", () => { expect(answered.match(/Include SSO\?/gu)).toHaveLength(1); }); + // BB-386 fix 4: the project steward must not invent an owner gate. When it + // asks the owner to merge a pull request whose lane gate is already met and + // whose decide list routes it to the project steward, the item still reaches + // the owner, marked as a workaround with the gate's verdict. + describe("BB-386 fix 4: a project steward's merge ask is marked a workaround", () => { + const head = "aaaaaaa1"; + const marker = comment({ id: "m1", author: "trotterdylan", body: ``, signedBy: "thr_reviewer", createdAt: "2026-10-14T16:00:00Z" }); + const projectEntry = { text: "A cross-repo contract other repos implement", decide: "project", paths: ["web/openapi.yaml"] }; + const userEntry = { text: "Identity and access", decide: "user", paths: ["web/openapi.yaml"] }; + + /** A bound ticket whose linked pull request is observed; the decide list is the test's. */ + async function withDecide(entries: unknown[], comments: ReturnType[] = [marker]) { + const t = await setup(); + t.files[PROJECT_FILE] = JSON.stringify({ version: 1, linear: { teams: ["ENG"] }, bigDecisions: entries }); + t.entities.set("uuid-12", issue({ linkedPulls: [{ key: "acme/web#7", url: "https://github.com/acme/web/pull/7" }] })); + t.entities.set("acme/web#7", pull({ id: "acme/web#7", key: "acme/web#7", url: "https://github.com/acme/web/pull/7", unit: "acme/web", comments }, { head: "bb/eng-12-retry", checks: { state: "success", failing: [] } })); + t.githubFiles.set("acme/web#7", ["web/openapi.yaml"]); + await t.ring("linear", "uuid-12"); + const [project, steward] = t.spawns.map((x) => x.id) as [string, string]; + const qid = (text: string) => /(qst_[\w-]+)/u.exec(text)![1]!; + const binding = () => t.hooks.store.find("ENG-12")!; + return { ...t, project, steward, qid, binding }; + } + + /** The project steward forwards a gate-met `stuck` escalation about the pull request. */ + async function forwardStuck(t: Awaited>) { + const b = t.binding(); + const esc = t.hooks.store.escalate({ + bindingId: b.id, + kind: "stuck", + question: "acme/web#7 is gate-met with nobody acting.", + meanwhile: "Wait.", + route: "project", + recommendation: null, + projectId: "p1", + url: "https://github.com/acme/web/pull/7", + headSha: head, + data: { pullStuck: "gate-met", pull: "acme/web#7" }, + }); + return { esc, result: await t.tool("steward_update", { binding: "ENG-12", forward: esc.id, resolution: "text" }, t.project) }; + } + + /** The project steward forwards a decision escalation the test wrote about the pull request. */ + async function forwardDecision(t: Awaited>, question: string, entry?: string) { + const b = t.binding(); + const esc = t.hooks.store.escalate({ + bindingId: b.id, + kind: "decision", + question, + meanwhile: "Wait.", + route: "project", + recommendation: null, + projectId: "p1", + url: "https://github.com/acme/web/pull/7", + }); + return { esc, result: await t.tool("steward_update", { binding: "ENG-12", forward: esc.id, resolution: "text", ...(entry === undefined ? {} : { entry }) }, t.project) }; + } + + it("marks the forwarded item and still delivers it to the owner", async () => { + const t = await withDecide([projectEntry]); + const { result } = await forwardStuck(t); + expect(result.error, result.text).toBe(false); + const q = t.hooks.store.question(t.qid(result.text))!; + // The item reaches the owner (open, never refused). + expect(q.status).toBe("open"); + // The marker and the gate's verdict are attached, and it names the real merge path. + expect(q.why).toContain("Workaround"); + expect(q.why).toContain("bb stewards merge acme/web#7"); + expect(q.details).toContain("gate met at aaaaaaa (no-review), decide: project"); + expect(q.data.workaround).toBe(true); + expect(q.data.gateMet).toBe(true); + }); + + it("does not mark it when the gate is not met", async () => { + const t = await withDecide([projectEntry], [comment({ id: "m1", author: "trotterdylan", body: ``, signedBy: "thr_reviewer" })]); + const { result } = await forwardStuck(t); + expect(result.error, result.text).toBe(false); + const q = t.hooks.store.question(t.qid(result.text))!; + expect(q.status).toBe("open"); + expect(q.why).not.toContain("Workaround"); + expect(q.data.workaround).toBeUndefined(); + }); + + it("does not mark it when the decide list routes the pull request to the user", async () => { + const t = await withDecide([userEntry]); + const { result } = await forwardStuck(t); + expect(result.error, result.text).toBe(false); + const q = t.hooks.store.question(t.qid(result.text))!; + expect(q.status).toBe("open"); + expect(q.why).not.toContain("Workaround"); + expect(q.data.workaround).toBeUndefined(); + }); + + it("leaves an unrelated question about the same gate-met pull request unmarked and keeps its why", async () => { + const t = await withDecide([projectEntry]); + const { result } = await forwardDecision(t, "Add the repo secret before this deploys?", "A cross-repo contract other repos implement"); + expect(result.error, result.text).toBe(false); + const q = t.hooks.store.question(t.qid(result.text))!; + expect(q.status).toBe("open"); + expect(q.why).not.toContain("Workaround"); + expect(q.why).toContain("A cross-repo contract other repos implement"); + expect(q.data.workaround).toBeUndefined(); + }); + + it("marks the project steward's own ask about a gate-met project-lane pull request", async () => { + const t = await withDecide([projectEntry]); + const asked = await t.tool("steward_update", { binding: "ENG-12", ask: { question: "Merge acme/web#7?", url: "https://github.com/acme/web/pull/7", resolution: "choice", choices: ["Merge", "Close"] } }, t.project); + expect(asked.error, asked.text).toBe(false); + const q = t.hooks.store.question(t.qid(asked.text))!; + expect(q.status).toBe("open"); + expect(q.why).toContain("Workaround"); + expect(q.data.workaround).toBe(true); + }); + + it("finds the pull request by a key in the question when the ask has no url", async () => { + const t = await withDecide([projectEntry]); + const asked = await t.tool("steward_update", { binding: "ENG-12", ask: { question: "Merge acme/web#7?", resolution: "text" } }, t.project); + expect(asked.error, asked.text).toBe(false); + const q = t.hooks.store.question(t.qid(asked.text))!; + expect(q.status).toBe("open"); + expect(q.why).toContain("Workaround"); + expect(q.data.workaround).toBe(true); + }); + }); + it("closing a forwarded question with resolve decides its escalation and tells the steward", async () => { const t = await adopted(); await t.tool("steward_report", { phase: "Todo", summary: "Scope unclear.", nextAction: "Wait", actor: "other", escalate: { kind: "scope", question: "Include SSO?", meanwhile: "Wait." } }, t.steward); diff --git a/plugins/stewards/server.ts b/plugins/stewards/server.ts index d5805124..af615d71 100644 --- a/plugins/stewards/server.ts +++ b/plugins/stewards/server.ts @@ -99,7 +99,7 @@ import { type RolesFile, } from "./roles.js"; import { decideForPull, explainDecision, formatDecisionListing, globMatches, type BigDecision } from "./decisions.js"; -import { ADOPTION_WHY, adoptionNeedLine, approveSpecNeedParts, forwardedQuestionParts, forwardWhy, lessonDecideParts, mergeNeedParts, mixedEvidenceDecideParts, playbookRefreshQuestionParts, repeatedObjectionQuestionParts } from "./need-parts.js"; +import { ADOPTION_WHY, adoptionNeedLine, approveSpecNeedParts, forwardedQuestionParts, forwardWhy, lessonDecideParts, mergeNeedParts, mergeWorkaroundParts, mixedEvidenceDecideParts, playbookRefreshQuestionParts, repeatedObjectionQuestionParts } from "./need-parts.js"; import { ASSESSMENT_DIVERGENCE_MAX_AGE_MS, ASSESSMENT_DIVERGENCE_MAX_ROWS, assess, assessIdle, assessLiveWakeSource, assessWorker, compare, ownPullEntities, waitOverdueMs, type Assessment, type AssessmentInput } from "./assessment.js"; import { composeAssessment } from "./contribution.js"; import { nonActionsSchema, sortedNonActions, type NonActionCode } from "./non-actions.js"; @@ -14140,6 +14140,58 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P }), }); + /** + * BB-386 fix 4: whether an escalation or question is an ask to merge a + * pull request. A gate-met `stuck` escalation is one; otherwise the ask + * must name a merge in its question or its choices, so an unrelated + * question about the same gate-met pull request is left alone. + */ + function asksToMerge(input: { kind: string | null; data: Record; question: string; choices: readonly string[] }): boolean { + if (input.kind === "stuck" && input.data.pullStuck === "gate-met") return true; + return /\bmerge\b/iu.test([input.question, ...input.choices].join(" ")); + } + + /** The observed pull request an ask names by its url or by a key in its text (BB-386 fix 4). */ + function referencedPull(target: Binding, observed: Observed, url: string | null | undefined, text: string): EntitySnapshot | null { + const pulls = observedPulls(target, observed); + const wanted = lc(url ?? ""); + if (wanted !== "") { + const byUrl = pulls.find((p) => [p.url, p.key].some((v) => v !== null && lc(v) === wanted)); + if (byUrl !== undefined) return byUrl; + } + const hay = lc(text); + const byKey = pulls.find((p) => hay.includes(lc(p.key)) || (p.url !== null && hay.includes(lc(p.url)))); + if (byKey !== undefined) return byKey; + // A bare "#N" with no repo, when exactly one observed pull has that number. + const number = /#(\d+)/u.exec(text)?.[1]; + if (number !== undefined) { + const matches = pulls.filter((p) => /#(\d+)$/u.exec(p.key)?.[1] === number); + if (matches.length === 1) return matches[0]!; + } + return null; + } + + /** + * BB-386 fix 4: the workaround marker and gate verdict for a project + * steward's ask to merge a pull request whose lane gate is already met and + * whose decide list routes it to the project steward. The item still + * reaches the owner; the marker and the gate's verdict are attached to it, + * so the owner sees the real state instead of a made-up reason. Returns + * null when no pull request is named, the gate is not met, or the pull + * request is the user's to decide. The caller passes only a merge ask. + */ + async function mergeWorkaroundFor(target: Binding, url: string | null | undefined, text: string): Promise<{ why: string; details: string; data: Record } | null> { + const observed = target.lastSnapshot; + if (observed === null) return null; + const pull = referencedPull(target, observed, url, text); + if (pull === null) return null; + const decisions = (await loadConfig(target.projectId))?.file.bigDecisions ?? []; + const gate = assessedGate(store, target, pull, now(), decisions); + const parts = mergeWorkaroundParts({ key: pull.key, lane: gate.lane, headSha: gate.headSha, gateMet: gate.gateMet, decision: gate.decision }); + if (parts === null) return null; + return { ...parts, data: { workaround: true, gateMet: true, gateLane: gate.lane, gateDecision: gate.decision } }; + } + bb.agents.registerTool({ name: "steward_update", description: @@ -14266,7 +14318,7 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P const done: string[] = []; const notes: string[] = []; /** Close the question and record the one asked, once every check has passed. */ - const questionWrites = (closing: { question: Question; answer: string; guidanceDropped: boolean } | null, target: Binding | null): string[] => { + const questionWrites = async (closing: { question: Question; answer: string; guidanceDropped: boolean } | null, target: Binding | null): Promise => { const out: string[] = []; if (closing !== null) { const closed = store.answer(closing.question.id, closing.answer, threadId); @@ -14284,6 +14336,12 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P if (askResolution === "secret" && input.ask.variable === undefined && input.ask.setting === undefined) { throw new Error("A secret question needs the variable name (variable), or a stewards secret setting (setting)."); } + // BB-386 fix 4: the project steward's own ask to merge a + // gate-met pull request on a `project`-routed lane is a + // workaround too. Only a merge ask is marked, and the pull + // request is found by the url or by a key in the question. + const mergeAsk = target !== null && asksToMerge({ kind: null, data: {}, question: input.ask.question, choices: input.ask.choices ?? [] }); + const workaround = target === null || !mergeAsk ? null : await mergeWorkaroundFor(target, input.ask.url, input.ask.question); const q = store.ask({ projectId: projectOf!, bindingId: target?.id ?? null, @@ -14293,12 +14351,14 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P resolutionKind: askResolution, choices: input.ask.choices, url: input.ask.url ?? null, + ...(workaround === null ? {} : { why: workaround.why, details: workaround.details }), data: { ...(input.ask.variable === undefined ? {} : { variable: input.ask.variable }), ...(input.ask.purpose === undefined ? {} : { purpose: input.ask.purpose }), ...(input.ask.setting === undefined ? {} : { setting: input.ask.setting }), ...(input.ask.writeEnv === undefined ? {} : { writeEnv: input.ask.writeEnv }), ...(input.ask.worker === undefined ? {} : { workerThreadId: input.ask.worker }), + ...(workaround === null ? {} : workaround.data), }, }); out.push(`question ${q.id} recorded${target === null ? "" : ` about ${target.entityKey}`}: ask the user in your reply, and close it with steward_update { resolve: "${q.id}", answer } once they answer`); @@ -14401,7 +14461,7 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P const forBinding = [guidance, resolve, input.forward, input.recommendation, input.priority, input.hold, input.behind, input.stack, input.stewardModel, input.workerModel, input.reviewerModel, input.approve, input.quote]; if (forBinding.some((v) => v !== undefined)) return toolError(new Error("Name the binding (binding: ENG-12 or owner/repo#3) for that.")); if (closing === null && input.ask === undefined && input.lesson === undefined) return toolError(new Error("Nothing to update: name a binding, ask a question, record a lesson, or close one.")); - const written = questionWrites(closing, null); + const written = await questionWrites(closing, null); if (input.lesson !== undefined) { if (input.lesson.scope === "boundary") return toolError(new Error("A boundary lesson must name the binding it came from: pass binding (and resolve) so the owner's Review PR/Drop item has somewhere to live.")); written.push(recordLesson(null, closing?.question.escalationId ?? null)); @@ -14625,7 +14685,7 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P } } - done.push(...questionWrites(closing, target)); + done.push(...(await questionWrites(closing, target))); if (input.lesson !== undefined) done.push(recordLesson(target.id, resolving?.id ?? closing?.question.escalationId ?? null)); if (input.cites !== undefined) { // BB-35 steps 2 and 6: count the citation, and keep the lessons on @@ -14686,6 +14746,15 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P if (resolutionKind === "secret" && input.variable === undefined && input.setting === undefined) { return toolError(new Error("A secret question needs the variable name (variable), or a stewards secret setting (setting).")); } + // BB-386 fix 4: a project steward asking the owner to merge a + // pull request whose lane gate is already met and whose decide + // list routes it to the project steward is asking a workaround. + // The item still reaches the owner; it carries the marker and the + // gate's verdict so the owner sees the real state, never a made-up + // reason. Only a merge ask is marked; an unrelated question about + // the same pull request keeps its own why. + const mergeAsk = route === "user" && !approvalToUser && !prToUser && asksToMerge({ kind: forwarding.kind, data: forwarding.data, question: forwarding.question, choices: forwarding.choices }); + const workaround = mergeAsk ? await mergeWorkaroundFor(target, forwarding.url ?? input.url, forwarding.question) : null; const q = approvalToUser || prToUser || route !== "user" ? null @@ -14693,7 +14762,8 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P projectId: target.projectId, bindingId: target.id, escalationId: forwarding.id, - ...forwardedQuestionParts({ question: forwarding.question, context: forwarding.context, why: forwardWhy(input.entry ?? null) }), + ...forwardedQuestionParts({ question: forwarding.question, context: forwarding.context, why: workaround?.why ?? forwardWhy(input.entry ?? null) }), + ...(workaround === null ? {} : { details: workaround.details }), ...(forwarding.choices.length === 0 ? {} : { choices: forwarding.choices }), resolutionKind, ...(input.url === undefined ? {} : { url: input.url }), @@ -14703,6 +14773,7 @@ export function createStewardsPlugin(deps: StewardsDeps): (bb: BbPluginApi) => P ...(input.setting === undefined ? {} : { setting: input.setting }), ...(input.writeEnv === undefined ? {} : { writeEnv: input.writeEnv }), ...(input.worker === undefined ? {} : { workerThreadId: input.worker }), + ...(workaround === null ? {} : workaround.data), }, }); // BB-35 step 4: a routine decision the guidance did not settle asks