@deftai/directive-content 0.61.2 → 0.62.0

package/skills/deft-directive-build/SKILL.md

@@ -76,11 +76,11 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
 
 ! If pre-cutover or strategy-nonconformant state is detected, **stop immediately** and display an actionable message that cites the exact validator:
 
-> "This project was generated with pre-v0.20 or non-conformant strategy output. Run the deterministic validator and follow its remediation: `task verify-strategy-output` (works in source and after `deft` package install) or `python .deft/core/scripts/validate_strategy_output.py --project-root .` . Then `task migrate:vbrief` / `task project:render` / strategy re-run as indicated."
+> "This project was generated with pre-v0.20 or non-conformant strategy output. Run the deterministic validator and follow its remediation: `task verify-strategy-output` (works in source and after `deft` package install) or `python .deft/core/scripts/validate_strategy_output.py --project-root .`. For document-model migration, follow UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068): pin v0.59.0, then run `task migrate:vbrief` from that payload. Otherwise `task project:render` / strategy re-run as indicated."
 
 ! Include specific details about what was detected (the validator output is authoritative):
 
-- Legacy specification.vbrief.json or missing lifecycle folders: "Run `task migrate:vbrief` to create the lifecycle folder structure and remove legacy dual-writes"
+- Legacy specification.vbrief.json or missing lifecycle folders: "Follow the frozen v0.59.0 migrator path (#2068) or run `task migrate:preflight` for current-release guidance"
 - Non-date-prefixed vBRIEFs: "Re-run the emitting strategy after the v0.20 migrations (#1166 s1+s2+...) or manually rename files to `YYYY-MM-DD-<slug>.vbrief.json` and `task scope:promote`"
 - Missing `PROJECT-DEFINITION.vbrief.json`: "Run `task project:render` to generate the project definition"
 - `SPECIFICATION.md` / `PROJECT.md` without sentinel: the classic pre-cutover messages
@@ -88,7 +88,7 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
 
 ! After the validator reports clean, re-run this guard before continuing.
 
-⊗ Proceed with build when pre-cutover or strategy-nonconformant artifacts are detected -- always redirect to migration first (or run the validator) and surface the exact remediation.
+⊗ Proceed with build when pre-cutover or strategy-nonconformant artifacts are detected -- always redirect to the frozen migration path first (or run the validator) and surface the exact remediation.
 ⊗ Silently ignore these artifacts or guess at fixes -- the validator (wired into `task check` and this guard) is the deterministic gate.
 
 ## USER.md Gate

package/skills/deft-directive-refinement/SKILL.md

@@ -317,6 +317,8 @@ The task scans every vBRIEF with a GitHub-backed reference (whether the referenc
 
 ! When the refinement session files a new umbrella issue (or surfaces one whose current-shape comment is missing), file the umbrella then file its `## Current shape (as of pass-N)` comment per `## Umbrella current-shape convention` in `AGENTS.md` (#1152) -- the edit-in-place comment is the canonical surface every subsequent design pass updates.
 
+! Before reporting an umbrella or epic's current status to the operator (what is done, what blocks, wave order), fetch `repos/<owner>/<repo>/issues/<N>/comments` via REST, read the `## Current shape (as of pass-N)` comment and any linked context/`LockedDecisions` vBRIEF — never conclude status from the issue body alone (claim-cites-state-surface, #2066).
+
 ~ Issue-label hygiene for any umbrella or child issue this skill files: before creating issues, inspect the target repo's existing labels with `gh label list` or the labels API; choose one or more suitable existing labels when practical, or explicitly note that no label was applied. This is a recommendation, not a gate -- do not block issue creation solely because no label fits, and do not invent ad hoc labels outside the repo's existing label set.
 
 ! When a refinement pass produces a slicing event (rare but possible -- e.g. a design pass on an existing umbrella files N additional Wave-N child issues), record the cohort in `vbrief/.eval/slices.jsonl` via `scripts/slice_record.py::write_slice(...)` with `actor="skill:refinement"` immediately after the children are filed (#1132 / D13). Same call shape as `skills/deft-directive-gh-slice/SKILL.md` Step 6. The cohort record is what makes `task triage:audit --orphans` able to detect Wave-2+ children whose umbrella closes prematurely; without it the production-side drift this surface guards against re-fires. Skip when the pass produced no new child cohort (e.g. a pure re-prioritization).

package/skills/deft-directive-setup/SKILL.md

@@ -12,12 +12,6 @@ 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`.
@@ -44,45 +38,24 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
 
 ### Action on Detection
 
-! If pre-cutover state is detected, **stop immediately** and display an actionable message:
+! If pre-cutover state is detected, **stop immediately** and display an actionable message pointing at the frozen-release migration path (#2068):
 
-> "This project uses the pre-v0.20 document model. Run `task migrate:vbrief` to upgrade to the vBRIEF-centric model."
+> "This project uses the pre-v0.20 document model. Current npm releases no longer ship in-product `task migrate:vbrief`. Follow UPGRADING.md § Frozen pre-v0.20 document-model migration: 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."
 
 ! Include specific details about what was detected:
 
-- Missing lifecycle folders: "Run `task migrate:vbrief` to create the lifecycle folder structure"
-- `SPECIFICATION.md` with real content: "SPECIFICATION.md contains non-redirect content -- this file is deprecated; use scope vBRIEFs in `vbrief/` instead"
-- `PROJECT.md` with real content: "PROJECT.md contains non-redirect content -- this file is deprecated; use `PROJECT-DEFINITION.vbrief.json` instead"
-- Missing `PROJECT-DEFINITION.vbrief.json`: "Run `task project:render` to generate the project definition"
-
-### Environment Preflight (before asking to run migration)
+- Missing lifecycle folders: "Create lifecycle folders via the frozen-release migrator on v0.59.0, or manually add `vbrief/{proposed,pending,active,completed,cancelled}/` after migrating narratives"
+- `SPECIFICATION.md` with real content: "SPECIFICATION.md contains non-redirect content — migrate on pinned v0.59.0 before upgrading to current npm"
+- `PROJECT.md` with real content: "PROJECT.md contains non-redirect content — migrate on pinned v0.59.0 before upgrading to current npm"
+- Missing `PROJECT-DEFINITION.vbrief.json`: "Run `task project:render` after document-model migration completes"
 
-! Before asking the user "Would you like me to run `task migrate:vbrief` now?", run an environment preflight and report the results to the user. Do NOT ask the yes/no prompt until preflight results have been reported. Each failing check must be surfaced with a specific fix pointer so the user (or agent) can resolve the blocker before approving the run.
+### Preflight (optional diagnostic)
 
-Run these four checks, in order:
+~ Run `task migrate:preflight` to confirm pre-cutover state and print the frozen-release guidance. It does **not** run migration.
 
-1. **Document-model confirmation** -- re-apply the Detection Criteria above (the executable source is `scripts/_precutover.py`). If `SPECIFICATION.md` is a current generated spec export from `vbrief/specification.vbrief.json` and all lifecycle folders exist, stop: migration is NOT needed and MUST NOT be run.
-2. **Task resolvability** -- check whether `task migrate:vbrief` is dispatchable from the project root:
-   - Run `task --list` (or platform-equivalent) and grep the output for a line containing `migrate:vbrief`.
-   - If present: the primary command works from the project root -- canonical invocation is `task migrate:vbrief`.
-   - If absent: the consumer `Taskfile.yml` does not include `deft/Taskfile.yml`. Fall back to the explicit-taskfile invocation `task -t ./deft/Taskfile.yml migrate:vbrief` and tell the user: "`task migrate:vbrief` is not resolvable from the project root. I will use the fallback invocation `task -t ./deft/Taskfile.yml migrate:vbrief`, which reads the task directly from the framework Taskfile. To make the primary command work in future, add an include for `deft/Taskfile.yml` to your project `Taskfile.yml` — see `deft/main.md` § Publishing deft tasks in your project root."
-3. **`uv` on PATH** -- the migrator runs `uv run python scripts/migrate_vbrief.py`. Check `uv --version` (or equivalent): if it fails, point the user at the uv install docs (`https://docs.astral.sh/uv/`) and stop; migration cannot run without `uv`.
-4. **Migration script present** -- check `deft/scripts/migrate_vbrief.py` exists on disk. If absent, the `deft/` checkout is incomplete or came from a pre-v0.20 framework version; point the user at `deft/QUICK-START.md` (framework refresh guidance) and stop.
-
-! Report each preflight check's result to the user (e.g. "✓ task migrate:vbrief resolvable", "✗ uv not on PATH — install from https://docs.astral.sh/uv/") BEFORE prompting for yes/no approval. If any check fails, do NOT offer to run migration until it is resolved.
-
-⊗ Skip preflight and immediately ask "Would you like me to run `task migrate:vbrief` now?" -- preflight catches preventable errors (unresolvable task, missing `uv`, missing script) before the user commits to running migration.
-⊗ Propose an install-step mutation that writes `migrate:vbrief` content into the consumer Taskfile. The supported publish mechanism is the `includes: deft: deft/Taskfile.yml` pattern documented in `deft/main.md` § Publishing deft tasks in your project root; inline Taskfile mutation is explicitly out of scope (per #506 D6).
-
-### Prompt and Run
-
-! After preflight results are reported (and all checks pass), ask the user: "Would you like me to run `task migrate:vbrief` now?"
-- If yes: run the migration command (use the fallback invocation `task -t ./deft/Taskfile.yml migrate:vbrief` if the preflight resolvability check found the primary task unresolvable). Then re-run the pre-cutover detection guard to verify clean state before proceeding.
-- If no: stop and let the user handle migration manually.
-
-⊗ Proceed with setup phases when pre-cutover artifacts are detected -- always redirect to migration first.
-⊗ Silently ignore pre-cutover artifacts -- the user must be informed with an actionable command to fix the state.
-⊗ Display the migration diagnostic without offering to run it -- always ask the user if they want the agent to handle it (after preflight has passed).
+⊗ Offer to run `task migrate:vbrief` from the current npm deposit — the migrator is not bundled on current releases (#2068).
+⊗ Proceed with setup phases when pre-cutover artifacts are detected — always redirect to the frozen migration path first.
+⊗ Silently ignore pre-cutover artifacts — the user must be informed with an actionable command to fix the state.
 
 ### Greenfield Projects (No Migration Needed)
 
@@ -96,19 +69,15 @@ Run these four checks, in order:
 
 ~ This is already handled by Phase 2 Output Path (creates `./vbrief/` and lifecycle subfolders) and Phase 3 Output (creates scope vBRIEFs in lifecycle folders). The guard ensures migrating projects are redirected before reaching these phases.
 
-### Migration safety flags
-
-`task migrate:vbrief` is destructive by default (it replaces `SPECIFICATION.md` and `PROJECT.md` with redirect stubs and rewrites `vbrief/`), but it carries four always-on / on-demand safety affordances so operators can preview, recover, and undo (#497, #506 D7). Agents offering to run migration MUST mention these and pick the right one for the operator's situation.
+### Migration safety flags (frozen v0.59.0 release only)
 
-- ! **Automatic `.premigrate.*` backups (always-on, no flag)**: before any destructive write the migrator copies every pre-cutover input to its `.premigrate` sibling -- `SPECIFICATION.md` -> `SPECIFICATION.premigrate.md`, `PROJECT.md` -> `PROJECT.premigrate.md`, `ROADMAP.md` -> `ROADMAP.premigrate.md`, `PRD.md` -> `PRD.premigrate.md` (only if present), and `vbrief/specification.vbrief.json` -> `vbrief/specification.premigrate.vbrief.json`. Each backup emits a `BACKUP <src> -> <dst> (<N> bytes)` line in the migration output. These files are `.gitignore`d by default so they do not leak into commits; operators who want them versioned can remove the patterns.
-- ! **`task migrate:vbrief -- --dry-run` (preview)**: prints the complete migration plan (every proposed backup, lifecycle folder, narrative ingestion, scope vBRIEF, and deprecation-redirect replacement) prefixed `DRYRUN` without writing any file. Exits 0 on success. Use this before running migration for the first time on an unfamiliar project.
-- ! **Dirty-tree guard (always-on)**: if `git status --porcelain` is non-empty the migrator refuses to run and points the operator at `--force`. Keeps migration output separable from in-progress edits. Bypass with `task migrate:vbrief -- --force` only after confirming the operator has accepted the risk.
-- ! **`task migrate:vbrief -- --rollback`**: restores every pre-cutover input from its `.premigrate.*` backup and removes the scope vBRIEFs and migration-report files a prior run created. Reads `vbrief/migration/safety-manifest.json` (written by the migrator). Refuses if any redirect stub has been edited since migration -- re-run with `--force` to overwrite those edits on purpose, or commit them before rolling back. Prompts for a yes/no confirmation unless `--force` is passed.
+When guiding an operator through migration on the pinned release, mention the migrator safety affordances (#497, #506 D7):
 
-! When a user declines an in-flight migration or reports an incorrect result, offer `task migrate:vbrief -- --rollback` before asking them to edit files by hand.
+- **`task migrate:vbrief -- --dry-run` (preview)** on v0.59.0
+- **Dirty-tree guard** — migrator refuses when the working tree is dirty unless `--force`
+- **`task migrate:vbrief -- --rollback`** on v0.59.0 to restore `.premigrate.*` backups
 
-⊗ Offer `task migrate:vbrief` without also telling the user about `--dry-run` when they sound hesitant -- previewing is free and catches reconciliation surprises that would otherwise land in a commit.
-⊗ Suggest `git reset --hard` or manual file deletion as a recovery path when `--rollback` would do the right thing more safely.
+⊗ Offer in-product migration from a current npm deposit — use the frozen path (#2068).
 
 ## Deterministic Questions Contract
 

package/skills/deft-directive-sync/SKILL.md

@@ -58,11 +58,11 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
 
 ! If pre-cutover state is detected, display the actionable migration message, then **skip Phases 1-6** and proceed directly to Phase 7 with the Document Model line set to "pre-v0.20 (legacy)":
 
-> "This project uses the pre-v0.20 document model. Run `task migrate:vbrief` to upgrade to the vBRIEF-centric model."
+> "This 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: pin framework v0.59.0, install Python 3.11+ and uv, run `task migrate:vbrief` once from that payload, then upgrade to current npm."
 
 ! Include specific details about what was detected:
 
-- Missing lifecycle folders: "Run `task migrate:vbrief` to create the lifecycle folder structure"
+- Missing lifecycle folders: "Create lifecycle folders via the frozen v0.59.0 migrator (#2068), or manually add `vbrief/{proposed,pending,active,completed,cancelled}/` after migrating narratives"
 - `SPECIFICATION.md` with real content: "SPECIFICATION.md contains non-redirect content -- this file is deprecated; use scope vBRIEFs in `vbrief/` instead"
 - `PROJECT.md` with real content: "PROJECT.md contains non-redirect content -- this file is deprecated; use `PROJECT-DEFINITION.vbrief.json` instead"
 - Missing `PROJECT-DEFINITION.vbrief.json`: "Run `task project:render` to generate the project definition"
@@ -72,7 +72,7 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
 
 ! Include a **Document Model** line in the Phase 7 summary:
 
-- Pre-cutover detected: "**Document Model**: pre-v0.20 (legacy) -- run `task migrate:vbrief` to upgrade"
+- Pre-cutover detected: "**Document Model**: pre-v0.20 (legacy) -- follow UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068)"
 - Post-cutover (lifecycle folders present, no stale artifacts): "**Document Model**: v0.20+ (vBRIEF-centric) -- OK"
 - Post-cutover with tampered placeholders: "**Document Model**: v0.20+ with warnings -- SPECIFICATION.md or PROJECT.md contains non-redirect content"
 
@@ -122,7 +122,7 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
    - `cancelled/`
 2. ! Report any missing folders with a clear warning:
    - "WARNING: vbrief/{folder}/ does not exist -- lifecycle structure is incomplete"
-3. ~ If folders are missing, suggest running `task migrate:vbrief` or creating them manually
+3. ~ If folders are missing, suggest `task migrate:preflight` and the frozen v0.59.0 migrator path (#2068), or creating them manually after migration
 
 ### 3b: PROJECT-DEFINITION.vbrief.json Validation
 

package/skills/deft-directive-triage/SKILL.md

@@ -102,6 +102,8 @@ What would you like to do with this candidate?
 4. ~ When the audit surfaces a stale acceptance (`accept` decision whose issue is no longer referenced by any `vbrief/active/`), surface it to the operator -- the typical fix is a fresh ingest via `task issue:ingest -- <N>` or a `task triage:reset <N>` if the acceptance was in error.
 5. ⊗ Skip the Phase 4 audit -- silent exit leaves the operator without a record of what landed in `vbrief/proposed/` this session, which is the typical recurrence vector for "what did I just accept?" confusion.
 
+! Before reporting an umbrella or epic's current status during triage (what is done, what blocks, wave order), fetch `repos/<owner>/<repo>/issues/<N>/comments` via REST, read the `## Current shape (as of pass-N)` comment and any linked context/`LockedDecisions` vBRIEF — never conclude status from the issue body alone (claim-cites-state-surface, #2066 / AGENTS.md #1152).
+
 ## Reversibility
 
 ! To undo a decision, run `task triage:reset <N>`. This writes a `reset` audit entry referencing the prior decision id; history is **never** deleted. `task triage:reset` is the canonical Layer 5 reversibility verb (resolves the V3 audit from 2026-05-13). After a reset, the candidate re-enters the untriaged group on the next `task triage:queue` render so it can be re-walked through Phase 3.

package/tasks/framework.yml

@@ -23,30 +23,26 @@ tasks:
     desc: "Read-only remote-version probe (#801) -- task framework:check-updates [-- --force | --json]. Honors DEFT_NO_NETWORK=1 and DEFT_REMOTE_PROBE_TIMEOUT (default 5s)."
     dir: '{{.USER_WORKING_DIR}}'
     env:
-      PYTHONUTF8: "1"
       # When the operator passes `--force`, the task wrapper sets
       # DEFT_FORCE_REMOTE_PROBE=1 so the gate-integration helper bypasses
-      # the 24h throttle. The `run` CLI surface (`run check-updates`) is
-      # already idempotent (does not write to the throttle file), so this
-      # env var only affects callers that probe through the upgrade gate.
+      # the 24h throttle. The deft-ts CLI surface is idempotent (does not
+      # write to the throttle file), so this env var only affects callers
+      # that probe through the upgrade gate.
       DEFT_FORCE_REMOTE_PROBE: '{{if (mustRegexMatch "(^|\\s)--force(\\s|$)" .CLI_ARGS)}}1{{else}}{{.DEFT_FORCE_REMOTE_PROBE | default ""}}{{end}}'
     cmds:
-      # Strip our own `--force` from the args we pass through to `run` so it
-      # does not surface as an unknown flag in the JSON / text output. Other
-      # supported flags (e.g. `--json`) flow through unchanged.
+      # Strip our own `--force` from the args we pass through so it does not
+      # surface as an unknown flag in the JSON / text output. Other supported
+      # flags (e.g. `--json`) flow through unchanged.
       #
-      # #1059: invoke Python through `uv --project "{{.DEFT_ROOT}}" run python`
-      # rather than a bare `python3`. On Windows the bare `python3` command
-      # resolves to the Microsoft Store app-execution-alias stub (exit 49) on
-      # default-configured hosts where the user installed Python via the
-      # official installer, so the wrapper aborted before `run check-updates`
-      # ever started. The `uv` wrapper matches the canonical pattern used by
-      # every other tasks/*.yml file (see e.g. `tasks/prd.yml`,
-      # `tasks/vbrief.yml`) and pins the project root via #1011 so the
-      # uv environment never walks up into a hostile ancestor pyproject.
-      - >-
-        uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/run" check-updates
-        {{regexReplaceAll "(^|\\s)--force(\\s|$)" .CLI_ARGS " "}}
+      # #2069: consumer path dispatches through the native deft-ts handler
+      # via engine:invoke (vendored bin.js in source checkouts, global deft
+      # on npm consumer deposits — #2022 Phase 3).
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: >-
+            framework:check-updates --project-root "{{.USER_WORKING_DIR}}"
+            --deft-root "{{.DEFT_ROOT}}"
+            {{regexReplaceAll "(^|\\s)--force(\\s|$)" .CLI_ARGS " "}}
 
   doctor:
     # #1272: the legacy ``task framework:doctor`` surface is REDACTED.

package/tasks/migrate.yml

@@ -10,75 +10,18 @@ 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
-    # `skills/deft-directive-setup/SKILL.md` § Environment Preflight as a
-    # runnable task so consumers running `task migrate:vbrief` directly
-    # (not via the agent-driven setup skill) get the same checks
-    # (uv on PATH, v0.20+ layout, document model, git working tree) before
-    # 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)."
+    # Pre-v0.20 document-model probe (#793, #2068 cutoff). Detects legacy
+    # SPECIFICATION.md / PROJECT.md or missing lifecycle folders and points
+    # operators at the frozen-release migration path in UPGRADING.md. Does NOT
+    # run the in-product migrator (retired from current npm deposits).
+    desc: "Detect pre-v0.20 document model and report the frozen-release migration path (#2068). Three-state exit (#793)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - _ts-build
     cmds:
       - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" migrate-preflight --project-root "{{.USER_WORKING_DIR}}" --deft-root "{{.DEFT_ROOT}}" {{.CLI_ARGS}}
-
-  vbrief:
-    desc: >
-      Migrate existing project files to vBRIEF-centric folder structure (RFC #309).
-      Pass safety flags after --, e.g. `task migrate:vbrief -- --dry-run`,
-      `task migrate:vbrief -- --force`, `task migrate:vbrief -- --rollback` (#497, #506 D7).
-      Pass `task migrate:vbrief -- --strict` to fail the run on any SPEC/ROADMAP
-      reconciliation conflict (#496, #506).
-      Self-invokes `task migrate:preflight` first (#793) so a non-zero preflight
-      exit aborts the run before any destructive mutation; pre-existing CLI
-      flags continue to dispatch to `scripts/migrate_vbrief.py` unchanged.
-      Emits framework events on guard trip: `dirty-tree:detected` (#497-3
-      dirty-tree guard) and `pre-cutover:detected` (when
-      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 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
-      # `migrate:preflight -- --dry-run` and exits 2 (`unrecognized
-      # arguments: --dry-run`) before the migrator runs. This bug was
-      # caught by the Windows task-dispatch regression job on PR #860.
-      - task: preflight
-        vars:
-          CLI_ARGS: ""
-    dir: '{{.USER_WORKING_DIR}}'
-    env:
-      PYTHONUTF8: "1"
-    cmds:
-      # #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}}

package/tasks/umbrella.yml

@@ -0,0 +1,30 @@
+version: '3'
+
+# tasks/umbrella.yml — umbrella issue tooling (#1152 / #2066).
+#
+# Hosts read-only surfaces for the canonical current-shape comment convention.
+# Runs from the consumer project root so git origin and gh auth resolve against
+# the operator's repo, not deftai/directive (#538 pattern).
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  _ensure-ts:
+    internal: true
+    desc: "Build the TS engine before umbrella gates (#2066)"
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
+  current-shape:
+    desc: "Fetch umbrella ## Current shape comment (#1152) — task umbrella:current-shape <N> [-- --repo OWNER/REPO | --json | --strict]. Does NOT read the issue body."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: >-
+            umbrella:current-shape --project-root "{{.USER_WORKING_DIR}}"
+            {{.CLI_ARGS}}

package/templates/agent-prompt-preamble.md

@@ -233,6 +233,20 @@ task scm:body:pr:edit -- --repo OWNER/REPO --pr 42 --body-file "$bodyFile"
 
 The wrapper reads UTF-8 body text from a file or stdin, sends JSON to `gh api --input -` via `_safe_subprocess.run_text` with `shell=False`, and prints the live post-mutation read-back object. Use live `gh` for immediate verification after mutations; do not use `ghx` for the first read-back because it may serve a cached stale GET.
 
+## 5.6 Umbrella status — claim-cites-state-surface (#2066)
+
+Before stating an umbrella or epic's current status (what is done, what blocks, wave order), satisfy the claim-cites-state-surface rule:
+
+1. ! Fetch issue comments via REST: `gh api repos/<owner>/<repo>/issues/<N>/comments` (or `ghx api ...` for cached read-only GET).
+2. ! Read the `## Current shape (as of pass-N)` comment and any linked context or `LockedDecisions` vBRIEF referenced there. Follow the AGENTS.md #1152 reading order: body -> current-shape comment -> amendment comments.
+3. ! Any "X is done" / "X is the blocker" assertion about an umbrella MUST cite the current-shape comment or another state artifact in the same message.
+
+Anti-pattern: reading only the issue body (pass-1 plan, stale by design) and concluding umbrella status from it — e.g. `gh issue view <N> --json body` or REST `repos/.../issues/<N>` body field alone. The live recurrence on 2026-06-28 misread #2013 Wave 0 status this way despite #1152 being loaded.
+
+⊗ Conclude umbrella or epic status from the issue body alone (#2066).
+
+Reference: AGENTS.md `## Umbrella current-shape convention (#1152)`, issue #2066.
+
 ## 6. No Draft re-toggling within a single review cycle
 
 Once a PR transitions Draft -> Ready, keep it Ready unless a P0 finding requires re-Draft. Repeated Draft<->Ready toggles cost GraphQL mutations and trigger stale CheckRun states downstream (Greptile re-runs, branch-protection re-evaluations).

package/templates/agents-entry.md

@@ -15,7 +15,7 @@ Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
 - ./PROJECT.md exists and is not a deprecation redirect (`<!-- deft:deprecated-redirect -->` or `<!-- Purpose: deprecation redirect -->`).
 - ./vbrief/ exists but any of the five lifecycle subfolders (proposed/, pending/, active/, completed/, cancelled/) is missing
 
-→ On detection: read .deft/core/.agents/skills/deft-directive-setup/SKILL.md "Pre-Cutover Detection Guard" section and follow the migration path BEFORE any other action. The Migrating from pre-v0.20 section of the full guidelines has the canonical command, the "task -t ./.deft/core/Taskfile.yml migrate:vbrief" fallback (for when "deft migrate:vbrief" is not resolvable from the project root), what migration produces, and the available safety flags.
+→ On detection: read .deft/core/.agents/skills/deft-directive-setup/SKILL.md "Pre-Cutover Detection Guard" section and follow the frozen migration path BEFORE any other action. The Migrating from pre-v0.20 section of the full guidelines and UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068) describe the pinned v0.59.0 path.
 
 ⊗ Start Phase 1, Phase 2, or a Returning-Sessions workflow while pre-cutover artifacts are present — run migration first.
 
@@ -83,6 +83,15 @@ The `plan.policy.wipCap` field caps the number of in-flight scope vBRIEFs (`vbri
 
 ⊗ Recommend a specific issue or vBRIEF without consulting `deft triage:queue` (or showing the operator the result of the consultation).
 
+## Umbrella status reading (#1152 / #2066)
+
+Umbrella and epic issues carry a pass-1 body (plan, stale by design) and a canonical `## Current shape (as of pass-N)` comment (live state). Before reporting umbrella status:
+
+- ! Fetch issue comments via REST (`gh api repos/<owner>/<repo>/issues/<N>/comments`), read the `## Current shape (as of pass-N)` comment, and any linked context or `LockedDecisions` vBRIEF referenced there — following the reading order body -> current-shape comment -> amendment comments (claim-cites-state-surface, #2066). Prefer the deterministic read path: `deft umbrella:current-shape <N>` (or `task umbrella:current-shape <N>`) — it locates the canonical comment, validates #1152 sections, and never falls back to the issue body.
+- ⊗ Conclude umbrella or epic status from the issue body alone. Any "X is done" / "X is the blocker" assertion about an umbrella MUST cite the current-shape comment or another state artifact, not the body.
+
+Cross-references: `.deft/core/.agents/skills/deft-directive-refinement/SKILL.md` and `.deft/core/.agents/skills/deft-directive-triage/SKILL.md` (before reporting umbrella status). Refs #1152, #2066.
+
 ## Content packs
 
 Deft ships versioned content packs (e.g. lessons learned from prior work) under `.deft/core/packs/`. Discover and LOAD pack content via the slice surface instead of reading whole pack files into context: