@pareto4/pp-core 1.13.0 → 1.17.1

package/pp-core/workflows/execute-phase/steps/serial-group-dispatch.md

@@ -1,73 +0,0 @@
-# Serial-group dispatch — execute-phase step 3 (`kind: serial-group` spawns)
-
-A serial group is a set of plans in one wave that share only non-source files (a test file, a size
-baseline, a changeset, a doc). `phase.dispatch-plan` gives the group ONE spawn with
-`isolation: main-checkout` and its `plans[]` in run order. Spawn exactly one executor for it — never
-one per plan, never in a worktree (no `isolation=` parameter). Main-checkout spawns run one at a time;
-the wave's worktree spawns may run alongside.
-
-Emit the plan-start heartbeat for the group's first plan, then dispatch (runs in a subagent — no output until the whole group returns; expected, not a freeze):
-
-```text
-Agent(
-  subagent_type="pp-executor",
-  description="Execute serial group {serial_group} of phase {phase_number}: {plan count} plans",
-  model="{executor_model}",  # omit this line when executor_model == "inherit"
-  prompt="
-    <objective>
-    Execute these plans of phase {phase_number}-{phase_name} on the main checkout, one after another, in this order:
-    {for each entry of spawn.plans, numbered:}
-    {n}. {plan.id} — {plan.title} — ${PROJECT_ROOT}/{phase_dir}/{plan file} — touched tests: {plan.touched_tests or "none"} — build: {plan.build}
-    For each plan in turn: execute its tasks with their own atomic commits, write and commit its own SUMMARY.md, run its touched test files, then start the next plan.
-    </objective>
-
-    <dispatch tracking="orchestrator" suite="orchestrator" build="{spawn.build}" />
-
-    <serial_group_rules>
-    - One plan at a time, in the listed order. Each plan gets its own task commits and its own `{plan_id}-SUMMARY.md`, committed before the next plan starts.
-    - Tests: per plan, run only the test files that plan touches (listed above) and its narrower `<verify>` commands. Never the full suite — the orchestrator runs it once after the wave.
-    - Build: only before the tests of a plan whose `build` is true. When the group's `build` is false, run no build at all.
-    - Never call `state.*`, `roadmap.update-plan-progress` or `requirements.mark-complete`, and never stage STATE.md, ROADMAP.md or REQUIREMENTS.md: the orchestrator advances them once per wave.
-    - Never run `size:baseline`; the phase's closing commit re-baselines.
-    - Halt: when a plan cannot finish (verification still failing after repair, a Rule 4 stop, a checkpoint), stop the group at that plan — do not start the next one — and return `## GROUP HALTED` with `**Halted at:** {plan_id}`, the reason, the completed plans with their SUMMARY paths, and the plans not started.
-    - Otherwise return `## GROUP COMPLETE` with one `## PLAN COMPLETE` block per plan, in order.
-    </serial_group_rules>
-
-    <sequential_execution>
-    You are running as a SEQUENTIAL executor agent on the main working tree.
-    Use normal git commits (with hooks). Do NOT use --no-verify.
-    REQUIRED ORDER, per plan: Write SUMMARY.md → commit → only then any narration.
-    </sequential_execution>
-
-    <execution_context>
-    @~/.claude/pp-core/workflows/execute-plan.md
-    @~/.claude/pp-core/templates/summary.md
-    @~/.claude/pp-core/references/checkpoints.md
-    @~/.claude/pp-core/references/tdd.md
-    </execution_context>
-
-    <files_to_read>
-    MANDATORY: load every file listed here with the Read tool before you start the work — this block is your required reading.
-    First resolve repo root: `PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)`
-    - Every plan file listed in <objective> (read the next one again before starting it)
-    - ${PROJECT_ROOT}/.planning/PROJECT.md, ${PROJECT_ROOT}/.planning/STATE.md, ${PROJECT_ROOT}/.planning/config.json (if exists)
-    - ${PROJECT_ROOT}/${phase_dir}/*-CONTEXT.md and *-RESEARCH.md (if they exist)
-    - ${PROJECT_ROOT}/CLAUDE.md or ${PROJECT_ROOT}/.claude/CLAUDE.md, and project skills (if any)
-    </files_to_read>
-
-    ${AGENT_SKILLS}
-    {spawn.contributions[].fragment — each verbatim, blank-line separated; nothing when empty}
-
-    <success_criteria>
-    - [ ] Every listed plan executed in order, or the group halted with the halting plan named
-    - [ ] Each task committed individually; one committed SUMMARY.md per completed plan
-    - [ ] No tracking-file writes (the orchestrator advances them once per wave)
-    </success_criteria>
-  "
-)
-```
-
-**On return:**
-- `## GROUP COMPLETE` → emit a plan-complete heartbeat per plan and go on to step 4 (spot-checks use the spawn's `expected_summaries`).
-- `## GROUP HALTED` → the plans before the halt are done (their SUMMARY.md counts for this wave's suite run and tracking commit). Route the halting plan to step 7 (handle failures). The plans after it are not started; they stay incomplete, so a re-run of `phase.dispatch-plan --wave {N}` lists only them.
-- A checkpoint at a plan → `checkpoint_handling`; once resolved, re-run `phase.dispatch-plan --wave {N}` and dispatch the remaining spawn.

package/pp-core/workflows/execute-phase/steps/vault-door-gate.md

@@ -1,19 +0,0 @@
-# Vault door gate (the side doors)
-
-A workflow that writes code outside `/pp-execute-phase` runs the same vault gate as execute:pre
-before its first write. The host Reads this file at the point it names and restates none of it.
-
-```bash
-_PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
-DOOR_VAULT=$(pp_run loop render-hooks execute:pre --active-cap vault) || exit 1
-echo "DOOR_VAULT=$DOOR_VAULT"
-```
-
-- **The fence exits non-zero:** render-hooks refused, and its message names the unreadable config
-  file. STOP: write nothing. The operator repairs the file and re-runs the command.
-- **`DOOR_VAULT=false`:** the vault capability is not active for this project. Continue silently.
-- **`DOOR_VAULT=true`:** the execute:pre vault step and gate are active. Read and execute
-  `pp-core/workflows/execute-phase/steps/vault-fetch.md`, then set `VAULT_GATE_POINT=execute` and
-  Read and execute `pp-core/workflows/execute-phase/steps/vault-load-gate.md`. Its fence prints
-  the card and exits non-zero on `stop`; a stop ends the host run before anything is written, in
-  every mode and every tier.

package/pp-core/workflows/plan-phase/steps/phase-tier.md

@@ -1,43 +0,0 @@
-# Plan-phase: ceremony tier
-
-Read at §1, right after init. The phase's tier decides which planning agents run. Never re-derive it from config: `src/phase-tier.cts` resolves it (`--tier` > the phase's ROADMAP `**Tier:**` line > `phase.tier` > `standard`; an explicit project `false` wins).
-
-```bash
-_PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
-TIER_PROPOSAL=$(pp_run query phase.tier-propose "$PHASE" --record $TIER_FLAG)
-DISPATCH_PLAN=$(pp_run query phase.dispatch-plan "$PHASE" $TIER_FLAG)
-```
-
-Print one line from `TIER_PROPOSAL`: `Tier: {effective.tier} ({effective.source}) — proposed {proposal.tier}: {proposal.reason}`. If `effective.suppressed` is non-empty, append `— kept off by your config: {effective.suppressed}`. Do not ask; the operator overrides with `--tier`. `--record` writes the proposal as `**Tier:** <tier> (proposed: …)` and never replaces a tier the operator chose; `--record --tier X` records X as the operator's choice.
-
-`DISPATCH_PLAN.stages.plan` lists what this run spawns, in order. The init booleans come from the same resolver, so they agree:
-
-| Stage entry | Agent | Init key / hook |
-|---|---|---|
-| `plan-research` | `pp-phase-researcher` | `research_enabled` |
-| `plan-patterns` | `pp-pattern-mapper` | pattern-mapper `plan:pre` hook (render-hooks `--phase`) |
-| `plan-planner` | `pp-planner` | always |
-| `plan-check-N` / `plan-revise-N` | `pp-plan-checker` / `pp-planner` | `plan_checker_enabled`; §12 caps checker passes at `plan_check_passes` |
-| `plan-bounce` | (script) | `plan_bounce_enabled` (§12.5) |
-| `plan-gaps` | (report) | gap-analysis `plan:post` hook (§13e) |
-
-Spawn nothing the stage does not list. The explicit flags still apply on top: `--research` forces research, `--skip-research`, `--skip-verify`, `--bounce` / `--skip-bounce`.
-
-## After planning (§9, `## PLANNING COMPLETE`)
-
-Threat-model presence gate first (active only when the tier resolves `security_enforcement` on, i.e. the step 5.55 banner showed):
-
-```bash
-TM_BLOCK=$(pp_run check threat-model-presence "$PHASE" $TIER_FLAG --pick block) || exit 1
-[ "$TM_BLOCK" != "true" ] || exit 1   # stderr names each new plan without <threat_model>
-```
-
-If it stops: do not go on to step 10 or 13; re-spawn the planner (step 8) requiring the block in each plan named, then return here.
-
-Plans now exist, so re-propose from their `files_modified`:
-
-```bash
-TIER_PROPOSAL=$(pp_run query phase.tier-propose "$PHASE" --record)
-```
-
-Print the same line. If `proposal.tier` differs from `effective.tier` (an operator choice is kept), add: `Plans suggest {proposal.tier} ({proposal.reason}); pass --tier {proposal.tier} to /pp:execute-phase and /pp:verify-work to apply it.` Execute-phase and verify-work read the recorded tier.

package/scripts/lib/size-budget.cjs

@@ -1,311 +0,0 @@
-'use strict';
-
-/**
- * @file size-budget.cjs
- *
- * The per-commit size budget for workflow and agent markdown (pack 9, item 4).
- *
- * ## What is measured
- *
- * Every CHANGE since the baseline file was last committed, one at a time:
- *   - each commit in `<last baseline commit>..HEAD` (at most MAX_COMMITS), against
- *     its parent — for a merge commit, against the larger of each file's sizes in
- *     its parents, so a merge adds nothing of its own and each plan commit is
- *     judged on its own branch;
- *   - the uncommitted edits under the guarded directory, against HEAD.
- * A file's allowance base is the LARGER of its size before the change and its
- * size in the committed baseline file. A change may grow one file by at most
- * `per_file_bytes` and all files together by at most `per_commit_bytes`. So:
- *   - a plan that grows a few files a little passes without touching the
- *     baseline, however much the phase has grown in earlier plans;
- *   - growth already recorded in the baseline (a justified re-baseline) passes;
- *   - one change growing past the budget fails, by file and by total, and stays
- *     red until it is shrunk or recorded — a later commit does not hide it.
- * A file that is in neither the baseline nor the parent (a new file) is not
- * budgeted; the tier, nested and new-file hard caps in the guard tests bound it.
- *
- * The cumulative growth of a phase is recorded once, at phase close:
- * `npm run size:baseline -- --reason "phase NN close"` in the phase's closing
- * commit, which also starts the next window. The tier hard caps stay absolute
- * red lines.
- *
- * ## Why per commit, not against the baseline alone
- *
- * Measured against the committed baseline alone, the slack is spent cumulatively:
- * a long phase whose plans each grow a different file by a few hundred bytes goes
- * red part-way through, and from then on every plan re-baselines — the baseline
- * becomes a file every plan touches, which serialises plans that are otherwise
- * independent.
- *
- * ## Fallback
- *
- * Not a git checkout, or no HEAD: the check is the previous one — growth
- * against the committed baseline with the same two numbers (`assertDeltaBudget`),
- * new and removed files included. In a shallow clone, commits whose parent is
- * missing are skipped (CI's `test` job clones with GitLab's default depth).
- *
- * ## The numbers
- *
- * `size_budget.per_file_bytes` (default 1024) and `size_budget.per_commit_bytes`
- * (default 4096) — the schema defaults in
- * `pp-core/bin/shared/config-defaults.manifest.json`, overridable in the
- * repository's `.planning/config.json`. Nothing else holds them.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { execFileSync } = require('child_process');
-const { assertDeltaBudget } = require('./allowlist-ratchet.cjs');
-
-const REPO_ROOT = path.join(__dirname, '..', '..');
-const DEFAULTS_MANIFEST = path.join(REPO_ROOT, 'pp-core', 'bin', 'shared', 'config-defaults.manifest.json');
-
-function isPositiveInt(v) {
-  return Number.isInteger(v) && v > 0;
-}
-
-/**
- * The budget numbers: project `.planning/config.json` `size_budget.*` when set to
- * positive integers, else the schema defaults from the manifest.
- *
- * @param {{ repoRoot?: string, manifestPath?: string }} [opts]
- * @returns {{ perFileBytes: number, perCommitBytes: number, source: { perFileBytes: string, perCommitBytes: string } }}
- */
-function readSizeBudget({ repoRoot = REPO_ROOT, manifestPath = DEFAULTS_MANIFEST } = {}) {
-  const defaults = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')).size_budget;
-  if (!defaults || !isPositiveInt(defaults.per_file_bytes) || !isPositiveInt(defaults.per_commit_bytes)) {
-    throw new Error(`${manifestPath} must define size_budget.per_file_bytes and size_budget.per_commit_bytes as positive integers`);
-  }
-  let project = {};
-  try {
-    const cfg = JSON.parse(fs.readFileSync(path.join(repoRoot, '.planning', 'config.json'), 'utf-8'));
-    if (cfg && typeof cfg.size_budget === 'object' && cfg.size_budget !== null) project = cfg.size_budget;
-  } catch {
-    // no project config: schema defaults apply
-  }
-  const pick = (key) =>
-    isPositiveInt(project[key])
-      ? { value: project[key], source: '.planning/config.json' }
-      : { value: defaults[key], source: 'schema default' };
-  const perFile = pick('per_file_bytes');
-  const perCommit = pick('per_commit_bytes');
-  return {
-    perFileBytes: perFile.value,
-    perCommitBytes: perCommit.value,
-    source: { perFileBytes: perFile.source, perCommitBytes: perCommit.source },
-  };
-}
-
-// A GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE inherited from a hook would point git at
-// another repository; the guarded directory decides which repository is meant.
-function git(cwd, args) {
-  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_')));
-  return execFileSync('git', args, { cwd, env, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
-}
-
-/** Cap on how many commits back the guard looks (a re-baseline resets the window). */
-const MAX_COMMITS = 300;
-
-/**
- * The changes to judge, oldest first, or null when git cannot provide them (see
- * the Fallback section above). A change is one commit since the baseline file
- * was last committed — `before` is, per file, the larger of its sizes in the
- * commit's parents (so a merge commit adds nothing of its own) — plus the
- * uncommitted edits under `dir` against HEAD.
- *
- * @param {{ dir: string, include: (rel: string) => boolean, baselinePath?: string }} opts
- *   `dir` the guarded directory; `include` filters POSIX paths relative to it
- *   (the same keys the measurer produces); `baselinePath` the committed baseline
- *   (its last commit starts the window; untracked → the last MAX_COMMITS commits).
- * @returns {{ commits: Array<{ label: string, before: Object<string, number>, after: Object<string, number> }>,
- *             head: Object<string, number>, dirty: boolean, since: string | null } | null}
- */
-function commitChanges({ dir, include, baselinePath }) {
-  let top;
-  try {
-    top = git(dir, ['rev-parse', '--show-toplevel']).trim();
-    git(top, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
-  } catch {
-    return null;
-  }
-  const realTop = fs.realpathSync(top);
-  const rel = path.relative(realTop, fs.realpathSync(dir)).split(path.sep).join('/');
-  const pathspec = rel === '' ? '.' : rel;
-  const prefix = rel === '' ? '' : `${rel}/`;
-
-  const cache = new Map();
-  const sizesAt = (rev) => {
-    if (cache.has(rev)) return cache.get(rev);
-    let listing = null;
-    try {
-      listing = git(top, ['ls-tree', '-r', '-l', '--full-tree', rev, '--', pathspec]);
-    } catch {
-      listing = null; // object missing (shallow boundary)
-    }
-    let sizes = null;
-    if (listing !== null) {
-      sizes = {};
-      for (const line of listing.split('\n')) {
-        const m = /^\d+ blob [0-9a-f]+\s+(\d+)\t(.+)$/.exec(line);
-        if (!m || !m[2].startsWith(prefix)) continue;
-        const key = m[2].slice(prefix.length);
-        if (include(key)) sizes[key] = Number(m[1]);
-      }
-    }
-    cache.set(rev, sizes);
-    return sizes;
-  };
-
-  let since = null;
-  if (baselinePath) {
-    try {
-      const relBaseline = path.relative(realTop, fs.realpathSync(baselinePath)).split(path.sep).join('/');
-      since = git(top, ['log', '-1', '--format=%H', 'HEAD', '--', relBaseline]).trim() || null;
-    } catch {
-      since = null; // baseline outside the repository or not there
-    }
-  }
-  const range = since ? [`${since}..HEAD`] : ['HEAD'];
-  // No pathspec here: path-limited rev-list rewrites parents and prunes merges.
-  const lines = git(top, ['rev-list', '--reverse', `--max-count=${MAX_COMMITS}`, '--parents', ...range])
-    .split('\n')
-    .filter(Boolean);
-  const commits = [];
-  for (const line of lines) {
-    const [sha, ...parents] = line.split(' ');
-    const after = sizesAt(sha);
-    const parentSizes = parents.map(sizesAt);
-    if (after === null || parents.length === 0 || parentSizes.some((p) => p === null)) continue;
-    const before = {};
-    for (const p of parentSizes) {
-      for (const [k, v] of Object.entries(p)) before[k] = Math.max(before[k] ?? -1, v);
-    }
-    const subject = git(top, ['log', '-1', '--format=%s', sha]).trim();
-    commits.push({ label: `commit ${sha.slice(0, 9)} "${subject}"`, before, after });
-  }
-  const dirty = git(top, ['status', '--porcelain', '--untracked-files=all', '--', pathspec]).trim() !== '';
-  return { commits, head: sizesAt('HEAD') ?? {}, dirty, since };
-}
-
-/**
- * The per-commit budget check. Reports through `fail`; returns the measurement.
- *
- * @param {object} o
- * @param {string} o.label - prefix for messages, e.g. 'workflow-size'
- * @param {Object<string, number>} o.current - sizes now (working tree)
- * @param {Object<string, number>} o.baseline - committed baseline sizes
- * @param {ReturnType<typeof commitChanges>} o.changes - from `commitChanges`; null → baseline-only fallback
- * @param {{ perFileBytes: number, perCommitBytes: number }} o.budget - from `readSizeBudget`
- * @param {(msg: string) => void} o.fail
- * @param {string} [o.updateHint]
- */
-function assertCommitDeltaBudget({ label, current, baseline, changes, budget, fail, updateHint }) {
-  const hint = updateHint ? `\n${updateHint}` : '';
-  if (changes === null) {
-    return {
-      mode: 'baseline',
-      ...assertDeltaBudget({
-        label,
-        current,
-        baseline,
-        perFileSlack: budget.perFileBytes,
-        totalSlack: budget.perCommitBytes,
-        fail,
-        updateHint: `(No git history available: measured against the committed baseline only.)${hint}`,
-      }),
-    };
-  }
-
-  if (Object.keys(baseline).length === 0) {
-    fail(
-      `[${label}] the committed baseline has no size entries — an empty baseline would make ` +
-        `every growth check pass vacuously. Regenerate it with \`npm run size:baseline\`.`
-    );
-  }
-  for (const [name, v] of Object.entries(baseline)) {
-    if (!Number.isInteger(v) || v < 0) fail(`[${label}] baseline entry ${name} is not a non-negative integer byte size: ${JSON.stringify(v)}`);
-  }
-  const base = (name) => (Number.isInteger(baseline[name]) && baseline[name] >= 0 ? baseline[name] : -1);
-  const todo =
-    `Shrink it — move content into a lazily-read steps/ or references/ file — or, if the growth is needed, ` +
-    `record it: npm run size:baseline -- --reason "<why this growth is needed>" and commit the baseline. ` +
-    `Growth within the budget needs no baseline commit: the phase's closing commit re-baselines once ` +
-    `with --reason "phase NN close".`;
-  const fmt = (o) => `  - ${o.name}: ${o.from} → ${o.to} (+${o.delta})`;
-
-  const judged = [...changes.commits];
-  if (changes.dirty) judged.push({ label: 'the uncommitted changes', before: changes.head, after: current });
-  const results = [];
-  for (const change of judged) {
-    const overages = [];
-    for (const name of Object.keys(change.after).sort()) {
-      const from = Math.max(base(name), change.before[name] ?? -1);
-      if (from < 0) continue; // new file: bounded by the hard caps, recorded at phase close
-      const to = change.after[name];
-      if (to > from) overages.push({ name, from, to, delta: to - from });
-    }
-    const totalOverage = overages.reduce((sum, o) => sum + o.delta, 0);
-    const where = `in ${change.label} (measured against its parent, or the committed baseline when larger)`;
-    const overFile = overages.filter((o) => o.delta > budget.perFileBytes);
-    if (overFile.length > 0) {
-      fail(
-        `[${label}] ${overFile.length} file(s) grew more than the per-file slack of ${budget.perFileBytes} bytes ` +
-          `(size_budget.per_file_bytes) ${where}. ${todo}\n${overFile.map(fmt).join('\n')}${hint}`
-      );
-    }
-    if (totalOverage > budget.perCommitBytes) {
-      fail(
-        `[${label}] total growth ${where} is ${totalOverage} bytes, over the total slack of ` +
-          `${budget.perCommitBytes} bytes (size_budget.per_commit_bytes). ${todo}\n${overages.map(fmt).join('\n')}${hint}`
-      );
-    }
-    results.push({ change: change.label, overages, totalOverage });
-  }
-  const unrecorded = Object.keys(current).filter((n) => base(n) < 0).sort();
-  const removed = Object.keys(baseline).filter((n) => !Object.prototype.hasOwnProperty.call(current, n)).sort();
-  return { mode: 'commit', since: changes.since, results, unrecorded, removed };
-}
-
-/**
- * The whole guard for one tree, as the size-budget tests run it: read the
- * committed baseline, measure, list the changes, check the budget and the
- * `_rebaselines` log. Returns failure messages (empty = green).
- *
- * @param {object} o
- * @param {string} o.label - 'workflow-size' / 'agent-size'
- * @param {string} o.dir - guarded directory
- * @param {string} o.baselinePath - committed baseline JSON
- * @param {(dir: string) => Object<string, number>} o.measure - the measurer
- * @param {(rel: string) => boolean} o.include - which repository paths (relative to dir) the measurer covers
- * @param {{ perFileBytes: number, perCommitBytes: number }} [o.budget] - default: readSizeBudget()
- * @param {object|null} [o.changes] - default: commitChanges({ dir, include, baselinePath }); null = baseline-only
- * @param {string} [o.updateHint]
- * @returns {string[]}
- */
-function checkSizeBudget({ label, dir, baselinePath, measure, include, budget, changes, updateHint }) {
-  // Lazy: update-size-baseline.cjs is the baseline file format's owner.
-  const { readBaseline, splitBaseline, validateRebaselineLog, REBASELINES_KEY } = require('../update-size-baseline.cjs');
-  const failures = [];
-  const raw = readBaseline(baselinePath);
-  if (raw === null) {
-    failures.push(`baseline ${baselinePath} does not exist — run \`npm run size:baseline\``);
-  } else if (!(REBASELINES_KEY in raw)) {
-    failures.push(`baseline ${baselinePath} has no ${REBASELINES_KEY} log — run \`npm run size:baseline\``);
-  }
-  const { sizes, rebaselines } = splitBaseline(raw);
-  assertCommitDeltaBudget({
-    label,
-    current: measure(dir),
-    baseline: sizes,
-    changes: changes === undefined ? commitChanges({ dir, include, baselinePath }) : changes,
-    budget: budget ?? readSizeBudget(),
-    fail: (m) => failures.push(m),
-    updateHint,
-  });
-  for (const problem of validateRebaselineLog(rebaselines)) {
-    failures.push(`[${label}] invalid ${REBASELINES_KEY} log: ${problem}`);
-  }
-  return failures;
-}
-
-module.exports = { readSizeBudget, commitChanges, assertCommitDeltaBudget, checkSizeBudget, DEFAULTS_MANIFEST, MAX_COMMITS };