@deftai/directive-content 0.96.0 → 0.97.0

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/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`.

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,27 @@
+# Consumer check contract (`verify:consumer-check-contract`)
+
+Refs: #3145 · Related: #3070 consumer gate integrity, #1519 check:consumer
+
+## 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.

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.

package/docs/test-boundary.md

@@ -0,0 +1,43 @@
+# Test / source boundary (`verify:test-boundary`)
+
+Refs: #3145 · Related: #1310 forward-coverage, testing layout guidance
+
+## Problem
+
+Directive accepted test harnesses, fixtures, and smoke orchestration under production-owned roots (`src/**`, `infra/**`, `Tools/**`, …) while gates stayed green. Placement guidance was prose-only.
+
+## Contract
+
+`task verify:test-boundary` / `deft verify:test-boundary` enforces a typed policy:
+
+| Field | Meaning |
+| --- | --- |
+| `sourceRoots` | Production-owned path globs |
+| `testRoots` | Allowed test roots |
+| `fixtureRoots` | Fixture roots |
+| `testFilePatterns` | Conventional test basenames (`test_*.py`, `*Tests.cs`, `*.test.ts`, `*.spec.ts`, …) |
+| `productionMayReferenceTestRoots` | Default `false` — production must not reference test/fixture roots |
+| `allow` | Narrow exceptions (`kind: exception` or `production-liveness`) |
+| `enforcementMode` | `warn` (migration/discovery) or `enforce` |
+
+## Policy sources (first wins)
+
+1. `--policy <path>`
+2. `.deft/test-boundary.policy.json`
+3. `plan.policy.testBoundary` in `xbrief/PROJECT-DEFINITION.xbrief.json`
+4. **Defaults** (conventional roots + patterns, `enforcementMode: warn`)
+
+## Migration path
+
+1. Run with defaults (warn-only): `task verify:test-boundary`
+2. Review findings; move test artifacts under declared test roots or classify production liveness/canaries in `allow`
+3. Persist reviewed policy under `.deft/test-boundary.policy.json` or `plan.policy.testBoundary` with `enforcementMode: "enforce"`
+4. Wire stays green via `task check` / consumer deposit
+
+## Production liveness carve-out
+
+Health probes, canaries, and operational evidence collectors may live under production roots when listed in `allow` with `kind: "production-liveness"` and a recorded reason. Do not use the word “smoke” alone as classification.
+
+## Remediation
+
+Failures name the path, violated boundary, and next step (move under test root, allow entry, or reclassify). See `content/contracts/test-boundary.md`.

package/main.md

@@ -71,6 +71,35 @@ See #634, #642. See [ADR-001](./docs/decisions/ADR-001.md) for the token-economi
 - ⊗ Continue executing a skill past its explicit instruction boundary — when a skill's steps are complete, stop and return to the calling context; do not drift into adjacent work (#198)
 - ! The end of a skill's final step is an exit condition — do not continue into adjacent work, even if it seems related or trivial
 
+## Dual Stop Rule (#2442)
+
+Loop engineering requires **two** stop conditions on multi-iteration autonomous work: a **success stop** (goal / AC / checker met) and a **failure or budget stop** (retries exhausted, no progress, or time/token budget). Directive already has strong success-shaped gates (`task check`, acceptance criteria, STOP on plan precondition mismatch -- #1613). This section requires the complementary failure envelope so agents escalate instead of thrashing forever.
+
+**Applies to:** multi-iteration autonomous loops -- build quality / implement-fix loops, pre-PR polish cycles, swarm repair and monitor loops, research fan-out, review fix cycles, and similar retrying work.
+
+**Does not apply to:** single-turn tasks (one shot answer, one file edit, one status probe). Not every task is a loop; do not invent iteration caps where there is no multi-step retry envelope.
+
+**Required stops on every multi-iteration loop:**
+
+1. ! **Success stop** -- goal, acceptance criteria, or checker is met; exit the loop and continue the skill or report done.
+2. ! **Failure stop** -- at least one of:
+   - **max iterations** (task-class default; e.g. a short quality-fix class vs a longer research class)
+   - **no-progress** (same outcome or same failure fingerprint N times in a row with no material change)
+   - **explicit budget** (time, tool-call, or token budget when the host exposes it)
+
+**On failure stop:**
+
+- ! Halt the loop. Do not silently continue, re-dispatch, or open a new identical attempt without an operator decision.
+- ! Emit an **operator-visible halt report** that states: (a) what was tried, (b) what is still missing or failing, (c) what human decision is needed next (scope change, unblock, override, or abandon).
+- ⊗ Keep iterating after the failure envelope is exhausted because "one more try" might work.
+- ⊗ Reset iteration counters solely by creating a new revision, swapping workers, or compacting context when the same failure class remains.
+
+**Relation to other rules:**
+
+- #1613 covers STOP when plan **preconditions** fail (reality mismatch). Dual stop covers the case where the plan is still "valid" but the agent must quit after N failed attempts, N identical no-progress outcomes, or a budget limit.
+- Skills name concrete defaults: `skills/deft-directive-build/SKILL.md` (implement / pre-PR loops), `skills/deft-directive-swarm/SKILL.md` and its Phase 4 / core-ops references (repair / monitor loops).
+- **Delivery / acceptance mechanical enforcement** (durable attempt ledger, material-progress circuit breaker, cross-revision budgets) is **#3143** — library: `packages/core/src/delivery-attempt/` (`evaluatePreDispatch`, unit ledger under `.deft/delivery-attempts/`). Docs: `content/docs/delivery-attempt.md`. #2442 is the principle + skill defaults; #3143 is the deterministic pre-dispatch gate. Route delivery/acceptance loops through that surface rather than inventing a parallel ledger.
+
 **Adaptive Teaching:**
 - ~ When a recommendation is accepted without question, be concise
 - ! When a recommendation is questioned or overridden, explain the reasoning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.96.0",
+  "version": "0.97.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",

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

@@ -35,6 +35,16 @@
       "path": "patterns/llm-app.md",
       "body": null
     },
+    {
+      "id": "operator-log-hygiene",
+      "title": "Operator-log hygiene (#1940)",
+      "description": "Consumer guidance for structured, operator-facing logs: six failure modes, anti-patterns, positive rules, explicit non-goals (no core schema, no default-on, not Insights/LLM telemetry). SLizard is external reference only. Checklist and optional consumer pack stub under docs/.",
+      "triggers": [
+        "operator-log-hygiene"
+      ],
+      "path": "patterns/operator-log-hygiene.md",
+      "body": null
+    },
     {
       "id": "multi-agent",
       "title": "Multi-agent identity separation pattern (#983)",