@deftai/directive-content 0.88.0 → 0.90.0

package/contracts/host-lifecycle-duties.md

@@ -0,0 +1,96 @@
+# 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).
+
+### OpenClaw pin wire (doctor) (#3001)
+
+Session-first hosts still need a **bridge** from the installed content package into the host workspace skills root. On OpenClaw:
+
+- ! `deft doctor` detects missing always-pins under `$OPENCLAW_STATE_DIR/workspace/skills` or `~/.openclaw/workspace/skills` when OpenClaw signals are present.
+- ! `deft doctor --fix` deposits/links the four always-pins (build, pre-pr, review-cycle, swarm) into that main skills root (symlink preferred; copy fallback). Non-destructive of other user skills.
+- ⊗ Rewrite every `workspace-*` crew seat by default — multi-seat only with `deft doctor --fix --openclaw-all-agents`.
+
+Full operator steps: [`../docs/openclaw-agent-host.md`](../docs/openclaw-agent-host.md) § Wire skills into OpenClaw workspace.
+
+## 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

@@ -17,11 +17,21 @@ Typed session-level enforcement under `plan.policy.runtimeAuthority` in `xbrief/
 
 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` for direct-write tools
-3. Runtime authority `scopes.push` / `scopes.merge` for Shell/Bash and classifiable MCP tools (#2711)
+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).
 
@@ -77,4 +87,4 @@ deft policy:show --field=runtimeAuthority
 
 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 residual, #2711, #2948 Wave 0.
+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/inter-run-learning.md

@@ -0,0 +1,27 @@
+# Inter-run learning surface
+
+**Load when:** designing or implementing cross-session agent memory, hot/cold budgets, frozen snapshots, or retargeting memory pattern issues under epic #2741.
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `⊗`=MUST NOT.
+
+## Pointer
+
+Canonical contract (Wave 0 design for [#2742](https://github.com/deftai/directive/issues/2742), epic [#2741](https://github.com/deftai/directive/issues/2741)):
+
+**[docs/analysis/2026-07-31-inter-run-learning-surface.md](../../docs/analysis/2026-07-31-inter-run-learning-surface.md)**
+
+That note inventories Directive memory SoTs (`USER.md` Personal, lessons/packs, triage cache, session ritual, decision/continue), defines **hot / cold / operator-gated** tiers with freeze and budget rules, lists non-goals, and retargets #688, #978, #832–#835, and #479.
+
+## Rules (discovery only)
+
+- ! Prefer the design note vocabulary over free-floating “agent-memory contracts” or Mem0-default RAG for Directive core.
+- ! Attach Wave 1+ pattern work (#832–#834, #835, #479) to the tiers and SoTs in the design note.
+- ⊗ Revive `x-vbrief/agent-memory` / `swarm/agent-memory.md` (#2700 solution shape abandoned).
+- ⊗ Implement mid-session mutable always-in hot memory without freeze-at-session-start.
+
+## Related
+
+- Session ritual: `content/commands.md` § Session-start ritual  
+- Continue checkpoints: `content/resilience/continue-here.md`  
+- Prompt assembly (freeze mechanism): `content/patterns/prompt-assembly-layer-ordering.md`  
+- Skills Index: `REFERENCES.md` → When Managing Context or Long Tasks

package/docs/openclaw-agent-host.md

@@ -111,12 +111,50 @@ OpenClaw agents often act under a **bot / service identity** (e.g. `ape-deft`-cl
 
 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.
+3. **Wire always-pin skills into the OpenClaw workspace** (see next section) so session `available_skills` can load cold-start paths.
+4. 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).
+5. For multi-story parallel work, follow **`deft-directive-swarm`** — do not hand-roll worktree orchestration outside the skill.
+6. Keep CHANGELOG / xBRIEF / branch gates the same as on Cursor or Warp; the host changes the **spawn surface**, not the Directive lifecycle.
 
 ---
 
+## Wire skills into OpenClaw workspace (#3001)
+
+OpenClaw is a **session-first** host: installing `@deftai/directive` puts pin skills in the content package / deposit, but the **main** OpenClaw workspace may still only list host-global skills until something bridges them into `~/.openclaw/workspace/skills` (or `$OPENCLAW_STATE_DIR/workspace/skills`).
+
+Always-pins required for cold-start / process gates ([skill-pin-policy.md](./skill-pin-policy.md) #2508):
+
+- `deft-directive-build`
+- `deft-directive-pre-pr`
+- `deft-directive-review-cycle`
+- `deft-directive-swarm`
+
+### Detect
+
+When OpenClaw signals are present (`OPENCLAW` / `DEFT_PROBE_OPENCLAW` / `DEFT_AGENT_RUNTIME=openclaw`, or `~/.openclaw` / `OPENCLAW_STATE_DIR`), `deft doctor` checks the **main** workspace skills root for those four pins.
+
+- **Miss:** warning + remediation `deft doctor --fix` (plus pointers to this page and [host-lifecycle-duties.md](../contracts/host-lifecycle-duties.md)).
+- **Hit:** success line — OpenClaw host pins present.
+
+### Fix
+
+```text
+deft doctor --fix
+```
+
+Doctor links (preferred) or copies the four pin directories from the installed content package (`@deftai/directive-content` / `content/skills/…`) into the main OpenClaw skills root. It does **not** delete other user skills (e.g. a local `vbrief` skill stays). Divergent same-named directories are left alone unless you pass `--force` or confirm on a TTY.
+
+After a successful wire: **restart the OpenClaw gateway or start a new session** so host `available_skills` refreshes.
+
+### Multi-seat / crew workspaces
+
+Default scope is **main only** (`workspace/skills`). Crew seats (`workspace-scotty`, `workspace-pike`, …) are **not** rewritten unless you opt in:
+
+```text
+deft doctor --fix --openclaw-all-agents
+```
+
+⊗ Silent rewrite of every `workspace-*` seat without that flag.
 
 ---
 
@@ -156,6 +194,8 @@ Full rules: [`skills/deft-directive-swarm/references/host-openclaw.md`](../skill
 - ⊗ 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).
+- ⊗ Assuming package install alone populates OpenClaw `available_skills` — wire main workspace pins via `deft doctor --fix` (#3001).
+- ⊗ Auto-enumerating every `workspace-*` seat without `--openclaw-all-agents` (#3001).
 
 ---
 

package/events/README.md

@@ -14,7 +14,7 @@ data-file-convention check follow-up
 
 - `registry.json` — single source of truth for every event name, category,
   payload contract, detector / emission pointer, and consumer pointers.
-  Lists 5 `detection-bound` events and 9 `behavioral` events (14 total).
+  Lists 5 `detection-bound` events and 11 `behavioral` events (16 total).
 - `registry.schema.json` — schema validating the registry's shape, including
   the required `category` enum (`detection-bound` | `behavioral`).
 - `event-record.schema.json` — schema for individual emitted event records.

package/events/registry.json

@@ -238,6 +238,42 @@
         "packages/core/src/events/attribution-ledger.ts",
         "(deferred) task deft:feedback:file / deft-directive-feedback skill (#1709 child 5)"
       ]
+    },
+    {
+      "name": "session:start",
+      "category": "behavioral",
+      "description": "Mutation session:start ceremony finished (cold or re-arm). Local process-cost observability for ceremony wall-clock (#2994 / WWYSYDH pilot). Always-on best-effort local JSONL; not gated on valueFeedback; no remote upload.",
+      "trigger": "packages/core/src/session/process-cost.ts::emitSessionStartProcessCost from packages/core/src/session/session-start.ts after cold or re-arm ceremony completes and ritual state is written.",
+      "payload": {
+        "ceremony_tier": "string enum -- cold | rearm",
+        "duration_ms": "integer -- total ceremony wall-clock milliseconds",
+        "exit_code": "integer -- 0 when ready, non-zero when a quick step failed",
+        "ready": "boolean (optional) -- true when exit_code is 0",
+        "optional_network": "boolean (optional) -- whether optional network steps ran (#2991)",
+        "steps": "array (optional) -- { name, duration_ms, skipped? } per major phase from session:start --json"
+      },
+      "consumers": [
+        "packages/core/src/session/process-cost.ts -- emit helper",
+        "packages/core/src/session/session-start.ts -- cold + re-arm completion call sites",
+        "content/commands.md § Process-cost events -- WWYSYDH ceremony label mapping (#2994)"
+      ]
+    },
+    {
+      "name": "session:ritual-blocked",
+      "category": "behavioral",
+      "description": "PreToolUse denied a mutation tool because the gated session ritual was not ready (missing/stale/invalid). Local process-cost / friction signal for ceremony blocks (#2994). Always-on best-effort local JSONL; not gated on valueFeedback; no remote upload.",
+      "trigger": "packages/core/src/session/process-cost.ts::emitSessionRitualBlockedProcessCost from packages/core/src/hooks/dispatcher.ts::inspectMutationGates when inspectSessionRitual returns non-zero or throws (ritual-not-ready deny path).",
+      "payload": {
+        "tool_name": "string -- host tool name that was denied",
+        "code": "string -- always ritual-not-ready for this event",
+        "recovery_tier": "string enum (optional) -- cold | rearm -- preferred recovery path (#2992)",
+        "detail": "string (optional) -- one-line inspect message (not the full recovery instruction)"
+      },
+      "consumers": [
+        "packages/core/src/session/process-cost.ts -- emit helper",
+        "packages/core/src/hooks/dispatcher.ts -- PreToolUse ritual deny path",
+        "content/commands.md § Process-cost events -- WWYSYDH ceremony label mapping (#2994)"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.88.0",
+  "version": "0.90.0",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "license": "MIT",
   "type": "module",