@pareto4/pp-core 1.12.1 → 1.17.1

package/pp-core/bin/lib/plan-graph.cjs

@@ -1,368 +0,0 @@
-"use strict";
-/**
- * Plan graph — the single owner of how a phase's plans are ordered.
- *
- * Computes, from each PLAN.md's frontmatter (`depends_on`, `files_modified`,
- * `serial_group`, `chain_reason`, task shapes):
- *
- *   - the wave of every plan;
- *   - the serial groups (plans that share a wave but must run one after
- *     another because they touch the same non-source file);
- *   - the chain metrics (plan count, wave count, longest chain, and how many
- *     links of that chain exist only because two plans touch the same
- *     non-source file);
- *   - the chain check the plan checker enforces (a longest chain longer than
- *     half the plan count FAILS unless every link of it carries a recorded
- *     `chain_reason`);
- *   - same-shape merge candidates for the planner.
- *
- * Callers: `phase-plan-index` (src/phase.cts) adds this to the plan inventory.
- * The planner and plan-checker agents read that output; they never compute a
- * wave or a chain themselves.
- *
- * ## The wave rule
- *
- * A plan's wave is its longest-path level over two kinds of edges:
- *   1. declared `depends_on` edges;
- *   2. implicit edges between two plans that share a SOURCE file (see
- *      `classifyPlanFile`) and are not already ordered by (1). The implicit
- *      edge runs from the earlier plan (file order) to the later one.
- * Two plans that share only NON-source files (a test file, a size baseline, a
- * changeset, a doc, a planning file) get no edge: they stay in the same wave
- * and are put in one serial group instead.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PLAN_TASK_CAP = exports.PLAN_TITLE_MAX = void 0;
-exports.classifyPlanFile = classifyPlanFile;
-exports.isInstructionFile = isInstructionFile;
-exports.isSourceFile = isSourceFile;
-exports.planTitleProblem = planTitleProblem;
-exports.readPlanTitle = readPlanTitle;
-exports.computePlanGraph = computePlanGraph;
-const SOURCE_DIRS = ['src/', 'bin/', 'pp-core/bin/', 'hooks/', 'scripts/'];
-const DOC_EXTENSIONS = /\.(md|mdx|markdown|rst|txt|adoc)$/i;
-const DOC_BASENAMES = /^(LICENSE|NOTICE|CHANGELOG|AUTHORS)(\.[a-z]+)?$/i;
-function normalizePath(file) {
-    return String(file).trim().replace(/\\/g, '/').replace(/^\.\//, '');
-}
-/**
- * Classify one `files_modified` entry. This is THE source/non-source predicate
- * for plan ordering; nothing else decides it.
- *
- * Checked in this order (first match wins):
- *   planning  — under `.planning/`
- *   changeset — under `.changeset/` or `.changesets/`
- *   baseline  — a `*baseline*.json`/`*.baseline.*` file, `__snapshots__/`, `*.snap`
- *   test      — under a `test/`, `tests/` or `__tests__/` directory or a
- *               `*.Tests/` project; or named `*.test.*`, `*.spec.*`,
- *               `*_test.go|py`, `test_*.py`
- *   source    — under `src/`, `bin/`, `pp-core/bin/`, `hooks/` or `scripts/`
- *               (pp-core ships executable code from these)
- *   doc       — a `.md/.mdx/.markdown/.rst/.txt/.adoc` file, anything under
- *               `docs/` or `doc/`, or LICENSE/NOTICE/CHANGELOG/AUTHORS. In
- *               pp-core this includes workflow, agent, reference and template
- *               markdown.
- *   source    — anything else. An unrecognised file is treated as source, so
- *               it keeps the strict "shared file = later wave" rule.
- */
-function classifyPlanFile(file) {
-    const p = normalizePath(file);
-    const base = p.split('/').pop() ?? p;
-    if (p.startsWith('.planning/'))
-        return 'planning';
-    if (/^\.changesets?\//.test(p))
-        return 'changeset';
-    if (/baseline[^/]*\.json$/i.test(base) || /\.baseline\./i.test(base) || /(^|\/)__snapshots__\//.test(p) || /\.snap$/i.test(base)) {
-        return 'baseline';
-    }
-    if (/(^|\/)(tests?|__tests__)\//.test(p) ||
-        /(^|\/)[^/]+\.Tests?\//.test(p) ||
-        /\.(test|spec)\.[^/]+$/i.test(base) ||
-        /_test\.(go|py)$/i.test(base) ||
-        /^test_[^/]*\.py$/i.test(base)) {
-        return 'test';
-    }
-    if (SOURCE_DIRS.some((dir) => p.startsWith(dir)))
-        return 'source';
-    if (DOC_EXTENSIONS.test(base) || /^docs?\//.test(p) || DOC_BASENAMES.test(base))
-        return 'doc';
-    return 'source';
-}
-/** A workflow or agent markdown file (the unit same-shape plans are made of). */
-function isInstructionFile(file) {
-    const p = normalizePath(file);
-    return /\.md$/i.test(p) && (/(^|\/)workflows\//.test(p) || /(^|\/)agents\//.test(p));
-}
-/** True when `file` is a source file for plan ordering (see `classifyPlanFile`). */
-function isSourceFile(file) {
-    return classifyPlanFile(file) === 'source';
-}
-/** Longest a plan title may be before it is reported (still valid). */
-exports.PLAN_TITLE_MAX = 100;
-/**
- * Problem with a plan's `title:` frontmatter value, or null when it is a valid
- * one-line title. `undefined` means the key is absent.
- */
-function planTitleProblem(value) {
-    if (value === undefined)
-        return 'Missing required frontmatter field: title';
-    if (typeof value !== 'string' || value.trim() === '') {
-        return 'Frontmatter field title must be a non-empty one-line string';
-    }
-    if (/[\r\n]/.test(value))
-        return 'Frontmatter field title must be one line';
-    return null;
-}
-/** Normalised title, or null when absent/invalid. */
-function readPlanTitle(value) {
-    return planTitleProblem(value) === null ? value.trim() : null;
-}
-/** Default task cap per plan (agents/pp-planner.md: "Each plan: 2-3 tasks maximum."). */
-exports.PLAN_TASK_CAP = 3;
-function slug(text) {
-    return text.toLowerCase().replace(/\.[a-z0-9]+$/i, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'group';
-}
-function intersect(a, b) {
-    return [...new Set(a.filter((f) => b.has(f)))].sort();
-}
-/**
- * Compute the plan graph. `nodes` must be in plan file order (that order
- * breaks ties and orients implicit edges).
- */
-function computePlanGraph(nodes, opts = {}) {
-    const taskCap = opts.taskCap ?? exports.PLAN_TASK_CAP;
-    const ids = nodes.map((n) => n.id);
-    const index = new Map(ids.map((id, i) => [id, i]));
-    const files = nodes.map((n) => n.filesModified.map(normalizePath).filter((f) => f !== ''));
-    const fileSets = files.map((f) => new Set(f));
-    const warnings = [];
-    // Adjacency over indices: edges[i] = successors of i.
-    const succ = nodes.map(() => new Set());
-    nodes.forEach((n, j) => {
-        for (const dep of n.dependsOn) {
-            const i = index.get(dep);
-            if (i === undefined || i === j)
-                continue;
-            succ[i].add(j);
-        }
-    });
-    const levelsOf = () => {
-        const inDeg = nodes.map(() => 0);
-        succ.forEach((s) => s.forEach((j) => { inDeg[j]++; }));
-        const level = nodes.map(() => 0);
-        const queue = [];
-        inDeg.forEach((d, i) => { if (d === 0)
-            queue.push(i); });
-        let head = 0;
-        while (head < queue.length) {
-            const cur = queue[head++];
-            for (const nxt of [...succ[cur]].sort((a, b) => a - b)) {
-                level[nxt] = Math.max(level[nxt], level[cur] + 1);
-                if (--inDeg[nxt] === 0)
-                    queue.push(nxt);
-            }
-        }
-        return { level, done: new Set(queue) };
-    };
-    // A declared cycle has no waves; nodes Kahn never dequeued are on or behind it.
-    const declaredLevels = levelsOf();
-    if (declaredLevels.done.size < nodes.length) {
-        return emptyGraph(nodes, ids.filter((_, i) => !declaredLevels.done.has(i)));
-    }
-    const reaches = (from, to) => {
-        const stack = [from];
-        const seen = new Set([from]);
-        while (stack.length > 0) {
-            const cur = stack.pop();
-            if (cur === to)
-                return true;
-            for (const nxt of succ[cur]) {
-                if (!seen.has(nxt)) {
-                    seen.add(nxt);
-                    stack.push(nxt);
-                }
-            }
-        }
-        return false;
-    };
-    // Implicit edges: a shared SOURCE file orders two otherwise-unordered plans.
-    const implicitEdges = [];
-    for (let i = 0; i < nodes.length; i++) {
-        for (let j = i + 1; j < nodes.length; j++) {
-            const sharedSource = intersect(files[j], fileSets[i]).filter(isSourceFile);
-            if (sharedSource.length === 0)
-                continue;
-            if (reaches(i, j) || reaches(j, i))
-                continue;
-            succ[i].add(j);
-            implicitEdges.push({ from: ids[i], to: ids[j], shared_source_files: sharedSource });
-        }
-    }
-    const { level } = levelsOf();
-    // Same-shape merge candidates: no source file, exactly one workflow/agent file
-    // (any other files are tests, baselines, changesets or planning), same task shape.
-    const shapeGroups = new Map();
-    nodes.forEach((n, i) => {
-        if (n.taskTypes.length === 0)
-            return;
-        const kinds = files[i].map(classifyPlanFile);
-        if (kinds.includes('source'))
-            return;
-        if (files[i].filter(isInstructionFile).length !== 1 || kinds.filter((k) => k === 'doc').length !== 1)
-            return;
-        const shape = n.taskTypes.join('+');
-        if (!shapeGroups.has(shape))
-            shapeGroups.set(shape, []);
-        shapeGroups.get(shape).push(i);
-    });
-    const mergeCandidates = [];
-    for (const [shape, members] of shapeGroups) {
-        if (members.length < 2)
-            continue;
-        const totalTasks = members.reduce((sum, i) => sum + nodes[i].taskTypes.length, 0);
-        mergeCandidates.push({
-            shape,
-            plans: members.map((i) => ids[i]),
-            total_tasks: totalTasks,
-            task_cap: taskCap,
-            action: totalTasks <= taskCap ? 'merge' : 'serial_group',
-        });
-    }
-    // Serial groups: union-find within each level.
-    const parent = nodes.map((_, i) => i);
-    const find = (x) => (parent[x] === x ? x : (parent[x] = find(parent[x])));
-    const union = (a, b) => {
-        const ra = find(a);
-        const rb = find(b);
-        if (ra !== rb)
-            parent[Math.max(ra, rb)] = Math.min(ra, rb);
-    };
-    for (let i = 0; i < nodes.length; i++) {
-        for (let j = i + 1; j < nodes.length; j++) {
-            if (level[i] !== level[j])
-                continue;
-            const shared = intersect(files[j], fileSets[i]);
-            const sameDeclared = nodes[i].serialGroup !== null && nodes[i].serialGroup === nodes[j].serialGroup;
-            if (shared.length > 0 || sameDeclared)
-                union(i, j);
-        }
-    }
-    for (const cand of mergeCandidates) {
-        if (cand.action !== 'serial_group')
-            continue;
-        const members = cand.plans.map((id) => index.get(id));
-        for (const a of members)
-            for (const b of members)
-                if (a < b && level[a] === level[b])
-                    union(a, b);
-    }
-    const groupsByRoot = new Map();
-    nodes.forEach((_, i) => {
-        const r = find(i);
-        if (!groupsByRoot.has(r))
-            groupsByRoot.set(r, []);
-        groupsByRoot.get(r).push(i);
-    });
-    const serialGroupOf = Object.fromEntries(ids.map((id) => [id, null]));
-    const serialGroups = [];
-    const usedNames = new Set();
-    const roots = [...groupsByRoot.keys()].sort((a, b) => a - b);
-    for (const root of roots) {
-        const members = groupsByRoot.get(root).sort((a, b) => a - b);
-        if (members.length < 2)
-            continue;
-        const sharedFiles = new Set();
-        for (const a of members)
-            for (const b of members)
-                if (a < b)
-                    intersect(files[b], fileSets[a]).forEach((f) => sharedFiles.add(f));
-        const shared = [...sharedFiles].sort();
-        const declaredName = members.map((i) => nodes[i].serialGroup).find((g) => !!g);
-        let name = declaredName ?? `w${level[root] + 1}-${shared.length > 0 ? slug(shared[0].split('/').pop()) : 'same-shape'}`;
-        if (usedNames.has(name)) {
-            let k = 2;
-            while (usedNames.has(`${name}-${k}`))
-                k++;
-            name = `${name}-${k}`;
-        }
-        usedNames.add(name);
-        for (const i of members)
-            serialGroupOf[ids[i]] = name;
-        serialGroups.push({ name, level: level[root], plans: members.map((i) => ids[i]), shared_files: shared });
-    }
-    nodes.forEach((n, i) => {
-        if (n.serialGroup && serialGroupOf[ids[i]] !== n.serialGroup) {
-            warnings.push(`Plan ${ids[i]}: declares serial_group: ${n.serialGroup} but the plan graph puts it in ` +
-                `${serialGroupOf[ids[i]] ?? 'no serial group'} (a serial group only holds plans of one wave).`);
-        }
-    });
-    // Longest chain (by plan count) over the full DAG.
-    const order = ids.map((_, i) => i).sort((a, b) => level[a] - level[b] || a - b);
-    const best = nodes.map(() => 1);
-    const prev = nodes.map(() => null);
-    const preds = nodes.map(() => []);
-    succ.forEach((s, i) => s.forEach((j) => preds[j].push(i)));
-    for (const j of order) {
-        for (const i of preds[j].sort((a, b) => a - b)) {
-            if (best[i] + 1 > best[j]) {
-                best[j] = best[i] + 1;
-                prev[j] = i;
-            }
-        }
-    }
-    let end = -1;
-    nodes.forEach((_, i) => { if (end === -1 || best[i] > best[end])
-        end = i; });
-    const chain = [];
-    for (let cur = end; cur !== null && cur !== -1; cur = prev[cur])
-        chain.unshift(cur);
-    const links = [];
-    for (let k = 1; k < chain.length; k++) {
-        const a = chain[k - 1];
-        const b = chain[k];
-        const shared = intersect(files[b], fileSets[a]);
-        const kind = shared.some(isSourceFile) ? 'source-file' : shared.length > 0 ? 'non-source-file' : 'declared';
-        links.push({ from: ids[a], to: ids[b], kind, shared_files: shared, reason: nodes[b].chainReason });
-    }
-    const nonSourceLinks = links.filter((l) => l.kind === 'non-source-file').length;
-    const limit = nodes.length / 2;
-    const unreasoned = links.filter((l) => !l.reason).map((l) => ({ from: l.from, to: l.to, kind: l.kind }));
-    const passed = chain.length <= limit || unreasoned.length === 0;
-    const waveCount = nodes.length === 0 ? 0 : Math.max(...level) + 1;
-    const message = passed
-        ? `longest chain ${chain.length} of ${nodes.length} plans (limit ${limit})` +
-            (chain.length > limit ? ' — every link has a chain_reason' : '')
-        : `longest chain is ${chain.length} plans, over half the plan count (${nodes.length} plans, limit ${limit}), ` +
-            `and ${unreasoned.length} link(s) have no chain_reason: ${unreasoned.map((l) => `${l.from}->${l.to} (${l.kind})`).join(', ')}. ` +
-            `Drop depends_on edges that exist only because two plans touch the same non-source file ` +
-            `(they share a wave in a serial group instead), merge same-shape plans, or record a ` +
-            `chain_reason on each later plan saying why it must wait.`;
-    return {
-        cycle: null,
-        level: Object.fromEntries(ids.map((id, i) => [id, level[i]])),
-        serialGroupOf,
-        serialGroups,
-        implicitEdges,
-        plan_count: nodes.length,
-        wave_count: waveCount,
-        longest_chain: { length: chain.length, plans: chain.map((i) => ids[i]), links, non_source_links: nonSourceLinks },
-        chain_check: { passed, limit, unreasoned_links: passed ? [] : unreasoned, message },
-        merge_candidates: mergeCandidates,
-        warnings,
-    };
-}
-function emptyGraph(nodes, cycle) {
-    return {
-        cycle,
-        level: {},
-        serialGroupOf: Object.fromEntries(nodes.map((n) => [n.id, null])),
-        serialGroups: [],
-        implicitEdges: [],
-        plan_count: nodes.length,
-        wave_count: 0,
-        longest_chain: { length: 0, plans: [], links: [], non_source_links: 0 },
-        chain_check: { passed: false, limit: nodes.length / 2, unreasoned_links: [], message: `depends_on cycle: ${cycle.join(', ')}` },
-        merge_candidates: [],
-        warnings: [],
-    };
-}

package/pp-core/references/planner-plan-graph.md

@@ -1,66 +0,0 @@
-# Planner — plan graph: waves, serial groups, chains, titles
-
-Read this in `assign_waves`. The plan graph is computed by `pp_run query phase-plan-index <phase>`
-(`src/plan-graph.cts`); you never hand-compute a wave or a chain. You write `depends_on`, `files_modified`,
-`title`, and when needed `chain_reason`; the query computes the rest.
-
-## What you write in `depends_on`
-
-Only real dependencies: plan B needs something plan A creates (a type, an API, a file's new content it reads).
-Do NOT add a `depends_on` edge because two plans touch the same file.
-
-## Source vs non-source files
-
-The query classifies each `files_modified` entry (first match wins):
-
-| Kind | Files |
-|------|-------|
-| planning | `.planning/**` |
-| changeset | `.changeset/**` |
-| baseline | `*baseline*.json`, `*.baseline.*`, `__snapshots__/`, `*.snap` |
-| test | `test/`, `tests/`, `__tests__/`, `*.Tests/` dirs; `*.test.*`, `*.spec.*`, `*_test.go`, `test_*.py` |
-| source | `src/`, `bin/`, `pp-core/bin/`, `hooks/`, `scripts/` |
-| doc | `.md`/`.mdx`/`.rst`/`.txt`/`.adoc`, `docs/`, LICENSE/NOTICE/CHANGELOG (in pp-core: workflow, agent and reference markdown) |
-| source | anything else |
-
-## The rules the query applies
-
-1. **Shared source file → later wave.** Two plans that share a source file and are not already ordered by
-   `depends_on` get an implicit edge (earlier plan file first). Unchanged from the old rule.
-2. **Shared non-source file only → same wave, one serial group.** Plans in the same wave that share only
-   tests, baselines, changesets, docs or planning files stay in that wave with a computed `serial_group`.
-   One executor runs a serial group's plans one after another, in plan order.
-3. **Same-shape plans** (same task types, each on exactly one workflow/agent file, no source file) are listed
-   in `graph.merge_candidates`. `action: merge` → fold them into one plan (they fit the 3-task cap).
-   `action: serial_group` → keep them as plans; the query puts those in one wave in one serial group.
-4. **Chain check.** `graph.chain_check.passed` is false when the longest chain is longer than half the plan
-   count and a link of it has no `chain_reason`. Fix it by dropping `depends_on` edges that exist only for a
-   shared non-source file, merging same-shape plans, or — when the order is real — writing on the later plan
-   `chain_reason: "<one line: what it needs from the plan before it>"`.
-
-## Frontmatter you write back
-
-After the query: set each plan's `wave:` to its computed `wave`, and `serial_group:` to its computed
-`serial_group` (omit the key when null). Use `pp_run query frontmatter.set <plan> wave <N>` /
-`... serial_group <name>`.
-
-## Print before you return
-
-```
-Plan graph: {plan_count} plans · {wave_count} waves · longest chain {longest_chain.length}
-({longest_chain.non_source_links} linked only by a non-source file) · chain check {passed|FAILED}
-```
-
-## Size baselines
-
-Never list `tests/*-size-baseline.json` in `files_modified` or put a `size:baseline` step in a plan. Each commit
-is checked against a per-commit budget (`size_budget.*` in config); execute-phase re-baselines once, in the
-phase's closing commit (`--reason "phase NN close"`). A plan whose design needs more growth than the budget says
-so in its task, and that task records it with `npm run size:baseline -- --reason "<why>"`.
-
-## Titles
-
-Every PLAN.md has `title:` — one line, what the plan delivers (e.g. `title: "Plan graph in phase-plan-index"`).
-`verify.plan-structure` and `frontmatter.validate --schema plan` fail a plan without one. Plans that already
-have a SUMMARY only warn. The inventory query prints the title; execute-phase's wave table and executor
-brief use it.

package/pp-core/workflows/execute-phase/steps/checkpoint-handling.md

@@ -1,45 +0,0 @@
-# Checkpoint handling (execute-phase `checkpoint_handling` step)
-
-Read by `execute-phase.md` when an executor returns a checkpoint (plans with
-`autonomous: false`, or an auth gate). Extracted verbatim so the host loop stays
-under its size ceiling; nothing here runs unless a checkpoint is returned.
-
-**Auto-mode checkpoint handling:**
-Read auto-advance config (chain flag OR user preference — same boolean as `check.auto-mode`):
-```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
-AUTO_MODE=$(pp_run query check auto-mode --pick active 2>/dev/null || echo "false")
-```
-
-When executor returns a checkpoint AND (`UNATTENDED` or `AUTO_MODE`) is true (U-E1):
-- **human-action**, or package legitimacy — ANY of `**Gate:** blocking-human` in the return (the executor copies the task's `gate` attribute there), `gate="blocking-human"`, or `what-built` begins `Package`; the last two are the fallback for a return that predates the `Gate:` line → hard stop: present to user (below).
-- **human-verify** (other) → continuation with `{user_response}` = `"DEFERRED — not verified by a human (unattended run); record this checkpoint as not done in the SUMMARY and continue"`; log `⏭ Checkpoint deferred (recorded, not approved)`.
-- **decision** → continuation with the option marked recommended, else the first; log `⚡ Auto-selected: [option]`.
-
-**Standard flow (neither flag, human-action, or blocking-human):**
-
-1. Spawn agent for checkpoint plan
-2. Agent runs until checkpoint task or auth gate → returns structured state
-3. Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited
-4. **Present to user:**
-   ```
-   ## Checkpoint: [Type]
-
-   **Plan:** 03-03 Dashboard Layout
-   **Progress:** 2/3 tasks complete
-
-   [Checkpoint Details from agent return]
-   [Awaiting section from agent return]
-   ```
-5. User responds: "approved"/"done" | issue description | decision selection
-6. **Spawn continuation agent (NOT resume)** using continuation-prompt.md template:
-   - `{completed_tasks_table}`: From checkpoint return
-   - `{resume_task_number}` + `{resume_task_name}`: Current task
-   - `{user_response}`: What user provided
-   - `{resume_instructions}`: Based on checkpoint type
-7. Continuation agent verifies previous commits, continues from resume point
-8. Repeat until plan completes or user stops
-
-**Fresh agent, not resume:** resume breaks with parallel tool calls.
-
-**Checkpoints in parallel waves:** Agent pauses and returns while other parallel agents may complete. Present checkpoint, spawn continuation, wait for all before next wave.

package/pp-core/workflows/execute-phase/steps/install-run.md

@@ -1,29 +0,0 @@
-# Install run — execute-phase step (heavy tier)
-
-Runs only when `DISPATCH_PLAN.stages.verify` lists `verify-install` (heavy tier). Verification of a heavy
-phase measures the installed product, not the repository: `phase.install-run` builds and packs the
-package, installs the tarball into a temp project with the installer the user runs
-(`pp-core --claude --local`, temp HOME), runs init there, then runs the phase's install checks against
-the INSTALLED `pp-tools` — never the repository's. The checks are the phase's ROADMAP
-`**Install check:**` line (backticked `pp-tools …` commands); without it, a default smoke set runs.
-
-```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
-INSTALL_RUN=$(pp_run query phase.install-run "${PHASE_NUMBER}")
-INSTALL_VERDICT=$(printf '%s' "$INSTALL_RUN" | jq -r '.verdict')
-INSTALL_RUN_FILE=$(printf '%s' "$INSTALL_RUN" | jq -r '.results_file')
-echo "install run: ${INSTALL_VERDICT} — $(printf '%s' "$INSTALL_RUN" | jq -r '.reason')"
-```
-
-The results file (`{phase_dir}/{phase_num}-INSTALL-RUN.json`) holds the tarball name and version, every
-command with its exit code and truncated output, `failures[]` and the verdict. Do not re-run the commands
-yourself and do not edit the file.
-
-- `pass` / `not_applicable` (not a pp-core package): continue to the verifier.
-- `fail`: the phase cannot pass verification. Print each `failures[]` entry (stage, command, exit code).
-
-When the verifier is spawned, add this line to its `<files_to_read>` block:
-`- {INSTALL_RUN_FILE} (installed-product run — judge user-facing behaviour on it, not on the repo)`.
-
-When the verifier is NOT listed and the verdict is `fail`: do not mark the phase passed. Present the
-failures as the gaps and offer `/pp-plan-phase {phase} --gaps`.

package/pp-core/workflows/execute-phase/steps/phase-close-rebaseline.md

@@ -1,23 +0,0 @@
-# Phase-close size re-baseline — execute-phase step
-
-Plans never run `size:baseline`: each commit is checked against a per-commit size budget
-(`size_budget.per_file_bytes` / `size_budget.per_commit_bytes`). The phase's growth is recorded once,
-here, in the phase's closing commit, after every wave, the code-review fixes and the regression gate.
-
-Applies only when the project defines a `size:baseline` npm script (pp-core's own repository). Elsewhere
-this step does nothing.
-
-```bash
-if node -e "process.exit((require('./package.json').scripts || {})['size:baseline'] ? 0 : 1)" 2>/dev/null; then
-  npm run size:baseline -- --reason "phase ${PHASE_NUMBER} close" || {
-    echo "size:baseline failed — fix before completing phase ${PHASE_NUMBER}" >&2; exit 1; }
-  CHANGED_BASELINES=$(git diff --name-only -- 'tests/*-size-baseline.json')
-  if [ -n "$CHANGED_BASELINES" ]; then
-    git add -- $CHANGED_BASELINES
-    git commit -m "chore(phase-${PHASE_NUMBER}): re-baseline workflow and agent sizes at phase close"
-  fi
-fi
-```
-
-The `_rebaselines` entry this writes lists every file the phase grew, with its delta — the review record for
-the phase's growth. Nothing to commit means the phase grew nothing past the baseline.

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

@@ -1,72 +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}
-
-    <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.