@deftai/directive-content 0.55.1 → 0.56.0

package/tasks/capacity.yml

@@ -0,0 +1,38 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# Capacity allocation accounting surface (#1419 Delivery Slice 4).
+#
+# `task capacity:show` derives per-bucket target-vs-actual mix from the vBRIEF
+# lifecycle folders (filesystem-truth, offline) with outcome (rework) and cost
+# overlays, and renders advisory mode when classified completions are below
+# minSampleSize. It is a DISPLAY surface and always exits 0 on a valid project
+# root (the companion `task verify:capacity` in tasks/verify.yml is the
+# three-state advisory gate).
+#
+# Conventions (mirroring tasks/scope.yml / tasks/verify.yml):
+#  * `dir: '{{.USER_WORKING_DIR}}'` so the script's CWD is the consumer project
+#    root, not deft/.
+#  * `DEFT_ROOT` defined locally via joinPath so the script path resolves on
+#    Windows (#566).
+#  * `{{.CLI_ARGS}}` forwarded bare (no double quotes, #577) and NO `sources:` /
+#    `generates:` so go-task does not swallow flags (#574 / conventions/
+#    task-caching.md).
+tasks:
+  show:
+    desc: "Capacity allocation target-vs-actual mix (advisory, offline). task capacity:show [-- --project-root <path>]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" capacity-show --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  backfill:
+    desc: "One-time capacity-bucket backfill for completed vBRIEFs (#1606): infer capacityBucket from origin-issue labels + stamp completedAt from git. Dry-run by default; idempotent; never touches cost. -- task capacity:backfill [-- --apply] [--window-only] [--cache-dir <path>] [--json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" capacity-backfill --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}

package/tasks/change.yml

@@ -0,0 +1,46 @@
+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:
+  changelog:check:
+    desc: Verify CHANGELOG.md has an [Unreleased] section with at least one entry
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c
+          "import sys, pathlib, re;
+          p = pathlib.Path('CHANGELOG.md');
+          (not p.exists()) and (print('FAIL: CHANGELOG.md not found'), sys.exit(1));
+          text = p.read_text('utf-8');
+          m = re.search(r'## \[Unreleased\][ \t]*\n(.*?)(?=\n## \[|$)', text, re.DOTALL);
+          (m is None) and (print('FAIL: No [Unreleased] section found in CHANGELOG.md'), sys.exit(1));
+          body = m.group(1);
+          entries = [l for l in body.splitlines() if l.strip().startswith('- ')];
+          (len(entries) == 0) and (print('FAIL: [Unreleased] section has no entries (no lines starting with \"- \")'), sys.exit(1));
+          print(f'OK: CHANGELOG.md [Unreleased] section has {len(entries)} entries')"
+
+  change:init:
+    desc: Create a new change proposal directory structure in history/changes/<name>/
+    cmds:
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c
+          "import sys, pathlib, json, re;
+          name = '{{.CLI_ARGS}}'.strip();
+          (not name) and (print('FAIL: Usage: task change:init -- <name>'), sys.exit(1));
+          (not re.match(r'^[\w][\w-]*$', name)) and (print('FAIL: Name must contain only alphanumeric characters, underscores, and hyphens'), sys.exit(1));
+          base = pathlib.Path('history/changes') / name;
+          base.exists() and (print(f'FAIL: {base} already exists'), sys.exit(1));
+          (base / 'specs').mkdir(parents=True, exist_ok=True);
+          proposal = {'vBRIEFInfo': {'version': '0.5'}, 'plan': {'title': name, 'status': 'draft', 'narratives': {'Problem': 'What is wrong or missing.', 'Change': 'What this proposal does about it.', 'Scope': 'In scope: ...  Out of scope: ...', 'Impact': 'What existing code/specs are affected.', 'Risks': 'What could go wrong.', 'Approach': 'How to implement the change.', 'Alternatives': 'What else was considered and why not.', 'Dependencies': 'What must exist before this works.'}}};
+          (base / 'proposal.vbrief.json').write_text(json.dumps(proposal, indent=2) + chr(10), encoding='utf-8');
+          tasks = {'vBRIEFInfo': {'version': '0.5'}, 'plan': {'title': name, 'status': 'draft', 'items': [], 'edges': []}};
+          (base / 'tasks.vbrief.json').write_text(json.dumps(tasks, indent=2) + chr(10), encoding='utf-8');
+          print(f'OK: Created change proposal at {base}/');
+          [print(f'  - {f}') for f in ['proposal.vbrief.json', 'tasks.vbrief.json', 'specs/']]"

package/tasks/changelog.yml

@@ -0,0 +1,24 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# Surface for the CHANGELOG.md union-merge helper (#911).
+#
+# Wraps scripts/resolve_changelog_unreleased.py, the canonical swarm-cascade
+# Phase 6 Step 1 helper that replaces the older HEAD-take-and-discard pattern
+# silently dropping rebasing-branch CHANGELOG entries on every cascade rebase.
+# See skills/deft-directive-swarm/SKILL.md Phase 6 Step 1 for the manual-
+# fallback contract -- this task is the canonical-path alternative.
+#
+# Per `conventions/task-caching.md` (#574): no `sources:` / `generates:`
+# because the task forwards user-facing flags via {{.CLI_ARGS}} (notably
+# --changelog-path / --dry-run / --quiet). The cached `cmds:` skip would
+# silently discard a recovery flag, and the helper is fast enough that a
+# real-time invocation does not need incremental-build caching.
+tasks:
+  resolve-unreleased:
+    desc: "Union-merge CHANGELOG.md [Unreleased] conflicts (#911) -- task changelog:resolve-unreleased [-- --changelog-path PATH] [--dry-run]"
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" changelog-resolve-unreleased {{.CLI_ARGS}}

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