* enhance(#4261): report size-cap headroom on every run, with a reserved margin The tier caps are red lines and none of them moves here. What was missing is everything below the red line: a passing run said nothing, so a contributor at 99.6% of a cap and one at 60% got identical feedback, and the density that produces merge-time collisions was invisible to the people creating it. Two levels, matching the shape execute-phase.md already carries by hand (a hard ceiling plus a lower margin "so minor future edits don't re-trip the gate") and which was until now the only capped file with one: 1. a headroom census printed every run, green included, sorted least-headroom-first, and appended to the GitHub job summary 2. a 95% reserved margin that names the files inside it and REPORTS rather than fails The margin deliberately does not fail. A cap breach is a red line; a file at 96% is not broken, it is a file whose next contributor should extract before adding. Failing there would create a second red line and force exactly the +N bumps the policy forbids. Neither level asserts a count, so this adds no snapshot to regenerate — the per-file size baseline was deleted by #2724 for conflicting on 7 of 7 PRs that touched it. Also deletes rather than refreshes the per-tier high-water comments in both guard files. They were measured once and then diverged from the tree: the LARGE line still claimed "gsd-executor 42,342 -> ~6.8 KB headroom" while the real high-water sat at 99.6% of that cap, so the comment documenting the margin was itself why nobody noticed the margin was gone. As measured on next by the new census, the pressure has grown since the issue was filed: gsd-plan-checker.md has 9 bytes of headroom, gsd-verifier.md 21, and plan-phase.md 14. * chore(#4261): add changeset for the size-cap headroom census * test(#4261): exercise reserved-margin boundaries --------- Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
This commit is contained in:
@@ -79,7 +79,17 @@ const assert = require('node:assert/strict');
|
||||
const fs = require('fs');
|
||||
const os = require('node:os');
|
||||
const path = require('path');
|
||||
const { lfByteCount: byteCount, listWorkflowStems, measureWorkflows } = require('../scripts/workflow-size.cjs');
|
||||
const fc = require('fast-check');
|
||||
const {
|
||||
lfByteCount: byteCount,
|
||||
listWorkflowStems,
|
||||
measureWorkflows,
|
||||
MARGIN_RATIO,
|
||||
marginFor,
|
||||
buildHeadroomRows,
|
||||
formatHeadroomTable,
|
||||
appendHeadroomStepSummary,
|
||||
} = require('../scripts/workflow-size.cjs');
|
||||
const { cleanup } = require('./helpers.cjs');
|
||||
|
||||
const WORKFLOWS_DIR = path.join(__dirname, '..', 'gsd-core', 'workflows');
|
||||
@@ -89,9 +99,17 @@ const WORKFLOWS_DIR = path.join(__dirname, '..', 'gsd-core', 'workflows');
|
||||
// only as the outer bound where the correct response is lazy extraction, never
|
||||
// a raise. Each sits above its tier's current high-water mark with real
|
||||
// headroom (vs the old GRACE=3000 hug):
|
||||
// XL 96 KiB — high-water execute-phase.md 93,400 → ~4.8 KB headroom
|
||||
// LARGE 60 KiB — high-water docs-update.md 55,468 → ~5.8 KB headroom
|
||||
// DEFAULT 40 KiB — high-water settings.md 40,352 → ~608 B headroom
|
||||
// XL 96 KiB
|
||||
// LARGE 60 KiB
|
||||
// DEFAULT 40 KiB
|
||||
//
|
||||
// #4261: the per-tier high-water marks that used to be written out here are
|
||||
// gone rather than refreshed. They were measured once and then quietly
|
||||
// diverged from the tree — the XL line named execute-phase.md as the
|
||||
// high-water when plan-phase.md had passed it — so the comment meant to
|
||||
// document the remaining headroom became a reason to believe there was more
|
||||
// of it than there was. The headroom census below emits the live numbers on
|
||||
// every run instead of asking a comment to stay true.
|
||||
// (DEFAULT is deliberately the tightest: a single-purpose workflow approaching
|
||||
// 40 KiB is the strongest extraction signal of the three. The previous DEFAULT
|
||||
// high-water, verify-phase.md at 40,931 (29 bytes of headroom), was deleted as
|
||||
@@ -150,6 +168,87 @@ function capFor(workflow) {
|
||||
// baseline generator so the guard and the snapshot can never measure
|
||||
// differently. See the #683 regression test at the bottom of this file.
|
||||
|
||||
// ─── #4261: headroom visibility + reserved margin ──────────────────────────
|
||||
//
|
||||
// See the twin block in tests/agent-size-budget.test.cjs for the rationale.
|
||||
// The short version: a green run used to say nothing, so the difference
|
||||
// between a file at 60% of its cap and one at 99.9% was invisible until the
|
||||
// day someone crossed the line — and because each PR's CI measures only its
|
||||
// own base plus its own diff, two individually-green PRs can be jointly over
|
||||
// with no run either of them produces able to show it.
|
||||
const WORKFLOW_HEADROOM_ROWS = buildHeadroomRows(SIZES, capFor);
|
||||
|
||||
describe('SIZE: workflow headroom census (issue #4261)', () => {
|
||||
test('reports every workflow\'s remaining bytes, and never fails for it', (t) => {
|
||||
for (const line of formatHeadroomTable(WORKFLOW_HEADROOM_ROWS)) t.diagnostic(line);
|
||||
const pressured = WORKFLOW_HEADROOM_ROWS.filter((r) => r.overMargin);
|
||||
t.diagnostic(
|
||||
`workflows: ${WORKFLOW_HEADROOM_ROWS.length} | over the ${Math.round(MARGIN_RATIO * 100)}% margin: ${pressured.length}`,
|
||||
);
|
||||
appendHeadroomStepSummary('Workflow size headroom', WORKFLOW_HEADROOM_ROWS);
|
||||
|
||||
// Reporting, not a gate — assert only that the corpus was measured, so an
|
||||
// empty census cannot read as good news.
|
||||
assert.equal(WORKFLOW_HEADROOM_ROWS.length, ALL_WORKFLOWS.length);
|
||||
});
|
||||
|
||||
test('names the workflows inside the reserved margin', (t) => {
|
||||
for (const r of WORKFLOW_HEADROOM_ROWS.filter((row) => row.overMargin)) {
|
||||
t.diagnostic(
|
||||
`RESERVED MARGIN: ${r.name}.md is ${r.bytes} bytes — ${r.headroom} under the ${r.tier} cap ` +
|
||||
`(${r.usedPct.toFixed(1)}%), past the ${r.margin}-byte margin. The cap is not moving: ` +
|
||||
`extract per-mode bodies to workflows/${r.name}/modes/, templates to ` +
|
||||
`workflows/${r.name}/templates/, or shared references to gsd-core/references/ — lazily.`,
|
||||
);
|
||||
}
|
||||
// No assertion on the count, deliberately: pinning it would recreate the
|
||||
// per-file size baseline #2724 deleted for conflicting on 7 of 7 PRs.
|
||||
});
|
||||
|
||||
test('the reserved margin sits strictly below every tier cap', () => {
|
||||
// Negative proof for the margin arithmetic, mirroring the hard-cap
|
||||
// boundary fixtures: a ratio or operator edit that widened the margin to
|
||||
// the cap would silently disable the warning, and no real-corpus test
|
||||
// would notice.
|
||||
for (const cap of [DEFAULT_CAP, LARGE_CAP, XL_CAP]) {
|
||||
const margin = marginFor(cap);
|
||||
assert.ok(margin < cap, `margin ${margin} must sit below cap ${cap}`);
|
||||
const rows = buildHeadroomRows({
|
||||
'below.md': margin - 1,
|
||||
'exact.md': margin,
|
||||
'above.md': margin + 1,
|
||||
}, () => ({ tier: 'FIXTURE', cap }));
|
||||
const byName = new Map(rows.map((row) => [row.name, row]));
|
||||
assert.equal(byName.get('below').overMargin, false, 'margin - 1 is NOT over it');
|
||||
assert.equal(byName.get('exact').overMargin, false, 'exactly at the margin is NOT over it');
|
||||
assert.equal(byName.get('above').overMargin, true, 'margin + 1 IS over it');
|
||||
}
|
||||
});
|
||||
|
||||
test('reserved-margin classification holds for every positive cap', () => {
|
||||
fc.assert(fc.property(
|
||||
fc.integer({ min: 2, max: 10_000_000 }),
|
||||
(cap) => {
|
||||
const margin = marginFor(cap);
|
||||
const rows = buildHeadroomRows({
|
||||
'below.md': margin - 1,
|
||||
'exact.md': margin,
|
||||
'above.md': margin + 1,
|
||||
}, () => ({ tier: 'FIXTURE', cap }));
|
||||
const byName = new Map(rows.map((row) => [row.name, row]));
|
||||
|
||||
assert.ok(margin >= 0 && margin < cap);
|
||||
assert.equal(byName.get('below').overMargin, false);
|
||||
assert.equal(byName.get('exact').overMargin, false);
|
||||
assert.equal(byName.get('above').overMargin, true);
|
||||
assert.equal(byName.get('below').headroom, cap - (margin - 1));
|
||||
assert.equal(byName.get('exact').headroom, cap - margin);
|
||||
assert.equal(byName.get('above').headroom, cap - (margin + 1));
|
||||
},
|
||||
));
|
||||
});
|
||||
});
|
||||
|
||||
describe('SIZE: workflow tier hard caps (issue #1074)', () => {
|
||||
// Absolute outer bound per tier. Unlike the old tighten-only ceiling, a cap
|
||||
// is NOT raised when a file approaches it — crossing it means extract, not
|
||||
|
||||
Reference in New Issue
Block a user