agentfootprint 9.41.0 → 9.44.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"skillNeverRoutes.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillNeverRoutes.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,69 @@
+/**
+ * skillPartition — three ADVISORY signals about the shape of the partition
+ * itself: how a graph cut the world into skills.
+ *
+ * ## Why the partition is worth a check at all
+ *
+ * Everything else the check-up reports is a wiring fact — an edge to a skill
+ * that is not there, a rule that can never win. The partition is upstream of
+ * all of it, and it is the decision with the most leverage: a graph whose
+ * skills follow SYSTEMS rather than CAPABILITIES makes one ordinary question
+ * cross four skills, and the capability the user actually wanted ends up
+ * implemented outside the graph, by hand, where nothing can see it. Field use
+ * produced exactly that shape — nineteen skills, ONE declared edge, and tool
+ * names carrying the system that owns them (`influx_*`, `pmax_*`, `pstore_*`,
+ * `rvtools_*`) with the skills following the prefixes.
+ *
+ * The important part: all three of those are visible from NAMES AND STRUCTURE
+ * ALONE, at build time, with no run and no model. So the runtime can say them.
+ *
+ * ## Why every one of them is an advisory, and stays one
+ *
+ * Each signal has a legitimate design behind it:
+ *
+ *   • a skill really can be one system's capability (a weather skill wrapping a
+ *     weather API is not a mistake);
+ *   • a deliberately FLAT menu of independent skills really does declare almost
+ *     no edges — a scorer or the model picks, and there is nothing to hand off;
+ *   • a one-call capability really can be one tool with a short body.
+ *
+ * So none of them is ever an error, and none of them says "this is wrong". Each
+ * message states the SIGNAL AS A FACT the author can check against their own
+ * intent — "your 19 skills declare 1 route", "every tool in `powerstore` shares
+ * the prefix `pstore_`" — and then names the design each fact usually indicates
+ * and the design it is also consistent with. This library's check-up teaches;
+ * it does not grade.
+ *
+ * ## The thresholds, and why each one is where it is
+ *
+ * Named constants below, each with the argument beside it. They are chosen so a
+ * SMALL graph is silent (small graphs have no partition problem worth naming),
+ * so a trivially-true observation is never dressed up as a finding (one tool
+ * shares a prefix with itself), and so the commonest honest naming convention —
+ * a VERB first — never fires.
+ *
+ * Zone: PURE CORE. Pinned by
+ * `test/lib/injection-engine/skill-graph-fence.test.ts`.
+ */
+import type { GraphProblem } from './skillGraphCheckup.js';
+import type { Injection } from './types.js';
+/** What the partition check reads. Counts, because that is what the signals
+ *  are about — no check here reasons about which edge goes where. */
+export interface PartitionInput {
+    /** Every skill in the graph (wired or not). */
+    readonly skills: readonly Injection[];
+    /** Declared routes, of any kind (a bare/model edge is still a declared
+     *  handoff — the signal is about handoffs that were never written down at
+     *  all, not about how deterministic they are). */
+    readonly routeCount: number;
+    /** Declared entries — quoted in the ratio message so the fact is complete. */
+    readonly entryCount: number;
+    /** A decision `tree()` owns its own routing and declares no routes by
+     *  construction, so the edge-ratio signal does not apply there. */
+    readonly isTree: boolean;
+}
+/**
+ * Run the three partition signals. Pure, and cheap: one pass over the skills
+ * and two integers. Every problem it produces is a WARNING.
+ */
+export declare function checkPartition(input: PartitionInput): GraphProblem[];

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

@@ -0,0 +1,273 @@
+/**
+ * skillPartition — three ADVISORY signals about the shape of the partition
+ * itself: how a graph cut the world into skills.
+ *
+ * ## Why the partition is worth a check at all
+ *
+ * Everything else the check-up reports is a wiring fact — an edge to a skill
+ * that is not there, a rule that can never win. The partition is upstream of
+ * all of it, and it is the decision with the most leverage: a graph whose
+ * skills follow SYSTEMS rather than CAPABILITIES makes one ordinary question
+ * cross four skills, and the capability the user actually wanted ends up
+ * implemented outside the graph, by hand, where nothing can see it. Field use
+ * produced exactly that shape — nineteen skills, ONE declared edge, and tool
+ * names carrying the system that owns them (`influx_*`, `pmax_*`, `pstore_*`,
+ * `rvtools_*`) with the skills following the prefixes.
+ *
+ * The important part: all three of those are visible from NAMES AND STRUCTURE
+ * ALONE, at build time, with no run and no model. So the runtime can say them.
+ *
+ * ## Why every one of them is an advisory, and stays one
+ *
+ * Each signal has a legitimate design behind it:
+ *
+ *   • a skill really can be one system's capability (a weather skill wrapping a
+ *     weather API is not a mistake);
+ *   • a deliberately FLAT menu of independent skills really does declare almost
+ *     no edges — a scorer or the model picks, and there is nothing to hand off;
+ *   • a one-call capability really can be one tool with a short body.
+ *
+ * So none of them is ever an error, and none of them says "this is wrong". Each
+ * message states the SIGNAL AS A FACT the author can check against their own
+ * intent — "your 19 skills declare 1 route", "every tool in `powerstore` shares
+ * the prefix `pstore_`" — and then names the design each fact usually indicates
+ * and the design it is also consistent with. This library's check-up teaches;
+ * it does not grade.
+ *
+ * ## The thresholds, and why each one is where it is
+ *
+ * Named constants below, each with the argument beside it. They are chosen so a
+ * SMALL graph is silent (small graphs have no partition problem worth naming),
+ * so a trivially-true observation is never dressed up as a finding (one tool
+ * shares a prefix with itself), and so the commonest honest naming convention —
+ * a VERB first — never fires.
+ *
+ * Zone: PURE CORE. Pinned by
+ * `test/lib/injection-engine/skill-graph-fence.test.ts`.
+ */
+import { skillToolNames } from './skillContract.js';
+/**
+ * How many tools a skill needs before "they all share a prefix" is evidence of
+ * anything. ONE tool shares a prefix with itself — a trivial truth, and the
+ * skill it describes has its own signal below. TWO is two coin flips; a
+ * `get_order` / `get_invoice` pair is a naming habit, not a system boundary.
+ * At THREE the shared prefix is a decision somebody made about scope.
+ */
+const MIN_TOOLS_FOR_PREFIX = 3;
+/**
+ * First segments that are NOT a system — they are the verb half of the house
+ * naming convention (`get_price`, `issue_refund`, `lookup_order`). Verified
+ * against this repo's real tool names, where the ten commonest first segments
+ * are all verbs and outnumber every system prefix put together: without this
+ * list the check would fire on the best-named skills in the library, which is
+ * the fastest way to teach an author to ignore a check-up.
+ *
+ * The test is deliberately crude — a first segment either IS one of these words
+ * or it is not. A cleverer part-of-speech guess would be wrong more quietly.
+ */
+const VERB_PREFIXES = new Set([
+    'get',
+    'set',
+    'put',
+    'post',
+    'add',
+    'read',
+    'write',
+    'list',
+    'find',
+    'fetch',
+    'load',
+    'save',
+    'open',
+    'close',
+    'make',
+    'create',
+    'update',
+    'delete',
+    'remove',
+    'search',
+    'query',
+    'count',
+    'check',
+    'verify',
+    'validate',
+    'run',
+    'exec',
+    'execute',
+    'send',
+    'call',
+    'ask',
+    'show',
+    'lookup',
+    'issue',
+    'approve',
+    'deny',
+    'pay',
+    'process',
+    'resolve',
+    'respond',
+    'inspect',
+    'export',
+    'import',
+    'start',
+    'stop',
+    'cancel',
+    'compute',
+    'calculate',
+    'generate',
+    'summarize',
+    'transform',
+]);
+/**
+ * The floor under ALL THREE signals: below this many skills there is no
+ * partition to have an opinion about.
+ *
+ * This is the module's one structural decision, and it is what keeps the
+ * advisories quiet by construction. Every signal here is a statement about how
+ * a graph CUT THE WORLD; a two-skill graph with no edge is a menu, one skill
+ * wrapping one tool is a choice about that skill, and a pair of tools sharing a
+ * prefix is a naming habit. None of those become a partition question until
+ * there are enough skills for the cut itself to be the design — and the field
+ * case that motivated all three had nineteen. A check that fires on a
+ * three-skill graph teaches an author to stop reading the check-up, which costs
+ * more than the finding is worth.
+ */
+const MIN_SKILLS_FOR_PARTITION = 5;
+/**
+ * The ratio that counts as "almost no declared edges". A graph needs N−1 edges
+ * to connect N skills into one routed structure; this fires below ONE EDGE PER
+ * FOUR SKILLS, which is four times sparser than a bare chain — far enough from
+ * the boundary that a graph tripping it is not a matter of taste. (The field
+ * case: 19 skills, 1 route — a ratio of 0.05.)
+ */
+const MIN_ROUTES_PER_SKILL = 0.25;
+/**
+ * Word count below which a body carries no knowledge the tool schema does not
+ * already carry. One sentence of real guidance — when to reach for this, what
+ * to check first, what the failure looks like — does not fit in 25 words, so a
+ * body under it is either a restatement of the tool's own description or a
+ * placeholder. Counted in whitespace-separated words, the only measure that
+ * means the same thing in prose as in markdown.
+ */
+const THIN_BODY_WORDS = 25;
+/**
+ * Run the three partition signals. Pure, and cheap: one pass over the skills
+ * and two integers. Every problem it produces is a WARNING.
+ */
+export function checkPartition(input) {
+    const skillCount = input.skills.length;
+    // The floor, applied once for all three signals — see
+    // MIN_SKILLS_FOR_PARTITION. A small graph reports byte-identically to the
+    // way it did before this module existed.
+    if (skillCount < MIN_SKILLS_FOR_PARTITION)
+        return [];
+    const problems = [];
+    for (const skill of input.skills) {
+        const tools = skillToolNames(skill);
+        const id = idOf(skill);
+        // 1. tools-share-prefix — every tool in the skill comes from one system.
+        //    Computed from the first `_`-delimited segment, which is where a system
+        //    prefix lives when there is one (`pstore_list_volumes` → `pstore`), and
+        //    silent when that segment is a verb (see VERB_PREFIXES).
+        const prefix = sharedPrefix(tools);
+        if (tools.length >= MIN_TOOLS_FOR_PREFIX && prefix !== undefined) {
+            problems.push({
+                kind: 'warning',
+                code: 'tools-share-prefix',
+                message: `Every tool in "${id}" shares the prefix \`${prefix}_\` (${tools.join(', ')}). ` +
+                    `A skill whose whole tool set comes from one system is usually a wrapper around ` +
+                    `that SYSTEM rather than a CAPABILITY — and when the skills follow the systems, one ` +
+                    `ordinary question crosses several of them, so the thing the user actually asked ` +
+                    `for gets built outside the graph where nothing can route it. Worth checking: ` +
+                    `could a user's question be answered by "${id}" alone, or does answering it need ` +
+                    `two of these skills at once? If it needs two, the capability is the skill and ` +
+                    `\`${prefix}_\` is just where its tools happen to come from. If "${id}" really is ` +
+                    `one system's capability, this is exactly right and there is nothing to fix.`,
+                skill: id,
+            });
+        }
+        // 2. skill-wraps-one-tool — one tool, and a body that adds nothing to its
+        //    schema. The body is what the model reads to decide HOW to use the
+        //    tool; when it is this short there is no procedure in the graph, only
+        //    an endpoint with a name.
+        if (tools.length === 1 && tools[0] !== undefined) {
+            const words = wordCount(bodyOf(skill));
+            if (words < THIN_BODY_WORDS) {
+                problems.push({
+                    kind: 'warning',
+                    code: 'skill-wraps-one-tool',
+                    message: `Skill "${id}" carries one tool (\`${tools[0]}\`) and a ${words}-word body — ` +
+                        `under the ${THIN_BODY_WORDS} words it takes to say when to reach for it, what to ` +
+                        `check first, or what a bad answer looks like. A skill whose body adds nothing to ` +
+                        `the tool's own schema is an endpoint wrapper: the model already sees the tool, so ` +
+                        `the skill buys nothing but a name and an activation. Either put the knowledge in ` +
+                        `the body (that is the half a schema cannot carry), or drop the skill and register ` +
+                        `\`${tools[0]}\` on the agent directly. If it is genuinely a one-call capability ` +
+                        `with nothing to say about it, registering the tool is the smaller thing.`,
+                    skill: id,
+                });
+            }
+        }
+    }
+    // 3. few-declared-edges — many skills, almost no declared handoffs. A graph
+    //    level fact, reported once, and never for a tree (a tree declares its
+    //    routing as the tree).
+    if (!input.isTree && input.routeCount < skillCount * MIN_ROUTES_PER_SKILL) {
+        problems.push({
+            kind: 'warning',
+            code: 'few-declared-edges',
+            message: `This graph declares ${plural(skillCount, 'skill', 'skills')}, ${plural(input.entryCount, 'entry', 'entries')} and ${plural(input.routeCount, 'route', 'routes')} — fewer than one route per four ` +
+                `skills, where connecting ${skillCount} skills into one routed structure takes at ` +
+                `least ${skillCount - 1}. When skills hand off to each other in PROSE ("then use the ` +
+                `capacity skill"), the handoff is invisible: nothing draws it, \`checkup()\` cannot ` +
+                `check it, the reachability walk cannot see it, and \`read_skill\`'s gate cannot ` +
+                `offer it — the model is left to infer the sequence every turn. Declaring the ones ` +
+                `you already rely on (\`.route(a, b, { onToolReturn })\`) turns each into something ` +
+                `the graph can route and a reader can see. If this is a deliberately flat menu of ` +
+                `independent skills — a scorer or the model picks one and it answers alone — then ` +
+                `there is nothing to hand off and this is the shape you meant.`,
+        });
+    }
+    return problems;
+}
+/** The id, read structurally like every other check in this family. */
+function idOf(skill) {
+    return skill.id;
+}
+/** The skill's BODY — the prose that lands in the system slot when it
+ *  activates. Same accessor `skillContract.ts` reads. */
+function bodyOf(skill) {
+    return skill.inject?.systemPrompt ?? '';
+}
+function wordCount(text) {
+    const trimmed = text.trim();
+    return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+}
+/**
+ * The first `_`-delimited segment shared by EVERY name, or undefined when there
+ * is none, when a name carries no `_` at all, or when the shared segment is a
+ * verb (a convention, not a system — see {@link VERB_PREFIXES}).
+ *
+ * Case-folded, because a tool registry that mixes `PSTORE_get` and
+ * `pstore_list` is still one system.
+ */
+function sharedPrefix(names) {
+    if (names.length === 0)
+        return undefined;
+    let shared;
+    for (const name of names) {
+        const separator = name.indexOf('_');
+        if (separator <= 0)
+            return undefined; // no prefix segment to speak of
+        const segment = name.slice(0, separator).toLowerCase();
+        if (shared === undefined)
+            shared = segment;
+        else if (shared !== segment)
+            return undefined;
+    }
+    return shared !== undefined && !VERB_PREFIXES.has(shared) ? shared : undefined;
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+//# sourceMappingURL=skillPartition.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skillPartition.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillPartition.ts"],"names":[],"mappings":"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"}

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

@@ -76,9 +76,36 @@
  *     others take `defineSkill`'s defaults.
  *   - unknown frontmatter keys are still IGNORED, not rejected, so a file
  *     carrying another tool's metadata still loads here. `name`,
- *     `description`, `tools`, `steps` and `onSkip` are the KNOWN keys — a file
- *     that used one of those five for something else is the one case this
- *     release can change, and it changes it loudly.
+ *     `description`, `tools`, `steps`, `onSkip` and `routes` are the KNOWN
+ *     keys — a file that used one of those six for something else is the one
+ *     case a release can change, and it changes it loudly.
+ *
+ * ── The routing, and the door that reads it (9.43.0) ─────────────────────────
+ * A runbook says what to do, what to do it with, in what order — and where the
+ * work goes NEXT. That last part is the graph, and until now it had to be
+ * hand-wired in code even when the files said it plainly. `routes:` closes it:
+ *
+ *   ---
+ *   name: billing
+ *   tools: lookup_order, issue_refund
+ *   routes:
+ *     - escalation: on issue_refund status=denied
+ *     - receipts: on issue_refund
+ *   ---
+ *
+ *   const runbook = await runbookFromDir('./skills', { tools: [...] });
+ *   const graph = skillGraph({ ...runbook, start: 'billing' });
+ *
+ * TWO DOORS, one truth: `skillsFromDir` returns skills and REFUSES a file that
+ * declares `routes:` (a door that dropped the routing would hand back a graph
+ * you believed was declared on disk); {@link runbookFromDir} returns
+ * `{ skills, steps }`. Same law as `tools:` — the file PICKS (a route names a
+ * skill id this directory declares; an unknown id is refused at load, by name,
+ * listing what is available), it never DEFINES. A guard is one of the two DATA
+ * conditions a route already has (`on <tool_name>`, `status=<outcome>`), and
+ * nothing else: a `when` predicate is CODE, no file can carry code, and that
+ * conditional stays in your source. See `skillsFromDirRoutes.ts` for the whole
+ * grammar and every refusal.
  *
  * A worked example feeding this into a graph:
  * `examples/features/47-skills-from-dir-graph.ts`.
@@ -111,6 +138,7 @@
 import type { Injection } from './types.js';
 import type { Tool } from '../../core/tools.js';
 import { type SurfaceMode } from './factories/defineSkill.js';
+import type { SkillGraphStep } from './skillGraph.js';
 export interface SkillsFromDirOptions {
     /**
      * Where a loaded skill's body lands once activated. Defaults to
@@ -133,6 +161,31 @@ export interface SkillsFromDirOptions {
      */
     readonly tools?: readonly Tool[];
 }
+/**
+ * A whole runbook directory, read as the two things a graph is made of
+ * (9.43.0): the skills, and the edges between them.
+ *
+ * Spreads straight into the graph — the field names are the graph's own, so
+ * nothing has to be translated at the call site:
+ *
+ *   const runbook = await runbookFromDir('./skills', { tools });
+ *   const graph = skillGraph({ ...runbook, start: 'triage' });
+ */
+export interface DirRunbook {
+    /** Every `SKILL.md` under the directory, as Skill Injections — byte-identical
+     *  to what `skillsFromDir` returns for the same directory. */
+    readonly skills: readonly Injection[];
+    /**
+     * The declared edges, ready for `skillGraph({ steps })`. In skill-name order,
+     * then file order, so a graph built from a directory is stable.
+     *
+     * NAME NOTE, because two different things are spelled `steps` in this
+     * library: a file's own `steps:` key is that SKILL's tool sequence (which
+     * rides on the skill, unchanged); these `steps` are the GRAPH's edges, read
+     * from each file's `routes:` key. They never meet.
+     */
+    readonly steps: readonly SkillGraphStep[];
+}
 /**
  * Load every `SKILL.md` under `dir` as a Skill Injection.
  *
@@ -155,3 +208,30 @@ export interface SkillsFromDirOptions {
  *   does not carry, or sequences a tool the file itself did not declare.
  */
 export declare function skillsFromDir(dir: string, opts?: SkillsFromDirOptions): Promise<readonly Injection[]>;
+/**
+ * Load a directory as a whole RUNBOOK (9.43.0) — the skills AND the edges
+ * between them.
+ *
+ * `skillsFromDir` reads what one skill is; this reads what the skills are TO
+ * EACH OTHER, from each file's `routes:` key, and hands back both halves ready
+ * for `skillGraph({ ...runbook, start })`. Everything else is identical: same
+ * layouts, same frontmatter, same tool registry, same refusals.
+ *
+ * The routing a file may carry is deliberately small, and the boundary is a
+ * security property rather than a limitation — see `skillsFromDirRoutes.ts`:
+ * a route NAMES a skill this directory declares (an unknown id is refused at
+ * load, by name, listing what is available — never a half-graph), and a guard
+ * is one of the two DATA conditions a route already has (`on <tool>`,
+ * `status=<outcome>`). A `when` predicate is code, so no file can express one;
+ * that conditional stays in your source, where `skillGraph({ steps })` takes it.
+ *
+ * @param dir - A local filesystem path. Same rule as `skillsFromDir`.
+ * @param opts - Applied uniformly to every loaded skill.
+ *
+ * @throws everything `skillsFromDir` throws, plus: a route to an id no
+ *   `SKILL.md` in the directory declares (the message lists what is
+ *   available), a guard the grammar cannot express (the message quotes the
+ *   whole grammar), a guard naming a tool the file itself does not declare,
+ *   and a file routing to the same skill twice.
+ */
+export declare function runbookFromDir(dir: string, opts?: SkillsFromDirOptions): Promise<DirRunbook>;

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

@@ -76,9 +76,36 @@
  *     others take `defineSkill`'s defaults.
  *   - unknown frontmatter keys are still IGNORED, not rejected, so a file
  *     carrying another tool's metadata still loads here. `name`,
- *     `description`, `tools`, `steps` and `onSkip` are the KNOWN keys — a file
- *     that used one of those five for something else is the one case this
- *     release can change, and it changes it loudly.
+ *     `description`, `tools`, `steps`, `onSkip` and `routes` are the KNOWN
+ *     keys — a file that used one of those six for something else is the one
+ *     case a release can change, and it changes it loudly.
+ *
+ * ── The routing, and the door that reads it (9.43.0) ─────────────────────────
+ * A runbook says what to do, what to do it with, in what order — and where the
+ * work goes NEXT. That last part is the graph, and until now it had to be
+ * hand-wired in code even when the files said it plainly. `routes:` closes it:
+ *
+ *   ---
+ *   name: billing
+ *   tools: lookup_order, issue_refund
+ *   routes:
+ *     - escalation: on issue_refund status=denied
+ *     - receipts: on issue_refund
+ *   ---
+ *
+ *   const runbook = await runbookFromDir('./skills', { tools: [...] });
+ *   const graph = skillGraph({ ...runbook, start: 'billing' });
+ *
+ * TWO DOORS, one truth: `skillsFromDir` returns skills and REFUSES a file that
+ * declares `routes:` (a door that dropped the routing would hand back a graph
+ * you believed was declared on disk); {@link runbookFromDir} returns
+ * `{ skills, steps }`. Same law as `tools:` — the file PICKS (a route names a
+ * skill id this directory declares; an unknown id is refused at load, by name,
+ * listing what is available), it never DEFINES. A guard is one of the two DATA
+ * conditions a route already has (`on <tool_name>`, `status=<outcome>`), and
+ * nothing else: a `when` predicate is CODE, no file can carry code, and that
+ * conditional stays in your source. See `skillsFromDirRoutes.ts` for the whole
+ * grammar and every refusal.
  *
  * A worked example feeding this into a graph:
  * `examples/features/47-skills-from-dir-graph.ts`.
@@ -109,6 +136,7 @@
  * import detonates a browser bundle at module-eval even when nothing calls it.
  */
 import { defineSkill } from './factories/defineSkill.js';
+import { readDeclaredRoutes, toGraphSteps } from './skillsFromDirRoutes.js';
 /** The file name every skill folder is expected to use. */
 const SKILL_FILE = 'SKILL.md';
 /**
@@ -144,6 +172,68 @@ const NAMES_IN_REFUSAL = 20;
  *   does not carry, or sequences a tool the file itself did not declare.
  */
 export async function skillsFromDir(dir, opts = {}) {
+    const { parsed, skills } = await loadSkillDir(dir, opts);
+    // A file that declares `routes:` loaded through THIS door would hand back a
+    // skill set with its routing silently dropped — the same failure the tool
+    // registry refuses ("a skill that loads without the tool it asked for still
+    // runs and still sounds sure of itself"). Refused by name, pointing at the
+    // door that reads the whole runbook.
+    const routing = parsed.find((skill) => skill.routes !== undefined);
+    if (routing !== undefined) {
+        throw new Error(`skillsFromDir: '${routing.file}' declares 'routes', and skillsFromDir returns SKILLS ` +
+            `only — the routing would be dropped without a word, leaving you a graph you thought ` +
+            `was declared on disk. Read the whole runbook instead: ` +
+            `const { skills, steps } = await runbookFromDir(dir, opts); ` +
+            `skillGraph({ skills, steps, start: '<entry id>' }). ` +
+            `(If 'routes' in this file belongs to another program, rename that key — it is a key ` +
+            `this loader now reads.)`);
+    }
+    return skills;
+}
+/**
+ * Load a directory as a whole RUNBOOK (9.43.0) — the skills AND the edges
+ * between them.
+ *
+ * `skillsFromDir` reads what one skill is; this reads what the skills are TO
+ * EACH OTHER, from each file's `routes:` key, and hands back both halves ready
+ * for `skillGraph({ ...runbook, start })`. Everything else is identical: same
+ * layouts, same frontmatter, same tool registry, same refusals.
+ *
+ * The routing a file may carry is deliberately small, and the boundary is a
+ * security property rather than a limitation — see `skillsFromDirRoutes.ts`:
+ * a route NAMES a skill this directory declares (an unknown id is refused at
+ * load, by name, listing what is available — never a half-graph), and a guard
+ * is one of the two DATA conditions a route already has (`on <tool>`,
+ * `status=<outcome>`). A `when` predicate is code, so no file can express one;
+ * that conditional stays in your source, where `skillGraph({ steps })` takes it.
+ *
+ * @param dir - A local filesystem path. Same rule as `skillsFromDir`.
+ * @param opts - Applied uniformly to every loaded skill.
+ *
+ * @throws everything `skillsFromDir` throws, plus: a route to an id no
+ *   `SKILL.md` in the directory declares (the message lists what is
+ *   available), a guard the grammar cannot express (the message quotes the
+ *   whole grammar), a guard naming a tool the file itself does not declare,
+ *   and a file routing to the same skill twice.
+ */
+export async function runbookFromDir(dir, opts = {}) {
+    const { parsed, skills } = await loadSkillDir(dir, opts);
+    // Resolved only once every file is in hand: "which ids exist" is a fact about
+    // the DIRECTORY, and no single file can be asked it.
+    const known = new Set(parsed.map((skill) => skill.name));
+    const steps = parsed.flatMap((skill) => skill.routes === undefined ? [] : toGraphSteps(skill.name, skill.routes, skill.file, known));
+    return { skills, steps };
+}
+/**
+ * The shared load: read the directory, parse every file, resolve the tools,
+ * build the skills. Both doors run exactly this — they differ only in what they
+ * do with the ROUTING each file declared, which is the one thing a skill list
+ * cannot carry.
+ *
+ * Returns the parsed files and the built skills IN THE SAME ORDER (sorted by
+ * skill name), so a caller can pair them by index.
+ */
+async function loadSkillDir(dir, opts) {
     assertLocalDirectoryArgument(dir);
     assertNoViaToolNameOption(opts);
     // Lazy node imports (browser-compat) — see module header.
@@ -205,10 +295,8 @@ export async function skillsFromDir(dir, opts = {}) {
     // shape. `undefined` (option omitted) is DISTINCT from an empty registry: the
     // refusals say different things, because the fixes are different.
     const registry = indexToolRegistry(opts.tools);
-    return parsed
-        .slice()
-        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
-        .map((skill) => {
+    const sorted = parsed.slice().sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const skills = sorted.map((skill) => {
         const tools = resolveDeclaredTools(skill, opts.tools, registry);
         return defineSkill({
             id: skill.name,
@@ -220,6 +308,7 @@ export async function skillsFromDir(dir, opts = {}) {
             ...(opts.surfaceMode !== undefined && { surfaceMode: opts.surfaceMode }),
         });
     });
+    return { parsed: sorted, skills };
 }
 // ─── Authorship guard ──────────────────────────────────────────────
 /**
@@ -390,6 +479,7 @@ function parseSkillFile(raw, file) {
     const toolNames = readToolNames(fields, file);
     const steps = readSteps(fields, file, toolNames);
     const onSkip = readOnSkip(fields, file, steps);
+    const routes = readRoutes(fields, file, toolNames);
     return {
         name,
         description,
@@ -397,6 +487,7 @@ function parseSkillFile(raw, file) {
         ...(toolNames !== undefined && { toolNames }),
         ...(steps !== undefined && { steps }),
         ...(onSkip !== undefined && { onSkip }),
+        ...(routes !== undefined && { routes }),
         file,
     };
 }
@@ -553,6 +644,26 @@ function readSteps(fields, file, toolNames) {
         return { tool: item.key, note: item.value };
     });
 }
+/**
+ * `routes:` → the edges out of this skill (9.43.0), as data.
+ *
+ * A block list, like `steps:` and for the same reason: routing is an ordered
+ * list of pairs (a target and its guard), and one line cannot carry that
+ * without a separator soup. The grammar itself — and every refusal in it —
+ * lives in `skillsFromDirRoutes.ts`; this reader only decides that the key is
+ * present and shaped like a list.
+ */
+function readRoutes(fields, file, toolNames) {
+    const field = fields.get('routes');
+    if (field === undefined)
+        return undefined;
+    if (field.kind === 'scalar') {
+        throw new Error(`skillsFromDir: '${file}' writes 'routes' on one line, and routing is a LIST of edges ` +
+            `(each with its own guard). Write it as a block:\nroutes:\n  - escalation: on ` +
+            `issue_refund status=denied\n  - receipts: on issue_refund`);
+    }
+    return readDeclaredRoutes(field.items, file, toolNames);
+}
 /** `onSkip:` → the skip policy. Refused here rather than at `defineSkill` so
  *  the message can name the file the author has to open. */
 function readOnSkip(fields, file, steps) {