@deftai/directive-content 0.58.0 → 0.60.0

package/scm/github.md

@@ -214,6 +214,26 @@ Following a v1.0.0 release, commits:
 - ⊗ Allow force pushes
 - ⊗ Allow deletions
 
+## ghx cache proxy (#884)
+
+[ghx](https://github.com/brunoborges/ghx) is a **supported, recommended** read-only cache proxy for the GitHub CLI. Deft's SCM layer (`resolveBinary` in `@deftai/directive-core/scm`) prefers `ghx` over `gh` when both are on PATH, so consumers benefit automatically once ghx is installed. ghx is optional for consumer projects — only `gh` is required — but strongly recommended for maintainers and multi-agent swarms that issue many read-only `gh api` / `gh issue view` calls.
+
+**Install (consent-gated, default deny):**
+
+```bash
+directive setup:ghx          # interactive y/N prompt (default: no)
+task setup:ghx               # same via Taskfile
+task setup:ghx -- --yes      # non-interactive CI / scripted approval
+```
+
+`task setup` runs a detection-only `--check` pass and nudges when `gh` is present but `ghx` is missing. Set `DEFT_SETUP_GHX_SKIP=1` to suppress the interactive install path in non-interactive shells.
+
+**Surface rules:**
+
+- ! Prefer `ghx` over `gh` for read-only GET operations when ghx is on PATH
+- ! Use live `gh` for mutations (POST/PATCH/PUT/DELETE) and for immediate read-back after a mutation — ghx is a cached GET proxy only
+- ⊗ Use `ghx api` for multi-arg write invocations — ghx accepts a single positional path arg; writes fall through to `gh`
+
 ## Destructive gh verbs (#1019)
 
 A detection-bound gate (`scripts/preflight_gh.py`) refuses three classes of destructive surface before they execute, complementing the #747 branch-protection gate which already refuses commits to the default branch:
@@ -234,8 +254,6 @@ Three enforcement surfaces back the gate:
 - For repo deletion specifically: prefer the GitHub web UI's archive-or-delete prompt -- archiving is reversible, the gate is not opining on it.
 - For an admin merge: the canonical recovery is to request review through the normal flow. The `--admin` flag is gated because the most-common legitimate use case (release hot-fix) is rare enough that documenting an explicit bypass is cheaper than letting the verb pass by default.
 
-**Out of scope (v1):** a PATH-shim that intercepts `gh` at the command layer is deferred -- the consent-gated install path mirrors `setup_ghx.py` (#884) and lands additively when a follow-up issue is opened. The current gate is detection-bound (pre-push hook + agent-side `--command` classifier + self-test contract) rather than execution-bound, which is sufficient to refuse the recurring failure mode that motivated #1019 (an agent with an unrestricted `gh` token executing a destructive verb).
-
 ## Release Workflow (UCCPR)
 
 **UCCPR** = Update Changelog, Commit, Push, Release

package/tasks/change.yml

@@ -3,44 +3,29 @@ version: '3'
 vars:
   # Per ../Taskfile.yml header: joinPath is evaluated eagerly by go-task
   # templating and yields a native-separator absolute path so {{.DEFT_ROOT}}
-  # resolves correctly under uv on Windows (#566). Used here to pin
-  # `uv --project` against ancestor pyproject.toml leakage (#1011).
+  # resolves correctly under node on Windows (#566).
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 
 tasks:
+  _ts-build:
+    internal: true
+    desc: "Build @deftai/cli dist/ before TS-backed gates run (#1828 s2)."
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
   changelog:check:
     desc: Verify CHANGELOG.md has an [Unreleased] section with at least one entry
-    env:
-      PYTHONUTF8: "1"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
     cmds:
-      - cmd: >-
-          uv --project "{{.DEFT_ROOT}}" run python -c
-          "import sys, pathlib, re;
-          p = pathlib.Path('CHANGELOG.md');
-          (not p.exists()) and (print('FAIL: CHANGELOG.md not found'), sys.exit(1));
-          text = p.read_text('utf-8');
-          m = re.search(r'## \[Unreleased\][ \t]*\n(.*?)(?=\n## \[|$)', text, re.DOTALL);
-          (m is None) and (print('FAIL: No [Unreleased] section found in CHANGELOG.md'), sys.exit(1));
-          body = m.group(1);
-          entries = [l for l in body.splitlines() if l.strip().startswith('- ')];
-          (len(entries) == 0) and (print('FAIL: [Unreleased] section has no entries (no lines starting with \"- \")'), sys.exit(1));
-          print(f'OK: CHANGELOG.md [Unreleased] section has {len(entries)} entries')"
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" changelog-check --project-root "{{.USER_WORKING_DIR}}"
 
   change:init:
     desc: Create a new change proposal directory structure in history/changes/<name>/
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
     cmds:
-      - cmd: >-
-          uv --project "{{.DEFT_ROOT}}" run python -c
-          "import sys, pathlib, json, re;
-          name = '{{.CLI_ARGS}}'.strip();
-          (not name) and (print('FAIL: Usage: task change:init -- <name>'), sys.exit(1));
-          (not re.match(r'^[\w][\w-]*$', name)) and (print('FAIL: Name must contain only alphanumeric characters, underscores, and hyphens'), sys.exit(1));
-          base = pathlib.Path('history/changes') / name;
-          base.exists() and (print(f'FAIL: {base} already exists'), sys.exit(1));
-          (base / 'specs').mkdir(parents=True, exist_ok=True);
-          proposal = {'vBRIEFInfo': {'version': '0.5'}, 'plan': {'title': name, 'status': 'draft', 'narratives': {'Problem': 'What is wrong or missing.', 'Change': 'What this proposal does about it.', 'Scope': 'In scope: ...  Out of scope: ...', 'Impact': 'What existing code/specs are affected.', 'Risks': 'What could go wrong.', 'Approach': 'How to implement the change.', 'Alternatives': 'What else was considered and why not.', 'Dependencies': 'What must exist before this works.'}}};
-          (base / 'proposal.vbrief.json').write_text(json.dumps(proposal, indent=2) + chr(10), encoding='utf-8');
-          tasks = {'vBRIEFInfo': {'version': '0.5'}, 'plan': {'title': name, 'status': 'draft', 'items': [], 'edges': []}};
-          (base / 'tasks.vbrief.json').write_text(json.dumps(tasks, indent=2) + chr(10), encoding='utf-8');
-          print(f'OK: Created change proposal at {base}/');
-          [print(f'  - {f}') for f in ['proposal.vbrief.json', 'tasks.vbrief.json', 'specs/']]"
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" change-init --project-root "{{.USER_WORKING_DIR}}" --name {{.CLI_ARGS}}

package/tasks/ci.yml

@@ -1,5 +1,13 @@
 version: '3'
 
+# Maintainer-only local CI mirror (#1813 contributor path / #2022 Phase 2).
+#
+# `ci:local` shells into scripts/ci_local.py via `uv run python`. Release
+# Step-5 pre-flight now uses the TS `task check` path (py-purge-ci-local-ts);
+# this fragment remains for explicit maintainer local CI only. Included from
+# the root Taskfile with `internal: true` — not wired into `check:consumer`
+# or the default `task check` aggregate.
+
 vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 

package/tasks/commit.yml

@@ -3,28 +3,21 @@ version: '3'
 vars:
   # Per ../Taskfile.yml header: joinPath is evaluated eagerly by go-task
   # templating and yields a native-separator absolute path so {{.DEFT_ROOT}}
-  # resolves correctly under uv on Windows (#566). Used here to pin
-  # `uv --project` against ancestor pyproject.toml leakage (#1011).
+  # resolves correctly under node on Windows (#566).
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 
 tasks:
+  _ts-build:
+    internal: true
+    desc: "Build @deftai/cli dist/ before TS-backed gates run (#1828 s2)."
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
   commit:lint:
     desc: Validate HEAD commit message against conventional commit format
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
     cmds:
-      - cmd: >-
-          uv --project "{{.DEFT_ROOT}}" run python -c
-          "import sys, re, subprocess;
-          result = subprocess.run(['git', 'log', '--format=%B', '-1'], capture_output=True, text=True);
-          (result.returncode != 0) and (print('FAIL: Could not read HEAD commit message'), sys.exit(1));
-          msg = result.stdout.strip();
-          subject = msg.splitlines()[0] if msg else '';
-          types = 'feat|fix|docs|chore|refactor|test|style|perf|ci|build|revert';
-          pattern = r'^(' + types + r')(\(.+\))?!?: .+';
-          ok = re.match(pattern, subject);
-          (not ok) and (print('FAIL: Commit message does not match conventional commit format'),
-          print(f'  Got:      {subject}'),
-          print(f'  Expected: type(scope): description'),
-          print(f'  Types:    feat, fix, docs, chore, refactor, test, style, perf, ci, build, revert'),
-          sys.exit(1));
-          print(f'OK: Commit message is valid conventional commit');
-          print(f'  Subject: {subject}')"
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" commit-lint --project-root "{{.USER_WORKING_DIR}}"

package/tasks/core.yml

@@ -1,5 +1,15 @@
 version: '3'
 
+# Maintainer-only Python self-test lane (#1813 contributor path / #2022 Phase 2).
+#
+# pytest, ruff, black, and mypy run here via `uv run` for framework-source-repo
+# pre-commit checks. This fragment is included from the root Taskfile with
+# `internal: true` so `core:*` tasks are NOT listed or callable from the CLI on
+# consumer installs — only `task check:framework-source` wires them as deps.
+#
+# Consumer `task check` dispatches to `check:consumer` (TS / deft verbs only).
+# Do NOT add these tasks to the consumer check aggregate.
+
 vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 

package/tasks/engine.yml

@@ -0,0 +1,42 @@
+version: '3'
+
+# Consumer engine resolution (#2022 Phase 3).
+#
+# Framework-source checkouts invoke the vendored `packages/cli/dist/bin.js`.
+# npm consumer deposits copy @deftai/directive-content only — no bundled CLI —
+# so tasks fall back to the globally installed `deft` / `directive` command.
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  _ts-build:
+    internal: true
+    desc: "Build CLI dist when running from the framework source checkout; no-op on npm consumer deposits (#2022 Phase 3)."
+    dir: '{{.DEFT_ROOT}}'
+    cmds:
+      - |
+        set -eu
+        if [ -f packages/cli/dist/bin.js ]; then
+          pnpm run build
+        fi
+
+  invoke:
+    internal: true
+    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (npm consumer deposit)."
+    # 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}}'
+    cmds:
+      - |
+        set -eu
+        bin="{{.DEFT_ROOT}}/packages/cli/dist/bin.js"
+        if [ -f "$bin" ]; then
+          node "$bin" {{.ENGINE_CMD}}
+        elif command -v deft >/dev/null 2>&1; then
+          deft {{.ENGINE_CMD}}
+        else
+          echo "deft: neither {{.DEFT_ROOT}}/packages/cli/dist/bin.js nor a global deft command is available." >&2
+          echo "  Install with: npm i -g @deftai/directive" >&2
+          exit 2
+        fi

package/tasks/framework.yml

@@ -13,6 +13,9 @@ version: '3'
 # `cmds:` skip would silently discard the recovery flag.
 
 vars:
+  # Per ../Taskfile.yml header: joinPath is evaluated eagerly by go-task
+  # templating and yields a native-separator absolute path so {{.DEFT_ROOT}}
+  # resolves correctly under node on Windows (#566).
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 
 tasks:

package/tasks/install.yml

@@ -3,11 +3,17 @@ version: '3'
 vars:
   # Per ../Taskfile.yml header: joinPath is evaluated eagerly by go-task
   # templating and yields a native-separator absolute path so {{.DEFT_ROOT}}
-  # resolves correctly under uv on Windows (#566). Used here to pin
-  # `uv --project` against ancestor pyproject.toml leakage (#1011).
+  # resolves correctly under node on Windows (#566).
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 
 tasks:
+  _ts-build:
+    internal: true
+    desc: "Build @deftai/cli dist/ before TS-backed gates run (#1828 s2)."
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
   install:
     desc: Install deft (dev convenience -- end users should use the compiled binary from GitHub Releases)
     cmds:
@@ -15,23 +21,18 @@ tasks:
 
   uninstall:
     desc: Remove deft entry from AGENTS.md
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
     cmds:
-      - cmd: >-
-          uv --project "{{.DEFT_ROOT}}" run python -c "from pathlib import Path;
-          f=Path('AGENTS.md');
-          t=f.read_text('utf-8') if f.exists() else '';
-          lines=t.splitlines(keepends=True);
-          out=''.join(l for l in lines if not l.startswith('See deft/main.md') and not l.startswith('Skills: deft/skills/'));
-          f.write_text(out,'utf-8') if f.exists() else None;
-          print('Removed deft entry from AGENTS.md' if out!=t else 'No deft entry found in AGENTS.md')"
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" install-uninstall --project-root "{{.USER_WORKING_DIR}}"
 
-  # User-facing upgrade entrypoint (#1061). Wraps the canonical
-  # ``run upgrade`` command (`cmd_upgrade` in ./run) which:
+  # User-facing upgrade entrypoint (#1061). Native deft-ts handler (#2022 Phase 2):
   #   1. Writes / refreshes the bare ``.deft-version`` marker.
   #   2. Writes the canonical YAML provenance manifest at
   #      ``<install>/VERSION`` (#1046 PR-B AC-4) -- including the
   #      ``install_root`` field added in #1062.
-  #   3. Delegates to ``cmd_agents_refresh`` so the AGENTS.md managed
+  #   3. Delegates to ``agents:refresh`` so the AGENTS.md managed
   #      section is brought to the current rendered template (v3 marker
   #      with sha/refreshed/session attributes, #1046 PR-B AC-5).
   # This wrapper exists so the ``framework:doctor`` failure prose and
@@ -43,18 +44,18 @@ tasks:
   # ``generates:`` because the task is mutating + must run on every
   # invocation. CLI_ARGS is explicitly cleared (``vars: { CLI_ARGS: "" }``)
   # so any operator-supplied ``-- <flags>`` are deterministically dropped
-  # before reaching ``run upgrade``: go-task only forwards ``{{.CLI_ARGS}}``
+  # before reaching the upgrade handler: go-task only forwards ``{{.CLI_ARGS}}``
   # when a ``cmds`` line references it, but pinning the var to empty makes
   # the contract explicit AND defends against a future edit that
   # accidentally appends ``{{.CLI_ARGS}}`` to the dispatch line (SLizard P1
-  # on PR #1067 -- ``cmd_upgrade`` does not currently accept flags; future
+  # on PR #1067 -- the upgrade handler does not currently accept flags; future
   # flag additions land deliberately, not implicitly via Taskfile drift).
   upgrade:
-    desc: "Upgrade deft framework: refresh AGENTS.md to current marker, write canonical install manifest, regenerate .deft-version derivative (#1061). Wraps `run upgrade`."
+    desc: "Upgrade deft framework: refresh AGENTS.md to current marker, write canonical install manifest, regenerate .deft-version derivative (#1061). Dispatches via deft-ts install-upgrade."
     dir: '{{.USER_WORKING_DIR}}'
-    env:
-      PYTHONUTF8: "1"
     vars:
       CLI_ARGS: ""
+    deps:
+      - _ts-build
     cmds:
-      - uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/run" upgrade
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" install-upgrade --project-root "{{.USER_WORKING_DIR}}" --framework-root "{{.DEFT_ROOT}}"

package/tasks/migrate.yml

@@ -1,13 +1,22 @@
 version: '3'
 
 vars:
-  # See deft/Taskfile.yml for the rationale behind per-subfile DEFT_ROOT
-  # (go-task re-evaluates var templates at use site; joinPath is eager and
-  # produces a clean, native-separator path so `uv --project "{{.DEFT_ROOT}}" run python` resolves it
-  # correctly on Windows -- #566).
+  # Per ../Taskfile.yml header: joinPath is evaluated eagerly by go-task
+  # templating and yields a native-separator absolute path so {{.DEFT_ROOT}}
+  # resolves correctly under node on Windows (#566).
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 
 tasks:
+  _ts-build:
+    internal: true
+    desc: "Build @deftai/cli dist/ before TS-backed gates run (#1828 s2)."
+    # Match scope.yml _ensure-ts: run from USER_WORKING_DIR with pnpm --dir so
+    # Windows consumer invocations via `-t <abs Taskfile>` do not double-prefix
+    # DEFT_ROOT under go-task's dir: handling (#566 / Windows CI regression).
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
   preflight:
     # Agent-side environment preflight for `task migrate:vbrief` (#793).
     # Reifies the prose contract documented in
@@ -18,16 +27,19 @@ tasks:
     # any destructive mutation runs. Three-state exit (0 ready / 1 not-ready / 2 config
     # error) mirrors `scripts/preflight_branch.py` (#747).
     #
+    # Consumer path dispatches through the native deft-ts handler (#2022 Phase 2);
+    # the legacy Python script remains for maintainer parity only.
+    #
     # NO `sources:` / `generates:` per `conventions/task-caching.md`: the
     # script forwards user-facing CLI flags (`--project-root`, `--deft-root`,
     # `--quiet`) via `{{.CLI_ARGS}}` and a cached cmds skip would silently
     # swallow them.
     desc: "Verify environment readiness for `task migrate:vbrief` (uv on PATH, v0.20+ layout, document model, git tree). Three-state exit (#793)."
     dir: '{{.USER_WORKING_DIR}}'
-    env:
-      PYTHONUTF8: "1"
+    deps:
+      - _ts-build
     cmds:
-      - uv --project "{{.DEFT_ROOT}}" run --frozen python "{{.DEFT_ROOT}}/scripts/migrate_preflight.py" --project-root "{{.USER_WORKING_DIR}}" --deft-root "{{.DEFT_ROOT}}" {{.CLI_ARGS}}
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" migrate-preflight --project-root "{{.USER_WORKING_DIR}}" --deft-root "{{.DEFT_ROOT}}" {{.CLI_ARGS}}
 
   vbrief:
     desc: >
@@ -44,12 +56,15 @@ tasks:
       run::_check_upgrade_gate is consulted by the CLI flow). See
       events/registry.json for the payload contracts and `DEFT_EVENT_LOG` for
       opt-in JSON-line capture (#635).
+      #2013 HOLDOUT: `migrate:vbrief` remains the sole consumer-path Python
+      entrypoint until the spec-authority umbrella resolves the
+      `migrate_vbrief.py` port-vs-cutoff decision (#2022 Phase 2).
     deps:
       # #793: gate destructive migration on the environment preflight. A
       # non-zero exit from the preflight task aborts this task before any
       # `cmds:` line runs. Operator-supplied `{{.CLI_ARGS}}` (e.g.
       # `--dry-run`, `--force`, `--rollback`, `--strict`) belong to the
-      # migrator and are NOT valid migrate_preflight.py flags. go-task
+      # migrator and are NOT valid migrate:preflight flags. go-task
       # forwards parent CLI_ARGS into dependency tasks by default, so we
       # explicitly clear CLI_ARGS here; otherwise `task migrate:vbrief --
       # --dry-run` reaches the preflight argparse surface as
@@ -63,11 +78,7 @@ tasks:
     env:
       PYTHONUTF8: "1"
     cmds:
-      # Pass Taskfile CLI args through so operators can opt into safety flags
-      # (#497) or --strict reconciliation (#496) without editing this file.
-      # Script path uses {{.DEFT_ROOT}} (defined locally in this file's
-      # `vars:` block above via `joinPath .TASKFILE_DIR ".."` -- see
-      # ../Taskfile.yml for why root-level definition is avoided) rather
-      # than {{.TASKFILE_DIR}}/.. to keep the path traversal-free; the
-      # mixed-separator form breaks `uv --project "{{.DEFT_ROOT}}" run python` on Windows (#566).
+      # #2013 holdout: migrate_vbrief.py stays on the consumer path until the
+      # spec-authority umbrella closes the port-vs-cutoff decision (#2022).
+      # Preflight is TS-native; the migrator body remains Python for now.
       - uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/scripts/migrate_vbrief.py" "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}

package/tasks/project.yml

@@ -9,6 +9,12 @@ vars:
 # own repo root when invoked via ``includes:`` -- consumers got their data
 # scanned from ``deft/vbrief/``. Switched to ``{{.USER_WORKING_DIR}}`` to
 # match the convention used by roadmap:render / spec:render / migrate:vbrief.
+#
+# Staleness acknowledgement (#640): ``task project:ack-staleness`` records a
+# completed-scope watermark on PROJECT-DEFINITION ``plan.metadata.staleness_review``
+# so ``task project:render`` stops re-emitting the same narrative staleness flags
+# after review. This is distinct from ``task reconcile:issues``, which reconciles
+# origin freshness on scope vBRIEFs — not PROJECT-DEFINITION narrative heuristics.
 
 tasks:
   _ts-build:
@@ -25,3 +31,13 @@ tasks:
       - _ts-build
     cmds:
       - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" project-render "{{.USER_WORKING_DIR}}/vbrief"
+
+  ack-staleness:
+    desc: >-
+      Acknowledge reviewed PROJECT-DEFINITION narrative staleness (#640).
+      Distinct from task reconcile:issues (scope origin freshness).
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" project-render --acknowledge-staleness "{{.USER_WORKING_DIR}}/vbrief"

package/tasks/relocate.yml

@@ -1,56 +1,26 @@
 version: '3'
 
-# tasks/relocate.yml -- wipe-and-reinstall relocator surface (#992 PR2).
+# tasks/relocate.yml -- DROPPED from the consumer task surface (#2022).
 #
-# Wires `task relocate` to scripts/relocate.py with full {{.CLI_ARGS}}
-# pass-through so operators can compose flags as documented in the script
-# docstring (--project-root / --framework-source / --force / --confirm /
-# --no-confirm / --dry-run / --rollback / --snapshot / --no-snapshot /
-# --json / --quiet).
+# The relocate task previously wired `task relocate` (namespaced
+# `relocate:relocate`) to `uv run python scripts/relocate.py` -- the sole
+# remaining consumer-exposed Python coupling on the deft task surface. Per
+# the #2022 Python-purge readiness gate it has been REMOVED from the
+# consumer-exposed task graph: this fragment is no longer referenced by the
+# root Taskfile.yml `includes:` block and exposes no task.
 #
-# Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
-# declarations because user-facing recovery flags (`--force`, `--confirm`,
-# `--rollback`, `--dry-run`) flow via {{.CLI_ARGS}} -- a go-task cache
-# short-circuit would silently drop the recovery flag and leave the
-# operator following the docs against an exit-0 no-op (the same hazard
-# `task prd:render -- --force` hit at #574).
+# Canonical consumer (re)install / relocate path is now the npm installer
+# (`npm i -g @deftai/directive@latest`), NOT a bundled task -- see
+# content/UPGRADING.md "Manual drift repair" and #1912 (the relocator is a
+# back-compat / legacy bridge only, never a routine-upgrade path). The
+# underlying helper scripts/relocate.py is intentionally retained for #1860
+# (big-bang Python delete) to remove; this story only drops the consumer
+# task surface.
 #
-# Path resolution uses the same {{.TASKFILE_DIR}} / joinPath idiom every
-# other fragment uses (#566) so the dispatch resolves correctly under
-# Windows / macOS / Linux. The dispatched script lives at
-# {{.DEFT_ROOT}}/scripts/relocate.py with helper modules at
-# {{.DEFT_ROOT}}/scripts/_relocate_states.py and
-# {{.DEFT_ROOT}}/scripts/_relocate_snapshot.py.
-#
-# Usage notes for operators:
-#
-# - Bare invocation against a project root that needs relocating prompts
-#   `[y/N]` on stdin (auto-prompt never auto-wipe per the active vBRIEF).
-# - For scripted use, pass `--confirm` to skip the prompt (or
-#   `--no-snapshot` for hermetic test fixtures).
-# - For consumer projects: the canonical entry point is the webinstaller
-#   bootstrap (`upgrade.sh` / `upgrade.ps1` in the separate `webinstaller`
-#   repo) which fetches a fresh framework copy to a temp dir and runs the
-#   relocator from THAT copy -- the in-place framework about to be wiped
-#   never executes its own wipe.
-# - `task relocate -- --rollback` extracts the most recent snapshot back
-#   into project root.
-#
-# Companion script: scripts/relocate.py
-# Companion tests:  tests/relocate/test_state_matrix.py
-#                   tests/relocate/test_preflight.py
-# Refs: #992 (parent issue), #11 (.deft/core/ origin),
-#       #768 (managed-section v2 contract), #794 (_wrap_legacy_in_markers),
-#       #884 (consent-gate convention).
+# This file is retained (un-wired) so the framework's own Taskfile
+# content-contract tests keep a stable fixture. The DEFT_ROOT joinPath var
+# below preserves the #566 per-subfile path-resolution idiom for any future
+# maintainer-side re-wiring.
 
 vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
-
-tasks:
-  relocate:
-    desc: "Wipe-and-reinstall relocator (#992 PR2) -- task relocate [-- --confirm | --dry-run | --force | --rollback | --json | --quiet]"
-    dir: '{{.USER_WORKING_DIR}}'
-    env:
-      PYTHONUTF8: "1"
-    cmds:
-      - uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/scripts/relocate.py" {{.CLI_ARGS}}

package/tasks/toolchain.yml

@@ -5,9 +5,19 @@ vars:
 
 tasks:
   check:
-    desc: Verify required toolchain is installed (go, uv, git, gh, node, pnpm)
-    deps: [":ts:build"]
-    env:
-      PYTHONUTF8: "1"
+    desc: Verify required maintainer toolchain is installed (go, uv, git, gh, node, pnpm)
+    deps:
+      - task: :engine:_ts-build
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" toolchain:check
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'toolchain-check'
+
+  check-consumer:
+    desc: Verify required consumer toolchain is installed (git, gh, node, pnpm, task) without Python/go/uv (#2022 Phase 3).
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'toolchain-check --consumer'

package/tasks/vbrief.yml

@@ -15,10 +15,11 @@ tasks:
     desc: Validate vBRIEF lifecycle folder structure and cross-file consistency
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
-      # Oracle/fallback (parity): scripts/vbrief_validate.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief:validate --vbrief-dir "{{.USER_WORKING_DIR}}/vbrief"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'vbrief:validate --vbrief-dir "{{.USER_WORKING_DIR}}/vbrief"'
 
   preflight:
     # Implementation-intent preflight wrapper (#810 / PR #812 fixup;

package/tasks/verify.yml

@@ -70,15 +70,11 @@ tasks:
     desc: "Detection-bound branch-protection gate (#747). Reads plan.policy.allowDirectCommitsToMaster from PROJECT-DEFINITION."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
-      # Oracle/fallback (parity): scripts/preflight_branch.py (#1828 Wave 8).
-      # `--allow-missing-project-definition` keeps the framework's own check
-      # green for fresh checkouts that have not yet run `task setup` (the
-      # bootstrap fallback path documented in #746 acceptance criterion E).
-      # Production projects with PROJECT-DEFINITION present will still get
-      # the full enforcement -- the flag is a no-op when the file exists.
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:branch --project-root "{{.USER_WORKING_DIR}}" --allow-missing-project-definition
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:branch --project-root "{{.USER_WORKING_DIR}}" --allow-missing-project-definition'
 
   routing:
     desc: "Operator coding sub-agent model routing gate (#1739). Pre-dispatch (default): fails when a dispatched worker role has no decision in .deft/routing.local.json. Pass --advise for the non-blocking session-start disclosure; --roles a,b to widen the gated set; --provider to override the runtime."
@@ -145,7 +141,7 @@ tasks:
     desc: "Pre-`start_agent` cache-freshness gate (#1127). Refuses implementation dispatch when the triage cache is stale, missing, or the target issue's latest decision is not `accept`. Subscription-aware via plan.policy.triageScope[] (D12 / #1131). Flags: --for-issue N / --max-age-hours N / --allow-stale / --repo OWNER/NAME / --allow-missing-bootstrap (consumed by the framework's own `task check` so a fresh checkout passes -- consumers leave it OFF)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
     # because the gate forwards user-facing flags via {{.CLI_ARGS}}
     # (--for-issue / --max-age-hours / --allow-stale / --repo) that
@@ -155,8 +151,9 @@ tasks:
     # `task triage:bootstrap`; consumer projects leave it off so a
     # missing cache fails their `task check` loudly.
     cmds:
-      # Oracle/fallback (parity): scripts/preflight_cache.py --allow-missing-bootstrap (#1854 s5).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" preflight-cache --project-root "{{.USER_WORKING_DIR}}" --allow-missing-bootstrap {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'preflight-cache --project-root "{{.USER_WORKING_DIR}}" --allow-missing-bootstrap {{.CLI_ARGS}}'
 
   codebase-map-fresh:
     desc: "Drift gate for the generated .planning/codebase/MAP.md projection (#1595 PR4)."
@@ -276,7 +273,7 @@ tasks:
     desc: "Pre-merge re-validation that pending/+active/ count is within plan.policy.wipCap (#1124 / D4 of #1119). Catches stale-branch merges + --force overrides. Default cap is 10 per umbrella #1119 Current Shape v3. The framework's own task check passes --allow-over-cap during landing-day overage; consumer projects MUST NOT pass that flag."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` /
     # `generates:` because the gate forwards user-facing flags via
     # {{.CLI_ARGS}} (--allow-over-cap / --quiet) that go-task's
@@ -288,5 +285,6 @@ tasks:
     # OFF so a stale-branch / --force-merge over-cap state fails their
     # `task check` loudly.
     cmds:
-      # Oracle/fallback (parity): scripts/preflight_wip_cap.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:wip-cap --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:wip-cap --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/templates/agents-entry.md

@@ -206,6 +206,5 @@ Directive product commands use the `/deft:directive:*` namespace (#418 / #1670).
 
 **CLI compatibility:**
 
-- .deft/core/run bootstrap         — CLI setup (terminal users)
-- .deft/core/run spec              — CLI spec generation
+The legacy Python `.deft/core/run` CLI is deprecated and is no longer a load-bearing operator path (#1933 Option 1, deprecate-by-disuse). Use the agent-driven setup skill for first-time setup and project/spec generation; if `deft` or `directive` will not run, read `.deft/core/UPGRADING.md`.
 <!-- /deft:managed-section -->