gsd-pi 2.77.0-dev.58d3d4d6c → 2.77.0-dev.cfd69e714

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -353,7 +353,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         if (isAutoActive() && typeof event.toolCallId === "string") {
             markToolEnd(event.toolCallId);
         }
-        if (isAutoActive() && event.isError && event.toolName.startsWith("gsd_")) {
+        if (isAutoActive() && event.isError) {
             const resultPayload = ("result" in event ? event.result : undefined);
             const errorText = typeof resultPayload === "string"
                 ? resultPayload
@@ -362,6 +362,8 @@ export function registerHooks(pi, ecosystemHandlers) {
                     : (typeof event.content === "string"
                         ? event.content
                         : String(resultPayload ?? "")));
+            // Let recordToolInvocationError classify the failure so non-gsd_ harness
+            // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
         }
         if (event.toolName !== "ask_user_questions")
@@ -447,12 +449,14 @@ export function registerHooks(pi, ecosystemHandlers) {
     });
     pi.on("tool_execution_end", async (event) => {
         markToolEnd(event.toolCallId);
-        // #2883: Capture tool invocation errors (malformed/truncated JSON arguments)
+        // #2883/#4974: Capture deterministic invocation/policy errors
         // so postUnitPreVerification can break the retry loop instead of re-dispatching.
-        if (event.isError && event.toolName.startsWith("gsd_")) {
+        if (event.isError) {
             const errorText = typeof event.result === "string"
                 ? event.result
                 : (typeof event.result?.content?.[0]?.text === "string" ? event.result.content[0].text : String(event.result));
+            // Let recordToolInvocationError classify the failure so non-gsd_ harness
+            // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
         }
         // Safety harness: record tool execution results for evidence cross-referencing

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

@@ -1,6 +1,13 @@
-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$/;
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { minimatch } from "minimatch";
+/**
+ * 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;
 /**
@@ -76,8 +83,15 @@ const GATE_SAFE_TOOLS = new Set([
     "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
     "search_and_read",
 ]);
+/**
+ * Persistence is ON by default (opt-out).
+ * Set GSD_PERSIST_WRITE_GATE_STATE="0" or GSD_PERSIST_WRITE_GATE_STATE="false"
+ * to disable. All other values — including unset — persist the snapshot.
+ * (Inverted from the original opt-in guard; see #4950.)
+ */
 function shouldPersistWriteGateSnapshot(env = process.env) {
-    return env.GSD_PERSIST_WRITE_GATE_STATE === "1";
+    const v = env.GSD_PERSIST_WRITE_GATE_STATE;
+    return v !== "0" && v !== "false";
 }
 function writeGateSnapshotPath(basePath = process.cwd()) {
     return join(basePath, ".gsd", "runtime", "write-gate-state.json");
@@ -94,9 +108,22 @@ function persistWriteGateSnapshot(basePath = process.cwd()) {
         return;
     const path = writeGateSnapshotPath(basePath);
     mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
-    const tempPath = `${path}.tmp`;
+    const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
     writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(), null, 2), "utf-8");
-    renameSync(tempPath, path);
+    try {
+        renameSync(tempPath, path);
+    }
+    catch (err) {
+        // EXDEV: cross-device rename (temp and dest on different mounts). Fall back
+        // to copy-then-delete so the snapshot is still written atomically enough.
+        if (err instanceof Error && err.code === "EXDEV") {
+            copyFileSync(tempPath, path);
+            unlinkSync(tempPath);
+        }
+        else {
+            throw err;
+        }
+    }
 }
 function clearPersistedWriteGateSnapshot(basePath = process.cwd()) {
     if (!shouldPersistWriteGateSnapshot())
@@ -295,9 +322,9 @@ export function isDepthConfirmationAnswer(selected, options) {
         const confirmLabel = options[0]?.label;
         return typeof confirmLabel === "string" && value === confirmLabel;
     }
-    // Fallback when options aren't available (e.g., older call sites):
-    // accept only if it contains "(Recommended)" — the prompt convention suffix.
-    return value.includes("(Recommended)");
+    // Fail-closed: no options means we cannot structurally validate the answer.
+    // Returning false prevents any free-form string from unlocking the gate.
+    return false;
 }
 export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queuePhaseActive) {
     if (toolName !== "write")
@@ -413,3 +440,94 @@ export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, q
         reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. Unknown tools are not permitted during queue mode.`,
     };
 }
+// ─── Planning-unit tools-policy enforcement (#4934) ───────────────────────
+const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
+const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
+const PLANNING_SAFE_TOOLS = new Set([
+    "read", "grep", "find", "ls", "glob",
+    "ask_user_questions",
+    "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
+    "search_and_read",
+]);
+function isPathUnderGsd(absPath, basePath) {
+    const gsdRoot = resolve(basePath, ".gsd");
+    const rel = relative(gsdRoot, absPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function matchesAllowedGlob(absPath, basePath, globs) {
+    const rel = relative(basePath, absPath);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return false;
+    const posix = rel.split(sep).join("/");
+    return globs.some(g => minimatch(posix, g, { dot: false, nocase: false }));
+}
+function blockReason(unitType, mode, what) {
+    return [
+        `HARD BLOCK: unit "${unitType}" runs under tools-policy "${mode}" — ${what}.`,
+        `This is a mechanical gate enforced by manifest.tools (#4934). You MUST NOT proceed,`,
+        `retry the same call, or rationalize past this block. If you need to write user source,`,
+        `the work belongs in execute-task, not in a planning unit.`,
+    ].join(" ");
+}
+/**
+ * Planning-unit tool-policy enforcement. Returns { block } per the policy
+ * resolved from the active unit's manifest:
+ *
+ *   - "all"        → never blocks.
+ *   - "read-only"  → blocks all writes, bash, and subagent dispatch.
+ *   - "planning"   → blocks writes to paths outside <basePath>/.gsd/,
+ *                    bash that isn't read-only, and subagent dispatch.
+ *   - "docs"       → like "planning" but also allows writes to paths
+ *                    matching `allowedPathGlobs` relative to basePath.
+ *
+ * `policy` of null means "no manifest resolved" — pass-through.
+ */
+export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitType, policy) {
+    if (!policy)
+        return { block: false };
+    if (policy.mode === "all")
+        return { block: false };
+    const tool = toolName;
+    if (policy.mode === "read-only") {
+        if (PLANNING_SAFE_TOOLS.has(tool))
+            return { block: false };
+        if (tool.startsWith("gsd_"))
+            return { block: false };
+        if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
+            return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
+        }
+        return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
+    }
+    // planning / docs modes
+    if (PLANNING_SAFE_TOOLS.has(tool))
+        return { block: false };
+    if (tool.startsWith("gsd_"))
+        return { block: false };
+    if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
+        return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
+    }
+    if (tool === "bash") {
+        if (BASH_READ_ONLY_RE.test(pathOrCommand))
+            return { block: false };
+        return {
+            block: true,
+            reason: blockReason(unitType, policy.mode, `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`),
+        };
+    }
+    if (PLANNING_WRITE_TOOLS.has(tool)) {
+        if (!pathOrCommand) {
+            return { block: true, reason: blockReason(unitType, policy.mode, `${tool} called with empty path`) };
+        }
+        const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
+        if (isPathUnderGsd(absPath, basePath))
+            return { block: false };
+        if (policy.mode === "docs" && matchesAllowedGlob(absPath, basePath, policy.allowedPathGlobs)) {
+            return { block: false };
+        }
+        return {
+            block: true,
+            reason: blockReason(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`),
+        };
+    }
+    return { block: false };
+}

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;
+}