@deftai/directive-content 0.65.0 → 0.66.1

package/tasks/umbrella.yml

@@ -10,18 +10,12 @@ 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
+      - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:

package/tasks/vbrief.yml

@@ -4,12 +4,6 @@ vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 
 tasks:
-  _ts-build:
-    internal: true
-    desc: "Build @deftai/cli dist/ before TS-backed gates run (#1828 s2)."
-    dir: '{{.DEFT_ROOT}}'
-    cmds:
-      - pnpm run build
 
   validate:
     desc: Validate vBRIEF lifecycle folder structure and cross-file consistency
@@ -17,9 +11,13 @@ tasks:
     deps:
       - task: :engine:_ts-build
     cmds:
+      # Layout-aware (#2109 part 2a): pass --project-root and let the engine
+      # resolve the lifecycle dir (xbrief when migrated, else vbrief). The prior
+      # hardcoded --vbrief-dir ".../vbrief" was a false-green that would validate
+      # zero files after the Part-2b flip.
       - task: :engine:invoke
         vars:
-          ENGINE_CMD: 'vbrief:validate --vbrief-dir "{{.USER_WORKING_DIR}}/vbrief"'
+          ENGINE_CMD: 'vbrief:validate --project-root "{{.USER_WORKING_DIR}}"'
 
   preflight:
     # Implementation-intent preflight wrapper (#810 / PR #812 fixup;
@@ -73,10 +71,12 @@ tasks:
     desc: "Preflight an implementation-intent gate (#810): exits 0 only when vBRIEF is in vbrief/active/ AND plan.status == 'running'. Fails closed (#1046 PR-C / #1047) if the wrapped script cannot be resolved."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/preflight_implementation.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief:preflight --vbrief-path {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'vbrief:preflight --vbrief-path {{.CLI_ARGS}}'
 
   reconcile:graph:
     # Cascade-unblock walker (#1287). Walks vbrief/proposed/, resolves each
@@ -101,10 +101,12 @@ tasks:
     desc: "Reconcile dep graph: promote proposed/ vBRIEFs whose swarm.depends_on[] all resolve to completed/ or cancelled/ (#1287). Flags: --force --dry-run --json."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/vbrief_reconcile_graph.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief-reconcile graph --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'vbrief-reconcile graph --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   reconcile:labels:
     # SCM label reconciliation (#1288). Walks vbrief/proposed/ + pending/ +
@@ -132,10 +134,12 @@ tasks:
     desc: "Reconcile SCM labels to mirror vBRIEF state: status:blocked / epic+status:tracker / rfc (#1288). Routes through scripts/scm.py. Flags: --repo --dry-run --json."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/vbrief_reconcile_labels.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief-reconcile labels --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'vbrief-reconcile labels --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   reconcile:umbrellas:
     # Umbrella current-shape auto-update (#1289). Walks every kind=epic
@@ -167,10 +171,12 @@ tasks:
     desc: "Reconcile epic umbrella current-shape comments to vBRIEF state per AGENTS.md #1152: edit in place (preserve permalink). Routes through scripts/scm.py. Flags: --repo --dry-run --json."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/vbrief_reconcile_umbrellas.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief-reconcile umbrellas --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'vbrief-reconcile umbrellas --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   activate:
     # Implementation-intent activation gate companion (#810). Idempotent:
@@ -201,7 +207,9 @@ tasks:
     desc: "Activate a vBRIEF: pending/ -> active/ (status: running). Idempotent. (#810)"
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/vbrief_activate.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief:activate {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'vbrief:activate {{.CLI_ARGS}}'

package/tasks/verify.yml

@@ -4,85 +4,95 @@ vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 
 tasks:
-  _ts-build:
-    internal: true
-    desc: "Build @deftai/cli dist/ before TS-backed gates run (#1828 s2)."
-    dir: '{{.DEFT_ROOT}}'
-    cmds:
-      - pnpm run build
 
   stubs:
     desc: Scan source files for stub patterns (TODO, FIXME, HACK, return null, bare pass)
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/verify-stubs.py (#1828 Wave 8 / #1854 s3).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-stubs
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-stubs'
 
   links:
     desc: Validate internal links in markdown files
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/validate-links.py (#1828 Wave 8 / #1854 s3).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" validate-links
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'validate-links'
 
   rule-ownership:
     desc: "Verify the Rule Ownership Map (conventions/rule-ownership.json) is in sync with its owner files (#635)"
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/rule_ownership_lint.py (#1828 Wave 8 / #1854 s3).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" rule-ownership-lint --root "{{.DEFT_ROOT}}"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'rule-ownership-lint --root "{{.DEFT_ROOT}}"'
 
   content-manifest:
     desc: "Verify the Content Manifest (conventions/content-manifest.json) classifies every git-tracked top-level entry (#1821). Fails on an unclassified entry, a stale classified path, an invalid bucket, or a duplicate path. Wave-1 shippability audit for the engine/content split (#1669)."
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Framework-source-only gate: it classifies THIS repo's top-level tree, so it
     # targets DEFT_ROOT (not USER_WORKING_DIR) -- a consumer install has no
     # content/ + engine/ top-level split to audit. Mirrors verify:rule-ownership.
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-content-manifest --project-root "{{.DEFT_ROOT}}"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-content-manifest --project-root "{{.DEFT_ROOT}}"'
 
   contract-drift:
     desc: "Drift gate for the public contract layer (#1799). Asserts packages/types/schemas/vbrief-core-0.6.schema.json matches content/vbrief/schemas/vbrief-core.schema.json and that @deftai/directive-types Status/version constants align with the schema. Three-state exit (0 clean / 1 drift / 2 config error)."
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-contract-drift --project-root "{{.DEFT_ROOT}}"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-contract-drift --project-root "{{.DEFT_ROOT}}"'
 
   cursor-tier1:
     desc: "Framework-source content gate (#1877): assert Cursor (cursor-composer / cursor-cloud-agent, Task-tool primitive) is enumerated as a Tier-1 descriptor in the swarm Phase 3 capability matrix AND the review-cycle monitoring tier table. Fails when a doc edit drops the Cursor descriptor and silently re-opens the Tier-3 blocking-poll misclassification. Three-state exit (0 clean / 1 missing marker / 2 config error)."
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Framework-source-only gate: it scans THIS repo's two skill docs, so it
     # targets DEFT_ROOT (not USER_WORKING_DIR) -- a consumer install renders
     # these skills under .deft/core and does not author them. Mirrors
     # verify:content-manifest / verify:rule-ownership.
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-cursor-tier1 --project-root "{{.DEFT_ROOT}}"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-cursor-tier1 --project-root "{{.DEFT_ROOT}}"'
 
   go-freeze:
     desc: "Tier-1 freeze gate for the legacy Go-installer bridge (#1912). Advisory while the Tier-0 SoT (lastGoInstaller) is null; once the operator pins it, fails when cmd/deft-install is bumped above the frozen tag. Three-state exit (0 ok / 1 violation / 2 config error). Emergency bypass: DEFT_ALLOW_GO_INSTALLER_BUMP=1."
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Framework-source-only gate: it inspects THIS repo's cmd/deft-install
     # version constant + the Tier-0 SoT, so it targets DEFT_ROOT (not
     # USER_WORKING_DIR) -- a consumer install has no Go-installer source to
     # freeze. Mirrors verify:content-manifest.
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-go-freeze --project-root "{{.DEFT_ROOT}}"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-go-freeze --project-root "{{.DEFT_ROOT}}"'
 
   bridge-drift:
     desc: "Tier-1 cross-surface drift gate for the legacy Go-installer bridge (#1912). Asserts no surface marked with the bridge sentinel hardcodes a Go-installer version instead of reading the Tier-0 SoT (lastGoInstaller). Three-state exit (0 clean / 1 drift / 2 config error). Passes whether or not the UPGRADING/doctor surfaces exist yet."
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Framework-source-only gate: it scans THIS repo's bridge-version surfaces
     # against the Tier-0 SoT, so it targets DEFT_ROOT. Mirrors
     # verify:content-manifest / verify:scm-boundary.
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-bridge-drift --project-root "{{.DEFT_ROOT}}"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-bridge-drift --project-root "{{.DEFT_ROOT}}"'
 
   branch:
     desc: "Detection-bound branch-protection gate (#747). Reads plan.policy.allowDirectCommitsToMaster from PROJECT-DEFINITION."
@@ -98,27 +108,31 @@ tasks:
     desc: "Operator coding sub-agent model routing gate (#1739). Pre-dispatch (default): fails when a dispatched worker role has no decision in .deft/routing.local.json. Pass --advise for the non-blocking session-start disclosure; --roles a,b to widen the gated set; --provider to override the runtime."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Bare CLI_ARGS per the verify:encoding convention -- go-task shell-escapes pass-through args.
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" swarm-routing-verify --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'swarm-routing-verify --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   hooks-installed:
     desc: "Assert the deft git hooks are installed AND functional -- core.hooksPath set, hooks dir + pre-commit/pre-push present, and the gate scripts resolve in this layout (own-repo or vendored). Fails loud on the #1463 false-green (wired but non-functional). Run `task setup` / re-run the installer if this fails (#747, #1463)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # No sources:/generates: -- a cached cmds skip would mask a hooks dir /
     # gate-script that was deleted after the last run.
     cmds:
       # Oracle/fallback (parity): scripts/verify_hooks_installed.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:hooks-installed --project-root "{{.USER_WORKING_DIR}}"
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:hooks-installed --project-root "{{.USER_WORKING_DIR}}"'
 
   encoding:
     desc: "Detect PS 5.1 non-ASCII round-trip corruption (#798). Scans tracked text files for U+FFFD, CP1252/CP437-as-UTF-8 mojibake, and unexpected BOM. Defaults to --all; pass --staged for the pre-commit invocation."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md`: NO `sources:` / `generates:` because
     # user-facing flags (--staged / --all / --allow-list <path>) MUST NOT be
     # silently swallowed by go-task's incremental-build cache. The same
@@ -127,33 +141,39 @@ tasks:
     # layer would otherwise discard.
     cmds:
       # Oracle/fallback (parity): scripts/verify_encoding.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:encoding --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:encoding --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   vbrief-conformance:
     desc: "Detect bare non-conformant vBRIEF keys (#1620). Scans tracked vbrief/**/*.vbrief.json and flags any document/plan/item key that is not 0.6 spec-core, x-directive/-namespaced, or x-vbrief/-namespaced. plan.policy + plan.completedNote carry a TEMPORARY allow-list pending vBRIEF #12. Defaults to --all; pass --staged for the pre-commit invocation."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md`: NO `sources:` / `generates:` because
     # user-facing flags (--staged / --all / --allow-list <path>) MUST NOT be
     # silently swallowed by go-task's incremental-build cache (same rationale
     # as verify:encoding above).
     cmds:
       # Oracle/fallback (parity): scripts/verify_vbrief_conformance.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief-validate conformance --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'vbrief-validate conformance --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   destructive-gh-verbs:
     desc: "Detection-bound gate for destructive gh verbs (#1019). Runs preflight-gh --self-test so the fixture-vs-classifier contract fails CI on drift. Override via DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1 (per-shell emergency bypass)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # No sources:/generates: -- the self-test fixture table is the
     # invariant under test; we want the gate to re-run on every
     # `task check` invocation regardless of whether the classifier file
     # mtime moved. Caching here would silently mask a regression.
     cmds:
       # Oracle/fallback (parity): scripts/preflight_gh.py --self-test (#1854 s5).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" preflight-gh --self-test {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'preflight-gh --self-test {{.CLI_ARGS}}'
 
   cache-fresh:
     desc: "Pre-`start_agent` cache-freshness gate (#1127). Refuses implementation dispatch when the triage cache is stale, missing, or the target issue's latest decision is not `accept`. Subscription-aware via plan.policy.triageScope[] (D12 / #1131). Flags: --for-issue N / --max-age-hours N / --allow-stale / --repo OWNER/NAME / --allow-missing-bootstrap (consumed by the framework's own `task check` so a fresh checkout passes -- consumers leave it OFF)."
@@ -177,49 +197,71 @@ tasks:
     desc: "Drift gate for the generated .planning/codebase/MAP.md projection (#1595 PR4)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per conventions/task-caching.md: no sources/generates because this gate
     # forwards output/artifact overrides through CLI_ARGS.
     cmds:
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" codebase-map-fresh --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'codebase-map-fresh --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   session-ritual:
     desc: "Fail-closed session ritual verifier (#1348). Flags: --tier quick|gated / --json. Set DEFT_SESSION_RITUAL_SKIP=1 for headless workers and CI."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # No sources/generates: this gate is time-, HEAD-, and worktree-sensitive.
     cmds:
       # Oracle/fallback (parity): scripts/verify_session_ritual.py (#1828 Wave 8 / #1854 s3).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-session-ritual --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-session-ritual --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   tools:
     desc: "Detect required Deft host tools and print install or manual guidance (#1187). Flags: --install / --yes / --json"
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     cmds:
       # Oracle/fallback (parity): scripts/verify_tools.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:tools {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:tools {{.CLI_ARGS}}'
 
   scm-boundary:
     desc: "Detection-bound gate against raw `gh` / `ghx` subprocess calls outside `scripts/scm.py` (#1145 / N5). Scans verb-layer Python files (`scripts/triage_*.py`, `scripts/scope_*.py`, `scripts/slice_*.py`, `scripts/_triage_*.py`, `scripts/_scope_*.py`, `scripts/resume_conditions.py`, `scripts/issue_ingest.py`) and fails loud when any of them invoke `gh` directly instead of going through `scm.call(source, verb, args)`. Three-state exit (0 clean / 1 violations / 2 config error). Document an exception via `--allow-list <path>` (file with newline-separated glob patterns)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
     # because the gate forwards user-facing flags via {{.CLI_ARGS}}
     # (`--allow-list <path>` / `--quiet`) that go-task's incremental-build
     # cache would silently swallow.
     cmds:
       # Oracle/fallback (parity): scripts/verify_scm_boundary.py (#1828 Wave 8 / #1854 s3).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-scm-boundary --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-scm-boundary --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  xbrief-drift:
+    desc: "Data-plane drift gate for the #2109 vbrief->xbrief rename. FAILS when a NEW legacy-layout token is reintroduced: a tracked `*.vbrief.json` artifact, a tracked file under a top-level `vbrief/` lifecycle dir, or a bare `x-vbrief/` reference type inside a canonical `xbrief/**/*.xbrief.json` corpus artifact. Sanctioned back-compat shims (the Part 1 layout-resolver fallback, the EXTENSION_PREFIXES legacy entry, the #2110 migrate path, the #1650 policy fallback) are TS source -- outside the scanned data plane -- and the legacy fixture trees (tests/, content/vbrief/, docs/, history/, xbrief/migration/) are allowlisted. Three-state exit (0 clean / 1 drift / 2 config error). Document an exception via `--allow-list <path>`."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
+    # because the gate forwards user-facing flags via {{.CLI_ARGS}}
+    # (`--allow-list <path>` / `--staged` / `--quiet`) that go-task's
+    # incremental-build cache would silently swallow.
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:xbrief-drift --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   story-ready:
     desc: "Deterministic story-start Gate 0 (#1378 Story C). Inspects working-tree cleanliness, the target vBRIEF lifecycle (active/ + plan.status==running), and the dispatch envelope's `## Allocation context` consent token (Story A schema). Three-state exit (0 ready / 1 not ready / 2 config error). -- task verify:story-ready -- --vbrief-path <active-story-path> [--allocation-context <dispatch-envelope-file>] [--allow-dirty] [--json]"
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
     # because the gate forwards user-facing flags via {{.CLI_ARGS}}
     # (--vbrief-path / --allocation-context / --allow-dirty / --json) that
@@ -229,37 +271,43 @@ tasks:
     # `task check` run has no way to supply.
     cmds:
       # Oracle/fallback (parity): scripts/preflight_story_start.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:story-ready --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:story-ready --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   investigation:
     desc: "Validate a forensic investigation ledger (#1621). Promotes the forensic-research validator into a deterministic gate: the close check before Wave 5 / any causal chat. Three-state exit (0 close-ready / 1 hard failures / 2 config error). Intentionally NOT in the `task check` aggregate -- it requires a concrete --ledger path. -- task verify:investigation -- --ledger .tmp/investigations/<id>/investigation.vbrief.json [--json]"
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
     # because the gate forwards user-facing flags via {{.CLI_ARGS}}
     # (--ledger / --json) that go-task's incremental-build cache would
     # silently swallow.
     cmds:
       # Oracle/fallback (parity): scripts/verify_investigation.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:investigation --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:investigation --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   architecture-sor:
     desc: "Diff-time system-of-record architecture gate. Scans stateful persistence signals and requires a matching architecture.systemOfRecord record. Example: task verify:architecture-sor -- --base-ref origin/main [--story-path <path>]"
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per conventions/task-caching.md: no sources/generates because this gate
     # forwards --base-ref, --story-path, and --json through CLI_ARGS.
     cmds:
       # Oracle/fallback (parity): scripts/preflight_architecture_sor.py (#1854 s5).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" architecture-preflight-sor --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'architecture-preflight-sor --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   capacity:
     desc: "Three-state ADVISORY capacity gate (#1419 Slice 4). Reports trailing-window target-vs-actual bucket mix from plan.policy.capacityAllocation; exits 0 in the default advise posture (and on insufficient sample / unconfigured policy), 1 only under an explicit enforce posture with a sampled deficit, 2 on config error. DELIBERATELY NOT in the `task check` aggregate -- capacity must never fail-closed on the framework tree."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
     # because the gate forwards user-facing flags via {{.CLI_ARGS}}
     # (--project-root / --quiet) that go-task's incremental-build cache would
@@ -268,13 +316,15 @@ tasks:
     # framework's own self-check (advise-mode discipline, #1419).
     cmds:
       # Oracle/fallback (parity): scripts/verify_capacity.py (#1828 Wave 8 / #1854 s3).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify-capacity --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-capacity --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   judgment-gates:
     desc: "Three-state ADVISORY judgment-gate engine (#1419 Slice 3). Evaluates a candidate change (diff paths / labels / body) against plan.policy.judgmentGates + four default-on universal safety gates (secrets / infra / AGENTS.md+skills / installer). Advisory by default (always exits 0); opt-in --enforce fails closed (exit 1) when a mechanical block-tier gate fires without a recorded clearance; exit 2 on config error. -- task verify:judgment-gates [-- --base-ref <ref>] [--path P] [--label L] [--enforce] [--json]. DELIBERATELY NOT in the `task check` aggregate -- judgment gates must never fail-closed on the framework tree (advise -> observe -> block rollout, #1419)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
-      - _ts-build
+      - task: :engine:_ts-build
     # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
     # because the gate forwards user-facing flags via {{.CLI_ARGS}}
     # (--base-ref / --path / --label / --body / --state / --enforce / --json /
@@ -285,7 +335,9 @@ tasks:
     # advisory on the framework's own tree (advise-mode discipline, #1419).
     cmds:
       # Oracle/fallback (parity): scripts/verify_judgment_gates.py (#1828 Wave 8).
-      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" verify:judgment-gates --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:judgment-gates --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   wip-cap:
     desc: "Pre-merge re-validation that pending/+active/ count is within plan.policy.wipCap (#1124 / D4 of #1119). Catches stale-branch merges + --force overrides. Default cap is 10 per umbrella #1119 Current Shape v3. The framework's own task check passes --allow-over-cap during landing-day overage; consumer projects MUST NOT pass that flag."

package/templates/agent-prompt-preamble.md

@@ -2,7 +2,7 @@
 
 This is the canonical preamble that orchestrators (this conversation, swarm-skill dispatchers, monitor agents, scheduled / cloud agents) MUST include verbatim or by reference in any implementation sub-agent's dispatch envelope. It encodes the rules learned from prior recurrence patterns so each fresh dispatch starts with the institutional memory already loaded.
 
-The orchestrator copies the section bodies into the worker prompt; the worker reads them as binding rules. Orchestrators MAY trim sections that are demonstrably out of scope (e.g. a docs-only worker may skip the rate-limit-throttle section), but MUST NOT silently drop the AGENTS.md read mandate, the #810 vBRIEF gate, the #1378 allocation-context token, the #1531 worker-metadata section when backend routing applies, or the PowerShell 5.1 non-ASCII rule.
+The orchestrator copies the section bodies into the worker prompt; the worker reads them as binding rules. Orchestrators MAY trim sections that are demonstrably out of scope (e.g. a docs-only worker may skip the rate-limit-throttle section), but MUST NOT silently drop the AGENTS.md read mandate, the #810 xBRIEF gate, the #1378 allocation-context token, the #1531 worker-metadata section when backend routing applies, or the PowerShell 5.1 non-ASCII rule.
 
 ## 1. Read AGENTS.md before any other tool call
 
@@ -10,27 +10,27 @@ The first action in your tool loop MUST be reading `AGENTS.md` at the project ro
 
 Anti-pattern: skimming AGENTS.md via `head` or `wc -l` and proceeding. Read the full file.
 
-## 2. #810 vBRIEF Implementation Intent Gate
+## 2. #810 xBRIEF Implementation Intent Gate
 
 Before any code-writing tool call (or before dispatching a sub-agent that will write code), satisfy the gate:
 
-1. Locate (or create) a scope vBRIEF for the work. If none exists in `vbrief/proposed/`, `vbrief/pending/`, or `vbrief/active/`, create one in `vbrief/proposed/` first.
-2. Promote the vBRIEF to `vbrief/pending/` via `task scope:promote -- <path>` (idempotent; lifecycle requires proposed -> pending -> active).
-3. Activate it: `task vbrief:activate -- <path>`. This moves the file to `vbrief/active/` and flips `plan.status` to `running`.
-4. Run the gate: `task vbrief:preflight -- vbrief/active/<file>.vbrief.json`. Exit 0 means you are clear to write code.
+1. Locate (or create) a scope xBRIEF for the work. If none exists in `xbrief/proposed/`, `xbrief/pending/`, or `xbrief/active/`, create one in `xbrief/proposed/` first.
+2. Promote the xBRIEF to `xbrief/pending/` via `task scope:promote -- <path>` (idempotent; lifecycle requires proposed -> pending -> active).
+3. Activate it: `task xbrief:activate -- <path>`. This moves the file to `xbrief/active/` and flips `plan.status` to `running`.
+4. Run the gate: `task xbrief:preflight -- xbrief/active/<file>.xbrief.json`. Exit 0 means you are clear to write code.
 
-Anti-pattern: editing files before activating the vBRIEF, then activating "to make the gate pass" retroactively. The gate is the contract; satisfy it first.
+Anti-pattern: editing files before activating the xBRIEF, then activating "to make the gate pass" retroactively. The gate is the contract; satisfy it first.
 
 The gate also requires an explicit action-verb directive from the user (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`). Affirmative continuation phrases ("yes", "go", "proceed") are NOT authorisation unless the prior turn explicitly proposed implementation.
 
 ## 2.5 Allocation context -- swarm-cohort consent token (#1378)
 
-Every dispatch envelope MUST carry a `## Allocation context` section so any downstream skill (the build SKILL Story Start Gate, the `task vbrief:preflight` gate) or deterministic gate can decide whether batched work was operator-approved by reading structured fields instead of pattern-matching free-form prose. The section has exactly five fields, in this order:
+Every dispatch envelope MUST carry a `## Allocation context` section so any downstream skill (the build SKILL Story Start Gate, the `task xbrief:preflight` gate) or deterministic gate can decide whether batched work was operator-approved by reading structured fields instead of pattern-matching free-form prose. The section has exactly five fields, in this order:
 
 - `dispatch_kind`: `solo` | `swarm-cohort` -- whether this worker is a lone dispatch or one member of an operator-approved swarm cohort.
 - `allocation_plan_id`: <swarm-monitor session id, or path to the Phase 5 allocation-plan snapshot> | null -- the stable handle for the allocation plan that authorized this dispatch.
 - `batching_rationale`: <one-line rationale from the Phase 5 allocation plan> | null -- the one-line reason the cohort was batched together.
-- `cohort_vbriefs`: [<vbrief-path>, ...] -- the full cohort vBRIEF list; a `solo` dispatch lists just its one vBRIEF.
+- `cohort_vbriefs`: [<xbrief-path>, ...] -- the full cohort xBRIEF list; a `solo` dispatch lists just its one xBRIEF.
 - `operator_approval_evidence`: <Phase 5 approval timestamp or session reference> -- the audit handle proving the operator approved the allocation plan (advisory / audit-only -- it is NOT part of the recognition-contract gate below).
 
 **Recognition contract:** a section reporting `dispatch_kind: swarm-cohort` with a NON-NULL `allocation_plan_id` AND a NON-NULL `batching_rationale` satisfies the Story Start Gate consent-token requirement (the #1371 carve-out) -- the worker does NOT re-prompt the operator for batching approval mid-cohort. When the `## Allocation context` section is ABSENT (pre-#1378 dispatches, solo-interactive sessions), fall back to the #1371 prose carve-out in the Story Start Gate.
@@ -43,11 +43,11 @@ Worked example (a swarm-cohort member):
 - dispatch_kind: swarm-cohort
 - allocation_plan_id: orchestrator-run-019e80bd-7328-7636-b283-a2f818243dd9
 - batching_rationale: Three disjoint-file-scope stories from #1378; Story A freezes the schema, Stories B and C build against it in parallel.
-- cohort_vbriefs: [vbrief/active/2026-06-01-1378a-allocation-context-schema.vbrief.json, vbrief/active/2026-06-01-1378b-skill-allocation-context-recognition.vbrief.json, vbrief/active/2026-06-01-1378c-preflight-story-start-gate.vbrief.json]
+- cohort_vbriefs: [xbrief/active/2026-06-01-1378a-allocation-context-schema.xbrief.json, xbrief/active/2026-06-01-1378b-skill-allocation-context-recognition.xbrief.json, xbrief/active/2026-06-01-1378c-preflight-story-start-gate.xbrief.json]
 - operator_approval_evidence: user directive "swarm 1378 per option a" 2026-06-01T02:26Z
 ```
 
-A `solo` dispatch sets `dispatch_kind: solo`, MAY leave `allocation_plan_id` / `batching_rationale` null, and lists only its own vBRIEF in `cohort_vbriefs`; such a section does NOT by itself satisfy the consent token, so the Story Start Gate falls through to the #1371 prose carve-out for a lone interactive dispatch.
+A `solo` dispatch sets `dispatch_kind: solo`, MAY leave `allocation_plan_id` / `batching_rationale` null, and lists only its own xBRIEF in `cohort_vbriefs`; such a section does NOT by itself satisfy the consent token, so the Story Start Gate falls through to the #1371 prose carve-out for a lone interactive dispatch.
 
 ## 2.6 Provider-neutral worker metadata (#1531)
 
@@ -74,7 +74,7 @@ Populate `selected_backend` OR `routing_policy` (or both when the operator sets
 
 **Role-boundary expectations (all providers):** the same boundaries apply whether the worker runs on Composer, Grok Build, Cursor/cloud, or a future adapter:
 
-- ! `leaf-implementation` workers implement scoped vBRIEF work in their assigned worktree only -- gates (`task check`, file-scope audit, Greptile review cycle) are model-agnostic and MUST still pass.
+- ! `leaf-implementation` workers implement scoped xBRIEF work in their assigned worktree only -- gates (`task check`, file-scope audit, Greptile review cycle) are model-agnostic and MUST still pass.
 - ! `orchestrator`, `review-monitor`, and `merge-release` roles MUST run on strong or review-capable agents; dispatchers MUST NOT route these roles to cheap leaf backends.
 - ⊗ Route a cheap leaf backend onto the merge cascade, Phase 5->6 release gate, conflict-resolution rebase, or review-cycle merge-ready decision -- these are irreversible-damage surfaces that stay on the strong tier regardless of provider.
 
@@ -233,19 +233,22 @@ 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)
+## 5.6 Issue reading — body then comments (#2143 / #2066)
 
-Before stating an umbrella or epic's current status (what is done, what blocks, wave order), satisfy the claim-cites-state-surface rule:
+Before ingesting a GitHub issue, building a worker dispatch envelope, or concluding what an issue actually asks for, satisfy the body→comments reading discipline for **any** issue (not only umbrellas):
 
-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.
+1. ! Fetch the issue via REST: `gh api repos/<owner>/<repo>/issues/<N>` (or `ghx api ...` for cached read-only GET).
+2. ! Fetch the comment thread via REST: `gh api repos/<owner>/<repo>/issues/<N>/comments` (or `ghx api ...` for cached read-only GET). The issue-ingest path fetches `/comments` by default and folds the thread into the ingested overview (#2143).
+3. ! Read body first, then the comment thread in chronological order. Later maintainer comments may supersede the original body — the #2126 recurrence shipped the wrong fix because dispatch used a body-only fetch.
+4. ! Any scope, fix, or status conclusion about the issue MUST reflect the full thread, not the body alone.
 
-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.
+**Umbrellas and epics (#1152):** when the issue is an umbrella or epic, the reading order extends to body → `## Current shape (as of pass-N)` comment → amendment comments. Prefer `task umbrella:current-shape <N>` for the deterministic current-shape read path.
 
-⊗ Conclude umbrella or epic status from the issue body alone (#2066).
+Anti-pattern: reading only the issue body and building a dispatch envelope from it — e.g. `gh issue view <N> --json body` or REST `repos/.../issues/<N>` body field alone when `comments` count is greater than zero.
 
-Reference: AGENTS.md `## Umbrella current-shape convention (#1152)`, issue #2066.
+⊗ Conclude what an issue asks for, or build a dispatch envelope, from the issue body alone when the issue has comments (#2143 / #2066).
+
+Reference: AGENTS.md `## Issue body→comments reading (#2143)`, `## Umbrella current-shape convention (#1152)`, issue #2143.
 
 ## 6. No Draft re-toggling within a single review cycle
 
@@ -305,7 +308,7 @@ This rule is complementary to §5 (REST-by-default) and §7 (rate-limit-aware th
 
 If you (the worker) need to spawn a sub-agent yourself:
 
-- Sub-agents MUST have non-overlapping file scopes. Use the parent vBRIEF's `files_owned` / `files_must_not_touch` to partition.
+- Sub-agents MUST have non-overlapping file scopes. Use the parent xBRIEF's `files_owned` / `files_must_not_touch` to partition.
 - Destructive operations (worktree removal, branch deletion, force-push) run alone, never in parallel.
 - Each sub-agent receives its own dispatch envelope including this preamble (or a reference to it).
 - Each child dispatch MUST carry its own `## Worker metadata` section per §2.6 when backend routing applies: set `dispatch_provider` and `worker_role` for the child's actual harness and role; propagate or override `selected_backend` / `routing_policy` so audit trails remain reconstructable at every tree depth (#1531).
@@ -391,7 +394,7 @@ The gate is detection-bound and has three exit states (mirrors the #747 branch g
 
 - `0` -- cache fresh, target issue's latest decision is `accept`, and the issue is inside the active `plan.policy.triageScope[]` subscription (D12 / #1131). Proceed to `start_agent`.
 - `1` -- cache is stale OR a blocking condition was found (issue's latest decision is `defer` / `reject` / `needs-ac` / `mark-duplicate` / absent, OR the issue is outside the active subscription, OR no cached entry exists for the issue under the resolved subscription). The dispatcher MUST refuse `start_agent` and surface the printed remediation (cite `task triage:bootstrap` / `task cache:fetch-all` for staleness, `task triage:accept` / `task triage:scope --list` for the gating decision).
-- `2` -- config error: `.deft-cache/` is absent or `vbrief/.eval/candidates.jsonl` is missing. The dispatcher MUST refuse `start_agent` and surface the bootstrap recovery line (`task triage:bootstrap`). This is the never-bootstrapped case and is distinct from the stale-cache case so the operator sees the right action.
+- `2` -- config error: `.deft-cache/` is absent or `xbrief/.eval/candidates.jsonl` is missing. The dispatcher MUST refuse `start_agent` and surface the bootstrap recovery line (`task triage:bootstrap`). This is the never-bootstrapped case and is distinct from the stale-cache case so the operator sees the right action.
 
 The `--allow-stale` override is per-shell and audited: the dispatcher MAY pass it after operator approval when the upstream issue body is known to be stable across the freshness window, but the override is logged to stderr and SHOULD be cited in the dispatch envelope so a downstream reviewer can audit the decision. Never silently strip the `--for-issue` arg to clear a failing gate; that defeats the contract.
 
@@ -420,4 +423,4 @@ Forbidden phrasing without direct user-side evidence: `you cancelled`, `you stop
 
 If any rule above conflicts with the user's explicit in-conversation directive, ASK rather than improvise. Rules represent the project's institutional memory; the user can override on a case-by-case basis but the dispatcher should surface the conflict, not silently bypass.
 
-This template is owned by `vbrief/active/2026-05-07-954-orchestrator-agents-md-preamble-template.vbrief.json` (lifecycle-moves to `vbrief/completed/` on PR merge) and may be revised via a #954-tagged PR.
+This template is owned by `xbrief/active/2026-05-07-954-orchestrator-agents-md-preamble-template.xbrief.json` (lifecycle-moves to `xbrief/completed/` on PR merge) and may be revised via a #954-tagged PR.