mdkg 0.3.6 → 0.3.8

package/dist/core/project_db_queue_contract.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectDbQueueAdapterContract = projectDbQueueAdapterContract;
+function projectDbQueueAdapterContract() {
+    return {
+        schema_version: 1,
+        contract_id: "mdkg.project_db.queue.adapter.v1",
+        stability: "public",
+        boundary: {
+            role: "durable local delivery state for mdkg project DB integrations",
+            canonical_history: "queue rows are not canonical event history or durable runtime transcripts",
+            raw_payload_policy: "store compact refs and redacted payloads; do not store raw secrets, prompts, provider payloads, or bulky runtime artifacts",
+            internal_surfaces: ["event", "receipt", "reducer", "writer_lease", "materializer"],
+        },
+        runtime: {
+            database: "node:sqlite",
+            transactions: "short BEGIN IMMEDIATE transactions for writes and claims",
+            external_dependencies: [],
+        },
+        commands: [
+            "mdkg db queue create <queue>",
+            "mdkg db queue pause <queue>",
+            "mdkg db queue resume <queue>",
+            "mdkg db queue enqueue <queue> <message-id>",
+            "mdkg db queue claim <queue>",
+            "mdkg db queue ack <queue> <message-id>",
+            "mdkg db queue fail <queue> <message-id>",
+            "mdkg db queue dead-letter <queue> <message-id>",
+            "mdkg db queue release-expired [queue]",
+            "mdkg db queue stats [queue]",
+            "mdkg db queue list <queue>",
+            "mdkg db queue show <queue> <message-id>",
+            "mdkg db queue contract",
+        ],
+        queue_control: {
+            table: "project_queue",
+            states: ["active", "paused"],
+            paused_behavior: {
+                rejects: ["enqueue", "claim"],
+                allows: ["ack", "fail", "dead-letter", "release-expired", "stats", "list", "show"],
+            },
+        },
+        message: {
+            table: "project_queue_message",
+            states: ["ready", "leased", "acked", "dead_letter"],
+            fields: [
+                "queue_name",
+                "message_id",
+                "dedupe_key",
+                "payload_json",
+                "payload_hash",
+                "status",
+                "available_at_ms",
+                "attempt_count",
+                "max_attempts",
+                "lease_owner",
+                "lease_deadline_ms",
+                "created_at_ms",
+                "updated_at_ms",
+                "last_error",
+            ],
+            terminal_states: ["acked", "dead_letter"],
+        },
+        payload_hash: {
+            algorithm: "sha256",
+            encoding: "sha256:<64 lowercase hex chars>",
+            canonicalization: "payload JSON is serialized deterministically with object keys sorted before hashing and storage",
+        },
+        dedupe: {
+            key: "queue_name + dedupe_key",
+            scope: "only non-null dedupe keys participate in the partial unique index",
+            duplicate_behavior: "enqueue with an existing dedupe key returns the existing message without replacing payload_json or payload_hash",
+        },
+        claim: {
+            selection: "oldest ready or expired leased message ordered by available_at_ms, created_at_ms, then message_id",
+            lease: "claim sets status=leased, lease_owner, and lease_deadline_ms; ack/fail/dead-letter must use the same lease owner",
+            transactional: true,
+        },
+        settlement: {
+            ack: "leased message becomes acked and clears lease owner/deadline",
+            fail: "leased message increments attempt_count; if attempts remain it becomes ready at now + retry_after_ms, otherwise it becomes dead_letter",
+            dead_letter: "leased message becomes dead_letter immediately and records last_error",
+            release_expired: "expired leased messages become ready and clear lease owner/deadline without changing attempt_count",
+        },
+        stats: {
+            counters: ["total", "ready", "leased", "acked", "dead_letter", "ready_available", "leased_expired"],
+            snapshot_summary: ["total", "ready", "leased", "acked", "dead_letter", "paused_ready", "active_ready"],
+        },
+        snapshot_policy: {
+            drain: "default seal policy; requires no ready or leased delivery work",
+            paused: "allows ready messages only when their queues are paused; leased messages are never allowed",
+        },
+        adapter_guidance: [
+            "create queues explicitly before enqueueing integration work",
+            "use dedupe keys for idempotent delivery",
+            "treat message payloads as refs and redacted envelopes, not canonical runtime state",
+            "settle or pause queues before committing sealed project DB state",
+            "use stats/list/show for operator review and avoid direct SQL coupling",
+        ],
+    };
+}

package/dist/graph/agent_file_types.js

@@ -3,15 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_ATTRIBUTE_KEY_ORDER = exports.AGENT_FILE_BASENAMES = exports.AGENT_FILE_TYPES = void 0;
+exports.AGENT_ATTRIBUTE_KEY_ORDER = exports.AGENT_FILE_BASENAMES = exports.AGENT_FILE_TYPES = exports.LEGACY_SPEC_BASENAME = exports.CANONICAL_MANIFEST_BASENAME = void 0;
 exports.isAgentFileType = isAgentFileType;
+exports.isManifestSemanticType = isManifestSemanticType;
+exports.collectManifestSiblingConflicts = collectManifestSiblingConflicts;
 exports.validateAgentFileName = validateAgentFileName;
 exports.validateAgentFrontmatter = validateAgentFrontmatter;
 exports.extractAgentAttributes = extractAgentAttributes;
 const path_1 = __importDefault(require("path"));
 const id_1 = require("../util/id");
 const refs_1 = require("../util/refs");
+exports.CANONICAL_MANIFEST_BASENAME = "MANIFEST.md";
+exports.LEGACY_SPEC_BASENAME = "SPEC.md";
 exports.AGENT_FILE_TYPES = [
+    "manifest",
     "spec",
     "work",
     "work_order",
@@ -21,7 +26,8 @@ exports.AGENT_FILE_TYPES = [
     "proposal",
 ];
 exports.AGENT_FILE_BASENAMES = {
-    spec: "SPEC.md",
+    manifest: exports.CANONICAL_MANIFEST_BASENAME,
+    spec: exports.LEGACY_SPEC_BASENAME,
     work: "WORK.md",
     work_order: "WORK_ORDER.md",
     receipt: "RECEIPT.md",
@@ -29,23 +35,25 @@ exports.AGENT_FILE_BASENAMES = {
     dispute: "DISPUTE.md",
     proposal: "PROPOSAL.md",
 };
+const MANIFEST_ATTRIBUTE_KEYS = [
+    "version",
+    "spec_kind",
+    "role",
+    "runtime_mode",
+    "work_contracts",
+    "requested_capabilities",
+    "skill_refs",
+    "tool_refs",
+    "model_refs",
+    "wasm_component_refs",
+    "runtime_image_refs",
+    "subagent_refs",
+    "resource_profile",
+    "update_policy",
+];
 exports.AGENT_ATTRIBUTE_KEY_ORDER = {
-    spec: [
-        "version",
-        "spec_kind",
-        "role",
-        "runtime_mode",
-        "work_contracts",
-        "requested_capabilities",
-        "skill_refs",
-        "tool_refs",
-        "model_refs",
-        "wasm_component_refs",
-        "runtime_image_refs",
-        "subagent_refs",
-        "resource_profile",
-        "update_policy",
-    ],
+    manifest: MANIFEST_ATTRIBUTE_KEYS,
+    spec: MANIFEST_ATTRIBUTE_KEYS,
     work: [
         "version",
         "agent_id",
@@ -207,9 +215,39 @@ function formatError(filePath, message) {
 function isAgentFileType(type) {
     return exports.AGENT_FILE_TYPES.includes(type);
 }
+function isManifestSemanticType(type) {
+    return type === "manifest" || type === "spec";
+}
+function collectManifestSiblingConflicts(filePaths, formatDir) {
+    const basenamesByDir = new Map();
+    for (const filePath of filePaths) {
+        const basename = path_1.default.basename(filePath);
+        if (basename !== exports.CANONICAL_MANIFEST_BASENAME && basename !== exports.LEGACY_SPEC_BASENAME) {
+            continue;
+        }
+        const dirPath = path_1.default.dirname(filePath);
+        const basenames = basenamesByDir.get(dirPath) ?? new Set();
+        basenames.add(basename);
+        basenamesByDir.set(dirPath, basenames);
+    }
+    const conflicts = [];
+    for (const [dirPath, basenames] of Array.from(basenamesByDir.entries()).sort()) {
+        if (basenames.has(exports.CANONICAL_MANIFEST_BASENAME) && basenames.has(exports.LEGACY_SPEC_BASENAME)) {
+            conflicts.push(`${formatDir(dirPath)}: MANIFEST.md and SPEC.md cannot both exist in the same logical Omni unit; keep MANIFEST.md and remove the legacy SPEC.md alias`);
+        }
+    }
+    return conflicts;
+}
 function validateAgentFileName(type, filePath) {
+    const basename = path_1.default.basename(filePath);
+    if (type === "spec" && basename === exports.CANONICAL_MANIFEST_BASENAME) {
+        return;
+    }
     const expected = exports.AGENT_FILE_BASENAMES[type];
-    if (path_1.default.basename(filePath) !== expected) {
+    if (basename !== expected) {
+        if (isManifestSemanticType(type)) {
+            throw formatError(filePath, `manifest files must be named MANIFEST.md (canonical) or SPEC.md (legacy alias); ${type} files must be named ${expected}`);
+        }
         throw formatError(filePath, `${type} files must be named ${expected}`);
     }
 }
@@ -303,7 +341,7 @@ function validateSpecKind(value, filePath) {
     }
     const route = DOCUMENTATION_ONLY_SPEC_KIND_ROUTES[value];
     if (route) {
-        throw formatError(filePath, `spec_kind ${value} is documentation-only; ${route}. SPEC.md must define a reusable invocable capability surface.`);
+        throw formatError(filePath, `spec_kind ${value} is documentation-only; ${route}. MANIFEST.md must define a reusable invocable capability surface; legacy SPEC.md follows the same contract.`);
     }
     throw formatError(filePath, `spec_kind must be one of ${Array.from(SPEC_KIND_VALUES).join(", ")}; documentation-only records belong in normal mdkg nodes such as task, test, epic, goal, checkpoint, EDD, PRD, DEC, bug, feedback, dispute, or proposal.`);
 }
@@ -398,6 +436,7 @@ function validateAgentFrontmatter(type, frontmatter, filePath) {
     const version = expectString(frontmatter, "version", filePath);
     requireSemver(version, "version", filePath);
     switch (type) {
+        case "manifest":
         case "spec": {
             const specKind = optionalString(frontmatter, "spec_kind", filePath);
             if (specKind) {

package/dist/graph/capabilities_indexer.js

@@ -10,6 +10,7 @@ const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const indexer_1 = require("./indexer");
+const agent_file_types_1 = require("./agent_file_types");
 const skills_indexer_1 = require("./skills_indexer");
 exports.CAPABILITIES_INDEX_RELATIVE_PATH = ".mdkg/index/capabilities.json";
 exports.CAPABILITY_KINDS = ["skill", "spec", "work", "core", "design"];
@@ -41,7 +42,7 @@ function workspaceMdkgPrefix(entry) {
     return `${wsPath}${mdkgDir}/`;
 }
 function classifyNodeCapability(node, config) {
-    if (node.type === "spec") {
+    if ((0, agent_file_types_1.isManifestSemanticType)(node.type)) {
         return "spec";
     }
     if (node.type === "work") {
@@ -115,7 +116,7 @@ function resolveWorkSpecs(index, workNode) {
     const candidates = new Map();
     const workRefs = nodeRefSet(workNode);
     for (const node of Object.values(index.nodes)) {
-        if (node.type !== "spec" || node.ws !== workNode.ws) {
+        if (!(0, agent_file_types_1.isManifestSemanticType)(node.type) || node.ws !== workNode.ws) {
             continue;
         }
         const agentId = typeof workNode.attributes.agent_id === "string" ? workNode.attributes.agent_id : undefined;
@@ -159,9 +160,49 @@ function buildCapabilityLinkage(index, node, kind) {
         receipt_qids: receipts.map((receiptNode) => receiptNode.qid),
     };
 }
+function manifestCapabilityMetadata(node) {
+    if (!(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
+        return undefined;
+    }
+    const sourceBasename = path_1.default.posix.basename(node.path);
+    const compatibilityMode = sourceBasename === agent_file_types_1.LEGACY_SPEC_BASENAME
+        ? "legacy"
+        : node.type === "spec"
+            ? "transitional"
+            : "canonical";
+    return {
+        semantic_kind: "manifest",
+        source_basename: sourceBasename,
+        source_type: node.type,
+        canonical_basename: agent_file_types_1.CANONICAL_MANIFEST_BASENAME,
+        legacy_basename: agent_file_types_1.LEGACY_SPEC_BASENAME,
+        compatibility_mode: compatibilityMode,
+        legacy: compatibilityMode !== "canonical",
+        deprecated: compatibilityMode !== "canonical",
+        command_family: "manifest",
+        legacy_command_family: "spec",
+    };
+}
+function manifestSearchAliases(metadata) {
+    if (!metadata) {
+        return [];
+    }
+    return [
+        "manifest",
+        "manifest.md",
+        "MANIFEST.md",
+        "manifest capability",
+        "MANIFEST.md legacy SPEC.md",
+        "spec.md compatibility alias",
+        "legacy spec.md",
+        metadata.compatibility_mode,
+        metadata.source_basename,
+    ];
+}
 function nodeCapabilityRecord(root, config, index, node, kind, indexedAt) {
     const absolutePath = path_1.default.resolve(root, node.path);
     const content = fs_1.default.readFileSync(absolutePath, "utf8");
+    const manifest = kind === "spec" ? manifestCapabilityMetadata(node) : undefined;
     const record = {
         kind,
         workspace: node.ws,
@@ -172,7 +213,7 @@ function nodeCapabilityRecord(root, config, index, node, kind, indexedAt) {
         title: node.title,
         tags: [...node.tags],
         refs: [...node.refs],
-        aliases: [...node.aliases],
+        aliases: Array.from(new Set([...node.aliases, ...manifestSearchAliases(manifest)])),
         links: [...node.links],
         artifacts: [...node.artifacts],
         updated: node.updated,
@@ -182,6 +223,7 @@ function nodeCapabilityRecord(root, config, index, node, kind, indexedAt) {
         node_type: node.type,
     };
     if (kind === "spec") {
+        record.manifest = manifest;
         record.spec = pickAttributes(node.attributes, [
             "version",
             "spec_kind",

package/dist/graph/edges.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractEdges = extractEdges;
 const id_1 = require("../util/id");
+const refs_1 = require("../util/refs");
 function formatError(filePath, key, message) {
     return new Error(`${filePath}: ${key} ${message}`);
 }
@@ -18,6 +19,12 @@ function normalizeIdRef(value, filePath, key, options) {
     }
     return normalized;
 }
+function normalizeSemanticRef(value, filePath, key) {
+    if (!(0, refs_1.validatePortableOrUriRef)(value)) {
+        throw formatError(filePath, key, `invalid semantic reference: ${value}`);
+    }
+    return value.includes("://") ? value : value.toLowerCase();
+}
 function readString(fm, key) {
     const value = fm[key];
     if (value === undefined) {
@@ -46,10 +53,18 @@ function extractEdges(frontmatter, filePath, options = {}) {
     const relates = readStringList(frontmatter, "relates") ?? [];
     const blocked_by = readStringList(frontmatter, "blocked_by") ?? [];
     const blocks = readStringList(frontmatter, "blocks") ?? [];
+    const context_refs = options.includeSemanticRefs
+        ? readStringList(frontmatter, "context_refs") ?? []
+        : [];
+    const evidence_refs = options.includeSemanticRefs
+        ? readStringList(frontmatter, "evidence_refs") ?? []
+        : [];
     const edges = {
         relates: relates.map((value) => normalizeIdRef(value, filePath, "relates", options)),
         blocked_by: blocked_by.map((value) => normalizeIdRef(value, filePath, "blocked_by", options)),
         blocks: blocks.map((value) => normalizeIdRef(value, filePath, "blocks", options)),
+        context_refs: context_refs.map((value) => normalizeSemanticRef(value, filePath, "context_refs")),
+        evidence_refs: evidence_refs.map((value) => normalizeSemanticRef(value, filePath, "evidence_refs")),
     };
     if (epic) {
         edges.epic = normalizeIdRef(epic, filePath, "epic", options);

package/dist/graph/frontmatter.js

@@ -8,12 +8,14 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "id",
     "type",
     "title",
+    "checkpoint_kind",
     "status",
     "priority",
     "goal_state",
     "goal_condition",
     "scope_refs",
     "active_node",
+    "last_active_node",
     "required_skills",
     "required_checks",
     "max_iterations",
@@ -60,7 +62,6 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "severity",
     "proposal_status",
     "proposal_kind",
-    "evidence_refs",
     "archive_kind",
     "source_path",
     "stored_path",
@@ -89,6 +90,8 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "blocked_by",
     "blocks",
     "refs",
+    "context_refs",
+    "evidence_refs",
     "aliases",
     "skills",
     "cases",

package/dist/graph/indexer.js

@@ -10,6 +10,7 @@ const node_1 = require("./node");
 const workspace_files_1 = require("./workspace_files");
 const validate_graph_1 = require("./validate_graph");
 const template_schema_1 = require("./template_schema");
+const agent_file_types_1 = require("./agent_file_types");
 function normalizeEdgeTarget(value, ws) {
     if (value.includes(":")) {
         return value;
@@ -25,6 +26,8 @@ function normalizeEdges(edges, ws) {
         relates: edges.relates.map((value) => normalizeEdgeTarget(value, ws)),
         blocked_by: edges.blocked_by.map((value) => normalizeEdgeTarget(value, ws)),
         blocks: edges.blocks.map((value) => normalizeEdgeTarget(value, ws)),
+        context_refs: (edges.context_refs ?? []).map((value) => normalizeEdgeTarget(value, ws)),
+        evidence_refs: (edges.evidence_refs ?? []).map((value) => normalizeEdgeTarget(value, ws)),
     };
 }
 function addReverseEdge(reverse, edgeKey, target, source) {
@@ -46,6 +49,10 @@ function buildIndex(root, config, options = {}) {
     for (const alias of workspaceAliases) {
         idsByWorkspace[alias] = new Set();
         const files = docFilesByAlias[alias];
+        const manifestConflicts = (0, agent_file_types_1.collectManifestSiblingConflicts)(files, (dirPath) => path_1.default.relative(root, dirPath).split(path_1.default.sep).join("/") || ".");
+        if (manifestConflicts.length > 0 && !tolerant) {
+            throw new Error(manifestConflicts[0]);
+        }
         for (const filePath of files) {
             if (path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core") {
                 continue;
@@ -118,6 +125,12 @@ function buildIndex(root, config, options = {}) {
         for (const target of edges.blocks) {
             addReverseEdge(reverse_edges, "blocks", target, qid);
         }
+        for (const target of edges.context_refs ?? []) {
+            addReverseEdge(reverse_edges, "context_refs", target, qid);
+        }
+        for (const target of edges.evidence_refs ?? []) {
+            addReverseEdge(reverse_edges, "evidence_refs", target, qid);
+        }
     }
     for (const edgeKey of Object.keys(reverse_edges)) {
         for (const target of Object.keys(reverse_edges[edgeKey])) {

package/dist/graph/node.js

@@ -37,6 +37,7 @@ const GOAL_ATTRIBUTE_KEYS = [
     "goal_condition",
     "scope_refs",
     "active_node",
+    "last_active_node",
     "required_skills",
     "required_checks",
     "max_iterations",
@@ -180,6 +181,13 @@ function validateGoalFrontmatter(type, frontmatter, filePath) {
             throw formatError(filePath, "active_node must be a local id or qid");
         }
     }
+    const lastActiveNode = optionalString(frontmatter, "last_active_node", filePath);
+    if (lastActiveNode !== undefined) {
+        const normalized = requireLowercase(lastActiveNode, "last_active_node", filePath);
+        if (!(0, id_1.isPortableIdRef)(normalized)) {
+            throw formatError(filePath, "last_active_node must be a local id or qid");
+        }
+    }
     const scopeRefs = optionalList(frontmatter, "scope_refs", filePath);
     for (const [index, value] of scopeRefs.entries()) {
         if (typeof value !== "string" || value.trim().length === 0) {
@@ -334,7 +342,10 @@ function parseNode(content, filePath, options) {
             throw formatError(filePath, "supersedes must be a dec-# id");
         }
     }
-    const edges = (0, edges_1.extractEdges)(frontmatter, filePath, { allowPortableRefs: true });
+    const edges = (0, edges_1.extractEdges)(frontmatter, filePath, {
+        allowPortableRefs: true,
+        includeSemanticRefs: exports.WORK_TYPES.has(type),
+    });
     const attributes = {
         ...extractGoalAttributes(type, frontmatter),
         ...(0, agent_file_types_1.extractAgentAttributes)(type, frontmatter),

package/dist/graph/sqlite_index.js

@@ -205,6 +205,8 @@ function writeSqliteIndex(options) {
                 ["relates", node.edges.relates],
                 ["blocked_by", node.edges.blocked_by],
                 ["blocks", node.edges.blocks],
+                ["context_refs", node.edges.context_refs ?? []],
+                ["evidence_refs", node.edges.evidence_refs ?? []],
             ]) {
                 for (const target of values) {
                     insertEdge.run(node.qid, kind, target);

package/dist/graph/subgraphs.js

@@ -278,6 +278,8 @@ function projectOneSubgraph(root, alias, subgraph) {
                         relates: remapTargets(node.edges.relates, qidMap),
                         blocked_by: remapTargets(node.edges.blocked_by, qidMap),
                         blocks: remapTargets(node.edges.blocks, qidMap),
+                        context_refs: remapTargets(node.edges.context_refs ?? [], qidMap),
+                        evidence_refs: remapTargets(node.edges.evidence_refs ?? [], qidMap),
                     },
                     source: {
                         imported: true,

package/dist/graph/template_schema.js

@@ -9,6 +9,9 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const frontmatter_1 = require("./frontmatter");
 const builtin_1 = require("../templates/builtin");
+const TEMPLATE_SCHEMA_ALIASES = {
+    spec: "manifest",
+};
 function listMarkdownFiles(dir) {
     if (!fs_1.default.existsSync(dir)) {
         return [];
@@ -46,6 +49,34 @@ function addKeyToSchema(schema, key, kind, filePath) {
         schema.listKeys.add(key);
     }
 }
+function cloneSchema(schema, type) {
+    return {
+        type,
+        allowedKeys: new Set(schema.allowedKeys),
+        keyKinds: { ...schema.keyKinds },
+        listKeys: new Set(schema.listKeys),
+    };
+}
+function loadBundledSchema(type) {
+    const bundledPath = (0, builtin_1.requireBundledTemplatePath)(type);
+    const content = fs_1.default.readFileSync(bundledPath, "utf8");
+    const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, bundledPath);
+    const typeValue = frontmatter.type;
+    if (typeValue !== type) {
+        throw new Error(`bundled template fallback type mismatch for ${type}: ${bundledPath}`);
+    }
+    const schema = {
+        type,
+        allowedKeys: new Set(),
+        keyKinds: {},
+        listKeys: new Set(),
+    };
+    for (const [key, value] of Object.entries(frontmatter)) {
+        const kind = getValueKind(value);
+        addKeyToSchema(schema, key, kind, bundledPath);
+    }
+    return schema;
+}
 function loadTemplateSchemas(root, config, requiredTypes) {
     return loadTemplateSchemasWithInfo(root, config, requiredTypes).schemas;
 }
@@ -84,24 +115,13 @@ function loadTemplateSchemasWithInfo(root, config, requiredTypes) {
     if (requiredTypes) {
         const required = Array.from(requiredTypes, (value) => value.toLowerCase());
         for (const missingType of required.filter((value) => !schemas[value])) {
-            const bundledPath = (0, builtin_1.requireBundledTemplatePath)(missingType);
-            const content = fs_1.default.readFileSync(bundledPath, "utf8");
-            const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, bundledPath);
-            const typeValue = frontmatter.type;
-            if (typeValue !== missingType) {
-                throw new Error(`bundled template fallback type mismatch for ${missingType}: ${bundledPath}`);
-            }
-            const schema = {
-                type: missingType,
-                allowedKeys: new Set(),
-                keyKinds: {},
-                listKeys: new Set(),
-            };
-            schemas[missingType] = schema;
-            for (const [key, value] of Object.entries(frontmatter)) {
-                const kind = getValueKind(value);
-                addKeyToSchema(schema, key, kind, bundledPath);
+            const aliasType = TEMPLATE_SCHEMA_ALIASES[missingType];
+            if (aliasType) {
+                const aliasSchema = schemas[aliasType] ?? loadBundledSchema(aliasType);
+                schemas[missingType] = cloneSchema(aliasSchema, missingType);
+                continue;
             }
+            schemas[missingType] = loadBundledSchema(missingType);
             fallbackTypes.push(missingType);
         }
     }

package/dist/graph/validate_graph.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectGraphErrors = collectGraphErrors;
 exports.validateGraph = validateGraph;
+const agent_file_types_1 = require("./agent_file_types");
 const refs_1 = require("../util/refs");
+const qid_1 = require("../util/qid");
 const goal_scope_1 = require("./goal_scope");
 function pushError(errors, message) {
     if (errors) {
@@ -19,6 +21,8 @@ function validateEdgeTargets(index, allowMissing, knownSkillSlugs, externalWorks
             ["relates", edges.relates],
             ["blocked_by", edges.blocked_by],
             ["blocks", edges.blocks],
+            ["context_refs", edges.context_refs ?? []],
+            ["evidence_refs", edges.evidence_refs ?? []],
         ];
         if (edges.epic) {
             edgeLists.push(["epic", [edges.epic]]);
@@ -34,6 +38,9 @@ function validateEdgeTargets(index, allowMissing, knownSkillSlugs, externalWorks
         }
         for (const [edgeKey, values] of edgeLists) {
             for (const value of values) {
+                if ((edgeKey === "context_refs" || edgeKey === "evidence_refs") && (0, refs_1.isUriRef)(value)) {
+                    continue;
+                }
                 const targetNode = nodes[value];
                 if (targetNode &&
                     ["epic", "parent", "prev", "next"].includes(edgeKey) &&
@@ -142,7 +149,7 @@ function validateAgentWorkflowSpecWorkContracts(index, allowMissing, errors) {
         });
     }
     for (const [qid, node] of Object.entries(index.nodes)) {
-        if (node.type !== "spec") {
+        if (!(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
             continue;
         }
         const workContracts = node.attributes.work_contracts;
@@ -228,7 +235,7 @@ function validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, external
 function buildSpecRolesByWorkspace(index) {
     const specRolesByWorkspace = {};
     for (const node of Object.values(index.nodes)) {
-        if (node.type !== "spec") {
+        if (!(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
             continue;
         }
         if (!specRolesByWorkspace[node.ws]) {
@@ -242,8 +249,12 @@ function buildSpecRolesByWorkspace(index) {
     return specRolesByWorkspace;
 }
 function resolveSpecRole(index, ws, value) {
-    const node = resolveTypedNodeRef(index, ws, value, "spec");
-    if (!node) {
+    const resolved = (0, qid_1.resolveQid)(index, value, ws);
+    if (resolved.status !== "ok") {
+        return undefined;
+    }
+    const node = index.nodes[resolved.qid];
+    if (!node || !(0, agent_file_types_1.isManifestSemanticType)(node.type)) {
         return undefined;
     }
     return {
@@ -254,7 +265,7 @@ function resolveSpecRole(index, ws, value) {
 function validateAgentWorkflowSubagentRefs(index, allowMissing, externalWorkspaces, errors) {
     const specRolesByWorkspace = buildSpecRolesByWorkspace(index);
     for (const [qid, node] of Object.entries(index.nodes)) {
-        if (node.type !== "spec" && node.type !== "work") {
+        if (!(0, agent_file_types_1.isManifestSemanticType)(node.type) && node.type !== "work") {
             continue;
         }
         const subagentRefs = node.attributes.subagent_refs;

package/dist/graph/visibility.js

@@ -88,6 +88,12 @@ function collectNodeStringReferences(node) {
     for (const [index, value] of node.edges.blocks.entries()) {
         values.push({ field: `blocks[${index}]`, value });
     }
+    for (const [index, value] of (node.edges.context_refs ?? []).entries()) {
+        values.push({ field: `context_refs[${index}]`, value });
+    }
+    for (const [index, value] of (node.edges.evidence_refs ?? []).entries()) {
+        values.push({ field: `evidence_refs[${index}]`, value });
+    }
     for (const [index, value] of node.links.entries()) {
         values.push({ field: `links[${index}]`, value });
     }