@deftai/directive-content 0.96.0 → 0.98.0

package/.agents/skills/deft-directive-portfolio-priority/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: deft-directive-portfolio-priority
+description: >-
+  Pre-promotion portfolio prioritization: cluster competing open RFCs/issues
+  from the local github-issue cache, emit a propose-not-apply priority brief
+  (conflict matrix, shortlist, park), with epistemic citation gates, then hand
+  off for operator dispose. Use when the operator asks for portfolio priority,
+  a priority brief, competing RFCs, or to cluster open issues.
+---
+
+Read and follow: skills/deft-directive-portfolio-priority/SKILL.md

package/Taskfile.yml

@@ -421,6 +421,9 @@ tasks:
       - verify:branch
       - verify:encoding
       - verify:forward-coverage
+      - verify:test-boundary
+      - verify:scope-provenance
+      - verify:consumer-check-contract
       - verify:vbrief-conformance
       - verify:destructive-gh-verbs
       - verify:scm-boundary
@@ -461,6 +464,9 @@ tasks:
       - verify:cache-fresh
       - verify:wip-cap
       - verify:orphan-active
+      - verify:test-boundary
+      - verify:scope-provenance
+      - verify:consumer-check-contract
       - vbrief:validate
       - verify-strategy-output
     cmds:

package/UPGRADING.md

@@ -260,26 +260,29 @@ The `deft-directive-sync` skill (and any agent following this upgrade path) MUST
 - ! Missing global CLI → remediate with `npm i -g @deftai/directive@latest` (not GitHub release-asset archaeology).
 - ! Git submodule update remains **legacy / back-compat only**; npm + `directive update` / `deft update` is the primary path.
 
-### One upgrade PR shape (#3127)
+### One upgrade PR shape (#3127 / #3193)
 
-A normal framework upgrade is **one PR**, not two stacked PRs. The deposited `deft-core-guard` (`no-mixed-core-and-app`, #1430) allowlists the upgrade co-travel unit so deposit + pin + freshness stamp land together:
+A normal framework upgrade is **one PR**, not two stacked PRs. The deposited `deft-core-guard` (`no-mixed-core-and-app`, #1430) allowlists the upgrade co-travel unit so deposit + pin + freshness stamp land together — and **content-constrains** package/lock when they co-travel with `.deft/core/**` (#3193):
 
 | Include in the upgrade PR | Why |
 | --- | --- |
 | `.deft/core/**` | Framework deposit payload |
 | Existing installer-managed deposits (`AGENTS.md`, hooks, skill stubs, slash commands, Taskfile include, `xbrief/.deft-version`, …) | Already framework-adjacent |
-| `package.json` + lockfile (`package-lock.json` / `pnpm-lock.yaml` / `yarn.lock`) when the change is the `@deftai/directive` pin (and lock follow-through) | npm pin doctor compares to deposit; part of the upgrade unit |
-| `.deft/GENERATION.json` | Live freshness stamp from `init` / `update` (#3117) |
+| `package.json` when the **only** dependency-key changes are `@deftai/directive*` under `dependencies` / `devDependencies` / `optionalDependencies` / `peerDependencies` (not scripts/settings that merely contain the substring) | npm pin doctor compares to deposit; pin unit only (#3193) |
+| lockfile (`package-lock.json` / `pnpm-lock.yaml` / `yarn.lock`) when changes are **follow-through** for that pin (Directive identity + necessary transitive/resolution lines), not unrelated direct product dependency identity | Lock follow-through for the pin unit (#3193) |
+| `.deft/GENERATION.json` | Live freshness stamp from `init` / `update` (#3117); remains path-allowlisted |
 
 | Keep out of the upgrade PR | Why |
 | --- | --- |
 | Application source, tests, product docs | True app/product work — guard still fails if mixed with `.deft/core/**` |
+| Unrelated `package.json` fields (scripts, metadata, non-Directive deps) co-travelling with deposit | Content-aware guard rejects (#3193); path allowlist alone is not enough |
+| Unrelated lock direct product dep bumps riding the pin exemption | Content-aware guard rejects (#3193) |
 | Consumer kit narrative / host prose not deposited by Directive | Not installer-managed |
 | Arbitrary playbooks, cast, features | Product scope, not upgrade |
 
-**Do not** split a routine version bump into “deposit-only” then “pin/GENERATION” PRs — that re-creates engine / deposit / pin skew between merges. **Do** keep product feature work on a separate branch/PR from the framework upgrade.
+**Do not** split a routine version bump into “deposit-only” then “pin/GENERATION” PRs — that re-creates engine / deposit / pin skew between merges. **Do** keep product feature work on a separate branch/PR from the framework upgrade. Consumers should **not** hand-roll a forked `deft-core-guard.yml` for normal upgrades — the deposited workflow already enforces pin-only + lock follow-through.
 
-Refs: [#3127](https://github.com/deftai/directive/issues/3127), [#1430](https://github.com/deftai/directive/issues/1430), [#3117](https://github.com/deftai/directive/issues/3117).
+Refs: [#3127](https://github.com/deftai/directive/issues/3127), [#3193](https://github.com/deftai/directive/issues/3193), [#1430](https://github.com/deftai/directive/issues/1430), [#3117](https://github.com/deftai/directive/issues/3117).
 
 Machine-readable skill exit line (for agents/operators):
 

package/commands.md

@@ -300,7 +300,20 @@ When the workflow needs an Approach 1 monitor, scope the Cursor leaf `stop-at: p
 - Repair missing/drifted entries: `deft update`.
 - **Refresh and opt-out (#2790, #2752):** Upgrade `@deftai/directive`, then run `deft update` to refresh all four deposits to the fast path; do not hand-edit host hook files. Set `plan.policy.hostHooks.<host>` to `false` only when you deliberately need to disable a host's Tier-1 enforcement — it is not the performance fix. When a host is opted out, `deft update` / `directive init` skip creating or re-merging Directive-managed hook entries for that host; if a prior deposit left managed entries in the file, the next update strips only those entries and preserves unrelated settings. Inspect with `deft policy:show --field=hostHooks`. Doctor and `verify:hooks-installed --scope=agent` treat opted-out hosts as healthy — they do not recommend `deft update` to repair them.
 - **Claude matcher scope:** Once `.claude/settings.json` hooks are loaded, Claude's `PreToolUse` matcher keys on tool names (`Edit`, `Write`, …), not target paths — matched tools can be gated for the whole session, including writes outside the project tree. Opt out of Claude hook deposit when that posture is unwanted.
-- **Compact re-arm (#2113 / #2992 / #2993):** Cursor `preCompact` and Claude/Grok `PreCompact`/`PostCompact` call `deft-hook --event session.compact` to mark the gated session ritual stale after context compaction/resume (`rearm_needed`). Prefer `deft session:ready` (#2993) as the one-shot recovery path. Multi-step remains valid: `deft session:start --rearm` (preferred when worktree/HEAD allow) or full `deft session:start`, then `deft verify:session-ritual -- --tier=gated`. Codex has no native compact hook — operators must re-run the mutation ritual manually after compaction.
+- **Compact re-arm + soft AGENTS re-bind (#2113 / #2992 / #2993 / #3171 / #2769):** post-compact posture is **two surfaces**:
+  - **Hard (Tier-1):** Cursor `preCompact` and Claude/Grok `PreCompact`/`PostCompact` call `deft-hook --event session.compact` to mark the gated session ritual stale (`rearm_needed`). Prefer `deft session:ready` (#2993) as the one-shot recovery path. Multi-step remains valid: `deft session:start --rearm` (preferred when worktree/HEAD allow) or full `deft session:start`, then `deft verify:session-ritual -- --tier=gated`. Soft **never** replaces or weakens hard deny for writes.
+  - **Soft:** the same hook path (and `session.start`) injects a **shared** AGENTS re-bind checklist (re-read AGENTS.md → confirm key rules → deposit integrity → summary≠SoT → operational-ask trap → mutation vs read-only). Soft fires without requiring a write tool; read-only/operational turns do **not** force full cold `session:start`. Soft never authorizes skipping the mutation ritual for writes.
+  - **Per-host matrix (#3171):**
+
+    | Host | Hard compact | Soft re-bind | Wire |
+    |------|--------------|--------------|------|
+    | **Cursor** | Yes (`preCompact`) | Required | compact `user_message` + SessionStart `additional_context` |
+    | **Claude Code** | Yes (`PreCompact`/`PostCompact`) | Required | compact + SessionStart `additionalContext` |
+    | **Grok Build** | Yes | Required (#3161 dogfood) | compact + SessionStart soft cue |
+    | **Codex** | **No** native compact | Docs + best-effort | SessionStart soft cue only; operators re-arm mutation ritual manually after compaction |
+    | **OpenClaw** | Not file-host hooks | Required | durable workspace skill `deft-directive-post-compact-rebind` via `deft doctor --fix` / init; see [openclaw-agent-host.md](./docs/openclaw-agent-host.md) |
+
+  - Shared checklist SoT: `packages/core/src/session/compact-ritual.ts` (all host deposits derive from it).
 - Codex project hooks are trust-gated by Codex. Directive can verify structural registration and command functionality, but reports trust separately as `manual-review-required` and interception as `not-directly-verified`; after an install or changed hook hash, open `/hooks` in Codex and review/approve the exact project hook commands. Runtime trust and real host interception cannot be inferred from the file or live shim probe alone.
 - Directive writes only `.codex/hooks.json`; it does not parse or modify `.codex/config.toml`. Codex can also load inline hooks from `config.toml`, so avoid defining duplicate Directive commands there or they may run more than once. See the [Codex hooks documentation](https://learn.chatgpt.com/docs/hooks).
 - The P0 hook slice does not classify shell-mediated *file* writes, richer unified-exec calls, or WebSearch by default. **Runtime authority (#1394 / #2711)** adds opt-in path allow/deny lists and graduated `scopes` (`edits`, `push`, `merge`) under `plan.policy.runtimeAuthority` — inspect with `deft policy:show --field=runtimeAuthority`. When `enabled: true`, PreToolUse denies classifiable direct-write targets outside `allowPaths` or matching `denyPaths` after ritual/scope/read-only gates; `scopes.edits` gates all direct writes. `scopes.push` / `scopes.merge` deny classifiable Shell/Bash (`git push`, `gh pr merge`) and classifiable MCP push/merge tool names; unclassifiable shell/MCP calls fail open (see `content/contracts/runtime-authority.md`). **Unified path write fence (#516 / #2443 / #2948 Wave 3):** PreToolUse also intersects project allow/deny with the active story’s `plan.metadata.swarm.file_scope` via `resolveWriteFence` (single evaluation SoT; optional `writeScope` alias normalizes at read-time only). Full contract: `content/contracts/path-write-fence.md`.
@@ -464,6 +477,8 @@ User-facing surface for the Phase 0 triage workflow and the unified content cach
 
 Directive does not guess your mix. Either you name the next units in order (**ordered plan**), or you let the ranked backlog suggest (**queue**). Labels bias the queue; they do not override an active plan.
 
+**See also (pre-promotion portfolio):** when the need is to cluster competing RFCs/issues into a propose-not-apply priority brief (not single-item queue ranking), use `skills/deft-directive-portfolio-priority/SKILL.md` (#3201 / #3198) — classify is filter-only; no SCM label writes.
+
 | Path | When | Who sets it | Bare "what's next?" means |
 |---|---|---|---|
 | **Ordered plan** | You know the next few units (A then B then stop) | `task plan-sequence:set -- --file <json>` | Current sequence entry only; exhaustion fails closed |
@@ -490,7 +505,7 @@ Directive does not guess your mix. Either you name the next units in order (**or
 - `task triage:reset -- <issue>` -- append a reset record so a candidate can be reconsidered.
 - `task triage:bulk-accept|bulk-reject|bulk-defer|bulk-needs-ac` -- apply predictable decisions over filtered cached candidates.
 - `task triage:summary`, `task triage:scope`, `task triage:scope-drift`, `task triage:subscribe`, `task triage:unsubscribe`, `task triage:classify`, `task triage:welcome`, and `task triage:smoketest` -- supporting workflow and onboarding commands.
-- `task triage:classify -- --mirror [--apply] [--include-closed] [--author LOGIN|@me] [--repo owner/name] [--batch-size N] [--delay-ms N] [--sample-limit N] [--json]` -- **Bootstrap mass-triage / Tier-1 SCM label mirror (#1423 Wave 1–2 / #3125, #3129).** Runs the existing classify engine over the github-issue cache and mirrors outcomes as labels (`triaged` idempotency marker + optional `plan.policy.triageLabelMirror.actionLabels`). **Default state filter is open-only** (opt-in `--include-closed` for closed archive stamps). Optional `--author` / `--author-mine` scopes plan/apply to matching `author.login` (AND with open-only; digest surfaces the filter) (#3129). Dry-run by default: operator digest with totals (scanned/planned/already_triaged/no_match/closed_skipped/author_skipped/errors), breakdown by **state / rule / action**, and samples (not a full dump as primary UX); `--json` includes the same aggregates. `--apply` writes via the SCM label client / repo-mutation boundary in **batches** (`--batch-size`, default 10) with **rate-limit delay** (`--delay-ms`, default 1000), reports partial failures, and is idempotent on re-run (already-`triaged` skip). Missing labels fail closed per issue with a create-label hint. **Never** calls `triage:accept` and **never** writes `proposed/` xBRIEFs. Wave 3 (agent Tier-2 comments) remains out of scope.
+- `task triage:classify -- --mirror [--apply] [--re-enrich] [--include-closed] [--author LOGIN|@me] [--repo owner/name] [--batch-size N] [--delay-ms N] [--sample-limit N] [--json]` -- **Bootstrap mass-triage / Tier-1 SCM label mirror (#1423 Wave 1–2 / #3125, #3129, #3197).** Runs the existing classify engine over the github-issue cache and mirrors outcomes as labels (`triaged` idempotency marker + optional `plan.policy.triageLabelMirror.actionLabels`). **Default state filter is open-only** (opt-in `--include-closed` for closed archive stamps). Optional `--author` / `--author-mine` scopes plan/apply to matching `author.login` (AND with open-only; digest surfaces the filter) (#3129). Dry-run by default: operator digest with totals (scanned/planned/already_triaged/no_match/closed_skipped/author_skipped/errors), breakdown by **state / rule / action**, and samples (not a full dump as primary UX); `--json` includes the same aggregates. `--apply` writes via the SCM label client / repo-mutation boundary in **batches** (`--batch-size`, default 10) with **rate-limit delay** (`--delay-ms`, default 1000), reports partial failures, and is idempotent on re-run (already-`triaged` skip). **Re-run vs re-enrich (#3124 / #3197):** default re-run keeps the one-shot stamp (`skipped_already_triaged`). After `actionLabels` / auto-classify rule / hold-marker changes, opt in with **`--re-enrich`** (still dry-run by default; pair with `--apply` to write) to re-classify already-stamped issues and plan **additive** label deltas only (v1 never removes obsolete chips; never full reconcile). Digest distinguishes `kind=first-time` vs `kind=re-enrich` planned/applied rows (`planned_kind` / `re_enrich_planned`). Missing labels fail closed per issue with a create-label hint. **Never** calls `triage:accept` and **never** writes `proposed/` xBRIEFs. Wave 3 (agent Tier-2 comments) remains out of scope.
 
 ### Cache Tasks
 

package/contracts/test-boundary.md

@@ -0,0 +1,18 @@
+# Contract: test-boundary (#3145)
+
+## Normative requirements
+
+- ! `verify:test-boundary` MUST reject recognized test files under declared `sourceRoots` when they are not under `testRoots` and not allowlisted.
+- ! Recognized patterns MUST include at least: Python `test_*.py` / `*_test.py`, C# `*Tests.cs` / `*Test.cs`, TypeScript/JavaScript `*.test.*` / `*.spec.*`, Go `*_test.go`.
+- ! When `productionMayReferenceTestRoots` is false, production source and deployment/infra scripts MUST NOT reference `testRoots` or `fixtureRoots` path prefixes.
+- ! Allow entries MUST support `kind: exception` and `kind: production-liveness` with recorded reason.
+- ! Failures MUST identify path, violated boundary, and remediation.
+- ! Defaults without authored policy MUST use warn-only discovery (`enforcementMode: warn`) for migration.
+- ⊗ Infer safety solely because a path was listed in an active xBRIEF.
+
+## Surfaces
+
+- Core: `packages/core/src/test-boundary/`
+- CLI: `deft verify:test-boundary` / `task verify:test-boundary`
+- Policy: `.deft/test-boundary.policy.json` or `plan.policy.testBoundary`
+- Docs: `content/docs/test-boundary.md`

package/docs/consumer-check-contract.md

@@ -0,0 +1,64 @@
+# Consumer check contract (`verify:consumer-check-contract`)
+
+Refs: #3145 · Related: #3070 consumer gate integrity, #1519 check:consumer · Policy: #3189 coverageDebt / checkResume
+
+## Problem
+
+A consumer could omit Directive enforcement gates from its `check` task and CI while local and CI success still looked green. Composition was not machine-checked.
+
+## Contract
+
+`task verify:consumer-check-contract` requires these gates to be defined under `tasks/verify.yml` and composed into consumer/framework check aggregates:
+
+- `verify:test-boundary`
+- `verify:scope-provenance`
+- `verify:consumer-check-contract`
+
+It fails with a concrete repair path when definitions or explicit check deps omit them. CI workflows that neither invoke the gates nor a composing entrypoint (`task check` / `deft check`) produce **warnings** by default (migration).
+
+## Repair path
+
+1. Restore deposit Taskfiles: `deft update` (includes `tasks/verify.yml`)
+2. Ensure `check:consumer` / `check:framework-source` deps list the three gates (framework source already ships this wiring)
+3. Prefer CI that runs `task check` or `deft check` rather than a partial custom graph
+
+## Relation to #3070
+
+`consumer-gate-integrity` proves Taskfile includes resolve. This gate proves the **required enforcement set** is present and composed — not merely that a random verify task exists.
+
+## Coverage-debt hatch and local check resume (#3189)
+
+Release-born hatch and suite-stamp features must not expand to consumers as silent defaults. Project policy lives under `plan.policy` in PROJECT-DEFINITION:
+
+| Field | Shape | Fail-closed when unset |
+|---|---|---|
+| `coverageDebt` | `status: unset \| decided`, `mode: off \| warn \| hatch`, `autoFile` (hatch only; default false) | mode off — no hatch soft-pass |
+| `checkResume` | `status: unset \| decided`, `localStamp: off \| on`, `ciTrustsLocalStamp: false` (fixed v1) | localStamp off; **CI never trusts a laptop stamp** |
+
+**Unset vs decided-off:** Unset keeps fail-closed *behavior* and still **nags** on interactive mutation session-start. Decided-off is quiet. Inspect with `deft policy:show --field=coverageDebt` and `--field=checkResume`. Doctor check `coverage-check-resume-policy` surfaces undecided as an **advisory skip** (never hard-fails doctor or `check:consumer`).
+
+### Skippable session nudge
+
+On interactive cold or re-arm **mutation** session-start, when either field is unset:
+
+- **Why:** long checks fail late or barely miss coverage; the project chooses fail-closed, warn, or hatch with a debt issue on **this** repo; local machines may resume a green suite at the same HEAD; CI must not trust a laptop stamp.
+- **What:** one bundled choice — **Strict** (recommended), **Hatch-aware**, or **Later** (plus Discuss / Back per #1470).
+- **Later** does **not** set `status=decided`; the next ritual nags again.
+- **Stop nag** only after Strict / Hatch-aware (preset write) or **dismiss-with-reason** (visible on policy:show / doctor).
+- Headless / CI / non-TTY: nudge is skipped (fail-open; never blocks).
+
+### Expansion gates (after decided)
+
+| Feature | Expand to consumers? | Gate |
+|---|---|---|
+| Fast-before-slow gate ordering | Yes (universal UX) | No policy wait |
+| Local suite stamp resume | When `checkResume.localStamp=on` | Local only; CI ignores |
+| Coverage hatch / auto-file | When `coverageDebt.mode=hatch` (+ optional `autoFile`) | Ledger on **this** consumer repo |
+| CI trusts local stamp | **Not v1** | Separate RFC |
+
+### Non-goals
+
+- Silent default-on hatch for consumers.
+- Auto-filing coverage-debt issues on **deftai/directive** from a consumer tree — the ledger is always **this** repo.
+- USER.md as source of truth for ship bars (personal never weakens the project bar).
+- Blocking headless CI on the nudge.

package/docs/deft-directive-disable.md

@@ -80,6 +80,12 @@ rm .deft-directive-disable
 # Start a NEW agent session
 ```
 
+## Agent self-serve ban under UAT (#3186)
+
+Operators plant and remove this flag **outside** an agent session (or with a prior human-origin grant). Under **active UAT**, PreToolUse classifies Shell writes that create `.deft-directive-disable` (and permanent opt-out `.no-deft-directive`) as **settings** and **denies** them without a human grant — same posture as `authz:grant` (#3110). Agents must not self-serve the kill-switch to bypass Write / push / PR / merge gates.
+
+Related: `policy:allow-bot-merge`, `policy:allow-direct-commits`, and `policy:disable-directive` (peers) are also settings under UAT and require a human grant.
+
 ## Non-goals (v1)
 
 - ⊗ Auto-delete `.deft/` or uninstall deposit

package/docs/delivery-attempt.md

@@ -0,0 +1,173 @@
+# Delivery-attempt circuit breaker (#3143)
+
+Deterministic pre-dispatch gate and durable attempt ledger for autonomous
+**delivery** and **operational-acceptance** loops.
+
+This is the mechanical enforcement surface for the delivery/acceptance subset of
+the dual-stop principle (#2442). Skill defaults (build / swarm / review-cycle)
+remain behavioral; hosts and orchestrators that dispatch delivery workflows
+MUST evaluate this gate before automatic retry or re-dispatch.
+
+## Module
+
+| Path | Role |
+|------|------|
+| `packages/core/src/delivery-attempt/` | Library (types, fingerprint, material-delta, ledger, evaluate, handoff) |
+| `@deftai/directive-core/delivery-attempt` | Package subpath export |
+| `.deft/delivery-attempts/` | On-disk unit ledgers (project-local) |
+
+## Pre-dispatch decisions
+
+`evaluatePreDispatch(ledger, input)` returns one of:
+
+| Decision | Meaning |
+|----------|---------|
+| `ALLOW_FIRST_ATTEMPT` | No open failure identity for the unit |
+| `ALLOW_TRANSIENT_RETRY` | Bounded retry after a transient (or under-threshold unknown) failure |
+| `ALLOW_MATERIAL_PROGRESS` | Relevant material delta addresses the failing invariant |
+| `ALLOW_OVERRIDE` / `ALLOW_RESUME` | Audited override or satisfied resume condition |
+| `DENY_DUPLICATE_ACTIVE` | Queued/running attempt already exists for the unit |
+| `BLOCK_NON_RETRYABLE` | Deterministic failure without progress |
+| `BLOCK_NO_MATERIAL_PROGRESS` | Same failure class, no relevant delta |
+| `BLOCK_REPEATED_UNKNOWN` | Identical unknown failures hit the threshold |
+| `BLOCK_ATTEMPT_BUDGET` | Failed-dispatch budget for the phase exhausted |
+| `BLOCK_ELAPSED_BUDGET` | Wall-clock budget exhausted |
+| `BLOCK_TOOL_OR_TOKEN_BUDGET` | Tool-call (or host-token when telemetried) budget exhausted |
+
+Once a **block** decision is emitted, automatic re-dispatch MUST stop until a
+declared resume condition is satisfied or an audited operator override is
+recorded. Persist the terminal handoff (`buildTerminalHandoff` /
+`formatHandoffReport`) before the worker exits.
+
+## Unit key and durability
+
+Logical unit: `scopeId + targetId + workflowId`.
+
+Counters (`failedAttemptCount`, `sameFailureCounts`, elapsed/tool/token totals)
+survive:
+
+- worker replacement / takeover
+- session restart and context compaction
+- new source revisions (fingerprint counters do **not** reset)
+
+Raw logs, credentials, and secret-bearing payloads MUST NOT be stored in the
+ledger. Failure fingerprints redact volatile ids, paths, timestamps, and
+secret-like values (`computeFailureFingerprint`).
+
+## Material progress
+
+Material progress means verifiable state changed in a way that can resolve or
+advance beyond the current failure (code/config/evidence/external-state/stage
+that **addresses** the failing invariant).
+
+Not material progress by themselves:
+
+- new revision identifiers alone
+- repeating the same dispatch
+- restating analysis
+- replacing the worker
+- compaction / session restart
+- evidence bound to an intermediate revision when evaluating a later revision
+
+## Safe defaults (`DEFAULT_DELIVERY_BUDGET_POLICY`)
+
+| Knob | Default |
+|------|---------|
+| max active (queued+running) | 1 |
+| max automatic transient retries | 1 |
+| identical unknown without progress → block | 2 |
+| failed dispatches per phase → block | 3 |
+| max elapsed seconds | 3600 |
+| max tool calls | 500 |
+| max host tokens | null (enforce only when host exposes usage **and** policy sets a cap) |
+
+Missing host token telemetry does **not** disable the circuit breaker — elapsed
+and tool-call budgets still apply.
+
+## Operator override
+
+`recordOperatorOverride` requires actor, rationale, timestamp, bounded
+`allowedAttempts`, and optional expiry. Overrides do **not** erase attempt
+history.
+
+## Skill routing
+
+| Surface | Role |
+|---------|------|
+| `main.md` Dual Stop Rule (#2442) | Principle; points here for delivery/acceptance |
+| build / swarm / review-cycle skills | Behavioral dual-stop defaults; point here for mechanical gate |
+| swarm `core-ops` / `core-phase-4` | Prompt + monitor envelopes; do not invent a second ledger |
+
+## Typical call shape
+
+Use the **locked disk APIs** for concurrent-safe begin/complete. Do not evaluate
+on a stale in-memory snapshot and then `saveUnitLedger` without the unit lock.
+
+```ts
+import {
+  beginAttemptOnDisk,
+  completeAttemptOnDisk,
+  buildFailureInfo,
+} from "@deftai/directive-core/delivery-attempt";
+
+// beginAttemptOnDisk: exclusive lock → reload → evaluatePreDispatch → begin → save
+let attempt;
+try {
+  const begun = beginAttemptOnDisk(projectRoot, {
+    scopeId,
+    targetId,
+    workflowId,
+    sourceRevision,
+    trigger: "automatic",
+    anticipatedFailure: lastFailure,
+    materialDelta: claims,
+  });
+  attempt = begun.attempt;
+} catch (err) {
+  // DENY_*/BLOCK_* — handoff already persisted when blocked
+  return;
+}
+
+// ... run workflow ...
+
+// completeAttemptOnDisk: exclusive lock → reload → complete → save
+const closed = completeAttemptOnDisk(projectRoot, {
+  scopeId,
+  targetId,
+  workflowId,
+  attemptId: attempt.attemptId,
+  status: "failed",
+  failure: buildFailureInfo({ stage, code, message, retryability }),
+});
+```
+
+Pure in-memory helpers (`evaluatePreDispatch`, `beginAttempt`, `completeAttempt`)
+remain for tests and single-threaded hosts. Multi-worker orchestration MUST use
+`beginAttemptOnDisk` / `completeAttemptOnDisk` (or `withUnitLock` around an
+equivalent sequence). Abandoned unit locks are reclaimed **only** when the owner
+PID is dead or the lock record is corrupt/unreadable. A live owner PID is never
+time-reclaimed (including long critical sections and event-loop stalls). Reclaim
+is serialized via an exclusive `*.lock.reclaim` ticket so concurrent reclaimers
+cannot unlink a live replacement lock. If a lock remains stuck after process
+death with PID reuse (or a hung live holder), delete the matching `.lock` /
+`.lock.reclaim` files under `.deft/delivery-attempts/` manually.
+
+Ledger load is **fail-closed on corruption**: a present but invalid ledger file
+throws (does not create an empty unit). Only a truly missing file creates a new
+empty ledger. Operators must repair or remove a corrupt file deliberately before
+dispatch can resume for that unit.
+
+## Observability
+
+Every evaluation emits a structured `PreDispatchDecisionEvent`
+(`decision`, `reasonCode`, retryability, fingerprint, counters, material-delta
+class, resume condition, override id). Aggregate metrics can count duplicate
+denies, deterministic blocks, and budget savings from early halt.
+
+## Non-goals
+
+- Weakening validation, review, or deploy safety gates
+- Treating every different downstream failure as the same failure
+- Preventing deliberate audited overrides
+- Provider-specific CI/CD lock-in
+- Prompt-only thrashing control (use dual-stop skill defaults for that class)

package/docs/openclaw-agent-host.md

@@ -56,7 +56,7 @@ Bodies stay **thin** (L5): frontmatter + short dispatch pointer to the same cont
 4. Opt-out: `plan.policy.openClawProductCommands: false` — removes **managed** L2 thin skills only; preserves consumer custom skills at the same slug.
 5. After deposit: **restart the OpenClaw gateway or start a new session** so `available_skills` refreshes.
 
-Always-pin skills (`deft-directive-build`, `pre-pr`, `review-cycle`, `swarm`) remain a **different** surface from L2 product commands (`/deft:directive:run:interview`, `/deft:continue`, …).
+Always-pin skills (`deft-directive-build`, `pre-pr`, `review-cycle`, `swarm`) remain a **different** surface from L2 product commands (`/deft:directive:run:interview`, `/deft:continue`, …). Soft post-compact re-bind (`deft-directive-post-compact-rebind`, #3171) is a third surface — see § Soft post-compact AGENTS re-bind below.
 
 Inspect policy:
 
@@ -66,6 +66,41 @@ deft policy:show --field=openClawProductCommands
 
 ---
 
+## Soft post-compact AGENTS re-bind (#3171 / #2769)
+
+OpenClaw is a **Family-2** session host. Soft AGENTS re-bind after compaction / long-session amnesia is **required** on OpenClaw and is **not** claimed via Cursor/Claude/Grok file-host `PreCompact` hooks alone.
+
+| Surface | OpenClaw posture |
+|---------|------------------|
+| **Hard** compact re-arm (file-host PreToolUse stale → deny writes) | **Not** provided by file-host compact hooks on OpenClaw. Mutation still requires `session:start` / `session:ready` / gated ritual via CLI/skills before gated writes. |
+| **Soft** AGENTS re-bind | **Required** durable workspace skill from the **shared checklist SoT** (`packages/core/src/session/compact-ritual.ts`). |
+
+### Checklist obligations (same SoT as file hosts)
+
+1. Re-read managed `AGENTS.md` session routing (#2176) — summary ≠ SoT.
+2. Confirm-what-you-learned (brief) in the user-visible reply.
+3. Deposit integrity: `deft` on PATH ≠ healthy `.deft/core` deposit.
+4. Summary/runbook (demo DBs, “start the app”) are hypotheses — re-verify PROJECT-DEFINITION / USER.md / local config.
+5. Operational-ask trap: “open/start/run the app” is still session-routed (#3161).
+6. Read-only → soft only; mutation → soft **plus** hard re-arm where supported. Soft **never** authorizes skipping the mutation ritual for writes.
+
+### Deposit / amnesia boundary
+
+| Step | Action |
+|------|--------|
+| Detect / fix | `deft doctor` warns when OpenClaw is detected and the managed skill is missing/stale; `deft doctor --fix` deposits it (multi-seat: `--openclaw-all-agents`) |
+| init / update | Deposits when OpenClaw signals are present (fail-closed otherwise) |
+| Skill id | `deft-directive-post-compact-rebind` under the OpenClaw workspace skills root |
+| After deposit | **Restart the OpenClaw gateway or start a new session** so skills reload |
+| Trigger | Session start / resume, gateway restart, long-session amnesia, operational asks after summary resume |
+
+⊗ Claim OpenClaw soft coverage from file-host hook deposits alone.  
+⊗ Treat “pins present” as “session ritual completed.”
+
+Shared dual-surface + five-host matrix: [commands.md](../commands.md) § Agent-host hooks → Compact re-arm + soft AGENTS re-bind.
+
+---
+
 ## Mental model (host class)
 
 | Host | Host-native background spawn (typical) | Directive review-monitor role |

package/docs/operator-log-hygiene-checklist.md

@@ -0,0 +1,57 @@
+# Operator-log hygiene checklist (#1940)
+
+Copy-paste block for **story acceptance criteria** and **probe locked
+decisions**. Full pattern:
+[`patterns/operator-log-hygiene.md`](../patterns/operator-log-hygiene.md).
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `⊗`=MUST NOT, `?`=MAY.
+
+**Load when:** building operator-facing services, adding WARN/ERROR paths
+operators triage, multi-process workers, or probing logging decisions.
+
+## Story AC / probe locked decisions (copy-paste)
+
+Use as-is in scope xBRIEF acceptance, probe locked decisions, or PR
+checklist. Mark N/A only with a one-line reason.
+
+```markdown
+### Operator-log hygiene (#1940)
+
+Legend: ! = MUST, ~ = SHOULD, ? = MAY (from patterns/operator-log-hygiene.md)
+
+- [ ] ! Terminal / completion events on **all** exit paths (success, skip,
+      timeout, supersede, cancel, failure) — not happy path only
+- [ ] ! Correlation IDs for multi-process / pool designs (job id, slot,
+      phase, parent id as applicable)
+- [ ] ! Infrastructure paths (rotation, flush-before-exit, IPC handoff,
+      boot supervision) fail-open where possible and emit structured
+      events when they degrade
+- [ ] ~ Operator-visible WARN/ERROR use a stable, queryable shape
+      (consumer-owned fields; e.g. stable event id + short operator
+      summary) — not ticket numbers alone
+- [ ] ~ Operator glossary / plain-English docs updated in the **same PR**
+      when operator-facing log lines change
+- [ ] ? Optional: wire consumer-owned validator into *your* check aggregate
+      (see docs/operator-log-hygiene-consumer-pack-stub.md) — not core default
+- [ ] Explicit non-goals respected: no assumption that core `deft check`
+      enforces this; log shape stays consumer-owned
+```
+
+## Agent rules when applying the checklist
+
+- ! MUST run this checklist before claiming "logging done" on an
+  operator-visible lifecycle path
+- ! MUST keep log field names and schemas **project-owned** unless the
+  consumer already defined them
+- ~ SHOULD attach the checklist under probe locked decisions when the plan
+  introduces or changes operator-facing logs
+- ⊗ MUST NOT invent a framework-wide required field set (`operatorSummary`,
+  etc.) from this checklist alone
+- ⊗ MUST NOT treat Product Insights (#2603) or LLM telemetry (#481) as
+  substitutes for operator-log hygiene
+
+## Related
+
+- Pattern: `content/patterns/operator-log-hygiene.md`
+- Optional consumer pack stub: `content/docs/operator-log-hygiene-consumer-pack-stub.md`
+- External case study (reference only): deftai/slizard operator-log hygiene docs and `operator-log:validate` — do not import schema into core

package/docs/operator-log-hygiene-consumer-pack-stub.md

@@ -0,0 +1,75 @@
+# Operator-log hygiene — optional consumer pack stub (#1940)
+
+Skeleton for **consumer projects** that want a ship-gate for operator-facing
+logs. Wire this into *your* check aggregate only if you opt in.
+
+Full pattern: [`patterns/operator-log-hygiene.md`](../patterns/operator-log-hygiene.md).
+Checklist: [`operator-log-hygiene-checklist.md`](./operator-log-hygiene-checklist.md).
+
+## Settled boundaries
+
+| Topic | Rule |
+|-------|------|
+| Default-on | **Off.** Directive core does not enable this for all services. |
+| Schema | **Consumer-owned.** You define fields and glossary path. |
+| Framework `deft check` | **Does not** hard-fail consumers who never opted in. |
+| External refs | SLizard `task operator-log:validate` is a **reference** only. |
+
+## Suggested Taskfile target name
+
+Prefer a project-local name so it does not imply framework ownership:
+
+```yaml
+# tasks/observability.yml (consumer-owned example — not shipped by core)
+version: "3"
+
+tasks:
+  operator-log:validate:
+    desc: Validate operator-facing log shape / glossary (consumer-owned)
+    cmds:
+      - echo "Implement inventory + schema checks for YOUR log contract"
+      # - node scripts/validate-operator-log.mjs --strict
+```
+
+Optional aliases consumers sometimes use:
+
+- `observability:validate`
+- `ops-log:check`
+
+Pick one name and keep it stable in your repo.
+
+## Validator skeleton (comments only)
+
+```js
+// scripts/validate-operator-log.mjs  (consumer-owned skeleton)
+//
+// 1. Inventory: find operator-facing log call sites (WARN/ERROR + terminal events).
+// 2. Schema: load YOUR glossary / field contract (path from project config).
+// 3. Strict mode: fail if new events lack required consumer fields.
+// 4. Exit 0 when clean; exit 1 with actionable paths when not.
+//
+// ⊗ Do not import SLizard glossary JSON as universal SoT.
+// ⊗ Do not expect @deftai/directive to ship or enforce this script.
+//
+// Reference shape (external): deftai/slizard task operator-log:validate
+```
+
+## Wire into *your* check (optional)
+
+```yaml
+# In the consumer Taskfile check aggregate — only if you want hard-fail
+tasks:
+  check:
+    deps:
+      - operator-log:validate
+      # ...other consumer gates...
+```
+
+- ! MUST document the gate as **project policy** when enabled
+- ⊗ MUST NOT claim framework `deft check` mandates this target by default
+- ? MAY keep the script warn-only until glossary coverage is good enough
+
+## Related
+
+- #1940 thin v1 — content + checklist + this stub
+- Pattern non-goals: no `plan.observability` core schema, no default-on

package/docs/scope-provenance.md

@@ -0,0 +1,54 @@
+# Approved-scope provenance (`verify:scope-provenance`)
+
+Refs: #3145 · Related: #1310, #2944 human-origin grants, #516 file scope
+
+## Problem
+
+An implementation PR could edit its own active xBRIEF to add new paths, after which one-way forward-coverage still passed. The modified xBRIEF became its own authorization source.
+
+## Contract
+
+At activation or operator approval, record an immutable **approved-scope digest** under:
+
+```text
+.deft/approved-scope/<plan-id>.json
+```
+
+Shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "xbriefRelPath": "xbrief/active/….xbrief.json",
+  "planId": "…",
+  "approvedAt": "2026-08-06T00:00:00Z",
+  "fileScope": ["packages/core/src/foo.ts"],
+  "fileScopeDigest": "<sha256 of sorted paths>",
+  "humanApproval": {
+    "kind": "operator",
+    "actor": "scott",
+    "mintedAt": "2026-08-06T00:00:00Z"
+  }
+}
+```
+
+`task verify:scope-provenance` compares the live active xBRIEF `plan.metadata.swarm.file_scope` to the digest when that xBRIEF is modified in the current change set.
+
+| Outcome | Behavior |
+| --- | --- |
+| No expansion | Pass |
+| Expansion + renewed human stamp / re-recorded matching digest | Pass |
+| Expansion without renewal | **Fail** — self-authorizing scope |
+| Modified active xBRIEF, no digest yet | **Warn** by default; `--enforce` fails closed |
+
+Agent-shaped stamps (`kind: agent`, `actor: agent:…`) never count as renewal.
+
+## Migration path
+
+1. Ship gate in warn mode (missing digests do not fail)
+2. Start recording digests on activation / promote
+3. Enable `--enforce` or project policy when ready
+
+## Remediation
+
+Re-record the approved-scope file after human review of the expanded `file_scope`. Editing the xBRIEF alone does not authorize new implementation paths.