@aitne/daemon 0.1.7 → 0.1.9

package/dist/core/skills-compiler-denied-tools.js

@@ -0,0 +1,204 @@
+import { INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, collectSessionDeniedTools, filterDeniedToolsForBackend, } from "@aitne/shared";
+/**
+ * §7.7 — apply the per-integration tool-deny policy to a delegated skill
+ * body. Two enforcement modes:
+ *
+ *  - **Claude (hard enforcement):** parse the YAML frontmatter and remove
+ *    every `allowed-tools` entry whose unsuffixed name (after the
+ *    descriptor's `toolNamespace`) is in `deniedTools`. The Claude Agent
+ *    SDK refuses to invoke any tool not present in `allowed-tools`, so
+ *    this is hard enforcement at the SDK boundary.
+ *
+ *  - **Codex / Gemini (soft enforcement):** append a "Denied tools (do
+ *    not invoke)" prose block at the end of the skill body listing the
+ *    full namespaced tool names. The CLI surfaces have no per-tool deny
+ *    mechanism comparable to Claude's `allowed-tools`; the prose is the
+ *    only guard. Documented soft-enforcement gap.
+ *
+ * Stale entries (a deniedTools name that doesn't match any tool in the
+ * active backend's `capabilityTools`) are silently ignored — the API
+ * already rejects them at PATCH time, but a delegatedBackend swap can
+ * leave Claude-namespaced names in a list now active for Codex.
+ *
+ * Run AFTER `renderPartialIncludes` and `stripUnconfiguredServices` so
+ * partial includes and service-section gating land first.
+ */
+export function applyDeniedTools(content, integrationKey, backendId, deniedTools) {
+    if (deniedTools.length === 0)
+        return content;
+    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
+    const connector = descriptor.backendConnectors[backendId];
+    if (!connector)
+        return content;
+    const { active } = filterDeniedToolsForBackend(integrationKey, backendId, deniedTools);
+    if (active.length === 0)
+        return content;
+    const namespacedDenied = active.map((t) => `${connector.toolNamespace}${t}`);
+    if (backendId === "claude") {
+        return filterClaudeAllowedTools(content, new Set(namespacedDenied));
+    }
+    return appendCliDenyBlock(content, namespacedDenied);
+}
+/**
+ * Strip every `allowed-tools` frontmatter entry whose name appears in
+ * `deniedSet`. Preserves frontmatter ordering, line breaks, and any other
+ * fields. Tolerates two YAML shapes:
+ *
+ *   allowed-tools:
+ *     - name1
+ *     - name2
+ *
+ *   allowed-tools: [name1, name2]
+ *
+ * The first form is what every skill in `agent-assets/skills/` uses today;
+ * the inline form is supported because it's valid YAML and the API + UI
+ * have no way to prevent a hand-edited skill from using it.
+ */
+function filterClaudeAllowedTools(content, deniedSet) {
+    if (!content.startsWith("---"))
+        return content;
+    const endIdx = content.indexOf("\n---", 3);
+    if (endIdx < 0)
+        return content;
+    const frontmatter = content.slice(4, endIdx);
+    const body = content.slice(endIdx + 4);
+    const lines = frontmatter.split("\n");
+    const out = [];
+    let inAllowedTools = false;
+    for (const line of lines) {
+        if (/^allowed-tools:\s*\[/.test(line)) {
+            // Inline-array form: parse, filter, re-emit on one line.
+            const m = /^(allowed-tools:\s*)\[([^\]]*)\]/.exec(line);
+            if (m) {
+                const items = m[2]
+                    .split(",")
+                    .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                    .filter((s) => s.length > 0 && !deniedSet.has(s));
+                out.push(`${m[1]}[${items.join(", ")}]`);
+                continue;
+            }
+        }
+        if (/^allowed-tools:\s*$/.test(line)) {
+            inAllowedTools = true;
+            out.push(line);
+            continue;
+        }
+        if (inAllowedTools) {
+            // Block-list form continuation. A block-list item is `  - <name>`;
+            // anything else (next top-level key, blank, or end of frontmatter)
+            // ends the section.
+            const itemMatch = /^\s*-\s*(.+?)\s*$/.exec(line);
+            if (itemMatch) {
+                const name = itemMatch[1].replace(/^["']|["']$/g, "");
+                if (!deniedSet.has(name))
+                    out.push(line);
+                continue;
+            }
+            // Anything else closes the block.
+            inAllowedTools = false;
+        }
+        out.push(line);
+    }
+    return `---\n${out.join("\n")}\n---${body}`;
+}
+/**
+ * DELEGATED-MODE-V2-DESIGN.md §4.3.3-§4.3.4 — render a top-level prose
+ * deny block listing every same-backend integration tool the user has
+ * denied. Returns `null` when no integration is in same-backend mode for
+ * this backend or the deny lists are empty.
+ *
+ * Codex (γ outcome): this prose is the ONLY enforcement surface — the
+ * Codex CLI's connector apps have no admin-policy or per-tool deny config.
+ * The agent profile (`AGENTS.md`) inlines this block above the behavioral
+ * rules so it is impossible to miss.
+ *
+ * Gemini: duplicate intent — admin-policy already hard-denies these tools
+ * (§4.3.3 hard enforcement), but echoing the deny in prose saves tokens
+ * the model would otherwise spend drafting a doomed call.
+ */
+export function buildSameBackendDenyBlock(integrations, sessionBackend) {
+    const map = collectSessionDeniedTools(integrations, sessionBackend);
+    if (map.size === 0)
+        return null;
+    const lines = [
+        "## Denied tools (per-integration)",
+        "",
+        "The user has restricted the following connector tools for this session.",
+        "Do NOT invoke them in any flow — including hourly check, morning routine,",
+        "or DM responses. If a workflow appears to require one, stop and tell the",
+        "user the tool is denied.",
+    ];
+    for (const [key, names] of map.entries()) {
+        lines.push("", `### ${key}`, "");
+        for (const n of names)
+            lines.push(`- \`${n}\``);
+    }
+    return lines.join("\n");
+}
+/**
+ * Append a soft-enforcement deny block to a CLI skill body. The block is
+ * idempotent — re-running with the same denied set produces identical
+ * output.
+ */
+function appendCliDenyBlock(content, namespacedDenied) {
+    // Strip any prior deny block we wrote, so re-materialization with a
+    // changed list doesn't accumulate stale ones. The block starts with
+    // `\n## Denied tools (do not invoke)` (one preceding newline, the join
+    // contributes the second) and runs until either the next `## ` heading
+    // or end of file.
+    const stripped = content.replace(/\n+## Denied tools \(do not invoke\)[\s\S]*?(?=\n## (?!Denied tools)|$)/, "");
+    const items = namespacedDenied.map((n) => `- \`${n}\``).join("\n");
+    // Two leading empty strings → block begins with "\n\n## " so the heading
+    // sits on its own paragraph (markdown convention) regardless of what
+    // trailing whitespace the body carried.
+    const block = [
+        "",
+        "",
+        "## Denied tools (do not invoke)",
+        "",
+        "The user has restricted these connector tools for this integration. Do",
+        "NOT invoke them in any flow — including hourly check, morning routine,",
+        "or DM responses. If a workflow appears to require one, stop and tell",
+        "the user the tool is denied.",
+        "",
+        items,
+        "",
+    ].join("\n");
+    return stripped.replace(/\s*$/, "") + block;
+}
+/**
+ * Apply the deny pass for every integration whose `skillsTouched` OR
+ * `deniedToolsAppliesToSkills` includes the given skill slug. A skill that
+ * touches no integration leaves content unchanged. Touching multiple
+ * integrations runs the pass once per integration so each contributes its
+ * own deny list.
+ *
+ * Hard enforcement of the same deny list for cross-backend delegated
+ * calls lives at the `POST /api/integrations/:key/exec` task-mode
+ * chokepoint (DELEGATED-MODE-V2-DESIGN.md §4.3.2). For same-backend
+ * native MCP it is
+ * enforced via SDK `disallowedTools` (Claude) / admin policy (Gemini);
+ * see `collectSessionDeniedTools` (§4.3.3).
+ */
+export function applyAllDeniedToolsForSkill(content, skillSlug, backendId, integrations) {
+    let result = content;
+    for (const key of INTEGRATION_KEYS) {
+        const descriptor = INTEGRATION_DESCRIPTORS[key];
+        const touched = descriptor.skillsTouched.includes(skillSlug)
+            || (descriptor.deniedToolsAppliesToSkills?.includes(skillSlug) ?? false);
+        if (!touched)
+            continue;
+        const state = integrations[key];
+        if (!state)
+            continue;
+        if (state.mode !== "delegated")
+            continue;
+        if (!state.delegatedBackend || state.delegatedBackend !== backendId)
+            continue;
+        const denied = state.deniedTools ?? [];
+        if (denied.length === 0)
+            continue;
+        result = applyDeniedTools(result, key, backendId, denied);
+    }
+    return result;
+}

package/dist/core/skills-compiler-skill-index.d.ts

@@ -0,0 +1,117 @@
+import type { BackendId } from "@aitne/shared";
+export declare const logger: import("pino").Logger<never, boolean>;
+/**
+ * Strip service sections from external-services/SKILL.md that correspond to
+ * unconfigured integrations. Sections are delimited by HTML comments:
+ *   <!-- service:calendar --> ... <!-- /service:calendar -->
+ * When `configuredServices` is empty the content is returned unchanged — the
+ * "no services configured yet" case keeps every section so the agent can see
+ * the full menu. Only strips once the user has configured at least one
+ * service (and therefore expressed an intent to narrow the surface).
+ */
+export declare function stripUnconfiguredServices(content: string, configuredServices: ReadonlySet<string>): string;
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §"Skill preamble" — load the static
+ * preamble shipped at
+ * `agent-assets/system-prompts/skill-index-instruction.md`. The preamble
+ * is constant per backend (Codex / Gemini) and explains the on-demand
+ * skill-load protocol. Returns a built-in minimal fallback when the asset
+ * is missing so tests that don't seed the system-prompts dir still
+ * produce deterministic output.
+ */
+export declare function loadSkillIndexPreamble(workspaceDir: string): string;
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §"`<skill-index>` block" — render
+ * the per-slug index from the **materialised** SKILL.md frontmatter on
+ * disk. Walking the destination dir (instead of the source manifest)
+ * keeps the index in sync with what the agent will actually find when
+ * it reads:
+ *
+ *   - Same-backend native MCP slugs whose variant resolved to `null` are
+ *     correctly omitted (no SKILL.md was written).
+ *   - User-authored slugs synced AFTER `writeSkillsDir` (via
+ *     `syncAllUserSkills` from the workdir layer) appear automatically
+ *     when this is called from the post-sync refresh helper.
+ *   - Frontmatter that has gone through curation / mode filter / deny
+ *     pass / read-sensitive banner reflects the post-pipeline state.
+ *
+ * The block is emitted with a fixed XML-style envelope so tests can pin
+ * its placement and the splicer in `refreshSkillIndexBlock` can locate
+ * it for in-place rewrites between turns.
+ *
+ * `destSkillsRootRelative` is the on-disk path the agent should Read
+ * (`.codex/skills` or `.gemini/skills`); it gets embedded in the header
+ * sentence verbatim. Built-ins and user-authored slugs are not
+ * distinguished here — see R4.
+ */
+export declare function renderSkillIndexBlock(destSkillsRootAbs: string, destSkillsRootRelative: string): string;
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 — re-render the `<skill-index>` block
+ * inside an existing instruction file. Called by the workdir layer AFTER
+ * `syncAllUserSkills` so user-authored slugs land in the index alongside
+ * the built-ins (`renderSkillIndexBlock` reads the dest dir on disk, so a
+ * post-sync re-render naturally picks them up).
+ *
+ * No-op when:
+ *  - The backend is Claude (no instruction file with `<skill-index>`).
+ *  - The instruction file is missing (the session has not been
+ *    materialised yet).
+ *  - The instruction file carries no `<skill-index>` block (slim
+ *    fetch_window sessions, or future backends that opt out).
+ *
+ * Idempotent — re-running with the same dest contents produces an
+ * identical instruction file.
+ */
+export declare function refreshSkillIndexBlock(sessionDir: string, backendId: BackendId): void;
+/**
+ * Resolve `{{> base }}` include directives in a skill/task-flow variant file.
+ * Reads `SKILL.base.md` (or `<key>.base.md` for task flows) from `basePath`
+ * and replaces every occurrence of `{{> base }}` with the base file's content
+ * (frontmatter stripped). A missing or empty base file is silently ignored.
+ *
+ * Only `{{> base }}` is supported — this is intentionally minimal (§4.7
+ * design note: "~40 lines of pure TS").
+ *
+ * @deprecated DELEGATED-PROXY-API-DESIGN.md §11 — after Phase D no in-tree
+ * skill uses `{{> base }}`: mail / external-services unified their bodies
+ * during Phase D, and the lone surviving `notion/SKILL.base.md` was
+ * removed in Phase 9 (its hourly-check read-only constraint moved to
+ * `routine.hourly_check.md` task-flow where the rule applies in every
+ * integration mode, including same-backend delegated where the skill
+ * body is dropped). The helper is retained for future composition needs;
+ * remove the call sites in `materializeClaudeSession` /
+ * `materializeCliSession` when no consumer reappears.
+ */
+export declare function renderPartialIncludes(content: string, basePath: string): string;
+/**
+ * Resolve `{{> ref:<name> }}` directives in a skill body by inlining
+ * `references/<name>.md` (frontmatter stripped) from the skill's source dir.
+ *
+ * Mirrors `renderPartialIncludes` but is intra-skill, not cross-skill: each
+ * skill carries its own `references/` dir. Used by progressive-disclosure
+ * skills (planned for `mail`, `roadmap`, `reading`, `user-interview` after
+ * Phase 2-B) so heavy reference tables can live next to the skill body
+ * without bloating the navigation overview.
+ *
+ * Behaviour:
+ *  - Missing `references/<name>.md` → directive replaced with empty string;
+ *    logged at WARN. (Mirrors the deprecated helper's missing-base behaviour.)
+ *  - The directive matches `{{> ref:<name> }}` with the strict-kebab name
+ *    pattern `[a-z][a-z0-9-]*`. Path-traversal (`../`, leading underscore,
+ *    uppercase) is rejected at the regex level — `existsSync` is never
+ *    consulted for invalid names.
+ *  - Multiple occurrences each inline the same file's content (re-read per
+ *    occurrence — pinned by the unit tests so a later caching refactor must
+ *    surface as a deliberate change).
+ *  - Frontmatter on the reference file (if present) is stripped before
+ *    inline, so reference files can carry `---\nkind: reference\n---`
+ *    headers for tooling without leaking YAML into skill bodies.
+ *  - The resolver is NOT fence-aware; a directive inside a triple-backtick
+ *    fence is still expanded. This matches `renderPartialIncludes` and is
+ *    deliberate for v1 — fence-aware resolution would be a separate refactor.
+ *
+ * Phase 2-A ships compiler-only; no in-tree skill carries a directive yet
+ * (`skills-manifest.test.ts` pins `0` as the lockstep count). Phase 2-B
+ * starts emitting them per the migration map in `SKILLS-PHASE-2-PLAN.md`.
+ */
+export declare function renderReferenceIncludes(content: string, skillSrcDir: string): string;

package/dist/core/skills-compiler-skill-index.js

@@ -0,0 +1,262 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../logging.js";
+import { parseSkillFrontmatter } from "./skills-compiler-variants.js";
+// Peer logger for this module. Exported so tests can spy on `logger.warn`
+// (specifically the missing-reference branch of `renderReferenceIncludes`).
+// Production callers do not import it.
+export const logger = createLogger("skills-compiler-skill-index");
+/**
+ * Strip service sections from external-services/SKILL.md that correspond to
+ * unconfigured integrations. Sections are delimited by HTML comments:
+ *   <!-- service:calendar --> ... <!-- /service:calendar -->
+ * When `configuredServices` is empty the content is returned unchanged — the
+ * "no services configured yet" case keeps every section so the agent can see
+ * the full menu. Only strips once the user has configured at least one
+ * service (and therefore expressed an intent to narrow the surface).
+ */
+export function stripUnconfiguredServices(content, configuredServices) {
+    if (configuredServices.size === 0)
+        return content;
+    const servicePattern = /<!-- service:(\w+) -->\n([\s\S]*?)<!-- \/service:\1 -->\n?/g;
+    return content.replace(servicePattern, (match, service) => configuredServices.has(service) ? match : "");
+}
+/** Strip YAML frontmatter (--- ... ---) from markdown content. */
+function stripFrontmatter(content) {
+    if (!content.startsWith("---"))
+        return content;
+    const endIdx = content.indexOf("\n---", 3);
+    if (endIdx < 0)
+        return content;
+    return content.slice(endIdx + 4).replace(/^\n+/, "");
+}
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §"Skill preamble" — load the static
+ * preamble shipped at
+ * `agent-assets/system-prompts/skill-index-instruction.md`. The preamble
+ * is constant per backend (Codex / Gemini) and explains the on-demand
+ * skill-load protocol. Returns a built-in minimal fallback when the asset
+ * is missing so tests that don't seed the system-prompts dir still
+ * produce deterministic output.
+ */
+export function loadSkillIndexPreamble(workspaceDir) {
+    const path = join(workspaceDir, "agent-assets", "system-prompts", "skill-index-instruction.md");
+    if (existsSync(path)) {
+        return readFileSync(path, "utf-8").trim();
+    }
+    return [
+        "## Skills",
+        "",
+        "Skills are materialised on disk under the per-backend dotfile",
+        "directory. When your task matches an entry in `<skill-index>` below,",
+        "`Read` its `SKILL.md` and follow the contents.",
+    ].join("\n");
+}
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 — splice sentinels.
+ *
+ * The visible `<skill-index>` / `</skill-index>` XML-style tags are the
+ * agent-facing contract; they MUST stay in the rendered output for the
+ * preamble's protocol to make sense. But using them as the splicer's
+ * region markers is fragile — any profile body, skill body, or user
+ * prose that quotes the tag verbatim would be misidentified as the
+ * splice region and silently corrupted on `refreshSkillIndexBlock`.
+ *
+ * The sentinels below are unique HTML comments emitted immediately
+ * outside the visible tags. The splicer keys on them instead, so even
+ * a profile that quotes `<skill-index>` cannot collide with the splice
+ * region. Comments render as low-signal tokens to the model and add
+ * ~50 bytes per session — negligible against the ~3 KB block.
+ */
+const SKILL_INDEX_START_SENTINEL = "<!-- skill-index:start -->";
+const SKILL_INDEX_END_SENTINEL = "<!-- skill-index:end -->";
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 §"`<skill-index>` block" — render
+ * the per-slug index from the **materialised** SKILL.md frontmatter on
+ * disk. Walking the destination dir (instead of the source manifest)
+ * keeps the index in sync with what the agent will actually find when
+ * it reads:
+ *
+ *   - Same-backend native MCP slugs whose variant resolved to `null` are
+ *     correctly omitted (no SKILL.md was written).
+ *   - User-authored slugs synced AFTER `writeSkillsDir` (via
+ *     `syncAllUserSkills` from the workdir layer) appear automatically
+ *     when this is called from the post-sync refresh helper.
+ *   - Frontmatter that has gone through curation / mode filter / deny
+ *     pass / read-sensitive banner reflects the post-pipeline state.
+ *
+ * The block is emitted with a fixed XML-style envelope so tests can pin
+ * its placement and the splicer in `refreshSkillIndexBlock` can locate
+ * it for in-place rewrites between turns.
+ *
+ * `destSkillsRootRelative` is the on-disk path the agent should Read
+ * (`.codex/skills` or `.gemini/skills`); it gets embedded in the header
+ * sentence verbatim. Built-ins and user-authored slugs are not
+ * distinguished here — see R4.
+ */
+export function renderSkillIndexBlock(destSkillsRootAbs, destSkillsRootRelative) {
+    const lines = [
+        SKILL_INDEX_START_SENTINEL,
+        "<skill-index>",
+        `The following skills are materialized at \`${destSkillsRootRelative}/<name>/SKILL.md\`.`,
+        "When your task matches a skill's `description`, `Read` the `SKILL.md`",
+        "to load its guidance and follow it. Skill bodies are NOT inlined in",
+        "this prompt — read them on demand. Multiple skills may be loaded in",
+        "one turn.",
+        "",
+    ];
+    let entryCount = 0;
+    if (existsSync(destSkillsRootAbs)) {
+        const slugs = readdirSync(destSkillsRootAbs, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort((a, b) => a.localeCompare(b));
+        for (const slug of slugs) {
+            const skillMdPath = join(destSkillsRootAbs, slug, "SKILL.md");
+            if (!existsSync(skillMdPath))
+                continue;
+            const fm = parseSkillFrontmatter(readFileSync(skillMdPath, "utf-8"));
+            if (!fm.name || !fm.description)
+                continue;
+            lines.push(`- name: ${fm.name}`);
+            lines.push(`  description: ${fm.description}`);
+            entryCount++;
+        }
+    }
+    if (entryCount === 0) {
+        lines.push("(No skills materialized this turn — proceed with the runtime profile only.)");
+    }
+    lines.push("</skill-index>", SKILL_INDEX_END_SENTINEL);
+    return lines.join("\n");
+}
+/**
+ * docs/design/appendices/skills-unification.md Phase 1 — re-render the `<skill-index>` block
+ * inside an existing instruction file. Called by the workdir layer AFTER
+ * `syncAllUserSkills` so user-authored slugs land in the index alongside
+ * the built-ins (`renderSkillIndexBlock` reads the dest dir on disk, so a
+ * post-sync re-render naturally picks them up).
+ *
+ * No-op when:
+ *  - The backend is Claude (no instruction file with `<skill-index>`).
+ *  - The instruction file is missing (the session has not been
+ *    materialised yet).
+ *  - The instruction file carries no `<skill-index>` block (slim
+ *    fetch_window sessions, or future backends that opt out).
+ *
+ * Idempotent — re-running with the same dest contents produces an
+ * identical instruction file.
+ */
+export function refreshSkillIndexBlock(sessionDir, backendId) {
+    // docs/design/appendices/skills-unification.md Phase 1 §R3 — OpenCode never gets a
+    // `<skill-index>` block. The cwd auto-discovery loader is the source
+    // of truth; emitting an index would inject a second listing the
+    // runtime ignores. Also matters in fallback workdirs where codex and
+    // opencode share AGENTS.md: a stray opencode refresh would clobber
+    // the codex-rendered sentinels with opencode's skill listing.
+    //
+    // Backend→dotfile dir mapping is inlined here (rather than imported from
+    // skills-compiler-cli-renderer) so this module sits at the same DAG
+    // level as cli-renderer — both depend only on `variants`. The mapping
+    // is two cases and changes once per new backend; the cost of duplication
+    // is bounded.
+    let cliRoot;
+    if (backendId === "codex")
+        cliRoot = ".codex";
+    else if (backendId === "gemini")
+        cliRoot = ".gemini";
+    else
+        return; // claude / opencode / future backends without `<skill-index>`
+    const destSkillsRootRelative = join(cliRoot, "skills");
+    const destSkillsRootAbs = join(sessionDir, destSkillsRootRelative);
+    const fileName = backendId === "gemini" ? "GEMINI.md" : "AGENTS.md";
+    const instructionPath = join(sessionDir, fileName);
+    if (!existsSync(instructionPath))
+        return;
+    const current = readFileSync(instructionPath, "utf-8");
+    // Splice on the HTML-comment sentinels, NOT on the visible
+    // `<skill-index>` tags — the sentinels are unique enough that a
+    // profile body or user-authored skill that quotes the visible tag
+    // cannot collide with the splice region.
+    const startIdx = current.indexOf(SKILL_INDEX_START_SENTINEL);
+    const endIdx = startIdx >= 0
+        ? current.indexOf(SKILL_INDEX_END_SENTINEL, startIdx + SKILL_INDEX_START_SENTINEL.length)
+        : -1;
+    if (startIdx < 0 || endIdx < 0)
+        return; // OpenCode (no index) or slim path
+    const replacement = renderSkillIndexBlock(destSkillsRootAbs, destSkillsRootRelative);
+    const next = current.slice(0, startIdx) +
+        replacement +
+        current.slice(endIdx + SKILL_INDEX_END_SENTINEL.length);
+    if (next !== current) {
+        writeFileSync(instructionPath, next, "utf-8");
+    }
+}
+/**
+ * Resolve `{{> base }}` include directives in a skill/task-flow variant file.
+ * Reads `SKILL.base.md` (or `<key>.base.md` for task flows) from `basePath`
+ * and replaces every occurrence of `{{> base }}` with the base file's content
+ * (frontmatter stripped). A missing or empty base file is silently ignored.
+ *
+ * Only `{{> base }}` is supported — this is intentionally minimal (§4.7
+ * design note: "~40 lines of pure TS").
+ *
+ * @deprecated DELEGATED-PROXY-API-DESIGN.md §11 — after Phase D no in-tree
+ * skill uses `{{> base }}`: mail / external-services unified their bodies
+ * during Phase D, and the lone surviving `notion/SKILL.base.md` was
+ * removed in Phase 9 (its hourly-check read-only constraint moved to
+ * `routine.hourly_check.md` task-flow where the rule applies in every
+ * integration mode, including same-backend delegated where the skill
+ * body is dropped). The helper is retained for future composition needs;
+ * remove the call sites in `materializeClaudeSession` /
+ * `materializeCliSession` when no consumer reappears.
+ */
+export function renderPartialIncludes(content, basePath) {
+    if (!content.includes("{{> base }}"))
+        return content;
+    if (!existsSync(basePath))
+        return content.replace(/\{\{> base \}\}/g, "");
+    const baseRaw = readFileSync(basePath, "utf-8");
+    const baseContent = stripFrontmatter(baseRaw).trim();
+    return content.replace(/\{\{> base \}\}/g, baseContent);
+}
+/**
+ * Resolve `{{> ref:<name> }}` directives in a skill body by inlining
+ * `references/<name>.md` (frontmatter stripped) from the skill's source dir.
+ *
+ * Mirrors `renderPartialIncludes` but is intra-skill, not cross-skill: each
+ * skill carries its own `references/` dir. Used by progressive-disclosure
+ * skills (planned for `mail`, `roadmap`, `reading`, `user-interview` after
+ * Phase 2-B) so heavy reference tables can live next to the skill body
+ * without bloating the navigation overview.
+ *
+ * Behaviour:
+ *  - Missing `references/<name>.md` → directive replaced with empty string;
+ *    logged at WARN. (Mirrors the deprecated helper's missing-base behaviour.)
+ *  - The directive matches `{{> ref:<name> }}` with the strict-kebab name
+ *    pattern `[a-z][a-z0-9-]*`. Path-traversal (`../`, leading underscore,
+ *    uppercase) is rejected at the regex level — `existsSync` is never
+ *    consulted for invalid names.
+ *  - Multiple occurrences each inline the same file's content (re-read per
+ *    occurrence — pinned by the unit tests so a later caching refactor must
+ *    surface as a deliberate change).
+ *  - Frontmatter on the reference file (if present) is stripped before
+ *    inline, so reference files can carry `---\nkind: reference\n---`
+ *    headers for tooling without leaking YAML into skill bodies.
+ *  - The resolver is NOT fence-aware; a directive inside a triple-backtick
+ *    fence is still expanded. This matches `renderPartialIncludes` and is
+ *    deliberate for v1 — fence-aware resolution would be a separate refactor.
+ *
+ * Phase 2-A ships compiler-only; no in-tree skill carries a directive yet
+ * (`skills-manifest.test.ts` pins `0` as the lockstep count). Phase 2-B
+ * starts emitting them per the migration map in `SKILLS-PHASE-2-PLAN.md`.
+ */
+export function renderReferenceIncludes(content, skillSrcDir) {
+    return content.replace(/\{\{> ref:([a-z][a-z0-9-]*) \}\}/g, (_match, name) => {
+        const refPath = join(skillSrcDir, "references", `${name}.md`);
+        if (!existsSync(refPath)) {
+            logger.warn({ skillSrcDir, name }, "renderReferenceIncludes: missing reference file");
+            return "";
+        }
+        return stripFrontmatter(readFileSync(refPath, "utf-8")).trim();
+    });
+}

package/dist/core/skills-compiler-tree.d.ts

@@ -0,0 +1,38 @@
+import type { MailAccount } from "../services/mail/provider.js";
+export interface SkillCompilerFile {
+    path: string;
+    content: string;
+    updatedAt: string | null;
+}
+/**
+ * Walk a materialized session subdirectory and rewrite every `.md` file with
+ * `{APP_NAME}` tokens resolved. Called immediately after `cpSync(src, dest, …)`
+ * so the verbatim copy from `agent-assets/` becomes brand-substituted before
+ * any downstream transform (renderReferenceIncludes, applyIntegrationModeFilter,
+ * tool-deny filter) reads it. Idempotent — running it twice is a no-op.
+ */
+export declare function substituteBrandTokensInDir(dir: string): void;
+interface WikiWorkspaceTokens {
+    vault_path: string;
+    language: string;
+    workspace_name: string;
+    schema_version: string;
+}
+export declare function setWikiWorkspaceTokenResolver(resolver: ((processKey: string, workspaceName?: string) => WikiWorkspaceTokens | null) | null): void;
+export declare function substituteWikiWorkspaceTokens(content: string, processKey: string | null | undefined, workspaceName: string | undefined): string;
+export declare function substituteWikiWorkspaceTokensInDir(dir: string, processKey: string | null | undefined, workspaceName: string | undefined): void;
+export declare const EMPTY_MAIL_ACCOUNTS_MD: string;
+export declare function renderMailAccountsMd(accounts: readonly MailAccount[]): string;
+/**
+ * Remove any built-in skill directory under `destRoot` whose slug is not
+ * in `keep`. Recognises a directory as a built-in by its presence under
+ * the source `agent-assets/skills/` tree — anything else (user-authored
+ * skill, accounts.md, etc.) is left alone, since `syncAllUserSkills` is
+ * the canonical writer for those.
+ *
+ * Idempotent and side-effect-free when there is nothing to prune.
+ * Exported for unit testing only.
+ */
+export declare function pruneStaleBuiltinSkillDirs(destRoot: string, sourceSkillsRoot: string, keep: readonly string[]): void;
+export declare function readTreeFiles(root: string): SkillCompilerFile[];
+export {};