@deftai/directive-content 0.64.0 → 0.65.0

package/.githooks/_deft-run.sh

@@ -0,0 +1,14 @@
+# Shared deft CLI resolver for .githooks/* (#2067).
+# REPO_ROOT must be set before sourcing.
+
+run_deft() {
+    if command -v deft >/dev/null 2>&1; then
+        deft "$@"
+    elif [ -f "$REPO_ROOT/packages/cli/dist/bin.js" ]; then
+        node "$REPO_ROOT/packages/cli/dist/bin.js" "$@"
+    else
+        echo "deft hooks: 'deft' not found on PATH and no local CLI at packages/cli/dist/bin.js." >&2
+        echo "  Install: npm i -g @deftai/directive" >&2
+        exit 1
+    fi
+}

package/.githooks/pre-commit

@@ -2,7 +2,8 @@
 # .githooks/pre-commit -- deft CLI gates (#2049 / #747 / #798 / #1620).
 #
 # Activated by `git config core.hooksPath .githooks` via `task setup` or the
-# deft installer (#1463). Pure POSIX shell; requires `deft` on PATH (no Python).
+# deft installer (#1463). Pure POSIX shell; prefers global `deft` on PATH,
+# falls back to local packages/cli/dist/bin.js in the maintainer monorepo (#2067).
 
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 if [ -z "$REPO_ROOT" ]; then
@@ -10,16 +11,12 @@ if [ -z "$REPO_ROOT" ]; then
     exit 1
 fi
 
-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
+. "$REPO_ROOT/.githooks/_deft-run.sh"
 
-deft verify:branch --project-root "$REPO_ROOT" || exit $?
+run_deft verify:branch --project-root "$REPO_ROOT" || exit $?
 
-deft verify:encoding --staged --project-root "$REPO_ROOT" || exit $?
+run_deft verify:encoding --staged --project-root "$REPO_ROOT" || exit $?
 
 if [ -d "$REPO_ROOT/vbrief" ]; then
-    deft verify:vbrief-conformance --staged --project-root "$REPO_ROOT" || exit $?
+    run_deft verify:vbrief-conformance --staged --project-root "$REPO_ROOT" || exit $?
 fi

package/.githooks/pre-push

@@ -3,7 +3,8 @@
 #
 # 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.
+# refspec-aware protection (#1814 Option A). Pure POSIX shell; prefers global
+# `deft` on PATH, falls back to local packages/cli/dist/bin.js (#2067).
 
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 if [ -z "$REPO_ROOT" ]; then
@@ -11,11 +12,7 @@ if [ -z "$REPO_ROOT" ]; then
     exit 1
 fi
 
-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
+. "$REPO_ROOT/.githooks/_deft-run.sh"
 
-deft preflight-gh --pre-push-stdin
+run_deft preflight-gh --pre-push-stdin
 exit $?

package/Taskfile.yml

@@ -346,6 +346,7 @@ tasks:
       - verify:links
       - verify:rule-ownership
       - verify:content-manifest
+      - verify:contract-drift
       - verify:cursor-tier1
       - verify:go-freeze
       - verify:bridge-drift

package/UPGRADING.md

@@ -42,6 +42,32 @@ From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical cons
 
 Start a **new agent session** after steps 2–3 so the refreshed AGENTS.md and skills load from a clean context.
 
+## Public contract layer — `@deftai/directive-types` (#1799)
+
+Downstream TypeScript projects can import the canonical vBRIEF/policy contract instead of hand-mirroring JSON shapes:
+
+```typescript
+import type { VBriefDocument, PlanPolicy, Status } from "@deftai/directive-types";
+```
+
+JSON Schema for non-TS consumers ships from the same package:
+
+```json
+{
+  "$schema": "https://vbrief.dev/schemas/vbrief-core-0.6.schema.json"
+}
+```
+
+Or import the artifact directly:
+
+```javascript
+import schema from "@deftai/directive-types/schemas/vbrief-core-0.6.schema.json" assert { type: "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 `vbrief/schemas/`. When in doubt, treat the directive repo canonical file as authoritative and refresh mirrors with `deft update` (install) or `@deftai/directive-types` (npm).
+
 ### `deft migrate` vs pre-v0.20 document-model migration
 
 These commands are unrelated — do not confuse them:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "type": "module",
   "files": [

package/tasks/verify.yml

@@ -45,6 +45,13 @@ tasks:
     cmds:
       - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-content-manifest --project-root "{{.DEFT_ROOT}}"
 
+  contract-drift:
+    desc: "Drift gate for the public contract layer (#1799). Asserts packages/types/schemas/vbrief-core-0.6.schema.json matches content/vbrief/schemas/vbrief-core.schema.json and that @deftai/directive-types Status/version constants align with the schema. Three-state exit (0 clean / 1 drift / 2 config error)."
+    deps:
+      - _ts-build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-contract-drift --project-root "{{.DEFT_ROOT}}"
+
   cursor-tier1:
     desc: "Framework-source content gate (#1877): assert Cursor (cursor-composer / cursor-cloud-agent, Task-tool primitive) is enumerated as a Tier-1 descriptor in the swarm Phase 3 capability matrix AND the review-cycle monitoring tier table. Fails when a doc edit drops the Cursor descriptor and silently re-opens the Tier-3 blocking-poll misclassification. Three-state exit (0 clean / 1 missing marker / 2 config error)."
     deps:

package/templates/agents-entry.md

@@ -65,7 +65,7 @@ Check what exists before doing anything else:
 `deft doctor` remains the install-integrity + toolchain + AGENTS.md managed-section freshness probe (#1308). When the managed-section is stale, the doctor points the operator at `deft agents:refresh` to regenerate AGENTS.md from `templates/agents-entry.md`. The canonical `scripts/doctor.py` (single owner post #1335/#1336) also detects payload staleness from the `<install>/VERSION` manifest and, when behind, emits the canonical upgrade command `npm i -g @deftai/directive@latest` (#1339 / #1409 / #1912).
 
 **Canonical bootstrap / update path:** Install and upgrade via npm: `npm i -g @deftai/directive` (install) or `npm i -g @deftai/directive@latest` (upgrade). Node ≥ 20 is required to run Deft (the live gates run on the TypeScript engine). On a machine without Node, install Node first, then use npm — the frozen legacy Go installer (GitHub Releases) is only a legacy/offline + layout-migration bridge (#1912), not a Node-free path. Legacy `deft upgrade` / `run upgrade` are metadata-only acknowledgment and `deft relocate -- --confirm` is back-compat only; git-clone / submodule / legacy doctor surfaces are de-emphasized in UPGRADING.md / README / skills. Agent example: after installing, start your session; `deft doctor` tells you the exact state.
-`deft triage:welcome` emits the triage one-liner and, when state is incomplete, nudges the operator at `deft triage:welcome --onboard` (#1143). Default mode is non-interactive; the `--onboard` flag runs the 6-phase interactive ritual.
+`deft triage:welcome` emits the triage one-liner and, when state is incomplete, nudges the operator at `deft triage:welcome --onboard` (#1143). Default mode is non-interactive; the `--onboard` flag runs the 6-phase interactive ritual. D2's 4-hour suppression window governs repeat emission during session start; the canonical key compares structured fields from the latest `vbrief/.eval/summary-history.jsonl` record: `cache_empty`, `untriaged`, `stale_defer`, `in_flight`, `in_flight_filesystem`, `in_flight_cache_scoped`, `triage_scope_configured`, `wip_count`, `wip_cap`, `repos`, `scope_drift`, and `reconcilable` (#1279). Re-emission within the window occurs when any key field changes, including when the `[triage:scope]` discrepancy line appears or resolves.
 
 ## Resume nudge (conditional, #1269)