@pareto4/pp-core 1.11.1 → 1.12.0

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

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Phase Scope — is this phase-directory match the current milestone's, and may
+ * this caller use it?
+ *
+ * THE owner of that decision for every consumer of the raw phase locator
+ *. The raw locator in phase-locator.cts answers a
+ * phase token from the live `phases/` tree first and then falls through to the
+ * closed milestones' `milestones/<v>-phases/` archives, marking such a match
+ * with the archive's version. It applies no milestone compare, and it must not:
+ * phase-locator stays a leaf that does not import roadmap-parser (quick
+ * 261007-jkl D2), which is why the compare lives here.
+ *
+ * History. 261007-jkl D2 put the compare into init.cts for the four init phase
+ * verbs only; every other consumer kept the raw fall-through, so `template fill`
+ * and `phase scaffold` wrote new files into a closed milestone's archive and
+ * `phase complete`, `roadmap update-plan-progress`, `check ui.plan-gate`, the ship
+ * pointer and the vault resolver answered a v2.0 phase from a v1.0 archive whose
+ * number the current ROADMAP reuses (todo "template-fill-writes-into-an-archived-
+ * phase-directory"). This module lifts the decision out of init so all of them
+ * share one answer (D-01: a new leaf-importing module, so every consumer can
+ * require it with no cycle — measured in the quick's sweep/CYCLES.md).
+ *
+ * Scopes (`resolvePhaseScope`):
+ *   - `live`               the match is in the live `phases/` tree;
+ *   - `archived-current`   archived, the ROADMAP lists the number, and the archive
+ *                          version equals the current milestone version — the
+ *                          roadmap entry IS the archived phase;
+ *   - `archived-unlisted`  archived and the ROADMAP no longer lists the number;
+ *   - `archived-collision` archived, the ROADMAP lists the number, versions differ —
+ *                          a PRIOR milestone's phase whose number the current
+ *                          ROADMAP reuses for a new phase;
+ *   - `none`               no match anywhere.
+ *
+ * Readers (D-03) use `forRead`: the match on live / archived-current /
+ * archived-unlisted, null on a collision — exactly what the init family has
+ * answered since 261007-jkl. Writers (D-02) use `forWrite`: a live match only;
+ * any archived match the caller would write into is refused naming the archive
+ * (archived-current, archived-unlisted), and a collision takes the writer's own
+ * not-found path. Nothing ever resolves a writer into a closed milestone's record.
+ *
+ * The current version comes from getMilestoneInfo(cwd) and is read ONLY for an
+ * archived match, so a live match does no extra I/O. Known limit (unchanged from
+ * 261007-jkl D2): with no version anywhere getMilestoneInfo defaults to v1.0, so
+ * a v1.0 archive under a version-less ROADMAP that lists the number counts as
+ * current. The archived marker has two readers left: phase-locator, which sets
+ * it, and this module, which classifies it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocatorModule = require("./phase-locator.cjs");
+const { findPhaseInternal } = phaseLocatorModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParserModule = require("./roadmap-parser.cjs");
+const { getRoadmapPhaseInternal, getMilestoneInfo } = roadmapParserModule;
+/** Milestone versions compare after dropping whitespace and one leading v/V; exact match otherwise. */
+function normalizeMilestoneVersion(version) {
+    return (typeof version === 'string' ? version : '').trim().replace(/^[vV]/, '').trim();
+}
+function resolvePhaseScope(cwd, phase) {
+    const match = findPhaseInternal(cwd, phase);
+    const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+    if (!match) {
+        return { scope: 'none', match: null, roadmapPhase, currentVersion: null, forRead: null, forWrite: { ok: false, reason: 'not_found' } };
+    }
+    if (!match.archived) {
+        return { scope: 'live', match, roadmapPhase, currentVersion: null, forRead: match, forWrite: { ok: true, match } };
+    }
+    const currentVersion = getMilestoneInfo(cwd).version;
+    const archivedRefusal = { ok: false, reason: 'archived', version: match.archived, directory: match.directory };
+    if (!roadmapPhase?.found) {
+        return { scope: 'archived-unlisted', match, roadmapPhase, currentVersion, forRead: match, forWrite: archivedRefusal };
+    }
+    if (normalizeMilestoneVersion(match.archived) === normalizeMilestoneVersion(currentVersion)) {
+        return { scope: 'archived-current', match, roadmapPhase, currentVersion, forRead: match, forWrite: archivedRefusal };
+    }
+    return { scope: 'archived-collision', match, roadmapPhase, currentVersion, forRead: null, forWrite: { ok: false, reason: 'not_found' } };
+}
+/** The match a READER may use (D-03): null on a prior-milestone collision and on no match. */
+function resolvePhaseForRead(cwd, phase) {
+    return resolvePhaseScope(cwd, phase).forRead;
+}
+/** The verdict a WRITER must obey (D-02): ok only for a live match. */
+function resolvePhaseForWrite(cwd, phase) {
+    return resolvePhaseScope(cwd, phase).forWrite;
+}
+module.exports = {
+    resolvePhaseScope,
+    resolvePhaseForRead,
+    resolvePhaseForWrite,
+    normalizeMilestoneVersion,
+};

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

@@ -0,0 +1,467 @@
+"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}`:
+ *
+ *   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`).
+ *
+ * ## 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, 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',
+];
+/**
+ * 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$`) },
+    { 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 };
+}