@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/observability/redaction.cjs

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Arg redaction policy — issue #177 (ADR-457 build-at-publish: the
+ * hand-written bin/lib/observability/redaction.cjs collapsed to a TypeScript
+ * source of truth). Behaviour is preserved byte-for-behaviour from the prior
+ * hand-written .cjs; only types are added.
+ *
+ * Privacy default: args are OMITTED from every emitted event (both stderr
+ * and file audit). Opt-in: set GSD_AUDIT_ARGS=1 to include args verbatim.
+ *
+ * This module is deliberately simple and has no side effects — redaction
+ * decisions are stateless reads of process.env at call time so that tests
+ * can toggle the env var without module-level caching issues.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldIncludeArgs = shouldIncludeArgs;
+exports.redactEvent = redactEvent;
+/**
+ * Returns true when the caller has opted in to including args in events.
+ * Only GSD_AUDIT_ARGS === '1' enables inclusion; any other value (including
+ * empty string, 'true', 'yes') keeps the default of omitting args.
+ */
+function shouldIncludeArgs() {
+    return process.env.GSD_AUDIT_ARGS === '1';
+}
+/**
+ * Return a redacted copy of a DispatchEvent.
+ *
+ * If args should be omitted (default), strips the `args` field entirely.
+ * If args should be included (GSD_AUDIT_ARGS=1), passes the event through
+ * unchanged (args were already set by makeDispatchEvent with includeArgs:true,
+ * or absent — in which case they stay absent).
+ *
+ * The original event object is never mutated (it is frozen by makeDispatchEvent).
+ *
+ * @param event - A DispatchEvent (frozen or plain).
+ * @returns A new plain object with the same fields, minus args when redacted.
+ */
+function redactEvent(event) {
+    if (shouldIncludeArgs()) {
+        // Include path: return a shallow copy with args preserved if present
+        const copy = Object.assign({}, event);
+        return copy;
+    }
+    // Exclude path: build a copy omitting `args`
+    const { args: _dropped, ...rest } = event;
+    return rest;
+}

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

@@ -0,0 +1,35 @@
+// @generated by scripts/generate-package-identity.cjs from package.json — DO NOT EDIT.
+// Single source for PP package coordinates (issue #498). Regenerate with:
+//   node scripts/generate-package-identity.cjs
+'use strict';
+
+const packageName = "@pareto4/pp-core";
+const binName = "pp-core";
+const repoSlug = "pareto4/pp-core";
+const repoUrl = "https://gitlab.com/pareto4/pp-core";
+const changelogRawUrl = "https://gitlab.com/pareto4/pp-core/-/raw/main/CHANGELOG.md";
+const cacheSlug = "pareto4-pp-core";
+const updateCacheFileName = "pp-update-check-pareto4-pp-core.json";
+
+function formatManualInstall({ packageName, binName, scope, runtime } = {}) {
+  const runtimeFlag = runtime ? ` --${runtime}` : '';
+  return `npx -y --package=${packageName}@latest -- ${binName}${runtimeFlag} --${scope}`;
+}
+
+function manualInstallCommand(opts = {}) {
+  return formatManualInstall({ packageName, binName, scope: opts.scope, runtime: opts.runtime });
+}
+
+module.exports = Object.freeze({
+  packageName,
+  // PACKAGE_NAME: back-compat alias for #516-era consumers. Baked here, so it
+  // survives the installed tree's synthetic package.json (fixes the #378 undefined).
+  PACKAGE_NAME: packageName,
+  binName,
+  repoSlug,
+  repoUrl,
+  changelogRawUrl,
+  cacheSlug,
+  updateCacheFileName,
+  manualInstallCommand,
+});

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

@@ -0,0 +1,368 @@
+"use strict";
+/**
+ * Package Legitimacy Module
+ *
+ * Replaces the bolt-on prose slopcheck gate (which pip-installed `slopcheck`
+ * and degraded ALL packages to [ASSUMED] when pip failed) with registry-API
+ * verdicts computed in code.
+ *
+ * Public interface:
+ *   DEFAULT_THRESHOLDS  — baseline thresholds
+ *   classifyPackage     — pure function: signals → { verdict, reasons }
+ *   checkPackages       — async: resolves registry signals and classifies
+ *   _setHttpGet         — test seam: override the HTTP transport (pass null to restore)
+ *
+ * All network IO is injected via a `registry` client option so that tests
+ * never touch the real network (same seam pattern as clock injection).
+ *
+ * ADR-457 build-at-publish: authored as TypeScript .cts → emits .cjs via tsc.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+const https = __importStar(require("node:https"));
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_THRESHOLDS = {
+    minAgeDays: 30,
+    minWeeklyDownloads: 1000,
+    requireRepo: true,
+};
+// Matches common dangerous postinstall execution patterns.
+// Deliberately EXCLUDES bare https?:// (over-fires on legit packages like
+// esbuild/sharp/node-gyp that reference download URLs without executing them).
+// Shell-execution / download-and-exec signatures only:
+const SUSPICIOUS_POSTINSTALL_RE = /(curl |wget |\|\s*(ba)?sh|bash -c|sh -c|node -e|eval|base64 -d|\/etc\/|\.\.\/|~\/|nc |>\s*\/)/i;
+// ---------------------------------------------------------------------------
+// Severity ordering for verdict merging (SLOP > SUS > OK)
+// ---------------------------------------------------------------------------
+const SEVERITY = { OK: 0, SUS: 1, SLOP: 2 };
+function moreSevereVerdict(a, b) {
+    return SEVERITY[a] >= SEVERITY[b] ? a : b;
+}
+// ---------------------------------------------------------------------------
+// classifyPackage — pure, no IO
+// ---------------------------------------------------------------------------
+function classifyPackage(signals, { thresholds = DEFAULT_THRESHOLDS, clock = Date } = {}) {
+    const reasons = [];
+    // Terminal: package does not exist
+    if (signals.exists === false) {
+        return { verdict: 'SLOP', reasons: ['does-not-exist'] };
+    }
+    // Age check
+    if (signals.publishedAt == null) {
+        reasons.push('unknown-age');
+    }
+    else {
+        const parsed = Date.parse(String(signals.publishedAt));
+        if (!Number.isFinite(parsed)) {
+            // Unparseable date — treat as unknown
+            reasons.push('unknown-age');
+        }
+        else {
+            const ageDays = Math.floor((clock.now() - parsed) / 86_400_000);
+            if (ageDays < thresholds.minAgeDays) {
+                reasons.push('too-new');
+            }
+        }
+    }
+    // Downloads check
+    const downloads = signals.weeklyDownloads;
+    if (downloads == null) {
+        reasons.push('unknown-downloads');
+    }
+    else if (typeof downloads !== 'number' || !Number.isFinite(downloads)) {
+        // Odd type / NaN — treat as unknown
+        reasons.push('unknown-downloads');
+    }
+    else if (downloads < thresholds.minWeeklyDownloads) {
+        reasons.push('low-downloads');
+    }
+    // Repository check
+    if (thresholds.requireRepo && !signals.repoUrl) {
+        reasons.push('no-repository');
+    }
+    // Deprecated check
+    if (signals.deprecated === true) {
+        reasons.push('deprecated');
+    }
+    // Suspicious postinstall (npm only — but apply whenever postinstall is present)
+    if (signals.postinstall != null && typeof signals.postinstall === 'string') {
+        if (SUSPICIOUS_POSTINSTALL_RE.test(signals.postinstall)) {
+            reasons.push('suspicious-postinstall');
+        }
+    }
+    // Terminal: suspicious postinstall is a slopsquatting execution risk
+    if (reasons.includes('suspicious-postinstall')) {
+        return { verdict: 'SLOP', reasons };
+    }
+    const verdict = reasons.length > 0 ? 'SUS' : 'OK';
+    return { verdict, reasons };
+}
+// ---------------------------------------------------------------------------
+// Injectable HTTP transport (test seam — W1)
+// ---------------------------------------------------------------------------
+/** The real HTTPS transport — resolves { statusCode, body } */
+function realHttpsGet(url, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const req = https.get(url, { headers: { 'User-Agent': 'gsd-core-package-legitimacy/1.0' } }, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => resolve({
+                statusCode: res.statusCode ?? 0,
+                body: Buffer.concat(chunks).toString('utf8'),
+            }));
+            res.on('error', reject);
+        });
+        req.setTimeout(timeoutMs, () => {
+            req.destroy(new Error(`timeout after ${timeoutMs}ms`));
+        });
+        req.on('error', reject);
+    });
+}
+/** Module-level transport pointer — overrideable via _setHttpGet for tests */
+let httpsGet = realHttpsGet;
+/**
+ * Test seam: replace the HTTP transport. Pass null to restore the real transport.
+ * Tests call this before exercising a real-adapter code path; always restore in finally.
+ */
+function _setHttpGet(fn) {
+    httpsGet = fn ?? realHttpsGet;
+}
+// ---------------------------------------------------------------------------
+// Real registry adapters (not exercised by tests — tests inject fakes)
+// ---------------------------------------------------------------------------
+function degradedSignals() {
+    return {
+        exists: null,
+        publishedAt: null,
+        weeklyDownloads: null,
+        repoUrl: null,
+        deprecated: false,
+        postinstall: null,
+    };
+}
+async function lookupNpm(name, version) {
+    try {
+        const resp = await httpsGet(`https://registry.npmjs.org/${encodeURIComponent(name)}`, 5000);
+        if (resp.statusCode === 404)
+            return { ...degradedSignals(), exists: false };
+        if (resp.statusCode < 200 || resp.statusCode >= 300)
+            return degradedSignals();
+        const data = JSON.parse(resp.body);
+        if (data.error)
+            return { ...degradedSignals(), exists: false };
+        const time = data.time ?? {};
+        const allVersions = data.versions ?? {};
+        // I3: when a specific version is requested, verify it exists
+        if (version !== undefined) {
+            if (!(version in allVersions)) {
+                return { ...degradedSignals(), exists: false };
+            }
+        }
+        const latestVersion = data['dist-tags']?.latest ?? '';
+        const resolvedVersion = version !== undefined ? version : latestVersion;
+        const versionMeta = allVersions[resolvedVersion] ?? {};
+        const scripts = versionMeta.scripts ??
+            {};
+        const postinstall = scripts.postinstall ?? null;
+        const repoField = versionMeta.repository;
+        let repoUrl = null;
+        if (typeof repoField === 'string')
+            repoUrl = repoField;
+        else if (repoField && typeof repoField.url === 'string') {
+            repoUrl = repoField.url;
+        }
+        const deprecated = typeof versionMeta.deprecated === 'string' ? true : false;
+        // Fetch weekly download count from the npm downloads API
+        let weeklyDownloads = null;
+        try {
+            const dlResp = await httpsGet(`https://api.npmjs.org/downloads/point/last-week/${encodeURIComponent(name)}`, 5000);
+            if (dlResp.statusCode >= 200 && dlResp.statusCode < 300) {
+                const dlData = JSON.parse(dlResp.body);
+                if (typeof dlData.downloads === 'number') {
+                    weeklyDownloads = dlData.downloads;
+                }
+            }
+        }
+        catch {
+            // Degraded: leave weeklyDownloads as null, never throw
+        }
+        return {
+            exists: true,
+            publishedAt: time[resolvedVersion] ?? time.created ?? null,
+            weeklyDownloads,
+            repoUrl,
+            deprecated,
+            postinstall,
+            ecosystem: 'npm',
+        };
+    }
+    catch {
+        return degradedSignals();
+    }
+}
+async function lookupPypi(name, version) {
+    try {
+        const resp = await httpsGet(`https://pypi.org/pypi/${encodeURIComponent(name)}/json`, 5000);
+        if (resp.statusCode === 404)
+            return { ...degradedSignals(), exists: false };
+        if (resp.statusCode < 200 || resp.statusCode >= 300)
+            return degradedSignals();
+        const data = JSON.parse(resp.body);
+        const info = data.info ?? {};
+        // I3: when a specific version is requested, verify it exists in releases
+        const releases = data.releases ?? {};
+        if (version !== undefined) {
+            if (!(version in releases)) {
+                return { ...degradedSignals(), exists: false };
+            }
+        }
+        // Finding 2: when version is provided, derive publishedAt from the
+        // version-specific release record rather than the package-level urls[] array
+        // (which reflects the latest release, not the requested version).
+        let uploadTime = null;
+        if (version !== undefined) {
+            const versionFiles = releases[version] ?? [];
+            uploadTime =
+                versionFiles.length > 0
+                    ? versionFiles[0].upload_time_iso_8601 ?? null
+                    : null;
+        }
+        else {
+            const urls = data.urls ?? [];
+            uploadTime =
+                urls.length > 0 ? urls[0].upload_time_iso_8601 ?? null : null;
+        }
+        const projectUrls = info.project_urls;
+        const repoUrl = projectUrls?.['Source'] ??
+            projectUrls?.['Homepage'] ??
+            info.home_page ??
+            null;
+        return {
+            exists: true,
+            publishedAt: uploadTime,
+            weeklyDownloads: null, // PyPI weekly downloads require a separate API
+            repoUrl: repoUrl || null,
+            deprecated: false, // PyPI doesn't have a first-class deprecated field
+            postinstall: null, // Not applicable for PyPI
+            ecosystem: 'pypi',
+        };
+    }
+    catch {
+        return degradedSignals();
+    }
+}
+async function lookupCrates(name, version) {
+    try {
+        const resp = await httpsGet(`https://crates.io/api/v1/crates/${encodeURIComponent(name)}`, 5000);
+        if (resp.statusCode === 404)
+            return { ...degradedSignals(), exists: false };
+        if (resp.statusCode < 200 || resp.statusCode >= 300)
+            return degradedSignals();
+        const data = JSON.parse(resp.body);
+        const krate = data.crate ?? {};
+        // I3: when a specific version is requested, verify it exists in versions list
+        const versions = data.versions ?? [];
+        if (version !== undefined) {
+            const found = versions.some((v) => v.num === version);
+            if (!found) {
+                return { ...degradedSignals(), exists: false };
+            }
+        }
+        const repoUrl = krate.repository ?? null;
+        // Finding 2: when version is provided, use the version-specific created_at
+        // rather than the package-level crate.created_at (first-ever publish date).
+        let created;
+        if (version !== undefined) {
+            const versionObj = versions.find((v) => v.num === version);
+            created = versionObj?.created_at ?? null;
+        }
+        else {
+            created = krate.created_at ?? null;
+        }
+        // recent_downloads is a 90-day count; normalize to a weekly figure for comparison
+        // against minWeeklyDownloads (which is a weekly threshold).
+        const rawDownloads = krate.recent_downloads;
+        const downloads = (rawDownloads != null && typeof Number(rawDownloads) === 'number' && !isNaN(Number(rawDownloads)))
+            ? Math.round(Number(rawDownloads) * 7 / 90)
+            : null;
+        return {
+            exists: true,
+            publishedAt: created,
+            weeklyDownloads: downloads,
+            repoUrl,
+            deprecated: false,
+            postinstall: null,
+            ecosystem: 'crates',
+        };
+    }
+    catch {
+        return degradedSignals();
+    }
+}
+const realRegistry = {
+    async lookup(ecosystem, name, version) {
+        switch (ecosystem) {
+            case 'npm':
+                return lookupNpm(name, version);
+            case 'pypi':
+                return lookupPypi(name, version);
+            case 'crates':
+                return lookupCrates(name, version);
+            default:
+                return degradedSignals();
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// checkPackages — orchestrates lookup + classify + slopcheck merge
+// ---------------------------------------------------------------------------
+async function checkPackages({ ecosystem, packages, version }, { registry = realRegistry, clock = Date, thresholds = DEFAULT_THRESHOLDS, slopcheck = null, } = {}) {
+    const results = [];
+    for (const name of packages) {
+        const signals = await registry.lookup(ecosystem, name, version);
+        const { verdict: registryVerdict, reasons } = classifyPackage(signals, { thresholds, clock });
+        let finalVerdict = registryVerdict;
+        if (slopcheck != null) {
+            const slopVerdict = await slopcheck.check(ecosystem, name);
+            if (slopVerdict != null) {
+                finalVerdict = moreSevereVerdict(finalVerdict, slopVerdict);
+            }
+        }
+        results.push({ name, verdict: finalVerdict, signals, reasons });
+    }
+    return results;
+}
+module.exports = { DEFAULT_THRESHOLDS, classifyPackage, checkPackages, _setHttpGet };

package/pp-core/bin/lib/phase-command-router.cjs

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * Manifest-backed phase subcommand router.
+ * Keeps gsd-tools.cjs thin while preserving existing command semantics.
+ *
+ * Unsupported in this router:
+ * - scaffold: routed through top-level scaffold command.
+ *
+ * CJS-only subcommands: mvp-mode (dispatched directly, before hub).
+ *
+ * #3788: dispatch is mediated by CommandRoutingHub. The public entry point
+ * and observable CLI behaviour are unchanged.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/phase-command-router.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+const command_aliases_cjs_1 = require("./command-aliases.cjs");
+// ─── CommandRoutingHub (issue #3788, simplified in #175, typed in #176) ───────
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const commandRoutingHub = require("./command-routing-hub.cjs");
+const { createHub, ERROR_KINDS, makeInvalidArgs } = commandRoutingHub;
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routePhaseCommand({ phase, args, cwd, raw, error }) {
+    // ── Unsupported subcommands ─────────────────────────────────────────────────
+    // Resolved before dispatch so the error message stays deterministic.
+    const UNSUPPORTED = {
+        scaffold: 'phase scaffold is routed through the top-level scaffold command.',
+    };
+    const subcommand = args[1];
+    if (subcommand && UNSUPPORTED[subcommand]) {
+        error(UNSUPPORTED[subcommand]);
+        return;
+    }
+    // ── No subcommand → reject early with helpful error ────────────────────────
+    // Pre-#3788 code resolved unknown subcommands via routeCjsCommandFamily which
+    // fell through to error() when no handler matched (including undefined).
+    // Post-#3788 the hub's manifest check is skipped for falsy subcommand, so we
+    // must guard here to preserve the deterministic "Available: ..." error message.
+    if (!subcommand) {
+        const available = command_aliases_cjs_1.PHASE_SUBCOMMANDS.filter(s => !UNSUPPORTED[s]).join(', ');
+        error(`Unknown phase subcommand. Available: ${available}`);
+        return;
+    }
+    // ── CJS-only subcommands (dispatched directly, before hub) ─────────────────
+    // `mvp-mode` has a CJS-native implementation in phase.cmdPhaseMvpMode that
+    // differs from the SDK query layer (different ROADMAP scan + error codes).
+    // Dispatch it early to preserve pre-migration observable behaviour (correct
+    // exit code, correct JSON error reason code, correct ROADMAP scan).
+    if (subcommand === 'mvp-mode') {
+        phase.cmdPhaseMvpMode(cwd, args.slice(2), raw);
+        return;
+    }
+    // ── Build the CJS registry ──────────────────────────────────────────────────
+    // Each handler receives a ctx object from the hub and must return a HubResult.
+    const cjsRegistry = {
+        phase: {
+            'next-decimal': (_ctx) => {
+                phase.cmdPhaseNextDecimal(cwd, args[2], raw);
+                return { ok: true, data: null };
+            },
+            add: (_ctx) => {
+                let customId = null;
+                const descArgs = [];
+                for (let i = 2; i < args.length; i++) {
+                    const token = args[i];
+                    if (token === '--raw') {
+                        continue;
+                    }
+                    if (token === '--id') {
+                        const id = args[i + 1];
+                        if (!id || id.startsWith('--')) {
+                            return makeInvalidArgs('--id', '--id requires a value');
+                        }
+                        customId = id;
+                        i++;
+                    }
+                    else if (token.startsWith('--')) {
+                        return makeInvalidArgs(token, `phase add does not support ${token}`);
+                    }
+                    else {
+                        descArgs.push(token);
+                    }
+                }
+                phase.cmdPhaseAdd(cwd, descArgs.join(' '), raw, customId);
+                return { ok: true, data: null };
+            },
+            'add-batch': (_ctx) => {
+                const descFlagIdx = args.indexOf('--descriptions');
+                let descriptions;
+                if (descFlagIdx !== -1) {
+                    const rawDescriptions = args[descFlagIdx + 1];
+                    if (!rawDescriptions || rawDescriptions.startsWith('--')) {
+                        return makeInvalidArgs('--descriptions', '--descriptions must be a JSON array');
+                    }
+                    try {
+                        descriptions = JSON.parse(rawDescriptions);
+                    }
+                    catch {
+                        return makeInvalidArgs('--descriptions', '--descriptions must be a JSON array');
+                    }
+                    if (!Array.isArray(descriptions)) {
+                        return makeInvalidArgs('--descriptions', '--descriptions must be a JSON array');
+                    }
+                }
+                else {
+                    descriptions = args.slice(2).filter(a => a !== '--raw');
+                }
+                phase.cmdPhaseAddBatch(cwd, descriptions, raw);
+                return { ok: true, data: null };
+            },
+            insert: (_ctx) => {
+                if (args.includes('--dry-run')) {
+                    return makeInvalidArgs('--dry-run', 'phase insert does not support --dry-run');
+                }
+                phase.cmdPhaseInsert(cwd, args[2], args.slice(3).join(' '), raw);
+                return { ok: true, data: null };
+            },
+            remove: (_ctx) => {
+                const removeArgs = args.slice(2).filter(token => token !== '--raw');
+                let forceFlag = false;
+                const positional = [];
+                for (const token of removeArgs) {
+                    if (token === '--force') {
+                        forceFlag = true;
+                        continue;
+                    }
+                    if (token.startsWith('--')) {
+                        return makeInvalidArgs(token, `phase remove does not support ${token}`);
+                    }
+                    positional.push(token);
+                }
+                if (positional.length !== 1) {
+                    return makeInvalidArgs('<phase-number>', 'phase remove accepts exactly one phase number');
+                }
+                phase.cmdPhaseRemove(cwd, positional[0], { force: forceFlag }, raw);
+                return { ok: true, data: null };
+            },
+            complete: (_ctx) => {
+                phase.cmdPhaseComplete(cwd, args[2], raw);
+                return { ok: true, data: null };
+            },
+            'uat-passed': (_ctx) => {
+                let requireVerification = false;
+                const positional = [];
+                for (const token of args.slice(2)) {
+                    if (token === '--require-verification') {
+                        requireVerification = true;
+                    }
+                    else if (token === '--raw') {
+                        // --raw is handled by the outer CLI layer; accepted here silently
+                    }
+                    else if (token.startsWith('--')) {
+                        return makeInvalidArgs(token, `phase uat-passed does not support ${token}`);
+                    }
+                    else {
+                        positional.push(token);
+                    }
+                }
+                phase.cmdPhaseUatPassed(cwd, positional[0], raw, { policy: { requireVerification } });
+                return { ok: true, data: null };
+            },
+        },
+    };
+    // ── Build manifest (available subcommands for UnknownCommand detection) ─────
+    // `availableSubcommands` is what the error message shows. It excludes
+    // unsupported commands (already handled above) but does NOT include 'mvp-mode'
+    // because it was absent from PHASE_SUBCOMMANDS in the original and was not
+    // shown in the "Available:" list there either.
+    //
+    // `manifestSubcommands` is the full routing set for the hub — it includes
+    // 'mvp-mode' (which the original code routed via a handler even without a
+    // manifest entry) so the hub's UnknownCommand check passes for it.
+    const availableSubcommands = command_aliases_cjs_1.PHASE_SUBCOMMANDS.filter(s => !UNSUPPORTED[s]);
+    const manifestSubcommands = ['mvp-mode', ...availableSubcommands];
+    const manifest = { phase: manifestSubcommands };
+    // ── Construct hub ──────────────────────────────────────────────────────────
+    // #175: Hub is CJS-only — no mode param, no sdkLoader.
+    const hub = createHub({ cjsRegistry, manifest });
+    // ── Dispatch ────────────────────────────────────────────────────────────────
+    const result = hub.dispatch({
+        family: 'phase',
+        subcommand,
+        args: args.slice(2),
+        cwd,
+        raw,
+    });
+    // ── Translate result → CLI output / error (adapter responsibility) ──────────
+    // CJS handlers call output() themselves (inside phase.cmdPhase*()).
+    // No further output call is needed here.
+    if (!result.ok) {
+        if (result.kind === ERROR_KINDS.UnknownCommand) {
+            const available = availableSubcommands.join(', ');
+            error(`Unknown phase subcommand. Available: ${available}`);
+            return;
+        }
+        if (result.kind === ERROR_KINDS.InvalidArgs || result.kind === ERROR_KINDS.HandlerRefusal) {
+            // #176: typed payload — reason holds the human-readable message
+            error(result.reason);
+            return;
+        }
+        // HandlerFailure: message field
+        error(result.message);
+        return;
+    }
+}
+module.exports = {
+    routePhaseCommand,
+};