@pareto4/pp-core 1.13.0 → 1.17.1

package/pp-core/bin/lib/phase-tier.cjs

@@ -1,480 +0,0 @@
-"use strict";
-/**
- * Phase tier — the single owner of how much ceremony a phase runs.
- *
- * A tier is a named preset over the existing gate booleans
- * `workflow.{research, pattern_mapper, plan_check, verifier,
- * nyquist_validation, code_review, post_planning_gaps, security_enforcement,
- * vault_review}`:
- *
- *   light    — planner and executor only; every gate off.
- *   standard — verifier and code review (with its fix loop) on, plan checker
- *              ONE pass and no bounce; everything else off. Schema default.
- *   heavy    — every gate on, the plan-checker loop up to its maximum
- *              (`PLAN_CHECK_MAX_PASSES`, the plan-phase revision cap), plan
- *              bounce on, and the fresh-install verification slot
- *              (`install_verification`).
- *
- * `vault_review` is the agent practice review (`pp-vault-reviewer`): on only in
- * heavy, and spawned only where the project's vault practices apply
- * (`vaultReviewApplies`, src/vault.cts). The vault's load, trace and audit gates
- * are NOT tier gates: they are cheap code checks and run in every tier.
- *
- * ## Precedence (`resolvePhaseTier`)
- *
- *   CLI `--tier` > the phase's ROADMAP entry `**Tier:**` field > project
- *   `phase.tier` in `.planning/config.json` > schema default `standard`.
- *
- * The ROADMAP entry is the ONE owner of the phase field: it exists for every
- * phase before discuss runs, and a light phase may skip discuss (so a
- * CONTEXT.md field would be missing exactly where it matters).
- *
- * A gate boolean the project EXPLICITLY sets to `false` in its own config
- * wins over every tier (listed in `suppressed` when the tier wanted it on). A
- * boolean the project explicitly sets to `true` does NOT force it on: the tier
- * decides on-ness; the project can only switch a gate off. "Explicit" means
- * present in the project's own config.json (workstream, then root) — a value
- * inherited from the manifest default is not explicit.
- *
- * ## Proposal (`proposePhaseTier`)
- *
- *   heavy    — a plan touches a gate (the vault's gate, verdict and redaction
- *              owners included), init, redaction, config-precedence or
- *              hook-dispatch file (`HEAVY_PATH_RULES`), or — before any plan
- *              exists — the requirement tags or ROADMAP text name one
- *              (`HEAVY_TEXT_RULES`);
- *   light    — plans exist and none touches a source file (`isSourceFile`,
- *              the plan-graph predicate);
- *   standard — otherwise.
- *
- * Readers: `init plan-phase` / `init execute-phase` / `init verify-work`,
- * `loop render-hooks --phase`, `phase.dispatch-plan`, `phase.tier` and
- * `phase.tier-propose`. Workflows never resolve a tier themselves.
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HEAVY_TEXT_RULES = exports.HEAVY_PATH_RULES = exports.TIER_PRESETS = exports.DEFAULT_PLAN_BOUNCE_PASSES = exports.PLAN_CHECK_MAX_PASSES = exports.TIER_GATE_KEYS = exports.SCHEMA_DEFAULT_TIER = exports.PHASE_TIERS = void 0;
-exports.isPhaseTier = isPhaseTier;
-exports.resolvePhaseTier = resolvePhaseTier;
-exports.heavyCategoryForPath = heavyCategoryForPath;
-exports.proposePhaseTier = proposePhaseTier;
-exports.readProjectTierConfig = readProjectTierConfig;
-exports.parsePhaseTierField = parsePhaseTierField;
-exports.readPhaseRecord = readPhaseRecord;
-exports.resolvePhaseTierForProject = resolvePhaseTierForProject;
-exports.overlayTierGates = overlayTierGates;
-exports.recordPhaseTier = recordPhaseTier;
-exports.parseTierFlag = parseTierFlag;
-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
-const planningWorkspace = require("./planning-workspace.cjs");
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const roadmapParser = require("./roadmap-parser.cjs");
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseIdModule = require("./phase-id.cjs");
-const { planningDir, planningRoot, withPlanningLock } = planningWorkspace;
-const { getRoadmapPhaseInternal } = roadmapParser;
-const { phaseMarkdownRegexSource } = phaseIdModule;
-exports.PHASE_TIERS = ['light', 'standard', 'heavy'];
-exports.SCHEMA_DEFAULT_TIER = 'standard';
-exports.TIER_GATE_KEYS = [
-    'research',
-    'pattern_mapper',
-    'plan_check',
-    'verifier',
-    'nyquist_validation',
-    'code_review',
-    'post_planning_gaps',
-    'security_enforcement',
-    'vault_review',
-];
-/**
- * The plan-checker loop's current maximum: plan-phase §12 "Revision Loop (Max
- * 3 Iterations)" — the checker runs once after planning and at most twice more
- * after a revision (verify-work's gap-plan loop has the same cap).
- */
-exports.PLAN_CHECK_MAX_PASSES = 3;
-/** `workflow.plan_bounce_passes` schema default (config-defaults manifest). */
-exports.DEFAULT_PLAN_BOUNCE_PASSES = 2;
-function gates(on) {
-    const out = {};
-    for (const k of exports.TIER_GATE_KEYS)
-        out[k] = on.includes(k);
-    return out;
-}
-exports.TIER_PRESETS = Object.freeze({
-    light: { gates: gates([]), plan_check_passes: 0, plan_bounce: false, install_verification: false },
-    standard: {
-        gates: gates(['plan_check', 'verifier', 'code_review']),
-        plan_check_passes: 1,
-        plan_bounce: false,
-        install_verification: false,
-    },
-    heavy: {
-        gates: gates([...exports.TIER_GATE_KEYS]),
-        plan_check_passes: exports.PLAN_CHECK_MAX_PASSES,
-        plan_bounce: true,
-        install_verification: true,
-    },
-});
-function isPhaseTier(value) {
-    return typeof value === 'string' && exports.PHASE_TIERS.includes(value);
-}
-function isExplicitFalse(value) {
-    return value === false || value === 'false';
-}
-function isExplicitTrue(value) {
-    return value === true || value === 'true';
-}
-/**
- * Resolve the effective gate set for one phase.
- *
- * `cli` must already be a valid tier or null (the CLI rejects anything else).
- */
-function resolvePhaseTier(input) {
-    const ignored = [];
-    const candidates = [
-        { source: 'cli', value: input.cli },
-        { source: 'phase', value: input.phaseRecord?.tier },
-        { source: 'project', value: input.config?.tier },
-    ];
-    let tier = exports.SCHEMA_DEFAULT_TIER;
-    let source = 'default';
-    for (const c of candidates) {
-        if (c.value === null || c.value === undefined || c.value === '')
-            continue;
-        const v = String(c.value).trim().toLowerCase();
-        if (isPhaseTier(v)) {
-            tier = v;
-            source = c.source;
-            break;
-        }
-        ignored.push({ source: c.source, value: String(c.value) });
-    }
-    const preset = exports.TIER_PRESETS[tier];
-    const explicit = input.config?.explicit ?? {};
-    const suppressed = [];
-    const notForced = [];
-    const resolve = (key, wanted) => {
-        const value = explicit[key];
-        if (wanted && isExplicitFalse(value)) {
-            suppressed.push(key);
-            return false;
-        }
-        if (!wanted && isExplicitTrue(value))
-            notForced.push(key);
-        return wanted;
-    };
-    const out = {};
-    for (const key of exports.TIER_GATE_KEYS)
-        out[key] = resolve(key, preset.gates[key]);
-    out.plan_check_passes = out.plan_check ? preset.plan_check_passes : 0;
-    out.plan_bounce = resolve('plan_bounce', preset.plan_bounce);
-    const passes = input.config?.plan_bounce_passes;
-    out.plan_bounce_passes = out.plan_bounce
-        ? (typeof passes === 'number' && Number.isInteger(passes) && passes > 0 ? passes : exports.DEFAULT_PLAN_BOUNCE_PASSES)
-        : 0;
-    out.install_verification = preset.install_verification;
-    return { tier, source, gates: out, suppressed, not_forced: notForced, ignored };
-}
-/** `src/<name>.cts` or its compiled `pp-core/bin/lib/<name>.cjs`. */
-const LIB = String.raw `^(?:src|pp-core/bin/lib)/`;
-/**
- * Paths that make a phase heavy. Matched against a plan's `files_modified`
- * (normalised, repo-relative). A matching file must also be a source file by
- * the plan-graph predicate, so a test or doc named after a gate never counts.
- */
-exports.HEAVY_PATH_RULES = Object.freeze([
-    { category: 'gate', example: 'src/ui-safety-gate.cts', pattern: new RegExp(`${LIB}(?:[^/]+/)*[^/]*gate[^/]*\\.c?[jt]s$`) },
-    { category: 'gate', example: 'src/check-command-router.cts', pattern: new RegExp(`${LIB}(?:check-command-router|prohibition-enforcement|gap-checker|plan-graph|dispatch-plan)\\.c?[jt]s$`) },
-    { category: 'gate', example: 'src/practices-review-check.cts', pattern: new RegExp(`${LIB}[^/]+-(?:check|guard)\\.c?[jt]s$`) },
-    // The vault's gate, verdict and redaction owners (`vault`, `vault-trace`,
-    // `vault-audit`, `vault-review`, `vault-practices`, …): a phase editing them
-    // changes what the load, trace and audit gates decide and what remote text is
-    // redacted, so it is proposed heavy.
-    { category: 'gate', example: 'src/vault.cts', pattern: new RegExp(`${LIB}vault[^/]*\\.c?[jt]s$`) },
-    { category: 'init', example: 'src/init.cts', pattern: new RegExp(`${LIB}init[^/]*\\.c?[jt]s$`) },
-    { category: 'redaction', example: 'src/observability/redaction.cts', pattern: /(?:^|\/)[^/]*(?:redact|secret)[^/]*$/i },
-    { category: 'config-precedence', example: 'src/config-loader.cts', pattern: new RegExp(`${LIB}(?:config[^/]*|configuration|federated-config|capability-activation|phase-tier)\\.c?[jt]s$`) },
-    { category: 'config-precedence', example: 'pp-core/bin/shared/config-defaults.manifest.json', pattern: /^pp-core\/bin\/shared\/config-[^/]+\.json$/ },
-    { category: 'hook-dispatch', example: 'hooks/pp-workflow-guard.js', pattern: /^hooks\// },
-    { category: 'hook-dispatch', example: 'src/loop-resolver.cts', pattern: new RegExp(`${LIB}(?:loop-resolver|capability-state|runtime-hooks-surface)\\.c?[jt]s$`) },
-    { category: 'hook-dispatch', example: 'capabilities/code-review/capability.json', pattern: /^capabilities\/[^/]+\/capability\.json$/ },
-    { category: 'hook-dispatch', example: 'scripts/build-hooks.js', pattern: /^scripts\/build-hooks\.js$/ },
-]);
-/** Words in requirement tags or ROADMAP text that make a not-yet-planned phase heavy. */
-exports.HEAVY_TEXT_RULES = Object.freeze([
-    { category: 'gate', pattern: /\b(?:gates?|gating)\b/i },
-    { category: 'init', pattern: /\b(?:init|pp-init|initiali[sz]ation)\b/i },
-    { category: 'redaction', pattern: /\b(?:redact(?:s|ed|ion)?|secrets?)\b/i },
-    { category: 'config-precedence', pattern: /\bconfig(?:uration)?\s+(?:precedence|resolution|loader|defaults)\b|\bprecedence\b/i },
-    { category: 'hook-dispatch', pattern: /\bhooks?\b[^.\n]{0,40}\bdispatch\w*\b|\bloop[- ]hooks?\b|\bcapability registry\b/i },
-]);
-/** Requirement-tag prefixes that name a heavy category (e.g. `INIT-02`). */
-const HEAVY_TAG_PREFIX = Object.freeze([
-    { category: 'gate', pattern: /^GATES?-/i },
-    { category: 'init', pattern: /^INIT-/i },
-    { category: 'redaction', pattern: /^(?:REDACT|REDACTION|SECRETS?)-/i },
-    { category: 'config-precedence', pattern: /^(?:CONFIG|CFG|PREC)-/i },
-    { category: 'hook-dispatch', pattern: /^HOOKS?-/i },
-]);
-function normalizePath(file) {
-    return String(file).trim().replace(/\\/g, '/').replace(/^\.\//, '');
-}
-function heavyCategoryForPath(file) {
-    const f = normalizePath(file);
-    if (f === '' || !(0, plan_graph_cjs_1.isSourceFile)(f))
-        return null;
-    for (const rule of exports.HEAVY_PATH_RULES)
-        if (rule.pattern.test(f))
-            return rule;
-    return null;
-}
-function proposePhaseTier(input) {
-    const plans = input.plans ?? [];
-    if (plans.length > 0) {
-        const heavy = [];
-        const source = [];
-        for (const p of plans) {
-            const files = (p.files_modified ?? []).map(normalizePath).filter((f) => f !== '');
-            if (files.length === 0)
-                source.push({ category: 'undeclared', plan: p.id });
-            for (const f of files) {
-                const rule = heavyCategoryForPath(f);
-                if (rule)
-                    heavy.push({ category: rule.category, plan: p.id, file: f });
-                else if ((0, plan_graph_cjs_1.isSourceFile)(f))
-                    source.push({ category: 'source', plan: p.id, file: f });
-            }
-        }
-        if (heavy.length > 0) {
-            const cats = [...new Set(heavy.map((m) => m.category))].join(', ');
-            return {
-                tier: 'heavy',
-                basis: 'plans',
-                reason: `a plan touches ${cats} code (${heavy.slice(0, 3).map((m) => `${m.plan}: ${m.file}`).join('; ')}${heavy.length > 3 ? '; …' : ''})`,
-                matched: heavy,
-            };
-        }
-        if (source.length === 0) {
-            return { tier: 'light', basis: 'plans', reason: 'no plan touches a source file; only docs, tests, workflow and planning files', matched: [] };
-        }
-        const undeclared = source.filter((m) => m.category === 'undeclared').map((m) => m.plan);
-        return {
-            tier: 'standard',
-            basis: 'plans',
-            reason: undeclared.length > 0 && undeclared.length === source.length
-                ? `plan(s) ${undeclared.join(', ')} declare no files_modified, so source is assumed`
-                : 'plans touch source files, none of them gate, init, redaction, config-precedence or hook-dispatch code',
-            matched: source,
-        };
-    }
-    const matched = [];
-    for (const tag of input.requirements ?? []) {
-        const t = String(tag).trim();
-        for (const r of HEAVY_TAG_PREFIX)
-            if (r.pattern.test(t))
-                matched.push({ category: r.category, text: t });
-    }
-    // The phase's own **Tier:** line (and a recorded proposal's reason) is never evidence.
-    const text = (input.roadmapText ?? '').replace(/^\*\*Tier(?::\*\*|\*\*:)[^\n]*$/gim, '');
-    for (const r of exports.HEAVY_TEXT_RULES) {
-        const m = r.pattern.exec(text);
-        if (m)
-            matched.push({ category: r.category, text: m[0] });
-    }
-    if (matched.length > 0) {
-        const cats = [...new Set(matched.map((m) => m.category))].join(', ');
-        return { tier: 'heavy', basis: 'text', reason: `no plans yet; the requirements or ROADMAP entry name ${cats} work (${matched.slice(0, 3).map((m) => `"${m.text}"`).join(', ')})`, matched };
-    }
-    return { tier: 'standard', basis: 'text', reason: 'no plans yet and nothing names gate, init, redaction, config-precedence or hook-dispatch work; planning re-proposes from files_modified', matched: [] };
-}
-// ─── I/O: project config, phase record, recording ─────────────────────────────
-const FLAT_ALIASES = {
-    research: 'research',
-    plan_check: 'plan_checker',
-    verifier: 'verifier',
-    nyquist_validation: 'nyquist_validation',
-    post_planning_gaps: 'post_planning_gaps',
-};
-function readJson(file) {
-    try {
-        const parsed = JSON.parse(node_fs_1.default.readFileSync(file, 'utf-8'));
-        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-function lookup(cfg, section, key, flat) {
-    if (flat !== undefined && cfg[flat] !== undefined)
-        return cfg[flat];
-    const sec = cfg[section];
-    if (sec && typeof sec === 'object' && !Array.isArray(sec)) {
-        const v = sec[key];
-        if (v !== undefined)
-            return v;
-    }
-    return undefined;
-}
-/**
- * The project's own config (workstream config.json first, then the root
- * config.json): `phase.tier`, the gate booleans actually written there, and
- * `workflow.plan_bounce_passes`. Manifest defaults are never read here.
- */
-function readProjectTierConfig(cwd) {
-    const files = [node_path_1.default.join(planningDir(cwd), 'config.json')];
-    const root = node_path_1.default.join(planningRoot(cwd), 'config.json');
-    if (root !== files[0])
-        files.push(root);
-    const configs = files.map(readJson).filter((c) => c !== null);
-    const first = (section, key, flat) => {
-        for (const c of configs) {
-            const v = lookup(c, section, key, flat);
-            if (v !== undefined)
-                return v;
-        }
-        return undefined;
-    };
-    const explicit = {};
-    for (const key of [...exports.TIER_GATE_KEYS, 'plan_bounce']) {
-        const v = first('workflow', key, FLAT_ALIASES[key]);
-        if (v !== undefined)
-            explicit[key] = v;
-    }
-    const tier = first('phase', 'tier');
-    const passes = first('workflow', 'plan_bounce_passes');
-    const script = first('workflow', 'plan_bounce_script');
-    return {
-        tier: typeof tier === 'string' ? tier : null,
-        explicit,
-        plan_bounce_passes: typeof passes === 'number' ? passes : null,
-        plan_bounce_script: typeof script === 'string' && script.trim() !== '' ? script : null,
-    };
-}
-const TIER_FIELD_RE = /^\*\*Tier(?::\*\*|\*\*:)[^\S\n]*([A-Za-z-]+)([^\n]*)$/im;
-/** The `**Tier:**` field of a ROADMAP phase section, or null when absent. */
-function parsePhaseTierField(section) {
-    if (!section)
-        return null;
-    const m = TIER_FIELD_RE.exec(section);
-    if (!m)
-        return null;
-    return { tier: m[1].toLowerCase(), proposed: /\(\s*proposed\b/i.test(m[2]), line: m[0] };
-}
-function readPhaseRecord(cwd, phase) {
-    const rp = getRoadmapPhaseInternal(cwd, phase);
-    const section = rp?.section ?? null;
-    const field = parsePhaseTierField(section);
-    return {
-        tier: field?.tier ?? null,
-        proposed: field?.proposed ?? false,
-        section,
-        phase_name: rp?.phase_name ?? null,
-    };
-}
-/** Resolve the tier of `phase` in the project at `cwd` (CLI value already validated). */
-function resolvePhaseTierForProject(cwd, phase, cli) {
-    const config = readProjectTierConfig(cwd);
-    const record = phase ? readPhaseRecord(cwd, phase) : null;
-    const phaseRecord = record && record.tier !== null ? { tier: record.tier, proposed: record.proposed } : null;
-    const resolved = resolvePhaseTier({ cli, phaseRecord, config });
-    return { ...resolved, phase_record: phaseRecord, project_tier: config.tier ?? null, plan_bounce_script: config.plan_bounce_script };
-}
-/**
- * The gate booleans of a resolved tier as a config overlay
- * (`{ workflow: { research: …, … } }`), merged over `base` without mutating
- * it. Used by `loop render-hooks --phase` so capability `when` keys and
- * activation keys read the tier-resolved values first.
- */
-function overlayTierGates(base, resolved) {
-    const wf = base['workflow'] && typeof base['workflow'] === 'object' && !Array.isArray(base['workflow'])
-        ? { ...base['workflow'] }
-        : {};
-    for (const key of exports.TIER_GATE_KEYS)
-        wf[key] = resolved.gates[key];
-    wf['plan_bounce'] = resolved.gates.plan_bounce;
-    const out = { ...base, workflow: wf };
-    for (const [key, flat] of Object.entries(FLAT_ALIASES)) {
-        if (flat !== undefined && flat in base)
-            out[flat] = resolved.gates[key];
-    }
-    return out;
-}
-/**
- * Write `**Tier:** <tier>` into the phase's ROADMAP entry (current milestone
- * only). A proposal (`proposed: true`) is written as `**Tier:** <tier>
- * (proposed: <reason>)` and never replaces an operator choice (a field without
- * the `(proposed` marker). An operator choice always replaces the field.
- */
-function recordPhaseTier(cwd, phase, tier, opts) {
-    const roadmapPath = node_path_1.default.join(planningDir(cwd), 'ROADMAP.md');
-    if (!node_fs_1.default.existsSync(roadmapPath))
-        return { recorded: false, tier: null, proposed: false, reason: 'ROADMAP.md not found' };
-    let result = { recorded: false, tier: null, proposed: false, reason: 'phase entry not found in ROADMAP.md' };
-    withPlanningLock(cwd, () => {
-        const content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-        const lastClose = content.lastIndexOf('</details>');
-        const offset = lastClose === -1 ? 0 : lastClose + '</details>'.length;
-        const scope = content.slice(offset);
-        const header = new RegExp(`^#{2,4}\\s*(?:\\[[^\\]]+\\]\\s*)?Phase\\s+${phaseMarkdownRegexSource(phase)}\\s*:[^\\n]*$`, 'im');
-        const hm = header.exec(scope);
-        if (!hm)
-            return;
-        const start = hm.index;
-        const after = scope.slice(start + hm[0].length);
-        const next = /\n#{2,4}\s+(?:\[[^\]]+\]\s*)?Phase\s+[\w]|\n#{1,2}\s+(?!#)/.exec(after);
-        const end = start + hm[0].length + (next ? next.index : after.length);
-        const section = scope.slice(start, end);
-        const existing = parsePhaseTierField(section);
-        if (existing && opts.proposed && !existing.proposed) {
-            result = { recorded: false, tier: existing.tier, proposed: false, reason: `kept the operator's choice (${existing.tier})` };
-            return;
-        }
-        const reason = (opts.reason ?? '').replace(/\s+/g, ' ').trim();
-        const line = opts.proposed ? `**Tier:** ${tier} (proposed${reason ? `: ${reason}` : ''})` : `**Tier:** ${tier}`;
-        let newSection;
-        if (existing) {
-            newSection = section.replace(existing.line, line);
-        }
-        else {
-            const goal = /^\*\*Goal(?:\*\*:|\*?\*?:\*\*)[^\n]*$/im.exec(section);
-            const anchorEnd = goal ? goal.index + goal[0].length : hm[0].length;
-            newSection = `${section.slice(0, anchorEnd)}\n${line}${section.slice(anchorEnd)}`;
-        }
-        if (newSection === section) {
-            result = { recorded: false, tier, proposed: opts.proposed, reason: 'already recorded' };
-            return;
-        }
-        const updated = content.slice(0, offset) + scope.slice(0, start) + newSection + scope.slice(end);
-        node_fs_1.default.writeFileSync(roadmapPath, updated, 'utf-8');
-        result = { recorded: true, tier, proposed: opts.proposed, reason: opts.proposed ? 'proposal recorded' : 'operator choice recorded' };
-    });
-    return result;
-}
-/** Parse a `--tier` value; returns the tier, null when absent, or an error message. */
-function parseTierFlag(args) {
-    const rest = [];
-    let tier = null;
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        let value;
-        if (a === '--tier')
-            value = args[++i];
-        else if (a.startsWith('--tier='))
-            value = a.slice('--tier='.length);
-        else {
-            rest.push(a);
-            continue;
-        }
-        const v = (value ?? '').trim().toLowerCase();
-        if (!isPhaseTier(v))
-            return { error: `--tier needs one of ${exports.PHASE_TIERS.join(', ')}` };
-        tier = v;
-    }
-    return { tier, rest };
-}