@pareto4/pp-core 1.11.1 → 1.12.0

package/pp-core/bin/lib/install-run.cjs

@@ -0,0 +1,536 @@
+"use strict";
+/**
+ * Install run — the single owner of heavy-tier "measure the installed
+ * product" verification (pack 9, item 5).
+ *
+ * For a pp-core package (a package.json whose `bin` has both `pp-core` and
+ * `pp-tools`), `phase.install-run <phase>`:
+ *
+ *   1. builds (`npm run build`, unless `--no-build`) and packs the package
+ *      (`npm pack`, whose `prepack` compiles the shipped `.cjs`) — or takes a
+ *      tarball given with `--tarball`;
+ *   2. installs the tarball into a temp npm prefix and runs the installer the
+ *      user runs (`pp-core --claude --local`) in a temp fixture project, under
+ *      a temp HOME — reusing the release smoke harness
+ *      (scripts/release-tarball-smoke.cjs: `runSmoke`, `driveInstaller`);
+ *   3. runs init non-interactively through the INSTALLED pp-tools
+ *      (`query init-contract --session-next/--session-answer`, the documented
+ *      non-interactive form of `pp-tools init`);
+ *   4. runs the phase's install-check commands against the INSTALLED
+ *      `.claude/pp-core/bin/pp-tools.cjs`, never the repository's;
+ *   5. writes `<phase_dir>/<NN>-INSTALL-RUN.json`: tarball name and version,
+ *      every command with its exit code and truncated stdout/stderr, and a
+ *      verdict (`pass` / `fail` / `not_applicable`).
+ *
+ * The install-check commands have ONE owner: the phase's ROADMAP entry, as an
+ * `**Install check:**` line of backticked `pp-tools …` commands (the same
+ * owner as the `**Tier:**` line). Without the line, `DEFAULT_INSTALL_CHECKS`
+ * run.
+ *
+ * npm runs offline first (`npm_config_offline`, from the caller's npm cache);
+ * on a cache miss it retries with `prefer-offline`, which may fetch the
+ * package's dependencies — the same network the existing install tests use.
+ * The registry is whatever the caller's npm configuration says; nothing here
+ * names one.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTPUT_LIMIT = exports.INIT_ANSWERS = exports.DEFAULT_INSTALL_CHECKS = exports.INSTALL_RUN_SUFFIX = exports.INSTALL_RUN_SCHEMA = void 0;
+exports.parseInstallCheckField = parseInstallCheckField;
+exports.splitCommandLine = splitCommandLine;
+exports.parseCheckCommand = parseCheckCommand;
+exports.resolveInstallChecks = resolveInstallChecks;
+exports.truncateOutput = truncateOutput;
+exports.computeInstallVerdict = computeInstallVerdict;
+exports.readTarballPackageJson = readTarballPackageJson;
+exports.isPpCorePackage = isPpCorePackage;
+exports.parseInstallRunArgs = parseInstallRunArgs;
+exports.findSmokeHarness = findSmokeHarness;
+exports.buildRunEnv = buildRunEnv;
+exports.runInstallRun = runInstallRun;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_zlib_1 = __importDefault(require("node:zlib"));
+const node_child_process_1 = require("node:child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- roadmap-parser.cjs is an export= CommonJS module
+const roadmapParser = require("./roadmap-parser.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
+const phaseLocator = require("./phase-locator.cjs");
+const { getRoadmapPhaseInternal } = roadmapParser;
+const { findPhaseInternal } = phaseLocator;
+exports.INSTALL_RUN_SCHEMA = 'pp-install-run/1';
+exports.INSTALL_RUN_SUFFIX = 'INSTALL-RUN.json';
+/** Run when the phase's ROADMAP entry has no `**Install check:**` line: the smoke job's surface. */
+exports.DEFAULT_INSTALL_CHECKS = Object.freeze([
+    'pp-tools --help',
+    'pp-tools query config-get project.slug',
+    'pp-tools init phase-op 1',
+    'pp-tools progress',
+]);
+/** Fixed answers for the non-interactive init session in the fixture project. */
+exports.INIT_ANSWERS = Object.freeze({
+    project_name: 'Install Run Fixture',
+    project_slug: 'install-run-fixture',
+    client_name: 'internal',
+    client_slug: 'internal',
+    description: 'Fixture project for the heavy-tier install run',
+    org_profile: 'none',
+    provider: 'none',
+    visibility: 'private',
+});
+exports.OUTPUT_LIMIT = 2000;
+const INIT_MAX_STEPS = 30;
+const COMMAND_TIMEOUT_MS = 120_000;
+const BUILD_TIMEOUT_MS = 600_000;
+const TOOL_NAMES = new Set(['pp-tools', 'pp_run']);
+// ─── Pure parts ──────────────────────────────────────────────────────────────
+const INSTALL_CHECK_RE = /^\*\*Install check(?::\*\*|\*\*:)[^\S\n]*([^\n]*)$/im;
+/** The `**Install check:**` line of a ROADMAP phase section: its backticked commands, or null when absent. */
+function parseInstallCheckField(section) {
+    if (!section)
+        return null;
+    const m = INSTALL_CHECK_RE.exec(section);
+    if (!m)
+        return null;
+    const commands = [...m[1].matchAll(/`([^`]+)`/g)].map((c) => c[1].trim()).filter(Boolean);
+    return { line: m[0].trim(), commands };
+}
+/** Split one command line into argv (single and double quotes, backslash escapes); no shell is involved. */
+function splitCommandLine(text) {
+    const argv = [];
+    let cur = '';
+    let inToken = false;
+    let quote = null;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else if (ch === '\\' && quote === '"' && i + 1 < text.length)
+                cur += text[++i];
+            else
+                cur += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            inToken = true;
+        }
+        else if (ch === '\\' && i + 1 < text.length) {
+            cur += text[++i];
+            inToken = true;
+        }
+        else if (/\s/.test(ch)) {
+            if (inToken)
+                argv.push(cur);
+            cur = '';
+            inToken = false;
+        }
+        else {
+            cur += ch;
+            inToken = true;
+        }
+    }
+    if (quote)
+        return { error: `unterminated ${quote} quote` };
+    if (inToken)
+        argv.push(cur);
+    return argv;
+}
+/** A listed command must start with `pp-tools` (or `pp_run`); the rest is its argv. */
+function parseCheckCommand(text) {
+    const split = splitCommandLine(text);
+    if (!Array.isArray(split))
+        return { text, error: split.error };
+    if (split.length === 0 || !TOOL_NAMES.has(split[0])) {
+        return { text, error: 'an install check must be a `pp-tools …` command (run against the installed copy)' };
+    }
+    return { text, argv: split.slice(1) };
+}
+/** The phase's install checks from its ROADMAP section, or the default smoke set. */
+function resolveInstallChecks(section) {
+    const field = parseInstallCheckField(section);
+    const texts = field ? field.commands : [...exports.DEFAULT_INSTALL_CHECKS];
+    const commands = [];
+    const invalid = [];
+    for (const text of texts) {
+        const parsed = parseCheckCommand(text);
+        if ('error' in parsed)
+            invalid.push(parsed);
+        else
+            commands.push(parsed);
+    }
+    if (field && field.commands.length === 0) {
+        invalid.push({ text: field.line, error: 'the **Install check:** line lists no backticked commands' });
+    }
+    return { source: field ? 'roadmap' : 'default', line: field ? field.line : null, commands, invalid };
+}
+/** Keep the head and tail of long output. */
+function truncateOutput(text, limit = exports.OUTPUT_LIMIT) {
+    const s = String(text ?? '');
+    if (s.length <= limit)
+        return s;
+    const half = Math.floor(limit / 2);
+    return `${s.slice(0, half)}\n… [${s.length - limit} chars truncated] …\n${s.slice(s.length - half)}`;
+}
+/**
+ * The verdict: `not_applicable` when nothing installable was found; `fail`
+ * when any recorded command exited non-zero (or did not run), a listed check
+ * was invalid, or init did not finish; `pass` otherwise.
+ */
+function computeInstallVerdict(input) {
+    if (!input.applicable) {
+        return { verdict: 'not_applicable', reason: input.notApplicableReason || 'nothing installable', failures: [] };
+    }
+    const failures = input.commands
+        .filter((c) => c.exit_code !== 0)
+        .map((c) => ({ stage: c.stage, command: c.command, exit_code: c.exit_code, ...(c.error ? { error: c.error } : {}) }));
+    for (const bad of input.invalid) {
+        failures.push({ stage: 'check', command: bad.text, exit_code: null, error: bad.error });
+    }
+    if (!input.initDone && !failures.some((f) => f.stage !== 'check')) {
+        failures.push({ stage: 'init', command: 'pp-tools init', exit_code: null, error: 'the init session did not finish' });
+    }
+    if (!input.checksRun && failures.length === 0) {
+        failures.push({ stage: 'check', command: '(install checks)', exit_code: null, error: 'the install checks did not run' });
+    }
+    if (failures.length === 0)
+        return { verdict: 'pass', reason: 'every command exited 0 against the installed copy', failures };
+    const f = failures[0];
+    const how = f.exit_code === null ? (f.error || 'did not run') : `exited ${f.exit_code}`;
+    return { verdict: 'fail', reason: `${f.stage}: \`${f.command}\` ${how}`, failures };
+}
+/** `package/package.json` from an npm tarball (gzip + ustar), without a `tar` binary. */
+function readTarballPackageJson(tarballPath) {
+    let buf;
+    try {
+        buf = node_zlib_1.default.gunzipSync(node_fs_1.default.readFileSync(tarballPath));
+    }
+    catch {
+        return null;
+    }
+    let off = 0;
+    let longName = null;
+    while (off + 512 <= buf.length) {
+        const header = buf.subarray(off, off + 512);
+        if (header.every((b) => b === 0))
+            break;
+        const field = (start, len) => header.subarray(start, start + len).toString('utf8').replace(/\0.*$/s, '');
+        const size = parseInt(field(124, 12).trim() || '0', 8) || 0;
+        const type = field(156, 1);
+        const prefix = field(345, 155);
+        const name = longName ?? (prefix ? `${prefix}/${field(0, 100)}` : field(0, 100));
+        longName = null;
+        const body = buf.subarray(off + 512, off + 512 + size);
+        if (type === 'L')
+            longName = body.toString('utf8').replace(/\0.*$/s, '');
+        else if (type === 'x') {
+            const m = /\d+ path=([^\n]*)\n/.exec(body.toString('utf8'));
+            if (m)
+                longName = m[1];
+        }
+        else if ((type === '0' || type === '') && name.replace(/^[^/]+\//, '') === 'package.json' && name.split('/').length === 2) {
+            try {
+                return JSON.parse(body.toString('utf8'));
+            }
+            catch {
+                return null;
+            }
+        }
+        off += 512 + Math.ceil(size / 512) * 512;
+    }
+    return null;
+}
+/** A pp-core package: its package.json `bin` names both `pp-core` (installer) and `pp-tools`. */
+function isPpCorePackage(pkg) {
+    const bin = pkg && typeof pkg['bin'] === 'object' && pkg['bin'] !== null ? pkg['bin'] : null;
+    return !!bin && typeof bin['pp-core'] === 'string' && typeof bin['pp-tools'] === 'string';
+}
+function parseInstallRunArgs(args) {
+    const usage = 'Usage: phase install-run <phase> [--tarball <path.tgz>] [--package-dir <dir>] [--no-build]';
+    let phase = null;
+    let tarball = null;
+    let packageDir = null;
+    let build = true;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--raw')
+            continue;
+        if (a === '--no-build')
+            build = false;
+        else if (a === '--tarball' || a === '--package-dir') {
+            const v = args[i + 1];
+            if (!v || v.startsWith('--'))
+                return { error: `${a} requires a value. ${usage}` };
+            if (a === '--tarball')
+                tarball = v;
+            else
+                packageDir = v;
+            i++;
+        }
+        else if (a.startsWith('--'))
+            return { error: `phase install-run does not support ${a}. ${usage}` };
+        else if (phase === null)
+            phase = a;
+        else
+            return { error: `phase install-run takes one phase. ${usage}` };
+    }
+    if (phase === null)
+        return { error: `phase required for phase install-run. ${usage}` };
+    if (tarball && packageDir)
+        return { error: `--tarball and --package-dir are exclusive. ${usage}` };
+    return { phase, tarball, packageDir, build };
+}
+const HARNESS_REL = node_path_1.default.join('scripts', 'release-tarball-smoke.cjs');
+/** The release smoke harness: the package's own first, then the running copy's. */
+function findSmokeHarness(packageDir) {
+    const own = node_path_1.default.resolve(__dirname, '..', '..', '..');
+    for (const root of [packageDir, own]) {
+        if (!root)
+            continue;
+        const p = node_path_1.default.join(root, HARNESS_REL);
+        if (node_fs_1.default.existsSync(p))
+            return p;
+    }
+    return null;
+}
+const npmCmd = () => (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+function npmConfigGet(key, env) {
+    const r = (0, node_child_process_1.spawnSync)(npmCmd(), ['config', 'get', key], { encoding: 'utf-8', env, shell: process.platform === 'win32', timeout: 30_000, windowsHide: true });
+    const v = r.status === 0 ? String(r.stdout || '').trim() : '';
+    return v && v !== 'undefined' && v !== 'null' ? v : null;
+}
+/**
+ * The env every child of the run sees: a temp HOME (and XDG config home), so
+ * nothing reads or writes the caller's runtime config dirs; the caller's npm
+ * cache and npm user config kept, so npm can install offline and reach the
+ * caller's configured registry.
+ */
+function buildRunEnv(base, home) {
+    const env = { ...base };
+    for (const k of Object.keys(env)) {
+        if (k.startsWith('GIT_') || k === 'GSD_TEST_MODE' || k === 'CLAUDE_CONFIG_DIR' || k === 'GSD_WORKSTREAM')
+            delete env[k];
+    }
+    const cache = base.npm_config_cache || npmConfigGet('cache', base);
+    if (cache)
+        env.npm_config_cache = cache;
+    env.npm_config_userconfig = base.npm_config_userconfig || node_path_1.default.join(node_os_1.default.homedir(), '.npmrc');
+    env.HOME = home;
+    env.USERPROFILE = home;
+    env.XDG_CONFIG_HOME = node_path_1.default.join(home, '.config');
+    env.npm_config_update_notifier = 'false';
+    env.npm_config_audit = 'false';
+    env.npm_config_fund = 'false';
+    env.npm_config_loglevel = 'error';
+    env.NO_UPDATE_NOTIFIER = '1';
+    return env;
+}
+const ANSI_RE = new RegExp('\\u001b\\[[0-9;]*[A-Za-z]', 'g');
+/** Drop ANSI colour codes and replace the temp root with `<install-run>`. */
+function scrub(text, root) {
+    const s = String(text ?? '').replace(ANSI_RE, '');
+    return root ? s.split(root).join('<install-run>') : s;
+}
+function record(out, root, stage, command, res, started) {
+    const entry = {
+        stage,
+        command,
+        exit_code: res.status,
+        stdout: truncateOutput(scrub(res.stdout ?? '', root)),
+        stderr: truncateOutput(scrub(res.stderr ?? '', root)),
+        duration_ms: Date.now() - started,
+        ...(res.error ? { error: scrub(res.error, root) } : {}),
+    };
+    out.push(entry);
+    return entry;
+}
+function spawnRecorded(out, root, stage, command, file, args, opts) {
+    const started = Date.now();
+    const r = (0, node_child_process_1.spawnSync)(file, args, {
+        cwd: opts.cwd, env: opts.env, encoding: 'utf-8', timeout: opts.timeout ?? COMMAND_TIMEOUT_MS,
+        stdio: ['pipe', 'pipe', 'pipe'], shell: opts.shell ?? false, windowsHide: true,
+    });
+    const error = r.error ? String(r.error.message || r.error) : (r.signal ? `terminated by ${r.signal}` : undefined);
+    return record(out, root, stage, command, { status: r.status, stdout: r.stdout, stderr: r.stderr, error }, started);
+}
+/** Run the install run for `phase` and write its results file. Throws only on a missing phase. */
+function runInstallRun(opts) {
+    const found = findPhaseInternal(opts.cwd, opts.phase);
+    if (!found)
+        throw new Error(`Phase ${opts.phase} not found`);
+    const phaseDirAbs = node_path_1.default.resolve(opts.cwd, found.directory);
+    const rp = getRoadmapPhaseInternal(opts.cwd, opts.phase);
+    const checks = resolveInstallChecks(rp?.section ?? null);
+    const commands = [];
+    const result = {
+        schema: exports.INSTALL_RUN_SCHEMA,
+        phase: found.phase_number,
+        phase_dir: found.directory.split(node_path_1.default.sep).join('/'),
+        generated_at: new Date().toISOString(),
+        verdict: 'fail',
+        reason: '',
+        package: { name: null, version: null, tarball: null, source: null },
+        install: { runtime: 'claude', scope: 'local', npm_mode: null, tools: null },
+        checks: { source: checks.source, line: checks.line, invalid: checks.invalid },
+        commands,
+        failures: [],
+    };
+    const root = node_path_1.default.join(node_os_1.default.tmpdir(), `pp-install-run-${node_crypto_1.default.randomUUID()}`);
+    let applicable = true;
+    let notApplicableReason = '';
+    let initDone = false;
+    let checksRun = false;
+    try {
+        node_fs_1.default.mkdirSync(root, { recursive: true });
+        const home = node_path_1.default.join(root, 'home');
+        const prefix = node_path_1.default.join(root, 'prefix');
+        const fixture = node_path_1.default.join(root, 'fixture');
+        for (const d of [home, prefix, fixture, node_path_1.default.join(root, 'pack')])
+            node_fs_1.default.mkdirSync(d, { recursive: true });
+        const env = buildRunEnv(opts.env ?? process.env, home);
+        const winShell = process.platform === 'win32';
+        // 1. The tarball: given, or built and packed from the package dir.
+        let tarballPath = null;
+        const packageDir = opts.tarball ? null : node_path_1.default.resolve(opts.cwd, opts.packageDir || '.');
+        if (opts.tarball) {
+            tarballPath = node_path_1.default.resolve(opts.cwd, opts.tarball);
+            result.package.source = 'tarball';
+            if (!node_fs_1.default.existsSync(tarballPath)) {
+                record(commands, root, 'pack', `(tarball) ${opts.tarball}`, { status: null, error: 'tarball not found' }, Date.now());
+                tarballPath = null;
+            }
+        }
+        else if (packageDir) {
+            let pkg = null;
+            try {
+                pkg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(packageDir, 'package.json'), 'utf-8'));
+            }
+            catch { /* no package.json */ }
+            if (!isPpCorePackage(pkg)) {
+                applicable = false;
+                notApplicableReason = 'the package dir is not a pp-core package (package.json bin lacks pp-core and pp-tools); nothing to install';
+            }
+            else {
+                result.package.source = 'pack';
+                const built = opts.build === false ? null
+                    : spawnRecorded(commands, root, 'build', 'npm run build', npmCmd(), ['run', 'build'], { cwd: packageDir, env, timeout: BUILD_TIMEOUT_MS, shell: winShell });
+                if (!built || built.exit_code === 0) {
+                    const packed = spawnRecorded(commands, root, 'pack', 'npm pack', npmCmd(), ['pack', '--pack-destination', node_path_1.default.join(root, 'pack')], { cwd: packageDir, env, timeout: BUILD_TIMEOUT_MS, shell: winShell });
+                    const tgz = node_fs_1.default.readdirSync(node_path_1.default.join(root, 'pack')).find((f) => f.endsWith('.tgz'));
+                    if (packed.exit_code === 0 && tgz)
+                        tarballPath = node_path_1.default.join(root, 'pack', tgz);
+                    else if (packed.exit_code === 0) {
+                        packed.exit_code = 1;
+                        packed.error = 'npm pack produced no .tgz';
+                    }
+                }
+            }
+        }
+        const harnessPath = applicable ? findSmokeHarness(packageDir) : null;
+        if (applicable && !harnessPath) {
+            applicable = false;
+            notApplicableReason = `no install harness (${HARNESS_REL.split(node_path_1.default.sep).join('/')}) in the package or the running pp-core`;
+        }
+        if (applicable && tarballPath) {
+            const meta = readTarballPackageJson(tarballPath);
+            result.package.tarball = node_path_1.default.basename(tarballPath);
+            result.package.name = meta && typeof meta['name'] === 'string' ? meta['name'] : null;
+            result.package.version = meta && typeof meta['version'] === 'string' ? meta['version'] : null;
+            // eslint-disable-next-line @typescript-eslint/no-require-imports -- the harness path is resolved at run time
+            const harness = require(harnessPath);
+            // 2. npm install into a temp prefix: offline first, then prefer-offline on a cache miss.
+            const installStarted = Date.now();
+            const smoke = (mode) => harness.runSmoke({
+                tarballPath, installPrefix: prefix, expectedVersion: result.package.version ?? '', lifecycleCommands: [],
+                npmEnv: { ...env, ...(mode === 'offline' ? { npm_config_offline: 'true' } : { npm_config_prefer_offline: 'true' }) },
+            });
+            let mode = 'offline';
+            let s = smoke(mode);
+            const detail = (key) => { const v = s.details[key]; return typeof v === 'string' ? v : ''; };
+            if (s.code === harness.SMOKE.INSTALL_FAILED && /ENOTCACHED/.test(detail('stderr'))) {
+                mode = 'prefer-offline';
+                s = smoke(mode);
+            }
+            result.install.npm_mode = mode;
+            const installCmd = `npm install -g --prefix <install-run>/prefix ${result.package.tarball} --${mode}`;
+            const installed = record(commands, root, 'install', installCmd, {
+                status: s.code === harness.SMOKE.OK ? 0 : 1,
+                stdout: detail('stdout'),
+                stderr: detail('stderr'),
+                error: s.code === harness.SMOKE.OK ? undefined : `harness code ${s.code}`,
+            }, installStarted);
+            // 3. The installer the user runs, in a fresh git project. The global npm
+            // prefix is the temp prefix: the installed product sees only itself
+            // installed globally, as on a fresh machine.
+            const toolEnv = { ...env, npm_config_prefix: prefix };
+            delete toolEnv.NPM_CONFIG_PREFIX;
+            if (installed.exit_code === 0) {
+                (0, node_child_process_1.spawnSync)('git', ['init', '-q'], { cwd: fixture, env, encoding: 'utf-8', timeout: COMMAND_TIMEOUT_MS, windowsHide: true });
+                const instStarted = Date.now();
+                const inst = harness.driveInstaller({
+                    installPrefix: prefix, flags: ['--claude', '--local'], cwd: fixture, configRoot: node_path_1.default.join(fixture, '.claude'), env: toolEnv,
+                });
+                const tools = node_path_1.default.join(fixture, '.claude', 'pp-core', 'bin', 'pp-tools.cjs');
+                const toolsMissing = inst.ok && !node_fs_1.default.existsSync(tools);
+                record(commands, root, 'install', 'pp-core --claude --local', {
+                    status: toolsMissing ? 1 : inst.status, stdout: inst.stdout, stderr: inst.stderr,
+                    error: inst.reason || (toolsMissing ? 'the installer exited 0 but .claude/pp-core/bin/pp-tools.cjs is missing' : undefined),
+                }, instStarted);
+                if (inst.ok && !toolsMissing) {
+                    result.install.tools = '.claude/pp-core/bin/pp-tools.cjs';
+                    const runTool = (stage, label, argv) => spawnRecorded(commands, root, stage, label, process.execPath, [tools, ...argv], { cwd: fixture, env: toolEnv });
+                    // 4. init, non-interactively, through the installed pp-tools.
+                    for (let i = 0; i < INIT_MAX_STEPS && !initDone; i++) {
+                        const next = runTool('init', 'pp-tools query init-contract --session-next --offline', ['query', 'init-contract', '--session-next', '--offline']);
+                        if (next.exit_code !== 0)
+                            break;
+                        let state;
+                        try {
+                            state = JSON.parse(next.stdout);
+                        }
+                        catch {
+                            next.exit_code = 1;
+                            next.error = 'unparseable init session state';
+                            break;
+                        }
+                        if (state.done) {
+                            initDone = true;
+                            break;
+                        }
+                        const step = String(state.step ?? '');
+                        const answer = exports.INIT_ANSWERS[step] ?? state.preselected ?? (state.optionalAnswer ? '' : undefined);
+                        if (answer === undefined) {
+                            next.exit_code = 1;
+                            next.error = `no fixture answer for init step "${step}"`;
+                            break;
+                        }
+                        const ans = runTool('init', `pp-tools query init-contract --session-answer ${step}=… --offline`, ['query', 'init-contract', '--session-answer', `${step}=${answer}`, '--offline']);
+                        if (ans.exit_code !== 0)
+                            break;
+                    }
+                    // 5. The phase's install checks against the installed copy.
+                    for (const check of checks.commands)
+                        runTool('check', check.text, check.argv);
+                    checksRun = true;
+                }
+            }
+        }
+    }
+    finally {
+        try {
+            node_fs_1.default.rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+        }
+        catch { /* best-effort */ }
+    }
+    const v = computeInstallVerdict({ applicable, notApplicableReason, commands, invalid: checks.invalid, initDone, checksRun });
+    result.verdict = v.verdict;
+    result.reason = v.reason;
+    result.failures = v.failures;
+    const resultsFile = node_path_1.default.join(phaseDirAbs, `${found.phase_number}-${exports.INSTALL_RUN_SUFFIX}`);
+    node_fs_1.default.writeFileSync(resultsFile, JSON.stringify(result, null, 2) + '\n');
+    return { ...result, results_file: node_path_1.default.relative(opts.cwd, resultsFile).split(node_path_1.default.sep).join('/') };
+}

package/pp-core/bin/lib/io.cjs

@@ -161,6 +161,7 @@ const ERROR_REASON = Object.freeze({
     CONFIG_NO_FILE: 'config_no_file',
     CONFIG_PARSE_FAILED: 'config_parse_failed',
     CONFIG_INVALID_KEY: 'config_invalid_key',
+    CONFIG_INVALID_VALUE: 'config_invalid_value',
     // SDK / pp-tools dispatch
     SDK_FAIL_FAST: 'sdk_fail_fast',
     SDK_UNKNOWN_COMMAND: 'sdk_unknown_command',
@@ -186,6 +187,20 @@ const ERROR_REASON = Object.freeze({
     VAULT_PROMOTE_TARGET_REFUSED: 'vault_promote_target_refused',
     VAULT_PROMOTE_CONCURRENT_EDIT: 'vault_promote_concurrent_edit',
     VAULT_PROMOTE_TRANSPORT_FAILED: 'vault_promote_transport_failed',
+    // discovery rollup (discovery-v2 Phase 1: D-07/D-08 gate)
+    DISCOVERY_ROLLUP_PARSE_FAILED: 'discovery_rollup_parse_failed',
+    DISCOVERY_ROLLUP_MISMATCH: 'discovery_rollup_mismatch',
+    // discovery input package (discovery-v2 Phase 2: D-19/D-22 gate)
+    DISCOVERY_INPUT_CHECK_FAILED: 'discovery_input_check_failed',
+    // discovery research track (discovery-v2 Phase 3: D-42/D-43 gate)
+    DISCOVERY_RESEARCH_CHECK_FAILED: 'discovery_research_check_failed',
+    // discovery screen inventory (discovery-v2 Phase 4: D-52/D-53 gate)
+    DISCOVERY_SCREEN_CHECK_FAILED: 'discovery_screen_check_failed',
+    DISCOVERY_FEEDBACK_OPEN: 'discovery_feedback_open',
+    // discovery prototype element sweep
+    DISCOVERY_ELEMENT_SWEEP_FAILED: 'discovery_element_sweep_failed',
+    // discovery scope re-baselining (discovery-v2 Phase 5: D-72/D-73 gate)
+    DISCOVERY_REBASELINE_CHECK_FAILED: 'discovery_rebaseline_check_failed',
     // generic
     USAGE: 'usage',
     UNKNOWN: 'unknown',

package/pp-core/bin/lib/loop-resolver.cjs

@@ -41,6 +41,8 @@ const { resolveCapabilityRuntimeState } = capabilityStateModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityActivationModule = require("./capability-activation.cjs");
 const { _getNestedConfigValue, _readRawConfigKey, _resolveActivationValue, resolveConfigKey } = capabilityActivationModule;
+// ─── Phase ceremony tier (pack 9): `--phase` / `--tier` overlay ───────────────
+const phase_tier_cjs_1 = require("./phase-tier.cjs");
 // ─── Canonical points (derived from LOOP_HOST_CONTRACT — authoritative 12) ───
 // FIX 2: Derive the authoritative canonical set from LOOP_HOST_CONTRACT so it
 // cannot drift from the host contract. CANONICAL_POINTS_FALLBACK is kept as an
@@ -400,6 +402,14 @@ function renderLoopHooks(resolved) {
  * No JSON envelope is emitted — output is clean for shell $(…) capture.
  * Missing <capId> value → coreError + non-zero exit.
  * Unknown/inactive capId → `false` (not an error).
+ *
+ * --phase <N> [--tier light|standard|heavy] (pack 9): resolve the phase's
+ * ceremony tier (src/phase-tier.cts) and overlay its gate booleans
+ * (`workflow.research`, `workflow.pattern_mapper`, …) on the config snapshot
+ * BEFORE capability state and hook activation read it, so every `when` /
+ * activation key of those gates answers the tier-resolved value. Without
+ * `--phase` the project's own booleans are read as before (an explicitly
+ * invoked gate command such as /pp-secure-phase is not governed by a tier).
  */
 function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (!point) {
@@ -429,6 +439,17 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     catch {
         config = {};
     }
+    const tierPhase = typeof options['phase'] === 'string' && options['phase'] !== '' ? options['phase'] : null;
+    const tierCli = typeof options['tier'] === 'string' && options['tier'] !== '' ? options['tier'] : null;
+    let phaseTier = null;
+    if (tierPhase !== null || tierCli !== null) {
+        if (tierCli !== null && !['light', 'standard', 'heavy'].includes(tierCli)) {
+            coreError('--tier needs one of light, standard, heavy');
+            return;
+        }
+        phaseTier = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, tierPhase, tierCli);
+        config = (0, phase_tier_cjs_1.overlayTierGates)(config, phaseTier);
+    }
     const state = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, config);
     // Registry is the static generated module — same object capability-state uses internally.
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -458,6 +479,9 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
         activeHooks: resolved.activeHooks,
         rendered,
     };
+    if (phaseTier) {
+        envelope.phase_tier = { phase: tierPhase, tier: phaseTier.tier, source: phaseTier.source, suppressed: phaseTier.suppressed };
+    }
     if (state.warnings && state.warnings.length > 0) {
         envelope.warnings = state.warnings;
     }