mdkg 0.0.2 → 0.0.4

package/dist/graph/skills_indexer.js

@@ -0,0 +1,160 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_SLUG_RE = exports.SKILLS_INDEX_RELATIVE_PATH = void 0;
+exports.resolveSkillsRoot = resolveSkillsRoot;
+exports.resolveSkillsIndexPath = resolveSkillsIndexPath;
+exports.buildSkillIndexEntry = buildSkillIndexEntry;
+exports.buildSkillsIndex = buildSkillsIndex;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const frontmatter_1 = require("./frontmatter");
+exports.SKILLS_INDEX_RELATIVE_PATH = ".mdkg/index/skills.json";
+exports.SKILL_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function listSkillMarkdownFiles(dir) {
+    if (!fs_1.default.existsSync(dir)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const slug = entry.name.toLowerCase();
+        const skillDir = path_1.default.join(dir, entry.name);
+        const canonicalPath = path_1.default.join(skillDir, "SKILL.md");
+        const compatPath = path_1.default.join(skillDir, "SKILLS.md");
+        if (fs_1.default.existsSync(canonicalPath) && fs_1.default.existsSync(compatPath)) {
+            throw new Error(`${skillDir}: both SKILL.md and SKILLS.md exist`);
+        }
+        if (fs_1.default.existsSync(canonicalPath)) {
+            files.push({ slug, filePath: canonicalPath });
+            continue;
+        }
+        if (fs_1.default.existsSync(compatPath)) {
+            files.push({ slug, filePath: compatPath });
+        }
+    }
+    files.sort((a, b) => a.slug.localeCompare(b.slug));
+    return files;
+}
+function requireString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${filePath}: ${key} is required and must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${filePath}: ${key} must be a non-empty string when set`);
+    }
+    return value;
+}
+function optionalList(frontmatter, key, filePath) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${filePath}: ${key} must be a list`);
+    }
+    return value;
+}
+function toLowercaseList(values) {
+    return values.map((value) => value.toLowerCase());
+}
+function extractOchatr(frontmatter) {
+    const keys = Object.keys(frontmatter)
+        .filter((key) => key.startsWith("ochatr_"))
+        .sort();
+    const extracted = {};
+    for (const key of keys) {
+        extracted[key] = frontmatter[key];
+    }
+    return extracted;
+}
+function hasDirectory(dirPath) {
+    if (!fs_1.default.existsSync(dirPath)) {
+        return false;
+    }
+    return fs_1.default.statSync(dirPath).isDirectory();
+}
+function rootWorkspaceMdkgPath(root, config) {
+    const rootWs = config.workspaces.root;
+    if (rootWs && rootWs.enabled) {
+        return path_1.default.resolve(root, rootWs.path, rootWs.mdkg_dir);
+    }
+    return path_1.default.resolve(root, ".mdkg");
+}
+function resolveSkillsRoot(root, config) {
+    return path_1.default.join(rootWorkspaceMdkgPath(root, config), "skills");
+}
+function resolveSkillsIndexPath(root) {
+    return path_1.default.resolve(root, exports.SKILLS_INDEX_RELATIVE_PATH);
+}
+function buildSkillIndexEntry(root, slug, filePath) {
+    if (!exports.SKILL_SLUG_RE.test(slug)) {
+        throw new Error(`${filePath}: skill slug must be kebab-case`);
+    }
+    const content = fs_1.default.readFileSync(filePath, "utf8");
+    const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+    const name = requireString(frontmatter, "name", filePath);
+    const description = requireString(frontmatter, "description", filePath);
+    const version = optionalString(frontmatter, "version", filePath);
+    const tags = toLowercaseList(optionalList(frontmatter, "tags", filePath));
+    const authors = toLowercaseList(optionalList(frontmatter, "authors", filePath));
+    const links = optionalList(frontmatter, "links", filePath);
+    const skillDir = path_1.default.dirname(filePath);
+    return {
+        slug,
+        id: `skill:${slug}`,
+        qid: `root:skill:${slug}`,
+        ws: "root",
+        type: "skill",
+        name,
+        description,
+        tags,
+        version,
+        authors,
+        links,
+        path: path_1.default.relative(root, filePath),
+        has_scripts: hasDirectory(path_1.default.join(skillDir, "scripts")),
+        has_references: hasDirectory(path_1.default.join(skillDir, "references")),
+        ochatr: extractOchatr(frontmatter),
+    };
+}
+function buildSkillsIndex(root, config) {
+    const skillsRoot = resolveSkillsRoot(root, config);
+    const files = listSkillMarkdownFiles(skillsRoot);
+    const skills = {};
+    for (const file of files) {
+        const { slug, filePath } = file;
+        if (skills[slug]) {
+            throw new Error(`${filePath}: duplicate skill slug ${slug}`);
+        }
+        skills[slug] = buildSkillIndexEntry(root, slug, filePath);
+    }
+    const sortedSkills = {};
+    for (const slug of Object.keys(skills).sort()) {
+        sortedSkills[slug] = skills[slug];
+    }
+    return {
+        meta: {
+            tool: config.tool,
+            schema_version: config.schema_version,
+            generated_at: new Date().toISOString(),
+            root,
+            skills_root: path_1.default.relative(root, skillsRoot),
+            skill_count: Object.keys(sortedSkills).length,
+        },
+        skills: sortedSkills,
+    };
+}

package/dist/init/README.md

@@ -0,0 +1,43 @@
+# mdkg Workspace Guide
+
+This repository is initialized for mdkg.
+
+## Layout
+
+- `core/`: rules, operating guide, and pinned docs
+- `design/`: product/engineering decision records
+- `work/`: epics, tasks, bugs, tests, checkpoints
+- `templates/`: default node templates
+- `index/`: generated index cache (do not commit)
+- `pack/`: generated context packs (do not commit)
+
+## First Commands
+
+```bash
+mdkg index
+mdkg new task "..." --status todo --priority 1
+mdkg list --status todo
+mdkg pack <id> --verbose
+mdkg validate
+```
+
+## Pack Profiles
+
+- `--pack-profile standard`: full body (current default behavior)
+- `--pack-profile concise`: summary body with code stripped by default
+- `--pack-profile headers`: metadata-only body (`none`)
+
+`--max-tokens` is a heuristic limit based on `chars / 4`.
+
+## Safety
+
+Ensure ignore files include:
+
+- `.mdkg/index/`
+- `.mdkg/pack/`
+
+Recommended:
+
+```bash
+mdkg init --update-gitignore --update-npmignore
+```

package/dist/init/core/rule-1-mdkg-conventions.md

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-01-22
+updated: 2026-03-05
 ---
 
 # mdkg conventions
@@ -87,6 +87,11 @@ Canonical ID format:
 
 `<prefix>-<number>`
 
+Reserved rule IDs allowed by contract:
+- `rule-guide`
+- `rule-soul`
+- `rule-human`
+
 Examples:
 - `task-183`
 - `edd-14`
@@ -153,11 +158,12 @@ All nodes MUST include:
 - `created` (YYYY-MM-DD)
 - `updated` (YYYY-MM-DD)
 
-Work items (`epic/feat/task/bug/chk/test`) MUST include:
+Work items (`epic/feat/task/bug/checkpoint/test`) MUST include:
   - `status`
 
 Work items MAY include:
   - `priority`
+  - `skills: [slug, ...]` (kebab-case skill references)
 
 Optional searchable metadata
 
@@ -222,6 +228,7 @@ They SHOULD include:
 The cache is enabled by default.
 
 - Root global index lives at `.mdkg/index/global.json`
+- Root skills index lives at `.mdkg/index/skills.json`
 - Index is rebuilt automatically when stale unless disabled by flag/config.
 - `.mdkg/index/` is generated and MUST be gitignored.
 

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

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-01-22
+updated: 2026-03-08
 ---
 
 # mdkg CLI contract
@@ -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
-  - optional `--json` output later (not required for v1)
+  - `--json` 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)
@@ -99,10 +99,17 @@ If a user provides an unqualified ID and it is ambiguous globally:
   - creates `.mdkg/config.json` if missing
   - creates core docs and templates if missing
   - does NOT overwrite existing docs unless `--force`
-  - optional agent files:
-    - `--agents` creates `AGENTS.md`
-    - `--claude` creates `CLAUDE.md`
-  - `--llm` creates both
+  - updates `.gitignore` and `.npmignore` by default
+  - `--no-update-ignores` disables default ignore writes
+  - explicit flags (`--update-gitignore`, `--update-npmignore`, `--update-dockerignore`) force writes even with global opt-out
+  - `--llm` is the canonical documented path for creating `AGENTS.md` and `CLAUDE.md`
+  - `--agents` / `--claude` remain compatibility flags, but are not part of the primary onboarding story
+  - `--omni` adds strict-node bootstrap docs and scaffolding:
+    - `.mdkg/core/SOUL.md` (`id: rule-soul`)
+    - `.mdkg/core/HUMAN.md` (`id: rule-human`)
+    - `.mdkg/skills/registry.md`
+    - `.mdkg/work/events/events.jsonl`
+    - deterministic `core.md` pin insertion (`rule-soul`, then `rule-human`)
 
 ### Guide
 - `mdkg guide`
@@ -116,6 +123,9 @@ If a user provides an unqualified ID and it is ambiguous globally:
 ### Indexing
 - `mdkg index`
   - rebuild global cache `.mdkg/index/global.json`
+  - rebuild skills cache `.mdkg/index/skills.json` from `.mdkg/skills/<slug>/SKILL.md`
+  - tolerate `.mdkg/skills/<slug>/SKILLS.md` on read with warning
+  - fail validation if both `SKILL.md` and `SKILLS.md` exist in one skill directory
   - strict by default (fails on invalid frontmatter)
   - optional `--tolerant` to skip invalid nodes (escape hatch)
 
@@ -140,24 +150,56 @@ Common flags:
 - `--artifacts <ref,ref,...>`
 - `--refs <id,id,...>`
 - `--aliases <text,text,...>`
+- `--skills <slug,slug,...>` (work items)
 - `--template <set>` (default from config)
 
 ### Read/search
-- `mdkg show <id-or-qid>`
-- `mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>]`
+- `mdkg show <id-or-qid> [--meta] [--json]`
+  - 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]`
   - 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>]`
-
-### Graph views
-- `mdkg tree <epic-id-or-qid> [--ws <alias>]`
-- `mdkg neighbors <id-or-qid> --depth <n> [--edges <...>]`
+- `mdkg list [--type <type>] [--status <status>] [--ws <alias>] [--epic <id>] [--blocked] [--priority <n>] [--tags <tag,tag,...>] [--tags-mode any|all] [--json]`
+- 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 validate [<slug>]`
+
+### Task lifecycle mutation
+- `mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]`
+  - supports `task`, `bug`, and `test` nodes only
+  - sets `status: progress`
+- `mdkg task update <id-or-qid> [...]`
+  - supports additive list mutation for `artifacts`, `links`, `refs`, `skills`, `tags`, and `blocked_by`
+  - supports scalar replacement for `status` and `priority`
+  - `--clear-blocked-by` resets blockers before optional re-add
+- `mdkg task done <id-or-qid> [--checkpoint "<title>"] [...]`
+  - supports `task`, `bug`, and `test` nodes only
+  - sets `status: done`
+  - optional checkpoint creation is explicit only
 
 ### Packs (core feature)
-- `mdkg pack <id-or-qid> [--depth <n>] [--verbose] [--edges <keys>] [--format md|json|toon|xml] [--out <path>] [--ws <alias>]`
+- `mdkg pack <id-or-qid> [--profile <name>] [--verbose] [--format md|json|toon|xml] [--out <path>] [--ws <alias>]`
+  - optional skill inclusion flags:
+    - `--skills none|auto|<slug,slug,...>`
+    - `--skills-depth meta|full`
+  - advanced shaping/debug flags remain supported but de-emphasized:
+    - `--depth <n>`
+    - `--edges <keys>`
+    - `--strip-code`
+    - `--max-code-lines <n>`
+    - `--max-chars <n>`
+    - `--max-lines <n>`
+    - `--max-tokens <n>`
+    - `--truncation-report <path>`
+    - `--stats-out <path>`
   - `--edges` adds to the default edge set
   - `--out` writes to a file (create parent dirs; overwrite if exists)
   - if `--out` is omitted, write to `.mdkg/pack/pack_<kind>_<id>_<timestamp>.<ext>`
   - short flags supported: `-o`, `-f`, `-v`, `-d`, `-e`, `-w`, `-r`
+  - `--profile` is the primary documented alias for `--pack-profile`
+  - pack selection includes latest checkpoint by pack-time resolver; index hint `latest_checkpoint_qid` is optimization-only
 
 ### Next priority
 - `mdkg next [<id-or-qid>] [--ws <alias>]`
@@ -169,9 +211,26 @@ Common flags:
   - creates a `chk-*` node from template
   - designed as a phase summary / compression node
 
+### Events
+- `mdkg event enable [--ws <alias>] [--no-update-gitignore]`
+  - creates `.mdkg/work/events/events.jsonl` if missing
+  - updates `.gitignore` by default
+- `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
+- current automatic mutation events:
+  - `NODE_CREATED`
+  - `SKILL_CREATED`
+  - `CHECKPOINT_CREATED`
+  - `TASK_STARTED`
+  - `TASK_UPDATED`
+  - `TASK_DONE`
+
 ### Validation and formatting
 - `mdkg validate`
   - strict frontmatter + graph integrity checks (exit code 2 on failure)
+  - validates optional node->skill references
+  - validates optional `.mdkg/work/events/events.jsonl` record shape when file exists
 - `mdkg format`
   - normalize frontmatter formatting and casing
   - avoid destructive body edits

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

@@ -36,6 +36,7 @@ Recommended `.gitignore` entries:
 - `.mdkg/index/`
 - `.mdkg/index/**`
 - `.mdkg/pack/`
+- `.mdkg/work/events/*.jsonl` (when episodic logging is enabled)
 
 ## npm publish safety (required)
 
@@ -67,14 +68,18 @@ For application builds:
 
 ## mdkg init behavior
 
-`mdkg init` MAY offer optional flags to append ignore entries:
+`mdkg init` updates ignore files by default for safety:
+
+- `.gitignore` appends `.mdkg/index/`, `.mdkg/pack/`, `.mdkg/work/events/*.jsonl`
+- `.npmignore` appends `.mdkg/`, `.mdkg/index/`, `.mdkg/pack/`
+- `--no-update-ignores` disables these default writes
+
+Explicit flags remain available and take precedence:
 
 - `--update-gitignore`
 - `--update-npmignore`
 - `--update-dockerignore`
 
-In v1, mdkg should default to **not** editing user files without an explicit flag.
-
 ## Index safety
 
 - `.mdkg/index/` is generated.
@@ -92,6 +97,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
 - ✅ npm publishes only `dist/`, `README.md`, `LICENSE`
 - ✅ optional `.npmignore` excludes `.mdkg/`
 - ✅ `.dockerignore` excludes `.mdkg/` when applicable

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

@@ -10,7 +10,7 @@ relates: []
 refs: []
 aliases: []
 created: 2026-01-06
-updated: 2026-01-22
+updated: 2026-03-05
 ---
 
 # Templates and schemas
@@ -65,6 +65,7 @@ Optional tokens (nice-to-have, may be empty):
 - `{{artifacts}}` (list)
 - `{{refs}}` (list)
 - `{{aliases}}` (list)
+- `{{skills}}` (list; work items)
 - `{{cases}}` (list)
 
 ## Frontmatter requirements by type
@@ -90,9 +91,10 @@ All nodes MAY include the following searchable frontmatter lists:
 List fields SHOULD be written as `[]` when empty.
 Optional scalar graph fields (like `epic`, `parent`, `prev`, `next`) should be omitted when empty.
 
-Work items (`epic/feat/task/bug/chk/test`):
+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`
 
 Decision records (`dec-*`):
@@ -182,5 +184,7 @@ Body headings are strongly recommended for agent usability but should not be har
 
 - Frontmatter: strict, hard fail if invalid.
 - Body headings: warn only (do not break indexing).
+- Node -> skill references in `skills: [...]` are validated against `.mdkg/skills/<slug>/SKILL.md`.
+- `.mdkg/work/events/events.jsonl` is optional; when present, records are schema-validated by `mdkg validate`.
 - If a template is missing:
   - `mdkg new` must fail with a helpful error (exit code 3).

package/dist/init/skills/SKILL.md.example

@@ -0,0 +1,41 @@
+---
+name: {{name}}
+description: {{description}}
+{{tags_block}}{{authors_block}}{{links_block}}---
+
+# Goal
+
+Describe the deterministic outcome this skill should achieve.
+
+## When To Use
+
+- Use this skill when the workflow is triggered and the needed outcome is clear.
+- Prefer this skill over ad-hoc instructions when the procedure should be repeatable.
+
+## Inputs
+
+- Repo root
+- Current task, node, or user goal
+- Any required references or artifacts
+
+## Steps
+
+1. Confirm the triggering task or need before acting.
+2. Load only the references and artifacts required for this run.
+3. Execute the smallest deterministic workflow that satisfies the request.
+
+## Outputs
+
+- Deterministic result, patch, or artifact
+- Evidence needed for review or orchestration
+
+## Safety
+
+- Prefer repo truth over chat memory.
+- Keep secrets out of skills, references, and generated artifacts.
+- Stop and resolve ambiguity instead of guessing.
+
+## Failure Handling
+
+- If required context or policy is unclear, stop and ask before proceeding.
+- If the procedure needs more detail, load the specific reference rather than broad context.

package/dist/init/templates/default/bug.md

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 created: {{created}}
 updated: {{updated}}
 ---

package/dist/init/templates/default/chk.md

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 scope: []
 created: {{created}}
 updated: {{updated}}

package/dist/init/templates/default/epic.md

@@ -13,6 +13,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 created: {{created}}
 updated: {{updated}}
 ---

package/dist/init/templates/default/feat.md

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 created: {{created}}
 updated: {{updated}}
 ---

package/dist/init/templates/default/task.md

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 created: {{created}}
 updated: {{updated}}
 ---

package/dist/init/templates/default/test.md

@@ -17,6 +17,7 @@ blocked_by: []
 blocks: []
 refs: []
 aliases: []
+skills: []
 cases: []
 created: {{created}}
 updated: {{updated}}