@deftai/directive-runtime 0.129.0 → 0.129.2

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

@@ -173,7 +173,7 @@ The agent may suggest the next phase, but the user decides. Phases can be entere
 - **Batch**: `task issue:ingest -- --all [--label <L>] [--status <S>]` — ingests every open issue matching the filters, skipping duplicates by `references.uri` match.
 - **Preview**: add `--dry-run` to either form to preview without writing files.
 
-The task emits xBRIEFs conforming to the canonical v0.6 schema (`xbrief/schemas/xbrief-core.schema.json`) with origin references in the form documented in [`../../conventions/references.md`](../../conventions/references.md):
+The task emits xBRIEFs conforming to the canonical xBRIEF v0.8 schema (`node_modules/@deftai/directive-runtime/vbrief/schemas/xbrief-core-0.8.schema.json`; OVPR pin is schema SoT) with origin references in the form documented in [`../../conventions/references.md`](../../conventions/references.md):
 
 ```json
 "references": [
@@ -187,7 +187,7 @@ The task emits xBRIEFs conforming to the canonical v0.6 schema (`xbrief/schemas/
 
 - ! New scope xBRIEFs MUST target `"xBRIEFInfo": { "version": "0.8" }` (the task handles this automatically)
 - ! `plan.status` starts at `"proposed"`; the task sets this
-- ! Conform to `xbrief/schemas/xbrief-core.schema.json` (v0.6) -- the task validates before writing
+- ! Conform to `node_modules/@deftai/directive-runtime/vbrief/schemas/xbrief-core-0.8.schema.json` (v0.8; pin schema SoT) -- the task validates before writing
 - ~ After ingest, review the generated xBRIEFs with the user before promoting any of them to `pending/`
 
 ⊗ Hand-author scope xBRIEFs inside the skill when the ingest task exists — duplicating the narrative logic is how #534 (non-conformant references) and #537 (drift between skill and task) arise

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

@@ -673,7 +673,7 @@ omit = [
 
 ### Template
 
-! The output MUST conform to the canonical xBRIEF v0.8 schema (`xbrief/schemas/xbrief-core-0.8.schema.json`, strict `const: "0.8"`). See [`../../conventions/references.md`](../../conventions/references.md). Write-path default is **0.8 only** (#2971); legacy 0.6 remains read-accepted until `deft migrate:xbrief`.
+! The output MUST conform to the canonical xBRIEF v0.8 schema (`node_modules/@deftai/directive-runtime/vbrief/schemas/xbrief-core-0.8.schema.json`, strict `const: "0.8"`; OVPR pin is schema SoT — install does not deposit project-root `xbrief/schemas/`). See [`../../conventions/references.md`](../../conventions/references.md). Write-path default is **0.8 only** (#2971); legacy 0.6 remains read-accepted until `deft migrate:xbrief`.
 
 ! Do not write this document onto `xbrief/PROJECT-DEFINITION.xbrief.json` yourself. After confirmation, write it to a temporary narratives file that is not that artifact, then run `deft project:write-narratives --project-root <policy-project-root> --narratives-file <path>`. The command stores Overview, TechStack, Strategy, Quality, ProjectRules, and Branching while `xbrief/active/` is empty. Optional `--title` sets `plan.title` only. A policy block in the temporary file is ignored. Policy still goes through the public writer in the gate above.
 
@@ -893,7 +893,7 @@ Per [strategies/interview.md](../../strategies/interview.md#interview-rules-shar
 - ⊗ Create a separate PRD.md on the Light path
 - ⊗ Generate an authoritative PRD.md — if needed, users run `task prd:render`
 
-! The xBRIEF files MUST conform to `xbrief/schemas/xbrief-core-0.8.schema.json` (v0.8):
+! The xBRIEF files MUST conform to `node_modules/@deftai/directive-runtime/vbrief/schemas/xbrief-core-0.8.schema.json` (v0.8; pin schema SoT):
 
 - ! All `narratives` and `narrative` values MUST be plain strings — never objects or arrays
 - ! Nested children within a PlanItem use `items` (preferred field); `subItems` is the deprecated legacy alias kept for backward compatibility only

package/skills/deft-directive-swarm/references/core-phase-0.md

@@ -153,7 +153,7 @@ Loop body, per candidate (top-of-queue first):
 ? When the operator explicitly opts out of the queue (e.g. a one-off ad-hoc cohort that has not been ingested into the triage cache yet, or a swarm batch driven from a hand-supplied list of issue numbers), the monitor MAY fall back to the legacy GitHub-issue path:
 
 1. ! Fetch issue data: `gh api repos/<owner>/<repo>/issues/<N>` (REST per `templates/agent-prompt-preamble.md` § 5; never the GraphQL `gh issue view --json` surface).
-2. ! Generate a minimal xBRIEF in `xbrief/proposed/` following the `YYYY-MM-DD-descriptive-slug.xbrief.json` naming convention (slug rules: [`../../conventions/vbrief-filenames.md`](../../conventions/vbrief-filenames.md)) and conforming to the canonical v0.6 schema (`xbrief/schemas/xbrief-core.schema.json`, strict `const: "0.6"`; see [`../../conventions/references.md`](../../conventions/references.md)).
+2. ! Generate a minimal xBRIEF in `xbrief/proposed/` following the `YYYY-MM-DD-descriptive-slug.xbrief.json` naming convention (slug rules: [`../../conventions/vbrief-filenames.md`](../../conventions/vbrief-filenames.md)) and conforming to the canonical xBRIEF v0.8 schema (`node_modules/@deftai/directive-runtime/vbrief/schemas/xbrief-core-0.8.schema.json`, strict `const: "0.8"`; OVPR pin is schema SoT — see [`../../conventions/references.md`](../../conventions/references.md)).
 3. ! Promote through the canonical lifecycle (`task scope:promote -- <path>` then `task scope:activate -- <path>`), respecting the WIP cap and the same `--force` audit-logged override semantics as the queue-driven loop.
 4. ! Surface the opt-out reason in the Step 4 (Present Analysis) summary so a reviewer can see WHY the queue was bypassed.
 

package/tasks/docs.yml

@@ -49,4 +49,4 @@ tasks:
     cmds:
       - task: :engine:invoke
         vars:
-          ENGINE_CMD: 'capability-map --project-root "{{.USER_WORKING_DIR}}" --check'
+          ENGINE_CMD: 'capability-map --project-root "{{.USER_WORKING_DIR}}" --check'

package/tasks/engine-invoke.cjs

@@ -23,11 +23,15 @@ 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). */
+/** Missing checkout pin remediation (#5994 / AC9.12): project PM first.
+ * pin-bin path never recommends npm i -g (that is DEPOSIT_REMEDIATION only).
+ */
 const PIN_INSTALL_REMEDIATION =
-  "npm i -g @deftai/directive, then directive install --repair (or package-manager install of @deftai/directive-runtime)";
+  "Run npm install or pnpm install (or yarn) in this project (missing node_modules/@deftai/directive-runtime)";
+/** Tip dogfood secondary when project install is not enough (#5805). */
 const PIN_MATERIALIZE_REMEDIATION = "task materialize:runtime";
 const PIN_BIN_REL = path.join("node_modules", "@deftai", "directive-runtime", "dist", "bin.js");
+const DISABLE_FLAG = ".deft-directive-disable";
 
 /**
  * cmd.exe command separators / metacharacters. Free-text DEFT_ENGINE_CMD_JSON
@@ -178,6 +182,29 @@ function resolveFrameworkPinBin(projectRoot, opts = {}) {
  * @param {string} projectRoot
  * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
  */
+/**
+ * AC9.12 / #5994: untracked root .deft-directive-disable → quiet skip before pin require.
+ * @param {string} projectRoot
+ * @param {{ fs?: typeof fs, path?: typeof path, spawnSync?: typeof spawnSync }} [opts]
+ */
+function isDirectiveDisableActive(projectRoot, opts = {}) {
+  const io = opts.fs || fs;
+  const pathMod = opts.path || path;
+  const spawn = opts.spawnSync || spawnSync;
+  if (!projectRoot) return false;
+  const killPath = pathMod.join(projectRoot, DISABLE_FLAG);
+  try {
+    if (!io.existsSync(killPath)) return false;
+    if (io.lstatSync(killPath).isSymbolicLink()) return false;
+  } catch {
+    return false;
+  }
+  const r = spawn("git", ["-C", projectRoot, "ls-files", "--error-unmatch", "--", DISABLE_FLAG], {
+    stdio: ["ignore", "ignore", "ignore"],
+  });
+  return r.status !== 0;
+}
+
 function hasFrameworkPinBin(projectRoot, opts = {}) {
   const io = opts.fs || fs;
   const pin = resolveFrameworkPinBin(projectRoot, opts);
@@ -399,8 +426,14 @@ if (require.main === module) {
   if (mode === "is-buildable-source") {
     process.exit(isBuildableSource(process.argv[3] || "") ? 0 : 1);
   }
+  if (mode === "disable-active") {
+    process.exit(isDirectiveDisableActive(process.argv[3] || "") ? 0 : 1);
+  }
   if (mode === "pin-bin") {
     const root = process.argv[3] || "";
+    if (isDirectiveDisableActive(root)) {
+      process.exit(0);
+    }
     const pin = resolveFrameworkPinBin(root);
     if (hasFrameworkPinBin(root)) {
       process.stdout.write(pin);
@@ -433,4 +466,6 @@ module.exports = {
   SOURCE_BUILD_REMEDIATION,
   PIN_INSTALL_REMEDIATION,
   PIN_MATERIALIZE_REMEDIATION,
+  isDirectiveDisableActive,
+  DISABLE_FLAG,
 };

package/tasks/engine-invoke.test.cjs

@@ -615,5 +615,19 @@ describe("framework pin exclusive invoke (#5805)", () => {
     const r = spawnSync(process.execPath, [script, "pin-bin", root], { encoding: "utf8" });
     assert.equal(r.status, 2);
     assert.match(r.stderr, /missing checkout pin/);
+    assert.match(r.stderr, /npm install or pnpm install/);
+  });
+
+  it("disable-active / pin-bin quiet-skip when untracked disable flag present (#5994)", () => {
+    const root = pinTempRoot();
+    const script = join(__dirname, "engine-invoke.cjs");
+    writeFileSync(join(root, ".deft-directive-disable"), "1\n");
+    // Ensure git repo so ls-files --error-unmatch can run (untracked → active).
+    spawnSync("git", ["init"], { cwd: root, stdio: "ignore" });
+    const d = spawnSync(process.execPath, [script, "disable-active", root], { encoding: "utf8" });
+    assert.equal(d.status, 0);
+    const r = spawnSync(process.execPath, [script, "pin-bin", root], { encoding: "utf8" });
+    assert.equal(r.status, 0);
+    assert.equal((r.stdout || "").trim(), "");
   });
 });

package/tasks/engine.yml

@@ -73,6 +73,11 @@ tasks:
     cmds:
       - |
         set -eu
+        # #5994 / AC9.12 / F1: disable BEFORE requiring pin bin.js; quiet skip.
+        # Untracked root .deft-directive-disable → exit 0 (no pin require, no global install).
+        if node "{{.TASKFILE_DIR}}/engine-invoke.cjs" disable-active "{{.DEFT_ROOT}}"; then
+          exit 0
+        fi
         # #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

package/vendor/directive-content/.githooks/_directive-run.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env sh
-# Package-relative Directive git-hook helper (AC9.9).
+# Package-relative Directive git-hook helper (AC9.9 / AC9.12 / #5994).
 # Sourced by pre-commit/pre-push; defines run_directive.
+# F1 order: disable → missing pin (project PM) → pin bin.js.
 if [ -z "${REPO_ROOT:-}" ]; then
   REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 fi
@@ -8,23 +9,19 @@ if [ -z "$REPO_ROOT" ]; then
   echo "directive hooks: unable to resolve repo root." >&2
   exit 1
 fi
-RUNTIME_BIN="$REPO_ROOT/node_modules/@deftai/directive-runtime/dist/bin.js"
-if [ ! -f "$RUNTIME_BIN" ]; then
-  echo "directive hooks: missing $RUNTIME_BIN" >&2
-  echo "Recovery: npm i -g @deftai/directive, then directive install --repair" >&2
-  exit 1
-fi
 run_directive() {
-  # #3039 / #5543: root local kill-switch — skip CLI spawn when flag is present,
-  # not a symlink, and not tracked by git (tracked flag must not disable clones).
+  # #3039 / #5543 / #5994 F1: disable BEFORE requiring pin bin.js; quiet skip.
   _kill="$REPO_ROOT/.deft-directive-disable"
   if [ -f "$_kill" ] && [ ! -L "$_kill" ]; then
     if ! git -C "$REPO_ROOT" ls-files --error-unmatch -- .deft-directive-disable >/dev/null 2>&1; then
-      echo "Directive is DISABLED for this project via root .deft-directive-disable (test/local kill-switch)." >&2
-      echo "Git hooks skipping Directive CLI spawn (#5543 / #3039). Deposit may remain." >&2
-      echo "Recovery: rm .deft-directive-disable && start a new agent session." >&2
       return 0
     fi
   fi
+  RUNTIME_BIN="$REPO_ROOT/node_modules/@deftai/directive-runtime/dist/bin.js"
+  if [ ! -f "$RUNTIME_BIN" ]; then
+    echo "directive hooks: missing $RUNTIME_BIN" >&2
+    echo "Directive hooks: missing node_modules/@deftai/directive-runtime. Run npm install or pnpm install (or yarn) in this project." >&2
+    exit 1
+  fi
   node "$RUNTIME_BIN" "$@"
 }

package/vendor/directive-content/.githooks/pre-push

@@ -5,8 +5,4 @@ REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 1
 . "$REPO_ROOT/.githooks/_directive-run.sh"
 run_directive verify:branch --project-root "$REPO_ROOT" || exit $?
 # Enrolled bound pre-PR arm: sole-stdin (do not redirect shared run_directive to /dev/null)
-# Pins older than #5804 lack --push-admit: keep the pre-#5804 hook there (verify:branch only).
-_pre_pr_help="$(run_directive pre-pr:run --help </dev/null 2>&1)" || exit $?
-case "$_pre_pr_help" in
-  *--push-admit*) run_directive pre-pr:run --push-admit --project-root "$REPO_ROOT" || exit $? ;;
-esac
+run_directive pre-pr:run --push-admit --project-root "$REPO_ROOT" || exit $?

package/vendor/directive-content/UPGRADING.md

@@ -79,7 +79,7 @@ npm install -g --allow-scripts=<pkg,...> <package>
 
 ### Framework monorepo contributors
 
-Install source of truth for this repo is **pnpm** (`packageManager` field; CI uses `pnpm install --frozen-lockfile`). Install-script builds are gated by `pnpm-workspace.yaml` **`allowBuilds`** (currently `esbuild: true`). Do **not** treat `npm approve-scripts` under the pnpm virtual store as monorepo SoT.
+Install source of truth for this repo is **pnpm** (`packageManager` field; CI uses `pnpm install --frozen-lockfile`). Install-script builds are gated by `pnpm-workspace.yaml` **`allowBuilds`** (currently `esbuild: true` where needed). **`allowBuilds` is PM-owned**: Directive install/upgrade uses the package manager for `package.json` / lockfile pin ops and does **not** hand-edit `allowBuilds`. If pnpm fails with `ERR_PNPM_IGNORED_BUILDS`, recover with `pnpm approve-builds` or set a real `true`/`false` under `allowBuilds` — do **not** commit pnpm's interactive placeholder text. Pin/add paths already pass `--ignore-scripts` so ordinary consumer upgrades should not need a runtime `allowBuilds` entry. Do **not** treat `npm approve-scripts` under the pnpm virtual store as monorepo SoT.
 
 ### Git / remote package sources and publish
 
@@ -456,7 +456,7 @@ import schema from "@deftai/directive-types/schemas/xbrief-core-0.8.schema.json"
 
 **Supported public API:** `@deftai/directive-types` and its published schema subpaths only. **`@deftai/directive-core` is published for npm dependency resolution but is not a supported library surface** — use the `deft` / `directive` CLI for behavior.
 
-**Schema source of truth:** `content/vbrief/schemas/vbrief-core.schema.json` in the directive repo. The types package mirrors it to `packages/types/schemas/` at build time; `deft` install also deposits schemas under project-root `xbrief/schemas/`. When in doubt, treat the directive repo canonical file as authoritative and refresh mirrors with `deft update` (install) or `@deftai/directive-types` (npm).
+**Schema source of truth (OVPR):** the pinned runtime ships schemas under `node_modules/@deftai/directive-runtime/vbrief/schemas/` (current write schema: `xbrief-core-0.8.schema.json`). The types package publishes the same artifacts as `@deftai/directive-types/schemas/…`. Framework source authors at `content/vbrief/schemas/`. Install does **not** deposit project-root `xbrief/schemas/`. Refresh via `directive upgrade` (pin) or `@deftai/directive-types` (npm).
 
 ### `deft migrate` vs pre-v0.20 document-model migration