@deftai/directive-content 0.59.0 → 0.60.0

package/.githooks/pre-push

@@ -1,14 +1,17 @@
 #!/usr/bin/env sh
-# .githooks/pre-push -- detection-bound branch-protection gate (#747).
+# .githooks/pre-push -- refspec-aware default-branch push gate (#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.
+# core.hooksPath for vendored consumer projects (#1463).
+#
+# Pre-push does NOT invoke preflight_branch.py (#747 gate #1). That gate
+# inspects HEAD only, so benign operations checked out on the default branch
+# (deleting a merged feature branch, pushing a non-default ref) false-positive
+# before the refspec-aware gate can approve them (#1814 Option A). HEAD-only
+# default-branch protection remains on pre-commit; pre-push relies on
+# preflight_gh --pre-push-stdin (gate #2) for refspec-aware protection.
 
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 if [ -z "$REPO_ROOT" ]; then
@@ -111,9 +114,7 @@ deft_py() {
     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
+# Refspec-aware default-branch push 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.

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

@@ -318,7 +318,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)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.59.0",
-  "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/, scripts/) the deposit wires. Refs #11, #1669, #1967.",
+  "version": "0.60.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": [
     "**/*",
@@ -17,7 +17,7 @@
     "provenance": true
   },
   "scripts": {
-    "prepack": "node --input-type=module -e \"import{cpSync,existsSync,readdirSync,rmSync}from'node:fs';import{dirname,join}from'node:path';import{fileURLToPath}from'node:url';const pkg=dirname(fileURLToPath(import.meta.url));const root=join(pkg,'..','..');const keep=(s)=>!s.includes('__pycache__')&&!s.endsWith('.pyc');const src=join(root,'content');for(const name of readdirSync(src)){const from=join(src,name);const to=join(pkg,name);if(existsSync(to))rmSync(to,{recursive:true,force:true});cpSync(from,to,{recursive:true,filter:keep});}for(const name of ['.githooks','Taskfile.yml','tasks','scripts']){const from=join(root,name);if(!existsSync(from))continue;const to=join(pkg,name);if(existsSync(to))rmSync(to,{recursive:true,force:true});cpSync(from,to,{recursive:true,filter:keep});}\"",
+    "prepack": "node --input-type=module -e \"import{cpSync,existsSync,readdirSync,rmSync}from'node:fs';import{dirname,join}from'node:path';import{fileURLToPath}from'node:url';const pkg=dirname(fileURLToPath(import.meta.url));const root=join(pkg,'..','..');const keep=(s)=>!s.includes('__pycache__')&&!s.endsWith('.pyc')&&!s.endsWith('.py');const src=join(root,'content');for(const name of readdirSync(src)){const from=join(src,name);const to=join(pkg,name);if(existsSync(to))rmSync(to,{recursive:true,force:true});cpSync(from,to,{recursive:true,filter:keep});}for(const name of ['.githooks','Taskfile.yml','tasks']){const from=join(root,name);if(!existsSync(from))continue;const to=join(pkg,name);if(existsSync(to))rmSync(to,{recursive:true,force:true});cpSync(from,to,{recursive:true,filter:keep});}\"",
     "postpack": "node --input-type=module -e \"import{readdirSync,rmSync}from'node:fs';import{dirname,join}from'node:path';import{fileURLToPath}from'node:url';const pkg=dirname(fileURLToPath(import.meta.url));for(const name of readdirSync(pkg)){if(name==='package.json')continue;rmSync(join(pkg,name),{recursive:true,force:true});}\""
   }
 }