@deftai/directive-content 0.64.0 → 0.66.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/.githooks/_deft-run.sh +14 -0
  2. package/.githooks/pre-commit +9 -10
  3. package/.githooks/pre-push +4 -7
  4. package/QUICK-START.md +8 -4
  5. package/Taskfile.yml +32 -14
  6. package/UPGRADING.md +40 -0
  7. package/commands.md +46 -41
  8. package/conventions/rule-ownership.json +1 -1
  9. package/docs/BROWNFIELD.md +37 -33
  10. package/docs/directive-lifecycle.md +2 -2
  11. package/docs/getting-started.md +8 -8
  12. package/package.json +1 -1
  13. package/packs/skills/skills-pack-0.1.json +28 -28
  14. package/skills/deft-directive-article-review/SKILL.md +4 -4
  15. package/skills/deft-directive-build/SKILL.md +37 -37
  16. package/skills/deft-directive-cost/SKILL.md +6 -6
  17. package/skills/deft-directive-debug/SKILL.md +4 -4
  18. package/skills/deft-directive-decompose/SKILL.md +15 -15
  19. package/skills/deft-directive-gh-arch/SKILL.md +3 -3
  20. package/skills/deft-directive-gh-slice/SKILL.md +2 -2
  21. package/skills/deft-directive-interview/SKILL.md +12 -12
  22. package/skills/deft-directive-pre-pr/SKILL.md +3 -3
  23. package/skills/deft-directive-probe/SKILL.md +9 -9
  24. package/skills/deft-directive-refinement/SKILL.md +65 -65
  25. package/skills/deft-directive-release/SKILL.md +3 -3
  26. package/skills/deft-directive-review-cycle/SKILL.md +4 -4
  27. package/skills/deft-directive-setup/SKILL.md +71 -71
  28. package/skills/deft-directive-swarm/SKILL.md +94 -94
  29. package/skills/deft-directive-sync/SKILL.md +55 -55
  30. package/skills/deft-directive-triage/SKILL.md +15 -15
  31. package/tasks/architecture.yml +3 -1
  32. package/tasks/cache.yml +20 -10
  33. package/tasks/capacity.yml +8 -4
  34. package/tasks/change.yml +8 -10
  35. package/tasks/changelog.yml +3 -1
  36. package/tasks/codebase.yml +20 -10
  37. package/tasks/commit.yml +4 -8
  38. package/tasks/engine.yml +16 -4
  39. package/tasks/install.yml +4 -8
  40. package/tasks/issue.yml +8 -10
  41. package/tasks/migrate.yml +24 -8
  42. package/tasks/packs.yml +32 -16
  43. package/tasks/policy.yml +24 -12
  44. package/tasks/pr.yml +16 -8
  45. package/tasks/prd.yml +9 -12
  46. package/tasks/project.yml +14 -14
  47. package/tasks/reconcile.yml +4 -8
  48. package/tasks/roadmap.yml +9 -5
  49. package/tasks/scm.yml +36 -18
  50. package/tasks/scope-undo.yml +3 -1
  51. package/tasks/scope.yml +40 -26
  52. package/tasks/session.yml +4 -2
  53. package/tasks/slice.yml +8 -10
  54. package/tasks/spec.yml +10 -12
  55. package/tasks/swarm.yml +20 -10
  56. package/tasks/triage-actions.yml +32 -16
  57. package/tasks/triage-bootstrap.yml +4 -2
  58. package/tasks/triage-bulk.yml +20 -10
  59. package/tasks/triage-classify.yml +4 -2
  60. package/tasks/triage-queue.yml +12 -6
  61. package/tasks/triage-reconcile.yml +4 -2
  62. package/tasks/triage-scope-drift.yml +4 -2
  63. package/tasks/triage-scope.yml +4 -2
  64. package/tasks/triage-smoketest.yml +4 -2
  65. package/tasks/triage-subscribe.yml +8 -4
  66. package/tasks/triage-summary.yml +4 -2
  67. package/tasks/triage-welcome.yml +4 -2
  68. package/tasks/ts.yml +3 -1
  69. package/tasks/umbrella.yml +1 -7
  70. package/tasks/vbrief.yml +25 -17
  71. package/tasks/verify.yml +107 -48
  72. package/templates/agent-prompt-preamble.md +16 -16
  73. package/templates/agents-entry.md +23 -19
  74. package/vbrief/conformance/extensions/valid/extension-at-root.vbrief.json +31 -0
  75. package/vbrief/conformance/extensions/valid/nested-extension-value.vbrief.json +19 -0
  76. package/vbrief/schemas/xbrief-core-0.8.schema.json +786 -0
@@ -2,7 +2,7 @@
2
2
  name: deft-directive-swarm
3
3
  description: >-
4
4
  Parallel local agent orchestration. Use when running multiple agents on
5
- story-level vBRIEFs simultaneously — to scan active/ for allocatable work,
5
+ story-level xBRIEFs simultaneously — to scan active/ for allocatable work,
6
6
  set up isolated worktrees, launch agents with proven prompts, monitor
7
7
  progress, handle stalled review cycles, and close out PRs cleanly.
8
8
  ---
@@ -14,7 +14,7 @@ description: >-
14
14
 
15
15
  # Deft Directive Swarm
16
16
 
17
- Structured workflow for a monitor agent to orchestrate N parallel local agents working on story-level vBRIEFs from `vbrief/active/`.
17
+ Structured workflow for a monitor agent to orchestrate N parallel local agents working on story-level xBRIEFs from `xbrief/active/`.
18
18
 
19
19
  Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
20
20
 
@@ -41,7 +41,7 @@ or invoke `task verify:branch`. The swarm skill creates branches per agent so th
41
41
  ## When to Use
42
42
 
43
43
  - User says "run agents", "parallel agents", "swarm", or "launch N agents on stories"
44
- - Multiple independent story-level vBRIEFs in `vbrief/active/` need to be worked on simultaneously
44
+ - Multiple independent story-level xBRIEFs in `xbrief/active/` need to be worked on simultaneously
45
45
  - A batch of stories are ready and have no mutual dependencies
46
46
 
47
47
  ## Running Swarms in Grok Build / Non-Warp Environments
@@ -59,7 +59,7 @@ This path became first-class in #1342 (platform adapter slices 1-3) and is fully
59
59
 
60
60
  ## Prerequisites
61
61
 
62
- - ! `vbrief/active/` contains one or more story-level vBRIEFs with status `running`
62
+ - ! `xbrief/active/` contains one or more story-level xBRIEFs with status `running`
63
63
  - ! GitHub CLI (`gh`) is authenticated
64
64
  - ! `git` supports worktrees (`git worktree` available)
65
65
  - ~ `oz` CLI available (for `oz agent run-cloud` cloud launch — see Phase 3 Step 2c)
@@ -71,14 +71,14 @@ This path became first-class in #1342 (platform adapter slices 1-3) and is fully
71
71
  ### Headless cohort fast-path: low-ceremony launch (C1 / #1387)
72
72
 
73
73
  ! When the operator supplies a **pre-approved cohort** via the **C1** `task swarm:launch` CLI, Phase 0 runs in headless / low-ceremony mode: the per-phase interactive approval gates (the Step 0c promote-fill prompts, the Step 0.5 lifecycle-bridge approval, and the Step 4/5 allocation approval) collapse into a SINGLE consent -- the `## Allocation context` token (#1378) carried in the dispatch envelope. The interactive promote-fill loop (Step 0a -- 0d below) is SKIPPED.
74
- ! The **C1** signature is `task swarm:launch -- --stories <ids|paths> [--group <label>] [--worktree-map <path>] [--base-branch <branch>] [--autonomous]`. `--stories` names the pre-approved story ids or vBRIEF paths; `--group` is an optional cohort label; `--worktree-map` points at the pre-created **C3** worktree-map JSON consumed in Phase 2; `--base-branch` overrides the default `master`; `--autonomous` runs without the interactive launch confirmation.
74
+ ! The **C1** signature is `task swarm:launch -- --stories <ids|paths> [--group <label>] [--worktree-map <path>] [--base-branch <branch>] [--autonomous]`. `--stories` names the pre-approved story ids or xBRIEF paths; `--group` is an optional cohort label; `--worktree-map` points at the pre-created **C3** worktree-map JSON consumed in Phase 2; `--base-branch` overrides the default `master`; `--autonomous` runs without the interactive launch confirmation.
75
75
  ! The SINGLE consent is the #1378 `## Allocation context` token with `dispatch_kind: swarm-cohort` and a NON-NULL `allocation_plan_id` AND `batching_rationale` (the recognition contract in `templates/agent-prompt-preamble.md` § 2.5). That token IS the batched approval for the whole cohort -- the deterministic-question gates the interactive path runs (per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md)) are bypassed wholesale on the headless path, not asked once per phase.
76
76
  ⊗ Re-prompt the operator for per-phase batching approval, or run the interactive promote-fill loop (Step 0a -- 0d), when a pre-approved cohort is supplied via `task swarm:launch` -- the headless path's single #1378 consent already authorizes the batch, and re-prompting mid-cohort violates the all-or-nothing dispatch-envelope rule (#954).
77
77
  ? The interactive queue-driven path (Step 0 below) remains the DEFAULT when no pre-approved cohort is supplied; the headless fast-path is the opt-in low-ceremony route for a cohort the operator has already curated and approved upstream.
78
78
 
79
79
  ### Step 0: Queue-driven cohort selection (#1142 / N2)
80
80
 
81
- ! Phase 0 is queue-driven: consult the triage cache (D2 / #1122 + D11 / #1128) for the ranked promotion candidates, then fill the WIP cap. Do NOT pick the cohort by hand from `vbrief/pending/` or `vbrief/active/` -- the queue is the canonical record of "what's next?" per AGENTS.md `## Cache-as-authoritative work selection (#1149)`. The four sub-phases below run in canonical order; existing Step 0.5 (lifecycle bridge) and Steps 1-5 (readiness / blockers / allocation / present / approval) proceed unchanged after Phase 0d.
81
+ ! Phase 0 is queue-driven: consult the triage cache (D2 / #1122 + D11 / #1128) for the ranked promotion candidates, then fill the WIP cap. Do NOT pick the cohort by hand from `xbrief/pending/` or `xbrief/active/` -- the queue is the canonical record of "what's next?" per AGENTS.md `## Cache-as-authoritative work selection (#1149)`. The four sub-phases below run in canonical order; existing Step 0.5 (lifecycle bridge) and Steps 1-5 (readiness / blockers / allocation / present / approval) proceed unchanged after Phase 0d.
82
82
 
83
83
  #### Phase 0a -- State overview via `task triage:summary` (D2 / #1122)
84
84
 
@@ -104,22 +104,22 @@ task triage:queue --state=accept --limit=20
104
104
 
105
105
  #### Phase 0c -- Promote-fill-cap loop
106
106
 
107
- ! While `pending/ + active/` count < `wipCap` AND the queue is non-empty, prompt the operator to promote the next ranked candidate to `vbrief/pending/`.
107
+ ! While `pending/ + active/` count < `wipCap` AND the queue is non-empty, prompt the operator to promote the next ranked candidate to `xbrief/pending/`.
108
108
 
109
109
  Loop body, per candidate (top-of-queue first):
110
110
 
111
111
  1. ! Render the next queue candidate with brief context (issue title, labels, top-1 ranking rationale).
112
- 2. ! Prompt the operator: `Promote #<N> to vbrief/pending/? [yes/skip/stop]`. The final two numbered options remain `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md).
112
+ 2. ! Prompt the operator: `Promote #<N> to xbrief/pending/? [yes/skip/stop]`. The final two numbered options remain `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md).
113
113
  3. On `yes` -- promote via the canonical lifecycle verb:
114
114
 
115
115
  ```pwsh path=null start=null
116
116
  # D18 #1136 fallback: the eventual --from-issue=<N> shape is OPEN but not
117
117
  # yet implemented. Until #1136 lands, the monitor resolves the candidate's
118
- # vBRIEF file from the issue number (file lives in vbrief/proposed/ from a
118
+ # xBRIEF file from the issue number (file lives in xbrief/proposed/ from a
119
119
  # prior triage:accept step, D10 / #1129) and passes the path to
120
120
  # `task scope:promote`. Same lifecycle command, just routed through the
121
121
  # file path rather than the issue-number shortcut.
122
- task scope:promote vbrief/proposed/<file>.vbrief.json
122
+ task scope:promote xbrief/proposed/<file>.xbrief.json
123
123
  # TODO(#1136): when D18 ships, replace the two-step (resolve file from #N,
124
124
  # then pass to `task scope:promote`) with the deterministic one-step
125
125
  # `task scope:promote --from-issue=<N>` invocation. The integration point
@@ -132,15 +132,15 @@ Loop body, per candidate (top-of-queue first):
132
132
  4. On `skip` -- drop this candidate from the current session's cohort; it stays in the queue for the next session. Advance to the next ranked candidate.
133
133
  5. On `stop` -- exit the loop early; the partial cohort proceeds to Phase 0d.
134
134
 
135
- ! **D18 #1136 integration point**: the eventual `task scope:promote --from-issue=<N>` shape (D18 / #1136) is OPEN but not yet implemented. When it lands, the prompt above will be replaced with a deterministic `task scope:promote --from-issue=<N>` invocation; the operator no longer needs to resolve the vBRIEF file path manually. Until then, the file-path fallback above is the canonical Phase 0c verb -- it is the same `task scope:promote` lifecycle command, just routed through the file path rather than the issue-number shortcut. Track via #1136.
135
+ ! **D18 #1136 integration point**: the eventual `task scope:promote --from-issue=<N>` shape (D18 / #1136) is OPEN but not yet implemented. When it lands, the prompt above will be replaced with a deterministic `task scope:promote --from-issue=<N>` invocation; the operator no longer needs to resolve the xBRIEF file path manually. Until then, the file-path fallback above is the canonical Phase 0c verb -- it is the same `task scope:promote` lifecycle command, just routed through the file path rather than the issue-number shortcut. Track via #1136.
136
136
 
137
- ! **WIP-cap exit-clean prose**: When WIP cap is reached, swarm Phase 0 stops adding to the cohort and exits cleanly with a count of what was filled. Operator can demote (D1 / #1121, `task scope:demote <existing>` or `task scope:demote --batch --older-than-days 30`) to free slots or `--force` to override (the override is audit-logged as `wip_cap_override` in `vbrief/.eval/scope-lifecycle.jsonl` per D4 / #1124).
137
+ ! **WIP-cap exit-clean prose**: When WIP cap is reached, swarm Phase 0 stops adding to the cohort and exits cleanly with a count of what was filled. Operator can demote (D1 / #1121, `task scope:demote <existing>` or `task scope:demote --batch --older-than-days 30`) to free slots or `--force` to override (the override is audit-logged as `wip_cap_override` in `xbrief/.eval/scope-lifecycle.jsonl` per D4 / #1124).
138
138
 
139
139
  ! **Cohort recovery on cap-fill exit**: If the queue surfaces 10 candidates but the cap allows only 4 more slots, the unpicked 6 stay queued for the next session. No state is lost; the queue is the canonical record. The operator can free a slot via `task scope:demote <existing>` (D1 / #1121) before re-running Phase 0, or accept the smaller cohort for this session.
140
140
 
141
141
  #### Phase 0d -- Cohort dispatch
142
142
 
143
- - ! After the promote-fill loop exits (cap reached, queue empty, or operator `stop`), `vbrief/pending/` now holds the cohort. Phase 0e below is now deprecated (#1891) -- per-role operator model routing (`task swarm:routing-set`, #1739) supersedes the sub-agent backend enum; `task verify:routing -- --advise` is the session-start disclosure surface. The existing Step 0.5 (Lifecycle Bridge -- Promote and Activate Proposed Scope vBRIEFs, #1025) moves the cohort `pending/ -> active/`, and Steps 1-5 (readiness report, blockers, allocation, present, approval) proceed against the activated set. Existing swarm Phase 1+ (Select, Setup, Launch, Monitor, Review, Close) proceeds unchanged.
143
+ - ! After the promote-fill loop exits (cap reached, queue empty, or operator `stop`), `xbrief/pending/` now holds the cohort. Phase 0e below is now deprecated (#1891) -- per-role operator model routing (`task swarm:routing-set`, #1739) supersedes the sub-agent backend enum; `task verify:routing -- --advise` is the session-start disclosure surface. The existing Step 0.5 (Lifecycle Bridge -- Promote and Activate Proposed Scope xBRIEFs, #1025) moves the cohort `pending/ -> active/`, and Steps 1-5 (readiness report, blockers, allocation, present, approval) proceed against the activated set. Existing swarm Phase 1+ (Select, Setup, Launch, Monitor, Review, Close) proceeds unchanged.
144
144
 
145
145
  #### Phase 0e -- Interactive sub-agent backend selection (DEPRECATED -- #1568 / superseded by #1739)
146
146
 
@@ -160,7 +160,7 @@ Loop body, per candidate (top-of-queue first):
160
160
 
161
161
  ! When all in-scope candidates are freshly setup-created candidates from the same setup session, present one explicit batch confirmation before promoting and activating the full set through Step 0.5. The confirmation must name the candidate list and the lifecycle transition (`proposed/` or `pending/` -> `active/`) so the setup handoff is swarm-ready without asking once per file.
162
162
 
163
- ~ Setup-side handoff language SHOULD point here: after setup creates initial scope vBRIEFs, tell the operator that the swarm skill will verify or offer to create the remaining project infrastructure before allocation. #1187 remains the dependency for missing executable tools; #1053 owns the greenfield project-infrastructure bridge.
163
+ ~ Setup-side handoff language SHOULD point here: after setup creates initial scope xBRIEFs, tell the operator that the swarm skill will verify or offer to create the remaining project infrastructure before allocation. #1187 remains the dependency for missing executable tools; #1053 owns the greenfield project-infrastructure bridge.
164
164
 
165
165
  ⊗ Treat #1187 machine-tool success as proof that a greenfield project is swarm-ready -- repo, remote, Taskfile wiring, install layout, gitignore, and scratch/worktree readiness are separate checks (#1053).
166
166
 
@@ -169,85 +169,85 @@ Loop body, per candidate (top-of-queue first):
169
169
  ? When the operator explicitly opts out of the queue (e.g. a one-off ad-hoc cohort that has not been ingested into the triage cache yet, or a swarm batch driven from a hand-supplied list of issue numbers), the monitor MAY fall back to the legacy GitHub-issue path:
170
170
 
171
171
  1. ! Fetch issue data: `gh api repos/<owner>/<repo>/issues/<N>` (REST per `templates/agent-prompt-preamble.md` § 5; never the GraphQL `gh issue view --json` surface).
172
- 2. ! Generate a minimal vBRIEF in `vbrief/proposed/` following the `YYYY-MM-DD-descriptive-slug.vbrief.json` naming convention (slug rules: [`../../conventions/vbrief-filenames.md`](../../conventions/vbrief-filenames.md)) and conforming to the canonical v0.6 schema (`vbrief/schemas/vbrief-core.schema.json`, strict `const: "0.6"`; see [`../../conventions/references.md`](../../conventions/references.md)).
172
+ 2. ! Generate a minimal xBRIEF in `xbrief/proposed/` following the `YYYY-MM-DD-descriptive-slug.xbrief.json` naming convention (slug rules: [`../../conventions/vbrief-filenames.md`](../../conventions/vbrief-filenames.md)) and conforming to the canonical v0.6 schema (`xbrief/schemas/xbrief-core.schema.json`, strict `const: "0.6"`; see [`../../conventions/references.md`](../../conventions/references.md)).
173
173
  3. ! Promote through the canonical lifecycle (`task scope:promote -- <path>` then `task scope:activate -- <path>`), respecting the WIP cap and the same `--force` audit-logged override semantics as the queue-driven loop.
174
174
  4. ! Surface the opt-out reason in the Step 4 (Present Analysis) summary so a reviewer can see WHY the queue was bypassed.
175
175
 
176
176
  ⊗ Default to the manual escape hatch when the queue is non-empty -- the cache-as-authoritative directive (AGENTS.md `## Cache-as-authoritative work selection (#1149)`) requires consulting the queue first.
177
177
 
178
- ### Step 0.5: Lifecycle Bridge -- Promote and Activate Proposed Scope vBRIEFs (#1025)
178
+ ### Step 0.5: Lifecycle Bridge -- Promote and Activate Proposed Scope xBRIEFs (#1025)
179
179
 
180
- ! Before running the Step 1 preflight gate, scan `vbrief/proposed/` and `vbrief/pending/` for candidate scope vBRIEFs and bridge them to `vbrief/active/`. The deft-directive-setup skill Phase 3 (Output -- Light Path / Output -- Full Path) deposits new scope vBRIEFs in `vbrief/proposed/`; the deft-directive-refinement skill Phase 4 (Promote/Demote) deposits them in `vbrief/pending/`. The swarm Phase 0 Step 1 preflight gate (`task vbrief:preflight`) only accepts vBRIEFs in `vbrief/active/` with `plan.status == "running"`, so candidates in `proposed/` or `pending/` MUST be bridged through the canonical lifecycle (`proposed -> pending -> active`) before allocation. Without this bridge, the monitor discovers the gap at runtime as a wholesale preflight rejection (`Invalid transition: 'activate' requires file in pending/`), as in the originating 2026-05-10 first-session consumer swarm.
180
+ ! Before running the Step 1 preflight gate, scan `xbrief/proposed/` and `xbrief/pending/` for candidate scope xBRIEFs and bridge them to `xbrief/active/`. The deft-directive-setup skill Phase 3 (Output -- Light Path / Output -- Full Path) deposits new scope xBRIEFs in `xbrief/proposed/`; the deft-directive-refinement skill Phase 4 (Promote/Demote) deposits them in `xbrief/pending/`. The swarm Phase 0 Step 1 preflight gate (`task xbrief:preflight`) only accepts xBRIEFs in `xbrief/active/` with `plan.status == "running"`, so candidates in `proposed/` or `pending/` MUST be bridged through the canonical lifecycle (`proposed -> pending -> active`) before allocation. Without this bridge, the monitor discovers the gap at runtime as a wholesale preflight rejection (`Invalid transition: 'activate' requires file in pending/`), as in the originating 2026-05-10 first-session consumer swarm.
181
181
 
182
- ! **Scan**: list every `*.vbrief.json` under `vbrief/proposed/` and `vbrief/pending/`. Cross-reference each candidate against the user's stated swarm scope (the issue numbers / vBRIEF filenames the user asked the monitor to swarm on). Candidates outside the stated scope MUST NOT be promoted or activated by this bridge -- they may be in a deliberate refinement queue owned by `skills/deft-directive-refinement/SKILL.md` Phase 4.
182
+ ! **Scan**: list every `*.xbrief.json` under `xbrief/proposed/` and `xbrief/pending/`. Cross-reference each candidate against the user's stated swarm scope (the issue numbers / xBRIEF filenames the user asked the monitor to swarm on). Candidates outside the stated scope MUST NOT be promoted or activated by this bridge -- they may be in a deliberate refinement queue owned by `skills/deft-directive-refinement/SKILL.md` Phase 4.
183
183
 
184
184
  ! **Present**: render a numbered list of in-scope candidates to the user with their current lifecycle folder (`proposed/` vs `pending/`) and `plan.status`. Render the canonical numbered menu in chat unless the host UI visibly preserves the same numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options MUST be `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md).
185
185
 
186
- ! **Approve**: wait for explicit user approval (`yes`, `confirmed`, `approve`) before any lifecycle mutation. Broad affirmative continuation phrases (`proceed`, `do it`, `go ahead`) are NOT authorisation -- the bridge MUST be explicitly confirmed because promoting + activating a scope vBRIEF is a lifecycle commitment that flips `plan.status` to `running` and clears the #810 implementation-intent gate for downstream agent dispatch.
186
+ ! **Approve**: wait for explicit user approval (`yes`, `confirmed`, `approve`) before any lifecycle mutation. Broad affirmative continuation phrases (`proceed`, `do it`, `go ahead`) are NOT authorisation -- the bridge MUST be explicitly confirmed because promoting + activating a scope xBRIEF is a lifecycle commitment that flips `plan.status` to `running` and clears the #810 implementation-intent gate for downstream agent dispatch.
187
187
 
188
188
  ! **Bridge**: for each approved candidate, run the canonical lifecycle commands in order:
189
189
 
190
- - For candidates in `vbrief/proposed/`: `task scope:promote -- <path>` (moves to `pending/`, status `pending`), THEN `task scope:activate -- <path-in-pending>` (moves to `active/`, status `running`).
191
- - For candidates already in `vbrief/pending/`: `task scope:activate -- <path>` alone (moves to `active/`, status `running`).
190
+ - For candidates in `xbrief/proposed/`: `task scope:promote -- <path>` (moves to `pending/`, status `pending`), THEN `task scope:activate -- <path-in-pending>` (moves to `active/`, status `running`).
191
+ - For candidates already in `xbrief/pending/`: `task scope:activate -- <path>` alone (moves to `active/`, status `running`).
192
192
 
193
193
  Both commands are idempotent: a same-folder move with matching status is a no-op (see `scripts/scope_lifecycle.py`). If either command exits non-zero, surface the exit message verbatim, do NOT attempt to allocate against the failed candidate, and ask the user how to route.
194
194
 
195
- ! **Verify**: re-run the scan and confirm each approved candidate now lives in `vbrief/active/` with `plan.status == "running"`. Only candidates that pass this verification advance to Step 1 (Read Project State); the rest stay surfaced as preflight rejections.
195
+ ! **Verify**: re-run the scan and confirm each approved candidate now lives in `xbrief/active/` with `plan.status == "running"`. Only candidates that pass this verification advance to Step 1 (Read Project State); the rest stay surfaced as preflight rejections.
196
196
 
197
- ⊗ Auto-promote + activate every candidate in `vbrief/proposed/` or `vbrief/pending/` without explicit user approval -- proposed-stage vBRIEFs may be in a deliberate refinement queue (`skills/deft-directive-refinement/SKILL.md` Phase 4) and silent promotion bypasses the user's lifecycle intent.
197
+ ⊗ Auto-promote + activate every candidate in `xbrief/proposed/` or `xbrief/pending/` without explicit user approval -- proposed-stage xBRIEFs may be in a deliberate refinement queue (`skills/deft-directive-refinement/SKILL.md` Phase 4) and silent promotion bypasses the user's lifecycle intent.
198
198
 
199
- ⊗ Skip the lifecycle bridge and let the Step 1 preflight gate (`task vbrief:preflight`) reject the candidates wholesale -- the gate's exit message tells the user WHAT failed but not WHY the source folder was wrong; the bridge is the contract that prevents that confusion before it surfaces.
199
+ ⊗ Skip the lifecycle bridge and let the Step 1 preflight gate (`task xbrief:preflight`) reject the candidates wholesale -- the gate's exit message tells the user WHAT failed but not WHY the source folder was wrong; the bridge is the contract that prevents that confusion before it surfaces.
200
200
 
201
201
  ⊗ Promote candidates outside the user's stated swarm scope. The bridge is scope-bounded by what the user asked the monitor to swarm on; out-of-scope candidates remain in `proposed/` / `pending/` for the refinement skill to own.
202
202
 
203
203
  Cross-references:
204
- - Setup-side deposit point: `skills/deft-directive-setup/SKILL.md` Phase 3 Output -- Light Path / Output -- Full Path (scope vBRIEFs land in `vbrief/proposed/`).
204
+ - Setup-side deposit point: `skills/deft-directive-setup/SKILL.md` Phase 3 Output -- Light Path / Output -- Full Path (scope xBRIEFs land in `xbrief/proposed/`).
205
205
  - Refinement-side deposit point: `skills/deft-directive-refinement/SKILL.md` Phase 4 -- Promote/Demote (lifecycle transitions via the same `task scope:promote` / `task scope:activate` surface).
206
206
  - Underlying CLI: `scripts/scope_lifecycle.py` (the deterministic state machine; idempotent on same-folder moves; three-state exit 0 / 1 / 2).
207
- - Recurrence record: issue #1025 (2026-05-10 first-session consumer tic-tac-toe swarm; monitor hit `Invalid transition: 'activate' requires file in pending/` on all four candidate vBRIEFs because they were still in `proposed/`).
207
+ - Recurrence record: issue #1025 (2026-05-10 first-session consumer tic-tac-toe swarm; monitor hit `Invalid transition: 'activate' requires file in pending/` on all four candidate xBRIEFs because they were still in `proposed/`).
208
208
 
209
209
  ### Step 1: Read Project State and Readiness Report
210
210
 
211
- - ! Scan `vbrief/active/` for candidate vBRIEFs (files matching `*.vbrief.json`)
212
- - ! For each candidate vBRIEF, MUST run `task vbrief:preflight -- <path>` (the structural intent gate, #810; wraps `scripts/preflight_implementation.py` so the same invocation works whether deft is the project root or installed as a `deft/` subdirectory) to validate lifecycle eligibility before allocation work. Skip any vBRIEF that exits non-zero -- the helper's stderr message is the actionable redirect (`task vbrief:activate <path>`). Surface the exit message in the Phase 0 Step 4 analysis so the user can route the lifecycle move; do NOT attempt to allocate, dispatch, or implement against a vBRIEF that fails the preflight.
213
- - ! Run `task swarm:readiness -- vbrief/active/*.vbrief.json` before any agent allocation. This deterministic report is the allocator's source of truth for ready stories, blocked stories, decomposition-needed epics/phases, dependency waves, conflict groups, file overlap matrix, and missing fields.
211
+ - ! Scan `xbrief/active/` for candidate xBRIEFs (files matching `*.xbrief.json`)
212
+ - ! For each candidate xBRIEF, MUST run `task xbrief:preflight -- <path>` (the structural intent gate, #810; wraps `scripts/preflight_implementation.py` so the same invocation works whether deft is the project root or installed as a `deft/` subdirectory) to validate lifecycle eligibility before allocation work. Skip any xBRIEF that exits non-zero -- the helper's stderr message is the actionable redirect (`task xbrief:activate <path>`). Surface the exit message in the Phase 0 Step 4 analysis so the user can route the lifecycle move; do NOT attempt to allocate, dispatch, or implement against a xBRIEF that fails the preflight.
213
+ - ! Run `task swarm:readiness -- xbrief/active/*.xbrief.json` before any agent allocation. This deterministic report is the allocator's source of truth for ready stories, blocked stories, decomposition-needed epics/phases, dependency waves, conflict groups, file overlap matrix, and missing fields.
214
214
  - ! Treat `plan.metadata.kind = "epic"` and `plan.metadata.kind = "phase"` as **needs decomposition**, not merely incomplete. Route broad scopes to `skills/deft-directive-decompose/SKILL.md` instead of assigning them to workers.
215
215
  - ! Read only readiness-approved story fields for allocation: `plan.title`, `plan.status`, non-empty `plan.items`, `planRef`, `references`, `plan.metadata.kind`, and `plan.metadata.swarm`.
216
- - ! Read `vbrief/PROJECT-DEFINITION.vbrief.json` for project-wide context (narratives, scope registry)
216
+ - ! Read `xbrief/PROJECT-DEFINITION.xbrief.json` for project-wide context (narratives, scope registry)
217
217
  - ! Determine the base branch: ask the user which branch to target for worktree creation, PR targets, and rebase cascade (default: `master`). Record this as the **configured base branch** for all subsequent phases.
218
- - ⊗ Spawn an implementation agent (via `start_agent`, `oz agent run`, Warp tab dispatch, or any other path) for a vBRIEF that has not passed `task vbrief:preflight` (which wraps `scripts/preflight_implementation.py`) -- the gate is the only authorization signal; affirmative continuation phrases and workflow-shape vocabulary are NOT (#810).
219
- - ⊗ Allocate concurrent workers unless candidates are swarm-ready `kind=story` vBRIEFs with non-empty executable `plan.items` and `task swarm:readiness` exits 0.
218
+ - ⊗ Spawn an implementation agent (via `start_agent`, `oz agent run`, Warp tab dispatch, or any other path) for a xBRIEF that has not passed `task xbrief:preflight` (which wraps `scripts/preflight_implementation.py`) -- the gate is the only authorization signal; affirmative continuation phrases and workflow-shape vocabulary are NOT (#810).
219
+ - ⊗ Allocate concurrent workers unless candidates are swarm-ready `kind=story` xBRIEFs with non-empty executable `plan.items` and `task swarm:readiness` exits 0.
220
220
  - ⊗ Use manual file-overlap reasoning as the only safety check; use the readiness report first, then explain any additional human judgment.
221
221
 
222
222
  ### Step 2: Surface Blockers
223
223
 
224
- - ! Identify blocked vBRIEFs (status `blocked`) and their blocking reasons (check `narrative` fields)
225
- - ! Identify vBRIEFs with incomplete acceptance criteria (no `plan.items` or empty items array)
226
- - ! Identify epic/phase scope vBRIEFs from the readiness report and route them to decomposition
227
- - ! Identify dependency conflicts between candidate vBRIEFs (e.g. story A depends on story B via `planRef` or `edges`, but B is assigned to a different agent or is incomplete)
228
- - ! Flag any candidate vBRIEFs whose prerequisites are unmet
224
+ - ! Identify blocked xBRIEFs (status `blocked`) and their blocking reasons (check `narrative` fields)
225
+ - ! Identify xBRIEFs with incomplete acceptance criteria (no `plan.items` or empty items array)
226
+ - ! Identify epic/phase scope xBRIEFs from the readiness report and route them to decomposition
227
+ - ! 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)
228
+ - ! Flag any candidate xBRIEFs whose prerequisites are unmet
229
229
 
230
230
  ### Step 3: Plan Allocation
231
231
 
232
- ! The monitor allocates one or more vBRIEFs to each agent based on scope, complexity, and dependencies. There is no fixed per-agent limit.
232
+ ! The monitor allocates one or more xBRIEFs to each agent based on scope, complexity, and dependencies. There is no fixed per-agent limit.
233
233
 
234
- - ! **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 vBRIEFs together and record the batching rationale
234
+ - ! **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
235
235
  - ! **Large/complex stories** get dedicated agents — a story with broad file scope or high acceptance criteria count should not share an agent
236
- - ! **Dependency-aware grouping** — vBRIEFs 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
236
+ - ! **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
237
237
  - ! The monitor decides allocation dynamically — no hardcoded 1:1 rule
238
- - ! **WIP cap awareness (#1124 / D4 of #1119)** — the cohort + any bridge-promoted candidates (Step 0.5) MUST fit within `plan.policy.wipCap` (default 10 per umbrella #1119 Current Shape v3). When `pending/ + active/` count is at-or-above the cap, `task scope:promote` refuses with an error message naming `task scope:demote <existing>` and `task scope:demote --batch --older-than-days 30` as the relief valves. The monitor MUST drain the WIP set via `task scope:demote` (D1 / #1121) before promoting more candidates, OR open a per-promote `task scope:promote <file> --force` (audit-logged as `wip_cap_override` in `vbrief/.eval/scope-lifecycle.jsonl`) for the genuinely time-critical case. `task triage:summary` (D2 / #1122) surfaces the cap as `WIP X/Y` with a warning glyph when at-or-above cap.
238
+ - ! **WIP cap awareness (#1124 / D4 of #1119)** — the cohort + any bridge-promoted candidates (Step 0.5) MUST fit within `plan.policy.wipCap` (default 10 per umbrella #1119 Current Shape v3). When `pending/ + active/` count is at-or-above the cap, `task scope:promote` refuses with an error message naming `task scope:demote <existing>` and `task scope:demote --batch --older-than-days 30` as the relief valves. The monitor MUST drain the WIP set via `task scope:demote` (D1 / #1121) before promoting more candidates, OR open a per-promote `task scope:promote <file> --force` (audit-logged as `wip_cap_override` in `xbrief/.eval/scope-lifecycle.jsonl`) for the genuinely time-critical case. `task triage:summary` (D2 / #1122) surfaces the cap as `WIP X/Y` with a warning glyph when at-or-above cap.
239
239
 
240
240
  ### Step 4: Present Analysis
241
241
 
242
242
  ! Present a summary to the user containing:
243
243
 
244
- - **Candidate vBRIEFs**: story-level vBRIEFs eligible for assignment (with titles, statuses, and origin references)
244
+ - **Candidate xBRIEFs**: story-level xBRIEFs eligible for assignment (with titles, statuses, and origin references)
245
245
  - **Readiness report**: ready stories, blocked stories, decomposition-needed epics/phases, dependency waves, conflict groups, file overlap matrix, and missing fields from `task swarm:readiness`.
246
- - **Preflight rejections (#810)**: any vBRIEFs that failed `task vbrief:preflight` (wraps `scripts/preflight_implementation.py`) in Step 1 -- include the file path AND the helper's exit message verbatim so the user can route the appropriate `task vbrief:activate <path>` move. These vBRIEFs MUST NOT be allocated until they pass the preflight on a re-run.
247
- - **Blockers found**: blocked vBRIEFs, unresolved dependencies, items requiring design decisions
246
+ - **Preflight rejections (#810)**: any xBRIEFs that failed `task xbrief:preflight` (wraps `scripts/preflight_implementation.py`) in Step 1 -- include the file path AND the helper's exit message verbatim so the user can route the appropriate `task xbrief:activate <path>` move. These xBRIEFs MUST NOT be allocated until they pass the preflight on a re-run.
247
+ - **Blockers found**: blocked xBRIEFs, unresolved dependencies, items requiring design decisions
248
248
  - **Decomposition needed**: epic/phase scopes that must go through `skills/deft-directive-decompose/SKILL.md` before swarm allocation
249
- - **Incomplete vBRIEFs**: stories with missing or empty acceptance criteria
250
- - **Allocation plan**: which agent gets which vBRIEF(s), with reasoning for batching decisions; multi-story batching is allowed only after explicit operator approval or approval of this allocation plan
249
+ - **Incomplete xBRIEFs**: stories with missing or empty acceptance criteria
250
+ - **Allocation plan**: which agent gets which xBRIEF(s), with reasoning for batching decisions; multi-story batching is allowed only after explicit operator approval or approval of this allocation plan
251
251
  - **Tentative version bump**: current version (from CHANGELOG.md or latest git tag) and proposed next version (patch/minor/major) based on the scope and nature of candidate items — this is advisory and will be confirmed before merge cascade
252
252
 
253
253
  ### Step 5: Get User Approval
@@ -262,17 +262,17 @@ Cross-references:
262
262
 
263
263
  ### Step 1: Confirm Candidates
264
264
 
265
- - ! Use the allocation plan and vBRIEF analysis from Phase 0 as the starting point
266
- - ! Re-read `vbrief/active/` only if Phase 0 was skipped (user override) or context was lost
267
- - ! For each candidate vBRIEF, verify its `plan.status` is `running` (not `blocked` or `completed`)
268
- - ! Exclude vBRIEFs that are blocked, have unresolved dependencies, or require design decisions
265
+ - ! Use the allocation plan and xBRIEF analysis from Phase 0 as the starting point
266
+ - ! Re-read `xbrief/active/` only if Phase 0 was skipped (user override) or context was lost
267
+ - ! For each candidate xBRIEF, verify its `plan.status` is `running` (not `blocked` or `completed`)
268
+ - ! Exclude xBRIEFs that are blocked, have unresolved dependencies, or require design decisions
269
269
 
270
270
  ### Step 2: File-Overlap Audit
271
271
 
272
- ! Before assigning tasks to agents, start from the `task swarm:readiness` file-overlap matrix and conflict groups, then list every file each vBRIEF's acceptance criteria are expected to touch.
272
+ ! Before assigning tasks to agents, start from the `task swarm:readiness` file-overlap matrix and conflict groups, then list every file each xBRIEF's acceptance criteria are expected to touch.
273
273
 
274
274
  - ! Verify ZERO file overlap between agents — no two agents may modify the same file
275
- - ! Check **transitive** file touches, not just primary scope — trace each vBRIEF's acceptance criteria to specific files. A task may require changes to files outside its obvious scope (e.g., an enforcement task adding an anti-pattern to a skill file owned by another agent).
275
+ - ! Check **transitive** file touches, not just primary scope — trace each xBRIEF's acceptance criteria to specific files. A task may require changes to files outside its obvious scope (e.g., an enforcement task adding an anti-pattern to a skill file owned by another agent).
276
276
  - ! Shared files (CHANGELOG.md) are exceptions — each agent adds entries but does not edit existing content
277
277
  - ! If overlap exists, reassign tasks until overlap is eliminated
278
278
 
@@ -281,7 +281,7 @@ Cross-references:
281
281
 
282
282
  ### Step 3: Present Assignment
283
283
 
284
- - ! Show the user: agent number, branch name, assigned vBRIEF(s) (with origin issue numbers), and files each agent will touch
284
+ - ! Show the user: agent number, branch name, assigned xBRIEF(s) (with origin issue numbers), and files each agent will touch
285
285
  - ~ Wait for user approval unless the user explicitly said to proceed autonomously
286
286
 
287
287
  ## Phase 2 — Setup
@@ -323,7 +323,7 @@ git worktree add <path> -b <branch-name> <configured-base-branch>
323
323
  ! Before dispatching ANY worker prompt -- swarm cohort OR solo -- the dispatcher MUST populate a `## Allocation context` section (the frozen schema defined in `templates/agent-prompt-preamble.md`, Story A of #1378) in every launched agent's dispatch envelope. Populate all five fields in order: `dispatch_kind` (`solo` | `swarm-cohort`), `allocation_plan_id`, `batching_rationale`, `cohort_vbriefs`, and `operator_approval_evidence`.
324
324
 
325
325
  - ! For a **swarm cohort**, set `dispatch_kind: swarm-cohort` with a non-null `allocation_plan_id` (the Phase 0 allocation-plan snapshot path or the monitor session id) AND a non-null `batching_rationale` (the one-line rationale from the Phase 0 Step 4 allocation plan), and list the full cohort in `cohort_vbriefs`. This is the structured consent token the worker's build-skill Step 0 recognizes mechanically (#1378 Story B), so the worker processes its cohort without re-prompting the parent for batching approval mid-cohort.
326
- - ! For a **solo dispatch**, set `dispatch_kind: solo` and list the single assigned vBRIEF in `cohort_vbriefs`; `allocation_plan_id` and `batching_rationale` MAY be null. Populating the section even for solo dispatches keeps the recognition surface uniform across every launch path.
326
+ - ! For a **solo dispatch**, set `dispatch_kind: solo` and list the single assigned xBRIEF in `cohort_vbriefs`; `allocation_plan_id` and `batching_rationale` MAY be null. Populating the section even for solo dispatches keeps the recognition surface uniform across every launch path.
327
327
 
328
328
  ⊗ Dispatch a worker prompt (cohort or solo) without a populated `## Allocation context` section -- an absent section forces the worker back onto the #1371 prose carve-out fallback and forfeits the deterministic consent-token recognition the structured section enables (#1378).
329
329
 
@@ -408,7 +408,7 @@ Cross-references: `scripts/platform_capabilities.py` (#1557a), `scripts/github_a
408
408
 
409
409
  1. **Dispatch provider** — the runtime primitive or adapter that launches the child worker (e.g. `spawn_subagent`, `start_agent`, Cursor Composer/task agents, cloud agents, or a future adapter).
410
410
  2. **Worker role** — what the child is permitted to do: leaf implementation, orchestrator/strategist, review-cycle monitor, conflict-resolution rebase, merge, or release gate. Role boundaries are load-bearing regardless of which dispatch provider is active.
411
- 3. **Model or agent selection** — the operator or harness policy that maps role plus vBRIEF attributes to a concrete agent/model. deft stays model-agnostic at dispatch time; the harness or provider backend resolves the concrete model.
411
+ 3. **Model or agent selection** — the operator or harness policy that maps role plus xBRIEF attributes to a concrete agent/model. deft stays model-agnostic at dispatch time; the harness or provider backend resolves the concrete model.
412
412
 
413
413
  ! **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.
414
414
 
@@ -416,7 +416,7 @@ Cross-references: `scripts/platform_capabilities.py` (#1557a), `scripts/github_a
416
416
 
417
417
  ~ **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.
418
418
 
419
- ! **Role boundaries for cheaper leaf agents:** Cheaper, high-context leaf agents are appropriate for **leaf implementation** work in isolated worktrees when vBRIEF scope is tight and gates (`task check`, Greptile review cycle) hold. The following roles MUST remain on strong, review-capable agents regardless of backend availability:
419
+ ! **Role boundaries for cheaper leaf agents:** Cheaper, high-context leaf agents are appropriate for **leaf implementation** work in isolated worktrees when xBRIEF scope is tight and gates (`task check`, Greptile review cycle) hold. The following roles MUST remain on strong, review-capable agents regardless of backend availability:
420
420
 
421
421
  - orchestration and cohort monitoring (the monitor / strategist conversation)
422
422
  - review-cycle decisions (fix-or-defer judgment, P0/P1 triage)
@@ -434,7 +434,7 @@ Cross-references: `scripts/policy.py` (`KNOWN_SUBAGENT_BACKEND_IDS`, `SWARM_WORK
434
434
 
435
435
  ! **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).
436
436
 
437
- ! **Worker-owns-lifecycle (Gap C):** Every implementation-worker dispatch prompt MUST declare the unit-of-work boundary: `stop-at: pr-open` OR `drive-to: merge-ready` (default for story vBRIEF work). Workers scoped `drive-to: merge-ready` own pre-PR, push, PR open, Greptile review-cycle poll/fix, and the #1259 Step 6 fail-closed exit as ONE dispatch — they spawn their own review poller per `skills/deft-directive-review-cycle/SKILL.md` monitoring tiers. The monitor MUST NOT plan a separate post-PR review leaf for a worker already scoped merge-ready.
437
+ ! **Worker-owns-lifecycle (Gap C):** Every implementation-worker dispatch prompt MUST declare the unit-of-work boundary: `stop-at: pr-open` OR `drive-to: merge-ready` (default for story xBRIEF work). Workers scoped `drive-to: merge-ready` own pre-PR, push, PR open, Greptile review-cycle poll/fix, and the #1259 Step 6 fail-closed exit as ONE dispatch — they spawn their own review poller per `skills/deft-directive-review-cycle/SKILL.md` monitoring tiers. The monitor MUST NOT plan a separate post-PR review leaf for a worker already scoped merge-ready.
438
438
 
439
439
  ! **Background / independent dispatch (Gap D):** Dispatch implementation, fix, and review-cycle workers independently / in the background when the platform supports it. On Cursor, use the Task tool background path (`run_in_background: true`) so the monitor conversation stays interactive. Foreground dispatch is for short tasks (<~3 min) only.
440
440
 
@@ -499,7 +499,7 @@ Agents execute on remote VMs without local MCP servers, codebase indexing, or Wa
499
499
  ### Step 2e: Cursor Launch (Task tool available) — #1877
500
500
 
501
501
  ! When the platform descriptor is `cursor-composer` or `cursor-cloud-agent` (Cursor `Task` tool detected, no `start_agent`, no `WARP_*`, no `spawn_subagent`), dispatch each worker via the Cursor `Task` tool with:
502
- 1. The canonical `templates/agent-prompt-preamble.md` content as the preamble (AGENTS.md read mandate, #810 vBRIEF gate, #798 PowerShell UTF-8, pre-PR + review-cycle mandates).
502
+ 1. The canonical `templates/agent-prompt-preamble.md` content as the preamble (AGENTS.md read mandate, #810 xBRIEF gate, #798 PowerShell UTF-8, pre-PR + review-cycle mandates).
503
503
  2. The standard worktree prompt (STEP 1-6 from the Prompt Template below).
504
504
  3. The worktree path set to the agent's isolated git worktree.
505
505
  4. ! **`run_in_background: true`** for any worker or poller whose loop runs longer than a short task (~3 min) — implementation, fix, and review-cycle workers — so the monitor conversation pane stays interactive (#1880 Gap D). The parent is notified on completion.
@@ -539,7 +539,7 @@ uv --project . run python scripts/subagent_monitor.py \
539
539
 
540
540
  Track each agent through these stages:
541
541
 
542
- 1. **Reading** — agent is loading AGENTS.md, vBRIEF files, project files (no file changes yet)
542
+ 1. **Reading** — agent is loading AGENTS.md, xBRIEF files, project files (no file changes yet)
543
543
  2. **Implementing** — working tree shows modified files
544
544
  3. **Validating** — agent running `task check`
545
545
  4. **Committed** — new commit(s) in `git log`
@@ -588,14 +588,14 @@ For each agent's PR:
588
588
  3. ! Verify no P0 or P1 issues remain (P2 are non-blocking style suggestions)
589
589
  4. ! **Worker-owns-lifecycle fallback (#1880):** Prefer workers scoped `drive-to: merge-ready` so this step is rare. When a worker exits at PR-open without reaching merge-ready, the monitor MAY run `skills/deft-directive-review-cycle/SKILL.md` itself or dispatch ONE review-cycle owner — but MUST NOT split review polling and fix batches across separate leaf agents for the same PR (#727 + #1880 Gap C).
590
590
 
591
- ### Complete vBRIEFs
591
+ ### Complete xBRIEFs
592
592
 
593
- ! The cohort's story vBRIEFs are completed by the deterministic **cohort completion sweep** in Phase 6 (`task swarm:complete-cohort`, Phase 6 Step 1.5 below), which runs AFTER the merge cascade. Do NOT move story vBRIEFs out of `vbrief/active/` before their PRs merge — a pre-merge move creates premature state if the merge cascade fails. This section is where the monitor records, per story, what the post-merge sweep will finalize:
593
+ ! The cohort's story xBRIEFs are completed by the deterministic **cohort completion sweep** in Phase 6 (`task swarm:complete-cohort`, Phase 6 Step 1.5 below), which runs AFTER the merge cascade. Do NOT move story xBRIEFs out of `xbrief/active/` before their PRs merge — a pre-merge move creates premature state if the merge cascade fails. This section is where the monitor records, per story, what the post-merge sweep will finalize:
594
594
 
595
- 1. ! For each story vBRIEF an agent's PR fully resolves, note that it is ready to complete (`vbrief/active/` -> `vbrief/completed/`, status `completed`). The underlying primitive is `task scope:complete <file>`; the Phase 6 sweep wraps it across the whole cohort so nothing is missed on the headless / multi-worker path.
596
- 2. ! If a story carries a `planRef` to a parent epic, the sweep also completes that epic once ALL its children are settled — you do NOT reconcile epic parents by hand, and you do NOT manually repair parent/child references (the lifecycle helper keeps `task vbrief:validate` green via the #1485 / #1487 reference maintenance).
595
+ 1. ! For each story xBRIEF an agent's PR fully resolves, note that it is ready to complete (`xbrief/active/` -> `xbrief/completed/`, status `completed`). The underlying primitive is `task scope:complete <file>`; the Phase 6 sweep wraps it across the whole cohort so nothing is missed on the headless / multi-worker path.
596
+ 2. ! If a story carries a `planRef` to a parent epic, the sweep also completes that epic once ALL its children are settled — you do NOT reconcile epic parents by hand, and you do NOT manually repair parent/child references (the lifecycle helper keeps `task xbrief:validate` green via the #1485 / #1487 reference maintenance).
597
597
 
598
- ⚠️ Both the vBRIEF lifecycle moves AND origin/issue closure happen in Phase 6 (after merge), not here — completing vBRIEFs or closing issues before merge creates premature state if the merge cascade fails.
598
+ ⚠️ Both the xBRIEF lifecycle moves AND origin/issue closure happen in Phase 6 (after merge), not here — completing xBRIEFs or closing issues before merge creates premature state if the merge cascade fails.
599
599
 
600
600
  ### Exit Condition
601
601
 
@@ -605,7 +605,7 @@ All PRs meet ALL of:
605
605
  - `task check` passed (or equivalent validation completed)
606
606
  - CHANGELOG entries present under `[Unreleased]`
607
607
 
608
- ! **Mandatory cohort verifier (#1364):** After every poller (Phase 6 review-cycle sub-agent) reports back, the monitor MUST run `task swarm:verify-review-clean -- <pr-numbers...>` (script: `scripts/swarm_verify_review_clean.py`) and confirm exit 0 BEFORE evaluating the rest of the Exit Condition or surfacing the Phase 5 -> 6 gate. The verifier re-uses the Greptile rolling-summary parser from `scripts/pr_merge_readiness.py` so the per-PR merge gate and the cohort gate stay in lockstep (a parser fix lands in both surfaces at once). Exit codes: 0 (cohort CLEAN -- all PRs simultaneously have SHA match + confidence > 3 + zero P0/P1 + not errored on current HEAD); 1 (one or more PRs unclean with per-PR diagnostics -- re-dispatch the poller for the unclean PR or address findings, then re-run the verifier); 2 (config error -- empty cohort, malformed vBRIEF glob, gh missing). The verifier is the structural answer to the #1166 swarm execution recurrence where multiple pollers exited with `clean_gate_holdout=confidence` (confidence == 3) and the monitor still raised the Phase 5 -> 6 gate because the trigger keyed on "all pollers have reported back" rather than "every PR in the cohort is objectively CLEAN".
608
+ ! **Mandatory cohort verifier (#1364):** After every poller (Phase 6 review-cycle sub-agent) reports back, the monitor MUST run `task swarm:verify-review-clean -- <pr-numbers...>` (script: `scripts/swarm_verify_review_clean.py`) and confirm exit 0 BEFORE evaluating the rest of the Exit Condition or surfacing the Phase 5 -> 6 gate. The verifier re-uses the Greptile rolling-summary parser from `scripts/pr_merge_readiness.py` so the per-PR merge gate and the cohort gate stay in lockstep (a parser fix lands in both surfaces at once). Exit codes: 0 (cohort CLEAN -- all PRs simultaneously have SHA match + confidence > 3 + zero P0/P1 + not errored on current HEAD); 1 (one or more PRs unclean with per-PR diagnostics -- re-dispatch the poller for the unclean PR or address findings, then re-run the verifier); 2 (config error -- empty cohort, malformed xBRIEF glob, gh missing). The verifier is the structural answer to the #1166 swarm execution recurrence where multiple pollers exited with `clean_gate_holdout=confidence` (confidence == 3) and the monitor still raised the Phase 5 -> 6 gate because the trigger keyed on "all pollers have reported back" rather than "every PR in the cohort is objectively CLEAN".
609
609
 
610
610
  ! **Resilient long-running monitor (#1368):** When a Phase 5 monitor needs to wait on an in-flight PR for an extended window (cascade rebase + re-review, late Greptile pass, CI sweep), use `scripts/monitor_pr.py <N> --repo <owner>/<repo>` as the canonical wait-until-ready helper. The script loops `scripts/pr_merge_readiness.py` with adaptive cadence (~1m for the first 3 polls, ~3m next, ~5m thereafter), routes subprocess capture through `_safe_subprocess.run_text` (#1366), and tolerates layered fallback responses without going blind on a transient gh failure. Exit codes: 0 (PR reached primary/fallback1 CLEAN), 1 (poll cap reached -- escalate to operator), 2 (config error -- gh missing / invalid args), 3 (PR merged or closed out from under the monitor before reaching CLEAN). The helper writes one terse status line per poll to stderr so the orchestrator transcript shows progress; the final verdict (JSON when `--json` is passed) lands on stdout.
611
611
 
@@ -756,50 +756,50 @@ This is defense in depth -- run it even when the pre-merge inspection above pass
756
756
 
757
757
  ### Step 1.5: Cohort Completion Sweep (#1487)
758
758
 
759
- ! **REQUIRED.** Once the cohort's PRs are merged (Step 1 complete), the monitor MUST run the deterministic cohort completion sweep so the finished swarm leaves NO stranded vBRIEFs. This step closes the gap where a completed cohort left its story vBRIEFs in `vbrief/active/` and their decompose-created epic parents in `vbrief/pending/` -- nothing in the swarm flow swept them to `completed/` (observed in the 2026-06-03 swarm: after the cohort's PRs merged, the child story vBRIEFs stayed in `active/` and their epic parents stayed in `pending/`).
759
+ ! **REQUIRED.** Once the cohort's PRs are merged (Step 1 complete), the monitor MUST run the deterministic cohort completion sweep so the finished swarm leaves NO stranded xBRIEFs. This step closes the gap where a completed cohort left its story xBRIEFs in `xbrief/active/` and their decompose-created epic parents in `xbrief/pending/` -- nothing in the swarm flow swept them to `completed/` (observed in the 2026-06-03 swarm: after the cohort's PRs merged, the child story xBRIEFs stayed in `active/` and their epic parents stayed in `pending/`).
760
760
 
761
761
  ```pwsh path=null start=null
762
762
  # Sweep the whole cohort by glob (typical close-out)...
763
- task swarm:complete-cohort -- --cohort 'vbrief/active/*.vbrief.json'
764
- # ...or name the cohort's story vBRIEFs explicitly:
765
- task swarm:complete-cohort -- vbrief/active/<story-a>.vbrief.json vbrief/active/<story-b>.vbrief.json
763
+ task swarm:complete-cohort -- --cohort 'xbrief/active/*.xbrief.json'
764
+ # ...or name the cohort's story xBRIEFs explicitly:
765
+ task swarm:complete-cohort -- xbrief/active/<story-a>.xbrief.json xbrief/active/<story-b>.xbrief.json
766
766
  ```
767
767
 
768
768
  What the sweep does (script: `scripts/swarm_complete_cohort.py`):
769
769
 
770
- 1. ! **Stage 1 -- stories:** every cohort story vBRIEF still in `vbrief/active/` is completed (`active/` -> `completed/`, status `completed`). A story already terminal (`completed/` / `cancelled/`) is an idempotent no-op, so the sweep is safe to re-run.
771
- 2. ! **Stage 2 -- epic parents:** each decompose-created epic parent is completed once ALL of its `x-vbrief/plan` children are settled (in `completed/` or `cancelled/`). A parent in `pending/` is bridged `activate` -> `complete`; a parent in `active/` is completed directly. The sweep iterates to a fixpoint, so nested decomposition (phase -> epic -> story) collapses bottom-up. A parent with even one still-active sibling outside the cohort is left untouched.
772
- 3. ! **D4 stays green automatically:** every move routes through `scripts/scope_lifecycle.py`, which keeps the decomposed parent<->child references in sync on BOTH directions -- child moves update the parent's forward `x-vbrief/plan` reference (#1485) and parent moves update each child's `planRef` back-pointer (#1487). Do NOT hand-edit references to "fix" linkage; the helper already does it.
773
- 4. ! After the sweep, the monitor MUST run `task vbrief:validate` and confirm it exits 0 (no D4 regressions). Exit codes for the sweep itself: 0 (sweep clean), 1 (one or more transitions failed -- per-item diagnostics printed), 2 (config error -- empty cohort or missing `vbrief/`).
770
+ 1. ! **Stage 1 -- stories:** every cohort story xBRIEF still in `xbrief/active/` is completed (`active/` -> `completed/`, status `completed`). A story already terminal (`completed/` / `cancelled/`) is an idempotent no-op, so the sweep is safe to re-run.
771
+ 2. ! **Stage 2 -- epic parents:** each decompose-created epic parent is completed once ALL of its `x-xbrief/plan` children are settled (in `completed/` or `cancelled/`). A parent in `pending/` is bridged `activate` -> `complete`; a parent in `active/` is completed directly. The sweep iterates to a fixpoint, so nested decomposition (phase -> epic -> story) collapses bottom-up. A parent with even one still-active sibling outside the cohort is left untouched.
772
+ 3. ! **D4 stays green automatically:** every move routes through `scripts/scope_lifecycle.py`, which keeps the decomposed parent<->child references in sync on BOTH directions -- child moves update the parent's forward `x-xbrief/plan` reference (#1485) and parent moves update each child's `planRef` back-pointer (#1487). Do NOT hand-edit references to "fix" linkage; the helper already does it.
773
+ 4. ! After the sweep, the monitor MUST run `task xbrief:validate` and confirm it exits 0 (no D4 regressions). Exit codes for the sweep itself: 0 (sweep clean), 1 (one or more transitions failed -- per-item diagnostics printed), 2 (config error -- empty cohort or missing `xbrief/`).
774
774
 
775
- ! **Interactive path:** the monitor runs `task swarm:complete-cohort` by hand (or `--dry-run` first to preview the planned transitions) once the merge cascade finishes, then runs `task vbrief:validate`.
775
+ ! **Interactive path:** the monitor runs `task swarm:complete-cohort` by hand (or `--dry-run` first to preview the planned transitions) once the merge cascade finishes, then runs `task xbrief:validate`.
776
776
 
777
- ! **Headless / multi-worker path:** the cohort sweep is NOT optional here -- it is the structural fix for the #1487 recurrence where the multi-worker close-out never executed the per-cohort completion. The launching monitor (or the close-out automation that follows `task pr:wait-mergeable-and-merge`, #1369) MUST invoke `task swarm:complete-cohort -- --cohort '<cohort-glob>'` after the last cohort PR merges and MUST gate on its exit 0 plus a green `task vbrief:validate` before declaring the swarm closed. The `--json` flag emits a structured verdict for a parent monitor agent to consume.
777
+ ! **Headless / multi-worker path:** the cohort sweep is NOT optional here -- it is the structural fix for the #1487 recurrence where the multi-worker close-out never executed the per-cohort completion. The launching monitor (or the close-out automation that follows `task pr:wait-mergeable-and-merge`, #1369) MUST invoke `task swarm:complete-cohort -- --cohort '<cohort-glob>'` after the last cohort PR merges and MUST gate on its exit 0 plus a green `task xbrief:validate` before declaring the swarm closed. The `--json` flag emits a structured verdict for a parent monitor agent to consume.
778
778
 
779
- ⊗ Declare a swarm closed while any cohort story vBRIEF remains in `vbrief/active/` or any fully-childless decompose-created epic parent remains in `vbrief/pending/` -- run `task swarm:complete-cohort` and confirm `task vbrief:validate` is green first (#1487).
779
+ ⊗ Declare a swarm closed while any cohort story xBRIEF remains in `xbrief/active/` or any fully-childless decompose-created epic parent remains in `xbrief/pending/` -- run `task swarm:complete-cohort` and confirm `task xbrief:validate` is green first (#1487).
780
780
 
781
781
  ### Step 2: Close Issues and Update Origins
782
782
 
783
783
  - ! Close resolved issues with a comment referencing the PR
784
784
  - ~ Issues with "Closes #N" in PR body auto-close on squash merge
785
785
  - ! After each squash merge, verify issues actually closed: `gh issue view <N> --json state --jq .state`. If not closed, close manually with a comment referencing the merged PR. Squash merge + closing keywords can silently fail to close issues (#167).
786
- - ! For each completed vBRIEF: read its `references` array and update each origin:
786
+ - ! For each completed xBRIEF: read its `references` array and update each origin:
787
787
  - For `github-issue` references: verify the issue is closed (auto-close from PR body or Phase 6 Step 2 above); if not, close with `gh issue close <N> --comment "Completed in #<PR>"`
788
788
  - For other reference types: document the completion as appropriate
789
789
 
790
790
  ### Step 2b: Commit and Push the Post-Merge Lifecycle Record (#1358)
791
791
 
792
- ! **REQUIRED.** After all cohort PRs have merged (Step 1) and the Cohort Completion Sweep (Step 1.5) has moved every finished story vBRIEF `vbrief/active/` -> `vbrief/completed/` (and bridged its epic parents), the monitor MUST commit and push those lifecycle moves so they become the **authoritative post-swarm lifecycle record** on the base branch. Without this step the moves sit uncommitted in the merger's worktree until an operator hand-runs `task scope:complete` and a `chore(vbrief)` commit by hand -- the exact manual closeout performed after the 2026-06-16 swarm (the #1358 recurrence this step closes).
792
+ ! **REQUIRED.** After all cohort PRs have merged (Step 1) and the Cohort Completion Sweep (Step 1.5) has moved every finished story xBRIEF `xbrief/active/` -> `xbrief/completed/` (and bridged its epic parents), the monitor MUST commit and push those lifecycle moves so they become the **authoritative post-swarm lifecycle record** on the base branch. Without this step the moves sit uncommitted in the merger's worktree until an operator hand-runs `task scope:complete` and a `chore(xbrief)` commit by hand -- the exact manual closeout performed after the 2026-06-16 swarm (the #1358 recurrence this step closes).
793
793
 
794
794
  The monitor MUST, from its OWN worktree and on the configured base branch:
795
795
 
796
796
  0. ! **Fast-forward the local base branch FIRST:** `git fetch origin && git merge --ff-only origin/<configured-base-branch>` (equivalently `git pull --ff-only origin <configured-base-branch>`). The merge cascade (Step 1) advanced the REMOTE base branch by N squash-merge commits, but the local base branch in this worktree has not yet been pulled (Step 3's canonical pull runs AFTER this step). Without this fast-forward the commit below is built on a stale base and the push in step 4 is rejected as non-fast-forward, stranding the agent. Doing the `--ff-only` sync first makes the subsequent commit + push fast-forward by construction; a non-fast-forward `--ff-only` failure here means an unexpected divergence -- stop and reconcile rather than force-push.
797
- 1. ! Confirm the lifecycle moves are present (the Step 1.5 sweep already ran `task scope:complete <file>` per story, `active/` -> `completed/`). If the sweep was skipped, run `task swarm:complete-cohort` now -- do NOT hand-move vBRIEF files.
798
- 2. ! Stage ALL lifecycle moves: `git add -A vbrief/` -- this captures both the `active/` deletions and the `completed/` additions, plus any parent/child `planRef` / `x-vbrief/plan` reference edits `scripts/scope_lifecycle.py` wrote during the sweep.
799
- 3. ! Commit them in a SINGLE commit on the base branch: `git commit -m "chore(vbrief): complete <slugs> post-merge"`, where `<slugs>` enumerates the completed story vBRIEF slugs (or the cohort label) so the commit is self-describing.
797
+ 1. ! Confirm the lifecycle moves are present (the Step 1.5 sweep already ran `task scope:complete <file>` per story, `active/` -> `completed/`). If the sweep was skipped, run `task swarm:complete-cohort` now -- do NOT hand-move xBRIEF files.
798
+ 2. ! Stage ALL lifecycle moves: `git add -A xbrief/` -- this captures both the `active/` deletions and the `completed/` additions, plus any parent/child `planRef` / `x-xbrief/plan` reference edits `scripts/scope_lifecycle.py` wrote during the sweep.
799
+ 3. ! Commit them in a SINGLE commit on the base branch: `git commit -m "chore(xbrief): complete <slugs> post-merge"`, where `<slugs>` enumerates the completed story xBRIEF slugs (or the cohort label) so the commit is self-describing.
800
800
  4. ! Push to origin: `git push origin <configured-base-branch>`. Because step 0 fast-forwarded the local base ahead of the commit, this push is a fast-forward and will not be rejected.
801
801
 
802
- ! **Authoritative lifecycle record (#1358):** this commit is what keeps the release ceremony's vBRIEF-lifecycle-sync gate green. The release pipeline's deterministic gate (`scripts/release.py::check_vbrief_lifecycle_sync`) and the release skill's Phase 1 sync gate (`skills/deft-directive-release/SKILL.md` Phase 1 -- `task reconcile:issues -- --apply-lifecycle-fixes`) both refuse to cut a release while a closed-issue vBRIEF still sits outside `vbrief/completed/`. Committing the moves here, at swarm close-out, is the **prevention** so the next release does not have to reconcile drift the swarm itself created. If drift is nevertheless detected later, `task reconcile:issues -- --apply-lifecycle-fixes` (script: `scripts/reconcile_issues.py`) is the recovery path -- but the post-merge commit in this step is what stops the drift from being authored in the first place.
802
+ ! **Authoritative lifecycle record (#1358):** this commit is what keeps the release ceremony's xBRIEF-lifecycle-sync gate green. The release pipeline's deterministic gate (`scripts/release.py::check_vbrief_lifecycle_sync`) and the release skill's Phase 1 sync gate (`skills/deft-directive-release/SKILL.md` Phase 1 -- `task reconcile:issues -- --apply-lifecycle-fixes`) both refuse to cut a release while a closed-issue xBRIEF still sits outside `xbrief/completed/`. Committing the moves here, at swarm close-out, is the **prevention** so the next release does not have to reconcile drift the swarm itself created. If drift is nevertheless detected later, `task reconcile:issues -- --apply-lifecycle-fixes` (script: `scripts/reconcile_issues.py`) is the recovery path -- but the post-merge commit in this step is what stops the drift from being authored in the first place.
803
803
 
804
804
  ⊗ Declare a swarm closed while the cohort's `active/` -> `completed/` lifecycle moves remain uncommitted in the merger's worktree -- an uncommitted lifecycle record is invisible to every other clone and re-surfaces as `check_vbrief_lifecycle_sync` drift at the next release (#1358). The Step 1.5 sweep moves the files; this step makes the move durable.
805
805
 
@@ -893,14 +893,14 @@ This is a git worktree. Do NOT just read files and stop — you must implement a
893
893
  run task check, commit, push, create a PR, and run the review cycle.
894
894
  DO NOT STOP until all steps are complete.
895
895
 
896
- STEP 1 — Read directives: Read AGENTS.md, vbrief/vbrief.md, and the assigned vBRIEF(s) from vbrief/active/.
896
+ STEP 1 — Read directives: Read AGENTS.md, vbrief/vbrief.md, and the assigned xBRIEF(s) from xbrief/active/.
897
897
  Read skills/deft-directive-review-cycle/SKILL.md.
898
898
 
899
- STEP 2 — Implement these N tasks (see assigned vBRIEF(s) for full acceptance criteria):
899
+ STEP 2 — Implement these N tasks (see assigned xBRIEF(s) for full acceptance criteria):
900
900
 
901
- Task A (vBRIEF: [filename], issue #[N]): [one-paragraph description with specific acceptance criteria]
901
+ Task A (xBRIEF: [filename], issue #[N]): [one-paragraph description with specific acceptance criteria]
902
902
 
903
- Task B (vBRIEF: [filename], issue #[N]): [one-paragraph description with specific acceptance criteria]
903
+ Task B (xBRIEF: [filename], issue #[N]): [one-paragraph description with specific acceptance criteria]
904
904
 
905
905
  [...repeat for each task...]
906
906
 
@@ -928,7 +928,7 @@ CONSTRAINTS:
928
928
 
929
929
  - ! First line MUST start with `TASK:` followed by an imperative statement
930
930
  - ! Include `DO NOT STOP until all steps are complete` in the preamble
931
- - ! Each task MUST include its vBRIEF filename and origin issue number
931
+ - ! Each task MUST include its xBRIEF filename and origin issue number
932
932
  - ! CONSTRAINTS section MUST list files the agent must not touch (other agents' scope)
933
933
  - ! Review cycle step MUST reference `skills/deft-directive-review-cycle/SKILL.md` explicitly
934
934
  - ⊗ Start the prompt with context ("You are working in...") — agents treat this as passive setup and may stop after reading
@@ -944,7 +944,7 @@ CONSTRAINTS:
944
944
  - ⊗ Assign overlapping files to multiple agents
945
945
  - ⊗ Merge PRs before Greptile exit condition is met (score > 3, no P0/P1)
946
946
  - ⊗ Assume agents will complete the full workflow — always verify review cycle completion
947
- - ⊗ Launch agents without checking vBRIEF acceptance criteria first
947
+ - ⊗ Launch agents without checking xBRIEF acceptance criteria first
948
948
  - ⊗ Skip the file-overlap audit in Phase 1
949
949
  - ⊗ Use `git reset --hard` or force-push in any worktree (swarm agents only -- monitor may `--force-with-lease` after rebase cascade per Phase 6 Step 1)
950
950
  - ⊗ Present static launch options (A/B/C) instead of detecting capabilities at runtime — always probe for `start_agent` and Warp environment variables before choosing a launch path
@@ -961,10 +961,10 @@ CONSTRAINTS:
961
961
  - ⊗ Run `git add` on a conflict-resolved file without re-reading and verifying structural integrity (no conflict markers, no collapsed lines, no encoding artifacts) -- see Phase 6 Step 1 read-back verification rule (#288)
962
962
  - ⊗ Use shell regex (`sed`, `Select-String -replace`) to resolve `CHANGELOG.md` rebase conflicts -- prefer `task changelog:resolve-unreleased` (#911) for `[Unreleased]` conflicts; fall back to `edit_files` for encoding safety and exact match verification when the helper exits 1 (#288, #911)
963
963
  - ⊗ Resolve a `CHANGELOG.md` `[Unreleased]` conflict by HEAD-take-and-discard -- the rebasing branch's new entry MUST land in the resolved file. Use `task changelog:resolve-unreleased` (#911) for the canonical union-merge or apply the union-merge pattern manually when the helper cannot mechanize the conflict
964
- - ⊗ Hardcode a 1:1 vBRIEF-per-agent allocation rule — the monitor decides allocation dynamically based on scope, complexity, and dependencies
965
- - ⊗ Complete a story without moving its vBRIEF from `active/` to `completed/` and updating its origin references
966
- - ⊗ Declare a swarm closed without running the Phase 6 Step 1.5 cohort completion sweep (`task swarm:complete-cohort`) and confirming `task vbrief:validate` is green -- skipping it leaves the cohort's story vBRIEFs stranded in `active/` and their decompose-created epic parents stranded in `pending/`, the exact #1487 recurrence (the headless / multi-worker close-out is where the sweep was historically missed)
967
- - ⊗ Declare a swarm closed while the cohort's `active/` -> `completed/` lifecycle moves remain uncommitted -- after the Step 1.5 sweep the monitor MUST commit them in a single `chore(vbrief): complete <slugs> post-merge` commit on the base branch and `git push origin <configured-base-branch>` (Phase 6 Step 2b). An uncommitted lifecycle record is invisible to every other clone and re-surfaces as `scripts/release.py::check_vbrief_lifecycle_sync` drift at the next release; the post-merge commit is the prevention, `task reconcile:issues -- --apply-lifecycle-fixes` is only the recovery (#1358)
964
+ - ⊗ Hardcode a 1:1 xBRIEF-per-agent allocation rule — the monitor decides allocation dynamically based on scope, complexity, and dependencies
965
+ - ⊗ Complete a story without moving its xBRIEF from `active/` to `completed/` and updating its origin references
966
+ - ⊗ Declare a swarm closed without running the Phase 6 Step 1.5 cohort completion sweep (`task swarm:complete-cohort`) and confirming `task xbrief:validate` is green -- skipping it leaves the cohort's story xBRIEFs stranded in `active/` and their decompose-created epic parents stranded in `pending/`, the exact #1487 recurrence (the headless / multi-worker close-out is where the sweep was historically missed)
967
+ - ⊗ Declare a swarm closed while the cohort's `active/` -> `completed/` lifecycle moves remain uncommitted -- after the Step 1.5 sweep the monitor MUST commit them in a single `chore(xbrief): complete <slugs> post-merge` commit on the base branch and `git push origin <configured-base-branch>` (Phase 6 Step 2b). An uncommitted lifecycle record is invisible to every other clone and re-surfaces as `scripts/release.py::check_vbrief_lifecycle_sync` drift at the next release; the post-merge commit is the prevention, `task reconcile:issues -- --apply-lifecycle-fixes` is only the recovery (#1358)
968
968
  - ⊗ Hardcode `master` as the base branch -- always use the configured base branch from Phase 0
969
969
  - ⊗ Treat a Greptile GitHub CheckRun of COMPLETED/NEUTRAL as equivalent to a passing review without inspecting the comment body. NEUTRAL is the result both when Greptile intentionally has nothing to say AND when it errored out mid-review; the two cases require opposite responses (#526)
970
970
  - ⊗ Loop the monitor indefinitely on the Greptile-service-errored state or time out silently at the poll cap -- detect the "Greptile encountered an error" comment body, retry once via `@greptileai review` with a 10-minute cap, and on second error escalate to the user with the three-way choice (wait / empty retrigger commit / documented override) per Phase 6 Step 1 (#526)
@@ -974,8 +974,8 @@ CONSTRAINTS:
974
974
  - ⊗ 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)
975
975
  - ⊗ 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
976
976
  - ⊗ 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)
977
- - ⊗ Skip the Phase 0 Step 0.5 lifecycle bridge (#1025) and let the Step 1 preflight gate reject candidate scope vBRIEFs wholesale. The setup skill deposits scope vBRIEFs in `vbrief/proposed/` and the refinement skill leaves them in `vbrief/pending/`; the swarm Phase 0 Step 1 preflight only accepts `vbrief/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/`)
978
- - ⊗ Auto-promote + activate every candidate in `vbrief/proposed/` or `vbrief/pending/` during the Phase 0 Step 0.5 bridge without explicit user approval (#1025). Proposed-stage vBRIEFs 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`
977
+ - ⊗ 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/`)
978
+ - ⊗ 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`
979
979
  - ⊗ Describe heterogeneous sub-agent routing as Grok Build-only — provider-neutral dispatch separates dispatch provider, worker role, and model or agent selection; Composer-class coding agents, Cursor/cloud agents, and future adapters are first-class backends alongside Grok Build `spawn_subagent` (#1531)
980
980
  - ⊗ Assume parent-shell `gh auth status` proves a worker sandbox can authenticate or reach GitHub — always run `scripts/github_auth_modes.py` from the worker envelope and surface full-access execution, trusted `gh` allowlisting, or injected-token handoff when sandbox auth fails (#1557)
981
981
  - ⊗ Present Cursor sandbox UID 0 or sandbox-root cwd ownership as host-root access — `sandbox_uid_remap` means the sandbox identity is remapped to the host user, not real root (#1557)