mdkg 0.0.5 → 0.0.6

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
@@ -200,7 +200,7 @@ 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/`
 - skills indexing and search/show/list support
 - optional `skills: [...]` on work items
 - pack-time skill inclusion
@@ -213,7 +213,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 +229,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 +246,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

@@ -261,8 +261,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 +272,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 +299,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 +315,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);
     }
@@ -779,8 +779,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": {

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/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,8 @@ 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.

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

@@ -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/`
@@ -219,9 +223,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/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

@@ -82,7 +82,6 @@ const BOOLEAN_FLAGS = new Set([
     "--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.6",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {