@deftai/directive-content 0.59.0 → 0.61.0

package/.githooks/pre-commit

@@ -1,143 +1,25 @@
 #!/usr/bin/env sh
-# .githooks/pre-commit -- detection-bound branch-protection gate (#747).
+# .githooks/pre-commit -- deft CLI gates (#2049 / #747 / #798 / #1620).
 #
-# Activated by `git config core.hooksPath .githooks` -- idempotent setup
-# performed by `task setup` (the directive repo itself) OR by the deft
-# installer, which copies this hook to the consumer root .githooks/ and sets
-# core.hooksPath for vendored consumer projects (#1463). Verify with:
-#
-#     task verify:hooks-installed
-#
-# Pure POSIX-shell so this runs from MSYS / Git for Windows without bash
-# being on PATH. The Python script itself is stdlib-only so it does NOT
-# require `uv` or a virtualenv to be active.
+# Activated by `git config core.hooksPath .githooks` via `task setup` or the
+# deft installer (#1463). Pure POSIX shell; requires `deft` on PATH (no Python).
 
-# Resolve repo root (this hook lives at <core.hooksPath>/pre-commit).
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 if [ -z "$REPO_ROOT" ]; then
     echo "deft pre-commit: unable to resolve repo root via 'git rev-parse'." >&2
     exit 1
 fi
 
-# Layout-aware helper resolution (#1463). In the directive repo the gate
-# scripts live at $REPO_ROOT/scripts/; in a vendored consumer the framework
-# payload (and its scripts/) lives at $REPO_ROOT/.deft/core/ (canonical) or
-# $REPO_ROOT/deft/ (legacy). Because the installer copies this hook to the
-# consumer root .githooks/, it MUST locate the helpers relative to the install
-# root rather than assuming $REPO_ROOT/scripts/. Probe the known layouts and
-# use the first that resolves so the hook works in BOTH layouts.
-SCRIPTS_DIR=""
-for candidate in "$REPO_ROOT/scripts" "$REPO_ROOT/.deft/core/scripts" "$REPO_ROOT/deft/scripts"; do
-    if [ -f "$candidate/preflight_branch.py" ]; then
-        SCRIPTS_DIR="$candidate"
-        break
-    fi
-done
-if [ -z "$SCRIPTS_DIR" ]; then
-    echo "deft pre-commit: unable to locate the deft scripts directory." >&2
-    echo "  Looked in scripts/, .deft/core/scripts/, deft/scripts/ under $REPO_ROOT." >&2
-    echo "  Re-run the deft installer or 'task setup' to wire the hooks correctly." >&2
-    exit 1
-fi
-
-# Resolve a usable Python interpreter (#1668). On Windows `python3` is usually
-# absent (only `python.exe` / the `py` launcher exist), and a bare `python3` on
-# PATH is often the Microsoft Store App-Execution-Alias stub that prints
-# "Python was not found" and exits non-zero. Probe DEFT_PYTHON -> python3 ->
-# python -> the `py -3` launcher, validating each candidate by running
-# `--version`, rejecting the alias stub, AND enforcing the framework's Python
-# 3.11+ floor (#1676 -- framework scripts import `from datetime import UTC`,
-# added in 3.11). PY_PREFIX carries the launcher selector (`-3`) when needed.
-PYTHON_BIN=""
-PY_PREFIX=""
-
-# _deft_try BIN [PREFIX] -- probe a candidate. Succeeds (and sets PYTHON_BIN /
-# PY_PREFIX) only when the candidate runs, is not the Windows alias stub, and
-# reports a Python version >= 3.11.
-_deft_try() {
-    _bin="$1"
-    _pre="${2:-}"
-    command -v "$_bin" >/dev/null 2>&1 || return 1
-    if [ -n "$_pre" ]; then
-        _out=$("$_bin" "$_pre" --version 2>&1) || return 1
-    else
-        _out=$("$_bin" --version 2>&1) || return 1
-    fi
-    case "$_out" in
-        *"Microsoft Store"*|*"was not found"*|*"execution alias"*) return 1 ;;
-    esac
-    case "$_out" in
-        *Python\ [0-9]*) ;;
-        *) return 1 ;;
-    esac
-    # Enforce the 3.11+ floor using POSIX parameter expansion (no sed/awk
-    # dependency). Parse major.minor from the "Python X.Y.Z" banner.
-    _rest=${_out#*Python }
-    _major=${_rest%%.*}
-    _rest=${_rest#*.}
-    _minor=${_rest%%.*}
-    case "$_major" in ''|*[!0-9]*) return 1 ;; esac
-    case "$_minor" in ''|*[!0-9]*) return 1 ;; esac
-    if [ "$_major" -gt 3 ]; then
-        PYTHON_BIN="$_bin"; PY_PREFIX="$_pre"; return 0
-    fi
-    if [ "$_major" -eq 3 ] && [ "$_minor" -ge 11 ]; then
-        PYTHON_BIN="$_bin"; PY_PREFIX="$_pre"; return 0
-    fi
-    return 1
-}
-
-if [ -n "${DEFT_PYTHON:-}" ]; then
-    # DEFT_PYTHON is the explicit override, but still version-checked so the
-    # hooks enforce the same 3.11+ floor as the installer (#1676).
-    _deft_try "$DEFT_PYTHON" || true
-    if [ -z "$PYTHON_BIN" ]; then
-        echo "deft pre-commit: DEFT_PYTHON ($DEFT_PYTHON) is not a usable Python 3.11+ interpreter." >&2
-        echo "  Point DEFT_PYTHON at a Python 3.11+ executable." >&2
-        exit 1
-    fi
-else
-    _deft_try python3 || _deft_try python || _deft_try py "-3" || true
-fi
-
-if [ -z "$PYTHON_BIN" ]; then
-    echo "deft pre-commit: no usable Python 3.11+ interpreter found." >&2
-    echo "  Probed python3, python, and the 'py' launcher (rejecting the Windows" >&2
-    echo "  App-Execution-Alias stub and interpreters older than 3.11)." >&2
-    echo "  Set DEFT_PYTHON=<absolute python 3.11+ path> or install Python 3.11+." >&2
+if ! command -v deft >/dev/null 2>&1; then
+    echo "deft pre-commit: 'deft' not found on PATH." >&2
+    echo "  Install: npm i -g @deftai/directive" >&2
     exit 1
 fi
 
-# deft_py forwards args to the resolved interpreter, preserving quoting for
-# paths that may contain spaces (common on Windows).
-deft_py() {
-    if [ -n "$PY_PREFIX" ]; then
-        "$PYTHON_BIN" "$PY_PREFIX" "$@"
-    else
-        "$PYTHON_BIN" "$@"
-    fi
-}
-
-# Step 1: branch-protection gate (#747).
-deft_py "$SCRIPTS_DIR/preflight_branch.py" --project-root "$REPO_ROOT" || exit $?
+deft verify:branch --project-root "$REPO_ROOT" || exit $?
 
-# Step 2: PS 5.1 non-ASCII round-trip corruption gate (#798). Scans staged
-# files for U+FFFD, CP1252/CP437-as-UTF-8 mojibake, and unexpected BOM.
-# Three-state exit propagates: 0 allowed / 1 corruption blocked with diagnostic
-# / 2 config error. Recurrence chain documented in scripts/verify_encoding.py.
-deft_py "$SCRIPTS_DIR/verify_encoding.py" --project-root "$REPO_ROOT" --staged || exit $?
+deft verify:encoding --staged --project-root "$REPO_ROOT" || exit $?
 
-# Step 3: vBRIEF 0.6 conformance gate (#1620). Scans staged vbrief/**/*.vbrief.json
-# for bare keys that are neither 0.6 spec-core nor x-directive/ / x-vbrief/
-# namespaced. Three-state exit propagates: 0 clean / 1 bare key blocked with
-# diagnostic / 2 config error. Rule body lives in scripts/verify_vbrief_conformance.py.
-# Guarded on a present vbrief/ corpus so a fresh consumer repo that has not yet
-# created the vBRIEF lifecycle folders is not blocked by the gate's intentional
-# exit-2-on-missing-vbrief/ config-error contract. Also guarded on the gate
-# script being present so a vendored consumer whose .deft/core/scripts/ payload
-# predates this gate (stale-payload upgrade window) is not blocked by a missing
-# script; payload-staleness is surfaced separately by `task doctor`.
-if [ -d "$REPO_ROOT/vbrief" ] && [ -f "$SCRIPTS_DIR/verify_vbrief_conformance.py" ]; then
-    deft_py "$SCRIPTS_DIR/verify_vbrief_conformance.py" --project-root "$REPO_ROOT" --staged
-    exit $?
+if [ -d "$REPO_ROOT/vbrief" ]; then
+    deft verify:vbrief-conformance --staged --project-root "$REPO_ROOT" || exit $?
 fi

package/.githooks/pre-push

@@ -1,14 +1,9 @@
 #!/usr/bin/env sh
-# .githooks/pre-push -- detection-bound branch-protection gate (#747).
+# .githooks/pre-push -- refspec-aware default-branch push gate (#2049 / #1019 / #1814).
 #
-# Activated by `git config core.hooksPath .githooks` -- idempotent setup
-# performed by `task setup` (the directive repo itself) OR by the deft
-# installer, which copies this hook to the consumer root .githooks/ and sets
-# core.hooksPath for vendored consumer projects (#1463). Mirrors the
-# pre-commit shape: pre-push defends against the case where a user opted out
-# at commit time (e.g. DEFT_ALLOW_DEFAULT_BRANCH_COMMIT in a single shell)
-# but still tries to push to the default branch in a fresh shell. The same
-# scripts run in both hooks so behavior stays consistent.
+# Pre-push does NOT invoke verify:branch (#747). HEAD-only default-branch
+# protection remains on pre-commit; pre-push relies on preflight-gh for
+# refspec-aware protection (#1814 Option A). Pure POSIX shell; `deft` only.
 
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 if [ -z "$REPO_ROOT" ]; then
@@ -16,106 +11,11 @@ if [ -z "$REPO_ROOT" ]; then
     exit 1
 fi
 
-# Layout-aware helper resolution (#1463) -- see .githooks/pre-commit for the
-# rationale. The installer copies this hook to the consumer root .githooks/,
-# so the gate scripts must be located relative to the install root (own-repo
-# scripts/, canonical .deft/core/scripts/, or legacy deft/scripts/) rather
-# than assuming $REPO_ROOT/scripts/.
-SCRIPTS_DIR=""
-for candidate in "$REPO_ROOT/scripts" "$REPO_ROOT/.deft/core/scripts" "$REPO_ROOT/deft/scripts"; do
-    if [ -f "$candidate/preflight_branch.py" ]; then
-        SCRIPTS_DIR="$candidate"
-        break
-    fi
-done
-if [ -z "$SCRIPTS_DIR" ]; then
-    echo "deft pre-push: unable to locate the deft scripts directory." >&2
-    echo "  Looked in scripts/, .deft/core/scripts/, deft/scripts/ under $REPO_ROOT." >&2
-    echo "  Re-run the deft installer or 'task setup' to wire the hooks correctly." >&2
+if ! command -v deft >/dev/null 2>&1; then
+    echo "deft pre-push: 'deft' not found on PATH." >&2
+    echo "  Install: npm i -g @deftai/directive" >&2
     exit 1
 fi
 
-# Resolve a usable Python interpreter (#1668) -- see .githooks/pre-commit for
-# the rationale. On Windows `python3` is usually absent (only `python.exe` /
-# the `py` launcher exist), and a bare `python3` on PATH is often the Microsoft
-# Store App-Execution-Alias stub. Probe DEFT_PYTHON -> python3 -> python -> the
-# `py -3` launcher, validating each candidate by running `--version`, rejecting
-# the alias stub, AND enforcing the framework's Python 3.11+ floor (#1676).
-PYTHON_BIN=""
-PY_PREFIX=""
-
-# _deft_try BIN [PREFIX] -- probe a candidate. Succeeds (and sets PYTHON_BIN /
-# PY_PREFIX) only when the candidate runs, is not the Windows alias stub, and
-# reports a Python version >= 3.11.
-_deft_try() {
-    _bin="$1"
-    _pre="${2:-}"
-    command -v "$_bin" >/dev/null 2>&1 || return 1
-    if [ -n "$_pre" ]; then
-        _out=$("$_bin" "$_pre" --version 2>&1) || return 1
-    else
-        _out=$("$_bin" --version 2>&1) || return 1
-    fi
-    case "$_out" in
-        *"Microsoft Store"*|*"was not found"*|*"execution alias"*) return 1 ;;
-    esac
-    case "$_out" in
-        *Python\ [0-9]*) ;;
-        *) return 1 ;;
-    esac
-    # Enforce the 3.11+ floor using POSIX parameter expansion (no sed/awk
-    # dependency). Parse major.minor from the "Python X.Y.Z" banner.
-    _rest=${_out#*Python }
-    _major=${_rest%%.*}
-    _rest=${_rest#*.}
-    _minor=${_rest%%.*}
-    case "$_major" in ''|*[!0-9]*) return 1 ;; esac
-    case "$_minor" in ''|*[!0-9]*) return 1 ;; esac
-    if [ "$_major" -gt 3 ]; then
-        PYTHON_BIN="$_bin"; PY_PREFIX="$_pre"; return 0
-    fi
-    if [ "$_major" -eq 3 ] && [ "$_minor" -ge 11 ]; then
-        PYTHON_BIN="$_bin"; PY_PREFIX="$_pre"; return 0
-    fi
-    return 1
-}
-
-if [ -n "${DEFT_PYTHON:-}" ]; then
-    # DEFT_PYTHON is the explicit override, but still version-checked so the
-    # hooks enforce the same 3.11+ floor as the installer (#1676).
-    _deft_try "$DEFT_PYTHON" || true
-    if [ -z "$PYTHON_BIN" ]; then
-        echo "deft pre-push: DEFT_PYTHON ($DEFT_PYTHON) is not a usable Python 3.11+ interpreter." >&2
-        echo "  Point DEFT_PYTHON at a Python 3.11+ executable." >&2
-        exit 1
-    fi
-else
-    _deft_try python3 || _deft_try python || _deft_try py "-3" || true
-fi
-
-if [ -z "$PYTHON_BIN" ]; then
-    echo "deft pre-push: no usable Python 3.11+ interpreter found." >&2
-    echo "  Probed python3, python, and the 'py' launcher (rejecting the Windows" >&2
-    echo "  App-Execution-Alias stub and interpreters older than 3.11)." >&2
-    echo "  Set DEFT_PYTHON=<absolute python 3.11+ path> or install Python 3.11+." >&2
-    exit 1
-fi
-
-# deft_py forwards args to the resolved interpreter, preserving quoting for
-# paths that may contain spaces (common on Windows).
-deft_py() {
-    if [ -n "$PY_PREFIX" ]; then
-        "$PYTHON_BIN" "$PY_PREFIX" "$@"
-    else
-        "$PYTHON_BIN" "$@"
-    fi
-}
-
-deft_py "$SCRIPTS_DIR/preflight_branch.py" --project-root "$REPO_ROOT" || exit $?
-
-# Step 2: destructive-gh-verb gate (#1019). Reads per-ref stdin lines from
-# git pre-push (one line per ref: <local_ref> <local_oid> <remote_ref> <remote_oid>)
-# and refuses pushes touching the default branch (force-push or otherwise).
-# DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1 is the per-shell emergency bypass.
-deft_py "$SCRIPTS_DIR/preflight_gh.py" --pre-push-stdin
+deft preflight-gh --pre-push-stdin
 exit $?

package/Taskfile.yml

@@ -70,9 +70,6 @@ env:
   UV_PROJECT: '{{.TASKFILE_DIR}}'
 
 includes:
-  core:
-    taskfile: ./tasks/core.yml
-    optional: true
   ts:
     taskfile: ./tasks/ts.yml
     optional: true
@@ -141,9 +138,6 @@ includes:
   pr:
     taskfile: ./tasks/pr.yml
     optional: true
-  ci:
-    taskfile: ./tasks/ci.yml
-    optional: true
   policy:
     taskfile: ./tasks/policy.yml
     optional: true
@@ -307,6 +301,24 @@ includes:
   packs:
     taskfile: ./tasks/packs.yml
     optional: true
+  # Maintainer-only Python self-test lanes (#1813 contributor path / #2022
+  # Phase 2). `internal: true` hides `core:*` / `ci:*` from `task -l` and
+  # blocks direct CLI invocation on consumer installs; only
+  # `check:framework-source` below wires them as deps. Consumer `task check`
+  # dispatches to `check:consumer` (TS / deft verbs — no uv/python).
+  core:
+    taskfile: ./tasks/core.yml
+    optional: true
+    internal: true
+  ci:
+    taskfile: ./tasks/ci.yml
+    optional: true
+    internal: true
+  # npm consumer deposits resolve verbs through global `deft` when the vendored
+  # packages/cli/dist/bin.js is absent (#2022 Phase 3).
+  engine:
+    taskfile: ./tasks/engine.yml
+    optional: true
 
 tasks:
   default:
@@ -320,14 +332,16 @@ tasks:
     desc: "Run the context-appropriate pre-commit gate: full framework self-check in this repo, consumer-safe gate from vendored installs (#1519)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - task: verify:_ts-build
+      - task: engine:_ts-build
     cmds:
-      # Oracle/fallback (parity): scripts/_project_context.py --dispatch-task-check (#1854 s5).
-      - node "{{.TASKFILE_DIR}}/packages/cli/dist/bin.js" check --framework-root "{{.TASKFILE_DIR}}" --project-root "{{.USER_WORKING_DIR}}"
+      - task: engine:invoke
+        vars:
+          ENGINE_CMD: 'check --framework-root "{{.TASKFILE_DIR}}" --project-root "{{.USER_WORKING_DIR}}"' 
 
   check:framework-source:
-    desc: "Run all framework source-repo pre-commit checks explicitly (skips @pytest.mark.slow tests via pyproject addopts -- run `task check:slow` for the slow lane, #975)."
+    desc: "Run all framework source-repo pre-commit checks explicitly (skips @pytest.mark.slow tests via pyproject addopts -- run `task check:slow` for the slow lane, #975). Sole wired consumer of maintainer-only core:* / ci:* Python lanes (#2022 Phase 2)."
     deps:
+      # Maintainer-only Python lanes (tasks/core.yml) — not on check:consumer.
       - core:validate
       - core:lint
       - core:test
@@ -359,7 +373,7 @@ tasks:
     desc: "Run the consumer-safe Deft quality gate for vendored installs (#1519)."
     deps:
       - doctor
-      - toolchain:check
+      - toolchain:check-consumer
       - verify:branch
       - verify:cache-fresh
       - verify:wip-cap
@@ -395,12 +409,11 @@ tasks:
     desc: "Deterministic v0.20 strategy output shape gate (#1166 s2). Fails on non-date-prefixed vBRIEFs in lifecycle dirs, missing PROJECT-DEFINITION.vbrief.json, or legacy specification.vbrief.json in user projects."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - task: verify:_ts-build
-        vars:
-          DEFT_ROOT: "{{.TASKFILE_DIR}}"
+      - task: engine:_ts-build
     cmds:
-      # Oracle/fallback (parity): scripts/validate_strategy_output.py (#1854 s3).
-      - node "{{.TASKFILE_DIR}}/packages/cli/dist/bin.js" validate-strategy-output --project-root "{{.USER_WORKING_DIR}}"
+      - task: engine:invoke
+        vars:
+          ENGINE_CMD: 'validate-strategy-output --project-root "{{.USER_WORKING_DIR}}"' 
 
   # Pack-projection drift gate (#1294 / #1283, ADR-001). User-facing alias for
   # `packs:verify-drift`, defined at the root Taskfile so it carries the
@@ -434,40 +447,24 @@ tasks:
   # addopts=` reset overrides the pyproject default of `-m 'not slow'`
   # so the `-m slow` selector here actually picks up the marked tests.
   check:slow:
-    desc: "Run the @pytest.mark.slow test lane (watchdog regression suite excluded from `task check` by default, #975)"
+    desc: "Run the @pytest.mark.slow test lane (watchdog regression suite excluded from `task check` by default, #975). Maintainer-only Python lane — not part of `check:consumer`."
     cmds:
       # `--project` pins uv to the framework root so ancestor pyproject.toml
       # files cannot hijack the resolver via uv's upward walk (#1011).
       - uv --project "{{.TASKFILE_DIR}}" run pytest tests/ -o addopts= -m slow
 
-  test:
-    desc: Run test suite (alias for core:test)
-    cmds:
-      - task: core:test
-  test:coverage:
-    desc: Run tests with coverage (alias for core:test:coverage)
-    cmds:
-      - task: core:test:coverage
-  lint:
-    desc: Lint and type-check Python code (alias for core:lint)
-    cmds:
-      - task: core:lint
-  fmt:
-    desc: Format Python code (alias for core:fmt)
-    cmds:
-      - task: core:fmt
+  # Maintainer-only packaging aliases (#2022 Phase 2). `core:*` is internal;
+  # these root aliases remain callable for release Step 6 (`task build`) and
+  # local maintainer workflows. Not wired into `check:consumer`.
   build:
-    desc: Package framework for distribution (alias for core:build)
+    desc: Package framework for distribution (maintainer-only; alias for core:build)
     cmds:
       - task: core:build
   clean:
-    desc: Clean generated artifacts (alias for core:clean)
+    desc: Clean generated artifacts (maintainer-only; alias for core:clean)
     cmds:
       - task: core:clean
-  validate:
-    desc: Validate all markdown files (alias for core:validate)
-    cmds:
-      - task: core:validate
+
   install:
     desc: Install deft (alias for install:install)
     cmds:
@@ -477,7 +474,7 @@ tasks:
     cmds:
       - task: install:uninstall
   # User-facing upgrade entrypoint (#1061). Aliases the install:upgrade
-  # wrapper that delegates to `run upgrade`. Cited by the doctor's
+  # wrapper that delegates to the native deft-ts install-upgrade handler. Cited by the doctor's
   # failure prose and docs/install-manifest.md as the canonical
   # post-drift repair entrypoint for the AGENTS.md / manifest /
   # .deft-version triple.
@@ -485,10 +482,6 @@ tasks:
     desc: "Upgrade deft framework -- refresh AGENTS.md + write install manifest + regenerate .deft-version (alias for install:upgrade, #1061)"
     cmds:
       - task: install:upgrade
-  stats:
-    desc: Show framework statistics (alias for core:stats)
-    cmds:
-      - task: core:stats
 
   # #1272: canonical doctor surface -- thin shim that forwards to
   # ``.deft/core/run doctor``. The ``run`` CLI owns the diagnostic
@@ -502,16 +495,18 @@ tasks:
   # in ``tasks/framework.yml`` now prints a redaction notice pointing
   # the operator at this surface.
   doctor:
-    desc: "Canonical doctor surface (#1272) -- task doctor [-- --session | --fix | --json | --quiet]. Shim for `.deft/core/run doctor`."
+    desc: "Canonical doctor surface (#1272) -- task doctor [-- --session | --fix | --json | --quiet]. Uses vendored bin.js in source checkouts or global deft on npm consumer deposits (#2022 Phase 3)."
     dir: '{{.USER_WORKING_DIR}}'
-    env:
-      PYTHONUTF8: "1"
     cmds:
-      - uv --project "{{.TASKFILE_DIR}}" run --frozen python "{{.TASKFILE_DIR}}/run" doctor {{.CLI_ARGS}}
+      - task: engine:invoke
+        vars:
+          ENGINE_CMD: 'doctor --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   setup:
     desc: "Idempotent local-dev setup: configure git hooks (#747); detect-and-prompt ghx (#884). Sets core.hooksPath=.githooks so .githooks/pre-commit + .githooks/pre-push run."
     dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - verify:_ts-build
     env:
       PYTHONUTF8: "1"
     cmds:
@@ -568,24 +563,19 @@ tasks:
       # GitHub CLI cache proxy. Default invocation here passes --check so
       # `task setup` never prompts on a clean re-run; operators wanting to
       # opt in run `task setup:ghx` (defined below) which is the
-      # interactive entry point. The script is pure-stdlib so it works
-      # before `uv sync` has run on a fresh worktree; `uv run` is still
-      # the canonical dispatcher to keep the python interpreter consistent
-      # with every other Taskfile-dispatched script. `--project` pins uv
-      # to the framework root so ancestor pyproject.toml files cannot
-      # hijack the resolver via uv's upward walk (#1011).
-      - uv --project "{{.TASKFILE_DIR}}" run python "{{.TASKFILE_DIR}}/scripts/setup_ghx.py" --check
+      # interactive entry point. Native TypeScript handler (#2022 Phase 1).
+      - node "{{.TASKFILE_DIR}}/packages/cli/dist/bin.js" setup:ghx --check
 
   setup:ghx:
     desc: "Consent-gated ghx (brunoborges/ghx) installer (#884) -- task setup:ghx [-- --yes]"
     dir: '{{.USER_WORKING_DIR}}'
-    env:
-      PYTHONUTF8: "1"
+    deps:
+      - verify:_ts-build
     # Per `conventions/task-caching.md` (#574): no `sources:` / `generates:`
     # because the script forwards user-facing flags via {{.CLI_ARGS}}
     # (notably --yes for non-interactive CI / scripted approval).
     cmds:
-      - uv --project "{{.TASKFILE_DIR}}" run python "{{.TASKFILE_DIR}}/scripts/setup_ghx.py" {{.CLI_ARGS}}
+      - node "{{.TASKFILE_DIR}}/packages/cli/dist/bin.js" setup:ghx {{.CLI_ARGS}}
 
   # Release pipeline tasks (#74 + #716 safety hardening, namespace flatten #718).
   #

package/UPGRADING.md

@@ -16,7 +16,7 @@ From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical upgr
 npm i -g @deftai/directive@latest
 ```
 
-Run from any shell with Node ≥ 20. After upgrading, start a new agent session so the refreshed AGENTS.md and skills load from a clean context. Run `directive doctor` to confirm the install state.
+Run from any shell with Node ≥ 20. After upgrading, run `deft update` from your project root to refresh the vendored `.deft/core/` payload and project-root `.githooks/` (#2049), then start a new agent session so the refreshed AGENTS.md and skills load from a clean context. Run `deft doctor` to confirm the install state.
 
 ### One-time migration from the Go installer (legacy → npm)
 
@@ -94,6 +94,7 @@ runs the doctor first gets pointed at this exact two-step before touching `init`
 - **From v0.25.x — manual (breaking).** The deft-cache on-disk layout changed: [From v0.25.x → v0.26.0](#from-v025x--v0260-deft-cache-unified-layer-breaking).
 - **From v0.26.x — auto-handled (interactive).** Run the triage adoption ritual: [From v0.26.x → v0.27](#from-v026x---v027-triage-adoption-via-task-triagewelcome).
 - **From v0.27.x — mostly auto-handled.** Pick up the install manifest and the `deft/` → `.deft/core/` layout: [From v0.27.x → v0.28](#from-v027x---v028-canonical-install-manifest-at-installversion), [From deft/ → .deft/core/](#from-deft---deftcore), and [From drifted AGENTS.md → current install](#from-drifted-agentsmd---current-install-task-upgrade-repair-path-1061).
+- **From v0.60.x — manual (hook refresh).** After #2049, consumer `.githooks/` dispatch through the `deft` CLI only. Run [From v0.60.0 → v0.61.x (refresh project-root git hooks, #2049)](#from-v0600--v061x-refresh-project-root-git-hooks-2049) after every framework upgrade that touches hook templates.
 - **From v0.28–v0.36 (and the final hop to current) — auto-handled.** If still on the Go-installer layout, follow the [One-time migration from the Go installer](#one-time-migration-from-the-go-installer-legacy--npm) above, then `npm i -g @deftai/directive@latest` for all future upgrades.
 
 **Final step for every bucket.** Finish on the canonical upgrade command, then let the doctor confirm you are current:
@@ -102,7 +103,22 @@ runs the doctor first gets pointed at this exact two-step before touching `init`
 npm i -g @deftai/directive@latest
 ```
 
-Then run `directive doctor`: it checks install integrity and tells you whether any further hop is still due. If still on a Go-installer layout, follow the [One-time migration from the Go installer](#one-time-migration-from-the-go-installer-legacy--npm) first.
+Then run `deft update` in your project root (refreshes `.deft/core/` and `.githooks/`), then `directive doctor`: it checks install integrity and tells you whether any further hop is still due. If still on a Go-installer layout, follow the [One-time migration from the Go installer](#one-time-migration-from-the-go-installer-legacy--npm) first.
+
+---
+
+## From v0.60.0 → v0.61.x (refresh project-root git hooks, #2049)
+
+- **Applies when:** your project was on deft v0.60.x (or earlier) with `.githooks/` installed via `deft setup` / the npm deposit path, and hooks still invoke legacy Python scripts (`scripts/preflight_branch.py`, `scripts/preflight_gh.py`, etc.). Detection: `deft verify:hooks-installed` fails with "still dispatches through Python scripts (expected deft CLI only, #2049)" or pre-commit/pre-push errors mentioning missing `scripts/*.py` on Python-free installs.
+- **Safe to auto-run:** Yes. `deft update` from the project root re-deposits the current `.githooks/` templates and refreshes the vendored `.deft/core/` payload. No manual hook editing required when the update completes cleanly.
+- **Restart required:** No for hook wiring — but start a **new agent session** after update so AGENTS.md and skills reflect the refreshed managed section.
+- **Commands:**
+  - `npm i -g @deftai/directive@latest` (upgrade the global CLI/engine)
+  - `deft update` (from project root — refreshes `.deft/core/` + `.githooks/`)
+  - `deft verify:hooks-installed` (confirm pre-commit/pre-push dispatch via `deft verify:branch`, `deft verify:encoding`, `deft preflight-gh`)
+  - `deft doctor` (install integrity + managed-section freshness)
+
+If `deft update` is unavailable (older deposit), fall back to `deft setup` to re-install the hooks path and copy current hook templates.
 
 ---
 
@@ -318,7 +334,7 @@ The relocator does NOT auto-rewrite consumer-owned files (the canonical reason:
 - `AGENTS.md` head/tail (above and below the managed-section markers) -- replace `deft/run` with `.deft/core/run` and `Full guidelines: deft/main.md` with `Full guidelines: .deft/core/main.md`.
 - CI workflow files (`.github/workflows/*.yml`) -- replace any `deft/run <task>` invocations.
 - Project scripts (`scripts/`, `Makefile`, `Taskfile.yml`, dotfiles) that hardcode the legacy path.
-- README / docs / contributor-onboarding prose that points new contributors at `deft/run` for bootstrap.
+- README / docs / contributor-onboarding prose that points new contributors at `directive bootstrap` for first-time setup (replaces legacy `deft/run bootstrap` / `run project` / `run spec` shims).
 
 The advisory grep output is the operator's worklist; treat it as a finite todo. Once every flagged occurrence is either updated to `.deft/core/run` or explicitly acknowledged as legacy-friendly redirect-stub content (e.g. the `skills/deft-{sync,setup,...}/SKILL.md` redirect stubs that intentionally retain `deft/run` per [#411](https://github.com/deftai/directive/issues/411)), commit the changes alongside the relocate. (F1 #1015)
 

package/docs/directive-lifecycle.md

@@ -0,0 +1,73 @@
+# The Directive Lifecycle (Conceptual Overview)
+
+A single-picture mental model of how Deft Directive turns an idea into shipped,
+auditable work — and keeps doing so as the project grows. It is **not** a one-and-done
+pipeline; it is two connected phases that loop.
+
+> **See also**: [getting-started.md](./getting-started.md) | [commands.md](../commands.md) | [strategies/README.md](../strategies/README.md) | [CONCEPTS.md](../../docs/CONCEPTS.md) | [ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
+>
+> The `CONCEPTS.md` / `ARCHITECTURE.md` links resolve in the framework source repo; in an installed `.deft/core/docs/` they are maintainer-side references that may not be present.
+
+![Deft Directive lifecycle: an inception phase (Concept → Strategy Analysis → Specification + Artifacts) feeding a recurring per-session phase (Session Start → Triage/Refine → Slice → Swarm → Review/Fix → Ship) that loops back through new issues and features](./assets/directive-lifecycle-diagram.png)
+
+> This diagram is a **conceptual overview**, not a command reference. The bubble labels are
+> plain-language stages; the [stage → real surface](#stage--real-surface) table below maps
+> each one to the actual strategy, skill, or `task` command that implements it.
+
+## The two phases
+
+### 1. At inception (run once, re-run as needed)
+
+A project starts with a **Concept**. That concept passes through **Strategy Analysis** — an
+iterative loop of *looking* at the terrain and *deep thinking* about the approach — until it
+produces a **Specification + Artifacts** (the project definition and the first proposed scope
+vBRIEFs).
+
+Strategy analysis is deliberately a loop, not a step: you can map, then probe, then discuss,
+then map again before the spec stabilizes. It is also re-entered later "as needed" when a piece
+of work turns out to be big or fuzzy enough to need rethinking rather than just refining.
+
+### 2. Resume (the usual entry, every session)
+
+Once a specification exists, the everyday on-ramp is **Session Start** — the session-start
+ritual answering "what's next?". From there work flows through the queue:
+
+- **Triage + Refine/Rethink** — the queue of candidate work. New **issues** and **features**
+  both enter here. Each item is either sliced forward, or — when it needs more thought —
+  escalated back up to Strategy Analysis (the *rethink* path).
+- **Slice** — break refined scope into independently-grabbable vertical slices.
+- **Swarm** — dispatch parallel agents against the sliced stories.
+- **Review/Fix** — a tight, skill-driven loop that resolves reviewer findings until the work is
+  merge-ready. Review comes **after** the swarm, not before.
+- **Ship** — merge and release.
+
+Shipping is not the end: it **surfaces new issues and features**, which flow back into the
+Triage queue. The specification and artifacts produced at inception also feed proposed scopes
+into the same queue. Every pass is iterative.
+
+## Stage → real surface
+
+The diagram's labels are conceptual. Here is what each one actually corresponds to in the
+framework:
+
+| Diagram label | What it really is |
+|---|---|
+| **Concept** | The initial idea / project framing — entry into [`deft-directive-setup`](../skills/deft-directive-setup/SKILL.md) or a `/deft:change`. |
+| **Look** | Mapping and exploring the terrain — [`strategies/map.md`](../strategies/map.md) (`/deft:run:map`), codebase structure. |
+| **Deep Think** | Adversarial / alignment analysis — [`strategies/probe.md`](../strategies/probe.md), [`strategies/discuss.md`](../strategies/discuss.md), [`strategies/research.md`](../strategies/research.md), and `deft-directive-gh-arch`. |
+| **Strategy Analysis** | The preparatory strategies cycling through the [strategy chaining gate](../strategies/README.md) before spec generation. |
+| **Spec / Specification + Artifacts** | Output of the spec-generating strategies (interview, speckit, …): `vbrief/PROJECT-DEFINITION.vbrief.json` plus dated `vbrief/proposed/` scope vBRIEFs. |
+| **Resume / Session Start** | The session-start ritual — `task session:start` and the `task triage:welcome` "what's next" one-liner. |
+| **Triage + Refine/Rethink** | The triage cache and refinement loop — `task triage:*`, [`deft-directive-triage`](../skills/deft-directive-triage/SKILL.md), [`deft-directive-refinement`](../skills/deft-directive-refinement/SKILL.md). "Rethink" = escalate back to Strategy Analysis. |
+| **Slice** | Vertical-slice decomposition — [`deft-directive-gh-slice`](../skills/deft-directive-gh-slice/SKILL.md) and [`deft-directive-decompose`](../skills/deft-directive-decompose/SKILL.md). |
+| **Swarm** | Parallel local agent orchestration — [`deft-directive-swarm`](../skills/deft-directive-swarm/SKILL.md), `task swarm:*`. |
+| **Review/Fix** | Bot-reviewer response loop — [`deft-directive-review-cycle`](../skills/deft-directive-review-cycle/SKILL.md) and [`deft-directive-pre-pr`](../skills/deft-directive-pre-pr/SKILL.md). |
+| **Ship** | PR merge and release — `task pr:*` and [`deft-directive-release`](../skills/deft-directive-release/SKILL.md). |
+| **Issues / Features** | GitHub issues and feature requests mirrored into `.deft-cache/` and surfaced as triage candidates. |
+
+## Why it loops
+
+The central claim of the picture is that Directive is **reiterative**. Strategy analysis is
+front-loaded but re-entrant. Triage either slices work forward or rethinks it. Review/fix
+cycles until merge-ready. And shipping generates the next round of issues and features. The
+framework is built to be re-entered every session, not walked once.

package/docs/getting-started.md

@@ -2,7 +2,11 @@
 
 Deft Directive is a Taskfile-first framework for AI-assisted software work. It combines agent guidance, deterministic gates, vBRIEF lifecycle metadata, installer/doctor handoff, and cache-backed backlog workflows. This guide walks through installation, preferences, project setup, and the first scope workflow.
 
-> **Note**: This guide is an orientation layer. For current architecture details, see [ARCHITECTURE.md](../../docs/ARCHITECTURE.md); for command behavior, see [commands.md](../commands.md).
+> **Note**: This guide is an orientation layer. For a single-picture mental model of how Directive turns an idea into shipped work, see [the Directive lifecycle](./directive-lifecycle.md); for command behavior, see [commands.md](../commands.md); for current architecture details, see [ARCHITECTURE.md](../../docs/ARCHITECTURE.md).
+
+## The shape of the workflow
+
+Before the mechanics below, it helps to see the whole loop. Directive is two connected phases that repeat: an **inception** phase (Concept → Strategy Analysis → Specification + Artifacts) that feeds a recurring **per-session** phase (Session Start → Triage/Refine → Slice → Swarm → Review/Fix → Ship), where shipping surfaces new issues and features that flow back into the queue. The full picture, with a stage-to-real-command mapping table, lives in [the Directive lifecycle overview](./directive-lifecycle.md).
 
 ## Deft & Directive (naming)