xcoder-dna 0.0.0-stage → 1.3.1

package/dist/skills/seed-skills.js

@@ -0,0 +1,213 @@
+// xcoder:version 5 | xcoder:task task-f9cf18 | xcoder:updated 2026-11-02T16:15:28.268Z | xcoder:subtask code-st-077ea2
+/**
+ * Idempotent, non-destructive seeding of the home skills directory.
+ *
+ * On first run the shipped packs are copied to ~/.xcoder/skills so the user
+ * owns an editable tree that survives uninstall. Precision matters here, so
+ * ownership is tracked with a per-file SHA-256 manifest:
+ *
+ *   absent                      -> write            (created)
+ *   present, hashes match       -> leave alone      (unchanged)
+ *   present, differs, IN manifest -> overwrite       (repaired)
+ *   present, differs, NOT in manifest -> never touch (preserved)
+ *   extra pack not in source    -> never touch      (preserved)
+ *
+ * There are NO deletes anywhere in this module — the one failure mode that
+ * cannot be undone is deleting a file the user wrote.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { getUserHomeSkillsDir, probeSkillsDir } from "./skills-root.js";
+import { MAX_PACK_DIRS, validateSkillName } from "./skill-path-guard.js";
+/** Ceiling on files considered inside one pack (defensive, not a real limit). */
+const MAX_PACK_FILES = 2048;
+/** Ceiling on directory nesting inside one pack. */
+const MAX_DEPTH = 8;
+function sha256(buf) {
+    return createHash("sha256").update(buf).digest("hex");
+}
+/** Walk `baseDir` and return posix-relative file paths -> sha256, all bounded. */
+async function hashTree(baseDir) {
+    const out = new Map();
+    async function walk(dir, prefix, depth) {
+        if (depth > MAX_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = await fsp.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.size >= MAX_PACK_FILES)
+                return;
+            if (entry.isSymbolicLink())
+                continue;
+            if (!validateSkillName(entry.name).ok)
+                continue;
+            const abs = path.join(dir, entry.name);
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(abs, rel, depth + 1);
+            }
+            else if (entry.isFile()) {
+                try {
+                    out.set(rel, sha256(await fsp.readFile(abs)));
+                }
+                catch {
+                    // Unreadable source file: skip rather than abort the whole seed.
+                }
+            }
+        }
+    }
+    await walk(baseDir, "", 0);
+    return out;
+}
+/** Read and schema-check an existing manifest; a bad manifest means "no manifest". */
+function readManifest(manifestPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(manifestPath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const m = parsed;
+        if (m["schemaVersion"] !== 1)
+            return undefined;
+        if (typeof m["packs"] !== "object" || m["packs"] === null)
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Seed the home skills directory from the shipped packs.
+ *
+ * Never throws: every failure is recorded in `errors` and the run continues.
+ */
+export async function seedSkillsHome(opts) {
+    const homeDir = opts.homeDir;
+    const targetSkillsDir = getUserHomeSkillsDir(homeDir);
+    const manifestPath = opts.manifestPath ?? path.join(path.dirname(targetSkillsDir), "skills-manifest.json");
+    const result = {
+        action: "skipped",
+        written: [],
+        updated: [],
+        preserved: [],
+        errors: [],
+        manifestPath,
+    };
+    let sourcePacks;
+    try {
+        sourcePacks = fs.readdirSync(opts.sourceDir, { withFileTypes: true });
+    }
+    catch {
+        result.errors.push({ path: opts.sourceDir, reason: "source directory unreadable" });
+        return result;
+    }
+    const targetExisted = probeSkillsDir(targetSkillsDir).count > 0 || fs.existsSync(targetSkillsDir);
+    const manifest = readManifest(manifestPath);
+    const nextManifest = {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        generator: "first-run",
+        packs: { ...(manifest?.packs ?? {}) },
+    };
+    let visited = 0;
+    for (const entry of sourcePacks) {
+        if (visited >= MAX_PACK_DIRS)
+            break;
+        if (!entry.isDirectory())
+            continue;
+        visited++;
+        if (!validateSkillName(entry.name).ok)
+            continue;
+        const sourcePackDir = path.join(opts.sourceDir, entry.name);
+        const targetPackDir = path.join(targetSkillsDir, entry.name);
+        const files = await hashTree(sourcePackDir);
+        if (files.size === 0) {
+            result.preserved.push(entry.name);
+            continue;
+        }
+        const ownedByUs = manifest?.packs?.[entry.name] !== undefined;
+        const targetPackExists = fs.existsSync(targetPackDir);
+        let touchedThisPack = false;
+        for (const [rel, sourceHash] of files) {
+            const targetFile = path.join(targetPackDir, ...rel.split("/"));
+            const exists = fs.existsSync(targetFile);
+            if (exists) {
+                const targetHash = sha256(await fsp.readFile(targetFile));
+                if (targetHash === sourceHash)
+                    continue;
+                if (!ownedByUs) {
+                    result.preserved.push(`${entry.name}/${rel}`);
+                    continue;
+                }
+                if (!opts.dryRun) {
+                    try {
+                        await fsp.mkdir(path.dirname(targetFile), { recursive: true });
+                        await fsp.writeFile(targetFile, await fsp.readFile(path.join(sourcePackDir, ...rel.split("/"))));
+                    }
+                    catch (e) {
+                        result.errors.push({ path: targetFile, reason: e.message });
+                        continue;
+                    }
+                }
+                touchedThisPack = true;
+                result.updated.push(`${entry.name}/${rel}`);
+                nextManifest.packs[entry.name] = { ...(nextManifest.packs[entry.name] ?? {}), [rel]: sourceHash };
+                continue;
+            }
+            if (!opts.dryRun) {
+                try {
+                    await fsp.mkdir(path.dirname(targetFile), { recursive: true });
+                    await fsp.writeFile(targetFile, await fsp.readFile(path.join(sourcePackDir, ...rel.split("/"))));
+                }
+                catch (e) {
+                    result.errors.push({ path: targetFile, reason: e.message });
+                    continue;
+                }
+            }
+            touchedThisPack = true;
+            result.written.push(`${entry.name}/${rel}`);
+            nextManifest.packs[entry.name] = { ...(nextManifest.packs[entry.name] ?? {}), [rel]: sourceHash };
+        }
+        // A pack that already exists on disk whose files we neither wrote nor
+        // repaired is the user's, not ours — record it and drop any manifest claim.
+        if (targetPackExists && !touchedThisPack) {
+            result.preserved.push(entry.name);
+            delete nextManifest.packs[entry.name];
+        }
+    }
+    if (opts.dryRun) {
+        result.action = "skipped";
+        return result;
+    }
+    try {
+        await fsp.mkdir(path.dirname(manifestPath), { recursive: true });
+        await fsp.writeFile(manifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`, "utf-8");
+    }
+    catch (e) {
+        result.errors.push({ path: manifestPath, reason: e.message });
+    }
+    if (result.updated.length > 0) {
+        result.action = "repaired";
+    }
+    else if (result.written.length > 0) {
+        result.action = targetExisted ? "repaired" : "created";
+    }
+    else {
+        result.action = "unchanged";
+    }
+    return result;
+}

package/dist/skills/skill-authoring/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: skill-authoring
+role: meta
+description: Author new role skills for xcoder's own hot-pluggable skill system (agent/skills/<name>/SKILL.md) — correct frontmatter, well-scoped triggers, and a body that actually changes agent behavior instead of restating generic advice.
+triggers:
+  - "create a skill"
+  - "new skill"
+  - "add a skill"
+  - "author a skill"
+  - "build a skill"
+  - "skill for"
+  - "write a skill"
+  - "skill.md"
+  - "skill registry"
+version: "1.0.0"
+requires_tools:
+  - read_tool
+  - write_edit_tool
+  - glob_tool
+  - grep_tool
+composes_with:
+  - ui-ux-design
+  - task-planning
+---
+
+## Purpose
+
+This skill is for when the task is to extend xcoder itself — adding a new role skill so future
+tasks route to specialized instructions instead of the generic base ReAct loop. It is a meta-skill:
+it does not solve the user's underlying problem, it produces a well-formed `SKILL.md` that will.
+
+## How xcoder actually loads skills (read this before writing anything)
+
+`src/core/skillRegistry.ts` is the source of truth — re-read it if this ever drifts:
+
+- Skills live at `agent/skills/<name>/SKILL.md` (one directory per skill; the directory name
+  doesn't have to match `name` in the frontmatter, but keep them identical to avoid confusion).
+- The file MUST match `^---\n(yaml)\n---\n(body)$` — a YAML frontmatter block bounded by `---`
+  lines, then a markdown body. `loadHeaders()` parses ONLY the frontmatter (cheap, called often);
+  `loadSkill()` parses frontmatter + body (only when a skill is actually selected).
+- `route(taskDescription)` lowercases the task text and, for every skill, counts how many of its
+  `triggers` are substrings of it. Skills with score > 0 are returned sorted by score descending.
+  Multiple skills can and do fire for the same task — that's intentional (`composes_with` documents
+  which skills are expected to be selected together).
+- There is no dedup, no stemming, no fuzzy match. `"deploy"` will not match `"deployment"` unless
+  you also list `"deployment"`. Write triggers as the literal substrings a real task description
+  would contain, including short synonyms and common phrasings — but not words so short/common
+  they'd false-positive on unrelated tasks (a bad trigger like `"add"` or `"fix"` will make a skill
+  fire on nearly everything).
+
+## The frontmatter schema (exact — matches `SkillHeader` in `src/core/types.ts`)
+
+```yaml
+name: kebab-case-unique-id       # must be unique across agent/skills/*
+role: short-noun-phrase          # e.g. "design", "planning", "meta", "devops" — used for display
+description: one sentence, third person, states what the skill is for and when it applies
+triggers:
+  - "phrase one"
+  - "phrase two"                 # lowercase; substring match against the lowercased task text
+version: "1.0.0"                 # semver as a string
+requires_tools:                  # tool names this skill's instructions assume are available
+  - some_tool
+composes_with:                   # names of OTHER skills this one is commonly selected alongside
+  - other-skill-name
+```
+
+All seven keys are required by the `SkillHeader` interface — an omitted key will still parse as
+YAML but will be `undefined` at runtime and can break anything that reads it (e.g. `role` showing
+as `undefined` in `xcoder --skills`). Fill in every field even if a list is empty (`[]`).
+
+## Writing a body that changes behavior (the part that's easy to get wrong)
+
+A skill body that just restates domain knowledge the model already has adds tokens without adding
+value. A good skill body encodes the things that are true of *this specific codebase or workflow*
+that the model can't otherwise infer:
+
+- **Concrete conventions**: exact file paths, exact tool names, exact naming patterns this project
+  uses (e.g. "phase reports go to `tasks/<slug>-phase-<N>.md`", not "save your progress somewhere").
+- **Decision rules tied to how the agent is actually scored or evaluated** — if there's a scoring
+  or validation mechanism (see the `task-planning` skill for this project's health-score system),
+  reference it by name and describe the specific behaviors it rewards/penalizes, not generic
+  "write good code" advice.
+- **Failure patterns worth naming** — a skill earns its keep by preventing a mistake the model
+  would otherwise make on this exact class of task.
+
+Recommended section structure (matches the `LoadedSkill.body` doc comment — "Process / Strategies
+/ Instructions / Planning / Experience" — use the subset that's actually useful, don't pad):
+
+```markdown
+## Process
+The concrete step order for this kind of task.
+
+## Instructions
+Non-negotiable rules — the things that are wrong if skipped.
+
+## Strategies
+Judgment calls / tradeoffs / "prefer X over Y when...".
+
+## Experience
+Known failure modes and how to recognize/avoid them.
+```
+
+## Checklist before considering a new skill done
+
+1. Frontmatter has all 7 keys, `name` is unique, `triggers` are realistic lowercase substrings.
+2. `requires_tools` lists only tools that actually exist (check `src/tools/toolSchemas.ts` — grep
+   for `"_tool"` to get the current list rather than assuming).
+3. `composes_with` references skills that actually exist under `agent/skills/`.
+4. The body contains at least one thing a generalist model would NOT already know or would get
+   wrong without it. If you can't identify that thing, the task probably doesn't need a new skill.
+5. Sanity-check by running `xcoder --skills` (uses `loadHeaders()`) to confirm it parses and shows
+   up with the right role/triggers, and test that the intended task phrasing actually routes to it
+   via `SkillRegistry.route(...)` logic (substring match, case-insensitive).
+
+## Common mistakes
+
+- Triggers that are single common words (`"design"`, `"plan"`) with no accompanying context words —
+  causes the skill to fire on unrelated tasks and dilutes routing quality for everything else.
+- Forgetting `version`/`requires_tools`/`composes_with` because they "don't seem important" — they
+  parse fine as `undefined` and the failure only shows up later, somewhere else.
+- A body that's a generic essay instead of project-specific, actionable instructions.
+- Copy-pasting another skill's triggers "just in case" — this makes two skills fire together on
+  tasks that only need one, bloating the context sent to the LLM for no benefit.

package/dist/skills/skill-header.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bounded, schema-validated SKILL.md frontmatter parsing.
+ *
+ * The previous implementation did an unbounded `readFileSync` and then
+ * dereferenced `header.name` straight off whatever `yaml.load` returned. A
+ * SKILL.md whose frontmatter was a YAML scalar (or an array) therefore threw
+ * a TypeError that took the whole scan down. This module closes that by:
+ *
+ *   1. reading at most `MAX_FRONTMATTER_BYTES` before parsing anything,
+ *   2. parsing with `JSON_SCHEMA` so YAML cannot construct arbitrary values,
+ *   3. refusing prototype-poisoning keys, and
+ *   4. normalising the result into a `SkillHeader` that downstream code can
+ *      dereference without a guard.
+ *
+ * Every failure returns `{ ok: false, reason }` instead of throwing.
+ */
+import type { SkillHeader } from "../types.js";
+/** Why a SKILL.md header could not be turned into a `SkillHeader`. */
+export type HeaderParseFailure = "unreadable" | "too-large" | "no-frontmatter" | "yaml-error" | "not-object" | "schema-invalid" | "unsafe-key";
+export interface HeaderParseResult {
+    ok: boolean;
+    header?: SkillHeader;
+    body?: string;
+    reason?: HeaderParseFailure;
+    /** How many bytes of the file were actually read for the header. */
+    bytesRead: number;
+}
+/**
+ * Collapse a header value onto one line and cap its length, so a description
+ * containing newlines or control characters cannot restructure the prompt
+ * block the skill list is injected into (LLM01).
+ */
+export declare function sanitizeHeaderText(value: string, maxLen: number): string;
+/** True when `value` can be safely dereferenced as a `SkillHeader`. */
+export declare function isSkillHeader(value: unknown): value is SkillHeader;
+/**
+ * Parse a SKILL.md header from an in-memory string.
+ * Pure — no filesystem access, so it is cheap to unit test.
+ */
+export declare function parseSkillHeaderBytes(raw: string): HeaderParseResult;
+/**
+ * Parse a SKILL.md from disk.
+ *
+ * The header is always parsed from a bounded prefix (8 KiB by default); the
+ * body is only re-read in full when `withBody` is set, so the header path can
+ * never be made to allocate an arbitrary amount of memory.
+ */
+export declare function parseSkillHeaderFile(skillPath: string, opts?: {
+    withBody?: boolean;
+    maxBytes?: number;
+}): HeaderParseResult;

package/dist/skills/skill-header.js

@@ -0,0 +1,163 @@
+// xcoder:version 1 | xcoder:task task-f9cf18 | xcoder:updated 2026-11-02T16:14:11.010Z | xcoder:subtask code-st-077ea2
+/**
+ * Bounded, schema-validated SKILL.md frontmatter parsing.
+ *
+ * The previous implementation did an unbounded `readFileSync` and then
+ * dereferenced `header.name` straight off whatever `yaml.load` returned. A
+ * SKILL.md whose frontmatter was a YAML scalar (or an array) therefore threw
+ * a TypeError that took the whole scan down. This module closes that by:
+ *
+ *   1. reading at most `MAX_FRONTMATTER_BYTES` before parsing anything,
+ *   2. parsing with `JSON_SCHEMA` so YAML cannot construct arbitrary values,
+ *   3. refusing prototype-poisoning keys, and
+ *   4. normalising the result into a `SkillHeader` that downstream code can
+ *      dereference without a guard.
+ *
+ * Every failure returns `{ ok: false, reason }` instead of throwing.
+ */
+import fs from "node:fs";
+import * as yaml from "js-yaml";
+import { MAX_FRONTMATTER_BYTES } from "./skill-path-guard.js";
+/** Keys that would let a crafted header reach `Object.prototype`. */
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/** Matches `---` ... `---` followed by the body. Applied to a bounded prefix. */
+const FRONTMATTER_RE = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+/** Longest single-line value kept in one header field (defensive cap). */
+const MAX_FIELD_LEN = 4096;
+/**
+ * Collapse a header value onto one line and cap its length, so a description
+ * containing newlines or control characters cannot restructure the prompt
+ * block the skill list is injected into (LLM01).
+ */
+export function sanitizeHeaderText(value, maxLen) {
+    return value
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, Math.max(0, maxLen));
+}
+/** True when `value` can be safely dereferenced as a `SkillHeader`. */
+export function isSkillHeader(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const v = value;
+    return (typeof v["name"] === "string" &&
+        v["name"].length > 0 &&
+        typeof v["description"] === "string");
+}
+function toStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => typeof item === "string")
+        .map((item) => sanitizeHeaderText(item, 256))
+        .filter((item) => item.length > 0);
+}
+function asString(value) {
+    return typeof value === "string" ? sanitizeHeaderText(value, MAX_FIELD_LEN) : "";
+}
+/** Read at most `maxBytes` from the head of a file. */
+function readPrefix(filePath, maxBytes) {
+    const fd = fs.openSync(filePath, "r");
+    try {
+        const buf = Buffer.allocUnsafe(maxBytes);
+        const bytesRead = fs.readSync(fd, buf, 0, maxBytes, 0);
+        return { text: buf.subarray(0, bytesRead).toString("utf-8"), bytesRead };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Parse a SKILL.md header from an in-memory string.
+ * Pure — no filesystem access, so it is cheap to unit test.
+ */
+export function parseSkillHeaderBytes(raw) {
+    const bytesRead = Buffer.byteLength(raw, "utf-8");
+    const match = FRONTMATTER_RE.exec(raw);
+    if (!match) {
+        return { ok: false, reason: "no-frontmatter", bytesRead };
+    }
+    const yamlBlock = match[1] ?? "";
+    if (Buffer.byteLength(yamlBlock, "utf-8") > MAX_FRONTMATTER_BYTES) {
+        return { ok: false, reason: "too-large", bytesRead };
+    }
+    let loaded;
+    try {
+        loaded = yaml.load(yamlBlock, { schema: yaml.JSON_SCHEMA });
+    }
+    catch {
+        return { ok: false, reason: "yaml-error", bytesRead };
+    }
+    if (typeof loaded !== "object" || loaded === null || Array.isArray(loaded)) {
+        return { ok: false, reason: "not-object", bytesRead };
+    }
+    const record = loaded;
+    for (const key of Object.keys(record)) {
+        if (UNSAFE_KEYS.has(key)) {
+            return { ok: false, reason: "unsafe-key", bytesRead };
+        }
+    }
+    if (!isSkillHeader(record)) {
+        return { ok: false, reason: "schema-invalid", bytesRead };
+    }
+    const header = {
+        name: asString(record["name"]),
+        role: asString(record["role"]),
+        description: asString(record["description"]),
+        triggers: toStringArray(record["triggers"]),
+        version: asString(record["version"]),
+        requires_tools: toStringArray(record["requires_tools"]),
+        composes_with: toStringArray(record["composes_with"]),
+    };
+    if (header.name.length === 0) {
+        return { ok: false, reason: "schema-invalid", bytesRead };
+    }
+    return {
+        ok: true,
+        header,
+        body: raw.slice(match[0].length).trim(),
+        bytesRead,
+    };
+}
+/**
+ * Parse a SKILL.md from disk.
+ *
+ * The header is always parsed from a bounded prefix (8 KiB by default); the
+ * body is only re-read in full when `withBody` is set, so the header path can
+ * never be made to allocate an arbitrary amount of memory.
+ */
+export function parseSkillHeaderFile(skillPath, opts) {
+    const maxBytes = opts?.maxBytes ?? MAX_FRONTMATTER_BYTES;
+    let prefix;
+    try {
+        prefix = readPrefix(skillPath, maxBytes);
+    }
+    catch {
+        return { ok: false, reason: "unreadable", bytesRead: 0 };
+    }
+    const parsed = parseSkillHeaderBytes(prefix.text);
+    if (!parsed.ok) {
+        // A file that starts with `---` but whose header delimiter never arrives
+        // inside the window is a too-large header, not a missing one.
+        const truncated = prefix.bytesRead >= maxBytes;
+        const looksLikeFrontmatter = /^(?:\uFEFF)?---\r?\n/.test(prefix.text);
+        if (truncated && looksLikeFrontmatter) {
+            return { ok: false, reason: "too-large", bytesRead: prefix.bytesRead };
+        }
+        return { ...parsed, bytesRead: prefix.bytesRead };
+    }
+    if (!opts?.withBody) {
+        return { ok: true, header: parsed.header, bytesRead: prefix.bytesRead };
+    }
+    try {
+        const fullParsed = parseSkillHeaderBytes(fs.readFileSync(skillPath, "utf-8"));
+        if (!fullParsed.ok) {
+            return { ...fullParsed, bytesRead: prefix.bytesRead };
+        }
+        return { ...fullParsed, bytesRead: prefix.bytesRead };
+    }
+    catch {
+        return { ok: false, reason: "unreadable", bytesRead: prefix.bytesRead };
+    }
+}

package/dist/skills/skill-path-guard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Skill path guard — validates a skill directory NAME in code, before any
+ * path join happens, and then proves containment with realpath.
+ *
+ * A skills directory is a trust boundary: whatever sits inside it is fed to
+ * the model. A directory called `../../.ssh` or `..\..\Windows` must never be
+ * joined onto the skills root, so policy lives here (PRM-09: enforce in code,
+ * never in a prompt) and failures are closed, never guessed.
+ */
+/** Longest accepted skill directory name. Shipped packs are <= 24 chars. */
+export declare const MAX_SKILL_NAME_LENGTH = 64;
+/** Hard ceiling on how many pack directories a single probe will visit. */
+export declare const MAX_PACK_DIRS = 512;
+/**
+ * Hard ceiling on YAML frontmatter size. A skill whose header exceeds this is
+ * rejected outright — a soft cap would re-introduce the unbounded read this
+ * limit exists to prevent.
+ */
+export declare const MAX_FRONTMATTER_BYTES = 8192;
+/** Why a candidate skill directory name was refused. */
+export type SkillNameRejectReason = "empty" | "too-long" | "separator" | "traversal" | "absolute" | "dot-prefixed" | "trailing-dot-or-space" | "reserved-device" | "illegal-char";
+export interface SkillNameCheck {
+    ok: boolean;
+    reason?: SkillNameRejectReason;
+}
+/**
+ * Decide whether `name` is safe to use as a single path segment.
+ *
+ * This is pure string inspection — it never touches the filesystem, so it is
+ * cheap enough to call for every pack on every scan.
+ */
+export declare function validateSkillName(name: string): SkillNameCheck;
+/**
+ * Resolve `parentDir/dirName` and prove the result is a *direct child* of
+ * `parentDir` both lexically and after symlink resolution.
+ *
+ * Returns `undefined` when the name is unsafe, when the entry does not exist,
+ * or when the real path escapes the parent (a symlinked pack). Callers skip
+ * anything that comes back `undefined` — fail closed.
+ */
+export declare function resolveSkillDir(parentDir: string, dirName: string): string | undefined;

package/dist/skills/skill-path-guard.js

@@ -0,0 +1,95 @@
+// xcoder:version 1 | xcoder:task task-f9cf18 | xcoder:updated 2026-11-02T16:13:48.255Z | xcoder:subtask code-st-077ea2
+/**
+ * Skill path guard — validates a skill directory NAME in code, before any
+ * path join happens, and then proves containment with realpath.
+ *
+ * A skills directory is a trust boundary: whatever sits inside it is fed to
+ * the model. A directory called `../../.ssh` or `..\..\Windows` must never be
+ * joined onto the skills root, so policy lives here (PRM-09: enforce in code,
+ * never in a prompt) and failures are closed, never guessed.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** Longest accepted skill directory name. Shipped packs are <= 24 chars. */
+export const MAX_SKILL_NAME_LENGTH = 64;
+/** Hard ceiling on how many pack directories a single probe will visit. */
+export const MAX_PACK_DIRS = 512;
+/**
+ * Hard ceiling on YAML frontmatter size. A skill whose header exceeds this is
+ * rejected outright — a soft cap would re-introduce the unbounded read this
+ * limit exists to prevent.
+ */
+export const MAX_FRONTMATTER_BYTES = 8192;
+/** Windows device names are resolved by the OS even with an extension. */
+const RESERVED_DEVICE_NAMES = new Set([
+    "con",
+    "prn",
+    "aux",
+    "nul",
+    ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+    ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
+/** Only these characters may appear in a skill directory name. */
+const SAFE_NAME_RE = /^[A-Za-z0-9._-]+$/;
+/**
+ * Decide whether `name` is safe to use as a single path segment.
+ *
+ * This is pure string inspection — it never touches the filesystem, so it is
+ * cheap enough to call for every pack on every scan.
+ */
+export function validateSkillName(name) {
+    if (typeof name !== "string" || name.length === 0) {
+        return { ok: false, reason: "empty" };
+    }
+    if (name.length > MAX_SKILL_NAME_LENGTH) {
+        return { ok: false, reason: "too-long" };
+    }
+    if (path.isAbsolute(name) || /^[A-Za-z]:/.test(name)) {
+        return { ok: false, reason: "absolute" };
+    }
+    if (name.includes("/") || name.includes("\\")) {
+        return { ok: false, reason: "separator" };
+    }
+    if (name === "." || name === ".." || name.includes("..")) {
+        return { ok: false, reason: "traversal" };
+    }
+    if (name.startsWith(".")) {
+        return { ok: false, reason: "dot-prefixed" };
+    }
+    if (name.endsWith(".") || name.endsWith(" ")) {
+        return { ok: false, reason: "trailing-dot-or-space" };
+    }
+    if (RESERVED_DEVICE_NAMES.has(name.split(".")[0].toLowerCase())) {
+        return { ok: false, reason: "reserved-device" };
+    }
+    if (!SAFE_NAME_RE.test(name)) {
+        return { ok: false, reason: "illegal-char" };
+    }
+    return { ok: true };
+}
+/**
+ * Resolve `parentDir/dirName` and prove the result is a *direct child* of
+ * `parentDir` both lexically and after symlink resolution.
+ *
+ * Returns `undefined` when the name is unsafe, when the entry does not exist,
+ * or when the real path escapes the parent (a symlinked pack). Callers skip
+ * anything that comes back `undefined` — fail closed.
+ */
+export function resolveSkillDir(parentDir, dirName) {
+    if (!validateSkillName(dirName).ok)
+        return undefined;
+    const parent = path.resolve(parentDir);
+    const candidate = path.resolve(parent, dirName);
+    if (candidate === parent || path.dirname(candidate) !== parent)
+        return undefined;
+    try {
+        const realParent = fs.realpathSync(parent);
+        const realCandidate = fs.realpathSync(candidate);
+        if (path.dirname(realCandidate) !== realParent)
+            return undefined;
+        return realCandidate;
+    }
+    catch {
+        return undefined;
+    }
+}