@deftai/directive-content 0.85.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.85.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": [

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

@@ -566,6 +566,24 @@
       "source": "Issue #1102. On 2026-05-12 a refinement session (PR #1098) filed #1099 proposing to add .github/dependabot.yml without checking master -- the file already existed (landed via #1070 / v0.29.1). #1099 closed as a stale duplicate the same day; #1100 re-filed as the additive-delta scope.",
       "body": "**Source:** Issue #1102. On 2026-05-12 a refinement session (PR #1098) filed #1099 proposing to add `.github/dependabot.yml` without checking master -- the file already existed (landed via #1070 / v0.29.1). #1099 closed as a stale duplicate the same day; #1100 was re-filed as the additive-delta scope.\n\n**Key insight:** A one-second `git ls-tree origin/master -- <path>` (or `gh api repos/{owner}/{repo}/contents/{path}` without a clone) existence check before filing an add-a-file issue prevents this whole close-and-refile class. If the path already exists, the issue must be scoped to the DELTA vs the on-master state, not the original 'deposit this file' framing.\n\n**Canonical encoding (strongest-applicable layer):** the `!` MUST rule + `\u2297` anti-pattern live in the canonical issue-filing skill `skills/deft-directive-gh-slice/SKILL.md` (Step 5 + Anti-Patterns), cross-referenced from `skills/deft-directive-refinement/SKILL.md` Phase 1. Deterministic shape-coverage: `packages/core/src/content-contracts/skills/gh_slice_prefiling_master_diff.test.ts`.\n\n**Cross-references:** #1070 (`.github/dependabot.yml` originally landed), #1099 (stale-duplicate filing, closed), #1100 (corrected additive-scope refile), PR #1098 (refinement session that surfaced the pattern)."
     },
+    {
+      "id": "monitor-as-implementer-after-false-done-2026-07",
+      "title": "Swarm monitor must not self-implement after false DONE (2026-07)",
+      "date": "2026-07",
+      "issue_refs": [
+        "#2843",
+        "#1880",
+        "#2824"
+      ],
+      "tags": [
+        "agent-experience",
+        "harness",
+        "agent-safety",
+        "swarm"
+      ],
+      "source": "Issue #2843. Recurrence in cohort-2026-07-26-hooks-appsec-coverage after #2839 PR #2842: a drive-to:merge-ready Cursor leaf exited DONE while Greptile P1 still blocked merge-ready, pulling the cohort monitor into inline fix batches and pr:watch.",
+      "body": "**Source:** Issue #2843. Recurrence in cohort-2026-07-26-hooks-appsec-coverage after #2839 PR #2842.\n\n**Failure mode:** A `drive-to: merge-ready` leaf emits `DONE` before `task pr:merge-ready` passes. The host reports terminal success; the swarm monitor reads Phase 5 \"monitor MAY run review-cycle itself\" and starts inline Greptile fixes — violating Gap D (monitor conversation no longer interactive) and Gap C (lifecycle ownership splits mid-cycle).\n\n**Rule:** Preamble §11 reserves `DONE` for merge-ready on `drive-to: merge-ready` envelopes; mid-cycle exits MUST be `BLOCKED` with PR, HEAD SHA, blocker class, worktree path, and `REDISPATCH_OK`. Swarm Phase 5 + review-cycle skill require Tier 1 monitors to background-dispatch ONE continuation leaf instead of self-implementing.\n\n**Canonical encoding:** `templates/agent-prompt-preamble.md` §11; `skills/deft-directive-swarm/SKILL.md` Phase 5 blocked-leaf continuation + completion-notification decision tree; `skills/deft-directive-review-cycle/SKILL.md` Review Monitoring.\n\n**Cross-references:** #1880 (Gap C/D doctrine), #2824 (REDISPATCH_OK / false-alive), #2843."
+    },
     {
       "id": "win32-ps-safe-multiline-git-gh-bodies-2026-07",
       "title": "Windows PowerShell: safe multi-line git/gh bodies (2026-07)",
@@ -583,6 +601,39 @@
       ],
       "source": "Issue #2646 (absorbs #1417). Dogfood on Cursor + Windows PowerShell 2026-07-19 while filing/updating the issue.",
       "body": "**Source:** Issue #2646 (absorbs #1417). On Windows PowerShell, agents fail when authoring multi-line git/gh payloads via bash heredocs, `<<<` redirection, inline multi-line `--body` flags, or multi-line PS here-strings in the agent command box. Host/agent shell wrappers can also rewrite shell-embedded commit/issue prose before PowerShell executes.\n\n**Failure modes:** (1) Bash heredoc / `<<<` under PowerShell -- parse abort before any gh call. (2) Long inline `gh issue create` / `gh pr create --body` -- argument splitting, angle-bracket parse errors, silent truncation (#1417). (3) Host wrapper injection into shell-embedded git/gh prose (Co-authored-by / Made-with fragments) corrupting PATCH payloads. (4) Partial fixes (escaping, backtick-n, PS here-strings) reintroduce #240 or #798 damage.\n\n**Rule:** never put multi-line markdown inline in a PowerShell agent command. Write a UTF-8 (no BOM) temp file in the OS temp directory via editor/Write/Node (outside the shell), then pass `git commit -F`, `gh --body-file`, or `gh api --input`. Verify posted bodies after PATCH when wrappers may have corrupted earlier attempts.\n\n**Canonical encoding (strongest-applicable layer):** rule body in `content/scm/github.md` \u00a7 Windows PowerShell: safe multi-line git/gh bodies (#2646); agent pointer in `templates/agent-prompt-preamble.md` \u00a7 3.9 and `templates/agents-entry.md` Contextual guardrails lazy-load trigger.\n\n**Cross-references:** #240 (Warp here-string splitting), #798 (PS 5.1 encoding safe write path), #1417 (long gh --body quoting, closed duplicate), #2646."
+    },
+    {
+      "id": "release-check-failure-file-and-merge-2026-07",
+      "title": "Release Phase 1 check failure \u2014 file-and-merge, not inline hotfix (2026-07)",
+      "date": "2026-07",
+      "issue_refs": [
+        "#2859",
+        "#2858"
+      ],
+      "tags": [
+        "agent-experience",
+        "release",
+        "documentation"
+      ],
+      "source": "Issue #2859. During v0.86.0 Phase 1, task check failed on #2858-class hang; orchestrator led with inline hotfix / skip-ci instead of file \u2192 PR \u2192 merge \u2192 resume.",
+      "body": "**Source:** Issue #2859 (recurrence during v0.86.0 cut; concrete hang #2858).\n\n**Failure mode:** Release Phase 1 `task check` / `ci:local` fails on a fixable defect. Agent offers inline hotfix, timeout tweaks, or untracked `--skip-ci` before filing a tracked issue and driving merge-ready.\n\n**Rule:** Pause the cut. File GitHub issue \u2192 xBRIEF \u2192 feature branch \u2192 PR \u2192 merge \u2192 confirm check green \u2192 resume Phase 1. `--allow-skip-ci=#N` stays incident-only with a tracked issue (Phase 4); never the first suggestion for a shippable bug.\n\n**AGENTS.md bulk rejected:** Always-pin expansion in AGENTS.md / agents-entry for this reminder was considered and rejected (#2859).\n\n**Canonical encoding:** `skills/deft-directive-release/SKILL.md` \u00a7 Fixable check failure \u2014 file-and-merge before resume (#2859); `docs/RELEASING.md` \u00a7 Fixable check failure during release."
+    },
+    {
+      "id": "release-coverage-debt-hatch-2026-07",
+      "title": "Release Step 5 coverage hairline \u2014 open-issue ledger hatch (2026-07)",
+      "date": "2026-07",
+      "issue_refs": [
+        "#2866",
+        "#2573",
+        "#2618"
+      ],
+      "tags": [
+        "agent-experience",
+        "release",
+        "documentation"
+      ],
+      "source": "Issue #2866. Hairline branch-coverage misses at release Step 5 repeatedly interrupted cuts; operator approved file-#N-then-hatch when no open debt issue exists.",
+      "body": "**Source:** Issue #2866 (operator-approved 2026-07-27).\n\n**Failure mode:** `task release` Step 5 fails on Vitest branch coverage below 85% (hairline miss). Agent treats it like a #2859 file-and-merge product defect or attempts consecutive `--allow-coverage-debt` soft-passes while a prior hatch debt issue is still open.\n\n**Rule (release-scoped only):** Hatch applies only when branches is the sole metric below 85%. Query open issues via `coverage-debt in:title,body` and `allow-coverage-debt in:body`; file new debt with title prefix `coverage-debt:` and both markers in body. If no open debt \u2192 file `#N`, continue with `--allow-coverage-debt=#N` (PowerShell: `N` or `\"#N\"`). If open debt from prior hatch \u2192 restore all four metrics \u2265 85% before reusing hatch. Multi-metric misses, hangs, and failing tests stay under #2859 file-and-merge.\n\n**Canonical encoding:** `skills/deft-directive-release/SKILL.md` \u00a7 Step 5 branch-coverage threshold \u2014 open-issue ledger hatch (#2866); `docs/RELEASING.md` \u00a7 Coverage debt hatch during release."
     }
   ]
 }