@deftai/directive-content 0.87.0 → 0.88.0

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

@@ -0,0 +1,37 @@
+# Host adapter: Warp
+
+Legend (RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+Descriptor: `warp-orchestrated` (`start_agent`) or `warp-manual` (`WARP_*` without `start_agent`).
+
+Load this file only after detect selects Warp. Do not load other host adapters.
+
+### Step 2a: Orchestrated Launch (start_agent available)
+
+! When `start_agent` is detected in the tool set, use it directly to launch each agent.
+
+- ! Launch one agent per worktree using `start_agent` with the generated prompt and worktree path as the working directory
+- ! Agents inherit the current environment's MCP servers, Warp Drive rules, and codebase index — equivalent to interactive Warp tabs but without manual tab management
+- ! No user intervention needed — launch is fully automated
+- ~ This is the preferred path: richest context with zero manual overhead
+
+### Step 2b: Interactive Warp Tabs (start_agent unavailable, Warp detected)
+
+! When `start_agent` is not available but Warp is detected (via `WARP_*` environment variables), fall back to manual Warp tab launch — briefly note that orchestrated launch is not available in this session, then proceed with the tab instructions below.
+
+! **Warp tabs cannot be opened programmatically.** There is no API or CLI command to open a new Warp terminal tab from an agent or script.
+
+Ask the user to open N new Warp terminal tabs. For each tab, the user:
+1. Navigates to the worktree: `cd <worktree>`
+2. Pastes the prompt directly into the **Warp agent chat input** (not the terminal)
+
+**Context advantages of Warp tabs:**
+- Global Warp Drive rules (personal rules auto-injected)
+- MCP servers via UUID (GitHub, etc. — zero-config)
+- Warp Drive notebooks, workflows, and other auto-injected context
+- Warm codebase index from the active Warp session (no cold-start delay)
+- Agent is interruptible and steerable mid-run
+
+**Tradeoff:** Requires the user to manually open and manage one Warp tab per agent.
+
+? If not running inside Warp at all (no `WARP_*` variables, no `start_agent`), use the same tab approach but with any terminal emulator — the user pastes prompts into their preferred terminal or agent interface.

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

@@ -162,6 +162,23 @@ The description is **the only thing the agent sees** when deciding whether to lo
 
 - ⊗ Omitting RFC2119 notation — deft skills use it consistently
 - ⊗ Putting all content in SKILL.md when it exceeds 150 lines — split into `references/*.md` or `REFERENCE.md`
+
+- ⊗ Putting every agent-host branch (Warp, Cursor, OpenClaw, Grok Build, generic) in one always-loaded SKILL body when a host-neutral core + per-host adapter split is feasible (#2928)
+
+---
+
+## Host-adapter skills (multi-host) (#2928)
+
+Large skills that branch on **agent host** (the runtime: Warp, Cursor, OpenClaw, Grok Build, generic-terminal) SHOULD use progressive host adapters:
+
+1. ! Keep a **thin host-neutral core** in `SKILL.md` (triggers, phase overview, detect, route table, cross-host MUST gates).
+2. ! Put shared depth in `references/core-*.md`.
+3. ! Put each host path in `references/host-<id>.md` (spawn primitive, cwd rules, monitor liveness, host MUST NOT list).
+4. ! Default load path: detect host → read core + **one** adapter. 
+5. ⊗ Load all host adapters “just in case.”
+
+Exemplar: `skills/deft-directive-swarm/` (route table in SKILL + `references/host-openclaw.md` etc.).
+
 - ⊗ Vague trigger phrases — use phrases the user would actually type
 - ⊗ Overlapping triggers without negative triggers — add `Do NOT trigger on …` to the description
 - ⊗ Naming a GitHub-integrated skill without `gh` in the name

package/strategies/artifact-guards.md

@@ -18,7 +18,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 This file is not a standalone strategy — it is a shared guard referenced by other strategies. It activates automatically when a strategy writes to vBRIEF artifacts.
 
-- ! Referenced by spec-generating strategies: [speckit](./speckit.md), [enterprise](./enterprise.md), [rapid](./rapid.md)
+- ! Referenced by spec-generating strategies: [speckit](./speckit.md), [enterprise](./enterprise.md), [rapid](./rapid.md), [interview](./interview.md), [yolo](./yolo.md)
 - ! Referenced by preparatory strategies: [bdd](./bdd.md), [discuss](./discuss.md), [research](./research.md), [map](./map.md), [probe](./probe.md)
 
 ## Workflow
@@ -32,11 +32,16 @@ This file is not a standalone strategy — it is a shared guard referenced by ot
 
 ## Spec-Generating Guard (Full)
 
-Applies to strategies that write to `PROJECT-DEFINITION.vbrief.json` (⊗ never `specification.vbrief.json` per [v0-20-contract.md](./v0-20-contract.md)): **speckit**, **enterprise**, **rapid**.
+Applies to strategies that write project identity as `PROJECT-DEFINITION` (⊗ never `specification.vbrief.json` / `specification.xbrief.json` per [v0-20-contract.md](./v0-20-contract.md)): **speckit**, **enterprise**, **rapid**, **interview**, **yolo**.
 
-! Before writing to `vbrief/PROJECT-DEFINITION.vbrief.json`, the strategy MUST perform the following checks (⊗ Never target the legacy `specification.vbrief.json`):
+! **Target resolution (xbrief-first)**: guard the file that is the live project identity:
+1. `./xbrief/PROJECT-DEFINITION.xbrief.json` when it exists (canonical current layout)
+2. else `./vbrief/PROJECT-DEFINITION.vbrief.json` when it exists (legacy layout)
+3. else the intended write path for a greenfield create (usually `./xbrief/PROJECT-DEFINITION.xbrief.json`)
 
-1. ! **Check existence**: Does the target file already exist?
+! Before writing or updating that target, the strategy MUST perform the following checks (⊗ Never target the legacy `specification.*.json`):
+
+1. ! **Check existence**: Does the resolved target file already exist?
    - If NO: proceed with the write — no guard needed.
    - If YES: continue to step 2.
 
@@ -51,35 +56,40 @@ Applies to strategies that write to `PROJECT-DEFINITION.vbrief.json` (⊗ never
    - ! Display: "A `{status}` version of this artifact already exists. Replace it? (yes/no)"
    - ~ If the user declines, offer to enrich (merge narratives) instead of replacing
 
-5. ! **Narrative preservation**: When overwriting `PROJECT-DEFINITION.vbrief.json`, read existing `narratives` keys first. If the strategy only writes a subset of narratives (e.g. speckit Phase 1 writes only `Principles`), merge the new narrative into the existing set — do NOT replace all narratives with only the new key.
-   - ⊗ Overwrite all `PROJECT-DEFINITION.vbrief.json` narratives when the strategy only produces a single narrative key
+5. ! **Narrative preservation**: When overwriting `PROJECT-DEFINITION`, read existing `narratives` keys first. If the strategy only writes a subset of narratives (e.g. speckit Phase 1 writes only `Principles`), merge the new narrative into the existing set — do NOT replace all narratives with only the new key.
+   - ⊗ Overwrite all `PROJECT-DEFINITION` narratives when the strategy only produces a single narrative key
+   - ⊗ Guard only the legacy `vbrief/` path while an `xbrief/PROJECT-DEFINITION.xbrief.json` is the live identity
 
 ---
 
 ## Preparatory Guard (Light)
 
-Applies to strategies that write scoped vBRIEFs to `vbrief/proposed/`: **bdd**, **discuss**, **research**, **map**.
+Applies to strategies that write scoped records to `proposed/`: **bdd**, **discuss**, **research**, **map**, **probe**, and brownfield **Add scope** paths from interview/setup.
+
+! **Target folder resolution (xbrief-first)**: scan `./xbrief/proposed/` when it exists; else legacy `./vbrief/proposed/`. Prefer writing new scopes under the same root the project already uses.
 
-! Before writing a scope vBRIEF to `vbrief/proposed/`, the strategy MUST check for existing files with the same scope or feature name:
+! Before writing a scope record to `proposed/`, the strategy MUST check for existing files with the same scope or feature name:
 
-1. ! **Check for existing file**: Scan `vbrief/proposed/` for files matching the target scope/feature slug (e.g. `*-{feature}-bdd.vbrief.json`, `*-{scope}-context.vbrief.json`).
+1. ! **Check for existing file**: Scan the resolved `proposed/` folder for files matching the target scope/feature slug (e.g. `*-{feature}-bdd.xbrief.json`, `*-{scope}-context.vbrief.json`).
    - If NO match: proceed with the write — no guard needed.
    - If a match exists: continue to step 2.
 
-2. ! **Warn and ask**: Display: "A vBRIEF for this scope already exists at `{path}`. Replace it, or create a new version? (replace/new)"
+2. ! **Warn and ask**: Display: "A scope record for this feature already exists at `{path}`. Replace it, or create a new version? (replace/new)"
    - ! If replace: overwrite the existing file
    - ! If new: append a numeric suffix or use today's date to create a distinct file
 
 3. ~ **Read existing decisions**: If the existing file contains a `LockedDecisions` or similar narrative, surface those decisions to the agent context so they are not lost even if the user chooses to replace.
 
-⊗ Silently overwrite an existing scope vBRIEF with the same feature/scope name without warning the user.
+⊗ Silently overwrite an existing scope record with the same feature/scope name without warning the user.
+⊗ Scan only legacy `vbrief/proposed/` when `xbrief/proposed/` is the live lifecycle root.
 
 ---
 
 ## Anti-Patterns
 
-- ⊗ Writing to `PROJECT-DEFINITION.vbrief.json` without checking the file's current status (⊗ never write `specification.vbrief.json` at all per v0-20-contract.md)
+- ⊗ Writing to `PROJECT-DEFINITION` without checking the file's current status (⊗ never write `specification.vbrief.json` / `specification.xbrief.json` at all per v0-20-contract.md)
+- ⊗ Guarding only `vbrief/PROJECT-DEFINITION.vbrief.json` while `xbrief/PROJECT-DEFINITION.xbrief.json` is the live identity
 - ⊗ Silently overwriting an `approved` or `completed` artifact — this discards locked decisions and approval state
-- ⊗ Replacing all `PROJECT-DEFINITION.vbrief.json` narratives when the strategy only contributes one narrative key (e.g. `Principles`)
-- ⊗ Overwriting a scope vBRIEF in `vbrief/proposed/` without checking if one already exists for the same scope
+- ⊗ Replacing all `PROJECT-DEFINITION` narratives when the strategy only contributes one narrative key (e.g. `Principles`)
+- ⊗ Overwriting a scope record in `proposed/` without checking if one already exists for the same scope
 - ⊗ Accepting vague confirmation (`proceed`, `ok`) when the guard requires explicit confirmation for approved/completed artifacts

package/strategies/discuss.md

@@ -72,6 +72,7 @@ Adapt question focus to what's being built:
 
 - ! Produce a `vbrief/proposed/{scope}-context.vbrief.json` scope vBRIEF with a `LockedDecisions` narrative
 - ! Each decision includes: **what** was decided, **why**, and **alternatives considered**
+- ! When the lock is an intentional under-build (weaker Now + decided end-product Later), the decision MUST also include dual-path graduation fields: `now`, `later`, `graduationRef`, `trigger`, and `status` (`open` | `shipped` | `cancelled`) — see [Graduation (Now+Later)](#graduation-nowlater-dual-path-locks-2899)
 - ! This vBRIEF is injected into all downstream work: planning, execution, verification
 - ! Persist decisions as vBRIEF narratives on the relevant plan items
 - ⊗ Write decisions to a hand-authored markdown context file -- use vBRIEF narratives for token-efficient agent consumption
@@ -85,6 +86,44 @@ Adapt question focus to what's being built:
 - ⊗ Silently making a different choice because the agent forgot what was decided
 - ⊗ Re-debating a settled decision without explicit user approval
 
+## Graduation (Now+Later) dual-path locks (#2899)
+
+**Graduation** (alias: Now+Later) is a first-class decision shape for intentional under-builds:
+
+> We *decided* to ship a weaker path **now**, and we also decided what the end-product path is **later**.
+
+It is **not** the same as other "later" concepts:
+
+| Concept | Meaning |
+|---|---|
+| `DeferredDecisions` (probe) | Not decided yet; open question with justification |
+| deferred plan item / `triage:defer` | Out of scope, or not accepted into the workspace backlog |
+| rapid **graduate** | Spike / prototype → fresh full interview/spec cycle |
+| **Graduation** | Decided weaker **Now** + decided end-product **Later** |
+
+Glossary naming for this term is owned by sibling work (#2907). Strategy prose here is the Wave A contract agents must follow until the glossary entry lands.
+
+### When a lock is an under-build
+
+- ! When a `LockedDecisions` entry chooses a temporary, weaker, MVP, or shortcut approach **and** a stronger end-product approach is also decided, the entry MUST record a dual-path graduation shape with all of:
+  - `now` — what this scope ships
+  - `later` — the end-product approach
+  - `graduationRef` — GitHub issue URL and/or scope xBRIEF path that tracks Later work
+  - `trigger` — free-text condition that makes Later required (examples are illustrative only, e.g. "before multi-tenant customers", "when latency SLO is adopted")
+  - `status` — `open` | `shipped` | `cancelled` (cancellation MUST include justification)
+- ! A permanent approach lock (no weaker temporary path) does **not** require graduation fields
+- ! Chat-only "we'll harden this later" is insufficient — same anti-pattern as decisions that exist only in conversation history
+- ~ Emitting `graduationRef` SHOULD use existing [emit-hints](./emit-hints.md) patterns (none / `--umbrella` / `--per-vbrief`) rather than a parallel SCM ontology
+- ⊗ Routing a *decided* under-build into `DeferredDecisions`, a deferred plan item, or `triage:defer` — those surfaces mean undecided or out-of-scope, not dual-path delivery
+- ⊗ Treating rapid prototype **graduate** as Graduation dual-path tracking inside a normal production build
+
+### Lifecycle: Now complete ≠ Later closed
+
+- ! `task scope:complete` on the Now story MUST NOT imply closure of linked graduation work (`graduationRef` issue and/or Later scope xBRIEF stay open until Later ships or is explicitly cancelled)
+- ⊗ Closing a graduation ticket solely because the MVP / Now story completed
+- ~ Wave A (soft): when completing a story whose `LockedDecisions` contain an open graduation, warn and audit if `graduationRef` is missing or invalid — hard fail / policy flag is Wave B follow-on
+- ! Durable surfaces for graduation are: (1) strategy output narratives (this contract), (2) optional always-loadable ProjectRules for stricter consumer policy — ⊗ Cursor-rule-only as the sole persistence path
+
 ---
 
 ## Then: Chaining Gate
@@ -115,7 +154,7 @@ run additional preparatory strategies or proceed to spec generation.
 
 1. **Open** -- Start with the user's goal statement; restate it in your own words
 2. **Explore** -- Follow energy, challenge vagueness, ask domain-sensitive questions
-3. **Lock** -- Record each decision in `vbrief/proposed/{scope}-context.vbrief.json` `LockedDecisions` narrative with what/why/alternatives
+3. **Lock** -- Record each decision in `vbrief/proposed/{scope}-context.vbrief.json` `LockedDecisions` narrative with what/why/alternatives (and dual-path graduation fields when the lock is an under-build; #2899)
 4. **Verify** -- Explain the full picture back to the user (Feynman check)
 5. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above
 

package/strategies/interview.md

@@ -13,7 +13,7 @@ follow this strategy.
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
-**⚠️ See also**: [strategies/discuss.md](./discuss.md) | [strategies/yolo.md](./yolo.md) | [core/glossary.md](../glossary.md)
+**⚠️ See also**: [strategies/discuss.md](./discuss.md) | [strategies/yolo.md](./yolo.md) | [strategies/artifact-guards.md](./artifact-guards.md) | [core/glossary.md](../glossary.md)
 
 ## When to Use
 
@@ -42,13 +42,37 @@ and wait for the user to choose before proceeding.
 - ! After each completed preparatory strategy (recursive — the gate reappears)
 - ! After the [Acceptance Gate](#acceptance-gate) when the user chooses "Revise" or "Switch"
 
+### Brownfield Detector
+
+Before rendering menu options, classify the repo (align with setup Phase 3):
+
+- **Brownfield** when **either**:
+  - `PROJECT-DEFINITION` exists under `./xbrief/` or legacy `./vbrief/` (`PROJECT-DEFINITION.xbrief.json` or `PROJECT-DEFINITION.vbrief.json`), **or**
+  - any lifecycle folder (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/` under `xbrief/` or legacy `vbrief/`) has scope records
+- **Greenfield** otherwise
+
+! The detector MUST run on every Chaining Gate presentation.
+⊗ Offer only the greenfield-framed **Proceed to specification** default on a brownfield repo.
+⊗ Treat brownfield as a full create path without an explicit Replace/scrap confirm.
+
 ### Options
 
-Present two groups sourced from the `Type` column in
-[strategies/README.md](./README.md#strategy-types):
+! Numbered Chaining Gate menus (greenfield and brownfield examples below) MUST end with `Discuss` and `Back` as the final two options per [deterministic-questions.md](../contracts/deterministic-questions.md).
+
+Present groups sourced from the `Type` column in
+[strategies/README.md](./README.md#strategy-types). The **default path** depends
+on the brownfield detector:
+
+**Default path (greenfield):**
+1. **Proceed to specification** (default) — continue to the [Sizing Gate](#sizing-gate) for a full create path
 
-**Default:**
-1. **Proceed to specification** (default) — continue to the [Sizing Gate](#sizing-gate)
+**Default path (brownfield) — create-vs-update menu:**
+1. **Add scope to this project** (default) — load existing project identity + preparatory artifacts; **skip** the greenfield "what are we building?" interview; gather only the new scope; emit **one** proposed scope record; apply the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) on write
+2. **Update project definition** — run a **delta** interview against existing identity; apply the [Spec-Generating Guard](./artifact-guards.md#spec-generating-guard-full); **merge** narratives (prefer enrich/merge when the user declines replace)
+3. **Replace specification (scrap)** — full recreate equivalent to greenfield Proceed; **only** after explicit affirmative (`yes` / `confirmed`); vague replies (`proceed`, `ok`, `go ahead`) are **not** acceptance
+   - ! On confirmed scrap, continue to the [Sizing Gate](#sizing-gate) as a full create path
+   - ⊗ Auto-delete PROJECT-DEFINITION without scrap confirm
+   - ⊗ Rename Proceed to "Update" without changing behavior
 
 **Preparatory strategies** (type: `preparatory` — loops back to this gate on completion):
 - Research — investigate the domain, find libraries, identify pitfalls
@@ -79,9 +103,28 @@ See `strategies/map.md` for standalone behavior.
 - ! Append all new artifact paths to the flat `artifacts` array
 - ! The next strategy and eventual spec generation MUST load all artifacts
   listed in `plan.vbrief.json`
+- ! On brownfield **Add scope** or **Update project definition**, load existing
+  PROJECT-DEFINITION identity and preparatory artifacts before asking questions
+
+### Write Guards (interview)
+
+! Interview is a **spec-generating** strategy and MUST follow
+[artifact-guards.md](./artifact-guards.md) before emission (Light or Full path).
+
+- ! **Before writing** scope records to `proposed/`: [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) (xbrief-first: `./xbrief/proposed/`, else legacy `./vbrief/proposed/`)
+- ! **Before writing** or updating `PROJECT-DEFINITION`: [Spec-Generating Guard](./artifact-guards.md#spec-generating-guard-full) against the **single live** identity file only — `./xbrief/PROJECT-DEFINITION.xbrief.json` when present (or after `deft migrate:xbrief`); else, until migrated, the existing legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`. ⊗ Dual-write both roots
+- ! Prefer enrich/merge when the user declines replace
+- ⊗ Silently overwrite PROJECT-DEFINITION or same-slug proposed scopes
+- ⊗ Guard only the legacy `vbrief/` path while an `xbrief/` PROJECT-DEFINITION is the live identity
+- ⊗ Rely on write-time guards alone without the brownfield Chaining Gate menu above
+
+Surface this obligation **inside `interview.md`** so agents that load only this
+file still hit the guards (#2925; incomplete closeout of #82/#387).
 
 ### Example Prompt
 
+**Greenfield:**
+
 ```
 Ready to generate the specification. Before we proceed, would you like to:
 
@@ -96,8 +139,32 @@ Ready to generate the specification. Before we proceed, would you like to:
 --- Switch strategy ---
 6. Switch to yolo — auto-pilot picks all answers
 7. Switch to speckit — formal spec process with story readiness before implementation
-
 8. Other (specify)
+9. Discuss
+10. Back
+```
+
+**Brownfield:**
+
+```
+This repo already has a project definition and/or scopes. Before we proceed:
+
+1. Add scope to this project (default) — keep identity; add one new proposed scope
+2. Update project definition — delta interview; merge narratives (Spec-Generating Guard)
+3. Replace specification (scrap) — requires explicit yes/confirmed; full recreate
+
+--- Preparatory (loops back) ---
+4. Run a research phase — investigate the domain, find libraries, identify pitfalls
+5. Run a discuss phase — lock key decisions using Feynman technique
+6. Run a probe phase — adversarially stress-test the plan; surface assumptions, edge cases, and risks
+7. Run a map phase — analyze existing codebase conventions
+
+--- Switch strategy ---
+8. Switch to yolo — auto-pilot picks all answers
+9. Switch to speckit — formal spec process with story readiness before implementation
+10. Other (specify)
+11. Discuss
+12. Back
 ```
 
 ---
@@ -188,19 +255,22 @@ flowchart LR
 
 ## Light Path (small/medium projects)
 
-Interview → scope vBRIEFs (date-prefixed in proposed/) + PROJECT-DEFINITION.vbrief.json + rendered SPECIFICATION (v0.20 contract).
+Interview → scope records (date-prefixed in proposed/) + live PROJECT-DEFINITION + rendered SPECIFICATION (v0.20 contract). Paths are **xbrief-first**: use `./xbrief/` when that root is the live project layout; else legacy `./vbrief/`.
 
 ### Flow
 
 1. Sizing gate selects Light
 2. Interview (rules above)
-3. Write scope vBRIEF(s) to `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` (date-prefixed per vbrief filename convention) with `status: proposed`
-4. Run `task project:render` to create/update `./vbrief/PROJECT-DEFINITION.vbrief.json` (full project identity + items registry) and ensure all five lifecycle folders exist
+3. Write scope record(s) to the live lifecycle root — `./xbrief/proposed/YYYY-MM-DD-<slug>.xbrief.json` when `./xbrief/` is live; else legacy `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` — date-prefixed with `status: proposed`
+4. Run `task project:render` to create/update the **live** PROJECT-DEFINITION under the resolved layout root (`./xbrief/PROJECT-DEFINITION.xbrief.json`). Engine layout resolution requires `xbrief/` (#2112); if the repo is legacy-only `./vbrief/`, run `deft migrate:xbrief` first, then render. Ensure all five lifecycle folders exist under the live root. ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `xbrief/` is live
 5. Summarize decisions, ask user to review
-6. On approval, use `task scope:promote` (or equivalent) to move scope vBRIEF(s) to `./vbrief/pending/` with `status: pending` / `approved`
-7. Run `task spec:render` (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` is legacy and is NOT written by this strategy on the v0.20 path)
+6. On approval, use `task scope:promote` (or equivalent) to move scope record(s) to `pending/` under the **same** live root with `status: pending` / `approved`
+7. Run `task project:export-spec` / `task spec:render` as appropriate (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` / `specification.xbrief.json` are legacy and are NOT written by this strategy on the v0.20 path)
 
-! At the emission step (step 3 above), after writing the scope vBRIEF(s) to `./vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
+! **Before writing** scope records or updating `PROJECT-DEFINITION` on the Light path, follow [artifact-guards.md](./artifact-guards.md): Preparatory Guard for `proposed/` scopes; Spec-Generating Guard against the **live** identity file (xbrief-first). Prefer enrich/merge when the user declines replace.
+! ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `./xbrief/PROJECT-DEFINITION.xbrief.json` is already the live identity.
+
+! At the emission step (step 3 above), after writing the scope record(s) to the live `proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
 
 ### SPECIFICATION Structure (Light)
 
@@ -252,20 +322,23 @@ How to ship it.
 
 ## Full Path (large/complex projects)
 
-Interview → PRD → scope vBRIEFs (date-prefixed in proposed/) + PROJECT-DEFINITION.vbrief.json + rendered SPECIFICATION (v0.20 contract).
+Interview → PRD → scope records (date-prefixed in proposed/) + live PROJECT-DEFINITION + rendered SPECIFICATION (v0.20 contract). Paths are **xbrief-first**: use `./xbrief/` when that root is the live project layout; else legacy `./vbrief/`.
 
 ### Flow
 
 1. Sizing gate selects Full
 2. Interview (rules above)
 3. Generate `PRD.md` — user approval gate
-4. Write scope vBRIEF(s) to `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` (date-prefixed per vbrief filename convention) with `status: proposed`
-5. Run `task project:render` to create/update `./vbrief/PROJECT-DEFINITION.vbrief.json` (full project identity + items registry) and ensure all five lifecycle folders exist
+4. Write scope record(s) to the live lifecycle root — `./xbrief/proposed/YYYY-MM-DD-<slug>.xbrief.json` when `./xbrief/` is live; else legacy `./vbrief/proposed/YYYY-MM-DD-<slug>.vbrief.json` — date-prefixed with `status: proposed`
+5. Run `task project:render` to create/update the **live** PROJECT-DEFINITION under the resolved layout root (`./xbrief/PROJECT-DEFINITION.xbrief.json`). Engine layout resolution requires `xbrief/` (#2112); if the repo is legacy-only `./vbrief/`, run `deft migrate:xbrief` first, then render. Ensure all five lifecycle folders exist under the live root. ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `xbrief/` is live
 6. Summarize decisions, ask user to review
-7. On approval, use `task scope:promote` (or equivalent) to move scope vBRIEF(s) to `./vbrief/pending/` with `status: pending` / `approved`
-8. Run `task spec:render` (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` is legacy and is NOT written by this strategy on the v0.20 path)
+7. On approval, use `task scope:promote` (or equivalent) to move scope record(s) to `pending/` under the **same** live root with `status: pending` / `approved`
+8. Run `task project:export-spec` / `task spec:render` as appropriate (SPECIFICATION.md is a rendered derivative with deprecation sentinel; `specification.vbrief.json` / `specification.xbrief.json` are legacy and are NOT written by this strategy on the v0.20 path)
+
+! **Before writing** PRD, scope records, or updating `PROJECT-DEFINITION` on the Full path, follow [artifact-guards.md](./artifact-guards.md): Preparatory Guard for `proposed/` scopes; Spec-Generating Guard against the **live** identity file (xbrief-first). Prefer enrich/merge when the user declines replace.
+! ⊗ Write a second PROJECT-DEFINITION under legacy `vbrief/` when `./xbrief/PROJECT-DEFINITION.xbrief.json` is already the live identity.
 
-! At the emission step (step 4 above), after writing the scope vBRIEF(s) to `./vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
+! At the emission step (step 4 above), after writing the scope record(s) to the live `proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
 
 ### PRD Structure (Full path only)
 
@@ -417,9 +490,9 @@ Each task SHOULD include:
 
 - ! All requirements mapped to tasks
 - ! Dependencies form a valid DAG (no cycles)
-- ! Scope vBRIEF(s) exist in `./vbrief/proposed/` (with date-prefixed filenames and `status: "proposed"`) or promoted to pending/active (with `status: "approved" / "pending"`)
-- ! `./vbrief/PROJECT-DEFINITION.vbrief.json` is present (populated via `task project:render`)
-- ! `SPECIFICATION.md` has been rendered via `task spec:render`
+- ! Scope records exist in the live `proposed/` root (`./xbrief/proposed/` when live; else legacy `./vbrief/proposed/`) with date-prefixed filenames and `status: "proposed"`, or promoted to pending/active (with `status: "approved" / "pending"`)
+- ! Live PROJECT-DEFINITION is present (`./xbrief/PROJECT-DEFINITION.xbrief.json` when that is the identity; else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) populated via `task project:render`
+- ! `SPECIFICATION.md` has been rendered via export/`task spec:render`
 - ! Proceed to [Acceptance Gate](#acceptance-gate)
 
 ---
@@ -517,20 +590,20 @@ diff only on the second pass or when the user explicitly asks for it.
 
 | Artifact | Purpose | Created By |
 |----------|---------|------------|
-| `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json` | Scope story vBRIEFs (date-prefixed, v0.20 contract) | Interview |
-| `./vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |
-| `SPECIFICATION.md` | Generated plan with embedded Requirements (rendered derivative; deprecation sentinel) | `task spec:render` |
-| (no `specification.vbrief.json`) | Legacy artifact — omitted on v0.20 path | — |
+| `./xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (else legacy `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json`) | Scope story records (date-prefixed, v0.20 contract) | Interview |
+| `./xbrief/PROJECT-DEFINITION.xbrief.json` (else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |
+| `SPECIFICATION.md` | Generated plan with embedded Requirements (rendered derivative; deprecation sentinel) | export / `task spec:render` |
+| (no `specification.*.json`) | Legacy artifact — omitted on v0.20 path | — |
 
 **Full path:**
 
 | Artifact | Purpose | Created By |
 |----------|---------|------------|
 | `PRD.md` | What to build (approval gate) | Interview |
-| `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json` | Scope story vBRIEFs (date-prefixed, v0.20 contract) | Post-PRD interview |
-| `./vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |
-| `SPECIFICATION.md` | Generated implementation plan (rendered derivative; deprecation sentinel) | `task spec:render` |
-| (no `specification.vbrief.json`) | Legacy artifact — omitted on v0.20 path | — |
+| `./xbrief/proposed/YYYY-MM-DD-*.xbrief.json` (else legacy `./vbrief/proposed/YYYY-MM-DD-*.vbrief.json`) | Scope story records (date-prefixed, v0.20 contract) | Post-PRD interview |
+| `./xbrief/PROJECT-DEFINITION.xbrief.json` (else legacy `./vbrief/PROJECT-DEFINITION.vbrief.json`) | Project identity gestalt + items registry | `task project:render` (triggered by strategy) |
+| `SPECIFICATION.md` | Generated implementation plan (rendered derivative; deprecation sentinel) | export / `task spec:render` |
+| (no `specification.*.json`) | Legacy artifact — omitted on v0.20 path | — |
 
 ## Invoking This Strategy
 
@@ -547,5 +620,5 @@ Use the interview strategy to plan [project].
 After completion:
 
 ```
-implement the scope vBRIEFs in ./vbrief/active/
+implement the scope records in ./xbrief/active/ (or legacy ./vbrief/active/)
 ```

package/strategies/probe.md

@@ -104,7 +104,7 @@ feature/component name if probing a sub-scope. Use the same value consistently
 throughout the session. Examples: `my-app-probe`, `auth-probe`.
 
 - ! Produce a `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF with three mandatory narratives:
-  - `LockedDecisions` — what was resolved and why
+  - `LockedDecisions` — what was resolved and why (when the lock is an intentional under-build, include dual-path graduation fields: `now`, `later`, `graduationRef`, `trigger`, `status` — see [Graduation (Now+Later)](#graduation-nowlater-when-locking-an-under-build-2899))
   - `SurfacedRisks` — concerns raised, even if not fully resolved
   - `DeferredDecisions` — explicitly acknowledged items with justification
 - ! Each entry in a narrative includes: **question asked**, **answer given**, **status** (locked / deferred / risk-accepted)
@@ -114,6 +114,30 @@ throughout the session. Examples: `my-app-probe`, `auth-probe`.
 
 ! After emitting the probe scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
 
+## Graduation (Now+Later) when locking an under-build (#2899)
+
+Probe already separates **locked**, **deferred**, and **risk-accepted** branches. **Graduation** is a fourth case that must not collapse into `DeferredDecisions`:
+
+| Concept | Probe role |
+|---|---|
+| `LockedDecisions` (permanent) | Approach is decided and is the end-product path |
+| `DeferredDecisions` | *Undecided* open question with justification |
+| **Graduation** on a lock | *Decided* weaker **Now** + *decided* end-product **Later** |
+| rapid **graduate** | Strategy-level spike → fresh spec; not dual-path tracking here |
+
+Glossary naming for Graduation is owned by sibling work (#2907); this section is the Wave A probe contract.
+
+- ! When probe **locks** a temporary / weaker approach and the end-product approach is also decided, record the dual-path shape on that `LockedDecisions` entry (not as a `DeferredDecisions` open question):
+  - `now` — what ships in the near path
+  - `later` — end-product approach
+  - `graduationRef` — GitHub issue and/or scope xBRIEF path for Later work
+  - `trigger` — condition that makes Later required (free text)
+  - `status` — `open` | `shipped` | `cancelled` (cancel with justification)
+- ! Permanent locks and true open questions do **not** gain graduation fields — do not ticket-spam every `DeferredDecisions` item into a graduation
+- ! `task scope:complete` on a Now story MUST NOT close linked graduation work; Later stays open until shipped or explicitly cancelled
+- ⊗ Accepting "we'll harden it later" as a locked under-build without dual-path fields, or filing it only as `DeferredDecisions`
+- ⊗ Closing graduation work solely because the MVP / Now story completed
+
 ---
 
 ## Then: Chaining Gate
@@ -143,6 +167,8 @@ written, return to the [chaining gate](./interview.md#chaining-gate).
 ## Anti-Patterns
 
 - ⊗ Accepting "we'll figure it out later" without marking it as explicitly deferred
+- ⊗ Recording a *decided* weaker-Now + stronger-Later path only as `DeferredDecisions` (or chat) instead of dual-path graduation fields on the lock (#2899)
+- ⊗ Treating Now-story `scope:complete` as closure of linked graduation work (#2899)
 - ⊗ Asking generic checklist questions instead of following the decision tree
 - ⊗ Letting vague answers pass without pushing for concrete specifics
 - ⊗ Using codebase exploration as a substitute for asking the user about deliberate design choices

package/tasks/engine-invoke.cjs

@@ -12,6 +12,29 @@
 
 const { spawnSync } = require("node:child_process");
 
+/**
+ * cmd.exe command separators / metacharacters. Free-text DEFT_ENGINE_CMD_JSON
+ * tokens (release --summary text, CLI_ARGS, #2547) may legitimately contain
+ * these; double-quoting renders them literal to cmd.exe's parser so a token can
+ * never break out of its argv slot (subprocess-scm-01 / #2911).
+ */
+const WIN32_CMD_METACHAR_RE = /[\s"&|<>^()%!]/;
+
+/**
+ * Quote a single argument for `cmd.exe /d /s /c` so that shell metacharacters
+ * stay inside one argv token. Mirrors tasks/engine-pm-run.cjs quoteWin32Arg but
+ * also quotes cmd.exe separators (& | < > ^ ( ) % !) because engine-invoke
+ * forwards operator free-text, not an allowlisted command.
+ * @param {string} arg
+ */
+function quoteWin32Arg(arg) {
+  const s = String(arg);
+  if (s.length > 0 && !WIN32_CMD_METACHAR_RE.test(s)) {
+    return s;
+  }
+  return `"${s.replace(/"/g, '""')}"`;
+}
+
 /** Minimal POSIX-ish shell word splitter (double/single quotes, escapes). */
 function shellSplit(input) {
   const out = [];
@@ -75,15 +98,8 @@ function main() {
     process.exit(2);
   }
 
-  let execPath;
-  let execArgv;
-  if (mode === "vendored") {
-    execPath = process.execPath;
-    execArgv = [target, ...argv];
-  } else if (mode === "global") {
-    execPath = target;
-    execArgv = argv;
-  } else {
+  const plan = buildSpawnPlan(mode, target, argv);
+  if (!plan) {
     console.error(`deft: engine-invoke unknown mode ${JSON.stringify(mode)}`);
     process.exit(2);
   }
@@ -97,11 +113,12 @@ function main() {
   // stdio inherit (not pipe): piped stdout/stderr deadlocks when the child emits
   // more than the OS pipe buffer before exit — observed as greenfield smoke
   // hanging then CI SIGTERM exit 143 with no output (#2554 / #2547).
-  const result = spawnSync(execPath, execArgv, {
+  const result = spawnSync(plan.command, plan.args, {
     stdio: "inherit",
     env: childEnv,
-    // Global deft/directive on Windows are .cmd shims; shell:false cannot spawn them (#2415).
-    shell: mode === "global" && process.platform === "win32",
+    // Never shell:true — even on win32 global (subprocess-scm-01 / #2911). The
+    // win32 .cmd shim is reached through a tightly quoted cmd.exe wrapper below.
+    shell: plan.shell,
     // CREATE_NO_WINDOW: hide console windows from Cursor Task / nested shells (#2563).
     windowsHide: true,
   });
@@ -109,8 +126,47 @@ function main() {
   process.exit(code === null ? 1 : code);
 }
 
+/**
+ * Resolve the concrete spawn command/args for a mode+target without ever using
+ * shell:true. On the win32 global path the target is a `.cmd` shim that Node
+ * refuses to spawn with shell:false (CVE-2024-27980 / #2415); shell:true would
+ * let cmd.exe re-parse free-text DEFT_ENGINE_CMD_JSON tokens (subprocess-scm-01
+ * / #2911). Instead route through `cmd.exe /d /s /c` with every token tightly
+ * quoted so metacharacters stay inside a single argv token — aligned with
+ * tasks/engine-pm-run.cjs executeAllowlisted().
+ *
+ * @param {string} mode
+ * @param {string} target
+ * @param {string[]} argv
+ * @param {{ platform?: string, nodePath?: string }} [opts]
+ * @returns {{ command: string, args: string[], shell: false } | null}
+ */
+function buildSpawnPlan(mode, target, argv, opts = {}) {
+  const platform = opts.platform || process.platform;
+  const nodePath = opts.nodePath || process.execPath;
+
+  let execPath;
+  let execArgv;
+  if (mode === "vendored") {
+    execPath = nodePath;
+    execArgv = [target, ...argv];
+  } else if (mode === "global") {
+    execPath = target;
+    execArgv = argv;
+  } else {
+    return null;
+  }
+
+  if (mode === "global" && platform === "win32") {
+    const commandLine = [execPath, ...execArgv].map(quoteWin32Arg).join(" ");
+    return { command: "cmd.exe", args: ["/d", "/s", "/c", commandLine], shell: false };
+  }
+
+  return { command: execPath, args: execArgv, shell: false };
+}
+
 if (require.main === module) {
   main();
 }
 
-module.exports = { shellSplit };
+module.exports = { shellSplit, quoteWin32Arg, buildSpawnPlan, WIN32_CMD_METACHAR_RE };