@deftai/directive-content 0.55.2 → 0.56.0

package/tasks/ci.yml

@@ -0,0 +1,49 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# ci:* tasks for running the full CI pipeline locally so contributors
+# catch CI failures before pushing.
+#
+# ci:local mirrors the step graph of .github/workflows/ci.yml on the
+# host platform:
+#
+#   - Linux:   Python (uv sync + ruff + mypy + pytest --cov), Go test +
+#              cross-compile builds for linux/amd64 + darwin/arm64 +
+#              windows/amd64, and the existing Taskfile-level
+#              verifications (toolchain:check, verify:stubs,
+#              verify:links, verify:rule-ownership, vbrief:validate,
+#              build).
+#
+#   - macOS:   Same as Linux. The darwin/arm64 cross-compile is the
+#              native build path. /dev/null is the discard target for
+#              cross-compile output.
+#
+#   - Windows: Same Python + Go + Taskfile-level steps; NUL replaces
+#              /dev/null as the cross-compile discard target.
+#              Additionally, when --matrix=windows is supplied the
+#              Windows-task-dispatch regression pytest guard-rails run
+#              -- those steps shell out to PowerShell and require a
+#              real Windows host (CI uses windows-latest).
+#
+# CLI_ARGS are forwarded so contributors can pass flags such as
+# --matrix=linux, --skip-build, --verbose, and --no-fail-fast.
+#
+# Per conventions/task-caching.md, this task forwards {{.CLI_ARGS}} to
+# a Python script that accepts user-facing flags (--skip-build,
+# --no-fail-fast, etc.); declaring sources: / generates: would short-
+# circuit the cmds: block and silently swallow those flags. Caching is
+# intentionally absent.
+#
+# Companion script: scripts/ci_local.py
+# Companion test:   tests/cli/test_ci_local.py
+
+tasks:
+  local:
+    desc: "Run the full CI pipeline locally (matrix-aware). Mirrors .github/workflows/ci.yml step graph; on Windows hosts --matrix=windows additionally runs the windows-task-dispatch regression guard-rails. Refs #233."
+    dir: '{{.USER_WORKING_DIR}}'
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/scripts/ci_local.py" --root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}

package/tasks/codebase.yml

@@ -0,0 +1,47 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  validate-structure:
+    desc: "Validate authored codeStructure metadata and PR3 discipline rules (#1595)."
+    dir: '{{.USER_WORKING_DIR}}'
+    # Per conventions/task-caching.md: no sources/generates because this task
+    # forwards user-supplied paths and project-root flags via CLI_ARGS.
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" code-structure-validate --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  extract-default:
+    desc: "Emit the dependency-free default codebase-map artifact to stdout (#1595 PR3)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" codebase-default-extractor --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  provider-map:
+    desc: "Select an external codebase-map provider or fall back to the default artifact (#1595 PR3)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" codebase-provider --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  map:
+    desc: "Generate .planning/codebase/MAP.md from the selected codebase-map artifact (#1595 PR4)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" codebase-map --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  projection-registry:
+    desc: "Inspect registered codebase projection kinds (#1595 PR3)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" codebase-projection-registry {{.CLI_ARGS}}

package/tasks/commit.yml

@@ -0,0 +1,30 @@
+version: '3'
+
+vars:
+  # Per ../Taskfile.yml header: joinPath is evaluated eagerly by go-task
+  # templating and yields a native-separator absolute path so {{.DEFT_ROOT}}
+  # resolves correctly under uv on Windows (#566). Used here to pin
+  # `uv --project` against ancestor pyproject.toml leakage (#1011).
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  commit:lint:
+    desc: Validate HEAD commit message against conventional commit format
+    cmds:
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c
+          "import sys, re, subprocess;
+          result = subprocess.run(['git', 'log', '--format=%B', '-1'], capture_output=True, text=True);
+          (result.returncode != 0) and (print('FAIL: Could not read HEAD commit message'), sys.exit(1));
+          msg = result.stdout.strip();
+          subject = msg.splitlines()[0] if msg else '';
+          types = 'feat|fix|docs|chore|refactor|test|style|perf|ci|build|revert';
+          pattern = r'^(' + types + r')(\(.+\))?!?: .+';
+          ok = re.match(pattern, subject);
+          (not ok) and (print('FAIL: Commit message does not match conventional commit format'),
+          print(f'  Got:      {subject}'),
+          print(f'  Expected: type(scope): description'),
+          print(f'  Types:    feat, fix, docs, chore, refactor, test, style, perf, ci, build, revert'),
+          sys.exit(1));
+          print(f'OK: Commit message is valid conventional commit');
+          print(f'  Subject: {subject}')"

package/tasks/core.yml

@@ -0,0 +1,126 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  validate:
+    desc: Validate all markdown files
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c "from pathlib import Path;
+          files=[f for f in sorted(Path('.').rglob('*.md')) if '.git' not in f.parts and 'backup' not in f.parts];
+          [print(f'\u2713 {f}') for f in files];
+          print(f'\u2713 All {len(files)} markdown files validated')"
+
+  test:
+    desc: Run test suite
+    cmds:
+      # #1474: tolerate a missing tests/ directory. The installer (#1482)
+      # prunes the vendored .deft/core/tests/ from the consumer deposit, so in
+      # a vendored consumer `task deft:check` -> framework check -> core:test
+      # would otherwise run `pytest tests/` against a now-absent directory and
+      # exit with a path error instead of 0 (blocking #1474 acceptance a1).
+      # A cross-platform pathlib guard (no bare shell conditional, per the
+      # AGENTS.md Windows rules) skips the run with a clear notice when tests/
+      # is absent; the framework's own repo (tests/ present) still runs the
+      # full suite unchanged. The check targets the same CWD-relative `tests`
+      # path pytest would run against, so it is correct regardless of CWD.
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c "import sys, subprocess;
+          from pathlib import Path;
+          _exists = Path('tests').exists();
+          print('no tests/ (vendored consumer) -- skipping') if not _exists else None;
+          sys.exit(subprocess.run([sys.executable, '-m', 'pytest', 'tests']).returncode if _exists else 0)"
+
+  test:coverage:
+    desc: Run tests with coverage (fails if < 85%)
+    cmds:
+      - uv --project "{{.DEFT_ROOT}}" run pytest tests/ --cov --cov-report=html
+
+  fmt:
+    desc: Format Python code
+    cmds:
+      - uv --project "{{.DEFT_ROOT}}" run ruff format .
+      - uv --project "{{.DEFT_ROOT}}" run black .
+
+  lint:
+    desc: Lint and type-check Python code
+    cmds:
+      - uv --project "{{.DEFT_ROOT}}" run ruff check .
+      # #1475: bring the local type-check gate to parity with CI. The CI
+      # Python job (.github/workflows/ci.yml) runs `mypy tests/`, but this
+      # local gate previously checked only run.py -- so a type error under
+      # tests/ shipped green locally (task check -> core:lint) and reddened
+      # master after merge. The tests/ tree is now part of the gate; run.py
+      # is retained for its pre-existing local-only coverage. Both surfaces
+      # share the [tool.mypy] config in pyproject.toml, including the
+      # tests.* override that relaxes disallow_untyped_defs while still
+      # failing on real type mismatches under tests/.
+      #
+      # #1474: the same vendored-consumer guard core:test uses. The installer
+      # (#1482) prunes the vendored .deft/core/tests/, and `task deft:check`
+      # runs core:lint too, so an unconditional `mypy run.py tests/` would
+      # fail on the now-absent tests/ path. The cross-platform pathlib guard
+      # (no bare shell conditional, per the AGENTS.md Windows rules) appends
+      # tests/ to the mypy target list only when it exists; run.py (always in
+      # the payload) stays checked either way.
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c "import sys, subprocess;
+          from pathlib import Path;
+          targets = ['run.py'] + (['tests'] if Path('tests').exists() else []);
+          sys.exit(subprocess.run([sys.executable, '-m', 'mypy', *targets]).returncode)"
+
+
+  build:
+    desc: Package framework for distribution (cross-platform via Python helper, #736)
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      # Single cross-platform dispatch (#736). The Python helper uses
+      # stdlib tarfile / zipfile with a canonical exclude list and
+      # auto-selects tar.gz on Linux/macOS, zip on Windows. The previous
+      # platform-split shape had the Windows branch missing the exclude
+      # list, ingesting .git history and the prior dist/ artifact.
+      # Regression-guarded by tests/content/test_taskfile_zip_parity.py.
+      - uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/scripts/build_dist.py" --version "{{.VERSION}}"
+
+  clean:
+    desc: Clean generated artifacts (cross-platform via Python helper, #736)
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      # Single cross-platform dispatch (#736) -- mirrors the build target's
+      # simplification. Python's pathlib + shutil.rmtree handles the dist/
+      # directory removal identically on POSIX and Windows, replacing the
+      # prior rm -rf / Remove-Item duplication.
+      #
+      # The dist/ path is anchored at {{.DEFT_ROOT}} so `task clean` works
+      # the same way regardless of the operator's current working directory.
+      # The previous shape relied on `pathlib.Path('dist')` resolving against
+      # the inherited CWD, which silently no-ops when the operator runs
+      # `task -t tasks/core.yml clean` from a subdirectory (Greptile P2 on
+      # PR #773).
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c "import shutil, pathlib;
+          d = pathlib.Path(r'{{.DEFT_ROOT}}') / 'dist';
+          shutil.rmtree(d) if d.exists() else None;
+          print(f'Cleaned {d}')"
+
+  stats:
+    desc: Show framework statistics
+    cmds:
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c "from pathlib import Path;
+          v='{{.VERSION}}';
+          sep='='*42;
+          dirs=[('Core files','core'),('Languages','languages'),('Interfaces','interfaces'),('Tools','tools'),('Templates','templates')];
+          counts=[(n,len(list(Path(d).glob('*.md')))) for n,d in dirs];
+          total=len([f for f in Path('.').rglob('*.md') if '.git' not in str(f) and 'backup' not in str(f)]);
+          print(f'Deft Framework v{v} Statistics:');
+          print(sep);
+          [print(f'{n}: {c}') for n,c in counts];
+          print(f'Total files: {total}');
+          print(sep)"

package/tasks/deployments.yml

@@ -0,0 +1,54 @@
+version: '3'
+
+set: [errexit, nounset, pipefail]
+
+vars:
+  CLOUDGOV_VERSION: v1.1.0
+  CLOUDGOV_UPSTREAM_DIR: deployments/cloud-gov/upstream
+  CLOUDGOV_EXPORT_DIR: .deft/cloud.gov
+  CLOUDGOV_ARCHIVE: '{{.CLOUDGOV_UPSTREAM_DIR}}/cloud-gov-instructions-{{.CLOUDGOV_VERSION}}.tar.gz'
+  CLOUDGOV_EXTRACT_DIR: '{{.CLOUDGOV_UPSTREAM_DIR}}/cloud-gov-instructions-1.1.0'
+
+tasks:
+  cloudgov:sync:
+    desc: Sync pinned cloud-gov-instructions release to deployments/cloud-gov/upstream
+    cmds:
+      - mkdir -p {{.CLOUDGOV_UPSTREAM_DIR}}
+      - curl -L https://github.com/adhocteam/cloud-gov-instructions/archive/refs/tags/{{.CLOUDGOV_VERSION}}.tar.gz -o {{.CLOUDGOV_ARCHIVE}}
+      - tar -xzf {{.CLOUDGOV_ARCHIVE}} -C {{.CLOUDGOV_UPSTREAM_DIR}}
+    generates:
+      - '{{.CLOUDGOV_ARCHIVE}}'
+      - '{{.CLOUDGOV_EXTRACT_DIR}}'
+
+  cloudgov:export:
+    desc: Export Copilot-ready cloud.gov instructions to .deft/cloud.gov
+    vars:
+      OUT_DIR: '{{.OUT_DIR | default .CLOUDGOV_EXPORT_DIR}}'
+    cmds:
+      - mkdir -p {{.OUT_DIR}}/.github/instructions {{.OUT_DIR}}/.github/agents {{.OUT_DIR}}/.github/skills
+      - cp deployments/cloud-gov/overview.md {{.OUT_DIR}}/.github/copilot-instructions.md
+      - cp deployments/cloud-gov/deployment.md {{.OUT_DIR}}/.github/instructions/deployment.instructions.md
+      - cp deployments/cloud-gov/manifest.md {{.OUT_DIR}}/.github/instructions/manifest.instructions.md
+      - cp deployments/cloud-gov/services.md {{.OUT_DIR}}/.github/instructions/services.instructions.md
+      - cp deployments/cloud-gov/cicd.md {{.OUT_DIR}}/.github/instructions/cicd.instructions.md
+      - cp deployments/cloud-gov/security.md {{.OUT_DIR}}/.github/instructions/security.instructions.md
+      - cp deployments/cloud-gov/logging.md {{.OUT_DIR}}/.github/instructions/logging.instructions.md
+      - cp deployments/cloud-gov/agents.md {{.OUT_DIR}}/AGENTS.md
+      - cp deployments/cloud-gov/agents/compliance-docs.md {{.OUT_DIR}}/.github/agents/compliance-docs.agent.md
+      - cp deployments/cloud-gov/skills/cf-troubleshoot.md {{.OUT_DIR}}/.github/skills/cf-troubleshoot.md
+      - cp deployments/cloud-gov/LICENSE.md {{.OUT_DIR}}/LICENSE.md
+    sources:
+      - deployments/cloud-gov/**/*.md
+    generates:
+      - '{{.OUT_DIR}}/.github/copilot-instructions.md'
+      - '{{.OUT_DIR}}/.github/instructions/deployment.instructions.md'
+      - '{{.OUT_DIR}}/.github/instructions/manifest.instructions.md'
+      - '{{.OUT_DIR}}/.github/instructions/services.instructions.md'
+      - '{{.OUT_DIR}}/.github/instructions/cicd.instructions.md'
+      - '{{.OUT_DIR}}/.github/instructions/security.instructions.md'
+      - '{{.OUT_DIR}}/.github/instructions/logging.instructions.md'
+      - '{{.OUT_DIR}}/.github/agents/compliance-docs.agent.md'
+      - '{{.OUT_DIR}}/.github/skills/cf-troubleshoot.md'
+      - '{{.OUT_DIR}}/AGENTS.md'
+      - '{{.OUT_DIR}}/LICENSE.md'
+    method: checksum

package/tasks/framework.yml

@@ -0,0 +1,74 @@
+version: '3'
+
+# tasks/framework.yml -- framework-level introspection / upkeep tasks (#801).
+#
+# Hosts surfaces that interrogate the deft framework itself (rather than the
+# consumer project). Currently only `framework:check-updates`, but this is
+# the natural home for any future "is the deft framework healthy / current"
+# probe (e.g. submodule SHA reconcile, .deft/core/run version vs marker, etc.).
+#
+# Per `conventions/task-caching.md` (#574): the check-updates task accepts a
+# user-facing `--force` recovery flag (mapped to DEFT_FORCE_REMOTE_PROBE=1)
+# and therefore MUST NOT declare `sources:` / `generates:` -- the cached
+# `cmds:` skip would silently discard the recovery flag.
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  check-updates:
+    desc: "Read-only remote-version probe (#801) -- task framework:check-updates [-- --force | --json]. Honors DEFT_NO_NETWORK=1 and DEFT_REMOTE_PROBE_TIMEOUT (default 5s)."
+    dir: '{{.USER_WORKING_DIR}}'
+    env:
+      PYTHONUTF8: "1"
+      # When the operator passes `--force`, the task wrapper sets
+      # DEFT_FORCE_REMOTE_PROBE=1 so the gate-integration helper bypasses
+      # the 24h throttle. The `run` CLI surface (`run check-updates`) is
+      # already idempotent (does not write to the throttle file), so this
+      # env var only affects callers that probe through the upgrade gate.
+      DEFT_FORCE_REMOTE_PROBE: '{{if (mustRegexMatch "(^|\\s)--force(\\s|$)" .CLI_ARGS)}}1{{else}}{{.DEFT_FORCE_REMOTE_PROBE | default ""}}{{end}}'
+    cmds:
+      # Strip our own `--force` from the args we pass through to `run` so it
+      # does not surface as an unknown flag in the JSON / text output. Other
+      # supported flags (e.g. `--json`) flow through unchanged.
+      #
+      # #1059: invoke Python through `uv --project "{{.DEFT_ROOT}}" run python`
+      # rather than a bare `python3`. On Windows the bare `python3` command
+      # resolves to the Microsoft Store app-execution-alias stub (exit 49) on
+      # default-configured hosts where the user installed Python via the
+      # official installer, so the wrapper aborted before `run check-updates`
+      # ever started. The `uv` wrapper matches the canonical pattern used by
+      # every other tasks/*.yml file (see e.g. `tasks/prd.yml`,
+      # `tasks/vbrief.yml`) and pins the project root via #1011 so the
+      # uv environment never walks up into a hostile ancestor pyproject.
+      - >-
+        uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/run" check-updates
+        {{regexReplaceAll "(^|\\s)--force(\\s|$)" .CLI_ARGS " "}}
+
+  doctor:
+    # #1272: the legacy ``task framework:doctor`` surface is REDACTED.
+    # ``task doctor`` (root Taskfile.yml shim for ``.deft/core/run doctor``)
+    # is now the canonical doctor entry point and owns the install-integrity
+    # probe, the root Taskfile.yml include diagnostics, and the optional
+    # interactive repair path. This shim prints a single-line redaction
+    # notice and exits 0 so legacy callers do not crash, while operators are
+    # nudged at the canonical surface. The Python probe at
+    # ``scripts/framework_doctor.py`` is still exercised internally by the
+    # upgrade gate's ``_maybe_run_framework_doctor`` advisory; nothing about
+    # that pathway changes.
+    desc: "Deprecated doctor surface (#1272) -- prints redaction; use `task doctor` (or `.deft/core/run doctor`) instead."
+    dir: '{{.USER_WORKING_DIR}}'
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      # Cross-platform redaction line. go-task runs every ``cmd:`` through
+      # its embedded mvdan/sh POSIX-sh interpreter on every host (Windows,
+      # macOS, Linux), so a single ``echo`` invocation is portable and
+      # strips the surrounding quotes uniformly -- emitting exactly:
+      #     redacted use run doctor instead
+      # The previous Windows branch shelled out to ``pwsh`` (PowerShell 7+),
+      # which is NOT present on stock Windows 10 / 11 (only ``powershell.exe``
+      # ships out of the box) so any consumer without PowerShell 7+ installed
+      # would see ``pwsh: not found`` instead of the redaction notice. Letting
+      # mvdan/sh handle the echo sidesteps the shell-dependence entirely.
+      - echo "redacted use run doctor instead"

package/tasks/install.yml

@@ -0,0 +1,60 @@
+version: '3'
+
+vars:
+  # Per ../Taskfile.yml header: joinPath is evaluated eagerly by go-task
+  # templating and yields a native-separator absolute path so {{.DEFT_ROOT}}
+  # resolves correctly under uv on Windows (#566). Used here to pin
+  # `uv --project` against ancestor pyproject.toml leakage (#1011).
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  install:
+    desc: Install deft (dev convenience -- end users should use the compiled binary from GitHub Releases)
+    cmds:
+      - go run ./cmd/deft-install/
+
+  uninstall:
+    desc: Remove deft entry from AGENTS.md
+    cmds:
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c "from pathlib import Path;
+          f=Path('AGENTS.md');
+          t=f.read_text('utf-8') if f.exists() else '';
+          lines=t.splitlines(keepends=True);
+          out=''.join(l for l in lines if not l.startswith('See deft/main.md') and not l.startswith('Skills: deft/skills/'));
+          f.write_text(out,'utf-8') if f.exists() else None;
+          print('Removed deft entry from AGENTS.md' if out!=t else 'No deft entry found in AGENTS.md')"
+
+  # User-facing upgrade entrypoint (#1061). Wraps the canonical
+  # ``run upgrade`` command (`cmd_upgrade` in ./run) which:
+  #   1. Writes / refreshes the bare ``.deft-version`` marker.
+  #   2. Writes the canonical YAML provenance manifest at
+  #      ``<install>/VERSION`` (#1046 PR-B AC-4) -- including the
+  #      ``install_root`` field added in #1062.
+  #   3. Delegates to ``cmd_agents_refresh`` so the AGENTS.md managed
+  #      section is brought to the current rendered template (v3 marker
+  #      with sha/refreshed/session attributes, #1046 PR-B AC-5).
+  # This wrapper exists so the ``framework:doctor`` failure prose and
+  # ``docs/install-manifest.md`` can cite a real Taskfile target rather
+  # than a raw ``run`` invocation. Idempotent on re-run: a second
+  # invocation against a current manifest + AGENTS.md is a no-op.
+  #
+  # Per ``conventions/task-caching.md`` (#574): no ``sources:`` /
+  # ``generates:`` because the task is mutating + must run on every
+  # invocation. CLI_ARGS is explicitly cleared (``vars: { CLI_ARGS: "" }``)
+  # so any operator-supplied ``-- <flags>`` are deterministically dropped
+  # before reaching ``run upgrade``: go-task only forwards ``{{.CLI_ARGS}}``
+  # when a ``cmds`` line references it, but pinning the var to empty makes
+  # the contract explicit AND defends against a future edit that
+  # accidentally appends ``{{.CLI_ARGS}}`` to the dispatch line (SLizard P1
+  # on PR #1067 -- ``cmd_upgrade`` does not currently accept flags; future
+  # flag additions land deliberately, not implicitly via Taskfile drift).
+  upgrade:
+    desc: "Upgrade deft framework: refresh AGENTS.md to current marker, write canonical install manifest, regenerate .deft-version derivative (#1061). Wraps `run upgrade`."
+    dir: '{{.USER_WORKING_DIR}}'
+    env:
+      PYTHONUTF8: "1"
+    vars:
+      CLI_ARGS: ""
+    cmds:
+      - uv --project "{{.DEFT_ROOT}}" run python "{{.DEFT_ROOT}}/run" upgrade

package/tasks/issue.yml

@@ -0,0 +1,50 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# issue ingest task.
+#
+# IMPORTANT: runs from the consumer project root (``dir:
+# '{{.USER_WORKING_DIR}}'``) so ``gh`` and ``git`` commands executed by
+# ``scripts/issue_ingest.py`` resolve against the CONSUMER's remote, not
+# deftai/directive (#538). The explicit ``--project-root`` flag makes the
+# intent clear to the script and gives it a stable anchor even if Task's
+# ``dir:`` semantics ever change. 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 issue gates (#1828 s4)"
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pnpm --dir "{{.DEFT_ROOT}}" run build
+
+  ingest:
+    desc: "Ingest GitHub issues as scope vBRIEFs (single <N> or --all [--label L] [--status S] [--dry-run])"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ensure-ts
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" issue-ingest --vbrief-dir "{{.USER_WORKING_DIR}}/vbrief" --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  # issue emit task -- the write-direction counterpart to issue:ingest
+  # (#1274 Change 2). Files GitHub issue(s) from scope vBRIEFs and records
+  # the issue URL back into each vBRIEF's references[]. Runs from the
+  # consumer project root (``dir: '{{.USER_WORKING_DIR}}'``) so ``gh`` /
+  # ``git`` resolve against the CONSUMER's remote, not deftai/directive
+  # (#538); --project-root anchors repo detection and glob expansion.
+  # Honors --dry-run AND DEFT_NO_NETWORK=1 (plan only; no forge write).
+  emit:
+    desc: "File GitHub issue(s) from scope vBRIEF(s) (<path> | --umbrella <glob> | --per-vbrief <glob> [--dry-run])"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps: [":ts:build"]
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" issue-emit --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}

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