@deftai/directive-content 0.59.0 → 0.61.0

package/scm/github.md

@@ -214,9 +214,42 @@ 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`
+
+## Local git hooks (#747 / #2049)
+
+Project-root `.githooks/` enforce branch policy and encoding gates through the **`deft` CLI only** — no Python `scripts/*.py` dispatch (#2049). Hooks are installed idempotently via `deft setup` (`git config core.hooksPath .githooks`).
+
+| Hook | Dispatches | Purpose |
+|------|------------|---------|
+| `pre-commit` | `deft verify:branch`, `deft verify:encoding`, `deft verify:vbrief-conformance` (when `vbrief/` exists) | Default-branch commit refusal (#747), encoding gate (#798), staged vBRIEF conformance (#1620) |
+| `pre-push` | `deft preflight-gh --pre-push-stdin` | Refspec-aware default-branch push refusal + destructive gh verb gate (#1019) |
+
+- ! Verify wiring after install or framework upgrade: `deft verify:hooks-installed` (also wired into `deft check`).
+- ! After upgrading the framework payload, run `deft update` from the project root to refresh `.githooks/` to the current TS-native templates (#2049). Stale hooks that still invoke `python scripts/preflight_branch.py` or other legacy paths fail `deft verify:hooks-installed`.
+- ~ Recovery when hooks are stale or broken: `deft setup` (re-installs hooks path) or `deft update` (refreshes hook files from the deposited payload).
+
 ## 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:
+A detection-bound gate (`deft preflight-gh`) refuses three classes of destructive surface before they execute, complementing the #747 branch-protection gate which already refuses commits to the default branch:
 
 - `delete_repo` -- `gh repo delete <owner/repo>` and `gh api -X DELETE repos/<owner>/<repo>[/...]`. Irreversible.
 - `force_push_default` -- `git push --force` / `--force-with-lease` / `+refspec` targeting `master` or `main`.
@@ -224,9 +257,9 @@ A detection-bound gate (`scripts/preflight_gh.py`) refuses three classes of dest
 
 Three enforcement surfaces back the gate:
 
-1. `.githooks/pre-push` invokes `preflight_gh.py --pre-push-stdin` after the #747 branch gate, refusing any push that touches the default branch (force-push or otherwise). Install via `task setup` (idempotent `git config core.hooksPath .githooks`); verify via `task verify:hooks-installed`.
-2. `task verify:destructive-gh-verbs` is wired into the `task check` aggregate. It runs `preflight_gh.py --self-test`, which drives a built-in fixture table through the classifier so a future edit that introduces a false negative / false positive fails CI immediately.
-3. Agent pre-execution callers can invoke `python scripts/preflight_gh.py --command "<full command>"` to classify a candidate verb before it executes. Three-state exit (0 allowed / 1 destructive refused / 2 config error) mirrors `scripts/preflight_branch.py`.
+1. `.githooks/pre-push` invokes `deft preflight-gh --pre-push-stdin` after the #747 branch gate (on pre-commit), refusing any push that touches the default branch (force-push or otherwise). Install via `deft setup` (idempotent `git config core.hooksPath .githooks`); verify via `deft verify:hooks-installed`.
+2. `deft verify:destructive-gh-verbs` (or `task verify:destructive-gh-verbs` in framework source repos) is wired into the `deft check` aggregate. It runs `deft preflight-gh --self-test`, which drives a built-in fixture table through the classifier so a future edit that introduces a false negative / false positive fails CI immediately.
+3. Agent pre-execution callers can invoke `deft preflight-gh --command "<full command>"` to classify a candidate verb before it executes. Three-state exit (0 allowed / 1 destructive refused / 2 config error) mirrors `deft verify:branch`.
 
 **Override paths:**
 
@@ -234,8 +267,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/skills/deft-directive-setup/SKILL.md

@@ -12,6 +12,12 @@ description: >-
 <!-- Regenerate with: task packs:render -->
 <!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
 
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
 # Deft Directive Setup
 
 Agent-driven alternative to `.deft/core/run bootstrap && .deft/core/run project && .deft/core/run spec`.
@@ -497,7 +503,7 @@ omit = [
 
 ## Phase 3 — Specification
 
-**Goal:** Generate an implementable spec using the strategy chosen in Phase 2, producing a `specification.vbrief.json` draft for human approval before downstream generation.
+**Goal:** Generate an implementable spec using the strategy chosen in Phase 2, producing scope vBRIEFs in `vbrief/proposed/` and PROJECT-DEFINITION narratives for human approval — greenfield v0.20 does not create `specification.vbrief.json`.
 
 ! **Path Resolution Anchor**: Same rule as Phase 2 -- resolve ALL paths relative to the user's pwd at skill entry, never relative to the skill file, AGENTS.md, or any framework directory.
 
@@ -656,24 +662,27 @@ Per [strategies/interview.md](../../strategies/interview.md#interview-rules-shar
 
 ⊗ Drop the user at the end of Phase 3 with scope vBRIEFs in `vbrief/proposed/` and no forward pointer to the bridge. Without this section the user discovers the gap at runtime when the swarm Phase 0 Step 1 preflight rejects every candidate (`Invalid transition: 'activate' requires file in pending/`), as in the originating 2026-05-10 first-session consumer tic-tac-toe swarm (issue #1025).
 
-### End-of-Phase-3 Export Prompt and Render Gate
+### End-of-Phase-3 Export Prompt (project:export-spec)
 
-! After the human approval gate on `specification.vbrief.json` narratives but BEFORE handing off to `deft-directive-build` (or advancing speckit Phase 3 → Phase 4), ask the user whether to generate human-readable exports. This replaces the invisible skip-if-absent behavior of `task check` (#398) and closes the greenfield gap (#433). This is also the Phase 3 → Phase 4 transition gate required by [strategies/speckit.md Post-Phase 3 Transition Gate](../../strategies/speckit.md#post-phase-3-transition-gate-render-for-review) (#432).
+! After scope vBRIEFs are written to `vbrief/proposed/` and PROJECT-DEFINITION is populated, but BEFORE handing off to `deft-directive-build` (or advancing speckit Phase 3 → Phase 4), ask the user whether to generate human-readable exports. Greenfield v0.20 projects export via `task project:export-spec` (not legacy `task spec:render`). This replaces the invisible skip-if-absent behavior of `task check` (#398), closes the greenfield gap (#433), and is the Phase 3 → Phase 4 transition gate required by [strategies/speckit.md Post-Phase 3 Transition Gate](../../strategies/speckit.md#post-phase-3-transition-gate-export-for-review) (#432 / #2013).
 
-1. ! Prompt: "Your `specification.vbrief.json` is approved. Generate `SPECIFICATION.md` and/or `PRD.md` now? (recommended for stakeholder review)"
-   1. Yes — render both
-   2. `SPECIFICATION.md` only
+1. ! Prompt: "Your scope vBRIEFs are ready. Generate a stakeholder-facing spec export and/or `PRD.md` now? (recommended for stakeholder review)"
+   1. Yes — export spec (+ PRD if selected)
+   2. Spec export only (`SPECIFICATION.md`)
    3. `PRD.md` only
-   4. Skip — I’ll render later with `task spec:render` / `task prd:render`
-2. ! Run the selected render command(s):
-   - `task spec:render` → writes `SPECIFICATION.md`
-   - `task prd:render` → writes `PRD.md`
-3. ! If the user picked a speckit-strategy project: `task spec:render` is **mandatory** at this boundary — invoke it even if the user declined the prompt, because speckit Phase 3 → Phase 4 is gated on `SPECIFICATION.md` existing and matching the current vBRIEF hash.
-4. ! Confirm to the user which files were written and remind them that direct edits to `SPECIFICATION.md` / `PRD.md` are overwritten on the next render — edit `specification.vbrief.json` instead.
-5. ~ If the user skipped rendering and is NOT on a speckit strategy, no-op and continue.
-
-⊗ Advance a speckit project to Phase 4 without running `task spec:render` at this gate — `SPECIFICATION.md` is required for the Phase 3 transition criterion.
+   4. Skip — I'll export later with `task project:export-spec` / `task prd:render`
+2. ! Run the selected export command(s):
+   - `task project:export-spec` → writes `SPECIFICATION.md` from PROJECT-DEFINITION + lifecycle scopes (greenfield default; stakeholder audience)
+   - `task project:export-spec -- --audience=internal` → same export but includes proposed scopes under `## Scope outlook` (use for setup/speckit internal handoff when proposed scopes need visibility)
+   - `task prd:render` → writes `PRD.md` (optional stakeholder review)
+   - Legacy `task spec:render` — migrated trees only (when `vbrief/specification.vbrief.json` exists); do NOT use on greenfield v0.20 projects
+3. ! If the user picked a speckit-strategy project: export is **mandatory** at this boundary — invoke `task project:export-spec` (with `--audience=internal` when proposed scopes exist) even if the user declined the prompt, because speckit Phase 3 → Phase 4 is gated on **export succeeded** (exit 0), not on `specification.vbrief.json` approval.
+4. ! Confirm to the user which files were written and remind them that direct edits to `SPECIFICATION.md` / `PRD.md` are overwritten on the next export — edit vBRIEF narratives in `vbrief/proposed/` and PROJECT-DEFINITION instead.
+5. ~ If the user skipped export and is NOT on a speckit strategy, no-op and continue.
+
+⊗ Advance a speckit project to Phase 4 without a successful `task project:export-spec` at this gate — export must succeed (exit 0) for the Phase 3 transition criterion.
 ⊗ Silently skip the prompt — greenfield users who never open a PR will miss the exports without it.
+⊗ Invoke legacy `task spec:render` on a greenfield v0.20 project — use `task project:export-spec` instead (#2013).
 
 ### Handoff to deft-directive-build
 

package/strategies/speckit.md

@@ -8,7 +8,7 @@
 
 A spec-driven development workflow inspired by [GitHub's spec-kit](https://github.com/github/spec-kit), with a Phase 4.5 readiness layer for decomposing broad implementation scopes into swarm-safe stories. Fully migrated to v0.20 (phases + stories emitted as date-prefixed vBRIEFs in proposed/; no legacy specification.vbrief.json).
 
-**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Speckit now emits only the canonical v0.20 shape (date-prefixed phase/epic + story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render or spec:render post, seeded lifecycle folders, no legacy specification.vbrief.json). Phase 4/4.5 scopes go to proposed/ (not pending/). See the dedicated ## v0.20 Output Shape section, the Artifacts Summary updated to the contract table, and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).
+**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Speckit now emits only the canonical v0.20 shape (date-prefixed phase/epic + story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render post, seeded lifecycle folders, no legacy specification.vbrief.json). Phase 4/4.5 scopes go to proposed/ (not pending/). Review exports use `task project:export-spec` (gate: export succeeded). See the dedicated ## v0.20 Output Shape section, the Artifacts Summary updated to the contract table, and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
@@ -49,7 +49,7 @@ flowchart LR
     style I fill:#f0abfc,stroke:#a855f7,color:#000
 ```
 
-(See ## v0.20 Output Shape for exact artifact rules, the mandatory `task project:render` / `task spec:render` post calls, and citation of strategies/v0-20-contract.md.)
+(See ## v0.20 Output Shape for exact artifact rules, the mandatory `task project:render` post call and `task project:export-spec` for review exports, and citation of strategies/v0-20-contract.md.)
 
 ---
 
@@ -137,13 +137,13 @@ Add the following narrative keys to the proposed/ vBRIEF `plan.narratives`:
 - ⊗ Write implementation code
 - ⊗ Create `specs/` directories or standalone `plan.md` files -- all content goes in the proposed/ date-prefixed vBRIEF(s)
 
-### Post-Phase 3 Transition Gate: Render for Review
+### Post-Phase 3 Transition Gate: Export for Review
 
-! Phase 3 -> Phase 4 is gated on an explicit render-and-review step, mirroring the Phase 2 approval gate. Complete the steps below **in order** before advancing. [skills/deft-directive-setup/SKILL.md](../skills/deft-directive-setup/SKILL.md) is required to invoke `task spec:render` at this boundary when running speckit interactively; the gate fails silently otherwise (yolo-mode agents used to skip it -- that is what this gate exists to prevent).
+! Phase 3 -> Phase 4 is gated on a successful spec export for human review, mirroring the Phase 2 approval gate. Complete the steps below **in order** before advancing. [skills/deft-directive-setup/SKILL.md](../skills/deft-directive-setup/SKILL.md) is required to invoke `task project:export-spec` at this boundary when running speckit interactively; the gate fails silently otherwise (yolo-mode agents used to skip it -- that is what this gate exists to prevent).
 
-1. ! Run `task spec:render` (or `task project:render`) to (re-)produce derivative views from the proposed/ vBRIEFs + PROJECT-DEFINITION if needed for human review.
-2. ! Confirm any rendered `SPECIFICATION.md` (if emitted as derivative) exists at the project root and contains the `<!-- deft:deprecated-redirect -->` sentinel.
-3. ! The proposed/ vBRIEFs + PROJECT-DEFINITION are the source of truth. Derivatives are read-only exports.
+1. ! Run `task project:export-spec` (use `--audience=internal` when proposed scopes must appear in the `## Scope outlook` section). Legacy migrated trees MAY use `task spec:render` when `vbrief/specification.vbrief.json` exists.
+2. ! Confirm export **succeeded** (command exit 0) and `SPECIFICATION.md` exists at the project root with the greenfield banner (`<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json -->`) or full-spec banner as appropriate.
+3. ! The proposed/ vBRIEFs + PROJECT-DEFINITION are the source of truth. `SPECIFICATION.md` is a read-only export.
 4. ! Human reviewer approves (or requests changes). On approval, proceed to Phase 4.
 
 ### Transition Criteria
@@ -151,7 +151,7 @@ Add the following narrative keys to the proposed/ vBRIEF `plan.narratives`:
 - ! All gates pass (or exceptions documented)
 - ! Every spec requirement maps to a plan element
 - ! Architecture reviewed and approved
-- ! **Phase 3 -> Phase 4 transition criterion:** The proposed/ date-prefixed vBRIEF(s) + PROJECT-DEFINITION represent the approved spec (agents MUST NOT advance to Phase 4 without review of the v0.20 artifacts).
+- ! **Phase 3 -> Phase 4 transition criterion:** `task project:export-spec` succeeded (exit 0) AND the proposed/ date-prefixed vBRIEF(s) + PROJECT-DEFINITION represent the approved spec (agents MUST NOT advance to Phase 4 without review of the v0.20 artifacts).
 
 ---
 
@@ -353,7 +353,7 @@ The readiness report lists ready stories, blocked stories, decomposition-needed
 | 1. Principles | `vbrief/PROJECT-DEFINITION.vbrief.json` | Governing rules (Principles narrative) |
 | 2. Specify | date-prefixed in `vbrief/proposed/` | WHAT/WHY narratives (v0.20) |
 | 3. Plan | date-prefixed in `vbrief/proposed/` | HOW narratives (enriches Phase 2; v0.20) |
-| 3b. Render (derivative) | `SPECIFICATION.md` (via `task spec:render`, sentinel only) | Read-only human review export (optional) |
+| 3b. Export (review) | `SPECIFICATION.md` (via `task project:export-spec`) | Read-only human review export (optional; gate requires export succeeded for Phase 3→4) |
 | 3c. Render PRD (derivative) | `PRD.md` (via `task prd:render`, sentinel only) | Optional stakeholder-review export |
 | 4. Tasks | `./vbrief/proposed/YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` (one per IP/epic) | Phase/epic scope vBRIEFs (v0.20: proposed/) drive roadmap/project render + decomposition |
 | 4.5. Story decomposition | Child story vBRIEFs with `plan.metadata.swarm` in proposed/ | Swarm-ready executable units (v0.20) |
@@ -371,7 +371,7 @@ project/
 │   │   └── YYYY-MM-DD-ip001-....vbrief.json
 │   ├── plan.vbrief.json                # Phase 4b: session todos (planRef to active scope)
 │   └── pending/ active/ etc.           # Lifecycle (seeded empty or with promoted)
-├── SPECIFICATION.md                    # Optional derivative (task spec:render; sentinel only)
+├── SPECIFICATION.md                    # Optional export (task project:export-spec)
 ├── PRD.md                              # Optional derivative (task prd:render; sentinel only)
 └── src/                                # Phase 5
 ```
@@ -386,12 +386,12 @@ This strategy has been migrated to the full v0.20 output shape so speckit-genera
 
 - ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.
 - ! Emit all scope items (principles context, spec phases/stories, implementation phases/epics) exclusively as date-prefixed scope vBRIEFs in `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (or the ipNNN convention for phases per vbrief.md). For speckit, phases use `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` in proposed/; stories from Phase 4.5 also in proposed/. Decompose plans into focused, buildable vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.
-- ! After the proposed/ vBRIEFs are written (or at Phase 3/4 boundaries), invoke `task project:render` (or `task spec:render` post) from the repo root to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry derived from the lifecycle folders).
+- ! After the proposed/ vBRIEFs are written (or at Phase 3/4 boundaries), invoke `task project:render` from the repo root to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry derived from the lifecycle folders). For human review at Phase 3→4, invoke `task project:export-spec` (or `--audience=internal` when proposed scopes must appear in `## Scope outlook`).
 - ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).
-- ~ `SPECIFICATION.md` / `PRD.md` at the project root, if produced at all, must be only read-only derivatives that include the v0.20 deprecated-redirect sentinel. The source of truth is the vbrief/ lifecycle (proposed/ phases + stories) + PROJECT-DEFINITION.
+- ~ `SPECIFICATION.md` / `PRD.md` at the project root, if produced at all, are read-only exports from `task project:export-spec` / `task prd:render`. The source of truth is the vbrief/ lifecycle (proposed/ phases + stories) + PROJECT-DEFINITION. Legacy `task spec:render` applies only to migrated trees with `vbrief/specification.vbrief.json`.
 - ! Before writing any proposed/ vBRIEFs or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).
 - ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF (a1: date-prefixed stories in proposed/ + deterministic gate; a2: speckit story-level in proposed/ not only pending phases; a3: no legacy specification.vbrief.json) and the 1166 decomposition.
-- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row (speckit: Yes lifecycle; Yes PROJECT-DEFINITION Phase 1+; proposed/ (phases + stories date-prefixed); Never specification.vbrief.json; Omit (use task spec:render post) for SPEC/PRD).
+- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row (speckit: Yes lifecycle; Yes PROJECT-DEFINITION Phase 1+; proposed/ (phases + stories date-prefixed); Never specification.vbrief.json; `task project:export-spec` for SPEC export).
 
 ---
 
@@ -404,7 +404,7 @@ This strategy has been migrated to the full v0.20 output shape so speckit-genera
 | `vbrief/PROJECT-DEFINITION.vbrief.json` | Principles + full items registry | Speckit Phase 1 + `task project:render` |
 | `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` + `YYYY-MM-DD-ipNNN-*.vbrief.json` | All spec (WHAT/WHY/HOW) + phases/epics/stories (date-prefixed; per v0.20 contract and vbrief.md speckit convention) | Speckit Phases 2-4.5 |
 | `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Speckit |
-| (optional derivative) `SPECIFICATION.md` / `PRD.md` | Human-readable (includes deprecated-redirect sentinel only) | `task spec:render` / `task prd:render` (post) |
+| (optional export) `SPECIFICATION.md` / `PRD.md` | Human-readable spec export | `task project:export-spec` / `task prd:render` |
 | `vbrief/plan.vbrief.json` | Session-level tactical plan (planRef to active) | Speckit (internal) |
 
 **Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**

package/strategies/v0-20-contract.md

@@ -76,6 +76,17 @@ All five lifecycle folders MUST be present (even if empty). This is the cutover
 - ⊗ No v0.20 strategy may create or dual-write `vbrief/specification.vbrief.json` alongside the new model artifacts.
 - Existing legacy files are handled only by `task migrate:vbrief` (which ingests them into scope vBRIEFs + PROJECT-DEFINITION and leaves a redirect stub at root if needed).
 
+### Greenfield spec export (#2013 / #1502)
+
+Greenfield projects (no `vbrief/specification.vbrief.json`) export stakeholder-facing spec text via `task project:export-spec`:
+
+- ! Source of truth: `vbrief/PROJECT-DEFINITION.vbrief.json` product narratives + lifecycle scope bodies (never the legacy singular spec file).
+- ! Default audience is **stakeholder** — proposed scopes are omitted; only pending/active/completed scopes appear under `## Scope outlook`.
+- ! Internal handoff (setup Phase 3, speckit Phase 3→4 when proposed scopes must be visible) uses `task project:export-spec -- --audience=internal`, which adds `### Not yet accepted (proposed)` under `## Scope outlook` with a fixed disclaimer that proposed scopes are ideas, not approved backlog.
+- ! Phase 3→4 transition gate: **export succeeded** (exit 0), not spec-file `approved` status — PROJECT-DEFINITION has no spec-approval lifecycle on greenfield trees.
+- ~ Legacy migrated trees with `vbrief/specification.vbrief.json` MAY continue using `task spec:render` until fully cut over.
+- ⊗ Invoke `task spec:render` on a greenfield tree that lacks `specification.vbrief.json` — use `task project:export-spec` instead.
+
 ### plan.vbrief.json and continue.vbrief.json
 - Session/tactical state files are permitted at vbrief/ root (they carry `planRef` links). They are not part of the "spec output" contract but strategies that maintain chaining state (e.g. interview) update them per their own rules.
 
@@ -85,7 +96,7 @@ All five lifecycle folders MUST be present (even if empty). This is the cutover
 |--------------|------------------|-------------------------------|-------------------------------|-----------------------------------------|-----------------------------|----------------------------------------|
 | interview    | spec-generating  | Yes                           | Yes (narratives + items)      | proposed/YYYY-MM-DD-*.vbrief.json only  | Never (post-migration)      | Omit or deprecation redirect only      |
 | yolo         | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.vbrief.json only  | Never                       | Omit or deprecation redirect only      |
-| speckit      | spec-generating  | Yes                           | Yes (Phase 1+)                | proposed/YYYY-MM-DD-*.vbrief.json only (phases + stories) | Never             | Omit (use task spec:render post)       |
+| speckit      | spec-generating  | Yes                           | Yes (Phase 1+)                | proposed/YYYY-MM-DD-*.vbrief.json only (phases + stories) | Never             | Omit or `task project:export-spec` (legacy: `task spec:render` on migrated trees) |
 | rapid        | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.vbrief.json only  | Never                       | Omit or deprecation redirect only      |
 | enterprise   | spec-generating  | Yes                           | Yes                           | proposed/YYYY-MM-DD-*.vbrief.json only  | Never                       | Omit or deprecation redirect only      |
 | preparatory (research, discuss, map, etc.) | preparatory | Yes (if first touch)         | No (unless also spec path)    | proposed/YYYY-MM-DD-*.vbrief.json (context/decision vBRIEFs) | N/A                    | N/A (preparatory only)                 |

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}}