mdkg 0.0.8 → 0.1.0

package/dist/graph/template_schema.js

@@ -3,77 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ALLOWED_TYPES = exports.DEC_TYPES = exports.WORK_TYPES = void 0;
-exports.buildNodeSchemas = buildNodeSchemas;
-exports.getNodeSchema = getNodeSchema;
-exports.schemaAllowsKey = schemaAllowsKey;
 exports.loadTemplateSchemas = loadTemplateSchemas;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const frontmatter_1 = require("./frontmatter");
-exports.WORK_TYPES = new Set(["epic", "feat", "task", "bug", "checkpoint", "test"]);
-exports.DEC_TYPES = new Set(["dec"]);
-exports.ALLOWED_TYPES = new Set([
-    "rule",
-    "prd",
-    "edd",
-    "dec",
-    "prop",
-    "epic",
-    "feat",
-    "task",
-    "bug",
-    "checkpoint",
-    "test",
-]);
-const COMMON_SCALAR_KEYS = ["id", "type", "title", "created", "updated"];
-const COMMON_LIST_KEYS = ["tags", "owners", "links", "artifacts", "relates", "refs", "aliases"];
-const NODE_SCHEMA_DEFS = {
-    rule: {
-        scalars: [...COMMON_SCALAR_KEYS],
-        lists: [...COMMON_LIST_KEYS],
-    },
-    prd: {
-        scalars: [...COMMON_SCALAR_KEYS],
-        lists: [...COMMON_LIST_KEYS],
-    },
-    edd: {
-        scalars: [...COMMON_SCALAR_KEYS],
-        lists: [...COMMON_LIST_KEYS],
-    },
-    prop: {
-        scalars: [...COMMON_SCALAR_KEYS],
-        lists: [...COMMON_LIST_KEYS],
-    },
-    dec: {
-        scalars: [...COMMON_SCALAR_KEYS, "status", "supersedes"],
-        lists: [...COMMON_LIST_KEYS],
-    },
-    epic: {
-        scalars: [...COMMON_SCALAR_KEYS, "status", "priority"],
-        lists: [...COMMON_LIST_KEYS, "blocked_by", "blocks", "skills"],
-    },
-    feat: {
-        scalars: [...COMMON_SCALAR_KEYS, "status", "priority", "epic", "parent", "prev", "next"],
-        lists: [...COMMON_LIST_KEYS, "blocked_by", "blocks", "skills"],
-    },
-    task: {
-        scalars: [...COMMON_SCALAR_KEYS, "status", "priority", "epic", "parent", "prev", "next"],
-        lists: [...COMMON_LIST_KEYS, "blocked_by", "blocks", "skills"],
-    },
-    bug: {
-        scalars: [...COMMON_SCALAR_KEYS, "status", "priority", "epic", "parent", "prev", "next"],
-        lists: [...COMMON_LIST_KEYS, "blocked_by", "blocks", "skills"],
-    },
-    checkpoint: {
-        scalars: [...COMMON_SCALAR_KEYS, "status", "priority", "epic", "parent", "prev", "next"],
-        lists: [...COMMON_LIST_KEYS, "blocked_by", "blocks", "skills", "scope"],
-    },
-    test: {
-        scalars: [...COMMON_SCALAR_KEYS, "status", "priority", "epic", "parent", "prev", "next"],
-        lists: [...COMMON_LIST_KEYS, "blocked_by", "blocks", "skills", "cases"],
-    },
-};
 function listMarkdownFiles(dir) {
     if (!fs_1.default.existsSync(dir)) {
         return [];
@@ -111,65 +44,13 @@ function addKeyToSchema(schema, key, kind, filePath) {
         schema.listKeys.add(key);
     }
 }
-function buildSchema(type, definition) {
-    const schema = {
-        type,
-        allowedKeys: new Set(),
-        keyKinds: {},
-        listKeys: new Set(),
-    };
-    for (const key of definition.scalars) {
-        addKeyToSchema(schema, key, "scalar", type);
-    }
-    for (const key of definition.lists ?? []) {
-        addKeyToSchema(schema, key, "list", type);
-    }
-    for (const key of definition.booleans ?? []) {
-        addKeyToSchema(schema, key, "boolean", type);
-    }
-    return schema;
-}
-function buildNodeSchemas(requiredTypes) {
-    const schemas = {};
-    for (const [type, definition] of Object.entries(NODE_SCHEMA_DEFS)) {
-        schemas[type] = buildSchema(type, definition);
-    }
-    if (requiredTypes) {
-        const required = Array.from(requiredTypes, (value) => value.toLowerCase());
-        const missing = required.filter((value) => !schemas[value]);
-        if (missing.length > 0) {
-            throw new Error(`template schema missing for type(s): ${missing.join(", ")}`);
-        }
-    }
-    return schemas;
-}
-function getNodeSchema(type) {
-    return buildNodeSchemas()[type.toLowerCase()];
-}
-function schemaAllowsKey(type, key) {
-    const schema = getNodeSchema(type);
-    return Boolean(schema?.allowedKeys.has(key));
-}
-function validateTemplateAgainstSchema(frontmatter, schema, filePath) {
-    for (const [key, value] of Object.entries(frontmatter)) {
-        const expected = schema.keyKinds[key];
-        if (!expected) {
-            throw new Error(`template key not allowed for ${schema.type}: ${key} (${filePath})`);
-        }
-        const kind = getValueKind(value);
-        if (expected !== kind) {
-            throw new Error(`template schema mismatch for ${schema.type}.${key}: expected ${expected} but found ${kind} (${filePath})`);
-        }
-    }
-}
 function loadTemplateSchemas(root, config, requiredTypes) {
-    const schemas = buildNodeSchemas(requiredTypes);
     const templateRoot = path_1.default.resolve(root, config.templates.root_path, config.templates.default_set);
     const files = listMarkdownFiles(templateRoot);
     if (files.length === 0) {
         throw new Error(`no templates found at ${templateRoot}`);
     }
-    const discoveredTypes = new Set();
+    const schemas = {};
     for (const filePath of files) {
         const content = fs_1.default.readFileSync(filePath, "utf8");
         const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, filePath);
@@ -181,16 +62,22 @@ function loadTemplateSchemas(root, config, requiredTypes) {
         if (normalizedType !== typeValue) {
             throw new Error(`template type must be lowercase in ${filePath}`);
         }
-        const schema = schemas[normalizedType];
-        if (!schema) {
-            throw new Error(`template schema missing for type ${normalizedType}`);
+        const schema = schemas[normalizedType] ??
+            {
+                type: normalizedType,
+                allowedKeys: new Set(),
+                keyKinds: {},
+                listKeys: new Set(),
+            };
+        schemas[normalizedType] = schema;
+        for (const [key, value] of Object.entries(frontmatter)) {
+            const kind = getValueKind(value);
+            addKeyToSchema(schema, key, kind, filePath);
         }
-        validateTemplateAgainstSchema(frontmatter, schema, filePath);
-        discoveredTypes.add(normalizedType);
     }
     if (requiredTypes) {
         const required = Array.from(requiredTypes, (value) => value.toLowerCase());
-        const missing = required.filter((value) => !discoveredTypes.has(value));
+        const missing = required.filter((value) => !schemas[value]);
         if (missing.length > 0) {
             throw new Error(`template schema missing for type(s): ${missing.join(", ")}`);
         }

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,20 @@ 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.
+- Use `mdkg upgrade` to preview scaffold updates; only run `mdkg upgrade --apply` after reviewing the receipt.
+- 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
@@ -41,8 +55,6 @@ Conventions:
 - mdkg does not execute skill scripts; runtimes decide when and whether to do that.
 - Prefer packs over ad-hoc file lists.
 - Prefer task/event commands for structured work-state changes and use markdown edits for narrative/body updates.
-- `skills` is valid metadata on all work items (`epic`, `feat`, `task`, `bug`, `checkpoint`, `test`), but `mdkg task ...` still mutates only `task`, `bug`, and `test`.
-- Treat mdkg-generated work items as schema-consistent by default: `mdkg new`, `mdkg validate`, and `mdkg task ...` should not require manual frontmatter repair.
 - Use `mdkg task done <id> --checkpoint "<title>"` for milestone compression, not every routine task completion.
 - Prefer checkpoints for feat/epic closeout summaries; parent status edits remain manual.
 - If `events.jsonl` is missing, `mdkg task start` and `mdkg task done` will remind you how to recreate it.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -8,6 +8,7 @@ Verify live help with:
 
 Primary commands:
 - `mdkg init`
+- `mdkg upgrade [--dry-run] [--apply] [--json]`
 - `mdkg new`
 - `mdkg show`
 - `mdkg list`
@@ -17,17 +18,64 @@ 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`
 - `mdkg init --llm --agent`
 - published bootstrap config is root-only by default
 
+Upgrade:
+- `mdkg upgrade` previews safe scaffold updates and writes nothing by default
+- `mdkg upgrade --apply` updates only managed or unchanged init assets
+- customized docs, templates, skills, and core files are preserved and reported
+
 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

@@ -15,12 +15,20 @@ This repository is initialized for mdkg.
 
 ```bash
 mdkg init --llm --agent
+mdkg upgrade
 mdkg search "..."
 mdkg show <id>
 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
@@ -43,3 +51,9 @@ Recommended:
 ```bash
 mdkg init --update-gitignore --update-npmignore
 ```
+
+## Upgrade
+
+`mdkg upgrade` previews safe scaffold updates for existing workspaces and writes nothing by default.
+
+Use `mdkg upgrade --apply` only after reviewing the receipt. Local customizations are preserved and reported instead of overwritten.

package/dist/init/core/rule-6-templates-and-schemas.md

@@ -95,9 +95,7 @@ Work items (`epic/feat/task/bug/checkpoint/test`):
   - `status` (enum)
   - optional `priority` (0..9)
   - optional `skills: [slug, ...]` (kebab-case skill slugs)
-  - optional graph fields are type-specific by the shared schema/templates
-  - `relates`, `blocked_by`, and `blocks` are common work-item list fields
-  - `epic`, `parent`, `prev`, and `next` are only valid on the work-item types whose templates/schema include them
+  - optional graph edges: `epic`, `parent`, `relates`, `blocked_by`, `blocks`, `prev`, `next`
 
 Decision records (`dec-*`):
 - `status` (enum: `proposed`, `accepted`, `rejected`, `superseded`)