@deftai/directive-content 0.98.1 → 0.100.0

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

@@ -43,6 +43,7 @@ The swarm skill creates branches per agent so the guard is mostly informational
 - User says "run agents", "parallel agents", "swarm", or "launch N agents on stories"
 - Multiple independent story-level xBRIEFs in `xbrief/active/` need to be worked on simultaneously
 - A batch of stories are ready and have no mutual dependencies
+- Operator re-authorizes a dual-stopped / hard-stopped / conf-hold unit: **pursue residual**, **follow-up hard-stop**, **same as conf-hold**, **continue dual-stopped PR**, or **re-babysit residual** — route to § Operator follow-up after dual-stop / hard stop (#3273)
 
 ## Prerequisites
 
@@ -138,8 +139,14 @@ Large multi-host skills use a **host-neutral core** plus **one** per-host adapte
 
 ! On failure stop: halt automatic continuation; emit an operator-visible report (what was tried, what is missing, what human decision is needed). ⊗ Silent re-dispatch or infinite monitor continuation after the envelope is exhausted.
 
+! **Halt-report resume line (MUST, #3273 / AC6):** Terminal dual-stop / hard-stop / conf-residual halt reports MUST end with residual class + conf (if any) + PR URL, example resume phrases (**pursue residual** | **follow-up hard-stop** | **same as conf-hold** | **continue dual-stopped PR**), and pointer to § Operator follow-up after dual-stop / hard stop. Full template: [`references/core-phase-4.md`](references/core-phase-4.md).
+
 ! Composes with minimal-subgraph repair guidance (#2439): keep repairs minimal **and** bounded by dual-stop -- minimal repair is not a license to thrash. Durable delivery/acceptance circuit-breaker: **#3143** `packages/core/src/delivery-attempt/` (`evaluatePreDispatch`, unit ledger). Docs: `docs/delivery-attempt.md`. Skill defaults remain behavioral; mechanical gate lives in core.
 
+### Operator follow-up after dual-stop / hard stop (#3273)
+
+Operator-initiated **one residual pass** after dual-stop / hard stop / conf-hold — not automatic re-thrash. Depth (steps, anti-thrash, conf-floor this-PR-only): [`references/core-phase-4.md`](references/core-phase-4.md) same section title. Thin pointer: dual-invoke `pr:merge-ready` / `pr:watch`; spawn **one** residual worker or review-cycle owner; document authorized conf floor for this PR only as human-merge/override trail (⊗ silent policy rewrite; `pr:merge-ready` still uses policy floor); re-stop without new consent. ⊗ Unlimited auto-retry. ⊗ Parent self-implement (#2843). Portable consumer + maintainer.
+
 ## Runtime Capability Detection (summary)
 
 ! Before selecting a launch method, probe the environment. Full probe text: [`references/core-phase-3.md`](references/core-phase-3.md).
@@ -158,6 +165,22 @@ Large multi-host skills use a **host-neutral core** plus **one** per-host adapte
 ⊗ Offer Warp-specific launch paths when not inside Warp.
 ⊗ Classify Claude Code as `cursor-composer` / `generic-terminal` when Claude-unique signals are present (#3134).
 
+## Retained addressable sub-agents (#3158)
+
+Named mode **beside** dispatch-and-collect. Canon: [`../../swarm/swarm.md`](../../swarm/swarm.md) `## Retained addressable sub-agents (#3158)`.
+
+| Mode | When | Mid-scope gate |
+|------|------|----------------|
+| **retained-child** (message-later / steer-mid-flight) | Host keeps a live, addressable child (`agent_id` / session name); parent can re-message or steer mid-flight | Single dispatch MAY pause for approval and continue the **same** child |
+| **dispatch-and-collect** (one-shot) | Host has no continue/resume; worker terminal on tool-loop exit | **Split-dispatch** mandatory (#954): Scope A → report → approve → Scope B |
+
+! After platform detect, read the loaded host adapter's **Retained / continue-by-id** note. Prefer continue-by-agent-id / resume-by-name / steerable mid-flight **only when that adapter documents support**.
+! When the host cannot retain: keep one-shot envelopes and split-dispatch mid-scope gates. Do not claim message-later semantics the platform cannot deliver.
+! Stance (#3164): retention is **orchestration only** — not mid-run constitution self-edit (managed AGENTS, pinned skills, policy).
+! Topology (#3155): retained children MUST obey nuclear-family A2A bounds (parent/sibling/child only).
+⊗ Force a second full dispatch on a retain-capable host solely because a mid-scope gate exists — re-message the live child instead.
+⊗ Invent retain / resume on hosts whose adapter marks one-shot only.
+
 ## Phase overview
 
 | Phase | Goal | Depth |
@@ -172,6 +195,11 @@ Large multi-host skills use a **host-neutral core** plus **one** per-host adapte
 
 ! Follow phases in order. Depth files hold the operative MUST rules; this page is the dispatch card.
 
+## Effort estimate on dispatch (#1581)
+
+! When plan items carry optional `effort` (S/M/L/XL with time anchors in `vbrief/vbrief.md`), use them for sizing: S/M single-agent, L may need a dedicated agent, XL blocks dispatch until broken into S/M/L. Activate fails closed on XL. Depth: [`references/core-phase-0.md`](references/core-phase-0.md) Steps 2–3.
+! Plan-item effort is **post-planning** (confirms/corrects provisional intake estimates). It is **not** session-start ritual input; ceremony dial (#3214) starts rapid and escalates — do not block cold-start ritual on missing plan-item `effort`. Headless: no operator confirmation for size or stage transitions.
+
 ## Critical anti-patterns (dispatch card)
 
 - ⊗ Load all host adapters “just in case” (#2928)
@@ -183,10 +211,14 @@ Large multi-host skills use a **host-neutral core** plus **one** per-host adapte
 - ⊗ Rely on soft skill prose alone as the sole parent-hang mitigation (#3131)
 - ⊗ Second+ user-visible consolidate for the same child runId without new evidence (#3092)
 - ⊗ Assign overlapping files to multiple agents
+- ⊗ Dispatch or activate work that still has `plan.items[].effort: "XL"` without breakdown (#1581)
 - ⊗ Merge before Greptile exit condition (score > 3, no P0/P1)
 - ⊗ Skip Phase 0 approval before Phase 1
 - ⊗ Misclassify OpenClaw `sessions_spawn` as `grok-build` or `generic-terminal` (#2875)
 - ⊗ Misclassify Claude Code as `cursor-composer` / `generic-terminal` (#3134)
 - ⊗ Run multi-iteration repair/monitor loops without a failure stop or with silent continuation after the envelope is exhausted (#2442)
+- ⊗ Dual-stop/hard-stop halt without #3273 resume line, or unlimited residual auto-retry without new operator consent (#3273)
+- ⊗ Force a second full dispatch on a retain-capable host solely for a mid-scope gate, or invent retain on one-shot hosts (#3158)
+- ⊗ Use retained-child messaging for mid-run constitution self-edit (#3158 / #3164)
 
 Full anti-pattern list: [`references/core-ops.md`](references/core-ops.md).

package/skills/deft-directive-swarm/references/core-ops.md

@@ -132,7 +132,8 @@ CONSTRAINTS:
 - ⊗ Omit override-merged PRs from the Phase 6 Step 5 Slack release announcement -- any merge that used the Greptile-service-errored override path MUST be called out with its one-line rationale so downstream readers can trace the documented override trail (#526)
 - ⊗ Run `gh pr merge` on a PR that has any protected (umbrella / staying-OPEN) issue listed in `gh pr view <N> --json closingIssuesReferences` -- the link is persistent in GitHub's database from a prior PR body revision (or sidebar attachment) and survives body edits, commit-message edits, and explicit `--subject` / `--body-file` overrides; manually unlink via the PR's Development sidebar panel before merging (Layer 3, #701)
 - ⊗ Skip the post-merge protected-issue reopen sweep for any squash merge that referenced an umbrella / staying-OPEN issue -- defense in depth catches Layer 3 false-positives the pre-merge inspection missed (#701)
-- ⊗ Merge on the basis of a SUCCESS Greptile CheckRun alone -- the CheckRun signals review **completion**, not review **approval** (PR #652 incident; symmetric blind spot to the NEUTRAL CheckRun #526 case). Always run `task pr:merge-ready -- <N>` before `gh pr merge` to parse the comment body for confidence + P0 / P1 findings
+- ⊗ Merge on the basis of a SUCCESS Greptile CheckRun alone -- the CheckRun signals review **completion**, not review **approval** (PR #652 incident; symmetric blind spot to the NEUTRAL CheckRun #526 case). Always run `task pr:merge-ready -- <N>` before `gh pr merge` to parse the comment body for confidence + P0 / P1 findings + advisory should-not-merge prose (#3225)
+- ⊗ Merge on mechanical Ready-to-merge / green checks while bot comment prose records should-not-merge or sub-threshold confidence -- mechanical mergeability is necessary, never sufficient (#3225 / #3095)
 - ⊗ Run `git checkout` (any branch) -- including the brief `cd <other-worktree>; git checkout master --quiet` shape -- in a worktree the merging agent does not own during Phase 6 Step 3 (Update Master) or Step 4 (Clean Up). Post-merge state-update semantics MUST be performed via `git fetch origin <base-branch>` from the merger's OWN worktree, never by switching HEAD on a sibling worktree another agent is actively using. Recurrence record: PR #797 merge session (2026-05-01); companion to the Sub-Agent Role Separation rules (#727) -- this anti-pattern extends the same boundary discipline from sub-agent spawn shape to worktree HEAD operations (#800)
 - ⊗ Skip the Phase 0 Step 0.5 lifecycle bridge (#1025) and let the Step 1 preflight gate reject candidate scope xBRIEFs wholesale. The setup skill deposits scope xBRIEFs in `xbrief/proposed/` and the refinement skill leaves them in `xbrief/pending/`; the swarm Phase 0 Step 1 preflight only accepts `xbrief/active/` with `plan.status == "running"`. The bridge step (`task scope:promote -- <path>` then `task scope:activate -- <path>`) is the contract that converts proposed/pending candidates to active before allocation -- bypassing it re-surfaces the originating 2026-05-10 first-session consumer-swarm failure mode (`Invalid transition: 'activate' requires file in pending/`)
 - ⊗ Auto-promote + activate every candidate in `xbrief/proposed/` or `xbrief/pending/` during the Phase 0 Step 0.5 bridge without explicit user approval (#1025). Proposed-stage xBRIEFs may be in a deliberate refinement queue (`skills/deft-directive-refinement/SKILL.md` Phase 4); silent promotion bypasses the user's lifecycle intent and may flip `plan.status` to `running` on scopes the user has not yet refined. Broad affirmatives (`proceed`, `do it`, `go ahead`) do NOT satisfy the bridge approval gate -- require an explicit `yes` / `confirmed` / `approve`
@@ -157,4 +158,10 @@ CONSTRAINTS:
 - ⊗ Full dual-source re-QC solely because the harness re-delivered the same settle event (#3092)
 - ⊗ Run multi-iteration repair, monitor, or implement-fix loops without a dual-stop failure envelope (max iterations and/or no-progress and/or budget) (#2442)
 - ⊗ Silently continue, re-dispatch, or open another identical attempt after the failure stop fires — halt with an operator-visible report (what was tried, what is missing, what human decision is needed) (#2442)
+- ⊗ Emit a dual-stop / hard-stop / conf-residual terminal halt report **without** the #3273 resume line (residual class + example phrases pursue residual / follow-up hard-stop / same as conf-hold / continue dual-stopped PR + skill section pointer) — primary discovery path; see `core-phase-4.md` Operator follow-up after dual-stop / hard stop
+- ⊗ Unlimited auto-retry or parent self-implement after dual-stop without new operator consent (#3273 / #2843 / #2442)
 - ⊗ Treat dual-stop skill defaults as a durable delivery-attempt ledger — mechanical cross-revision circuit breaker is #3143 (`packages/core/src/delivery-attempt/`), not prompt-only thrashing control (#2442)
+- ⊗ Spawn a second implement leaf without `task swarm:pre-dispatch` exit 0, or while exit 1 (`DENY_DUPLICATE_ACTIVE`) — gate is authoritative (#3228 / #3143); takeover is cancel-then-begin, not dual active
+- ⊗ Force a second full dispatch on a retain-capable host solely because a mid-scope approval gate exists — re-message the live child (message-later / steer-mid-flight) instead (#3158)
+- ⊗ Claim retained-child / continue-by-agent-id semantics on hosts whose adapter marks one-shot only — capability-gate first; default split-dispatch (#3158 / #954)
+- ⊗ Use retained-child messaging to rewrite managed AGENTS, pinned skills, or policy mid-run — retention is orchestration only (#3158 / #3164)

package/skills/deft-directive-swarm/references/core-phase-0.md

@@ -200,11 +200,13 @@ Cross-references:
 - ! Identify epic/phase scope xBRIEFs from the readiness report and route them to decomposition
 - ! Identify dependency conflicts between candidate xBRIEFs (e.g. story A depends on story B via `planRef` or `edges`, but B is assigned to a different agent or is incomplete)
 - ! Flag any candidate xBRIEFs whose prerequisites are unmet
+- ! **Effort XL (#1581):** scan `plan.items` (nested) for `effort: "XL"`. XL means "needs breakdown" (anchors: S <2h, M 2-4h, L 1-2d). Flag XL items as blockers before dispatch; `task scope:activate` / `task vbrief:activate` fail closed until each XL item is broken into S/M/L. Omitted effort is not a hard blocker (field optional). Plan-item effort is post-planning authority only — not a session-start ritual input (#3214 two-stage rapid→escalate).
 
 ### Step 3: Plan Allocation
 
 ! The monitor allocates one or more xBRIEFs to each agent based on scope, complexity, and dependencies. There is no fixed per-agent limit.
 
+- ! **Respect `PlanItem.effort` when present (#1581):** S/M → safe single-agent dispatch; L → prefer a dedicated agent (or parallel worktrees when the file scope allows); XL → do not dispatch — break down first (same rule as the activate gate).
 - ! **Small/independent stories** can be batched to a single agent only after explicit operator approval or an approved allocation plan -- group related or low-complexity xBRIEFs together and record the batching rationale
 - ! **Large/complex stories** get dedicated agents — a story with broad file scope or high acceptance criteria count should not share an agent
 - ! **Dependency-aware grouping** — xBRIEFs that share `planRef` to the same epic or have `edges` between them should be assigned to the same agent when possible, OR sequenced with clear ordering

package/skills/deft-directive-swarm/references/core-phase-3.md

@@ -100,6 +100,8 @@ Cross-references: `packages/core/src/platform/platform-capabilities.ts` (#1557a)
 
 ! **Supported backend examples (none mandatory):** Composer-class coding agents, Grok Build `spawn_subagent` workers, Cursor/cloud agents, and future adapters are all first-class examples. No single backend is required — Grok Build is one implementation of provider-neutral routing, not the only target.
 
+! **Implement-leaf pre-dispatch (#3228):** Before the actual spawn primitive for an implement leaf (and before any re-dispatch), run `task swarm:pre-dispatch -- --scope-id <id> --target-id <worktree-or-branch>` — exit **0** only means spawn is allowed; exit **1** is `DENY_DUPLICATE_ACTIVE` (do not spawn). Depth + takeover: [`core-phase-4.md`](core-phase-4.md) Pre-dispatch deny gate; library #3143.
+
 ! **Operator model routing (#1739):** the concrete per-role model lives in the gitignored, per-machine `.deft/routing.local.json`, keyed by `(dispatch_provider, worker_role)`. Record a decision with `task swarm:routing-set -- --role <role> (--model <slug> | --harness-default)`. `task swarm:launch` resolves the active provider's route and stamps `resolved_model` + `model_source` into each C2 manifest record. When `resolved_model` is non-null, the monitor MUST pass it as the **model argument of the actual dispatch primitive** (e.g. the Task tool's `model` field for a Cursor sub-agent) — stamping the manifest is prep; a recorded model that never reaches the spawn call is the bug #1739 closes. Run `task verify:routing` before dispatching a cohort (pre-dispatch hard gate; fails when a dispatched role is undecided) and `task verify:routing -- --advise` at session start (non-blocking disclosure). For harness-bound providers (e.g. `grok`) only `--harness-default` is recordable and `resolved_model` stays null.
 
 ~ **DEPRECATED — Policy surface (#1531a / #1891):** `plan.policy.swarmSubagentBackend` (set via `task policy:subagent-backend`) was the previous mechanism for recording the operator's preferred coding sub-agent provider. It is superseded by per-role operator model routing above (#1739). The enum and associated `task policy:subagent-backend(s)` tasks remain functional but deprecated; hard deletion is tracked by #1860. Use `task swarm:routing-set` instead.
@@ -118,6 +120,22 @@ Cross-references: `packages/core/src/platform/platform-capabilities.ts` (#1557a)
 Cross-references: `packages/core/src/swarm/routing.ts` (`SWARM_WORKER_ROLES`), `templates/agent-prompt-preamble.md` (dispatch envelope metadata), `docs/the-harness-is-everything.md` (orchestrator -> commodity-coder layering). Refs #1531.
 
 
+### Retained vs one-shot dispatch mode (#3158)
+
+! After platform detection (Step 1) and before spawn, classify the host as **retain-capable** or **one-shot** using the loaded host adapter's retained / continue-by-id note (and `swarm/swarm.md` § Retained addressable sub-agents).
+
+| Classification | Dispatch posture | Mid-scope user-approval gate |
+|----------------|------------------|------------------------------|
+| **retain-capable** | Prefer **retained-child** when the unit of work needs iterative refinement, standing expertise, or mid-flight steer; keep persistent `agent_id` / session handle | Single dispatch MAY include a mid-scope gate — parent **re-messages** the same live child (message-later / steer-mid-flight). Do not force a second full dispatch solely for the gate. |
+| **one-shot** (default when adapter does not document retain) | **dispatch-and-collect** — closed envelope; worker terminal on tool-loop exit | **Split-dispatch** remains mandatory (#954 / preamble §10): Scope A completes → user approves → Scope B as a new dispatch |
+
+! Record the mode in monitor notes when non-default (e.g. `dispatch_mode: retained-child` + retained `agent_id`) so Phase 4 does not spawn a duplicate on the same worktree while a retained child is still addressable.
+! Stance (#3164): retention is orchestration only — ⊗ mid-run rewrite of managed AGENTS, pinned skills, or policy via retained messaging.
+~ Topology bounds for retained A2A messaging: obey landed nuclear-family bounds in swarm/swarm.md § Communication Topology (#3155).
+
+⊗ Treat every host as retain-capable without adapter evidence.
+⊗ Spawn a replacement on a worktree that still has a live retained child the parent can re-message (#261 / #263 duplicate-agent class).
+
 ### Orchestrator dispatch doctrine (#1880)
 
 ! **Deliberate model routing before ANY dispatch:** Before launching ANY worker in this phase (cohort OR solo), run `task verify:routing` and resolve each `(dispatch_provider, worker_role)` via `task swarm:routing-set` / `.deft/routing.local.json`. Populate `## Worker metadata` per `templates/agent-prompt-preamble.md` §2.6 and pass `resolved_model` into the actual dispatch primitive when non-null. Never silently inherit the monitor's model. Deterministic gate enforcement is #1877; this rule is behavioral doctrine (#1880).

package/skills/deft-directive-swarm/references/core-phase-4.md

@@ -74,14 +74,74 @@ tools: explore=0 commit=3 verify=0 coordinate=0 unknown=1 | anomalies: commit-wi
 
 ! When the failure stop fires: **halt** automatic repair/re-dispatch; emit an **operator-visible halt report** (what was tried, current stage, missing evidence, human decision needed). Prefer `BLOCKED:` over thin `DONE` when the unit cannot reach merge-ready inside the envelope.
 
+! **Halt-report resume line (MUST, #3273 / AC6):** Terminal dual-stop / hard-stop / conf-residual halt reports MUST end with a copy-pasteable operator resume affordance so agents discover the follow-up path without prior chat memory:
+
+```
+RESUME: residual=<class> conf=<n/5|n/a> PR=<url>
+Operator may re-authorize **one residual pass** with: pursue residual | follow-up hard-stop | same as conf-hold | continue dual-stopped PR
+Skill: deft-directive-swarm § Operator follow-up after dual-stop / hard stop (#3273) · deft-directive-review-cycle same section
+```
+
+Residual class examples: `review_cycle_cap` / `greptile_p0_p1` / `conf_floor` / `no_progress` / `ci_weather` / `thin_done`.
+
+### Operator follow-up after dual-stop / hard stop (#3273)
+
+Operator-initiated resume after dual-stop, hard-stop, or conf-floor residual — **not** automatic re-thrash. Primary discovery is the halt-report resume line above; this section holds the steps. Portable for consumer deposit and maintainer tree (`task` / `deft` dual-invoke; no framework-monorepo-only path).
+
+**Triggers:** pursue residual · follow-up hard-stop · same as conf-hold · continue dual-stopped PR · re-babysit residual
+
+**One residual pass (then re-stop):**
+1. Ground-truth: dual-invoke `pr:merge-ready` / `pr:watch --one-shot` on the PR (CLI `deft` first, then `task deft:` — see review-cycle #2893).
+2. If a delivery attempt is still active, cancel then begin with the **same unit ids** (exit 0 required before residual spawn) (#3228 / #3143):
+   ```
+   task swarm:pre-dispatch -- --scope-id <story-or-issue-or-xbrief-id> --target-id <worktree-path-or-branch> --action cancel
+   task swarm:pre-dispatch -- --scope-id <story-or-issue-or-xbrief-id> --target-id <worktree-path-or-branch>
+   ```
+3. Spawn **one** active residual worker or review-cycle owner (not sleep-only re-poll as the only work). Monitor MUST NOT self-implement product fixes after merge-ready leaf handback (#2843).
+4. If the operator authorized a conf floor for **this PR only** (e.g. ≥4/5): post a PR audit comment naming the floor, HEAD SHA, and who authorized it. That comment is the **human-merge / documented-override trail** — it does **not** rewrite `plan.policy.review.minGreptileConfidence` or make `pr:merge-ready` / `pr:watch` exit CLEAN below policy. Merge still requires policy CLEAN, bot-merge authority + override path, or human merge after the documented floor is met in the bot body. ⊗ Silent policy edit of `minGreptileConfidence` for one residual.
+5. Wait re-review; merge when policy floor + gates met (or human-merge after documented PR-local floor). Run `scope:complete` + lifecycle land when in scope (#3264 / finalize).
+
+! Dual-stop re-entry: after the residual pass (+ re-review wait), if still blocked, halt again with a fresh resume line. Another pass requires **new** operator consent.
+
+⊗ Unlimited auto-retry after dual-stop without new operator consent (#3273 / #2442).
+⊗ Sleep-only multi-hour re-poll as the sole residual work.
+⊗ Parent/monitor self-implement after merge-ready leaf handback (#2843).
+⊗ Lower project-wide `minGreptileConfidence` for one residual.
+
 ! Composes with minimal-subgraph repair (#2439): repairs stay minimal **and** dual-stop bounded. Mechanical delivery/acceptance circuit breaker: **#3143** `packages/core/src/delivery-attempt/` (`evaluatePreDispatch`). Docs: `docs/delivery-attempt.md`.
 
 ⊗ Silently continue the monitor repair loop after the envelope is exhausted.
 ⊗ Count a worker swap or session handoff as a fresh unlimited budget when the same failure class remains.
 
+### Pre-dispatch deny gate (#3228 / #3143)
+
+! **Before any implement-leaf spawn or re-dispatch** (initial launch, resume-fail recovery, residual batch, thin-DONE recovery, takeover replacement): run the deterministic pre-dispatch gate. Non-zero exit means **do not spawn**.
+
+```
+# Register / begin an attempt when no active peer exists (exit 0 allow / 1 deny / 2 config)
+task swarm:pre-dispatch -- \
+  --scope-id <story-or-issue-or-xbrief-id> \
+  --target-id <worktree-path-or-branch>
+
+# Terminal: complete the attempt when the leaf exits
+task swarm:pre-dispatch -- \
+  --scope-id <id> --target-id <target> \
+  --action complete --status succeeded|failed|cancelled|blocked
+
+# Takeover: cancel prior attempt, THEN pre-dispatch begin again (never dual active)
+task swarm:pre-dispatch -- --scope-id <id> --target-id <target> --action cancel
+task swarm:pre-dispatch -- --scope-id <id> --target-id <target>   # begin
+```
+
+! Gate authority is **#3143** `DENY_DUPLICATE_ACTIVE` (`maxActiveAttempts: 1`) on the delivery-attempt unit ledger (`scopeId` + `targetId` + `workflowId`, default workflow `drive-to:merge-ready`). CLI is authoritative; this section is a pointer only.
+⊗ Spawn a second implement leaf while pre-dispatch exits 1 (active attempt exists).
+⊗ Treat "resume failed" / host false-alive as license to skip the gate.
+⊗ Lift DENY by concurrent dual active — escape hatch is cancel-then-begin, not override-while-both-run.
+Docs: `docs/delivery-attempt.md`.
+
 ### Takeover Triggers
 
-! **Pre-spawn verification:** Before spawning a replacement agent, verify the original is truly unresponsive by waiting for an idle/blocked lifecycle event — verified via worktree state (`git status`, `git log --oneline -3`) and sub-agent lifecycle signals showing no in-flight work (for grok-build / spawn_subagent agents: polling is via worktree state + `get_command_or_subagent_output` rather than tab observation; for openclaw / sessions_spawn agents: worktree state + parent completion announce / heartbeat records, not Grok Build poll output). Do NOT spawn a replacement based solely on message timing, absence of recent commits, or a perceived delay — original agents (Warp tabs, spawn_subagent processes, or OpenClaw sessions) can resume after apparent failure, and spawning a new agent creates two concurrent agents on the same worktree (see Duplicate-Tab Failure Mode below).
+! **Pre-spawn verification:** Before spawning a replacement agent, verify the original is truly unresponsive by waiting for an idle/blocked lifecycle event — verified via worktree state (`git status`, `git log --oneline -3`) and sub-agent lifecycle signals showing no in-flight work (for grok-build / spawn_subagent agents: polling is via worktree state + `get_command_or_subagent_output` rather than tab observation; for openclaw / sessions_spawn agents: worktree state + parent completion announce / heartbeat records, not Grok Build poll output). Do NOT spawn a replacement based solely on message timing, absence of recent commits, or a perceived delay — original agents (Warp tabs, spawn_subagent processes, or OpenClaw sessions) can resume after apparent failure, and spawning a new agent creates two concurrent agents on the same worktree (see Duplicate-Tab Failure Mode below). Run `task swarm:pre-dispatch` after cancel when replacing — see Pre-dispatch deny gate above.
 
 ! Take over an agent's workflow if ANY of these occur:
 
@@ -98,8 +158,8 @@ When taking over: read the agent's current state (git log, diff, PR comments), c
 
 **Recovery guidance:**
 - ! Keep original agents active until their PR is merged — do not terminate agent processes that appear stalled (for Warp tabs: keep the tab open; for grok-build / spawn_subagent agents: verify via `get_command_or_subagent_output` before replacing; for openclaw / sessions_spawn: verify via heartbeat + absence of parent completion announce)
-- ! If an agent appears stalled, attempt to resume it in its original context (for Warp: go to the original Warp tab and say "continue from where you left off"; for grok-build: re-query via `get_command_or_subagent_output` or send a resume message; for openclaw: re-announce / resume the same session rather than spawning a replacement) rather than spawning a replacement
-- ! If the original agent is truly unrecoverable (Warp crash, tab closed, spawn_subagent process terminated, or OpenClaw session ended without recovery), only then create a new agent — and first verify the worktree state (`git status`, `git log`, `gh pr list`) to avoid conflicting with any in-flight work
+- ! If an agent appears stalled, attempt to resume it in its original context (for Warp: go to the original Warp tab and say "continue from where you left off"; for grok-build: re-query via `get_command_or_subagent_output` or send a resume message; for openclaw: re-announce / resume the same session rather than spawning a replacement) rather than spawning a replacement — resume does **not** open a second delivery-attempt (`task swarm:pre-dispatch` will DENY while the first is active)
+- ! If the original agent is truly unrecoverable (Warp crash, tab closed, spawn_subagent process terminated, or OpenClaw session ended without recovery), only then create a new agent — cancel the prior attempt via `task swarm:pre-dispatch -- --action cancel`, run pre-dispatch begin (exit 0 required), and verify worktree state (`git status`, `git log`, `gh pr list`) before spawn
 
 ### Context-Length Warning
 

package/skills/deft-directive-swarm/references/core-phase-5-6.md

@@ -104,11 +104,15 @@ All PRs meet ALL of:
 
    ! **Cohort gate (#1364):** Before the merge-readiness checklist is even emitted, the monitor MUST have already passed `task swarm:verify-review-clean -- <pr-numbers...>` per the Phase 5 Exit Condition above. The cohort gate is the structural pre-condition for this entire Phase 5 -> 6 sequence -- without exit 0 on the verifier, the checklist below MUST NOT be presented to the user. The per-merge `task pr:merge-ready` gate below remains the merge-time freshness-window-atomic check; the cohort verifier is the once-after-pollers gate that gates the discussion at all.
 
-   ! **Programmatic gate:** Before each `gh pr merge` call, the monitor MUST run `task pr:merge-ready -- <N>` and abort the cascade on non-zero exit. The task parses the Greptile rolling-summary comment **body** (confidence, P0 / P1 badge counts, errored sentinel, HEAD-SHA freshness) -- not the GitHub CheckRun status. The CheckRun goes green when Greptile finishes its review pass, irrespective of findings; relying on it alone is the SUCCESS-with-findings blind spot that started the PR #652 incident merge cascade against `Confidence: 3/5 + 1×P1 + 2×P2`.
+   ! **Programmatic gate:** Before each `gh pr merge` call, the monitor MUST run `task pr:merge-ready -- <N>` and abort the cascade on non-zero exit. The task parses the Greptile rolling-summary comment **body** (confidence, P0 / P1 badge counts, **advisory should-not-merge prose (#3225)**, errored sentinel, HEAD-SHA freshness) -- not the GitHub CheckRun status. The CheckRun goes green when Greptile finishes its review pass, irrespective of findings; relying on it alone is the SUCCESS-with-findings blind spot that started the PR #652 incident merge cascade against `Confidence: 3/5 + 1×P1 + 2×P2`.
+
+   ! **Mechanical mergeability is necessary, never sufficient (#3225):** GitHub Ready-to-merge / green checks / formal review without Changes-Requested are **not** a CLEAN signal by themselves. Reviewer bots may record should-not-merge + sub-threshold confidence only in comment prose. `pr:merge-ready` / `pr:watch` MUST refuse when advisory prose or `minGreptileConfidence` (#3095) blocks, regardless of the mechanical merge box. Cross-link: `skills/deft-directive-review-cycle/SKILL.md` § Mechanical mergeability.
 
    ! **Atomic gate (freshness window):** The monitor MUST invoke `task pr:merge-ready -- <N>` and `gh pr merge <N>` in the same shell call (e.g. `task pr:merge-ready -- <N> && gh pr merge <N> --squash --delete-branch --admin`) so no time elapses between verdict and merge. A readiness check more than ~60 seconds stale is a Mode-1 false-positive risk: in the elapsed window an unrelated commit may land on master, auto-rebase trigger a fresh Greptile pass, and the new pass surface a P1 the cached verdict did not see. Re-invoking the gate is cheap (single `gh api` call); the shell-`&&` chain makes the freshness window structurally enforceable rather than prose-trust.
 
-   ⊗ Merge on the basis of a SUCCESS Greptile CheckRun alone. The CheckRun signals review **completion**, not review **approval**. Parse the comment body (confidence + P0/P1 count) via `task pr:merge-ready -- <N>` before merging.
+   ⊗ Merge on the basis of a SUCCESS Greptile CheckRun alone. The CheckRun signals review **completion**, not review **approval**. Parse the comment body (confidence + P0/P1 count + advisory should-not-merge prose) via `task pr:merge-ready -- <N>` before merging.
+
+   ⊗ Merge because the merge box is Ready-to-merge while bot prose still says should-not-merge or confidence is below the resolved floor (#3225 / #3095).
 
    ⊗ Run `task pr:merge-ready -- <N>` upstream of `gh pr merge <N>` (e.g. as a separate batched check during cascade prep, then later run `gh pr merge` after intervening rebase / sub-agent dispatch / user discussion). Stale verdicts risk Mode-1 false positives -- always chain readiness and merge in the same shell call.
 3. ! Wait for explicit user approval (`yes`, `confirmed`, `approve`) before proceeding to Phase 6 merge cascade

package/skills/deft-directive-swarm/references/host-claude-code.md

@@ -81,6 +81,13 @@ Probe order (must match engine `probeMonitoringTier` / `resolveDispatchProvider`
 
 ! Pre-spawn verification and Duplicate-Agent rules in `references/core-phase-4.md` apply.
 
+## Retained / continue-by-id (#3158)
+
+! **Default one-shot after Agent completion:** Claude Code background `Agent` leaves that exit are typically terminal — prefer **split-dispatch** for mid-scope user-approval gates (#954) unless the host documents continue/resume of the same agent id.
+? When the host supports re-attach or re-prompt of a still-live Agent with context intact, treat as **retain-capable** for message-later / steer-mid-flight.
+! Nested-Agent boundary above still forbids implementation leaves from retaining a second-level review-monitor as a substitute for split ownership rules.
+~ Stance: orchestration only (#3164).
+
 ## Phase handoff (see also core #2934)
 
 ! After coding cohort complete, same-turn next-phase tool dispatch or explicit terminal status — see `references/core-phase-5-6.md` and the thin SKILL MUST block. ⊗ End the turn with only narrative “I will spawn…”.

package/skills/deft-directive-swarm/references/host-cursor.md

@@ -23,3 +23,10 @@ Load this file only after detect selects Cursor. Do not load other host adapters
 ## Nested Task boundary
 
 ! Cursor ownership split (#2797 / #2893) lives in `references/core-phase-3.md` Orchestrator dispatch doctrine — a Cursor `Task` implementation leaf MUST NOT nested-spawn a review-monitor Task.
+
+## Retained / continue-by-id (#3158)
+
+! **Default one-shot after Task completion:** Cursor `Task` leaves that exit their tool loop are typically terminal — prefer **split-dispatch** for mid-scope user-approval gates (#954) unless the host surfaces an explicit continue/resume-by-agent-id for that Task.
+? When the host documents resume of the same Task / agent id with context intact, treat as **retain-capable** for message-later / steer-mid-flight and re-message instead of a full second Task spawn.
+! Liveness failures (`task verify:subagent-alive` exit `1` / `REDISPATCH_OK`) still authorize replacement re-dispatch — retain does not override the false-alive contract (#2824).
+~ Stance: orchestration only (#3164).

package/skills/deft-directive-swarm/references/host-generic.md

@@ -25,3 +25,9 @@ Agents execute on remote VMs without local MCP servers, codebase indexing, or Wa
 ## Serial self-execution / manual paste
 
 When no orchestration primitive is detected, follow the `generic-terminal` branch in `references/core-phase-3.md` Step 1 (serial self-execution downgrade + manual paste fallback).
+
+## Retained / continue-by-id (#3158)
+
+! **One-shot only:** generic-terminal and cloud escape paths have no platform continue-by-agent-id. Treat every paste / serial self-execution / `oz agent run-cloud` run as **dispatch-and-collect**.
+! Mid-scope user-approval gates MUST use **split-dispatch** (new paste / new run after approval) — never claim retained-child messaging on this descriptor.
+~ Stance: orchestration only (#3164).

package/skills/deft-directive-swarm/references/host-grok-build.md

@@ -35,3 +35,10 @@ This path became first-class in #1342 (platform adapter slices 1-3) and is fully
 
 ! Heartbeat liveness on the Grok Build hybrid path is required — see `references/core-phase-4.md` Heartbeat liveness check (#1365) and `docs/subagent-heartbeat.md`.
 ! Poll coordination uses worktree state + `get_command_or_subagent_output` (not OpenClaw parent-announce).
+
+## Retained / continue-by-id (#3158)
+
+! **Default one-shot:** `spawn_subagent` workers that finish their tool loop are observed terminal (`succeeded` / failed); the `agent_id` is not a general message-later inbox. Mid-scope user-approval gates MUST use **split-dispatch** (#954) unless this host later documents continue-by-agent-id.
+? While a worker is still `in_progress` and the host exposes a live steer / re-prompt channel to that `agent_id`, the parent MAY steer mid-flight without a second spawn — that is the only retain-capable slice on this path today.
+! After terminal exit, always dispatch a successor for remaining scope; do not invent re-attach semantics.
+~ Stance: orchestration only (#3164).

package/skills/deft-directive-swarm/references/host-openclaw.md

@@ -93,6 +93,13 @@ Skill residual of #2874 / #2876 (spawn routing fixed; post-spawn ownership still
 ! Long pollers MUST honour on-disk heartbeats (`docs/subagent-heartbeat.md`, #1166).
 ! Pre-spawn verification and Duplicate-Agent rules in `references/core-phase-4.md` apply; resume the same OpenClaw session when possible rather than spawning a replacement on the same worktree.
 
+## Retained / continue-by-id (#3158)
+
+! **Retain-capable when the OpenClaw session remains addressable:** Prefer continue / resume by session id or name (host continue-by-agent-id surface) for message-later and steer-mid-flight instead of a second `sessions_spawn` on the same worktree for mid-scope gates.
+! When the session is terminal or the host cannot re-attach, use **one-shot + split-dispatch** (#954).
+! Resume the same session rather than spawning a replacement while the prior session is still live (#261 / #263).
+~ Stance: orchestration only (#3164). Topology bounds: #3155 nuclear-family (retain does not license open mesh).
+
 ### Parent-monitor after `subagent_announce` (#2943 / hard-stop #3131)
 
 ! When a leaf completion arrives via `subagent_announce` (parent-push completion), the parent’s **first response** MUST be one of:

package/skills/deft-directive-swarm/references/host-warp.md

@@ -34,4 +34,10 @@ Ask the user to open N new Warp terminal tabs. For each tab, the user:
 
 **Tradeoff:** Requires the user to manually open and manage one Warp tab per agent.
 
+## Retained / continue-by-id (#3158)
+
+! **Retain-capable when the tab or `start_agent` session stays live:** Warp agents are interruptible and steerable mid-run. Prefer **message-later / steer-mid-flight** on the same tab or agent handle rather than a second full dispatch for mid-scope gates.
+! When a Warp agent has exited terminal with no resume handle, fall back to **one-shot / split-dispatch** (#954).
+~ Record the retained handle (tab / agent id) in monitor notes. Stance: orchestration only (#3164) — not constitution self-edit.
+
 ? If not running inside Warp at all (no `WARP_*` variables, no `start_agent`), use the same tab approach but with any terminal emulator — the user pastes prompts into their preferred terminal or agent interface.

package/skills/deft-directive-write-skill/SKILL.md

@@ -62,6 +62,7 @@ Ask the user (one question at a time):
 - ! Include negative triggers in `description` (`Do NOT trigger on …`) so near-miss phrases do not load the wrong skill
 - ~ Use the trigger words the user would naturally say
 - ! Use RFC2119 notation throughout (!=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY)
+- ! Apply **goal-gate determinism** (#852): rigid goal, acceptance criteria, quality gates, exit/handoff, and scope `⊗` boundaries; demote pure execution steps to `~` unless they are gates — see [`patterns/goal-gate-determinism.md`](../../patterns/goal-gate-determinism.md)
 - ~ Include attribution blockquote if inspired by an external source
 - ~ When porting Warp-tuned playbooks, read [`references/composer-skill-porting.md`](../../references/composer-skill-porting.md) for fast-path vs isolation, short-chat expectations, and Composer naming
 
@@ -162,6 +163,7 @@ The description is **the only thing the agent sees** when deciding whether to lo
 
 - ⊗ Omitting RFC2119 notation — deft skills use it consistently
 - ⊗ Putting all content in SKILL.md when it exceeds 150 lines — split into `references/*.md` or `REFERENCE.md`
+- ⊗ Prescribing a rigid tool-call path as MUST when only the goal/gates need determinism — use goal-gate-determinism (#852)
 
 - ⊗ Putting every agent-host branch (Warp, Cursor, OpenClaw, Grok Build, generic) in one always-loaded SKILL body when a host-neutral core + per-host adapter split is feasible (#2928)
 

package/strategies/rapid.md

@@ -8,6 +8,8 @@
 
 Quick prototyping workflow -- v0.20 date-prefixed story vBRIEF output with minimal gates and fast iteration.
 
+**Ceremony dial (#3214):** when `plan.policy.ceremonyDial` (or session inputs) selects depth `rapid` — default for S-task × frontier model on a project-shaped session — session ritual / gate depth follows this light path. See `task policy:show --field=ceremonyDial`. Non-project sessions select `minimal` and compose the #3014 minimal AGENTS profile research pointer instead.
+
 **v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Rapid now emits only the canonical v0.20 shape (date-prefixed story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
@@ -99,6 +101,15 @@ Rapid is a **spec-generating** strategy. Selecting it at the chaining gate produ
 
 ---
 
+## Literal acceptance-command verification (#3267)
+
+Rapid lightens cold ceremony only. When the task statement names exact shell acceptance commands:
+
+- ! Capture them at intake as executable AC (`plan.metadata.literal_acceptance_commands`) — do not paraphrase.
+- ! Before done, run `task verify:literal-ac -- <active-story-path>` (verbatim flags/cwd). Fail closed on non-zero.
+- ! This check survives ceremony dial rapid/minimal (#3214) — it is the positive verification content of the light path.
+- ⊗ Treat self-chosen approximate checks as sufficient when the statement named exact commands.
+
 ## Anti-Patterns
 
 - ⊗ Using rapid for production features -- rapid output is explicitly throwaway

package/swarm/swarm.md

@@ -30,6 +30,57 @@ Exposure surfaces for Directive's own swarm mode: a swarm cohort where multiple
 
 Cross-references: [`../meta/security.md`](../meta/security.md) `### 5. Systemic (Compositional Fragment)` (trap-class mitigation pointer), [`../main.md`](../../main.md) `## Agent Trap Defenses (#480)` (framework-layer instruction-hierarchy rule that forbids fragment aggregation), [`../vbrief/vbrief.md`](../vbrief/vbrief.md) `### TrustLevel (#480)` (per-fragment provenance the merge step inspects), [`../patterns/llm-app.md`](../patterns/llm-app.md) `## Multi-agent and orchestration` (application-layer analogue).
 
+## Communication Topology (#3155)
+
+Agent-to-agent messaging follows a **nuclear-family** graph: each agent may exchange orchestration messages only with its **parent**, its **siblings** (same parent/cohort), and its **children**. The Prime Agent practice is shortest useful graph, not agents everywhere.
+
+This is a security and chaos bound for Directive swarm and any local A2A surfaces that inherit swarm doctrine — not the full outbound A2A client protocol (#2705). Retained addressable children (#3158) make this bound *more* important: long-lived children MUST still only message within the nuclear family.
+
+- ! Orchestrators and workers MUST limit agent-to-agent messaging to parent, sibling (same cohort / same parent), and child edges only
+- ! When designing dispatch graphs (solo worker, cohort, nested sub-agents), MUST adopt the shortest useful nuclear-family graph that covers the work — do not grow edges "just in case"
+- ! Cross-cohort or cross-session coordination MUST go through a shared parent (or durable shared artifacts the parent owns: issues, PRs, xBRIEF, decision log) — not peer mesh links between unrelated sessions
+- ! Untrusted content carried on allowed nuclear-family edges remains subject to `## Compositional Fragment Defense (#480)` — topology bounds *who* may talk; fragment defense bounds *how* aggregated content is trusted
+- ~ Prefer parent-mediated fan-in/fan-out over sibling side-channels when either would work; sibling messages are for cohort coordination, not a substitute for parent authority
+- ⊗ Open-mesh agent-to-agent messaging across arbitrary sessions, cohorts, or unrelated agent IDs ("agents everywhere")
+- ⊗ Treat retained / re-addressable children (#3158) as license to mesh outside the nuclear family
+- ⊗ Implement remote open-mesh A2A product mode as default swarm topology; outbound A2A client posture and wire protocol remain #2705 / #2706 / #2707
+
+**Security rationale:** each extra A2A edge multiplies confused-deputy and compositional-fragment surface (untrusted peer content entering another agent context). Bounding the graph to parent/sibling/child caps that multiplier. Detail: [`../meta/security.md`](../meta/security.md) `## Unbounded A2A graphs (#3155)`, ADR [`../../../docs/decisions/ADR-003-a2a-nuclear-family-topology.md`](../../../docs/decisions/ADR-003-a2a-nuclear-family-topology.md).
+
+**Cross-links:** parent epic [#3179](https://github.com/deftai/directive/issues/3179) (bounded multi-agent graphs); pair [#3158](https://github.com/deftai/directive/issues/3158) (retained children); A2A client posture [#2705](https://github.com/deftai/directive/issues/2705) (this topology is a decision input; full client ADR remaining work stays on #2705).
+
+## Retained addressable sub-agents (#3158)
+
+Named mode **alongside** dispatch-and-collect for multi-agent orchestration. Extends status-polled multi-session workers (#2510) and recursive sub-agent delegation (#673); neither fully names this semantic.
+
+| Mode | Semantic |
+|------|----------|
+| **dispatch-and-collect** (default historical swarm) | One-shot envelope per child; worker is terminal when its tool loop ends; parent collects result and may spawn a successor. Mid-scope user-approval gates use **split-dispatch** (Scope A → report → approve → Scope B) (#954). |
+| **retained-child** (message-later / steer-mid-flight) | Child is a full agent with **persistent identity** (`agent_id` / session name). Results arrive as **messages** (not only one blocked return). Parent MAY **steer mid-flight** and **re-message the same child later** with context intact when the host keeps the child addressable. |
+
+**When to retain vs one-shot:**
+
+- ~ **Retain** for iterative refinement, standing expertise (same specialist across multiple related asks), mid-scope gates where re-attaching is cheaper than a second full dispatch, or long-lived pollers the parent still needs to steer.
+- ~ **One-shot / dispatch-and-collect** for closed unit-of-work envelopes (`drive-to: merge-ready` leaves that own their lifecycle end-to-end), hosts that cannot resume, and any child that exits terminal with no resume primitive.
+
+**Capability gate (host-dependent):**
+
+- ! Orchestrators MUST capability-gate retained-child mode on the runtime platform descriptor and host adapter (`skills/deft-directive-swarm` route table). Hosts that document continue-by-agent-id, resume-by-name, or steerable mid-flight sessions MAY use a **single dispatch with a mid-scope gate** and re-message the live child.
+- ! Hosts that treat a paused or completed worker as terminal (`agent_id` unreachable after tool-loop exit) MUST keep the **split-dispatch** mandate for mid-scope user-approval gates (#954). Do not invent retain semantics the host cannot enforce.
+- ⊗ Assume every host retains children. Capability-gate first; fall back to one-shot + split-dispatch.
+
+**Topology coupling (#3155):**
+
+- ! Retained children MUST obey **nuclear-family** messaging bounds (`## Communication Topology (#3155)`): parent / sibling / child only — not open mesh.
+- ⊗ Treat retain / message-later as license to mesh outside the nuclear family.
+
+**Stance (#3164 / #3179):**
+
+- ! Retention is for **orchestration** (addressable children, message-later, steer-mid-flight) — **not** mid-run constitution self-edit.
+- ⊗ Use retained-child messaging to rewrite managed AGENTS.md, pinned skills, policy flags, or other constitution substrate mid-run. Self-improvement stays propose-not-apply through gates (#3164).
+
+Skill depth: `skills/deft-directive-swarm/SKILL.md` (retained mode pointer) + per-host `references/host-*.md` continue/resume notes. Always-on mid-scope tier: `templates/agents-entry.md` § Mid-scope gate capability tier. Preamble: `templates/agent-prompt-preamble.md` §10.
+
 ## Communication Protocols
 
 **Explicit Context:**
@@ -231,6 +282,7 @@ new_state = state.model_copy(deep=True, update={'status': 'completed'})
 
 ## Anti-Patterns
 
+- ⊗ Open-mesh agent messaging across cohorts or sessions (violates nuclear-family topology #3155)
 - ⊗ Assuming previous agent's context
 - ⊗ Modifying files without declaring scope
 - ⊗ Committing without task ID reference
@@ -298,3 +350,5 @@ task check
 - [git.md](../scm/git.md) - Commit conventions, branch strategy
 - [taskfile.md](../tools/taskfile.md) - Build and test automation
 - [testing.md](../coding/testing.md) - Testing requirements
+- [meta/security.md](../meta/security.md) - Agent trap taxonomy; unbounded A2A graph surface (#3155)
+- [ADR-003 nuclear-family topology](../../../docs/decisions/ADR-003-a2a-nuclear-family-topology.md) - Accepted bounded-graph posture; #2705 client ADR remainder deferred

package/tasks/decision.yml

@@ -0,0 +1,30 @@
+version: '3'
+
+# tasks/decision.yml -- structured agent decision log (#1396).
+#
+# Per `conventions/task-caching.md`, tasks forwarding user-facing flags via
+# {{.CLI_ARGS}} MUST NOT declare `sources:` / `generates:`.
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  write:
+    desc: "Write a lightweight structured decision record (#1396). -- task decision:write -- [--decision TEXT] [--governing-rule ...] [--alternative ...] [--why-winner ...] [--confidence low|medium|high] [--revisit-trigger ...] [--scope PATH] [--body-file PATH] [--json] [--dry-run]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'decision:write --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  list:
+    desc: "List structured decision records under xbrief/decisions/ (#1396). -- task decision:list -- [--query TEXT] [--scope PATH] [--issue N] [--limit N] [--json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'decision:list --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/tasks/swarm.yml

@@ -16,6 +16,22 @@ tasks:
         vars:
           ENGINE_CMD: 'swarm-readiness {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"'
 
+  # swarm:pre-dispatch -- implement-leaf pre-dispatch gate (#3228 / #3143).
+  # Before starting a peer implement leaf on a unit, if a non-terminal attempt
+  # already exists → exit 1 DENY_DUPLICATE_ACTIVE and do not spawn.
+  # begin (default) begins an attempt on allow; complete/cancel terminalise.
+  # Takeover = cancel prior attempt, then pre-dispatch begin again.
+  # Exit: 0 allow / 1 active deny or gate block / 2 config.
+  # Skill citation: skills/deft-directive-swarm/references/core-phase-4.md
+  pre-dispatch:
+    desc: "Pre-dispatch gate for implement leaves: DENY_DUPLICATE_ACTIVE when unit already has an active attempt (#3228 / #3143). Exit 0 allow / 1 deny / 2 config."
+    deps: [":engine:_ts-build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'swarm-pre-dispatch {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"'
+
   # swarm:launch -- deterministic headless launch engine (#1387). Turns an
   # operator-supplied, pre-approved cohort into a ready-to-spawn launch
   # manifest: resolves --stories (issue numbers / story ids / paths) against

package/tasks/verify.yml

@@ -472,6 +472,26 @@ tasks:
         vars:
           ENGINE_CMD: 'verify:orphan-active --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
+  completed-tracked:
+    desc: "Fail-closed completed-tracked land guard (#3264 / #1358 recurrence). Closed scoped GitHub issues with a known lifecycle xBRIEF origin must have a tracked xbrief/completed/ or xbrief/cancelled/ artifact on the delivery tip. Remediation: task swarm:finalize-cohort or a lifecycle PR. Three-state exit (0 clean / 1 missing land / 2 config). Pass --skip-gh to rely on triage cache only; --tip to override delivery tip."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:completed-tracked --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  literal-ac:
+    desc: "Literal acceptance-command verification (#3267). Run stated acceptance commands from the active (or --xbrief) scope artifact VERBATIM before done — same flags/cwd. Capture-only audit: --capture-only. Three-state exit (0 pass or none stated / 1 command failed / 2 config). Extends #973; required on ceremony dial rapid/minimal (#3214)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:literal-ac --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
   agents-md-budget:
     desc: "Layered AGENTS.md budget instrument (#645 + #2450). Fail-closed relative ratchet: counts the managed section and the unmanaged region separately (the #1309 propagation duplicates content across the marker) and fails when either region grows past plan.policy.agentsMdBudget. Seeded at current size, so it ships green; growth past the ratchet fails. ADVISORY absolute north-star: also reports managed-section size vs ≤8 KB / ~2k tok (#2372 layered instrument) without affecting exit codes in Wave 1. Three-state exit (0 within / 1 over ratchet / 2 config error)."
     dir: '{{.USER_WORKING_DIR}}'

package/templates/agent-prompt-preamble.md

@@ -486,9 +486,9 @@ These rules bind **orchestrators** dispatching implementation, fix, or review-cy
 
 Reference: issue #1880 (doctrine), #1877 (gate enforcement), #954 (multi-agent discipline). Cross-references: `skills/deft-directive-swarm/SKILL.md` Phase 3 dispatch + Phase 5→6, `skills/deft-directive-review-cycle/SKILL.md` Review Monitoring.
 
-## 10. Dispatcher lifecycle hygiene -- workers are all-or-nothing
+## 10. Dispatcher lifecycle hygiene -- workers are all-or-nothing (capability-tiered, #3158)
 
-If your dispatch envelope contains a "pause for user approval" step in the middle of the worker's scope, REWRITE IT into two dispatches:
+**Default (hosts without retain):** If your dispatch envelope contains a "pause for user approval" step in the middle of the worker's scope, REWRITE IT into two dispatches:
 
 - WRONG: `Implement deliverables 1-3, then pause and wait for user confirmation before opening the PR.`
   - Worker implements 1-3, sends "paused, awaiting confirmation" message, exits its tool loop, lifecycle goes `succeeded` (terminal). User approval message hits a dead `agent_id`. Dispatcher must spawn a successor anyway -- the gate accomplished nothing except adding a context-handoff cost.
@@ -497,11 +497,13 @@ If your dispatch envelope contains a "pause for user approval" step in the middl
   - User reviews diff.
   - Dispatch B: `Open PR via REST, apply label, run review-cycle skill.`
 
-Lifecycle events (`succeeded`, `failed`, `blocked`, `in_progress`, `cancelled`, `errored`) are emitted by the platform observing the worker's process state -- the worker does not choose them directly. A worker that finishes its tool loop with a "paused" message will be observed as `succeeded` (terminal); the agent_id becomes unreachable. The only ways for a worker to remain reachable mid-flight are: keep the tool loop alive (long-lived poll / sleep) or be observed by the platform as `blocked` via a sanctioned blocked_action. Neither is a natural fit for "I finished sub-task A and want approval before sub-task B."
+Lifecycle events (`succeeded`, `failed`, `blocked`, `in_progress`, `cancelled`, `errored`) are emitted by the platform observing the worker's process state -- the worker does not choose them directly. A worker that finishes its tool loop with a "paused" message will be observed as `succeeded` (terminal); the agent_id becomes unreachable. The only ways for a worker to remain reachable mid-flight are: keep the tool loop alive (long-lived poll / sleep) or be observed by the platform as `blocked` via a sanctioned blocked_action. Neither is a natural fit for "I finished sub-task A and want approval before sub-task B" **when the host cannot re-attach**.
 
-Workers must therefore be all-or-nothing on their dispatch envelope. Approval gates split scope at the dispatcher layer.
+**Capability tier (#3158):** On hosts that **retain** a live, addressable child (continue-by-agent-id / resume-by-name / steerable mid-flight session — see host adapter retained notes and `swarm/swarm.md` § Retained addressable sub-agents), a single dispatch MAY include a mid-scope gate: the parent re-messages the same child after approval instead of forcing a second full dispatch. Capability-gate first via platform descriptor; do not invent retain on one-shot hosts. Retention is for **orchestration** (message-later, steer-mid-flight) only — not mid-run constitution self-edit (#3164). Topology bounds: #3155 nuclear-family (retain does not license open mesh).
 
-Reference: scope-expansion comment 4399553752 on issue #954.
+On hosts without retain, workers remain all-or-nothing on their dispatch envelope. Approval gates split scope at the dispatcher layer.
+
+Reference: scope-expansion comment 4399553752 on issue #954; retained-child amendment #3158.
 
 ## 10.5 Heartbeat contract (#1365)
 
@@ -534,6 +536,8 @@ Multi-iteration implement, pre-PR, repair, and monitor loops require **two** sto
 
 ! On failure stop: halt; emit an operator-visible report (what was tried, what is missing, what human decision is needed). Prefer `BLOCKED:` over silent retry. ⊗ Thrash past the envelope. Durable delivery/acceptance mechanical enforcement is **#3143** (`packages/core/src/delivery-attempt/`; not prompt-only).
 
+! **Implement-leaf pre-dispatch (#3228):** Before spawning a peer implement leaf on a unit (story/worktree), monitors/orchestrators MUST run `task swarm:pre-dispatch -- --scope-id <id> --target-id <worktree-or-branch>` (exit **0** allow / **1** active deny / **2** config). Non-zero → do not spawn. Gate is #3143 `DENY_DUPLICATE_ACTIVE`. Takeover = `--action cancel` then pre-dispatch begin again. Pointer only — skill depth: swarm `core-phase-4.md`.
+
 ## 11. Mandatory DONE message even on early exit
 
 Every worker MUST send a final status message before exiting its tool loop, regardless of outcome: