@deftai/directive-content 0.87.0 → 0.88.0

package/QUICK-START.md

@@ -153,6 +153,10 @@ Read and follow `../AGENTS.md`. This starts the normal first-session flow (user
 
 **OpenClaw agent-host pointer:** Running Directive under OpenClaw persistent-memory agents? See [docs/openclaw-agent-host.md](./docs/openclaw-agent-host.md) for Control UI / identity notes, the executable babysit path (installed review-cycle skill), and the epic babysit → `sessions_spawn` Approach 1 expectation — skill and register contracts stay in shipped skills (#2877 / epic #2874).
 
+**Writing pointer:** For docs, issues, and PR prose that maintainers or agents author, follow [docs/writing-ste100.md](./docs/writing-ste100.md) (short controlled English; #2927).
+
+**Opt-out pointer:** Projects that must not use Directive should commit root [`.no-deft-directive`](./docs/no-deft-directive.md) so session/doctor/init/setup skip install and ritual (#2926).
+
 **Contributor pointer (non-blocking):** Working on Deft itself (a `deftai/directive` source checkout)? See [CONTRIBUTING.md](../CONTRIBUTING.md) and use the maintainer install path (`deft-install --yes --upgrade --maintainer --repo-root . --json`). The repo's root `AGENTS.md` has contributor instructions — you do not need the consumer first-session flow above.
 
 ## Update notifications

package/Taskfile.yml

@@ -403,6 +403,7 @@ tasks:
       - verify:rule-ownership
       - verify:biome-config
       - verify:content-manifest
+      - verify:license-sync
       - verify:skill-external-fetch-gate
       - verify:contract-drift
       - verify:cursor-tier1

package/UPGRADING.md

@@ -8,7 +8,29 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 <!-- xbrief-backcompat-2111 -->
 
-> **xBRIEF rename (#2034 / #2110):** Projects still on the legacy `vbrief/` layout and `x-vbrief/` reference tokens remain read-accepted until you run `deft migrate:xbrief` (or `task migrate:xbrief`). `deft doctor` and `deft update` signpost unmigrated layouts.
+### xBRIEF rename (#2034 / #2110 / #2907)
+
+> **Single authoritative rename/history note.** Public product voice uses **xBRIEF** / `xbrief/` only. **vBRIEF** is **legacy**.
+
+| Legacy (historical) | Current public canon |
+| --- | --- |
+| `vbrief/` lifecycle root | `xbrief/` |
+| `*.vbrief.json` | `*.xbrief.json` |
+| `vBRIEF` / “scope vBRIEF” in guidance | `xBRIEF` / “scope xBRIEF” |
+| `x-vbrief/*` reference tokens | `x-xbrief/*` (and migrate-accepted legacy tokens) |
+| `task vbrief:*` / `migrate:vbrief` aliases | Prefer `task xbrief:*` / `deft migrate:xbrief`; keep `vbrief:*` only as deprecated aliases when required for back-compat |
+| Envelope keys `vBRIEFInfo` | `xBRIEFInfo` (legacy keys still read-accepted on unmigrated files) |
+
+**Why two names existed:** consumer layout and disk SoT moved to `xbrief/` while docs, glossary, and marketing still taught vBRIEF as current. That dual present-day naming is retired (#2907). Schema lineage, fixtures, migrate paths, changelog history, and archive prose may still say vBRIEF — always as **legacy/historical**, never as competing current guidance.
+
+**What to do:**
+
+1. Prefer `xbrief/` and `.xbrief.json` in all new docs, skills, CLI help, and agent prose.
+2. On projects still on disk under `vbrief/`, run `deft migrate:xbrief` (or `task migrate:xbrief`). `deft doctor` and `deft update` signpost unmigrated layouts.
+3. Do **not** tell users to “prefer vBRIEF” or treat xbrief and vBRIEF as two current models.
+4. Deep schema conventions still live under `content/vbrief/` (path name is historical for the schema package); public work-state name remains xBRIEF.
+
+Refs: [#2034](https://github.com/deftai/directive/issues/2034), [#2110](https://github.com/deftai/directive/issues/2110), [#2907](https://github.com/deftai/directive/issues/2907).
 
 ---
 
@@ -927,7 +949,7 @@ After you update `deft/` to v0.20.0, `vbrief/*.vbrief.json` files are the source
 - [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) — detailed brownfield adoption / migration walkthrough.
 - [QUICK-START.md](./QUICK-START.md) — agent-facing bootstrap + upgrade detection.
 - [vbrief/vbrief.md](./vbrief/vbrief.md) — canonical vBRIEF file taxonomy.
-- [glossary.md](./glossary.md) — canonical v0.20 vocabulary (Scope vBRIEF, lifecycle folder, canonical narrative keys, rendered export, source of truth, ...).
+- [glossary.md](./glossary.md) — canonical xBRIEF / v0.20+ vocabulary (Scope xBRIEF, lifecycle folder, canonical narrative keys, rendered export, source of truth; vBRIEF marked legacy).
 - [CHANGELOG.md](../CHANGELOG.md) — full v0.20.0 change list.
 
 ---

package/coding/coding.md

@@ -125,9 +125,12 @@ This rule is the OPERATIONAL complement to the EPISTEMIC honesty rules elsewhere
 - ⊗ MUST NOT use successful-sounding completion phrasing to paper over uncertainty -- default to surfacing uncertainty, not hiding it
 - ⊗ MUST NOT suppress error output (`2>$null`, `2>/dev/null`, `try/except: pass` around the verification command) and then claim completion based on the resulting silence
 
+- ! Before claiming "feature complete", "ready for real users", "production-ready", or equivalent area-complete language for a surface that has open graduations (Now+Later dual-path locks; #2899), MUST name the open `graduationRef`s, **or** explicitly state that graduation review was skipped and why — otherwise the claim is outcome-blind under this rule
+- ⊗ MUST NOT claim "feature complete" / "production-ready" / "ready for real users" for an area with open graduations without naming those `graduationRef`s or an explicit skip-with-reason
+
 The rule applies to agent completion claims during task execution. It applies equally to claims to the user, claims in commit messages, claims in PR bodies, claims in CHANGELOG entries, and claims in status messages to a parent agent. A short, honest "the migration completed; I did not verify the per-record count" is strictly preferred over a confident "migration completed successfully" that hides the gap.
 
-**Cross-references:** `## Quality Standards` above (`⊗ Claim checks passed without running them` -- the sibling rule that this expands from process to outcome); `hygiene.md` `## Error Handling: No Hiding` (the same hiding pattern at the code-write level, not the claim level); `skills/deft-directive-pre-pr/SKILL.md` (pre-PR verification claims); `skills/deft-directive-build/SKILL.md` Step 4 Quality Gates (task-completion claims); `skills/deft-directive-review-cycle/SKILL.md` (the review-cycle skill explicitly checks for hidden incompleteness in fix-batch completion claims).
+**Cross-references:** strategies discuss/probe Graduation dual-path locks (#2899); `## Quality Standards` above (`⊗ Claim checks passed without running them` -- the sibling rule that this expands from process to outcome); `hygiene.md` `## Error Handling: No Hiding` (the same hiding pattern at the code-write level, not the claim level); `skills/deft-directive-pre-pr/SKILL.md` (pre-PR verification claims); `skills/deft-directive-build/SKILL.md` Step 4 Quality Gates (task-completion claims); `skills/deft-directive-review-cycle/SKILL.md` (the review-cycle skill explicitly checks for hidden incompleteness in fix-batch completion claims).
 
 ## Calling LLM APIs (#481)
 
@@ -231,5 +234,6 @@ See [debugging.md](debugging.md) for the full four-phase process, evidence disci
 - ⊗ Circular imports between modules
 - ⊗ Duplicate logic across 2+ call sites without shared abstraction
 - ⊗ Outcome-blind completion claims: "tests pass" with skipped tests, "migration completed" without per-record counts, "feature works" without naming the verified edge case (#1006 -- see `## Fail Loud` above)
+- ⊗ Outcome-blind "feature complete" / "production-ready" claims that ignore open graduations (`graduationRef`s) without naming them or an explicit skip (#2899 / #1006 -- see `## Fail Loud` above)
 - ⊗ Averaging contradicting codebase patterns: writing new code that satisfies both of two conflicting patterns simultaneously (#1005 -- see `hygiene.md` `## Surface Conflicts`)
 - ⊗ Debugging by guess-and-check: fixing before reproducing, treating the first plausible hypothesis as confirmed, or presenting a duration/exit-status as a root cause (#1621 -- see `debugging.md`)

package/commands.md

@@ -218,7 +218,7 @@ When the workflow needs an Approach 1 monitor, scope the Cursor leaf `stop-at: p
 - **Compact re-arm (#2113):** Cursor `preCompact` and Claude/Grok `PreCompact`/`PostCompact` call `deft-hook --event session.compact` to mark the gated session ritual stale after context compaction/resume; the existing PreToolUse gate then denies direct writes until `deft session:start` and `deft verify:session-ritual -- --tier=gated`. Codex has no native compact hook — operators must re-run the mutation ritual manually after compaction.
 - Codex project hooks are trust-gated by Codex. Directive verifies only that the registrations are structurally current; after an install or changed hook hash, open `/hooks` in Codex and review/approve the project hook commands. Runtime trust cannot be inferred from the file alone.
 - Directive writes only `.codex/hooks.json`; it does not parse or modify `.codex/config.toml`. Codex can also load inline hooks from `config.toml`, so avoid defining duplicate Directive commands there or they may run more than once. See the [Codex hooks documentation](https://learn.chatgpt.com/docs/hooks).
-- The P0 hook slice does not classify shell-mediated writes, MCP mutations, richer unified-exec calls, or WebSearch by default. **Runtime authority (#1394)** adds opt-in path allow/deny lists and graduated `scopes` (`edits`, `push`, `merge`) under `plan.policy.runtimeAuthority` — inspect with `deft policy:show --field=runtimeAuthority`. When `enabled: true`, PreToolUse denies classifiable direct-write targets outside `allowPaths` or matching `denyPaths` after ritual/scope/read-only gates; `scopes.edits` gates all direct writes. `push` / `merge` scopes are schema-only until Shell/MCP matchers land (host gap — TODO).
+- The P0 hook slice does not classify shell-mediated *file* writes, richer unified-exec calls, or WebSearch by default. **Runtime authority (#1394 / #2711)** adds opt-in path allow/deny lists and graduated `scopes` (`edits`, `push`, `merge`) under `plan.policy.runtimeAuthority` — inspect with `deft policy:show --field=runtimeAuthority`. When `enabled: true`, PreToolUse denies classifiable direct-write targets outside `allowPaths` or matching `denyPaths` after ritual/scope/read-only gates; `scopes.edits` gates all direct writes. `scopes.push` / `scopes.merge` deny classifiable Shell/Bash (`git push`, `gh pr merge`) and classifiable MCP push/merge tool names; unclassifiable shell/MCP calls fail open (see `content/contracts/runtime-authority.md`).
 
 ## Session-start ritual (#1149)
 

package/contracts/runtime-authority.md

@@ -1,4 +1,4 @@
-# Runtime authority policy (#1394)
+# Runtime authority policy (#1394 / #2711)
 
 Typed session-level enforcement under `plan.policy.runtimeAuthority` in `xbrief/PROJECT-DEFINITION.xbrief.json`.
 
@@ -10,8 +10,8 @@ Typed session-level enforcement under `plan.policy.runtimeAuthority` in `xbrief/
 | `allowPaths` | `[]` | Empty = allow all paths (when enabled) |
 | `denyPaths` | `[]` | Deny wins over allow |
 | `scopes.edits` | `true` | Direct Write/Edit/StrReplace tools |
-| `scopes.push` | `false` | Schema only — Shell matcher TODO |
-| `scopes.merge` | `false` | Schema only — Shell matcher TODO |
+| `scopes.push` | `false` | Shell/Bash `git push` and classifiable MCP push tools (#2711) |
+| `scopes.merge` | `false` | Shell/Bash `gh pr merge` and classifiable MCP merge tools (#2711) |
 
 ## Path globs
 
@@ -20,10 +20,38 @@ Gitignore-style globs via the shared `matchPath` helper (`src/**`, `**/AGENTS.md
 ## Evaluation order (PreToolUse)
 
 1. Ritual / scope / read-only / spawn gates (existing #2438 / #1185 stack)
-2. Runtime authority path + `scopes.edits` (this policy)
+2. Runtime authority path + `scopes.edits` for direct-write tools
+3. Runtime authority `scopes.push` / `scopes.merge` for Shell/Bash and classifiable MCP tools (#2711)
 
 Policy load failures fail open (host crash behavior unchanged).
 
+## Shell / MCP classification (#2711)
+
+When `enabled: true`:
+
+| Classified as | Examples | Scope |
+| --- | --- | --- |
+| **push** | `git push …`, `git -C <path> push`, env-prefixed `FOO=1 git push`, after `&&` / `;` / `\|` | `scopes.push` |
+| **merge** | `gh pr merge …`, `gh.exe pr merge …` | `scopes.merge` |
+| **MCP merge** | tool names matching `merge_pull_request`, `pr_merge`, … | `scopes.merge` |
+| **MCP push** | tool names matching `git_push`, `push_branch`, … | `scopes.push` |
+
+**Fail open (allow)** when:
+
+- the tool is Shell/MCP but the command/tool name is **not** classifiable as push or merge (e.g. `git status`, unrelated MCP tools)
+- the host payload omits a command string
+- policy load throws
+
+**Install note:** agent-host PreToolUse deposits include a Shell/Bash matcher (`SHELL_HOOK_MATCHER`) so classifiable shell ops reach `hook:dispatch` (#2711). MCP tools are classified when the host invokes the hook for that tool name; hosts that never fire PreToolUse for MCP remain a residual gap.
+
+**Not enforced** (document as residual host gap):
+
+- WebSearch / non-shell non-MCP tools
+- Obfuscated shell (`bash -c "$(echo Z2l0IHB1c2g=|base64 -d)"`) — not a complete substitute for Tier-2 git hooks
+- Every MCP host spelling — only patterns above; unknown MCP tools fail open
+- MCP tools on hosts that do not install/subscribe a PreToolUse matcher for those tool names
+Tier-2 git hooks remain authoritative for commit/push on the working tree. This layer is session-time PreToolUse only.
+
 ## Inspection
 
 ```bash
@@ -47,8 +75,6 @@ deft policy:show --field=runtimeAuthority
 }
 ```
 
-## Deferred (host gap)
-
-- Shell/Bash `git push`, `gh pr merge`, MCP mutations — not on the direct-write PreToolUse matcher today. `scopes.push` / `scopes.merge` are reserved for a follow-on Shell matcher (#1394 phase 2).
+With that shape, a PreToolUse `Bash` / `Shell` invocation of `git push` or `gh pr merge` is denied when the matching scope is `false`.
 
-Refs #2437 Core T1 Wave C.
+Refs #2437 Core T1 Wave C residual, #2711, #2948 Wave 0.

package/docs/getting-started.md

@@ -141,3 +141,7 @@ Full command reference for every triage and cache verb lives in [`commands.md`
 <!-- TODO: Cover AGENTS.md, skill routing, Warp Drive integration, and cloud agent dispatch -->
 
 **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.
+
+**Writing:** For docs, issues, and PR prose, follow [writing-ste100.md](./writing-ste100.md) (short controlled English; #2927).
+
+**Opt out:** To mark a repo as not using Directive, add root [`.no-deft-directive`](./no-deft-directive.md) (#2926). Tools skip install and session ritual when that file is present.

package/docs/no-deft-directive.md

@@ -0,0 +1,87 @@
+# Opt out with `.no-deft-directive`
+
+Some projects should not use Deft Directive. Use a **root file flag** so tools and agents stop offering install, session ritual, and setup.
+
+Tracker: [#2926](https://github.com/deftai/directive/issues/2926).
+
+## Filename and location
+
+```text
+.no-deft-directive
+```
+
+- **Exact name:** lowercase `.no-deft-directive`
+- **Location:** project / workspace **root only** (the root the agent or CLI opened)
+- **Content:** empty file or a short `#` comment. Presence is the flag. No schema.
+
+~ Commit the flag. Opt-out is a project decision other clones should see.
+
+## Behavior
+
+| Condition | Behavior |
+|-----------|----------|
+| Flag **present** | Directive **off** for this project. Do not install. Do not run session ritual (CLI `session:start` **and** installed host SessionStart hooks). Do not offer setup. |
+| Flag **absent**, no deposit | Tools **may** ask whether to install. On decline, create the flag. On enable, install and do **not** create the flag. |
+| Operator stops using DD | Create `.no-deft-directive`. Do **not** auto-delete an existing deposit. |
+| Operator starts using DD | Remove the flag, then run `directive init` or `directive update` so install is present. |
+
+One-line message when tools honor the flag:
+
+```text
+Directive disabled via `.no-deft-directive`
+```
+
+## Inconsistent state (flag + deposit)
+
+If **both** `.no-deft-directive` and a deposit (`.deft/core`) exist:
+
+- **Doctor:** **warns** and exits dirty (exit 1)
+- **`session:start`:** short-circuits with the disabled message plus the inconsistency warning (exit 1)
+- **Host SessionStart hooks:** skip ritual bookkeeping (allow with `session-start-disabled`); never write `.deft/last-session.json` under opt-out
+- **`init` / `update`:** **fail closed** (no scaffold/refresh)
+
+**Product choice (v1):** warn in doctor; fail closed on mutating install paths (`warn-and-fail-closed`).
+
+Fix by either:
+
+1. Removing the flag if the project should use Directive, or
+2. Removing the deposit if opt-out is intentional (explicit cleanup only — tools do not delete `.deft/` when creating the flag)
+
+## Local flag wins (v1)
+
+The root flag **wins locally** over ambient trusted-org / product-signal force-on. Org defaults must not override a committed opt-out without an explicit product decision beyond v1.
+
+## CLI helpers (optional)
+
+```bash
+directive policy:disable-directive [--project-root .] [--note "reason"]
+directive policy:enable-directive [--project-root .]
+```
+
+- `disable-directive` creates the flag (optional `--note` becomes a `#` comment)
+- `enable-directive` removes the flag and tells you to ensure install
+
+Presence detection is the core contract. CLI helpers are convenience only.
+
+## Setup skill contract
+
+When `deft-directive-setup` runs:
+
+1. ! Check for root `.no-deft-directive` **before** any install or interview phase
+2. ! If present → stop with `Directive disabled via \`.no-deft-directive\``
+3. ? If absent and no deposit → ask the human whether to use Directive
+4. ! On decline → create `.no-deft-directive` and stop
+5. ! On enable / “start using DD” → remove the flag and ensure install
+
+## Non-goals / follow-ups
+
+- ⊗ Auto-delete `.deft/` when creating the flag
+- ⊗ Org-wide ban (this is per-project filesystem only)
+- ⊗ Nested monorepo package roots (v1 is workspace root only; multi-package monorepo rules are a follow-up)
+- ⊗ Host personality / who may approve gates
+
+## Related
+
+- [getting-started.md](./getting-started.md) — install and first project
+- [product-signal.md](./product-signal.md) — optional partner signal (defaults off; flag still wins locally)
+- `session:start`, `doctor`, `directive init`, `directive update`

package/docs/openclaw-agent-host.md

@@ -33,7 +33,7 @@ OpenClaw’s native background-spawn tool is **`sessions_spawn`**. Operator inte
 
 ! Gate tiers, allowed register primitives, dispatch detection, and review Approaches are defined **only** in shipped skill + engine text:
 
-- Swarm capability matrix + launch path: [`skills/deft-directive-swarm/SKILL.md`](../skills/deft-directive-swarm/SKILL.md) (Phase 3 runtime detection / launch adapter).
+- Swarm capability matrix + launch path: [`skills/deft-directive-swarm/SKILL.md`](../skills/deft-directive-swarm/SKILL.md) (thin skill: detect + route table) and OpenClaw adapter [`skills/deft-directive-swarm/references/host-openclaw.md`](../skills/deft-directive-swarm/references/host-openclaw.md) (Step 2f launch, worktree-before-spawn #2929, phase handoff #2934, parent-monitor tool-first after announce #2943). Skill text remains source of truth.
 - PR babysit / shepherd / watch: [`skills/deft-directive-review-cycle/SKILL.md`](../skills/deft-directive-review-cycle/SKILL.md) → **Review Monitoring**.
 - Provider-neutral dispatch envelope: [`templates/agent-prompt-preamble.md`](../templates/agent-prompt-preamble.md).
 - Review-owner lease: `task review-monitor:register` / `task verify:review-monitor` (only `--platform-primitive` values those commands accept in your install).
@@ -117,6 +117,36 @@ OpenClaw agents often act under a **bot / service identity** (e.g. `ape-deft`-cl
 
 ---
 
+
+---
+
+## Swarm on OpenClaw (#2929 / #2934 / #2943)
+
+! For **parallel** swarm leaves on OpenClaw:
+
+1. Create worktrees (or consume a worktree-map) **before** any `sessions_spawn`.
+2. Set each worker cwd to that worktree — not the shared repo root.
+3. Prefer `task swarm:launch` + manifest; DIY multi-leaf `sessions_spawn` without worktree prep is forbidden.
+
+! After a coding cohort completes, dispatch the next phase with a **real tool call in the same turn**, or write explicit terminal status (`blocked` / `awaiting-human` / `done`). Do not end on narrative-only “I will spawn…”.
+
+### Parent-monitor after `subagent_announce` (#2943)
+
+OpenClaw parents can lock into a **text-only repetition hang** after thin leaf completions: the model regenerates the same “checking worktrees / open PRs next” sentence with **zero tool calls** until length cap or abort. Subagents may still be healthy; only the parent appears hung.
+
+! After any leaf completion event (`subagent_announce` / parent-push completion), the parent’s **first response** MUST be **tool-first** or **yield**:
+
+1. **Tool-first ground-truth batch** — one same-turn tool batch that inspects reality (`gh` PR/issue status, `git` / worktree status, or file/xBRIEF state), **or**
+2. **`sessions_yield`** (or host equivalent yield) — leave the turn steerable without narrating unfinished work.
+
+⊗ Open the first response after announce with multi-sentence progress-only prose (“Two leaves look unfinished…”, “Checking worktrees next…”, “Implementing both myself…”) and **zero** tool calls / yield.
+
+! **Thin DONE = failed leaf:** a completion without PR URL / merge evidence (and without a structured `BLOCKED` / `FAILED` terminal) is **not** success. Treat as failed: re-dispatch or take over after the ground-truth batch. Do not celebrate thin DONE as shipped.
+
+~ Prefer structured completion fields when present (`prUrl`, `mergeStatus`, `emptyDiff`); never model free-text thin DONE as success.
+
+Full rules: [`skills/deft-directive-swarm/references/host-openclaw.md`](../skills/deft-directive-swarm/references/host-openclaw.md), thin swarm SKILL hard-gates, and [`templates/agent-prompt-preamble.md`](../templates/agent-prompt-preamble.md) §11. This page does not fork a second source of truth.
+
 ## Anti-patterns
 
 - ⊗ Main-session `gh` poll + **cron** as the default babysit path when the installed skill offers a Tier 1 / background monitor.
@@ -124,6 +154,8 @@ OpenClaw agents often act under a **bot / service identity** (e.g. `ape-deft`-cl
 - ⊗ Treating `content/platforms/` hardware packs as the home for agent-host OpenClaw guidance.
 - ⊗ Substituting host-native review theater for `deft-directive-review-cycle` on Deft-managed repos.
 - ⊗ Claiming this doc alone makes `sessions_spawn` a shipped register/matrix primitive — that is epic skill/engine work (#2875 / #2876).
+- ⊗ Multi-sentence progress-only first response after `subagent_announce` with zero tools / yield (#2943 text-repetition hang).
+- ⊗ Treating thin DONE (no PR URL / merge evidence) as success (#2943).
 
 ---
 
@@ -134,4 +166,5 @@ OpenClaw agents often act under a **bot / service identity** (e.g. `ape-deft`-cl
 - [skill-pin-policy.md](./skill-pin-policy.md) — always-pin process skills (includes review-cycle)
 - [`skills/deft-directive-review-cycle/SKILL.md`](../skills/deft-directive-review-cycle/SKILL.md)
 - [`skills/deft-directive-swarm/SKILL.md`](../skills/deft-directive-swarm/SKILL.md)
+- [`skills/deft-directive-swarm/references/host-openclaw.md`](../skills/deft-directive-swarm/references/host-openclaw.md) — OpenClaw swarm adapter
 - [`templates/agent-prompt-preamble.md`](../templates/agent-prompt-preamble.md)

package/docs/product-signal.md

@@ -6,6 +6,8 @@ Phase 1 consented product-improvement signal under epic #2603 (#2693). Defaults
 
 Trusted-org repos (`deftai/*`, plus `DEFT_VALUE_AUTOENABLE_ORGS`) receive a **one-time** install/upgrade force-on (#2822): local value feedback and product-signal enable flip ON on the next `directive update`, with a durable `.deft-cache/org-force-on-v2822.json` marker so later intentional opt-out is not fought forever. Outbound product signal still requires personal consent (D17).
 
+**Verify-on-skip (#2903):** the marker stores the pre-migration policy snapshots (key-order independent). If `PROJECT-DEFINITION` force-on is discarded (working-tree-only write lost beside a deposit PR, `git restore`, branch without PD) while the marker remains, the next `directive update` sees current typed blocks still equal those snapshots and **re-applies** force-on. Snapshot equality is company policy: restoring the exact pre-migration disabled shape is treated as incomplete migration (not a durable opt-out). An intentional post-migration disable must **differ** from the previous snapshot (and from the force-on shape), or use `task policy:clear-value-feedback`, or root `.no-deft-directive`. Outbound product signal still requires personal consent (D17) even when local enable is forced on. Manual recovery remains `rm -f .deft-cache/org-force-on-v2822.json && deft update`, then commit `xbrief/PROJECT-DEFINITION.xbrief.json`.
+
 ```bash
 task product-signal:enable -- --confirm
 task policy:show -- --field=productSignal

package/docs/writing-ste100.md

@@ -0,0 +1,53 @@
+# Controlled English for docs and issues
+
+Directive uses a short **controlled-English** bar for product docs, issues, PRs, and agent-facing prose.
+
+**ASD-STE100** is Simplified Technical English (aerospace controlled language). Here it means a practical subset. It is not a certification program.
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `≉`=SHOULD NOT, `⊗`=MUST NOT, `?`=MAY.
+
+Tracker: [#2927](https://github.com/deftai/directive/issues/2927).
+
+---
+
+## Rules (minimum bar)
+
+1. **Short sentences.** Prefer one main idea per sentence.
+2. **Active voice.** Prefer "The agent runs the gate" over "The gate is run by the agent."
+3. **One term = one meaning.** Keep product terms stable (`xbrief`, host, skill pack, swarm, deposit). Do not reuse one word for two concepts.
+4. **First-use definitions.** Define a tech term the first time it appears when the reader may not know it.
+
+! Apply these four rules to **new and touched** prose that maintainers or agents author for this repo.
+
+~ Prefer clarity over ceremony. When a product term already has a glossary or category note, reuse that meaning.
+
+---
+
+## Where it applies
+
+- Agent and maintainer communications about Directive
+- Product docs (including `content/docs/` and related guides)
+- GitHub issues, PRs, and review comments that maintainers or agents author here
+- Skill and strategy prose where clarity matters for agent load
+
+---
+
+## Non-goals
+
+- ⊗ Full ASD-STE100 dictionary compliance or formal STE tooling certification
+- ⊗ A big-bang rewrite of the historical issue corpus
+- ⊗ A red CI style gate in v1 that blocks merges on style nitpicks
+
+Process expectation only: follow the bar by default. Do not invent a merge blocker from this page alone.
+
+---
+
+## Related
+
+| Issue | Role |
+|-------|------|
+| [#740](https://github.com/deftai/directive/issues/740) | Plain-English UX pass (closed; interview-focused) |
+| [#865](https://github.com/deftai/directive/issues/865) | Every rule is a token tax |
+| [#847](https://github.com/deftai/directive/issues/847) | Lean context first |
+| [#2484](https://github.com/deftai/directive/issues/2484) | Progressive disclosure for large skills |
+| [#2905](https://github.com/deftai/directive/issues/2905) | Category terms (host vs skill pack vs practice layer) |

package/glossary.md

@@ -40,7 +40,7 @@ These concepts originate from [GSD](https://github.com/gsd-build/get-shit-done)
 
 **Fractal summaries** — Hierarchical memory compression: task summaries compress into feature summaries, which compress into release summaries. Iron rule: never summarize summaries — regenerate each level from the level below + code state. See [context/fractal-summaries.md](./context/fractal-summaries.md).
 
-**Specification vbrief** — The source-of-truth pattern for project intent. `./vbrief/specification.vbrief.json` is the canonical specification file; `SPECIFICATION.md` is a generated artifact rendered from it. The spec vbrief is created via interview (`templates/make-spec.md`), reviewed by the user, approved (`status: approved`), then rendered. Never edit the `.md` directly — edit the source vbrief. See [vbrief/vbrief.md](./vbrief/vbrief.md).
+**Specification xbrief** — The source-of-truth pattern for project intent. `./xbrief/specification.xbrief.json` is the canonical specification file; `SPECIFICATION.md` is a generated artifact rendered from it. Never edit the `.md` directly — edit the source xbrief. See [vbrief/vbrief.md](./vbrief/vbrief.md) (schema reference; public name is xBRIEF).
 
 **Stub detection** — Scanning completed code for incomplete implementations: `TODO`/`FIXME` markers, `return null`/`return {}`/`pass` placeholders, functions under ~8 lines returning hardcoded values. See [verification/verification.md](./verification/verification.md).
 
@@ -48,98 +48,96 @@ These concepts originate from [GSD](https://github.com/gsd-build/get-shit-done)
 
 **Zero discovery calls** — The principle that agents should never spend tokens figuring out where they are, what exists, or what was decided. All of that should be pre-assembled in context before the task starts. See [resilience/context-pruning.md](./resilience/context-pruning.md).
 
-**Brownfield mapping** — Structured reconnaissance of an existing codebase before modifying it. Produces four artifacts: STACK (languages, frameworks, infrastructure), ARCHITECTURE (layers, entry points, data flow), CONVENTIONS (naming, patterns, file layout), and CONCERNS (tech debt, fragile areas, missing tests). See [strategies/map.md](./strategies/map.md). Invoked via `/deft:run:map`.
+**Brownfield mapping** — Structured reconnaissance of an existing codebase before modifying it. Produces four artifacts: STACK, ARCHITECTURE, CONVENTIONS, and CONCERNS. See [strategies/map.md](./strategies/map.md). Invoked via `/deft:run:map`.
 
 **Integration checking** — Cross-feature wiring verification that every export has a matching import, every API endpoint has a consumer, auth gates protect all required routes, and at least one E2E flow traces through the full stack. See [verification/integration.md](./verification/integration.md).
 
-**Plan checking** — Pre-execution verification of a plan across four dimensions: (1) coverage — every acceptance criterion maps to at least one task, (2) completeness — every task has a verify command, (3) wiring — cross-feature dependencies declared in boundary maps, (4) scope — task count within sanity thresholds (2–3 ideal, 5+ requires split). See [verification/plan-checking.md](./verification/plan-checking.md).
+**Plan checking** — Pre-execution verification of a plan across four dimensions: coverage, completeness, wiring, scope. See [verification/plan-checking.md](./verification/plan-checking.md).
 
-**Scope sanity** — A threshold-based guard against over-scoped plans that degrade context window quality. 1–3 tasks per plan is ideal; 4 is a warning; 5+ is a blocker requiring plan split. Part of plan checking dimension 4. See [verification/plan-checking.md](./verification/plan-checking.md).
+**Scope sanity** — Threshold guard against over-scoped plans (1–3 tasks ideal; 5+ requires split). Part of plan checking. See [verification/plan-checking.md](./verification/plan-checking.md).
 
-**Spec delta** — A scoped document capturing how a change modifies existing requirements. Shows new requirements and was/now diffs for modified ones. Linked to the baseline spec via vBRIEF `references` with `type: "x-vbrief/plan"`. Lives in `history/changes/<name>/specs/`. See [context/spec-deltas.md](./context/spec-deltas.md). Invoked as part of `/deft:change`.
+**Spec delta** — Scoped document capturing how a change modifies existing requirements. Linked via xBRIEF `references`. Lives in `history/changes/<name>/specs/`. See [context/spec-deltas.md](./context/spec-deltas.md).
 
-**Verify command** — A concrete, runnable command specified per task that confirms the task's work is correct (e.g., `pytest tests/test_auth.py`, `curl localhost:8080/health`). Required by plan checking dimension 2 (completeness). Tasks without a verify command fail the plan check.
+**Verify command** — A concrete, runnable command per task that confirms the work is correct. Required by plan checking dimension 2.
 
 ---
 
 ## Framework Design Terms
 
-Terms describing how directive itself is structured and governed.
-
 **Bounded context** (framework sense) — A file or directory in directive that owns a specific rule domain. Other files reference it; they do not restate its rules. Prevents rule drift through duplication. Examples: `coding/hygiene.md` owns hygiene rules; `coding/testing.md` owns universal testing standards.
 
 **Rule ownership** — The principle that each concept in directive has exactly one owning file. When multiple files need to reference the concept, they link to the owner rather than duplicating the rule.
 
 **Ubiquitous language** — The shared, precisely defined vocabulary used consistently across all directive files and by all agents. This glossary is the source of truth. Synonyms and informal restatements of defined terms are not permitted.
 
+**Coding host** (host) · **skill pack** · **practice layer** · **orchestrator** — Buyer/evaluator category map. Canonical aid: [docs/CATEGORY.md](../docs/CATEGORY.md) (#2905).
+
 ---
 
 ## Hygiene Terms
 
-Terms used in [coding/hygiene.md](./coding/hygiene.md).
-
-**Hygiene** — The ongoing practice of keeping a codebase clean beyond what individual changes introduce: removing dead code, eliminating circular dependencies, surfacing hidden errors, and removing legacy/deprecated code paths. Distinct from per-change quality gates, which only govern new code.
+**Hygiene** — Keeping a codebase clean beyond what individual changes introduce: dead code, circular deps, hidden errors, legacy paths. See [coding/hygiene.md](./coding/hygiene.md).
 
-**Dead code** — Code that is defined but never executed: unused functions, unreachable branches, stale feature flags, and commented-out blocks. Distinct from deprecated code, which may still execute on a legacy path.
+**Dead code** — Code defined but never executed.
 
-**Error hiding** — Any pattern that prevents an error from being observed by the caller or operator: empty catch blocks, silent fallbacks, returning neutral/zero values to mask failures, or log-and-continue without surfacing the error upstream.
+**Error hiding** — Patterns that prevent errors from being observed by the caller or operator.
 
-**Legacy code** — A code path, implementation, or feature flag that has been superseded but not removed. Identified by markers such as `LEGACY`, `COMPAT`, `OLD_`, `TODO: remove`, or the presence of two parallel implementations without a migration path.
+**Legacy code** — Superseded path not yet removed.
 
-**Circular dependency** — An import cycle where module A depends on module B which depends (directly or transitively) on module A. Indicates architectural coupling that prevents modular testing and signals a layering violation.
+**Circular dependency** — Import cycle A→B→A (directly or transitively).
 
 ---
 
 ## GSD → Deft Term Mapping
 
-For readers familiar with [GSD](https://github.com/gsd-build/get-shit-done):
-
 | GSD Term | Deft Term | Notes |
 |----------|-----------|-------|
 | Milestone | **Release** | Shippable version |
 | Slice | **Feature** | Vertical capability with demo sentence |
 | Task | **Task** | Same — add "fits in one context window" |
-| Must-haves | **Acceptance criteria** | With subcategories: truths, artifacts, key links |
-| Continue file | **Continue checkpoint** | `./vbrief/continue.vbrief.json` (singular) |
-| Discuss phase | **Interview** (extended) | Adds decision locking + Feynman technique |
-| Boundary map | **Contract** (at planning level) | Extension of Contract-First |
+| Must-haves | **Acceptance criteria** | truths, artifacts, key links |
+| Continue file | **Continue checkpoint** | `./xbrief/continue.xbrief.json` |
+| Discuss phase | **Interview** (extended) | decision locking + Feynman |
+| Boundary map | **Contract** (planning) | Extension of Contract-First |
 | Wave execution | **Parallel group** | Speckit `[P]`/`[S]` markers |
 | Research phase | **Research** | Already in speckit |
 
 ---
 
-## vBRIEF Lifecycle Terms (v0.20+)
+## xBRIEF Lifecycle Terms
+
+Canonical vocabulary for the xBRIEF lifecycle. **xBRIEF** / `xbrief/` is the sole public current name (#2907). **vBRIEF** is legacy — see [UPGRADING.md — xBRIEF rename](./UPGRADING.md#xbrief-rename-2034--2110--2907).
 
-Canonical vocabulary for the vBRIEF lifecycle. (Merged from the former top-level `glossary.md` during the #1875 content/ move; deduplicated to a single canonical glossary.)
+- **Scope xBRIEF** -- A durable unit-of-work record, one per feature / bug / initiative, stored as `YYYY-MM-DD-slug.xbrief.json` inside a [lifecycle folder](#xbrief-lifecycle-terms). Primary work artifact (schema detail: [vbrief/vbrief.md](./vbrief/vbrief.md)).
 
-- **Scope vBRIEF** -- A durable unit-of-work record, one per feature / bug / initiative, stored as `YYYY-MM-DD-slug.vbrief.json` inside a [lifecycle folder](#terms). Scope vBRIEFs are the primary work artifact in v0.20 (see [vbrief/vbrief.md -- Scope vBRIEFs and Lifecycle Folders](./vbrief/vbrief.md#scope-vbriefs-and-lifecycle-folders)).
+- **Lifecycle folder** -- One of five subdirectories under `xbrief/`: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`. Folder location reflects (but does not define) `plan.status`. See [vbrief/vbrief.md](./vbrief/vbrief.md).
 
-- **Lifecycle folder** -- One of the five subdirectories under `vbrief/`: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`. Folder location reflects (but does not define) `plan.status`; see [vbrief/vbrief.md -- Directory Structure](./vbrief/vbrief.md#directory-structure) and [Status-Driven Moves](./vbrief/vbrief.md#status-driven-moves).
+- **Plan-level narrative** -- A key under `plan.narratives` in an xBRIEF (e.g. `Description`, `Acceptance`, `Traces`). Plain strings only. See [vbrief/vbrief.md](./vbrief/vbrief.md).
 
-- **Plan-level narrative** -- A key under `plan.narratives` in a vBRIEF file, describing the scope/plan as a whole (e.g. `Description`, `Acceptance`, `Traces`). Plan-level narratives describe the *what and why*; see [vbrief/vbrief.md -- Narratives](./vbrief/vbrief.md#narratives).
+- **Item-level narrative** -- A narrative string under `plan.items[].narrative` for one PlanItem. Plain strings only. See [vbrief/vbrief.md](./vbrief/vbrief.md).
 
-- **Item-level narrative** -- A narrative string under `plan.items[].narrative` describing a single `PlanItem` (a task / subtask within a scope). Both plan-level and item-level narratives MUST be plain strings -- never objects (see [vbrief/vbrief.md -- Narratives](./vbrief/vbrief.md#narratives)).
+- **Filename stem** -- The portion of an xBRIEF filename before `.xbrief.json`. Scope stems: `YYYY-MM-DD-<slug>`; speckit Phase 4: `YYYY-MM-DD-ip<NNN>-<slug>`. See [vbrief/vbrief.md](./vbrief/vbrief.md).
 
-- **Filename stem** -- The portion of a vBRIEF filename before `.vbrief.json`. For scope vBRIEFs the stem follows `YYYY-MM-DD-<slug>`; for speckit Phase 4 emissions the stem is `YYYY-MM-DD-ip<NNN>-<slug>` with `NNN` zero-padded to 3 digits (see [vbrief/vbrief.md -- Filename Convention](./vbrief/vbrief.md#filename-convention)).
+- **Cross-scope dependency** -- Dependency between two scope xBRIEFs at `plan.metadata.dependencies` (array of dependency IDs). See [vbrief/vbrief.md](./vbrief/vbrief.md).
 
-- **Cross-scope dependency** -- A dependency between two scope vBRIEFs (rather than between items inside a single scope). Cross-scope dependencies live at `plan.metadata.dependencies` as an array of dependency IDs -- plan-level by design (see [vbrief/vbrief.md -- Plan-level metadata](./vbrief/vbrief.md#plan-level-metadata)).
+- **Exit Commands** -- The seven deterministic `task scope:*` commands that transition a scope xBRIEF between lifecycle folders: `scope:promote`, `scope:activate`, `scope:complete`, `scope:cancel`, `scope:restore`, `scope:block`, `scope:unblock` (see [tasks/scope.yml](../tasks/scope.yml)).
 
-- **Exit Commands** -- The seven deterministic `task scope:*` commands that transition a scope vBRIEF between lifecycle folders: `scope:promote`, `scope:activate`, `scope:complete`, `scope:cancel`, `scope:restore`, `scope:block`, `scope:unblock` (see [tasks/scope.yml](../tasks/scope.yml)). Agents MUST use these instead of moving files by hand.
+- **Origin provenance** -- A `references` entry linking a scope xBRIEF to its origin issue / ticket / user-request. Required for ingestion dedup. See [vbrief/vbrief.md](./vbrief/vbrief.md).
 
-- **Origin provenance** -- A `references` entry on a scope vBRIEF linking back to the issue / ticket / user-request that spawned it (`type: github-issue`, `jira-ticket`, or `user-request`). Required for ingestion dedup; see [vbrief/vbrief.md -- Origin Provenance](./vbrief/vbrief.md#origin-provenance).
+- **Canonical narrative key** -- Reserved plan-level keys (`Description`, `Acceptance`, `Traces`) that tooling reads by name. See [vbrief/vbrief.md](./vbrief/vbrief.md).
 
-- **Canonical narrative key** -- One of the small set of reserved plan-level narrative keys (`Description`, `Acceptance`, `Traces`) that tooling (`task roadmap:render`, swarm allocator) reads by name. See [vbrief/vbrief.md -- Scope vBRIEF narrative keys](./vbrief/vbrief.md#scope-vbrief-narrative-keys).
+- **Preparatory strategy** -- A [strategies/](./strategies/) workflow that gathers context without producing a spec directly (e.g. `research.md`, `discuss.md`, `map.md`).
 
-- **Preparatory strategy** -- A [strategies/](./strategies/) workflow that gathers context without producing a spec directly (e.g. `research.md`, `discuss.md`, `map.md`, `bdd.md`). Preparatory strategies chain into a [spec-generating strategy](#terms).
+- **Spec-generating strategy** -- A [strategies/](./strategies/) workflow that emits `xbrief/specification.xbrief.json` (and optionally scope xBRIEFs) as authoritative output.
 
-- **Spec-generating strategy** -- A [strategies/](./strategies/) workflow that emits `vbrief/specification.vbrief.json` (and optionally scope vBRIEFs) as its authoritative output (e.g. `interview.md`, `speckit.md`, `enterprise.md`, `rapid.md`, `yolo.md`).
+- **Rendered export** -- A human-readable `.md` file (`SPECIFICATION.md`, `PRD.md`, `ROADMAP.md`) generated by `task *:render` from the underlying `.xbrief.json`. Read-only views; edit the source, not the export. See [UPGRADING.md](./UPGRADING.md).
 
-- **Rendered export** -- A human-readable `.md` file (`SPECIFICATION.md`, `PRD.md`, `ROADMAP.md`) generated on demand by a `task *:render` command from the underlying `.vbrief.json` file. Rendered exports are read-only views; direct edits are overwritten on the next render (see [UPGRADING.md -- What to expect](./UPGRADING.md#what-to-expect)).
+- **Source of truth** -- The file tooling treats as authoritative. Current: `.xbrief.json` files under `xbrief/`; corresponding `.md` files are [rendered exports](#xbrief-lifecycle-terms).
 
-- **Source of truth** -- The file that tooling treats as authoritative for a given piece of information. In v0.20 the `.vbrief.json` files are the source of truth; the corresponding `.md` files are [rendered exports](#terms). Editing a rendered export does not change the source of truth -- edit the `.vbrief.json` instead.
+- **Deterministic mode** -- Interaction shape for structured questions. Every deterministic-mode prompt MUST include `Discuss` and `Back` as the final two options (#767). Canonical rule: [`contracts/deterministic-questions.md`](./contracts/deterministic-questions.md).
 
-- **Deterministic mode** -- The interaction shape used by every Deft skill that asks the user structured questions (via `ask_user_question` single-select / multi-select) or numbered-menu prompts in skill prose. Every deterministic-mode prompt MUST include `Discuss` and `Back` as the final two numbered options (#767). The canonical rule and verbatim Discuss-pause semantic live at [`contracts/deterministic-questions.md`](./contracts/deterministic-questions.md); skill prose `!` cross-references that contract instead of duplicating the rule body.
+- **Branch-protection policy** -- Controls direct commits to master/main. Typed flag `plan.policy.allowDirectCommitsToMaster` on `xbrief/PROJECT-DEFINITION.xbrief.json` (#746); default `false`. Surfaces: skill guards, `task verify:branch` + hooks (#747), CI `branch-gate`. Reconfigure via `task policy:*`. Emergency: `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1`.
 
-- **Branch-protection policy** -- The Deft policy surface that controls whether direct commits to the default branch (master/main) are allowed. The typed flag is `plan.policy.allowDirectCommitsToMaster` on `vbrief/PROJECT-DEFINITION.vbrief.json` (#746); default `false` (enforce feature branches). Three enforcement surfaces back the policy: skill-level guards at the entry of `deft-directive-{swarm,review-cycle,pre-pr,release}` (#746 part C), the detection-bound `scripts/preflight_branch.py` reachable via `task verify:branch` and the `.githooks/pre-commit` + `.githooks/pre-push` hooks (#747), and the CI `branch-gate` workflow asserting `head_ref != base_ref` (#747 part E). Reconfigure via `task policy:show` / `task policy:enforce-branches` / `task policy:allow-direct-commits -- --confirm`. Emergency bypass: `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1`.
+- **Policy audit log** -- Append-only ledger at `meta/policy-changes.log` for transitions of `allowDirectCommitsToMaster` (#746 / #747).
 
-- **Policy audit log** -- One-line append-only ledger at `meta/policy-changes.log` recording every transition of `plan.policy.allowDirectCommitsToMaster`. Written by `scripts/policy_set.py` whenever `task policy:enforce-branches` or `task policy:allow-direct-commits -- --confirm` is invoked, including the actor, previous value, and any operator-supplied `--note`. Surface introduced by #746 acceptance criterion G2.
+- **vBRIEF (legacy)** -- Historical name for xBRIEF / `xbrief/` work-state. On-disk `vbrief/`, `*.vbrief.json`, `x-vbrief/*` tokens, and `vbrief:*` task aliases remain read-accepted until `deft migrate:xbrief`. ⊗ Teach vBRIEF as the current product name. Authoritative map: [UPGRADING.md — xBRIEF rename](./UPGRADING.md#xbrief-rename-2034--2110--2907).

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "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",
   "type": "module",
   "files": [
     "**/*",