wingfoil 0.2.2 → 0.3.0

package/dist/core/loaders.js

@@ -1,15 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ROLES_YAML_PATH = exports.DIRECTIVES_DIR_PATH = exports.DNA_YAML_PATH = exports.MEMORY_YAML_PATH = void 0;
+exports.ROLES_YAML_PATH = exports.DIRECTIVES_DIR_PATH = exports.DNA_YAML_PATH = exports.MEMORY_YAML_PATH = exports.ConfigFileMissingError = void 0;
 exports.loadMemoryYaml = loadMemoryYaml;
 exports.loadMemoryYamlAtHead = loadMemoryYamlAtHead;
+exports.loadMemoryYamlAtRev = loadMemoryYamlAtRev;
+exports.loadMemoryYamlAtCommit = loadMemoryYamlAtCommit;
 exports.loadDnaYaml = loadDnaYaml;
 exports.loadDnaYamlAtHead = loadDnaYamlAtHead;
+exports.loadDnaYamlAtRev = loadDnaYamlAtRev;
+exports.loadDnaYamlAtCommit = loadDnaYamlAtCommit;
 exports.loadWorkflowsYaml = loadWorkflowsYaml;
+exports.loadWorkflowsYamlAtRev = loadWorkflowsYamlAtRev;
+exports.loadWorkflowsYamlAtCommit = loadWorkflowsYamlAtCommit;
+exports.loadDirectiveInventory = loadDirectiveInventory;
 exports.loadDirectives = loadDirectives;
 exports.loadDirectivesAtHead = loadDirectivesAtHead;
+exports.loadDirectivesAtRev = loadDirectivesAtRev;
+exports.loadDirectivesAtCommit = loadDirectivesAtCommit;
 exports.loadRolesYaml = loadRolesYaml;
 exports.loadRolesYamlAtHead = loadRolesYamlAtHead;
+exports.loadRolesYamlAtRev = loadRolesYamlAtRev;
+exports.loadRolesYamlAtCommit = loadRolesYamlAtCommit;
 /**
  * Per-pillar loaders (task-004-decoupled-pillars, REQ-SYS-02). `core` exposes exactly one loader
  * per pillar — `loadMemoryYaml`, `loadDnaYaml`, `loadWorkflowsYaml`, `loadDirectives` — each reading
@@ -24,40 +35,163 @@ exports.loadRolesYamlAtHead = loadRolesYamlAtHead;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const schema_1 = require("../directives/schema");
+const version_1 = require("../directives/version");
 const schema_2 = require("../dna/schema");
 const schema_3 = require("../memory/schema");
 const storage_1 = require("../storage");
 const validation_1 = require("../validation");
+const format_1 = require("../validation/format");
 const schema_4 = require("../workflow/schema");
+const revision_1 = require("./revision");
+const bindings_1 = require("../workflow/bindings");
+const workflow_diagnostics_1 = require("./workflow-diagnostics");
 /**
- * Recursively list every `.md` file under `dir`, as paths relative to `dir`, sorted
- * lexicographically (REQ-SYS-07: no unordered iteration in a context-building path — directory-entry
+ * The resolved `Stats` of `full`, or why it cannot be resolved (task-143, `bug-125`). `statSync`
+ * follows a symbolic link, so a dangling one throws `ENOENT` — the raw error that used to escape every
+ * directive read. `lstatSync` sees the entry itself first, so a broken link is told apart from any
+ * other failure and named as one. The reasons are phrased like `requireInspectableTarget`'s
+ * (`./write-guard.ts`), the write-side guard over the same kind of entry.
+ */
+function resolveEntry(full) {
+    try {
+        return (0, fs_1.statSync)(full);
+    }
+    catch (error) {
+        const code = error.code;
+        let isLink = false;
+        try {
+            isLink = (0, fs_1.lstatSync)(full).isSymbolicLink();
+        }
+        catch {
+            // `lstat` fails too — a directory listed without search permission, or an entry that vanished
+            // after `readdirSync`: report what `stat` said.
+        }
+        if (isLink && (code === 'ENOENT' || code === 'ENOTDIR')) {
+            return { reason: 'it is a symbolic link whose target does not exist' };
+        }
+        return { reason: `it cannot be read (${String(code)})` };
+    }
+}
+/** The `code` of a filesystem error, as a skip reason's suffix. */
+function cannotBeRead(error) {
+    return `it cannot be read (${String(error.code)})`;
+}
+/**
+ * Recursively list every `.md` file under `dir`, as paths relative to `dir`, in lexicographic
+ * traversal order (REQ-SYS-07: no unordered iteration in a context-building path — directory-entry
  * order from `readdirSync` is not guaranteed stable, so traversal always sorts explicitly, mirroring
- * `src/storage/snapshot.ts`'s `listFilesSorted`). Returns `[]` if `dir` doesn't exist.
+ * `src/storage/snapshot.ts`'s `listFilesSorted`). Returns no entries if `dir` doesn't exist.
+ *
+ * An entry that cannot be resolved — a dangling symbolic link above all, a subdirectory that cannot be
+ * listed, or a directory link back to one of its own ancestors — is **skipped**, and comes back as a
+ * `skipped` entry with its reason, in the same traversal order (task-143, `bug-125`). Whatever the
+ * link's name, it is reported: a dangling link has no type, so one named without `.md` may have been
+ * a directory of directives. `dir` itself, when it is a dangling link, is one skipped entry with
+ * `relative: ''`.
+ *
+ * Symlinked directories are followed, but never into a directory already on the walk's stack (by
+ * `realpath`): without that, a link to an ancestor is walked until the OS refuses (ELOOP after some
+ * forty levels), and every directive above it is listed that many times (task-143 review).
+ *
+ * `dir` itself is the pillar: when it cannot be listed, `rootError` carries the reason and the caller
+ * refuses the read.
  */
 function listMarkdownFilesSorted(dir) {
-    if (!(0, fs_1.existsSync)(dir) || !(0, fs_1.statSync)(dir).isDirectory())
-        return [];
-    const out = [];
-    const walk = (current, prefix) => {
-        for (const entry of (0, fs_1.readdirSync)(current).sort()) {
+    const entries = [];
+    if (!(0, fs_1.existsSync)(dir)) {
+        // `existsSync` follows a link: a dangling `dir` is reported, a genuinely absent one is not.
+        // `lstat` itself fails on a path through a non-directory (`.wingfoil` a file): absent, as before.
+        let isLink;
+        try {
+            isLink = (0, fs_1.lstatSync)(dir).isSymbolicLink();
+        }
+        catch {
+            isLink = false;
+        }
+        if (isLink)
+            entries.push({ relative: '', kind: 'skipped', reason: 'it is a symbolic link whose target does not exist' });
+        return { entries };
+    }
+    if (!(0, fs_1.statSync)(dir).isDirectory())
+        return { entries };
+    let rootNames;
+    try {
+        rootNames = (0, fs_1.readdirSync)(dir);
+    }
+    catch (error) {
+        return { entries, rootError: cannotBeRead(error) };
+    }
+    const walk = (current, prefix, names, ancestors) => {
+        for (const entry of [...names].sort()) {
             const full = (0, path_1.join)(current, entry);
             const relative = prefix ? `${prefix}/${entry}` : entry;
-            if ((0, fs_1.statSync)(full).isDirectory()) {
-                walk(full, relative);
+            const resolved = resolveEntry(full);
+            if (!('isDirectory' in resolved)) {
+                entries.push({ relative, kind: 'skipped', reason: resolved.reason });
+            }
+            else if (resolved.isDirectory()) {
+                let real;
+                let children;
+                try {
+                    real = (0, fs_1.realpathSync)(full);
+                    children = (0, fs_1.readdirSync)(full);
+                }
+                catch (error) {
+                    entries.push({ relative, kind: 'skipped', reason: cannotBeRead(error) });
+                    continue;
+                }
+                if (ancestors.has(real)) {
+                    entries.push({ relative, kind: 'skipped', reason: 'it is a symbolic link to an ancestor directory' });
+                    continue;
+                }
+                walk(full, relative, children, new Set([...ancestors, real]));
             }
             else if (entry.endsWith('.md')) {
-                out.push(relative);
+                entries.push({ relative, kind: 'file' });
             }
         }
     };
-    walk(dir, '');
-    return out.sort();
+    walk(dir, '', rootNames, new Set([(0, fs_1.realpathSync)(dir)]));
+    return { entries };
+}
+/**
+ * A configuration file the read needs is not in the working tree (task-179, `bug-245`): a `.wingfoil/`
+ * exists — the absent case is `requireInitializedProject`'s — but this pillar's file does not. The
+ * message names the file repository-relative and what to do, never the host's absolute path, so the
+ * output is the same on every machine and safe to paste into an issue. It keeps Node's `code: 'ENOENT'`,
+ * so every caller that maps a missing file (`coreErrorOf` → `NOT_FOUND`, exit `1`) still does.
+ */
+class ConfigFileMissingError extends Error {
+    relativePath;
+    /** Node's code for a missing file, kept so existing `ENOENT` mappings still apply. */
+    code = 'ENOENT';
+    /** @param relativePath - the missing file, relative to the repository root (`.wingfoil/dna.yaml`). */
+    constructor(relativePath) {
+        super(`${relativePath} is missing: restore it from git, or re-create it ('wingfoil init' scaffolds a complete .wingfoil/ in a project that has none)`);
+        this.relativePath = relativePath;
+        this.name = 'ConfigFileMissingError';
+    }
+}
+exports.ConfigFileMissingError = ConfigFileMissingError;
+/**
+ * Read a working-tree configuration file named repository-relative (`.wingfoil/dna.yaml`): a missing one
+ * is a {@link ConfigFileMissingError}, any other failure propagates unchanged. The relative path is also
+ * the label every parse and validation issue carries (task-179, `bug-245`), as the `HEAD:`-labelled
+ * readers already do.
+ */
+function readConfigFile(root, relativePath) {
+    try {
+        return (0, storage_1.readDocument)((0, path_1.join)(root, relativePath));
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            throw new ConfigFileMissingError(relativePath);
+        throw error;
+    }
 }
 /** Load and validate `.wingfoil/memory.yaml` in isolation (spec-001-memory-yaml-schema). */
 function loadMemoryYaml(root) {
-    const filePath = (0, path_1.join)(root, '.wingfoil', 'memory.yaml');
-    return parseMemoryYaml((0, storage_1.readDocument)(filePath), filePath);
+    return parseMemoryYaml(readConfigFile(root, exports.MEMORY_YAML_PATH), exports.MEMORY_YAML_PATH);
 }
 /**
  * Root-relative POSIX path of `memory.yaml` — the form git wants for a revision read
@@ -69,10 +203,13 @@ exports.MEMORY_YAML_PATH = '.wingfoil/memory.yaml';
  * The Memory pillar's two-pass parse, over bytes that may come from anywhere — the working-tree file
  * ({@link loadMemoryYaml}) or a git revision ({@link loadMemoryYamlAtHead}). `filePath` is a label
  * only: it rides every issue this raises, so an error names the baseline it came from
- * (`HEAD:.wingfoil/memory.yaml`, not just a path on disk).
+ * (`HEAD:.wingfoil/memory.yaml`, not just a path on disk). A `format` newer than this build reads is
+ * refused before the structural pass (`dl-149`, task-251).
  */
 function parseMemoryYaml(raw, filePath) {
-    return (0, validation_1.runValidation)(schema_3.MemoryYaml, (0, validation_1.parseYaml)(raw, filePath), filePath);
+    const data = (0, validation_1.parseYaml)(raw, filePath);
+    (0, format_1.refuseNewerFormat)(data, format_1.MEMORY_YAML_FORMAT, filePath);
+    return (0, validation_1.runValidation)(schema_3.MemoryYaml, data, filePath);
 }
 /**
  * Load and validate `.wingfoil/memory.yaml` **as the repository has committed it** — the version at
@@ -94,10 +231,34 @@ function parseMemoryYaml(raw, filePath) {
  * byte-identical, and `HEAD` is the one available before that commit exists.
  */
 function loadMemoryYamlAtHead(root) {
-    const raw = (0, storage_1.readPathAtRev)(root, 'HEAD', exports.MEMORY_YAML_PATH);
+    return (0, revision_1.atHeadOr)(root, () => loadMemoryYamlAtRev(root, 'HEAD'), null);
+}
+/**
+ * Load and validate `.wingfoil/memory.yaml` **as commit `rev` holds it** (task-137, `spec-012` §2
+ * `stateRef`) — the general form of {@link loadMemoryYamlAtHead}, which is this at `'HEAD'`. `null`
+ * when that commit does not hold the file; a later commit and the working tree are never read.
+ *
+ * @param rev - A revision naming one commit, resolved once (`resolveRevision`, `./revision.ts`).
+ * @throws `RevisionError` when `rev` is malformed or names no commit — never an empty answer.
+ */
+function loadMemoryYamlAtRev(root, rev) {
+    return memoryYamlAt(root, (0, revision_1.resolveRevision)(root, rev), rev);
+}
+/**
+ * {@link loadMemoryYamlAtRev} for a `sha` already resolved to a commit (`resolveRevision`, `./revision.ts`),
+ * read without resolving it again: a reader that reads several pillars at one commit resolves it once
+ * (task-283, `bug-309`: the workflow deduction's snapshot).
+ *
+ * @param sha - The full sha of a commit, as `resolveRevision` returned it; parse errors name it.
+ */
+function loadMemoryYamlAtCommit(root, sha) {
+    return memoryYamlAt(root, sha, sha);
+}
+function memoryYamlAt(root, sha, label) {
+    const raw = (0, storage_1.readPathAtRev)(root, sha, exports.MEMORY_YAML_PATH);
     if (raw === null)
         return null;
-    return parseMemoryYaml(raw, `HEAD:${exports.MEMORY_YAML_PATH}`);
+    return parseMemoryYaml(raw, `${label}:${exports.MEMORY_YAML_PATH}`);
 }
 /**
  * `js-yaml`'s `YAMLException#message` always embeds the failure position as `(<line>:<column>)`
@@ -121,7 +282,7 @@ function extractYamlErrorLine(message) {
  * `parseYaml`/`ValidationError`'s shared behavior for `memory.yaml`/`workflows.yaml`/directives.
  */
 function loadDnaYaml(root) {
-    return parseDnaYaml((0, storage_1.readDocument)((0, path_1.join)(root, '.wingfoil', 'dna.yaml')), (0, path_1.join)(root, '.wingfoil', 'dna.yaml'));
+    return parseDnaYaml(readConfigFile(root, exports.DNA_YAML_PATH), exports.DNA_YAML_PATH);
 }
 /**
  * Root-relative POSIX path of `dna.yaml` — the form git wants for a revision read
@@ -147,6 +308,8 @@ function parseDnaYaml(raw, filePath) {
         }
         throw err;
     }
+    // A file from a newer WingFoil is refused for its format alone (`dl-149`, task-251).
+    (0, format_1.refuseNewerFormat)(data, format_1.DNA_YAML_FORMAT, filePath);
     return (0, validation_1.runValidation)(schema_2.DnaYaml, data, filePath);
 }
 /**
@@ -177,55 +340,263 @@ function parseDnaYaml(raw, filePath) {
  * a write refuses while its target carries modifications it does not own.)
  */
 function loadDnaYamlAtHead(root) {
-    const raw = (0, storage_1.readPathAtRev)(root, 'HEAD', exports.DNA_YAML_PATH);
+    return (0, revision_1.atHeadOr)(root, () => loadDnaYamlAtRev(root, 'HEAD'), null);
+}
+/**
+ * Load and validate `.wingfoil/dna.yaml` **as commit `rev` holds it** (task-137, `spec-012` §2
+ * `stateRef`) — the general form of {@link loadDnaYamlAtHead}, which is this at `'HEAD'`. `null` when
+ * that commit does not hold the file; a later commit and the working tree are never read.
+ *
+ * @param rev - A revision naming one commit, resolved once (`resolveRevision`, `./revision.ts`).
+ * @throws `RevisionError` when `rev` is malformed or names no commit — never an empty answer.
+ */
+function loadDnaYamlAtRev(root, rev) {
+    return dnaYamlAt(root, (0, revision_1.resolveRevision)(root, rev), rev);
+}
+/**
+ * {@link loadDnaYamlAtRev} for a `sha` already resolved to a commit, read without resolving it again
+ * (task-283, `bug-309`).
+ *
+ * @param sha - The full sha of a commit, as `resolveRevision` returned it; parse errors name it.
+ */
+function loadDnaYamlAtCommit(root, sha) {
+    return dnaYamlAt(root, sha, sha);
+}
+function dnaYamlAt(root, sha, label) {
+    const raw = (0, storage_1.readPathAtRev)(root, sha, exports.DNA_YAML_PATH);
     if (raw === null)
         return null;
-    return parseDnaYaml(raw, `HEAD:${exports.DNA_YAML_PATH}`);
+    return parseDnaYaml(raw, `${label}:${exports.DNA_YAML_PATH}`);
+}
+/** The manifest's path relative to `.wingfoil/` — the `file` of its diagnostics (spec-003). */
+const WORKFLOWS_MANIFEST_FILE = 'workflows.yaml';
+/** A Zod issue path as spec-003 spells a diagnostic `path`: `phases[3].include`. */
+function diagnosticPath(path) {
+    let out = '';
+    for (const segment of path) {
+        if (typeof segment === 'number')
+            out += `[${segment}]`;
+        else
+            out += out === '' ? String(segment) : `.${String(segment)}`;
+    }
+    return out;
+}
+/**
+ * One included file's structural (Zod) pass, as diagnostics (spec-003 § "Diagnostics": structural
+ * failures keep spec-009's structural codes, except the named `kind` refusal). An empty list means the
+ * file is valid and `workflow` is set.
+ */
+function parseWorkflowFile(data, file, filePath) {
+    const result = schema_4.Workflow.safeParse(data);
+    if (result.success) {
+        // The same once-per-file unknown-field warning `runValidation` fires (spec-009 §2).
+        (0, validation_1.emitUnknownFieldWarning)(data, schema_4.Workflow, filePath);
+        return { workflow: result.data, diagnostics: [] };
+    }
+    const diagnostics = zodDiagnostics(result.error.issues, file).map((diagnostic) => diagnostic.path === 'kind' ? { ...diagnostic, code: 'E_WORKFLOW_INVALID_KIND' } : diagnostic);
+    return { workflow: null, diagnostics };
+}
+/** Zod issues as `E_VALIDATION` diagnostics of `file` (spec-009's structural code). */
+function zodDiagnostics(issues, file) {
+    return issues.map((issue) => ({ code: validation_1.E_VALIDATION, severity: 'error', file, path: diagnosticPath(issue.path), message: issue.message }));
+}
+/**
+ * Parse `raw` as YAML; a parse failure becomes one `E_YAML_PARSE_ERROR` diagnostic of `file` (the
+ * spec-009 code, with the parser's message) instead of a throw, so it takes its place in the array.
+ */
+function parseYamlOrDiagnostic(raw, filePath, file) {
+    try {
+        return { data: (0, validation_1.parseYaml)(raw, filePath), diagnostic: null };
+    }
+    catch (err) {
+        // `parseYaml` throws nothing but `ValidationError.yamlParse`: one issue, the parser's message.
+        const { message } = err.issues[0];
+        return { data: null, diagnostic: { code: validation_1.E_YAML_PARSE_ERROR, severity: 'error', file, path: '', message } };
+    }
 }
 /**
  * Load and validate the Workflow pillar in isolation (spec-003-workflows-yaml-schema): Layer 1
  * (`.wingfoil/workflows.yaml`), then every file its `include` list names (Layer 2), resolved
- * relative to `.wingfoil/` per spec-003. Two cross-file Pass-2 checks that need the loaded files
- * themselves (spec-009 §1 "Cross-file" category) run here, not in the schema module:
+ * relative to `.wingfoil/` per spec-003, then the **loader** rows of spec-003 § "Diagnostics" — the
+ * checks that need the loaded files themselves (spec-009 §1 "Cross-file" category), run here rather
+ * than in the schema module (`./workflow-diagnostics.ts`, task-136).
  *
- * - every `include` path must resolve to a file that actually exists
- *   (`E_WORKFLOW_FILE_NOT_FOUND`, spec-003);
- * - at least one loaded workflow must be `kind: main` (REQ-STATE-03 / spec-003 Layer 1 step 3).
+ * - An **absent** manifest is an empty registry, with no diagnostic (spec-003 Layer 1).
+ * - A manifest that is not YAML, or fails its structural pass, is the whole array: one
+ *   `E_YAML_PARSE_ERROR`, or its Zod issues as `E_VALIDATION`, on `workflows.yaml`.
+ * - Everything else is collected into one ordered `diagnostics` array (REQ-SYS-07): the manifest's
+ *   (`E_WORKFLOW_FILE_NOT_FOUND`, `E_NO_MAIN_WORKFLOW`), then each file in `include` order —
+ *   a YAML parse failure (`E_YAML_PARSE_ERROR`) or the structural (Zod) issues, then
+ *   workflow-level, then phase-level. If it holds an error, the load throws a
+ *   {@link DiagnosticsError}: `VALIDATION`, exit `1`, the first error as the reason and the whole array
+ *   attached.
  */
 function loadWorkflowsYaml(root) {
     const configDir = (0, path_1.join)(root, '.wingfoil');
-    const manifestPath = (0, path_1.join)(configDir, 'workflows.yaml');
-    const manifestRaw = (0, storage_1.readDocument)(manifestPath);
-    const manifestData = (0, validation_1.parseYaml)(manifestRaw, manifestPath);
-    const manifest = (0, validation_1.runValidation)(schema_4.WorkflowsYaml, manifestData, manifestPath);
-    const workflows = [];
-    for (const includePath of manifest.include) {
-        const workflowPath = (0, path_1.join)(configDir, includePath);
-        if (!(0, storage_1.documentExists)(workflowPath)) {
-            throw validation_1.ValidationError.semantic([
-                {
-                    code: 'E_WORKFLOW_FILE_NOT_FOUND',
-                    path: 'include',
-                    file: manifestPath,
-                    message: `included workflow file not found: ${includePath}`,
-                },
-            ]);
+    return loadWorkflowsFrom({
+        read: (file) => {
+            const path = (0, path_1.join)(configDir, file);
+            return (0, storage_1.documentExists)(path) ? (0, storage_1.readDocument)(path) : null;
+        },
+        // Repository-relative, never the host path (task-179, `bug-245`).
+        label: (file) => `.wingfoil/${file}`,
+    });
+}
+/**
+ * Load and validate the Workflow pillar **as commit `rev` holds it** (task-137, `spec-017` §1.1: the
+ * registry is read at `HEAD`): the manifest and every file it includes, read at that commit. It runs
+ * the same body as {@link loadWorkflowsYaml} over the committed bytes, so the result — or the
+ * {@link DiagnosticsError} and its ordered `diagnostics` array (task-136) — is the one the working-tree
+ * loader gives for the same bytes. Only the parse-error labels differ (`<rev>:.wingfoil/<file>`); every
+ * diagnostic's `file` stays relative to `.wingfoil/`. A path the commit holds as a directory counts as
+ * absent (`E_WORKFLOW_FILE_NOT_FOUND`).
+ *
+ * @param rev - A revision naming one commit, resolved once (`resolveRevision`, `./revision.ts`).
+ * @param overlay - Files that replace the commit's own, keyed by repository-relative path (`.wingfoil/…`);
+ *   `null` reads as absent. `workflow create` / `remove` (task-211) load the registry as their commit would
+ *   leave it, before writing it. Empty by default: the commit alone.
+ * @throws `RevisionError` when `rev` is malformed or names no commit — never an empty registry.
+ */
+function loadWorkflowsYamlAtRev(root, rev, overlay = new Map()) {
+    return workflowsYamlAt(root, (0, revision_1.resolveRevision)(root, rev), rev, overlay);
+}
+/**
+ * {@link loadWorkflowsYamlAtRev} for a `sha` already resolved to a commit, read without resolving it
+ * again (task-283, `bug-309`).
+ *
+ * @param sha - The full sha of a commit, as `resolveRevision` returned it; labels name it.
+ * @param overlay - As {@link loadWorkflowsYamlAtRev}'s.
+ */
+function loadWorkflowsYamlAtCommit(root, sha, overlay = new Map()) {
+    return workflowsYamlAt(root, sha, sha, overlay);
+}
+function workflowsYamlAt(root, sha, rev, overlay) {
+    const committedPath = (file) => path_1.posix.normalize(`.wingfoil/${file}`);
+    // The included files and `bindings.yaml`, read in one `cat-file --batch` once the manifest names them
+    // (task-216, REQ-PERF-03: one spawn instead of one per workflow file).
+    const fetched = new Map();
+    const fetch = (files) => {
+        const answers = (0, storage_1.readPathsAtRev)(root, sha, files.map(committedPath));
+        return files.map((file, index) => {
+            const path = committedPath(file);
+            return overlay.has(path) ? overlay.get(path) : (answers[index] ?? null);
+        });
+    };
+    return loadWorkflowsFrom({
+        read: (file) => {
+            if (fetched.has(file))
+                return fetched.get(file);
+            const [raw = null] = fetch([file]);
+            return raw;
+        },
+        prefetch: (files) => {
+            const answers = fetch(files);
+            files.forEach((file, index) => fetched.set(file, answers[index] ?? null));
+        },
+        label: (file) => `${rev}:${committedPath(file)}`,
+    });
+}
+/**
+ * The Workflow pillar's load (spec-003 Layers 1–2 and the loader rows of § "Diagnostics"), over a
+ * {@link WorkflowSource} — the one body {@link loadWorkflowsYaml} and {@link loadWorkflowsYamlAtRev}
+ * share, so the two baselines cannot drift on what a registry or a diagnostic is.
+ */
+function loadWorkflowsFrom(source) {
+    const manifestRaw = source.read(WORKFLOWS_MANIFEST_FILE);
+    if (manifestRaw === null)
+        return { manifest: null, workflows: [], bindings: null, diagnostics: [] };
+    const manifestPath = source.label(WORKFLOWS_MANIFEST_FILE);
+    // A manifest that cannot be read as YAML, or fails its structural pass, names no file to load: its
+    // diagnostics are the whole array.
+    const manifestData = parseYamlOrDiagnostic(manifestRaw, manifestPath, WORKFLOWS_MANIFEST_FILE);
+    if (manifestData.diagnostic)
+        throw new validation_1.DiagnosticsError([manifestData.diagnostic]);
+    // A manifest from a newer WingFoil is refused for its format alone (`dl-149`, task-251).
+    const manifestFormat = (0, format_1.newerFormatIssue)(manifestData.data, format_1.WORKFLOWS_YAML_FORMAT, WORKFLOWS_MANIFEST_FILE);
+    if (manifestFormat)
+        throw new validation_1.DiagnosticsError([{ ...manifestFormat, severity: 'error' }]);
+    const manifestResult = schema_4.WorkflowsYaml.safeParse(manifestData.data);
+    if (!manifestResult.success)
+        throw new validation_1.DiagnosticsError(zodDiagnostics(manifestResult.error.issues, WORKFLOWS_MANIFEST_FILE));
+    (0, validation_1.emitUnknownFieldWarning)(manifestData.data, schema_4.WorkflowsYaml, manifestPath);
+    const manifest = manifestResult.data;
+    source.prefetch?.([...manifest.include, bindings_1.BINDINGS_FILE]);
+    const manifestDiagnostics = [];
+    const files = [];
+    const structural = [];
+    manifest.include.forEach((includePath, position) => {
+        const raw = source.read(includePath);
+        if (raw === null) {
+            manifestDiagnostics.push({
+                code: 'E_WORKFLOW_FILE_NOT_FOUND',
+                severity: 'error',
+                file: WORKFLOWS_MANIFEST_FILE,
+                path: `include[${position}]`,
+                message: `included workflow file not found: ${includePath}`,
+            });
+            return;
         }
-        const raw = (0, storage_1.readDocument)(workflowPath);
-        const data = (0, validation_1.parseYaml)(raw, workflowPath);
-        workflows.push((0, validation_1.runValidation)(schema_4.Workflow, data, workflowPath));
-    }
-    if (!workflows.some((workflow) => workflow.kind === 'main')) {
-        throw validation_1.ValidationError.semantic([
-            {
-                code: 'E_NO_MAIN_WORKFLOW',
-                path: 'include',
-                file: manifestPath,
-                message: 'at least one included workflow must be `kind: main` (REQ-STATE-03)',
-            },
-        ]);
-    }
-    return { manifest, workflows };
+        const workflowPath = source.label(includePath);
+        const yaml = parseYamlOrDiagnostic(raw, workflowPath, includePath);
+        if (yaml.diagnostic) {
+            files.push({ file: includePath, workflow: null, rawName: null });
+            structural.push([yaml.diagnostic]);
+            return;
+        }
+        const data = yaml.data;
+        const rawName = data?.name;
+        // A workflow file from a newer WingFoil: its format is its one structural diagnostic (task-251).
+        const newerFormat = (0, format_1.newerFormatIssue)(data, format_1.WORKFLOW_FORMAT, includePath);
+        if (newerFormat) {
+            files.push({ file: includePath, workflow: null, rawName: typeof rawName === 'string' ? rawName : null });
+            structural.push([{ ...newerFormat, severity: 'error' }]);
+            return;
+        }
+        const parsed = parseWorkflowFile(data, includePath, workflowPath);
+        files.push({ file: includePath, workflow: parsed.workflow, rawName: typeof rawName === 'string' ? rawName : null });
+        structural.push(parsed.diagnostics);
+    });
+    const index = (0, workflow_diagnostics_1.indexWorkflowFiles)(files, manifest.include.length - files.length);
+    const noStartable = (0, workflow_diagnostics_1.noStartableDiagnostic)(files, index);
+    if (noStartable)
+        manifestDiagnostics.push(noStartable);
+    // `workflows/bindings.yaml` (Layer 3, task-175) is read before the workflow files are checked, since
+    // their tokens resolve through it, but its own diagnostics come last (spec-003 § "Diagnostics" order).
+    const layer3 = loadBindingsFrom(source);
+    const diagnostics = [...manifestDiagnostics];
+    files.forEach((_, i) => {
+        diagnostics.push(...structural[i], ...(0, workflow_diagnostics_1.workflowFileDiagnostics)(files, index, i, layer3.context));
+    });
+    diagnostics.push(...layer3.diagnostics);
+    if (diagnostics.some((diagnostic) => diagnostic.severity === 'error'))
+        throw new validation_1.DiagnosticsError(diagnostics);
+    // Every file is structurally valid once no error was reported.
+    return { manifest, workflows: files.map((loaded) => loaded.workflow), bindings: layer3.context.bindings, diagnostics };
+}
+/**
+ * Layer 3 (spec-003, task-175): `workflows/bindings.yaml` through the same source as the workflow
+ * files. Absent → no bindings and no diagnostic. Not YAML → one `E_YAML_PARSE_ERROR`; a newer `format`
+ * (`dl-153` (A)) → one `E_INVALID_FORMAT` in place of the structural pass; structurally invalid → its Zod
+ * issues as `E_VALIDATION`; in all three cases the tokens' bindings are left undecided.
+ * Otherwise the file's loader rows ({@link bindingsFileDiagnostics}).
+ */
+function loadBindingsFrom(source) {
+    const raw = source.read(bindings_1.BINDINGS_FILE);
+    if (raw === null)
+        return { context: workflow_diagnostics_1.NO_BINDINGS_FILE, diagnostics: [] };
+    const undecided = { bindings: null, decided: false };
+    const yaml = parseYamlOrDiagnostic(raw, source.label(bindings_1.BINDINGS_FILE), bindings_1.BINDINGS_FILE);
+    if (yaml.diagnostic)
+        return { context: undecided, diagnostics: [yaml.diagnostic] };
+    // A bindings file from a newer WingFoil is refused for its format alone (`dl-153` (A), task-199).
+    const newerFormat = (0, format_1.newerFormatIssue)(yaml.data, format_1.BINDINGS_YAML_FORMAT, bindings_1.BINDINGS_FILE);
+    if (newerFormat)
+        return { context: undecided, diagnostics: [{ ...newerFormat, severity: 'error' }] };
+    const result = bindings_1.BindingsYaml.safeParse(yaml.data ?? {});
+    if (!result.success)
+        return { context: undecided, diagnostics: zodDiagnostics(result.error.issues, bindings_1.BINDINGS_FILE) };
+    (0, validation_1.emitUnknownFieldWarning)((yaml.data ?? {}), bindings_1.BindingsYaml, source.label(bindings_1.BINDINGS_FILE));
+    return { context: { bindings: result.data, decided: true }, diagnostics: (0, workflow_diagnostics_1.bindingsFileDiagnostics)(result.data) };
 }
 /**
  * Root-relative POSIX path of the Directives tree — the form git wants for a revision listing, as
@@ -241,8 +612,11 @@ exports.DIRECTIVES_DIR_PATH = '.wingfoil/directives';
  * cannot drift on what a directive file *is*.
  *
  * @param relativePath - The file's path relative to `.wingfoil/directives/`, POSIX-spelled.
+ * @param warn - Receives a `version` warning (task-144, R1). `src/core` prints nothing (task-143): the
+ *   working-tree inventory forwards it to its `warnings`; a reader at a revision has no channel and
+ *   drops it.
  */
-function parseDirectiveFile(raw, filePath, relativePath) {
+function parseDirectiveFile(raw, filePath, relativePath, warn = () => { }) {
     const frontmatterText = (0, storage_1.extractFrontmatter)(raw);
     if (frontmatterText === null) {
         throw validation_1.ValidationError.semantic([
@@ -255,25 +629,79 @@ function parseDirectiveFile(raw, filePath, relativePath) {
         ]);
     }
     const data = (0, validation_1.parseYaml)(frontmatterText, filePath);
-    const frontmatter = (0, validation_1.runValidation)(schema_1.DirectiveFrontmatter, data, filePath);
+    // A directive from a newer WingFoil is refused for its format alone (`dl-149`, task-251).
+    (0, format_1.refuseNewerFormat)(data, format_1.DIRECTIVE_FORMAT, filePath);
+    // `version` never fails the pillar (task-144 review, R1): a lossy number or a wrong type is a warning.
+    const versionCheck = (0, version_1.checkDirectiveVersion)(data, frontmatterText);
+    if (versionCheck.warning !== null)
+        warn(versionCheck.warning);
+    const frontmatter = (0, validation_1.runValidation)(schema_1.DirectiveFrontmatter, versionCheck.data, filePath);
     // `join`, so `DirectiveFile.path` carries the platform separator on both loaders — `requireCustomAsset`
     // and `selectDirectivesById` see one spelling whichever baseline produced the file.
     return { path: (0, path_1.join)('directives', ...relativePath.split('/')), frontmatter };
 }
 /**
- * Load and validate every Directives file in isolation (task-004-decoupled-pillars — see
- * `src/directives/schema.ts` for why this pillar has no dedicated approved tech-spec yet). Reads
+ * The working-tree directive inventory, warnings included: the form a caller with a channel of its
+ * own reads. `directives list` puts the warnings in its payload (`dl-042`), so they reach `--format
+ * json` readers and MCP clients; `directive remove` puts them in its refusal's `details`. `src/core`
+ * never prints them itself (task-143 review: a stray stderr line breaks spec-005 §3.2's one-object
+ * error under `--format json`).
+ *
+ * A `.md` file that cannot be **read** is skipped like any other unreadable entry: its bytes never
+ * reach the parser. A file that is read and then fails to parse or validate stays fatal — that is a
+ * broken directive, not a broken entry, and silently dropping a rule an agent must obey is worse than
+ * refusing the read. So is a `.wingfoil/directives` that cannot be listed: it is the pillar, and is
+ * refused as `E_DIRECTIVES_UNREADABLE`, naming it root-relative.
+ */
+function loadDirectiveInventory(root) {
+    const directivesDir = (0, path_1.join)(root, '.wingfoil', 'directives');
+    const { entries, rootError } = listMarkdownFilesSorted(directivesDir);
+    if (rootError !== undefined) {
+        throw new validation_1.ValidationError([
+            { code: 'E_DIRECTIVES_UNREADABLE', path: '', file: '.wingfoil/directives', message: rootError },
+        ]);
+    }
+    const files = [];
+    const warnings = [];
+    const skip = (relative, reason) => {
+        const shown = relative === '' ? '.wingfoil/directives' : `.wingfoil/directives/${relative}`;
+        warnings.push(`directive entry '${shown}' skipped: ${reason}`);
+    };
+    for (const entry of entries) {
+        if (entry.kind === 'skipped') {
+            skip(entry.relative, entry.reason);
+            continue;
+        }
+        const absolute = (0, path_1.join)(directivesDir, entry.relative);
+        let raw;
+        try {
+            raw = (0, storage_1.readDocument)(absolute);
+        }
+        catch (error) {
+            skip(entry.relative, cannotBeRead(error));
+            continue;
+        }
+        files.push(parseDirectiveFile(raw, `.wingfoil/directives/${entry.relative}`, entry.relative, (warning) => warnings.push(`directive '.wingfoil/directives/${entry.relative}': ${warning}`)));
+    }
+    return { files, warnings };
+}
+/**
+ * Load and validate every Directives file in isolation (task-004-decoupled-pillars), against
+ * `spec-013-directive-frontmatter-schema`'s `DirectiveFrontmatter` (`src/directives/schema.ts`). Reads
  * every `.md` file under `.wingfoil/directives/**` (built-in + custom) **in the working tree**,
  * sorted deterministically (REQ-SYS-07: no unordered iteration in a context-building path), extracts
  * its frontmatter (`storage.extractFrontmatter`), and validates it against `DirectiveFrontmatter`.
  *
- * This is the *report* baseline — what the user has now — and it is what `directives list`, context
- * assembly and the MCP Resources read. A read that **gates** a mutation reads
- * {@link loadDirectivesAtHead} instead (`dl-080` (B)).
+ * This is the *report* baseline — what the user has now — and it is what context assembly and the
+ * MCP role Prompts read. A read that **gates** a mutation reads {@link loadDirectivesAtHead} instead
+ * (`dl-080` (B)).
+ *
+ * The files only: an entry that cannot be resolved or read is skipped (task-143, `bug-125`) and its
+ * warning dropped, since `src/core` does not print. A caller that can report the warnings reads
+ * {@link loadDirectiveInventory} instead.
  */
 function loadDirectives(root) {
-    const directivesDir = (0, path_1.join)(root, '.wingfoil', 'directives');
-    return listMarkdownFilesSorted(directivesDir).map((relativePath) => parseDirectiveFile((0, storage_1.readDocument)((0, path_1.join)(directivesDir, relativePath)), (0, path_1.join)(directivesDir, relativePath), relativePath));
+    return loadDirectiveInventory(root).files;
 }
 /**
  * Load and validate every Directives file **as the repository has committed it** — the tree at
@@ -301,19 +729,46 @@ function loadDirectives(root) {
  * unknown). `listPathsAtRev` keeps the distinction for callers that do need it.
  */
 function loadDirectivesAtHead(root) {
-    const paths = (0, storage_1.listPathsAtRev)(root, 'HEAD', exports.DIRECTIVES_DIR_PATH) ?? [];
+    return (0, revision_1.atHeadOr)(root, () => loadDirectivesAtRev(root, 'HEAD'), []);
+}
+/**
+ * Load and validate every Directives file **as commit `rev` holds it** (task-137, `spec-012` §2
+ * `stateRef`) — the general form of {@link loadDirectivesAtHead}, which is this at `'HEAD'`: the
+ * `.md` files `storage.listPathsAtRev` lists under `.wingfoil/directives/` at that commit, in its
+ * sorted order, all read in one batch with `storage.readPathsAtRev` at the resolved sha (task-283). An empty array when the commit holds no
+ * directive file; a later commit and the working tree are never read.
+ *
+ * @param rev - A revision naming one commit, resolved once (`resolveRevision`, `./revision.ts`).
+ * @throws `RevisionError` when `rev` is malformed or names no commit — never an empty array.
+ */
+function loadDirectivesAtRev(root, rev) {
+    return directivesAt(root, (0, revision_1.resolveRevision)(root, rev), rev);
+}
+/**
+ * {@link loadDirectivesAtRev} for a `sha` already resolved to a commit, read without resolving it again
+ * (task-283, `bug-309`: `workflow next`, `status` and `show` read the directives at their snapshot's commit).
+ *
+ * @param sha - The full sha of a commit, as `resolveRevision` returned it; parse errors name it.
+ */
+function loadDirectivesAtCommit(root, sha) {
+    return directivesAt(root, sha, sha);
+}
+function directivesAt(root, sha, label) {
+    const paths = (0, revision_1.listPathsAtCommit)(root, sha, exports.DIRECTIVES_DIR_PATH).filter((path) => path.endsWith('.md'));
+    // One batched read (`readPathsAtRev`, one `git cat-file --batch`) for every directive, not one `git show`
+    // each (task-283, `bug-309`: 13 spawns per `workflow next` on this repository). `task-096`'s suite pins
+    // this read by name, through the `../storage` barrel.
+    const raws = (0, storage_1.readPathsAtRev)(root, sha, paths);
     const files = [];
-    for (const path of paths) {
-        if (!path.endsWith('.md'))
-            continue;
-        const raw = (0, storage_1.readPathAtRev)(root, 'HEAD', path);
-        // Unreachable by construction — git has just listed this blob. Reachable only if the ref moved
-        // between the two calls, and skipping is the fail-closed answer there: a directive nobody can read
-        // is a directive that does not exist, so a binding to it is refused rather than committed.
+    paths.forEach((path, index) => {
+        const raw = raws[index];
+        // Unreachable by construction — git has just listed this blob at the same sha. Skipping is still
+        // the fail-closed answer: a directive nobody can read is a directive that does not exist, so a
+        // binding to it is refused rather than committed.
         if (raw === null)
-            continue;
-        files.push(parseDirectiveFile(raw, `HEAD:${path}`, path.slice(exports.DIRECTIVES_DIR_PATH.length + 1)));
-    }
+            return;
+        files.push(parseDirectiveFile(raw, `${label}:${path}`, path.slice(exports.DIRECTIVES_DIR_PATH.length + 1)));
+    });
     return files;
 }
 /**
@@ -328,15 +783,16 @@ exports.ROLES_YAML_PATH = '.wingfoil/roles.yaml';
  * Load and validate `.wingfoil/roles.yaml` in isolation (task-037-role-task-scoped-context,
  * REQ-STATE-05's `directive-loader`, P3.2/P3.7 role → directive bindings) — the same shared two-pass
  * pipeline (`readDocument` + `parseYaml` + `runValidation`) every other pillar loader uses, so this
- * pillar's own validation never depends on another pillar's schema (REQ-SYS-02). Consumed by
- * `resolveRoleDirectives`/`assembleExecutionContext` (`./context.ts`) to resolve a role's assigned
- * directives.
+ * pillar's own validation never depends on another pillar's schema (REQ-SYS-02). The working-tree
+ * reader: `directives list` and the MCP role Prompts resolve a role's directives from it, while the
+ * execution context (`assembleExecutionContext`, `./context.ts`) reads {@link loadRolesYamlAtRev} at its
+ * `stateRef`.
  */
 function loadRolesYaml(root) {
-    const filePath = (0, path_1.join)(root, '.wingfoil', 'roles.yaml');
-    const raw = (0, storage_1.readDocument)(filePath);
-    const data = (0, validation_1.parseYaml)(raw, filePath);
-    return (0, validation_1.runValidation)(schema_1.RolesYaml, data, filePath);
+    const raw = readConfigFile(root, exports.ROLES_YAML_PATH);
+    const data = (0, validation_1.parseYaml)(raw, exports.ROLES_YAML_PATH);
+    (0, format_1.refuseNewerFormat)(data, format_1.ROLES_YAML_FORMAT, exports.ROLES_YAML_PATH);
+    return (0, validation_1.runValidation)(schema_1.RolesYaml, data, exports.ROLES_YAML_PATH);
 }
 /**
  * Load and validate `.wingfoil/roles.yaml` **as the repository has committed it** — the version at
@@ -355,10 +811,35 @@ function loadRolesYaml(root) {
  * committed `roles.yaml` that does not **validate** is the different case, and that one does refuse.
  */
 function loadRolesYamlAtHead(root) {
-    const raw = (0, storage_1.readPathAtRev)(root, 'HEAD', exports.ROLES_YAML_PATH);
+    return (0, revision_1.atHeadOr)(root, () => loadRolesYamlAtRev(root, 'HEAD'), null);
+}
+/**
+ * Load and validate `.wingfoil/roles.yaml` **as commit `rev` holds it** (task-137, `spec-012` §2
+ * `stateRef`) — the general form of {@link loadRolesYamlAtHead}, which is this at `'HEAD'`. `null` when
+ * that commit does not hold the file; a later commit and the working tree are never read.
+ *
+ * @param rev - A revision naming one commit, resolved once (`resolveRevision`, `./revision.ts`).
+ * @throws `RevisionError` when `rev` is malformed or names no commit — never an empty answer.
+ */
+function loadRolesYamlAtRev(root, rev) {
+    return rolesYamlAt(root, (0, revision_1.resolveRevision)(root, rev), rev);
+}
+/**
+ * {@link loadRolesYamlAtRev} for a `sha` already resolved to a commit, read without resolving it again
+ * (task-283, `bug-309`).
+ *
+ * @param sha - The full sha of a commit, as `resolveRevision` returned it; parse errors name it.
+ */
+function loadRolesYamlAtCommit(root, sha) {
+    return rolesYamlAt(root, sha, sha);
+}
+function rolesYamlAt(root, sha, rev) {
+    const raw = (0, storage_1.readPathAtRev)(root, sha, exports.ROLES_YAML_PATH);
     if (raw === null)
         return null;
-    const label = `HEAD:${exports.ROLES_YAML_PATH}`;
-    return (0, validation_1.runValidation)(schema_1.RolesYaml, (0, validation_1.parseYaml)(raw, label), label);
+    const label = `${rev}:${exports.ROLES_YAML_PATH}`;
+    const data = (0, validation_1.parseYaml)(raw, label);
+    (0, format_1.refuseNewerFormat)(data, format_1.ROLES_YAML_FORMAT, label);
+    return (0, validation_1.runValidation)(schema_1.RolesYaml, data, label);
 }
 //# sourceMappingURL=loaders.js.map