@deftai/directive-content 0.82.0 → 0.84.0

package/skills/deft-directive-build/SKILL.md

@@ -209,14 +209,27 @@ All xBRIEFs (including those read from `xbrief/active/` and any new xBRIEFs this
 - ! If any required tool is missing, stop and report — do not proceed to Step 3
 - ⊗ Assume tools are available because the spec references them
 
-### Step 3: Build Phase by Phase
+### Gate throughput — iteration fast lane vs merge chokepoint (#1704)
+
+> **Invariant:** every change MUST pass the full gate at least once before merge. Iteration MAY use a cheaper proxy; the merge chokepoint MUST NOT be skipped.
+
+- ! **Iteration lane (agents + humans):** during implementation commits, use affected/static gates — targeted tests on changed paths (`vitest run --coverage <paths>` or project equivalent), static `verify:*` gates relevant to touched files, and `task coverage:hotspots` / `task verify:forward-coverage` — NOT full `task check` on every commit.
+- ! **Merge chokepoint:** run full `task check` (or `task check:merge` in the framework source repo) once before push/PR and again when CI merge gate runs. Pre-PR skill exit and review-cycle fix batches still require a green full gate.
+- ! **Escape-rate safety (#1703 Tier-1):** before tightening fast-lane defaults fleet-wide, consult `#1703` measurement — `task eval:health` (Tier 0) and Tier-1 session telemetry (`helped/crud-metrics.jsonl` via instrumented CRUD / workflow metrics). Do NOT invent a separate fast-lane escape-rate surface (#1704 LockedDecisions).
+- ~ **In-engine incrementality (#1713):** content-hash task cache and runner-delegated affected selection are sibling work — not required for this policy face.
+- ⊗ Run full `task check` on every iteration commit when a cheaper proxy suffices — reserve the full gate for PR/merge (#1704).
+- ⊗ Skip the merge chokepoint because the iteration lane passed — the fast lane is convenience only.
+
+**Cost model (swarm-heavy path):** moves from roughly `O(commits × full-gate)` toward `O(merges × full-gate) + O(iterations × cheap-proxy)` when workers iterate with affected/static gates and run full `task check` only at PR/merge.
+
+## Step 3: Build Phase by Phase
 
 For each phase:
 
 1. ! **Scaffold** — file structure, dependencies, config
 2. ! **Test first** — write tests before implementation (TDD)
 3. ! **Implement** — make tests pass, following deft coding standards
-4. ! **Verify** — run `task check`, fix any issues
+4. ! **Verify (iteration lane)** — run affected/static gates per `#1704` fast lane above; fix failures before checkpoint commits
 5. ! **Origin sync** — when this phase materially changed an origin-linked scope xBRIEF (`plan.references` includes `x-xbrief/github-issue`), run `task issue:sync-from-xbrief -- <path>` (or `--dry-run` to preview) so the linked GitHub issue receives a sync comment; if skipped, document why in the PR or session notes (#2540)
 6. ! **Checkpoint** — tell user what's done, what's next
 
@@ -224,15 +237,24 @@ For each phase:
 
 ### Step 4: Quality Gates
 
-After EVERY phase:
+After EVERY phase (iteration lane — #1704):
+
+```bash
+vitest run --coverage <changed-paths>   # or project test runner on touched modules
+task coverage:hotspots                  # branch headroom before merge
+task verify:forward-coverage            # new-source coverage (#1310)
+```
+
+Before PR / phase handoff (merge chokepoint):
 
 ```bash
-task check          # Format, lint, type check, test, coverage
+task check          # Full gate — format, lint, typecheck, tests, coverage, verify:*
 task test:coverage  # >=85% or PROJECT-DEFINITION.xbrief.json override
 ```
 
-- ! Phase is NOT done until `task check` passes
+- ! Phase checkpoint commits MAY use the iteration lane; phase is NOT done for PR handoff until full `task check` passes at the merge chokepoint
 - ⊗ Skip quality gates or claim they passed without running
+- ⊗ Treat iteration-lane green as merge-ready without full `task check`
 
 ## Coding Standards (Summary)
 
@@ -244,7 +266,7 @@ Read full files when you need detail:
 - ~ Naming: hyphens for filenames unless language idiom dictates otherwise
 - ! Contracts first: define interfaces/types before implementation
 - ! Secrets: in `secrets/` dir with `.example` templates; ⊗ secrets in code
-- ! Commits: Conventional Commits format; ! run `task check` before every commit
+- ! Commits: Conventional Commits format; ! use iteration fast lane before checkpoint commits; ! run full `task check` at PR/merge chokepoint only (#1704)
 
 See `deft/coding/coding.md` and `deft/coding/testing.md` for full rules.
 
@@ -266,7 +288,7 @@ See `deft/coding/coding.md` and `deft/coding/testing.md` for full rules.
 
 - ! Default to one story per branch/PR. Batching multiple stories in one branch requires explicit operator approval and a short rationale.
 - ! Create a checkpoint commit after each completed story before beginning another story.
-- ! Run `task check` before committing
+- ! Use iteration fast lane before checkpoint commits; run full `task check` at PR/merge chokepoint (#1704)
 - ⊗ Claim checks passed without running them
 
 ```
@@ -296,7 +318,7 @@ feat(phase-2): add REST API endpoints with integration tests
 - ⊗ Implement things not in scope xBRIEF without asking
 - ⊗ Read every deft file upfront
 - ⊗ Move to next phase before current passes checks
-- ⊗ Make commits without running `task check`
+- ⊗ Make commits without running iteration-lane validation; ⊗ skip full `task check` at PR/merge chokepoint (#1704)
 - ⊗ Proceed without USER.md -- always run the USER.md Gate first
 - ⊗ Spawn an implementation agent or invoke a code-writing tool against a xBRIEF that has not passed `task xbrief:preflight` (which wraps `scripts/preflight_implementation.py`) -- always run the Step 0 Implementation Preflight (#810) first; satisfy via `task xbrief:activate <path>`
 - ⊗ Proceed without `COST-ESTIMATE.md` and a recorded build / rescope / no-build / skip(+reason) decision -- always run the Cost Phase Gate (#739) first

package/skills/deft-directive-pre-pr/SKILL.md

@@ -60,10 +60,20 @@ task verify:plan-sequence -- --target-kind <entry-kind> --target <entry-id>
 - ! After the PR's review cycle completes successfully, run `task plan-sequence:advance` so "next" resolves to the following entry (or exhausted).
 - ⊗ Treat skill-chaining or "what's next?" as permission to open a PR outside the current sequence entry.
 
+## Gate throughput — iteration fast lane vs merge chokepoint (#1704)
+
+> **Invariant:** every change MUST pass the full gate at least once before merge. Pre-PR is the merge chokepoint — NOT every iteration commit.
+
+- ! **Iteration lane (Phases 2–3 loop):** use affected/static gates on changed paths — `vitest run --coverage <paths>`, relevant `verify:*` on touched files, `task coverage:hotspots` — instead of full `task check` on every RWLDL iteration.
+- ! **Merge chokepoint (Phase 3 Lint exit + final confirm):** run full `task check` once before push/PR; Phase 3c targeted coverage precedes but does not replace the full gate.
+- ! **Escape-rate safety (#1703 Tier-1):** before recommending fleet-wide fast-lane tightening, cite `#1703` Tier-1 telemetry (`helped/crud-metrics.jsonl`) and `task eval:health` — do NOT invent a separate escape-rate surface.
+- ~ **In-engine incrementality (#1713):** content-hash cache + runner-delegated affected selection are sibling work (#1713).
+- ⊗ Treat Phase 3c targeted coverage alone as PR-ready without full `task check` at the merge chokepoint.
+
 ## When to Use
 
 - ! Before pushing a branch for PR creation
-- ! After completing implementation but before the final `task check` gate
+- ! After completing implementation but before the final merge-chokepoint `task check` (#1704)
 - ~ After addressing bot reviewer findings (run one RWLDL pass before pushing the fix batch)
 - ? During mid-implementation checkpoints on large changes
 
@@ -95,9 +105,9 @@ Each iteration proceeds through all phases in order. Do NOT skip phases or reord
 
 ### Phase 3 -- Lint
 
-! Run `task check` and fix any failures.
+! Run the merge-chokepoint gate and fix any failures (#1704).
 
-- ! Run `task check` (fmt + lint + typecheck + tests + coverage)
+- ! Run full `task check` (fmt + lint + typecheck + tests + coverage + verify:*) — the merge chokepoint, not every RWLDL iteration
 - ! Fix all failures before proceeding to Phase 3b
 - ~ If a lint fix requires changing a file, that counts as a change for the Loop phase
 

package/skills/deft-directive-product-signal/SKILL.md

@@ -27,6 +27,8 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 - ! `plan.policy.productSignal.enabled` MUST be true (`task policy:show --field=productSignal`)
 - ! Install-level consent MUST be recorded before outbound submit (`task product-signal:status`)
+- ! Consent schema v2 binds to the configured sinkRepo; legacy v1 consent authorizes only `deftai/product-signal` (#2767)
+- ! Re-consent after changing `plan.policy.productSignal.sinkRepo`; mismatch soft-skips as sink-unconsented
 - ⊗ Prompt or submit when `enabled` is false
 - ⊗ Block story work on sink errors — fail open (#2693 D16/D18)
 
@@ -50,7 +52,7 @@ When enabled, interactive, and consent missing/revoked, ask:
 >
 > Reply **yes** to consent, or **no** to decline.
 
-- **yes** → `task product-signal:consent -- --grant`; continue
+- **yes** → `task product-signal:consent -- --grant` (pass `--project-root` when using a custom sinkRepo); continue
 - **no** → soft-skip; do not badger every turn
 
 ## Phase 3 — Interview (≤3 answers + optional NPS)

package/skills/deft-directive-swarm/SKILL.md

@@ -325,6 +325,18 @@ git worktree add <path> -b <branch-name> <configured-base-branch>
 
 ~ Also prepare plain-text prompt versions for pasting into Warp agent chat or other terminal interfaces.
 
+## Gate throughput — iteration fast lane vs merge chokepoint (#1704)
+
+> **Invariant:** every change MUST pass the full gate at least once before merge. Swarm workers and human operators share the same commands.
+
+- ! **Iteration lane:** during implement/fix loops, run affected/static gates (targeted tests on changed paths, relevant static `verify:*` gates, `task coverage:hotspots`) — NOT full `task check` on every commit.
+- ! **Merge chokepoint:** run full `task check` once before push/PR open; CI enforces the same monolith at merge (#1704). Monitor checkpoints treat "Validating" as iteration-lane OR full gate; push requires full gate green at least once on the branch.
+- ! **Escape-rate safety (#1703 Tier-1):** consult `task eval:health` and Tier-1 session telemetry (`helped/crud-metrics.jsonl`) before fleet-wide fast-lane tightening — do NOT invent a separate escape-rate surface.
+- ~ **In-engine incrementality (#1713):** content-hash cache + runner-delegated affected plumbing is sibling work; this skill owns process policy only.
+- ⊗ Require full `task check` on every swarm iteration commit when affected/static proxies suffice (#1704).
+
+**Swarm cost model:** cohort workers move from `O(commits × full-gate)` toward `O(merges × full-gate) + O(iterations × cheap-proxy)` when they iterate with the fast lane and reserve full `task check` for PR/merge.
+
 ## Phase 3 — Launch
 
 ### Step 0: Populate the allocation-context consent token (#1378)
@@ -552,7 +564,7 @@ Track each agent through these stages:
 
 1. **Reading** — agent is loading AGENTS.md, xBRIEF files, project files (no file changes yet)
 2. **Implementing** — working tree shows modified files
-3. **Validating** — agent running `task check`
+3. **Validating** — agent running iteration-lane gates or full `task check` (full gate required before push/PR — #1704)
 4. **Committed** — new commit(s) in `git log`
 5. **Pushed** — branch exists on `origin`
 6. **PR Created** — PR visible via `gh pr list --head <branch>`
@@ -613,7 +625,7 @@ For each agent's PR:
 All PRs meet ALL of:
 - Greptile confidence > 3
 - No P0 or P1 issues remain (P2 issues are non-blocking style suggestions)
-- `task check` passed (or equivalent validation completed)
+- `task check` passed at merge chokepoint before push (or equivalent full-gate validation — #1704)
 - CHANGELOG entries present under `[Unreleased]`
 
 ! **Mandatory cohort verifier (#1364):** After every poller (Phase 6 review-cycle sub-agent) reports back, the monitor MUST run `task swarm:verify-review-clean -- <pr-numbers...>` and confirm exit 0 BEFORE evaluating the rest of the Exit Condition or surfacing the Phase 5 -> 6 gate. The verifier re-uses the Greptile rolling-summary parser from `task pr:merge-ready` so the per-PR merge gate and the cohort gate stay in lockstep (a parser fix lands in both surfaces at once). Exit codes: 0 (cohort CLEAN -- all PRs simultaneously have SHA match + confidence > 3 + zero P0/P1 + not errored on current HEAD); 1 (one or more PRs unclean with per-PR diagnostics -- re-dispatch the poller for the unclean PR or address findings, then re-run the verifier); 2 (config error -- empty cohort, malformed xBRIEF glob, gh missing). The verifier is the structural answer to the #1166 swarm execution recurrence where multiple pollers exited with `clean_gate_holdout=confidence` (confidence == 3) and the monitor still raised the Phase 5 -> 6 gate because the trigger keyed on "all pollers have reported back" rather than "every PR in the cohort is objectively CLEAN".
@@ -641,7 +653,7 @@ All PRs meet ALL of:
 2. ! **Merge-readiness checklist:** Before any `gh pr merge` call, the monitor MUST emit a structured checklist confirming each PR is merge-ready. For each PR, verify and explicitly confirm:
    - Greptile confidence score > 3
    - No P0 or P1 issues remaining
-   - `task check` passed on the branch
+   - full `task check` passed on the branch before push (#1704 merge chokepoint)
    - CHANGELOG.md entry present under `[Unreleased]`
    - Explicit user approval received for this merge cascade
 
@@ -918,7 +930,8 @@ When a monitor session crashes or a new session must take over an in-progress sw
 ```
 TASK: You must complete N [type] fixes on this branch ([branch-name]) in the deft directive repo.
 This is a git worktree. Do NOT just read files and stop — you must implement all changes,
-run task check, commit, push, create a PR, and run the review cycle.
+run iteration-lane validation during implement/fix loops, full task check before push,
+commit, push, create a PR, and run the review cycle.
 DO NOT STOP until all steps are complete.
 
 STEP 1 — Read directives: Read AGENTS.md, vbrief/vbrief.md, and the assigned xBRIEF(s) from xbrief/active/.
@@ -932,7 +945,7 @@ Task B (xBRIEF: [filename], issue #[N]): [one-paragraph description with specifi
 
 [...repeat for each task...]
 
-STEP 3 — Validate: Run task check. Fix any failures.
+STEP 3 — Validate: Use iteration fast lane during commits (affected/static gates). Run full task check once before push/PR (#1704). Fix any failures.
 
 STEP 4 — Commit: Add CHANGELOG.md entries under [Unreleased].
 Commit with message: [type]([scope]): [description] — with bullet-point body.
@@ -948,7 +961,7 @@ CONSTRAINTS:
 - Do not touch [list files other agents are working on]
 - New source files (scripts/, src/, cmd/, *.py, *.go) must have corresponding test files in the same PR
 - Use conventional commits: type(scope): description
-- Run task check before every commit
+- Iteration commits: affected/static fast lane only; full task check required before push (#1704)
 - Never force-push
 ```
 
@@ -963,7 +976,7 @@ CONSTRAINTS:
 
 ## Push Autonomy
 
-! Swarm agents operating under this skill with a monitor agent may push, create PRs, and run review cycles autonomously after passing `task check`. The global "never push/commit without explicit user instruction" convention does not apply to swarm agents executing the full STEP 1-6 prompt workflow -- the skill's quality gates (`task check`, Greptile review cycle) replace the interactive confirmation gate.
+! Swarm agents operating under this skill with a monitor agent may push, create PRs, and run review cycles autonomously after passing full `task check` at the merge chokepoint (#1704). The global "never push/commit without explicit user instruction" convention does not apply to swarm agents executing the full STEP 1-6 prompt workflow -- the skill's quality gates (merge chokepoint `task check`, Greptile review cycle) replace the interactive confirmation gate.
 
 ## Anti-Patterns
 

package/tasks/engine-pm-run.cjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Run package.json scripts via pnpm / Corepack without shell-interpolating
+ * repository-controlled packageManager pins (#2765 / #2761).
+ *
+ * Consumed by tasks/engine.yml `:engine:pm-run` and `:engine:_ts-build`.
+ * Lives under tasks/ so @deftai/directive-content prepack ships it beside
+ * tasks/engine.yml (#2022 Phase 3).
+ */
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const WIN32_ALLOWLIST = new Set(["pnpm", "corepack", "npm"]);
+const SHELL_METACHAR_RE = /[;&|`$<>()\\'"!#\n\r\t]/;
+const SEMVER_RE =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+const SCRIPT_NAME_RE = /^[A-Za-z0-9:_-]+$/;
+
+/** @param {string | null | undefined} version */
+function isValidSemVer(version) {
+  return typeof version === "string" && SEMVER_RE.test(version);
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {{ ok: true, semver: string | null, pin: string | null } | { ok: false, reason: string }}
+ */
+function parsePnpmPin(raw) {
+  if (raw === undefined || raw === null || raw === "") {
+    return { ok: true, semver: null, pin: null };
+  }
+  const str = String(raw);
+  if (str !== str.trim()) {
+    return { ok: false, reason: "packageManager has leading/trailing whitespace" };
+  }
+  if (/\s/.test(str)) {
+    return { ok: false, reason: "packageManager contains whitespace" };
+  }
+  if (SHELL_METACHAR_RE.test(str)) {
+    return { ok: false, reason: "packageManager contains shell metacharacters" };
+  }
+  if (!str.startsWith("pnpm@")) {
+    return { ok: false, reason: "packageManager must be pnpm@<semver> when set" };
+  }
+  const semver = str.slice("pnpm@".length);
+  if (!semver || !isValidSemVer(semver)) {
+    return { ok: false, reason: "packageManager semver is invalid" };
+  }
+  if (str !== `pnpm@${semver}`) {
+    return { ok: false, reason: "packageManager pin malformed" };
+  }
+  return { ok: true, semver, pin: str };
+}
+
+/**
+ * @param {unknown} name
+ * @param {Record<string, unknown> | undefined} scripts
+ */
+function validateScriptName(name, scripts) {
+  if (typeof name !== "string" || !name || !SCRIPT_NAME_RE.test(name)) {
+    return false;
+  }
+  return !!scripts && Object.prototype.hasOwnProperty.call(scripts, name);
+}
+
+/** @param {string} arg */
+function quoteWin32Arg(arg) {
+  const s = String(arg);
+  if (!/[\s"]/.test(s)) {
+    return s;
+  }
+  return `"${s.replace(/"/g, '""')}"`;
+}
+
+/**
+ * @param {typeof execFileSync} execFn
+ * @param {string} name
+ */
+function hasCmd(execFn, name) {
+  const spawnOpts = (/** @type {Record<string, unknown>} */ extra) => ({
+    stdio: "ignore",
+    windowsHide: true,
+    ...extra,
+  });
+  try {
+    execFn(name, ["--version"], spawnOpts({}));
+    return true;
+  } catch {
+    try {
+      execFn(name, ["--version"], spawnOpts({ shell: true }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * @param {typeof execFileSync} execFn
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd: string, spawn?: Record<string, unknown> }} opts
+ */
+function executeAllowlisted(execFn, cmd, args, opts) {
+  if (!WIN32_ALLOWLIST.has(cmd)) {
+    throw new Error(`deft: allowlisted shim required, got ${JSON.stringify(cmd)}`);
+  }
+  const spawnOverride = opts.spawn && typeof opts.spawn === "object" ? opts.spawn : {};
+  const base = {
+    cwd: opts.cwd,
+    stdio: "inherit",
+    windowsHide: true,
+    shell: false,
+    ...spawnOverride,
+    shell: false,
+  };
+  if (process.platform === "win32") {
+    const commandLine = [quoteWin32Arg(cmd), ...args.map(quoteWin32Arg)].join(" ");
+    execFn("cmd.exe", ["/d", "/s", "/c", commandLine], base);
+    return;
+  }
+  execFn(cmd, args, base);
+}
+
+/**
+ * @param {{ hasPnpm: boolean, hasCorepack: boolean, semver: string | null, script: string }} input
+ */
+function buildDispatchSteps(input) {
+  const steps = [];
+  if (input.hasPnpm) {
+    steps.push({ cmd: "pnpm", args: ["run", input.script] });
+  }
+  if (input.hasCorepack && input.semver) {
+    steps.push({ cmd: "corepack", args: [`pnpm@${input.semver}`, "run", input.script] });
+  }
+  if (input.hasCorepack) {
+    steps.push({ cmd: "corepack", args: ["pnpm", "run", input.script] });
+  }
+  return steps;
+}
+
+/** @param {string} root */
+function markWarm(root) {
+  try {
+    const dist = path.join(root, "packages", "cli", "dist");
+    fs.mkdirSync(dist, { recursive: true });
+    fs.writeFileSync(path.join(dist, ".deft-ts-build-stamp"), new Date().toISOString());
+  } catch {
+    // best-effort warm marker
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} script
+ * @param {{ execFileSync?: typeof execFileSync, markWarm?: boolean }} [deps]
+ */
+function runPackageScript(root, script, deps = {}) {
+  const execFn = deps.execFileSync || execFileSync;
+  const pkgPath = path.join(root, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    console.error(`deft: package.json missing at ${root}`);
+    return 2;
+  }
+  let pkg;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.error(`deft: package.json at ${root} is not a JSON object`);
+      return 2;
+    }
+    pkg = parsed;
+  } catch {
+    console.error(`deft: package.json at ${root} is not valid JSON`);
+    return 2;
+  }
+  if (!validateScriptName(script, pkg.scripts)) {
+    console.error(`deft: package.json has no script ${JSON.stringify(script)}`);
+    return 2;
+  }
+
+  const pinResult = parsePnpmPin(pkg.packageManager);
+  if (!pinResult.ok) {
+    console.error(`deft: invalid packageManager pin — ${pinResult.reason}`);
+    return 3;
+  }
+
+  const envPm = String(process.env.DEFT_PACKAGE_MANAGER || "")
+    .trim()
+    .toLowerCase();
+  if (envPm === "npm") {
+    try {
+      executeAllowlisted(execFn, "npm", ["run", script], { cwd: root });
+      if (deps.markWarm) {
+        markWarm(root);
+      }
+      return 0;
+    } catch {
+      console.error(`deft: npm run ${JSON.stringify(script)} failed`);
+      return 1;
+    }
+  }
+
+  const hasPnpm = hasCmd(execFn, "pnpm");
+  const hasCorepack = hasCmd(execFn, "corepack");
+  const steps = buildDispatchSteps({
+    hasPnpm,
+    hasCorepack,
+    semver: pinResult.semver,
+    script,
+  });
+
+  for (const step of steps) {
+    try {
+      executeAllowlisted(execFn, step.cmd, step.args, { cwd: root });
+      if (deps.markWarm) {
+        markWarm(root);
+      }
+      return 0;
+    } catch {
+      // fall through to Corepack / next resolver
+    }
+  }
+
+  console.error(`deft: neither pnpm nor corepack is available to run ${JSON.stringify(script)}.`);
+  if (pinResult.pin) {
+    console.error(
+      `  Enable Corepack for the pinned manager: corepack enable && corepack prepare ${pinResult.pin} --activate`,
+    );
+  } else {
+    console.error("  Install pnpm or enable Corepack (see package.json#packageManager).");
+  }
+  console.error("  Or set DEFT_PACKAGE_MANAGER=npm for an explicit npm build path.");
+  return 127;
+}
+
+function main() {
+  const root = process.argv[2];
+  const script = process.argv[3];
+  const markWarmFlag = process.argv.includes("--mark-warm");
+  if (!root || !script) {
+    console.error("deft: engine-pm-run usage: engine-pm-run.cjs <DEFT_ROOT> <script> [--mark-warm]");
+    process.exit(2);
+  }
+  const code = runPackageScript(root, script, { markWarm: markWarmFlag });
+  process.exit(code);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  SHELL_METACHAR_RE,
+  WIN32_ALLOWLIST,
+  buildDispatchSteps,
+  executeAllowlisted,
+  hasCmd,
+  isValidSemVer,
+  markWarm,
+  parsePnpmPin,
+  quoteWin32Arg,
+  runPackageScript,
+  validateScriptName,
+};