Repository navigation
feat(review): add a --topology minimal single-pass A/B arm #9919
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 1 commit
395a1fc
0817a7c
c793f2d
cba3a29
dafe7a1
dc5a5cf
2fa7756
7e7f14a
11cf00c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -39,6 +39,20 @@ export type ReviewEffort = 'low' | 'medium' | 'high'; | |
| */ | ||
| export type ReviewSeverityFloor = 'critical' | 'suggestion'; | ||
|
|
||
| /** | ||
| * The review topology: which shape the run takes. `auto` is the standing | ||
| * effort-driven pipeline (the 3A/3B/3C fan-outs). `minimal` is the A/B | ||
| * comparison arm from issue #9783 — a single careful senior-engineer pass | ||
| * over the diff in the orchestrator's own context, at most fifteen findings, | ||
| * each carrying a concrete failure scenario; no subagent fan-out, no | ||
| * verification, no reverse audit, no posting. It exists so the full pipeline | ||
| * and the minimal prompt can be run over the same PR set and compared per | ||
| * model. It is deliberately orthogonal to `effort` — it is a different | ||
| * _shape_ of review, not a depth of the same one — and selecting it skips the | ||
| * agent machinery (roster, coverage, budget) entirely rather than shrinking it. | ||
| */ | ||
| export type ReviewTopology = 'auto' | 'minimal'; | ||
|
|
||
| export type ReviewTarget = | ||
| | { type: 'pr-number'; number: number } | ||
| | { | ||
|
|
@@ -111,6 +125,13 @@ export interface ParsedReviewArgs { | |
| */ | ||
| severityFloor: ReviewSeverityFloor | 'auto'; | ||
| severityFloorSource: 'explicit' | 'configured' | 'default'; | ||
| /** | ||
| * The review topology. `auto` (the default) runs the standing effort-driven | ||
| * pipeline; `minimal` runs the single-pass A/B arm and, because it neither | ||
| * posts nor edits, forces `comment.effective` and `fix.effective` to false. | ||
| */ | ||
| topology: ReviewTopology; | ||
| topologySource: 'explicit' | 'default'; | ||
| /** The `--host` flag's value, when present — recorded verbatim so the | ||
| * write gate can bind a recorded bare-number target's platform (the | ||
| * target itself carries no host in that spelling). */ | ||
|
|
@@ -156,6 +177,14 @@ export const SEVERITY_FLOORS: ReadonlySet<string> = new Set([ | |
| 'auto', | ||
| ]); | ||
|
|
||
| export const TOPOLOGIES: ReadonlySet<string> = new Set([ | ||
| 'minimal', | ||
| // `auto` is a legal EXPLICIT value for the same reason it is for | ||
| // `--severity-floor`: typing `--topology auto` means "the standing | ||
| // effort-driven pipeline", not a typo to reject. | ||
| 'auto', | ||
| ]); | ||
|
|
||
| // The verdict's owner/repo/number are interpolated into `gh` commands by the | ||
| // caller, so they must be established trustworthily, not merely extracted: | ||
| // the scheme is case-insensitive, the number must END at the path segment | ||
|
|
@@ -202,6 +231,11 @@ function asSeverityFloor(value: string): ReviewSeverityFloor | 'auto' | null { | |
| : null; | ||
| } | ||
|
|
||
| function asTopology(value: string): ReviewTopology | null { | ||
| const lower = value.toLowerCase(); | ||
| return TOPOLOGIES.has(lower) ? (lower as ReviewTopology) : null; | ||
| } | ||
|
|
||
| /** | ||
| * Single-dash tokens count as flags too: `-c` is never a plausible review | ||
| * target, and classifying it as a file path demoted the real target the | ||
|
|
@@ -336,6 +370,7 @@ export function parseReviewArgs( | |
| let resumeRequested = false; | ||
| let explicitEffort: ReviewEffort | null = null; | ||
| let explicitFloor: ReviewSeverityFloor | 'auto' | null = null; | ||
| let explicitTopology: ReviewTopology | null = null; | ||
| let recordedHostFlag: string | undefined; | ||
|
|
||
| // The configured default gets the same validation as an explicit flag: | ||
|
|
@@ -384,6 +419,8 @@ export function parseReviewArgs( | |
| // deferred-warning problem; its issues are a separate list because its | ||
| // resolution sentence is its own. | ||
| const floorIssues: EffortIssue[] = []; | ||
| // `--topology` shares the value-token grammar too, for the same reason. | ||
| const topologyIssues: EffortIssue[] = []; | ||
|
|
||
| // First pass: pull out flags (and each value-taking flag's value token, | ||
| // when the spaced form legitimately consumes one). Non-flag tokens are kept | ||
|
|
@@ -392,7 +429,7 @@ export function parseReviewArgs( | |
| interface Kept { | ||
| token: string; | ||
| /** Set when this token arrived as an invalid value of the named flag. */ | ||
| invalidValueOf?: '--effort' | '--severity-floor'; | ||
| invalidValueOf?: '--effort' | '--severity-floor' | '--topology'; | ||
| } | ||
| const kept: Kept[] = []; | ||
|
|
||
|
|
@@ -510,6 +547,40 @@ export function parseReviewArgs( | |
| continue; | ||
| } | ||
|
|
||
| if (token === '--topology' || token.startsWith('--topology=')) { | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Deferred to the next round. The extraction is the right fix, but it is this batch's largest change — ~90 lines of churn across three hardened copies of the value-token grammar that carry four documented grammar-fix rounds — and this round already carries the Critical (R1-10) plus seven other findings, at the ~8-finding batch bound. De-risking for it landed this round: the three 中文说明延至下一轮处理。抽取助手函数是正确的修复方向,但它是本批中最大的改动——约 90 行的改动横跨值-令牌语法的三份已加固拷贝(各有四份有据可查的语法修复记录)——而本轮已承载 Critical(R1-10)加另外七条发现,达到每轮约 8 条的批次上限。本轮已为其提前降低风险:原先没有证据的三个 |
||
| if (token.includes('=')) { | ||
| const value = token.slice(token.indexOf('=') + 1); | ||
| const topologyValue = asTopology(value); | ||
| if (topologyValue !== null) { | ||
| explicitTopology = topologyValue; | ||
| } else if (value !== '' && isPrShapedToken(value)) { | ||
| kept.push({ token: value, invalidValueOf: '--topology' }); | ||
| } else { | ||
| topologyIssues.push({ kind: 'invalid-eq', value }); | ||
| } | ||
| continue; | ||
| } | ||
| const next = i + 1 < tokens.length ? tokens[i + 1] : undefined; | ||
| const nextTopology = next !== undefined ? asTopology(next) : null; | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Deferred to the next round, not declined — this round ran under a budget warning and was scoped to the two Critical findings only. The finding is acknowledged as real (with its corrected note that the 中文说明推迟到下一轮,并非拒绝——本轮在预算警告下运行,范围被限定为仅处理两条 Critical 发现。该发现被承认为真实(包括其修正说明: |
||
| if (nextTopology !== null) { | ||
| explicitTopology = nextTopology; | ||
| i++; | ||
| continue; | ||
| } | ||
| if (next === '') { | ||
| topologyIssues.push({ kind: 'missing' }); | ||
| i++; | ||
| continue; | ||
| } | ||
| if (next === undefined || isFlag(next)) { | ||
| topologyIssues.push({ kind: 'missing' }); | ||
| continue; | ||
| } | ||
| kept.push({ token: next, invalidValueOf: '--topology' }); | ||
| i++; | ||
| continue; | ||
| } | ||
|
|
||
| if (isFlag(token)) { | ||
| unknownFlags.push(token); | ||
| warnings.push(`Unrecognized flag ${JSON.stringify(token)}; ignored.`); | ||
|
|
@@ -652,7 +723,12 @@ export function parseReviewArgs( | |
| : undefined; | ||
| let rescuedPr = false; | ||
| for (const k of kept) { | ||
| const issues = k.invalidValueOf === '--effort' ? effortIssues : floorIssues; | ||
| const issues = | ||
| k.invalidValueOf === '--effort' | ||
| ? effortIssues | ||
| : k.invalidValueOf === '--severity-floor' | ||
| ? floorIssues | ||
| : topologyIssues; | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Deferred to the next round, not declined — this round ran under a budget warning and was scoped to the two Critical findings only. The finding is acknowledged as real: the rescue loop's flag→issue-list ternary ends in an 中文说明推迟到下一轮,并非拒绝——本轮在预算警告下运行,范围被限定为仅处理两条 Critical 发现。该发现被承认为真实:救援循环里 flag→issue 列表的三元链以 |
||
| if (k.invalidValueOf !== undefined) { | ||
| const survives = isPrShaped(k.token) | ||
| ? !hasValidCandidate && distinctPr.size === 1 | ||
|
|
@@ -732,12 +808,30 @@ export function parseReviewArgs( | |
|
|
||
| const isPr = target.type === 'pr-number' || target.type === 'pr-url'; | ||
|
|
||
| // The topology resolves like the effort — an explicit flag beats the | ||
| // standing `auto` default. There is no configured (settings) topology: the | ||
| // minimal arm is an explicit A/B comparison, never a background default. | ||
| const topology: ReviewTopology = explicitTopology ?? 'auto'; | ||
| const topologySource: ParsedReviewArgs['topologySource'] = | ||
| explicitTopology !== null ? 'explicit' : 'default'; | ||
| // The minimal arm is terminal-only — it neither posts to a PR nor edits a | ||
| // working tree — so both write operations are gated off it. This keeps the | ||
| // guarantee in code rather than in whichever prose the orchestrator reads. | ||
| const isMinimal = topology === 'minimal'; | ||
|
|
||
| const commentRequested = commentRequestedByFlag || defaults.comment === true; | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Deferred to the next round, not declined — this round ran under a budget warning and was scoped to the two Critical findings only. The finding is acknowledged as real: no test crosses a settings-provided 中文说明推迟到下一轮,并非拒绝——本轮在预算警告下运行,范围被限定为仅处理两条 Critical 发现。该发现被承认为真实:没有任何测试把设置提供的 |
||
| const commentEffective = commentRequested && isPr; | ||
| const commentEffective = commentRequested && isPr && !isMinimal; | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Deferred to the next round, not declined — this round ran under a budget warning and was scoped to the two Critical findings only. The finding is acknowledged as real: the write-authorization refusal 中文说明推迟到下一轮,并非拒绝——本轮在预算警告下运行,范围被限定为仅处理两条 Critical 发现。该发现被承认为真实: |
||
| if (commentRequestedByFlag && !isPr) { | ||
| warnings.push( | ||
| 'Warning: `--comment` flag is ignored because the review target is not a PR.', | ||
| ); | ||
| } else if (commentRequested && isPr && isMinimal) { | ||
| // Only when minimal is THE reason a would-be-effective comment is | ||
|
Comment on lines
+853
to
+854
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Deferred to the next round, not declined — this round ran under a budget warning (the previous round exhausted its time budget) and was scoped to the two Critical findings only. The finding is acknowledged as real: the minimal-topology comment warning fires on 中文说明推迟到下一轮,并非拒绝——本轮在预算警告下运行(上一轮耗尽了时间预算),范围被限定为仅处理两条 Critical 发现。该发现被承认为真实:minimal 拓扑的 comment 警告基于 |
||
| // suppressed: on a non-PR target the comment does not apply anyway, and | ||
| // that case keeps its usual handling above. | ||
| warnings.push( | ||
| 'Warning: `--comment` is ignored because `--topology minimal` is terminal-only — the minimal arm posts nothing.', | ||
| ); | ||
| } | ||
|
|
||
| const resumeEffective = resumeRequested && isPr; | ||
|
|
@@ -750,13 +844,17 @@ export function parseReviewArgs( | |
| // `--fix` edits a working tree, so it needs one that outlives the review. A | ||
| // PR review's tree is the ephemeral worktree Step 9 removes; a `local` or | ||
| // `file` review's tree is the user's own checkout. | ||
| const fixEffective = fixRequested && !isPr; | ||
| const fixEffective = fixRequested && !isPr && !isMinimal; | ||
| if (fixRequested && isPr) { | ||
| warnings.push( | ||
| 'Warning: `--fix` flag is ignored because a PR review runs in an ephemeral ' + | ||
| 'worktree that is deleted when the review ends — there is no durable tree to ' + | ||
| 'fix. Use `--comment` to publish the findings instead.', | ||
| ); | ||
| } else if (fixRequested && isMinimal) { | ||
| warnings.push( | ||
| 'Warning: `--fix` is ignored because `--topology minimal` is terminal-only — the minimal arm edits nothing.', | ||
| ); | ||
| } | ||
|
|
||
| let effort: ReviewEffort; | ||
|
|
@@ -900,6 +998,37 @@ export function parseReviewArgs( | |
| ); | ||
| } | ||
|
|
||
| // The topology's deferred warnings, composed now that the resolution is | ||
| // final — the same shape as the effort's and the floor's. | ||
| const topologyResolution = | ||
| topologySource === 'explicit' | ||
| ? `--topology ${topology} (the last valid occurrence) is in effect` | ||
| : 'using the default topology (auto)'; | ||
| for (const issue of topologyIssues) { | ||
| switch (issue.kind) { | ||
| case 'invalid-eq': | ||
| warnings.push( | ||
| `Invalid --topology value ${JSON.stringify(issue.value)}; ${topologyResolution}.`, | ||
| ); | ||
| break; | ||
| case 'missing': | ||
| warnings.push(`--topology requires a value; ${topologyResolution}.`); | ||
| break; | ||
| case 'discarded': | ||
| warnings.push( | ||
| `Invalid --topology value ${JSON.stringify(issue.value)} discarded; ${topologyResolution}.`, | ||
| ); | ||
| break; | ||
| case 'kept-as-target': | ||
| warnings.push( | ||
| `Invalid --topology value ${JSON.stringify(issue.value)}; treating it as the review target — ${topologyResolution}.`, | ||
| ); | ||
| break; | ||
| default: | ||
| break; | ||
| } | ||
| } | ||
|
|
||
| return { | ||
| target, | ||
| effort, | ||
|
|
@@ -908,6 +1037,8 @@ export function parseReviewArgs( | |
| fix: { requested: fixRequested, effective: fixEffective }, | ||
| severityFloor, | ||
| severityFloorSource, | ||
| topology, | ||
| topologySource, | ||
| ...(recordedHostFlag !== undefined ? { host: recordedHostFlag } : {}), | ||
| resume: { requested: resumeRequested, effective: resumeEffective }, | ||
| extraTokens, | ||
|
|
@@ -954,7 +1085,7 @@ function reviewDefaultsFromSettings(): { | |
| export const parseArgsCommand: CommandModule = { | ||
| command: 'parse-args [raw]', | ||
| describe: | ||
| 'Parse the /review skill argument string (--comment, --fix, --resume, --effort, --severity-floor, target disambiguation) and emit the verdict as JSON; pass the string on stdin via --stdin (a positional that begins with a dash never reaches this handler — yargs rejects it as an unknown flag)', | ||
| 'Parse the /review skill argument string (--comment, --fix, --resume, --effort, --severity-floor, --topology, target disambiguation) and emit the verdict as JSON; pass the string on stdin via --stdin (a positional that begins with a dash never reaches this handler — yargs rejects it as an unknown flag)', | ||
| builder: (yargs) => | ||
| yargs | ||
| .positional('raw', { | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -690,6 +690,8 @@ The countermeasure is cheap and needs no new machinery: before Step 4, sanity-ch | |
|
|
||
| ## LLM call budget | ||
|
|
||
| **`--topology minimal` — 0 subagent calls.** The minimal arm (issue #9783, Step 3M) is a single careful pass over the diff in the orchestrator's own context — no fan-out, no verification, no reverse audit, no build/test. It costs one model turn, the same shape as the low tier's inline pass, and it is priced here for completeness, not as a recommended default: it exists so the full pipeline and this minimal prompt can be run over the same PR set and compared per model. This section tracks per-topology _cost_; the A/B the minimal arm enables extends it with per-model _quality_, which is what decides whether any cell of a future model-family × effort routing table routes away from the full pipeline. Until that data exists, every review runs the topology below. | ||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Deferred to the next round, not declined — this round ran under a budget warning and was scoped to the two Critical findings only. The finding is acknowledged as real: the minimal arm shares all three properties the prose reserves for low, but 中文说明推迟到下一轮,并非拒绝——本轮在预算警告下运行,范围被限定为仅处理两条 Critical 发现。该发现被承认为真实:minimal 臂具备文案保留给 low 的全部三个属性,但 |
||
|
|
||
| **Small diffs (≤ 500 source lines AND ≤ 3200 total diff lines, Step 3A, high effort) — 17-28 calls (typically 17-19):** | ||
|
|
||
| | Stage | Calls | Why | | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Deferred to the next round, not declined — this round ran under a budget warning and was scoped to the two Critical findings only, and this one is a refactor (~34-line grammar extraction across three flags plus unifying three deferred-warning switches). The finding is acknowledged as real:
--topologyis a near-verbatim third copy of the value-token grammar, and the module's own comments record grammar bug-fixes that had to be replicated across every copy. The extraction into one shared helper +composeIssueWarningsis queued for the next round, where it can get its own verification pass.中文说明
推迟到下一轮,并非拒绝——本轮在预算警告下运行,范围被限定为仅处理两条 Critical 发现,而本条是一次重构(跨三个 flag 提取约 34 行的值 token 语法,并统一三个延迟警告 switch)。该发现被承认为真实:
--topology是值 token 语法的第三份近乎逐字的拷贝,模块自身的注释也记录了每次语法修复都必须在所有拷贝中复制的历史。抽成一个共享助手函数 +composeIssueWarnings已排入下一轮,届时可以有自己独立的验证过程。