Ship policy can mark published data as content, so /ship can review large data PRs (GST-3158) (#4511)

A repo can now list published-data folders under a new
`review_content_patterns` ship-policy key, so /ship leaves `.patch`
diffs, `MANIFEST.sha256` and extension-less licences out of review,
while source files there stay reviewed.

Why: gstack-evals #352 is 13.8 MB, 13.6 MB of it published session data,
and could never pass /ship's 2 MB review limit.

Nothing to do until a repo adds the key to its base-branch policy; a
pattern that keeps too many files now stops with
`REVIEW_EXCLUDE_KEEP_TOO_LARGE` instead of being dropped.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: p1/red-team#2 reader=red-team
Review-Finding: p2full/red-team#1 reader=red-team
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-19 09:02:33 +00:00
1 parent c25390daa2
commit f13dbb0d4a
11 files changed
+340 -48

No files matched your search

+6 -1
View File
@@ -594,7 +594,12 @@ export const RELEASE_RESULT_CODES = {
REVIEW_DIFF_TOO_LARGE: {
anchor: 'review-diff-too-large',
summary: 'one reviewer\'s diff is over the 2,000,000-byte review ceiling, so /ship stopped before writing a manifest or a brief instead of handing a reader more than it can read',
fix: 'follow the fix the line prints for where the base policy stands: land the printed review_exclude_paths JSON on the base as its own PR, then bring the base into the branch and rerun once; or narrow a pattern the kept-file bound skipped; or split the PR',
fix: 'follow the fix the line prints for where the base policy stands: land the printed review_exclude_paths JSON on the base as its own PR, then bring the base into the branch and rerun once; or split the PR',
},
REVIEW_EXCLUDE_KEEP_TOO_LARGE: {
anchor: 'review-exclude-keep-too-large',
summary: 'a review_exclude_paths pattern keeps so many matched files in review that the command readers run to read them would pass 24,000 argument bytes, so gstack-review-plan stopped instead of silently dropping the pattern; the line names the pattern, the kept count, the reasons they are kept and the bytes',
fix: 'when the kept files are published data (reason code on .patch, MANIFEST.sha256 or extension-less files), land a review_content_patterns entry over them beside the pattern on the base as its own PR, then bring the base into the branch and rerun once; otherwise narrow the pattern or split the PR',
},
REVIEW_DIFF_UNREADABLE: {
anchor: 'review-diff-unreadable',
+55 -20
View File
@@ -11,7 +11,9 @@
* stable reason. Applied patterns become `:(top,exclude,glob)` pathspecs on every reader,
* and kept files under them come back through a second `:(top,literal)` command, because a
* git exclude beats any positive pathspec. That second command is bounded by its argument
* bytes: a pattern whose kept files would pass KEEP_ARG_MAX_BYTES on it is not applied.
* bytes: a pattern whose kept files would pass KEEP_ARG_MAX_BYTES on it refuses the plan
* (REVIEW_EXCLUDE_KEEP_TOO_LARGE) instead of being dropped (GST-3158). A file the base policy's
* review_content_patterns also matches is content whatever its extension, unless it is a source file (SOURCE_EXT, any case): the policy says so.
*
* A file kept only for a secret line (a line that names a credential and carries a value, secretValueLine;
* no other reason, under an applied pattern, gate scan and consumer scan both read) is also listed in `excerpt`: pass readers
@@ -29,6 +31,7 @@ import * as os from 'node:os';
import * as path from 'node:path';
import { collectLive } from './review-collect';
import { DATA_PATH, classifyPath, isAgentProse, isDataConfig, isGatePath, type PathLines } from './review-depth';
import { SOURCE_EXT } from './pregate/import-graph';
import { scan } from './redact-engine';
import { shannonEntropy } from './redact-patterns';
import { KEY_NAME, SECRET_LINE, secretPath } from './review-risk';
@@ -51,7 +54,7 @@ export type KeptReason = (typeof KEPT_REASONS)[number];
/** What the receipt records and the queue and carry compare (by `digest`, never by `source`). */
export interface ExcludeRecord {
source: string; patterns: string[]; applied: string[]; skipped: Array<{ pattern: string; kept: number; bytes: number }>; unmatched: string[];
source: string; patterns: string[]; applied: string[]; unmatched: string[];
excluded: number; excluded_bytes: number; kept: number; gate_tagged: string[]; patterns_sha256: string; list_sha256: string; digest: string;
}
export interface ActiveExclusion {
@@ -63,7 +66,7 @@ export interface ActiveExclusion {
export type Exclusion =
| { state: 'none' }
| { state: 'head-only'; patterns: string[]; source: string }
| { state: 'refused'; code: 'POLICY_SOURCE_UNAVAILABLE' | 'POLICY_INVALID' | 'REVIEW_DIFF_UNREADABLE'; lines: string[] }
| { state: 'refused'; code: 'POLICY_SOURCE_UNAVAILABLE' | 'POLICY_INVALID' | 'REVIEW_DIFF_UNREADABLE' | 'REVIEW_EXCLUDE_KEEP_TOO_LARGE'; lines: string[] }
| ActiveExclusion;
export interface ExcludeInput {
@@ -256,15 +259,44 @@ function attributeBinaryLines(i: ExcludeInput, paths: readonly string[], unread:
}
/** The kind of content a path holds when the policy may exclude it, or null for code (tests included). */
export type ContentKind = 'binary' | 'data' | 'docs' | 'log';
/** One range's input with the matched files a pattern names by their file name (its last segment, with no glob character): a config name there is data. */
type Scope = ExcludeInput & { named?: ReadonlySet<string> };
export type ContentKind = 'binary' | 'data' | 'docs' | 'log' | 'declared';
/**
* One range's input with the matched files a pattern names by their file name (its last segment, with no glob character): a
* config name there is data; and the files a review_exclude_paths and a review_content_patterns pattern both match, which
* the base policy declares content.
*/
type Scope = ExcludeInput & { named?: ReadonlySet<string>; declared?: ReadonlySet<string> };
const config = (i: Scope, p: string) => isDataConfig(p) && !i.named?.has(p);
const SOURCE = new RegExp(SOURCE_EXT.source, 'i');
function contentKind(i: Scope, p: string, binary: ReadonlySet<string>): ContentKind | null {
if (binary.has(p)) return 'binary';
if (DATA_PATH.test(p) && !config(i, p)) return 'data';
if (/\.log$/i.test(p)) return 'log';
return classifyPath(p, i.classRoot) === 'docs' ? 'docs' : null;
if (classifyPath(p, i.classRoot) === 'docs') return 'docs';
return i.declared?.has(p) && !SOURCE.test(p) ? 'declared' : null;
}
/**
* The files at the head (the index on a live tree) and at the merge base that a review_exclude_paths pattern and a
* review_content_patterns pattern both match, listed by git under the same `:(top,glob)` pathspecs; null when git cannot
* list them. Whole trees, not only the range: a declared file the branch did not change is no consumer either.
*/
function declaredContent(i: ExcludeInput, patterns: readonly string[], content: readonly string[]): Set<string> | null {
const out = new Set<string>();
if (!content.length) return out;
const empty = git(i.root, ['hash-object', '-t', 'tree', '--stdin'], '');
if (!empty.ok) return null;
const list = (rev: string, specs: readonly string[]) => {
const r = git(i.root, [...(rev ? ['diff', '--name-only', '-z', '--no-renames', empty.out.trim(), rev] : ['ls-files', '-z']), '--', ...specs.map(p => `:(top,glob)${p}`)]);
return r.ok ? new Set(r.out.split('\0').filter(Boolean)) : null;
};
for (const rev of [i.head ?? '', i.mergeBase]) {
const matched = list(rev, patterns);
const declared = list(rev, content);
if (!matched || !declared) return null;
for (const f of matched) if (declared.has(f)) out.add(f);
}
return out;
}
/**
@@ -281,7 +313,7 @@ function pathReason(i: Scope, p: string, m: Matched, binary: ReadonlySet<string>
if (m.oldMode === '100755' || m.newMode === '100755') return 'executable';
if ([m.oldMode, m.newMode].some(x => x === '120000' || x === '160000')) return 'link';
if (i.gateTagged?.has(p)) return 'gate-tagged';
if (binary.has(p)) return BINARY_CONTENT_EXT.test(p) && !native.has(p) ? null : 'code';
if (binary.has(p)) return (BINARY_CONTENT_EXT.test(p) || (i.declared?.has(p) && !SOURCE.test(p))) && !native.has(p) ? null : 'code';
if (isAgentProse(p)) return 'agent-prose';
if (config(i, p)) return 'config';
if (contentKind(i, p, binary) === null) return 'code';
@@ -364,12 +396,14 @@ export function reviewExclude(i: ExcludeInput): Exclusion {
if (!patterns.length) { const head = headPatterns(i); return head.length ? { state: 'head-only', patterns: head, source } : { state: 'none' }; }
const sel = select(i, patterns);
if ('error' in sel) return { state: 'refused', code: 'REVIEW_DIFF_UNREADABLE', lines: [`${i.context}: git could not list the files review_exclude_paths matches (${sel.error}); fix: git fetch origin ${base}, then rerun once; nothing was planned (REVIEW_DIFF_UNREADABLE)`] };
const declared = declaredContent(i, patterns, load.policy.review_content_patterns);
if (!declared) return { state: 'refused', code: 'REVIEW_DIFF_UNREADABLE', lines: [`${i.context}: git could not list the files review_content_patterns matches; fix: git fetch origin ${base}, then rerun once; nothing was planned (REVIEW_DIFF_UNREADABLE)`] };
const unread = new Set<string>();
const native = new Set<string>();
const claimed = i.perPath.filter(e => e.binary && sel.files.has(e.path)).map(e => e.path);
const binary = binaryContent(i, sel.files, new Set([...claimed, ...(bytesBinary(i, patterns) ?? sel.files.keys())]), unread, native);
const fileName = (s: string) => s.slice(s.lastIndexOf('/') + 1);
const x: Scope = { ...i, named: new Set(patterns.flatMap(q => /[*?[\\]/.test(fileName(q)) ? [] : (sel.byPattern.get(q) ?? []).filter(f => fileName(f) === fileName(q)))) };
const x: Scope = { ...i, declared, named: new Set(patterns.flatMap(q => /[*?[\\]/.test(fileName(q)) ? [] : (sel.byPattern.get(q) ?? []).filter(f => fileName(f) === fileName(q)))) };
const text = { ...x, added: { ...i.added, ...attributeBinaryLines(i, claimed.filter(p => !binary.has(p) && !unread.has(p)), unread) } };
const collected = new Map(i.perPath.map(e => [e.path, e]));
const unseen = (p: string) => { const e = collected.get(p); return !e || (!e.binary && e.lines > 0 && !(p in text.added)); };
@@ -385,14 +419,18 @@ export function reviewExclude(i: ExcludeInput): Exclusion {
}
const excerptable = new Set(i.gateTagged === null || named === null ? [] : secretOnly.filter(p => !named.has(p)));
const applied: string[] = [];
const skipped: ExcludeRecord['skipped'] = [];
const keep = new Set<string>();
for (const p of patterns) {
const hit = sel.byPattern.get(p) ?? [];
if (!hit.some(f => reasons.get(f) === null)) continue;
const kept = hit.filter(f => reasons.get(f) !== null);
const bytes = argBytes([...new Set([...keep, ...kept])].filter(f => !excerptable.has(f)));
if (bytes > KEEP_ARG_MAX_BYTES) { skipped.push({ pattern: p, kept: kept.length, bytes }); continue; }
if (bytes > KEEP_ARG_MAX_BYTES) {
const why = new Map<string, number>();
for (const f of kept) why.set(reasons.get(f)!, (why.get(reasons.get(f)!) ?? 0) + 1);
const top = [...why].sort((a, b) => b[1] - a[1]).map(([r, n]) => `${r}:${n}`).join(',');
return { state: 'refused', code: 'REVIEW_EXCLUDE_KEEP_TOO_LARGE', lines: [`${i.context}: review_exclude_paths pattern ${p} on ${source} keeps ${kept.length} matched files in review (${top}), and the command readers run to read them would need ${bytes} argument bytes (more than ${KEEP_ARG_MAX_BYTES}), so the pattern cannot be applied and is not dropped either; fix: when those files are published data, add a review_content_patterns entry for them beside the pattern on ${base} as its own PR (docs/ship-policy.md#review-content-patterns), else narrow the pattern or split the PR; nothing was planned (REVIEW_EXCLUDE_KEEP_TOO_LARGE)`] };
}
applied.push(p);
for (const f of kept) keep.add(f);
}
@@ -400,14 +438,14 @@ export function reviewExclude(i: ExcludeInput): Exclusion {
const excerpt = [...excerptable].filter(p => keep.has(p)).sort();
const keptList = [...reasons].filter(([, r]) => r !== null).map(([p, r]) => ({ path: p, reason: r! })).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
const sortedExcluded = [...excluded].sort();
const content: Record<ContentKind, number> = { binary: 0, data: 0, docs: 0, log: 0 };
const content: Record<ContentKind, number> = { binary: 0, data: 0, docs: 0, log: 0, declared: 0 };
for (const p of sortedExcluded) content[contentKind(x, p, binary)!]++;
const prefixes = [...new Set(applied.map(literalPrefix).filter(Boolean))];
const refs = grepFixed(x, prefixes, excluded, []) ?? new Map<string, Set<string>>();
const patterns_sha256 = sha256(JSON.stringify(patterns));
const list_sha256 = sha256(JSON.stringify({ applied, excluded: sortedExcluded, kept: keptList.map(k => [k.path, k.reason]) }));
const record: ExcludeRecord = {
source, patterns: [...patterns], applied, skipped, unmatched: patterns.filter(p => !(sel.byPattern.get(p) ?? []).length),
source, patterns: [...patterns], applied, unmatched: patterns.filter(p => !(sel.byPattern.get(p) ?? []).length),
excluded: excluded.size, excluded_bytes: excludedBytes(i, sortedExcluded, sel.files), kept: keptList.length,
gate_tagged: keptList.filter(k => k.reason === 'gate-tagged').map(k => k.path), patterns_sha256, list_sha256, digest: sha256(`${patterns_sha256}\n${list_sha256}`),
};
@@ -431,8 +469,7 @@ export function excludeLines(x: Exclusion, base: string): string[] {
if (x.state === 'none' || x.state === 'refused') return [];
if (x.state === 'head-only') return [`REVIEW_EXCLUDE: none (head sets review_exclude_paths; it applies after it lands on ${base}) patterns=${x.patterns.length} source=${x.source}`];
const r = x.record;
const skipped = r.skipped.length ? ` skipped=${r.skipped.map(s => `${s.pattern}:kept=${s.kept}:bytes=${s.bytes}`).join(',')} (kept files over ${KEEP_ARG_MAX_BYTES} argument bytes: pattern not applied)` : '';
const out = [`REVIEW_EXCLUDE: patterns=${r.applied.length}/${r.patterns.length} excluded=${r.excluded} bytes=${r.excluded_bytes} kept=${r.kept} content=${Object.entries(x.content).filter(([, n]) => n).map(([k, n]) => `${k}:${n}`).join(',') || 'none'} source=${r.source} digest=${r.digest}${skipped}${r.unmatched.length ? ` unmatched=${r.unmatched.join(',')}` : ''}`];
const out = [`REVIEW_EXCLUDE: patterns=${r.applied.length}/${r.patterns.length} excluded=${r.excluded} bytes=${r.excluded_bytes} kept=${r.kept} content=${Object.entries(x.content).filter(([, n]) => n).map(([k, n]) => `${k}:${n}`).join(',') || 'none'} source=${r.source} digest=${r.digest}${r.unmatched.length ? ` unmatched=${r.unmatched.join(',')}` : ''}`];
for (const k of x.kept.slice(0, 20)) out.push(`REVIEW_EXCLUDE_KEPT: ${k.reason} ${k.path}`);
if (x.kept.length > 20) out.push(`REVIEW_EXCLUDE_KEPT: +${x.kept.length - 20} more (gstack-review-plan --json lists every kept file)`);
if (x.excerpt.length) out.push(`REVIEW_EXCLUDE_EXCERPT: ${x.excerpt.length} kept files hold no keep reason but a secret line; gstack-review-dispatch pass gives readers their matched lines in context, not the whole files, and DIFF_KEEP leaves them out`);
@@ -507,7 +544,7 @@ export function readSelection(root: string, diffBase: string, pathspecs: readonl
export const redact = (s: string) => s.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s'"]+/gi, '<url>').replace(/\b[\w.-]+@[\w.-]+:[^\s'"]+/g, '<url>');
/** Where the over-ceiling selection's policy stands: decides the fix the line prints. */
export interface CeilingContext { state: 'none' | 'head-only' | 'active'; base: string; source: string; floor?: string | null; headPatterns?: string[]; record?: Pick<ExcludeRecord, 'patterns' | 'skipped' | 'excluded'> }
export interface CeilingContext { state: 'none' | 'head-only' | 'active'; base: string; source: string; floor?: string | null; headPatterns?: string[]; record?: Pick<ExcludeRecord, 'patterns' | 'excluded'> }
/** The policy hunk to land, as JSON a person can paste: the patterns, and a floor at least this key's version. */
function policyJson(patterns: readonly string[], floor?: string | null): string {
@@ -533,9 +570,7 @@ export function tooLargeLine(context: string, reader: string, d: { bytes: number
const top = d.byDir.slice(0, 5).map(([dir, n]) => `${dir}:${n}`).join(',') || 'none';
const land = (patterns: readonly string[]) => `ask the repo owner to land ${policyJson(patterns, c.floor)} in ${SHIP_POLICY_PATH} on ${c.base} as its own PR (docs/ship-policy.md#review-exclude-paths), then bring ${c.base} into this branch and rerun once; if it is still over, split the PR`;
const dirs = suggest(d.byDir, d.bytes);
const s = c.record?.skipped[0];
const fix = c.state === 'head-only' ? `this branch declares review_exclude_paths, but only the copy on ${c.base} applies: ${land(c.headPatterns ?? [])}`
: s ? `pattern ${s.pattern} was not applied: its ${s.kept} kept files need ${s.bytes} argument bytes (more than ${KEEP_ARG_MAX_BYTES}); narrow the pattern on ${c.base} or move the kept files out of it, or split the PR`
: c.state === 'active' ? `still over after excluding ${c.record?.excluded ?? 0} files; ${dirs.length ? land([...(c.record?.patterns ?? []), ...dirs.filter(p => !c.record?.patterns.includes(p))]) : 'split the PR'}`
: dirs.length ? land(dirs) : 'split the PR';
const line = `${context}: the reader's diff is over the review ceiling (reader=${reader} bytes=${d.bytes} max=${REVIEW_DIFF_MAX_BYTES} top=${top} policy=${c.source}); fix: ${fix}; nothing was written (REVIEW_DIFF_TOO_LARGE)`;
@@ -554,7 +589,7 @@ export function unreadableLine(context: string, reader: string, d: Extract<Reade
}
/** The plan's review_exclude object (gstack-review-plan --json), or null for a repository without the key. */
export type PlanExclude = { state: string; patterns?: string[]; skipped?: ExcludeRecord['skipped']; excluded?: number } | null;
export type PlanExclude = { state: string; patterns?: string[]; excluded?: number } | null;
/**
* Where <base>'s policy stands for a REVIEW_DIFF_TOO_LARGE fix: the source commit, its min_gstack_version, and the exclusion
@@ -576,5 +611,5 @@ export function ceilingContext(root: string, base: string, known?: PlanExclude):
const floor = read?.policy.min_gstack_version ?? null;
if (!x) return { state: 'none', base: b, source, floor };
if (x.state === 'head-only') return { state: 'head-only', base: b, source, floor, headPatterns: x.patterns ?? [] };
return { state: 'active', base: b, source, floor, record: { patterns: x.patterns ?? [], skipped: x.skipped ?? [], excluded: x.excluded ?? 0 } };
return { state: 'active', base: b, source, floor, record: { patterns: x.patterns ?? [], excluded: x.excluded ?? 0 } };
}
+2 -1
View File
@@ -57,6 +57,7 @@ export const LAND_DOCS_ONLY_SKIP_KEY_VERSION = '1.99.0.0';
/** `history: no-rewrite` and `land.merge_commit_paths` are a value and a field of older keys, checked by value like bump: never. */
export const HISTORY_NO_REWRITE_KEY_VERSION = '1.100.0.0';
export const LAND_MERGE_COMMIT_PATHS_KEY_VERSION = '1.100.0.0';
export const REVIEW_CONTENT_KEY_VERSION = '1.102.0.0';
export const POLICY_KEY_INTRODUCED: Record<PolicyKey, string> = {
bump: '1.91.73.0', queue_mode: '1.91.73.0', release_tool: '1.91.73.0', release_outputs: '1.91.73.0', stamp_paths: '1.91.73.0',
changelog: '1.91.73.0', mirror: '1.91.73.0', history: '1.91.73.0', preregistration_shas: '1.91.73.0', stamp_sensitive_gates: '1.91.73.0',
@@ -64,7 +65,7 @@ export const POLICY_KEY_INTRODUCED: Record<PolicyKey, string> = {
migrations: '1.91.98.0', gate_command: SHIP_QUEUE_KEYS_VERSION, full_e2e: SHIP_QUEUE_KEYS_VERSION, min_gstack_version: SHIP_QUEUE_KEYS_VERSION,
train: TRAIN_KEYS_VERSION, review_scope: REVIEW_SCOPE_KEY_VERSION, docs: DOCS_CAPS_KEY_VERSION,
changelog_fragments: CHANGELOG_FRAGMENTS_KEY_VERSION,
base_red: BASE_RED_KEY_VERSION, review_exclude_paths: REVIEW_EXCLUDE_KEY_VERSION, review: REVIEW_POLICY_KEY_VERSION, release_gate: RELEASE_GATE_KEY_VERSION,
base_red: BASE_RED_KEY_VERSION, review_exclude_paths: REVIEW_EXCLUDE_KEY_VERSION, review_content_patterns: REVIEW_CONTENT_KEY_VERSION, review: REVIEW_POLICY_KEY_VERSION, release_gate: RELEASE_GATE_KEY_VERSION,
stamp_placeholders: STAMP_PLACEHOLDERS_KEY_VERSION, merge: MERGE_KEY_VERSION, land: LAND_KEY_VERSION, readers: READERS_KEY_VERSION,
bookkeeping: BOOKKEEPING_KEY_VERSION, mechanical_retake: MECHANICAL_RETAKE_KEY_VERSION, test_code: TEST_CODE_KEY_VERSION, ci_record_timeout_s: CI_RECORD_TIMEOUT_KEY_VERSION,
plan_record: PLAN_RECORD_KEY_VERSION, docs_only: DOCS_ONLY_KEY_VERSION,
+12 -6
View File
@@ -66,6 +66,8 @@ export interface ShipPolicy {
review_scope: ReviewScope;
/** Git glob pathspecs (root-anchored) whose data, docs, binary and log files /ship's reviewers leave out; read from the base only (docs/ship-policy.md#review-exclude-paths). */
review_exclude_paths: string[];
/** Git glob pathspecs (root-anchored) that mark files review_exclude_paths also matches as content, whatever their extension; read from the base only (docs/ship-policy.md#review-content-patterns). */
review_content_patterns: string[];
/** How much review /ship runs (docs/review-policy.md#review-depth): the panel fallback, the risk reader's model, platform review and extra risk paths; read from the base only. */ review: ReviewPolicy;
/** What /ship's readers may not fetch or open beyond the default fetch rule, and the one-line note every brief carries; the base governs, the head may only add (docs/ship-policy.md#readers). */ readers: ReadersPolicy;
/** Consumed by the plan reviews (D1). */
@@ -181,6 +183,7 @@ export const DEFAULT_POLICY: ShipPolicy = {
stamp_sensitive_gates: [],
review_scope: 'frozen',
review_exclude_paths: [],
review_content_patterns: [],
review: { panel: 'all', reader_model: 'lane', platform: 'off', risk_paths: [] },
pr_count: { default_pr_count: 1, split_requires_owner: true },
maintainers: [],
@@ -217,6 +220,7 @@ export const POLICY_EXPLANATIONS: Record<PolicyKey, string> = {
stamp_sensitive_gates: 'Evidence labels (gstack-evidence --label) that read VERSION or generated bytes; the tree receipt never marks them reusable.',
review_scope: 'frozen | diff-plus-blocking | all. frozen (default): /ship Step 9 fixes findings in the diff on pass 1, files blocking findings in code the PR did not change as issues, and later passes read only the range since the previous pass and fix only blocking findings; diff-plus-blocking: the same, but a blocking finding in code the PR did not change is fixed in this PR instead of filed; all: every finding is fixed now (the pre-1.91.249 loop).',
review_exclude_paths: 'Git glob pathspecs, root-anchored and case-sensitive (`receipts/**`, `**/*.jsonl`; at most 64, 256 characters each, no leading `:` or `!`): /ship\'s reviewers leave out the data, docs, binary and .log files they match. Read from the base branch only, so a branch cannot exclude its own files. Code, gate paths, agent prose, config, executables, .gstack/ and .github/ files, gate-tagged or secret-bearing files and files a kept code or test file names by full path stay reviewed (docs/ship-policy.md#review-exclude-paths).',
review_content_patterns: 'Git glob pathspecs in the same dialect as review_exclude_paths (`results/*/raw/**`): a file both keys match is content, so the exclusion leaves it out whatever its extension (.patch files, MANIFEST.sha256, extension-less licence texts). Explicit policy only: nothing is inferred, and a pattern here with no review_exclude_paths pattern over the same files excludes nothing. Read from the base branch only. Gate paths, agent prose, config, source files (.ts, .py, .sh and the like), executables, links, native binaries, .gstack/ and .github/ files, gate-tagged or secret-bearing files and files a kept code or test file names by full path stay reviewed (docs/ship-policy.md#review-content-patterns).',
review: '{ panel?, reader_model?, platform?, risk_paths? }, read from the base branch only. panel: all (default: today\'s panel and loop everywhere) | risk (opt-in: today\'s panel at full depth on risk class, one reader on the rest) | off (one merged reader on risk class too); risk and off run one fix round. Their one-reader shape has not passed a no-loss replay yet (GSTA-258 C: FIX-METHOD). reader_model: the model of the one reader a lean depth runs, `lane` (default: the lane\'s own model, the native adversarial reader), `cross-family` or a model id. platform: off (default) | on: a docs or tests diff with no numeric, results or prereg claims whose PR carries the platform review (capy-ai[bot]) at the exact head skips /ship\'s readers (review_depth platform); never runtime code. risk_paths: globs of code paths that are risk class on top of R51\'s; data, docs and binary files under them stay out (docs/review-policy.md#review-depth).',
readers: READERS_EXPLANATION,
pr_count: '{ default_pr_count, split_requires_owner }: the PR-count row in plan reviews.',
@@ -328,13 +332,13 @@ function listErrors(key: string, value: unknown, out: PolicyError[], check: (ite
});
}
/** `review_exclude_paths`: git glob pathspecs, each one repo-relative line with no pathspec magic of its own; every error is POLICY_INVALID at its index. */
function excludeErrors(value: unknown, out: PolicyError[]): void {
if (!Array.isArray(value)) { out.push({ code: 'POLICY_INVALID', path: 'review_exclude_paths', message: 'must be an array of git glob pathspecs' }); return; }
if (value.length > MAX_LIST) out.push({ code: 'POLICY_INVALID', path: 'review_exclude_paths', message: `more than ${MAX_LIST} patterns` });
/** `review_exclude_paths` and `review_content_patterns`: git glob pathspecs, each one repo-relative line with no pathspec magic of its own; every error is POLICY_INVALID at its index. */
function excludeErrors(key: 'review_exclude_paths' | 'review_content_patterns', value: unknown, out: PolicyError[]): void {
if (!Array.isArray(value)) { out.push({ code: 'POLICY_INVALID', path: key, message: 'must be an array of git glob pathspecs' }); return; }
if (value.length > MAX_LIST) out.push({ code: 'POLICY_INVALID', path: key, message: `more than ${MAX_LIST} patterns` });
value.forEach((p, i) => {
const why = typeof p !== 'string' ? 'must be a string' : containedRelative(p) ?? (/^[:!]/.test(p) ? 'must not start with : or ! (no pathspec magic or negation)' : /[\x00-\x1f\x7f]/.test(p) ? 'contains a control character' : p.replace(/\/+$/, '') === '' || p === '.' ? 'must not name the whole repository' : null);
if (why) out.push({ code: 'POLICY_INVALID', path: `review_exclude_paths[${i}]`, message: `${JSON.stringify(p)} ${why}` });
if (why) out.push({ code: 'POLICY_INVALID', path: `${key}[${i}]`, message: `${JSON.stringify(p)} ${why}` });
});
}
@@ -473,7 +477,8 @@ export function validatePolicy(raw: unknown, opts: { gstackVersion?: string } =
oneOf('history', ['merge-only', 'squash-ok', 'no-rewrite']);
oneOf('review_scope', ['frozen', 'diff-plus-blocking', 'all']);
oneOf('merge', ['direct', 'train']);
if ('review_exclude_paths' in obj) excludeErrors(obj.review_exclude_paths, errors);
if ('review_exclude_paths' in obj) excludeErrors('review_exclude_paths', obj.review_exclude_paths, errors);
if ('review_content_patterns' in obj) excludeErrors('review_content_patterns', obj.review_content_patterns, errors);
if ('review' in obj) reviewErrors(obj.review, errors, (k, v) => listErrors(k, v, errors, globError));
if ('readers' in obj) readersErrors(obj.readers, errors, containedRelative);
if ('release_tool' in obj && obj.release_tool !== null) {
@@ -762,6 +767,7 @@ export function shipConsequences(policy: ShipPolicy, base: string): string[] {
? 'review_scope diff-plus-blocking: Step 9.4 runs `gstack-review-scope classify --policy diff-plus-blocking` each pass; pass 1 fixes the diff and every blocking finding, in unchanged code too, later passes read only the range since the previous pass and fix only blocking findings; notes go to the PR body'
: 'review_scope frozen: Step 9.4 runs `gstack-review-scope classify` each pass; pass 1 fixes the diff and defers blocking findings in unchanged code to the PR body, later passes read only the range since the previous pass and fix only blocking findings; notes go to the PR body');
if (policy.review_exclude_paths.length) out.push(`review_exclude_paths ${policy.review_exclude_paths.join(' ')}: Step 9's reviewers leave out the data, docs, binary and .log files these git globs match on this branch; gstack-review-plan prints REVIEW_EXCLUDE: with the counts and the kept files, and every brief names what was left out (docs/ship-policy.md#review-exclude-paths)`);
if (policy.review_exclude_paths.length && policy.review_content_patterns.length) out.push(`review_content_patterns ${policy.review_content_patterns.join(' ')}: files these globs and review_exclude_paths both match count as content whatever their extension, so Step 9's reviewers leave them out too (docs/ship-policy.md#review-content-patterns)`);
if (policy.preregistration_shas.length) out.push(`preregistration: \`gstack-evidence ancestor --from-policy --base ${base}\` must print only ANCESTOR: ok before push; the ship receipt records the result`);
if (policy.release_tool) out.push(`release_tool: \`${policy.release_tool}\` runs only inside gstack-restamp (staging worktree, outputs confined to release_outputs)`);
return out;