@deftai/directive-content 0.55.1 → 0.56.0

package/tasks/migrate.yml

@@ -0,0 +1,73 @@
+version: '3'
+
+vars:
+  # See deft/Taskfile.yml for the rationale behind per-subfile DEFT_ROOT
+  # (go-task re-evaluates var templates at use site; joinPath is eager and
+  # produces a clean, native-separator path so `uv --project "{{.DEFT_ROOT}}" run python` resolves it
+  # correctly on Windows -- #566).
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  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).
+    #
+    # NO `sources:` / `generates:` per `conventions/task-caching.md`: the
+    # script forwards user-facing CLI flags (`--project-root`, `--deft-root`,
+    # `--quiet`) via `{{.CLI_ARGS}}` and a cached cmds skip would silently
+    # swallow them.
+    desc: "Verify environment readiness for `task migrate:vbrief` (uv on PATH, v0.20+ layout, document model, git tree). Three-state exit (#793)."
+    dir: '{{.USER_WORKING_DIR}}'
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - uv --project "{{.DEFT_ROOT}}" run --frozen python "{{.DEFT_ROOT}}/scripts/migrate_preflight.py" --project-root "{{.USER_WORKING_DIR}}" --deft-root "{{.DEFT_ROOT}}" {{.CLI_ARGS}}
+
+  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).
+    deps:
+      # #793: gate destructive migration on the environment preflight. A
+      # non-zero exit from the preflight task aborts this task before any
+      # `cmds:` line runs. Operator-supplied `{{.CLI_ARGS}}` (e.g.
+      # `--dry-run`, `--force`, `--rollback`, `--strict`) belong to the
+      # migrator and are NOT valid migrate_preflight.py flags. go-task
+      # 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:
+      # Pass Taskfile CLI args through so operators can opt into safety flags
+      # (#497) or --strict reconciliation (#496) without editing this file.
+      # Script path uses {{.DEFT_ROOT}} (defined locally in this file's
+      # `vars:` block above via `joinPath .TASKFILE_DIR ".."` -- see
+      # ../Taskfile.yml for why root-level definition is avoided) rather
+      # than {{.TASKFILE_DIR}}/.. to keep the path traversal-free; the
+      # mixed-separator form breaks `uv --project "{{.DEFT_ROOT}}" run python` on Windows (#566).
+      - uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/scripts/migrate_vbrief.py" "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}

package/tasks/packs.yml

@@ -0,0 +1,92 @@
+version: '3'
+
+# Pack-slicing surface (#1283 design, #1294 lessons pilot, #1295 skills pack,
+# #1296 rules + strategies packs, ADR-001 Layer B).
+#
+# `packs:slice` is the agent-facing named-slice API (pack-agnostic, driven by
+# each pack's schema x-sliceRegistry + x-display); `packs:render` regenerates
+# every pack's projection (meta/lessons.md for lessons, the proof SKILL.md for
+# skills, the proof coding/testing.md for rules, the proof strategies/yolo.md
+# for strategies) from its canonical pack source; `packs:verify-drift` is the
+# drift gate that fails when ANY committed projection diverges from a freshly
+# rendered buffer. The pack-agnostic renderer/resolver is the #1294 machinery
+# generalized to four packs through a shared data-driven registry, not
+# copy-pasted per pack.
+#
+# DEFT_ROOT is defined locally via `{{joinPath .TASKFILE_DIR ".."}}` (same
+# idiom as tasks/issue.yml) so the scripts dispatch traversal-free on every
+# platform (#566). The slice / render scripts resolve their own pack source /
+# output paths relative to the framework root, so they are CWD-independent;
+# `dir: '{{.USER_WORKING_DIR}}'` keeps parity with the other Taskfile-
+# dispatched scripts. Per `conventions/task-caching.md` (#574) none of these
+# declare `sources:` / `generates:` because they forward user-facing flags via
+# `{{.CLI_ARGS}}` (slice filters, --check) that go-task's incremental-build
+# cache would otherwise silently swallow.
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  slice:
+    desc: "Named, structured slice access to a content pack (#1283, #1295). -- task packs:slice <pack> <name> [-- --since YYYY-MM | --tag T | --trigger KW] [--list] [--list-packs] [--json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: ":ts:build"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" packs-slice {{.CLI_ARGS}}
+
+  render:
+    desc: "Regenerate every content-pack projection from its canonical source (ADR-001): meta/lessons.md (lessons), the proof SKILL.md (skills), coding/testing.md (rules), strategies/yolo.md (strategies). -- task packs:render [-- --pack rules] [--check]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: ":ts:build"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pack-render {{.CLI_ARGS}}
+
+  render-skills:
+    desc: "One-shot migration: rebuild packs/skills/skills-pack-0.1.json from skills/*/SKILL.md + the AGENTS.md Skill Routing table (#1295)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: ":ts:build"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pack-migrate-skills {{.CLI_ARGS}}
+
+  render-rules:
+    desc: "One-shot migration: rebuild packs/rules/rules-pack-0.1.json from the RFC2119 directives in coding/*.md (#1296)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: ":ts:build"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pack-migrate-rules {{.CLI_ARGS}}
+
+  render-strategies:
+    desc: "One-shot migration: rebuild packs/strategies/strategies-pack-0.1.json from strategies/*.md (#1296)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: ":ts:build"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pack-migrate-strategies {{.CLI_ARGS}}
+
+  render-patterns:
+    desc: "One-shot migration: rebuild packs/patterns/patterns-pack-0.1.json from patterns/*.md (#1637)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: ":ts:build"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pack-migrate-patterns {{.CLI_ARGS}}
+
+  render-swarm-spec:
+    desc: "One-shot migration: rebuild packs/swarm-spec/swarm-spec-pack-0.1.json from swarm/*.md (#1637)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: ":ts:build"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pack-migrate-swarm-spec {{.CLI_ARGS}}
+
+  verify-drift:
+    desc: "Drift gate: fail (exit 1) when ANY pack projection (meta/lessons.md, the skills proof SKILL.md, coding/testing.md, strategies/yolo.md) diverges from a freshly rendered buffer. Wired into `task check` and surfaced as `task verify:pack-drift`."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: ":ts:build"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pack-render --check {{.CLI_ARGS}}

package/tasks/policy.yml

@@ -0,0 +1,75 @@
+version: '3'
+
+# tasks/policy.yml -- reconfiguration surface for the typed branch policy
+# (#746) and the detection-bound gate (#747). Per `conventions/task-caching.md`,
+# tasks that accept user-facing recovery flags via `{{.CLI_ARGS}}` (here:
+# `--confirm`, `--note "<text>"`) MUST NOT declare `sources:` / `generates:`
+# -- the cached cmds: skip would silently discard the recovery flag.
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  show:
+    # N8 (#1148) of #1119 Wave-2d-1: `task policy:show` is now the
+    # CONSOLIDATED typed-policy inspector. Walks every entry in
+    # `scripts.policy._REGISTERED_POLICIES` (allowDirectCommitsToMaster #746,
+    # wipCap #1124, triageScope #1131, triageScopeIgnores #1133/#1182,
+    # triageRankingLabels #1128, triageAutoClassify #1129, triageHoldMarkers
+    # #1129) and prints current / default / source per row. Flags forwarded
+    # via {{.CLI_ARGS}}:
+    #   --format=text|json    -- machine-stable scripting envelope
+    #   --changed-only         -- drop default-source rows
+    #   --field=<name>         -- single-field isolation
+    # The legacy `python -m scripts.policy show` CLI continues to work for
+    # any scripts that called it directly (back-compat for #746 consumers).
+    desc: "Inspect every registered typed-policy field on vbrief/PROJECT-DEFINITION.vbrief.json (#1148 / N8). -- task policy:show [-- --format=json] [--changed-only] [--field=<name>]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" policy show --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  enforce-branches:
+    desc: "Set plan.policy.allowDirectCommitsToMaster=false (enforce feature branches). Audits to meta/policy-changes.log. (#746)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" policy enforce-branches --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  allow-direct-commits:
+    desc: "Set plan.policy.allowDirectCommitsToMaster=true (capability-cost: branch-protection OFF). Requires --confirm to apply. (#746)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" policy allow-direct-commits --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  wip-cap:
+    desc: "Set plan.policy.wipCap=N (#1124 / D4 of #1119). Requires --set N --confirm. Default cap is 10 per umbrella #1119 Current Shape v3."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" policy-set wip-cap {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  subagent-backend:
+    desc: "DEPRECATED (superseded by `task swarm:routing-set`, #1739). Was: Set plan.policy.swarmSubagentBackend (#1531a). -- task policy:subagent-backend -- --set composer|grok-build|cursor-cloud"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - cmd: echo "[deft deprecation] task policy:subagent-backend is superseded by 'task swarm:routing-set' (#1739). The swarmSubagentBackend enum is no longer the active routing surface." 1>&2
+        silent: true
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" policy-set subagent-backend {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  subagent-backends:
+    desc: "DEPRECATED (superseded by `task swarm:routing-set` / `task verify:routing`, #1739). Was: Probe sub-agent backend ids, role capabilities, and availability (#1531a). -- task policy:subagent-backends [-- --format=json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - cmd: echo "[deft deprecation] task policy:subagent-backends is superseded by 'task verify:routing -- --advise' and 'task swarm:routing-set' (#1739). The swarmSubagentBackend enum is no longer the active routing surface." 1>&2
+        silent: true
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" policy-set subagent-backends {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"

package/tasks/pr.yml

@@ -0,0 +1,89 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# pr:* tasks for PR-level merge-discipline checks.
+#
+# pr:check-protected-issues is the Taskfile-level encoding of the Layer 3
+# pre-merge protected-issue link inspection from
+# skills/deft-directive-swarm/SKILL.md Phase 6 Step 1 (#701). Per the Rule
+# Authority [AXIOM] block in main.md, deterministic and Taskfile encodings
+# rank above prose -- this target wraps the canonical
+#   gh pr view <N> --json closingIssuesReferences
+# query so a swarm monitor (or any operator) can verify in one command that
+# no protected (umbrella / staying-OPEN) issue is GitHub-side linked to the
+# PR before squash-merging.
+#
+# Companion script: scripts/pr_check_protected_issues.py
+# Companion test:   tests/cli/test_pr_check_protected_issues.py
+
+tasks:
+  check-protected-issues:
+    desc: "Verify NO protected (umbrella / staying-OPEN) issue is GitHub-side linked to a PR before squash merge (#701)"
+    deps: [":ts:build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pr-protected-issues {{.CLI_ARGS}}
+
+  # pr:check-closing-keywords -- Layer 0 (prevention) closing-keyword
+  # negation-context lint introduced by #737. Refuses to push when the
+  # PR body or any commit message contains a closing-keyword token in a
+  # negation / quotation / example / code-block context. Pairs with the
+  # existing Layer 3 (recovery) ``pr:check-protected-issues`` (#701).
+  #
+  # Per ``conventions/task-caching.md`` (#574): NO ``sources:`` /
+  # ``generates:`` because user-facing recovery flags (``--pr``,
+  # ``--body-file``, ``--commits-file``, ``--allow-known-false-positives``)
+  # MUST NOT be silently swallowed by go-task's incremental-build cache.
+  check-closing-keywords:
+    desc: "Scan PR body + commit messages for closing-keyword substrings in negation/quotation/example contexts that would trigger Layer 0 false-positive auto-closes (#737)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps: [":ts:build"]
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pr-closing-keywords {{.CLI_ARGS}}
+
+  # pr:merge-ready -- programmatic Greptile-body verdict gate. Closes the
+  # SUCCESS-with-findings blind spot in the Phase 5 -> 6 merge-readiness
+  # checklist. Parses the Greptile rolling-summary comment body (NOT the
+  # CheckRun status) for confidence, P0/P1 findings, errored sentinel
+  # (#526), and HEAD-SHA freshness. Companion to the swarm SKILL Phase 6
+  # Step 1 prose rule. PR #652 incident motivated this gap-closer.
+  #
+  # Companion script: scripts/pr_merge_readiness.py
+  # Companion test:   tests/cli/test_pr_merge_readiness.py
+  merge-ready:
+    desc: "Verify a PR's Greptile review body satisfies the merge exit condition (confidence >3, no P0/P1, HEAD-SHA fresh, not errored)"
+    deps: [":ts:build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pr-merge-readiness {{.CLI_ARGS}}
+
+  # pr:wait-mergeable-and-merge -- cascade automation surface (#1369).
+  # Wraps scripts/pr_wait_mergeable.py which composes the resilient
+  # wait-until-ready monitor (#1368) and the Layer-3 protected-issue
+  # link inspector (#701) into a single end-to-end primitive so a swarm
+  # monitor can request "wait until this PR is mergeable, then merge it"
+  # without hand-rolling the loop. The companion script invokes
+  # scripts/pr_check_protected_issues.py (Layer-3 #701) BEFORE the wait
+  # loop when --protected is supplied, so a persistent
+  # closingIssuesReferences link short-circuits the cascade with exit 1
+  # ahead of any gh pr merge call. Cascade automation on the Grok Build
+  # hybrid path MUST go through this surface per the AGENTS.md
+  # `## Cascade automation surface (#1369)` rule.
+  #
+  # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
+  # because user-facing flags (`--cap-minutes` / `--protected` / `--repo`
+  # / `--json`) MUST NOT be silently swallowed by go-task's incremental-
+  # build cache.
+  #
+  # Companion script: scripts/pr_wait_mergeable.py
+  # Companion test:   tests/cli/test_pr_wait_mergeable.py
+  wait-mergeable-and-merge:
+    desc: "Wait until PR is mergeable (resilient cascade, #1368) and squash-merge with admin (#1369); Layer-3 protected-issue check (#701) chains before any merge call"
+    deps: [":ts:build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" pr-wait-mergeable {{.CLI_ARGS}}

package/tasks/prd.yml

@@ -0,0 +1,39 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# prd:render task.
+#
+# IMPORTANT: explicit absolute paths are passed for BOTH the input spec and
+# the output PRD.md so a stray ``dir:`` or ``CWD`` mis-resolution can never
+# cause the framework's own ``deft/PRD.md`` to be silently overwritten from
+# a consumer project (#539). Standardised on ``node .../bin.js prd-render`` --
+# the prior ``python3`` invocation was inconsistent with every other task and
+# caused sporadic PATH issues on Windows.
+
+tasks:
+  _ts-build:
+    internal: true
+    desc: "Build @deftai/cli dist/ before TS-backed render gates run (#1854 s2)."
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
+  render:
+    # Caching: intentionally absent. `prd:render` runs in <30ms and its
+    # CLI_ARGS carry recovery flags (e.g. `--force` from the #539
+    # refuse-to-overwrite safety check). Declaring `sources:` / `generates:`
+    # would cause go-task to short-circuit before `cmds:` runs, dropping
+    # CLI_ARGS and silently breaking the #539 recovery path (#573, #574).
+    # See deft/conventions/task-caching.md for the full rule.
+    desc: Export plan.narratives from specification.vbrief.json to a read-only PRD.md
+    summary: |
+      Reads specification.vbrief.json and extracts plan.narratives into a
+      human-readable PRD.md for stakeholder export. PRD.md is never
+      authoritative -- the vBRIEF is the source of truth.
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" prd-render --spec "{{.USER_WORKING_DIR}}/vbrief/specification.vbrief.json" --output "{{.USER_WORKING_DIR}}/PRD.md" {{.CLI_ARGS}}

package/tasks/project.yml

@@ -0,0 +1,27 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# project:render task.
+#
+# Fixed #539: the task previously used ``{{.ROOT_DIR}}`` which is deft's
+# own repo root when invoked via ``includes:`` -- consumers got their data
+# scanned from ``deft/vbrief/``. Switched to ``{{.USER_WORKING_DIR}}`` to
+# match the convention used by roadmap:render / spec:render / migrate:vbrief.
+
+tasks:
+  _ts-build:
+    internal: true
+    desc: "Build @deftai/cli dist/ before TS-backed render gates run (#1854 s2)."
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
+  render:
+    desc: Regenerate PROJECT-DEFINITION.vbrief.json items registry from lifecycle folders
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" project-render "{{.USER_WORKING_DIR}}/vbrief"

package/tasks/reconcile.yml

@@ -0,0 +1,32 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# reconcile issues task.
+#
+# IMPORTANT: runs from the consumer project root (``dir:
+# '{{.USER_WORKING_DIR}}'``) so ``gh`` and ``git`` commands executed by
+# ``scripts/reconcile_issues.py`` resolve against the CONSUMER's remote,
+# not deftai/directive (#538). Script path dispatched via {{.DEFT_ROOT}}
+# (defined locally in this file's `vars:` block via
+# ``{{joinPath .TASKFILE_DIR ".."}}`` -- see ../Taskfile.yml for why
+# root-level definition is avoided) to keep the path traversal-free and
+# avoid the {{.TASKFILE_DIR}}/.. form that breaks on Windows under
+# `uv --project "{{.DEFT_ROOT}}" run python` (#566).
+
+tasks:
+  _ensure-ts:
+    internal: true
+    desc: "Build the TS engine before reconcile gates (#1828 s4)"
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
+  issues:
+    desc: "Reconcile GitHub issues against vBRIEF references -- report linked, unlinked, and resolved"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" reconcile-issues --vbrief-dir "{{.USER_WORKING_DIR}}/vbrief" --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}

package/tasks/relocate.yml

@@ -0,0 +1,56 @@
+version: '3'
+
+# tasks/relocate.yml -- wipe-and-reinstall relocator surface (#992 PR2).
+#
+# Wires `task relocate` to scripts/relocate.py with full {{.CLI_ARGS}}
+# pass-through so operators can compose flags as documented in the script
+# docstring (--project-root / --framework-source / --force / --confirm /
+# --no-confirm / --dry-run / --rollback / --snapshot / --no-snapshot /
+# --json / --quiet).
+#
+# Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
+# declarations because user-facing recovery flags (`--force`, `--confirm`,
+# `--rollback`, `--dry-run`) flow via {{.CLI_ARGS}} -- a go-task cache
+# short-circuit would silently drop the recovery flag and leave the
+# operator following the docs against an exit-0 no-op (the same hazard
+# `task prd:render -- --force` hit at #574).
+#
+# Path resolution uses the same {{.TASKFILE_DIR}} / joinPath idiom every
+# other fragment uses (#566) so the dispatch resolves correctly under
+# Windows / macOS / Linux. The dispatched script lives at
+# {{.DEFT_ROOT}}/scripts/relocate.py with helper modules at
+# {{.DEFT_ROOT}}/scripts/_relocate_states.py and
+# {{.DEFT_ROOT}}/scripts/_relocate_snapshot.py.
+#
+# Usage notes for operators:
+#
+# - Bare invocation against a project root that needs relocating prompts
+#   `[y/N]` on stdin (auto-prompt never auto-wipe per the active vBRIEF).
+# - For scripted use, pass `--confirm` to skip the prompt (or
+#   `--no-snapshot` for hermetic test fixtures).
+# - For consumer projects: the canonical entry point is the webinstaller
+#   bootstrap (`upgrade.sh` / `upgrade.ps1` in the separate `webinstaller`
+#   repo) which fetches a fresh framework copy to a temp dir and runs the
+#   relocator from THAT copy -- the in-place framework about to be wiped
+#   never executes its own wipe.
+# - `task relocate -- --rollback` extracts the most recent snapshot back
+#   into project root.
+#
+# Companion script: scripts/relocate.py
+# Companion tests:  tests/relocate/test_state_matrix.py
+#                   tests/relocate/test_preflight.py
+# Refs: #992 (parent issue), #11 (.deft/core/ origin),
+#       #768 (managed-section v2 contract), #794 (_wrap_legacy_in_markers),
+#       #884 (consent-gate convention).
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  relocate:
+    desc: "Wipe-and-reinstall relocator (#992 PR2) -- task relocate [-- --confirm | --dry-run | --force | --rollback | --json | --quiet]"
+    dir: '{{.USER_WORKING_DIR}}'
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/scripts/relocate.py" {{.CLI_ARGS}}

package/tasks/roadmap.yml

@@ -0,0 +1,28 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# roadmap tasks -- consumer-safe CWD + script resolution (#539, #540, #566).
+# Scripts are dispatched via {{.DEFT_ROOT}} (defined locally in this file's
+# `vars:` block via ``{{joinPath .TASKFILE_DIR ".."}}`` -- see
+# ../Taskfile.yml for why root-level definition is avoided) to keep the
+# path traversal-free and avoid the {{.TASKFILE_DIR}}/.. form that breaks
+# on Windows under `uv --project "{{.DEFT_ROOT}}" run python` (#566).
+
+tasks:
+  render:
+    desc: Render ROADMAP.md from vbrief/pending/ (Active) and vbrief/completed/ (Completed) lifecycle folders
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" roadmap-render "{{.USER_WORKING_DIR}}/vbrief/pending" "{{.USER_WORKING_DIR}}/ROADMAP.md"
+
+  check:
+    desc: Verify ROADMAP.md matches what roadmap:render would produce
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" roadmap-render "{{.USER_WORKING_DIR}}/vbrief/pending" "{{.USER_WORKING_DIR}}/ROADMAP.md" --check

package/tasks/scm.yml

@@ -0,0 +1,126 @@
+version: '3'
+
+# ---------------------------------------------------------------------------
+# scm.yml -- STUB for #883 v1 cache layer (Story 1) + #976 REST opt-in + #1555 safe body posting.
+#
+# DO NOT EXTEND except for the narrow #1555 body-posting carve-out below.
+#
+# The full scm:* task namespace lives at #881; this file is replaced wholesale
+# when #881 lands. The stub exposes the minimum surface the #883 v1 cache
+# consumer (Story 2 cache:fetch-all) needs:
+#
+#   - scm:issue:list    (thin wrapper over `ghx|gh issue list`)
+#   - scm:issue:view    (thin wrapper over `ghx|gh issue view`)
+#   - scm:issue:close   (thin wrapper over `ghx|gh issue close`)
+#   - scm:issue:edit    (thin wrapper over `ghx|gh issue edit`)
+#   - scm:body:*        (#1555 safe Markdown body posting via github-body TS CLI)
+#
+# Each command is a thin pass-through to `ghx <verb>` (when ghx is on PATH)
+# or `gh <verb>` (fallback). Output JSON via the consumer-supplied --json
+# flag. The JSON-shape contract Story 2 depends on is pinned by the
+# tests/test_scm_contract.py contract test against tests/fixtures/scm_issue_view.json.
+#
+# REST opt-in (#976): callers may pass `--rest` to scm:issue:view /
+# scm:issue:list to route the read through scripts/gh_rest.py REST
+# helpers (rest_issue_view / rest_issue_list) instead of forwarding to
+# `ghx|gh issue view|list`. This sidesteps the GraphQL bucket entirely so
+# a depleted graphql.remaining no longer fails read-only smoke / cache
+# flows. The REST shape differs from the gh --json GraphQL shape (REST
+# emits user/created_at/lowercase state vs GraphQL author/createdAt/
+# uppercase state); only callers that opt in see the REST shape. Story 2
+# cache:fetch-all keeps the legacy (GraphQL) path until #881. Mutations
+# (close, edit) keep forwarding to gh -- they have non-trivial flag
+# surfaces (--body-file, --add-label, --remove-label, ...) that this
+# stub deliberately does not re-implement; #881 owns the full surface.
+#
+# Forward-compat marker: the ONLY scm:* surface in v1 is the four issue:*
+# commands above plus the #1555 body-posting safety wrapper. PR commands
+# (scm:pr:list/view/merge/close) and any additional scm:* surface are
+# EXPLICITLY deferred to #881; do not add them here. See
+# vbrief/active/2026-05-05-883-story-1-scm-stub.vbrief.json for the full
+# Story 1 scope and vbrief/active/2026-05-05-883-deft-cache-quarantine-v1.vbrief.json
+# for the epic chain context.
+# ---------------------------------------------------------------------------
+
+vars:
+  # Each included sub-taskfile defines its own DEFT_ROOT mirror so scripts
+  # can be dispatched via {{.DEFT_ROOT}}/scripts/<name>.py on every platform
+  # (#566). joinPath is evaluated eagerly by go-task templating and yields
+  # a native-separator absolute path that uv --project "{{.DEFT_ROOT}}" run python can open on Windows.
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# Per `conventions/task-caching.md` (#574): tasks that accept user-facing
+# CLI args via {{.CLI_ARGS}} MUST NOT declare `sources:` / `generates:` --
+# the cached cmds skip would silently discard the recovery flag.
+tasks:
+  issue:list:
+    desc: "[#883 stub] List issues -- task scm:issue:list -- [--rest] --repo OWNER/NAME --json number,title,state,updatedAt [--state ...] (#976 --rest routes via REST helpers; default forwards to ghx|gh)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scm issue list {{.CLI_ARGS}}
+
+  issue:view:
+    desc: "[#883 stub] View an issue -- task scm:issue:view -- [--rest] <N> --repo OWNER/NAME --json number,title,body,state,author,createdAt,updatedAt,labels,comments (#976 --rest routes via REST helpers and emits REST shape; default forwards to ghx|gh GraphQL shape)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scm issue view {{.CLI_ARGS}}
+
+  issue:close:
+    desc: "[#883 stub] Close an issue -- task scm:issue:close -- <N> --repo OWNER/NAME [--comment ...]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scm issue close {{.CLI_ARGS}}
+
+  issue:edit:
+    desc: "[#883 stub] Edit an issue -- task scm:issue:edit -- <N> --repo OWNER/NAME [--add-label ...] [--body ...]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scm issue edit {{.CLI_ARGS}}
+
+  body:issue:create:
+    desc: "[#1555] Safely create an issue body from --body-file without shell Markdown interpolation"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" github-body issue-create {{.CLI_ARGS}}
+
+  body:issue:edit:
+    desc: "[#1555] Safely edit an issue body from --body-file and live gh read-back"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" github-body issue-edit {{.CLI_ARGS}}
+
+  body:comment:create:
+    desc: "[#1555] Safely create an issue/PR comment body from --body-file and live gh read-back"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" github-body comment-create {{.CLI_ARGS}}
+
+  body:comment:edit:
+    desc: "[#1555] Safely edit an issue comment body from --body-file and live gh read-back"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" github-body comment-edit {{.CLI_ARGS}}
+
+  body:pr:edit:
+    desc: "[#1555] Safely edit a PR body from --body-file and live gh read-back"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" github-body pr-edit {{.CLI_ARGS}}