pactwright 0.0.1

package/dist/lifecycle/run.js

@@ -0,0 +1,167 @@
+import { PactwrightError } from "../errors.js";
+import { deriveLineage } from "../graph/lineage.js";
+import { loadProject } from "../loader.js";
+import { isActive, isTransientStage, nextActionFor, selectLineages } from "./engine.js";
+/**
+ * The runtime has no way to perform automatic stages until an agent pack is
+ * installed (Checkpoint 1, Step 10): every automatic stage fails, so `run`
+ * stops there instead of pretending.
+ */
+export const noExecutor = ({ stage }) => ({
+    status: "failed",
+    message: `no executor for automatic stage "${stage}"; agent-pack execution arrives with the default agent pack`,
+});
+function load(root) {
+    try {
+        return loadProject({ root });
+    }
+    catch (error) {
+        if (error instanceof PactwrightError)
+            return error;
+        throw error;
+    }
+}
+function validationStop(intent, error, executed) {
+    return {
+        ...(intent === undefined ? {} : { intent }),
+        stop: "validation-error",
+        executed,
+        message: error.message,
+        problems: error.problems,
+    };
+}
+/** Runs one lineage (or the capture-intent entry point) until it stops. */
+async function runLineage(options, intent, first) {
+    const executed = [];
+    const done = new Set();
+    let project = first;
+    let previousState;
+    const tag = intent === undefined ? {} : { intent };
+    for (;;) {
+        let lineage;
+        if (intent !== undefined) {
+            lineage = deriveLineage(intent, project.graph.nodes, project.graph.edges);
+            if (lineage === undefined) {
+                // The loader validated the graph, so only a vanished intent gets here.
+                return {
+                    ...tag,
+                    stop: "validation-error",
+                    executed,
+                    message: `intent "${intent}" has no unambiguous lineage`,
+                };
+            }
+            if (lineage.state !== previousState)
+                done.clear();
+            previousState = lineage.state;
+        }
+        const next = nextActionFor(project, lineage, done);
+        if (next.stage === undefined)
+            return { ...tag, stop: "completed", executed };
+        if (next.gate) {
+            return { ...tag, stop: "human-gate", stage: next.stage, requiredActor: "human", executed };
+        }
+        let outcome;
+        try {
+            outcome = await options.execute({
+                stage: next.stage,
+                project,
+                ...(lineage ? { lineage } : {}),
+            });
+        }
+        catch (error) {
+            outcome = {
+                status: "failed",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        if (outcome.status === "failed") {
+            return {
+                ...tag,
+                stop: "stage-failed",
+                stage: next.stage,
+                executed,
+                message: outcome.message,
+            };
+        }
+        executed.push(next.stage);
+        // Repository state is re-read after every stage: a validation error stops the run.
+        const reloaded = load(options.root);
+        if (reloaded instanceof PactwrightError)
+            return validationStop(intent, reloaded, executed);
+        project = reloaded;
+        if (isTransientStage(next.stage)) {
+            done.add(next.stage);
+            continue;
+        }
+        // A graph-marking stage must have advanced the lineage, else the run would loop forever.
+        const advanced = intent === undefined
+            ? selectLineages(project).some((candidate) => candidate !== undefined && isActive(candidate))
+            : deriveLineage(intent, project.graph.nodes, project.graph.edges)?.state !== previousState;
+        if (!advanced) {
+            return {
+                ...tag,
+                stop: "stage-failed",
+                stage: next.stage,
+                executed,
+                message: `${next.stage} completed without advancing the graph`,
+            };
+        }
+        if (intent === undefined) {
+            // capture-intent created the first active lineage(s); the caller picks them up.
+            return { ...tag, stop: "completed", executed };
+        }
+    }
+}
+/**
+ * `lifecycle run` (Delivery Graph §20): runs automatic stages of every
+ * active lineage (or the one `intentId`) until a human gate, completion, a
+ * stage failure or a validation error. Gates are checked by the runtime on
+ * every step, so a configured gate is never skipped whatever the executor
+ * could do. Never throws for expected failures.
+ */
+export async function runLifecycle(options) {
+    const project = load(options.root);
+    if (project instanceof PactwrightError)
+        return [validationStop(options.intentId, project, [])];
+    let targets;
+    try {
+        targets = selectLineages(project, options.intentId);
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        return [validationStop(options.intentId, error, [])];
+    }
+    const results = [];
+    let current = project;
+    for (const target of targets) {
+        const result = await runLineage(options, target?.intent.id, current);
+        results.push(result);
+        if (target === undefined && result.stop === "completed" && result.executed.length > 0) {
+            // capture-intent ran: continue with the lineages it created, reloading
+            // before each one so lineage N+1 starts from the graph lineage N wrote.
+            const reloaded = load(options.root);
+            if (reloaded instanceof PactwrightError) {
+                results.push(validationStop(undefined, reloaded, []));
+                break;
+            }
+            const createdIds = selectLineages(reloaded)
+                .filter((created) => created !== undefined && isActive(created))
+                .map((created) => created.intent.id);
+            for (const created of createdIds) {
+                const fresh = load(options.root);
+                if (fresh instanceof PactwrightError) {
+                    results.push(validationStop(created, fresh, []));
+                    break;
+                }
+                results.push(await runLineage(options, created, fresh));
+            }
+            break;
+        }
+        const reloaded = load(options.root);
+        if (reloaded instanceof PactwrightError)
+            break;
+        current = reloaded;
+    }
+    return results;
+}

package/dist/loader.d.ts

@@ -0,0 +1,38 @@
+import { type PactwrightConfig } from "./config/config.js";
+import { type LifecycleConfig } from "./config/lifecycle.js";
+import { type LockFile } from "./config/lock.js";
+import { type ResolvedExtension } from "./extension/resolve.js";
+import { type Edge } from "./graph/edges.js";
+import { type GraphNode } from "./graph/nodes.js";
+import { type ProjectPaths } from "./project.js";
+/** Fully loaded canonical project state. */
+export interface Project {
+    readonly paths: ProjectPaths;
+    readonly config: PactwrightConfig;
+    readonly lifecycle: LifecycleConfig;
+    readonly lock: LockFile;
+    /** Every configured extension, resolved; empty when none are configured. */
+    readonly extensions: readonly ResolvedExtension[];
+    readonly graph: {
+        readonly nodes: readonly GraphNode[];
+        readonly edges: readonly Edge[];
+    };
+}
+export interface LoadProjectOptions {
+    /** Directory to start searching for the project root from. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    /** Use this root directly instead of searching upward from `cwd`. */
+    readonly root?: string;
+}
+/**
+ * The single canonical loading path for a Pactwright project.
+ *
+ * Reads, in order: config → lifecycle → lock → configured extensions (whose
+ * registered graph types extend the schema registries) → nodes (then node
+ * schemas) → edges (then the typed-edge registry) → current-lineage
+ * derivation. Every file is parsed even after an earlier one fails so the
+ * caller sees all problems at once; if any problem was found a
+ * `PactwrightError` with code `project-load-failed` is thrown carrying the
+ * full list.
+ */
+export declare function loadProject(options?: LoadProjectOptions): Project;

package/dist/loader.js

@@ -0,0 +1,64 @@
+import { PactwrightError } from "./errors.js";
+import { loadConfig } from "./config/config.js";
+import { loadLifecycle } from "./config/lifecycle.js";
+import { loadLock } from "./config/lock.js";
+import { composedRegistries, resolveExtensions, } from "./extension/resolve.js";
+import { CORE_EDGE_SCHEMAS, validateEdges } from "./graph/edge-schema.js";
+import { loadEdges } from "./graph/edges.js";
+import { validateLineages } from "./graph/lineage.js";
+import { loadNodes } from "./graph/nodes.js";
+import { CORE_NODE_SCHEMAS, validateNodes } from "./graph/schema.js";
+import { findProjectRoot, projectPaths } from "./project.js";
+/**
+ * The single canonical loading path for a Pactwright project.
+ *
+ * Reads, in order: config → lifecycle → lock → configured extensions (whose
+ * registered graph types extend the schema registries) → nodes (then node
+ * schemas) → edges (then the typed-edge registry) → current-lineage
+ * derivation. Every file is parsed even after an earlier one fails so the
+ * caller sees all problems at once; if any problem was found a
+ * `PactwrightError` with code `project-load-failed` is thrown carrying the
+ * full list.
+ */
+export function loadProject(options = {}) {
+    const root = options.root ?? findProjectRoot(options.cwd);
+    const paths = projectPaths(root);
+    const problems = [];
+    const config = loadConfig(paths.config);
+    problems.push(...config.problems);
+    const lifecycle = loadLifecycle(paths.lifecycle);
+    problems.push(...lifecycle.problems);
+    const lock = loadLock(paths.lock);
+    problems.push(...lock.problems);
+    let extensions = [];
+    let nodeRegistry = CORE_NODE_SCHEMAS;
+    let edgeRegistry = CORE_EDGE_SCHEMAS;
+    if (config.value !== undefined && Object.keys(config.value.extensions).length > 0) {
+        const resolved = resolveExtensions({ root: paths.root, config: config.value });
+        if (resolved.value === undefined) {
+            problems.push(...resolved.problems);
+        }
+        else {
+            extensions = resolved.value;
+            ({ nodes: nodeRegistry, edges: edgeRegistry } = composedRegistries(extensions));
+        }
+    }
+    const nodes = loadNodes(paths.nodesDir);
+    problems.push(...nodes.problems);
+    problems.push(...validateNodes(nodes.nodes, nodeRegistry));
+    const edges = loadEdges(paths.edges);
+    problems.push(...edges.problems);
+    problems.push(...validateEdges(edges.edges, nodes.nodes, edgeRegistry, paths.edges));
+    problems.push(...validateLineages(nodes.nodes, edges.edges));
+    if (problems.length > 0 || !config.value || !lifecycle.value || !lock.value) {
+        throw PactwrightError.fromProblems("project-load-failed", problems);
+    }
+    return {
+        paths,
+        config: config.value,
+        lifecycle: lifecycle.value,
+        lock: lock.value,
+        extensions,
+        graph: { nodes: nodes.nodes, edges: edges.edges },
+    };
+}

package/dist/pack/capabilities.d.ts

@@ -0,0 +1,22 @@
+import type { PackManifest } from "./manifest.js";
+/**
+ * The capabilities every Delivery project requires of its agent pack
+ * (Distribution §7): the Specification, Delivery and Review
+ * responsibilities of Delivery Graph §16. Graph mutation is a runtime
+ * responsibility, never a pack capability.
+ */
+export declare const CORE_CAPABILITIES: readonly ["delivery-specification", "delivery-execution", "delivery-review"];
+export type CoreCapability = (typeof CORE_CAPABILITIES)[number];
+/** Capability names are kebab-case identifiers, like `operations-analysis`. */
+export declare const CAPABILITY_PATTERN: RegExp;
+/**
+ * The capability set the selected pack must satisfy: the core set plus the
+ * `agent_capabilities` of every enabled extension (Distribution §5, §7).
+ * Callers pass the manifests of the enabled extensions, so only capabilities
+ * an enabled extension asks for are mandatory.
+ */
+export declare function requiredCapabilities(extensions?: ReadonlyArray<{
+    readonly agentCapabilities: readonly string[];
+}>): readonly string[];
+/** Required capabilities the manifest does not map to an agent, sorted. */
+export declare function missingCapabilities(manifest: PackManifest, required: readonly string[]): readonly string[];

package/dist/pack/capabilities.js

@@ -0,0 +1,31 @@
+/**
+ * The capabilities every Delivery project requires of its agent pack
+ * (Distribution §7): the Specification, Delivery and Review
+ * responsibilities of Delivery Graph §16. Graph mutation is a runtime
+ * responsibility, never a pack capability.
+ */
+export const CORE_CAPABILITIES = [
+    "delivery-specification",
+    "delivery-execution",
+    "delivery-review",
+];
+/** Capability names are kebab-case identifiers, like `operations-analysis`. */
+export const CAPABILITY_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/**
+ * The capability set the selected pack must satisfy: the core set plus the
+ * `agent_capabilities` of every enabled extension (Distribution §5, §7).
+ * Callers pass the manifests of the enabled extensions, so only capabilities
+ * an enabled extension asks for are mandatory.
+ */
+export function requiredCapabilities(extensions = []) {
+    const union = new Set(CORE_CAPABILITIES);
+    for (const manifest of extensions) {
+        for (const capability of manifest.agentCapabilities)
+            union.add(capability);
+    }
+    return [...union].sort();
+}
+/** Required capabilities the manifest does not map to an agent, sorted. */
+export function missingCapabilities(manifest, required) {
+    return required.filter((capability) => manifest.capabilities[capability] === undefined).sort();
+}

package/dist/pack/locate.d.ts

@@ -0,0 +1,22 @@
+import type { Problem } from "../errors.js";
+export declare function sha256(text: string): string;
+/** Whether `range` is a shape `satisfiesRange` understands: `x.y.z` or `^x.y.z`. */
+export declare function isValidRange(range: string): boolean;
+/**
+ * Whether `version` satisfies `range`: an exact version, or a `^x.y.z`
+ * caret range with npm semantics (`^0.0.z` is exact, `^0.y.z` fixes the
+ * minor, `^x.y.z` fixes the major). During the `0.0.x` series packs declare
+ * the exact runtime version, so caret only matters from `0.1.0` onward.
+ */
+export declare function satisfiesRange(version: string, range: string): boolean;
+/** Whether `source` is a filesystem path rather than a package name. */
+export declare function isPathSource(source: string): boolean;
+/**
+ * Where a package-backed component (agent pack or extension) lives. A path
+ * source resolves from the project root. A package source resolves like a
+ * dependency of the project first (`<root>/node_modules`), then like a
+ * dependency of the runtime — which is how `@pactwright/standard`, a
+ * dependency of `pactwright`, is always found after one
+ * `pnpm add -D pactwright`. `kind` names the component in problem messages.
+ */
+export declare function locatePackage(root: string, source: string, kind: string): string | Problem;

package/dist/pack/locate.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+export function sha256(text) {
+    return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+function parseVersion(text) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(text);
+    if (match === null)
+        return undefined;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** Whether `range` is a shape `satisfiesRange` understands: `x.y.z` or `^x.y.z`. */
+export function isValidRange(range) {
+    return parseVersion(range.startsWith("^") ? range.slice(1) : range) !== undefined;
+}
+/**
+ * Whether `version` satisfies `range`: an exact version, or a `^x.y.z`
+ * caret range with npm semantics (`^0.0.z` is exact, `^0.y.z` fixes the
+ * minor, `^x.y.z` fixes the major). During the `0.0.x` series packs declare
+ * the exact runtime version, so caret only matters from `0.1.0` onward.
+ */
+export function satisfiesRange(version, range) {
+    const caret = range.startsWith("^");
+    const want = parseVersion(caret ? range.slice(1) : range);
+    const have = parseVersion(version);
+    if (want === undefined || have === undefined)
+        return false;
+    if (!caret)
+        return have.every((part, i) => part === want[i]);
+    const cmp = (i) => have[i] - want[i];
+    const notBelow = cmp(0) !== 0 ? cmp(0) > 0 : cmp(1) !== 0 ? cmp(1) > 0 : cmp(2) >= 0;
+    if (!notBelow)
+        return false;
+    if (want[0] !== 0)
+        return have[0] === want[0];
+    if (want[1] !== 0)
+        return have[0] === 0 && have[1] === want[1];
+    return have[0] === 0 && have[1] === 0 && have[2] === want[2];
+}
+/** Whether `source` is a filesystem path rather than a package name. */
+export function isPathSource(source) {
+    return source.startsWith("./") || source.startsWith("../") || isAbsolute(source);
+}
+/**
+ * Where a package-backed component (agent pack or extension) lives. A path
+ * source resolves from the project root. A package source resolves like a
+ * dependency of the project first (`<root>/node_modules`), then like a
+ * dependency of the runtime — which is how `@pactwright/standard`, a
+ * dependency of `pactwright`, is always found after one
+ * `pnpm add -D pactwright`. `kind` names the component in problem messages.
+ */
+export function locatePackage(root, source, kind) {
+    if (isPathSource(source))
+        return resolve(root, source);
+    const candidates = [join(root, "package.json"), import.meta.url];
+    let unexported = false;
+    for (const from of candidates) {
+        try {
+            return dirname(createRequire(from).resolve(`${source}/package.json`));
+        }
+        catch (error) {
+            // An installed package whose `exports` map hides package.json is a
+            // different failure from an absent one; try the next location.
+            const code = error.code;
+            if (code === "ERR_PACKAGE_PATH_NOT_EXPORTED")
+                unexported = true;
+        }
+    }
+    if (unexported) {
+        return {
+            code: "pack-not-exported",
+            message: `${kind} "${source}" is installed but its package "exports" does not expose ./package.json, so it cannot be used as a ${kind}`,
+        };
+    }
+    return {
+        code: "pack-not-found",
+        message: `${kind} "${source}" is not installed: it resolves neither from ${root} nor from the runtime`,
+    };
+}

package/dist/pack/manifest.d.ts

@@ -0,0 +1,34 @@
+import type { ParseResult } from "../config/config.js";
+/** File name of an agent-pack manifest at the pack root. */
+export declare const PACK_MANIFEST_FILE = "pack.yml";
+/** Skills are looked up by name at `skills/<name>.md` under the pack root. */
+export declare const SKILLS_DIR = "skills";
+export interface PackAgent {
+    /** Prompt path relative to the pack root, e.g. `agents/spec.md`. */
+    readonly prompt: string;
+    /** Skill names, in manifest order, each resolving to `skills/<name>.md`. */
+    readonly skills: readonly string[];
+}
+/** An agent-pack manifest (Distribution §7). */
+export interface PackManifest {
+    readonly name: string;
+    readonly version: string;
+    /** Compatible runtime: an exact version or a `^x.y.z` caret range. */
+    readonly pactwright: string;
+    /** Capability → agent key; every value names an entry of `agents`. */
+    readonly capabilities: Readonly<Record<string, string>>;
+    readonly agents: Readonly<Record<string, PackAgent>>;
+}
+export declare const VERSION_PATTERN: RegExp;
+export declare const COMPAT_PATTERN: RegExp;
+export declare const PACKAGE_NAME_PATTERN: RegExp;
+/** Parses manifest data; structural checks only, no filesystem access. */
+export declare function parsePackManifest(raw: unknown, path: string): ParseResult<PackManifest>;
+export declare function skillPath(dir: string, skill: string): string;
+/**
+ * Loads and validates the manifest at `<dir>/pack.yml`, then checks that
+ * every agent prompt and every referenced skill exists as a non-empty file.
+ */
+export declare function loadPackManifest(dir: string): ParseResult<PackManifest>;
+/** Reads a pack file with LF line endings, the bytes that are hashed. */
+export declare function readPackFile(dir: string, relative: string): string;

package/dist/pack/manifest.js

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, normalize, sep } from "node:path";
+import { Checker, expectRecord, expectString, rejectUnknownKeys, requireKeys, } from "../validation.js";
+import { readYamlFile } from "../yaml.js";
+import { CAPABILITY_PATTERN } from "./capabilities.js";
+/** File name of an agent-pack manifest at the pack root. */
+export const PACK_MANIFEST_FILE = "pack.yml";
+/** Skills are looked up by name at `skills/<name>.md` under the pack root. */
+export const SKILLS_DIR = "skills";
+export const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+export const COMPAT_PATTERN = /^\^?\d+\.\d+\.\d+$/;
+const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+// npm package name, optionally scoped; capped at npm's 214-character limit.
+export const PACKAGE_NAME_PATTERN = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const PACK_NAME_PATTERN = PACKAGE_NAME_PATTERN;
+function expectRelativeFile(c, value, label) {
+    const text = expectString(c, value, label);
+    if (text === undefined)
+        return undefined;
+    const clean = normalize(text);
+    // Reject a leading `..` path *segment*, not any name starting with two
+    // dots: `agents/..foo.md` is a legitimate (if odd) file name.
+    if (isAbsolute(clean) || clean === ".." || clean.startsWith(`..${sep}`)) {
+        return c.fail("invalid-path", `${label} must be a relative path inside the pack`);
+    }
+    return text;
+}
+function parseAgent(c, raw, label) {
+    const record = expectRecord(c, raw, label);
+    if (record === undefined)
+        return c.fail("invalid-type", `${label} must be a mapping`);
+    requireKeys(c, record, label, ["prompt"]);
+    rejectUnknownKeys(c, record, label, ["prompt", "skills"]);
+    const prompt = expectRelativeFile(c, record["prompt"], `${label}.prompt`);
+    const skills = [];
+    if (record["skills"] !== undefined) {
+        if (!Array.isArray(record["skills"])) {
+            c.fail("invalid-type", `${label}.skills must be a list of skill names`);
+        }
+        else {
+            record["skills"].forEach((item, index) => {
+                const name = expectString(c, item, `${label}.skills[${index}]`);
+                if (name === undefined)
+                    return;
+                if (!NAME_PATTERN.test(name)) {
+                    c.fail("invalid-value", `${label}.skills[${index}] "${name}" is not a valid skill name`);
+                }
+                else if (skills.includes(name)) {
+                    c.fail("duplicate-skill", `${label}.skills lists "${name}" more than once`);
+                }
+                else
+                    skills.push(name);
+            });
+        }
+    }
+    return prompt === undefined ? undefined : { prompt, skills };
+}
+/** Parses manifest data; structural checks only, no filesystem access. */
+export function parsePackManifest(raw, path) {
+    const c = new Checker(path);
+    const root = expectRecord(c, raw, "pack");
+    if (root === undefined) {
+        c.fail("invalid-type", "pack manifest must be a mapping");
+        return { value: undefined, problems: c.problems };
+    }
+    requireKeys(c, root, "pack", ["name", "version", "pactwright", "capabilities", "agents"]);
+    rejectUnknownKeys(c, root, "pack", ["name", "version", "pactwright", "capabilities", "agents"]);
+    const name = expectString(c, root["name"], "pack.name");
+    if (name !== undefined && (name.length > 214 || !PACK_NAME_PATTERN.test(name))) {
+        c.fail("invalid-value", `pack.name must be a lowercase npm package name (optionally scoped), found "${name}"`);
+    }
+    const version = expectString(c, root["version"], "pack.version");
+    if (version !== undefined && !VERSION_PATTERN.test(version)) {
+        c.fail("invalid-value", `pack.version must be x.y.z, found "${version}"`);
+    }
+    const pactwright = expectString(c, root["pactwright"], "pack.pactwright");
+    if (pactwright !== undefined && !COMPAT_PATTERN.test(pactwright)) {
+        c.fail("invalid-value", `pack.pactwright must be x.y.z or ^x.y.z, found "${pactwright}"`);
+    }
+    // Prototype-less maps: keys are author-controlled, and a name like
+    // "constructor" must never resolve to an Object.prototype member.
+    const agents = Object.create(null);
+    const agentsRaw = expectRecord(c, root["agents"], "pack.agents");
+    if (agentsRaw !== undefined) {
+        for (const key of Object.keys(agentsRaw).sort()) {
+            if (!NAME_PATTERN.test(key)) {
+                c.fail("invalid-value", `pack.agents key "${key}" is not a valid agent name`);
+                continue;
+            }
+            const agent = parseAgent(c, agentsRaw[key], `pack.agents.${key}`);
+            if (agent !== undefined)
+                agents[key] = agent;
+        }
+        if (Object.keys(agentsRaw).length === 0) {
+            c.fail("missing-field", "pack.agents must declare at least one agent");
+        }
+    }
+    const capabilities = Object.create(null);
+    const capsRaw = expectRecord(c, root["capabilities"], "pack.capabilities");
+    if (capsRaw !== undefined) {
+        for (const capability of Object.keys(capsRaw).sort()) {
+            if (!CAPABILITY_PATTERN.test(capability)) {
+                c.fail("invalid-capability", `pack.capabilities "${capability}" is not a capability name`);
+                continue;
+            }
+            const agent = expectString(c, capsRaw[capability], `pack.capabilities.${capability}`);
+            if (agent === undefined)
+                continue;
+            if (agentsRaw !== undefined && !Object.hasOwn(agentsRaw, agent)) {
+                c.fail("unknown-agent", `pack.capabilities.${capability} names agent "${agent}", which pack.agents does not declare`);
+                continue;
+            }
+            capabilities[capability] = agent;
+        }
+    }
+    if (!c.ok || name === undefined || version === undefined || pactwright === undefined) {
+        return { value: undefined, problems: c.problems };
+    }
+    return { value: { name, version, pactwright, capabilities, agents }, problems: [] };
+}
+export function skillPath(dir, skill) {
+    return join(dir, SKILLS_DIR, `${skill}.md`);
+}
+function isNonEmptyFile(path) {
+    try {
+        return statSync(path).isFile() && statSync(path).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Loads and validates the manifest at `<dir>/pack.yml`, then checks that
+ * every agent prompt and every referenced skill exists as a non-empty file.
+ */
+export function loadPackManifest(dir) {
+    const manifestPath = join(dir, PACK_MANIFEST_FILE);
+    if (!existsSync(manifestPath)) {
+        return {
+            value: undefined,
+            problems: [
+                { code: "pack-not-found", message: `no ${PACK_MANIFEST_FILE} found`, path: manifestPath },
+            ],
+        };
+    }
+    const read = readYamlFile(manifestPath);
+    if (read.problems.length > 0)
+        return { value: undefined, problems: read.problems };
+    const parsed = parsePackManifest(read.value, manifestPath);
+    if (parsed.value === undefined)
+        return parsed;
+    const c = new Checker(manifestPath);
+    for (const [key, agent] of Object.entries(parsed.value.agents)) {
+        if (!isNonEmptyFile(join(dir, agent.prompt))) {
+            c.fail("missing-prompt", `pack.agents.${key}.prompt "${agent.prompt}" is not a non-empty file in the pack`);
+        }
+        for (const skill of agent.skills) {
+            if (!isNonEmptyFile(skillPath(dir, skill))) {
+                c.fail("missing-skill", `pack.agents.${key} uses skill "${skill}" but ${SKILLS_DIR}/${skill}.md is not a non-empty file in the pack`);
+            }
+        }
+    }
+    return c.ok ? parsed : { value: undefined, problems: c.problems };
+}
+/** Reads a pack file with LF line endings, the bytes that are hashed. */
+export function readPackFile(dir, relative) {
+    return readFileSync(join(dir, relative), "utf8").replace(/\r\n/g, "\n");
+}