mdkg 0.0.7 → 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
@@ -184,6 +186,7 @@ Current source behavior:
   - `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
@@ -219,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/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/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,6 +41,8 @@ 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/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/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/package.json

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