@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/workflow/lane-template.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Fan-out lane templating for the evolve workflow's per-lane working areas.
+ *
+ * Under N-way fan-out (`docs/designs/evolve-sync-parallelism-slice.md` §7), the
+ * shared `current/` scratch directory collides across lanes, so each lane runs
+ * in its own `current/lane_<k>/` sub-path. This module rewrites the three
+ * surfaces that hardcode `current/`: agent prompts (via `{laneDir}`/`{laneId}`
+ * placeholders, §7.3), deterministic argv paths (via current-prefix rewriting,
+ * §7.1), and the per-lane `--lane <k>` flag the bridge reads (§7.1/§8.4).
+ *
+ * ESCAPING INVARIANT (read before adding a new caller). Every substitution here
+ * is a LITERAL text replacement, and the substituted values are
+ * orchestrator-controlled trusted lane identities: `lane.id` is a non-negative
+ * integer the orchestrator assigns (`buildFanOutLaneContext`), and `lane.dir` /
+ * `lane.relativeDir` are orchestrator-computed `…/current/lane_<id>` paths — none
+ * of them ever carry agent- or user-authored text. The rendered result is
+ * concatenated into a prompt (free text) or an argv array, so NO shell, markdown,
+ * or argv escaping is performed here. That is sound ONLY because of this
+ * invariant. A future caller MUST NOT template untrusted data (agent output, user
+ * input, file contents) through these helpers — doing so would inject unescaped
+ * text into a prompt/argv. If you need to interpolate untrusted data, escape it
+ * at the call site first; do not relax this module to do it for you.
+ */
+import type { WorkflowContext, FanOutDefinition, WorkflowSettings } from './types.js';
+/**
+ * Resolves the effective lane count for a fan-out state, exactly as the runtime
+ * does at `orchestrator.ts` (`runFanOutSegment`): `count: 'workers'` defers to
+ * `settings.workers` (default 1), while a numeric `count` is a per-state override
+ * independent of the global worker count.
+ *
+ * Single source of truth so the validator and linter gate their multi-lane
+ * safety checks on the SAME lane count the runtime will spin up — a numeric
+ * `count` override must not be able to bypass those checks just because
+ * `settings.workers` is 1. Keep in lockstep with the orchestrator's resolution.
+ */
+export declare function resolveFanOutWorkers(fanOut: FanOutDefinition, settings?: WorkflowSettings): number;
+export declare const DEFAULT_EVOLVE_LANE_DIR = "/workspace/.evolve_runs/main/current";
+/**
+ * Zero-pad width of the `step_<NNNN>` batch index. Mirrors the Python `:04d`
+ * format in `scripts/evolve_result.py` (`step_{batch_index:04d}_lane_{lane}`).
+ */
+export declare const EVOLVE_STEP_INDEX_WIDTH = 4;
+/**
+ * The single TS spelling of the fan-out step name `step_<NNNN>_lane_<k>` (the
+ * other half of the lane-dir seam above). The Python bridge writes the same
+ * literal at `f"step_{batch_index:04d}_lane_{lane}"`; the orchestrator parses it
+ * back with EVOLVE_LANE_STEP_RE. Keep all three (this fn, the Python f-string,
+ * the regex) in lockstep — they are one cross-language format contract.
+ */
+export declare function evolveStepName(batchIndex: number, lane: number): string;
+export declare const DEFAULT_EVOLVE_LANE_RELATIVE_DIR = ".evolve_runs/main/current";
+/**
+ * The bridge script basename. Exported so the orchestrator matches fan-out
+ * sample commands against the same literal this module uses for `--lane`
+ * injection, instead of re-spelling the find/`endsWith` matcher (see
+ * {@link evolveResultScriptIndex}).
+ */
+export declare const EVOLVE_RESULT_SCRIPT = "evolve_result.py";
+/**
+ * Substitutes the `{laneDir}` / `{laneRelativeDir}` / `{laneRelDir}` /
+ * `{laneId}` / `${laneId}` placeholders in `value` with this lane's trusted
+ * identity (falling back to the bare `current/` dir and lane id `0` when no lane
+ * is active, so `workers: 1` renders the legacy paths). Pure literal replacement
+ * — see the module's ESCAPING INVARIANT.
+ */
+export declare function applyLaneTemplate(value: string, context: WorkflowContext): string;
+/**
+ * Lane-scopes a path: first applies the placeholder templating, then rewrites a
+ * bare `…/current/<rest>` prefix to `…/current/lane_<k>/<rest>` (both the
+ * container-absolute `DEFAULT_EVOLVE_LANE_DIR` and the workspace-relative
+ * `DEFAULT_EVOLVE_LANE_RELATIVE_DIR` forms). Returns `value` unchanged when no
+ * lane is active. See the module's ESCAPING INVARIANT for why the values are
+ * trusted.
+ */
+export declare function laneScopeEvolveCurrentPath(value: string, context: WorkflowContext): string;
+/**
+ * Lane-scopes every path argument in a deterministic `run:` command, then
+ * injects `--lane <id>` after the bridge subcommand for the lane-aware
+ * subcommands ({@link EVOLVE_LANE_AWARE_COMMANDS}). Returns the command
+ * unchanged when no lane is active. See the module's ESCAPING INVARIANT.
+ */
+export declare function templateLaneCommand(command: readonly string[], context: WorkflowContext): readonly string[];
+/**
+ * Finds the index of the {@link EVOLVE_RESULT_SCRIPT} bridge entry in a command
+ * argv (matching either the bare basename or any `…/evolve_result.py` path), or
+ * `-1` if absent. The single source of truth for locating the bridge so the
+ * orchestrator and the `--lane` injector agree on what counts as the script.
+ */
+export declare function evolveResultScriptIndex(command: readonly string[]): number;

package/dist/workflow/lane-template.js

@@ -0,0 +1,141 @@
+/**
+ * Resolves the effective lane count for a fan-out state, exactly as the runtime
+ * does at `orchestrator.ts` (`runFanOutSegment`): `count: 'workers'` defers to
+ * `settings.workers` (default 1), while a numeric `count` is a per-state override
+ * independent of the global worker count.
+ *
+ * Single source of truth so the validator and linter gate their multi-lane
+ * safety checks on the SAME lane count the runtime will spin up — a numeric
+ * `count` override must not be able to bypass those checks just because
+ * `settings.workers` is 1. Keep in lockstep with the orchestrator's resolution.
+ */
+export function resolveFanOutWorkers(fanOut, settings) {
+    return fanOut.count === 'workers' ? (settings?.workers ?? 1) : fanOut.count;
+}
+// Lane-dir format seam: `current/lane_<k>`. The matching step-name half of this
+// convention lives on the Python side as STEP_NAME_RE in
+// scripts/evolve_result.py (`step_<NNNN>_lane_<k>`) — keep both in sync if the
+// lane/step naming ever changes.
+export const DEFAULT_EVOLVE_LANE_DIR = '/workspace/.evolve_runs/main/current';
+/**
+ * Zero-pad width of the `step_<NNNN>` batch index. Mirrors the Python `:04d`
+ * format in `scripts/evolve_result.py` (`step_{batch_index:04d}_lane_{lane}`).
+ */
+export const EVOLVE_STEP_INDEX_WIDTH = 4;
+/**
+ * The single TS spelling of the fan-out step name `step_<NNNN>_lane_<k>` (the
+ * other half of the lane-dir seam above). The Python bridge writes the same
+ * literal at `f"step_{batch_index:04d}_lane_{lane}"`; the orchestrator parses it
+ * back with EVOLVE_LANE_STEP_RE. Keep all three (this fn, the Python f-string,
+ * the regex) in lockstep — they are one cross-language format contract.
+ */
+export function evolveStepName(batchIndex, lane) {
+    return `step_${String(batchIndex).padStart(EVOLVE_STEP_INDEX_WIDTH, '0')}_lane_${lane}`;
+}
+export const DEFAULT_EVOLVE_LANE_RELATIVE_DIR = '.evolve_runs/main/current';
+/**
+ * The bridge script basename. Exported so the orchestrator matches fan-out
+ * sample commands against the same literal this module uses for `--lane`
+ * injection, instead of re-spelling the find/`endsWith` matcher (see
+ * {@link evolveResultScriptIndex}).
+ */
+export const EVOLVE_RESULT_SCRIPT = 'evolve_result.py';
+const EVOLVE_LANE_AWARE_COMMANDS = new Set(['sample', 'evaluate', 'record', 'attach_analysis']);
+function laneId(context) {
+    return String(context.lane?.id ?? 0);
+}
+function laneDir(context) {
+    return context.lane?.dir ?? DEFAULT_EVOLVE_LANE_DIR;
+}
+function laneRelativeDir(context) {
+    return context.lane?.relativeDir ?? DEFAULT_EVOLVE_LANE_RELATIVE_DIR;
+}
+/**
+ * Substitutes the `{laneDir}` / `{laneRelativeDir}` / `{laneRelDir}` /
+ * `{laneId}` / `${laneId}` placeholders in `value` with this lane's trusted
+ * identity (falling back to the bare `current/` dir and lane id `0` when no lane
+ * is active, so `workers: 1` renders the legacy paths). Pure literal replacement
+ * — see the module's ESCAPING INVARIANT.
+ */
+export function applyLaneTemplate(value, context) {
+    let rendered = value;
+    rendered = rendered.replaceAll('{laneDir}', laneDir(context));
+    rendered = rendered.replaceAll('{laneRelativeDir}', laneRelativeDir(context));
+    rendered = rendered.replaceAll('{laneRelDir}', laneRelativeDir(context));
+    rendered = rendered.replaceAll('${laneId}', laneId(context));
+    rendered = rendered.replaceAll('{laneId}', laneId(context));
+    return rendered;
+}
+/**
+ * Lane-scopes a path: first applies the placeholder templating, then rewrites a
+ * bare `…/current/<rest>` prefix to `…/current/lane_<k>/<rest>` (both the
+ * container-absolute `DEFAULT_EVOLVE_LANE_DIR` and the workspace-relative
+ * `DEFAULT_EVOLVE_LANE_RELATIVE_DIR` forms). Returns `value` unchanged when no
+ * lane is active. See the module's ESCAPING INVARIANT for why the values are
+ * trusted.
+ */
+export function laneScopeEvolveCurrentPath(value, context) {
+    const lane = context.lane;
+    if (!lane)
+        return applyLaneTemplate(value, context);
+    let rendered = applyLaneTemplate(value, context);
+    rendered = replaceCurrentPrefix(rendered, DEFAULT_EVOLVE_LANE_DIR, lane.dir);
+    rendered = replaceCurrentPrefix(rendered, DEFAULT_EVOLVE_LANE_RELATIVE_DIR, lane.relativeDir);
+    return rendered;
+}
+/**
+ * Lane-scopes every path argument in a deterministic `run:` command, then
+ * injects `--lane <id>` after the bridge subcommand for the lane-aware
+ * subcommands ({@link EVOLVE_LANE_AWARE_COMMANDS}). Returns the command
+ * unchanged when no lane is active. See the module's ESCAPING INVARIANT.
+ */
+export function templateLaneCommand(command, context) {
+    const templated = command.map((arg) => laneScopeEvolveCurrentPath(arg, context));
+    const lane = context.lane;
+    if (!lane)
+        return templated;
+    return injectEvolveLaneArg(templated, lane.id);
+}
+/**
+ * Finds the index of the {@link EVOLVE_RESULT_SCRIPT} bridge entry in a command
+ * argv (matching either the bare basename or any `…/evolve_result.py` path), or
+ * `-1` if absent. The single source of truth for locating the bridge so the
+ * orchestrator and the `--lane` injector agree on what counts as the script.
+ */
+export function evolveResultScriptIndex(command) {
+    return command.findIndex((arg) => arg === EVOLVE_RESULT_SCRIPT || arg.endsWith(`/${EVOLVE_RESULT_SCRIPT}`));
+}
+function replaceCurrentPrefix(value, currentDir, replacement) {
+    if (value === currentDir)
+        return replacement;
+    const prefix = `${currentDir}/`;
+    if (!value.startsWith(prefix))
+        return value;
+    const suffix = value.slice(prefix.length);
+    // Idempotency guard: a path already lane-scoped (`current/lane_<n>/…`) must
+    // not be re-prefixed into `current/lane_<k>/lane_<n>/…`. This makes the rewrite
+    // safe to apply more than once (e.g. an argv that was templated upstream and
+    // re-templated here) and protects manifest paths that hardcode `lane_${laneId}`
+    // — applyLaneTemplate already expanded those, so the literal `lane_<n>/` they
+    // produce must be left alone. The flip side: a manifest that hardcodes a literal
+    // `lane_<digit>/` (no `${laneId}` to expand) is left UNCHANGED by every lane and
+    // would clobber — the validator (`HARDCODED_LANE_RESULT_FILE_RE` in validate.ts)
+    // rejects exactly that, matching this guard's `/^lane_\d+\//` notion of "a lane
+    // segment"; the two must stay consistent.
+    if (/^lane_\d+\//.test(suffix))
+        return value;
+    return `${replacement}/${suffix}`;
+}
+function injectEvolveLaneArg(command, id) {
+    if (command.includes('--lane'))
+        return command;
+    const scriptIndex = evolveResultScriptIndex(command);
+    if (scriptIndex < 0)
+        return command;
+    const subcommandIndex = scriptIndex + 1;
+    const subcommand = command[subcommandIndex];
+    if (!EVOLVE_LANE_AWARE_COMMANDS.has(subcommand))
+        return command;
+    return [...command.slice(0, subcommandIndex + 1), '--lane', String(id), ...command.slice(subcommandIndex + 1)];
+}
+//# sourceMappingURL=lane-template.js.map

package/dist/workflow/lane-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lane-template.js","sourceRoot":"","sources":["../../src/workflow/lane-template.ts"],"names":[],"mappings":"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"}

package/dist/workflow/lint-integration.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared pre-flight lint integration used by both the CLI and the daemon.
+ * UI-agnostic: returns a `PreflightResult` that callers format themselves
+ * (stderr for CLI, JSON-RPC error data for the daemon).
+ */
+import { type Diagnostic, type LintContext } from './lint.js';
+import type { WorkflowDefinition } from './types.js';
+/**
+ * Default `LintContext` shared by both the CLI and the daemon. Backed by the
+ * real filesystem-resolving `personaExists` from `src/persona/resolve.ts`.
+ */
+export declare const defaultLintContext: LintContext;
+/**
+ * How strict the pre-flight should be:
+ * - `off`   : skip linting entirely; always ok.
+ * - `warn`  : fail only on error-severity diagnostics; warnings pass.
+ * - `strict`: fail on any diagnostic, including warnings.
+ */
+export type LintMode = 'off' | 'warn' | 'strict';
+export interface PreflightResult {
+    readonly ok: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function preflightLint(definition: WorkflowDefinition, context: LintContext, mode: LintMode): PreflightResult;
+/**
+ * Discriminated result for {@link runPreflight}. Three variants:
+ *
+ * - `{ ok: true, ... }`: the definition loaded and lint either had no
+ *   diagnostics or had only diagnostics tolerated by `mode`. `warnings`
+ *   counts the (passing) warnings present.
+ * - `{ ok: false, kind: 'load', ... }`: the definition file could not be
+ *   parsed or did not validate. `loadKind` distinguishes the two.
+ * - `{ ok: false, kind: 'lint', ... }`: the definition loaded but lint
+ *   produced diagnostics that fail `mode`. The definition is still returned
+ *   so callers can render it alongside the diagnostics.
+ */
+export type RunPreflightResult = {
+    ok: true;
+    definition: WorkflowDefinition;
+    diagnostics: readonly Diagnostic[];
+    warnings: number;
+} | {
+    ok: false;
+    kind: 'load';
+    loadKind: 'parse' | 'validate';
+    message: string;
+} | {
+    ok: false;
+    kind: 'lint';
+    definition: WorkflowDefinition;
+    diagnostics: readonly Diagnostic[];
+    errors: number;
+    warnings: number;
+};
+/**
+ * Loads + validates a definition from `definitionPath`, then runs
+ * {@link preflightLint} with a {@link LintContext} derived from
+ * {@link defaultLintContext} but bound to `definitionPath` so
+ * package-relative checks (currently WF010 — skill references) can
+ * resolve sibling resources. Never throws — returns a discriminated
+ * result that callers map to their own error surfaces (stderr+exit
+ * for CLI, RpcError for the daemon).
+ */
+export declare function runPreflight(definitionPath: string, mode: LintMode): RunPreflightResult;

package/dist/workflow/lint-integration.js

@@ -0,0 +1,56 @@
+/**
+ * Shared pre-flight lint integration used by both the CLI and the daemon.
+ * UI-agnostic: returns a `PreflightResult` that callers format themselves
+ * (stderr for CLI, JSON-RPC error data for the daemon).
+ */
+import { countBySeverity, lintWorkflow } from './lint.js';
+import { personaExists } from '../persona/resolve.js';
+import { loadDefinition } from './definition-loader.js';
+/**
+ * Default `LintContext` shared by both the CLI and the daemon. Backed by the
+ * real filesystem-resolving `personaExists` from `src/persona/resolve.ts`.
+ */
+export const defaultLintContext = { personaExists };
+export function preflightLint(definition, context, mode) {
+    if (mode === 'off')
+        return { ok: true, diagnostics: [] };
+    const diagnostics = lintWorkflow(definition, context);
+    const { errors } = countBySeverity(diagnostics);
+    const failed = mode === 'strict' ? diagnostics.length > 0 : errors > 0;
+    return { ok: !failed, diagnostics };
+}
+/**
+ * Loads + validates a definition from `definitionPath`, then runs
+ * {@link preflightLint} with a {@link LintContext} derived from
+ * {@link defaultLintContext} but bound to `definitionPath` so
+ * package-relative checks (currently WF010 — skill references) can
+ * resolve sibling resources. Never throws — returns a discriminated
+ * result that callers map to their own error surfaces (stderr+exit
+ * for CLI, RpcError for the daemon).
+ */
+export function runPreflight(definitionPath, mode) {
+    const loaded = loadDefinition(definitionPath);
+    if (!loaded.ok) {
+        return { ok: false, kind: 'load', loadKind: loaded.kind, message: loaded.message };
+    }
+    const ctx = { ...defaultLintContext, workflowFilePath: definitionPath };
+    const lintResult = preflightLint(loaded.definition, ctx, mode);
+    const { errors, warnings } = countBySeverity(lintResult.diagnostics);
+    if (lintResult.ok) {
+        return {
+            ok: true,
+            definition: loaded.definition,
+            diagnostics: lintResult.diagnostics,
+            warnings,
+        };
+    }
+    return {
+        ok: false,
+        kind: 'lint',
+        definition: loaded.definition,
+        diagnostics: lintResult.diagnostics,
+        errors,
+        warnings,
+    };
+}
+//# sourceMappingURL=lint-integration.js.map

package/dist/workflow/lint-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-integration.js","sourceRoot":"","sources":["../../src/workflow/lint-integration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAqC,MAAM,WAAW,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAgB,EAAE,aAAa,EAAE,CAAC;AAejE,MAAM,UAAU,aAAa,CAAC,UAA8B,EAAE,OAAoB,EAAE,IAAc;IAChG,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAEzD,MAAM,WAAW,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAEvE,OAAO,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;AACtC,CAAC;AAoCD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,cAAsB,EAAE,IAAc;IACjE,MAAM,MAAM,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACrF,CAAC;IAED,MAAM,GAAG,GAAgB,EAAE,GAAG,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC;IACrF,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC/D,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,eAAe,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAErE,IAAI,UAAU,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO;YACL,EAAE,EAAE,IAAI;YACR,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,WAAW,EAAE,UAAU,CAAC,WAAW;YACnC,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,KAAK;QACT,IAAI,EAAE,MAAM;QACZ,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,MAAM;QACN,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/workflow/lint.d.ts

@@ -0,0 +1,72 @@
+import type { WorkflowDefinition } from './types.js';
+/**
+ * Diagnostic codes.
+ *
+ * WF008 occupies the slot previously used for a raw-YAML check that
+ * `maxVisits` is only declared on agent states. That check now throws
+ * `WorkflowValidationError` before lint runs, so it never emits a WF code;
+ * the slot is reclaimed here for the visit-cap transition-ordering rule.
+ * WF009 is retired for the same reason (state-ID regex is a validation
+ * error) and must not be reused.
+ *
+ * WF005 (parallelKey + worktree needs gitRepoPath) is retired: the
+ * `parallelKey` schema field was removed as unused, so the trigger
+ * condition can no longer fire. Must not be reused.
+ *
+ * WF010 covers two related concerns under a single code:
+ *   1. State-scoped: an agent state's `skills:` entry is invalid or
+ *      doesn't match any discoverable skill in the package.
+ *   2. Package-scoped: a `SKILL.md` under the workflow package's
+ *      `skills/` tree is malformed, unreadable, or missing required
+ *      frontmatter fields. These are surfaced even when no state
+ *      references the broken skill, so authors get fast feedback on a
+ *      typo in frontmatter rather than discovering it via a "skill not
+ *      found" message at runtime.
+ *
+ * Both concerns are skipped cleanly when the lint caller did not
+ * supply a `workflowFilePath` (the package dir is the only place skill
+ * manifests can live).
+ *
+ * WF013 (fan-out maxRounds budget) and WF014 (fan-out child-bounds) are
+ * sibling fan-out checks split apart so each carries one concern. WF014
+ * previously flagged non-barrier fan-out joins; that is now a parse-time
+ * rejection (`FanOutDefinition.join` is the literal `'barrier'`), so the
+ * lint became unreachable and the number was reclaimed for child-bounds.
+ */
+export type DiagnosticCode = 'WF001' | 'WF002' | 'WF003' | 'WF004' | 'WF006' | 'WF007' | 'WF008' | 'WF010' | 'WF011' | 'WF012' | 'WF013' | 'WF014';
+export type DiagnosticSeverity = 'error' | 'warning';
+export interface Diagnostic {
+    readonly code: DiagnosticCode;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly stateId?: string;
+    readonly hint?: string;
+}
+/**
+ * Injected facts the linter cannot derive from the definition alone.
+ *
+ * Kept minimal: methods/fields are added only when a new check
+ * genuinely needs external context.
+ */
+export interface LintContext {
+    /** Returns true iff the named persona is installed locally. */
+    personaExists(name: string): boolean;
+    /**
+     * Absolute path to the workflow file being linted, when known. Used
+     * by checks that resolve co-packaged resources off the manifest's
+     * directory (currently WF010 — skill references). Lint callers that
+     * do not have a path on hand (e.g., synthesized definitions in tests)
+     * may omit this; rules that need it skip cleanly when absent.
+     */
+    readonly workflowFilePath?: string;
+}
+export type LintResult = readonly Diagnostic[];
+/**
+ * Runs all registered checks against `def`. Pure: same input => same
+ * output. Diagnostics come back in stable order (WF001 first, WF007 last).
+ */
+export declare function lintWorkflow(def: WorkflowDefinition, ctx: LintContext): LintResult;
+export declare function countBySeverity(diagnostics: readonly Diagnostic[]): {
+    errors: number;
+    warnings: number;
+};