@deftai/directive-content 0.101.0 → 0.103.0

package/UPGRADING.md

@@ -282,7 +282,9 @@ A normal framework upgrade is **one PR**, not two stacked PRs. The deposited `de
 
 **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), [#3193](https://github.com/deftai/directive/issues/3193), [#1430](https://github.com/deftai/directive/issues/1430), [#3117](https://github.com/deftai/directive/issues/3117).
+**Load fix (#3345):** if GitHub Actions shows workflow name as the path string `.github/workflows/deft-core-guard.yml` (not `deft-core-guard`), or historical runs are 0s/0 jobs and the required check `no-mixed-core-and-app` never appears on PRs, the deposited workflow failed to load (invalid YAML from an unindented Python heredoc). Run `deft update` (or re-init deposit) so the fixed workflow is rewritten, then open a normal upgrade PR — classic branch protection that requires `no-mixed-core-and-app` can clear once the job posts.
+
+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), [#3345](https://github.com/deftai/directive/issues/3345).
 
 Machine-readable skill exit line (for agents/operators):
 

package/commands.md

@@ -275,7 +275,7 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 - `task verify:capacity`, `task verify:wip-cap`, and `task verify:judgment-gates` -- policy/capacity gates.
 - `task verify:orphan-active` -- fail closed when active/running xBRIEFs still point at closed issues or merged PRs (#2321).
 - `task verify:completed-tracked` -- fail closed when closed scoped issues lack a tracked `xbrief/completed/` or `xbrief/cancelled/` artifact on the delivery tip (#3264); remediate with `task swarm:finalize-cohort` or a lifecycle PR. Standalone verb (not part of `task check`); use `--tip HEAD` when validating an in-flight land branch.
-- `task verify:ac` -- product-first acceptance gate (#3284). Runs `plan.acceptance.commands` (or #3267 literal ledger) **verbatim** before done; records AC-source rung (`stated`/`derived`/`project_floor`). Empty commands require `none_stated: true`. Primary name used first in `task check` (fail-fast); `--soft-missing-xbrief` for check composition. Rapid ceremony = AC-only; pressure/degraded makes hygiene advisory. `--capture-only` lists resolved commands without executing. Extends #3267 / #973.
+- `task verify:ac` -- product-first acceptance gate (#3284). Runs `plan.acceptance.commands` (or #3267 literal ledger) **verbatim** before done; records AC-source rung (`stated`/`derived`/`project_floor`). Empty commands require `none_stated: true`. Empty resolution is not a green run when the project has no suite floor (`soft_empty` + stamp-acceptance remedy, #3334). Primary name used first in `task check` (fail-fast); `--soft-missing-xbrief` for check composition. Rapid ceremony = AC-only; pressure/degraded makes hygiene advisory. `--capture-only` lists resolved commands without executing. Extends #3267 / #973.
 - `task verify:literal-ac` -- #3267 mechanism alias for verbatim stated-command run (same flags/cwd); prefer `verify:ac` for product-first done-gate.
 - `task coverage:hotspots` / `deft coverage:hotspots` -- read the latest coverage report, compare global metrics to the project's vitest thresholds, fail closed below the branch floor or below configured headroom (default 0.3pp), and list lowest modules plus uncovered branch samples for git-diff paths (`--json` for agents). Complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573); does not replace them.
 

package/context/context.md

@@ -32,12 +32,40 @@ Externalize intermediate state so it doesn't consume context window.
 
 Load only what's needed, when it's needed.
 
+Directive practices **human-curated context partitioning**: structure the
+world so agents can inspect an index (AGENTS.md → main.md → REFERENCES.md →
+skill scope / pack slices), then load only the slices the task needs. That is
+lazy load by design — partition first, then select — not "paste everything and
+hope attention holds."
+
 - ! **Follow [REFERENCES.md](../../REFERENCES.md)** for lazy-loading guidance
 - ~ Maintain lightweight references (file paths, line numbers, search queries) rather than full file contents
+- ~ Prefer **handles** over paste when the host can dereference: paths, pack
+  slices (`task packs:slice`), xBRIEF ids, cache keys, issue/PR numbers — pass
+  the handle and load on demand instead of inlining large contents
 - ~ Use **targeted retrieval**: `grep`, line ranges, `head`/`tail` — not whole-file reads
 - ⊗ **Speculatively loading files** "just in case"
 - ? Pre-fetch a file only when the next step certainly requires it
 
+**Related patterns (do not conflate):**
+
+- **Code Mode** ([patterns/code-mode.md](../patterns/code-mode.md), #2593) —
+  compact tool discovery + sandboxed execute so large *capability* catalogs
+  do not bloat the prompt. Context partitioning (this section) is about
+  *what docs and state* enter context; Code Mode is about *how tools are
+  invoked*.
+- **RLM (citation only):** Recursive Language Models are one recent research
+  framing of model-driven partition → recurse → combine over a prompt-as-
+  environment ([arxiv:2512.24601](https://arxiv.org/abs/2512.24601); popular
+  write-up: [raw.works/rlms-are-the-new-reasoning-models](https://raw.works/rlms-are-the-new-reasoning-models)).
+  Directive's human-curated partitions are **architecturally related**, not
+  an identity claim that "lazy load is an RLM." Headline claims such as
+  "100× context" are **benchmark-dependent and still being validated** —
+  treat them as motivation for partitioning, not as product guarantees.
+  Model-driven runtime partitioning (the model slices and re-queries without
+  a human-authored index) is a different instantiation from REFERENCES /
+  skill-scope curation.
+
 ## Strategy 3: Compress
 
 Reduce token count while preserving signal.

package/context/long-horizon.md

@@ -35,6 +35,18 @@ When tasks have dependencies, express them as vBRIEF edges:
 - ~ Carry the summary forward, not the full history
 - ≉ Re-reading entire conversation history when a checkpoint exists
 
+## Partition → recurse → combine
+
+For large codebases or long documents, **partition** the work into slices,
+**recurse** (or re-enter) with focused context per slice, then **combine**
+results at a higher checkpoint — rather than stuffing the whole surface into
+one window. This is the long-horizon form of human-curated context
+partitioning ([context.md](./context.md) Strategy 2 Select; research framing
+on #487). Prefer handles and slice summaries over pasting full subtree
+contents. Hierarchical compression of *what already happened* remains
+[fractal-summaries.md](./fractal-summaries.md); do not treat that file as a
+rebrand of external RLM identity.
+
 ## Progress Tracking
 
 - ~ Maintain `./vbrief/plan.vbrief.json` for multi-phase work — this is the session-level tactical plan (the *how right now*)

package/context/tool-design.md

@@ -87,7 +87,8 @@ 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
+Mode / a host-side program (related: #1167, #2593; pattern:
+[patterns/code-mode.md](../patterns/code-mode.md)) and multi-step token
 breakpoints (#1170). Those reduce **how many** tools exist; this section
 shapes **how each remaining tool looks** at the dialect layer.
 
@@ -119,7 +120,7 @@ and consumer MCP / product-agent schemas:
 | 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) |
+| **How many tools** exist | [Code Mode](../patterns/code-mode.md) / DSL / abstraction (#1167, #2593) — compact `search`/`describe` + sandboxed `execute` |
 | **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) |

package/docs/consumer-check-contract.md

@@ -1,6 +1,6 @@
 # Consumer check contract (`verify:consumer-check-contract`)
 
-Refs: #3145 · Related: #3070 consumer gate integrity, #1519 check:consumer · Policy: #3189 coverageDebt / checkResume
+Refs: #3145 · Related: #3070 consumer gate integrity, #1519 check:consumer · Policy: #3314 coverageDebt / checkResume (reserved)
 
 ## Problem
 
@@ -49,34 +49,26 @@ Root cause of red `greenfield-python-free-smoke` after #3145: the gate only insp
 
 `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)
+## Coverage-debt hatch and local check resume (#3314)
 
-Release-born hatch and suite-stamp features must not expand to consumers as silent defaults. Project policy lives under `plan.policy` in PROJECT-DEFINITION:
+Release-born hatch and suite-stamp features must not expand to consumers as silent defaults. Two **plain optional** fields live under `plan.policy` in PROJECT-DEFINITION. Both default off. Both are **reserved** — `task check` and `task release` do not read them.
 
-| Field | Shape | Fail-closed when unset |
+| Field | Shape | Fail-closed when absent / invalid / off |
 |---|---|---|
-| `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** |
+| `coverageDebt.mode` | `off \| warn \| hatch` | no hatch soft-pass |
+| `checkResume.localStamp` | `off \| on` | no local suite-stamp resume; **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`).
+Inspect with `deft policy:show --field=coverageDebt` and `--field=checkResume`. Doctor check `coverage-check-resume-policy` reports a **malformed typed block** (advisory skip). Absent or valid values pass. Interactive mutation session-start prints a one-line disclosure when either field is non-default; silent when both default.
 
-### Skippable session nudge
+`task check` is fail-closed **by policy**. The live manual hatch is `--allow-coverage-debt=#N` (#2866). Framework `task release` Step 5 hatch is #3187. These flags do not control either path.
 
-On interactive cold or re-arm **mutation** session-start, when either field is unset:
+### Expansion gates
 
-- **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 |
+| Feature | Status | Notes |
 |---|---|---|
-| 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 |
+| Fast-before-slow gate ordering | Available | Universal UX; no policy wait |
+| Local suite stamp resume | **Reserved** | Setting exists; consumer expansion not implemented |
+| Coverage hatch / auto-file | **Reserved** | Setting exists; consumer expansion not implemented. Live hatch: `--allow-coverage-debt=#N` (#2866) |
 | CI trusts local stamp | **Not v1** | Separate RFC |
 
 ### Non-goals
@@ -84,4 +76,4 @@ On interactive cold or re-arm **mutation** session-start, when either field is u
 - 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.
+- A session-start Strict / Hatch-aware / Later quiz.

package/docs/decision-log.md

@@ -92,9 +92,34 @@ Cross-cutting process/architecture decisions often have empty `activeScopeRefs`.
 | Chat / transcripts | Non-goal |
 | Full inter-run memory (#2741) | Related consumer later; not owned by this surface |
 
+## Overlap-cluster dispose (#3315)
+
+! Human-dispose an overlap cluster with `task decision:write`. Put **every** member issue number in `relatedIssues`. Repeat `--related-issue` once per member, or pass `--body-file` JSON with `relatedIssues: [N, M, ...]`. Include a `revisitTrigger`. Free-text MAY name the relationship (duplicate / consolidate / not-duplicate / parent-child / related) and a proposed canonical. No new schema.
+
+! Before re-recommending an overlap, portfolio-priority runs `task decision:list -- --issue N --json` per cited member and parks only when a dispose decision's `relatedIssues` covers this overlap's members, unless `revisitTrigger` applies. This is **advisory skill diligence**, not a `task check` gate.
+
+⊗ Treat the portfolio brief as the decision record (#3198/#3201). ⊗ Auto-close member issues from a dispose write. ⊗ Replace `triage:mark-duplicate`. ⊗ Project cluster labels.
+
+**Boundaries**
+
+| Surface | Role |
+|---------|------|
+| #886 | Governance tracker |
+| #1178 | Pre-filing |
+| #786 | PR-output cluster |
+| #3198/#3201 | Brief is never the decision record |
+| #1396 (this log) | Phase-1 home for dispose records |
+| `triage:mark-duplicate` | Unchanged |
+| Cluster labels | No projection |
+
+**Ledger earning condition**
+
+A dedicated tracked ledger (`xbrief/.triage-cache/duplicate-clusters.jsonl` + verbs) is **deferred**. Build only when a portfolio/coupling pass re-litigates a cluster **despite** a dispose decision already listing the member issue numbers. Design archive: #3310 (do not re-derive).
+
 ## Consumers
 
 - Portfolio dispose (#3198 / #3201 / pilot #3200)
+- Overlap-cluster dispose (#3315); ledger archive #3310
 - Process policy dogfood (SCM label-mirror first mass-apply #1423)
 - Multi-agent handoff continuity (related #2741 class)
 

package/main.md

@@ -313,11 +313,14 @@ See [`skills/deft-directive-refinement/SKILL.md`](./content/skills/deft-directiv
 
 **Learning:**
 - ~ Continuously improve agent workflows
-- ~ Before implementing, LOAD relevant prior lessons via the content-pack slice surface: discover packs with `task deft:packs:slice --list-packs`, discover a pack's slices with `task deft:packs:slice <pack> --list`, then read the slice you need (read the slice, not the whole file)
-- ~ When repeated correction or better approach found, codify in `./lessons.md`
+- ~ Before implementing, LOAD prior lessons: (1) content-pack slice surface — `task deft:packs:slice --list-packs`, then `task deft:packs:slice <pack> --list` / the needed slice; (2) when present, also read project `./lessons.md` informal inbox so one-off prose is not invisible to the next session
+- ~ Ask: could this failure recur with a different query or different session?
+  - One-off / non-recurrable prose → write `./lessons.md` (informal inbox, readable on next load above); promote durable lessons into the lessons pack source then `task packs:render` — ⊗ hand-edit generated `meta/lessons.md`
+  - Recurrable structural gap → propose skill or directive change via GitHub issue/PR under [Self-Improving, Not Self-Editing (#3164)](#self-improving-not-self-editing-3164) gates — never mid-run constitution self-edit
 - ? Modify `./lessons.md` without prior approval
 - ~ When using codified instruction, inform user which rule was applied
 - ! Promote constitution-tier improvements (skills, policy, managed AGENTS rules) through issue / PR / quality gate — not mid-run self-edit (see [Self-Improving, Not Self-Editing (#3164)](#self-improving-not-self-editing-3164))
+- ? Escalate via kaizen runtime when that skill exists (#666) — pointer only; do not invent the skill here
 
 **Observation:**
 - ~ Think beyond immediate task

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.101.0",
+  "version": "0.103.0",
+  "deftConsumerDeposit": true,
   "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

@@ -13,6 +13,16 @@
       "path": "patterns/agent-skill-supply-chain.md",
       "body": null
     },
+    {
+      "id": "code-mode",
+      "title": "Code Mode \u2014 compact search + sandboxed execute (#2593)",
+      "description": "Pattern for **code-mediated tool use**: the model writes and runs code that orchestrates capabilities, instead of requesting each tool call separately against a large static catalog. The public surface stays tiny (typically `search` / `describe` for progressive discovery and `execute` for sandboxed capability calls); the broader capability graph lives behind that surface in typed code.",
+      "triggers": [
+        "code-mode"
+      ],
+      "path": "patterns/code-mode.md",
+      "body": null
+    },
     {
       "id": "executor-layer-credentials",
       "title": "Executor-layer credentials (#806)",