@deftai/directive-content 0.101.0 → 0.103.0

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/scm/github.md

@@ -393,9 +393,9 @@ Following a v1.0.0 release, commits:
 
 **Framework CI runners (#2672)**:
 - ! `deftai/directive` required CI prefers Blacksmith (`blacksmith-4vcpu-ubuntu-2404`) for TypeScript and Go cost
-- ! Capacity watchdog (~20 minute budget): if a Blacksmith primary job stays `queued` with `runner_name` null and no `started_at`, cancel that queued attempt (concurrency cancel-in-progress) and run the same suite on `ubuntu-latest`
-- ! Branch-protection required check names (`TypeScript (build + lint + test)`, `Go (test + build)`) live **only** on the aggregator jobs — never on primary/failover lane names
-- ⊗ Fail over `in_progress` jobs (execution hangs) — those stay timeout + fix (#2652); capacity failover is queue-stall only
+- ! Capacity watchdog (~20 minute budget): if a required Blacksmith job (TypeScript, Go, or merge-gate) stays unclaimed (`runner_name` null — `started_at` alone is not a claim), cancel that unclaimed attempt and run the same suite on `ubuntu-latest` (#3340)
+- ! Branch-protection required check names (`TypeScript (build + lint + test)`, `Go (test + build)`, `Merge gate (task check)`) live **only** on the aggregator jobs — never on primary/failover lane names
+- ⊗ Fail over a job that has `runner_name` (claimed execution hang) — those stay timeout + fix (#2652); capacity failover is unclaimed-queue stall only (#3340)
 - ! Consumer scaffolds and `npm-publish.yml` stay on GitHub-hosted `ubuntu-latest` (Blacksmith is opt-in for consumer orgs; npm `--provenance` requires GH-hosted)
 - ! Agents seeing `runner_capacity_stall` / `RUNNER_CAPACITY_STALL` MUST wait for auto-failover — ⊗ `--skip-ci` as a capacity remedy
 

package/skills/deft-directive-build/SKILL.md

@@ -366,6 +366,15 @@ task verify:ac -- <active-story-path>
 - ⊗ Skip this gate because ceremony dial is rapid/minimal — rapid's positive content is exactly this check (#3284).
 - ⊗ Leave `plan.acceptance.commands` empty without `none_stated: true` — absence must be an explicit decision.
 
+## Product-oracle gate integrity (#3322 / #3156)
+
+A red product verification may be resolved only by a product change or an independently re-derived oracle (both sides rebuilt from scratch, different method). In-place repair of the failing comparison then pass is not a pass — it is an unresolved discrepancy.
+
+- ! When a product oracle is red, resolve it by changing the product or by independently re-deriving the oracle, and record `independent_rederivation` on the run-summary `verification` event.
+- ! Emit a run-summary verification event `{check_id, method_fingerprint, outcome}` for each product-oracle attempt when `DEFT_RUN_SUMMARY_PATH` is set. `fail` then a different `method_fingerprint` then `pass` on one check id is machine-flagged.
+- ! `task verify:ac` treats comparison-method mutation as unresolved (exit non-zero) unless independent re-derivation is recorded. Lead the done report with any unresolved discrepancy (#1006).
+- ⊗ Self-adjudicate a red product oracle by editing the comparison (reference file, diff invocation, one-sided regenerate) and shipping the new pass as success.
+
 ## Operator-log hygiene (lazy-load, #1940)
 
 When the story touches **operator-facing** services (dashboards, multi-process
@@ -510,3 +519,4 @@ Docs: `docs/decision-log.md` · `xbrief/decisions/README.md`.
 - ⊗ Silently skip deepening for budget without a fail-loud summary note (#3266 / #1006)
 - ⊗ Chase post-bank out-of-scope findings when surplus budget is insufficient — report, do not thrash the banked pass (#3285)
 - ⊗ Skip finalize-on-green after first stated AC pass under a hard budget (#3285)
+- ⊗ Clear a red product oracle by editing the comparison method then treating the new pass as a pass — record independent re-derivation or fix the product (#3322 / #3156)

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

@@ -84,16 +84,18 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 3. ! Emit an ordered **shortlist** (deep dive / promote candidates) and a **park list** with park reasons.
 4. ! Separate **interrupt / non-portfolio** rows (escalate, hold, already dispositioned) so they are not ranked against park list.
 5. ⊗ Claim "#X supersedes #Y" from titles alone — see Phase 4 epistemic gates.
+6. ! **List-before-re-recommend** (#3315): for each cited `#N` before re-recommending an overlap, run `task decision:list -- --issue N --json` and match `relatedIssues` from the JSON. Park / do not re-shortlist as novel overlap only when a dispose decision's `relatedIssues` covers this overlap's members (not some other relationship that merely mentions N), unless `revisitTrigger` applies. Advisory diligence — not a `task check` gate. ⊗ Auto-close issues or treat the brief as the dispose record.
+7. Parent/child, leaf/tracker, and sibling-validator pairs are **not** duplicates — #3066/#3082, #95/#96, #513/#514.
 
 ### Phase 4 — Epistemic gates (MUST)
 
 Before citing any `#N` in the brief:
 
 1. ! **Verify existence + state** for every cited issue via live `gh api repos/OWNER/NAME/issues/N` (REST) **or** a proven-fresh cache entry whose state matches the claim.
-2. ! **Read the body** of every issue used for shortlist, park-as-superseded, pack membership, or "decided" claims.
+2. ! **Read the body** of every issue used for shortlist, park-as-superseded, duplicate/consolidate classification, pack membership, or "decided" claims.
 3. ! When claiming decided / superseded / closed-by-comment, also **read comments** (REST `issues/N/comments`).
 4. ! State **open/closed accurately**; never invent issue numbers.
-5. ⊗ **Title-only supersession** or ownership claims.
+5. ⊗ **Title-only supersession**, duplicate, or ownership claims.
 6. ⊗ Cite PRs as issues without filtering `pull_request` on mixed issue lists.
 
 ### Phase 5 — Emit priority brief
@@ -117,9 +119,10 @@ Before citing any `#N` in the brief:
 ### Phase 6 — Dispose checklist (hand off)
 
 1. ! Present the dispose checklist to the operator (accept/edit shortlist + park; record dispose; optional plan-sequence for P1).
-2. ! Point dispose targets: `task decision:write` (#1396 structured decision log under `xbrief/decisions/`; optional interim issue comment only if the write surface is unavailable), and/or `task plan-sequence:set`.
+2. ! Point dispose targets: `task decision:write` (#1396 / [`docs/decision-log.md`](../../docs/decision-log.md)): every overlap-cluster member in `relatedIssues`; include `revisitTrigger`; free-text MAY name relationship. Optional `task plan-sequence:set`. Interim issue comment only if the write surface is unavailable.
 3. ⊗ Auto-promote shortlist into plan-sequence without explicit operator dispose.
 4. ⊗ Exit treating the brief alone as durable prioritization memory (#2741 class).
+~ Dedicated duplicate-clusters ledger is deferred; earn it only when a pass re-litigates a cluster despite a dispose decision listing the members (#3310). Boundaries: #886, #1178, #786, #3198/#3201, #1396.
 
 ## Anti-Patterns
 
@@ -130,6 +133,7 @@ Before citing any `#N` in the brief:
 - ⊗ Full open-backlog unattended ranking without an explicit slice
 - ⊗ Replacing `triage:queue` for buildable work selection
 - ⊗ Treating the brief as the decision record without dispose
+- ⊗ Re-shortlist a disposed overlap without `task decision:list -- --issue N` (#3315)
 
 ## EXIT
 
@@ -141,4 +145,5 @@ Before citing any `#N` in the brief:
 
 - #3198 process + dogfood · #3201 this skill · #3200 / patterns pilot brief
 - #1396 decision log · #3179 propose-not-apply · #1423 / #3197 classify filter only
+- #3315 overlap dispose · #3310 ledger archive · #886 / #1178 / #786 boundaries
 - Siblings: `deft-directive-triage`, `deft-directive-refinement` — not #1419/#1511 post-promotion

package/skills/deft-directive-pre-pr/SKILL.md

@@ -181,6 +181,15 @@ When session effort-budget is hard-capped (`DEFT_MAX_TURNS` / `DEFT_MAX_BUDGET`
 - ! Full `task check` already runs `verify:ac` first; still run it explicitly before push when AC is stated so failures are visible without the full hygiene suite.
 - ⊗ Skip AC run on rapid/minimal ceremony dial — rapid = AC-only; AC never degrades when commands exist (#3284 / #3156).
 
+## Product-oracle gate integrity (#3322 / #3156)
+
+A red product verification may be resolved only by a product change or an independently re-derived oracle (both sides rebuilt from scratch, different method). In-place repair of the failing comparison then pass is not a pass — it is an unresolved discrepancy.
+
+- ! When a product oracle is red, resolve it by changing the product or by independently re-deriving the oracle, and record `independent_rederivation` on the run-summary `verification` event.
+- ! Emit a run-summary verification event `{check_id, method_fingerprint, outcome}` for each product-oracle attempt when `DEFT_RUN_SUMMARY_PATH` is set. `fail` then a different `method_fingerprint` then `pass` on one check id is machine-flagged.
+- ! `task verify:ac` treats comparison-method mutation as unresolved (exit non-zero) unless independent re-derivation is recorded. Lead the done report with any unresolved discrepancy (#1006).
+- ⊗ Self-adjudicate a red product oracle by editing the comparison (reference file, diff invocation, one-sided regenerate) and shipping the new pass as success.
+
 ## Probe-then-fill remote claims (#3120)
 
 ! Before filling any **remote** handoff field (PR URL, PR number, commit/HEAD SHA, CI green/success, review score) or claiming `status: pass` / ship/gate done, MUST **probe then fill**:
@@ -228,5 +237,6 @@ Docs: `docs/decision-log.md`.
 - ⊗ Invent remote PR/SHA/CI/review claims in handoff evidence without same-turn probe binding — invented-done (#3120)
 - ⊗ Fill remote ship/gate fields from memory when only local work completed; legal partial omits PR fields (#3120)
 - ⊗ Clear a failing gate by editing the gate (definition, verifier, reward, required check, coverage floor, policy, eval fixture) instead of the work under test — gate integrity (#3156); see [docs/gate-integrity.md](../../docs/gate-integrity.md)
+- ⊗ Clear a red product oracle by editing the comparison method then treating the new pass as a pass — record independent re-derivation or fix the product (#3322 / #3156)
 - ⊗ Under a hard turn/cost budget, gold-plate pre-PR polish past the stated bar until the budget expires (#3266)
 - ⊗ Exit pre-PR after skipping deepen-for-budget without naming the skip in the summary (#3266 / #1006)

package/skills/deft-directive-release/SKILL.md

@@ -144,7 +144,7 @@ See [`docs/RELEASING.md`](../../../docs/RELEASING.md) § Fixable check failure d
 2. If **no open coverage-debt issue exists** → auto-hatch files `#N` (or operator files manually) with title prefix `coverage-debt:` and body containing both markers. The open `#N` remains WIP until coverage is restored and the issue is closed.
 3. If an **open coverage-debt issue from a prior hatch still exists** → ⊗ soft-pass again; restore real coverage (all four metrics ≥ 85%) and close the debt issue before the cut proceeds.
 
-**Framework-release-first (#3187):** auto-hatch applies to framework `task release` Step 5 (e.g. deftai/directive). Consumer expansion of auto-hatch is blocked on project `plan.policy.coverageDebt` (#3189) — refuse when `status=unset` or `mode=off`. Do not auto-file debt on the framework repo from consumer trees; consumer ledger is always the consumer repo.
+**Framework-release-first (#3187):** auto-hatch applies to framework `task release` Step 5 (e.g. deftai/directive). Consumer expansion of auto-hatch via `plan.policy.coverageDebt` is reserved; consumer expansion is not implemented (#3314). Refuse when unset or off. Live hatch is `--allow-coverage-debt=#N` (#2866). Do not auto-file debt on the framework repo from consumer trees; consumer ledger is always the consumer repo.
 
 ⊗ Auto-pass on a near-miss band without `#N` (#2573).
 ⊗ Silent soft-pass with no tracked issue.

package/tasks/engine-invoke.cjs

@@ -11,6 +11,18 @@
  */
 
 const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+/** Consumer-deposit identity (#3324). Present on @deftai/directive-content. */
+const CONSUMER_DEPOSIT_FIELD = "deftConsumerDeposit";
+/** Optional marker file at DEFT_ROOT (installer / test fixture). */
+const CONSUMER_DEPOSIT_MARKER_FILE = ".deft-consumer-deposit";
+/** Published content-package name also identifies a deposit. */
+const CONTENT_PACKAGE_NAME = "@deftai/directive-content";
+/** Single remediation when a deposit has no global CLI (#3324 / #3265). */
+const DEPOSIT_REMEDIATION = "npm i -g @deftai/directive";
+const SOURCE_BUILD_REMEDIATION = "task build";
 
 /**
  * cmd.exe command separators / metacharacters. Free-text DEFT_ENGINE_CMD_JSON
@@ -73,6 +85,142 @@ function shellSplit(input) {
   return out;
 }
 
+/**
+ * True when DEFT_ROOT is a consumer deposit, not a framework source checkout.
+ * Honors an explicit package.json field, the content-package name, or a
+ * marker file. #3324: deposits must never take the self-build path.
+ * @param {string} root
+ * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
+ */
+/**
+ * Consumer Taskfile includes live at `.deft/core/tasks/`, so DEFT_ROOT is
+ * `.deft/core`. Framework source uses repo-root `tasks/`. Go source-tarball
+ * deposits keep the unmarked monorepo package.json at that core root (#3324
+ * Greptile P1) — the path itself is the deposit identity.
+ * @param {string} root
+ */
+function isVendoredCoreRoot(root, opts = {}) {
+  const io = opts.fs || fs;
+  const pathMod = opts.path || path;
+  const norm = String(root).replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!/(^|\/)\.deft\/core$/.test(norm)) {
+    return false;
+  }
+  // Installer tarballs exclude .git (#1425). A genuine source checkout mounted
+  // at this path still has .git and must keep the self-build path.
+  try {
+    if (io.existsSync(pathMod.join(root, ".git"))) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+function hasConsumerDepositMarker(root, opts = {}) {
+  const io = opts.fs || fs;
+  const pathMod = opts.path || path;
+  if (!root) {
+    return false;
+  }
+  if (isVendoredCoreRoot(root, opts)) {
+    return true;
+  }
+  const markerPath = pathMod.join(root, CONSUMER_DEPOSIT_MARKER_FILE);
+  try {
+    if (io.existsSync(markerPath)) {
+      return true;
+    }
+  } catch {
+    // ignore unreadable marker path
+  }
+  const pkgPath = pathMod.join(root, "package.json");
+  try {
+    const pkg = JSON.parse(io.readFileSync(pkgPath, "utf8"));
+    if (pkg && pkg[CONSUMER_DEPOSIT_FIELD] === true) {
+      return true;
+    }
+    if (pkg && pkg.name === CONTENT_PACKAGE_NAME) {
+      return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+/**
+ * Buildable-source means "may run pnpm/corepack/`task build`". A deposit
+ * marker forces false even when packages/cli + scripts.build are present.
+ * @param {string} root
+ * @param {{ fs?: typeof fs, path?: typeof path }} [opts]
+ */
+function isBuildableSource(root, opts = {}) {
+  if (hasConsumerDepositMarker(root, opts)) {
+    return false;
+  }
+  const io = opts.fs || fs;
+  const pathMod = opts.path || path;
+  if (!root) {
+    return false;
+  }
+  const cliPkg = pathMod.join(root, "packages", "cli", "package.json");
+  const rootPkg = pathMod.join(root, "package.json");
+  try {
+    if (!io.existsSync(cliPkg) || !io.existsSync(rootPkg)) {
+      return false;
+    }
+    const pkg = JSON.parse(io.readFileSync(rootPkg, "utf8"));
+    return Boolean(pkg && pkg.scripts && pkg.scripts.build);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Dispatch decision after local dist / buildable / runtime-whitelist probes.
+ * Deposit marker is applied via isBuildableSource(false); this keeps the
+ * runtime-verb whitelist for true source checkouts only (#3324 / #2409).
+ *
+ * @param {{
+ *   hasBin: boolean,
+ *   isBuildableSource: boolean,
+ *   isRuntimeVerb: boolean,
+ *   hasGlobalCli: boolean,
+ * }} input
+ * @returns {{
+ *   action: "vendored" | "global" | "fail-closed",
+ *   remediations?: string[],
+ *   exitCode?: number,
+ * }}
+ */
+function resolveInvokeDispatch(input) {
+  if (input.hasBin) {
+    return { action: "vendored" };
+  }
+  if (input.isBuildableSource) {
+    if (input.isRuntimeVerb && input.hasGlobalCli) {
+      return { action: "global" };
+    }
+    return {
+      action: "fail-closed",
+      remediations: input.isRuntimeVerb
+        ? [DEPOSIT_REMEDIATION, SOURCE_BUILD_REMEDIATION]
+        : [SOURCE_BUILD_REMEDIATION],
+      exitCode: 2,
+    };
+  }
+  if (input.hasGlobalCli) {
+    return { action: "global" };
+  }
+  return {
+    action: "fail-closed",
+    remediations: [DEPOSIT_REMEDIATION],
+    exitCode: 2,
+  };
+}
+
 function main() {
   const mode = process.argv[2];
   const target = process.argv[3];
@@ -171,7 +319,28 @@ function buildSpawnPlan(mode, target, argv, opts = {}) {
 }
 
 if (require.main === module) {
+  const mode = process.argv[2];
+  if (mode === "deposit-marker") {
+    process.exit(hasConsumerDepositMarker(process.argv[3] || "") ? 0 : 1);
+  }
+  if (mode === "is-buildable-source") {
+    process.exit(isBuildableSource(process.argv[3] || "") ? 0 : 1);
+  }
   main();
 }
 
-module.exports = { shellSplit, quoteWin32Arg, buildSpawnPlan, WIN32_CMD_METACHAR_RE };
+module.exports = {
+  shellSplit,
+  quoteWin32Arg,
+  buildSpawnPlan,
+  WIN32_CMD_METACHAR_RE,
+  hasConsumerDepositMarker,
+  isVendoredCoreRoot,
+  isBuildableSource,
+  resolveInvokeDispatch,
+  CONSUMER_DEPOSIT_FIELD,
+  CONSUMER_DEPOSIT_MARKER_FILE,
+  CONTENT_PACKAGE_NAME,
+  DEPOSIT_REMEDIATION,
+  SOURCE_BUILD_REMEDIATION,
+};

package/tasks/engine-invoke.test.cjs

@@ -2,12 +2,23 @@
 "use strict";
 
 const assert = require("node:assert/strict");
-const { describe, it } = require("node:test");
+const { spawnSync } = require("node:child_process");
+const { mkdtempSync, mkdirSync, writeFileSync, rmSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+const { describe, it, after } = require("node:test");
 const {
   shellSplit,
   quoteWin32Arg,
   buildSpawnPlan,
   WIN32_CMD_METACHAR_RE,
+  hasConsumerDepositMarker,
+  isVendoredCoreRoot,
+  isBuildableSource,
+  resolveInvokeDispatch,
+  CONSUMER_DEPOSIT_MARKER_FILE,
+  CONTENT_PACKAGE_NAME,
+  DEPOSIT_REMEDIATION,
 } = require("./engine-invoke.cjs");
 
 const WIN32 = { platform: "win32", nodePath: "/node" };
@@ -203,7 +214,141 @@ describe("buildSpawnPlan — CodeQL absolute-path isolation (#3175 / alert #74)"
     assert.equal(plan.args[3].includes("node.exe"), false);
     assert.deepEqual(splitCmdTokens(plan.args[3]), ["deft", "release", "--summary", "ok"]);
   });
+});
+
+describe("consumer-deposit marker (#3324)", () => {
+  const created = [];
+
+  after(() => {
+    for (const dir of created.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  function tempRoot() {
+    const dir = mkdtempSync(join(tmpdir(), "3324-deposit-"));
+    created.push(dir);
+    return dir;
+  }
+
+  function writePkg(dir, pkg) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify(pkg), "utf8");
+  }
+
+  function writeBuildableTree(dir, pkgExtra = {}) {
+    writePkg(dir, { name: "looks-like-source", scripts: { build: "tsc -b" }, ...pkgExtra });
+    mkdirSync(join(dir, "packages", "cli"), { recursive: true });
+    writePkg(join(dir, "packages", "cli"), { name: "@deftai/directive-cli" });
+  }
+
+  it("detects the package.json deftConsumerDeposit field", () => {
+    const root = tempRoot();
+    writePkg(root, { name: "app", deftConsumerDeposit: true, scripts: { build: "tsc" } });
+    assert.equal(hasConsumerDepositMarker(root), true);
+  });
+
+  it("detects @deftai/directive-content as a deposit", () => {
+    const root = tempRoot();
+    writePkg(root, { name: CONTENT_PACKAGE_NAME, scripts: { build: "tsc" } });
+    assert.equal(hasConsumerDepositMarker(root), true);
+  });
+
+  it("detects the .deft-consumer-deposit marker file", () => {
+    const root = tempRoot();
+    writePkg(root, { name: "app", scripts: { build: "tsc" } });
+    writeFileSync(join(root, CONSUMER_DEPOSIT_MARKER_FILE), "1\n", "utf8");
+    assert.equal(hasConsumerDepositMarker(root), true);
+  });
+
+  it("does not mark a framework source checkout", () => {
+    const root = tempRoot();
+    writeBuildableTree(root);
+    assert.equal(hasConsumerDepositMarker(root), false);
+    assert.equal(isBuildableSource(root), true);
+  });
+
+  it("treats a .deft/core DEFT_ROOT as a deposit (Go source-tarball layout)", () => {
+    const root = join(tempRoot(), ".deft", "core");
+    writeBuildableTree(root);
+    assert.equal(isVendoredCoreRoot(root), true);
+    assert.equal(hasConsumerDepositMarker(root), true);
+    assert.equal(isBuildableSource(root), false);
+  });
 
+  it("does not treat a source checkout mounted at .deft/core as a deposit", () => {
+    const root = join(tempRoot(), ".deft", "core");
+    writeBuildableTree(root);
+    mkdirSync(join(root, ".git"));
+    assert.equal(isVendoredCoreRoot(root), false);
+    assert.equal(isBuildableSource(root), true);
+  });
+
+  it("never treats a marked deposit as buildable source", () => {
+    const root = tempRoot();
+    writeBuildableTree(root, { deftConsumerDeposit: true });
+    assert.equal(hasConsumerDepositMarker(root), true);
+    assert.equal(isBuildableSource(root), false);
+  });
+
+  it("routes every deposit verb via global CLI (not the self-build path)", () => {
+    const plan = resolveInvokeDispatch({
+      hasBin: false,
+      isBuildableSource: false,
+      isRuntimeVerb: false,
+      hasGlobalCli: true,
+    });
+    assert.deepEqual(plan, { action: "global" });
+  });
+
+  it("fails closed with the one remediation when a deposit has no global CLI", () => {
+    const plan = resolveInvokeDispatch({
+      hasBin: false,
+      isBuildableSource: false,
+      isRuntimeVerb: false,
+      hasGlobalCli: false,
+    });
+    assert.equal(plan.action, "fail-closed");
+    assert.equal(plan.exitCode, 2);
+    assert.deepEqual(plan.remediations, [DEPOSIT_REMEDIATION]);
+    assert.equal(DEPOSIT_REMEDIATION, "npm i -g @deftai/directive");
+  });
+
+  it("keeps the runtime-verb whitelist for true source checkouts", () => {
+    const runtime = resolveInvokeDispatch({
+      hasBin: false,
+      isBuildableSource: true,
+      isRuntimeVerb: true,
+      hasGlobalCli: true,
+    });
+    assert.deepEqual(runtime, { action: "global" });
+
+    const check = resolveInvokeDispatch({
+      hasBin: false,
+      isBuildableSource: true,
+      isRuntimeVerb: false,
+      hasGlobalCli: true,
+    });
+    assert.equal(check.action, "fail-closed");
+    assert.deepEqual(check.remediations, ["task build"]);
+  });
+
+  it("CLI probe exits 0 for a marked deposit and 1 for is-buildable-source", () => {
+    const root = tempRoot();
+    writeBuildableTree(root, { deftConsumerDeposit: true });
+    const script = join(__dirname, "engine-invoke.cjs");
+    const marker = spawnSync(process.execPath, [script, "deposit-marker", root], {
+      encoding: "utf8",
+    });
+    assert.equal(marker.status, 0, marker.stderr);
+    const buildable = spawnSync(process.execPath, [script, "is-buildable-source", root], {
+      encoding: "utf8",
+    });
+    assert.equal(buildable.status, 1, buildable.stderr);
+  });
+});
+
+describe("buildSpawnPlan — CodeQL absolute-path isolation (#3175 / alert #74)", () => {
   it("uses nodePath only as the non-shell vendored command (never cmd.exe)", () => {
     const nodePath = String.raw`C:\Program Files\nodejs\node.exe`;
     const plan = buildSpawnPlan("vendored", String.raw`C:\repo\packages\cli\dist\bin.js`, ["session:start"], {