@voybio/ace-swarm 0.1.0

package/dist/schemas.js

@@ -0,0 +1,830 @@
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { isInside, mapAceWorkspaceRelativePath } from "./helpers.js";
+const NON_EMPTY = z.string().min(1);
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const MODULE_ID = /^(capability|agent)-[a-z0-9-]+$/;
+const REQUIRED_PROVENANCE_FIELDS = [
+    "artifact_id",
+    "artifact_path",
+    "producer_module",
+    "spec_version",
+    "req_ids",
+    "checksum",
+    "confidence_level",
+    "evidence_ref",
+    "timestamp",
+];
+const swarmHandoffSchema = z
+    .object({
+    handoff_id: NON_EMPTY,
+    timestamp_utc: z.string().datetime({ offset: true }),
+    router: z
+        .object({
+        from: NON_EMPTY,
+        via: NON_EMPTY,
+        to: NON_EMPTY,
+    })
+        .strict(),
+    task: z
+        .object({
+        title: NON_EMPTY,
+        type: z.enum(["venture", "ux", "engineering", "mixed"]),
+        priority: z.enum(["P0", "P1", "P2"]),
+        owner: NON_EMPTY,
+        depends_on: z.array(z.string()),
+        scope: NON_EMPTY,
+    })
+        .strict(),
+    context: z
+        .object({
+        business_requirement: z.string(),
+        design_constraint: z.string(),
+        engineering_constraint: z.string(),
+        directive: NON_EMPTY,
+    })
+        .strict(),
+    acceptance_criteria: z.array(NON_EMPTY).min(1),
+    deliverables: z.array(z.string()),
+    verification: z
+        .object({
+        required_evidence: z.array(NON_EMPTY).min(1),
+        review_check: NON_EMPTY,
+        status: z.enum(["pending", "in_progress", "pass", "fail"]),
+    })
+        .strict(),
+    risks: z.array(z.string()),
+    open_questions: z.array(z.string()),
+    lessons_hook: z
+        .object({
+        on_correction_update: NON_EMPTY,
+        rule_format: NON_EMPTY,
+    })
+        .strict(),
+    return_payload_contract: z
+        .object({
+        must_include: z.array(NON_EMPTY).min(1),
+    })
+        .strict(),
+})
+    .strict();
+const agentStateHandoffSchema = z
+    .object({
+    meta: z
+        .object({
+        timestamp: z.string().datetime({ offset: true }),
+        iteration: z.number().int().min(1),
+        session_id: NON_EMPTY,
+        log_commit: z.string().regex(SHA256),
+    })
+        .strict(),
+    transition: z
+        .object({
+        from: z.string().regex(MODULE_ID),
+        to: z.string().regex(MODULE_ID),
+        status: z.enum(["READY", "READY_FOR_REVIEW", "BLOCKED", "DONE"]),
+        reason: NON_EMPTY,
+    })
+        .strict(),
+    payload: z
+        .object({
+        primary_artifact: NON_EMPTY,
+        interface_contract: NON_EMPTY,
+        evidence_pointer: NON_EMPTY,
+        known_issues: z.array(z.string()),
+    })
+        .strict(),
+    integrity: z
+        .object({
+        checksum: z.string().regex(SHA256),
+        file_count: z.number().int().min(0),
+    })
+        .strict(),
+})
+    .strict();
+const statusEventSchema = z
+    .object({
+    schema_version: z.literal("1.0.0"),
+    event_id: NON_EMPTY,
+    trace_id: NON_EMPTY,
+    timestamp: z.string().datetime({ offset: true }),
+    source_module: z.string().regex(MODULE_ID),
+    event_type: NON_EMPTY,
+    status: z.enum(["started", "in_progress", "pass", "fail", "blocked", "done"]),
+    objective_id: z.string().optional(),
+    decision_id: z.string().optional(),
+    payload: z
+        .object({
+        summary: NON_EMPTY,
+        gate_id: z.string().optional(),
+        evidence_ref: z.string().optional(),
+        artifact_delta: z.array(z.string()).optional(),
+    })
+        .passthrough(),
+})
+    .strict();
+/**
+ * Stricter schema for provenance-critical events: objective_id or decision_id
+ * or evidence_ref MUST be present (fail-closed autonomy gate).
+ */
+const provenanceCriticalEventSchema = statusEventSchema
+    .refine((ev) => {
+    const hasObj = typeof ev.objective_id === "string" && ev.objective_id.length > 0;
+    const hasDec = typeof ev.decision_id === "string" && ev.decision_id.length > 0;
+    const hasEv = typeof ev.payload.evidence_ref === "string" && ev.payload.evidence_ref.length > 0;
+    return hasObj || hasDec || hasEv;
+}, {
+    message: "Provenance-critical event MUST include at least one of: objective_id, decision_id, or payload.evidence_ref",
+});
+const artifactManifestEntrySchema = z
+    .object({
+    artifact_id: z.string().min(4),
+    artifact_path: NON_EMPTY,
+    producer_module: z.string().regex(MODULE_ID),
+    spec_version: NON_EMPTY,
+    req_ids: z.array(NON_EMPTY).min(1),
+    timestamp: z.string().datetime({ offset: true }),
+    checksum: z.string().regex(SHA256),
+    confidence_level: z.enum(["low", "medium", "high", "WIP", "Draft", "Verified"]),
+    evidence_ref: NON_EMPTY,
+    dependencies: z.array(z.string()).optional(),
+    evidence_refs: z.array(NON_EMPTY).min(1).optional(),
+})
+    .strict()
+    .superRefine((entry, ctx) => {
+    if (entry.evidence_refs && !entry.evidence_refs.includes(entry.evidence_ref)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["evidence_refs"],
+            message: "evidence_refs must include evidence_ref when provided",
+        });
+    }
+});
+const artifactManifestFileSchema = z
+    .object({
+    schema_version: z.literal("1.1.0"),
+    updated_at: z.string().datetime({ offset: true }),
+    artifacts: z.array(artifactManifestEntrySchema),
+})
+    .strict();
+const workspaceHookStateSchema = z
+    .object({
+    status: z.enum(["not_run", "ok", "failed"]),
+    detail: z.string().optional(),
+})
+    .strict();
+const workspaceSessionRecordSchema = z
+    .object({
+    session_id: NON_EMPTY,
+    workspace_path: NON_EMPTY,
+    root_path: NON_EMPTY,
+    status: z.enum(["active", "archived", "removed", "failed"]),
+    source: z.enum(["manual", "executor", "test"]),
+    objective_id: z.string().optional(),
+    tracker_item_id: z.string().optional(),
+    last_error: z.string().optional(),
+    created_at: z.string().datetime({ offset: true }),
+    updated_at: z.string().datetime({ offset: true }),
+    hooks: z
+        .object({
+        after_create: workspaceHookStateSchema,
+        before_run: workspaceHookStateSchema,
+        after_run: workspaceHookStateSchema,
+        before_remove: workspaceHookStateSchema,
+    })
+        .strict(),
+})
+    .strict();
+const workspaceSessionRegistrySchema = z
+    .object({
+    version: z.literal(1),
+    updated_at: z.string().datetime({ offset: true }),
+    sessions: z.array(workspaceSessionRecordSchema),
+})
+    .strict();
+const trackerMetadataSchema = z.record(z.string(), z.unknown());
+const trackerItemSchema = z
+    .object({
+    item_id: NON_EMPTY,
+    external_id: z.string().optional(),
+    title: NON_EMPTY,
+    body: z.string().optional(),
+    state: NON_EMPTY,
+    labels: z.array(z.string()),
+    assignee: z.string().optional(),
+    url: z.string().optional(),
+    updated_at: z.string().datetime({ offset: true }),
+    metadata: trackerMetadataSchema,
+})
+    .strict();
+const trackerCommentSchema = z
+    .object({
+    comment_id: NON_EMPTY,
+    item_id: NON_EMPTY,
+    body: NON_EMPTY,
+    author: NON_EMPTY,
+    created_at: z.string().datetime({ offset: true }),
+    metadata: trackerMetadataSchema,
+})
+    .strict();
+const trackerSnapshotSchema = z
+    .object({
+    version: z.literal(1),
+    adapter_kind: z.enum(["none", "memory", "external"]),
+    updated_at: z.string().datetime({ offset: true }),
+    items: z.array(trackerItemSchema),
+    comments: z.array(trackerCommentSchema),
+})
+    .strict();
+const runtimeToolSchemaScalarSchema = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+]);
+const runtimeToolSchemaNodeSchema = z.lazy(() => z
+    .object({
+    type: z.enum(["object", "array", "string", "number", "integer", "boolean", "null"]),
+    description: z.string().optional(),
+    enum: z.array(runtimeToolSchemaScalarSchema).optional(),
+    properties: z.record(z.string(), runtimeToolSchemaNodeSchema).optional(),
+    required: z.array(z.string()).optional(),
+    additionalProperties: z.boolean().optional(),
+    items: runtimeToolSchemaNodeSchema.optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.type === "object" && value.items) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["items"],
+            message: "object schemas must not define items",
+        });
+    }
+    if (value.type !== "object" && (value.properties || value.required)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["properties"],
+            message: "only object schemas may define properties or required",
+        });
+    }
+    if (value.type === "array" && !value.items) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["items"],
+            message: "array schemas must define items",
+        });
+    }
+    if (value.type !== "array" && value.items) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["items"],
+            message: "only array schemas may define items",
+        });
+    }
+}));
+const runtimeToolExecutorSchema = z
+    .object({
+    command: NON_EMPTY,
+    cwd: z.string().optional(),
+    timeout_ms: z.number().int().positive().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+})
+    .strict();
+const runtimeToolSpecSchema = z
+    .object({
+    name: NON_EMPTY,
+    description: NON_EMPTY,
+    input_schema: runtimeToolSchemaNodeSchema,
+    success_schema: runtimeToolSchemaNodeSchema.optional(),
+    failure_schema: runtimeToolSchemaNodeSchema.optional(),
+    executor: runtimeToolExecutorSchema,
+})
+    .strict();
+const runtimeToolSpecRegistrySchema = z
+    .object({
+    version: z.literal(1),
+    updated_at: z.string().datetime({ offset: true }),
+    tools: z.array(runtimeToolSpecSchema),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const names = new Set();
+    for (const [index, tool] of value.tools.entries()) {
+        if (names.has(tool.name)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["tools", index, "name"],
+                message: `duplicate tool name "${tool.name}"`,
+            });
+        }
+        names.add(tool.name);
+    }
+});
+const unattendedToolCallRecordSchema = z
+    .object({
+    tool_name: NON_EMPTY,
+    ok: z.boolean(),
+    summary: NON_EMPTY,
+    request_path: NON_EMPTY,
+    response_path: NON_EMPTY,
+    started_at: z.string().datetime({ offset: true }),
+    ended_at: z.string().datetime({ offset: true }),
+    output: z.unknown().optional(),
+    error: z.unknown().optional(),
+    validation_errors: z.array(z.string()).optional(),
+})
+    .strict();
+const unattendedTurnRecordSchema = z
+    .object({
+    turn_number: z.number().int().positive(),
+    task: NON_EMPTY,
+    started_at: z.string().datetime({ offset: true }),
+    ended_at: z.string().datetime({ offset: true }),
+    status: z.enum(["completed", "failed", "blocked", "stopped"]),
+    response_status: z.enum(["continue", "done", "blocked", "failed"]),
+    summary: NON_EMPTY,
+    prompt_path: NON_EMPTY,
+    request_path: NON_EMPTY,
+    response_path: NON_EMPTY,
+    exit_code: z.number().int().nullable(),
+    stdout: z.string(),
+    stderr: z.string(),
+    tool_calls: z.array(unattendedToolCallRecordSchema),
+})
+    .strict();
+const runtimeExecutorSessionRecordSchema = z
+    .object({
+    session_id: NON_EMPTY,
+    status: z.enum(["starting", "running", "completed", "failed", "blocked", "stopped"]),
+    task: NON_EMPTY,
+    current_task: NON_EMPTY,
+    runtime_profile_path: NON_EMPTY,
+    workspace_session_id: NON_EMPTY,
+    workspace_path: NON_EMPTY,
+    objective_id: z.string().optional(),
+    tracker_item_id: z.string().optional(),
+    command: NON_EMPTY,
+    max_turns: z.number().int().positive(),
+    turn_timeout_ms: z.number().int().positive(),
+    turn_count: z.number().int().min(0),
+    created_at: z.string().datetime({ offset: true }),
+    updated_at: z.string().datetime({ offset: true }),
+    started_at: z.string().datetime({ offset: true }).optional(),
+    ended_at: z.string().datetime({ offset: true }).optional(),
+    result_summary: z.string().optional(),
+    last_error: z.string().optional(),
+    cleanup_error: z.string().optional(),
+    workspace_cleanup_status: z.enum(["pending", "removed", "archived", "failed"]),
+    turns: z.array(unattendedTurnRecordSchema),
+})
+    .strict();
+const runtimeExecutorSessionRegistrySchema = z
+    .object({
+    version: z.literal(1),
+    updated_at: z.string().datetime({ offset: true }),
+    sessions: z.array(runtimeExecutorSessionRecordSchema),
+})
+    .strict();
+const vericifyProcessPostSchema = z
+    .object({
+    process_post_id: NON_EMPTY,
+    run_id: NON_EMPTY,
+    branch_id: z.string().optional(),
+    lane_id: z.string().optional(),
+    agent_id: NON_EMPTY,
+    kind: z.enum(["intent", "progress", "blocker", "handoff_note", "stale_ack", "completion"]),
+    summary: NON_EMPTY,
+    tool_refs: z.array(z.string()),
+    evidence_refs: z.array(z.string()),
+    checkpoint_ref: z.string().optional(),
+    timestamp: z.string().datetime({ offset: true }),
+})
+    .strict();
+const vericifyProcessPostLogSchema = z
+    .object({
+    version: z.literal(1),
+    updated_at: z.string().datetime({ offset: true }),
+    posts: z.array(vericifyProcessPostSchema),
+})
+    .strict();
+const vericifyBridgeSourceStateSchema = z
+    .object({
+    path: NON_EMPTY,
+    exists: z.boolean(),
+    updated_at: z.string().datetime({ offset: true }).optional(),
+    record_count: z.number().int().min(0),
+    summary: NON_EMPTY,
+})
+    .strict();
+const vericifyBridgeActiveRunRefSchema = z
+    .object({
+    run_id: NON_EMPTY,
+    branch_id: NON_EMPTY,
+    lane_id: NON_EMPTY,
+    session_id: NON_EMPTY,
+    status: NON_EMPTY,
+    objective_id: z.string().optional(),
+    tracker_item_id: z.string().optional(),
+    workspace_path: NON_EMPTY,
+    updated_at: z.string().datetime({ offset: true }),
+})
+    .strict();
+const vericifyBridgeSnapshotSchema = z
+    .object({
+    version: z.literal(1),
+    generated_at: z.string().datetime({ offset: true }),
+    bridge_enabled: z.boolean(),
+    workspace_root: NON_EMPTY,
+    runtime_profile_path: NON_EMPTY,
+    bridge_path: NON_EMPTY,
+    process_post_path: NON_EMPTY,
+    sources: z
+        .object({
+        handoff_registry: vericifyBridgeSourceStateSchema,
+        todo_state: vericifyBridgeSourceStateSchema,
+        run_ledger: vericifyBridgeSourceStateSchema,
+        status_events: vericifyBridgeSourceStateSchema,
+        runtime_workspaces: vericifyBridgeSourceStateSchema,
+        runtime_executor_sessions: vericifyBridgeSourceStateSchema,
+        tracker_snapshot: vericifyBridgeSourceStateSchema,
+        process_posts: vericifyBridgeSourceStateSchema,
+    })
+        .strict(),
+    active_run_refs: z.array(vericifyBridgeActiveRunRefSchema),
+})
+    .strict();
+/**
+ * Event types that MUST carry provenance fields (autonomy gate – fail-closed).
+ * Exported so status-events.ts can use the same canonical set.
+ */
+export const PROVENANCE_CRITICAL_EVENT_TYPES = new Set([
+    "SAFE_EDIT_COMPLETED",
+    "SAFE_EDIT_FAILED",
+    "FRAMEWORK_VALIDATED",
+    "GIT_COMMITTED",
+    "CIRCUIT_BREAKER_OPENED",
+    "CIRCUIT_BREAKER_CLOSED",
+    "DISCOVERY_INDEX_READY",
+]);
+function formatZodErrors(error) {
+    return error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+        return `${path}: ${issue.message}`;
+    });
+}
+function validateWithSchema(schemaName, schema, payload) {
+    const result = schema.safeParse(payload);
+    if (result.success)
+        return { ok: true, schema: schemaName };
+    return {
+        ok: false,
+        schema: schemaName,
+        errors: formatZodErrors(result.error),
+    };
+}
+export function validateSwarmHandoffPayload(payload) {
+    return validateWithSchema("swarm-handoff@1.0.0", swarmHandoffSchema, payload);
+}
+export function validateAgentStateHandoffPayload(payload) {
+    return validateWithSchema("agent-state-handoff@1.0.0", agentStateHandoffSchema, payload);
+}
+export function validateArtifactManifestPayload(payload) {
+    const fileValidation = validateWithSchema("artifact-manifest@1.1.0", artifactManifestFileSchema, payload);
+    if (fileValidation.ok)
+        return fileValidation;
+    const entryValidation = validateWithSchema("artifact-manifest-entry@1.1.0", artifactManifestEntrySchema, payload);
+    if (entryValidation.ok)
+        return entryValidation;
+    return {
+        ok: false,
+        schema: "artifact-manifest@1.1.0",
+        errors: [
+            ...fileValidation.errors.map((error) => `[manifest] ${error}`),
+            ...entryValidation.errors.map((error) => `[entry] ${error}`),
+        ],
+    };
+}
+export function validateWorkspaceSessionRegistryPayload(payload) {
+    return validateWithSchema("workspace-session-registry@1.0.0", workspaceSessionRegistrySchema, payload);
+}
+export function validateTrackerSnapshotPayload(payload) {
+    return validateWithSchema("tracker-snapshot@1.0.0", trackerSnapshotSchema, payload);
+}
+export function validateRuntimeToolSpecRegistryPayload(payload) {
+    return validateWithSchema("runtime-tool-spec-registry@1.0.0", runtimeToolSpecRegistrySchema, payload);
+}
+export function validateRuntimeExecutorSessionRegistryPayload(payload) {
+    return validateWithSchema("runtime-executor-session-registry@1.0.0", runtimeExecutorSessionRegistrySchema, payload);
+}
+export function validateVericifyProcessPostLogPayload(payload) {
+    return validateWithSchema("vericify-process-post-log@1.0.0", vericifyProcessPostLogSchema, payload);
+}
+export function validateVericifyBridgeSnapshotPayload(payload) {
+    return validateWithSchema("vericify-bridge-snapshot@1.0.0", vericifyBridgeSnapshotSchema, payload);
+}
+export function validateStatusEventPayload(payload, options) {
+    if (options?.provenanceCritical) {
+        return validateWithSchema("status-event-provenance@1.0.0", provenanceCriticalEventSchema, payload);
+    }
+    return validateWithSchema("status-event@1.0.0", statusEventSchema, payload);
+}
+export function validateStatusEventsNdjsonContent(content) {
+    const lines = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 0) {
+        return {
+            ok: false,
+            schema: "status-event-ndjson@1.0.0",
+            errors: ["NDJSON content is empty"],
+        };
+    }
+    const errors = [];
+    lines.forEach((line, idx) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            errors.push(`line ${idx + 1}: invalid JSON`);
+            return;
+        }
+        const validation = validateStatusEventPayload(parsed);
+        if (!validation.ok) {
+            errors.push(...validation.errors.map((error) => `line ${idx + 1}: ${error}`));
+        }
+    });
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            schema: "status-event-ndjson@1.0.0",
+            errors,
+        };
+    }
+    return { ok: true, schema: "status-event-ndjson@1.0.0" };
+}
+export function validateTealConfigContent(content) {
+    const errors = [];
+    const fenceCount = (content.match(/```/g) ?? []).length;
+    const fencedBlocks = [...content.matchAll(/```([^\n]*)\n([\s\S]*?)```/g)];
+    if (fenceCount !== 2 || fencedBlocks.length !== 1) {
+        errors.push(`TEAL_CONFIG.md must contain exactly one fenced code block; found ${fencedBlocks.length}`);
+    }
+    const block = fencedBlocks[0];
+    if (block) {
+        const language = block[1].trim().toLowerCase();
+        const yamlBody = block[2].trim();
+        if (language !== "yaml") {
+            errors.push(`TEAL_CONFIG.md active config block must be fenced as \`\`\`yaml, found "${block[1].trim() || "(none)"}"`);
+        }
+        if (!yamlBody) {
+            errors.push("TEAL_CONFIG.md YAML block is empty");
+        }
+        else {
+            for (const section of ["modules", "pipelines"]) {
+                if (!new RegExp(`^\\s*${section}:`, "m").test(yamlBody)) {
+                    errors.push(`TEAL_CONFIG.md YAML block is missing required top-level section "${section}:"`);
+                }
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            schema: "teal-config-markdown@1.0.0",
+            errors,
+        };
+    }
+    return { ok: true, schema: "teal-config-markdown@1.0.0" };
+}
+export function validateProvenanceLogContent(content) {
+    const errors = [];
+    const normalized = content.toLowerCase();
+    if (!content.trim()) {
+        errors.push("PROVENANCE_LOG.md is empty");
+    }
+    if (!normalized.includes("# provenance log")) {
+        errors.push('PROVENANCE_LOG.md must start with a "# PROVENANCE LOG" heading');
+    }
+    const missingFields = REQUIRED_PROVENANCE_FIELDS.filter((field) => !normalized.includes(field.toLowerCase()));
+    if (missingFields.length > 0) {
+        errors.push(`PROVENANCE_LOG.md is missing required provenance fields: ${missingFields.join(", ")}`);
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            schema: "provenance-log-markdown@1.0.0",
+            errors,
+        };
+    }
+    return { ok: true, schema: "provenance-log-markdown@1.0.0" };
+}
+export function validateHandoffPayload(payload, mode = "auto") {
+    if (mode === "swarm")
+        return validateSwarmHandoffPayload(payload);
+    if (mode === "agent-state")
+        return validateAgentStateHandoffPayload(payload);
+    const swarm = validateSwarmHandoffPayload(payload);
+    if (swarm.ok)
+        return swarm;
+    const agentState = validateAgentStateHandoffPayload(payload);
+    if (agentState.ok)
+        return agentState;
+    return {
+        ok: false,
+        schema: "handoff-auto",
+        errors: [
+            ...swarm.errors.map((error) => `[swarm] ${error}`),
+            ...agentState.errors.map((error) => `[agent-state] ${error}`),
+        ],
+    };
+}
+// ────────────────────────────────────────────────────────────────────
+// Deep handoff lint — route legitimacy + evidence existence checks
+// ────────────────────────────────────────────────────────────────────
+/** Known legitimate ACE role prefixes (matches ROLE_ENUM in shared.ts). */
+const KNOWN_ROLES = new Set([
+    "orchestrator", "vos", "ui", "coders", "astgrep", "skeptic",
+    "ops", "research", "spec", "builder", "qa", "docs",
+    "memory", "security", "observability", "eval", "release",
+]);
+function extractRole(agentLabel) {
+    return agentLabel.replace(/^ACE-/i, "").toLowerCase();
+}
+const HANDOFF_LINK_FALLBACK_ROOTS = [
+    "agent-state",
+    "global-state",
+    "tasks",
+    "venture-state",
+    "brand-state",
+    "business-state",
+    "engineering-state",
+];
+const ACE_HANDOFF_MANAGED_PREFIXES = [
+    "tasks",
+    "scripts",
+    ".github",
+    ".claude",
+    ".cursor",
+    ".vscode",
+    ".mcp-config",
+];
+const ACE_HANDOFF_MANAGED_FILES = new Set([
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".cursorrules",
+]);
+function mapHandoffLinkWorkspaceRelativePath(relPath) {
+    const normalized = relPath.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+    if (!normalized)
+        return normalized;
+    if (ACE_HANDOFF_MANAGED_FILES.has(normalized)) {
+        return `.agents/ACE/${normalized}`;
+    }
+    for (const prefix of ACE_HANDOFF_MANAGED_PREFIXES) {
+        if (normalized === prefix || normalized.startsWith(`${prefix}/`)) {
+            return `.agents/ACE/${normalized}`;
+        }
+    }
+    return mapAceWorkspaceRelativePath(normalized);
+}
+function resolveLinkedWorkspacePath(workspaceRoot, filePath, preferredRoots = []) {
+    const normalized = filePath.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+    if (!normalized)
+        return undefined;
+    if (isAbsolute(normalized)) {
+        return isInside(workspaceRoot, normalized) && existsSync(normalized)
+            ? normalized
+            : undefined;
+    }
+    const candidates = new Set();
+    const pushCandidate = (candidate) => {
+        const cleaned = candidate.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+        if (!cleaned)
+            return;
+        candidates.add(mapHandoffLinkWorkspaceRelativePath(cleaned));
+    };
+    pushCandidate(normalized);
+    if (!normalized.includes("/")) {
+        for (const root of [...preferredRoots, ...HANDOFF_LINK_FALLBACK_ROOTS]) {
+            pushCandidate(`${root}/${normalized}`);
+        }
+    }
+    for (const candidate of candidates) {
+        const absPath = resolve(workspaceRoot, candidate);
+        if (isInside(workspaceRoot, absPath) && existsSync(absPath)) {
+            return absPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Deep lint beyond schema validation:
+ *  - Route legitimacy (from/to must be known roles)
+ *  - Evidence freshness (context_pointers must reference existing files)
+ *  - Acceptance criteria must be non-trivial
+ *  - Required evidence array must be non-empty
+ */
+export function lintHandoffPayload(payload, workspaceRoot) {
+    const warnings = [];
+    const errors = [];
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        errors.push("Payload is not an object");
+        return { ok: false, warnings, errors };
+    }
+    const obj = payload;
+    // ── Route legitimacy ────────────────────────────────────────────
+    const router = obj.router;
+    if (router && typeof router === "object") {
+        for (const field of ["from", "to"]) {
+            const val = router[field];
+            if (typeof val === "string") {
+                const role = extractRole(val);
+                if (!KNOWN_ROLES.has(role)) {
+                    errors.push(`router.${field} references unknown role: "${val}" (resolved: "${role}")`);
+                }
+            }
+        }
+        // Self-routing check
+        if (typeof router.from === "string" &&
+            typeof router.to === "string" &&
+            extractRole(router.from) === extractRole(router.to)) {
+            warnings.push(`Self-routing detected: from and to resolve to same role "${extractRole(router.from)}"`);
+        }
+    }
+    // ── Transition (agent-state handoff) ────────────────────────────
+    const transition = obj.transition;
+    if (transition && typeof transition === "object") {
+        for (const field of ["from", "to"]) {
+            const val = transition[field];
+            if (typeof val === "string" && !/^(capability|agent)-[a-z0-9-]+$/.test(val)) {
+                errors.push(`transition.${field} doesn't match MODULE_ID pattern: "${val}"`);
+            }
+        }
+    }
+    // ── Evidence / context pointer existence (HARD FAIL) ────────────
+    // Helper: extract file path from evidence pointers that may contain
+    // #anchor (including ISO timestamps like #2026-03-06T17:43:28Z) or
+    // :line suffixes. Naive split(":") would truncate timestamps.
+    function extractFilePath(pointer) {
+        // Strip #anchor first (handles #line, #section, #timestamp)
+        const hashIdx = pointer.indexOf("#");
+        const withoutAnchor = hashIdx >= 0 ? pointer.slice(0, hashIdx) : pointer;
+        // Now strip any trailing :line-number reference (only numeric after colon)
+        const stripped = withoutAnchor.replace(/:(\d+)$/, "");
+        return stripped.trim();
+    }
+    const context = obj.context;
+    if (context && typeof context === "object") {
+        for (const [key, val] of Object.entries(context)) {
+            if (typeof val !== "string" || !val.trim())
+                continue;
+            // Check if value looks like a file reference (contains path separators or common extensions)
+            if (/\.(md|json|ts|js|yaml|yml|toml|txt|ndjson)/.test(val) || val.includes("/")) {
+                const filePath = extractFilePath(val);
+                const absPath = resolveLinkedWorkspacePath(workspaceRoot, filePath);
+                if (!absPath) {
+                    errors.push(`context.${key} references non-existent file: "${filePath}"`);
+                }
+            }
+        }
+    }
+    // ── Payload evidence pointer (agent-state handoffs) — HARD FAIL ─
+    const agentPayload = obj.payload;
+    if (agentPayload && typeof agentPayload === "object") {
+        const evidencePointer = agentPayload.evidence_pointer;
+        if (typeof evidencePointer === "string" && evidencePointer.trim()) {
+            const filePath = extractFilePath(evidencePointer);
+            const absPath = resolveLinkedWorkspacePath(workspaceRoot, filePath, ["agent-state"]);
+            if (!absPath) {
+                errors.push(`payload.evidence_pointer references non-existent file: "${filePath}"`);
+            }
+        }
+    }
+    // ── Acceptance criteria quality ─────────────────────────────────
+    const criteria = obj.acceptance_criteria;
+    if (Array.isArray(criteria)) {
+        if (criteria.length === 0) {
+            errors.push("acceptance_criteria is empty");
+        }
+        for (let i = 0; i < criteria.length; i++) {
+            const item = criteria[i];
+            if (typeof item === "string" && item.trim().length < 10) {
+                warnings.push(`acceptance_criteria[${i}] is trivially short: "${item}"`);
+            }
+        }
+    }
+    // ── Verification required_evidence ──────────────────────────────
+    const verification = obj.verification;
+    if (verification && typeof verification === "object") {
+        const requiredEvidence = verification.required_evidence;
+        if (Array.isArray(requiredEvidence) && requiredEvidence.length === 0) {
+            errors.push("verification.required_evidence is empty");
+        }
+    }
+    return { ok: errors.length === 0, warnings, errors };
+}
+//# sourceMappingURL=schemas.js.map