@pareto4/pp-core 1.13.0 → 1.18.0

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

@@ -1,483 +0,0 @@
-"use strict";
-/**
- * Dispatch plan — the single owner of what execute-phase spawns and runs.
- *
- * From the plan inventory (`phase-plan-index`: waves and serial groups from
- * src/plan-graph.cts) and the project's isolation settings, it computes, per
- * wave and in order:
- *
- *   - the executor spawns: ONE spawn per serial group, on the main checkout
- *     (no worktree), listing its plans in run order; one spawn per other plan,
- *     isolated in a worktree unless worktrees are off or the plan touches a
- *     git submodule path (the rule execute-phase applied per plan before);
- *   - whether each spawn needs a build: only when one of its plans touches a
- *     source file (`isSourceFile`, the plan-graph predicate);
- *   - the merge step, then exactly ONE full-suite run by the orchestrator after
- *     the merge, then exactly ONE STATE/ROADMAP/REQUIREMENTS tracking commit by
- *     the orchestrator;
- *   - planning defects: a source file shared by two plans of one wave, or any
- *     file shared by two plans in different spawns. A wave with a defect runs
- *     its spawns one at a time.
- *
- * Totals: spawn count, suite-run count, tracking-commit count, build count and
- * the SUMMARY.md files the phase is expected to produce.
- *
- * There is no spawn trace: workflows are markdown a model follows. This plan
- * is what execute-phase spawns ("spawn exactly the listed spawns"), so it is
- * the dry run that tests count.
- *
- * ## Stages
- *
- * Output is shaped as `stages: { plan, execute, verify }`. `stages.plan` and
- * `stages.verify` come from the phase's resolved ceremony tier
- * (`resolvePhaseTier` in src/phase-tier.cts, laid out by `computeTierStages`
- * here): researcher, pattern mapper,
- * planner (always) and plan checker passes; then code reviewer and fixer,
- * the heavy-tier install run (`phase.install-run`, src/install-run.cts),
- * verifier, security auditor, nyquist auditor and — heavy tier, vault
- * practices on — the agent practice review. `totals.spawns` counts every agent spawn of every stage, as an upper
- * bound: entries marked `conditional` run only when the step before them asks
- * for it (a revision after a failed check, a fix after review findings).
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.STAGE_AGENTS = void 0;
-exports.computeTierStages = computeTierStages;
-exports.submoduleIntersection = submoduleIntersection;
-exports.parseGitmodulesPaths = parseGitmodulesPaths;
-exports.computeDispatchPlan = computeDispatchPlan;
-exports.parseDispatchPlanArgs = parseDispatchPlanArgs;
-exports.resolveDispatchPolicy = resolveDispatchPolicy;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const plan_graph_cjs_1 = require("./plan-graph.cjs");
-// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
-const planningWorkspace = require("./planning-workspace.cjs");
-// eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
-const configLoaderMod = require("./config-loader.cjs");
-const { planningDir } = planningWorkspace;
-const { loadConfig } = configLoaderMod;
-/** Agent type names the stages spawn (each is a file under agents/). */
-exports.STAGE_AGENTS = Object.freeze({
-    researcher: 'pp-phase-researcher',
-    patternMapper: 'pp-pattern-mapper',
-    planner: 'pp-planner',
-    planChecker: 'pp-plan-checker',
-    verifier: 'pp-verifier',
-    codeReviewer: 'pp-code-reviewer',
-    codeFixer: 'pp-code-fixer',
-    nyquistAuditor: 'pp-nyquist-auditor',
-    securityAuditor: 'pp-security-auditor',
-    vaultReviewer: 'pp-vault-reviewer',
-});
-function spawn(id, agent, gate, reason, conditional = false) {
-    return { id, kind: 'spawn', agent, gate, reason, conditional };
-}
-function step(id, gate, reason) {
-    return { id, kind: 'step', agent: null, gate, reason, conditional: false };
-}
-/**
- * The planning and verification stages of a phase, from its resolved tier.
- * `planBounceScript`: bounce runs only with a configured script.
- * `vaultReview`: the project's vault practices apply (`vaultReviewApplies`,
- * src/vault.cts — the caller reads it); the agent practice review is spawned
- * only when that AND the tier's `vault_review` gate are both on.
- */
-function computeTierStages(tier, opts = {}) {
-    const g = tier.gates;
-    const plan = [];
-    if (g.research)
-        plan.push(spawn('plan-research', exports.STAGE_AGENTS.researcher, 'research', 'workflow.research is on for this tier'));
-    if (g.pattern_mapper)
-        plan.push(spawn('plan-patterns', exports.STAGE_AGENTS.patternMapper, 'pattern_mapper', 'workflow.pattern_mapper is on for this tier'));
-    plan.push(spawn('plan-planner', exports.STAGE_AGENTS.planner, 'planner', 'the planner always runs'));
-    if (g.plan_check) {
-        for (let pass = 1; pass <= g.plan_check_passes; pass++) {
-            if (pass > 1) {
-                plan.push(spawn(`plan-revise-${pass - 1}`, exports.STAGE_AGENTS.planner, 'plan_check', `revision ${pass - 1}: only when check pass ${pass - 1} found issues`, true));
-            }
-            plan.push(spawn(`plan-check-${pass}`, exports.STAGE_AGENTS.planChecker, 'plan_check', pass === 1 ? `check pass 1 of at most ${g.plan_check_passes}` : `check pass ${pass} of at most ${g.plan_check_passes}: after revision ${pass - 1}`, pass > 1));
-        }
-    }
-    if (g.plan_bounce && opts.planBounceScript) {
-        plan.push(step('plan-bounce', 'plan_bounce', `refine plans through workflow.plan_bounce_script, ${g.plan_bounce_passes} pass(es)`));
-        if (g.plan_check)
-            plan.push(spawn('plan-bounce-check', exports.STAGE_AGENTS.planChecker, 'plan_bounce', 're-check bounced plans; a plan that fails is restored', true));
-    }
-    if (g.post_planning_gaps)
-        plan.push(step('plan-gaps', 'post_planning_gaps', 'post-planning gap report (plan:post), non-blocking'));
-    const verify = [];
-    if (g.code_review) {
-        verify.push(spawn('verify-code-review', exports.STAGE_AGENTS.codeReviewer, 'code_review', 'code review of the phase source changes'));
-        verify.push(spawn('verify-code-fix', exports.STAGE_AGENTS.codeFixer, 'code_review', 'fix loop: only when the review finds issues', true));
-    }
-    // The install run goes first: the verifier judges the phase on its results file.
-    if (g.install_verification)
-        verify.push(step('verify-install', 'install_verification', 'pack, install into a temp project, init and run the phase install checks against the installed copy (phase.install-run → NN-INSTALL-RUN.json)'));
-    if (g.verifier)
-        verify.push(spawn('verify-goal', exports.STAGE_AGENTS.verifier, 'verifier', 'goal-backward phase verification (VERIFICATION.md)'));
-    if (g.security_enforcement)
-        verify.push(spawn('verify-security', exports.STAGE_AGENTS.securityAuditor, 'security_enforcement', 'threat-model verification (SECURITY.md)'));
-    if (g.nyquist_validation)
-        verify.push(spawn('verify-nyquist', exports.STAGE_AGENTS.nyquistAuditor, 'nyquist_validation', 'validation-gap audit (VALIDATION.md)'));
-    if (g.vault_review && opts.vaultReview === true) {
-        verify.push(spawn('verify-vault-review', exports.STAGE_AGENTS.vaultReviewer, 'vault_review', 'agent practice review of the client vault (VAULT-REVIEW.md); reports, never gates'));
-    }
-    return { plan, verify };
-}
-function normalizePath(file) {
-    return String(file).trim().replace(/\\/g, '/').replace(/^\.\//, '');
-}
-function stripEnds(p) {
-    return p.replace(/^\.\//, '').replace(/\/$/, '');
-}
-/**
- * Planned paths that touch a submodule (the per-plan worktree rule, #2772):
- * either side normalised (leading `./`, one trailing `/`), matched both ways
- * (planned path inside the submodule, or submodule inside the planned path),
- * and a globbed planned path matched by its literal prefix before the first
- * `*`, `?` or `[`.
- */
-function submoduleIntersection(planFiles, submodulePaths) {
-    const hits = new Set();
-    const inside = (a, b) => a === b || a.startsWith(`${b}/`);
-    for (const smRaw of submodulePaths) {
-        const sm = stripEnds(smRaw.trim());
-        if (sm === '')
-            continue;
-        for (const pfRaw of planFiles) {
-            const pf = stripEnds(String(pfRaw).trim());
-            if (pf === '')
-                continue;
-            let matched = inside(pf, sm) || inside(sm, pf);
-            if (!matched && /[*?[]/.test(pf)) {
-                const prefix = pf.slice(0, pf.search(/[*?[]/)).replace(/\/$/, '');
-                matched = prefix !== '' && (inside(sm, prefix) || inside(prefix, sm));
-            }
-            if (matched)
-                hits.add(String(pfRaw).trim());
-        }
-    }
-    return [...hits];
-}
-/** Submodule paths declared in a `.gitmodules` file's text. */
-function parseGitmodulesPaths(text) {
-    const paths = [];
-    let inSubmodule = false;
-    for (const line of text.split(/\r?\n/)) {
-        const section = /^\s*\[\s*([^\s\]]+)/.exec(line);
-        if (section) {
-            inSubmodule = section[1].toLowerCase() === 'submodule';
-            continue;
-        }
-        const kv = /^\s*path\s*=\s*(.+?)\s*$/i.exec(line);
-        if (inSubmodule && kv)
-            paths.push(kv[1].replace(/^"(.*)"$/, '$1'));
-    }
-    return paths;
-}
-function isolationFor(plan, policy) {
-    if (!policy.useWorktrees) {
-        return { isolation: 'main-checkout', reason: `worktrees off (workflow.use_worktrees=false, from ${policy.useWorktreesSource})` };
-    }
-    if (policy.submodulePaths.length > 0) {
-        const files = plan.files_modified.map((f) => String(f).trim()).filter((f) => f !== '');
-        if (files.length === 0) {
-            return { isolation: 'main-checkout', reason: 'files_modified missing/unparseable in a submodule project — no worktree, as a safety fallback' };
-        }
-        const hits = submoduleIntersection(files, policy.submodulePaths);
-        if (hits.length > 0) {
-            return { isolation: 'main-checkout', reason: `planned paths intersect submodule paths (${hits.join(' ')})` };
-        }
-    }
-    return { isolation: 'worktree', reason: 'independent plan: its own worktree' };
-}
-function summaryPath(phaseDir, id) {
-    return `${phaseDir}/${id === '' ? '' : `${id}-`}SUMMARY.md`;
-}
-function planEntry(plan, phaseDir) {
-    const files = plan.files_modified.map(normalizePath).filter((f) => f !== '');
-    return {
-        id: plan.id,
-        title: plan.title,
-        build: files.length === 0 || files.some(plan_graph_cjs_1.isSourceFile),
-        touched_tests: files.filter((f) => (0, plan_graph_cjs_1.classifyPlanFile)(f) === 'test'),
-        summary: summaryPath(phaseDir, plan.id),
-    };
-}
-function buildReason(plans) {
-    const reasons = [];
-    for (const p of plans) {
-        const files = p.files_modified.map(normalizePath).filter((f) => f !== '');
-        if (files.length === 0)
-            reasons.push(`${p.id}: files_modified not declared`);
-        else {
-            const src = files.filter(plan_graph_cjs_1.isSourceFile);
-            if (src.length > 0)
-                reasons.push(`${p.id} touches ${src.join(', ')}`);
-        }
-    }
-    return reasons.length > 0 ? reasons.join('; ') : 'no plan touches a source file';
-}
-function waveDefects(spawns, byId) {
-    const members = [];
-    for (const s of spawns) {
-        for (const p of s.plans) {
-            const plan = byId.get(p.id);
-            members.push({ id: p.id, spawn: s.id, files: new Set(plan.files_modified.map(normalizePath).filter((f) => f !== '')) });
-        }
-    }
-    const defects = [];
-    for (let i = 0; i < members.length; i++) {
-        for (let j = i + 1; j < members.length; j++) {
-            const a = members[i];
-            const b = members[j];
-            const shared = [...a.files].filter((f) => b.files.has(f)).sort();
-            if (shared.length === 0)
-                continue;
-            const source = shared.filter(plan_graph_cjs_1.isSourceFile);
-            if (source.length > 0) {
-                defects.push({
-                    kind: 'source-file-overlap',
-                    plans: [a.id, b.id],
-                    files: source,
-                    message: `Plan ${a.id} and Plan ${b.id} both modify source file(s) ${source.join(', ')} in one wave — a shared source file must order the plans into separate waves (planning defect).`,
-                });
-            }
-            else if (a.spawn !== b.spawn) {
-                defects.push({
-                    kind: 'cross-spawn-overlap',
-                    plans: [a.id, b.id],
-                    files: shared,
-                    message: `Plan ${a.id} and Plan ${b.id} both modify ${shared.join(', ')} but run in different spawns — they belong in one serial group (planning defect).`,
-                });
-            }
-        }
-    }
-    return defects;
-}
-/**
- * Compute the dispatch plan. `plans` are `phase-plan-index` rows in plan file
- * order; `phaseDir` is the phase directory relative to the project root.
- */
-function computeDispatchPlan(phase, phaseDir, plans, policy, tier = null, tierOpts = {}) {
-    const contributions = (tierOpts.executorContributions ?? []).map((c) => ({ capId: c.capId, fragment: c.fragment }));
-    const byId = new Map(plans.map((p) => [p.id, p]));
-    const skippedComplete = plans.filter((p) => p.has_summary).map((p) => p.id);
-    const incomplete = plans.filter((p) => !p.has_summary && (!policy.gapsOnly || p.gap_closure === true));
-    const selected = incomplete.filter((p) => policy.waveFilter === null || p.wave === policy.waveFilter);
-    const selectedIds = new Set(selected.map((p) => p.id));
-    const skippedByFilter = plans.filter((p) => !p.has_summary && !selectedIds.has(p.id)).map((p) => p.id);
-    const lowerWaveIncomplete = policy.waveFilter === null
-        ? []
-        : incomplete.filter((p) => p.wave < policy.waveFilter).map((p) => p.id);
-    const waveNumbers = [...new Set(selected.map((p) => p.wave))].sort((a, b) => a - b);
-    const waves = [];
-    for (const n of waveNumbers) {
-        const inWave = selected.filter((p) => p.wave === n);
-        const groupCounts = new Map();
-        for (const p of inWave)
-            if (p.serial_group)
-                groupCounts.set(p.serial_group, (groupCounts.get(p.serial_group) ?? 0) + 1);
-        const spawns = [];
-        const placedGroups = new Set();
-        for (const p of inWave) {
-            const group = p.serial_group && (groupCounts.get(p.serial_group) ?? 0) >= 2 ? p.serial_group : null;
-            if (group !== null) {
-                if (placedGroups.has(group))
-                    continue;
-                placedGroups.add(group);
-                const members = inWave.filter((q) => q.serial_group === group);
-                const entries = members.map((q) => planEntry(q, phaseDir));
-                spawns.push({
-                    id: `w${n}-s${spawns.length + 1}`,
-                    agent: 'pp-executor',
-                    kind: 'serial-group',
-                    serial_group: group,
-                    plans: entries,
-                    isolation: 'main-checkout',
-                    isolation_reason: `serial group ${group}: one executor runs its ${members.length} plans in order on the main checkout`,
-                    build: entries.some((e) => e.build),
-                    build_reason: buildReason(members),
-                    checkpoint: members.some((q) => !q.autonomous),
-                    expected_summaries: entries.map((e) => e.summary),
-                    contributions: contributions.map((c) => ({ ...c })),
-                });
-                continue;
-            }
-            const entry = planEntry(p, phaseDir);
-            const iso = isolationFor(p, policy);
-            spawns.push({
-                id: `w${n}-s${spawns.length + 1}`,
-                agent: 'pp-executor',
-                kind: 'plan',
-                serial_group: null,
-                plans: [entry],
-                isolation: iso.isolation,
-                isolation_reason: iso.reason,
-                build: entry.build,
-                build_reason: buildReason([p]),
-                checkpoint: !p.autonomous,
-                expected_summaries: [entry.summary],
-                contributions: contributions.map((c) => ({ ...c })),
-            });
-        }
-        const defects = waveDefects(spawns, byId);
-        const worktreeSpawns = spawns.filter((s) => s.isolation === 'worktree').length;
-        const run = defects.length > 0 || !policy.parallelization || spawns.length < 2 ? 'sequential' : 'parallel';
-        const runReason = defects.length > 0
-            ? 'planning defect: overlapping files_modified in this wave — run every spawn one at a time'
-            : !policy.parallelization
-                ? 'parallelization is off'
-                : spawns.length < 2
-                    ? 'one spawn'
-                    : 'worktree spawns run alongside each other; main-checkout spawns run one at a time';
-        const requirements = [...new Set(inWave.flatMap((p) => p.requirements ?? []))];
-        const expected = spawns.flatMap((s) => s.expected_summaries);
-        waves.push({
-            wave: n,
-            run,
-            run_reason: runReason,
-            spawns,
-            merge: { worktree_spawns: worktreeSpawns, cleanup: worktreeSpawns > 0 },
-            build: spawns.some((s) => s.build),
-            suite_runs: 1,
-            suite: { by: 'orchestrator', after: 'merge' },
-            tracking_commits: 1,
-            tracking: { by: 'orchestrator', plans: inWave.map((p) => p.id), requirements },
-            expected_summaries: expected,
-            defects,
-        });
-    }
-    const stages = tier ? computeTierStages(tier, tierOpts) : { plan: [], verify: [] };
-    const stagePlan = stages.plan;
-    const stageVerify = stages.verify;
-    const planSpawns = stagePlan.filter((e) => e.kind === 'spawn').length;
-    const verifySpawns = stageVerify.filter((e) => e.kind === 'spawn').length;
-    const executorSpawns = waves.flatMap((w) => w.spawns);
-    return {
-        phase,
-        phase_dir: phaseDir,
-        tier: tier ? { tier: tier.tier, source: tier.source, suppressed: tier.suppressed, gates: tier.gates } : null,
-        policy: {
-            use_worktrees: policy.useWorktrees,
-            use_worktrees_source: policy.useWorktreesSource,
-            parallelization: policy.parallelization,
-            submodule_paths: policy.submodulePaths,
-        },
-        filters: {
-            wave: policy.waveFilter,
-            gaps_only: policy.gapsOnly,
-            skipped_complete: skippedComplete,
-            skipped_by_filter: skippedByFilter,
-            lower_wave_incomplete: lowerWaveIncomplete,
-        },
-        stages: { plan: stagePlan, execute: { waves }, verify: stageVerify },
-        totals: {
-            waves: waves.length,
-            spawns: planSpawns + executorSpawns.length + verifySpawns,
-            plan_spawns: planSpawns,
-            verify_spawns: verifySpawns,
-            executor_spawns: executorSpawns.length,
-            main_checkout_spawns: executorSpawns.filter((s) => s.isolation === 'main-checkout').length,
-            isolated_spawns: executorSpawns.filter((s) => s.isolation === 'worktree').length,
-            builds: executorSpawns.filter((s) => s.build).length,
-            suite_runs: waves.reduce((sum, w) => sum + w.suite_runs, 0),
-            tracking_commits: waves.reduce((sum, w) => sum + w.tracking_commits, 0),
-            expected_summaries: waves.flatMap((w) => w.expected_summaries),
-            defects: waves.reduce((sum, w) => sum + w.defects.length, 0),
-        },
-    };
-}
-/** `<phase> [--wave N] [--gaps-only] [--use-worktrees true|false] [--tier light|standard|heavy]`. */
-function parseDispatchPlanArgs(args) {
-    const usage = 'Usage: phase dispatch-plan <phase> [--wave N] [--gaps-only] [--use-worktrees true|false] [--tier light|standard|heavy]';
-    let phase = null;
-    let waveFilter = null;
-    let gapsOnly = false;
-    let useWorktrees = null;
-    let tier = null;
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a === '--raw')
-            continue;
-        if (a === '--gaps-only') {
-            gapsOnly = true;
-            continue;
-        }
-        if (a === '--wave') {
-            const v = args[++i];
-            if (v === undefined || !/^\d+$/.test(v))
-                return { error: `--wave needs a wave number. ${usage}` };
-            waveFilter = parseInt(v, 10);
-            continue;
-        }
-        if (a === '--use-worktrees') {
-            const v = args[++i];
-            if (v !== 'true' && v !== 'false')
-                return { error: `--use-worktrees needs true or false. ${usage}` };
-            useWorktrees = v === 'true';
-            continue;
-        }
-        if (a === '--tier') {
-            const v = args[++i];
-            if (v !== 'light' && v !== 'standard' && v !== 'heavy')
-                return { error: `--tier needs light, standard or heavy. ${usage}` };
-            tier = v;
-            continue;
-        }
-        if (a.startsWith('--'))
-            return { error: `phase dispatch-plan does not support ${a}. ${usage}` };
-        if (phase !== null)
-            return { error: `phase dispatch-plan takes one phase. ${usage}` };
-        phase = a;
-    }
-    if (!phase)
-        return { error: `phase required for phase dispatch-plan. ${usage}` };
-    return { phase, waveFilter, gapsOnly, useWorktrees, tier };
-}
-/** Isolation and concurrency settings: CLI flag, then `.planning/config.json`, then defaults. */
-function resolveDispatchPolicy(cwd, args) {
-    let raw = {};
-    try {
-        raw = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'config.json'), 'utf-8'));
-    }
-    catch {
-        raw = {};
-    }
-    const workflow = (raw['workflow'] && typeof raw['workflow'] === 'object' ? raw['workflow'] : {});
-    let useWorktrees = true;
-    let useWorktreesSource = 'default';
-    if (args.useWorktrees !== null) {
-        useWorktrees = args.useWorktrees;
-        useWorktreesSource = 'cli';
-    }
-    else if (workflow['use_worktrees'] !== undefined) {
-        useWorktrees = workflow['use_worktrees'] !== false && workflow['use_worktrees'] !== 'false';
-        useWorktreesSource = 'config';
-    }
-    let parallelization = true;
-    try {
-        parallelization = loadConfig(cwd)['parallelization'] !== false;
-    }
-    catch {
-        parallelization = true;
-    }
-    let submodulePaths = [];
-    try {
-        submodulePaths = parseGitmodulesPaths(node_fs_1.default.readFileSync(node_path_1.default.join(cwd, '.gitmodules'), 'utf-8'));
-    }
-    catch {
-        submodulePaths = [];
-    }
-    return {
-        useWorktrees,
-        useWorktreesSource,
-        parallelization,
-        submodulePaths,
-        waveFilter: args.waveFilter,
-        gapsOnly: args.gapsOnly,
-    };
-}