@deftai/directive-content 0.61.1 → 0.62.0

package/.agents/skills/deft-directive-decompose/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: deft-directive-decompose
+description: >-
+  Convert phase/epic scope vBRIEFs into swarm-ready story vBRIEFs before swarm
+  allocation. Use when the operator asks to decompose, split stories, or assess
+  swarm readiness.
+---
+
+Read and follow: skills/deft-directive-decompose/SKILL.md

package/.agents/skills/deft-directive-probe/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: deft-directive-probe
+description: >-
+  Adversarial one-question-per-turn plan stress-testing before vBRIEF or plan
+  artifacts. Use when the operator asks to run probe or stress-test a plan.
+---
+
+Read and follow: skills/deft-directive-probe/SKILL.md

package/QUICK-START.md

@@ -113,31 +113,28 @@ Pick exactly one case from Step 2 and follow its instructions. Do not mix cases.
 
 ### Case H — Pre-cutover migration (SPECIFICATION.md / PROJECT.md without sentinel)
 
-1. Tell the user: "Your project uses the pre-v0.20 document model. I can run `task migrate:vbrief` to upgrade, which replaces SPECIFICATION.md and PROJECT.md with deprecation redirect stubs and creates the `vbrief/` lifecycle folders. First I'll run an environment preflight."
-2. ! Execute the environment preflight from `./skills/deft-directive-setup/SKILL.md` "Pre-Cutover Detection Guard" § Environment Preflight: check (a) `task migrate:vbrief` resolvability, (b) `uv` on PATH, (c) `deft/scripts/migrate_vbrief.py` present. Report each result to the user BEFORE asking for approval. If any check fails, surface the specific fix pointer and stop — do not prompt for approval until preflight passes.
-3. ! If `task migrate:vbrief` is not resolvable from the project root (the consumer `Taskfile.yml` does not yet include `deft/Taskfile.yml`), tell the user the fallback invocation `task -t ./deft/Taskfile.yml migrate:vbrief` will be used instead. See [./main.md](../main.md#publishing-deft-tasks-in-your-project-root) for the recommended include pattern that makes the primary command work from the project root.
-4. ! Only after preflight results have been reported, ask the user: "Preflight passed. Shall I run `task migrate:vbrief` (or the fallback invocation) now?" Wait for explicit user approval (`yes`, `approve`, `confirmed`). ⊗ Run migration on a broad "proceed" or "go ahead".
-5. On approval: run the resolved command (primary `task migrate:vbrief` or the fallback `task -t ./deft/Taskfile.yml migrate:vbrief`) from the project root. For preview (`--dry-run`), dirty-tree bypass (`--force`), and undo (`--rollback`) see the [Migration safety flags](./skills/deft-directive-setup/SKILL.md#migration-safety-flags) subsection.
-6. See [./main.md](../main.md#migrating-from-pre-v020) for the full migration reference (what pre-cutover looks like, what the migrator produces, safety flags) and [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) for the brownfield adoption guide.
-7. After migration completes, re-run Step 2 of this QUICK-START — the project state has changed. Most likely you land in Case G (AGENTS.md still references old paths) or Case J.
-8. When AGENTS.md is refreshed, ! instruct the user: **"Framework updated. Start a new agent session to pick up the changes. The current session has stale context."**
+1. Tell the user: "Your project uses the pre-v0.20 document model. Current npm releases no longer ship in-product `task migrate:vbrief` (#2068). Follow [UPGRADING.md § Frozen pre-v0.20 document-model migration](./UPGRADING.md#frozen-pre-v020-document-model-migration-2068): pin framework **v0.59.0** (frozen Go installer or git tag), install Python 3.11+ and `uv`, run `task migrate:vbrief` once from that payload, then upgrade to current npm."
+2. ! Run `task migrate:preflight` (or `task -t ./.deft/core/Taskfile.yml migrate:preflight`) to confirm pre-cutover state and print the frozen-release guidance. ⊗ Do NOT offer to run `task migrate:vbrief` from the current npm deposit — the migrator is not bundled.
+3. See [./main.md](../main.md#migrating-from-pre-v020) for what pre-cutover looks like and what the migrator produces, and [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) for the brownfield adoption guide.
+4. After migration completes on v0.59.0 and the operator upgrades to current npm, re-run Step 2 of this QUICK-START — the project state has changed. Most likely you land in Case G (AGENTS.md still references old paths) or Case J.
+5. When AGENTS.md is refreshed, ! instruct the user: **"Framework updated. Start a new agent session to pick up the changes. The current session has stale context."**
 
 ### Case G+H — Combined stale AGENTS.md + pre-cutover migration (big-jump, one session)
 
-Reached only via the **Big-jump joint check** in 2b: the managed section in `../AGENTS.md` is stale (Case G) AND pre-v0.20 artifacts are present at `../` (Case H). This is the typical shape of a multi-version "big jump" that crossed both the AGENTS.md managed-section refresh and the pre-v0.20 document-model cutover. Running Case G and Case H as two separate sessions wastes an agent-session round-trip, because `task migrate:vbrief` re-reads filesystem state directly and does NOT depend on the refreshed `AGENTS.md` being in the current agent's context. Both remediations therefore complete safely in **one session**.
+Reached only via the **Big-jump joint check** in 2b: the managed section in `../AGENTS.md` is stale (Case G) AND pre-v0.20 artifacts are present at `../` (Case H). This is the typical shape of a multi-version "big jump" that crossed both the AGENTS.md managed-section refresh and the pre-v0.20 document-model cutover.
 
-! Run the two remediations in this exact order — **AGENTS.md refresh first, migration second** — then emit a **single** restart instruction at the very end:
+! Run the two remediations in this exact order — **AGENTS.md refresh first, frozen migration guidance second** — then emit a **single** restart instruction at the very end:
 
 1. **Refresh AGENTS.md first (Case G work).** Perform Case G steps 1-4 verbatim: identify the managed section, append when the sentinel is absent or byte-replace it when present, and preserve everything outside the managed region. ⊗ Do NOT emit the Case G step-5 restart instruction here — the combined path defers the single restart to step 3.
-2. **Run migration second (Case H work).** Perform Case H steps 1-6 verbatim: run the environment preflight, report each result, ask for explicit approval, and on approval run `task migrate:vbrief` (or the `task -t ./deft/Taskfile.yml migrate:vbrief` fallback) from the project root. ⊗ Do NOT perform Case H step 7 (re-run Step 2) or step 8 (restart): the AGENTS.md refresh is already done in step 1, and the single restart is emitted in step 3. The migration reads filesystem state directly, so refreshing AGENTS.md first does not change its inputs — the ordering is safe.
-3. **Single restart, exactly once.** Only after BOTH the refresh and the migration have completed, ! instruct the user EXACTLY ONCE: **"Framework updated and project migrated. Start a new agent session to pick up the changes. The current session has stale context."** ⊗ Do NOT emit a second restart instruction — the deferred Case G restart and the Case H restart collapse into this one.
+2. **Surface frozen migration path second (Case H work).** Perform Case H steps 1-3 verbatim: explain the v0.59.0 pinned migrator path (#2068), run `task migrate:preflight`, and point at UPGRADING.md. The operator (or a machine with v0.59.0 deposited) runs `task migrate:vbrief` outside the current npm deposit. ⊗ Do NOT perform Case H steps 4-5 until migration has completed on the pinned release and the operator has upgraded to current npm.
+3. **Single restart, exactly once.** Only after BOTH the refresh and the operator-confirmed migration + npm upgrade have completed, ! instruct the user EXACTLY ONCE: **"Framework updated and project migrated. Start a new agent session to pick up the changes. The current session has stale context."** ⊗ Do NOT emit a second restart instruction.
 
-The end state is byte-identical to running Case G and Case H separately: the same managed-section refresh against `./templates/agents-entry.md` and the same `task migrate:vbrief` output (deprecation-redirect stubs plus the five `vbrief/` lifecycle folders). The only thing removed is the wasted intermediate session restart. For the version-by-version context of a big jump, see the [big-jump triage entry point](./UPGRADING.md#big-jump-triage--multi-version-upgrades-start-here) in UPGRADING.md.
+For the version-by-version context of a big jump, see the [big-jump triage entry point](./UPGRADING.md#big-jump-triage--multi-version-upgrades-start-here) in UPGRADING.md.
 
 ### Case I — Partial migration repair
 
-1. Tell the user: "Your project has a partial vBRIEF layout. Missing lifecycle folders: <list the absent ones>. Shall I complete the migration by running `task migrate:vbrief`? It is idempotent and safe to re-run."
-2. On approval, run `task migrate:vbrief` (or fall back to `task -t ./deft/Taskfile.yml migrate:vbrief` if the task is not resolvable from the project root — see [./main.md](../main.md#publishing-deft-tasks-in-your-project-root)). Re-run Step 2 afterwards.
+1. Tell the user: "Your project has a partial vBRIEF layout. Missing lifecycle folders: <list the absent ones>. Complete the layout via the frozen v0.59.0 migrator (see UPGRADING.md § Frozen pre-v0.20 document-model migration) or create the missing folders manually after migrating narratives."
+2. Run `task migrate:preflight` to confirm state. If the operator has v0.59.0 deposited, they may run `task migrate:vbrief` there; otherwise point at the frozen path. Re-run Step 2 afterwards.
 3. If the user declines, point them at [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) §Troubleshooting and stop.
 
 ### Case J — Everything clean

package/Taskfile.yml

@@ -144,6 +144,9 @@ includes:
   framework:
     taskfile: ./tasks/framework.yml
     optional: true
+  umbrella:
+    taskfile: ./tasks/umbrella.yml
+    optional: true
   session:
     taskfile: ./tasks/session.yml
     optional: true

package/UPGRADING.md

@@ -10,24 +10,88 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 ## Canonical upgrade — npm (v0.55.1+)
 
-From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical upgrade command is:
+From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical consumer upgrade path is:
 
-```bash
-npm i -g @deftai/directive@latest
-```
+1. **Upgrade the global engine** (Node ≥ 20):
+
+   ```bash
+   npm i -g @deftai/directive@latest
+   ```
+
+2. **Refresh the project deposit** from your project root:
+
+   ```bash
+   deft update
+   ```
+
+   This re-copies the vendored `.deft/core/` payload and refreshes project-root `.githooks/` (#2049).
+
+3. **Stamp npm provenance (one-time, idempotent):**
 
-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.
+   ```bash
+   deft migrate
+   ```
+
+   Adds `managed_by: npm` to `.deft/core/VERSION` so doctor and future updates recognize the npm channel. Safe to re-run — when already hybrid, migrate is a no-op.
+
+4. **Verify:**
+
+   ```bash
+   deft doctor
+   ```
+
+Start a **new agent session** after steps 2–3 so the refreshed AGENTS.md and skills load from a clean context.
+
+### `deft migrate` vs pre-v0.20 document-model migration
+
+These commands are unrelated — do not confuse them:
+
+| Command | When to use | What it does |
+| --- | --- | --- |
+| `deft migrate` / `directive migrate` | Canonical-vendored `.deft/core/` deposit after npm upgrade (#1941) | Stamps `managed_by: npm` into the install manifest. Idempotent; never downloads payload. |
+| Pre-v0.20 document-model migration | Legacy authoritative `SPECIFICATION.md` / `PROJECT.md` only | **Not shipped on current npm releases (#2068).** Use the [frozen-release path](#frozen-pre-v020-document-model-migration-2068) below. |
+
+### Frozen pre-v0.20 document-model migration (#2068)
+
+Current `@deftai/directive` npm releases no longer ship `task migrate:vbrief` or `scripts/migrate_vbrief.py` on the consumer deposit path (#2022 Phase 3). If your project still uses the pre-v0.20 flat document model (authoritative root `SPECIFICATION.md` / `PROJECT.md` without vBRIEF lifecycle folders), migrate **once** on a pinned release that still bundles the Python migrator, then join the normal npm upgrade path.
+
+**Applies when:** `deft doctor` reports `Pre-cutover: migration needed`, or `task migrate:preflight` exits non-zero with a `document-model` FAIL line.
+
+**Pinned release:** `v0.59.0` (last release before the Python-free npm deposit; includes `scripts/migrate_vbrief.py`).
+
+**Steps:**
+
+1. Install **Python 3.11+** and **[uv](https://docs.astral.sh/uv/)** on the migration machine.
+2. Deposit framework **v0.59.0** using one of:
+   - **Frozen Go installer** at [GitHub Releases tag v0.59.0](https://github.com/deftai/directive/releases/tag/v0.59.0) (layout migration + full source tarball under `.deft/core/`), or
+   - **Git submodule / clone:** `git checkout v0.59.0` in your framework checkout.
+3. From the project root, preview then apply:
+   ```bash
+   task migrate:preflight
+   task migrate:vbrief -- --dry-run
+   task migrate:vbrief
+   ```
+   Fallback when the consumer Taskfile has no deft include: `task -t ./.deft/core/Taskfile.yml migrate:vbrief`.
+4. Regenerate exports once: `task roadmap:render`, `task project:render`, and `task prd:render -- --force` when you maintain a `PRD.md`.
+5. Upgrade to current npm: `npm i -g @deftai/directive@latest`, then `deft update`, `deft migrate`, `deft doctor`.
+6. Start a **new agent session** so refreshed AGENTS.md and skills load from a clean context.
+
+⊗ Run `npm i -g @deftai/directive@latest` / `deft update` on a project that still has authoritative pre-v0.20 root docs — the current deposit cannot run the migrator; follow the frozen path first.
+
+See [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) for what migration produces and how content is preserved.
 
 ### One-time migration from the Go installer (legacy → npm)
 
 If your current install uses the frozen Go installer (`deft-install`), migrate once:
 
 1. Install Node ≥ 20 if not already present.
-2. Run `npm i -g @deftai/directive` to install from npm.
-3. In your project, run `directive agents:refresh` to update AGENTS.md with the npm-based managed section.
-4. Verify with `directive doctor` — the install-integrity check confirms the npm payload is current.
+2. Run `npm i -g @deftai/directive@latest` to install the engine from npm.
+3. In your project, run `deft update` to refresh `.deft/core/` and `.githooks/`.
+4. Run `deft migrate` once to stamp npm provenance (idempotent).
+5. Run `deft agents:refresh` if the AGENTS.md managed section is stale.
+6. Verify with `deft doctor` — install integrity confirms the npm payload is current.
 
-The frozen Go installer remains available at [GitHub Releases](https://github.com/deftai/directive/releases) as a legacy / offline bridge but receives no further updates (#1912); Node ≥ 20 is still required to run Deft afterward. After this one-time step, `npm i -g @deftai/directive@latest` is the only upgrade command you need.
+The frozen Go installer remains available at [GitHub Releases](https://github.com/deftai/directive/releases) as a legacy / offline bridge but receives no further updates (#1912); Node ≥ 20 is still required to run Deft afterward. After this one-time step, the four-step npm path above is all you need for every future upgrade.
 
 ---
 
@@ -89,7 +153,7 @@ runs the doctor first gets pointed at this exact two-step before touching `init`
 
 **Version-range buckets (apply-order, oldest applicable first):**
 
-- **From pre-v0.20 (very old) — manual.** Run the pre-cutover migration, then refresh AGENTS.md: [From any pre-v0.20 version → v0.20.0](#from-any-pre-v020-version--v0200) and [From pre-#768 AGENTS.md → managed-section AGENTS.md](#from-pre-768-agentsmd--managed-section-agentsmd). Agents: when the project shows BOTH a stale AGENTS.md and pre-cutover artifacts, follow [QUICK-START.md Case G+H](./QUICK-START.md#case-gh--combined-stale-agentsmd--pre-cutover-migration-big-jump-one-session) to complete both in one session instead of two.
+- **From pre-v0.20 (very old) — manual.** Run the pre-cutover migration on pinned **v0.59.0**, then refresh AGENTS.md: [Frozen pre-v0.20 document-model migration (#2068)](#frozen-pre-v020-document-model-migration-2068) and [From pre-#768 AGENTS.md → managed-section AGENTS.md](#from-pre-768-agentsmd--managed-section-agentsmd). Agents: when the project shows BOTH a stale AGENTS.md and pre-cutover artifacts, follow [QUICK-START.md Case G+H](./QUICK-START.md#case-gh--combined-stale-agentsmd--pre-cutover-migration-big-jump-one-session) to complete both in one session instead of two.
 - **From v0.20–v0.24 — auto-handled (opt-in).** Triage v1 is purely additive; nothing breaks if you skip it: [Migration to triage v1](#migration-to-triage-v1).
 - **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).
@@ -97,13 +161,16 @@ runs the doctor first gets pointed at this exact two-step before touching `init`
 - **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:
+**Final step for every bucket.** Finish on the canonical npm upgrade path, then let the doctor confirm you are current:
 
 ```bash
 npm i -g @deftai/directive@latest
+deft update
+deft migrate
+deft doctor
 ```
 
-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.
+Run those from your project root after any bucket-specific hops (`deft update` refreshes `.deft/core/` and `.githooks/`; `deft migrate` stamps npm provenance once and is idempotent). 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.
 
 ---
 
@@ -522,18 +589,19 @@ The contract is byte-stable by construction:
 
 ---
 
-## From any pre-v0.20 version → v0.20.0
+## From any pre-v0.20 version → v0.20.0 (historical; use frozen path)
 
-- **Applies when:** `.deft/core/run gate` reports `precutover=SPECIFICATION.md,PROJECT.md` (or any subset thereof) AND/OR `agents-md=missing`. The presence of legacy `SPECIFICATION.md` / `PROJECT.md` without the `<!-- deft:deprecated-redirect -->` sentinel is the canonical pre-cutover signal.
-- **Safe to auto-run:** No -- `task migrate:vbrief` rewrites `SPECIFICATION.md` and `PROJECT.md` into deprecation-redirect stubs and creates lifecycle folders; the operator must review the dry-run output and acknowledge the rewrite. `--dry-run` is recommended on any non-trivial project before the live run.
-- **Restart required:** Yes -- the agent's current session still holds stale rules from the previous `AGENTS.md`. After cleanup commands complete, stop the session and start a fresh one so the rewritten `AGENTS.md` and v0.20 skills are loaded from a clean context.
-- **Commands:**
-  - `task migrate:vbrief --dry-run` (preview)
+> **Current releases (#2068):** follow [Frozen pre-v0.20 document-model migration](#frozen-pre-v020-document-model-migration-2068) instead of upgrading straight to latest npm. The section below documents what the v0.20 cutover changed; commands assume framework **v0.59.0** (or another pinned release that still ships `migrate_vbrief.py`).
+
+- **Applies when:** `deft doctor` / `task migrate:preflight` reports pre-cutover state. Legacy `SPECIFICATION.md` / `PROJECT.md` without the `<!-- deft:deprecated-redirect -->` sentinel is the canonical signal.
+- **Safe to auto-run:** No — `task migrate:vbrief` on the pinned release rewrites `SPECIFICATION.md` and `PROJECT.md` into deprecation-redirect stubs and creates lifecycle folders; review `--dry-run` first.
+- **Restart required:** Yes — after migration completes, stop the session and start fresh so rewritten AGENTS.md and v0.20 skills load cleanly.
+- **Commands (on pinned v0.59.0 payload):**
+  - `task migrate:vbrief -- --dry-run` (preview)
   - `task migrate:vbrief` (apply)
-  - `.deft/core/run upgrade` (writes `vbrief/.deft-version` AND now refreshes the AGENTS.md managed section in one step per #768)
-  - `.deft/core/run agents:refresh` (idempotent; runs implicitly via `.deft/core/run upgrade` -- only invoke directly if you skipped that step)
+  - `deft upgrade` or `task upgrade` (record framework version + refresh AGENTS.md managed section)
   - `task roadmap:render` / `task project:render` / `task prd:render -- --force` (regenerate exports)
-  - `task check` (verify)
+  - `deft check` or `task check` (verify)
 
 ### Remote probe (#801)
 

package/docs/BROWNFIELD.md

@@ -51,15 +51,19 @@ git clone https://github.com/deftai/directive.git deft
 
 ---
 
-## 2. Migrate Existing Docs (`task migrate:vbrief`)
+## 2. Migrate Existing Docs (frozen-release path, #2068)
 
-If your project already contains `SPECIFICATION.md`, `PROJECT.md`, or `ROADMAP.md`, run the one-shot migration:
+If your project already contains authoritative root `SPECIFICATION.md`, `PROJECT.md`, or incomplete vBRIEF lifecycle folders, **current npm releases no longer ship the in-product migrator**. Pin framework **v0.59.0**, install Python 3.11+ and `uv`, then run the one-shot migration from that payload:
 
 ```bash
+task migrate:preflight
+task migrate:vbrief -- --dry-run
 task migrate:vbrief
 ```
 
-The migration is **idempotent** -- safe to re-run on a partially-migrated project.
+See [UPGRADING.md § Frozen pre-v0.20 document-model migration](../UPGRADING.md#frozen-pre-v020-document-model-migration-2068) for the full frozen Go-installer / git-tag path, then upgrade to current npm with `npm i -g @deftai/directive@latest` and `deft update`.
+
+The migration is **idempotent** on the pinned release — safe to re-run on a partially-migrated project.
 
 ### What migration does
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.61.1",
+  "version": "0.62.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": [