agentfootprint 8.3.0 → 8.5.0

package/dist/esm/lib/injection-engine/skillBodyDelivery.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Where a skill's BODY actually lands — and the one combination where the honest
+ * answer is "nowhere" (8.5.0).
+ *
+ * `surfaceMode` names a delivery CHANNEL, and `'tool-only'` names the channel that
+ * only exists when the model calls `read_skill`: the body is returned as that tool's
+ * result, and the system slot suppresses it by design (`buildSystemPromptSlot`,
+ * mirrored in `routeActiveInjections`). That is exactly right for a skill `read_skill`
+ * activates, which is what the mode was designed against and what every shipped
+ * Block-C test covers.
+ *
+ * It is a hole for a skill the GRAPH activates. A route target, a flat entry and a
+ * decision-tree leaf all activate off the cursor, without any `read_skill` call — so
+ * the tool result never happens, the system slot suppresses the body anyway, and the
+ * body reaches the model through no channel at all. The skill's TOOLS still arrive,
+ * which makes it worse than the skill not loading: the model is handed the tools of a
+ * procedure it was never told.
+ *
+ * The rule that closes it is the one 8.4.0 already uses for the `read_skill` gate:
+ * `trigger.kind === 'llm-activated'` is precisely "read_skill can really activate
+ * this". A skill may claim the read_skill delivery channel exactly when read_skill is
+ * what activates it.
+ *
+ * Refusal rather than a quiet fall back to the system slot, because the author wrote
+ * `'tool-only'` to keep the body OUT of the system prompt (token cost, attention
+ * placement). Silently putting it back would honour the activation and break the
+ * declaration — a different lie, not a fix. `'both'` already means "deliver it either
+ * way", so the refusal has a real, one-word answer to name.
+ */
+import type { Injection } from './types.js';
+import { type SurfaceMode } from './factories/defineSkill.js';
+/**
+ * The surface mode a skill will be TREATED as at runtime.
+ *
+ * Today the runtime compares the literal string, so `'auto'` is its own mode and
+ * lands in the system slot — pass no provider and that is what you get back, which
+ * is the truth about the current engine.
+ *
+ * Pass a provider (and model) to ask the OTHER question: what would `'auto'` become
+ * if the `resolveSurfaceMode` cascade were wired into the runtime? It resolves to
+ * `'tool-only'` for every non-Claude provider, so wiring it in without this guard
+ * would silently open the delivered-nowhere hole for every OpenAI / Bedrock / Ollama
+ * user at once. Routing both questions through ONE function is what keeps that from
+ * being a future accident: the refusal below is written against this, so the day the
+ * cascade is wired in, the guard already covers it.
+ */
+export declare function resolvedSurfaceModeOf(skill: Injection, provider?: string, model?: string): SurfaceMode;
+/**
+ * Can this skill's body be delivered through the `read_skill` tool result?
+ *
+ * Only if `read_skill` is what activates it. `'llm-activated'` is the one trigger
+ * kind that reads `activatedInjectionIds`, which is the only thing a `read_skill`
+ * call writes — the same clause the gate's open-skill rule turns on (8.4.0).
+ */
+export declare function activatesByRead(skill: Injection): boolean;
+/**
+ * Refuse every skill that claims the `read_skill` delivery channel without being
+ * activated by `read_skill`. Returns the message, or `undefined` when all is well.
+ *
+ * Runs over the FINAL injection list — the agent is the only place that sees every
+ * skill's compiled trigger, whichever call registered it — and names every offender,
+ * because `skillsFromDir({ surfaceMode: 'tool-only' })` under a graph refuses a whole
+ * directory at once and a list is debuggable where one sample is not.
+ */
+export declare function toolOnlyDeliveryRefusal(injections: readonly Injection[]): string | undefined;

package/dist/esm/lib/injection-engine/skillBodyDelivery.js

@@ -0,0 +1,110 @@
+/**
+ * Where a skill's BODY actually lands — and the one combination where the honest
+ * answer is "nowhere" (8.5.0).
+ *
+ * `surfaceMode` names a delivery CHANNEL, and `'tool-only'` names the channel that
+ * only exists when the model calls `read_skill`: the body is returned as that tool's
+ * result, and the system slot suppresses it by design (`buildSystemPromptSlot`,
+ * mirrored in `routeActiveInjections`). That is exactly right for a skill `read_skill`
+ * activates, which is what the mode was designed against and what every shipped
+ * Block-C test covers.
+ *
+ * It is a hole for a skill the GRAPH activates. A route target, a flat entry and a
+ * decision-tree leaf all activate off the cursor, without any `read_skill` call — so
+ * the tool result never happens, the system slot suppresses the body anyway, and the
+ * body reaches the model through no channel at all. The skill's TOOLS still arrive,
+ * which makes it worse than the skill not loading: the model is handed the tools of a
+ * procedure it was never told.
+ *
+ * The rule that closes it is the one 8.4.0 already uses for the `read_skill` gate:
+ * `trigger.kind === 'llm-activated'` is precisely "read_skill can really activate
+ * this". A skill may claim the read_skill delivery channel exactly when read_skill is
+ * what activates it.
+ *
+ * Refusal rather than a quiet fall back to the system slot, because the author wrote
+ * `'tool-only'` to keep the body OUT of the system prompt (token cost, attention
+ * placement). Silently putting it back would honour the activation and break the
+ * declaration — a different lie, not a fix. `'both'` already means "deliver it either
+ * way", so the refusal has a real, one-word answer to name.
+ */
+import { resolveSurfaceMode } from './factories/defineSkill.js';
+/** A skill's declared surface mode, before any provider resolution. */
+function declaredSurfaceModeOf(skill) {
+    const meta = skill.metadata;
+    return meta?.surfaceMode ?? 'auto';
+}
+/**
+ * The surface mode a skill will be TREATED as at runtime.
+ *
+ * Today the runtime compares the literal string, so `'auto'` is its own mode and
+ * lands in the system slot — pass no provider and that is what you get back, which
+ * is the truth about the current engine.
+ *
+ * Pass a provider (and model) to ask the OTHER question: what would `'auto'` become
+ * if the `resolveSurfaceMode` cascade were wired into the runtime? It resolves to
+ * `'tool-only'` for every non-Claude provider, so wiring it in without this guard
+ * would silently open the delivered-nowhere hole for every OpenAI / Bedrock / Ollama
+ * user at once. Routing both questions through ONE function is what keeps that from
+ * being a future accident: the refusal below is written against this, so the day the
+ * cascade is wired in, the guard already covers it.
+ */
+export function resolvedSurfaceModeOf(skill, provider, model) {
+    const declared = declaredSurfaceModeOf(skill);
+    if (declared !== 'auto' || provider === undefined)
+        return declared;
+    return resolveSurfaceMode(provider, model);
+}
+/**
+ * Can this skill's body be delivered through the `read_skill` tool result?
+ *
+ * Only if `read_skill` is what activates it. `'llm-activated'` is the one trigger
+ * kind that reads `activatedInjectionIds`, which is the only thing a `read_skill`
+ * call writes — the same clause the gate's open-skill rule turns on (8.4.0).
+ */
+export function activatesByRead(skill) {
+    return skill.trigger.kind === 'llm-activated';
+}
+/** How a refused skill is identified back to its author, so a directory-sized
+ *  refusal reads as a list of names and reasons rather than one mystery. */
+function describeRouting(skill) {
+    const routing = skill.metadata
+        ?.skillGraph;
+    if (routing?.via === 'route') {
+        return routing.from
+            ? `a route target (the graph routes "${routing.from}" → "${skill.id}")`
+            : 'a route target';
+    }
+    if (routing?.via === 'entry')
+        return 'a graph entry';
+    if (routing?.via === 'tree')
+        return 'a decision-tree leaf';
+    return `activated by rule (trigger '${skill.trigger.kind}')`;
+}
+/**
+ * Refuse every skill that claims the `read_skill` delivery channel without being
+ * activated by `read_skill`. Returns the message, or `undefined` when all is well.
+ *
+ * Runs over the FINAL injection list — the agent is the only place that sees every
+ * skill's compiled trigger, whichever call registered it — and names every offender,
+ * because `skillsFromDir({ surfaceMode: 'tool-only' })` under a graph refuses a whole
+ * directory at once and a list is debuggable where one sample is not.
+ */
+export function toolOnlyDeliveryRefusal(injections) {
+    const offenders = injections.filter((i) => i.flavor === 'skill' &&
+        resolvedSurfaceModeOf(i) === 'tool-only' &&
+        !activatesByRead(i) &&
+        (i.inject.systemPrompt ?? '').length > 0);
+    if (offenders.length === 0)
+        return undefined;
+    const list = offenders.map((s) => `  • "${s.id}" — ${describeRouting(s)}`).join('\n');
+    const subject = offenders.length === 1 ? 'This skill sets' : 'These skills set';
+    const its = offenders.length === 1 ? 'its' : 'their';
+    return (`Agent: ${subject} surfaceMode: 'tool-only', which delivers the body as the ` +
+        `read_skill tool result — but nothing here activates by read_skill, so ${its} ` +
+        `body would reach the model NOWHERE: the system slot suppresses a tool-only body ` +
+        `by design, and no read_skill call happens to carry it.\n${list}\n` +
+        `Use 'both' (system prompt AND tool result) or 'system-prompt'. Only a skill ` +
+        `read_skill actually activates — trigger 'llm-activated', which is every skill a ` +
+        `graph does not route — can be 'tool-only'.`);
+}
+//# sourceMappingURL=skillBodyDelivery.js.map

package/dist/esm/lib/injection-engine/skillBodyDelivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillBodyDelivery.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillBodyDelivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,kBAAkB,EAAoB,MAAM,4BAA4B,CAAC;AAElF,uEAAuE;AACvE,SAAS,qBAAqB,CAAC,KAAgB;IAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,QAAqD,CAAC;IACzE,OAAO,IAAI,EAAE,WAAW,IAAI,MAAM,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAgB,EAChB,QAAiB,EACjB,KAAc;IAEd,MAAM,QAAQ,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACnE,OAAO,kBAAkB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,eAAe,CAAC;AAChD,CAAC;AAED;4EAC4E;AAC5E,SAAS,eAAe,CAAC,KAAgB;IACvC,MAAM,OAAO,GAAI,KAAK,CAAC,QAAyE;QAC9F,EAAE,UAAU,CAAC;IACf,IAAI,OAAO,EAAE,GAAG,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,IAAI;YACjB,CAAC,CAAC,qCAAqC,OAAO,CAAC,IAAI,QAAQ,KAAK,CAAC,EAAE,IAAI;YACvE,CAAC,CAAC,gBAAgB,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,EAAE,GAAG,KAAK,OAAO;QAAE,OAAO,eAAe,CAAC;IACrD,IAAI,OAAO,EAAE,GAAG,KAAK,MAAM;QAAE,OAAO,sBAAsB,CAAC;IAC3D,OAAO,+BAA+B,KAAK,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;AAC/D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAgC;IACtE,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CACjC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,MAAM,KAAK,OAAO;QACpB,qBAAqB,CAAC,CAAC,CAAC,KAAK,WAAW;QACxC,CAAC,eAAe,CAAC,CAAC,CAAC;QACnB,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAC3C,CAAC;IACF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7C,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtF,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,CAAC;IAChF,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;IACrD,OAAO,CACL,UAAU,OAAO,4DAA4D;QAC7E,yEAAyE,GAAG,GAAG;QAC/E,kFAAkF;QAClF,2DAA2D,IAAI,IAAI;QACnE,8EAA8E;QAC9E,kFAAkF;QAClF,4CAA4C,CAC7C,CAAC;AACJ,CAAC"}

package/dist/esm/lib/injection-engine/skillGraph.d.ts

@@ -12,8 +12,9 @@
  *
  * **v2 keystone — `from` IS enforced (a sticky cursor state machine).** A skill
  * graph is a state machine over skills; the engine tracks which node it is in via
- * `InjectionContext.currentSkillId` (the cursor). One pure resolver — `nextSkill(ctx)`
- * (see `makeNextSkill`) — is the single source of truth: each route target B
+ * `InjectionContext.currentSkillId` (the cursor). One pure resolver — `resolveCursor`
+ * (see `makeResolveCursor`), of which `nextSkill(ctx)` is the `.to` projection — is the
+ * single source of truth: each route target B
  * compiles to the trigger `nextSkill(ctx) === B`, which delivers `from`-gating
  * (an edge `A→B` fires only while the cursor is on A — no cross-skill edge bleed),
  * stickiness (the cursor stays on B until an edge leaves B), and a clean handoff
@@ -24,16 +25,26 @@
  * compiled trigger is always a `rule`. `toMermaid()` renders declared === drawn.
  *
  * A decision `tree()` routes per-iteration by stable `ctx` predicates (no cursor)
- * and is unaffected by `from`-gating.
+ * and is unaffected by `from`-gating. It has no cursor for `read_skill` to move
+ * either, so `reachableSkills()` is EMPTY there and the gate refuses a leaf pick
+ * (8.5.0) — see `reachableSkills` for why honouring it would break three of this
+ * module's own invariants.
  *
  * **The model moves too (`read_skill`).** Scoped `read_skill` bounds the model to
  * `reachableSkills(cursor)` — the declared successors of where it stands, plus the
  * entries. A pick the gate ACCEPTS moves the cursor exactly like a declared edge
- * does (`ctx.pendingSkillPick`, honoured in `makeNextSkill`), so what the gate
+ * does (`ctx.pendingSkillPick`, honoured in `makeResolveCursor`), so what the gate
  * allows and what actually takes effect are the same set. A declared edge that
  * fires the same turn wins (`D1 > D2`, docs/design/skill-graph.md §4A.1) and the
  * run emits `agentfootprint.skill.reroute_superseded` rather than leaving the
  * model's answered-"activated" claim quietly unmet.
+ *
+ * **The resolver says WHY, it is not asked to be guessed.** `explainNextSkill(ctx)`
+ * returns the destination AND the winning clause (`CursorMove`), decided at the same
+ * `return`. The agent stamps it on `context.evaluated` as `cursorMove`, which is how
+ * `routeRecorder()` can tell a model pick from a declared edge that happens to point
+ * at the same skill (8.5.0 — before, the drawn build-time provenance was read as the
+ * per-hop cause, so a model pick was recorded under a declared edge's label).
  */
 import type { Injection, InjectionContext } from './types.js';
 import type { Embedder } from '../../memory/embedding/types.js';
@@ -53,45 +64,75 @@ export interface BuildOptions {
      */
     readonly check?: GraphCheckMode;
 }
+/** Where a turn starts, in the object-literal (flat) form. */
+export type SkillGraphStart = string | {
+    readonly use: string;
+} | {
+    readonly rules: ReadonlyArray<{
+        readonly when: (ctx: InjectionContext) => boolean;
+        readonly use: string;
+    }>;
+} | {
+    readonly entries: readonly string[];
+    /** Rank the entries with a scorer strategy (`keywordScorer()`,
+     *  `embeddingScorer(e)`, or your own). Takes precedence over `byRelevance`. */
+    readonly scoredBy?: EntryScorer;
+    /** Sugar: rank the entries with an embedder (cosine/softmax). Omit both → the
+     *  LLM reads the menu and picks (`.entryByRead()`) — no model call. */
+    readonly byRelevance?: Embedder;
+};
+/** One tool-result transition in the object-literal (flat) form. */
+export interface SkillGraphStep {
+    readonly from: string;
+    readonly to: string;
+    readonly when?: SkillRouteOptions['when'];
+    readonly onToolReturn?: string | RegExp;
+    readonly label?: string;
+}
 /**
- * Object-literal form of a skill graph — an alternative to the fluent builder.
- * Listing `skills` INDEPENDENTLY of the wiring is the point: the check-up can then
- * flag a skill that was listed but never wired (the fluent builder only ever sees
- * skills that appear in an edge). Compiles to the SAME `SkillGraph`. `check`
- * defaults to `'throw'` here (a new surface, fail-loud).
+ * Object-literal form, FLAT arm — `start` + `steps` declare the routing.
+ * `tree` is typed `never` here so `{ tree, start }` is a COMPILE error, not just
+ * a build-time refusal (see `SkillGraphConfig`).
  */
-export interface SkillGraphConfig {
+export interface SkillGraphFlatConfig {
     /** Every skill in the graph (wired or not). */
     readonly skills: readonly Injection[];
-    /** Where a turn starts. Omit when using `tree`. */
-    readonly start?: string | {
-        readonly use: string;
-    } | {
-        readonly rules: ReadonlyArray<{
-            readonly when: (ctx: InjectionContext) => boolean;
-            readonly use: string;
-        }>;
-    } | {
-        readonly entries: readonly string[];
-        /** Rank the entries with a scorer strategy (`keywordScorer()`,
-         *  `embeddingScorer(e)`, or your own). Takes precedence over `byRelevance`. */
-        readonly scoredBy?: EntryScorer;
-        /** Sugar: rank the entries with an embedder (cosine/softmax). Omit both → the
-         *  LLM reads the menu and picks (`.entryByRead()`) — no model call. */
-        readonly byRelevance?: Embedder;
-    };
+    /** Where a turn starts. */
+    readonly start?: SkillGraphStart;
     /** Tool-result transitions; `from`/`to` are skill ids resolved against `skills`. */
-    readonly steps?: ReadonlyArray<{
-        readonly from: string;
-        readonly to: string;
-        readonly when?: SkillRouteOptions['when'];
-        readonly onToolReturn?: string | RegExp;
-        readonly label?: string;
-    }>;
+    readonly steps?: readonly SkillGraphStep[];
+    readonly tree?: never;
+    readonly check?: GraphCheckMode;
+}
+/**
+ * Object-literal form, TREE arm — a decision tree owns the routing, so there is
+ * no entry menu and no cursor for `start`/`steps` to describe. Both are typed
+ * `never` so the contradiction is a compile error.
+ */
+export interface SkillGraphTreeConfig {
+    /** Every skill in the graph. Under `tree` this must be exactly the leaf set —
+     *  a listed skill that is not a leaf would never load, and is refused. */
+    readonly skills: readonly Injection[];
     /** A decision tree (instead of `start` + `steps`). */
-    readonly tree?: DecisionNode | Injection;
+    readonly tree: DecisionNode | Injection;
+    readonly start?: never;
+    readonly steps?: never;
     readonly check?: GraphCheckMode;
 }
+/**
+ * Object-literal form of a skill graph — an alternative to the fluent builder.
+ * Listing `skills` INDEPENDENTLY of the wiring is the point: the check-up can then
+ * flag a skill that was listed but never wired (the fluent builder only ever sees
+ * skills that appear in an edge). Compiles to the SAME `SkillGraph`. `check`
+ * defaults to `'throw'` here (a new surface, fail-loud).
+ *
+ * A UNION of two arms, because `tree` and `start`/`steps` are two ways to declare
+ * the same thing and only one of them compiles: `{ tree, start }` is a type error
+ * for a TypeScript consumer and a build-time refusal for everyone else (8.4.0 —
+ * before, the tree silently won and the flat wiring was discarded). Valid tree-only
+ * and flat-only configs typecheck exactly as they did.
+ */
+export type SkillGraphConfig = SkillGraphFlatConfig | SkillGraphTreeConfig;
 export type { EntryScore, EntryScoring };
 /** Deterministic routing into a skill, keyed on the last tool result. */
 export interface SkillRouteOptions {
@@ -122,8 +163,15 @@ export interface TreeOptions {
      * A decision tree routes to EXACTLY ONE skill per iteration, so each leaf is
      * stamped `autoActivate: 'currentSkill'` — its `inject.tools` reach the LLM
      * ONLY when the tree routes there, instead of every skill's tools landing in
-     * the always-on static registry on every call. `read_skill` stays available as
-     * the escape hatch to reach another skill mid-run.
+     * the always-on static registry on every call.
+     *
+     * `read_skill` cannot reach another LEAF mid-run (8.5.0): a tree has no cursor to
+     * move, and this "exactly one leaf" property is one of the reasons — admitting a
+     * second leaf would put two leaves' tools on the wire and make the dev-mode
+     * exactly-one monitor warn. It said otherwise until 8.5.0, and the pick was
+     * accepted and then silently dropped. The escape hatch is a skill registered
+     * BESIDE the graph (`.skill(x)`, `.selfExplain()`), which really does activate by
+     * `read_skill` and is admitted from anywhere.
      *
      * Default `true`. Set `false` for the legacy additive behavior (all leaves'
      * tools always visible). A leaf that sets its OWN `autoActivate` in
@@ -158,6 +206,33 @@ export interface DecisionNode {
  *  other `decideSkill(...)` results. (Renamed from `decide` in v7 to avoid
  *  colliding with footprintjs's `decide()`.) */
 export declare function decideSkill(predicate: (ctx: InjectionContext) => boolean, whenTrue: DecisionNode | Injection, whenFalse: DecisionNode | Injection, label?: string): DecisionNode;
+/**
+ * WHY the cursor landed where it did on one iteration — the winning clause of the
+ * one cursor resolver, reported rather than guessed (8.5.0).
+ *
+ *   • `'entry'`      — cold start: the first entry whose `when` passed;
+ *   • `'route'`      — a declared, `from`-gated edge fired (D1);
+ *   • `'model-pick'` — no declared edge fired, so the model's gate-accepted
+ *                      `read_skill` pick moved the cursor (D2), at cold start or mid-run;
+ *   • `'stay'`       — nothing fired; the cursor is sticky and stayed put;
+ *   • `'none'`       — no cursor at all (cold start with nothing to enter, or a
+ *                      decision `tree()`, which routes by predicate and has no cursor).
+ *
+ * This exists because the DRAWN provenance on a skill (`metadata.skillGraph`) answers
+ * "how is this skill reachable" — a build-time fact — and was being read as "how did
+ * we get here this turn". A model pick into a skill that also has a declared edge was
+ * therefore attributed to that edge, label and all, in the recorded route.
+ */
+export type CursorMoveCause = 'entry' | 'route' | 'model-pick' | 'stay' | 'none';
+/** The cursor resolver's full answer: where, and by which clause. */
+export interface CursorMove {
+    /** The cursor after this iteration (what `nextSkill` returns). */
+    readonly to?: string;
+    /** The cursor before it. */
+    readonly from?: string;
+    /** The winning clause. */
+    readonly by: CursorMoveCause;
+}
 /** A node in the drawn graph — a `predicate` diamond or a `skill` box. */
 export interface SkillNode {
     readonly id: string;
@@ -226,6 +301,19 @@ export interface SkillGraph {
      * by predicate (no cursor) and returns the unchanged `ctx.currentSkillId`.
      */
     nextSkill(ctx: InjectionContext): string | undefined;
+    /**
+     * The same answer as `nextSkill`, plus WHICH CLAUSE produced it — the resolver
+     * reporting its own reasoning instead of a consumer inferring it from the drawn
+     * provenance (8.5.0). `explainNextSkill(ctx).to === nextSkill(ctx)`, always: there
+     * is one resolver and `nextSkill` is a thin projection of this one, so the two can
+     * never drift.
+     *
+     * The agent threads this into the injection engine, which stamps the result on
+     * `agentfootprint.context.evaluated` as `cursorMove` — that is what lets
+     * `routeRecorder()` mark a model-pick hop as a model pick instead of borrowing the
+     * label of a declared edge that never fired.
+     */
+    explainNextSkill(ctx: InjectionContext): CursorMove;
     /**
      * The REACHABLE set — which skills the model may `read_skill`-jump to from the
      * current cursor. The agent's runtime gate rejects any `read_skill('id')` whose
@@ -233,8 +321,19 @@ export interface SkillGraph {
      *   • cold start (`currentSkillId` undefined) → the entry skills;
      *   • otherwise → the current skill's direct successors ∪ the entry skills, minus
      *     the current skill itself (deliberate "stay" is the no-tool-call ReAct stop).
-     * Pure + deterministic. A decision `tree()` has no cursor, so it returns ALL leaf
-     * skills — `read_skill` stays a full escape hatch there.
+     *
+     * A decision `tree()` returns EMPTY (8.5.0). A tree routes by predicate on every
+     * iteration and has no cursor to jump: its leaves compile to `rule` triggers, and a
+     * `read_skill` call writes only `activatedInjectionIds`, which a `rule` trigger does
+     * not read. Until 8.5.0 this returned all the leaves, so the gate accepted a leaf
+     * pick, the tool answered "activated for the next iteration", and the leaf never
+     * activated. That is the same clause 8.4.0 already applies everywhere else — a skill
+     * is open only when its trigger is `llm-activated` — reaching the one set that had
+     * escaped it. The escape hatch under a tree is the OPEN skills (anything registered
+     * beside the graph: `.skill(x)`, `.selfExplain()`), which the agent's gate still
+     * admits from any cursor.
+     *
+     * Pure + deterministic.
      */
     reachableSkills(currentSkillId?: string): readonly string[];
     /**