@deftai/directive-content 0.86.0 → 0.87.0

package/QUICK-START.md

@@ -151,6 +151,8 @@ 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).
+
 **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

@@ -406,6 +406,7 @@ tasks:
       - verify:skill-external-fetch-gate
       - verify:contract-drift
       - verify:cursor-tier1
+      - verify:openclaw-tier1
       - verify:go-freeze
       - verify:bridge-drift
       - verify:branch
@@ -960,7 +961,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/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,5 @@ 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.

package/docs/openclaw-agent-host.md

@@ -0,0 +1,137 @@
+# 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) (Phase 3 runtime detection / launch adapter).
+- 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.
+
+---
+
+## 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).
+
+---
+
+## 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)
+- [`templates/agent-prompt-preamble.md`](../templates/agent-prompt-preamble.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.86.0",
+  "version": "0.87.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.",
   "type": "module",
   "files": [