@deftai/directive-content 0.79.2 → 0.79.4

package/skills/deft-directive-pre-pr/SKILL.md

@@ -38,14 +38,25 @@ or invoke `task verify:branch`. Pre-PR is the last gate before push, so a stale
 
 ## Ordered-plan target gate (#2402)
 
-! Before opening or pushing a PR, when an ordered-plan sequence may be active, verify the PR target matches the current authorized entry:
+! Before opening or pushing a PR, when an ordered-plan sequence may be active, verify the work unit matches the current authorized entry:
+
+1. Resolve the current entry kind and id:
 
 ```
-task verify:plan-sequence -- --target-kind pr --target <issue-or-entry-id>
+task plan-sequence:current
+```
+
+   Use `task plan-sequence:current -- --json` when you need machine-readable `kind` / `id` fields from the current entry.
+
+2. Verify with the **entry kind** (not hardcoded `pr` — `story` / `issue` entries are common):
+
+```
+task verify:plan-sequence -- --target-kind <entry-kind> --target <entry-id>
 ```
 
 - ! Exit non-zero → fail closed; do not open an unauthorized PR.
 - ! Exit 0 with "skipped (no active ordered-plan sequence)" → proceed under normal pre-PR rules.
+- ⊗ Hardcode `--target-kind pr` when the current entry is `kind=story` or `kind=issue` — the verifier matches entry kind exactly (#2662).
 - ! After the PR's review cycle completes successfully, run `task plan-sequence:advance` so "next" resolves to the following entry (or exhausted).
 - ⊗ Treat skill-chaining or "what's next?" as permission to open a PR outside the current sequence entry.
 
@@ -92,6 +103,15 @@ Each iteration proceeds through all phases in order. Do NOT skip phases or reord
 
 ~ **Windows + Grok Build (#1353):** Avoid `|`, `>`, or `2>&1` in `run_terminal_command` strings -- use Python `pathlib`/`subprocess` or plain task commands instead.
 
+### Phase 3c -- Coverage headroom (#2683)
+
+! Before the full `task check` coverage gate, run targeted coverage on changed modules and verify headroom above the project floor.
+
+- ! Run targeted coverage first: `vitest run --coverage <changed-paths>` (or language equivalent) — not only full `task check`.
+- ! Exercise both sides of new branches (ternary / early-return / catch / default switch / `||` / `??`).
+- ! Treat barely ≥ floor as insufficient — aim for ≥ floor + 0.3–0.5pp headroom on the branch metric relative to **your project's** vitest/coverage floor (may differ from 85%).
+- ! Run `task coverage:hotspots` / `deft coverage:hotspots` to locate uncovered branches before opening a PR; complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573).
+
 ### Phase 3b -- Auto-Render Exports
 
 ! If `xbrief/specification.xbrief.json` exists, refresh rendered exports before the diff check:

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

@@ -143,7 +143,9 @@ The harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke
 
 ! **Last human gate before npm (#1972, #2002).** Immediately before invoking `task release`, re-state that the tag push in this step will irrevocably publish all four `@deftai/directive*` packages to npm via `.github/workflows/npm-publish.yml`. There is no undo on npm; only forward recovery (deprecate / dist-tag / patch). Proceed only when the operator explicitly confirms.
 
-! Invoke `task release -- <version>` (NO `--dry-run`, NO `--skip-tag`, NO `--skip-release`). If Phase 1 collected an operator summary, pass `--summary "<text>"` so the production cut writes the same blockquote the dry-run previewed.
+! Invoke `task release -- <version>` (NO `--dry-run`, NO `--skip-tag`, NO `--skip-release`, NO `--skip-ci`). If Phase 1 collected an operator summary, pass `--summary "<text>"` so the production cut writes the same blockquote the dry-run previewed.
+
+⊗ Use `--skip-ci` on a production cut except under explicit operator incident review — it skips Step 5 vitest coverage and ships untested npm builds (#2652). When unavoidable, pass `--allow-skip-ci=#N` citing the tracked issue; Step 5 emits a loud WARN. See [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Vitest coverage hang recovery. The next patch after the hang fix must cut without `--skip-ci`.
 
 ```
 task release -- <version> --summary "<text>"

package/skills/deft-directive-review-cycle/SKILL.md

@@ -182,6 +182,22 @@ Both commands extract the "Comments Outside Diff" section with surrounding conte
 
 ⊗ Push any additional commits — including unrelated fixes, doc updates, or lessons — while waiting for the bot to finish reviewing the current head. Every push re-triggers Greptile and resets the review clock. If you discover additional work while waiting, stage it locally but do NOT push until the current review completes.
 
+
+
+### Greptile CLEAN vs CI holdout (`pr:watch` / #2688)
+
+! When waiting on a Greptile verdict for a `drive-to: merge-ready` worker (or any review-cycle owner), prefer `task pr:watch -- <N>` (or `--one-shot --json`) over ad-hoc sleep loops (#1056). Parse `clean_gate_holdout` on every probe.
+
+! When `clean_gate_holdout=ci_failures` and Greptile otherwise satisfies the probe-side Step 6 fields (SHA match on HEAD, confidence > 3, no P0/P1, not errored): **MUST NOT** idle-poll hoping CI heals. Treat Greptile CLEAN + CI red with the **same ownership** as a Greptile P0 for a merge-ready worker — one fix batch, re-push, re-probe.
+
+! On persistent `ci_failures` holdout: exit the Greptile wait immediately, fetch failing check annotations (`gh pr checks <N>`, CodeQL / required-check details, or `ci_failed_checks` from `pr:watch --json`), fix or escalate with evidence, then re-enter the review loop after CI is green.
+
+! PR body "Test plan" checkboxes being `[x]` do **not** authorize idle wait — merge-ready is `pr:watch` CLEAN / the merge path only.
+
+⊗ Treat `pr:watch` TIMEOUT or long PENDING with `clean_gate_holdout=ci_failures` as "Greptile still reviewing" — it means **CI blocked the clean gate**.
+
+~ Surface the holdout to the user/parent on the first stable `ci_failures` probe (fail-loud), not after burning `max-wait-minutes`. See also [`templates/swarm-greptile-poller-prompt.md`](../../templates/swarm-greptile-poller-prompt.md) CLEAN gate evaluation (#1039).
+
 ### Stall Detection Rubric (#564)
 
 ! Track per poll: `startedAt` (timestamp of the first observation of the IN_PROGRESS check run for the current commit) and `commit.oid` (head SHA being reviewed). Both fields MUST be re-recorded every time the head SHA changes -- the rubric measures elapsed time on a single commit, not across the whole review cycle.
@@ -226,6 +242,11 @@ Both commands extract the "Comments Outside Diff" section with surrounding conte
 
 ! Swarm agents (whether launched via `start_agent` or `spawn_subagent` per the platform descriptor) SHOULD prefer Approach 1 for their own review-monitor sub-agent. Approach 2's yield-between-polls is not self-sustaining for swarm agents (see warning below). Always include the canonical `templates/agent-prompt-preamble.md` (AGENTS.md read mandate, #810 xBRIEF gate, #798 PowerShell UTF-8, pre-PR + review-cycle mandates) when spawning a poller sub-agent.
 
+! **Deterministic review-monitor gate (#2655):** When Tier 1 is available, run `task verify:review-monitor -- --pr <N> [--call-site solo]` before yielding, entering Approach 3, or claiming review monitoring started. After spawning Approach 1, register with `task review-monitor:register -- --pr <N> --monitor-agent-id <id> --platform-primitive start_agent|spawn_subagent|cursor-task`. Exit `0` ready / `1` not ready / `2` config. Approach 3 on Tier 1 is a gate failure — use `--approach3 --approach3-warned` only on Tier 3 after the user warning.
+
+! **CI-holdout carve-out (#2688):** When `task pr:watch --one-shot --json` reports `clean_gate_holdout=ci_failures` with Greptile fields otherwise satisfied on current HEAD, do **not** freeze on `verify:review-monitor` / spawn-monitor as if Greptile latency were the blocker. Fix CI first (same ownership as Greptile P0). Keep or register a review-monitor only while still waiting on Greptile latency; a `BLOCKED: ci_failures` DONE handback to the implementation owner is correct.
+
+
 **Approach 1 (preferred -- sub-agent orchestration available per platform descriptor):**
 
 ! **Background dispatch (#1880):** Spawn the review-monitor sub-agent via the matching primitive IN THE BACKGROUND (Cursor: Task `run_in_background: true`; Grok Build: `spawn_subagent` with parent yielding). The parent MUST remain interactive while the poller runs.

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

@@ -616,12 +616,14 @@ All PRs meet ALL of:
 
 ! **Mandatory cohort verifier (#1364):** After every poller (Phase 6 review-cycle sub-agent) reports back, the monitor MUST run `task swarm:verify-review-clean -- <pr-numbers...>` and confirm exit 0 BEFORE evaluating the rest of the Exit Condition or surfacing the Phase 5 -> 6 gate. The verifier re-uses the Greptile rolling-summary parser from `task pr:merge-ready` so the per-PR merge gate and the cohort gate stay in lockstep (a parser fix lands in both surfaces at once). Exit codes: 0 (cohort CLEAN -- all PRs simultaneously have SHA match + confidence > 3 + zero P0/P1 + not errored on current HEAD); 1 (one or more PRs unclean with per-PR diagnostics -- re-dispatch the poller for the unclean PR or address findings, then re-run the verifier); 2 (config error -- empty cohort, malformed xBRIEF glob, gh missing). The verifier is the structural answer to the #1166 swarm execution recurrence where multiple pollers exited with `clean_gate_holdout=confidence` (confidence == 3) and the monitor still raised the Phase 5 -> 6 gate because the trigger keyed on "all pollers have reported back" rather than "every PR in the cohort is objectively CLEAN".
 
-! **Resilient long-running monitor (#1368):** When a Phase 5 monitor needs to wait on an in-flight PR for an extended window (cascade rebase + re-review, late Greptile pass, CI sweep), use `task pr:watch -- <N> --repo <owner>/<repo>` as the canonical wait-until-ready helper. The task loops `task pr:merge-ready` with adaptive cadence (~1m for the first 3 polls, ~3m next, ~5m thereafter), tolerates layered fallback responses without going blind on a transient gh failure. Exit codes: 0 (PR reached primary/fallback1 CLEAN), 1 (poll cap reached -- escalate to operator), 2 (config error -- gh missing / invalid args), 3 (PR merged or closed out from under the monitor before reaching CLEAN). The helper writes one terse status line per poll to stderr so the orchestrator transcript shows progress; the final verdict (JSON when `--json` is passed) lands on stdout.
+! **Deterministic PR-verdict wait (#1056):** When a Phase 5 monitor needs to wait on Greptile/SLizard for an in-flight PR (cascade rebase + re-review, late Greptile pass), use `task pr:watch -- <N> [--repo <owner>/<repo>]` as the canonical wait-until-verdict helper. Blocking-by-default poll to a terminal three-state verdict — exit `0` CLEAN, `1` NEW_P0_P1, `2` ERRORED|STALL|TIMEOUT|config — with `--one-shot` for a single probe, `--json` for the structured shape, and `--max-wait-minutes` / `--poll-seconds` for the budget (defaults 30m / 90s). SHA-match gates the verdict to the current HEAD. For mergeable+merge cascade automation (not Greptile verdict alone), use `task pr:wait-mergeable-and-merge` (#1369); for adaptive merge-ready polling with layered `via` fallbacks, use `task pr:merge-ready` / `task pr:monitor` (#1368).
 
 ! **Fallback-chain discriminator semantics (#1368):** `task pr:merge-ready -- <N> --json` ALWAYS emits a `via` discriminator on every response. `via="primary"` and `via="fallback1"` are authoritative -- a `merge_ready: true` verdict on either is CLEAN. `via="fallback2"` is the coarse PR-view + check-run last-resort signal: it surfaces the PR's `state` / `merged` / `mergeable` / flattened check-run summary so a monitor can keep stepping forward through transient gh failures, but it is NEVER CLEAN -- the failure list carries the sentinel `"fallback2 is a coarse signal, not a CLEAN verdict ..."` and the merge cascade MUST keep waiting for a primary/fallback1 CLEAN. `via="error"` (every layer failed) is also non-CLEAN; the response carries `error` (one-line summary) + `partial_data` (per-layer diagnostics) so the monitor can step forward without blinding. Both `task swarm:verify-review-clean` and `task pr:merge-ready` treat fallback2 and error as merge-blocked.
 
 ⊗ Surface or discuss the Phase 5 -> 6 merge cascade gate while `task swarm:verify-review-clean` has not yet exited 0 on the current cohort (#1364). Keying the transition on poller lifecycle completion alone -- i.e. treating "every poller sub-agent returned a terminal message" as sufficient -- is the exact recurrence pattern this rule closes. The verifier is the only authoritative cohort-level CLEAN signal; a poller's `clean_gate_holdout=confidence` / `clean_gate_holdout=has_blocking` / `clean_gate_holdout=sha_match` / `clean_gate_holdout=errored` exit IS a non-CLEAN report and MUST hold the gate even if every sub-agent has technically returned.
 
+! **Review-monitor gate (#2655 / #1386):** Before surfacing the Phase 5→6 merge gate (or yielding while implementers' PRs await Greptile), run `task verify:review-monitor -- --pr <N> [--call-site swarm-phase5-6]` for each in-flight PR when Tier 1 is available. Register monitors after spawning Approach 1 pollers via `task review-monitor:register`. Do not duplicate the monitoring matrix here — see `skills/deft-directive-review-cycle/SKILL.md` Review Monitoring + the verify verb.
+
 ⊗ Treat a `via="fallback2"` or `via="error"` response from `task pr:merge-ready` as CLEAN, regardless of the surrounding `merge_ready` field (#1368). Fallback2 is structurally never CLEAN -- the Greptile rolling-summary comment was unreachable on both the primary and fallback1 paths, so any merge taken on the basis of the coarse signal alone bypasses the SUCCESS-with-findings blind spot the per-PR gate was designed to close (#796 / #652). The merge cascade MUST keep waiting for a primary/fallback1 CLEAN.
 
 ### Phase 5→6 Gate: Release Decision Checkpoint
@@ -717,7 +719,9 @@ If any protected (umbrella / staying-OPEN) issue number appears in the output, t
 
 ! **Autonomous re-review monitoring after force-push:** After each `--force-with-lease` push of a rebased branch in the cascade, the monitor MUST autonomously wait for the Greptile re-review to complete before proceeding to the next merge. Use the tiered monitoring approach defined in `skills/deft-directive-review-cycle/SKILL.md` Step 4 Review Monitoring (Approach 1: spawn sub-agent via the platform adapter's dispatch primitive (e.g. `spawn_subagent` or `start_agent`) to poll and report back; Approach 2 fallback: discrete `run_shell_command` wait-mode calls with yield between polls, adaptive cadence -- see deft-directive-review-cycle SKILL.md). Do NOT duplicate the full monitoring logic here -- follow the canonical skill.
 
-~ **Resilient wait-until-ready helper (#1368):** For the in-cascade wait between a force-push and the next merge, the canonical surface is `task pr:watch -- <N> --repo <owner>/<repo> --cap-minutes <M>`. It loops `task pr:merge-ready` with adaptive cadence (~1m -> 3m -> 5m), tolerates `via="fallback1"` / `via="fallback2"` / `via="error"` responses without blinding, and exits 0 only on a primary or fallback1 CLEAN (never fallback2 -- the coarse signal is a monitor heartbeat, not a merge gate). A `via="fallback2"` payload reporting `partial_data.merged == true` short-circuits the loop with exit code 3 (PR-TERMINAL) so a cascade can detect a sibling-merged-out-from-under-us state without burning the full cap. Use this in place of hand-rolled polling loops in long-running cascade waits.
+! **Review-monitor gate after force-push (#2655 / #380):** After each cascade force-push, run `task verify:review-monitor -- --pr <N> --call-site swarm-phase6-cascade` before yielding for re-review when Tier 1 is available. Spawn/register Approach 1 pollers per review-cycle skill; do not yield idle without an active monitor record.
+
+~ **In-cascade Greptile wait (#1056):** For the wait between a force-push and the next merge, poll the Greptile/SLizard verdict with `task pr:watch -- <N> [--repo <owner>/<repo>] [--max-wait-minutes <M>]` (exit `0` CLEAN / `1` NEW_P0_P1 / `2` ERRORED|STALL|TIMEOUT|config). Do not use `--cap-minutes` — that flag belongs to `task pr:monitor`, not `pr:watch`. For the composed wait-until-mergeable-then-merge path, use `task pr:wait-mergeable-and-merge` (#1369). Use these in place of hand-rolled polling loops in long-running cascade waits.
 
 ! **Cascade automation surface (#1369):** The canonical one-verb compose-point for "wait until PR <N> is mergeable, then squash-merge with admin" is `task pr:wait-mergeable-and-merge -- <N> --repo <owner>/<repo>`. The helper runs the resilient wait loop (#1368) and the Layer-3 protected-issue link inspection (#701) AHEAD of any merge call, then invokes `gh pr merge <N> --squash --delete-branch --admin` only after the wait loop exits CLEAN on the current HEAD. Three-state exit (0 merged / 1 timeout-or-escalation / 2 config error) mirrors every other framework verb. Pass `--protected <issue-numbers>` for the Layer-3 chain when the PR is known to reference any umbrella / staying-OPEN issue -- the helper short-circuits with exit 1 BEFORE the merge call if a persistent `closingIssuesReferences` link is detected. The Wave-3 surface is the automated cascade wrapper; the per-PR atomic gate (`task pr:merge-ready -- <N> && gh pr merge <N>`) documented above remains the manual freshness-window-atomic check the monitor MUST use when running merges by hand. The two co-exist -- the cascade surface is the automation, the per-PR atomic gate is the manual fall-through. See AGENTS.md `## Cascade automation surface (#1369)`.
 

package/tasks/coverage.yml

@@ -0,0 +1,15 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  hotspots:
+    desc: "Coverage hotspots + branch headroom gate (#2683): read coverage/coverage-final.json, compare global metrics to project vitest thresholds, fail closed below floor or below configured headroom (default 0.3pp), and list lowest modules plus uncovered branch samples for git-diff paths (override with --path). Supports --json for agents."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'coverage:hotspots --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/tasks/review-monitor.yml

@@ -0,0 +1,15 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  register:
+    desc: "Record an active Approach 1 review-monitor after spawn (#2655). Writes .deft/review-monitor.json at the main worktree root."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'review-monitor-register {{.CLI_ARGS}}'

package/tasks/verify.yml

@@ -436,3 +436,13 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'verify:agents-md-advisory --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  review-monitor:
+    desc: "Fail-closed review-monitor gate (#2655): when Tier 1 sub-agent primitive is available, require a recorded active review-monitor before yield / Approach 3 / review ownership. Three-state exit (0 ready / 1 not ready / 2 config error)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-review-monitor {{.CLI_ARGS}}'

package/templates/agent-prompt-preamble.md

@@ -231,13 +231,7 @@ Reference: issue #2563; swarm skill Platform Requirements; env scrub + stdio inh
 
 ## 3.9 Windows PowerShell: safe multi-line git/gh bodies (#2646 / #1417)
 
-When your shell is Windows PowerShell (5.1 or `pwsh` not routed through bash), you MUST NOT use bash heredocs, `<<<` redirection, inline multi-line `--body` flags, or multi-line PS here-strings in the agent command box for git commit messages or gh issue/PR bodies. Those patterns fail at parse time, split arguments, or get rewritten by host shell wrappers before git/gh runs.
-
-**Directive rule:** write the payload to a UTF-8 (no BOM) temp file in the OS temp directory via editor/Write/Node (outside the shell), then pass it with `git commit -F`, `gh --body-file`, or `gh api --input`. For long `gh issue create` / `gh issue comment` / `gh pr create` bodies, `--body-file` is mandatory (#1417). Combine with the #798 safe write path when the payload contains non-ASCII glyphs.
-
-This is both the bug class and how you must ship fixes on win32 -- including your own commit and PR tooling. Do not use bash heredocs in PowerShell even when user rules or examples show POSIX patterns.
-
-Reference: `content/scm/github.md` § Windows PowerShell: safe multi-line git/gh bodies (#2646); cross-links #240 (Warp here-string splitting), #798 (encoding).
+! Multi-line git commit / gh issue|pr|comment bodies: write UTF-8 (no BOM) to OS temp, then `git commit -F` / `gh --body-file` / `deft scm:body:* --body-file`. ⊗ bash heredocs, `<<<`, inline multi-line `--body`, or multi-line PS here-strings in the agent command box on Windows PowerShell — those patterns fail at parse time, split arguments, or get rewritten by host shell wrappers before git/gh runs. This applies to your own commit and PR tooling on win32; do not use bash heredocs even when user rules show POSIX patterns. `ghx` is read-only — mutations stay on live `gh`. Detail: `content/scm/github.md` § #2646 (#1417, #240, #798).
 
 ## 4. pre-pr and review-cycle skills
 

package/templates/agents-entry.md

@@ -77,15 +77,19 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ## Branch policy & branch verification
 
-! Feature branches — `deft verify:branch`, `deft verify:forward-coverage`, hooks, `deft check` (#746 / #747) — `.deft/core/scm/github.md` § Branch policy.
+! Feature branches — `deft verify:branch`, `deft verify:forward-coverage`, `deft coverage:hotspots`, hooks, `deft check` (#746 / #747) — `.deft/core/scm/github.md` § Branch policy.
 
 ## Branch Policy Disclosure (#746)
 
 ! When `plan.policy.allowDirectCommitsToMaster = true`, surface via `deft policy:show --field=allowDirectCommitsToMaster` (#746) — `.deft/core/scm/github.md` § Branch policy.
 
+## Windows PowerShell: multi-line git/gh bodies (#2646)
+
+! Multi-line git commit / gh issue|pr|comment bodies: write UTF-8 (no BOM) to OS temp, then `git commit -F` / `gh --body-file` / `deft scm:body:* --body-file`. ⊗ bash heredocs, `<<<`, or inline multi-line `--body` on Windows PowerShell. Detail: `.deft/core/scm/github.md` § #2646. `ghx` is read-only — mutations stay on live `gh`.
+
 ## Contextual guardrails (runtime-detect lazy-load)
 
-! Detect OS/shell; use portable syntax or explicit shell (#2568). `.deft/core/scm/github.md` (#2157/#2369): PS multi-line git/gh bodies→§ Windows PowerShell safe multi-line git/gh bodies (#2646); PS encoding→`deft verify:encoding` (#798); TS capture; cascade→`deft pr:wait-mergeable-and-merge`; SCM→`deft verify:scm-boundary`.
+! Detect OS/shell; use portable syntax or explicit shell (#2568). `.deft/core/scm/github.md` (#2157/#2369): PS encoding→`deft verify:encoding` (#798); TS capture; cascade→`deft pr:wait-mergeable-and-merge`; SCM→`deft verify:scm-boundary`.
 
 ## Development Process