@deftai/directive-content 0.98.0 → 0.99.0

package/Taskfile.yml

@@ -344,6 +344,10 @@ includes:
   value:
     taskfile: ./tasks/value.yml
     optional: true
+  # Structured agent decision log (#1396). Inner tasks write/list → decision:write / decision:list.
+  decision:
+    taskfile: ./tasks/decision.yml
+    optional: true
   product-signal:
     taskfile: ./tasks/product-signal.yml
     optional: true

package/coding/coding.md

@@ -4,7 +4,6 @@
 <!-- Regenerate with: task packs:render -->
 <!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
 
-
 # Coding Guidelines
 
 Software development specific guidelines for AI agents.
@@ -126,7 +125,7 @@ See [../scm/git.md](../scm/git.md) for:
 
 The failure mode is the agent stating completion at the level of **intent** ("I ran the migration", "the tests pass", "the feature works") rather than at the level of **outcome verification** ("all 167 records migrated, 0 skipped", "42 tests collected, 42 passed, 0 skipped, 0 xfailed", "the edge case asked about was reproduced and now returns the expected value"). Outcome-blind completion claims hide silent skips, swallowed exceptions, suppressed errors, and unverified edge cases behind successful-sounding language. The example from the source: a database migration that completed "successfully" had silently skipped 14% of records on a constraint violation; the skip was logged but not surfaced; the bad reports were discovered 11 days later.
 
-This rule is the OPERATIONAL complement to the EPISTEMIC honesty rules elsewhere in the framework (`main.md` morals section: don't present speculation as fact; label unverified claims). Morals.md says "don't lie". Fail-loud says "count the records, check the logs, run the edge case, **then** claim completion." It is also the output-side complement to goal-gate-determinism (the gate specifies what evidence is required) and machine-verifiable-spec (verification commands prevent silent skips) -- without fail-loud, an agent can satisfy the letter of a gate ("tests pass") while hiding the gap ("some tests were skipped").
+This rule is the OPERATIONAL complement to the EPISTEMIC honesty rules elsewhere in the framework (`main.md` morals section: don't present speculation as fact; label unverified claims). Morals.md says "don't lie". Fail-loud says "count the records, check the logs, run the edge case, **then** claim completion." It is also the output-side complement to [goal-gate-determinism](../patterns/goal-gate-determinism.md) (#852 — the gate specifies what evidence is required) and machine-verifiable-spec (verification commands prevent silent skips) -- without fail-loud, an agent can satisfy the letter of a gate ("tests pass") while hiding the gap ("some tests were skipped").
 
 - ! Before claiming a batch operation succeeded, MUST verify the record count and surface it in the claim ("migrated 167/167 records, 0 skipped, 0 errored" -- not "migration completed")
 - ! Before claiming "tests pass", MUST report the count of collected / passed / skipped / xfailed / errored tests ("42 collected, 42 passed, 0 skipped" -- not "tests pass"). A skipped or xfailed test is NOT a passing test for the purpose of this claim
@@ -144,7 +143,7 @@ This rule is the OPERATIONAL complement to the EPISTEMIC honesty rules elsewhere
 
 The rule applies to agent completion claims during task execution. It applies equally to claims to the user, claims in commit messages, claims in PR bodies, claims in CHANGELOG entries, and claims in status messages to a parent agent. A short, honest "the migration completed; I did not verify the per-record count" is strictly preferred over a confident "migration completed successfully" that hides the gap.
 
-**Cross-references:** strategies discuss/probe Graduation dual-path locks (#2899); `## Quality Standards` above (`⊗ Claim checks passed without running them` -- the sibling rule that this expands from process to outcome); `hygiene.md` `## Error Handling: No Hiding` (the same hiding pattern at the code-write level, not the claim level); `skills/deft-directive-pre-pr/SKILL.md` (pre-PR verification claims); `skills/deft-directive-build/SKILL.md` Step 4 Quality Gates (task-completion claims); `skills/deft-directive-review-cycle/SKILL.md` (Greptile adapter; universal review principles in [review.md](review.md); the adapter explicitly checks for hidden incompleteness in fix-batch completion claims).
+**Cross-references:** strategies discuss/probe Graduation dual-path locks (#2899); `## Quality Standards` above (`⊗ Claim checks passed without running them` -- the sibling rule that this expands from process to outcome); `hygiene.md` `## Error Handling: No Hiding` (the same hiding pattern at the code-write level, not the claim level); [`patterns/goal-gate-determinism.md`](../patterns/goal-gate-determinism.md) (#852 — rigid goals/gates, flexible path); `skills/deft-directive-pre-pr/SKILL.md` (pre-PR verification claims); `skills/deft-directive-build/SKILL.md` Step 4 Quality Gates (task-completion claims); `skills/deft-directive-review-cycle/SKILL.md` (Greptile adapter; universal review principles in [review.md](review.md); the adapter explicitly checks for hidden incompleteness in fix-batch completion claims).
 
 ## Calling LLM APIs (#481)
 

package/commands.md

@@ -183,6 +183,25 @@ flowchart TD
 
 ---
 
+## Structured decision log (#1396)
+
+Lightweight intent-debt records for **significant** choices (architecture, product behavior, security, public/private boundary, data model, runtime topology, hard-to-reverse process). Not every trivial scope. Not ADR migration; leave `docs/decisions/ADR-*.md` alone. Split from lessons (#1513).
+
+| Command | Purpose |
+|---------|---------|
+| `task decision:write` | Validate and write `xbrief/decisions/YYYY-MM-DD-<slug>.decision.json`; optional `--scope` appends a pointer under `plan.narratives.Decisions` |
+| `task decision:list` | List/filter records (`--query`, `--scope`, `--issue`, `--json`) |
+
+Required fields: decision, governing rule/constraint, alternatives considered, why winner, confidence, timestamp, revisit trigger; active scope ref(s) when applicable.
+
+! For significant choices during build / pre-PR / portfolio dispose, record via `task decision:write` (or `--body-file` on Windows for multi-line fields).
+⊗ Require a decision record before every `scope:complete` in v1 (guidance only; no deterministic complete-hook yet).
+⊗ Store chat transcripts or replace git history with this surface.
+
+Docs: [docs/decision-log.md](./docs/decision-log.md) · layout: `xbrief/decisions/README.md`. Consumers: portfolio dispose (#3198/#3201), process dogfood (#1423).
+
+---
+
 ## Generated Document Commands
 
 Edit the xBRIEF source, then render the markdown view.
@@ -554,7 +573,7 @@ flowchart TD
 - `task release:*` -- release, publish, rollback, and e2e release rehearsal.
   - Step 3 (`Pre-flight vBRIEF lifecycle sync`) fetches GitHub issue states via REST. On HTTP 403 rate-limit exhaustion it sleeps once (capped at 120s) and retries before failing.
   - When Step 3 still fails with rate-limit exhaustion, stderr includes a `gh api rate_limit` probe (`core.remaining`, reset time) and recovery guidance. After local `task vbrief:validate` (or `task xbrief:validate`) exits 0, operators may pass `--allow-vbrief-drift` to skip Step 3 for that cut — reserved for transient SCM bucket stalls, not unreviewed lifecycle drift.
-- `task swarm:*` -- readiness, launch, review-clean verification, and cohort completion.
+- `task swarm:*` -- readiness, launch, pre-dispatch deny gate (#3228), review-clean verification, and cohort completion.
 - `task slice:*` -- feature-slice helpers.
 - `task policy:*` and `task capacity:*` -- policy inspection and allocation helpers.
 

package/context/tool-design.md

@@ -4,6 +4,16 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 Principles for designing tools that agents can use effectively.
 
+**Load when:** authoring host tools, MCP/server tool schemas, skill-facing
+task surfaces, or any agent-callable parameter shape. Also load when a
+tool call fails in ways that look like "the model is dumb" but may be
+dialect sampling cost.
+
+**⚠️ See also**:
+- [patterns/llm-app.md](../patterns/llm-app.md) `## Tool / function calling` — security, least privilege, validation (confused deputy)
+- [patterns/tool-call-taxonomy.md](../patterns/tool-call-taxonomy.md) — explore / commit / verify activity buckets (orthogonal)
+- [deterministic-split.md](./deterministic-split.md) — what must not be an LLM step at all
+
 ---
 
 ## Minimal, Non-Overlapping Tool Sets
@@ -12,6 +22,110 @@ Principles for designing tools that agents can use effectively.
 - ≉ Offering multiple tools that do the same thing with slight variations
 - ~ Each tool should have a **single, clear purpose**
 
+## Tool-surface grammar (#3085)
+
+A tool "call" is **dialect sampling** in the token stream. The model does
+not decide to call a tool as a special act. It continues the completion
+loop under a harness dialect (`function_calls` / `invoke` / JSON args /
+provider-specific tags). Schema design is a first-order **reliability and
+cost** surface, not cosmetics.
+
+**Rule of thumb:** reliability degrades with
+**nesting × heterogeneity × cleverness**.
+
+Source framing (practitioner ablation, not product UI): Can Bölük
+([@_can1357](https://x.com/_can1357/status/2084104053651317140), 2026-08-03).
+The post's emoji / plaintext "control group" is **not** a product
+recommendation. At roughly ten or more tools, native tool-calls win on
+ergonomics; still design the **thinnest grammar** you can get away with.
+
+### Prefer flat, homogeneous params
+
+- ~ Prefer **flat scalar/string parameters** over nested objects and
+  arrays-as-escaped-JSON inside a single parameter value
+- ~ Prefer a **homogeneous** parameter set (similar types, predictable
+  names) over mixed clever packing (object + freeform JSON string +
+  parallel batch bag in one tool)
+- ~ When the host owns the tools, prefer a **vector / flat** shape (one
+  named field per logical input) over "batch JSON in a string" when that
+  batch only exists to save parallel tool-call round-trips
+- ≉ Nested argument bags that force the model to emit valid escaped JSON
+  for complex objects when plain scalar parameters would suffice
+- ≉ Heterogeneous mega-tools that pack unrelated concerns into one clever
+  payload "for flexibility"
+- ! Treat provider schema fields (`minimum`, `maximum`, `enum`, long
+  descriptions) as **documentation the harness may show**. Validation is
+  the application's job unless the harness (or provider) actually rejects
+  invalid args — do not assume the model "must" obey schema mins/maxes
+- ! Validate tool arguments in the harness before side effects
+  (`patterns/llm-app.md` tool-call rules). A flat grammar still needs a
+  validator and common dialect failure handling (leaked call text,
+  truncated invoke blocks, wrong tool name tokens)
+
+### Good vs bad shapes (sketch)
+
+Bad — nested / heterogeneous / JSON-in-string:
+
+```text
+apply_batch({
+  "ops": "[{\"path\":\"a.ts\",\"edits\":[{\"start\":1,\"end\":2,\"text\":\"...\"}]}]"
+})
+```
+
+The model must sample valid escaped JSON for a nested array. One quote
+or brace error fails the turn. High nesting × high cleverness.
+
+Better — flat / homogeneous (host-owned tools):
+
+```text
+edit_file(path="a.ts", start_line=1, end_line=2, text="...")
+```
+
+Scalars and strings after named parameters. The dialect delimiter ends
+the value; no JSON escape maze for the common case. Repeat the tool or
+use parallel invokes when multiple edits are needed.
+
+When composition is large (many steps, dynamic graphs), **do not** invent
+deeper nested tool packs. Prefer fewer tools via code abstraction / Code
+Mode / a host-side program (related: #1167, #2593) and multi-step token
+breakpoints (#1170). Those reduce **how many** tools exist; this section
+shapes **how each remaining tool looks** at the dialect layer.
+
+### Authoring checklist (Directive + consumers)
+
+Use for Directive-owned task/skill tool surfaces, documented host schemas,
+and consumer MCP / product-agent schemas:
+
+| Prefer | Avoid |
+|--------|--------|
+| Flat named scalars/strings | Nested object trees as required args |
+| One clear purpose per tool | Mega-tools with optional clever branches |
+| Homogeneous repeated fields | Mixed types + freeform JSON bags |
+| Host validation + repair | Trusting provider schema as enforcement |
+| Code / DSL for multi-step | Deeper nesting to "express workflows" |
+
+- ~ Document constraints in parameter descriptions for human and model
+  readers, then **enforce in code**
+- ≉ Shipping emoji/plaintext tool channels as a product default (control
+  group only in the source post)
+- ≉ Migrating every existing tool in one pass — land the principle first;
+  reshape high-failure surfaces when measured failure rates justify it
+- ? Keep a short failure catalog of dialect errors for your harness
+  (sibling track: #3086) so "won't fix" provider quirks become harness
+  duties
+
+### Complementarity
+
+| Concern | Where it lives |
+|---------|----------------|
+| **How each tool's args sample** (this doc) | Flat grammar, low nesting tax |
+| **How many tools** exist | Code Mode / DSL / abstraction (#1167, #2593) |
+| **When multi-step burns tokens** | Breakpoints / long-horizon (#1170) |
+| **Security of tool use** | `patterns/llm-app.md` (schema validate, least privilege) |
+| **Protocol / model-tier cost after shape** | Cost-envelope notes (e.g. #3078) |
+
+---
+
 ## Token-Efficient Outputs
 
 - ~ Support **filtering** — let the caller request only the fields they need
@@ -25,6 +139,8 @@ Principles for designing tools that agents can use effectively.
 - ! **Tool descriptions** should state what the tool does, when to use it, and what it returns
 - ~ **Parameters** should be self-documenting — use descriptive names and include constraints in descriptions
 - ≉ Relying on the agent to infer parameter semantics from names alone
+- ~ Keep descriptions short enough to load on demand; put deep examples in
+  linked docs, not in every tool definition (token tax — see also #865)
 
 ## Error Messages
 

package/contracts/host-lifecycle-duties.md

@@ -84,12 +84,21 @@ Full operator steps: [`../docs/openclaw-agent-host.md`](../docs/openclaw-agent-h
 | **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. |
 
+## Content-surface honesty (#3162)
+
+Session start records a **host content-surface class** (`file-first` / `repl-first` / `self-mutating` / `unknown`) and managed AGENTS section drift. Operators set `DEFT_HOST_CONTENT_SURFACE` (or REPL / self-mutate env flags) when the host is not file-first.
+
+! Do not assume file gates or agent-only pins see host-kernel work product or host refine CRUDs.
+
+Full honesty matrix and Tier-1 hook home: [`../docs/host-surface-assumptions.md`](../docs/host-surface-assumptions.md). Stance #3164 unchanged.
+
 ## 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.
+- ⊗ Assume file/git gates saw REPL-kernel or mid-run host-refine work product (#3162).
 
 ## Acceptance pointer
 

package/docs/agent-docs.md

@@ -43,6 +43,7 @@ These are the specific blocks the study measured *hurting* agent quality — tre
 
 When a workflow skill must not be skipped on trigger miss (implementation, pre-PR, review-cycle, swarm), name it in AGENTS.md as an **always-pin** — not by pasting the skill body. Tier definitions, default pin list, and anti-patterns (do not pin entire language packs): [`skill-pin-policy.md`](./skill-pin-policy.md).
 
+On REPL-first or self-mutating hosts, pins and file gates have honest limits — see [`host-surface-assumptions.md`](./host-surface-assumptions.md) (#3162).
 ## Relationship to directive's own dogfooding
 
 Directive holds its own AGENTS.md to this bar via the `verify:agents-md-budget` ratchet (#645) and the consumer-side advisory signal (`agentsMdAdvisory`, #2155). The doc-sprawl awareness step in the `deft-directive-sync` skill (#647) surfaces reachable-doc-volume drift before it silently degrades agent quality. This doc is the "how to structure it well" companion to those "keep it from bloating" guards.

package/docs/consumer-check-contract.md

@@ -16,11 +16,34 @@ A consumer could omit Directive enforcement gates from its `check` task and CI w
 
 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).
 
+### Greenfield include-only Taskfile (#3218)
+
+After `directive init`, the consumer root `Taskfile.yml` is often **include-only**:
+
+```yaml
+includes:
+  deft:
+    taskfile: ./.deft/core/Taskfile.yml
+    optional: true
+```
+
+Operators run `task deft:check` (namespaced include). Composition lives in the **included** framework `Taskfile.yml` + `.deft/core/tasks/verify.yml`, not in root `check` deps.
+
+`verify:consumer-check-contract` **trusts that included graph** when:
+
+1. The root Taskfile declares the canonical `.deft/core/Taskfile.yml` include, and
+2. No local `check` / `check:consumer` / `check:framework-source` aggregate is defined at the root, and
+3. The included framework Taskfile defines the required gates in `tasks/verify.yml` and composes them (deps or check orchestrator body).
+
+A **partial local** root check aggregate still fails closed — the include must not conceal incomplete root deps.
+
+Root cause of red `greenfield-python-free-smoke` after #3145: the gate only inspected the root Taskfile, treated include-only greenfield as “no check composition,” and hard-failed (`exit 201` via #3188). That was a **gate false positive** for the intentional deposit shape, not a missing deposit wiring bug.
+
 ## 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
+1. Restore deposit Taskfiles: `deft update` (includes `tasks/verify.yml` under `.deft/core/`)
+2. Ensure `check:consumer` / `check:framework-source` deps list the three gates (framework source already ships this wiring), **or** keep the include-only greenfield shape so the gate follows the canonical include
+3. Prefer CI that runs `task check` / `task deft:check` / `deft check` rather than a partial custom graph (installer-only workflows such as `deft-core-guard` stay warn-only for CI composition)
 
 ## Relation to #3070
 

package/docs/decision-log.md

@@ -0,0 +1,114 @@
+# Structured agent decision log (#1396)
+
+Durable **intent-debt** records for significant agent and operator choices.
+
+Git history records *what* changed. Decision records capture *why* A won over B, under which rule, and when a later agent should re-open the choice.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## When to record
+
+! Record a decision when the choice is **significant**:
+
+- architecture
+- product behavior
+- security
+- public / private boundary
+- data model
+- runtime topology
+- hard-to-reverse process
+
+⊗ Record a decision for every trivial scope or routine bugfix.
+
+## Commands
+
+```bash
+# Write (flags and/or --body-file JSON)
+task decision:write -- \
+  --decision "Prefer dual location for decision records" \
+  --governing-rule "Significant choices leave durable rationale" \
+  --governing-path "content/docs/decision-log.md" \
+  --governing-rfc MUST \
+  --alternative "scope-only narratives" \
+  --alternative "ADR-only" \
+  --why-winner "Covers scope-bound and cross-cutting without ADR noise" \
+  --confidence high \
+  --revisit-trigger "If list/find is painful, revisit folder layout" \
+  --scope xbrief/active/2026-08-09-example.xbrief.json \
+  --related-issue 1396 \
+  --tag process
+
+# List / filter
+task decision:list --
+task decision:list -- --query mirror --json
+task decision:list -- --issue 1423
+task decision:list -- --scope xbrief/active/
+```
+
+On Windows, prefer `--body-file` for multi-line fields (UTF-8 no BOM temp file).
+
+Invalid schema fails closed (exit 2).
+
+## Schema (lightweight, not xBRIEF lifecycle)
+
+| Field | Required | Notes |
+|-------|----------|--------|
+| `schemaVersion` | yes | `deft.decision.v1` |
+| `id` | yes | kebab slug (derived from decision if omitted) |
+| `decision` | yes | what was decided |
+| `governingRule` | yes | `{ description, path?, rfc2119? }` or string |
+| `alternativesConsidered` | yes | non-empty array of `{ option, whyNot? }` |
+| `whyWinner` | yes | why the chosen path won |
+| `confidence` | yes | `low` \| `medium` \| `high` |
+| `activeScopeRefs` | no | relative scope xBRIEF path(s) |
+| `timestamp` | yes | ISO-8601 UTC |
+| `revisitTrigger` | yes | when/why to re-open |
+| `tags` / `relatedIssues` | no | list filters |
+
+Files: `xbrief/decisions/YYYY-MM-DD-<slug>.decision.json` (committed; not gitignored).
+
+## Dual location
+
+1. **Always** write the JSON file under `xbrief/decisions/`.
+2. When `--scope` points at a scope xBRIEF, also append a pointer line under `plan.narratives.Decisions` (string narrative; validators accept extra narrative keys).
+3. Use `--standalone` to skip scope attach even if scope refs are present.
+
+Cross-cutting process/architecture decisions often have empty `activeScopeRefs`.
+
+## Enforcement (v1)
+
+! Guidance only in build / pre-pr / portfolio (and related) skills for **significant** choices.
+
+⊗ Do **not** require a decision record before every `scope:complete` in v1 (deterministic complete-hook is later work).
+
+## Split from other surfaces
+
+| Surface | Role |
+|---------|------|
+| This decision log (#1396) | Single durable rationale events |
+| Lessons / compound memory (#1513) | Reusable patterns and anti-patterns |
+| `docs/decisions/ADR-*.md` | Heavyweight architecture ADRs — leave alone |
+| Portfolio brief (#3198/#3201) | Propose-not-apply; **dispose** into `decision:write` |
+| Chat / transcripts | Non-goal |
+| Full inter-run memory (#2741) | Related consumer later; not owned by this surface |
+
+## Consumers
+
+- Portfolio dispose (#3198 / #3201 / pilot #3200)
+- Process policy dogfood (SCM label-mirror first mass-apply #1423)
+- Multi-agent handoff continuity (related #2741 class)
+
+## Dogfood seeds
+
+- `xbrief/decisions/2026-08-08-scm-label-mirror-first-mass-apply.decision.json`
+- `xbrief/decisions/2026-08-09-portfolio-dispose-into-decision-log.decision.json`
+
+## Cold-path discovery (#3211)
+
+! Always-on AGENTS managed pointer (via `content/templates/agents-entry.md` + `task agents:refresh`), Level-0 `REFERENCES.md` under context/long tasks, and [`inter-run-learning.md`](./inter-run-learning.md) link this surface so a fresh session can name `decision:list` without loading build or pre-pr skills.
+
+## See also
+
+- [`xbrief/decisions/README.md`](../../xbrief/decisions/README.md)
+- `task decision:write` / `task decision:list` in [`commands.md`](../commands.md)
+- [`inter-run-learning.md`](./inter-run-learning.md) (cold memory SoTs; this log is the durable *why* lane)

package/docs/delivery-attempt.md

@@ -90,13 +90,29 @@ and tool-call budgets still apply.
 `allowedAttempts`, and optional expiry. Overrides do **not** erase attempt
 history.
 
+## Swarm implement-leaf wiring (#3228)
+
+Portable CLI gate on the swarm re-dispatch path (not library-only):
+
+```
+task swarm:pre-dispatch -- --scope-id <story|issue|xbrief-id> --target-id <worktree|branch>
+# exit 0 allow (beginAttempt) / 1 DENY_DUPLICATE_ACTIVE or other gate block / 2 config
+```
+
+Default unit key: `scopeId` + `targetId` + `workflowId=drive-to:merge-ready`.
+Actions: `begin` (default), `complete` (`--status succeeded|failed|cancelled|blocked`), `cancel` (takeover step 1).
+Monitors MUST run begin before any peer implement spawn; spawn only on exit 0.
+Takeover: cancel prior attempt, then begin again — never concurrent dual active.
+Implementation: `packages/core/src/swarm/pre-dispatch.ts` + `task swarm:pre-dispatch`.
+
 ## 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 |
+| swarm `core-ops` / `core-phase-4` | Prompt + monitor envelopes; pre-dispatch CLI pointer (#3228); do not invent a second ledger |
+| `task swarm:pre-dispatch` | Authoritative implement-leaf gate (#3228); wires `DENY_DUPLICATE_ACTIVE` |
 
 ## Typical call shape
 

package/docs/gate-integrity.md

@@ -0,0 +1,112 @@
+# Gate integrity — a failing gate must not be fixed by editing the gate (#3156)
+
+General product and process rule for Directive fix loops, refine loops, and quality-gate repair: **when a gate is red, clear red by fixing the work under test — not by mutating the gate.**
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `≉`=SHOULD NOT, `⊗`=MUST NOT, `?`=MAY.
+
+Parent epic: [#3179](https://github.com/deftai/directive/issues/3179) (self-improving under gates). Stance: [#3164](https://github.com/deftai/directive/issues/3164) (**shipped** — constitution-tier changes go through issue/PR + review; this doc does not re-litigate that stance). Extends verification independence [#782](https://github.com/deftai/directive/issues/782) / [#1499](https://github.com/deftai/directive/issues/1499) and scope self-auth themes [#3145](https://github.com/deftai/directive/issues/3145).
+
+---
+
+## The rule (sharp form)
+
+- ⊗ A self-modification, refine, fix, or pre-PR loop **MUST NOT** clear a failing gate by editing the **gate definition**, **verifier**, **reward**, **required check**, coverage floor, policy flag, eval fixture, or other evaluator surface that is currently failing — solely so the loop can report green.
+- ! When a gate fails, fix the **product, process, test, or documentation under test**.
+- ! Deliberate **gate definition** changes (raise/lower thresholds, rewrite verify scripts, change required checks) go through the normal **issue → PR → review** path with explicit rationale — same disposal model as constitution-tier content under [#3164](https://github.com/deftai/directive/issues/3164).
+- ~ If the gate itself is wrong (false positive, obsolete check, wrong floor), open or amend an issue/PR that **names the gate change as the change**, not as a silent sibling edit inside a product fix.
+
+One-line form:
+
+> When a gate fails, the fix MUST NOT be an edit to the gate.
+
+---
+
+## What counts as a “gate” here
+
+Any deterministic pass/fail surface that adjudicates work quality, including but not limited to:
+
+| Surface | Examples |
+|---------|----------|
+| Aggregate quality | `task check`, CI required checks |
+| Coverage / thresholds | coverage floors, hotspot floors, `--allow-coverage-debt` misuse |
+| Verify scripts | `verify:*` tasks, content contracts, schema validators |
+| Policy flags | `plan.policy.*` that weaken or skip enforcement |
+| Eval / fixtures | golden eval cells, reward definitions, required fixture assertions |
+| Scope / process | active xBRIEF `file_scope` self-expansion that self-authorizes (#3145) |
+
+The **evaluator lives outside the editable surface under test** (#782 agent-loop / fixed evaluator). Moving the goalposts is not a valid fix.
+
+---
+
+## Separation from #2436 (refine-internal SkillOpt)
+
+| Layer | Owner | What it protects |
+|-------|-------|------------------|
+| **Refine-loop-internal** | [#2436](https://github.com/deftai/directive/issues/2436) SkillOpt / control stack | Proposer cannot edit its own reward / slow-update / validator **region inside the refine runtime** (bounded patch algebra, reject buffer, protected region) |
+| **General product/process gate integrity** | **This issue (#3156)** | Agents and fix loops must not clear **Directive product/process gates** (check, coverage, verify, policy, eval fixtures, scope) by mutating those gates |
+
+- ⊗ Re-implement SkillOpt, proposer runtime, or refine-internal protected regions under this rule’s delivery.
+- ! Treat #2436 as complementary machinery for self-improvement loops; treat **#3156 as the general behavioral rule** for every fix/pre-PR path that hits a red gate.
+- ~ Host honesty limits when the **runtime** self-mutates or is REPL-first: [host-surface-assumptions.md](./host-surface-assumptions.md) (#3162). That doc names what file gates cannot see; it does not reverse this rule or #3164.
+
+---
+
+## Motivating evidence (Factorio / Continual Harness)
+
+Prime Agent / Continual-Harness-class refine loops have packaged reward hacks as reusable skills. A concrete case study: in Factorio, a refine loop found a resource-spawn exploit and codified the exploit the same way it codifies good tactics — “self-improvement has no moral compass, only reward.”
+
+That failure mode is exactly what #782 / #1499 / #2436 argue against, observed in a shipped MIT harness rather than only hypothesized. Directive’s answer at the **general product/process** layer is this gate-integrity rule; refine-internal machinery remains on #2436.
+
+Field notes and parent framing: issue [#3156](https://github.com/deftai/directive/issues/3156); related safety-via-gates [#1200](https://github.com/deftai/directive/issues/1200).
+
+---
+
+## Legitimate gate change vs cheating the evaluator
+
+| Allowed | Forbidden in a fix/refine loop |
+|---------|--------------------------------|
+| Fix product code so tests/coverage pass honestly | Lower coverage floor or delete failing tests only to go green |
+| Fix a broken product test that asserts wrong behavior (with rationale) | Weaken the assert until anything passes |
+| PR that **is** “raise coverage floor to 90%” with review | Same PR as a feature fix that silently drops the floor |
+| Issue + PR changing a verify script with explicit AC | Edit verify script mid-loop because it failed your change |
+| Scoped `#N` coverage-debt allow with tracked issue | Blanket skip of required checks without policy path |
+
+- ! Gate-definition PRs MUST state the intended standard change in the PR body and issue link.
+- ⊗ Bundle silent gate weakening with an unrelated product fix to “make CI green.”
+- ? Temporary operator-approved debt (`--allow-coverage-debt=#N`, policy override with audit) MAY exist when the framework already defines that escape hatch — still not a free rewrite of the gate.
+
+---
+
+## Discoverability
+
+- Pre-PR Diff phase checklist: [deft-directive-pre-pr](../skills/deft-directive-pre-pr/SKILL.md) (gate-integrity bullet).
+- Stance / propose-not-apply: [main.md § Self-Improving, Not Self-Editing (#3164)](../../main.md#self-improving-not-self-editing-3164), [philosophy.md](../meta/philosophy.md).
+- Verification outcomes: [verification.md](../verification/verification.md).
+- Goal/gate rigidity: [goal-gate-determinism.md](../patterns/goal-gate-determinism.md) (#852).
+- Scope self-auth instance: [scope-provenance.md](./scope-provenance.md) (#3145).
+
+Full CI automation that blocks “diff touches a gate that just failed” without operator acknowledgment is an **optional follow-up** — this story ships the sharp rule and pre-PR discoverability, not a new verify binary.
+
+---
+
+## Cross-links
+
+| Topic | Where |
+|-------|--------|
+| Parent epic | [#3179](https://github.com/deftai/directive/issues/3179) |
+| Stance (propose-not-apply) | [#3164](https://github.com/deftai/directive/issues/3164), [main.md](../../main.md#self-improving-not-self-editing-3164) |
+| Refine-internal SkillOpt | [#2436](https://github.com/deftai/directive/issues/2436) |
+| Fixed evaluator / agent-loop | [#782](https://github.com/deftai/directive/issues/782) |
+| Verification independence | [#1499](https://github.com/deftai/directive/issues/1499) |
+| Scope self-authorization | [#3145](https://github.com/deftai/directive/issues/3145), [scope-provenance.md](./scope-provenance.md) |
+| Host self-mutate honesty | [#3162](https://github.com/deftai/directive/issues/3162), [host-surface-assumptions.md](./host-surface-assumptions.md) |
+| Safety via formal gates | [#1200](https://github.com/deftai/directive/issues/1200) |
+
+---
+
+## Non-goals (#3156)
+
+- ⊗ Implementing full SkillOpt / proposer runtime (#2436)
+- ⊗ Host hook enforcement for self-mutating hosts (#3162)
+- ⊗ Replacing design-principle docs under #1200 (complementary)
+- ⊗ Shipping full “gate-diff-when-red” CI automation in this story