@deftai/directive-runtime 0.127.0 → 0.129.0

package/tasks/docs.yml

@@ -22,8 +22,6 @@ tasks:
   rule-map:
     desc: "Build the maintainer Rule Map (docs/RULE-MAP.md + gitignored docs/rule-map/index.html)"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -32,8 +30,6 @@ tasks:
   rule-map:check:
     desc: "Fail if committed docs/RULE-MAP.md is out of date (for CI / pre-commit gating)"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -42,15 +38,15 @@ tasks:
   capability-map:
     desc: "Generate content/docs/capabilities.md from the capability overlay (#4099)"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/core/dist/docs/capability-map.js" --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'capability-map --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   capability-map:check:
     desc: "Fail if committed content/docs/capabilities.md is stale or the overlay disagrees with registries (#4099)"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/core/dist/docs/capability-map.js" --project-root "{{.USER_WORKING_DIR}}" --check
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'capability-map --project-root "{{.USER_WORKING_DIR}}" --check'

package/tasks/engine-invoke.cjs

@@ -23,6 +23,11 @@ const CONTENT_PACKAGE_NAME = "@deftai/directive-content";
 /** Single remediation when a deposit has no global CLI (#3324 / #3265). */
 const DEPOSIT_REMEDIATION = "npm i -g @deftai/directive";
 const SOURCE_BUILD_REMEDIATION = "task build";
+/** Missing checkout pin remediation (#5805 Prefer-A Bound P1). */
+const PIN_INSTALL_REMEDIATION =
+  "npm i -g @deftai/directive, then directive install --repair (or package-manager install of @deftai/directive-runtime)";
+const PIN_MATERIALIZE_REMEDIATION = "task materialize:runtime";
+const PIN_BIN_REL = path.join("node_modules", "@deftai", "directive-runtime", "dist", "bin.js");
 
 /**
  * cmd.exe command separators / metacharacters. Free-text DEFT_ENGINE_CMD_JSON
@@ -156,6 +161,63 @@ function hasConsumerDepositMarker(root, opts = {}) {
  * @param {string} root
  * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
  */
+
+/**
+ * Absolute path of the checkout-local pin binary (AC9.9 / #5805).
+ * @param {string} projectRoot
+ * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
+ */
+function resolveFrameworkPinBin(projectRoot, opts = {}) {
+  const pathMod = opts.path || path;
+  if (!projectRoot) return "";
+  return pathMod.join(projectRoot, "node_modules", "@deftai", "directive-runtime", "dist", "bin.js");
+}
+
+/**
+ * True when the checkout-local pin binary exists.
+ * @param {string} projectRoot
+ * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
+ */
+function hasFrameworkPinBin(projectRoot, opts = {}) {
+  const io = opts.fs || fs;
+  const pin = resolveFrameworkPinBin(projectRoot, opts);
+  if (!pin) return false;
+  try {
+    return io.existsSync(pin);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Framework-source ordinary invoke: pin exclusive, fail closed when missing (#5805).
+ * Deposit / non-buildable keep prior hasBin → vendored / global behavior.
+ * @param {{
+ *   hasBin: boolean,
+ *   isBuildableSource: boolean,
+ *   hasPinBin: boolean,
+ *   isRuntimeVerb?: boolean,
+ *   hasGlobalCli?: boolean,
+ * }} input
+ */
+function resolveFrameworkSourceInvoke(input) {
+  if (!input.isBuildableSource) {
+    return resolveInvokeDispatch({
+      hasBin: input.hasBin,
+      isBuildableSource: false,
+      isRuntimeVerb: Boolean(input.isRuntimeVerb),
+      hasGlobalCli: Boolean(input.hasGlobalCli),
+    });
+  }
+  if (input.hasPinBin) {
+    return { action: "vendored", binKind: "pin" };
+  }
+  return {
+    action: "fail-closed",
+    remediations: [PIN_INSTALL_REMEDIATION, PIN_MATERIALIZE_REMEDIATION],
+    exitCode: 2,
+  };
+}
 function isBuildableSource(root, opts = {}) {
   if (hasConsumerDepositMarker(root, opts)) {
     return false;
@@ -337,6 +399,18 @@ if (require.main === module) {
   if (mode === "is-buildable-source") {
     process.exit(isBuildableSource(process.argv[3] || "") ? 0 : 1);
   }
+  if (mode === "pin-bin") {
+    const root = process.argv[3] || "";
+    const pin = resolveFrameworkPinBin(root);
+    if (hasFrameworkPinBin(root)) {
+      process.stdout.write(pin);
+      process.exit(0);
+    }
+    console.error("deft: missing checkout pin " + pin);
+    console.error("  Recovery: " + PIN_INSTALL_REMEDIATION);
+    console.error("  Or tip dogfood: " + PIN_MATERIALIZE_REMEDIATION);
+    process.exit(2);
+  }
   main();
 }
 
@@ -349,9 +423,14 @@ module.exports = {
   isVendoredCoreRoot,
   isBuildableSource,
   resolveInvokeDispatch,
+  resolveFrameworkPinBin,
+  hasFrameworkPinBin,
+  resolveFrameworkSourceInvoke,
   CONSUMER_DEPOSIT_FIELD,
   CONSUMER_DEPOSIT_MARKER_FILE,
   CONTENT_PACKAGE_NAME,
   DEPOSIT_REMEDIATION,
   SOURCE_BUILD_REMEDIATION,
+  PIN_INSTALL_REMEDIATION,
+  PIN_MATERIALIZE_REMEDIATION,
 };

package/tasks/engine-invoke.test.cjs

@@ -533,3 +533,87 @@ describe("buildSpawnPlan — CodeQL absolute-path isolation (#3175 / alert #74)"
     assert.deepEqual(plan.args, [String.raw`C:\repo\packages\cli\dist\bin.js`, "session:start"]);
   });
 });
+
+describe("framework pin exclusive invoke (#5805)", () => {
+  const {
+    resolveFrameworkPinBin,
+    hasFrameworkPinBin,
+    resolveFrameworkSourceInvoke,
+    PIN_INSTALL_REMEDIATION,
+    PIN_MATERIALIZE_REMEDIATION,
+  } = require("./engine-invoke.cjs");
+  const pinRoots = [];
+  function pinTempRoot() {
+    const root = mkdtempSync(join(tmpdir(), "pin-inv-"));
+    pinRoots.push(root);
+    return root;
+  }
+  after(() => {
+    for (const root of pinRoots) {
+      try {
+        rmSync(root, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+
+  it("resolveFrameworkPinBin joins checkout pin path", () => {
+    const pin = resolveFrameworkPinBin(join("C:", "repo"));
+    assert.match(pin.replace(/\\/g, "/"), /node_modules\/@deftai\/directive-runtime\/dist\/bin\.js$/);
+  });
+
+  it("hasFrameworkPinBin is false when missing", () => {
+    const root = pinTempRoot();
+    assert.equal(hasFrameworkPinBin(root), false);
+  });
+
+  it("hasFrameworkPinBin is true when pin bin exists", () => {
+    const root = pinTempRoot();
+    const pin = resolveFrameworkPinBin(root);
+    mkdirSync(require("node:path").dirname(pin), { recursive: true });
+    writeFileSync(pin, "module.exports={}\n");
+    assert.equal(hasFrameworkPinBin(root), true);
+  });
+
+  it("framework-source with pin selects vendored pin (not tip dist)", () => {
+    const plan = resolveFrameworkSourceInvoke({
+      hasBin: true,
+      isBuildableSource: true,
+      hasPinBin: true,
+    });
+    assert.deepEqual(plan, { action: "vendored", binKind: "pin" });
+  });
+
+  it("framework-source missing pin fails closed even when tip dist / global exist", () => {
+    const plan = resolveFrameworkSourceInvoke({
+      hasBin: true,
+      isBuildableSource: true,
+      hasPinBin: false,
+      hasGlobalCli: true,
+      isRuntimeVerb: true,
+    });
+    assert.equal(plan.action, "fail-closed");
+    assert.equal(plan.exitCode, 2);
+    assert.deepEqual(plan.remediations, [PIN_INSTALL_REMEDIATION, PIN_MATERIALIZE_REMEDIATION]);
+  });
+
+  it("deposit path keeps prior resolveInvokeDispatch behavior", () => {
+    const plan = resolveFrameworkSourceInvoke({
+      hasBin: false,
+      isBuildableSource: false,
+      hasPinBin: false,
+      hasGlobalCli: true,
+      isRuntimeVerb: false,
+    });
+    assert.deepEqual(plan, { action: "global" });
+  });
+
+  it("pin-bin CLI exits 2 when missing", () => {
+    const root = pinTempRoot();
+    const script = join(__dirname, "engine-invoke.cjs");
+    const r = spawnSync(process.execPath, [script, "pin-bin", root], { encoding: "utf8" });
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /missing checkout pin/);
+  });
+});

package/tasks/engine.yml

@@ -2,11 +2,13 @@ version: '3'
 
 # Consumer engine resolution (#2022 Phase 3).
 #
-# Framework-source checkouts invoke the vendored `packages/runtime/dist/bin.js`.
+# Framework-source checkouts invoke the checkout pin
+# `node_modules/@deftai/directive-runtime/dist/bin.js` exclusively (#5805 / AC9.9).
+# Tip dogfood without publish is `task materialize:runtime`, not packages/runtime/dist.
 # npm consumer deposits copy @deftai/directive-content only — no bundled CLI —
-# so tasks fall back to the globally installed `deft` / `directive` command.
+# so tasks fall back to OVPR DEFT_ROOT/dist/bin.js or global `deft` / `directive`.
 # A deposit marker (package.json deftConsumerDeposit / .deft-consumer-deposit /
-# @deftai/directive-content name) forces that fallback for every verb (#3324).
+# @deftai/directive-content name) forces that deposit path for every verb (#3324).
 
 vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
@@ -59,7 +61,7 @@ tasks:
 
   invoke:
     internal: true
-    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (deposit / runtime fallback #2409 / #3324). Runtime/session verbs must not trigger engine:_ts-build / pnpm (#2181)."
+    desc: "Run a deft-ts verb from the checkout pin (framework-source #5805) or OVPR/global deposit path (#2409 / #3324). Ordinary framework-source verbs never fall through to packages/runtime/dist."
     # Run from the operator project root so deft verbs resolve USER_WORKING_DIR
     # correctly; without this, included engine.yml defaults cwd to tasks/ (#2022).
     dir: '{{.USER_WORKING_DIR}}'
@@ -71,23 +73,18 @@ tasks:
     cmds:
       - |
         set -eu
-        # OVPR consumer: DEFT_ROOT is node_modules/@deftai/directive-runtime → dist/bin.js.
-        # Framework source / legacy .deft/core: DEFT_ROOT/packages/runtime/dist/bin.js.
-        bin=""
-        if [ -f "{{.DEFT_ROOT}}/dist/bin.js" ]; then
-          bin="{{.DEFT_ROOT}}/dist/bin.js"
-        elif [ -f "{{.DEFT_ROOT}}/packages/runtime/dist/bin.js" ]; then
-          bin="{{.DEFT_ROOT}}/packages/runtime/dist/bin.js"
-        fi
-        root_pkg="{{.DEFT_ROOT}}/package.json"
-        # #3324: deposit marker (package.json field / file / content-package
-        # name) forces is_buildable_source=0 so every verb uses global CLI.
+        # #3324: deposit marker forces is_buildable_source=0 (consumer / OVPR path).
         is_buildable_source=0
         if node "{{.TASKFILE_DIR}}/engine-invoke.cjs" is-buildable-source "{{.DEFT_ROOT}}"; then
           is_buildable_source=1
         fi
-        if [ -n "$bin" ] && [ -f "$bin" ]; then
-          if [ "$is_buildable_source" = 1 ] && [ -f "$root_pkg" ]; then
+        if [ "$is_buildable_source" = 1 ]; then
+          # #5805 Prefer-A Bound: framework-source ordinary invoke is pin-exclusive.
+          # No packages/runtime/dist fallthrough; missing pin fails closed.
+          # Resolve pin from DEFT_ROOT so subdirectory cwd still finds the checkout pin (#5805).
+          pin_bin=$(node "{{.TASKFILE_DIR}}/engine-invoke.cjs" pin-bin "{{.DEFT_ROOT}}" ) || exit $?
+          root_pkg="{{.DEFT_ROOT}}/package.json"
+          if [ -f "$root_pkg" ]; then
             node -e "
               const fs=require('fs');
               const pkg=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));
@@ -101,80 +98,22 @@ tasks:
               }
             " "$root_pkg" || exit $?
           fi
-          node "{{.TASKFILE_DIR}}/engine-invoke.cjs" vendored "$bin"
-        elif [ "$is_buildable_source" = 1 ]; then
-          first_token=$(node -e "process.stdout.write(JSON.parse(process.env.DEFT_ENGINE_CMD_JSON||'\"\"').split(/\\s+/)[0]||'')")
-          is_runtime_verb=0
-          case " ${first_token} " in
-            " session:start "|" session-start "|\
-            " session:ready "|" session-ready "|\
-            " occupancy:steal "|" occupancy-steal "|\
-            " occupancy:release "|" occupancy-release "|\
-            " occupancy:heartbeat "|" occupancy-heartbeat "|\
-            " occupancy:grant "|" occupancy-grant "|\
-            " session:end "|" session-end "|\
-            " lifecycle:event "|" lifecycle-event "|\
-            " verify:session-ritual "|" verify-session-ritual "|\
-            " verify:tools "|" verify-tools "|\
-            " triage:summary "|" triage-summary "|\
-            " triage:welcome "|" triage-welcome "|\
-            " verify:cache-fresh "|" verify-cache-fresh "|\
-            " preflight-cache "|\
-            " ownership:doctor "|" ownership-doctor "|\
-            " ownership:fix "|" ownership-fix "|\
-            " verify:ownership "|" verify-ownership ")
-              is_runtime_verb=1
-              ;;
-          esac
-          if [ "${DEFT_USE_GLOBAL_CLI:-}" = "1" ]; then
-            is_runtime_verb=1
+          node "{{.TASKFILE_DIR}}/engine-invoke.cjs" vendored "$pin_bin"
+        else
+          # OVPR consumer / deposit: DEFT_ROOT is often the runtime package itself.
+          bin=""
+          if [ -f "{{.DEFT_ROOT}}/dist/bin.js" ]; then
+            bin="{{.DEFT_ROOT}}/dist/bin.js"
           fi
-          global_cli=""
-          if command -v deft >/dev/null 2>&1; then
-            global_cli=deft
+          if [ -n "$bin" ] && [ -f "$bin" ]; then
+            node "{{.TASKFILE_DIR}}/engine-invoke.cjs" vendored "$bin"
+          elif command -v deft >/dev/null 2>&1; then
+            node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global deft
           elif command -v directive >/dev/null 2>&1; then
-            global_cli=directive
-          fi
-          if [ "$is_runtime_verb" = 1 ] && [ -n "$global_cli" ]; then
-            node -e "
-              const {execFileSync}=require('child_process');
-              const root=process.argv[1];
-              const cli=process.argv[2];
-              let srcVer='0.0.0-dev';
-              try{
-                if(process.env.DEFT_RELEASE_VERSION){
-                  srcVer=process.env.DEFT_RELEASE_VERSION;
-                }else{
-                  srcVer=execFileSync('git',['describe','--tags','--abbrev=0'],{cwd:root,encoding:'utf8'}).trim().replace(/^v/,'');
-                }
-              }catch{}
-              let globalVer='unknown';
-              try{
-                globalVer=execFileSync(cli,['--version'],{encoding:'utf8'}).trim();
-              }catch{}
-              const m=globalVer.match(/@([0-9]+\\.[0-9]+\\.[0-9]+)/)||globalVer.match(/([0-9]+\\.[0-9]+\\.[0-9]+)/);
-              const gv=m?m[1]:globalVer;
-              if(srcVer!=='0.0.0-dev'&&gv!=='unknown'&&gv!==srcVer){
-                console.error('deft: using global '+cli+' ('+gv+'); source checkout is v'+srcVer+' — run task build for a local engine match.');
-              }
-            " "{{.DEFT_ROOT}}" "$global_cli" >&2 || true
-            node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global "$global_cli"
+            node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global directive
           else
-            echo "deft: CLI artifact missing under {{.DEFT_ROOT}} (tried dist/bin.js and packages/runtime/dist/bin.js)" >&2
-            if [ "$is_runtime_verb" = 1 ]; then
-              echo "  Install global deft: npm i -g @deftai/directive" >&2
-              echo "  Or run \`task build\` first (framework source checkout)." >&2
-            else
-              echo "  Run \`task build\` first (framework source checkout)." >&2
-            fi
+            echo "deft: neither OVPR bin.js under {{.DEFT_ROOT}} nor a global deft command is available." >&2
+            echo "  Install with: npm i -g @deftai/directive" >&2
             exit 2
           fi
-        elif command -v deft >/dev/null 2>&1; then
-          node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global deft
-        elif command -v directive >/dev/null 2>&1; then
-          node "{{.TASKFILE_DIR}}/engine-invoke.cjs" global directive
-        else
-          echo "deft: neither OVPR/legacy bin.js under {{.DEFT_ROOT}} nor a global deft command is available." >&2
-          echo "  Install with: npm i -g @deftai/directive" >&2
-          exit 2
         fi

package/tasks/eval.yml

@@ -6,8 +6,6 @@ vars:
 tasks:
   health:
     desc: "Tier 0 static self-consistency aggregation -- versioned framework health score (#1703). -- task eval:health [-- --json] [--no-persist] [--project-root PATH]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -15,8 +13,6 @@ tasks:
 
   run:
     desc: "Tier 2 golden corpus champion-challenger eval (#1703). -- task eval:run -- --model MODEL [--seed N] [--directive-version V] [--harness NAME] [--json] [--no-persist] [--project-root PATH]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -24,8 +20,6 @@ tasks:
 
   report:
     desc: "Tier 2 version-diff report with significance (#1703). -- task eval:report -- --champion V --challenger V --model MODEL [--json] [--project-root PATH]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -33,8 +27,6 @@ tasks:
 
   triggers:
     desc: "Trigger routing coverage for AGENTS.md / Skills Index (#1586). Offline skill-pi-trigger-eval compatible eval over evals/trigger-cases.jsonl vs REFERENCES.md. -- task eval:triggers [-- --json] [--project-root PATH]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/feedback.yml

@@ -6,8 +6,6 @@ vars:
 tasks:
   file:
     desc: "Draft or file a deduped framework-gap issue upstream (#1709 / #3713). -- task feedback:file -- [--summary TEXT | positional] [--context ...] [--blocker] [--confirm] [--dry-run] [--json]"
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/install.yml

@@ -20,8 +20,6 @@ tasks:
   uninstall:
     desc: Remove deft entry from AGENTS.md
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -62,8 +60,6 @@ tasks:
     # `task upgrade` failed on the primary npm consumer workflow. Framework-root is
     # intentionally omitted: install-upgrade auto-detects the consumer's
     # `.deft/core/VERSION` (#2053) when run from the global engine.
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/issue.yml

@@ -22,8 +22,6 @@ tasks:
   ingest:
     desc: "Ingest GitHub issues as scope vBRIEFs (single <N> or --all [--label L] [--status S] [--dry-run])"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
@@ -39,7 +37,6 @@ tasks:
   emit:
     desc: "File GitHub issue(s) from scope vBRIEF(s) (<path> | --umbrella <glob> | --per-vbrief <glob> [--dry-run])"
     dir: '{{.USER_WORKING_DIR}}'
-    deps: [":engine:_ts-build"]
     env:
       PYTHONUTF8: "1"
     cmds:

package/tasks/lifecycle.yml

@@ -27,7 +27,6 @@ tasks:
   stats:
     desc: "Local xBRIEF lifecycle folder counts for process rollups (#2995). -- task lifecycle:stats -- --since=7d [--json] [--project-root <path>]"
     dir: '{{.USER_WORKING_DIR}}'
-    deps: [':engine:_ts-build']
     env:
       PYTHONUTF8: "1"
     cmds: