@deftai/directive-content 0.55.1 → 0.56.0

package/.githooks/pre-commit

@@ -0,0 +1,143 @@
+#!/usr/bin/env sh
+# .githooks/pre-commit -- detection-bound branch-protection gate (#747).
+#
+# 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.
+
+# 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
+    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 $?
+
+# 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 $?
+
+# 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 $?
+fi

package/.githooks/pre-push

@@ -0,0 +1,121 @@
+#!/usr/bin/env sh
+# .githooks/pre-push -- detection-bound branch-protection gate (#747).
+#
+# 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.
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$REPO_ROOT" ]; then
+    echo "deft pre-push: unable to resolve repo root via 'git rev-parse'." >&2
+    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
+    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
+exit $?

package/QUICK-START.md

@@ -4,9 +4,19 @@ You are reading this because a user told you to, or because a stale `AGENTS.md`
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-## Installing Deft from GitHub (fetch-and-run one-liner)
+## Installing Deft (canonical — npm)
 
-! If Deft is **not yet installed** and you were told to "download and install Deft from GitHub into this directory," do NOT build from a source checkout and do NOT guess a path. Run the canonical per-platform fetch-and-run one-liner below. Each downloads the correct release binary from `https://github.com/deftai/directive/releases/latest/download/<asset>`, makes it executable, then runs it headless against the current directory (`--yes --repo-root . --json`).
+! If Deft is **not yet installed** and you were told to "install Deft into this directory," the canonical install is npm (Node ≥ 20 required):
+
+```bash
+npm i -g @deftai/directive
+```
+
+Once installed, run `directive` (or the `deft` alias) from your project directory. Continue with Step 1 below.
+
+### Legacy / offline install (frozen Go installer, #1912)
+
+Node ≥ 20 is required to **run** Deft regardless of how it's installed — the Go installer only deposits files on disk, so install Node first ([nvm](https://github.com/nvm-sh/nvm) / your OS package manager / [nodejs.org](https://nodejs.org/)) and prefer the npm command above. Use the Go installer only for an **offline / air-gapped** deposit or to **migrate a legacy on-disk layout**. Do NOT build from a source checkout and do NOT guess a path. Each one-liner downloads the correct release binary from `releases/latest/download`, makes it executable, then runs it headless.
 
 **macOS (Intel + Apple Silicon):**
 
@@ -26,7 +36,7 @@ curl -fsSL -o /tmp/deft-install https://github.com/deftai/directive/releases/lat
 Invoke-WebRequest -Uri https://github.com/deftai/directive/releases/latest/download/install-windows-amd64.exe -OutFile $env:TEMP\deft-install.exe; & $env:TEMP\deft-install.exe --yes --repo-root . --json
 ```
 
-⊗ Do NOT `go build` from a source checkout or a developer-specific path (e.g. a hardcoded `/Users/<name>/...` clone) — the canonical fetch path above never assumes a local clone. Once the installer finishes, continue with Step 1 below.
+⊗ Do NOT `go build` from a source checkout or a developer-specific path (e.g. a hardcoded `/Users/<name>/...` clone). Once the installer finishes, continue with Step 1 below.
 
 ## Step 1 — Who are you?