@deftai/directive-content 0.87.0 → 0.89.0

package/contracts/host-lifecycle-duties.md

@@ -0,0 +1,86 @@
+# Host lifecycle duty list (#2968 / A3)
+
+Stable moments where a **host** (IDE deposit or session-first workspace) must load
+Directive’s portable brain (Skills Index, pins, main.md / AGENTS.md) before freestyle
+tools. Short duty list — not a multi-host platform RFC.
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `≉`=SHOULD NOT, `⊗`=MUST NOT, `?`=MAY.
+
+Related: OpenClaw cold-start adapter
+[`../skills/deft-directive-swarm/references/host-openclaw.md`](../skills/deft-directive-swarm/references/host-openclaw.md) (A7),
+skill pins [`../docs/skill-pin-policy.md`](../docs/skill-pin-policy.md) (#2508),
+session routing in AGENTS.md (#2176), cold-start algorithm orientation (#609).
+
+## Two host families
+
+| Family | Typical hosts | How Directive loads |
+|--------|---------------|---------------------|
+| **1 — IDE / repo deposit** | Cursor, VS Code-class | Open folder → installer rails / deposit → agent already on project root |
+| **2 — Session / workspace / companion** | OpenClaw, Buzz-class | Agent awake in workspace home; host skill list ≠ Directive Skills Index until bridged |
+
+! Directive **writes** host adapters. Host vendors expose extension points; they are not required to ship Directive adapters.
+
+⊗ Wait on Cursor / OpenClaw / Buzz vendors to implement our adapter for cold-start correctness.
+
+## Duty table (stable moments)
+
+| Moment | Duty |
+|--------|------|
+| **Session start** | Resolve **project root** (WSL / dual-path SoT when applicable). Know how to reach the **Skills Index** (consumer: `.deft/core/REFERENCES.md`; framework: `content/REFERENCES.md` or root `REFERENCES.md`). Optional session ritual when mutation intent applies (`session:start` / `#1149`). Confirm Deft alignment when USER.md is present (#2176). |
+| **Deft-shaped user intent** | Route via **Skills Index / skill trigger path before freestyle host tools**. Prefer **pinned Directive skills** over same-named host skills (e.g. Cursor `/review` or host “review” ≠ `deft-directive-article-review` / `deft-directive-review-cycle`). |
+| **Tool boundary** (optional) | Classifier hook / write-intent path when installed (#2967 A2 class). Graph append when installed (#2966 A1 class). Not required for this first cut. |
+| **Turn / session end** (optional) | Evidence flush / MEMORY note of which skill path ran, for APE continuity. |
+
+### Deft-shaped intent (examples)
+
+Treat as Deft-shaped when the user asks for skills, review, triage, swarm, build, pre-PR, article review, consumer-repo Directive work, xBRIEF lifecycle, or equivalent process verbs.
+
+! On Deft-shaped intent: scan Skills Index (Level-0) → open matching `SKILL.md` (Level-1) **before** freestyle `gh` / shell / host-global skill improvisation.
+
+! Prefer always-pin Directive skills (`deft-directive-build`, `deft-directive-pre-pr`, `deft-directive-review-cycle`, `deft-directive-swarm`) when the work type matches (#2508).
+
+⊗ Answer a Deft-shaped request with only host-global tools or same-named host skills when a Directive skill is in the Skills Index for that intent (2026-07-30 miss class: “use review skill” + URL never entered `deft-directive-article-review`).
+
+## Family-1 reference: Cursor deposit
+
+Cursor / project-deposit remains the **family-1 reference adapter**:
+
+1. Open repo at project root.
+2. Deposit / AGENTS managed section points at Skills Index and pins.
+3. Session routing loads main → USER → PROJECT-DEFINITION before mutation.
+
+### Cursor parity checklist
+
+| Check | Status |
+|-------|--------|
+| Project root = opened workspace folder | **Pass** (host default) |
+| Skills Index reachable from AGENTS managed section | **Pass** when deposit current |
+| Always-pin names for process skills | **Pass** when AGENTS pin section present (#2508) |
+| Plan-mode / product action bypass of skill path | **Known gap** — plan-mode and host product actions can skip skill load (#1708 class); fix on Cursor adapter only when cold-start or skill route still fails |
+| Same-named host skill vs Directive skill | **Known gap** — prefer Directive pin / Skills Index match over host `/review`-class labels |
+
+## Family-2 first ship: OpenClaw (A7)
+
+OpenClaw cold-start steps live in the swarm host adapter (source of truth for spawn + cold-start on that host):
+
+[`../skills/deft-directive-swarm/references/host-openclaw.md`](../skills/deft-directive-swarm/references/host-openclaw.md) § Cold-start.
+
+Operator map (non-authoritative discovery): [`../docs/openclaw-agent-host.md`](../docs/openclaw-agent-host.md).
+
+## Extension notes (out of first ship)
+
+| Host / class | Note |
+|--------------|------|
+| **Buzz / Pi** | Session-first family-2 peers. Implement a dedicated `host-*.md` adapter when scheduled; reuse this duty table. Do not invent full platform abstraction in this cut. |
+| **Warp / Grok Build** | Family-1-adjacent spawn hosts; deposit + AGENTS still own session orientation. Swarm launch adapters are separate from cold-start Skills Index load. |
+
+## Anti-patterns
+
+- ⊗ Freestyle host tools first on Deft-shaped intent, then maybe open a skill.
+- ⊗ Treat host skill inventory (`available_skills`, workspace skill folders) as the Directive Skills Index without a bridge.
+- ⊗ Assume IDE deposit behavior on a session-first host that started outside the project root.
+- ⊗ Abstract multi-host portability RFC with zero OpenClaw (or second-family) behavior change.
+
+## Acceptance pointer
+
+Issue [#2968](https://github.com/deftai/directive/issues/2968): A3 = this contract; A7 = OpenClaw cold-start in `host-openclaw.md`. First cut closes when both surfaces land and `task verify:openclaw-tier1` stays green.

package/contracts/human-origin-authz.md

@@ -0,0 +1,109 @@
+# Human-origin approval + UAT mutation lease (#2944 / #2948 Wave 1)
+
+Layer **L1–L2** of the layered authorization stack (epic #2948). Composes with
+`runtimeAuthority` (L3, #1394 / #2711) and does **not** re-implement Shell push/merge
+matchers.
+
+Threat model: **aligned agent** confusion — the agent believes self-authored
+xBRIEF/lifecycle/dispatch state is permission. Credential-compromised local-file
+forgery remains #983-class out of scope.
+
+## Defaults
+
+| Surface | Default | Notes |
+| --- | --- | --- |
+| UAT lease | inactive | No Wave 1 denials until operator starts UAT |
+| Human-origin grants | none | Minted only via `deft authz:grant` |
+
+## Human-origin grant
+
+Stored under `.deft/authz/grants/<id>.json`.
+
+Accepted `origin.kind` values:
+
+- `operator-cli` (mint path: `deft authz:grant`)
+- `operator-session` (future interactive approval)
+- `human-event` (external human event ref)
+
+**Rejected** (never satisfy an implementation-approval gate):
+
+- `agent-lifecycle`, `xbrief-status`, `dispatch-envelope`, `allocation-context`,
+  `self-asserted`, `agent-authored`
+- any grant with actor `agent` / `agent:*` / `self`
+
+Structural binding (not crypto/HMAC):
+
+- `scope.planRef`, `repo`, `branch`, `worktree`
+- `scope.surfaces` — path globs (including user-visible UI)
+- `scope.operations` — `edit` \| `push` \| `pr` \| `merge` \| `settings` \| `deployment` \| `issue_mutation`
+- `scope.storyIds` / `issueIds`
+- `scope.cohortId` — **required** for product mutations while UAT is active
+- `semantics.expiresAt` / `singleUse`
+
+## Fail-closed UAT mutation lease
+
+Start: `deft authz:uat-start -- --campaign <id>`  
+Suspend: `deft authz:uat-suspend`  
+Inspect: `deft authz:show`
+
+While UAT is **active** (and was started with human-origin provenance):
+
+| Attempt | Result without matching fix-cohort grant |
+| --- | --- |
+| Product / UI direct write | **deny** |
+| `git push` / classifiable push MCP | **deny** |
+| `gh pr create` / ready / edit | **deny** |
+| `gh pr merge` / classifiable merge MCP | **deny** |
+| settings / deploy heuristics | **deny** |
+| Test execution (`vitest`, `pnpm test`, …) | **allow** |
+| Issue filing (`gh issue create`) | **allow** |
+| Evidence / defect capture writes (`xbrief/proposed/**`, `**/evidence/**`, `incidents/**`) | **allow** |
+
+Approving one named fix cohort **does not** clear the UAT lock or authorize adjacent
+failures or other operations (e.g. edit grant ≠ push).
+
+## Enforcement order (PreToolUse)
+
+1. Ritual / scope / read-only / spawn gates
+2. **Authz Wave 1** — UAT lease + human-origin grant (`#2944`)
+3. Runtime authority path + `scopes.edits` / `scopes.push` / `scopes.merge` (#1394 / #2711)
+
+Denials name the missing permission and the human action required (typically
+`deft authz:grant -- --cohort <id> --operations … --surfaces …`).
+
+Audit appends to `.deft/authz/audit.jsonl` with:
+
+`humanApprovalRef`, `approvedScope`, `attemptedOp`, `path`, `result`, `code`, `campaignId`.
+
+## CLI
+
+```bash
+deft authz:show
+deft authz:uat-start -- --campaign uat-2026-07-30
+deft authz:grant -- --operations edit --surfaces 'apps/web/src/**' --cohort fix-defect-12 --stories 2944
+deft authz:uat-suspend
+deft authz:revoke -- grant-…
+```
+
+## Explicit non-goals (siblings)
+
+| Concern | Owner |
+| --- | --- |
+| Shell/MCP push/merge matchers alone | #2711 |
+| Slash-command intent ceiling / human merge | #1193 |
+| Path write fence schema | #516 / #2443 |
+| AFK session-auth / release verbs | #1095 — see `content/contracts/closed-verb-authz.md` (Wave 4; consumes these grants) |
+| HMAC / hardware-keyed grants | non-goal for MVP |
+
+## Wave 4 consumers
+
+Release-class closed verbs (`release-cut`, `release-publish`, `release-rollback`)
+evaluate via `evaluateClosedVerb` and accept only:
+
+- `DEFT_ALLOW_<VERB>=1` ephemeral bypass, or
+- a **human-origin** grant from this store (templates: `deft authz:grant -- --template release-publish --target <ver>`)
+
+They do not mint grants of their own. Walk-away finish-loop product: #871 (Wave 5) —
+`authz:grant --template finish-loop` and `content/contracts/finish-loop.md`.
+
+Refs #2948 #2711 #1394 #1378 #2176 #2402 #1095.

package/contracts/intent-ceiling.md

@@ -0,0 +1,44 @@
+# Intent ceiling — slash-command containment, hotfix classifier, human merge (#1193)
+
+Wave 2 of the layered authorization stack (#2948). Complements human-origin grants (#2944) and runtimeAuthority (#2711 / #1394).
+
+## R1 — Slash-command intent containment
+
+When a session is originated by a slash command, that command is the **only** authorized verb for the session.
+
+| Surface | Behavior |
+|---------|----------|
+| Env | `DEFT_SESSION_SLASH_VERB` (e.g. `/github-issue`, `/build`) |
+| Preflight | `task xbrief:preflight` fails when the verb is non-implement |
+| Hooks | PreToolUse denies implement/push/merge for non-implement verbs |
+| Pure API | `evaluateIntentCeiling({ sessionVerb, requestedOp })` in `@deftai/directive-core/policy` |
+
+**Implement verbs:** `/build`, `/ship`, `/ship-hotfix`, `/swarm`, `/implement` (plus free-text #810 action verbs when no slash provenance).
+
+**Non-implement (contained):** `/github-issue`, `/triage`, `/refine`, `/discuss`, `/research`, and unknown stems (fail closed for lifecycle escalation).
+
+## R2 — Hotfix classifier
+
+Typed `plan.policy.hotfixCriteria` (`maxLines` default 10, `maxFiles` default 2, `forbiddenPathGlobs`).
+
+Pure `evaluateHotfixEligibility(input)`:
+
+- **Eligible → propose `hotfix-candidate` only** (agent never promotes to `hotfix`)
+- Pure revert always qualifies
+- Small fix within limits, restores green, no new deps/exports/schema
+- **Never:** refactor, new handler/route, export surface change, forbidden paths (Dockerfile, fly.toml, `.github/workflows/**`, migrations, auth/secrets)
+
+## R3 — Human merge gate
+
+Typed `plan.policy.requireHumanMerge` (default **true** when `autoDeployOnMerge` is true).
+
+| Surface | Behavior |
+|---------|----------|
+| Merge preflight | `task pr:wait-mergeable-and-merge` refuses agent merge when ON |
+| `verify:branch` | Advisory note when ON |
+| Branch protection | Setup docs: ≥1 human reviewer when ON |
+| Session-start | Disclosure: `[deft policy] Human merge gate is ON …` |
+
+**Override:** `task policy:allow-bot-merge -- --confirm` (capability-cost disclosure + audit log) or `DEFT_ALLOW_BOT_MERGE=1`.
+
+Inspect: `task policy:show --field=requireHumanMerge` / `--field=hotfixCriteria`.

package/contracts/path-write-fence.md

@@ -0,0 +1,128 @@
+# Path write fence (#516 / #2443 / #2948 Wave 3)
+
+Unified **write-scope** enforcement for agents: project path policy and per-story
+`file_scope` share one evaluation model. There is no third parallel `writeScope`
+schema with its own matcher.
+
+## Source of truth
+
+| Layer | Where declared | Role |
+| --- | --- | --- |
+| **Project** | `plan.policy.runtimeAuthority` in `xbrief/PROJECT-DEFINITION.xbrief.json` | Session-level `allowPaths` / `denyPaths` + scopes (`edits` / `push` / `merge`) |
+| **Story** | `plan.metadata.swarm.file_scope` on the active running xBRIEF | Per-story allow globs (swarm readiness already uses this list) |
+| **Legacy alias** | `writeScope` on `plan.metadata` or `plan.metadata.swarm` | Read-time normalize to `file_scope` + deny globs only — **not** a second engine |
+
+**Evaluation SoT (code):**
+
+1. `resolveWriteFence(projectPolicy, storyFileScope?)` builds one `RuntimeAuthorityPolicy`
+2. `evaluateRuntimeAuthorityPath` / `evaluateRuntimeAuthorityDirectWrite` decide allow/deny
+
+## Intersection rules
+
+- **Empty project `allowPaths` when enabled** → all paths allowed until a story narrows them
+- **Empty story `file_scope`** → project policy only
+- **Story alone** (project `runtimeAuthority.enabled: false`) → story fence still enables path checks for direct writes
+- **Both non-empty** → path must match **project allow** *and* **story file_scope** (AND)
+- **`denyPaths` always win** (project denys + any denys from normalized `writeScope.deny`)
+
+## Runtime enforcement
+
+When a fence is active, PreToolUse direct writes (Write / Edit / StrReplace / …) **fail closed**
+for out-of-fence paths after ritual / scope / read-only / human-origin authz gates.
+
+Deny reasons are stable and name the fence source:
+
+- `write fence project allowPaths (source: project)` or `project+story`
+- `write fence story file_scope (source: story)` or `project+story`
+- `write-fence denyPaths (source: …)`
+
+Inspect project policy:
+
+```bash
+deft policy:show --field=runtimeAuthority
+```
+
+### Active-story seam
+
+The hook dispatcher loads `file_scope` from the implementation-eligible active xBRIEF
+path when `inspectActiveScope` reports one. Residual gaps (document, not silent):
+
+- Host / worktree cannot identify the active story → story layer omitted; project fence still applies
+- Multiple active artifacts → first preflight-eligible path wins (same as scope gate)
+- Story JSON unreadable → story layer fail-open; project fence still applies
+
+Shell/MCP push/merge scopes remain project-only (`runtimeAuthority.scopes`); they are not
+re-scoped by `file_scope`.
+
+## Skill behavior (build / swarm)
+
+When a project or active-story fence is set:
+
+- **build** and **swarm** workers MUST treat out-of-fence Write/Edit as refused (PreToolUse deny
+  or equivalent product check)
+- Prefer declaring intended paths in `plan.metadata.swarm.file_scope` before autonomous loops
+- ⊗ Do not invent a second write-scope schema or dual matcher beside `resolveWriteFence` +
+  `evaluateRuntimeAuthority*`
+
+## writeScope alias (compatibility)
+
+```json
+{
+  "plan": {
+    "metadata": {
+      "writeScope": {
+        "allow": ["src/**", "tests/**"],
+        "deny": [".env", "secrets/**"]
+      }
+    }
+  }
+}
+```
+
+Loaders map this to `file_scope` + deny globs at read time. If both `file_scope` and
+`writeScope.allow` are present, **`file_scope` wins** for the allow list; `writeScope.deny`
+still merges into denyPaths.
+
+## Example
+
+```json
+// PROJECT-DEFINITION
+{
+  "plan": {
+    "policy": {
+      "runtimeAuthority": {
+        "enabled": true,
+        "allowPaths": ["packages/**", "src/**", "xbrief/**"],
+        "denyPaths": [".env", "secrets/**"],
+        "scopes": { "edits": true, "push": false, "merge": false }
+      }
+    }
+  }
+}
+
+// Active story swarm block
+{
+  "plan": {
+    "metadata": {
+      "swarm": {
+        "file_scope": [
+          "packages/core/src/policy/**",
+          "content/contracts/path-write-fence.md"
+        ]
+      }
+    }
+  }
+}
+```
+
+With both set, a write to `packages/core/src/policy/write-fence.ts` is allowed;
+`src/index.ts` is denied (outside story); `secrets/x` is denied (deny wins).
+
+## Related
+
+- Contract: `content/contracts/runtime-authority.md` (#1394 / #2711)
+- Human-origin / UAT: `content/contracts/human-origin-authz.md` (#2944)
+- Intent ceiling: `content/contracts/intent-ceiling.md` (#1193)
+- Program: #2948 Wave 3
+
+Refs #516, #2443, #2948, #1394.

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,20 +10,58 @@ 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
 
 Gitignore-style globs via the shared `matchPath` helper (`src/**`, `**/AGENTS.md`, etc.). Paths are normalized to project-relative POSIX before matching.
 
+## Unified write fence (#516 / #2443 / #2948 Wave 3)
+
+Path checks for direct writes go through **one** evaluation SoT:
+
+1. `resolveWriteFence(projectPolicy, storyFileScope?)` intersects this project policy with the active story’s `plan.metadata.swarm.file_scope` (optional `writeScope` alias normalizes at read-time — not a second engine)
+2. `evaluateRuntimeAuthorityPath` / `evaluateRuntimeAuthorityDirectWrite` decide allow/deny
+
+Rules: empty project `allowPaths` when enabled = all paths until story narrows; empty story scope = project only; **denyPaths always win**; when both allow layers are non-empty, a path must match **both**. Full contract: `content/contracts/path-write-fence.md`.
+
 ## Evaluation order (PreToolUse)
 
 1. Ritual / scope / read-only / spawn gates (existing #2438 / #1185 stack)
-2. Runtime authority path + `scopes.edits` (this policy)
+2. **Human-origin authz / UAT lease** (#2944 Wave 1) — when UAT is active, product mutations require a named fix-cohort human-origin grant (see `content/contracts/human-origin-authz.md`). Composes with this policy; does not re-own Shell matchers.
+3. Runtime authority path + story write fence + `scopes.edits` for direct-write tools (`resolveWriteFence` → `evaluateRuntimeAuthorityDirectWrite`)
+4. 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 +85,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; Wave 3 path fence #516 / #2443 — `content/contracts/path-write-fence.md`.

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