@pareto4/pp-core 1.11.0 → 1.12.0

package/scripts/prompt-injection-scan.sh

@@ -64,31 +64,46 @@ PATTERNS=(
 )
 
 # ─── Allowlist ───────────────────────────────────────────────────────────────
-# Files that legitimately discuss injection patterns (security docs, tests, this script)
+# Files that legitimately contain injection-shaped text (pattern sources, negative
+# test fixtures, adversarial corpora, security documentation).
+#
+# FORMAT (HINST-03, D-09-09): every entry is 'path::reason'.
+#   - `path` is matched as a SUBSTRING of the scanned file path, not as a prefix
+#     and not as a glob: entry `SECURITY.md` exempts every path ending in it.
+#   - `reason` states WHY that path legitimately carries injection-shaped text,
+#     and the hit count measured when it was written. It must be at least 80
+#     characters, and it must contain neither a single quote (the entry is a
+#     single-quoted bash literal) nor the two-character delimiter that opens it.
+#   - `is_allowlisted` strips the reason before matching, so the reason never
+#     participates in the substring rule.
+#
+# Membership is PINNED EXACTLY by tests/security-scan.security.test.cjs
+# (describe 'prompt-injection-scan.sh ALLOWLIST is pinned'). That test sources
+# THIS file and reads the array bash actually expands — adding, removing or
+# un-reasoning an entry here without editing the test turns the suite red.
 ALLOWLIST=(
-  'scripts/prompt-injection-scan.sh'
-  'scripts/base64-scan.sh'
-  'scripts/secret-scan.sh'
-  'tests/security-scan.security.test.cjs'
-  'tests/security.test.cjs'
-  'tests/prompt-injection-scan.security.test.cjs'
-  'tests/verify.test.cjs'
-  'pp-core/bin/lib/security.cjs'
-  'hooks/gsd-prompt-guard.js'
-  'hooks/gsd-read-injection-scanner.js'
-  'tests/read-injection-scanner.security.test.cjs'
-  'tests/security-prompt-injection.security.test.cjs'
-  'tests/fixtures/adversarial/security/'
-  'SECURITY.md'
-  # These files contain intentional injection examples / security-model prose
-  # and are not attack vectors — they explain/demonstrate injection patterns.
-  'TEST-EXAMPLES.md'
-  'explanation/security-model.md'
+  'scripts/prompt-injection-scan.sh::the PATTERNS array above is the literal source of every phrase this scanner looks for, so the file matches itself by construction; measured 4 pattern hits at HEAD on 2026-10-11'
+  'scripts/base64-scan.sh::decodes base64 blobs and re-scans the recovered plaintext against the same injection vocabulary, so it names those phrases inline; measured 2 pattern hits at HEAD on 2026-10-11'
+  'scripts/secret-scan.sh::third of the three diff-mode scan scripts CI runs together in the security-scan job of .gitlab-ci.yml; measured 0 pattern hits at HEAD on 2026-10-11, retained because its own exemption list at line 223 already names security-prompt-injection.security.test.cjs and grows with that vocabulary'
+  'tests/security-scan.security.test.cjs::the behavioural suite for this very scanner, so every positive case embeds a real injection phrase as fixture input; measured 28 pattern hits at HEAD on 2026-10-11'
+  'tests/security.test.cjs::the adversarial suite for the library sanitisers, whose fixtures are real override and role-manipulation strings asserted to be neutralised; measured 54 pattern hits at HEAD on 2026-10-11'
+  'tests/prompt-injection-scan.security.test.cjs::drives scanForInjection in the compiled security library with crafted payloads, and carries a second allowlist of its own for that separate scanner; measured 11 pattern hits at HEAD on 2026-10-11'
+  'tests/vault-security.test.cjs::the vault fencing suite plants an instruction-override heading in a fixture vault file and asserts SUMMARY.md fences and defangs it rather than passing it to the agent as instructions; measured 1 pattern hit at HEAD on 2026-10-11'
+  'tests/verify.test.cjs::the verification suite plants an instruction-override line in a phase artifact and asserts it is rejected, so the line is present as a negative fixture; measured 1 pattern hit at HEAD on 2026-10-11'
+  'pp-core/bin/lib/security.cjs::gitignored build output compiled from src/security.cts per .gitignore line 117, so it is unreachable in diff mode and matters only to a local dir-mode run; it carries the library injection patterns inline; measured 8 pattern hits at HEAD on 2026-10-11'
+  'tests/read-injection-scanner.security.test.cjs::exercises the read-time injection scanner hook with the payloads a hostile file would carry, each asserted to be blocked rather than obeyed; measured 14 pattern hits at HEAD on 2026-10-11'
+  'tests/security-prompt-injection.security.test.cjs::carries two deliberate NUL bytes at lines 631 and 881 so grep classifies it as binary and reports whole-file matches with no line numbers; 10 binary pattern matches measured at HEAD on 2026-10-11'
+  'tests/fixtures/adversarial/security/::a directory of adversarial corpus files whose entire purpose is to BE injection payloads for the suites above; measured 20 pattern hits across its 7 tracked files at HEAD on 2026-10-11'
+  'SECURITY.md::the substring rule makes this exempt every path ending in SECURITY.md, including pp-core/templates/SECURITY.md and every per-phase threat register generated from that template; the breadth is accepted because a security policy is exactly where injection phrasing is legitimately quoted; measured 1 pattern hit across all 13 such files on disk at HEAD on 2026-10-11, a quoted attack shape in a phase threat register'
+  'TEST-EXAMPLES.md::documentation that demonstrates injection examples in order to explain what these scanners catch, so the example text is the point of the file rather than an attack; measured 1 pattern hit at HEAD on 2026-10-11'
+  'explanation/security-model.md::matches docs/explanation/security-model.md through the substring rule; it is the prose that explains the injection threat model and quotes the attack shapes pp-core defends against; measured 2 pattern hits at HEAD on 2026-10-11'
 )
 
 is_allowlisted() {
   local file="$1"
   for allowed in "${ALLOWLIST[@]}"; do
+    # Strip the 'path::reason' suffix — the reason never takes part in matching.
+    allowed="${allowed%%::*}"
     if [[ "$file" == *"$allowed"* ]]; then
       return 0
     fi
@@ -204,4 +219,10 @@ main() {
   exit 0
 }
 
-main "$@"
+# Sourceable for the test that pins the ALLOWLIST (D-09-10): sourcing this
+# script must expand the array WITHOUT running the scanner. Direct execution
+# (bash scripts/prompt-injection-scan.sh ... , or ./scripts/...) is unchanged —
+# there BASH_SOURCE[0] and $0 are the same string. Verified on bash 3.2.57.
+if [[ "${BASH_SOURCE[0]:-}" == "${0}" ]]; then
+  main "$@"
+fi

package/scripts/sync-manifest-versions.cjs

@@ -4,10 +4,17 @@
 /**
  * sync-manifest-versions.cjs
  *
- * Stamps the package.json version into every runtime-integration manifest whose
- * top-level `version` field MUST track the package version.  Called automatically
- * by the `version` npm lifecycle script so that `npm version X.Y.Z` keeps all
- * registered manifests in sync.
+ * Stamps the package.json version into every versioned manifest.  Called
+ * automatically by the `version` npm lifecycle script so that `npm version X.Y.Z`
+ * keeps all registered manifests in sync.  Two kinds:
+ *
+ *   - VERSIONED_MANIFESTS — JSON runtime-integration manifests whose top-level
+ *     `version` field MUST track the package version.
+ *   - VERSIONED_TEXT_FILES — plain-text manifests whose ENTIRE content is the
+ *     version followed by one newline.  Root `VERSION` is the repo layout's
+ *     version source for `resolveCreatedWith` (src/compose-bindings.cts), so a
+ *     repo build stamps `createdWith` from it.  As a plain-text file it could not
+ *     join the JSON loop, so nothing kept it in step with package.json.
  *
  * Usage:
  *   node scripts/sync-manifest-versions.cjs           # stamp + report
@@ -29,6 +36,22 @@ const VERSIONED_MANIFESTS = [
   'gemini-extension.json',
 ];
 
+// Plain-text manifests: the whole file is the version plus one newline. Stamped,
+// drift-checked, staged and counted exactly like VERSIONED_MANIFESTS.
+const VERSIONED_TEXT_FILES = [
+  'VERSION',
+];
+
+// A text manifest's trimmed content, or null when the file is missing.
+function readTextVersion(abs) {
+  try {
+    return fs.readFileSync(abs, 'utf8').trim();
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
 function readJson(p) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
@@ -53,6 +76,13 @@ function syncManifestVersions(opts) {
       changed.push(rel);
     }
   }
+  for (const rel of VERSIONED_TEXT_FILES) {
+    const abs = path.join(root, rel);
+    if ((readTextVersion(abs) || '') !== v) {
+      fs.writeFileSync(abs, v + '\n');
+      changed.push(rel);
+    }
+  }
   return changed;
 }
 
@@ -65,6 +95,10 @@ function findDrift(opts) {
     const found = readJson(path.join(root, rel)).version;
     if (found !== v) drift.push({ manifest: rel, found, expected: v });
   }
+  for (const rel of VERSIONED_TEXT_FILES) {
+    const found = readTextVersion(path.join(root, rel));
+    if (found !== v) drift.push({ manifest: rel, found, expected: v });
+  }
   return drift;
 }
 
@@ -84,14 +118,14 @@ function stageManifests(opts) {
     return;
   }
   try {
-    execFileSync('git', ['add', '--', ...VERSIONED_MANIFESTS], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
+    execFileSync('git', ['add', '--', ...VERSIONED_MANIFESTS, ...VERSIONED_TEXT_FILES], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
   } catch (err) {
     const detail = err && err.stderr ? err.stderr.toString().trim() : (err && err.message) || 'unknown error';
     throw new Error(`sync-manifest-versions: failed to git-add manifests inside a work tree: ${detail}`);
   }
 }
 
-module.exports = { VERSIONED_MANIFESTS, syncManifestVersions, findDrift, getPackageVersion, stageManifests };
+module.exports = { VERSIONED_MANIFESTS, VERSIONED_TEXT_FILES, syncManifestVersions, findDrift, getPackageVersion, stageManifests };
 
 if (require.main === module) {
   const args = process.argv.slice(2);
@@ -105,7 +139,7 @@ if (require.main === module) {
       console.error('Run `node scripts/sync-manifest-versions.cjs` to fix.');
       process.exitCode = 1;
     } else {
-      console.log('All ' + VERSIONED_MANIFESTS.length + ' versioned manifests in sync at ' + version + '.');
+      console.log('All ' + (VERSIONED_MANIFESTS.length + VERSIONED_TEXT_FILES.length) + ' versioned manifests in sync at ' + version + '.');
     }
   } else {
     const changed = syncManifestVersions({ version });

package/scripts/sync-runtime-launcher.cjs

@@ -23,6 +23,75 @@ const WORKFLOWS_DIR = path.join(__dirname, '..', 'pp-core', 'workflows');
 const AGENTS_DIR = path.join(__dirname, '..', 'agents');
 const SNIPPET_FILE = path.join(WORKFLOWS_DIR, '_runtime-launcher.snippet.sh');
 
+/**
+ * The prefix every launcher line starts with (after trimming leading indentation).
+ */
+const LAUNCHER_HEAD = '_PP_SHIM_NAME="pp-tools.cjs"; ';
+
+/**
+ * Launcher carriers that live OUTSIDE this script's two roots
+ * (pp-core/workflows/ and agents/).
+ *
+ * Why a list rather than another walked root: these are commands, docs and
+ * references whose block structure must survive untouched. transformFile()
+ * strips every resolver line from every shell block and re-inserts ONE preamble
+ * into the first pp_run block — correct for a workflow, wrong here, because
+ * commands/pp-graphify.md legitimately carries five copies (one per Bash-tool
+ * block a reader may run in isolation) and docs/DEBUGGING.md carries one inside
+ * an explanatory fence. They get line-level in-place replacement instead:
+ * same count, same positions, same indentation.
+ *
+ * Adding a launcher line to a file outside the roots without listing it here is
+ * caught by the repo-wide sweep in tests/runtime-launcher-parity.test.cjs (W6),
+ * which reads this array — the sweep is deliberately wider than the generator.
+ */
+const EXTRA_CARRIERS = Object.freeze([
+  'commands/pp-discuss-phase.md',
+  'commands/pp-graphify.md',
+  'commands/pp-import.md',
+  'docs/DEBUGGING.md',
+  'pp-core/references/planner-load-graph-context.md',
+]);
+
+/**
+ * True when `line` is a launcher line: it starts with the launcher head
+ * (ignoring indentation) and closes the one-line if/elif/else chain with `fi`.
+ *
+ * A prose line that merely mentions the head in backticks does not close with
+ * `fi`, so it is rejected. This is the SINGLE detector shared by the generator
+ * and the parity sweep.
+ *
+ * @param {string} line
+ * @returns {boolean}
+ */
+function isLauncherLine(line) {
+  if (typeof line !== 'string') return false;
+  const trimmed = line.trim();
+  return trimmed.startsWith(LAUNCHER_HEAD) && /\bfi$/.test(trimmed);
+}
+
+/**
+ * Replace every launcher line in `content` with `canonicalLine`, in place:
+ * the line count, each line's position and each line's leading whitespace are
+ * preserved. Nothing else in the document is read or written.
+ *
+ * @param {string} content
+ * @param {string} canonicalLine
+ * @returns {string|null} the new content, or null when nothing changed
+ */
+function replaceCanonicalLines(content, canonicalLine) {
+  const lines = content.split('\n');
+  let changed = false;
+  const out = lines.map((line) => {
+    if (!isLauncherLine(line)) return line;
+    const indent = line.slice(0, line.length - line.trimStart().length);
+    const replacement = indent + canonicalLine;
+    if (replacement !== line) changed = true;
+    return replacement;
+  });
+  return changed ? out.join('\n') : null;
+}
+
 // Read canonical preamble (full content of snippet file)
 function loadPreamble() {
   const raw = fs.readFileSync(SNIPPET_FILE, 'utf8');
@@ -413,12 +482,48 @@ function main() {
     }
   }
 
+  // Process the launcher carriers outside the two roots (in-place line mode).
+  if (preamble.length !== 1) {
+    throw new Error(
+      `_runtime-launcher.snippet.sh must be exactly ONE line (found ${preamble.length}). ` +
+        'The in-place carrier mode, the repo-wide parity sweep and the one-line extractor in ' +
+        'tests/bug-3668-workflow-runtime-resolution.test.cjs all depend on that contract.',
+    );
+  }
+  const repoRoot = path.join(__dirname, '..');
+  for (const rel of EXTRA_CARRIERS) {
+    const full = path.join(repoRoot, rel);
+    const content = fs.readFileSync(full, 'utf8');
+    if (!content.split('\n').some((line) => isLauncherLine(line))) {
+      throw new Error(
+        `EXTRA_CARRIERS lists ${rel} but that file carries no launcher line. ` +
+          'A stale list must fail loudly rather than silently skip a carrier — ' +
+          'remove the entry or restore the launcher line.',
+      );
+    }
+    const result = replaceCanonicalLines(content, preamble[0]);
+    if (result !== null) {
+      fs.writeFileSync(full, result, 'utf8');
+      transformedCount++;
+      console.log(`transformed (carrier): ${rel}`);
+    } else {
+      unchangedCount++;
+    }
+  }
+
   console.log(`\nDone. ${transformedCount} files transformed, ${unchangedCount} unchanged.`);
 }
 
 // Export the pure transform for tests; only run the filesystem walk when invoked
 // directly (`node scripts/sync-runtime-launcher.cjs`), never on require().
-module.exports = { transformFile, loadPreamble };
+module.exports = {
+  transformFile,
+  loadPreamble,
+  isLauncherLine,
+  replaceCanonicalLines,
+  EXTRA_CARRIERS,
+  LAUNCHER_HEAD,
+};
 
 if (require.main === module) {
   main();

package/scripts/update-size-baseline.cjs

@@ -4,65 +4,309 @@
 /**
  * @file update-size-baseline.cjs
  *
- * Regenerates the committed per-file workflow size baseline
- * (`tests/workflow-size-baseline.json`) from the current workflow files.
+ * Regenerates the committed per-file size baselines
+ * (`tests/workflow-size-baseline.json`, `tests/agent-size-baseline.json`) from
+ * the current 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.
+ * Workflow size budget policy (2026-10-11; per commit since pack 9): the guards
+ * allow each commit a small DELTA BUDGET (config size_budget.*, see
+ * scripts/lib/size-budget.cjs), so plans never run this script. It runs once per
+ * phase, in the phase's closing commit (`--reason "phase NN close"`, from
+ * execute-phase), and otherwise only when one commit must grow past the budget.
+ * Because a raise is the review record of growth, RAISING any entry requires a
+ * reason:
  *
- * Idempotent: running it twice with no file changes produces no diff.
+ *   npm run size:baseline                         # lower / add / remove only
+ *   npm run size:baseline -- --reason "<why>"     # also allowed to raise
+ *
+ * Without `--reason`, a run that would raise any entry is REFUSED: it exits
+ * non-zero and writes nothing (neither baseline). With a reason, every raise is
+ * recorded in the baseline file's `_rebaselines` array (newest last) as
+ * `{ date, reason, deltas: [{ file, from, to, delta }] }` — the committed
+ * review record of a deliberate growth.
+ *
+ * Idempotent: running it twice with no file changes produces no diff (a run
+ * with nothing to raise never appends a `_rebaselines` entry).
  */
 
 const fs = require('fs');
 const path = require('path');
-const { measureMdFiles, WORKFLOWS_DIR } = require('./workflow-size.cjs');
+const { measureMdFiles, measureMdTree, WORKFLOWS_DIR } = require('./workflow-size.cjs');
 
 const BASELINE_PATH = path.join(__dirname, '..', 'tests', 'workflow-size-baseline.json');
 const AGENTS_DIR = path.join(__dirname, '..', 'agents');
 const AGENT_BASELINE_PATH = path.join(__dirname, '..', 'tests', 'agent-size-baseline.json');
-const isGsdAgent = (f) => f.startsWith('pp-');
+const isPpAgent = (f) => f.startsWith('pp-');
+
+/** Key of the raise log inside a baseline file. Never a measured filename. */
+const REBASELINES_KEY = '_rebaselines';
+
+/**
+ * Split a parsed baseline file into its size entries and its raise log.
+ * Size entries are the numeric values; metadata keys (`_rebaselines`) are not
+ * sizes and must never reach a guard as one.
+ *
+ * @param {object|null} raw - Parsed baseline JSON (null when absent).
+ * @returns {{ sizes: Object<string, number>, rebaselines: Array<object> }}
+ */
+function splitBaseline(raw) {
+  const sizes = {};
+  let rebaselines = [];
+  if (raw && typeof raw === 'object') {
+    for (const [key, value] of Object.entries(raw)) {
+      if (key === REBASELINES_KEY) rebaselines = value;
+      else sizes[key] = value;
+    }
+  }
+  return { sizes, rebaselines };
+}
+
+/**
+ * Read and parse a baseline file; `null` when it does not exist.
+ *
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function readBaseline(filePath) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  return JSON.parse(text);
+}
 
 /**
- * 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).
+ * Serialize to the on-disk baseline format: size keys sorted, then the
+ * `_rebaselines` log last; 2-space indent, trailing newline (a stable,
+ * minimal-diff artifact).
  *
  * @param {Object<string, number>} sizes
+ * @param {Array<object>} [rebaselines]
  * @returns {string}
  */
-function serializeBaseline(sizes) {
+function serializeBaseline(sizes, rebaselines = []) {
   const sorted = {};
   for (const key of Object.keys(sizes).sort()) sorted[key] = sizes[key];
+  sorted[REBASELINES_KEY] = rebaselines;
   return JSON.stringify(sorted, null, 2) + '\n';
 }
 
 /**
- * Write a baseline file from the measured `.md` sizes in a directory.
+ * Classify the difference between an old and a new size map.
+ *
+ * @param {Object<string, number>} oldSizes
+ * @param {Object<string, number>} newSizes
+ * @returns {{ raised: Array<{file:string,from:number,to:number,delta:number}>,
+ *             lowered: Array<{file:string,from:number,to:number,delta:number}>,
+ *             added: string[], removed: string[] }}
+ */
+function diffSizes(oldSizes, newSizes) {
+  const raised = [];
+  const lowered = [];
+  const added = [];
+  for (const file of Object.keys(newSizes).sort()) {
+    if (!(file in oldSizes)) {
+      added.push(file);
+      continue;
+    }
+    const from = oldSizes[file];
+    const to = newSizes[file];
+    if (to > from) raised.push({ file, from, to, delta: to - from });
+    else if (to < from) lowered.push({ file, from, to, delta: from - to });
+  }
+  const removed = Object.keys(oldSizes).filter((f) => !(f in newSizes)).sort();
+  return { raised, lowered, added, removed };
+}
+
+/**
+ * Validate a `_rebaselines` log. Returns a list of problems (empty = valid).
+ * Every entry must carry an ISO date, a non-empty reason and a non-empty list
+ * of positive deltas whose arithmetic holds; dates must be non-decreasing
+ * (newest last).
+ *
+ * @param {unknown} log
+ * @returns {string[]}
+ */
+function validateRebaselineLog(log) {
+  if (!Array.isArray(log)) return [`${REBASELINES_KEY} must be an array, got ${JSON.stringify(log)}`];
+  const problems = [];
+  const isSize = (n) => Number.isInteger(n) && n >= 0;
+  let prevDate = '';
+  log.forEach((entry, i) => {
+    const at = `${REBASELINES_KEY}[${i}]`;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      problems.push(`${at} must be an object`);
+      return;
+    }
+    if (typeof entry.date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(entry.date)) {
+      problems.push(`${at}.date must be YYYY-MM-DD, got ${JSON.stringify(entry.date)}`);
+    } else {
+      if (entry.date < prevDate) problems.push(`${at}.date ${entry.date} is older than the entry before it (newest must be last)`);
+      prevDate = entry.date;
+    }
+    if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
+      problems.push(`${at}.reason must be a non-empty string`);
+    }
+    if (!Array.isArray(entry.deltas) || entry.deltas.length === 0) {
+      problems.push(`${at}.deltas must be a non-empty array`);
+      return;
+    }
+    entry.deltas.forEach((d, j) => {
+      const dat = `${at}.deltas[${j}]`;
+      if (!d || typeof d.file !== 'string' || d.file === '') problems.push(`${dat}.file must be a non-empty string`);
+      if (!d || !isSize(d.from) || !isSize(d.to)) problems.push(`${dat}.from/.to must be non-negative integers`);
+      else if (!Number.isInteger(d.delta) || d.delta <= 0 || d.delta !== d.to - d.from) {
+        problems.push(`${dat}.delta must be the positive difference to - from (${d.to - d.from}), got ${JSON.stringify(d.delta)}`);
+      }
+    });
+  });
+  return problems;
+}
+
+/**
+ * Compute (but do not write) a regenerated baseline.
  *
  * @param {object} [opts]
  * @param {string} [opts.dir]       - Directory to measure (default: workflows).
- * @param {string} [opts.outPath]   - Baseline file to write (default: workflow).
- * @param {function(string): boolean} [opts.predicate] - Filename filter.
- * @returns {{ outPath: string, count: number, content: string }}
+ * @param {string} [opts.outPath]   - Baseline file (default: workflow baseline).
+ * @param {function(string): boolean} [opts.predicate] - File filter.
+ * @param {function(string, function): Object<string, number>} [opts.measure] -
+ *        Measurer (default: recursive `measureMdTree`; agents pass `measureMdFiles`).
+ * @param {string} [opts.reason]    - Justification; required to raise any entry.
+ * @param {string} [opts.today]     - Date stamp for a raise (default: today, UTC).
+ * @returns {{ outPath: string, refused: boolean, count: number, content: string|null,
+ *             change: ReturnType<typeof diffSizes> }}
  */
-function generateBaseline({ dir = WORKFLOWS_DIR, outPath = BASELINE_PATH, predicate } = {}) {
-  const sizes = measureMdFiles(dir, predicate);
-  const content = serializeBaseline(sizes);
-  fs.writeFileSync(outPath, content);
-  return { outPath, count: Object.keys(sizes).length, content };
+function planBaseline({
+  dir = WORKFLOWS_DIR,
+  outPath = BASELINE_PATH,
+  predicate,
+  measure = measureMdTree,
+  reason,
+  today = new Date().toISOString().slice(0, 10),
+} = {}) {
+  const sizes = measure(dir, predicate);
+  const { sizes: oldSizes, rebaselines: oldLog } = splitBaseline(readBaseline(outPath));
+  const change = diffSizes(oldSizes, sizes);
+  const count = Object.keys(sizes).length;
+  const hasReason = typeof reason === 'string' && reason.trim() !== '';
+  if (change.raised.length > 0 && !hasReason) {
+    return { outPath, refused: true, count, content: null, change };
+  }
+  const log = Array.isArray(oldLog) ? [...oldLog] : [];
+  if (change.raised.length > 0) {
+    log.push({ date: today, reason: reason.trim(), deltas: change.raised });
+  }
+  return { outPath, refused: false, count, content: serializeBaseline(sizes, log), change };
 }
 
-if (require.main === module) {
-  const targets = [
-    { label: 'workflow', dir: WORKFLOWS_DIR, outPath: BASELINE_PATH },
-    { label: 'agent', dir: AGENTS_DIR, outPath: AGENT_BASELINE_PATH, predicate: isGsdAgent },
-  ];
-  for (const t of targets) {
-    const { outPath, count } = generateBaseline(t);
-    process.stdout.write(
-      `Wrote ${count} ${t.label} sizes to ${path.relative(process.cwd(), outPath)}\n`
+/**
+ * Regenerate one baseline file. A refused plan (a raise without a reason)
+ * writes nothing.
+ *
+ * @param {Parameters<typeof planBaseline>[0]} [opts]
+ * @returns {ReturnType<typeof planBaseline>}
+ */
+function generateBaseline(opts = {}) {
+  const plan = planBaseline(opts);
+  if (!plan.refused) fs.writeFileSync(plan.outPath, plan.content);
+  return plan;
+}
+
+/**
+ * Parse CLI arguments: only `--reason <text>` / `--reason=<text>`.
+ *
+ * @param {string[]} argv
+ * @returns {{ reason?: string }}
+ */
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--reason') {
+      out.reason = argv[++i];
+      if (out.reason === undefined) throw new Error('--reason needs a value');
+    } else if (arg.startsWith('--reason=')) {
+      out.reason = arg.slice('--reason='.length);
+    } else {
+      throw new Error(`unknown argument: ${arg} (only --reason "<text>" is accepted)`);
+    }
+  }
+  if (out.reason !== undefined && out.reason.trim() === '') throw new Error('--reason must not be empty');
+  return out;
+}
+
+const TARGETS = [
+  { label: 'workflow', dir: WORKFLOWS_DIR, outPath: BASELINE_PATH, measure: measureMdTree },
+  { label: 'agent', dir: AGENTS_DIR, outPath: AGENT_BASELINE_PATH, predicate: isPpAgent, measure: measureMdFiles },
+];
+
+/**
+ * CLI entry. Plans every target first and writes only when none is refused,
+ * so a refusal leaves BOTH baselines untouched.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {Array<object>} [io.targets]
+ * @param {string} [io.today]
+ * @param {NodeJS.WritableStream} [io.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr]
+ * @returns {number} exit code
+ */
+function main(argv, { targets = TARGETS, today, stdout = process.stdout, stderr = process.stderr } = {}) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    stderr.write(`size:baseline: ${err.message}\n`);
+    return 2;
+  }
+  const plans = targets.map((t) => ({ t, plan: planBaseline({ ...t, reason: args.reason, today }) }));
+  const refused = plans.filter((p) => p.plan.refused);
+  if (refused.length > 0) {
+    const lines = refused.flatMap(({ t, plan }) =>
+      plan.change.raised.map((r) => `  - ${t.label}: ${r.file}: ${r.from} → ${r.to} (+${r.delta})`)
+    );
+    stderr.write(
+      'size:baseline: REFUSED — this run would RAISE baseline entries, which needs a reason:\n' +
+        `${lines.join('\n')}\n` +
+        'Shrink the file(s), or re-run with: npm run size:baseline -- --reason "<why this growth is needed>"\n' +
+        'Nothing was written.\n'
     );
+    return 1;
   }
+  for (const { t, plan } of plans) {
+    fs.writeFileSync(plan.outPath, plan.content);
+    const c = plan.change;
+    stdout.write(
+      `Wrote ${plan.count} ${t.label} sizes to ${path.relative(process.cwd(), plan.outPath)} ` +
+        `(raised ${c.raised.length}, lowered ${c.lowered.length}, added ${c.added.length}, removed ${c.removed.length})\n`
+    );
+  }
+  if (args.reason !== undefined && plans.every((p) => p.plan.change.raised.length === 0)) {
+    stdout.write('Note: nothing was raised, so --reason was not recorded.\n');
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
 }
 
-module.exports = { generateBaseline, serializeBaseline, BASELINE_PATH, AGENT_BASELINE_PATH };
+module.exports = {
+  generateBaseline,
+  planBaseline,
+  serializeBaseline,
+  splitBaseline,
+  readBaseline,
+  diffSizes,
+  validateRebaselineLog,
+  parseArgs,
+  main,
+  REBASELINES_KEY,
+  BASELINE_PATH,
+  AGENT_BASELINE_PATH,
+};