@deftai/directive-content 0.78.0 → 0.79.1

package/scm/github.md

@@ -309,7 +309,7 @@ Phrasing from `deft policy:show --field=allowDirectCommitsToMaster`. When OFF (d
 
 ## Local git hooks (#747 / #2049)
 
-Project-root `.githooks/` enforce branch policy and encoding gates through the **`deft` CLI only** — no Python `scripts/*.py` dispatch (#2049). Hooks are installed idempotently via `deft setup` (`git config core.hooksPath .githooks`).
+Project-root `.githooks/` enforce branch policy and encoding gates through the **`deft` CLI only** — no Python `scripts/*.py` dispatch (#2049). `deft init` and `deft update` deposit hook files; `deft setup` / `task setup` wires `core.hooksPath=.githooks` and refuses when the directory is missing (#2530).
 
 | Hook | Dispatches | Purpose |
 |------|------------|---------|
@@ -318,7 +318,7 @@ Project-root `.githooks/` enforce branch policy and encoding gates through the *
 
 - ! Verify wiring after install or framework upgrade: `deft verify:hooks-installed` (also wired into `deft check`).
 - ! After upgrading the framework payload, run `deft update` from the project root to refresh `.githooks/` to the current TS-native templates (#2049). Stale hooks that still invoke `python scripts/preflight_branch.py` or other legacy paths fail `deft verify:hooks-installed`.
-- ~ Recovery when hooks are stale or broken: `deft setup` (re-installs hooks path) or `deft update` (refreshes hook files from the deposited payload).
+- ~ Recovery when hooks are stale or broken: `deft update` (deposits/refreshes hook files from the framework payload, including on an already-current deposit) then `deft setup` / `task setup` (wires `core.hooksPath` when files are present).
 
 ## Destructive gh verbs (#1019)
 

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

@@ -217,7 +217,8 @@ For each phase:
 2. ! **Test first** — write tests before implementation (TDD)
 3. ! **Implement** — make tests pass, following deft coding standards
 4. ! **Verify** — run `task check`, fix any issues
-5. ! **Checkpoint** — tell user what's done, what's next
+5. ! **Origin sync** — when this phase materially changed an origin-linked scope xBRIEF (`plan.references` includes `x-xbrief/github-issue`), run `task issue:sync-from-xbrief -- <path>` (or `--dry-run` to preview) so the linked GitHub issue receives a sync comment; if skipped, document why in the PR or session notes (#2540)
+6. ! **Checkpoint** — tell user what's done, what's next
 
 - ⊗ Move to next phase until current phase passes all checks
 

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

@@ -254,6 +254,14 @@ The task scans every xBRIEF with a GitHub-backed reference (whether the referenc
 ⊗ Auto-update xBRIEFs based on origin changes without user approval
 ⊗ Overwrite intentional divergence -- if a xBRIEF has been refined beyond the original issue, preserve the refinement
 
+### Origin sync after material xBRIEF edits (#2540)
+
+! When this refinement pass **materially updates** an origin-linked scope xBRIEF (AC, `plan.status`, or `plan.items` statuses/titles), run `task issue:sync-from-xbrief -- <path>` to post a sync comment on the linked GitHub issue so the human-facing tracker stays current. Use `--dry-run` to preview the comment without posting.
+
+! If sync is intentionally skipped (offline, issue frozen, divergence is deliberate), document the skip reason in the session notes or PR body — do not silently leave the origin stale.
+
+⊗ Materially edit an origin-linked xBRIEF without running `issue:sync-from-xbrief` or documenting why it was skipped
+
 ## Phase 4 -- Promote/Demote
 
 ! Move xBRIEFs between lifecycle folders using deterministic task commands. The status values below align with the canonical v0.6 Status enum (`draft | proposed | approved | pending | running | completed | blocked | failed | cancelled`) — note that `failed` is also a valid terminal transition for active work that could not complete.

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

@@ -37,12 +37,20 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 task policy:allow-direct-commits -- --confirm
 ```
 
-This writes `plan.policy.allowDirectCommitsToMaster = true` on `xbrief/PROJECT-DEFINITION.xbrief.json` with a capability-cost disclosure. After the release completes (or if the session aborts), restore enforcement:
+This writes `plan.policy.allowDirectCommitsToMaster = true` on `xbrief/PROJECT-DEFINITION.xbrief.json` with a capability-cost disclosure. After the release completes (or if the session aborts), restore enforcement **and commit the restore in the same closeout** (#2623):
 
 ```
 task policy:enforce-branches
+# enforce flips the typed flag to false locally — the commit that lands that
+# flip cannot use the typed opt-in anymore. Scope the emergency env bypass to
+# ONLY this closeout commit+push (do NOT export it for the whole session):
+DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 git add xbrief/PROJECT-DEFINITION.xbrief.json meta/policy-changes.log
+DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 git commit -m "chore(policy): restore branch protection after vX.Y.Z"
+DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1 git push origin HEAD
 ```
 
+⊗ Leave `allowDirectCommitsToMaster=true` on origin after publish. ⊗ Run `policy:enforce-branches` and leave the dirty restore under protection ON without committing (forces a follow-up PR — the v0.79.0 / #2619 failure mode).
+
 **Branch-guard probe (either path).** Regardless of which opt-out path you chose, confirm the guard passes before Phase 1 mutates state:
 
 ```
@@ -113,13 +121,15 @@ The dry-run prints `[N/13] <step>... DRYRUN (would <action>)` for every pipeline
 
 ## Phase 3 — E2E sanity
 
-! Invoke `task release:e2e` against an auto-created+destroyed temp repo to verify the full pipeline shape works end-to-end before touching the real repo.
+! Invoke `task release:e2e` against an auto-created temp repo to verify the full pipeline shape works end-to-end before touching the real repo.
 
 ```
 task release:e2e
 ```
 
-The harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke-test rehearsal, and destroys the temp repo in a `try/finally` clause. Cleanup runs even if the rehearsal fails. If `gh repo delete` fails, surface the manual-cleanup hint to the user and continue.
+The harness provisions `deftai/deftai-release-test-<ts>-<uuid6>`, runs the smoke-test rehearsal, and **by default keeps** the temp repo (#2572). Stderr always includes the full `owner/slug` and a copy-pasteable manual-cleanup command (`gh repo delete <owner>/<slug> --yes`). Privileged environments (CI or an operator with `delete_repo`) MAY pass `task release:e2e -- --destroy-repo` to attempt auto-delete; destroy failure emits a WARN and does **not** block Phase 4 when the rehearsal succeeded.
+
+! After Phase 3, the agent MUST NOT retry or escalate temp-repo deletion. Include any leftover temp repo(s) in the phase summary for the operator to clean up manually.
 
 ! Treat a non-zero exit from `task release:e2e` as a hard refusal to proceed to Phase 4. Surface the diagnostic and ask whether to debug (return to Phase 1) or abort (`quit`).
 
@@ -281,4 +291,6 @@ Where `<one-line guidance>` is one of:
 - ⊗ Hardcode `master` as the base branch -- delegate to the configured base branch from `task release --base-branch <branch>`
 - ⊗ Skip the post-create verify-isDraft gate (#724) -- a successful `gh release create` exit code does NOT prove the release actually landed in draft state; the 5-second poll-and-flip gate in `scripts/release.py` Step 11 is the only safety net against operator-error variants and partial-success races, and any manual recovery path that bypasses `scripts/release.py` MUST run `gh release view --json isDraft` followed by `gh release edit --draft=true` on `isDraft=false` before handing off to Phase 5
 - ⊗ Manually rewrite the Phase 8 Slack `*Summary*:` line to deviate from the CHANGELOG `[<version>]` blockquote -- the canonical narrative is authored ONCE at Phase 1 via `--summary` and propagates verbatim across all three audiences (CHANGELOG / GitHub release body / Slack). Per-audience hand-edits create documentation drift that the deterministic `--summary` flow is designed to prevent. If the operator wants Slack-specific tone, fold it into the canonical Phase 1 wording before passing `--summary`, OR amend the CHANGELOG blockquote BEFORE Phase 8 so all three surfaces stay aligned
-- ⊗ Export `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` for the entire release session or wrap `task release` / `task ci:local` in it (#1553) -- the env var is process-wide and leaks into nested tests and temporary repos, producing false preflight failures. Prefer `task policy:allow-direct-commits -- --confirm` and restore with `task policy:enforce-branches` after the cut
+- ⊗ Export `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` for the entire release session or wrap `task release` / `task ci:local` in it (#1553) -- the env var is process-wide and leaks into nested tests and temporary repos, producing false preflight failures. Prefer `task policy:allow-direct-commits -- --confirm` and restore with `task policy:enforce-branches` after the cut (closeout commit+push may use a **scoped** env prefix on those three git commands only — see Branch-Protection Policy Guard, #2623)
+- ⊗ Pass `--allow-coverage-debt=#N` unquoted on Windows PowerShell (#2621) -- `#` starts a comment and silently drops the issue number. Use `--allow-coverage-debt=N` or `--allow-coverage-debt="#N"`
+- ⊗ Soft-pass coverage debt on consecutive releases when the prior cut already cited debt (#2618 / #2573) -- restore real branch coverage >= 85% instead of reusing the escape hatch

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

@@ -57,7 +57,7 @@ This path became first-class in #1342 (platform adapter slices 1-3) and is fully
 
 ~ **Windows + Grok Build (#1353):** When issuing shell commands via `run_terminal_command` on this platform, avoid `|`, `>`, or `2>&1` in the command string — use Python `pathlib`/`subprocess` or plain `task` targets instead to avoid wrapper leakage. See `templates/agent-prompt-preamble.md` §3.5 for the full escape hatch list.
 
-! **Windows + Cursor Task-tool console storm (#2563):** Local Cursor Task subagents on Windows have frozen the host by flooding visible `cmd.exe` / `conhost` windows (observed with both parallel and serial Task agents; in-parent work stayed stable). Prefer one of: (1) in-parent / serial monitor-owned implementation, (2) cloud workers, or (3) after the #2563 mitigations (`windowsHide` + warm-dist skip in `engine:_ts-build`) are on the branch under test, keep local Task concurrency at **1** and prefer `pnpm exec` / warm `dist/bin.js` over repeated cold `task` rebuilds. See `templates/agent-prompt-preamble.md` §3.8. ⊗ Launch a wide parallel local Cursor Task cohort on Windows without that mitigation or an explicit operator acceptance of host-freeze risk.
+! **Windows + Cursor Task-tool console windows (#2563):** Local Cursor Task swarms on Windows are first-class. Shipped mitigations (do not regress): `windowsHide: true` (CREATE_NO_WINDOW) on engine/spawn paths, and warm-dist skip via `tasks/ts-build-fresh.cjs` so `engine:_ts-build` does not cold-rebuild when `packages/cli/dist` is current. See `templates/agent-prompt-preamble.md` §3.8. ! Default to **local** Task workers on Windows (not cloud-for-Windows). Parallel cohorts are allowed — do not force concurrency=1 for #2563. ⊗ Drop or weaken those mitigations without a replacement that keeps Windows local swarm workable.
 
 ## Prerequisites
 

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

@@ -1,12 +1,13 @@
 ---
 name: deft-directive-triage
 description: >-
-  Triage-cache hygiene and "what's next?" queue selection -- the agent-facing
-  playbook for syncing the triage cache, classifying candidates, presenting a
-  ranked queue, walking per-item decisions (accept / reject / defer / needs-ac
-  / mark-duplicate), and auditing the session. Use when the operator asks what
-  to work on next, wants to build a cohort, work the cache, or run a triage
-  hygiene pass.
+  Triage-cache hygiene and "what's next?" work selection (ordered plan or
+  ranked queue) -- the agent-facing playbook for syncing the triage cache,
+  classifying candidates, presenting a ranked queue or binding to an active
+  plan-sequence, walking per-item decisions (accept / reject / defer /
+  needs-ac / mark-duplicate), and auditing the session. Use when the operator
+  asks what to work on next, wants to build a cohort, work the cache, or run a
+  triage hygiene pass.
 triggers:
   - triage
   - triage hygiene
@@ -26,7 +27,7 @@ triggers:
 
 # Deft Directive Triage
 
-Triage-cache hygiene + "what's next?" queue selection. Operates against the unified `.deft-cache/github-issue/` mirror (#883 Story 2) and the append-only `xbrief/.eval/candidates.jsonl` audit log (#845 Story 2); writes only via the canonical `task triage:*` verbs.
+Triage-cache hygiene + "what's next?" work selection (ordered plan or ranked queue). Operates against the unified `.deft-cache/github-issue/` mirror (#883 Story 2) and the append-only `xbrief/.eval/candidates.jsonl` audit log (#845 Story 2); writes only via the canonical `task triage:*` verbs.
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
@@ -38,11 +39,17 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 ! Every numbered-menu prompt rendered in this skill (Phase 2 candidate selection, Phase 3 per-item decision walk) ! MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): render the canonical numbered menu in chat unless the host UI visibly preserves numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options are `Discuss` and `Back`, in that order, and the Discuss-pause semantic from the contract applies verbatim -- on `Discuss` the agent halts the in-progress sequence and resumes only on an explicit user signal.
 
+## Work selection fork (#2542 / #2402)
+
+Directive does not guess your mix: **ordered plan** (`task plan-sequence:*`) when you know the next units in order, or **ranked queue** (`task triage:queue`) when picking from the backlog. Labels bias the queue; they do not override an active plan.
+
+! Before Phase 2 on bare "what's next?", run `task plan-sequence:current`. Active sequence → that entry only; exhausted → fail closed. Explicit "what's the queue?" / "build a cohort" → Phase 2. See `commands.md` § Backlog Triage → Two paths.
+
 ## Phase 0 -- Sync
 
 ! Probe cache freshness before doing any classification or selection. Stale cache reads produce stale decisions; the gate is the contract.
 
-1. ! Run `task verify:cache-fresh` (D5 / #1127). Exit 0 -> proceed to Phase 1. Exit 1 (stale or blocked) -> refresh per the printed remediation. Exit 2 (no bootstrap) -> run `task triage:bootstrap` first.
+1. ! Run `task verify:cache-fresh` (D5 / #1127). Exit 0 -> proceed to Phase 1. Exit 1 (stale or blocked) -> refresh per the printed remediation. Exit 2 (no bootstrap) -> run `task triage:bootstrap` first. When the cache has zero entries, read paths auto-fetch from GitHub first (#2575).
 2. ~ Refresh path: `task cache:fetch-all -- --source=github-issue --repo OWNER/NAME` for an already-bootstrapped project (idempotent, TTL-aware, re-applies the #883 scanner v2 quarantine rules); `task triage:bootstrap` for a first-time seed.
 3. ~ If `xbrief/active/*.xbrief.json` references are in play, run `task triage:refresh-active` to compare cached `meta.json.fetched_at` against live upstream `updatedAt` and surface drift before the queue is rendered.
 4. ~ When the one-liner emitted by the session-start ritual carries a `[scope-drift] N` segment (D14 / #1133), run `task triage:scope-drift` to see the per-label / per-milestone breakdown of upstream signals on cached open issues that fall outside the active `plan.policy.triageScope[]` subscription. The output documents both opt-in (`task triage:subscribe -- --label=<L>`) and opt-out (`task triage:scope-drift -- --ignore-label=<L>`) paths -- pick one before walking the queue so the cohort reflects the operator's current intent rather than a stale subscription.
@@ -59,14 +66,9 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 5. ⊗ Re-classify items already terminally decided (accept / reject / mark-duplicate) without explicit operator approval -- the audit log is append-only and supersession runs through Layer 5 (`task triage:reset <N>`), not through silent re-walks.
 6. ⊗ Block issue creation solely because no label was selected, or invent ad hoc labels outside the repository's existing label set.
 
-
-## Ordered-plan precedence (#2402)
-
-! Before queue selection on bare "what's next?", run `task plan-sequence:current`. Active sequence → that entry only; exhausted → fail closed and ask. Explicit "what's the queue?" / "build a cohort" still use Phase 2. Chaining is non-authorizing. ⊗ Reuse triage `continuationNumbers`/`continuationOrder` for ordered-plan state.
-
 ## Phase 2 -- Present
 
-! When no ordered-plan is active, render `task triage:queue` before suggesting work (#1149). Active sequence yields to the ordered-plan entry (#2402).
+! Apply the Work selection fork gate (#2542): when no ordered-plan is active, render `task triage:queue` before suggesting work (#1149). Active sequence yields to the ordered-plan entry (#2402).
 
 1. ! Run `task triage:queue --limit=N` (D11 / #1128) -- default `N=10` per the umbrella Current Shape v3 WIP cap. Output is grouped `[RESUME]` -> `[URGENT]` -> untriaged -> other; within-group ordering follows the consumer-supplied `plan.policy.triageRankingLabels[]` (framework default empty per §12 boundary), tiebroken by `updated_at` descending.
 2. ! For per-item detail, run `task triage:show <N>` -- prints the cached upstream payload, the latest triage decision, the audit timeline, and the active-xBRIEF reference flag. Exit 0 on hit, 1 on cache miss (re-sync per Phase 0).
@@ -118,6 +120,7 @@ What would you like to do with this candidate?
 ## Anti-Patterns
 
 - ⊗ Recommend a specific issue without first consulting `task triage:queue` (binding under AGENTS.md `## Cache-as-authoritative work selection (#1149)`).
+- ⊗ Conclude "nothing to do" from `xbrief/{pending,active}` scans or live GitHub reads alone — `task triage:queue` is the ranked superset (#2576).
 - ⊗ Walk the queue against a stale cache (Phase 0 gate skipped).
 - ⊗ Reimplement audit-log append / `proposed/` write inline -- the `task triage:*` verbs own those surfaces (#845, #883).
 - ⊗ Treat `defer` / `needs-ac` as terminal -- they intentionally resurface on the next pass.

package/templates/agent-prompt-preamble.md

@@ -211,17 +211,23 @@ PYTEST_ADDOPTS="--basetemp=$(mktemp -d)/pt" task check
 
 A clean result under an isolated basetemp is attributable to your change, not to the ambient shared-`/tmp` race. Do NOT point `--basetemp` at a static path shared across workers -- that re-introduces the collision. Solo / single-run invocations on a private worktree do not require this, but it is harmless to apply unconditionally.
 
-## 3.8 Windows Cursor Task-tool console storm (#2563)
+## 3.8 Windows Cursor Task-tool console windows (#2563)
 
-On Windows, Cursor Task-tool local subagents can open a visible `cmd.exe` / `conhost` window per shell turn. Framework source checkouts amplify this: many `task <verb>` calls run `engine:_ts-build` → `pnpm`/`tsc` via `shell: true`. Parallel (and even serial) Task agents have frozen the maintainer host; completing the same stories in-parent (no Task subagent) stayed stable.
+On Windows, Cursor Task-tool local subagents historically opened a visible `cmd.exe` / `conhost` window per shell turn. Framework source checkouts amplified this when every `task <verb>` cold-ran `engine:_ts-build` → `pnpm`/`tsc` via `shell: true`.
+
+**Shipped mitigations (keep; do not regress):**
+
+- `windowsHide: true` (CREATE_NO_WINDOW) on engine invoke / package-manager probe / `spawnCommandText` paths
+- Warm-dist skip via `tasks/ts-build-fresh.cjs` so `_ts-build` does not rebuild when `packages/cli/dist` is current (override with `DEFT_FORCE_TS_BUILD=1` / `DEFT_SKIP_TS_BUILD=1`)
 
 **Directive rule for orchestrators on Windows:**
 
-- ! Prefer in-parent implementation or cloud workers for Cursor Task cohorts until the branch under test includes the #2563 mitigations (`windowsHide` on engine spawns + warm-dist skip via `tasks/ts-build-fresh.cjs`).
-- ! When local Task agents are required, keep concurrency at **1**, reuse a warm `packages/cli/dist/bin.js` (set `DEFT_SKIP_TS_BUILD=1` only when dist is known current), and avoid spawning nested Task agents from workers.
-- ⊗ Launch a multi-agent local Cursor Task swarm on Windows that multiplies cold `task` rebuilds without operator acceptance of host-freeze risk.
+- ! Use **local** Cursor Task swarm workers as the default dispatch path — same as other platforms. Do not route to cloud solely because the host is Windows.
+- ! Parallel local cohorts are allowed; do not force concurrency=1 because of #2563.
+- ~ Prefer the normal warm `task` / `dist/bin.js` path; avoid unnecessary `DEFT_FORCE_TS_BUILD=1` across a parallel cohort.
+- ⊗ Drop or weaken the #2563 `windowsHide` / warm-dist mitigations without a replacement that keeps Windows local swarm workable.
 
-Reference: issue #2563; swarm skill Platform Requirements; env scrub + stdio inherit for nested Task recursion (#2554 / #2438) are necessary but not sufficient alone.
+Reference: issue #2563; swarm skill Platform Requirements; env scrub + stdio inherit for nested Task recursion (#2554 / #2438).
 
 ## 4. pre-pr and review-cycle skills
 

package/templates/agents-consumer-header.md

@@ -10,6 +10,7 @@ Scoped work, ranked queue, and tracked bugs live in authoritative sources — no
 
 - Project identity → `xbrief/PROJECT-DEFINITION.xbrief.json`
 - Scoped work → `xbrief/` lifecycle folders
+- Work selection → default ranked queue (`deft triage:queue`); lock a short ordered plan (`deft plan-sequence:set`) when you want bounded delivery — see `deft/commands.md` § Backlog Triage → Two paths
 - Ranked queue → `deft triage:queue` / `deft triage:welcome`
 - Tracked bugs → GitHub issues
 

package/templates/agents-entry.md

@@ -27,9 +27,9 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ## Cache-as-authoritative work selection (#1149)
 
-! "what next?" → ordered-plan first (#2402 / `deft plan-sequence:*`); else `deft triage:queue --limit=10` (D11) — `commands.md` § Backlog Triage.
+! "what next?" → two work-selection modes (#2402): **ordered plan** (`deft plan-sequence:*`) or **ranked queue** (`deft triage:queue`) — `commands.md` § Backlog Triage → Two paths. ordered-plan first; else `deft-directive-triage` + `deft triage:queue --limit=10` (D11). Empty cache auto-populates from GitHub (#2575).
 
-⊗ Recommend work without queue/plan consult; ⊗ widen past an exhausted plan.
+⊗ Recommend work without queue/plan consult; ⊗ widen past an exhausted plan; ⊗ conclude "nothing to do" from `xbrief/{pending,active}` folder scans or GitHub-only reads without `deft triage:queue` (#2576).
 
 ## Umbrella status reading (#1152 / #2066)
 
@@ -85,7 +85,7 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ## Contextual guardrails (runtime-detect lazy-load)
 
-! Lazy-load `.deft/core/scm/github.md` before risky ops (#2157 / #2369): PowerShell → `deft verify:encoding` (#798); TS capture (#1366); cascade → `deft pr:wait-mergeable-and-merge` (#1369); SCM → `deft verify:scm-boundary` (#884).
+! 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`.
 
 ## Development Process