@deftai/directive-content 0.79.1 → 0.79.3

package/scm/github.md

@@ -149,6 +149,43 @@ PowerShell 5.x (Windows default) uses UTF-16LE internally and may inject a BOM o
 
 - ! Never paste multi-line PowerShell string literals (here-strings `@" ... "@`) directly into the Warp agent input box -- Warp splits multi-line input across separate command blocks, causing syntax errors or silent truncation. Always write multi-line PS content to a temp file first (e.g. `[System.IO.File]::WriteAllText($tmpFile, $content, [System.Text.UTF8Encoding]::new($false))`), then use the temp file path in subsequent commands
 
+### Windows PowerShell: safe multi-line git/gh bodies (#2646 / #1417)
+
+On Windows PowerShell (5.1 and often `pwsh` when commands are not routed through bash), multi-line git and gh payloads MUST NOT be authored inline in agent shell commands. Bash-style heredocs, POSIX here-document redirection (including `<<<`), inline multi-line `--body` flags, and multi-line PS here-strings pasted into the agent command box all fail or corrupt the payload before git/gh receives it. Related but distinct failure modes: #240 (Warp splits PS here-strings across command blocks) and #798 (PS 5.1 encoding corruption on read/write round-trips -- use the safe write path when creating temp files).
+
+**Canonical pattern (Windows PowerShell agents):**
+
+1. Write the multi-line payload to a UTF-8 (no BOM) temp file in the OS temp directory (`$env:TEMP` / `[System.IO.Path]::GetTempFileName()`), not the worktree.
+2. Prefer creating that file **outside the shell** (editor/Write tool, Node script on disk) so host/agent shell wrappers cannot rewrite strings that look like git commit or gh body invocations.
+3. Pass the file to git/gh: `git commit -F <file>`, `gh pr create --body-file <file>`, `gh issue create --body-file <file>`, `gh issue comment --body-file <file>`, or `gh api ... --input <file>` (JSON bodies for PATCH/POST).
+
+**PowerShell example (commit message + PR body):**
+
+```powershell
+$bodyFile = [System.IO.Path]::GetTempFileName()
+[System.IO.File]::WriteAllText($bodyFile, $prBody, [System.Text.UTF8Encoding]::new($false))
+git commit -F $bodyFile
+gh pr create --title "feat: example" --body-file $bodyFile
+```
+
+**Recovery pattern for issue/PR PATCH (when wrappers corrupt inline payloads):** write a Node (or other) script to disk with the editor/Write tool, have it emit JSON to a temp file, then `gh api -X PATCH ... --input <file>` via `execFileSync` / equivalent. Verify the posted body afterward for injected Co-authored-by or Made-with markers.
+
+**Dogfood failure modes (Cursor on win32, 2026-07-19, #2646):**
+
+1. Bash `<<<` in a PowerShell script -- parse abort (`Missing file specification after redirection operator`); the whole script never runs.
+2. Host wrapper rewrote `git commit ...` prose inside an issue-body PATCH -- injected angle brackets made PowerShell treat `<...>` as operators (`The '<' operator is reserved for future use`).
+3. Host wrapper rewrote inline `--body "..."` prose -- corrupted failure-mode examples mid-PATCH.
+4. File-staged `gh api --input <file>` (payload written outside the shell) succeeded.
+
+- ! Under Windows PowerShell, MUST use temp-file delivery for all multi-line git commit messages (`git commit -F`) and gh bodies (`--body-file` / `gh api --input`) -- never bash heredocs, `<<<`, or inline multi-line `--body` flags
+- ! For `gh issue create`, `gh issue comment`, and `gh pr create`, long bodies MUST use `--body-file` (temp file), not an inline `--body` flag (#1417)
+- ! Create temp payload files via a safe UTF-8 write path (#798) -- prefer editor/Write/Node on disk over PS here-strings in the agent command box (#240)
+- ⊗ Use bash-style heredocs or `<<<` redirection under Windows PowerShell -- not valid; payloads never reach git/gh intact
+- ⊗ Embed multi-line markdown inside a PowerShell agent shell string for git/gh -- quoting splits arguments, angle brackets parse as operators, and host wrappers may rewrite the text
+- ⊗ Build multi-line gh/git PATCH JSON inside an instrumented agent shell one-liner -- stage the file first, then `gh api --input`
+
+Refs #240, #798, #1417, #2646.
+
 ## PowerShell platform-conditional rules for agents (#798 / #1353)
 
 These runtime-specific rules are lazy-loaded here rather than shipped in the always-loaded AGENTS.md, so they don't crowd context for sessions that can't trigger them (#2157 / #1882). Load this section **before** the risky operation when your session matches one of the triggers below.

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

@@ -226,6 +226,8 @@ 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.
+
 **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/engine.yml

@@ -230,6 +230,7 @@ tasks:
           is_runtime_verb=0
           case " ${first_token} " in
             " session:start "|" session-start "|\
+            " lifecycle:event "|" lifecycle-event "|\
             " verify:session-ritual "|" verify-session-ritual "|\
             " verify:tools "|" verify-tools "|\
             " triage:summary "|" triage-summary "|\

package/tasks/lifecycle.yml

@@ -0,0 +1,23 @@
+version: '3'
+
+# tasks/lifecycle.yml -- behavioral framework event recorder (#2631 / #635).
+# Consumer npm deposits invoke via engine:invoke without a local build (#2181).
+#
+# Review-cycle merge-gate approval uses `task lifecycle:event -- emit plan:approved ...`.
+# Per conventions/task-caching.md: no sources/generates because the task forwards
+# user-facing flags via CLI_ARGS.
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  event:
+    desc: "Emit behavioral framework events (review-cycle plan:approved recorder). -- task lifecycle:event -- emit plan:approved --plan-ref <url> --approver <login> --approval-phrase <yes|confirmed|approve> --pr-number <N> [--head-sha <sha>]"
+    dir: '{{.USER_WORKING_DIR}}'
+    # Runtime dispatch: no engine:_ts-build / pnpm build (#2181 / consumer npm deposit).
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'lifecycle:event {{.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

@@ -229,6 +229,16 @@ On Windows, Cursor Task-tool local subagents historically opened a visible `cmd.
 
 Reference: issue #2563; swarm skill Platform Requirements; env scrub + stdio inherit for nested Task recursion (#2554 / #2438).
 
+## 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).
+
 ## 4. pre-pr and review-cycle skills
 
 Before pushing any branch:

package/templates/agents-entry.md

@@ -85,7 +85,7 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ## Contextual guardrails (runtime-detect lazy-load)
 
-! Detect OS/shell; use portable syntax or explicit shell (#2568). `.deft/core/scm/github.md` (#2157/#2369): PS→`deft verify:encoding`; 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 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`.
 
 ## Development Process