@deftai/directive-content 0.55.2 → 0.56.1

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

package/tasks/scope-undo.yml

@@ -0,0 +1,36 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# scope:undo fragment (D15 / #1134).
+#
+# Standalone fragment per the post-D12 sub-task convention so the
+# orchestrator's cross-child coordination contract does not collide
+# with edits on tasks/scope.yml. The user-facing alias `task scope:undo`
+# lives in the root Taskfile.yml below; this fragment exposes the inner
+# task name `undo` under the include namespace key `scope-undo`, so the
+# fragment-namespace form `task scope-undo:undo` is also reachable for
+# debugging but is not the documented surface.
+#
+# CLI_ARGS forwarded bare (matches every other scope:* verb -- go-task's
+# shell-escape pipeline misbehaves on Windows when CLI_ARGS is wrapped
+# in double quotes, see #577).
+#
+# `dir: '{{.USER_WORKING_DIR}}'` keeps Python CWD at the consumer project
+# root so `--project-root "{{.USER_WORKING_DIR}}"` resolves correctly
+# (#535 path-resolution invariant).
+#
+# `env: PYTHONUTF8: "1"` is a belt-and-suspenders guard for Windows cp1252
+# default (#540); root Taskfile.yml also sets this.
+#
+# Per `conventions/task-caching.md` (#574) no `sources:` / `generates:`
+# because the verb forwards user-facing flags (`--dry-run` / `--batch-id` /
+# `--decision-id`) via {{.CLI_ARGS}}.
+
+tasks:
+  undo:
+    desc: "Reverse a scope-lifecycle audit entry (#1134). Single: `task scope:undo -- <decision_id>` / `task scope:undo -- --decision-id=<uuid>`. Batch: `task scope:undo -- --batch-id=<uuid>`. Optional `--dry-run`."
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-undo {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"

package/tasks/scope.yml

@@ -0,0 +1,141 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# scope lifecycle tasks.
+#
+# IMPORTANT: every task sets ``dir: '{{.USER_WORKING_DIR}}'`` so the Python
+# script's CWD is the consumer project root, NOT ``deft/``. The script path
+# is resolved via ``{{.DEFT_ROOT}}/scripts/`` (DEFT_ROOT is defined locally
+# in this file's `vars:` block via ``{{joinPath .TASKFILE_DIR ".."}}`` --
+# see ../Taskfile.yml for why root-level definition is avoided) so it
+# still points at ``deft/scripts/scope_lifecycle.py`` after the dir switch.
+# The previous ``{{.TASKFILE_DIR}}/../scripts/`` form broke on Windows
+# under `uv --project "{{.DEFT_ROOT}}" run python` (#566) because mixed-separator traversal
+# normalizes incorrectly and drops the deft/ prefix.
+#
+# CLI_ARGS: passed to the script raw / unquoted. go-task shell-escapes
+# CLI_ARGS with single quotes on its own, so wrapping the interpolation
+# in Taskfile-level double quotes produces ``"'path'"`` at dispatch time
+# on Windows (pwsh/cmd preserve nested quotes verbatim), and Python's
+# argv receives a literal single-quote-prefixed filename that fails to
+# open (#577). All seven scope:* commands therefore forward
+# ``{{.CLI_ARGS}}`` bare -- matching migrate.yml / prd.yml / issue.yml /
+# reconcile.yml.  ``scope_lifecycle.py`` handles both absolute and
+# relative values via ``_resolve_file_path`` + ``resolve_project_root``
+# -- the script owns path resolution, the task just forwards
+# ``--project-root`` so detection never silently falls back to deft's
+# own tree (#535). Relative paths resolve against the consumer root
+# thanks to ``--project-root``; absolute paths are used as-is.
+#
+# ``env: PYTHONUTF8: "1"`` is set per-task as a belt-and-suspenders guard
+# for Windows (cp1252 default crashes on -- / -> / x / !); the top-level
+# Taskfile.yml also sets this (#540).
+
+tasks:
+  _ensure-ts:
+    internal: true
+    desc: "Build the TS engine before lifecycle gates (#1828 s4)"
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
+  promote:
+    desc: "Promote a vBRIEF scope: proposed/ -> pending/ (status: pending)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-lifecycle promote {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  activate:
+    desc: "Activate a vBRIEF scope: pending/ -> active/ (status: running)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-lifecycle activate {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  complete:
+    desc: "Complete a vBRIEF scope: active/ -> completed/ (status: completed)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-lifecycle complete {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  fail:
+    # Terminal ``failed`` transition (#614). Parallels ``scope:complete``
+    # (same source + destination folders) and differs only in the
+    # resulting ``plan.status`` (``failed`` vs ``completed``). Semantic
+    # contract: use ``scope:fail`` when a scope was attempted but could
+    # not be completed (external blocker, infeasibility discovered
+    # mid-flight, deadline hit, agent exhausted retries) and should NOT
+    # be cancelled. ``scope:cancel`` remains the right call when the
+    # scope is no longer wanted / superseded / obsolete. The canonical
+    # v0.6 Status enum includes ``failed`` (see
+    # vbrief/schemas/vbrief-core.schema.json).
+    desc: "Fail a vBRIEF scope: active/ -> completed/ (status: failed)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-lifecycle fail {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  cancel:
+    desc: "Cancel a vBRIEF scope: any folder -> cancelled/ (status: cancelled)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-lifecycle cancel {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  restore:
+    desc: "Restore a cancelled vBRIEF scope: cancelled/ -> proposed/ (status: proposed)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-lifecycle restore {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  block:
+    desc: "Block a vBRIEF scope: stays in active/ (status: blocked)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-lifecycle block {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  unblock:
+    desc: "Unblock a vBRIEF scope: stays in active/ (status: running)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-lifecycle unblock {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  decompose:
+    desc: "Apply/check an approved epic/phase -> story decomposition draft"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-decompose {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"
+
+  # Operator-driven demote (D1 / #1121). Moves a vBRIEF scope from
+  # vbrief/pending/ back to vbrief/proposed/ and appends a structured
+  # audit entry (including a `demote_meta` block) to
+  # vbrief/.eval/scope-lifecycle.jsonl. Two modes are supported:
+  #   * Single: `task scope:demote -- path/to/foo.vbrief.json [--reason TEXT]`
+  #   * Batch:  `task scope:demote -- --batch [--older-than-days 45]`
+  # The 30%-threshold falsification gate from D17 was explicitly dropped
+  # per Current Shape Decision 2 on #1121; lightweight metrics over the
+  # audit log live separately at #1180.
+  demote:
+    desc: "Demote a vBRIEF scope: pending/ -> proposed/ (#1121). Single-file or --batch --older-than-days N (default 45)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" scope-demote {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"