mdkg 0.0.5 → 0.0.7

package/README.md

@@ -13,7 +13,7 @@ mdkg stays deliberately boring:
 - zero runtime dependencies
 - no sqlite, daemon, hosted index, or vector DB
 
-Current package version in source: `0.0.5`
+Current package version in source: `0.0.6`
 
 ## The product shape
 
@@ -49,7 +49,7 @@ Initialize mdkg in a repo:
 mdkg init --llm
 ```
 
-This is the generic OSS bootstrap path. It creates `.mdkg/` and updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out.
+This is the generic OSS bootstrap path. It creates `.mdkg/` and updates `.gitignore` / `.npmignore` by default. Use `--no-update-ignores` to opt out of those ignore-file updates.
 
 Optional agent-ready scaffold:
 
@@ -57,7 +57,7 @@ Optional agent-ready scaffold:
 mdkg init --agent
 ```
 
-This adds strict-node `SOUL.md` / `HUMAN.md`, a skills scaffold, seeded events JSONL, core pin updates, and mirrored skill folders under `.agents/skills/` and `.claude/skills/`.
+This adds strict-node `SOUL.md` / `HUMAN.md`, seeds the three default mdkg usage skills, creates `events.jsonl`, updates the skill registry, adds core pin updates, and creates mirrored skill folders under `.agents/skills/` and `.claude/skills/`.
 
 Create a task:
 
@@ -86,7 +86,7 @@ Validate before handoff or commit:
 mdkg validate
 ```
 
-Mutate a task-like node without manual markdown editing:
+Update structured task state and evidence while keeping body and narrative edits in markdown:
 
 ```bash
 mdkg task start task-1 --run-id run_local_1
@@ -94,7 +94,7 @@ mdkg task update task-1 --add-artifacts tests://unit.txt --add-tags release
 mdkg task done task-1 --checkpoint "release readiness milestone"
 ```
 
-Enable and append baseline event memory:
+Ensure and append baseline event memory:
 
 ```bash
 mdkg event enable
@@ -176,10 +176,13 @@ 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,...]`
 - packs may include skills with `--skills` and `--skills-depth`
 - mdkg indexes and discovers skills but does not execute skill scripts
@@ -200,12 +203,14 @@ This repo now dogfoods three internal skills:
 
 This release includes:
 - `init --agent`
-- default ignore updates with `--no-update-ignores`
+- 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
 
@@ -213,7 +218,8 @@ Current direction:
 - keep the OSS story generic around `init --llm`
 - use `init --agent` for deeper AI-agent bootstrap
 - keep `pack <id>` at the center of the human/agent loop
-- make task mutation and event logging guided instead of purely manual
+- use `mdkg task ...` for structured state changes and markdown edits for narrative/body content
+- make event logging guided instead of purely manual
 - dogfood real skills inside the repo
 - make skill authoring first-class through `mdkg skill`
 - make `CLI_COMMAND_MATRIX.md` the single source of truth for the live CLI surface
@@ -228,7 +234,7 @@ mdkg is not a secret store.
 Use these defaults:
 - keep `.mdkg/index/` gitignored
 - keep `.mdkg/pack/` gitignored
-- keep `.mdkg/work/events/*.jsonl` gitignored unless you deliberately opt in
+- event logs are committed by default; ignore or delete them manually if a repo wants local-only provenance
 - do not ship `.mdkg/` into production builds or published packages
 - if an external orchestrator is writing mdkg state, keep one durable writer per run and batch commits at end-of-run or checkpoint boundaries
 - do not commit on every tool call
@@ -245,7 +251,7 @@ Suggested local loop:
 2. inspect truth with `search`, `show`, or `next`
 3. build context with `pack <id>`
 4. mutate task state with `mdkg task ...` when durable state changes
-5. enable event logging if provenance should be captured in JSONL
+5. ensure event logging exists if the JSONL file was deleted or is missing
 6. implement and test
 7. run `mdkg validate`
 

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:");
@@ -261,8 +262,8 @@ function printTaskHelp(log, subcommand) {
             log("Usage:");
             log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]');
             log("\nWhen to use:");
-            log("  Move a task, bug, or test into progress and emit a baseline event when logging is enabled.");
-            log("  If events are disabled, mdkg prints a short reminder about `mdkg event enable`.");
+            log("  Move a task, bug, or test into progress as a structured state change.");
+            log("  If `events.jsonl` is missing, mdkg prints a short reminder about `mdkg event enable`.");
             printGlobalOptions(log);
             return;
         case "update":
@@ -272,7 +273,7 @@ function printTaskHelp(log, subcommand) {
             log("                   [--add-skills <slug,...>] [--add-tags <tag,...>] [--add-blocked-by <id,...>]");
             log('                   [--clear-blocked-by] [--run-id <id>] [--note "<text>"]');
             log("\nWhen to use:");
-            log("  Update task metadata and evidence without editing markdown manually.");
+            log("  Update structured task metadata and evidence while keeping body and narrative edits in markdown.");
             printGlobalOptions(log);
             return;
         case "done":
@@ -299,9 +300,9 @@ function printEventHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "enable":
             log("Usage:");
-            log("  mdkg event enable [--ws <alias>] [--no-update-gitignore]");
+            log("  mdkg event enable [--ws <alias>]");
             log("\nWhen to use:");
-            log("  Create the append-only JSONL event log for a workspace.");
+            log("  Create or ensure the append-only JSONL event log for a workspace.");
             printGlobalOptions(log);
             return;
         case "append":
@@ -315,7 +316,7 @@ function printEventHelp(log, subcommand) {
             return;
         default:
             log("Usage:");
-            log("  mdkg event enable [--ws <alias>] [--no-update-gitignore]");
+            log("  mdkg event enable [--ws <alias>]");
             log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [options]");
             printGlobalOptions(log);
     }
@@ -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,
             });
@@ -779,8 +799,7 @@ function runEventSubcommand(parsed, root) {
                 throw new errors_1.UsageError("event enable does not accept positional arguments");
             }
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-            const noUpdateGitignore = parseBooleanFlag("--no-update-gitignore", parsed.flags["--no-update-gitignore"]);
-            (0, event_1.runEventEnableCommand)({ root, ws, updateGitignore: !noUpdateGitignore });
+            (0, event_1.runEventEnableCommand)({ root, ws });
             return 0;
         }
         case "append": {
@@ -931,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)({
@@ -939,7 +958,7 @@ function runCommand(parsed, root, runtime) {
                 id,
                 ws,
                 metaOnly,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -957,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)({
@@ -970,7 +989,7 @@ function runCommand(parsed, root, runtime) {
                 blocked,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });
@@ -986,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)({
@@ -997,7 +1016,7 @@ function runCommand(parsed, root, runtime) {
                 status,
                 tags,
                 tagsMode,
-                json,
+                format,
                 noCache,
                 noReindex,
             });

package/dist/commands/event.js

@@ -7,8 +7,7 @@ const errors_1 = require("../util/errors");
 function runEventEnableCommand(options) {
     const result = (0, event_support_1.ensureEventsEnabled)(options);
     const createdLabel = result.created ? "created" : "already present";
-    const ignoreLabel = result.gitignoreUpdated ? "updated .gitignore" : "left .gitignore unchanged";
-    console.log(`event logging enabled: ${result.ws} (${createdLabel}; ${ignoreLabel})`);
+    console.log(`event logging enabled: ${result.ws} (${createdLabel})`);
 }
 function normalizeEventStatus(value) {
     const normalized = value.trim().toLowerCase();

package/dist/commands/event_support.js

@@ -16,27 +16,6 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
 const errors_1 = require("../util/errors");
-function appendIgnoreEntries(filePath, entries) {
-    const normalizedEntries = entries.map((entry) => entry.trim()).filter(Boolean);
-    if (normalizedEntries.length === 0) {
-        return false;
-    }
-    let existing = "";
-    if (fs_1.default.existsSync(filePath)) {
-        existing = fs_1.default.readFileSync(filePath, "utf8");
-    }
-    const existingLines = new Set(existing
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter(Boolean));
-    const additions = normalizedEntries.filter((entry) => !existingLines.has(entry));
-    if (additions.length === 0) {
-        return false;
-    }
-    const next = existing.length === 0 ? `${additions.join("\n")}\n` : `${existing.replace(/\s*$/, "\n")}${additions.join("\n")}\n`;
-    fs_1.default.writeFileSync(filePath, next, "utf8");
-    return true;
-}
 function normalizeWorkspaceForEvents(config, raw) {
     const normalized = (raw ?? "root").toLowerCase();
     if (normalized === "all") {
@@ -70,20 +49,13 @@ function ensureEventsEnabled(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const ws = normalizeWorkspaceForEvents(config, options.ws);
     const eventsPath = resolveEventsPath(options.root, config, ws);
-    const updateGitignore = options.updateGitignore !== false;
     let created = false;
     if (!fs_1.default.existsSync(eventsPath)) {
         fs_1.default.mkdirSync(path_1.default.dirname(eventsPath), { recursive: true });
         fs_1.default.writeFileSync(eventsPath, "", "utf8");
         created = true;
     }
-    let gitignoreUpdated = false;
-    if (updateGitignore) {
-        gitignoreUpdated = appendIgnoreEntries(path_1.default.join(options.root, ".gitignore"), [
-            ".mdkg/work/events/*.jsonl",
-        ]);
-    }
-    return { ws, eventsPath, created, gitignoreUpdated };
+    return { ws, eventsPath, created };
 }
 function normalizeIdOrIdRef(value) {
     return value.trim().toLowerCase();
@@ -131,7 +103,7 @@ function appendEvent(options) {
     }
     const eventsPath = resolveEventsPath(options.root, config, record.workspace);
     if (!fs_1.default.existsSync(eventsPath)) {
-        throw new errors_1.NotFoundError(`event logging is not enabled for workspace ${record.workspace}; run \`mdkg event enable --ws ${record.workspace}\``);
+        throw new errors_1.NotFoundError(`events.jsonl is missing for workspace ${record.workspace}; run \`mdkg event enable --ws ${record.workspace}\``);
     }
     fs_1.default.appendFileSync(eventsPath, `${JSON.stringify(record)}\n`, "utf8");
     return record;

package/dist/commands/init.js

@@ -235,6 +235,7 @@ function runInitCommand(options) {
     const seedAgentStart = path_1.default.join(seedRoot, "AGENT_START.md");
     const seedCliMatrix = path_1.default.join(seedRoot, "CLI_COMMAND_MATRIX.md");
     const seedReadme = path_1.default.join(seedRoot, "README.md");
+    const seedDefaultSkills = path_1.default.join(seedRoot, "skills", "default");
     if (!fs_1.default.existsSync(seedConfig) || !fs_1.default.existsSync(seedCore) || !fs_1.default.existsSync(seedTemplates)) {
         throw new errors_1.NotFoundError(`init assets not found at ${seedRoot} (try reinstalling mdkg)`);
     }
@@ -256,6 +257,9 @@ function runInitCommand(options) {
     if (!fs_1.default.existsSync(seedReadme)) {
         throw new errors_1.NotFoundError(`init assets missing README.md at ${seedRoot}`);
     }
+    if (options.agent && !fs_1.default.existsSync(seedDefaultSkills)) {
+        throw new errors_1.NotFoundError(`init assets missing default skills at ${seedRoot}`);
+    }
     const mdkgDir = path_1.default.join(root, ".mdkg");
     fs_1.default.mkdirSync(mdkgDir, { recursive: true });
     fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "work"), { recursive: true });
@@ -286,6 +290,7 @@ function runInitCommand(options) {
         const eventsPath = path_1.default.join(eventsDir, "events.jsonl");
         fs_1.default.mkdirSync(skillsDir, { recursive: true });
         fs_1.default.mkdirSync(eventsDir, { recursive: true });
+        copySeedDir(seedDefaultSkills, skillsDir, force, stats);
         writeFileIfMissing(soulPath, soulTemplate(today), force, stats);
         writeFileIfMissing(humanPath, humanTemplate(today), force, stats);
         writeFileIfMissing(registryPath, (0, skill_support_1.registryTemplate)(), force, stats);
@@ -296,6 +301,7 @@ function runInitCommand(options) {
         ensureCorePins(coreListPath, [SOUL_PIN_ID, HUMAN_PIN_ID]);
         (0, skill_mirror_1.scaffoldMirrorRoots)(root);
         const config = (0, config_1.loadConfig)(root);
+        (0, skill_support_1.refreshSkillsRegistry)(root, config);
         (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
     }
     const noUpdateIgnores = Boolean(options.noUpdateIgnores);
@@ -305,7 +311,6 @@ function runInitCommand(options) {
         appendIgnoreEntries(path_1.default.join(root, ".gitignore"), [
             ".mdkg/index/",
             ".mdkg/pack/",
-            ".mdkg/work/events/*.jsonl",
         ]);
     }
     if (shouldUpdateNpmignore) {

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/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/skill_mirror.js

@@ -110,29 +110,62 @@ function loadCanonicalSources(root, config) {
         };
     });
 }
-function copyDir(srcDir, destDir) {
+function writeFileIfChanged(srcPath, destPath) {
+    const next = fs_1.default.readFileSync(srcPath);
+    if (fs_1.default.existsSync(destPath) && fs_1.default.statSync(destPath).isFile()) {
+        const current = fs_1.default.readFileSync(destPath);
+        if (current.equals(next)) {
+            return;
+        }
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(destPath), { recursive: true });
+    fs_1.default.writeFileSync(destPath, next);
+}
+function syncDir(srcDir, destDir) {
     fs_1.default.mkdirSync(destDir, { recursive: true });
-    const entries = fs_1.default.readdirSync(srcDir, { withFileTypes: true });
-    for (const entry of entries) {
+    const sourceEntries = fs_1.default.readdirSync(srcDir, { withFileTypes: true });
+    const sourceNames = new Set(sourceEntries.map((entry) => entry.name));
+    if (fs_1.default.existsSync(destDir)) {
+        for (const existing of fs_1.default.readdirSync(destDir)) {
+            if (!sourceNames.has(existing)) {
+                fs_1.default.rmSync(path_1.default.join(destDir, existing), { recursive: true, force: true });
+            }
+        }
+    }
+    for (const entry of sourceEntries) {
         const srcPath = path_1.default.join(srcDir, entry.name);
         const destPath = path_1.default.join(destDir, entry.name);
         if (entry.isDirectory()) {
-            copyDir(srcPath, destPath);
+            syncDir(srcPath, destPath);
         }
         else if (entry.isFile()) {
-            fs_1.default.mkdirSync(path_1.default.dirname(destPath), { recursive: true });
-            fs_1.default.copyFileSync(srcPath, destPath);
+            writeFileIfChanged(srcPath, destPath);
         }
     }
 }
 function materializeSkillMirror(source, destDir) {
-    fs_1.default.rmSync(destDir, { recursive: true, force: true });
     fs_1.default.mkdirSync(destDir, { recursive: true });
-    fs_1.default.copyFileSync(source.docPath, path_1.default.join(destDir, "SKILL.md"));
+    const expectedRootEntries = new Set(["SKILL.md"]);
+    for (const entry of ["references", "assets", "scripts"]) {
+        const srcPath = path_1.default.join(source.sourceDir, entry);
+        if (fs_1.default.existsSync(srcPath) && fs_1.default.statSync(srcPath).isDirectory()) {
+            expectedRootEntries.add(entry);
+        }
+    }
+    for (const existing of fs_1.default.readdirSync(destDir)) {
+        if (!expectedRootEntries.has(existing)) {
+            fs_1.default.rmSync(path_1.default.join(destDir, existing), { recursive: true, force: true });
+        }
+    }
+    writeFileIfChanged(source.docPath, path_1.default.join(destDir, "SKILL.md"));
     for (const entry of ["references", "assets", "scripts"]) {
         const srcPath = path_1.default.join(source.sourceDir, entry);
+        const destPath = path_1.default.join(destDir, entry);
         if (fs_1.default.existsSync(srcPath) && fs_1.default.statSync(srcPath).isDirectory()) {
-            copyDir(srcPath, path_1.default.join(destDir, entry));
+            syncDir(srcPath, destPath);
+        }
+        else if (fs_1.default.existsSync(destPath)) {
+            fs_1.default.rmSync(destPath, { recursive: true, force: true });
         }
     }
 }

package/dist/commands/task.js

@@ -173,7 +173,7 @@ function maybeWarnEventsDisabled(root, config, ws) {
     if ((0, event_support_1.isEventLoggingEnabled)(root, config, ws)) {
         return;
     }
-    console.error(`note: event logging not enabled for workspace ${ws}; run mdkg event enable --ws ${ws} if you want JSONL provenance`);
+    console.error(`note: events.jsonl is missing for workspace ${ws}; run mdkg event enable --ws ${ws} to restore JSONL provenance`);
 }
 function runTaskStartCommand(options) {
     const loaded = loadMutableTaskNode(options.root, options.id, options.ws);

package/dist/init/AGENTS.md

@@ -6,3 +6,4 @@ Codex/OpenAI conventions for this repo:
 - use `AGENT_START.md` as the startup contract
 - use `.agents/skills/` for product-facing mirrored skills when present
 - use `mdkg skill ...` as the canonical skill command family
+- use `mdkg task ...` for structured task fields and markdown edits for narrative/body changes

package/dist/init/AGENT_START.md

@@ -40,7 +40,14 @@ Conventions:
 - `.agents/skills/` and `.claude/skills/` mirror canonical skills from `.mdkg/skills/` when agent bootstrap is enabled.
 - 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 over hand-editing routine work-state changes.
+- Prefer task/event commands for structured work-state changes and use markdown edits for narrative/body updates.
 - 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 in 0.0.5.
-- If events are disabled, `mdkg task start` and `mdkg task done` will remind you how to enable JSONL provenance.
+- 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)
@@ -107,6 +107,10 @@ If a user provides an unqualified ID and it is ambiguous globally:
   - `--agent` adds strict-node bootstrap docs and scaffolding:
     - `.mdkg/core/SOUL.md` (`id: rule-soul`)
     - `.mdkg/core/HUMAN.md` (`id: rule-human`)
+    - seeded canonical skills:
+      - `.mdkg/skills/select-work-and-ground-context/SKILL.md`
+      - `.mdkg/skills/build-pack-and-execute-task/SKILL.md`
+      - `.mdkg/skills/verify-close-and-checkpoint/SKILL.md`
     - `.mdkg/skills/registry.md`
     - `.mdkg/work/events/events.jsonl`
     - `.agents/skills/`
@@ -160,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>"]`
@@ -219,9 +224,9 @@ Common flags:
   - designed as a phase summary / compression node
 
 ### Events
-- `mdkg event enable [--ws <alias>] [--no-update-gitignore]`
+- `mdkg event enable [--ws <alias>]`
   - creates `.mdkg/work/events/events.jsonl` if missing
-  - updates `.gitignore` by default
+  - leaves `.gitignore` unchanged
 - `mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [...]`
   - appends one JSONL provenance record
 - automatic command-level events append only when event logging is enabled for the target workspace

package/dist/init/core/rule-4-repo-safety-and-ignores.md

@@ -36,7 +36,6 @@ Recommended `.gitignore` entries:
 - `.mdkg/index/`
 - `.mdkg/index/**`
 - `.mdkg/pack/`
-- `.mdkg/work/events/*.jsonl` (when episodic logging is enabled)
 
 ## npm publish safety (required)
 
@@ -70,7 +69,7 @@ For application builds:
 
 `mdkg init` updates ignore files by default for safety:
 
-- `.gitignore` appends `.mdkg/index/`, `.mdkg/pack/`, `.mdkg/work/events/*.jsonl`
+- `.gitignore` appends `.mdkg/index/`, `.mdkg/pack/`
 - `.npmignore` appends `.mdkg/`, `.mdkg/index/`, `.mdkg/pack/`
 - `--no-update-ignores` disables these default writes
 
@@ -97,7 +96,7 @@ Workspace-local `.mdkg/` directories (near code) should follow the same rules:
 ## Summary checklist
 
 - ✅ `.mdkg/index/` ignored
-- ✅ `.mdkg/work/events/*.jsonl` ignored when event logging is enabled
+- ✅ event logs are committed by default unless a repo chooses to ignore them manually
 - ✅ npm publishes only `dist/`, `README.md`, `LICENSE`
 - ✅ optional `.npmignore` excludes `.mdkg/`
 - ✅ `.dockerignore` excludes `.mdkg/` when applicable

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/init/skills/default/build-pack-and-execute-task/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: build-pack-and-execute-task
+description: Build a deterministic mdkg pack for the active work item and use it as the execution handoff when coding or delegating to another AI agent.
+tags: [stage:execute, writer:patch-only, mdkg, pack-first, context]
+version: 0.1.0
+authors: [mdkg]
+links: [README.md, PACK_EXAMPLES.md, llms.txt]
+---
+
+# Goal
+
+Use `mdkg pack <id>` as the default execution context instead of ad-hoc file gathering.
+
+## When To Use
+
+- Before coding
+- Before handing work to another AI agent
+- Before review when precise linked context matters
+
+## Inputs
+
+- Selected node id
+- Optional profile choice
+- Optional skills inclusion mode
+
+## Steps
+
+1. Start with `mdkg pack <id>`.
+2. For a preview, use `mdkg pack <id> --profile concise --dry-run --stats`.
+3. Use `--verbose` only when pinned core docs must be included in the pack body.
+4. Use `--skills auto` when the work item already references the right skills.
+5. Use `--skills-depth full` only for active execution, not early discovery.
+6. Discover skills by metadata first; load full skill bodies only for the selected execution procedures.
+7. Hand the pack, not a loose file list, to the next coding step or agent.
+8. Keep this stage patch-only: subagents and tools may produce patches, test output, and evidence, but not direct mdkg state writes or commits.
+9. If execution reveals new artifacts or blockers, hand them to the orchestrator stage for `mdkg task update ...` as structured field updates; keep narrative summaries in markdown.
+
+## Outputs
+
+- Deterministic pack file or dry-run selection report
+- Stable context bundle for execution or review
+- Patch bundles, test output, or evidence artifacts ready for orchestrator review
+
+## Safety
+
+- Prefer smaller packs first; expand only when the task requires it.
+- Keep pinned rules ahead of opportunistic context.
+- Do not treat raw event logs as primary execution context.
+- Do not mutate task status, create checkpoints, or commit from this stage.
+- mdkg indexes and discovers skills, but does not execute skill scripts.
+- If event logging is enabled, rely on later task/checkpoint commands to append baseline events instead of writing ad-hoc log entries here.
+
+## Failure Handling
+
+- If the pack is too broad, reduce profile or skill depth before continuing.
+- If the required procedure is unclear, return to metadata discovery instead of loading every skill body.
+- If execution requires a durable memory update, hand control back to the orchestrator stage instead of writing directly.

package/dist/init/skills/default/select-work-and-ground-context/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: select-work-and-ground-context
+description: Select the right mdkg work item and ground execution before coding when the active task or context is still being established.
+tags: [stage:plan, writer:read-only, mdkg, onboarding, context]
+version: 0.1.0
+authors: [mdkg]
+links: [AGENT_START.md, README.md, CLI_COMMAND_MATRIX.md]
+---
+
+# Goal
+
+Choose the correct work item and load the smallest deterministic context needed to act.
+
+## When To Use
+
+- At the start of a work session
+- When the active task is unclear
+- Before generating a pack or making code changes
+
+## Inputs
+
+- Current repo root
+- Optional task or epic id
+- Optional user goal in plain language
+
+## Steps
+
+1. If a task id is already known, inspect it with `mdkg show <id>`.
+2. If the task is not known, read `AGENT_START.md` and use `mdkg next` or `mdkg search "<query>"` to narrow candidates.
+3. Use `mdkg show <id> --meta` when you only need the card and link metadata.
+4. Confirm the selected node has the right constraints, related design docs, and current status.
+5. If the task is ambiguous, resolve that before building a pack.
+6. If the chosen task is ready to be claimed, hand off to `mdkg task start <id>` in the writer stage for the structured status change.
+7. If resuming closeout work for a feat or epic, inspect the latest relevant checkpoint before deciding what remains open.
+8. Treat this stage as read-only: inspect and decide, but do not mutate mdkg state or commit.
+
+## Outputs
+
+- One selected node id
+- Clear understanding of the active task, related docs, and current state
+- No durable mdkg writes or commits from this stage
+
+## Safety
+
+- Do not start coding from chat memory alone.
+- Prefer explicit rules, EDDs, DECs, and task nodes over informal notes.
+- If multiple tasks appear valid, stop and choose deliberately instead of guessing.
+- If writer ownership or policy boundaries are unclear, stop and resolve them before execution.
+- mdkg indexes and discovers skills, but does not execute skill scripts.
+- Event logging is committed by default in `init --agent` repos; use `mdkg event enable` only if `events.jsonl` is missing.
+
+## Failure Handling
+
+- If no clear work item exists, stop and ask for clarification instead of guessing.
+- If the selected task conflicts with current status or linked design docs, resolve the conflict before moving to pack generation.

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

@@ -0,0 +1,62 @@
+---
+name: verify-close-and-checkpoint
+description: Verify code and mdkg state, attach evidence, and close work cleanly when the single-writer AI agent or human orchestrator is ready to perform durable writes.
+tags: [stage:review, writer:orchestrator, mdkg, validation, release]
+version: 0.1.0
+authors: [mdkg]
+links: [README.md, AGENT_PROMPT_SNIPPET.md]
+---
+
+# Goal
+
+Finish work with evidence, validation, and minimal memory drift.
+
+## When To Use
+
+- After implementation
+- Before commit
+- Before marking a task done
+- Before creating a checkpoint
+
+## Inputs
+
+- Active task id
+- Test or build outputs
+- Any new artifact references
+
+## Steps
+
+1. Run the relevant technical gates for the changed surface.
+2. Run `mdkg validate` before closing the task.
+3. Use `mdkg task update <id> ...` for additive evidence and structured metadata changes; keep narrative/body edits in markdown.
+4. Use `mdkg task done <id> --checkpoint "<title>"` when the task should close with milestone compression.
+5. Batch durable mdkg writes at one boundary: task status, artifact refs, optional checkpoint, and commit.
+6. Mark tasks done only after evidence exists.
+7. Create a checkpoint only for milestone-level transitions, not every small step.
+8. For feat or epic closeout, prefer a checkpoint body as the durable narrative summary of what changed and what is next.
+9. Use feat closeout scope as direct children with `parent: <feat-id>` and epic closeout scope as descendant work with `epic: <epic-id>`.
+10. Parent status edits remain manual; do not invent a hidden parent-closeout workflow.
+11. If the latest checkpoint is relevant, use it as durable recall; treat raw events as provenance/debugging, not primary execution context.
+12. If `events.jsonl` is missing, recreate it with `mdkg event enable` before expecting automatic JSONL provenance.
+
+## Outputs
+
+- Verified mdkg graph state
+- Attached evidence and artifact refs
+- Task ready for review, done, or checkpointing
+- One durable writer action at the selected run or milestone boundary
+
+## Safety
+
+- Do not mark work done without validation.
+- Do not create checkpoint spam.
+- Keep commits event-driven and single-writer when agents are involved.
+- Only the orchestrator performs durable mdkg writes or commit/push actions.
+- Never commit on every tool call.
+- mdkg indexes and discovers skills, but does not execute skill scripts.
+
+## Failure Handling
+
+- If validation fails, stop and return the task to active work instead of closing it.
+- If artifact or evidence refs are missing, attach them before status changes or checkpoint creation.
+- If writer ownership is unclear, stop and resolve it before any durable mdkg update or commit.

package/dist/util/argparse.js

@@ -79,10 +79,12 @@ const BOOLEAN_FLAGS = new Set([
     "--version",
     "--dry-run",
     "--json",
+    "--xml",
+    "--toon",
+    "--md",
     "--list-profiles",
     "--with-scripts",
     "--clear-blocked-by",
-    "--no-update-gitignore",
 ]);
 const FLAG_ALIASES = {
     "--o": "--out",

package/package.json

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