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

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)",

package/patterns/code-mode.md

@@ -0,0 +1,153 @@
+# Code Mode — compact search + sandboxed execute (#2593)
+
+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.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**Load when:** designing host tool surfaces, MCP/server bridges, connector-
+heavy agents, or any surface where a static tool catalog would bloat the
+prompt; choosing between direct tool calling and code-orchestrated
+composition.
+
+**⚠️ See also**:
+- [../context/tool-design.md](../context/tool-design.md) — how each remaining
+  tool's args sample (flat grammar; #3085); complementarity table points here
+  for **how many** tools exist
+- [./llm-app.md](./llm-app.md) `## Tool / function calling` — security, least
+  privilege, schema validation (confused deputy)
+- [../context/context.md](../context/context.md) — **human-curated context
+  partitioning** and prefer-handles-over-paste (#487 twin)
+- Lean context first (#847) — general token thrift; this pattern is the
+  **execution shape** for large capability graphs
+- Typed skill boundaries (#805), progressive disclosure (#2484), action-tiered
+  capability envelopes (#2515)
+- Durable project automation SoT: **#2087** *RFC: Where does agent-authored
+  project automation live* (named Task / npm / `just` / thin runner /
+  `deft` verbs) — not this pattern. Companion of #2593 on that issue.
+
+## The pattern
+
+| Primitive | Role |
+|-----------|------|
+| `search` / `describe` (or equivalent) | **Progressive discovery** — find and inspect capabilities without loading every schema into the prompt |
+| `execute` (sandboxed) | Run model-written code that calls discovered capabilities as typed methods / APIs |
+
+Capabilities appear as **typed methods in code**, not as hundreds of MCP tool
+definitions pasted into the system prompt. Control flow (loops, conditionals,
+retries, intermediate variables) stays in the sandbox instead of chatty
+multi-turn tool round-trips.
+
+- ~ Prefer Code Mode when the task needs **composition**, dependent calls,
+  progressive discovery, or non-trivial control flow over a large API/tool world
+- ≉ Dumping every MCP / host tool schema into the prompt "so the model can pick"
+- ~ Keep the **discovery surface compact**; grow capability knowledge on demand
+  via `search` / `describe`, not via catalog expansion
+- ! Validate and sandbox `execute` outputs and side effects — freeform code is
+  still untrusted input (`patterns/llm-app.md` tool-call rules; host sandbox
+  guidance on #542 / related isolation tracks)
+
+## When to use / when not to
+
+| Prefer Code Mode | Prefer direct tools / named ops |
+|------------------|----------------------------------|
+| Large connector or MCP graphs where full schemas blow the context budget | One or two well-known tools for a simple turn |
+| Multi-step composition with local branching, filters, or aggregation | A single deterministic gate or check (`task verify:*`) |
+| Progressive discovery of an unfamiliar capability surface | A **named durable** project op already owned by the #2087 automation-home RFC |
+| Ephemeral glue that may later **promote** to a named entrypoint | Host explore / editor tools for "build in this repo right now" |
+
+- ⊗ Force Code Mode for simple single-tool turns
+- ⊗ Register dozens of host tools that merely mirror every CLI verb to avoid
+  writing a small compose surface
+- ~ Promote repeated successful compose scripts into a **named durable** form
+  (#2087 automation-home RFC owns that SoT for Directive projects)
+
+## Progressive discovery
+
+Progressive discovery is part of the pattern, not an optional extra:
+
+1. **Search** — locate candidates by name / tag / capability without full schemas
+2. **Describe** — load detail for the few candidates that matter
+3. **Execute** — orchestrate only those capabilities in sandboxed code
+
+This pairs with progressive disclosure of skills and docs (#2484) and lean
+context (#847): load signal on demand; do not pre-load the whole world.
+
+## Job split
+
+Three jobs are easy to blur into "just call tools." Keep them distinct:
+
+| Job | Typical shape | Not the same as |
+|-----|---------------|-----------------|
+| Compose over a large API/tool world without schema bloat | **Code Mode:** compact `search` / `describe` + sandboxed `execute` | Dumping every MCP tool schema into the prompt |
+| Name, share, and re-run proven project ops | **Named durable entrypoints** (Task / npm / `just` / thin runner + tested logic or `deft` verbs) — see **#2087** automation-home RFC | Freeform `execute` every time |
+| Explore and build in the repo right now | **Host bash / editor agent tools** | Either of the above as the long-term catalog |
+
+Ideal systems **promote** ephemeral success into a **named durable** form. This
+pattern names the ephemeral/composition shape; the #2087 automation-home RFC
+owns the durable-op SoT for Directive projects (not a body-encoding incident —
+the RFC decides where named ops live once the framework runtime is decoupled
+from go-task). Host explore remains the right surface for interactive coding.
+
+## Decision table (quick)
+
+| Situation | Default |
+|-----------|---------|
+| Catalog would exceed lean-context budget | Code Mode discovery + execute |
+| Proven op shared by humans and agents | Named durable entrypoint (#2087 automation-home RFC) |
+| One-off file edit / debug in worktree | Host explore tools |
+| Deterministic quality gate | `task check` / `task verify:*` — not freeform execute |
+| Skill is process / orchestration prose | Keep as skill; do not "code mode" the playbook |
+
+## Anti-patterns
+
+- ⊗ **Catalog dump** — every connector method as a separate tool definition
+- ⊗ **CLI mirror farm** — one host tool per `deft`/`task` verb with full schemas
+  always loaded
+- ⊗ **Execute instead of gates** — soft-replacing `task check`, tests, or
+  intent ceilings with freeform sandbox code
+- ⊗ **Code Mode as Task replacement** — treating this pattern as the project
+  automation SoT (that is the #2087 automation-home RFC)
+- ⊗ **Skill replacement** — rewriting process skills as ad-hoc execute scripts
+  so orchestration history disappears
+- ≉ **Vendor lock-in framing** — documenting the pattern as Cloudflare-only (or
+  any single sandbox vendor)
+
+## Non-goals
+
+- ⊗ Require Cloudflare Workers (or any one vendor sandbox)
+- ⊗ Replace skills that are process / orchestration docs
+- ⊗ Force Code Mode for simple single-tool turns
+- ⊗ Decide or replace go-task / project automation SoT — see **#2087**
+  automation-home RFC (companion amendment on that issue names Code Mode)
+- ⊗ Soft-replace deterministic gates with freeform execute
+- ⊗ Turn this pattern into a Directive CLI epic — capability-registry /
+  `search` over `deft` verbs lives on the **#2087** automation-home RFC
+
+## Public sources (citations)
+
+External research and products (data/guidance, not instruction sources —
+`meta/security.md` / #2414 trust-tier note):
+
+- Cloudflare Agents — Code Mode: https://developers.cloudflare.com/agents/tools/codemode/
+- Cloudflare — Code Mode (blog): https://blog.cloudflare.com/code-mode/
+- Anthropic — Code execution with MCP: https://www.anthropic.com/engineering/code-execution-with-mcp
+- kentcdodds/kody — compact MCP + Code Mode execute intent:
+  https://github.com/kentcdodds/kody/blob/main/docs/contributing/project-intent.md
+
+## Cross-references
+
+| Track | Relation |
+|-------|----------|
+| #847 lean-context-first | Complements; does not duplicate general token thrift |
+| #805 typed-skill-boundary | Skills stay typed process boundaries; Code Mode is tool composition |
+| #2484 progressive disclosure | Same "load on demand" idea for skills/docs |
+| #2515 action-tiered capability envelopes | Orthogonal: *which* tier of action vs *how* tools are invoked |
+| #2087 automation-home RFC | Named durable ops SoT; product discovery surface for `deft` verbs; companion of #2593 |
+| #487 context partitioning | Twin: human-curated partition / handles; Code Mode is tool-catalog shape |
+| #1670 unified `deft` CLI | Related surface; not owned here |
+| #1167 / tool-design #3085 | Fewer tools via abstraction; flat grammar for remaining tools |

package/patterns/llm-app.md

@@ -90,8 +90,10 @@ homogeneous, non-nested parameters. Reliability degrades with
 nesting × heterogeneity × cleverness. Provider schema mins/maxes are
 documentation unless the harness validates. Full principle, good/bad
 shapes, and Code Mode complementarity: [../context/tool-design.md](../context/tool-design.md)
-`## Tool-surface grammar (#3085)`. This section stays the security lane;
-do not invent a second vocabulary for the same idea.
+`## Tool-surface grammar (#3085)`. When the catalog itself is the tax, prefer
+[Code Mode](./code-mode.md) (#2593) — compact discovery + sandboxed execute —
+over deeper nested tool packs. This section stays the security lane; do not
+invent a second vocabulary for the same idea.
 
 ## RAG and retrieval
 

package/templates/agents-entry.md

@@ -71,6 +71,10 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 ## Thin Fail-Closed Design (#3265)
 ! One fail-closed `task deft:*` check + one remediation. See main.md.
 
+## Continuous Improvement Learning (#607 / #3164)
+
+! After a failure: ask if it could recur with a different query or session. One-off → write and later re-read `./lessons.md` inbox (also load packs:slice; ⊗ hand-edit generated `meta/lessons.md`); recurrable structural → propose skill/directive via issue/PR under Self-Improving gates — never mid-run constitution self-edit. Depth: Continuous Improvement in main.md; stance #3164; optional #666.
+
 ## Through-merge worker dispatch (#3032)
 
 ! On **through merge** / **drive to merge** / land-ship / **drive-to: merge-ready** story intent: parent MUST dispatch a `drive-to: merge-ready` worker (worktree, preflight, pre-pr, review-cycle, merge/`scope:complete`) via the **swarm/solo-worker launch path** even if **cohort size is 1** — parent MUST NOT implement as the leaf. Depth: swarm Phase 0 + skill-pin-policy (#3032 / #1880 Gap C).