fix: pre-landing review fixes (pass 1) and the review-loop budget wording

Two blocking findings from /ship's own pass 1, both reproduced in the QA smoke before the fix:
gstack-ship-receipt carry hashed the product diff with git patch-id --stable, which strips
whitespace, so a space moved in a reviewed shell line carried as "no product change"; and it
classed package.json and every lockfile as release metadata, so a dependency swap carried too.
The patch-id is now --verbatim, package.json and VERSION are metadata only while the change is a
version stamp (lib/pregate/stamp-only.ts), lockfiles are product unless the policy names them,
the test globs name code extensions, a dirty working tree refuses before anything is compared,
and a receipt carried twice keeps the reviewed head as carry.from.

gstack-review-scope: an unresolvable base is POLICY_SOURCE_UNAVAILABLE instead of a silent
working-tree read; --range-base is validated; git runs with core.quotePath=false; range_base is
null on pass 1; a blocking finding with no path is fix; category "testing" is a test finding
below the floor; defer searches once, files nothing on a failed search and exits 0 unfiled;
summary refuses zero matching passes and the receipt write is chained to it with &&; a finding
the diff causes elsewhere names the changed line in `cause` and classify follows it.

Review-loop budget wording (ideas from tstack's sol-loop and pstack's interrogate, rewritten;
NOTICE.md): the blocker / should / nit glossary and two stop rules in Step 9.4, the checklist
and docs/review-policy.md; a lead-judgment stage in the finding merge both /review and /ship
render. The core read diffs $RANGE_BASE from pass 2 on. Caps and pins re-measured with reasons.

Step 7 coverage audit: four tests added in existing files, the --review-loop case moved to its
own test (the shared test tripped bun's 5 s default).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
garrytanandcapy-ai[bot] committed 2026-10-26 16:29:06 +00:00
1 parent 6f5782b5fd
commit c3e27fc2b8
22 files changed
+807 -153

No files matched your search

+22 -10
View File
@@ -26,6 +26,8 @@ export const HUNK_CONTEXT_LINES = 3;
export interface ScopeFinding {
fingerprint?: string; path?: string; line?: number; severity?: string; category?: string; summary?: string;
problem?: string; fix?: string; specialist?: string; advisory?: boolean; test_stub?: string;
/** The changed line that causes a defect reported elsewhere (a broken caller, a consumer of a removed export); the locus follows it. */
cause?: { path?: string; line?: number };
[key: string]: unknown;
}
export interface ScopedFinding extends ScopeFinding { locus: Locus; kind: Kind; blocking: boolean; scope: ScopeAction }
@@ -72,11 +74,17 @@ function inHunks(hunks: HunkMap, path: string, line: number | undefined, context
return ranges.some(([a, b]) => line >= a - context && line <= b + context);
}
/** Where a finding sits: in the range since the previous pass, in the branch diff, or in code the PR did not change. */
/**
* Where a finding sits: in the range since the previous pass, in the branch
* diff, or in code the PR did not change. A `cause` anchor wins over the
* reported path, so a defect the diff causes in an unchanged caller is the
* diff's.
*/
export function locusOf(finding: ScopeFinding, diffHunks: HunkMap, rangeHunks: HunkMap | null, context = HUNK_CONTEXT_LINES): Locus {
const path = typeof finding.path === 'string' ? finding.path : fingerprintPath(finding.fingerprint);
const anchor = finding.cause && typeof finding.cause === 'object' && typeof finding.cause.path === 'string' ? finding.cause : finding;
const path = typeof anchor.path === 'string' ? anchor.path : fingerprintPath(finding.fingerprint);
if (!path) return 'outside';
const line = typeof finding.line === 'number' ? finding.line : fingerprintLine(finding.fingerprint);
const line = typeof anchor.line === 'number' ? anchor.line : anchor === finding ? fingerprintLine(finding.fingerprint) : undefined;
if (rangeHunks && inHunks(rangeHunks, path, line, context)) return 'fix-range';
if (inHunks(diffHunks, path, line, context)) return 'diff';
return 'outside';
@@ -93,11 +101,13 @@ function fingerprintLine(fp: unknown): number | undefined {
return Number.isInteger(n) && n > 0 ? n : undefined;
}
/** A finding's kind: optional advice, a missing test, or a defect. */
/** The categories a reviewer uses for a test finding; `testing` is what the Testing specialist's schema emits. */
export const TEST_GAP_CATEGORIES: readonly string[] = ['testing', 'tests', 'test-gap', 'test-coverage', 'coverage', 'missing-test', 'untested'];
/** A finding's kind: optional advice, a test finding (a gap, a weak or flaky test), or a product defect. */
export function kindOf(finding: ScopeFinding): Kind {
if (finding.advisory === true) return 'advisory';
const category = String(finding.category ?? '').toLowerCase();
if (/^(test-gap|test-coverage|coverage|missing-test|untested)$/.test(category)) return 'test-gap';
if (TEST_GAP_CATEGORIES.includes(String(finding.category ?? '').toLowerCase())) return 'test-gap';
return 'defect';
}
@@ -124,9 +134,11 @@ export function scopeFindings(findings: readonly ScopeFinding[], input: ScopeInp
const kind = kindOf(finding);
const blocking = isBlocking(finding, kind);
const locus = locusOf(finding, input.diffHunks, input.pass > 1 ? input.rangeHunks : null, input.context);
// A blocking finding nobody could place cannot be filed against a path; the diff's author resolves it now.
const placed = typeof finding.path === 'string' || fingerprintPath(finding.fingerprint) !== undefined;
let scope: ScopeAction;
if (input.policy === 'all') scope = 'fix';
else if (locus === 'outside') scope = !blocking ? 'note' : input.policy === 'diff-plus-blocking' ? 'fix' : 'defer';
else if (locus === 'outside') scope = !blocking ? 'note' : input.policy === 'diff-plus-blocking' || !placed ? 'fix' : 'defer';
else if (input.pass <= 1) scope = 'fix';
else scope = blocking ? 'fix' : 'note';
return { ...finding, locus, kind, blocking, scope };
@@ -187,11 +199,11 @@ export function renderDeferredIssue(f: ScopedFinding, ctx: DeferContext): { titl
export interface DeferredRecord { fingerprint: string; path: string; severity: string; summary: string; issue: number | null; url?: string; reason?: string }
/** The PR-body section for deferred findings: references, never closing keywords, so a merge closes nothing. */
export function renderDeferredSection(deferred: readonly DeferredRecord[], noted: readonly ScopeFinding[] = [], policy: ReviewScopePolicy = 'frozen'): string {
/** The PR-body section for deferred findings: references, never closing keywords, so a merge closes nothing. Only `frozen` defers. */
export function renderDeferredSection(deferred: readonly DeferredRecord[], noted: readonly ScopeFinding[] = []): string {
const out: string[] = [];
if (deferred.length) {
out.push('## Deferred findings', '', `Blocking findings in code this PR did not change (review scope: ${policy}); filed as issues and not closed by this PR.`, '');
out.push('## Deferred findings', '', 'Blocking findings in code this PR did not change (review scope: frozen); filed as issues and not closed by this PR.', '');
for (const d of deferred) {
const ref = d.issue ? `#${d.issue}` : `unfiled${d.reason ? ` (${oneLine(d.reason)})` : ''}`;
out.push(`- Deferred: ${ref} — ${oneLine(d.severity)} \`${oneLine(d.path)}\` ${oneLine(d.summary)}`);
+40 -17
View File
@@ -10,6 +10,7 @@ import { ARTIFACT_SCHEMAS, checkSchema, type ShipReceipt, type ValidationError }
import { approvalSummary } from './approval-citations';
import { renderIssueLines } from './issue-links';
import { matchesAny } from './ship-policy';
import { stampFileKind, versionStampOnly } from './pregate/stamp-only';
export const RECEIPT_FENCE = 'gstack-ship-receipt';
const KEY_ORDER: Array<keyof ShipReceipt> = [
@@ -130,25 +131,25 @@ export function receiptSummaryLine(r: ShipReceipt): string {
/**
* Paths whose change never invalidates a /ship verdict on its own: tests (the
* reviewed product code is what the verdict covers; CI at the new head reruns
* them) and release metadata (stamps, lockfiles, the agents digest). A repo
* extends the lists through its ship policy (`stamp_files`, `stamp_paths`,
* `release_outputs`, `changelog`).
* them, unreviewed) and release metadata (the version stamp, the changelog, the
* agents digest). A repo extends the lists through its ship policy
* (`stamp_files`, `stamp_paths`, `release_outputs`, `changelog`); lockfiles are
* product unless the policy names them, because a dependency change is a
* product change. The test globs name code extensions only: an API contract
* such as `openapi.spec.yaml` is product.
*/
const TEST_CODE_EXTENSIONS = ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts', 'rb', 'py', 'go', 'rs', 'java', 'kt', 'swift', 'dart', 'php', 'cs'];
export const CARRY_TEST_GLOBS: readonly string[] = [
'test/**', 'tests/**', 'spec/**', '__tests__/**', 'e2e/**', 'cypress/**', '**/__tests__/**', '**/*.test.*', '**/*.spec.*',
'test/**', 'tests/**', 'spec/**', '__tests__/**', 'e2e/**', 'cypress/**', '**/__tests__/**',
...TEST_CODE_EXTENSIONS.flatMap(ext => [`**/*.test.${ext}`, `**/*.spec.${ext}`]),
'**/*_test.go', '**/test_*.py', '**/*_test.py', '**/*_spec.rb', '**/*Test.java', '**/*Tests.swift',
];
export const CARRY_METADATA_GLOBS: readonly string[] = [
'VERSION', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'bun.lock', 'bun.lockb', 'yarn.lock', 'pnpm-lock.yaml',
'Cargo.lock', 'Gemfile.lock', 'agents-digest/**',
];
export const CARRY_METADATA_GLOBS: readonly string[] = ['VERSION', 'CHANGELOG.md', 'package.json', 'agents-digest/**'];
export type CarryClass = 'product' | 'test' | 'metadata';
export interface CarryPlanInput {
/** The reviewed head the receipt names. */
from: string; head: string;
/** Merge base of origin/<base> with `from` and with `head`. */
fromBase: string; headBase: string;
/** Paths changed between from and head, classified. */
changed: Array<{ path: string; class: CarryClass }>;
/** Product patch-ids at both heads (empty string for no product diff). */
@@ -162,9 +163,20 @@ export interface CarryPlanInput {
export interface CarryRecord { from: string; reason: string; product_patch_id: string; changed_paths: string[]; merge_commits: number; range_diff: string; covers: string[]; reruns: string[] }
export type CarryPlan = { ok: true; carry: CarryRecord } | { ok: false; code: 'RECEIPT_CARRY_PRODUCT_CHANGED' | 'RECEIPT_CARRY_REFUSED'; message: string };
export function classifyCarryPath(rel: string, extra: { tests?: readonly string[]; metadata?: readonly string[] } = {}): CarryClass {
if (matchesAny([...CARRY_METADATA_GLOBS, ...(extra.metadata ?? [])], rel)) return 'metadata';
if (matchesAny([...CARRY_TEST_GLOBS, ...(extra.tests ?? [])], rel)) return 'test';
/**
* One changed path's carry class. A default-metadata manifest (`package.json`,
* `VERSION`) is metadata only while its from..head change is a version stamp
* and nothing else (`versionStampOnly`): a dependency, a script or a new key is
* product. `change` carries the file's text at both heads; without it the
* default lists decide (the paths a policy names are the repo's own call).
*/
export function classifyCarryPath(rel: string, extra: { metadata?: readonly string[] } = {}, change?: { before: string | null; after: string | null }): CarryClass {
if (matchesAny(extra.metadata ?? [], rel)) return 'metadata';
if (matchesAny(CARRY_METADATA_GLOBS, rel)) {
if (change && stampFileKind(rel) && !versionStampOnly(rel, change.before, change.after).stampOnly) return 'product';
return 'metadata';
}
if (matchesAny(CARRY_TEST_GLOBS, rel)) return 'test';
return 'product';
}
@@ -190,18 +202,29 @@ export function planCarry(input: CarryPlanInput): CarryPlan {
carry: {
from: input.from, reason: reasons.join(' + '), product_patch_id: input.productPatchId.head || 'none',
changed_paths: input.changed.slice(0, 50).map(c => `${c.class}:${c.path}`), merge_commits: input.mergeCommits, range_diff: input.rangeDiff,
covers: ['pre-landing review', 'adversarial review', 'gate integrity', 'documentation audit'], reruns: ['CI at head (gstack-ship-queue ready requires it)'],
covers: ['pre-landing review', 'adversarial review', 'gate integrity', 'documentation audit'],
reruns: ['CI at head (gstack-ship-queue ready requires it); test and helper code changed since the reviewed head runs there unreviewed'],
},
};
}
/** The carried receipt: the same evidence, bound to the new head, with the carry recorded. */
/**
* The carried receipt: the same evidence, bound to the new head, with the carry
* recorded. A receipt carried before keeps the reviewed head as `from` and adds
* this hop's merges and paths, so the record always names the head a review saw.
*/
export function carryReceipt(receipt: ShipReceipt, head: string, carry: CarryRecord): ShipReceipt {
return orderReceipt({ ...receipt, head, carry });
const prior = receipt.carry;
const merged: CarryRecord = !prior ? carry : {
...carry, from: prior.from, reason: prior.reason === carry.reason ? carry.reason : `${prior.reason} + ${carry.reason}`,
merge_commits: prior.merge_commits + carry.merge_commits,
changed_paths: [...prior.changed_paths, ...carry.changed_paths.filter(p => !prior.changed_paths.includes(p))].slice(0, 50),
};
return orderReceipt({ ...receipt, head, carry: merged });
}
/** The loop counters the factory scorecard reads (passes, blocking_found, deferred), as `write --review-loop` records them. */
export interface ReviewLoopReceipt { passes: number; blocking_found: number; deferred: number; noted?: number; fixed?: number; scope?: string }
export type ReviewLoopReceipt = NonNullable<ShipReceipt['review_loop']>;
export function parseReviewLoop(value: unknown): ReviewLoopReceipt | undefined {
if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
const v = value as Record<string, unknown>;