@deftai/directive-content 0.98.1 → 0.99.0

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

@@ -79,9 +79,35 @@ tools: explore=0 commit=3 verify=0 coordinate=0 unknown=1 | anomalies: commit-wi
 ⊗ 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 +124,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.

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

package/templates/agents-entry.md

@@ -83,6 +83,17 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 ⊗ `stop-at: pr-open` without a named babysit / merge-path owner, or dual review-monitor leases on recovery (#3044 / #2261).
 ⊗ Stand down at CLEAN under human-merge with no reachable post-merge `scope:complete` owner.
 
+## Nuclear-family A2A topology (#3155)
+
+! Agent-to-agent messaging is **nuclear-family** only: parent / sibling (same cohort) / child. Cross-cohort or cross-session coordination goes through a shared parent or durable parent-owned artifacts — not peer mesh. Depth: `.deft/core/swarm/swarm.md` `## Communication Topology (#3155)`; security: `.deft/core/meta/security.md` `## Unbounded A2A graphs (#3155)`; ADR: `docs/decisions/ADR-003-a2a-nuclear-family-topology.md` (decision input to #2705; client-posture ADR remainder stays on #2705). Pair: retained children #3158; parent epic #3179.
+⊗ Open-mesh agent-to-agent messaging across cohorts or sessions ("agents everywhere").
+⊗ Treat retained / re-addressable children as license to mesh outside the nuclear family.
+
+## Mid-scope gate capability tier (#3158 / #954)
+
+! Mid-scope gates: **split-dispatch** when `agent_id` is terminal; retain-capable hosts (continue-by-agent-id / message-later / steer-mid-flight) MAY re-message the live child. Retention = orchestration only — not constitution self-edit (#3164). Depth: preamble §10; `deft-directive-swarm`. Topology: #3155 nuclear-family. ⊗ Invent retain on one-shot hosts.
+
+
 ## Review-surface precedence (#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).
@@ -91,6 +102,9 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ! `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).
 
+## Structured decision log (#1396 / #3211)
+! Significant choices → `deft decision:write`; re-load → `deft decision:list` / `xbrief/decisions/`; depth `.deft/core/docs/decision-log.md` (not triage/ADRs/lessons).
+
 ## Eval and framework health (#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).
@@ -114,6 +128,10 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ## Development Process
 
+### Gate integrity (#3156)
+
+! When a quality gate fails, fix the product/process/test under test — ⊗ clear red by editing the gate definition, verifier, reward, required check, coverage floor, or policy flag solely to go green. Deliberate gate changes go through issue/PR + review. Depth: `.deft/core/docs/gate-integrity.md` (refine-internal SkillOpt stays on #2436).
+
 ### Implementation Intent Gate (#810 / #1193)
 
 ! `deft xbrief:preflight -- <path>` on `xbrief/active/` before code-writing; action-verb (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`) (#810). Slash-command sessions inherit only that verb (`DEFT_SESSION_SLASH_VERB`); non-implement verbs (`/github-issue`, `/triage`, …) MUST NOT authorize implement/push/PR/merge/deploy (#1193) — `commands.md` / `contracts/intent-ceiling.md`.

package/templates/swarm-greptile-poller-prompt.md

@@ -196,20 +196,64 @@ for m in _TIER25_RE.finditer(body):
 # Greptile sometimes inlines the verdict as plain prose, e.g.
 #     Three P1 findings (two from prior review, one new): wrong exception ...
 #     Not safe to merge until the mocked-import test defect is resolved.
+#     should-not-merge / Do not merge until residual risk is documented (#3225)
+#     Safe to merge once corrected
 #     P1 -- wrong exception type for state validation in populate()
 # Negation-context guard applies to the count-prose sentinel (`No P0 findings`,
-# `Zero P1 findings` MUST NOT trigger). The `Not safe to merge` substring is
-# Greptile's explicit human-readable verdict and is treated as a hard block.
+# `Zero P1 findings` MUST NOT trigger). Advisory should-not-merge prose is a
+# hard block even when formal review is still Comment (#3225); composes with
+# minGreptileConfidence (#3095). Canonical TS detector:
+# packages/core/src/content-contracts/skills/greptile-detector.ts
 _TIER3_COUNT_RE = re.compile(
     r"\b(?:One|Two|Three|Four|Five|Six|Seven|Eight|Nine|Ten|\d+)\s+P[01]\s+findings?\b",
     re.IGNORECASE,
 )
 _TIER3_LINE_RE = re.compile(r"^\s*P[01]\s+--\s", re.MULTILINE)
 _TIER3_NEGATIONS = ("No ", "Zero ", "no ", "NO ")
+# #3225 advisory should-not-merge family — LINE-ANCHORED (parity with
+# packages/core/src/content-contracts/skills/greptile-detector.ts).
+# Mid-sentence descriptive mentions ("adds should-not-merge matching") MUST NOT
+# trigger; Summary:/Decision: labels, bullets, and short subject prefixes
+# ("The PR is …") are stripped before the match.
+_ADVISORY_SHOULD_NOT_MERGE_RES = (
+    re.compile(r"\bnot\s+(?:yet\s+)?safe\s+to\s+merge\b", re.IGNORECASE),
+    re.compile(r"\bshould\s*[-–—]?\s*not\s*[-–—]?\s*merge\b", re.IGNORECASE),
+    re.compile(r"\bsafe\s+to\s+merge\s+once\s+corrected\b", re.IGNORECASE),
+    re.compile(r"\bdo\s+not\s+merge\b", re.IGNORECASE),
+    re.compile(r"\bnot\s+ready\s+to\s+merge\b", re.IGNORECASE),
+    re.compile(r"\bnot\s+ready\s+for\s+merge\b", re.IGNORECASE),
+)
+_ADVISORY_LINE_PREFIX_RE = re.compile(
+    r"^(?:Summary|Decision|Verdict)\s*[:\-–—]\s*",
+    re.IGNORECASE,
+)
+_ADVISORY_SUBJECT_RE = re.compile(
+    r"^(?:the\s+pr|this\s+pr|this\s+change|the\s+change|this\s+diff)\s+is\s+",
+    re.IGNORECASE,
+)
+
+def _line_has_anchored_advisory(line: str) -> bool:
+    bare = line.strip()
+    bare = re.sub(r"^>\s*", "", bare)
+    bare = _ADVISORY_LINE_PREFIX_RE.sub("", bare, count=1)
+    bare = re.sub(r"^(?:[-*•]\s+)+", "", bare)
+    bare = re.sub(r"^\*\*", "", bare)
+    bare = re.sub(r"\*\*$", "", bare)
+    bare = re.sub(r"^_", "", bare)
+    bare = re.sub(r"_$", "", bare)
+    bare = _ADVISORY_SUBJECT_RE.sub("", bare, count=1).strip()
+    if not bare:
+        return False
+    for pat in _ADVISORY_SHOULD_NOT_MERGE_RES:
+        m = pat.search(bare)
+        if m is not None and m.start() <= 4:
+            return True
+    return False
 
 def _has_tier3_sentinel(body: str) -> bool:
-    if "Not safe to merge" in body:
-        return True
+    for line in body.splitlines():
+        if _line_has_anchored_advisory(line):
+            return True
     for m in _TIER3_COUNT_RE.finditer(body):
         line = _line_for(body, m.start())
         if any(neg in line for neg in _TIER3_NEGATIONS):

package/vbrief/schemas/vbrief-core.schema.json

@@ -509,6 +509,11 @@
             "critical"
           ]
         },
+        "effort": {
+          "type": "string",
+          "enum": ["S", "M", "L", "XL"],
+          "description": "Optional effort estimate with time anchors: S <2h, M half-day (2-4h), L 1-2 days, XL needs breakdown into S/M/L before activation. Omitted items still validate."
+        },
         "dueDate": {
           "$ref": "#/$defs/dateTime"
         },

package/vbrief/schemas/xbrief-core-0.8.schema.json

@@ -318,6 +318,11 @@
             "critical"
           ]
         },
+        "effort": {
+          "type": "string",
+          "enum": ["S", "M", "L", "XL"],
+          "description": "Optional effort estimate with time anchors: S <2h, M half-day (2-4h), L 1-2 days, XL needs breakdown into S/M/L before activation. Omitted items still validate."
+        },
         "dueDate": {
           "$ref": "#/$defs/dateTime"
         },

package/vbrief/vbrief.md

@@ -419,6 +419,43 @@ Scope vBRIEFs use a small set of **canonical narrative keys** at the `plan.narra
 }
 ```
 
+### Effort estimate (S/M/L/XL) (#1581)
+
+`PlanItem.effort` is an **optional** sizing field on each plan item. Existing items that omit it still validate.
+
+| Value | Time anchor | Meaning |
+|-------|-------------|---------|
+| `S` | less than 2 hours | Safe single-agent slice |
+| `M` | half-day (2–4 hours) | Single-agent; modest scope |
+| `L` | 1–2 days | May warrant a dedicated agent or parallel worktrees |
+| `XL` | needs breakdown | **Must not enter `active/` / `running`** until broken into S/M/L items |
+
+#### Authority and ordering (compose with ceremony dial #3214)
+
+Plan-item `effort` is **post-planning** authority. Estimates live on scope plan items after planning has produced those items. Session-start ceremony (ritual, deposit load, gate setup) runs **before** planning, so plan-item effort is **not** available as session-start ritual input.
+
+- ! Treat `PlanItem.effort` as the planning-time confirm/correct signal for provisional intake size — not as a required input for initial ritual depth
+- ⊗ Claim or require plan-item `effort` at session start to choose ceremony depth — that wiring deadlocks (no plan items yet)
+- ~ Ceremony dial (#3214) SHOULD use a **two-stage** path: start every session at **rapid** depth, then escalate to full ceremony when the plan lands M/L or the task proves project-shaped; optional intake-time provisional S/M/L is a tiebreaker only
+- ! Headless / autonomous runs MUST apply provisional estimates and stage transitions **without** operator confirmation prompts
+
+Rules:
+
+- ! When present, `effort` MUST be one of `S`, `M`, `L`, `XL` (case-sensitive)
+- ? Omit `effort` when sizing is unknown; validation does not require the field
+- ! XL items MUST be broken into S/M/L sub-items (or re-estimated to S/M/L) before `task scope:activate` / `task vbrief:activate` — both paths fail closed while any nested item still has `effort: "XL"`
+- ~ Swarm allocation SHOULD read `effort` when sizing agents (XL blocks dispatch until breakdown; L may warrant a dedicated agent; S/M are safe single-agent)
+- ~ Refinement SHOULD prompt for an estimate when accepting proposed → pending so cost signal is present before activation
+
+```json
+{
+  "id": "auth-slice",
+  "title": "Wire OAuth callback",
+  "status": "pending",
+  "effort": "M"
+}
+```
+
 ### Hierarchical Items (v0.6)
 
 Specs with phases, subphases, and tasks express nesting via `PlanItem.items`:

package/verification/verification.md

@@ -4,7 +4,7 @@ Goal-backward verification of agent output — check outcomes, not checklists.
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [coding/testing.md](../coding/testing.md) | [verification/uat.md](./uat.md) | [core/glossary.md](../glossary.md)
+**⚠️ See also**: [coding/testing.md](../coding/testing.md) | [verification/uat.md](./uat.md) | [core/glossary.md](../glossary.md) | [patterns/goal-gate-determinism.md](../patterns/goal-gate-determinism.md) (#852 — rigid goals/gates; flexible execution path) | [docs/gate-integrity.md](../docs/gate-integrity.md) (#3156 — do not clear red by editing the gate)
 
 > Adapted from [GSD](https://github.com/gsd-build/get-shit-done) verification model.
 
@@ -115,3 +115,4 @@ Pick the **strongest tier reachable** for each task.
 - ⊗ Accepting stubs as complete
 - ⊗ Asking a human to check what the agent can verify itself
 - ⊗ Verifying process ("I did steps 1–5") instead of outcomes ("user can log in")
+- ⊗ Clearing a failing gate by editing the gate definition, verifier, reward, required check, coverage floor, or policy flag — fix the work under test, or change the gate via issue/PR + review ([gate-integrity.md](../docs/gate-integrity.md) #3156)