@deftai/directive-content 0.76.0 → 0.78.0

package/templates/agent-prompt-preamble.md

@@ -49,6 +49,28 @@ Worked example (a swarm-cohort member):
 
 A `solo` dispatch sets `dispatch_kind: solo`, MAY leave `allocation_plan_id` / `batching_rationale` null, and lists only its own xBRIEF in `cohort_vbriefs`; such a section does NOT by itself satisfy the consent token, so the Story Start Gate falls through to the #1371 prose carve-out for a lone interactive dispatch.
 
+## 2.55 Ordered-plan continuation boundary (#2402)
+
+When the operator supplies an ordered plan (delivery sequence, cohort, checklist, review batch, or phase list), continuation language is bounded by that sequence — not by the triage queue, skill chaining, or adjacent backlog memory.
+
+! Record the active sequence with `task plan-sequence:set -- --file <json>` (persists `.deft/plan-sequence.json`). Inspect with `task plan-sequence:current`; advance with `task plan-sequence:advance`; clear with `task plan-sequence:clear`.
+
+! Before creating or dispatching a new external work unit (PR, branch, story activation, sub-agent implementation task), when a sequence is active run `task verify:plan-sequence -- --target-kind <kind> --target <id-or-title>`. Exit non-zero means fail closed.
+
+! "next" / "what's next?" / "proceed" / "resume" / "move on" means **exactly one** next unit in the **narrowest active** ordered sequence. Unit type is inherited from that sequence.
+
+! When the sequence is exhausted (`continuation_past_final` defaults false), stop and ask. Do not open PR 3 after an approved two-PR plan. Do not consult `task triage:queue`, open-issue intuition, or skill-chaining instructions to invent the next unit.
+
+! Explicit queue/backlog asks ("what's the queue?", "build a cohort") remain queue-driven even mid-plan. Bare "what's next?" is **not** such an ask while a sequence is active.
+
+! Skill-exit chaining instructions are advisory entrypoints only — they do not authorize adjacent work unless it matches the current ordered-plan entry or a fresh operator directive.
+
+! Review-cycle exit returns to the ordered-plan context and authorizes at most the next sequence entry (after `plan-sequence:advance` for the completed PR). Cohort/build flows stop after the final approved entry.
+
+⊗ Reuse triage queue `continuationNumbers` / `continuationOrder` for ordered-plan state — those fields are for `[RESUME]` / stale-defer ordering only.
+
+⊗ Treat affirmative continuation ("yes", "proceed") as permission to widen past the approved sequence.
+
 ## 2.6 Provider-neutral worker metadata (#1531)
 
 Heterogeneous swarm dispatch (#1531) assigns each worker a **dispatch provider** (the runtime primitive that launched the agent), a **worker role** (what the agent is allowed to do), and a **selected backend** or **routing policy** (how the harness maps that role to a concrete agent). These fields are provider-neutral: Composer-class coding agents, Grok Build (`spawn_subagent`), Cursor/cloud agents, and future adapters share the same contract.
@@ -189,6 +211,18 @@ 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)
+
+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.
+
+**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.
+
+Reference: issue #2563; swarm skill Platform Requirements; env scrub + stdio inherit for nested Task recursion (#2554 / #2438) are necessary but not sufficient alone.
+
 ## 4. pre-pr and review-cycle skills
 
 Before pushing any branch:
@@ -203,8 +237,55 @@ Anti-pattern: pushing without pre-pr and relying on Greptile to find issues. Tha
 The active host harness may expose its own review-labeled surfaces. On Cursor these are the `bugbot` and `security-review` Task **subagent types** and the `review-bugbot` / `review-security` **skills**; other harnesses may ship equivalents. A generic operator request to "review" / "get this reviewed" / "use sub-agents for reviews" must NOT be routed to those host-native tools as the review of record.
 
 - ! Route ALL review work through the canonical `skills/deft-directive-review-cycle/SKILL.md` surface. Map a generic review request to the review cycle **by intent**, not by literal keyword -- "review this", "get this reviewed", and "use sub-agents for reviews" all mean run `deft-directive-review-cycle` (extends the #1862 / #2261 intent-routing fix).
-- ~ Host review tools (Cursor `bugbot` / `security-review` subagent types, `review-bugbot` / `review-security` skills, or any future host equivalent) MAY be folded in as *advisory* finding sources INSIDE the review cycle -- the #2019 harness-aware-reviewer path -- with their findings batched alongside the Greptile / bot findings the cycle already processes.
-- ⊗ Substitute a host-native review subagent type or `review-*` skill for `deft-directive-review-cycle` as the review surface. The host tools are advisory inputs folded into the cycle, never a replacement for it. Reaching for them on a bare "review" request is the 3rd recurrence of the #1862 / #2261 wrong-review-surface class (see also #2019, #2018).
+- ! Map **PR shepherding intent** the same way: `babysit`, `babysit this PR`, `shepherd`, `watch the PR`, and the Cursor product action **babysit-pull-request-in-cloud** all mean run `deft-directive-review-cycle` on Deft-managed repos (`.deft/core/` installed) -- NOT the Cursor-global `babysit` skill (`~/.cursor/skills-cursor/babysit/SKILL.md`) (#2261).
+- ~ Host review tools (Cursor `babysit` / `bugbot` / `security-review` subagent types, `review-bugbot` / `review-security` skills, or any future host equivalent) MAY be folded in as *advisory* finding sources INSIDE the review cycle -- the #2019 harness-aware-reviewer path -- with their findings batched alongside the Greptile / bot findings the cycle already processes.
+- ⊗ Substitute a host-native review subagent type, Cursor global `babysit`, or `review-*` skill for `deft-directive-review-cycle` as the review surface. The host tools are advisory inputs folded into the cycle, never a replacement for it. Reaching for them on a bare "review" or "babysit" request is the #1862 / #2261 wrong-review-surface class (see also #2019, #2018).
+
+## 4.6 Cloud PR-shepherd dispatch -- review-monitor worked example (#2261)
+
+When an operator triggers **babysit-pull-request-in-cloud** (or equivalent PR-shepherding intent) on a Deft-managed repo, the orchestrator MUST dispatch a **review-monitor** worker with this preamble (or a reference to `templates/agent-prompt-preamble.md`) and an explicit mandate to read `skills/deft-directive-review-cycle/SKILL.md` before any PR mutation.
+
+Worked example (cloud background review-monitor on PR #1037):
+
+```markdown
+## Allocation context
+
+- dispatch_kind: solo
+- allocation_plan_id: null
+- batching_rationale: null
+- cohort_vbriefs: []
+- operator_approval_evidence: operator selected babysit-pull-request-in-cloud 2026-07-03
+
+## Worker metadata
+
+- dispatch_provider: cursor-cloud-agent
+- worker_role: review-monitor
+- selected_backend: cursor-cloud
+- routing_policy: null
+- resolved_model: null
+- model_source: harness-default explicit
+
+## Runtime and GitHub auth mode
+
+- runtime_mode: cloud-headless
+- github_auth_mode: injected-token
+
+## Unit of work
+
+drive-to: merge-ready on PR #1037 (repo: deftai/deftvisage, branch: fix/visage-repo-org-scoping)
+
+## Mandates
+
+1. First tool call: read AGENTS.md; confirm Deft alignment.
+2. Read `templates/agent-prompt-preamble.md` (binding) and `skills/deft-directive-review-cycle/SKILL.md` end-to-end -- NOT `~/.cursor/skills-cursor/babysit/SKILL.md`.
+3. Run review-cycle Phase 1 process audit before the fix loop; batch Phase 1 + Phase 2 fixes per review-cycle discipline.
+4. Poll terminal verdict via `task pr:watch -- <N>` when waiting on Greptile/SLizard (#1056).
+5. Exit only on review-cycle Step 6 fail-closed all-of (#1259) -- ad hoc SLizard P2 fixes without the exit predicate are insufficient.
+
+DONE: include PR URL, role review-monitor, and whether Step 6 CLEAN was reached.
+```
+
+Anti-pattern: dispatching `Task(environment=cloud)` with only the Cursor global babysit skill attached and no preamble / `deft-directive-review-cycle` path -- that is the #2261 recurrence class.
 
 ## 5. REST-by-default for read-only gh calls
 

package/templates/agents-entry.md

@@ -7,16 +7,7 @@ Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
 
 ## Session routing (#2176)
 
-! **Read-only default** until mutation intent (Q&A, Plan Mode, ticket-shaping): load AGENTS.md, main.md, USER.md, `xbrief/PROJECT-DEFINITION.xbrief.json`; confirm Deft alignment ("Deft Directive active" + addressing-name from USER.md); ⊗ do not run mutable `deft session:start`, triage welcome, sync, or branch-policy ceremony unless the operator asks or the task is implementation-ready (#2176). Full contract: `.deft/core/commands.md` § Session routing.
-
-**Bootstrap card** (before answering):
-- `deft` / `directive` won't run → README.md § Cold-start bootstrap (#2273); ⊗ never `.deft/core/`
-- Pre-cutover artifacts → `.deft/core/.agents/skills/deft-directive-setup/SKILL.md` § Pre-Cutover Detection Guard (#2068)
-- USER.md missing → setup SKILL Phase 1; `xbrief/PROJECT-DEFINITION.xbrief.json` missing → setup SKILL Phase 2 (#1813); ⊗ respond before phase completes
-- Config complete → read main.md → USER.md → PROJECT-DEFINITION (USER.md wins on conflicts); ~ `deft-directive-sync` on return
-
-**Mutation boundary:** code-writing, scope lifecycle, `start_agent`, commits, push, or release → `deft session:start` then `deft verify:session-ritual -- --tier=gated` per `.deft/core/commands.md` § Session-start ritual (#1149).
-- ? `deft session:start -- --read-only` — alignment only, no ritual-state (#2176)
+! **Read-only default** until mutation intent: load AGENTS.md / main.md / USER.md / `xbrief/PROJECT-DEFINITION.xbrief.json`; resolve USER.md via `deft session:start` (`USER.md resolved …`; win32 `%APPDATA%\deft\USER.md`; unix `~/.config/deft/USER.md`; ⊗ invent `~/.config/deft` on Windows #2544); confirm Deft alignment + addressing-name; ⊗ no mutable `deft session:start` / triage welcome / sync / branch-policy unless asked or implementation-ready (#2176) — `.deft/core/commands.md` § Session routing. Bootstrap: cold-start → README § Cold-start (#2273) ⊗ never `.deft/core/`; pre-cutover → setup Pre-Cutover (#2068); missing USER.md / PROJECT-DEFINITION → setup Phase 1/2 (#1813) ⊗ before answering; else main → USER → PROJECT-DEFINITION; ~ sync. Mutation → `deft session:start` then `deft verify:session-ritual -- --tier=gated` (#1149). ? `deft session:start -- --read-only` (#2176).
 
 ## Session-start ritual (#1149)
 
@@ -24,11 +15,11 @@ Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
 
 ## WIP cap
 
-! Respect `plan.policy.wipCap` (default 20) — at cap `deft scope:promote` refuses; relief via `deft scope:demote --batch --older-than-days 30` (#2319 / #1121). Full WIP workflow: `.deft/core/.agents/skills/deft-directive-swarm/SKILL.md`.
+! Respect `plan.policy.wipCap` (default 20) — at cap `deft scope:promote` refuses; relief via `deft scope:demote --batch --older-than-days 30` (#2319 / #1121). Full WIP: `.deft/core/.agents/skills/deft-directive-swarm/SKILL.md`.
 
 ## xBRIEF layout (#2034 / #2110)
 
-Projects on legacy `vbrief/` still read-accepted; run `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8). `x-vbrief/` tokens read-accepted until migrated.
+Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8). `x-vbrief/` tokens read-accepted until migrated.
 
 ## Unmanaged project header (#2065)
 
@@ -36,9 +27,9 @@ Projects on legacy `vbrief/` still read-accepted; run `deft migrate:xbrief` for
 
 ## Cache-as-authoritative work selection (#1149)
 
-! "what next?" / cohort / queue → `deft triage:queue --limit=10` (D11 / #1128); present ranked list first — `.deft/core/commands.md` § Backlog Triage.
+! "what next?" → ordered-plan first (#2402 / `deft plan-sequence:*`); else `deft triage:queue --limit=10` (D11) — `commands.md` § Backlog Triage.
 
-⊗ Recommend issue or xBRIEF without `deft triage:queue` (or showing its result).
+⊗ Recommend work without queue/plan consult; ⊗ widen past an exhausted plan.
 
 ## Umbrella status reading (#1152 / #2066)
 
@@ -48,61 +39,65 @@ Projects on legacy `vbrief/` still read-accepted; run `deft migrate:xbrief` for
 
 ## Deterministic questions runtime obligation (#1470)
 
-! Any agent-initiated structured question MUST include `Discuss` and `Back` as the final two options — full Discuss-pause semantic in `.deft/core/contracts/deterministic-questions.md` (#1470 / #767).
+! Structured questions MUST end with `Discuss` and `Back` — `.deft/core/contracts/deterministic-questions.md` (#1470 / #767).
 
 ## Issue body→comments reading (#2143)
 
-! Fetch body + `issues/<N>/comments` via REST before requirements or dispatch — `.deft/core/templates/agent-prompt-preamble.md` § 5.6 / `deft issue:ingest` (#2143).
-
-⊗ Build a dispatch envelope from the issue body alone when the issue has comments.
+! Fetch body + `issues/<N>/comments` via REST before requirements or dispatch — `.deft/core/templates/agent-prompt-preamble.md` § 5.6 / `deft issue:ingest` (#2143). ⊗ Build a dispatch envelope from the issue body alone when the issue has comments.
 
 ## Content packs
 
-! Before improvising, discover packs with `deft packs:slice --list-packs`, then load via `deft packs:slice <pack> --list` / `deft packs:slice <pack> <slice>` — full pack surface in `.deft/core/commands.md` (§ packs); never enumerate pack or slice names here.
+! Before improvising: `deft packs:slice --list-packs`, then `deft packs:slice <pack> --list` / `deft packs:slice <pack> <slice>` — `commands.md` (§ packs); never enumerate names here.
 
 ## Codebase MAP Projection (#1595 / #1498)
 
-! `plan.architecture.codeStructure` is durable SoT; `.planning/codebase/MAP.md` is generated orientation — use `deft codebase:map` / `deft verify:codebase-map-fresh` (`.deft/core/commands.md` § Project And Architecture). ⊗ Do not hand-edit the MAP, block unrelated work on stale/absent MAP, or treat the projection as more authoritative than the xBRIEF metadata (#1595 / #1498).
+! `plan.architecture.codeStructure` is durable SoT; `.planning/codebase/MAP.md` is generated — `deft codebase:map` / `deft verify:codebase-map-fresh` (`commands.md`). ⊗ Do not hand-edit MAP, block on stale/absent MAP, or elevate projection above xBRIEF (#1595 / #1498).
 
 ## Skills
 
-! Skill routing lives in the **Skills Index** (Level-0) in `.deft/core/REFERENCES.md` — scan it before improvising; read a `SKILL.md` only on index match. `welcome` / `onboard triage` → `deft triage:welcome --onboard` (N3 / #1143); `lessons` / `prior art` → Content packs `packs:slice` above.
+! **Skills Index** (Level-0) in `.deft/core/REFERENCES.md` — scan before improvising; read `SKILL.md` only on index match. `welcome` / `onboard triage` → `deft triage:welcome --onboard` (N3 / #1143); lessons → packs:slice.
+
+## Skill pin policy (#2508)
+
+! Process-critical skills with false-negative risk MUST be named in AGENTS.md (always-pin tier) — tier definitions: `.deft/core/docs/skill-pin-policy.md` (#2508).
+! **Default always-pins:** `deft-directive-build`, `deft-directive-pre-pr`, `deft-directive-review-cycle`, `deft-directive-swarm` — read each `SKILL.md` when that work type starts.
+⊗ Pin entire language packs, deployment docs, or framework bulk into AGENTS.md — pins are for false-negative-sensitive process gates only (#2508).
 
 ## Review-surface precedence (#2308)
 
-! Route review work through `deft-directive-review-cycle` — `.deft/core/.agents/skills/deft-directive-review-cycle/SKILL.md`; host tools (`bugbot`, `security-review`, `review-*` skills) advisory-only (#2308).
+! Route PR shepherding / review work through `deft-directive-review-cycle` — `.deft/core/.agents/skills/deft-directive-review-cycle/SKILL.md`; host `babysit` / `bugbot` / `security-review` advisory-only (#2308 / #2261).
 
 ## Value feedback and attribution (#1709)
 
-! `plan.policy.valueFeedback.enabled` defaults OFF — opt-in via `deft policy:show --field=valueFeedback` / `deft policy:enable-value-feedback -- --confirm`; detail via `deft value:show`; gaps via `deft feedback:file`; rules in `.deft/core/.agents/skills/deft-directive-feedback/SKILL.md` (#1709).
+! `plan.policy.valueFeedback.enabled` defaults OFF — `deft policy:show --field=valueFeedback` / `deft policy:enable-value-feedback -- --confirm`; `deft value:show`; `deft feedback:file`; `.deft/core/.agents/skills/deft-directive-feedback/SKILL.md` (#1709).
 
 ## Eval and framework health (#1703)
 
-! Run `deft eval:health` when orienting or after gate/policy changes (Tier 0; 4-hour debounce). Maintainer release eval: `deft eval:run` / `deft eval:report` (#1703).
+! `deft eval:health` when orienting or after gate/policy changes (Tier 0; 4-hour debounce). Release: `deft eval:run` / `deft eval:report`; skill routing: `deft eval:triggers` (#1586 / #1703).
 
 ## Branch policy & branch verification
 
-! Work on feature branches — `deft verify:branch`, `deft verify:forward-coverage`, hooks, and `deft check` enforce default-branch protection (#746 / #747); full surfaces in `.deft/core/scm/github.md` § Branch policy.
+! Feature branches — `deft verify:branch`, `deft verify:forward-coverage`, hooks, `deft check` (#746 / #747) — `.deft/core/scm/github.md` § Branch policy.
 
 ## Branch Policy Disclosure (#746)
 
-! When `plan.policy.allowDirectCommitsToMaster = true`, surface policy at session start via `deft policy:show --field=allowDirectCommitsToMaster` (#746) — full phrasing and override paths in `.deft/core/scm/github.md` § Branch policy.
+! When `plan.policy.allowDirectCommitsToMaster = true`, surface via `deft policy:show --field=allowDirectCommitsToMaster` (#746) — `.deft/core/scm/github.md` § Branch policy.
 
 ## Contextual guardrails (runtime-detect lazy-load)
 
-! Lazy-load `.deft/core/scm/github.md` sections 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).
+! 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).
 
 ## Development Process
 
 ### Implementation Intent Gate (#810)
 
-! `deft xbrief:preflight -- <path>` on `xbrief/active/` before code-writing; action-verb directive (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`) (#810) — `.deft/core/commands.md` § Scope xBRIEF Lifecycle.
+! `deft xbrief:preflight -- <path>` on `xbrief/active/` before code-writing; action-verb (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`) (#810) — `commands.md` § Scope xBRIEF Lifecycle.
 
 ### Story Start Gate
 
-! `git status --short --branch` + `deft verify:story-ready`; lifecycle via `deft scope:promote -- <path>` / `deft scope:activate -- <path>` / `deft scope:complete -- <active-story-path>` (#1378) — `.deft/core/commands.md` § Scope xBRIEF Lifecycle.
+! `git status --short --branch` + `deft verify:story-ready`; `deft scope:promote -- <path>` / `deft scope:activate -- <path>` / `deft scope:complete -- <active-story-path>` (#1378) — `commands.md` § Scope xBRIEF Lifecycle.
 
 ## Commands
 
-! Directive product commands use the `/deft:directive:*` namespace (#418 / #1670); the full command and alias table lives in `.deft/core/commands.md` — load on demand, not rendered here.
+! `/deft:directive:*` namespace (#418 / #1670); full table in `.deft/core/commands.md` — load on demand.
 <!-- /deft:managed-section -->

package/tools/package-manager-network.md

@@ -13,8 +13,8 @@ Directive runs against arbitrary repositories, including private monorepos with
 ## Rules
 
 - ! Read-only, session-start, and session-ritual flows (`deft session:start`, `deft verify:session-ritual`, `deft verify:tools`) MUST perform no npm/pnpm registry access. Tool-presence probes MUST use PATH lookups (`which`/`accessSync`) or `--version` checks, never a subcommand that can resolve dependencies or query a registry.
-- ! `deft doctor` MUST default to an OFFLINE tier: no check in the default run may contact an npm/pnpm registry. The one check that can (`payload-staleness`, which resolves the latest framework version via `git ls-remote` and falls back to `npm view <package> version`) is gated behind the explicit `--network` flag and is skipped by default with a pointer to that flag.
-- ! Before a network-gated check runs, `deft doctor --network` MUST print a disclosure line naming the tool and registry class it may contact (e.g. "may contact your git remote and, as a fallback, the npm registry") BEFORE any network call is attempted.
+- ! `deft doctor` MUST default to an OFFLINE tier: no check in the default run may contact an npm/pnpm registry. The one check that can (`payload-staleness`, which uses `git ls-remote` to verify the installed pin and `npm view <package> version` to compare a release-tag install with the latest stable package) is gated behind the explicit `--network` flag and is skipped by default with a pointer to that flag.
+- ! Before a network-gated check runs, `deft doctor --network` MUST print a disclosure line naming the tool and registry class it may contact (for example, "may contact your git remote and the npm registry") BEFORE any network call is attempted.
 - ! Any future doctor check, session step, or read-only command that needs to invoke `npm`/`pnpm` in a way that can reach a registry MUST follow the same pattern: explicit flag or subcommand, disclosed registry class before the call, and offline by default.
 - ~ Where a package-manager operation is unavoidable in an explicitly-invoked flow (e.g. a release or install workflow that legitimately needs to fetch packages), prefer offline/frozen modes (`--offline`, `--prefer-offline`, `--frozen-lockfile`) when the operation only needs to validate local state rather than resolve fresh metadata.
 - ⊗ MUST NOT invoke `npm`/`pnpm` subcommands that can contact a registry from any code path reachable by `session:start`, `verify:session-ritual`, `verify:tools`, or the default `deft doctor` invocation.