mdkg 0.0.7 → 0.0.9

package/dist/graph/validate_graph.js

@@ -9,7 +9,7 @@ function pushError(errors, message) {
     }
     throw new Error(message);
 }
-function validateEdgeTargets(index, allowMissing, errors) {
+function validateEdgeTargets(index, allowMissing, knownSkillSlugs, errors) {
     const nodes = index.nodes;
     for (const [qid, node] of Object.entries(nodes)) {
         const edges = node.edges;
@@ -33,6 +33,12 @@ function validateEdgeTargets(index, allowMissing, errors) {
         for (const [edgeKey, values] of edgeLists) {
             for (const value of values) {
                 if (!nodes[value]) {
+                    if (edgeKey === "relates" &&
+                        node.type === "proposal" &&
+                        node.attributes.proposal_kind === "skill_update" &&
+                        validateSkillRef(qid, edgeKey, value, knownSkillSlugs, allowMissing, errors)) {
+                        continue;
+                    }
                     if (allowMissing) {
                         continue;
                     }
@@ -42,6 +48,25 @@ function validateEdgeTargets(index, allowMissing, errors) {
         }
     }
 }
+const SKILL_DOT_REF_RE = /^skill\.([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+function skillSlugFromDotRef(value) {
+    const localValue = value.includes(":") ? value.split(":").pop() ?? value : value;
+    return SKILL_DOT_REF_RE.exec(localValue)?.[1];
+}
+function validateSkillRef(qid, field, value, knownSkillSlugs, allowMissing, errors) {
+    const slug = skillSlugFromDotRef(value);
+    if (!slug) {
+        return false;
+    }
+    if (knownSkillSlugs === undefined || knownSkillSlugs.has(slug)) {
+        return true;
+    }
+    if (allowMissing) {
+        return true;
+    }
+    pushError(errors, `${qid}: ${field} references missing skill ${value}`);
+    return true;
+}
 function validatePrevNextSymmetry(index, _allowMissing, errors) {
     const nodes = index.nodes;
     for (const [qid, node] of Object.entries(nodes)) {
@@ -66,6 +91,274 @@ function validatePrevNextSymmetry(index, _allowMissing, errors) {
         }
     }
 }
+function normalizeDocPath(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function pathEndsWithContractRef(nodePath, contractRef) {
+    const normalizedNodePath = normalizeDocPath(nodePath);
+    const normalizedContractRef = normalizeDocPath(contractRef);
+    return (normalizedNodePath === normalizedContractRef ||
+        normalizedNodePath.endsWith(`/${normalizedContractRef}`));
+}
+function validateAgentWorkflowSpecWorkContracts(index, allowMissing, errors) {
+    const workNodesByWorkspace = {};
+    for (const node of Object.values(index.nodes)) {
+        if (node.type !== "work") {
+            continue;
+        }
+        if (!workNodesByWorkspace[node.ws]) {
+            workNodesByWorkspace[node.ws] = [];
+        }
+        workNodesByWorkspace[node.ws].push({
+            qid: node.qid,
+            path: node.path,
+            agentId: typeof node.attributes.agent_id === "string" ? node.attributes.agent_id : undefined,
+        });
+    }
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "spec") {
+            continue;
+        }
+        const workContracts = node.attributes.work_contracts;
+        if (!Array.isArray(workContracts)) {
+            continue;
+        }
+        const workspaceWorkNodes = workNodesByWorkspace[node.ws] ?? [];
+        for (const [indexValue, value] of workContracts.entries()) {
+            if (typeof value !== "string") {
+                continue;
+            }
+            const matches = workspaceWorkNodes.filter((workNode) => pathEndsWithContractRef(workNode.path, value));
+            if (matches.length === 0) {
+                if (allowMissing) {
+                    continue;
+                }
+                pushError(errors, `${qid}: work_contracts[${indexValue}] references missing WORK.md ${value}`);
+                continue;
+            }
+            if (matches.length > 1) {
+                pushError(errors, `${qid}: work_contracts[${indexValue}] ambiguously matches ${matches
+                    .map((match) => match.qid)
+                    .sort()
+                    .join(", ")}`);
+                continue;
+            }
+            const matchedWorkNode = matches[0];
+            if (matchedWorkNode.agentId !== undefined && matchedWorkNode.agentId !== node.id) {
+                pushError(errors, `${qid}: work_contracts[${indexValue}] references ${matchedWorkNode.qid} owned by agent_id ${matchedWorkNode.agentId}, not ${node.id}`);
+            }
+        }
+    }
+}
+function validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, errors) {
+    const workNodesByWorkspaceAndId = {};
+    for (const node of Object.values(index.nodes)) {
+        if (node.type !== "work") {
+            continue;
+        }
+        if (!workNodesByWorkspaceAndId[node.ws]) {
+            workNodesByWorkspaceAndId[node.ws] = {};
+        }
+        workNodesByWorkspaceAndId[node.ws][node.id] = {
+            qid: node.qid,
+            version: typeof node.attributes.version === "string" ? node.attributes.version : undefined,
+        };
+    }
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "work_order") {
+            continue;
+        }
+        const workId = node.attributes.work_id;
+        if (typeof workId !== "string") {
+            continue;
+        }
+        const workNode = workNodesByWorkspaceAndId[node.ws]?.[workId];
+        if (!workNode) {
+            if (allowMissing) {
+                continue;
+            }
+            pushError(errors, `${qid}: work_id references missing WORK.md ${workId}`);
+            continue;
+        }
+        const workVersion = node.attributes.work_version;
+        if (typeof workVersion === "string" &&
+            workNode.version !== undefined &&
+            workVersion !== workNode.version) {
+            pushError(errors, `${qid}: work_version ${workVersion} does not match ${workNode.qid} version ${workNode.version}`);
+        }
+    }
+}
+function validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, errors) {
+    const workOrderIdsByWorkspace = {};
+    for (const node of Object.values(index.nodes)) {
+        if (node.type !== "work_order") {
+            continue;
+        }
+        if (!workOrderIdsByWorkspace[node.ws]) {
+            workOrderIdsByWorkspace[node.ws] = new Set();
+        }
+        workOrderIdsByWorkspace[node.ws].add(node.id);
+    }
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "receipt") {
+            continue;
+        }
+        const workOrderId = node.attributes.work_order_id;
+        if (typeof workOrderId !== "string") {
+            continue;
+        }
+        if (workOrderIdsByWorkspace[node.ws]?.has(workOrderId)) {
+            continue;
+        }
+        if (allowMissing) {
+            continue;
+        }
+        pushError(errors, `${qid}: work_order_id references missing WORK_ORDER.md ${workOrderId}`);
+    }
+}
+function buildSpecRolesByWorkspace(index) {
+    const specRolesByWorkspace = {};
+    for (const node of Object.values(index.nodes)) {
+        if (node.type !== "spec") {
+            continue;
+        }
+        if (!specRolesByWorkspace[node.ws]) {
+            specRolesByWorkspace[node.ws] = {};
+        }
+        specRolesByWorkspace[node.ws][node.id] = {
+            qid: node.qid,
+            role: typeof node.attributes.role === "string" ? node.attributes.role : undefined,
+        };
+    }
+    return specRolesByWorkspace;
+}
+function validateAgentWorkflowSubagentRefs(index, allowMissing, errors) {
+    const specRolesByWorkspace = buildSpecRolesByWorkspace(index);
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "spec" && node.type !== "work") {
+            continue;
+        }
+        const subagentRefs = node.attributes.subagent_refs;
+        if (!Array.isArray(subagentRefs)) {
+            continue;
+        }
+        for (const [indexValue, value] of subagentRefs.entries()) {
+            if (typeof value !== "string") {
+                continue;
+            }
+            const specNode = specRolesByWorkspace[node.ws]?.[value];
+            if (!specNode) {
+                if (allowMissing) {
+                    continue;
+                }
+                pushError(errors, `${qid}: subagent_refs[${indexValue}] references missing SPEC.md ${value}`);
+                continue;
+            }
+            if (specNode.role !== undefined && specNode.role !== "subagent") {
+                pushError(errors, `${qid}: subagent_refs[${indexValue}] references ${specNode.qid} with role ${specNode.role}, not subagent`);
+            }
+        }
+    }
+}
+function validateAgentWorkflowDisputeRefs(index, allowMissing, errors) {
+    const workOrderIdsByWorkspace = {};
+    const receiptNodesByWorkspaceAndId = {};
+    for (const node of Object.values(index.nodes)) {
+        if (node.type === "work_order") {
+            if (!workOrderIdsByWorkspace[node.ws]) {
+                workOrderIdsByWorkspace[node.ws] = new Set();
+            }
+            workOrderIdsByWorkspace[node.ws].add(node.id);
+        }
+        if (node.type === "receipt") {
+            if (!receiptNodesByWorkspaceAndId[node.ws]) {
+                receiptNodesByWorkspaceAndId[node.ws] = {};
+            }
+            receiptNodesByWorkspaceAndId[node.ws][node.id] = {
+                qid: node.qid,
+                workOrderId: typeof node.attributes.work_order_id === "string"
+                    ? node.attributes.work_order_id
+                    : undefined,
+            };
+        }
+    }
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "dispute") {
+            continue;
+        }
+        const workOrderId = node.attributes.work_order_id;
+        if (typeof workOrderId !== "string") {
+            continue;
+        }
+        if (!workOrderIdsByWorkspace[node.ws]?.has(workOrderId) && !allowMissing) {
+            pushError(errors, `${qid}: work_order_id references missing WORK_ORDER.md ${workOrderId}`);
+        }
+        const receiptId = node.attributes.receipt_id;
+        if (typeof receiptId !== "string") {
+            continue;
+        }
+        const receiptNode = receiptNodesByWorkspaceAndId[node.ws]?.[receiptId];
+        if (!receiptNode) {
+            if (allowMissing) {
+                continue;
+            }
+            pushError(errors, `${qid}: receipt_id references missing RECEIPT.md ${receiptId}`);
+            continue;
+        }
+        if (receiptNode.workOrderId !== undefined && receiptNode.workOrderId !== workOrderId) {
+            pushError(errors, `${qid}: receipt_id ${receiptId} belongs to work_order_id ${receiptNode.workOrderId}, not ${workOrderId}`);
+        }
+    }
+}
+function buildNodeIdsByWorkspace(index) {
+    const nodeIdsByWorkspace = {};
+    for (const node of Object.values(index.nodes)) {
+        if (!nodeIdsByWorkspace[node.ws]) {
+            nodeIdsByWorkspace[node.ws] = new Set();
+        }
+        nodeIdsByWorkspace[node.ws].add(node.id);
+    }
+    return nodeIdsByWorkspace;
+}
+function validateAgentWorkflowNodeIdRef(qid, ws, field, value, nodeIdsByWorkspace, allowSkillRef, knownSkillSlugs, allowMissing, errors) {
+    if (nodeIdsByWorkspace[ws]?.has(value)) {
+        return;
+    }
+    if (allowSkillRef &&
+        validateSkillRef(qid, field, value, knownSkillSlugs, allowMissing, errors)) {
+        return;
+    }
+    if (allowMissing) {
+        return;
+    }
+    pushError(errors, `${qid}: ${field} references missing node ${value}`);
+}
+function validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, errors) {
+    const nodeIdsByWorkspace = buildNodeIdsByWorkspace(index);
+    for (const [qid, node] of Object.entries(index.nodes)) {
+        if (node.type !== "feedback" && node.type !== "proposal") {
+            continue;
+        }
+        const targetId = node.attributes.target_id;
+        if (typeof targetId === "string") {
+            const allowSkillTarget = node.type === "proposal" && node.attributes.proposal_kind === "skill_update";
+            validateAgentWorkflowNodeIdRef(qid, node.ws, "target_id", targetId, nodeIdsByWorkspace, allowSkillTarget, knownSkillSlugs, allowMissing, errors);
+        }
+        if (node.type !== "proposal") {
+            continue;
+        }
+        const evidenceRefs = node.attributes.evidence_refs;
+        if (!Array.isArray(evidenceRefs)) {
+            continue;
+        }
+        for (const [indexValue, value] of evidenceRefs.entries()) {
+            if (typeof value !== "string") {
+                continue;
+            }
+            validateAgentWorkflowNodeIdRef(qid, node.ws, `evidence_refs[${indexValue}]`, value, nodeIdsByWorkspace, true, knownSkillSlugs, allowMissing, errors);
+        }
+    }
+}
 function detectPrevNextCycles(index, errors) {
     const nodes = index.nodes;
     const seen = new Set();
@@ -102,8 +395,15 @@ function detectPrevNextCycles(index, errors) {
 function collectGraphErrors(index, options = {}) {
     const errors = [];
     const allowMissing = options.allowMissing ?? false;
-    validateEdgeTargets(index, allowMissing, errors);
+    const knownSkillSlugs = options.knownSkillSlugs;
+    validateEdgeTargets(index, allowMissing, knownSkillSlugs, errors);
     validatePrevNextSymmetry(index, allowMissing, errors);
+    validateAgentWorkflowSpecWorkContracts(index, allowMissing, errors);
+    validateAgentWorkflowWorkOrderWorkRefs(index, allowMissing, errors);
+    validateAgentWorkflowReceiptWorkOrderRefs(index, allowMissing, errors);
+    validateAgentWorkflowSubagentRefs(index, allowMissing, errors);
+    validateAgentWorkflowDisputeRefs(index, allowMissing, errors);
+    validateAgentWorkflowFeedbackProposalRefs(index, allowMissing, knownSkillSlugs, errors);
     detectPrevNextCycles(index, errors);
     return errors;
 }

package/dist/init/AGENT_START.md

@@ -15,6 +15,19 @@ Trust order:
 - relevant skills
 - chat history
 
+Agent operating prompt:
+- You are working in a repository that uses mdkg for deterministic project memory.
+- Prefer `mdkg pack <id>` over ad-hoc file lists when a work item is known.
+- Treat mdkg rules, EDDs, DECs, PRDs, and work nodes as more authoritative than chat memory.
+- Use `mdkg show <id>` for direct inspection and `mdkg show <id> --meta` for card-only inspection.
+- Use `mdkg search "..."` and `mdkg next` to discover current work.
+- Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
+- Use `mdkg task start/update/done` for structured task, bug, and test lifecycle fields.
+- Keep nuanced summaries, body text, and manual parent closeout edits in markdown.
+- Use `mdkg event enable` only if `events.jsonl` is missing and provenance should be restored.
+- Use `CLI_COMMAND_MATRIX.md` for the canonical command and flag surface.
+- Run `mdkg validate` before marking work done.
+
 If the active task is known:
 - `mdkg pack <id>`
 - `mdkg task start <id>` when durable work begins

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -17,6 +17,47 @@ Primary commands:
 - `mdkg task`
 - `mdkg validate`
 
+Validation commands:
+- `mdkg validate [--out <path>] [--quiet] [--json]`
+
+Node creation commands:
+- `mdkg new <type> "<title>" [options] [--json]`
+
+Agent workflow file type creation:
+- `mdkg new spec "<title>" [options] [--json]`
+- `mdkg new work "<title>" [options] [--json]`
+- `mdkg new work_order "<title>" [options] [--json]`
+- `mdkg new receipt "<title>" [options] [--json]`
+- `mdkg new feedback "<title>" [options] [--json]`
+- `mdkg new dispute "<title>" [options] [--json]`
+- `mdkg new proposal "<title>" [options] [--json]`
+- `mdkg new spec "image worker" --id agent.image-worker`
+- `mdkg new work "generate image" --id work.generate-image`
+
+Agent workflow notes:
+- `--id <portable-id>` is only for agent workflow file types.
+- `spec` and `work` scaffold as validation-clean standalone docs.
+- `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
+
+Workspace registry commands:
+- `mdkg workspace ls [--json]`
+- `mdkg workspace add <alias> <path> [--mdkg-dir <dir>] [--json]`
+- `mdkg workspace rm <alias> [--json]`
+- `mdkg workspace enable <alias> [--json]`
+- `mdkg workspace disable <alias> [--json]`
+
+Event log commands:
+- `mdkg event enable [--ws <alias>] [--json]`
+- `mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [options] [--json]`
+
+Task mutation commands:
+- `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]`
+- `mdkg task update <id-or-qid> [options] [--json]`
+- `mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]`
+
+Checkpoint commands:
+- `mdkg checkpoint new <title> [--ws <alias>] [--json]`
+
 Agent bootstrap:
 - `mdkg init --llm`
 - `mdkg init --agent`
@@ -27,7 +68,8 @@ Skill discovery:
 - `mdkg skill list --tags stage:plan --json`
 - `mdkg skill search "<query>" --json`
 - `mdkg skill show <slug> --json`
-- `mdkg skill sync`
+- `mdkg skill validate [<slug>] [--json]`
+- `mdkg skill sync [--force] [--json]`
 
 Discovery/show export flags:
 - `--json`

package/dist/init/README.md

@@ -21,6 +21,13 @@ mdkg pack <id>
 mdkg validate
 ```
 
+Agent workflow docs can use semantic ids:
+
+```bash
+mdkg new spec "image worker" --id agent.image-worker
+mdkg new work "generate image" --id work.generate-image
+```
+
 Read `AGENT_START.md` first when this repo includes it.
 
 ## Pack Profiles

package/dist/init/skills/default/verify-close-and-checkpoint/SKILL.md

@@ -4,7 +4,7 @@ description: Verify code and mdkg state, attach evidence, and close work cleanly
 tags: [stage:review, writer:orchestrator, mdkg, validation, release]
 version: 0.1.0
 authors: [mdkg]
-links: [README.md, AGENT_PROMPT_SNIPPET.md]
+links: [README.md, AGENT_START.md]
 ---
 
 # Goal

package/dist/init/templates/default/dispute.md

@@ -0,0 +1,31 @@
+---
+id: {{id}}
+type: dispute
+title: {{title}}
+version: 0.1.0
+work_order_id: order.example
+receipt_id: receipt.example
+dispute_status: open
+severity: medium
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Dispute
+
+Capture the dispute or report summary.
+
+# Evidence
+
+List evidence references without secrets.
+
+# Resolution
+
+Record review outcome when available.

package/dist/init/templates/default/feedback.md

@@ -0,0 +1,27 @@
+---
+id: {{id}}
+type: feedback
+title: {{title}}
+version: 0.1.0
+target_id: work.example
+sentiment: neutral
+feedback_status: new
+source_ref: user.example
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Feedback
+
+Capture high-signal feedback without raw secrets.
+
+# Evidence
+
+List supporting references and artifacts.

package/dist/init/templates/default/proposal.md

@@ -0,0 +1,35 @@
+---
+id: {{id}}
+type: proposal
+title: {{title}}
+version: 0.1.0
+target_id: work.example
+proposal_status: proposed
+proposal_kind: work_update
+evidence_refs: []
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Summary
+
+Summarize the improvement proposal.
+
+# Evidence
+
+List feedback, receipts, disputes, or other evidence.
+
+# Proposed Change
+
+Describe the proposed update to a SPEC.md, WORK.md, or SKILL.md.
+
+# Review
+
+Capture review status and next decision points.

package/dist/init/templates/default/receipt.md

@@ -0,0 +1,31 @@
+---
+id: {{id}}
+type: receipt
+title: {{title}}
+version: 0.1.0
+work_order_id: order.example
+receipt_status: recorded
+outcome: success
+cost_ref: cost.redacted
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Outcome
+
+Record the result and proof summary.
+
+# Artifacts
+
+List committed artifact references.
+
+# Notes
+
+Capture non-secret execution notes.

package/dist/init/templates/default/spec.md

@@ -0,0 +1,43 @@
+---
+id: {{id}}
+type: spec
+title: {{title}}
+version: 0.1.0
+role: subagent
+runtime_mode: room_orchestrated
+work_contracts: []
+requested_capabilities: []
+skill_refs: []
+tool_refs: []
+model_refs: []
+wasm_component_refs: []
+runtime_image_refs: []
+subagent_refs: []
+resource_profile: builder
+update_policy: manual
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Purpose
+
+Define the agent, package, or runtime specification.
+
+# Runtime
+
+Describe role, runtime mode, resource profile, and update policy.
+
+# Work Contracts
+
+List related WORK.md contracts.
+
+# Capabilities
+
+List requested capabilities and relevant constraints.

package/dist/init/templates/default/work.md

@@ -0,0 +1,44 @@
+---
+id: {{id}}
+type: work
+title: {{title}}
+version: 0.1.0
+agent_id: agent.example
+kind: generic
+pricing_model: quoted
+required_capabilities: []
+skill_refs: []
+tool_refs: []
+model_refs: []
+wasm_component_refs: []
+runtime_image_refs: []
+subagent_refs: []
+inputs: [request:text:required]
+outputs: [result:text:required]
+receipt_required: true
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Capability
+
+Describe the reusable capability contract.
+
+# Inputs
+
+Document input descriptors and validation expectations.
+
+# Outputs
+
+Document output descriptors and artifact expectations.
+
+# Receipt
+
+Describe required receipt evidence.

package/dist/init/templates/default/work_order.md

@@ -0,0 +1,32 @@
+---
+id: {{id}}
+type: work_order
+title: {{title}}
+version: 0.1.0
+work_id: work.example
+work_version: 0.1.0
+requester: user.example
+order_status: submitted
+request_ref: request.example
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Request
+
+Capture the concrete request against a WORK.md version.
+
+# Inputs
+
+Record committed input references without secrets.
+
+# Constraints
+
+Capture relevant policy, budget, and artifact constraints.