@pareto4/pp-core 1.12.1 → 1.13.0

package/pp-core/bin/lib/init-contract.cjs

@@ -44,7 +44,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INIT_SESSION_WRITE_FAILED = exports.INIT_SESSION_MALFORMED = exports.INIT_CONTRACT_FLAGS = exports.INIT_COMPOSE_DECLINED_KEY = void 0;
+exports.INIT_SESSION_WRITE_FAILED = exports.INIT_SESSION_MALFORMED = exports.INIT_CONTRACT_FLAGS = exports.INIT_ORG_PROFILE_DECLINED_KEY = exports.INIT_COMPOSE_DECLINED_KEY = void 0;
 exports.buildInitQuestions = buildInitQuestions;
 exports.verifyInitInvariants = verifyInitInvariants;
 exports.initSessionNext = initSessionNext;
@@ -74,6 +74,21 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
  * a bare unregistered top-level namespace would trip.
  */
 exports.INIT_COMPOSE_DECLINED_KEY = 'init.compose_declined';
+/**
+ * The dotted `.planning/config.json` key `pp-tools init` sets when the
+ * operator is offered a detected org profile and SKIPS it — a blank answer or
+ * `none` in any letter case. It is the only signal that tells "offered a
+ * detected profile and skipped it" from "the question never ran": both leave
+ * `org.profile` unset, and without it `verifyInitInvariants` reported every
+ * deliberate skip as `INIT_QUESTIONS_ORG_PROFILE_UNASKED`. Written by
+ * `initSessionAnswer` only when a profile was detectable (the predicate the
+ * violation reads), read back with strict boolean identity, and written back
+ * to `false` when a later run selects a profile. Registered under the
+ * `vault` capability so `config-set` accepts it. Kept OFF
+ * `ORG_PROFILE_ALLOWLIST`: a profile package must never answer the question
+ * about itself.
+ */
+exports.INIT_ORG_PROFILE_DECLINED_KEY = 'init.org_profile_declined';
 /** The identity-only choices appended after the provider seam's own
  * `PROVIDERS` list — never retyped ahead of `PROVIDERS` itself (T-34-50). */
 const IDENTITY_ONLY_PROVIDER_OPTIONS = Object.freeze(['github', 'other', 'none']);
@@ -167,10 +182,12 @@ function getDotted(obj, dottedPath) {
  * `optionalAnswer: true` — that flag describes the ANSWER (pressing Enter
  * is a complete, valid response), never whether the question is asked.
  *
- * Question 6 (`org_profile`)'s `preselected` is resolved via
- * `resolveDetectedOrgProfile` — set only when exactly one org-profile-shaped
- * package is installed (INIT-PATCH-C); the prompt text is built from that
- * detected value rather than kept as two hard-coded strings that can drift.
+ * Question 6 (`org_profile`) names a HINT, never a default: when
+ * `resolveDetectedOrgProfile` finds exactly one org-profile-shaped package
+ * installed (INIT-PATCH-C), the prompt names it, Enter skips, and typing its
+ * name (or any other) selects it — the question carries no `preselected`.
+ * The prompt text is built from that detected value rather than kept as two
+ * hard-coded strings that can drift.
  * `opts._globalRoot` is forwarded to it unchanged, the same test-seam
  * convention `verifyInitInvariants`'s own `_globalRoot` already follows —
  * production callers omit it.
@@ -201,14 +218,16 @@ function buildInitQuestions(cwd, opts = {}) {
     // stays maximally strict, no allowlist entry was added for it. The detected
     // value itself is never a literal in this file — it is a runtime string
     // read from an installed package, interpolated into the prompt below.
+    // A detected profile is a HINT, never a default: no `preselected`, so a
+    // profile installed on the operator's machine (perhaps another client's)
+    // never becomes a project's binding by pressing Enter. Enter skips (and
+    // `initSessionAnswer` records the skip); typing the name selects it.
     const orgProfileQuestion = isUsableString(detectedOrgProfile)
         ? {
             id: 'org_profile',
-            prompt: `Org profile package (optional — a single installed org profile was detected: "${detectedOrgProfile}". ` +
-                'Press Enter to use it, type "none" to skip it, or type a different package name.)',
+            prompt: `Org profile package (optional — "${detectedOrgProfile}" is installed: type its name to use it, ` +
+                'or press Enter to skip)',
             optionalAnswer: true,
-            preselected: detectedOrgProfile,
-            preselectedLabel: `${detectedOrgProfile} (detected installed profile)`,
         }
         : {
             id: 'org_profile',
@@ -242,36 +261,6 @@ function buildInitQuestions(cwd, opts = {}) {
     ];
 }
 // ─── verifyInitInvariants ───────────────────────────────────────────────────
-/**
- * Byte-for-byte the same heuristic `src/org-profile.cts`'s own (private,
- * unexported) `resolveGlobalPackageRoot` uses. Duplicated here because it
- * is not part of that module's public surface — the same per-module
- * duplication convention every sibling seam module in this repo follows
- * for helpers it cannot import without either widening an unrelated
- * module's exports or risking a require cycle.
- */
-function resolveGlobalNodeModulesRoot() {
-    try {
-        const prefixEnv = process.env.NPM_CONFIG_PREFIX ?? process.env.npm_config_prefix;
-        let candidate;
-        if (typeof prefixEnv === 'string' && prefixEnv.trim() !== '') {
-            const prefix = prefixEnv.trim();
-            candidate =
-                process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules');
-        }
-        else {
-            const execDir = node_path_1.default.dirname(process.execPath);
-            candidate =
-                process.platform === 'win32'
-                    ? node_path_1.default.join(execDir, 'node_modules')
-                    : node_path_1.default.resolve(execDir, '..', 'lib', 'node_modules');
-        }
-        return node_fs_1.default.existsSync(candidate) ? candidate : null;
-    }
-    catch {
-        return null;
-    }
-}
 /** Conservative npm-package-name shape check (bare `name` or scoped
  * `@scope/name`; lowercase, digits, `.`/`_`/`-`, never leading `.`/`_` in
  * either segment). A directory name that does not match is never offered as
@@ -367,15 +356,27 @@ function collectOrgProfileShapedPackages(nodeModulesDir, opts = {}) {
 function containsOrgProfileShapedPackage(nodeModulesDir) {
     return collectOrgProfileShapedPackages(nodeModulesDir, { limit: 1 }).names.length > 0;
 }
+/**
+ * The global roots DETECTION scans — the org-profile hint and the UNASKED
+ * check — from the one candidate builder in `src/org-profile.cts`, never a
+ * private copy (the single-root duplicate that lived here missed every
+ * Homebrew layout). `explicitPrefixOnly`: an explicit npm prefix is
+ * authoritative, so a hint or a violation never comes from a tree the
+ * operator did not point at. The `_globalRoot` seam still wins.
+ */
+function detectionGlobalRoots(opts) {
+    return (0, org_profile_cjs_1.globalRootCandidatesFor)({ _globalRoot: opts._globalRoot, explicitPrefixOnly: true });
+}
 function orgProfilePackageResolvable(cwd, opts) {
     try {
         const projectNodeModules = node_path_1.default.join(cwd, 'node_modules');
         if (node_fs_1.default.existsSync(projectNodeModules) && containsOrgProfileShapedPackage(projectNodeModules)) {
             return true;
         }
-        const globalRoot = opts._globalRoot !== undefined ? opts._globalRoot : resolveGlobalNodeModulesRoot();
-        if (globalRoot && containsOrgProfileShapedPackage(globalRoot)) {
-            return true;
+        for (const globalRoot of detectionGlobalRoots(opts)) {
+            if (containsOrgProfileShapedPackage(globalRoot)) {
+                return true;
+            }
         }
         return false;
     }
@@ -405,8 +406,7 @@ function resolveDetectedOrgProfile(cwd, opts) {
             for (const name of projectResult.names)
                 names.add(name);
         }
-        const globalRoot = opts._globalRoot !== undefined ? opts._globalRoot : resolveGlobalNodeModulesRoot();
-        if (globalRoot) {
+        for (const globalRoot of detectionGlobalRoots(opts)) {
             const globalResult = collectOrgProfileShapedPackages(globalRoot);
             if (globalResult.capped)
                 anyCapped = true;
@@ -421,6 +421,14 @@ function resolveDetectedOrgProfile(cwd, opts) {
         return null;
     }
 }
+/** The one owner of the org-profile decline rule: a blank answer, or `none`
+ * in any letter case with surrounding whitespace, skips the question. Enter
+ * in the TTY driver and `--session-answer org_profile=none` / `org_profile=`
+ * all end here. */
+function isOrgProfileDecline(value) {
+    const trimmed = value.trim();
+    return trimmed === '' || trimmed.toLowerCase() === 'none';
+}
 /** Read `.planning/config.json` at `cwd`, distinguishing "file absent" from
  * "file present but empty/malformed" — `INIT_IDENTITY_MISSING` only fires
  * on the latter (see `verifyInitInvariants`'s own doc comment for why an
@@ -504,12 +512,17 @@ function verifyInitInvariants(cwd, opts = {}) {
     // installed (project node_modules or the machine's global root) but
     // org.profile was never set, i.e. Question 6 appears to have been
     // skipped rather than answered blank.
+    // A recorded skip (init.org_profile_declined, the JSON boolean true and
+    // nothing else) is an answer. A set pointer is checked first; the marker is
+    // checked before the node_modules scan.
     try {
         const orgProfilePointer = getDotted(parsed, org_profile_cjs_1.ORG_PROFILE_CONFIG_KEY);
-        if (!isUsableString(orgProfilePointer) && orgProfilePackageResolvable(cwd, opts)) {
+        const orgProfileDeclined = getDotted(parsed, exports.INIT_ORG_PROFILE_DECLINED_KEY) === true;
+        if (!isUsableString(orgProfilePointer) && !orgProfileDeclined && orgProfilePackageResolvable(cwd, opts)) {
             violations.push({
                 code: INVARIANT_CODE.ORG_PROFILE_UNASKED,
-                message: 'An org-profile-shaped package is installed but org.profile is unset — the pointer question (Question 6) appears to have been skipped rather than answered.',
+                message: 'An org-profile-shaped package is installed but org.profile is unset and no skip was recorded — the pointer question (Question 6) appears not to have been answered. ' +
+                    'Re-run "pp-tools init --reset" and either type the package name to use it, or press Enter (or type "none") to record a skip.',
             });
         }
     }
@@ -890,10 +903,13 @@ function initSessionNext(cwd, opts = {}) {
  * any answer once the session is already `done`.
  *
  * The `org_profile` answer is written to `.planning/config.json` (`org.profile`)
- * IMMEDIATELY when non-blank — the one exception to the "batch write after
- * the last answer" rule in `computeCurrentStep`'s own doc comment — because
- * the very next question (`provider`) must see it to re-resolve its
- * `preselected` (the walk-3 regression Task 1's acceptance names).
+ * IMMEDIATELY when it selects a package — the one exception to the "batch
+ * write after the last answer" rule in `computeCurrentStep`'s own doc
+ * comment — because the very next question (`provider`) must see it to
+ * re-resolve its `preselected` (the walk-3 regression Task 1's acceptance
+ * names). A decline (`isOrgProfileDecline`: blank, or `none` in any case) is
+ * recorded instead as `init.org_profile_declined: true` when a profile was
+ * detectable.
  */
 function initSessionAnswer(cwd, stepId, value, opts = {}) {
     const loaded = loadSession(cwd);
@@ -937,13 +953,34 @@ function initSessionAnswer(cwd, stepId, value, opts = {}) {
             if (!step.question.optionalAnswer && (typeof value !== 'string' || value.trim() === '')) {
                 return { ok: false, reason: 'answer_required', message: `Question "${stepId}" requires a non-blank answer.` };
             }
-            session.answers[stepId] = typeof value === 'string' ? value : '';
+            const answerValue = typeof value === 'string' ? value : '';
             if (stepId === 'org_profile') {
-                const trimmed = session.answers[stepId].trim();
-                if (trimmed !== '') {
-                    writeConfigMerge(cwd, { org: { profile: trimmed } });
+                if (isOrgProfileDecline(answerValue)) {
+                    // Enter and `none` leave the same session record. The marker is
+                    // written exactly when the UNASKED violation would otherwise fire
+                    // (the same predicate); with no profile detectable nothing was
+                    // offered, so nothing is recorded.
+                    session.answers[stepId] = '';
+                    if (orgProfilePackageResolvable(cwd, { _globalRoot: opts._globalRoot })) {
+                        writeConfigMerge(cwd, { init: { org_profile_declined: true } });
+                    }
+                    persistSession(cwd, session);
+                    return { ok: true };
+                }
+                const trimmed = answerValue.trim();
+                session.answers[stepId] = answerValue;
+                const orgPatch = { org: { profile: trimmed } };
+                // A selection after an earlier recorded skip writes the marker back to
+                // false in the same merge, so a stale decline never sits beside a set
+                // pointer. No write when the marker is absent.
+                if (getDotted(readConfigFile(cwd).parsed, exports.INIT_ORG_PROFILE_DECLINED_KEY) === true) {
+                    orgPatch.init = { org_profile_declined: false };
                 }
+                writeConfigMerge(cwd, orgPatch);
+                persistSession(cwd, session);
+                return { ok: true };
             }
+            session.answers[stepId] = answerValue;
             persistSession(cwd, session);
             return { ok: true };
         }
@@ -1028,7 +1065,16 @@ function initSessionReset(cwd) {
  * `init-contract --arm-vault`: turn the client vault on for a project whose
  * client vault is bound. Writes `vault.enabled: true` ONLY when the key is
  * absent — an explicit `false` (or any other explicit value) is the
- * operator's decision and is kept. With no client vault bound (no or
+ * operator's decision and is kept. When the vault ends up enabled it also
+ * writes `vault.required: true` where that key is absent: a project with a
+ * bound client vault should stop when that vault stops loading, instead of
+ * building without it after a confirmation. An explicit `vault.required`
+ * (including `false`) is kept, and so is an org profile's value: when the
+ * profile sets `vault.required` nothing is written, because the gate already
+ * reads it (project > profile > default). It also writes
+ * `vault.practices_enabled: true` where that key is absent, so the project
+ * records which client practices each phase applied from its first phase on;
+ * an explicit value is kept. All keys go in one write. With no client vault bound (no or
  * malformed `.platform-bindings.json`, or `client.vaultRepo` /
  * `client.vaultRef` missing — the same "bound" the gate's verdict uses) it
  * writes nothing and returns `ok: false` naming /pp-init. A present but
@@ -1063,6 +1109,8 @@ function armVault(cwd) {
             ok: false,
             armed: false,
             enabled: undefined,
+            required: undefined,
+            practicesEnabled: undefined,
             client,
             message: '.planning/config.json is not valid JSON — fix it (or re-run /pp-init), then arm the vault again. Nothing was written.',
         };
@@ -1071,33 +1119,99 @@ function armVault(cwd) {
     const nested = vaultSection && Object.prototype.hasOwnProperty.call(vaultSection, 'enabled');
     const flat = Object.prototype.hasOwnProperty.call(cfg, 'vault.enabled');
     const current = nested && vaultSection ? vaultSection.enabled : flat ? cfg['vault.enabled'] : undefined;
+    const requiredNested = vaultSection && Object.prototype.hasOwnProperty.call(vaultSection, 'required');
+    const requiredFlat = Object.prototype.hasOwnProperty.call(cfg, 'vault.required');
+    const currentRequired = requiredNested && vaultSection ? vaultSection.required : requiredFlat ? cfg['vault.required'] : undefined;
+    const practicesNested = vaultSection && Object.prototype.hasOwnProperty.call(vaultSection, 'practices_enabled');
+    const practicesFlat = Object.prototype.hasOwnProperty.call(cfg, 'vault.practices_enabled');
+    const currentPractices = practicesNested && vaultSection
+        ? vaultSection.practices_enabled
+        : practicesFlat
+            ? cfg['vault.practices_enabled']
+            : undefined;
+    const practicesAbsent = !(practicesNested || practicesFlat);
     if (!binding.bound) {
         return {
             ok: false,
             armed: false,
             enabled: current,
+            required: currentRequired,
+            practicesEnabled: currentPractices,
             client,
             message: 'No client vault is bound — .platform-bindings.json needs client.vaultRepo and client.vaultRef. Run /pp-init to bind it; vault.enabled was not changed.',
         };
     }
-    if (nested || flat) {
+    const enabledAbsent = !(nested || flat);
+    const enabledAfter = enabledAbsent ? true : current;
+    const requiredAbsent = !(requiredNested || requiredFlat);
+    // An org profile that sets vault.required already decides it for this project (the gate
+    // reads project > profile > default); arming must not override it with a project value.
+    let profileRequired = null;
+    if (requiredAbsent) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const orgProfile = require('./org-profile.cjs');
+            const r = orgProfile.resolveVaultRequired(cwd);
+            if (r.source === 'profile')
+                profileRequired = r.required;
+        }
+        catch {
+            /* no profile: arm as before */
+        }
+    }
+    const patch = {};
+    if (enabledAbsent)
+        patch.enabled = true;
+    if (enabledAfter === true && requiredAbsent && profileRequired === null)
+        patch.required = true;
+    // A bound client vault also records which of its practices each phase applied,
+    // from the first phase on. An explicit value is the operator's choice and is kept.
+    if (enabledAfter === true && practicesAbsent)
+        patch.practices_enabled = true;
+    const clauses = [
+        enabledAbsent
+            ? 'vault.enabled set to true (it was absent)'
+            : current === true
+                ? 'vault.enabled is already true'
+                : `vault.enabled is explicitly set to ${JSON.stringify(current)} — kept as the operator's choice`,
+    ];
+    if (enabledAfter === true) {
+        clauses.push(!requiredAbsent
+            ? `vault.required is set to ${JSON.stringify(currentRequired)} — kept as the operator's choice`
+            : profileRequired !== null
+                ? `vault.required comes from the org profile (${profileRequired}) — not written to the project`
+                : 'vault.required set to true (it was absent): planning and the build now stop when the client vault does not load');
+        clauses.push(practicesAbsent
+            ? "vault.practices_enabled set to true (it was absent): each plan now carries the client vault's practices and a record of which applied"
+            : `vault.practices_enabled is set to ${JSON.stringify(currentPractices)} — kept as the operator's choice`);
+    }
+    const requiredAfter = Object.prototype.hasOwnProperty.call(patch, 'required')
+        ? true
+        : profileRequired !== null
+            ? profileRequired
+            : currentRequired;
+    const practicesAfter = Object.prototype.hasOwnProperty.call(patch, 'practices_enabled')
+        ? true
+        : currentPractices;
+    if (Object.keys(patch).length === 0) {
         return {
-            ok: true,
-            armed: false,
-            enabled: current,
-            client,
-            message: current === true
-                ? 'vault.enabled is already true — nothing to do.'
-                : `vault.enabled is explicitly set to ${JSON.stringify(current)} — kept as the operator's choice.`,
+            ok: true, armed: false, enabled: current, required: requiredAfter, practicesEnabled: practicesAfter, client,
+            message: `${clauses.join('; ')} — nothing to do.`,
         };
     }
     try {
-        writeConfigMerge(cwd, { vault: { enabled: true } });
+        writeConfigMerge(cwd, { vault: patch });
     }
     catch (err) {
-        return { ok: false, armed: false, enabled: undefined, client, message: writeFailedMessage(err) };
+        return {
+            ok: false, armed: false, enabled: current, required: currentRequired, practicesEnabled: currentPractices, client,
+            message: writeFailedMessage(err),
+        };
     }
-    return { ok: true, armed: true, enabled: true, client, message: 'vault.enabled set to true (it was absent).' };
+    return {
+        ok: true, armed: true, enabled: enabledAfter, required: requiredAfter, practicesEnabled: practicesAfter, client,
+        message: `${clauses.join('; ')}.`,
+    };
 }
 // ─── cmdInitContract ────────────────────────────────────────────────────────
 /**

package/pp-core/bin/lib/init-interactive.cjs

@@ -168,26 +168,10 @@ async function runInitInteractive(cwd, prompter, opts = {}) {
                 preselectedLabel: state.preselectedLabel,
                 optionalAnswer: state.optionalAnswer,
             });
-            // INIT-PATCH-C: Enter accepts a carried default, "none" clears it.
-            // Scoped to an OPTIONAL step carrying a usable `preselected` — today
-            // that is only `org_profile` when exactly one org-profile-shaped
-            // package was detected. `provider` also carries a `preselected` but is
-            // NOT `optionalAnswer`, so the `state.optionalAnswer === true` guard
-            // below leaves it untouched: a blank answer there still falls through
-            // to `initSessionAnswer` verbatim, which still rejects it and re-asks
-            // exactly as today.
-            const hasUsableDefault = state.optionalAnswer === true && typeof state.preselected === 'string' && state.preselected.trim() !== '';
-            let submittedAnswer = answer;
-            if (hasUsableDefault) {
-                const trimmedLower = answer.trim().toLowerCase();
-                if (answer.trim() === '') {
-                    submittedAnswer = state.preselected;
-                }
-                else if (trimmedLower === 'none') {
-                    submittedAnswer = '';
-                }
-            }
-            const result = (0, init_contract_cjs_1.initSessionAnswer)(cwd, stepId, submittedAnswer, sessionOpts);
+            // A detected org profile is a hint, never a default: the driver has no
+            // default-acceptance path, and the answer goes to initSessionAnswer
+            // verbatim, which owns the none/blank decline.
+            const result = (0, init_contract_cjs_1.initSessionAnswer)(cwd, stepId, answer, sessionOpts);
             if (result.ok) {
                 if (stepId === 'compose_confirm') {
                     wroteBinding = readBindingsContent(cwd) !== preBindings;

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

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Loop gate runner — the one owner of the generic `check.query` gate contract.
+ *
+ * Command surface: pp-tools loop run-gates <point> [--phase <N>] [--tier light|standard|heavy] [--query <q>] [--raw]
+ *
+ * Resolves the active hooks at <point> through the loop resolver (the same
+ * owner `loop render-hooks` uses, so an unreadable config refuses here too),
+ * then runs every active gate in registry order and applies the two-step gate
+ * contract execute-phase states for `execute:wave:post` / `execute:post`:
+ *
+ *   Step 1 — did the check COMMAND succeed? (`pp-tools check <query> [<phase>]
+ *   [<check.args>…] --raw` exits 0 with a JSON object). If not: `onError: halt` halts,
+ *   `onError: skip` (or absent) warns and moves on; `block` is never read.
+ *   Step 2 — read `block`. A blocking gate (`blocking: true`) halts on
+ *   `block: true`; that halt is never bypassed by `onError`. An advisory gate
+ *   (`blocking` not true) reports `block: true` or a non-empty `message` as an
+ *   advisory and never halts. `block: false` with no message passes silently;
+ *   a blocking gate that passes WITH a message (a note) passes with an `ℹ` line.
+ *
+ * `check.args` (optional) are literal tokens the gate declaration appends after
+ * the phase — the gate's own policy, stated where the gate is declared (e.g.
+ * `--stage plan`). `--query <q>` runs only the gates whose `check.query` is `q`,
+ * so a host can run one gate in code beside a loop that handles the others.
+ *
+ * A gate this runner cannot run (no `check.query`, or a query that is not a
+ * check name) halts when it is blocking and is reported when it is advisory:
+ * a blocking gate is never passed having checked nothing.
+ *
+ * Output: the verdict JSON on stdout (`{ point, phase, halt, gates[], lines[] }`),
+ * every line of `lines` also on stderr so a host capturing `$(…)` still shows
+ * them, and exit 1 when `halt` is true. A host therefore writes
+ * `X=$(pp_run loop run-gates <point> …) || exit 1` and the halt stops it.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { output: coreOutput, error: coreError, ERROR_REASON } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const loopResolverModule = require("./loop-resolver.cjs");
+const { resolveProjectLoopHooks } = loopResolverModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderModule = require("./config-loader.cjs");
+const { unreadableConfigFiles } = configLoaderModule;
+const phase_tier_cjs_1 = require("./phase-tier.cjs");
+/** A check name as `routeCheckCommand` accepts it (dotted or hyphenated); never an option or a path. */
+const CHECK_QUERY_RE = /^[a-z0-9][a-z0-9.-]*$/i;
+/** A declared `check.args` token: a flag or a plain word — never a path, a quote or a shell metacharacter. */
+const CHECK_ARG_RE = /^(?:--[a-z][a-z0-9-]*|[a-z0-9][a-z0-9._-]*)$/i;
+const CHECK_ARGS_MAX = 8;
+const CHECK_TIMEOUT_MS = 300_000;
+/** A check's operator message is relayed whole (line breaks kept), up to this many characters. */
+const MESSAGE_CAP = 16_000;
+function boundMessage(v) {
+    if (typeof v !== 'string')
+        return null;
+    const flat = v.replace(/\r\n?/g, '\n').replace(/[\u0000-\u0008\u000B-\u001F\u007F]+/g, ' ').trim();
+    if (flat === '')
+        return null;
+    return flat.length > MESSAGE_CAP ? `${flat.slice(0, MESSAGE_CAP)}…` : flat;
+}
+/** The declared `check.args`, or null when the declaration carries an argument this runner will not pass. */
+function declaredCheckArgs(check) {
+    const args = check ? check['args'] : undefined;
+    if (args === undefined)
+        return [];
+    if (!Array.isArray(args) || args.length > CHECK_ARGS_MAX)
+        return null;
+    return args.every((a) => typeof a === 'string' && CHECK_ARG_RE.test(a)) ? args : null;
+}
+/** Run `pp-tools check <query> [<phase>] [<args>…] --raw` in a child process (check handlers exit the process). */
+const defaultCheckRunner = (query, phase, cwd, checkArgs) => {
+    const tools = node_path_1.default.join(__dirname, '..', 'pp-tools.cjs');
+    const args = [tools, 'check', query, ...(phase ? [phase] : []), ...checkArgs, '--raw'];
+    const r = (0, shell_command_projection_cjs_1.execTool)(process.execPath, args, { cwd, timeout: CHECK_TIMEOUT_MS });
+    if (r.exitCode !== 0 || r.signal) {
+        const why = r.signal ? `killed by ${r.signal}` : `exit ${r.exitCode}`;
+        return { ok: false, result: null, error: `${why}${r.stderr ? `: ${r.stderr.split('\n')[0]}` : ''}` };
+    }
+    if (r.stdout === '')
+        return { ok: false, result: null, error: 'empty output' };
+    try {
+        const parsed = JSON.parse(r.stdout);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return { ok: false, result: null, error: 'output is not a JSON object' };
+        return { ok: true, result: parsed, error: null };
+    }
+    catch {
+        return { ok: false, result: null, error: 'output is not JSON' };
+    }
+};
+/**
+ * Run every active gate at `point` (already resolved) under the two-step
+ * contract. Pure apart from `runCheck`.
+ */
+function runGates(point, phase, activeHooks, cwd, runCheck = defaultCheckRunner) {
+    const gates = [];
+    const lines = [];
+    let halt = false;
+    for (const h of activeHooks) {
+        if (h.kind !== 'gate')
+            continue;
+        const blocking = h.blocking === true;
+        const onError = typeof h.onError === 'string' ? h.onError : 'skip';
+        const check = h.check && typeof h.check === 'object' ? h.check : null;
+        const query = check && typeof check['query'] === 'string' ? check['query'] : null;
+        const checkArgs = declaredCheckArgs(check);
+        const run = { capId: h.capId, query, blocking, onError, outcome: 'pass', block: null, message: null };
+        if (query === null || !CHECK_QUERY_RE.test(query) || checkArgs === null) {
+            run.outcome = 'unrunnable';
+            run.message = query === null
+                ? 'the gate declares no check.query'
+                : checkArgs === null ? 'check.args is not a list of plain flags and words' : 'check.query is not a check name';
+            if (blocking) {
+                halt = true;
+                lines.push(`⛔ ${point} blocked: capability gate (${h.capId}) cannot be run (${run.message}). Fix the capability declaration before continuing.`);
+            }
+            else {
+                lines.push(`⚠ ${h.capId} advisory (${point}): gate not run — ${run.message}.`);
+            }
+            gates.push(run);
+            continue;
+        }
+        // Step 1 — did the check command itself succeed?
+        const r = runCheck(query, phase, cwd, checkArgs);
+        if (!r.ok || r.result === null) {
+            run.message = boundMessage(r.error) ?? 'command error';
+            if (onError === 'halt') {
+                run.outcome = 'error-halt';
+                halt = true;
+                lines.push(`⛔ ${point} blocked: gate check command failed (${h.capId}: check ${query}): ${run.message}. Resolve before continuing.`);
+            }
+            else {
+                run.outcome = 'error-skip';
+                lines.push(`⚠ ${point} gate check command failed (${h.capId}: check ${query}): ${run.message} — skipped (onError: ${onError}).`);
+            }
+            gates.push(run);
+            continue;
+        }
+        // Step 2 — read block (only reached when the command succeeded).
+        const block = r.result['block'] === true;
+        run.block = block;
+        run.message = boundMessage(r.result['message']) ?? boundMessage(r.result['reason']);
+        if (blocking && block) {
+            run.outcome = 'blocked';
+            halt = true;
+            lines.push(`⛔ ${point} blocked by capability gate (${h.capId}): ${run.message ?? `check ${query} reported block`}. Resolve before continuing.`);
+        }
+        else if (!blocking && (block || boundMessage(r.result['message']) !== null)) {
+            run.outcome = 'advisory';
+            lines.push(`⚠ ${h.capId} advisory (${point}): ${run.message ?? `check ${query} reported block`}`);
+        }
+        else {
+            run.outcome = 'pass';
+            const note = blocking ? boundMessage(r.result['message']) : null;
+            if (note !== null)
+                lines.push(`ℹ ${h.capId} (${point}): ${note}`);
+        }
+        gates.push(run);
+    }
+    return { point, phase, halt, gates, lines };
+}
+/**
+ * `loop run-gates <point> [--phase <N>] [--tier <t>]`. Exit 1 on a halt or a
+ * refusal; the verdict JSON is on stdout either way except on a refusal.
+ */
+function cmdLoopRunGates(cwd, point, raw, options = {}) {
+    if (!point) {
+        coreError('loop run-gates requires a <point> argument (e.g. verify:post)', ERROR_REASON.USAGE);
+        return;
+    }
+    const phase = typeof options['phase'] === 'string' && options['phase'] !== '' ? options['phase'] : null;
+    const tierCli = typeof options['tier'] === 'string' && options['tier'] !== '' ? options['tier'] : null;
+    if (tierCli !== null && !['light', 'standard', 'heavy'].includes(tierCli)) {
+        coreError('--tier needs one of light, standard, heavy', ERROR_REASON.USAGE);
+        return;
+    }
+    const phaseTier = (phase !== null || tierCli !== null) && unreadableConfigFiles(cwd).length === 0
+        ? (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, phase, tierCli)
+        : null;
+    const outcome = resolveProjectLoopHooks(cwd, point, { phaseTier, what: `loop run-gates ${point}` });
+    if (!outcome.ok) {
+        coreError(outcome.message, outcome.reason === 'config_unreadable' ? ERROR_REASON.CONFIG_PARSE_FAILED : undefined);
+        return;
+    }
+    const onlyQuery = typeof options['query'] === 'string' && options['query'] !== '' ? options['query'] : null;
+    const hooks = onlyQuery === null
+        ? outcome.resolved.activeHooks
+        : outcome.resolved.activeHooks.filter((h) => {
+            const c = h.check && typeof h.check === 'object' ? h.check : null;
+            return c !== null && c['query'] === onlyQuery;
+        });
+    const verdict = runGates(point, phase, hooks, cwd);
+    if (verdict.lines.length > 0) {
+        try {
+            process.stderr.write(verdict.lines.join('\n') + '\n');
+        }
+        catch {
+            /* stderr closed */
+        }
+    }
+    coreOutput(verdict, raw);
+    if (verdict.halt)
+        process.exitCode = 1;
+}
+module.exports = {
+    runGates,
+    cmdLoopRunGates,
+};