mdkg 0.0.6 → 0.0.8

package/README.md

@@ -94,6 +94,8 @@ mdkg task update task-1 --add-artifacts tests://unit.txt --add-tags release
 mdkg task done task-1 --checkpoint "release readiness milestone"
 ```
 
+`mdkg task ...` remains limited to `task`, `bug`, and `test`, but `skills: [...]` is valid metadata on all work items (`epic`, `feat`, `task`, `bug`, `checkpoint`, `test`). mdkg-generated work items should validate and round-trip through the task mutators without manual frontmatter repair.
+
 Ensure and append baseline event memory:
 
 ```bash
@@ -176,11 +178,15 @@ Current source behavior:
   - `mdkg skill show <slug>`
   - `mdkg skill validate [<slug>]`
   - `mdkg skill sync`
-- machine-readable skill discovery is available through:
+- machine-readable skill discovery and inspection is available through:
   - `mdkg skill list --json`
   - `mdkg skill search "<query>" --json`
   - `mdkg skill show <slug> --json`
+  - `mdkg skill list --xml|--toon|--md`
+  - `mdkg skill search "<query>" --xml|--toon|--md`
+  - `mdkg skill show <slug> --xml|--toon|--md`
 - work items may reference `skills: [slug,...]`
+- `skills` is valid on all work items (`epic`, `feat`, `task`, `bug`, `checkpoint`, `test`)
 - packs may include skills with `--skills` and `--skills-depth`
 - mdkg indexes and discovers skills but does not execute skill scripts
 - `SKILL.md` is canonical
@@ -201,11 +207,13 @@ This repo now dogfoods three internal skills:
 This release includes:
 - `init --agent`
 - default ignore updates with `--no-update-ignores` for `.mdkg/index/` and `.mdkg/pack/`
+- root-only published init seed config
 - skills indexing and search/show/list support
 - optional `skills: [...]` on work items
 - pack-time skill inclusion
 - latest-checkpoint resolver + index hint
 - events JSONL validation
+- XML / TOON / Markdown output for node and skill list/search/show
 - product-specific skill mirrors for Codex/OpenAI and Claude
 - shared `AGENT_START.md` startup guidance
 
@@ -214,6 +222,7 @@ Current direction:
 - use `init --agent` for deeper AI-agent bootstrap
 - keep `pack <id>` at the center of the human/agent loop
 - use `mdkg task ...` for structured state changes and markdown edits for narrative/body content
+- keep validation strict and fix schema drift instead of papering over mdkg-generated inconsistencies
 - make event logging guided instead of purely manual
 - dogfood real skills inside the repo
 - make skill authoring first-class through `mdkg skill`

package/dist/cli.js

@@ -134,7 +134,7 @@ function printIndexHelp(log) {
 }
 function printShowHelp(log) {
     log("Usage:");
-    log("  mdkg show <id-or-qid> [--ws <alias>] [--meta] [--json]");
+    log("  mdkg show <id-or-qid> [--ws <alias>] [--meta] [--json|--xml|--toon|--md]");
     log("\nWhen to use:");
     log("  Inspect one mdkg node exactly. Use `mdkg skill show <slug>` for skills.");
     log("\nDefault behavior:");
@@ -144,7 +144,8 @@ function printShowHelp(log) {
 function printListHelp(log) {
     log("Usage:");
     log("  mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>]");
-    log("           [--priority <n>] [--blocked] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
+    log("           [--priority <n>] [--blocked] [--tags <tag,tag,...>] [--tags-mode any|all]");
+    log("           [--json|--xml|--toon|--md]");
     log("\nWhen to use:");
     log("  List mdkg nodes. Use `mdkg skill list` for skills.");
     printGlobalOptions(log);
@@ -152,7 +153,7 @@ function printListHelp(log) {
 function printSearchHelp(log) {
     log("Usage:");
     log('  mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>]');
-    log("               [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
+    log("               [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
     log("\nWhen to use:");
     log("  Search mdkg nodes by metadata. Use `mdkg skill search` for skills.");
     printGlobalOptions(log);
@@ -210,21 +211,21 @@ function printSkillHelp(log, subcommand) {
             return;
         case "list":
             log("Usage:");
-            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
+            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
             log("\nWhen to use:");
             log("  Discover skills directly, including stage-tagged orchestrator lookups.");
             printGlobalOptions(log);
             return;
         case "show":
             log("Usage:");
-            log("  mdkg skill show <slug> [--meta] [--json]");
+            log("  mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]");
             log("\nWhen to use:");
             log("  Inspect one skill body or metadata after discovery.");
             printGlobalOptions(log);
             return;
         case "search":
             log("Usage:");
-            log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json]');
+            log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]');
             log("\nWhen to use:");
             log("  Search skills by trigger text, tags, and stage conventions like `stage:plan`.");
             printGlobalOptions(log);
@@ -244,9 +245,9 @@ function printSkillHelp(log, subcommand) {
         default:
             log("Usage:");
             log('  mdkg skill new <slug> "<name>" --description "<description>" [options]');
-            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json]");
-            log("  mdkg skill show <slug> [--meta] [--json]");
-            log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json]');
+            log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
+            log("  mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]");
+            log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]');
             log("  mdkg skill validate [<slug>]");
             log("  mdkg skill sync [--force]");
             log("\nNotes:");
@@ -528,6 +529,25 @@ function parseTagsModeFlag(value) {
     }
     throw new errors_1.UsageError("--tags-mode must be any or all");
 }
+function parseQueryOutputFormat(parsed) {
+    const enabled = [];
+    if (parseBooleanFlag("--json", parsed.flags["--json"])) {
+        enabled.push("json");
+    }
+    if (parseBooleanFlag("--xml", parsed.flags["--xml"])) {
+        enabled.push("xml");
+    }
+    if (parseBooleanFlag("--toon", parsed.flags["--toon"])) {
+        enabled.push("toon");
+    }
+    if (parseBooleanFlag("--md", parsed.flags["--md"])) {
+        enabled.push("md");
+    }
+    if (enabled.length > 1) {
+        throw new errors_1.UsageError("choose at most one output flag: --json, --xml, --toon, or --md");
+    }
+    return enabled[0];
+}
 function handleCommandError(err, command, runtime) {
     const message = err instanceof Error ? err.message : String(err);
     if (err instanceof errors_1.UsageError) {
@@ -622,12 +642,12 @@ function runSkillSubcommand(parsed, root) {
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             (0, skill_1.runSkillListCommand)({
                 root,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -639,14 +659,14 @@ function runSkillSubcommand(parsed, root) {
                 throw new errors_1.UsageError("skill show requires <slug>");
             }
             const metaOnly = parseBooleanFlag("--meta", parsed.flags["--meta"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, skill_1.runSkillShowCommand)({
                 root,
                 slug,
                 metaOnly,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -659,7 +679,7 @@ function runSkillSubcommand(parsed, root) {
             const query = parsed.positionals.slice(2).join(" ");
             const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, skill_1.runSkillSearchCommand)({
@@ -667,7 +687,7 @@ function runSkillSubcommand(parsed, root) {
                 query,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -930,7 +950,7 @@ function runCommand(parsed, root, runtime) {
             }
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
             const metaOnly = parseBooleanFlag("--meta", parsed.flags["--meta"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, show_1.runShowCommand)({
@@ -938,7 +958,7 @@ function runCommand(parsed, root, runtime) {
                 id,
                 ws,
                 metaOnly,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -956,7 +976,7 @@ function runCommand(parsed, root, runtime) {
             const blocked = parseBooleanFlag("--blocked", parsed.flags["--blocked"]);
             const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, list_1.runListCommand)({
@@ -969,7 +989,7 @@ function runCommand(parsed, root, runtime) {
                 blocked,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -985,7 +1005,7 @@ function runCommand(parsed, root, runtime) {
             const status = requireFlagValue("--status", parsed.flags["--status"]);
             const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
-            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             (0, search_1.runSearchCommand)({
@@ -996,7 +1016,7 @@ function runCommand(parsed, root, runtime) {
                 status,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });

package/dist/commands/list.js

@@ -53,13 +53,14 @@ function runListCommand(options) {
         tagsMode: options.tagsMode,
     });
     const sorted = (0, sort_1.sortNodesByQid)(filtered);
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "list",
             kind: "node",
             count: sorted.length,
             items: sorted.map(query_output_1.toNodeSummaryJson),
-        });
+        }, format);
         return;
     }
     (0, query_output_1.writeCount)(sorted.length, sorted.length === 0 ? "no nodes matched current filters" : undefined);

package/dist/commands/new.js

@@ -10,6 +10,7 @@ const config_1 = require("../core/config");
 const index_cache_1 = require("../graph/index_cache");
 const node_1 = require("../graph/node");
 const indexer_1 = require("../graph/indexer");
+const template_schema_1 = require("../graph/template_schema");
 const loader_1 = require("../templates/loader");
 const date_1 = require("../util/date");
 const errors_1 = require("../util/errors");
@@ -172,7 +173,7 @@ function runNewCommand(options) {
             throw new errors_1.UsageError(`--status must be one of ${Array.from(allowed).join(", ")}`);
         }
     }
-    else if (type === "dec") {
+    else if (node_1.DEC_TYPES.has(type)) {
         status = statusInput ?? "proposed";
         if (!DEC_STATUS.has(status)) {
             throw new errors_1.UsageError(`--status must be one of ${Array.from(DEC_STATUS).join(", ")}`);
@@ -196,12 +197,20 @@ function runNewCommand(options) {
     else if (options.priority !== undefined) {
         throw new errors_1.UsageError("--priority is only valid for work items");
     }
-    if (!node_1.WORK_TYPES.has(type)) {
-        if (options.epic || options.parent || options.prev || options.next || options.blockedBy || options.blocks) {
-            throw new errors_1.UsageError("epic/parent/prev/next/blocked-by/blocks are only valid for work items");
+    const graphFields = [
+        ["epic", options.epic],
+        ["parent", options.parent],
+        ["prev", options.prev],
+        ["next", options.next],
+        ["blocked_by", options.blockedBy],
+        ["blocks", options.blocks],
+    ];
+    for (const [key, raw] of graphFields) {
+        if (raw && !(0, template_schema_1.schemaAllowsKey)(type, key)) {
+            throw new errors_1.UsageError(`--${key.replace("_", "-")} is not valid for ${type} nodes`);
         }
     }
-    if (options.cases && type !== "test") {
+    if (options.cases && !(0, template_schema_1.schemaAllowsKey)(type, "cases")) {
         throw new errors_1.UsageError("--cases is only valid for test nodes");
     }
     const epic = options.epic ? normalizeIdRef(options.epic, "--epic") : undefined;
@@ -219,7 +228,7 @@ function runNewCommand(options) {
     const skills = normalizeSkillList(options.skills);
     const links = normalizeList(options.links);
     const artifacts = normalizeList(options.artifacts);
-    if (skills.length > 0 && !node_1.WORK_TYPES.has(type)) {
+    if (skills.length > 0 && !(0, template_schema_1.schemaAllowsKey)(type, "skills")) {
         throw new errors_1.UsageError("--skills is only valid for work items");
     }
     if (type === "dec" && options.supersedes) {
@@ -258,6 +267,7 @@ function runNewCommand(options) {
     }
     const today = (0, date_1.formatDate)(options.now ?? new Date());
     const template = (0, loader_1.loadTemplate)(options.root, config, type, options.template);
+    const schema = (0, template_schema_1.getNodeSchema)(type);
     const content = (0, loader_1.renderTemplate)(template, {
         id,
         type,
@@ -282,7 +292,7 @@ function runNewCommand(options) {
         supersedes: options.supersedes ? options.supersedes.toLowerCase() : undefined,
         created: today,
         updated: today,
-    });
+    }, schema?.allowedKeys);
     fs_1.default.mkdirSync(targetDir, { recursive: true });
     fs_1.default.writeFileSync(filePath, content, "utf8");
     if (config.index.auto_reindex && !noReindex) {

package/dist/commands/query_output.js

@@ -5,6 +5,7 @@ exports.toNodeDetailJson = toNodeDetailJson;
 exports.toSkillSummaryJson = toSkillSummaryJson;
 exports.toSkillDetailJson = toSkillDetailJson;
 exports.writeJson = writeJson;
+exports.writeStructuredOutput = writeStructuredOutput;
 exports.writeCount = writeCount;
 function toNodeSummaryJson(node) {
     return {
@@ -76,6 +77,113 @@ function toSkillDetailJson(skill, body) {
 function writeJson(payload) {
     console.log(JSON.stringify(payload, null, 2));
 }
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function isPrimitive(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+function objectToXml(tag, value, indent = "") {
+    if (value === undefined) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        const lines = [`${indent}<${tag}>`];
+        for (const item of value) {
+            lines.push(...objectToXml("item", item, `${indent}  `));
+        }
+        lines.push(`${indent}</${tag}>`);
+        return lines;
+    }
+    if (isPrimitive(value)) {
+        return [`${indent}<${tag}>${escapeXml(value === null ? "" : String(value))}</${tag}>`];
+    }
+    const lines = [`${indent}<${tag}>`];
+    for (const [key, child] of Object.entries(value)) {
+        lines.push(...objectToXml(key, child, `${indent}  `));
+    }
+    lines.push(`${indent}</${tag}>`);
+    return lines;
+}
+function formatMarkdownScalar(value) {
+    return value === null ? "null" : String(value);
+}
+function objectToMarkdown(value, lines, indent = "", key) {
+    if (value === undefined) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (key) {
+            lines.push(`${indent}- ${key}:`);
+        }
+        const childIndent = key ? `${indent}  ` : indent;
+        if (value.length === 0) {
+            lines.push(`${childIndent}- []`);
+            return;
+        }
+        for (const item of value) {
+            if (isPrimitive(item)) {
+                lines.push(`${childIndent}- ${formatMarkdownScalar(item)}`);
+                continue;
+            }
+            lines.push(`${childIndent}-`);
+            objectToMarkdown(item, lines, `${childIndent}  `);
+        }
+        return;
+    }
+    if (isPrimitive(value)) {
+        if (!key) {
+            lines.push(`${indent}- ${formatMarkdownScalar(value)}`);
+            return;
+        }
+        lines.push(`${indent}- ${key}: ${formatMarkdownScalar(value)}`);
+        return;
+    }
+    if (key) {
+        lines.push(`${indent}- ${key}:`);
+    }
+    const childIndent = key ? `${indent}  ` : indent;
+    for (const [childKey, childValue] of Object.entries(value)) {
+        objectToMarkdown(childValue, lines, childIndent, childKey);
+    }
+}
+function writeXml(payload) {
+    const lines = ['<?xml version="1.0" encoding="UTF-8"?>'];
+    lines.push(...objectToXml("response", payload));
+    console.log(lines.join("\n"));
+}
+function writeToon(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+function writeMarkdown(payload) {
+    const lines = ["# mdkg response"];
+    objectToMarkdown(payload, lines);
+    console.log(lines.join("\n"));
+}
+function writeStructuredOutput(payload, format) {
+    switch (format) {
+        case "json":
+            writeJson(payload);
+            return;
+        case "xml":
+            writeXml(payload);
+            return;
+        case "toon":
+            writeToon(payload);
+            return;
+        case "md":
+            writeMarkdown(payload);
+            return;
+    }
+}
 function writeCount(count, note) {
     console.error(`count: ${count}`);
     if (note) {

package/dist/commands/search.js

@@ -71,13 +71,14 @@ function runSearchCommand(options) {
         tagsMode: options.tagsMode,
     }).filter((node) => matchesQuery(node, terms));
     const sorted = (0, sort_1.sortNodesByQid)(nodeResults);
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "search",
             kind: "node",
             count: sorted.length,
             items: sorted.map(query_output_1.toNodeSummaryJson),
-        });
+        }, format);
         return;
     }
     (0, query_output_1.writeCount)(sorted.length, sorted.length === 0 ? `no nodes matched query "${query}"` : undefined);

package/dist/commands/show.js

@@ -58,12 +58,13 @@ function runShowCommand(options) {
         const content = fs_1.default.readFileSync(filePath, "utf8");
         body = (0, frontmatter_1.parseFrontmatter)(content, filePath).body.trimEnd();
     }
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "show",
             kind: "node",
             item: (0, query_output_1.toNodeDetailJson)(node, options.metaOnly ? undefined : body),
-        });
+        }, format);
         return;
     }
     const lines = [];

package/dist/commands/skill.js

@@ -205,13 +205,14 @@ function runSkillListCommand(options) {
         console.error("warning: skills index is stale; run mdkg index to refresh");
     }
     const skills = filterSkills(Object.values(index.skills), options.tags, options.tagsMode ?? "any").sort((a, b) => a.qid.localeCompare(b.qid));
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "list",
             kind: "skill",
             count: skills.length,
             items: skills.map(query_output_1.toSkillSummaryJson),
-        });
+        }, format);
         return;
     }
     (0, query_output_1.writeCount)(skills.length, skills.length === 0 ? "no skills matched current filters" : undefined);
@@ -243,12 +244,13 @@ function runSkillShowCommand(options) {
         }
         body = fs_1.default.readFileSync(skillPath, "utf8").trimEnd();
     }
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "show",
             kind: "skill",
             item: (0, query_output_1.toSkillDetailJson)(skill, options.metaOnly ? undefined : body),
-        });
+        }, format);
         return;
     }
     if (options.metaOnly) {
@@ -307,13 +309,14 @@ function runSkillSearchCommand(options) {
     const skills = filterSkills(Object.values(index.skills), options.tags, options.tagsMode ?? "any")
         .filter((skill) => matchesSkillQuery(skill, terms))
         .sort((a, b) => a.qid.localeCompare(b.qid));
-    if (options.json) {
-        (0, query_output_1.writeJson)({
+    const format = options.format ?? (options.json ? "json" : undefined);
+    if (format) {
+        (0, query_output_1.writeStructuredOutput)({
             command: "search",
             kind: "skill",
             count: skills.length,
             items: skills.map(query_output_1.toSkillSummaryJson),
-        });
+        }, format);
         return;
     }
     (0, query_output_1.writeCount)(skills.length, skills.length === 0 ? `no skills matched query "${query}"` : undefined);

package/dist/commands/task.js

@@ -9,10 +9,12 @@ exports.runTaskDoneCommand = runTaskDoneCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
+const node_1 = require("../graph/node");
 const indexer_1 = require("../graph/indexer");
 const index_cache_1 = require("../graph/index_cache");
 const frontmatter_1 = require("../graph/frontmatter");
 const skills_indexer_1 = require("../graph/skills_indexer");
+const template_schema_1 = require("../graph/template_schema");
 const date_1 = require("../util/date");
 const errors_1 = require("../util/errors");
 const qid_1 = require("../util/qid");
@@ -112,7 +114,12 @@ function loadMutableTaskNode(root, idOrQid, wsHint) {
     }
     const filePath = path_1.default.resolve(root, node.path);
     const content = fs_1.default.readFileSync(filePath, "utf8");
-    const parsed = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+    const parsed = (0, node_1.parseNode)(content, filePath, {
+        workStatusEnum: config.work.status_enum,
+        priorityMin: config.work.priority_min,
+        priorityMax: config.work.priority_max,
+        templateSchemas: (0, template_schema_1.loadTemplateSchemas)(root, config, node_1.ALLOWED_TYPES),
+    });
     return {
         config,
         index,

package/dist/graph/node.js

@@ -4,24 +4,13 @@ exports.ALLOWED_TYPES = exports.DEC_TYPES = exports.WORK_TYPES = void 0;
 exports.parseNode = parseNode;
 const frontmatter_1 = require("./frontmatter");
 const edges_1 = require("./edges");
+const template_schema_1 = require("./template_schema");
+Object.defineProperty(exports, "ALLOWED_TYPES", { enumerable: true, get: function () { return template_schema_1.ALLOWED_TYPES; } });
+Object.defineProperty(exports, "DEC_TYPES", { enumerable: true, get: function () { return template_schema_1.DEC_TYPES; } });
+Object.defineProperty(exports, "WORK_TYPES", { enumerable: true, get: function () { return template_schema_1.WORK_TYPES; } });
 const id_1 = require("../util/id");
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const DEC_ID_RE = /^dec-[0-9]+$/;
-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 DEC_STATUS = new Set(["proposed", "accepted", "rejected", "superseded"]);
 const SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function formatError(filePath, message) {
@@ -153,8 +142,8 @@ function validateTemplateKeys(frontmatter, schema, filePath) {
 function parseNode(content, filePath, options) {
     const { frontmatter, body } = (0, frontmatter_1.parseFrontmatter)(content, filePath);
     const type = requireLowercase(expectString(frontmatter, "type", filePath), "type", filePath);
-    if (!exports.ALLOWED_TYPES.has(type)) {
-        throw formatError(filePath, `type must be one of ${Array.from(exports.ALLOWED_TYPES).join(", ")}`);
+    if (!template_schema_1.ALLOWED_TYPES.has(type)) {
+        throw formatError(filePath, `type must be one of ${Array.from(template_schema_1.ALLOWED_TYPES).join(", ")}`);
     }
     const schema = requireTemplateSchema(type, options.templateSchemas, filePath);
     validateTemplateKeys(frontmatter, schema, filePath);
@@ -165,7 +154,7 @@ function parseNode(content, filePath, options) {
     const statusValue = optionalString(frontmatter, "status", filePath);
     let status = undefined;
     const workStatus = new Set(options.workStatusEnum.map((value) => value.toLowerCase()));
-    if (exports.WORK_TYPES.has(type)) {
+    if (template_schema_1.WORK_TYPES.has(type)) {
         if (!statusValue) {
             throw formatError(filePath, "status is required for work items");
         }
@@ -175,7 +164,7 @@ function parseNode(content, filePath, options) {
         }
         status = normalized;
     }
-    else if (exports.DEC_TYPES.has(type)) {
+    else if (template_schema_1.DEC_TYPES.has(type)) {
         if (!statusValue) {
             throw formatError(filePath, "status is required for decision records");
         }
@@ -191,7 +180,7 @@ function parseNode(content, filePath, options) {
     const priorityValue = optionalString(frontmatter, "priority", filePath);
     let priority = undefined;
     if (priorityValue !== undefined) {
-        if (!exports.WORK_TYPES.has(type)) {
+        if (!template_schema_1.WORK_TYPES.has(type)) {
             throw formatError(filePath, "priority is only allowed for work items");
         }
         priority = parsePriority(priorityValue, filePath, options.priorityMin, options.priorityMax);
@@ -204,13 +193,13 @@ function parseNode(content, filePath, options) {
     const aliases = requireLowercaseList(optionalList(frontmatter, "aliases", filePath), "aliases", filePath);
     const skillsRaw = optionalList(frontmatter, "skills", filePath);
     const skills = normalizeSkillList(skillsRaw, filePath);
-    if (skills.length > 0 && !exports.WORK_TYPES.has(type)) {
+    if (skills.length > 0 && !template_schema_1.WORK_TYPES.has(type)) {
         throw formatError(filePath, "skills is only allowed for work items");
     }
     normalizeIdList(optionalList(frontmatter, "scope", filePath), "scope", filePath);
     const supersedesValue = optionalString(frontmatter, "supersedes", filePath);
     if (supersedesValue !== undefined) {
-        if (!exports.DEC_TYPES.has(type)) {
+        if (!template_schema_1.DEC_TYPES.has(type)) {
             throw formatError(filePath, "supersedes is only allowed for decision records");
         }
         const normalized = requireLowercase(supersedesValue, "supersedes", filePath);

package/dist/graph/template_schema.js

@@ -3,10 +3,77 @@ 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 [];
@@ -44,13 +111,65 @@ 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 schemas = {};
+    const discoveredTypes = new Set();
     for (const filePath of files) {
         const content = fs_1.default.readFileSync(filePath, "utf8");
         const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, filePath);
@@ -62,22 +181,16 @@ function loadTemplateSchemas(root, config, requiredTypes) {
         if (normalizedType !== typeValue) {
             throw new Error(`template type must be lowercase in ${filePath}`);
         }
-        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);
+        const schema = schemas[normalizedType];
+        if (!schema) {
+            throw new Error(`template schema missing for type ${normalizedType}`);
         }
+        validateTemplateAgainstSchema(frontmatter, schema, filePath);
+        discoveredTypes.add(normalizedType);
     }
     if (requiredTypes) {
         const required = Array.from(requiredTypes, (value) => value.toLowerCase());
-        const missing = required.filter((value) => !schemas[value]);
+        const missing = required.filter((value) => !discoveredTypes.has(value));
         if (missing.length > 0) {
             throw new Error(`template schema missing for type(s): ${missing.join(", ")}`);
         }

package/dist/init/AGENT_START.md

@@ -41,7 +41,15 @@ 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.
 - Files outside mdkg-managed skill mirrors, such as local tool permission files, are not managed by mdkg unless documented explicitly.
+
+Structured discovery/show exports:
+- `--json`
+- `--xml`
+- `--toon`
+- `--md`

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -21,9 +21,16 @@ Agent bootstrap:
 - `mdkg init --llm`
 - `mdkg init --agent`
 - `mdkg init --llm --agent`
+- published bootstrap config is root-only by default
 
 Skill discovery:
 - `mdkg skill list --tags stage:plan --json`
 - `mdkg skill search "<query>" --json`
 - `mdkg skill show <slug> --json`
 - `mdkg skill sync`
+
+Discovery/show export flags:
+- `--json`
+- `--xml`
+- `--toon`
+- `--md`

package/dist/init/config.json

@@ -52,16 +52,6 @@
       "path": ".",
       "enabled": true,
       "mdkg_dir": ".mdkg"
-    },
-    "polish": {
-      "path": "polish",
-      "enabled": true,
-      "mdkg_dir": ".mdkg"
-    },
-    "smoke": {
-      "path": "smoke",
-      "enabled": true,
-      "mdkg_dir": ".mdkg"
     }
   }
-}
+}

package/dist/init/core/rule-3-cli-contract.md

@@ -88,7 +88,7 @@ If a user provides an unqualified ID and it is ambiguous globally:
 - Commands should be script-friendly:
   - concise outputs for single items
   - predictable formatting
-  - `--json` output for supported discovery/show commands
+  - `--json`, `--xml`, `--toon`, and `--md` output for supported discovery/show commands
   - when printing node summaries (e.g., `show`/list results), outputs SHOULD surface key searchable frontmatter fields such as `links` and `artifacts`
 
 ## Command set (v1 target)
@@ -164,18 +164,19 @@ Common flags:
 - `--template <set>` (default from config)
 
 ### Read/search
-- `mdkg show <id-or-qid> [--meta] [--json]`
+- `mdkg show <id-or-qid> [--meta] [--json|--xml|--toon|--md]`
   - default behavior shows the full node body
   - `--meta` is the compact card-only view
-- `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+- `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - search SHOULD match on IDs, titles, tags, path tokens, and searchable frontmatter lists (`links`, `artifacts`, `refs`, `aliases`)
-- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
 - skills are first-class under `mdkg skill ...` only:
-  - `mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
-  - `mdkg skill show <slug> [--meta] [--json]`
-  - `mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+  - `mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
+  - `mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]`
+  - `mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]`
   - `mdkg skill validate [<slug>]`
   - `mdkg skill sync [--force]`
+- discovery/show output flags are mutually exclusive; text mode remains the default when none are supplied
 
 ### Task lifecycle mutation
 - `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]`

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

@@ -95,7 +95,9 @@ Work items (`epic/feat/task/bug/checkpoint/test`):
   - `status` (enum)
   - optional `priority` (0..9)
   - optional `skills: [slug, ...]` (kebab-case skill slugs)
-  - optional graph edges: `epic`, `parent`, `relates`, `blocked_by`, `blocks`, `prev`, `next`
+  - 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
 
 Decision records (`dec-*`):
 - `status` (enum: `proposed`, `accepted`, `rejected`, `superseded`)

package/dist/init/llms.txt

@@ -15,3 +15,5 @@ First commands:
 - `mdkg pack <id>`
 - `mdkg skill list --tags stage:plan --json`
 - `mdkg validate`
+
+Discovery and show commands also support `--xml`, `--toon`, and `--md` when JSON is not the desired interchange format.

package/dist/templates/loader.js

@@ -48,8 +48,8 @@ function renderTokenValue(value) {
     }
     return value;
 }
-function renderTemplate(template, context) {
-    const allowedKeys = new Set(Object.keys(template.frontmatter));
+function renderTemplate(template, context, allowedKeysInput) {
+    const allowedKeys = new Set(allowedKeysInput ?? Object.keys(template.frontmatter));
     const rendered = {};
     for (const [key, value] of Object.entries(template.frontmatter)) {
         if (isTokenPlaceholder(value)) {

package/dist/util/argparse.js

@@ -79,6 +79,9 @@ const BOOLEAN_FLAGS = new Set([
     "--version",
     "--dry-run",
     "--json",
+    "--xml",
+    "--toon",
+    "--md",
     "--list-profiles",
     "--with-scripts",
     "--clear-blocked-by",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {