@deftai/directive-content 0.67.0 → 0.68.1

package/skills/deft-directive-gh-slice/SKILL.md

@@ -97,6 +97,7 @@ Iterate until the user approves the breakdown.
 
 ### Step 5: Create the GitHub issues
 
+- ! **Pre-filing master-diff check (#1102):** before filing an issue that proposes ADDING a file or directory, run `git ls-tree origin/master -- <path>` (or `gh api repos/{owner}/{repo}/contents/{path}` for repos without a local clone) to confirm the file does not already exist on master. If it does, scope the issue to the DELTA between current state and the proposed end-state, not the original "deposit this file" framing.
 - ! Create issues in dependency order (blockers first) so you can reference real issue numbers
 - ! Use `gh issue create` for each approved slice with the template below
 - ! Trace each issue back to the relevant SPECIFICATION.md phase/task IDs where applicable
@@ -197,3 +198,4 @@ task slice:list                  # enumerate recorded slices for verification
 - ⊗ Proceeding without `gh` authentication
 - ⊗ Omitting dependency ordering — blockers must be created first
 - ⊗ Describing implementation internals instead of observable behavior in issue bodies
+- ⊗ File an issue proposing to add a file or directory that already exists on master without first running the `git ls-tree origin/master -- <path>` existence check (#1102) -- the stale "add file X" filing (#1099 proposed adding `.github/dependabot.yml`, which had already landed via #1070; closed as a duplicate and re-filed as the additive-delta #1100) is exactly the recurrence this check prevents

package/skills/deft-directive-refinement/SKILL.md

@@ -154,6 +154,8 @@ The agent may suggest the next phase, but the user decides. Phases can be entere
 
 ! Scan external sources for new work items and create proposed scope xBRIEFs.
 
+! **Pre-filing master-diff check (#1102).** When a refinement pass FILES a new GitHub issue that proposes ADDING a file or directory (rather than ingesting an existing issue), first run the pre-filing existence check from [`../deft-directive-gh-slice/SKILL.md`](../deft-directive-gh-slice/SKILL.md) Step 5 -- `git ls-tree origin/master -- <path>` (or `gh api repos/{owner}/{repo}/contents/{path}`) -- so a stale "add file X" issue is never opened against state that already exists on master (the #1099 -> #1100 close-and-refile recurrence).
+
 ### Step 1: Gather Sources
 
 1. ? Scan non-GitHub sources (Jira, direct user requests, etc.) manually if applicable — those ingest paths are not yet task-wrapped

package/skills/deft-directive-swarm/SKILL.md

@@ -774,7 +774,20 @@ What the sweep does (script: `scripts/swarm_complete_cohort.py`):
 
 ! **Interactive path:** the monitor runs `task swarm:complete-cohort` by hand (or `--dry-run` first to preview the planned transitions) once the merge cascade finishes, then runs `task xbrief:validate`.
 
-! **Headless / multi-worker path:** the cohort sweep is NOT optional here -- it is the structural fix for the #1487 recurrence where the multi-worker close-out never executed the per-cohort completion. The launching monitor (or the close-out automation that follows `task pr:wait-mergeable-and-merge`, #1369) MUST invoke `task swarm:complete-cohort -- --cohort '<cohort-glob>'` after the last cohort PR merges and MUST gate on its exit 0 plus a green `task xbrief:validate` before declaring the swarm closed. The `--json` flag emits a structured verdict for a parent monitor agent to consume.
+! **Headless / multi-worker path (#2225):** after the merge cascade (`task pr:wait-mergeable-and-merge`, #1369) reports the cohort's PRs MERGED, the monitor SHOULD invoke the automated finalize surface instead of hand-authoring a separate lifecycle-sweep PR:
+
+```pwsh path=null start=null
+# Resolve merged stories from PR closing keywords and land the sweep PR:
+task swarm:finalize-cohort -- --pr <N1>,<N2> --repo <owner/repo> [--label <cohort-label>]
+# Preview only (no commit / no PR):
+task swarm:finalize-cohort -- --pr <N1>,<N2> --repo <owner/repo> --dry-run
+# Explicit story list when PR bodies omit Closes #N:
+task swarm:finalize-cohort -- --stories <issue-or-path>... --repo <owner/repo>
+```
+
+The finalize surface runs the same `completeCohort(...)` engine as `task swarm:complete-cohort`, fast-forwards the local base branch, creates a `swarm/finalize/<label>` feature branch (branch policy #747 safe), commits the `xbrief/` lifecycle moves, and auto-opens the sweep PR. Pass `--no-commit` to sweep only (manual Step 2b), or `--no-open-pr` to commit locally without opening the PR. Gate on exit 0 plus green `task xbrief:validate` before declaring the swarm closed.
+
+! **Manual fallback (#1487):** `task swarm:complete-cohort` remains the idempotent manual primitive when finalize automation is unavailable or you need a dry-run preview of transitions only. The headless path above replaces the historical requirement to hand-author a separate `chore(xbrief)` sweep PR every cycle.
 
 ⊗ Declare a swarm closed while any cohort story xBRIEF remains in `xbrief/active/` or any fully-childless decompose-created epic parent remains in `xbrief/pending/` -- run `task swarm:complete-cohort` and confirm `task xbrief:validate` is green first (#1487).
 

package/tasks/engine.yml

@@ -37,7 +37,7 @@ tasks:
 
   invoke:
     internal: true
-    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (npm consumer deposit)."
+    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (npm consumer deposit). Source checkouts without a built dist fail fast (#2181) -- runtime/session tasks must not trigger engine:_ts-build / pnpm."
     # Run from the operator project root so deft verbs resolve USER_WORKING_DIR
     # correctly; without this, included engine.yml defaults cwd to tasks/ (#2022).
     dir: '{{.USER_WORKING_DIR}}'
@@ -45,8 +45,33 @@ tasks:
       - |
         set -eu
         bin="{{.DEFT_ROOT}}/packages/cli/dist/bin.js"
+        root_pkg="{{.DEFT_ROOT}}/package.json"
+        is_buildable_source=0
+        if [ -f "{{.DEFT_ROOT}}/packages/cli/package.json" ] \
+           && [ -f "$root_pkg" ] \
+           && node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.exit(j.scripts&&j.scripts.build?0:1)" "$root_pkg"; then
+          is_buildable_source=1
+        fi
         if [ -f "$bin" ]; then
+          if [ "$is_buildable_source" = 1 ] && [ -f "$root_pkg" ]; then
+            node -e "
+              const fs=require('fs');
+              const pkg=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));
+              const req=pkg.engines&&pkg.engines.node;
+              if(!req) process.exit(0);
+              const major=Number(process.versions.node.split('.')[0]);
+              const m=String(req).match(/>=\\s*(\\d+)/);
+              if(m&&major<Number(m[1])){
+                console.error('deft: Node '+process.versions.node+' does not satisfy engines.node '+req+' (read from '+process.argv[1]+').');
+                process.exit(2);
+              }
+            " "$root_pkg" || exit $?
+          fi
           node "$bin" {{.ENGINE_CMD}}
+        elif [ "$is_buildable_source" = 1 ]; then
+          echo "deft: CLI artifact missing at {{.DEFT_ROOT}}/packages/cli/dist/bin.js" >&2
+          echo "  Run \`task build\` first (framework source checkout)." >&2
+          exit 2
         elif command -v deft >/dev/null 2>&1; then
           deft {{.ENGINE_CMD}}
         else

package/tasks/pr.yml

@@ -95,3 +95,32 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'pr-wait-mergeable {{.CLI_ARGS}}'
+
+  # pr:watch -- deterministic PR-verdict polling surface (#1056). A
+  # blocking-by-default poll that resolves to a terminal three-state verdict
+  # (exit 0 CLEAN / 1 NEW_P0_P1 / 2 ERRORED|STALL|TIMEOUT|config), so an
+  # orchestrator that promises to poll a PR review to conclusion cannot
+  # silently forget (the invocation IS the wait). --one-shot degrades to a
+  # single probe. Reuses the CANONICAL Greptile/SLizard verdict detector
+  # (packages/core/src/content-contracts/skills/greptile-detector.ts -- the
+  # same module pr:merge-ready and the swarm poller template consume); no
+  # second detector. SHA-match gating means a stale pre-push review is never
+  # read as the verdict. All gh access routes through the UTF-8-safe
+  # execFile shim (#1366). Cross-referenced from the AGENTS.md
+  # `## Multi-agent orchestration discipline (#954)` Tier-4 pointer.
+  #
+  # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
+  # because user-facing flags (`--one-shot` / `--max-wait-minutes` /
+  # `--poll-seconds` / `--json` / `--repo` / `--project-root`) MUST NOT be
+  # silently swallowed by go-task's incremental-build cache.
+  #
+  # Companion module: packages/core/src/pr-watch/
+  # Companion tests:  packages/core/src/pr-watch/*.test.ts
+  watch:
+    desc: "Blocking poll of a PR to a terminal three-state verdict (0 CLEAN / 1 NEW_P0_P1 / 2 ERRORED|STALL|TIMEOUT|config); --one-shot for a single probe (#1056)"
+    deps: [":engine:_ts-build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'pr-watch {{.CLI_ARGS}}'

package/tasks/session.yml

@@ -12,7 +12,7 @@ tasks:
   start:
     desc: "Run quick-tier session-start ritual and write .deft/ritual-state.json (#1348). Flags: --defer step=reason / --json"
     dir: '{{.USER_WORKING_DIR}}'
-    deps: [":engine:_ts-build"]
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     env:
       PYTHONUTF8: "1"
     cmds:

package/tasks/swarm.yml

@@ -93,3 +93,19 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'swarm-complete-cohort {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"'
+
+  # swarm:finalize-cohort -- post-merge cohort lifecycle automation (#2225).
+  # After a cohort's PRs merge, resolves the merged stories (via Closes #N ->
+  # active-brief mapping or an explicit --stories list), runs the same
+  # completeCohort(...) sweep as swarm:complete-cohort, and lands the
+  # active/ -> completed/ moves on a feature branch with an auto-opened PR —
+  # eliminating the hand-authored lifecycle-sweep PR tax for stop-at:pr-open
+  # swarms. swarm:complete-cohort remains the idempotent manual primitive.
+  finalize-cohort:
+    desc: "After cohort PRs merge, auto-sweep story briefs active/ -> completed/ and open the lifecycle PR (#2225)"
+    deps: [":engine:_ts-build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'swarm-finalize-cohort {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"'

package/tasks/triage-summary.yml

@@ -23,7 +23,7 @@ tasks:
   summary:
     desc: "Emit the D2 (#1122) one-line triage state for the session-start ritual (N9 / #1149). Always exits 0; appends a JSONL record to vbrief/.eval/summary-history.jsonl. -- task triage:summary -- [--json] [--no-history]"
     internal: true
-    deps: [":engine:_ts-build"]
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     dir: '{{.USER_WORKING_DIR}}'
     cmds:
       - task: :engine:invoke

package/tasks/triage-welcome.yml

@@ -24,7 +24,7 @@ tasks:
   welcome:
     desc: "Run the 6-phase onboarding ritual (N3 / #1143): detect prior state, prompt subscription scope, run triage:bootstrap, prompt wipCap, offer WIP relief, print triage:summary. Idempotent; re-run resumes cleanly. -- task triage:welcome -- [--no-subprocess]"
     internal: true
-    deps: [":engine:_ts-build"]
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     dir: '{{.USER_WORKING_DIR}}'
     env:
       DEFT_TASK_PREFIX: '{{.DEFT_TASK_PREFIX | default ""}}'

package/tasks/verify.yml

@@ -157,6 +157,20 @@ tasks:
         vars:
           ENGINE_CMD: 'verify:encoding --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
+  forward-coverage:
+    desc: "Forward-coverage gate (#1310): fail when a NEW source file (scripts/, src/, cmd/, packages/*/src, or *.py/*.go/*.ts/*.tsx, excluding *.test.ts / *_test.go / test_*.py / *.d.ts) is added without a corresponding test in the SAME diff. Migrates the prose 'new source files MUST include tests' rule to deterministic enforcement, mirroring verify:encoding (#798) / verify:branch (#747). Defaults to the HEAD-relative diff; pass --staged for the pre-commit invocation. Three-state exit (0 clean / 1 missing forward coverage / 2 config error)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    # Per `conventions/task-caching.md`: NO `sources:` / `generates:` because
+    # user-facing flags (--staged / --head / --allow-list <path> / --quiet) MUST
+    # NOT be silently swallowed by go-task's incremental-build cache (same
+    # rationale as verify:encoding above).
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:forward-coverage --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}}'
@@ -190,8 +204,8 @@ tasks:
   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:
-      - task: :engine:_ts-build
+    # Runtime/session + pre-dispatch gate: no engine:_ts-build / pnpm build (#2181).
+    # Parent `task check` still builds via its own engine:_ts-build dep first.
     # 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
@@ -220,8 +234,7 @@ tasks:
   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:
-      - task: :engine:_ts-build
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     # 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).
@@ -232,8 +245,7 @@ tasks:
   tools:
     desc: "Detect required Deft host tools and print install or manual guidance (#1187). Flags: --install / --yes / --json"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     cmds:
       # Oracle/fallback (parity): scripts/verify_tools.py (#1828 Wave 8).
       - task: :engine:invoke

package/templates/agents-entry.md

@@ -130,6 +130,7 @@ Three consumer-facing surfaces enforce the branch-policy contract (#746 / #747):
 - `deft verify:branch` -- branch gate wired into the `deft check` aggregate; refuses a commit on the default branch unless `plan.policy.allowDirectCommitsToMaster = true` (typed) or `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` is set.
 - `.githooks/pre-commit` / `pre-push` -- local hooks installed via `deft setup`; verify via `deft verify:hooks-installed`. After a framework upgrade, run `deft update` to refresh hook templates to the current TS-native `deft verify:*` / `deft preflight-gh` wiring (#2049).
 - `deft policy:show --field=allowDirectCommitsToMaster` -- inspect the resolved policy; `deft policy:allow-direct-commits -- --confirm` writes the typed override with an audit row.
+- `deft verify:forward-coverage` -- forward-coverage gate (#1310): a NEW source file (`scripts/`, `src/`, `cmd/`, `packages/*/src`, or `*.py`/`*.go`/`*.ts`/`*.tsx`, excluding tests + `*.d.ts`) added without a corresponding test in the SAME diff fails the gate. Wired into `deft check` + the pre-commit hook (`--staged`); document genuine exceptions (shims, generated code) via `--allow-list <path>`. Mirrors the `deft verify:encoding` (#798) prose->deterministic migration.
 
 ## Branch Policy Disclosure (#746)