gsd-pi 2.77.0-dev.1d17f366c → 2.77.0-dev.2daa994b6

package/dist/resources/extensions/gsd/auto-start.js

@@ -19,12 +19,13 @@ import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock } from "./crash-recovery.js";
 import { acquireSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
-import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeCheckoutBranch, nativeBranchList, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeCheckoutBranch, nativeBranchList, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, nativeCommitCountBetween, } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import { captureIntegrationBranch, detectWorktreeName, setActiveMilestoneId, } from "./worktree.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { readResourceVersion, cleanStaleRuntimeUnits } from "./auto-worktree.js";
 import { worktreePath as getWorktreeDir, isInsideWorktreesDir } from "./worktree-manager.js";
+import { emitWorktreeOrphaned } from "./worktree-telemetry.js";
 import { initMetrics } from "./metrics.js";
 import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
@@ -63,25 +64,15 @@ export async function openProjectDbIfPresent(basePath) {
         logWarning("engine", `gsd-db: failed to open existing database: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-/**
- * Audit for orphaned milestone branches at bootstrap.
- *
- * After a milestone completes, the teardown step (merge branch → main,
- * delete branch, remove worktree) runs as a post-completion engine step.
- * If the session ends between completion and teardown, the branch and
- * worktree are orphaned — the DB says "complete" so auto-mode won't
- * re-enter the milestone, and the teardown is never retried.
- *
- * This audit runs on every fresh bootstrap to catch that gap:
- * 1. Lists all local `milestone/*` branches.
- * 2. For each, checks if the milestone's DB status is "complete".
- * 3. If the branch is already merged into main → deletes the branch
- *    and cleans up any orphaned worktree directory (safe, no data loss).
- * 4. If the branch is NOT merged → preserves it and warns the user
- *    so they can merge manually (data safety first).
- *
- * Returns a summary of actions taken for the caller to surface via notify.
- */
+export function decideSurvivorAction(hasSurvivorBranch, phase) {
+    if (!hasSurvivorBranch)
+        return "none";
+    if (phase === "needs-discussion")
+        return "discuss";
+    if (phase === "complete")
+        return "finalize";
+    return "none";
+}
 export function auditOrphanedMilestoneBranches(basePath, isolationMode) {
     const recovered = [];
     const warnings = [];
@@ -120,10 +111,58 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode) {
     for (const branch of milestoneBranches) {
         const milestoneId = branch.replace(/^milestone\//, "");
         const milestone = getMilestone(milestoneId);
-        // Only audit completed milestones
-        if (!milestone || milestone.status !== "complete")
+        if (!milestone)
             continue;
         const isMerged = mergedBranches.has(branch);
+        // #4762 — in-progress milestone branch with unmerged commits ahead of
+        // main. This is the pre-completion orphan case: auto-mode exited without
+        // completing the milestone (pause, stop, crash, merge error, blocker) and
+        // work is stranded on the branch or in the worktree. Data safety first:
+        // we never delete or touch; we just surface a warning so the user knows
+        // where to look.
+        //
+        // Gate on isClosedStatus so we only warn about genuinely open milestones.
+        // Parked/other closed statuses go through the legacy complete/unmerged
+        // path below where appropriate.
+        if (!isClosedStatus(milestone.status)) {
+            if (isMerged)
+                continue; // nothing to recover
+            let commitsAhead = 0;
+            try {
+                commitsAhead = nativeCommitCountBetween(basePath, mainBranch, branch);
+            }
+            catch {
+                // Rev-walk failure — skip rather than noise
+                continue;
+            }
+            if (commitsAhead === 0)
+                continue;
+            const wtDir = getWorktreeDir(basePath, milestoneId);
+            const wtDirExists = existsSync(wtDir);
+            const wtSuffix = wtDirExists
+                ? ` Worktree directory at .gsd/worktrees/${milestoneId}/ holds the live work.`
+                : "";
+            warnings.push(`Branch ${branch} has ${commitsAhead} commit(s) ahead of ${mainBranch} for in-progress milestone ${milestoneId}.` +
+                wtSuffix +
+                ` Run \`/gsd auto\` to resume, or merge manually if abandoning.`);
+            // #4764 telemetry
+            try {
+                emitWorktreeOrphaned(basePath, milestoneId, {
+                    reason: "in-progress-unmerged",
+                    commitsAhead,
+                    worktreeDirExists: wtDirExists,
+                });
+            }
+            catch (err) {
+                logWarning("engine", `worktree-orphaned telemetry failed for ${milestoneId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            continue;
+        }
+        // Only the "complete" status participates in the merged/unmerged cleanup
+        // paths below — other closed statuses (parked, etc.) are intentionally
+        // left alone.
+        if (milestone.status !== "complete")
+            continue;
         if (isMerged) {
             // Branch is merged — safe to delete branch and clean up worktree dir
             try {
@@ -170,6 +209,16 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode) {
             // Branch is NOT merged — preserve for safety, warn the user
             warnings.push(`Branch ${branch} exists for completed milestone ${milestoneId} but is NOT merged into ${mainBranch}. ` +
                 `This may contain unmerged work. Merge manually or run \`/gsd health --fix\` to resolve.`);
+            // #4764 telemetry
+            try {
+                emitWorktreeOrphaned(basePath, milestoneId, {
+                    reason: "complete-unmerged",
+                    worktreeDirExists: existsSync(getWorktreeDir(basePath, milestoneId)),
+                });
+            }
+            catch (err) {
+                logWarning("engine", `worktree-orphaned telemetry failed for ${milestoneId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     return { recovered, warnings };
@@ -391,7 +440,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // The worktree/branch was created but the milestone only has CONTEXT-DRAFT.md.
         // Route to the interactive discussion handler instead of falling through to
         // auto-mode, which would immediately stop with "needs discussion".
-        if (hasSurvivorBranch && state.phase === "needs-discussion") {
+        if (decideSurvivorAction(hasSurvivorBranch, state.phase) === "discuss") {
             const { showSmartEntry } = await import("./guided-flow.js");
             await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
             invalidateAllCaches();
@@ -411,7 +460,9 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // The milestone artifacts were written but finalization (merge, worktree
         // cleanup) never ran. Run mergeAndExit to finalize, then re-derive state
         // so the normal "all milestones complete" or "next milestone" path runs.
-        if (hasSurvivorBranch && state.phase === "complete") {
+        // Re-evaluate via the helper — the discuss branch above may have cleared
+        // hasSurvivorBranch after a successful promotion.
+        if (decideSurvivorAction(hasSurvivorBranch, state.phase) === "finalize") {
             const mid = state.activeMilestone.id;
             ctx.ui.notify(`Milestone ${mid} is complete but branch/worktree was not finalized. Running merge now.`, "info");
             const resolver = buildResolver();

package/dist/resources/extensions/gsd/auto.js

@@ -528,6 +528,40 @@ export async function stopAuto(ctx, pi, reason) {
         return;
     const loadedPreferences = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
     const reasonSuffix = reason ? ` — ${reason}` : "";
+    // #4764 — telemetry: record the exit reason and whether the current milestone
+    // was merged before we entered stopAuto. This is the producer-side signal for
+    // the #4761 orphan class: milestoneMerged=false + currentMilestoneId present
+    // is exactly the pattern that strands work.
+    try {
+        const { emitAutoExit } = await import("./worktree-telemetry.js");
+        // Normalize the free-form reason to a closed set so the telemetry
+        // aggregator buckets stably. Raw detail is preserved in the phases.ts
+        // notification and the notify'd error string.
+        const rawReason = reason ?? "stop";
+        const normalizedReason = rawReason.startsWith("Blocked:")
+            ? "blocked"
+            : rawReason.startsWith("Merge conflict")
+                ? "merge-conflict"
+                : rawReason.startsWith("Merge error") || rawReason.startsWith("Merge failed")
+                    ? "merge-failed"
+                    : rawReason.startsWith("slice-merge-conflict")
+                        ? "slice-merge-conflict"
+                        : rawReason === "All milestones complete"
+                            ? "all-complete"
+                            : rawReason === "No active milestone"
+                                ? "no-active-milestone"
+                                : rawReason === "stop" || rawReason === "pause"
+                                    ? rawReason
+                                    : "other";
+        emitAutoExit(s.originalBasePath || s.basePath, {
+            reason: normalizedReason,
+            milestoneId: s.currentMilestoneId ?? undefined,
+            milestoneMerged: s.milestoneMergedInPhases === true,
+        });
+    }
+    catch (err) {
+        logWarning("engine", `auto-exit telemetry failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     try {
         // ── Step 1: Timers and locks ──
         try {

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -12,7 +12,15 @@ import { classifyError, createRetryState, resetRetryState, isTransient, } from "
 import { blockModel, isModelBlocked } from "../blocked-models.js";
 const retryState = createRetryState();
 const MAX_NETWORK_RETRIES = 2;
-const MAX_TRANSIENT_AUTO_RESUMES = 8;
+/**
+ * Cap on auto-resume attempts for sustained transient-provider errors.
+ *
+ * Exported so tests assert against the shared constant instead of
+ * regex-scraping the source literal (see #4837). Raising this value to
+ * handle longer provider overloads should update the single constant; the
+ * test in provider-errors.test.ts consumes it directly.
+ */
+export const MAX_TRANSIENT_AUTO_RESUMES = 8;
 /**
  * Reset the module-level retry state so a resumed auto-session starts fresh.
  * Called by provider-error-resume.ts before startAuto() — without this, the

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,6 +1,12 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
+/**
+ * Regex matching milestone CONTEXT.md file names in both legacy M001
+ * and unique M001-abc123 formats. Exported so regex-hardening tests
+ * can exercise the real pattern rather than a drift-prone inline
+ * re-implementation (see #4835).
+ */
+export const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
 /**

package/dist/resources/extensions/gsd/component-loader.js

@@ -0,0 +1,447 @@
+/**
+ * Component Loader
+ *
+ * Multi-format loader that handles:
+ * 1. New format: component.yaml + SKILL.md/AGENT.md
+ * 2. Legacy skill format: SKILL.md with YAML frontmatter
+ * 3. Legacy agent format: .md with YAML frontmatter (name, description, tools, model)
+ *
+ * Auto-detects format by checking for component.yaml first, then falling back
+ * to legacy formats based on file naming conventions.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { parseFrontmatter } from '@gsd/pi-coding-agent';
+import { validateComponentName, validateComponentDescription, computeComponentId, } from './component-types.js';
+const SUPPORTED_COMPONENT_KINDS = ['skill', 'agent'];
+const SUPPORTED_API_VERSIONS = ['gsd/v1'];
+// ============================================================================
+// Single Component Loading
+// ============================================================================
+/**
+ * Load a component from a directory.
+ * Checks for component.yaml first, then legacy formats.
+ */
+export function loadComponentFromDir(dir, source) {
+    const diagnostics = [];
+    // Try new format first: component.yaml
+    const componentYamlPath = join(dir, 'component.yaml');
+    if (existsSync(componentYamlPath)) {
+        return loadFromComponentYaml(componentYamlPath, dir, source);
+    }
+    // Try legacy skill format: SKILL.md
+    const skillMdPath = join(dir, 'SKILL.md');
+    if (existsSync(skillMdPath)) {
+        return loadFromLegacySkill(skillMdPath, dir, source);
+    }
+    // No recognized component format found
+    return { component: null, diagnostics };
+}
+/**
+ * Load a component from a legacy agent .md file (flat file, not directory).
+ */
+export function loadComponentFromAgentFile(filePath, source) {
+    return loadFromLegacyAgent(filePath, source);
+}
+// ============================================================================
+// New Format: component.yaml
+// ============================================================================
+function loadFromComponentYaml(yamlPath, dir, source) {
+    const diagnostics = [];
+    let raw;
+    try {
+        raw = readFileSync(yamlPath, 'utf-8');
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'failed to read component.yaml';
+        diagnostics.push({ type: 'error', message: msg, path: yamlPath });
+        return { component: null, diagnostics };
+    }
+    let definition;
+    try {
+        definition = parseYaml(raw);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'failed to parse component.yaml';
+        diagnostics.push({ type: 'error', message: `invalid YAML: ${msg}`, path: yamlPath });
+        return { component: null, diagnostics };
+    }
+    // Validate required fields
+    if (!definition?.apiVersion) {
+        diagnostics.push({ type: 'error', message: 'missing apiVersion', path: yamlPath });
+        return { component: null, diagnostics };
+    }
+    if (!SUPPORTED_API_VERSIONS.includes(definition.apiVersion)) {
+        diagnostics.push({
+            type: 'error',
+            message: `unsupported apiVersion "${String(definition.apiVersion)}"`,
+            path: yamlPath,
+        });
+        return { component: null, diagnostics };
+    }
+    if (!definition.kind) {
+        diagnostics.push({ type: 'error', message: 'missing kind', path: yamlPath });
+        return { component: null, diagnostics };
+    }
+    if (!SUPPORTED_COMPONENT_KINDS.includes(definition.kind)) {
+        diagnostics.push({
+            type: 'error',
+            message: `unsupported kind "${definition.kind}"`,
+            path: yamlPath,
+        });
+        return { component: null, diagnostics };
+    }
+    if (!definition.metadata?.name) {
+        diagnostics.push({ type: 'error', message: 'missing metadata.name', path: yamlPath });
+        return { component: null, diagnostics };
+    }
+    if (!definition.metadata?.description) {
+        diagnostics.push({ type: 'error', message: 'missing metadata.description', path: yamlPath });
+        return { component: null, diagnostics };
+    }
+    const nameErrors = validateComponentName(definition.metadata.name);
+    for (const err of nameErrors) {
+        diagnostics.push({ type: 'error', message: err, path: yamlPath });
+    }
+    const descErrors = validateComponentDescription(definition.metadata.description);
+    for (const err of descErrors) {
+        diagnostics.push({ type: 'error', message: err, path: yamlPath });
+    }
+    if (nameErrors.length > 0 || descErrors.length > 0) {
+        return { component: null, diagnostics };
+    }
+    // Validate kind-specific spec
+    if (!definition.spec) {
+        diagnostics.push({ type: 'error', message: 'missing spec', path: yamlPath });
+        return { component: null, diagnostics };
+    }
+    const entryFileDiagnostic = validateEntryFile(definition.kind, definition.spec, dir, yamlPath);
+    if (entryFileDiagnostic) {
+        diagnostics.push(entryFileDiagnostic);
+        return { component: null, diagnostics };
+    }
+    const id = computeComponentId(definition.metadata.name, definition.metadata.namespace);
+    const component = {
+        id,
+        kind: definition.kind,
+        metadata: definition.metadata,
+        spec: definition.spec,
+        requires: definition.requires,
+        compatibility: definition.compatibility,
+        routing: definition.routing,
+        dirPath: dir,
+        filePath: yamlPath,
+        source,
+        format: 'component-yaml',
+        enabled: true,
+    };
+    return { component, diagnostics };
+}
+function loadFromLegacySkill(filePath, dir, source) {
+    const diagnostics = [];
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'failed to read SKILL.md';
+        diagnostics.push({ type: 'warning', message: msg, path: filePath });
+        return { component: null, diagnostics };
+    }
+    const { frontmatter } = parseFrontmatter(raw);
+    const parentDirName = basename(dir);
+    const name = frontmatter.name || parentDirName;
+    // Validate
+    const nameErrors = validateComponentName(name);
+    for (const err of nameErrors) {
+        diagnostics.push({ type: 'warning', message: err, path: filePath });
+    }
+    const descErrors = validateComponentDescription(frontmatter.description);
+    for (const err of descErrors) {
+        diagnostics.push({ type: 'warning', message: err, path: filePath });
+    }
+    if (!frontmatter.description || frontmatter.description.trim() === '') {
+        return { component: null, diagnostics };
+    }
+    const spec = {
+        prompt: 'SKILL.md',
+        disableModelInvocation: frontmatter['disable-model-invocation'] === true,
+    };
+    const id = computeComponentId(name);
+    const component = {
+        id,
+        kind: 'skill',
+        metadata: {
+            name,
+            description: frontmatter.description,
+        },
+        spec,
+        dirPath: dir,
+        filePath,
+        source,
+        format: 'skill-md',
+        enabled: true,
+    };
+    return { component, diagnostics };
+}
+function loadFromLegacyAgent(filePath, source) {
+    const diagnostics = [];
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'failed to read agent file';
+        diagnostics.push({ type: 'warning', message: msg, path: filePath });
+        return { component: null, diagnostics };
+    }
+    const { frontmatter } = parseFrontmatter(raw);
+    if (!frontmatter.name || !frontmatter.description) {
+        diagnostics.push({
+            type: 'warning',
+            message: 'agent file missing name or description in frontmatter',
+            path: filePath,
+        });
+        return { component: null, diagnostics };
+    }
+    // Parse tools from comma-separated string
+    const tools = frontmatter.tools
+        ? {
+            allow: frontmatter.tools
+                .split(',')
+                .map((t) => t.trim())
+                .filter(Boolean),
+        }
+        : undefined;
+    const spec = {
+        systemPrompt: basename(filePath),
+        model: frontmatter.model,
+        tools,
+    };
+    const id = computeComponentId(frontmatter.name);
+    const dir = dirname(filePath);
+    const component = {
+        id,
+        kind: 'agent',
+        metadata: {
+            name: frontmatter.name,
+            description: frontmatter.description,
+        },
+        spec,
+        dirPath: dir,
+        filePath,
+        source,
+        format: 'agent-md',
+        enabled: true,
+    };
+    return { component, diagnostics };
+}
+// ============================================================================
+// Directory Scanning
+// ============================================================================
+/**
+ * Scan a directory for components (skills format).
+ * Handles both new and legacy directory layouts.
+ *
+ * Expected layouts:
+ * - dir/{component-name}/component.yaml  (new format)
+ * - dir/{component-name}/SKILL.md        (legacy skill)
+ * - dir/{name}.md                        (legacy root-level skill)
+ */
+export function scanComponentDir(dir, source, kind) {
+    const components = [];
+    const diagnostics = [];
+    if (!existsSync(dir)) {
+        return { components, diagnostics };
+    }
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf-8' });
+    }
+    catch {
+        return { components, diagnostics };
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+            continue;
+        }
+        const fullPath = join(dir, entry.name);
+        let isDir = entry.isDirectory();
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                const stats = statSync(fullPath);
+                isDir = stats.isDirectory();
+                isFile = stats.isFile();
+            }
+            catch {
+                continue;
+            }
+        }
+        if (isDir) {
+            const result = loadComponentFromDir(fullPath, source);
+            if (result.component) {
+                if (!kind || result.component.kind === kind) {
+                    components.push(result.component);
+                }
+            }
+            diagnostics.push(...result.diagnostics);
+        }
+        else if (isFile && entry.name.endsWith('.md')) {
+            // Root-level .md files — could be legacy skills or agents
+            // Peek at frontmatter to determine type
+            const result = loadFromFile(fullPath, source);
+            if (result.component) {
+                if (!kind || result.component.kind === kind) {
+                    components.push(result.component);
+                }
+            }
+            diagnostics.push(...result.diagnostics);
+        }
+    }
+    return { components, diagnostics };
+}
+/**
+ * Scan a directory specifically for agent .md files (legacy agent format).
+ */
+export function scanAgentDir(dir, source) {
+    const components = [];
+    const diagnostics = [];
+    if (!existsSync(dir)) {
+        return { components, diagnostics };
+    }
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf-8' });
+    }
+    catch {
+        return { components, diagnostics };
+    }
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        let isDir = entry.isDirectory();
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                const stats = statSync(fullPath);
+                isDir = stats.isDirectory();
+                isFile = stats.isFile();
+            }
+            catch {
+                continue;
+            }
+        }
+        if (isDir) {
+            const result = loadComponentFromDir(fullPath, source);
+            if (result.component?.kind === 'agent') {
+                components.push(result.component);
+            }
+            diagnostics.push(...result.diagnostics);
+            continue;
+        }
+        if (!entry.name.endsWith('.md'))
+            continue;
+        if (!isFile)
+            continue;
+        // Check if there's a component.yaml in a same-named directory
+        const nameWithoutExt = entry.name.replace(/\.md$/, '');
+        const componentDir = join(dir, nameWithoutExt);
+        if (existsSync(join(componentDir, 'component.yaml'))) {
+            // New format takes precedence and is loaded by the directory branch.
+            continue;
+        }
+        const result = loadComponentFromAgentFile(fullPath, source);
+        if (result.component) {
+            components.push(result.component);
+        }
+        diagnostics.push(...result.diagnostics);
+    }
+    return { components, diagnostics };
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Load a single file, detecting whether it's a skill or agent by frontmatter.
+ */
+function loadFromFile(filePath, source) {
+    const diagnostics = [];
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'failed to read file';
+        diagnostics.push({ type: 'warning', message: msg, path: filePath });
+        return { component: null, diagnostics };
+    }
+    const { frontmatter } = parseFrontmatter(raw);
+    // If it has 'tools' field, treat as agent
+    if (frontmatter.tools !== undefined) {
+        return loadFromLegacyAgent(filePath, source);
+    }
+    // Otherwise treat as a legacy skill (root-level .md)
+    const dir = dirname(filePath);
+    const name = frontmatter.name || basename(filePath, '.md');
+    const description = frontmatter.description;
+    if (!description || description.trim() === '') {
+        return { component: null, diagnostics };
+    }
+    const spec = {
+        prompt: basename(filePath),
+        disableModelInvocation: frontmatter['disable-model-invocation'] === true,
+    };
+    const id = computeComponentId(name);
+    const component = {
+        id,
+        kind: 'skill',
+        metadata: { name, description },
+        spec,
+        dirPath: dir,
+        filePath,
+        source,
+        format: 'skill-md',
+        enabled: true,
+    };
+    return { component, diagnostics };
+}
+function validateEntryFile(kind, spec, dir, yamlPath) {
+    const relativePath = kind === 'skill'
+        ? spec.prompt
+        : spec.systemPrompt;
+    const field = kind === 'skill' ? 'spec.prompt' : 'spec.systemPrompt';
+    if (!relativePath || typeof relativePath !== 'string') {
+        return {
+            type: 'error',
+            message: `missing ${field}`,
+            path: yamlPath,
+        };
+    }
+    const entryPath = join(dir, relativePath);
+    if (!existsSync(entryPath)) {
+        return {
+            type: 'error',
+            message: `missing referenced file for ${field}: ${relativePath}`,
+            path: entryPath,
+        };
+    }
+    try {
+        if (!statSync(entryPath).isFile()) {
+            return {
+                type: 'error',
+                message: `referenced ${field} is not a file: ${relativePath}`,
+                path: entryPath,
+            };
+        }
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'failed to inspect referenced file';
+        return {
+            type: 'error',
+            message: `${msg}: ${relativePath}`,
+            path: entryPath,
+        };
+    }
+    return null;
+}