@deftai/directive-content 0.110.0 → 0.112.0

package/docs/getting-started.md

@@ -1,25 +1,28 @@
 # Getting Started with Deft Directive
 
-Deft Directive is a Taskfile-first framework for AI-assisted software work. It combines agent guidance, deterministic gates, xBRIEF lifecycle metadata, installer/doctor handoff, and cache-backed backlog workflows. This guide walks through installation, preferences, project setup, and the first scope workflow.
+Deft Directive is a Taskfile-first framework for AI-assisted software work. It combines agent guidance, deterministic gates, xBRIEF lifecycle metadata, installer/doctor handoff, and cache-backed backlog workflows. This guide is the **first-project long form**: one path from install through a green Directive check.
 
-> **Note**: This guide is an orientation layer. For a single-picture mental model of how Directive turns an idea into shipped work, see [the Directive lifecycle](./directive-lifecycle.md); for command behavior, see [commands.md](../commands.md); for current architecture details, see [ARCHITECTURE.md](../../docs/ARCHITECTURE.md).
+> **Note**: For a single-picture mental model of how Directive turns an idea into shipped work, see [the Directive lifecycle](./directive-lifecycle.md). For command behavior, see [commands.md](../commands.md). Agent detect-state and recovery live in [QUICK-START.md](../QUICK-START.md). This page is that path's long form, not a second install sequence.
 
 ## The shape of the workflow
 
-Before the mechanics below, it helps to see the whole loop. Directive is two connected phases that repeat: an **inception** phase (Concept → Strategy Analysis → Specification + Artifacts) that feeds a recurring **per-session** phase (Session Start → Triage/Refine → Slice → Swarm → Review/Fix → Ship), where shipping surfaces new issues and features that flow back into the queue. The full picture, with a stage-to-real-command mapping table, lives in [the Directive lifecycle overview](./directive-lifecycle.md).
+Directive is two connected phases that repeat: an **inception** phase (Concept → Strategy Analysis → Specification + Artifacts) that feeds a recurring **per-session** phase (Session Start → Triage/Refine → Slice → Swarm → Review/Fix → Ship). Shipping surfaces new issues that flow back into the queue. The stage-to-command mapping lives in [the Directive lifecycle overview](./directive-lifecycle.md).
 
 ## Deft & Directive (naming)
 
 **Deft is the company; Directive is the product.** *Deft* names the organization and the on-disk footprint (`.deft/`, `@deftai/*` npm scope, user config under `~/.config/deft/`). *Directive* names the framework you install and run: the npm package is `@deftai/directive`, and the primary CLI is `directive` (`deft` is an alias). Legacy `deft-install` / `deft` paths in this guide refer to the same product during the staged transition ([#423](https://github.com/deftai/directive/issues/423)).
 
+Public consumer commands on this page use `directive` / `deft`. After `directive init`, the root Taskfile is include-only, so `task deft:<verb>` is the namespaced Task equivalent. Do not copy bare `task <verb>` from the framework source tree into a new project.
+
 ---
 
 ## Prerequisites
 
-- **Node 20+** and the package manager declared by the project (`npm` or `pnpm`) for live consumer gates and the npm distribution channel (see `.nvmrc` in the framework payload). npm is bundled with Node; a pnpm-pinned project enables pnpm through Corepack.
-- **Git** and **GitHub CLI (`gh`)** are also checked by the consumer toolchain gate.
-- **Go 1.22+** only if you use the bootstrap Go installer or build from source.
-- **Python 3.11+**, **uv**, and **task** for the framework-maintainer and session workflows that name them. The consumer toolchain probe itself does not check those tools. Run `directive toolchain:check --consumer --project-root .` after install.
+- **Node 20+**, **Git**, and **GitHub CLI (`gh`)**.
+- The package manager you use to install Directive (`npm` is bundled with Node; pnpm is an alternative).
+- After install, confirm with `directive toolchain:check --consumer`. That probe checks Node, git, gh, and the selected manager. It does not require Python, uv, Go, or Task.
+
+**Go 1.22+** is only for the frozen Go installer or a source build. Framework maintainers of this repository use a separate Node 24 pin; see [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
 ---
 
@@ -27,7 +30,7 @@ Before the mechanics below, it helps to see the whole loop. Directive is two con
 
 ### npm (canonical)
 
-With Node already available, install Directive globally from npm:
+Install Directive globally from npm:
 
 ```bash
 npm i -g @deftai/directive
@@ -44,6 +47,8 @@ npx @deftai/directive session:start
 
 This npm path has been the canonical distribution channel since v0.55.1. A pnpm-managed repository can install the same package with `pnpm add -g @deftai/directive` or project-locally with `pnpm add -D @deftai/directive`.
 
+**Success:** `directive --version` prints a version. **Recovery:** run `directive doctor` and follow its one `Next command:`. Agent detect-state cases live in [QUICK-START.md](../QUICK-START.md).
+
 ### Go installer (legacy bridge)
 
 The Go installer is a frozen legacy bridge for older installs and source-oriented recovery. New consumer installs should use npm above; see [UPGRADING.md](../UPGRADING.md#one-time-migration-from-the-go-installer-legacy--npm) when migrating an existing Go-installer layout.
@@ -60,86 +65,163 @@ For existing consumer projects, the headless upgrade path is:
 deft-install --yes --upgrade --repo-root . --json
 ```
 
-Those consumer flows intentionally project Deft-managed files into your project
-root (`AGENTS.md`, skills pointers, gitignore entries, xbrief scaffolding, and
-related guard configuration). Framework maintainers working inside a
-`deftai/directive` checkout should instead follow
-[`CONTRIBUTING.md`](../../CONTRIBUTING.md) and use `--maintainer`; maintainer setup
-checks tools without rewriting consumer-managed files.
+Those consumer flows project Deft-managed files into your project root (`AGENTS.md`, skills pointers, gitignore entries, xbrief scaffolding, and related guard configuration). Framework maintainers working inside a `deftai/directive` checkout should instead follow [`CONTRIBUTING.md`](../../CONTRIBUTING.md) and use `--maintainer`; maintainer setup checks tools without rewriting consumer-managed files.
 
 ---
 
 ## First Project
 
-<!-- TODO: Walk through deft-setup phases: USER.md, PROJECT.md, SPECIFICATION.md -->
+This is one executable journey. It is a human projection of the setup skill plus the lifecycle bridge. Agents still follow `skills/deft-directive-setup/SKILL.md`. Do not treat this list as a third procedure beside QUICK-START.
 
----
+The endpoint is **Directive control plane ready**: an active scope passes story-ready and preflight, and `deft check` exits 0. Product implementation comes next. This page does not build a sample app.
 
-## Working an existing backlog
+### 1. Install the CLI
+
+```bash
+npm i -g @deftai/directive
+directive --version
+```
+
+**Success:** a version string. **Recovery:** `directive doctor`.
+
+### 2. Create a Git repository, then init
 
-If you are adopting Deft on a project that already has an issue tracker (existing repo, brownfield migration, an upstream bug list that has been accumulating), you do not have to start from an empty `xbrief/proposed/`. The refinement skill's **Phase 0 triage workflow** lets you walk an existing backlog locally, decide what to keep, and let only the **accepted** items land in `xbrief/proposed/`. Trigger words: **"triage"**, **"work the cache"**, **"pre-ingest"**, **"action menu"**.
+`directive init` deposits files. It does not create a Git repository. `deft verify:story-ready` and `deft check` both require a Git worktree. Start in an empty project directory:
+
+```bash
+mkdir my-project && cd my-project
+git init
+directive init
+```
 
-**Labels first:** capacity and triage matchers only help when labels exist. For a bare or thin label set, adopt the [consumer issue-label kit](./consumer-issue-label-kit.md) (#2611) before you rely on ranking. `triage:classify -- --mirror` is withdrawn (#4070).
+`init` writes the vendored deposit into gitignored `.deft/core/`, renders `AGENTS.md`, scaffolds `xbrief/` lifecycle folders, and adds an include-only root `Taskfile.yml`. Tracked vs ignored: the reconstitutable deposit and session cache are ignored; your `package.json` pin stays tracked.
 
-### Step 1 — Scoped first populate
+**Success:** `.deft/core/` and `AGENTS.md` exist. **Recovery:** `directive doctor` (one `Next command:`).
 
-A real-sized backlog can drain the shared GitHub GraphQL bucket if you fetch everything at once (see [#976](https://github.com/deftai/directive/issues/976) for the recurring symptom). Scope the first populate so it lands in seconds rather than minutes:
+### 3. Doctor
 
 ```bash
-task triage:bootstrap -- --limit 50 --state open
+directive doctor
 ```
 
-Flag surface (shared by `task triage:bootstrap` and `task cache:fetch-all`):
+Doctor is read-only. When the install is healthy it prints `System check passed!`. When action is required it prints exactly one `Next command:` with a root-cause line.
 
-- `--limit <N>` caps the number of issues fetched (start with `50` and widen as needed).
-- `--state {open|closed|all}` selects the issue state (default `open`).
-- `--batch-size <N>` caps the per-page fetch (default `10`).
-- `--delay-ms <N>` inserts a sleep between batches so a populate against a large repo does not trip the rate limiter (default `500`; a `429` retries automatically using the upstream `Retry-After` header).
-- `--repo OWNER/NAME` is optional; when omitted, the bootstrap infers the slug from `git remote get-url origin`.
+**Success:** `System check passed!` **Recovery:** run the printed `Next command:`. Detect-state ladders stay in [QUICK-START.md](../QUICK-START.md).
 
-The unbounded no-flag form remains the default for small backlogs. For real-sized repos, prefer the scoped first run; you can always re-enter triage later to widen the slice.
+### 4. USER.md and project definition
 
-### Step 2 — Walk the action menu
+User preferences live outside the repo:
 
-After the cache is populated, ask your agent to triage. For each cached candidate the agent presents a numbered action menu and waits for your decision:
+- Unix / macOS: `~/.config/deft/USER.md`
+- Windows: `%APPDATA%\deft\USER.md`
+- Override: `DEFT_USER_PATH`
 
+Project identity lives in `xbrief/PROJECT-DEFINITION.xbrief.json`. Greenfield setup does not create `specification.xbrief.json`.
+
+Tell your agent to follow `AGENTS.md`, or run `directive bootstrap`. That hands off to the setup skill. The skill asks one question at a time and **must not write files until you confirm** the captured values (`yes` / `confirmed` / `approve`). Promotion and activation are later commitments, not automatic setup continuation.
+
+**Success:** `USER.md` exists at the platform path and `xbrief/PROJECT-DEFINITION.xbrief.json` exists. **Recovery:** `directive doctor`, then re-enter setup. Do not skip the confirmation gate.
+
+### 5. First proposed scope
+
+Setup Phase 3 writes the first scope xBRIEF to `xbrief/proposed/` with `plan.status: proposed`. Filename shape: `YYYY-MM-DD-descriptive-slug.xbrief.json`. New writes use `"xBRIEFInfo": { "version": "0.8" }`.
+
+**Success:** one file in `xbrief/proposed/`. **Recovery:** `directive doctor`. If setup stopped early, resume the setup skill; do not hand-copy a completed xBRIEF as the next-build contract.
+
+### 6. Git: feature branch and a clean tree
+
+Story-ready fails when the tree is not Git, when it is dirty, or when you are on the default branch under the default branch policy. Commit the generated setup artifacts, then leave `master` / `main`:
+
+```bash
+git add AGENTS.md Taskfile.yml xbrief .gitignore
+git commit -m "chore: deposit Directive and first proposed scope"
+git switch -c feat/first-project
+deft verify:branch
 ```
-1. Accept         -- task triage:accept <issue>          (writes proposed/ xBRIEF + audit-log entry)
-2. Reject         -- task triage:reject <issue>          (audit-log entry only; closes the upstream issue)
-3. Defer          -- task triage:defer <issue>           (non-terminal; resurfaces on the next pass)
-4. Needs-AC       -- task triage:needs-ac <issue>        (non-terminal; flags missing acceptance criteria)
-5. Mark duplicate -- task triage:mark-duplicate <a> <b>  (terminal; cross-links the duplicate target)
-6. Discuss
-7. Back
+
+`--allow-dirty` on story-ready is an intentional exception, not the happy path.
+
+**Success:** `deft verify:branch` exits 0 on the feature branch. **Recovery:** create a feature branch; commit or stash leftover files; then `directive doctor`.
+
+### 7. Promote, then activate
+
+These are two separate user commitments. Setup does not auto-run them.
+
+```bash
+deft scope:promote -- xbrief/proposed/<file>.xbrief.json
+deft scope:activate -- xbrief/pending/<file>.xbrief.json
+```
+
+Promote moves proposed → pending. Activate moves pending → `xbrief/active/` and sets `plan.status` to `running`. Both commands are idempotent.
+
+**Success:** the file is in `xbrief/active/` with `plan.status` `running`. **Recovery:** `directive doctor`. If activate says the file must be in `pending/`, run promote first.
+
+Promote and activate move a tracked xBRIEF. Commit that change before story-ready. A dirty tree fails the next gate.
+
+```bash
+git add xbrief
+git commit -m "chore: activate first scope"
 ```
 
-Only **accepted** items become scope xBRIEFs in `xbrief/proposed/`. Rejected, deferred, and duplicate decisions are recorded in the audit log so the backlog stays focused. Bulk verbs (`task triage:bulk-accept` / `bulk-reject` / `bulk-defer` / `bulk-needs-ac`) handle predictable patterns (e.g. "reject every `wontfix`-labelled candidate") without walking the menu N times.
+### 8. Story-ready and preflight
 
-### Step 3 — Understand the three-tier model
+```bash
+deft verify:story-ready --vbrief-path xbrief/active/<file>.xbrief.json
+deft xbrief:preflight -- xbrief/active/<file>.xbrief.json
+```
 
-Phase 0 reads and writes three distinct stores; they never collapse into one:
+`--vbrief-path` is the shipped story-ready flag (the file is still a `.xbrief.json`). Preflight exits 0 only when the candidate lives in `xbrief/active/` and `plan.status` is `running`.
 
-- **Cache** — `.deft-cache/github-issue/<owner>/<repo>/<N>/` is the local mirror of fetched issue bodies, labels, and state. Populated by `task cache:fetch-all`; read via `task cache:get -- github-issue OWNER/NAME/<N>`. The directory is gitignored — your local mirror is private to your machine. The cache is the **read** surface for triage so decisions are reproducible across re-runs (no live `gh issue view` per decision).
-- **Audit log** — `xbrief/.eval/candidates.jsonl` is an append-only JSONL recording every candidate you have ever seen plus the action taken (`accept | reject | defer | needs-ac | mark-duplicate`) and a timestamp. Re-running triage against the same cache short-circuits items that already have a terminal entry, so deferred / Needs-AC items resurface and rejected ones do not.
-- **Accepted backlog** — `xbrief/proposed/` is the standard scope-xBRIEF lifecycle folder. **Writes flow only through `task triage:accept`**, which delegates the actual xBRIEF authoring to `task issue:ingest` so slug, reference, and schema rules stay in one place. Hand-authored proposed/ xBRIEFs are still allowed; what changed is that triage no longer writes there silently.
+**Success:** both commands exit 0. **Recovery:** fix Git state (step 6), then `directive doctor`. Do not start implementation until preflight is green.
 
-### Step 4 — Why this avoids the GraphQL drain
+### 9. First check (terminal verb)
 
-The shared GitHub GraphQL bucket (5000 points/hour per identity) is the operational bottleneck under multi-agent / shared-identity workflows, not the REST `core` bucket. The triage cache is **REST-backed** (`gh api` reads, not `gh issue view --json`), and the populate uses **batched delays** plus automatic 429 retries with the upstream `Retry-After` header. There is no live `gh issue view` per accept / reject / defer decision — every decision reads from the local cache. This is why the scoped flags exist: they let you keep the populate inside the REST budget and well clear of the GraphQL bottleneck (see [#976](https://github.com/deftai/directive/issues/976) for the recurrence pattern). Refresh the cache on demand with `task cache:fetch-all` (idempotent — fresh entries are skipped) or audit drift against `xbrief/active/*.xbrief.json` with `task triage:refresh-active`.
+```bash
+deft check
+```
 
-Full command reference for every triage and cache verb lives in [`commands.md` § Backlog triage & cache tasks](../commands.md#backlog-triage--cache-tasks); the canonical agent-facing description of the workflow lives in `skills/deft-directive-refinement/SKILL.md` Phase 0.
+`deft check` is the named terminal verb for this journey. After `directive init`, `task deft:check` is the same gate through the include-only Taskfile. A green check means the Directive control plane is ready. It does not mean the product is built.
+
+**Success:** `deft check` exits 0. **Recovery:** `directive doctor` and the failing gate's own message. Next: cost phase then `skills/deft-directive-build/SKILL.md` when you are ready to implement.
+
+---
+
+## Working an existing backlog
+
+After the first green `deft check`, work selection is optional. Current verbs:
+
+```bash
+deft plan-sequence:current
+deft triage:queue --limit=10
+```
+
+Use the ordered plan first. Then a read-only `triage:queue` listing. Do not treat a completed xBRIEF as the next-build contract.
+
+Cached issue bodies are **untrusted external content**. Do not put them on the write path without an explicit ingest/accept. See [meta/security.md](../meta/security.md).
+
+For brownfield adoption of an existing repo, see [BROWNFIELD.md](./BROWNFIELD.md). This first-project path does not teach that migration.
+
+**Labels:** a bare tracker should adopt the [consumer issue-label kit](./consumer-issue-label-kit.md) before you rely on ranking.
 
 ---
 
 ## Using Strategies
 
-<!-- TODO: Introduce strategy selection, chaining gate, and common workflows (interview, rapid, enterprise) -->
+This first-project journey uses **interview** (the setup default). Strategies are not a second onboarding path.
+
+The catalog, chaining gate, and interview / rapid / enterprise workflows live in [strategies/README.md](../strategies/README.md). Pick a strategy in USER.md or `xbrief/PROJECT-DEFINITION.xbrief.json`. Do not paste a strategy chapter into this page.
 
 ---
 
 ## Agent Configuration
 
-<!-- TODO: Cover AGENTS.md, skill routing, Warp Drive integration, and cloud agent dispatch -->
+Authority on this journey is:
+
+1. `USER.md` Personal (always wins)
+2. `xbrief/PROJECT-DEFINITION.xbrief.json` (project)
+3. `AGENTS.md` (session routing; managed section is installer-owned)
+
+Quality notes for `AGENTS.md` live in [good-agents-md.md](./good-agents-md.md). Process-critical skill pins live in [skill-pin-policy.md](./skill-pin-policy.md). Host-specific dispatch (OpenClaw, cloud spawn, Warp auto-approve) is **not** this tutorial. Setup already warns that Warp auto-approve can silently answer interview questions.
 
 **OpenClaw:** If your agent host is OpenClaw (persistent-memory agents, Control UI, `sessions_spawn`), read [openclaw-agent-host.md](./openclaw-agent-host.md) for the host mental model, executable babysit path (installed skills), and the epic babysit → `sessions_spawn` Approach 1 expectation. Skill gate text remains in `deft-directive-review-cycle` / `deft-directive-swarm` — the host doc only points.
 

package/docs/scope-provenance.md

@@ -90,6 +90,8 @@ Flags:
 | `--xbrief-rel-path` | no | override path binding; default maps `pending/` → `active/` |
 | `--repo` | no | `owner/name` seed for preimage `approvedRepos` (same source as `issue:emit`) |
 
+Those two record kinds are **tracked provenance**, not local cache. Canonical `deft init` / `deft update` gitignore must not ignore the `.deft/approved-scope/` directory. Crash-journal, lock, and `.next` sidecars in that directory stay ignored. `git add` of the two record files must work without `-f`. Leftover directory ignore lines (both slash spellings) are healed off on update.
+
 Commit **both** `.deft/approved-scope/<plan-id>.json` and `<plan-id>.intent.json` on the **merge base** (or a prior PR) before the implementation PR activates or expands the scoped xBRIEF. Read the preimage before you commit — that file is the approved intent.
 
 ## Three layers (do not mix)

package/main.md

@@ -10,7 +10,7 @@ Foundational guidelines for AI agent behavior in the Deft framework.
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ Rule Precedence**: USER.md has two sections: `Personal` (always wins — name, custom rules) and `Defaults` (fallback — strategy, coverage, languages; PROJECT-DEFINITION.vbrief.json overrides these). (Override path via `DEFT_USER_PATH` env var; )
+**⚠️ Rule Precedence**: USER.md has two sections: `Personal` (always wins — name, custom rules) and `Defaults` (fallback — strategy, coverage, languages; PROJECT-DEFINITION.xbrief.json overrides these). (Override path via `DEFT_USER_PATH` env var; )
 
 **📋 Lazy Loading**: See `npx deft packs:slice skills list` (Skills Index; `REFERENCES.md` is maintainer-only and does not ship) for guidance on when to load which files.
 
@@ -26,7 +26,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 - `main.md` - General AI behavior (this document)
 - [coding/coding.md](./coding/coding.md) - Software development guidelines
 - `~/.config/deft/USER.md` - Personal preferences (highest precedence)
-- `./vbrief/PROJECT-DEFINITION.vbrief.json` - Project identity gestalt and scope registry
+- `./xbrief/PROJECT-DEFINITION.xbrief.json` - Project identity gestalt and scope registry
 
 **Coding-Specific:**
 - Languages: [languages/cpp.md](./languages/cpp.md), [languages/go.md](./languages/go.md), [languages/officejs.md](./languages/officejs.md), [languages/python.md](./languages/python.md), [languages/typescript.md](./languages/typescript.md), [languages/vba.md](./languages/vba.md)
@@ -191,21 +191,21 @@ Source material: AI Agent Traps paper (`docs/ssrn-6372438.pdf`, Franklin et al.,
 
 Propagation: the canonical orchestrator preamble at [templates/agent-prompt-preamble.md](./templates/agent-prompt-preamble.md) carries the same rule so dispatched workers inherit the behavior. This is the same class as the approval-fatigue defense above (`## Agent Trap Defenses`) applied to a different surface -- "you cancelled" is a buried mis-attribution that the rule corrects with the same fail-loud / surface-the-anomaly discipline.
 
-## vBRIEF Persistence
+## xBRIEF Persistence
 
-- ! All vBRIEF files MUST be stored in `./vbrief/` or its lifecycle subfolders — never in workspace root
-- ! Use `PROJECT-DEFINITION.vbrief.json` (singular) as the project identity gestalt — narratives for identity, items as scope registry
-- ! Use `plan.vbrief.json` (singular) for session-level tactical plans and progress tracking
-- ! Use `continue.vbrief.json` (singular) for interruption recovery checkpoints
-- ! Specifications are written as `specification.vbrief.json`, then rendered to `.md`
-- ! Scope vBRIEFs live in lifecycle folders: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`
-- ! Scope vBRIEF filenames MUST follow: `YYYY-MM-DD-descriptive-slug.vbrief.json` (slug rules: [`conventions/vbrief-filenames.md`](./conventions/vbrief-filenames.md))
-- ! Playbooks use `playbook-{name}.vbrief.json` (named, not ULID-suffixed)
+- ! All xBRIEF files MUST be stored in `./xbrief/` or its lifecycle subfolders — never in workspace root
+- ! Use `PROJECT-DEFINITION.xbrief.json` (singular) as the project identity gestalt — narratives for identity, items as scope registry
+- ! Use `plan.xbrief.json` (singular) for session-level tactical plans and progress tracking
+- ! Use `continue.xbrief.json` (singular) for interruption recovery checkpoints
+- ! Specifications are written as `specification.xbrief.json`, then rendered to `.md`
+- ! Scope xBRIEFs live in lifecycle folders: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`
+- ! Scope xBRIEF filenames MUST follow: `YYYY-MM-DD-descriptive-slug.xbrief.json` (slug rules: [`conventions/vbrief-filenames.md`](./conventions/vbrief-filenames.md))
+- ! Playbooks use `playbook-{name}.xbrief.json` (named, not ULID-suffixed)
 - ! Completed xBRIEFs are evidence of what was built — full standing as a record of *what is*, zero authority over *what to build next* (#3383). The current contract is the active xBRIEF plus the human operator's live instruction. Both halves are required.
 - ⊗ Use ULID-suffixed filenames for plan, todo, or continue files
-- ⊗ Place vBRIEF files at workspace root
-- ⊗ Write `SPECIFICATION.md` directly — it MUST be generated from `specification.vbrief.json`
-- ⊗ Move scope vBRIEFs between lifecycle folders without updating `plan.status`
+- ⊗ Place xBRIEF files at workspace root
+- ⊗ Write `SPECIFICATION.md` directly — it MUST be generated from `specification.xbrief.json`
+- ⊗ Move scope xBRIEFs between lifecycle folders without updating `plan.status`
 - ⊗ Treat a completed xBRIEF as the next-build contract, or let it override the active story or the live human instruction
 
 ### Schema version: v0.8 (canonical write)
@@ -230,10 +230,10 @@ Projects that pre-date v0.20 (pre-vBRIEF-centric model) must migrate on a **pinn
 
 A consumer project is **pre-cutover** if ANY of these hold:
 
-- `SPECIFICATION.md` exists at the project root and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: vbrief/specification.vbrief.json -->`, and `vbrief/specification.vbrief.json` plus all five lifecycle folders exist.
+- `SPECIFICATION.md` exists at the project root and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and a layout-resolved `<!-- Source of truth: ... -->` line for the specification artifact (`xbrief/specification.xbrief.json` on a migrated tree), and that artifact plus all five lifecycle folders exist.
 - `PROJECT.md` exists at the project root and is not a deprecation redirect (`<!-- deft:deprecated-redirect -->` or `<!-- Purpose: deprecation redirect -->`)
-- `vbrief/` exists but one or more of the five lifecycle subfolders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`) is missing
-- `vbrief/PROJECT-DEFINITION.vbrief.json` is absent on a project that otherwise looks set up
+- `xbrief/` exists but one or more of the five lifecycle subfolders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`) is missing
+- `xbrief/PROJECT-DEFINITION.xbrief.json` is absent on a project that otherwise looks set up
 
 The executable detection helper is `task migrate:preflight`. The full agent-facing flow lives in [QUICK-START.md](./QUICK-START.md) Step 2 and in [skills/deft-directive-setup/SKILL.md](./skills/deft-directive-setup/SKILL.md) (Pre-Cutover Detection Guard).
 
@@ -275,7 +275,7 @@ After migration completes, upgrade to current npm per [UPGRADING.md](./UPGRADING
 
 ### What migration produces
 
-The migrator replaces `SPECIFICATION.md` and `PROJECT.md` with deprecation-redirect stubs (both carry the `<!-- deft:deprecated-redirect -->` sentinel) and writes:
+**Legacy (frozen v0.59.0 `task migrate:vbrief` only — not a current write path; do not reverse #2907).** The migrator replaces `SPECIFICATION.md` and `PROJECT.md` with deprecation-redirect stubs (both carry the `<!-- deft:deprecated-redirect -->` sentinel) and writes:
 
 - `vbrief/PROJECT-DEFINITION.vbrief.json` — project identity gestalt (narratives + items registry)
 - `vbrief/specification.vbrief.json` — design narratives and requirements
@@ -366,18 +366,18 @@ See [commands.md](./commands.md) for full workflow details.
 ### Session
 
 - `/deft:continue` — Resume from continue checkpoint ([resilience/continue-here.md](./resilience/continue-here.md))
-- `/deft:checkpoint` — Save session state to `./vbrief/continue.vbrief.json`
+- `/deft:checkpoint` — Save session state to `./xbrief/continue.xbrief.json`
 
 ## Context Awareness
 
 **Project Context:**
-- ! Check `./vbrief/PROJECT-DEFINITION.vbrief.json` (in your consumer project) for project-specific rules and scope registry
+- ! Check `./xbrief/PROJECT-DEFINITION.xbrief.json` (in your consumer project) for project-specific rules and scope registry
 - ! Follow project-specific patterns and conventions
 - ~ Note which rules/patterns are being applied
 
 **User Context:**
 - ! Respect `~/.config/deft/USER.md` Personal section (highest precedence)
-- ! For project-scoped settings, PROJECT-DEFINITION.vbrief.json overrides USER.md Defaults
+- ! For project-scoped settings, PROJECT-DEFINITION.xbrief.json overrides USER.md Defaults
 - ! Remember user's maintained projects and their purposes
 - ~ Adapt communication style to user's expertise level
 
@@ -389,4 +389,4 @@ See [commands.md](./commands.md) for full workflow details.
 
 **Context Engineering:**
 - ~ See [context/context.md](./context/context.md) for strategies on managing context budget
-- ~ Use vBRIEF ([vbrief.org](https://vbrief.org)) for structured task plans, scratchpads, and checkpoints
+- ~ Use xBRIEF for structured task plans, scratchpads, and checkpoints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.110.0",
+  "version": "0.112.0",
   "deftConsumerDeposit": true,
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "license": "MIT",

package/packs/rules/rules-pack-0.1.json

@@ -3839,7 +3839,7 @@
       "id": "agents-029",
       "tier": "MUST",
       "domain": "agents",
-      "text": "**Worker-owns-lifecycle (Gap C):** When dispatching an implementation worker, the envelope MUST declare `stop-at: pr-open` OR `drive-to: merge-ready` (default for story work). Workers scoped `drive-to: merge-ready` own PR + review cycle + fix batches through merge-ready as ONE unit of work \u2014 they spawn their own review poller per review-cycle monitoring tiers; the orchestrator MUST NOT hand back at PR-open and re-dispatch separate leaf agents for review/fixes.",
+      "text": "**Worker-owns-lifecycle (Gap C):** When dispatching an implementation worker, the envelope MUST declare `stop-at: pr-open` OR `drive-to: merge-ready` (default for story work). Workers scoped `drive-to: merge-ready` own PR + review cycle + fix batches through merge-ready as ONE unit of work \u2014 following review-cycle monitoring tiers (Grok Build / Cursor / Claude Code leaves that cannot nest block on `pr:watch` in-process and MUST NOT spawn a child poller) (#4130); the orchestrator MUST NOT hand back at PR-open and re-dispatch separate leaf agents for review/fixes.",
       "path": "AGENTS.md",
       "body": null
     },