mdkg 0.3.5 → 0.3.7

package/dist/commands/status.js

@@ -229,6 +229,7 @@ function collectStatus(root) {
             selected_exists: selected.state === null ? null : !selectedMissing,
             selected_achieved: selected.state === null ? null : selectedAchieved,
             active_node: selectedNode?.attributes.active_node ?? null,
+            last_active_node: selectedNode?.attributes.last_active_node ?? null,
             goal_state: selectedNode?.attributes.goal_state ?? null,
             status: selectedNode?.status ?? null,
         },

package/dist/commands/task.js

@@ -297,6 +297,7 @@ function runTaskDoneCommandLocked(options) {
             ws: loaded.ws,
             relates: loaded.id,
             scope: loaded.id,
+            kind: options.checkpointKind,
             runId: options.runId,
             note: `checkpoint created from mdkg task done for ${loaded.id}`,
             now,
@@ -309,6 +310,7 @@ function runTaskDoneCommandLocked(options) {
             ws: loaded.ws,
             relates: loaded.id,
             scope: loaded.id,
+            kind: options.checkpointKind,
             runId: options.runId,
             note: `checkpoint created from mdkg task done for ${loaded.id}`,
             now,

package/dist/commands/upgrade.js

@@ -13,6 +13,8 @@ const paths_1 = require("../core/paths");
 const version_1 = require("../core/version");
 const project_db_1 = require("../core/project_db");
 const errors_1 = require("../util/errors");
+const frontmatter_1 = require("../graph/frontmatter");
+const workspace_files_1 = require("../graph/workspace_files");
 const init_manifest_1 = require("./init_manifest");
 const skill_support_1 = require("./skill_support");
 const skill_mirror_1 = require("./skill_mirror");
@@ -273,6 +275,64 @@ function migrateConfigIfNeeded(root, dryRun, summary, changes) {
         writeFile(cfgPath, `${JSON.stringify(nextConfig.config, null, 2)}\n`);
     }
 }
+function migrateClosedGoalActiveNodes(root, dryRun, summary, changes) {
+    const config = (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(JSON.parse(fs_1.default.readFileSync((0, paths_1.configPath)(root), "utf8"))).config);
+    const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(root, config);
+    let planned = 0;
+    for (const files of Object.values(filesByAlias)) {
+        for (const filePath of files) {
+            const content = fs_1.default.readFileSync(filePath, "utf8");
+            let parsed;
+            try {
+                parsed = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+            }
+            catch {
+                continue;
+            }
+            const frontmatter = { ...parsed.frontmatter };
+            if (frontmatter.type !== "goal") {
+                continue;
+            }
+            const status = typeof frontmatter.status === "string" ? frontmatter.status : "";
+            const goalState = typeof frontmatter.goal_state === "string" ? frontmatter.goal_state : "";
+            const activeNode = typeof frontmatter.active_node === "string" ? frontmatter.active_node : undefined;
+            if (!activeNode || (status !== "done" && goalState !== "achieved")) {
+                continue;
+            }
+            const relativePath = path_1.default.relative(root, filePath).split(path_1.default.sep).join("/");
+            const lastActiveNode = typeof frontmatter.last_active_node === "string" ? frontmatter.last_active_node : undefined;
+            if (lastActiveNode && lastActiveNode !== activeNode) {
+                planned += 1;
+                record(summary, changes, {
+                    path: relativePath,
+                    category: "goal_lifecycle",
+                    action: "conflict",
+                    reason: `closed goal has active_node ${activeNode} but different last_active_node ${lastActiveNode}; local content preserved`,
+                });
+                continue;
+            }
+            planned += 1;
+            record(summary, changes, {
+                path: relativePath,
+                category: "goal_lifecycle",
+                action: "migrate",
+                reason: "move closed goal active_node to last_active_node",
+            });
+            if (!dryRun) {
+                if (!lastActiveNode) {
+                    frontmatter.last_active_node = activeNode;
+                }
+                delete frontmatter.active_node;
+                const frontmatterBlock = ["---", ...(0, frontmatter_1.formatFrontmatter)(frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER), "---"].join("\n");
+                const body = parsed.body.length > 0 ? parsed.body : "";
+                writeFile(filePath, body.length > 0 ? `${frontmatterBlock}\n${body}` : frontmatterBlock);
+            }
+        }
+    }
+    if (planned === 0) {
+        summary.unchanged += 1;
+    }
+}
 function isIgnoredBySimpleGitignore(root, relativePath) {
     const ignorePath = path_1.default.join(root, ".gitignore");
     if (!fs_1.default.existsSync(ignorePath)) {
@@ -440,6 +500,7 @@ function runUpgradeCommand(options) {
     const agentWorkspace = isAgentWorkspace(root);
     const managedCurrentFiles = [];
     migrateConfigIfNeeded(root, dryRun, summary, changes);
+    migrateClosedGoalActiveNodes(root, dryRun, summary, changes);
     for (const file of currentManifest.files) {
         if (!shouldIncludeFile(file, agentWorkspace)) {
             continue;

package/dist/commands/validate.js

@@ -3,13 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOMMENDED_HEADINGS = void 0;
 exports.collectValidateReceipt = collectValidateReceipt;
 exports.runValidateCommand = runValidateCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 const config_1 = require("../core/config");
 const template_schema_1 = require("../graph/template_schema");
 const node_1 = require("../graph/node");
+const agent_file_types_1 = require("../graph/agent_file_types");
 const skills_indexer_1 = require("../graph/skills_indexer");
 const workspace_files_1 = require("../graph/workspace_files");
 const validate_graph_1 = require("../graph/validate_graph");
@@ -18,7 +21,7 @@ const visibility_1 = require("../graph/visibility");
 const sqlite_index_1 = require("../graph/sqlite_index");
 const errors_1 = require("../util/errors");
 const skill_mirror_1 = require("./skill_mirror");
-const RECOMMENDED_HEADINGS = {
+exports.RECOMMENDED_HEADINGS = {
     task: [
         "Overview",
         "Acceptance Criteria",
@@ -103,6 +106,143 @@ function extractHeadings(body) {
     }
     return headings;
 }
+const RAW_CONTENT_MARKERS = [
+    { id: "raw_prompt", pattern: /\bRAW_PROMPT_MARKER\b/i, description: "raw prompt marker" },
+    { id: "raw_payload", pattern: /\bRAW_PAYLOAD_MARKER\b/i, description: "raw payload marker" },
+    { id: "raw_secret", pattern: /\bRAW_SECRET_MARKER\b|BEGIN [A-Z ]*PRIVATE KEY|secret\s*=/i, description: "raw secret marker" },
+];
+function shouldCheckRawContentWarnings(node) {
+    if ((0, agent_file_types_1.isAgentFileType)(node.type)) {
+        return true;
+    }
+    return node.type === "checkpoint" && typeof node.frontmatter.checkpoint_kind === "string";
+}
+function collectRawContentWarnings(qid, node) {
+    if (!shouldCheckRawContentWarnings(node)) {
+        return [];
+    }
+    const warnings = [];
+    for (const marker of RAW_CONTENT_MARKERS) {
+        if (marker.pattern.test(node.body)) {
+            warnings.push(`${qid}: raw-content.${marker.id} warning: ${marker.description} detected; use refs, hashes, summaries, or artifact links instead of raw secrets/prompts/payloads`);
+        }
+    }
+    return warnings;
+}
+function collectChangedPaths(root) {
+    const result = (0, child_process_1.spawnSync)("git", ["-C", root, "status", "--porcelain", "--", ".mdkg"], {
+        encoding: "utf8",
+    });
+    if (result.status !== 0) {
+        return new Set();
+    }
+    const changed = new Set();
+    for (const line of result.stdout.split(/\r?\n/)) {
+        if (!line.trim()) {
+            continue;
+        }
+        const rawPath = line.slice(3).trim();
+        const filePath = rawPath.includes(" -> ") ? rawPath.split(" -> ").pop() ?? rawPath : rawPath;
+        changed.add(filePath.replace(/\\/g, "/"));
+    }
+    return changed;
+}
+function qidFromWarning(message) {
+    const match = /^([a-z0-9_-]+:[^\s:]+):/.exec(message);
+    return match?.[1];
+}
+function warningPath(message, nodes) {
+    const qid = qidFromWarning(message);
+    if (qid && nodes[qid]) {
+        return nodes[qid].path;
+    }
+    for (const node of Object.values(nodes)) {
+        if (message.includes(node.path)) {
+            return node.path;
+        }
+    }
+    const match = /([.]mdkg\/[^\s:]+\.md|[.]mdkg\/[^\s:]+\/SKILLS?\.md)/.exec(message);
+    return match?.[1];
+}
+function warningDiagnostic(message, nodes) {
+    const qid = qidFromWarning(message);
+    const pathValue = warningPath(message, nodes);
+    const rawMatch = /raw-content\.([a-z_]+)/.exec(message);
+    if (rawMatch) {
+        return {
+            id: `raw-content.${rawMatch[1]}`,
+            category: "raw-content",
+            severity: "warning",
+            message,
+            qid,
+            path: pathValue,
+            ref: qid,
+            remediation: "Replace raw secrets, prompts, tokens, or payloads with refs, hashes, redacted summaries, or archive/artifact links.",
+        };
+    }
+    if (message.includes("missing recommended heading")) {
+        return {
+            id: "heading.missing",
+            category: "headings",
+            severity: "warning",
+            message,
+            qid,
+            path: pathValue,
+            ref: qid,
+            remediation: "Run mdkg format --headings --dry-run to review missing heading additions, then --apply if acceptable.",
+        };
+    }
+    if (message.includes("bundled template schema fallback")) {
+        return {
+            id: "template_schema.fallback",
+            category: "templates",
+            severity: "warning",
+            message,
+            path: pathValue,
+            remediation: "Run mdkg upgrade --apply to vendor missing built-in template schemas when the managed asset update is safe.",
+        };
+    }
+    if (message.includes("sqlite") || message.includes("index")) {
+        return {
+            id: "cache.index",
+            category: "cache",
+            severity: "warning",
+            message,
+            path: pathValue,
+            remediation: "Run mdkg index or mdkg db index rebuild when generated cache state should be refreshed.",
+        };
+    }
+    if (message.includes("skill") || message.includes("mirror")) {
+        return {
+            id: "skill_mirror.warning",
+            category: "skills",
+            severity: "warning",
+            message,
+            path: pathValue,
+            remediation: "Run mdkg skill sync after reviewing managed skill mirror drift.",
+        };
+    }
+    if (message.includes("subgraph")) {
+        return {
+            id: "subgraph.warning",
+            category: "subgraph",
+            severity: "warning",
+            message,
+            path: pathValue,
+            remediation: "Run mdkg subgraph verify or refresh the source bundle after reviewing child graph freshness.",
+        };
+    }
+    return {
+        id: "warning.generic",
+        category: "general",
+        severity: "warning",
+        message,
+        qid,
+        path: pathValue,
+        ref: qid,
+        remediation: "Review the warning and apply the focused mdkg command suggested by the message when appropriate.",
+    };
+}
 function isCoreListFile(filePath) {
     return path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core";
 }
@@ -121,6 +261,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 buildIndexNode(root, ws, filePath, node) {
@@ -178,6 +320,12 @@ function buildReverseEdges(nodes) {
         for (const target of node.edges.blocks) {
             addReverseEdge(reverse, "blocks", target, qid);
         }
+        for (const target of node.edges.context_refs ?? []) {
+            addReverseEdge(reverse, "context_refs", target, qid);
+        }
+        for (const target of node.edges.evidence_refs ?? []) {
+            addReverseEdge(reverse, "evidence_refs", target, qid);
+        }
     }
     for (const targets of Object.values(reverse)) {
         for (const sources of Object.values(targets)) {
@@ -292,7 +440,7 @@ function collectValidateReceipt(options) {
                 idsByWorkspace[alias].set(node.id, filePath);
                 const qid = `${alias}:${node.id}`;
                 nodes[qid] = buildIndexNode(options.root, alias, filePath, node);
-                const recommended = RECOMMENDED_HEADINGS[node.type];
+                const recommended = exports.RECOMMENDED_HEADINGS[node.type];
                 if (recommended) {
                     const headings = extractHeadings(node.body);
                     for (const heading of recommended) {
@@ -301,6 +449,7 @@ function collectValidateReceipt(options) {
                         }
                     }
                 }
+                warnings.push(...collectRawContentWarnings(qid, node));
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : "unknown error";
@@ -372,7 +521,13 @@ function collectValidateReceipt(options) {
     }
     warnings.push(...(0, skill_mirror_1.auditSkillMirrors)(options.root, config));
     validateEventsJsonl(options.root, config, errors);
-    const uniqueWarnings = Array.from(new Set(warnings));
+    const allUniqueWarnings = Array.from(new Set(warnings));
+    const allWarningDiagnostics = allUniqueWarnings.map((warning) => warningDiagnostic(warning, nodes));
+    const changedPaths = options.changedOnly ? collectChangedPaths(options.root) : new Set();
+    const filteredWarningDiagnostics = options.changedOnly
+        ? allWarningDiagnostics.filter((warning) => warning.path !== undefined && changedPaths.has(warning.path))
+        : allWarningDiagnostics;
+    const uniqueWarnings = filteredWarningDiagnostics.map((warning) => warning.message);
     const uniqueErrors = Array.from(new Set(errors));
     const reportLines = [
         ...uniqueWarnings.map((warning) => `warning: ${warning}`),
@@ -390,8 +545,12 @@ function collectValidateReceipt(options) {
         warning_count: uniqueWarnings.length,
         error_count: uniqueErrors.length,
         warnings: uniqueWarnings,
+        warning_diagnostics: filteredWarningDiagnostics,
         errors: uniqueErrors,
         ...(outPath ? { report_path: outPath } : {}),
+        ...(options.changedOnly
+            ? { warning_filter: { mode: "changed-only", changed_paths: Array.from(changedPaths).sort() } }
+            : {}),
     };
     return receipt;
 }

package/dist/commands/work.js

@@ -11,6 +11,7 @@ exports.runWorkTriggerCommand = runWorkTriggerCommand;
 exports.runWorkReceiptNewCommand = runWorkReceiptNewCommand;
 exports.runWorkReceiptUpdateCommand = runWorkReceiptUpdateCommand;
 exports.runWorkReceiptVerifyCommand = runWorkReceiptVerifyCommand;
+exports.runWorkValidateCommand = runWorkValidateCommand;
 exports.runWorkArtifactAddCommand = runWorkArtifactAddCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -34,11 +35,15 @@ const archive_1 = require("./archive");
 const project_db_1 = require("../core/project_db");
 const project_db_migrations_1 = require("../core/project_db_migrations");
 const project_db_queue_1 = require("../core/project_db_queue");
+const validate_1 = require("./validate");
+const query_output_1 = require("./query_output");
+const workspace_files_1 = require("../graph/workspace_files");
 const PRICING_MODELS = new Set(["free", "included", "quoted", "fixed", "metered", "subscription"]);
 const ORDER_STATUSES = new Set(["submitted", "accepted", "running", "completed", "cancelled", "failed"]);
 const RECEIPT_STATUSES = new Set(["recorded", "verified", "rejected", "superseded"]);
 const OUTCOMES = new Set(["success", "partial", "failure"]);
 const REDACTION_POLICIES = new Set(["refs_and_hashes_only", "redacted_summary", "external_private"]);
+const WORKFLOW_VALIDATE_TYPES = new Set(agent_file_types_1.AGENT_FILE_TYPES);
 function parseCsvList(raw) {
     if (!raw) {
         return [];
@@ -210,6 +215,162 @@ function resolveReadableWorkNode(index, idOrQid, ws, type, label) {
     }
     return node;
 }
+function normalizeWorkflowValidateType(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = value.toLowerCase();
+    if (!WORKFLOW_VALIDATE_TYPES.has(normalized)) {
+        throw new errors_1.UsageError(`--type must be one of ${agent_file_types_1.AGENT_FILE_TYPES.join(", ")}`);
+    }
+    return normalized;
+}
+function isWorkflowNode(node) {
+    return WORKFLOW_VALIDATE_TYPES.has(node.type);
+}
+function resolveWorkflowTarget(index, idOrQid, ws) {
+    const resolved = (0, qid_1.resolveQid)(index, idOrQid, ws);
+    if (resolved.status !== "ok") {
+        throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("workflow record", idOrQid, resolved, ws));
+    }
+    const node = index.nodes[resolved.qid];
+    if (!node || !isWorkflowNode(node)) {
+        throw new errors_1.NotFoundError(`workflow record not found: ${idOrQid}`);
+    }
+    return node;
+}
+function workflowDiagnosticCode(message) {
+    const rawMatch = /raw-content\.([a-z_]+)/.exec(message);
+    if (rawMatch) {
+        return `raw-content.${rawMatch[1]}`;
+    }
+    if (message.includes("missing recommended heading")) {
+        return "heading.missing";
+    }
+    if (message.includes("references missing") || message.includes("references missing node")) {
+        return "reference.missing";
+    }
+    if (message.includes("must be named")) {
+        return "schema.basename";
+    }
+    if (message.includes("must be") || message.includes("is required")) {
+        return "schema.invalid";
+    }
+    if (message.includes("visibility:")) {
+        return "visibility.policy";
+    }
+    return "validation.message";
+}
+function workflowDiagnosticQid(message, nodes) {
+    for (const node of nodes) {
+        if (message.includes(node.qid) || message.includes(node.path)) {
+            return node.qid;
+        }
+    }
+    return undefined;
+}
+function workflowCandidatePaths(options) {
+    const values = new Set();
+    if (options.target) {
+        values.add(options.target.path);
+        values.add(path_1.default.resolve(options.root, options.target.path));
+        return Array.from(values);
+    }
+    const basenames = options.type
+        ? new Set([agent_file_types_1.AGENT_FILE_BASENAMES[options.type]])
+        : new Set(Object.values(agent_file_types_1.AGENT_FILE_BASENAMES));
+    const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(options.root, options.config);
+    for (const [alias, files] of Object.entries(filesByAlias)) {
+        if (options.ws !== "root" && alias !== options.ws) {
+            continue;
+        }
+        for (const filePath of files) {
+            if (!basenames.has(path_1.default.basename(filePath))) {
+                continue;
+            }
+            values.add(filePath);
+            values.add(path_1.default.relative(options.root, filePath).split(path_1.default.sep).join("/"));
+        }
+    }
+    return Array.from(values);
+}
+function filterWorkflowMessages(messages, nodes, candidatePaths) {
+    if (nodes.length === 0 && candidatePaths.length === 0) {
+        return [];
+    }
+    return messages.filter((message) => nodes.some((node) => message.includes(node.qid) || message.includes(node.path)) ||
+        candidatePaths.some((filePath) => message.includes(filePath)));
+}
+function buildWorkValidateReceipt(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const ws = normalizeWorkspace(options.ws);
+    const { index } = (0, index_cache_1.loadIndex)({ root: options.root, config, tolerant: true });
+    const type = normalizeWorkflowValidateType(options.type);
+    let targets;
+    let target;
+    if (options.id) {
+        target = resolveWorkflowTarget(index, options.id, ws);
+        if (type && target.type !== type) {
+            throw new errors_1.UsageError(`workflow record ${target.qid} is ${target.type}, not ${type}`);
+        }
+        targets = [target];
+    }
+    else {
+        targets = Object.values(index.nodes)
+            .filter((node) => isWorkflowNode(node) && (!type || node.type === type))
+            .sort((a, b) => a.qid.localeCompare(b.qid));
+    }
+    const candidatePaths = workflowCandidatePaths({ root: options.root, config, ws, type, target });
+    const validation = (0, validate_1.collectValidateReceipt)({ root: options.root });
+    const warnings = filterWorkflowMessages(validation.warnings, targets, candidatePaths);
+    const errors = filterWorkflowMessages(validation.errors, targets, candidatePaths);
+    const diagnostics = [
+        ...warnings.map((message) => ({
+            severity: "warning",
+            code: workflowDiagnosticCode(message),
+            message,
+            qid: workflowDiagnosticQid(message, targets),
+        })),
+        ...errors.map((message) => ({
+            severity: "error",
+            code: workflowDiagnosticCode(message),
+            message,
+            qid: workflowDiagnosticQid(message, targets),
+        })),
+    ];
+    return {
+        action: "work.validate",
+        ok: errors.length === 0,
+        type: type ?? "all",
+        ...(target ? { target: (0, query_output_1.toNodeSummaryJson)(target) } : {}),
+        checked_count: target ? 1 : candidatePaths.filter((value) => !path_1.default.isAbsolute(value)).length,
+        nodes: targets.map((node) => (0, query_output_1.toNodeSummaryJson)(node)),
+        warning_count: warnings.length,
+        error_count: errors.length,
+        warnings,
+        errors,
+        diagnostics,
+    };
+}
+function printWorkValidateReceipt(receipt, json) {
+    if (json) {
+        (0, query_output_1.writeJson)(receipt);
+        if (!receipt.ok) {
+            throw new errors_1.ValidationError(`workflow validation failed with ${receipt.error_count} error(s)`);
+        }
+        return;
+    }
+    for (const warning of receipt.warnings) {
+        console.error(`warning: ${warning}`);
+    }
+    if (!receipt.ok) {
+        for (const error of receipt.errors) {
+            console.error(error);
+        }
+        throw new errors_1.ValidationError(`workflow validation failed with ${receipt.error_count} error(s)`);
+    }
+    console.log(`workflow validation ok: ${receipt.checked_count} file(s)`);
+}
 function resolveTriggerWorkNode(index, ws, refRaw) {
     const ref = normalizePortableIdRef(refRaw, "<work-or-capability-ref>");
     const resolved = (0, qid_1.resolveQid)(index, ref, ws);
@@ -943,6 +1104,9 @@ function runWorkReceiptUpdateCommand(options) {
 function runWorkReceiptVerifyCommand(options) {
     return runWorkReceiptVerifyCommandLocked(options);
 }
+function runWorkValidateCommand(options) {
+    return printWorkValidateReceipt(buildWorkValidateReceipt(options), options.json);
+}
 function runWorkArtifactAddCommand(options) {
     return withWorkLock(options.root, () => runWorkArtifactAddCommandLocked(options));
 }

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/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);