@deftai/directive-content 0.86.0 → 0.88.0

package/QUICK-START.md

@@ -151,6 +151,12 @@ Read and follow `../AGENTS.md`. This starts the normal first-session flow (user
 
 **Upgrade pointer:** Users moving between framework versions should also read [UPGRADING.md](./UPGRADING.md) in the repo root for the version-by-version guide. For a multi-version "big jump", start at its [big-jump triage entry point](./UPGRADING.md#big-jump-triage--multi-version-upgrades-start-here), which names which version buckets apply and in what order. An agent on a big jump that hits both a stale AGENTS.md and pre-cutover artifacts should follow [Case G+H](#case-gh--combined-stale-agentsmd--pre-cutover-migration-big-jump-one-session) above to complete both in one session.
 
+**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,9 +403,11 @@ tasks:
       - verify:rule-ownership
       - verify:biome-config
       - verify:content-manifest
+      - verify:license-sync
       - verify:skill-external-fetch-gate
       - verify:contract-drift
       - verify:cursor-tier1
+      - verify:openclaw-tier1
       - verify:go-freeze
       - verify:bridge-drift
       - verify:branch
@@ -960,7 +962,7 @@ tasks:
           CLI_ARGS: "{{.CLI_ARGS}}"
 
   triage:show:
-    desc: "Per-issue triage detail (#1128 / D11). -- task triage:show -- <N> [--repo OWNER/NAME]"
+    desc: "Per-issue triage detail (#1128 / D11, #2890). -- task triage:show -- <N> [--format=default|operator] [--repo OWNER/NAME]"
     cmds:
       - task: triage-queue:show
         vars:

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/conventions/references.md

@@ -46,7 +46,7 @@ The following `type` values are recognized by deft's tooling and skills. Any
 semantics.
 
 - `x-vbrief/plan` — reference to another vBRIEF plan (epic→story or story→epic links, also the canonical v0.5 enum value)
-- `x-vbrief/github-issue` — a GitHub issue (the origin of an ingested scope vBRIEF, or a related issue)
+- `x-vbrief/github-issue` — a GitHub issue (the **primary** origin of an ingested scope vBRIEF). `task issue:emit` treats any `plan.references[]` entry whose type matches `github-issue` / `x-vbrief/github-issue` / `x-xbrief/github-issue` as **already tracked** and SKIPs create. Do **not** add related-only issue refs with this type when the brief still needs emit for its primary origin — keep related links in narratives / PR body / `Refs #N` prose instead (#2881 related-ref footgun).
 - `x-vbrief/github-pr` — a GitHub pull request (implementing PR, related PR, or superseded PR)
 - `x-vbrief/jira-ticket` — a Jira ticket (origin provenance for Jira-backed projects)
 - `x-vbrief/user-request` — a direct user request captured verbatim (no external tracker ID)

package/docs/getting-started.md

@@ -139,3 +139,9 @@ Full command reference for every triage and cache verb lives in [`commands.md`
 ## Agent Configuration
 
 <!-- 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

@@ -0,0 +1,170 @@
+# Agent host: OpenClaw
+
+Consumer/operator guide for running **Deft Directive** under **OpenClaw** persistent-memory agents (`ape-deft`-class and peers).
+
+This is an **agent-host** adapter note — not a product-UI design standard (those live under `interfaces/` for CLI/TUI/REST/Web) and not a hardware platform pack (`platforms/` is Atari/Unity-class). OpenClaw sits in the same mental model as Warp, Cursor, and Grok Build: a runtime that can host Directive skills, swarm launch, and PR review-monitors.
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `≉`=SHOULD NOT, `⊗`=MUST NOT, `?`=MAY.
+
+Epic spine: [#2874](https://github.com/deftai/directive/issues/2874). This doc is the discoverable operator path for [#2877](https://github.com/deftai/directive/issues/2877).
+
+---
+
+## Who this is for
+
+- Operators running OpenClaw as the always-on agent runtime and wanting Directive lifecycle (xBRIEF, triage, swarm, review-cycle) without re-deriving host mappings every session.
+- First-session agents that need a short answer to: **“What is babysit on OpenClaw?”**
+- Maintainers comparing host primitives across Warp / Cursor / Grok Build / OpenClaw.
+
+If you are installing Directive for the first time, start at [QUICK-START.md](../QUICK-START.md) or [getting-started.md](./getting-started.md), then return here for host-specific expectations.
+
+---
+
+## Mental model (host class)
+
+| Host | Host-native background spawn (typical) | Directive review-monitor role |
+|------|----------------------------------------|-------------------------------|
+| Warp | `start_agent` | Approach 1 when Tier 1 |
+| Grok Build | `spawn_subagent` | Approach 1 when Tier 1 |
+| Cursor | `Task` (`run_in_background: true`) | Approach 1 when Tier 1 |
+| **OpenClaw** | **`sessions_spawn`** (optional visible) | Approach 1 when Tier 1 **in the installed skill/matrix** |
+
+OpenClaw’s native background-spawn tool is **`sessions_spawn`**. Operator intent places that tool in the **same Tier-1 role** as Warp / Grok Build / Cursor — not “interactive shell only.” Whether a given Directive **release** classifies OpenClaw as Tier 1 is decided by the **shipped** swarm matrix and review-cycle skill, not by this page.
+
+! 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) (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).
+
+! When this host guide and the installed skill/CLI disagree, **the skill and CLI win**.
+
+⊗ Invent a parallel “OpenClaw-only” review gate that bypasses `deft-directive-review-cycle`.
+
+⊗ Pass `sessions_spawn` (or any host-native name) to `task review-monitor:register -- --platform-primitive …` unless that exact token is listed in the **installed** skill/CLI help.
+
+---
+
+## First-session: babysit on OpenClaw
+
+**Operator says:** “babysit this PR”, “shepherd”, “watch the PR”, or equivalent PR-shepherding intent on a Deft-managed repo (`.deft/core/` present, or framework checkout with Directive skills).
+
+### Executable path (any installed Directive version)
+
+1. ! Load **`deft-directive-review-cycle`** — not a host-global babysit skill and not a freestyle `gh` poll loop in the main session ([#2261](https://github.com/deftai/directive/issues/2261) class).
+2. ! Select monitoring Approach using **runtime detection in that skill** (and the swarm Phase 3 matrix when relevant). Do not invent a host path outside the skill.
+3. ! If the installed skill reports Tier 1, use **Approach 1** (background review-monitor) and register with a **`--platform-primitive` value accepted by the installed CLI**.
+4. ! Prefer deterministic wait language from the skill (`task pr:watch` when the consumer Taskfile exposes it) over inventing sleep/cron loops.
+5. ⊗ Treat **OpenClaw cron alone** as Approach 1. Cron / scheduler re-invocation is fallback territory when a live background review-monitor cannot be spawned per the skill — not a substitute for Approach 1 when the skill says spawn is available.
+6. ⊗ Block the main session with long `gh` poll + sleep when the skill’s Tier 1 / background path is available (#1880 Gap D / incident class on epic #2874).
+
+### Operator expectation: babysit → `sessions_spawn` (epic target)
+
+Epic [#2874](https://github.com/deftai/directive/issues/2874) sets the **intended** OpenClaw mapping:
+
+> On OpenClaw, PR babysit/shepherd/watch routes into **`deft-directive-review-cycle` Approach 1** using the host-native **`sessions_spawn`** (prefer **visible** when Control UI is the control plane), not main-session `gh` poll + cron.
+
+That expectation is for operators and first-session agents to **find and remember**. It becomes the **executable** default only when the installed Directive version’s swarm matrix + review-cycle skill name OpenClaw / `sessions_spawn` as Tier 1 Approach 1 (sibling work):
+
+| Issue | Lands |
+|-------|--------|
+| [#2875](https://github.com/deftai/directive/issues/2875) | Swarm matrix + `openclaw` descriptor + verify gate |
+| [#2876](https://github.com/deftai/directive/issues/2876) | Review-cycle Approach 1 + register primitive for OpenClaw `sessions_spawn`; cron ≠ Approach 1 |
+| [#2879](https://github.com/deftai/directive/issues/2879) | Poller/preamble templates + heartbeat mapping |
+| [#2878](https://github.com/deftai/directive/issues/2878) | Consumer `pr:watch` / official gh fallback |
+
+~ After those slices are in your Directive version, follow the **updated skill text** end-to-end (including any new register token). Until then, still open review-cycle on babysit intent and use only primitives the **current** skill accepts — while keeping the `sessions_spawn` expectation as the design north star (do not freestyle a weaker path when you could wait for / upgrade to the OpenClaw-capable release).
+
+This section is a **discovery map**. Authoritative Approaches, register primitives, and exit predicates live only in skill files and CLI.
+
+---
+
+## Control plane preference (operator signal)
+
+When multiple OpenClaw surfaces are available:
+
+| Surface | Role |
+|---------|------|
+| **Control UI** | Default **control plane** for long infra work and **visible** subagent watch (review-monitors, swarm leaves). |
+| **Telegram** (or similar mobile chat) | Remote/mobile chat; not the preferred surface for long blocking polls. |
+| **TUI** | Break-glass local terminal — use when UI/channels are unavailable. |
+
+~ Prefer **visible** background review-monitors when Control UI is in play so the operator can see the subagent without freezing the parent conversation. Once OpenClaw Approach 1 is skill-backed, that usually means visible `sessions_spawn`.
+
+! Keep long-running review-monitors and implementation leaves on independent/background dispatch so the parent session stays interactive (Gap D — see preamble and review-cycle skill).
+
+---
+
+## Bot identity vs human GitHub identity
+
+OpenClaw agents often act under a **bot / service identity** (e.g. `ape-deft`-class) that is distinct from the human operator’s GitHub login.
+
+- ! Assume the agent’s `gh` auth may be a bot account with different permissions than the human (merge rights, org SSO, protected-branch rules).
+- ~ Prefer bot-owned comments, review-monitor leases, and PR status updates when the bot is the active worker; do not silently switch identities mid-loop.
+- ⊗ Mandate merge rights for bot accounts in this doc — merge policy is per-repo ops, not an OpenClaw host requirement (epic #2874 out of scope).
+- ~ When a merge or ruleset action requires a human, surface a clear handoff instead of retrying with the wrong identity.
+
+---
+
+## Directive-for-OpenClaw-users (onboarding blurb)
+
+1. Install / refresh Directive like any other host ([QUICK-START.md](../QUICK-START.md), `directive init` / `directive update`).
+2. Confirm skills resolve under the deposit (consumer: `.deft/core/.agents/skills/…`; framework checkout: `content/skills/…`).
+3. On first PR shepherding request, open **`deft-directive-review-cycle`** and follow its Review Monitoring section for **your** install. Remember the epic expectation: OpenClaw → Approach 1 via `sessions_spawn` once skill wiring ships (#2875 / #2876).
+4. For multi-story parallel work, follow **`deft-directive-swarm`** — do not hand-roll worktree orchestration outside the skill.
+5. Keep CHANGELOG / xBRIEF / branch gates the same as on Cursor or Warp; the host changes the **spawn surface**, not the Directive lifecycle.
+
+---
+
+
+---
+
+## 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.
+- ⊗ Inventing skill gate semantics or unregistered `--platform-primitive` values in operator docs instead of linking to shipped `SKILL.md` / CLI text.
+- ⊗ 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).
+
+---
+
+## See also
+
+- [QUICK-START.md](../QUICK-START.md) — install / AGENTS.md refresh entry
+- [getting-started.md](./getting-started.md) — orientation lifecycle
+- [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) |