@deftai/directive-content 0.55.1 → 0.56.0

package/tasks/vbrief.yml

@@ -0,0 +1,206 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  _ts-build:
+    internal: true
+    desc: "Build @deftai/cli dist/ before TS-backed gates run (#1828 s2)."
+    dir: '{{.DEFT_ROOT}}'
+    cmds:
+      - pnpm run build
+
+  validate:
+    desc: Validate vBRIEF lifecycle folder structure and cross-file consistency
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      # Oracle/fallback (parity): scripts/vbrief_validate.py (#1828 Wave 8).
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief:validate --vbrief-dir "{{.USER_WORKING_DIR}}/vbrief"
+
+  preflight:
+    # Implementation-intent preflight wrapper (#810 / PR #812 fixup;
+    # #1046 PR-C / #1047 fail-closed resolver). Skill files
+    # (skills/deft-directive-build/SKILL.md Step 0,
+    # skills/deft-directive-swarm/SKILL.md Phase 0 Step 1) and the
+    # AGENTS.md template (templates/agents-entry.md Implementation Intent
+    # Gate block) reference THIS task rather than the underlying Python
+    # script directly so the skills are path-prefix-agnostic across the
+    # three supported install layouts:
+    #
+    #   1. ``.deft/core/scripts/...`` (v0.27+ canonical install per #992)
+    #   2. ``deft/scripts/...``       (legacy v0.20-v0.26 install)
+    #   3. ``scripts/...``            (in-repo case: deft framework itself)
+    #
+    # The wrapped ``preflight_implementation.py`` script is located
+    # via ``scripts/_resolve_preflight_path.py`` (#1046 PR-C / #1047),
+    # which probes the three candidate locations under
+    # ``{{.USER_WORKING_DIR}}`` in priority order and exits 2 with a
+    # structured ``gate misconfigured`` error pointing at
+    # ``task framework:doctor`` (#1046 PR-B / #1057) when no candidate
+    # resolves. The two-step invocation (resolve, then run) makes the
+    # fail-closed semantic explicit: if the resolver returns non-zero
+    # the inline ``sh:`` block exits with the same code BEFORE the
+    # downstream ``uv run python <script>`` ever fires, so the gate
+    # never silently fails open on a misconfigured install (the safety
+    # regression #1047 described).
+    #
+    # The resolver script ITSELF is dispatched via ``{{.DEFT_ROOT}}``
+    # (the Taskfile-relative install root) so it lives wherever the
+    # framework lives -- the resolver then probes the consumer's
+    # project root via ``{{.USER_WORKING_DIR}}``.
+    #
+    # The task bakes ``--vbrief-path`` so callers pass only the vBRIEF
+    # path: ``task vbrief:preflight -- <path>``.
+    #
+    # CLI_ARGS forwarding (#577): bare ``{{.CLI_ARGS}}`` -- DO NOT wrap
+    # in Taskfile-level double quotes. go-task already shell-escapes
+    # CLI_ARGS with single quotes, so wrapping in double quotes yields
+    # ``"'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. This matches
+    # the convention enforced by tests/content/test_taskfile_cli_args.py
+    # and used in tasks/scope.yml / migrate.yml / prd.yml / etc.
+    # (Greptile P2 suggestion to quote was a false-positive against this
+    # project's established convention.)
+    #
+    # NOTE: NO ``sources:`` / ``generates:`` per ``conventions/task-caching.md``
+    # because the vBRIEF path is a user-facing argument forwarded via
+    # {{.CLI_ARGS}} and a cached cmds skip would silently swallow it.
+    desc: "Preflight an implementation-intent gate (#810): exits 0 only when vBRIEF is in vbrief/active/ AND plan.status == 'running'. Fails closed (#1046 PR-C / #1047) if the wrapped script cannot be resolved."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      # Oracle/fallback (parity): scripts/preflight_implementation.py (#1828 Wave 8).
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief:preflight --vbrief-path {{.CLI_ARGS}}
+
+  reconcile:graph:
+    # Cascade-unblock walker (#1287). Walks vbrief/proposed/, resolves each
+    # candidate's plan.metadata.swarm.depends_on[] against current lifecycle
+    # state, and promotes (proposed/ -> pending/ via scope_lifecycle) every
+    # candidate whose dependencies ALL resolve to a brief in completed/ or
+    # cancelled/. Pure-vBRIEF / forge-agnostic: reuses the swarm_readiness.py
+    # dep-graph + cycle machinery and the scope_lifecycle promote surface.
+    # WIP-cap aware, cycle-safe (exit 1 on a detected cycle), and idempotent
+    # (a second run is a no-op). Pass-through flags: --force (override the WIP
+    # cap, audited), --dry-run (report without moving), --json (machine
+    # summary).
+    #
+    # CLI_ARGS forwarding (#577): bare ``{{.CLI_ARGS}}`` -- DO NOT wrap in
+    # Taskfile-level double quotes. go-task already shell-escapes CLI_ARGS
+    # with single quotes; double-wrapping breaks Windows argv. See the
+    # preflight task below for the full rationale.
+    #
+    # NOTE: NO ``sources:`` / ``generates:`` per ``conventions/task-caching.md``
+    # because the walk reads/writes lifecycle folders that go-task does not
+    # track, so a cached skip would silently swallow real promotions.
+    desc: "Reconcile dep graph: promote proposed/ vBRIEFs whose swarm.depends_on[] all resolve to completed/ or cancelled/ (#1287). Flags: --force --dry-run --json."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      # Oracle/fallback (parity): scripts/vbrief_reconcile_graph.py (#1828 Wave 8).
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief-reconcile graph --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  reconcile:labels:
+    # SCM label reconciliation (#1288). Walks vbrief/proposed/ + pending/ +
+    # active/, resolves each brief's linked GitHub issue from its
+    # x-vbrief/github-issue reference, and applies/removes a fixed set of
+    # managed labels so the forge surface mirrors canonical vBRIEF state:
+    # status=blocked or an unresolved swarm.depends_on[] -> status:blocked;
+    # kind=epic -> epic + status:tracker; kind=research -> rfc. Mirror (not
+    # accumulate): managed labels that no longer apply are removed; labels
+    # outside the managed set are never touched. Every forge call routes
+    # through scripts/scm.py (#1145) so task verify:scm-boundary stays green,
+    # and the verb is idempotent (a second run mutates nothing). Pass-through
+    # flags: --repo OWNER/NAME (fallback when a reference URI lacks owner/
+    # repo), --dry-run (report without mutating), --json (machine summary).
+    #
+    # CLI_ARGS forwarding (#577): bare ``{{.CLI_ARGS}}`` -- DO NOT wrap in
+    # Taskfile-level double quotes. go-task already shell-escapes CLI_ARGS
+    # with single quotes; double-wrapping breaks Windows argv. See the
+    # preflight task above for the full rationale.
+    #
+    # NOTE: NO ``sources:`` / ``generates:`` per ``conventions/task-caching.md``
+    # because the walk reads the lifecycle folders and mutates remote forge
+    # state that go-task does not track, so a cached skip would silently
+    # swallow real label changes.
+    desc: "Reconcile SCM labels to mirror vBRIEF state: status:blocked / epic+status:tracker / rfc (#1288). Routes through scripts/scm.py. Flags: --repo --dry-run --json."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      # Oracle/fallback (parity): scripts/vbrief_reconcile_labels.py (#1828 Wave 8).
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief-reconcile labels --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  reconcile:umbrellas:
+    # Umbrella current-shape auto-update (#1289). Walks every kind=epic
+    # vBRIEF, resolves its children from its x-vbrief/plan references,
+    # computes the wave structure from the children's swarm.depends_on[]
+    # edges, builds the canonical AGENTS.md section-1152 current-shape body
+    # (Last updated / Last pass type / Child count / Child-count history /
+    # Open children / Closed children / Wave order / Open questions /
+    # Reading order), and edits the linked SCM umbrella's current-shape
+    # comment IN PLACE so the permalink is preserved and the amendment
+    # trail is never touched. When no current-shape comment exists yet, one
+    # is created at pass-1. Every forge call routes through scripts/scm.py
+    # (#1145) so task verify:scm-boundary stays green, and the verb is
+    # idempotent (a second run with unchanged epic state mutates nothing --
+    # the pass number is only bumped when the rendered body differs).
+    # Pass-through flags: --repo OWNER/NAME (fallback when a reference URI
+    # lacks owner/repo), --dry-run (report without mutating), --json
+    # (machine summary).
+    #
+    # CLI_ARGS forwarding (#577): bare ``{{.CLI_ARGS}}`` -- DO NOT wrap in
+    # Taskfile-level double quotes. go-task already shell-escapes CLI_ARGS
+    # with single quotes; double-wrapping breaks Windows argv. See the
+    # preflight task below for the full rationale.
+    #
+    # NOTE: NO ``sources:`` / ``generates:`` per ``conventions/task-caching.md``
+    # because the walk reads the lifecycle folders and mutates remote forge
+    # state that go-task does not track, so a cached skip would silently
+    # swallow real comment updates.
+    desc: "Reconcile epic umbrella current-shape comments to vBRIEF state per AGENTS.md #1152: edit in place (preserve permalink). Routes through scripts/scm.py. Flags: --repo --dry-run --json."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      # Oracle/fallback (parity): scripts/vbrief_reconcile_umbrellas.py (#1828 Wave 8).
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief-reconcile umbrellas --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  activate:
+    # Implementation-intent activation gate companion (#810). Idempotent:
+    # already-active vBRIEFs print a no-op message and exit 0; pending/
+    # vBRIEFs flip plan.status pending|approved -> running, stamp
+    # vBRIEFInfo.updated to current ISO8601 UTC, and atomically move to
+    # vbrief/active/. Any other source folder is rejected with an
+    # actionable message. Pairs with `scripts/preflight_implementation.py`
+    # (also reachable via `task vbrief:preflight`): this task is the ONLY
+    # supported way to satisfy that gate.
+    #
+    # Dispatched via `{{.DEFT_ROOT}}/scripts/vbrief_activate.py` mirroring
+    # the `tasks/scope.yml` pattern (scope_lifecycle.py) so the JSON edit
+    # + atomic move logic is testable. The companion test lives at
+    # `tests/cli/test_vbrief_activate.py` to satisfy the forward-coverage
+    # rule from main.md.
+    #
+    # CLI_ARGS forwarding (#577): bare ``{{.CLI_ARGS}}`` -- DO NOT wrap
+    # in Taskfile-level double quotes. See the preflight task above for
+    # the full rationale; the short version is that go-task already
+    # shell-escapes CLI_ARGS with single quotes, and double-wrapping it
+    # breaks Windows argv. Spaces in paths survive correctly through
+    # bare interpolation.
+    #
+    # NOTE: NO ``sources:`` / ``generates:`` per ``conventions/task-caching.md``
+    # because the vBRIEF path is a user-facing argument forwarded via
+    # {{.CLI_ARGS}} and a cached cmds skip would silently swallow it.
+    desc: "Activate a vBRIEF: pending/ -> active/ (status: running). Idempotent. (#810)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - _ts-build
+    cmds:
+      # Oracle/fallback (parity): scripts/vbrief_activate.py (#1828 Wave 8).
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" vbrief:activate {{.CLI_ARGS}}

package/tasks/verify.yml

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

package/templates/agents-entry.md

@@ -62,9 +62,9 @@ Check what exists before doing anything else:
 
 ⊗ Self-report the session-start ritual as complete without a fresh `deft session:start` state, or bypass `deft verify:session-ritual` before implementation dispatch. Headless workers and CI MAY set `DEFT_SESSION_RITUAL_SKIP=1`; the verifier exits 0 but warns when the bypass hides a failure.
 
-`deft doctor` remains the install-integrity + toolchain + AGENTS.md managed-section freshness probe (#1308). When the managed-section is stale, the doctor points the operator at `deft agents:refresh` to regenerate AGENTS.md from `templates/agents-entry.md`. The canonical `scripts/doctor.py` (single owner post #1335/#1336) also detects payload staleness from the `<install>/VERSION` manifest and, when behind, emits the canonical headless upgrade command `deft-install --yes --upgrade --repo-root . --json` (#1339 / #1409). The installer itself calls `scripts/doctor.py --session --json` at the end of every run for the unified handoff.
+`deft doctor` remains the install-integrity + toolchain + AGENTS.md managed-section freshness probe (#1308). When the managed-section is stale, the doctor points the operator at `deft agents:refresh` to regenerate AGENTS.md from `templates/agents-entry.md`. The canonical `scripts/doctor.py` (single owner post #1335/#1336) also detects payload staleness from the `<install>/VERSION` manifest and, when behind, emits the canonical upgrade command `npm i -g @deftai/directive@latest` (#1339 / #1409 / #1912).
 
-**Canonical bootstrap / update path (#1339 #1340 #1409 Epic-5/6):** Use the published platform installer binary (from GitHub Releases) as the single deterministic entrypoint. For an existing install, the canonical headless refresh is `deft-install --yes --upgrade --repo-root . --json` (drop `--json` for human-readable output) -- it replaces the payload + manifest + AGENTS.md in one shot. Legacy `deft upgrade` / `run upgrade` are metadata-only acknowledgment (they do NOT replace the payload) and `deft relocate -- --confirm` is back-compat only; git-clone / submodule / legacy doctor surfaces are de-emphasized in UPGRADING.md / README / skills. Agent example: after running the installer command, start your session; the doctor output (or `deft doctor`) tells you the exact state and whether a re-install is needed for freshness.
+**Canonical bootstrap / update path:** Install and upgrade via npm: `npm i -g @deftai/directive` (install) or `npm i -g @deftai/directive@latest` (upgrade). Node ≥ 20 is required to run Deft (the live gates run on the TypeScript engine). On a machine without Node, install Node first, then use npm — the frozen legacy Go installer (GitHub Releases) is only a legacy/offline + layout-migration bridge (#1912), not a Node-free path. Legacy `deft upgrade` / `run upgrade` are metadata-only acknowledgment and `deft relocate -- --confirm` is back-compat only; git-clone / submodule / legacy doctor surfaces are de-emphasized in UPGRADING.md / README / skills. Agent example: after installing, start your session; `deft doctor` tells you the exact state.
 `deft triage:welcome` emits the triage one-liner and, when state is incomplete, nudges the operator at `deft triage:welcome --onboard` (#1143). Default mode is non-interactive; the `--onboard` flag runs the 6-phase interactive ritual.
 
 ## Resume nudge (conditional, #1269)