@deftai/directive-content 0.79.1 → 0.79.2

package/Taskfile.yml

@@ -152,6 +152,9 @@ includes:
   session:
     taskfile: ./tasks/session.yml
     optional: true
+  lifecycle:
+    taskfile: ./tasks/lifecycle.yml
+    optional: true
   plan-sequence:
     taskfile: ./tasks/plan-sequence.yml
     optional: true
@@ -363,6 +366,11 @@ tasks:
         vars:
           ENGINE_CMD: 'check --framework-root "{{.TASKFILE_DIR}}" --project-root "{{.USER_WORKING_DIR}}"'
 
+  test:coverage:
+    desc: "Run tests with coverage (alias for ts:test; canonical coverage path used by task check, #2528)"
+    cmds:
+      - task: ts:test
+
   check:framework-source:
     desc: "Run all framework source-repo pre-commit checks (TS-only after #1860). Sole wired consumer of maintainer-only core:build / core:clean."
     deps:

package/commands.md

@@ -95,7 +95,7 @@ Common commands:
 - `task scope:fail -- xbrief/active/<file>.xbrief.json` -- mark running work failed when the scope cannot complete.
 - `task scope:cancel -- <path>` -- move a scope to `cancelled/`.
 - `task scope:restore`, `task scope:block`, `task scope:unblock`, `task scope:demote`, and `task scope:undo:*` -- repair or reverse lifecycle transitions.
-- `task issue:sync-from-xbrief -- <path>` -- post a GitHub issue comment summarizing material AC/status changes for an origin-linked scope xBRIEF (`plan.references` with `x-xbrief/github-issue`). Supports `--dry-run` (print without posting) and `--repo OWNER/NAME` when the reference URI lacks a repo slug. Skips when no material changes since the last successful sync. Closes the reverse-sync gap after `task issue:ingest` (#2540).
+- `task issue:sync-from-xbrief -- <path>` -- post a GitHub issue comment summarizing material AC/status changes for an origin-linked scope xBRIEF (`plan.references` with `x-xbrief/github-issue`). Supports `--dry-run` (print without posting), `--repo OWNER/NAME` when the reference URI lacks a repo slug, and `--allow-cross-repo` for intentional cross-repo sync (refused by default; #2633). Skips when no material changes since the last successful sync. Closes the reverse-sync gap after `task issue:ingest` (#2540).
 - `task issue:ingest -- <N>` / `task issue:ingest -- --all [--label L] [--status S] [--dry-run]` -- ingest GitHub issues as scope xBRIEFs (deduplicates via existing references).
 - `task reconcile:issues [-- --apply-lifecycle-fixes]` -- scan origin-linked xBRIEFs for stale or closed GitHub issues.
 
@@ -234,6 +234,17 @@ flowchart TD
 
 ---
 
+## Framework behavioral events (#635 / #2631)
+
+Review-cycle merge-gate approval is recorded as a structural artifact, not prose-only.
+
+- `task lifecycle:event -- emit plan:approved --plan-ref <pr-url> --approver <login> --approval-phrase <yes|confirmed|approve> --pr-number <N> [--head-sha <sha>]`
+- `deft lifecycle:event emit plan:approved --plan-ref <pr-url> --approver <login> --approval-phrase <yes|confirmed|approve> --pr-number <N> [--head-sha <sha>]`
+
+Writes a `plan:approved` record to `.deft-cache/events.jsonl` with repository (derived from the PR URL when available), approver, optional PR number and approved HEAD SHA, and a timestamp envelope. Repeating the same approval for the same PR/approver/HEAD SHA is idempotent.
+
+---
+
 ## Backlog Triage And Cache Tasks
 
 User-facing surface for the Phase 0 triage workflow and the unified content cache. These commands let agents work an existing backlog locally without repeatedly draining shared GitHub rate limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.79.1",
+  "version": "0.79.2",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "type": "module",
   "files": [

package/packs/lessons/lessons-pack-0.1.json

@@ -565,6 +565,24 @@
       ],
       "source": "Issue #1102. On 2026-05-12 a refinement session (PR #1098) filed #1099 proposing to add .github/dependabot.yml without checking master -- the file already existed (landed via #1070 / v0.29.1). #1099 closed as a stale duplicate the same day; #1100 re-filed as the additive-delta scope.",
       "body": "**Source:** Issue #1102. On 2026-05-12 a refinement session (PR #1098) filed #1099 proposing to add `.github/dependabot.yml` without checking master -- the file already existed (landed via #1070 / v0.29.1). #1099 closed as a stale duplicate the same day; #1100 was re-filed as the additive-delta scope.\n\n**Key insight:** A one-second `git ls-tree origin/master -- <path>` (or `gh api repos/{owner}/{repo}/contents/{path}` without a clone) existence check before filing an add-a-file issue prevents this whole close-and-refile class. If the path already exists, the issue must be scoped to the DELTA vs the on-master state, not the original 'deposit this file' framing.\n\n**Canonical encoding (strongest-applicable layer):** the `!` MUST rule + `\u2297` anti-pattern live in the canonical issue-filing skill `skills/deft-directive-gh-slice/SKILL.md` (Step 5 + Anti-Patterns), cross-referenced from `skills/deft-directive-refinement/SKILL.md` Phase 1. Deterministic shape-coverage: `packages/core/src/content-contracts/skills/gh_slice_prefiling_master_diff.test.ts`.\n\n**Cross-references:** #1070 (`.github/dependabot.yml` originally landed), #1099 (stale-duplicate filing, closed), #1100 (corrected additive-scope refile), PR #1098 (refinement session that surfaced the pattern)."
+    },
+    {
+      "id": "win32-ps-safe-multiline-git-gh-bodies-2026-07",
+      "title": "Windows PowerShell: safe multi-line git/gh bodies (2026-07)",
+      "date": "2026-07",
+      "issue_refs": [
+        "#2646",
+        "#1417",
+        "#240",
+        "#798"
+      ],
+      "tags": [
+        "agent-experience",
+        "github",
+        "scm"
+      ],
+      "source": "Issue #2646 (absorbs #1417). Dogfood on Cursor + Windows PowerShell 2026-07-19 while filing/updating the issue.",
+      "body": "**Source:** Issue #2646 (absorbs #1417). On Windows PowerShell, agents fail when authoring multi-line git/gh payloads via bash heredocs, `<<<` redirection, inline multi-line `--body` flags, or multi-line PS here-strings in the agent command box. Host/agent shell wrappers can also rewrite shell-embedded commit/issue prose before PowerShell executes.\n\n**Failure modes:** (1) Bash heredoc / `<<<` under PowerShell -- parse abort before any gh call. (2) Long inline `gh issue create` / `gh pr create --body` -- argument splitting, angle-bracket parse errors, silent truncation (#1417). (3) Host wrapper injection into shell-embedded git/gh prose (Co-authored-by / Made-with fragments) corrupting PATCH payloads. (4) Partial fixes (escaping, backtick-n, PS here-strings) reintroduce #240 or #798 damage.\n\n**Rule:** never put multi-line markdown inline in a PowerShell agent command. Write a UTF-8 (no BOM) temp file in the OS temp directory via editor/Write/Node (outside the shell), then pass `git commit -F`, `gh --body-file`, or `gh api --input`. Verify posted bodies after PATCH when wrappers may have corrupted earlier attempts.\n\n**Canonical encoding (strongest-applicable layer):** rule body in `content/scm/github.md` \u00a7 Windows PowerShell: safe multi-line git/gh bodies (#2646); agent pointer in `templates/agent-prompt-preamble.md` \u00a7 3.9 and `templates/agents-entry.md` Contextual guardrails lazy-load trigger.\n\n**Cross-references:** #240 (Warp here-string splitting), #798 (PS 5.1 encoding safe write path), #1417 (long gh --body quoting, closed duplicate), #2646."
     }
   ]
 }

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