test(#1074): add additive per-file workflow size baseline guard (PR 1/3) (#1089)

* test(#1074): add additive per-file workflow size baseline guard (PR 1/3)

Introduces a committed per-file size baseline scheme alongside (not replacing)
the existing tier anti-creep tests. Green by construction — the baseline
records current sizes, so both schemes pass side by side during migration.

- scripts/lib/allowlist-ratchet.cjs: add assertFileBaseline (third pure helper,
  same injected-fail style) — per-file growth/shrink/add/remove diff vs baseline.
- scripts/workflow-size.cjs: single source of truth for LF-normalized byte
  counting (#683) + workflow enumeration, shared by the guard and the generator
  so they can never measure differently. Lives in scripts/ root (NOT scripts/lib/)
  because it is dev/CI-only tooling — scripts/lib/ is bundled into the installed
  runtime, scripts/ root is not, so this keeps it out of the shipped payload.
- scripts/update-size-baseline.cjs + npm run size:baseline: regenerate the
  snapshot (sorted keys, trailing newline, idempotent).
- tests/workflow-size-baseline.json: generated snapshot (88 workflows).
- tests/workflow-size-budget.test.cjs: import the shared counter (drops the
  duplicated local byteCount) and add the per-file baseline describe block.
- Tests for the helper, the shared module, and the generator (incl. round-trip
  and fault-injection cases).

Refs #1074. Part 1 of 3; PR 2 swaps enforcement, PR 3 covers the agent test.

* test(#1074): regenerate workflow baseline after Update-branch merge with next

The 'Update branch' merge (652a916b) pulled in next's update.md change (#1090)
without regenerating the snapshot, leaving the per-file baseline stale by one
file. Re-ran `npm run size:baseline` so the committed baseline matches the
merged workflow files.

Refs #1074.

---------

Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

scripts/lib/allowlist-ratchet.cjs

@@ -133,4 +133,104 @@ function assertTightCeiling({ label, actualMax, ceiling, grace, fail }) {
   return { ok, slack };
 }
 
-module.exports = { assertWithinAllowlist, assertTightCeiling };
+/**
+ * Assert that each artifact's measured size matches a committed per-file
+ * baseline snapshot.  Growth, shrinkage, additions, and removals are each
+ * surfaced by name — there is no aggregate "max" that can mask one file's
+ * growth behind another file's size.
+ *
+ * Fails when, for the union of `current` and `baseline` keys:
+ * - `current[name] > baseline[name]` → GROWTH: the file grew past its recorded
+ *   size.  Regenerate the baseline and justify the growth in the PR (or extract
+ *   the content lazily).  This is the headline guard.
+ * - `current[name] < baseline[name]` → STALE: the file shrank but the baseline
+ *   still records the old (larger) size.  Regenerate to auto-tighten — the
+ *   per-file analogue of `assertWithinAllowlist`'s stale-entry rule, so the
+ *   snapshot can only ratchet downward.
+ * - name in `current` but not `baseline` → ADDED: a new artifact with no
+ *   recorded baseline.  Regenerate to record it.
+ * - name in `baseline` but not `current` → REMOVED: an orphaned baseline entry
+ *   whose artifact no longer exists.  Regenerate to drop it.
+ *
+ * ## Why per-file, not a tier max (issue #1074)
+ *
+ * A `max(group) within grace` ceiling only binds the single largest file in the
+ * group; every other file inherits that ceiling and can grow silently beneath
+ * it.  Recording each file's exact size removes the masking blind spot — the
+ * same reason `assertWithinAllowlist` enforces on identity rather than a count
+ * (issue #597).
+ *
+ * @param {object} opts
+ * @param {string} opts.label   - Human-readable guard name (used in messages).
+ * @param {Object<string, number>} opts.current  - Measured sizes by name.
+ * @param {Object<string, number>} opts.baseline - Committed sizes by name.
+ * @param {function(string): void} opts.fail - Callback invoked once per
+ *                                    non-empty violation category with a
+ *                                    descriptive message.  Injected so callers
+ *                                    control the failure mode (assert.fail, a
+ *                                    thrower, or a collector in unit tests).
+ * @param {string} [opts.updateHint] - Optional remediation hint appended to
+ *                                    every failure message (e.g. the regen
+ *                                    command).
+ * @returns {{ grown: Array<{name:string,from:number,to:number,delta:number}>,
+ *             shrunk: Array<{name:string,from:number,to:number,delta:number}>,
+ *             added: string[], removed: string[] }}
+ *   Sorted-by-name breakdown of every difference.
+ */
+function assertFileBaseline({ label, current, baseline, fail, updateHint }) {
+  const currentNames = new Set(Object.keys(current));
+  const baselineNames = new Set(Object.keys(baseline));
+
+  const added = [...currentNames].filter((n) => !baselineNames.has(n)).sort();
+  const removed = [...baselineNames].filter((n) => !currentNames.has(n)).sort();
+
+  const grown = [];
+  const shrunk = [];
+  const shared = [...currentNames].filter((n) => baselineNames.has(n)).sort();
+  for (const name of shared) {
+    const from = baseline[name];
+    const to = current[name];
+    if (to > from) grown.push({ name, from, to, delta: to - from });
+    else if (to < from) shrunk.push({ name, from, to, delta: from - to });
+  }
+
+  const hint = updateHint ? `\n${updateHint}` : '';
+
+  if (grown.length > 0) {
+    const list = grown
+      .map((g) => `  - ${g.name}: ${g.from} → ${g.to} (+${g.delta})`)
+      .join('\n');
+    fail(
+      `[${label}] ${grown.length} file(s) grew past the committed baseline. ` +
+        `Regenerate the baseline and justify the growth in your PR, or extract the content lazily.\n${list}${hint}`
+    );
+  }
+
+  if (shrunk.length > 0) {
+    const list = shrunk
+      .map((s) => `  - ${s.name}: ${s.from} → ${s.to} (-${s.delta})`)
+      .join('\n');
+    fail(
+      `[${label}] ${shrunk.length} file(s) are SMALLER than the baseline — the snapshot is stale ` +
+        `and MUST be regenerated so the budget ratchets downward.\n${list}${hint}`
+    );
+  }
+
+  if (added.length > 0) {
+    const list = added.map((n) => `  - ${n}`).join('\n');
+    fail(
+      `[${label}] ${added.length} file(s) are not in the baseline — regenerate to record them.\n${list}${hint}`
+    );
+  }
+
+  if (removed.length > 0) {
+    const list = removed.map((n) => `  - ${n}`).join('\n');
+    fail(
+      `[${label}] ${removed.length} baseline entry(ies) no longer exist — regenerate to drop them.\n${list}${hint}`
+    );
+  }
+
+  return { grown, shrunk, added, removed };
+}
+
+module.exports = { assertWithinAllowlist, assertTightCeiling, assertFileBaseline };

scripts/update-size-baseline.cjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * @file update-size-baseline.cjs
+ *
+ * Regenerates the committed per-file workflow size baseline
+ * (`tests/workflow-size-baseline.json`) from the current workflow files.
+ *
+ * Run via `npm run size:baseline` whenever a workflow file legitimately grows
+ * or shrinks.  Growth must still be justified in the PR; this script only
+ * records the new reality so the CI guard (issue #1074) can diff against it.
+ *
+ * Idempotent: running it twice with no file changes produces no diff.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { measureWorkflows, WORKFLOWS_DIR } = require('./workflow-size.cjs');
+
+const BASELINE_PATH = path.join(__dirname, '..', 'tests', 'workflow-size-baseline.json');
+
+/**
+ * Serialize a size map to the on-disk baseline format: keys sorted, 2-space
+ * indent, trailing newline (so the file is a stable, minimal-diff artifact).
+ *
+ * @param {Object<string, number>} sizes
+ * @returns {string}
+ */
+function serializeBaseline(sizes) {
+  const sorted = {};
+  for (const key of Object.keys(sizes).sort()) sorted[key] = sizes[key];
+  return JSON.stringify(sorted, null, 2) + '\n';
+}
+
+/**
+ * Write the baseline file from the measured workflow sizes.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.dir]      - Workflows dir to measure (default canonical).
+ * @param {string} [opts.outPath]  - Baseline file to write (default canonical).
+ * @returns {{ outPath: string, count: number, content: string }}
+ */
+function generateBaseline({ dir = WORKFLOWS_DIR, outPath = BASELINE_PATH } = {}) {
+  const sizes = measureWorkflows(dir);
+  const content = serializeBaseline(sizes);
+  fs.writeFileSync(outPath, content);
+  return { outPath, count: Object.keys(sizes).length, content };
+}
+
+if (require.main === module) {
+  const { outPath, count } = generateBaseline();
+  process.stdout.write(
+    `Wrote ${count} workflow sizes to ${path.relative(process.cwd(), outPath)}\n`
+  );
+}
+
+module.exports = { generateBaseline, serializeBaseline, BASELINE_PATH };

scripts/workflow-size.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * @file workflow-size.cjs
+ *
+ * Single source of truth for measuring workflow `.md` file sizes in bytes.
+ *
+ * Shared by `tests/workflow-size-budget.test.cjs` (the CI guard) and
+ * `scripts/update-size-baseline.cjs` (the baseline generator) so the two can
+ * never disagree on HOW a file is measured.  A divergence between the generator
+ * and the guard would silently mis-record the baseline (issue #1074).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const WORKFLOWS_DIR = path.join(__dirname, '..', 'gsd-core', 'workflows');
+
+/**
+ * Byte size of a file, counted as on an LF (Unix) checkout.
+ *
+ * The size budget is calibrated against `wc -c` on a Unix (LF) checkout, but
+ * these `.md` files have no `eol=lf` in `.gitattributes`, so Windows checks
+ * them out as CRLF.  Counting raw on-disk bytes there adds one byte per line,
+ * a Windows-only false positive that diverges from the LF calibration basis
+ * (issue #683).  Stripping CR yields the same LF byte count on every platform.
+ * This is still a raw byte count (not a trailing-newline-stripping line count).
+ *
+ * @param {string} filePath - Absolute or relative path to the file.
+ * @returns {number} LF-normalized byte length.
+ */
+function lfByteCount(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return Buffer.byteLength(content.replace(/\r\n/g, '\n'), 'utf-8');
+}
+
+/**
+ * List top-level workflow stems (filenames without the `.md` extension), sorted.
+ * Non-recursive by design: per-mode bodies under `workflows/<name>/modes/` and
+ * templates are NOT measured — only the always-loaded top-level workflows.
+ *
+ * @param {string} [dir] - Workflows directory (defaults to the canonical one).
+ * @returns {string[]} Sorted stems, e.g. `['autonomous', 'plan-phase', ...]`.
+ */
+function listWorkflowStems(dir = WORKFLOWS_DIR) {
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => f.replace(/\.md$/, ''))
+    .sort();
+}
+
+/**
+ * Measure every top-level workflow file, keyed by filename (`<stem>.md`).
+ *
+ * @param {string} [dir] - Workflows directory (defaults to the canonical one).
+ * @returns {Object<string, number>} Map of `<stem>.md` → LF byte size, with
+ *   keys inserted in sorted order.
+ */
+function measureWorkflows(dir = WORKFLOWS_DIR) {
+  const out = {};
+  for (const stem of listWorkflowStems(dir)) {
+    out[`${stem}.md`] = lfByteCount(path.join(dir, `${stem}.md`));
+  }
+  return out;
+}
+
+module.exports = { WORKFLOWS_DIR, lfByteCount, listWorkflowStems, measureWorkflows };